Using transition_sampling

Upon installing transition_sampling, a command line entry point aimless_driver is created.

aimless_driver inputs.yml [--log-level=INFO] [--log-file=aimless.log]

inputs.yml

describes all necessary inputs for the full pipeline, shown below.

log-level

defaulted to INFO, but can take values DEBUG, INFO, WARNING, ERROR, CRITICAL in order of decreasing granularity.

log-file

defaulted to aimless.log, but can be set to the path log messages should be directed to.

inputs.yml Format

We’ve chosen the YAML format to describe the inputs to aimless_driver. It’s split into three main sections, one for each present in Transition Sampling Workflow. Checkout the example input file on github.

md_inputs (Optional)

These are the required inputs for running aimless shooting and generating new shooting points with MD. If this section is excluded, MD will not be run and we will continue to the next present part.

engine_inputs

enginestr (Required)

Define what MD engine will be used. Currently only cp2k and gromacs

engine_dirstr (Required)

Directory where temporary files created by engine (e.g. md.out) will be placed. If running over multiple nodes, all nodes must be able to access this (i.e. /tmp/* may not work). Files here will not be deleted, so they can be inspected afterwards if anything went wrong.

Note

This should be the full path.

md_cmdstr (Required)

Command to launch one simulation with, excluding any specific input or output files

plumed_filestr (Required)

Path to the PLUMED file containing COMMITTOR basins

delta_tfloat (Required)

The \(\Delta t\) as defined in aimless shooting, in femtoseconds.

Other required engine specific inputs: see MD Engines

aimless_inputs

starts_dirstr (Required)

Path to directory containing .xyz files (in Å) of initial starting guesses

output_namestr (Required)

Prefix to the output names. Two files will be created, <output_name>.xyz and <output_name>.csv. Note that this string should not include an extension.

tempfloat (Required)

Temperature to generate initial velocities at in Kelvin

n_parallelint (Required)

Number of aimless shootings to run in parallel. Total number of simulations running at any given point is given by n_parallel * 2

n_pointsint (Required)

Number of accepted shooting points to be generated by a single aimless shooting before considered “done”

n_state_triesint (Required)

Number of times to reselect a known accepting state on failure to accept

n_vel_triesint (Required)

Number of times to resample velocities after getting a rejected shooting point before retrying known accepting states

acceptor (Optional - can be defined, excluded, or null. In the latter two cases, uses default)

Used to define what cases of committing should be considered accepted.

typestr (default or multibasin)

• If default, accept if the forward and reverse trajectories commit to any different basins

• If multibasin, accept if the forward and reverse trajectories commit to a product basin and a reactant basin, which must be defined as lists below.

reactantslist[int] (Required if type = multibasin)

The basins to be considered as “reactants”

productslist[int] (Required if type = multibasin)

The basins to be considered as “products”

colvar_inputs (Optional)

These are the required inputs to calculate new CVs from the results of aimless shooting. If this section is excluded, new CVs will not be calculated and we will continue to the next present part.

plumed_cmdstr (Required)

Command to launch PLUMED with, the PLUMED binary

plumed_filestr (Required)

Path to the plumed.dat that contains CV definitions

output_namestr (Required)

Path to file that PLUMED should dump CVs to in its COLVAR format

csv_inputstr (Optional)

If you’ve excluded md_inputs and don’t want to run it, you need to explicitly set the file name of the .csv file produced by a previous run. If md_inputs is defined and this field is missing or null, the file name will be inferred from the md_inputs section.

xyz_inputstr (Optional)

If you’ve excluded md_inputs and don’t want to run it, you need to explicitly set the file name of the .xyz file produced by a previous run. If md_inputs is defined and this field is missing or null, the file name will be inferred from the md_inputs section.

likelihood_inputs (Optional)

These are the required inputs to perform likelihood maximization on the results of aimless shooting and calculated CVs If this section is excluded, likelihood maximization will not be performed and the program will exit after completing any preceding sections.

max_cvs: int (Optional)

Set the maximum length of the set of CVs to be considered. If null or missing, all may be considered if the improvement for length i to i+1 is enough as given by Peters.

output_namestr (Required)

Path to the file to put results of maximization in.

csv_inputstr (Optional)

If you’ve excluded md_inputs and don’t want to run it, you need to explicitly set the file name of the .csv file produced by a previous run. If md_inputs is defined and this field is missing or null, the file name will be inferred from the md_inputs section.

colvar_inputstr (Optional)

If you’ve excluded colvar_inputs and don’t want to run it, you need to explicitly set the file name of the COLVAR file produced by a previous run. If colvar_inputs is defined and this field is missing or null, the file name will be inferred from the colvar_inputs section.

n_iterint (Optional)

Global optimization is performed by basinhopping. This is the number of local optimization to perform per global optimizations. If missing, defaults to 100.

use_jacbool (Optional)

Set to true if you want to use use the analytical calculation for the jacobian during optimization, which generally is faster. Set to false to use a finite difference approximation. Defaults to true if excluded.