Configuring a simulation process

In running molecular dynamics we saw how easy it was to set up and run molecular simulations using BioSimSpace. While in most cases the default options are perfectly satisfactory, on occasion you may wish to customise the process to your specific needs. In addition to its high-level interface, BioSimSpace also provides functionality for low-level configuration, allowing experts to set up and run simulations with specific molecular simulation engines. While this gives the user complete control, it breaks the concept of interoperability, so scripts written in this way are no longer guaranteed to be portable.

import BioSimSpace as BSS

# Here we assume that we've already created a system and defined a protocol.

# Initialise a process to run a simulation with AMBER.
process = BSS.Process.Amber(system, protocol)

# Initialise a process to run a simulation with GROMACS.
process = BSS.Process.Gromacs(system, protocol)

# Initialise a process to run a simulation with NAMD.
process = BSS.Process.Namd(system, protocol)

As with BSS.MD.run, the specific process objects will search your system path for an appropriate executable. To get the name of the executable, run:

process.exe()

If you wish to specify the executable to use, simply use the exe keyword argument:

# Initialise an AMBER simulation process specifying the executable path.
process = BSS.Process.Amber(system, protocol, exe="/path/to/my/binary")

By default, BioSimSpace uses a unique temporary work space for each process. To get the location of the working directory, run:

process.workDir()

Use the work_dir keyword argument to specify the directory:

process = BSS.Process.Amber(system, protocol, work_dir="/path/to/my/work/dir")

When a Process object is created, it automatically writes all of the input and configuration files needed to run the desired protocol. To get the list of autogenerated files:

process.inputFiles()

To get the list of configuration file strings, run:

process.getConfig()

In some cases, you might wish to ammend the default configuration parameters. BioSimSpace provides several ways of doing this.

 # Set the configuration from file.
 process.setConfig("my_config.txt")

 # Set the configuration using a list of configuration strings.
 my_config = ["some config parameter string", "another config parameter string"]
 process.setConfig(my_config)

It is also possible to add to the existing list of parameters:

# Add using a configuration from file.
process.addToConfig("my_config.txt")

# Add a list of parameter strings to the configuration.
my_config = ["some config parameter string", "another config parameter string"]
process.addToConfig(my_config)

If you ever want to revert to the original configuration, simply run:

process.resetConfig()

Where necessary, BioSimSpace will configure the command-line arguments needed to run the process.

To view the command-line argument string, run:

process.getArgString()

The arguments are stored internally as an OrderedDict object. To view it, run:

process.getArgs()

BioSimSpace provides functionality for setting and manipulating the arguments. For example, to disable the overwriting of output files in an AMBER process:

process.setArg('-O', False)

The setArg method can be used to add a new argument, or to overwrite the value of an existing argument. There are several other methods that allow the arguments to be modified:

process.setArgs(args)                    # Overwrite all arguments with a new dictionary.
process.addArgs(args)                    # Append additional arguments.
process.insertArgs(arg, value, index)    # Insert an argument at a specific index.
process.deleteArg(arg)                   # Delete an argument from the dictionary.
process.clearArgs()                      # Clear all of the arguments.

If you ever get in trouble, it’s easy to reset the arguments to their default values:

process.resetArgs()

Once you are happy with how the process is configured, it can be started by running:

process.start()