ProtoCaller.Simulation package

This package automates free energy simulations based on the input files created from Ensemble. The module currently consists of a single class: RunGMX. Through this class, it is possible to streamline free energy calculations in an accessible way. One can either instantiate this class with a single GRO and TOP file or with several topologies and/or initial coordinates. In any case the lambda values have to be passed to the initialiser.

The main function of the method is runSimulation(). It enables running simulations based on protocols generated through Protocol. The different lambda windows can be run either sequentially or in parallel where the user can optionally specify OpenMP and MPI threads. If the detected GROMACS version is patched with PLUMED, the user can also perform replica exchange between adjacent lambda windows.

The GROMACS binary is detected automatically from the bash aliases “gmx” and “gmx_mpi”. If the used binaries are not satisfactory, the user can set the environment variable GROMACSHOME to the path where the bin/ directory is located. Alternatively, one can set the ProtoCaller.GROMACSEXE and/or the ProtoCaller.GROMACSMPIEXE variables to the absolute path of the desired binary.

A useful example of this module in action can be found here.

Module contents

class ProtoCaller.Simulation.RunGMX(name, gro_files, top_files, work_dir=None, **lambda_dict)

Bases: object

A wrapper for performing a run in GROMACS.

Parameters

  • name (str) – The name of the run.

  • gro_files (str) – Path(s) to the input GRO file(s).

  • top_files ([str] or str) – Path(s) to the input TOP file(s).

  • work_dir (str, optional) – Initialises the run in a custom directory.

  • lambda_dict – Initialises lambda_dict.

files

A dictionary with extensions as keys and absolute paths to files as values.

Type

dict

lambda_dict

A dictionary of lists of lambda values. All of them must be of the same length.

Type

dict

protocols

A list of Protocol objects corresponding to the already run protocols.

Type

[ProtoCaller.Protocol.Protocol]

mbar_data

Data which is to be passed to pymbar.

Type

numpy.ndarray

generateMBARData(n_cores=None, n_nodes=1, cont=True)

Manually generates input data for MBAR using gmx mdrun -rerun using N topologies and N trajectories generated from N simulations (N squared energy evaluations are needed). Doesn’t work with constrained simulations. For most cases one should instead use the XVG files readily generated by GROMACS during the simulation.

Parameters

n_cores (int or None, optional) – Number of cores used. Default: the same as the number of replicas.

n_nodesint, optional

Number of nodes used.

contbool, optional

Whether to overwrite existing files or to continue from the last one.

Returns

mbar_data – Data which is to be passed to pymbar.

Return type

numpy.ndarray

property lambda_size

Returns the number of lambda windows.

Type

int

runMBAR(n_points_to_ignore=1, temperature=298)

Runs pymbar and outputs to the logger. Note that this option is only valid after running generateMBARData(). For regular data output by GROMACS one should use external scripts such as alchemical_analysis.

Parameters

  • n_points_to_ignore (int, optional) – Number of initial points which are to be excluded in the calculation.

  • temperature (float, optional) – The temperature at which the simulations were originally run.

Returns

  • f (numpy.ndarray) – The free energy matrix output by pymbar.

  • df (numpy.ndarray) – The statistical uncertainty matrix output by pymbar.

runSimulation(name, multi=False, multidir=False, single_lambda=None, use_mpi=False, mdrun_mpi=False, gpu_id=None, use_preset=None, replex=None, plumed_file=None, n_cores_per_process=None, n_nodes=1, n_processes=None, dlb=False, gmx_kwargs=None, **protocol_params)

Runs a simulation in GROMACS.

Parameters

  • name (str) – The name of the simulation.

  • multi (bool, optional) – Whether to run the simulations in parallel, using -multi.

  • multidir (bool, optional) – Whether to run the simulations in parallel, using -multidir. Overrides multi.

  • single_lambda (None, int, optional) – An integer runs a simulation at a single lambda value and overrides multi and replex. None runs all lambda values.

  • use_mpi (bool, optional) – Whether to use ProtoCaller.GROMACSEXE or GROMACSMPIEXE.

  • mdrun_mpi (bool, optional) – Whether to call mdrun as “mdrun” or as “mdrun_mpi”.

  • gpu_id (str, optional) – Which GPU id to be used, if applicable.

  • use_preset (str, Protocaller.Protocol.Protocol, None) – Which default preset to use. One of: “minimisation”, “equilibration_nvt”, “equilibration_npt”, “production” “vacuum”. You can alternatively pass a custom protocol here, in which case **protocol_params will not be used.

  • replex (int or None, optional) – Attempts replica exchange after replex number of steps using PLUMED. None means no replica exchange. Overrides use_mpi and multi if not None.

  • plumed_file (str, optional) – If replex is True, it uses this file as a configuration for PLUMED, otherwise an empty file is used.

  • n_cores_per_process (int or None, optional) – Number of cores used per process. Default: let GROMACS decide.

  • n_nodes (int, optional) – Number of physical nodes used.

  • n_processes (int, optional) – Number of processes. Default: the same as the number of simulation.

  • dlb (bool) – Whether to enable dynamic load balancing. Default is False due to some possible instabilities with gmx_mpi mdrun in some cases.

  • gmx_kwargs (dict) – Additional arguments to be passed to mdrun. The keys of the dictionary need to be the name of the option, e.g. “cpt” for checkpoint interval, while the values need to be the value of the option if it permits one or None if it doesn’t. If the values contain “{}” while the user is running the lambda windows in serial, this will be replaced by the lambda number.

  • protocol_params – Keyword arguments passed to ProtoCaller.Protocol.Protocol.