Protocols

BioSimSpace attempts to achieve interoperability by abstracting a range of common biomolecular simulation tasks through generic protocols. These present the user with a limited set of options which are handled by all of the external packages which we support. For example, the various protocols used for molecular dynamics simulations are defined here.

Protocols are translated into a package specific implementation during the construction of a process object. It is here that all of the required input files are created for the specific process, as well as any command-line arguments that need to be passed to the executable.

Customising protocols

Often a user may wish to customise the protocols that are provided by BioSimSpace. For a particular molecular dynamics engine, this can be done after the creation of a process by using helper methods, such as setConfig. This is useful if you wish to make small tweaks to the default protocols. For example, see the BioSimSpace.Process.Amber documentation. (Command-line arguments can be configured in a similar way.) Alternatively, a user can directly generate a completely custom procotol using BioSimSpace.Protocol.Custom, which takes a list of configuration strings, or the path to a configuration file, as a constructor argument. This will then need to be passed to the constructor of the appropriate process object, (e.g. BioSimSpace.Process.Amber if it were a configuration file for AMBER).

Note that both of the methods above tie you in to a specific simulation engine, i.e. a script written with a custom protocol is no longer interoperable since it will only work on a different computer if the same simulation engine happens to be installed there.

Another way to customise the existing protocols is to override the private _generate_config method in the classes for each of the simulation processes. This could be done in your own Python module, which could be installed alongside BioSimSpace to provide an alternative interoperable implementation of the protocols.

Writing protocols

Occasionally it might be desirable to write a protocol for a new simulation that isn’t currently supported by BioSimSpace. To do so requires the following steps:

  1. Create a new Protocol class that accepts keyword arguments that are supported across all molecular dynamics engines that implement the protocol. (It is not necessary that the protocol is implemented by all of the engines, only that the arguments are supported by those that do.) The class should provide functionality for setting and getting the configuration options, along with checking the type and value of the user input.

  2. Update the private _generate_config method in each of the Process classes that support the protocol to translate the high-level options into package specific configuration files. There is no need to make modifications to the process classes that don’t support the protocol, since a BioSimSpace._Exceptions.IncompatibleError will be raised if the user attempts to create a process to implement the protocol.

  3. Some protocols require specific command-line arguments to be passed to engine’s executable. If this is the case, update the _generate_args method of the process to modify the argument string when the protocol is used.

Protocols are also used in several other places within BioSimSpace, other than for defining specific molecular dynamics processes described above. In particular:

  • Protocols are used to define the way in which a molecular parameterisation is performed. The BioSimSpace.Parameters package comes with its own set of protocols, which can be customised by the user. To do so, either override the run method of an existing protocol, or define an entirely new protocol that inherits from the base class (you would need to do this if, for example, you were adding support for a new force field).

  • Complex, multi-stage, molecular simulation protocols, such as free-energy perturbation, are typically executed by a separate package, e.g. BioSimSpace.FreeEnergy. Here a run method orchestrates the separate processes that are required by overall simulation. This means that the free-energy objects themselves, e.g. BioSimSpace.FreeEnergy.Binding, can be thought of as a high-level protocol for the simulation method, with low-level protocols used to implement the specific stages of the simulation.

  • Metadynamics support is provided via a molecular simulation engine patched by PLUMED. Since it is not possible to use PLUMED in isolation, the BioSimSpace.Process.Plumed class is not exposed to the user, instead being indirectly created as a member of another molecular simulation process, e.g. BioSimSpace.Process.Gromacs, when a metadynamics protocol is chosen. Modifications for specific metadynamics protocols, e.g. adding support for new collective variables, needs to be implemented in the createConfig method of the BioSimSpace.Process.Plumed class.