Developer API

directory_helper

Organizes the directory structure for BRER runs. Creates directories on the fly.

How the directory structure is organized:

• This script should be run from your “top” directory (where you are planning to run all your ensemble members)

• The top directory contains ensemble member subdirectories This script is intended to handle just ONE ensemble member, so we’ll only be concerned with a single member subdirectory.

• The example below is for the first iteration (iter 0) of one of the members. Future iterations would go in directories 1,2,…y

class brer.directory_helper.DirectoryHelper(top_dir, param_dict)

Small class for manipulating a standard directory structure for BRER runs.

Parameters:

• top_dir – the path to the directory containing all the ensemble members.

• param_dict – a dictionary specifying the ensemble number, the iteration, and the phase of the simulation.

Examples

>>> .
>>> ├── 0
>>> │   ├── converge_dist
>>> │   │   ├── state.cpt
>>> │   │   ├── state_prev.cpt
>>> │   │   └── traj_comp.part0001.xtc
>>> │   ├── production
>>> │   │   ├── confout.part0005.gro
>>> │   │   ├── state.cpt
>>> │   │   ├── state_prev.cpt
>>> │   │   ├── state_step4622560.cpt
>>> │   │   ├── traj_comp.part0002.xtc
>>> │   └── training
>>> │       ├── state.cpt
>>> │       ├── state_prev.cpt
>>> │       └── traj_comp.part0001.xtc
>>> ├── state.json
>>> ├── state_{iteration}.json
>>> ├── submit.slurm
>>> └── syx.tpr

build_working_dir()

Checks to see if the working directory for current state of BRER simulation exists. If it does not, creates the directory.

change_dir(level)

Change to directory specified by level.

Parameters:

level (str) – How far to go down the directory tree. Can be one of ‘top’, ‘ensemble_num’, ‘iteration’, or ‘phase’.

get_dir(level)

Get the directory for however far you want to go down the directory tree.

Parameters:

level (str) – one of ‘top’, ‘ensemble_num’, ‘iteration’, or ‘phase’. See the directory structure example provided at the beginning of this class.

Returns:

the path to the specified directory level.

Return type:

str

plugin_configs

Classes used to build gmxapi plugins for all phases of a BRER iteration.

Each class corresponds to one restraint potential provided by :py:mod`brer.md`. Each instance corresponds to one restrained pair in a single simulation phase.

class brer.plugin_configs.PluginConfig(sites, logging_filename)

Abstract class for the BRER potential configurations.

Provide base class functionality and required interface to build training, convergence, and production phase pluggable MD potentials.

Parameters:

• sites (list[int]) –

• logging_filename (str) –

abstract build_plugin()

Abstract method for building a plugin.

To be determined by the phase of the simulation (training, convergence, production)

create_from(obj)

Get an instance of the appropriate type from the provided data structure.

Source obj is either a Mapping or an object with the fields necessary to initialize a cls instance.

Extra fields in obj are ignored.

class brer.plugin_configs.TrainingPluginConfig(sites, logging_filename, A, num_samples, target, tau, tolerance)

Configure BRER potential for the training phase.

The BRER training phase uses the MD potential provided by brer.brer_restraint().

See https://pubs.acs.org/doi/10.1021/acs.jpclett.9b01407 for details.

Parameters:

• sites (list[int]) –

• logging_filename (str) –

• A (float) –

• num_samples (int) –

• target (float) –

• tau (float) –

• tolerance (float) –

build_plugin()

Builds training phase plugin for BRER simulations.

Returns:

a gmxapi WorkElement to be added to the workflow graph

Return type:

WorkElement

class brer.plugin_configs.ConvergencePluginConfig(sites, logging_filename, alpha, sample_period, target, tolerance)

Configure BRER potential for the convergence phase.

The BRER convergence phase uses the MD potential provided by brer.linearstop_restraint().

See https://pubs.acs.org/doi/10.1021/acs.jpclett.9b01407 for details.

Parameters:

• sites (list[int]) –

• logging_filename (str) –

• alpha (float) –

• sample_period (float) –

• target (float) –

• tolerance (float) –

build_plugin()

Builds convergence phase plugin for BRER simulations.

Returns:

a gmxapi WorkElement to be added to the workflow graph

Return type:

WorkElement

Raises:

ValueError – If inappropriate values are detected for any fields.

class brer.plugin_configs.ProductionPluginConfig(sites, logging_filename, alpha, sample_period, target)

Configure BRER potential for the convergence phase.

The BRER production phase uses the MD potential provided by brer.linear_restraint().

See https://pubs.acs.org/doi/10.1021/acs.jpclett.9b01407 for details.

Parameters:

• sites (list[int]) –

• logging_filename (str) –

• alpha (float) –

• sample_period (float) –

• target (float) –

build_plugin()

Builds production phase plugin for BRER simulations.

Returns:

a gmxapi WorkElement to be added to the workflow graph

Return type:

WorkElement

Raises:

ValueError – If inappropriate values are detected for any fields.

MD potentials

MD potentials for BRER simulation workflows.

As of 2022, we are still using the old gmxapi 0.0.7 style WorkElement to connect pluggable extension code to the GROMACS simulator. The WorkElement is constructed by the brer.plugin_configs module by encoding an entry point function and its input parameters.

Entry points

The following creation functions are used to support creation of gmxapi pluggable GROMACS restraint potentials. The entry point function consumes a gmxapi.simulation.workflow.WorkElement to produce an opaque object that can finish setting up the interactions with the gmxapi simulator lifetime management.

In addition to the parameters described below, all restraint potentials require a sites parameter.

sites

(list[int]) Describe the pair distance relevant to an instance of a BRER potential. The list is a sequence of two or more sites, expressed as atom indices in the molecular model. The first and last index define the origin and tip of the displacement vector. In the case that this vector may be ambiguous with respect to periodic boundary conditions (if the sites are likely to ever be further apart on the molecule than half of the shortest simulation box dimension), additional indices can be inserted between the first and last element to define a sequence of vectors that can reliably sum to the intended vector.

brer.md.linear_restraint()

Configure the BRER potential used for the production phase.

Parameters:

• alpha (float) – coupling parameter.

• target (float) – site displacement distance to bias towards.

• sample_period (float) – time between samples (simulator time units)

• logging_filename (str) – output file

brer.md.linearstop_restraint()

Configure the BRER potential used during the convergence phase.

Parameters:

• alpha (float) – coupling parameter.

• target (float) – site displacement distance to bias towards.

• tolerance (float) – convergence detection parameter

• sample_period (float) – time between samples (simulator time units)

• logging_filename (str) – output file

brer.md.brer_restraint()

brer_restraint(arg0: object) -> brer.md.BRERBuilder

Configure the self-tuning potential for the BRER training phase.

Configure the BRER potential used for the training phase.

Parameters:

• A (float) – control the maximum energy input while training the coupling parameter.

• tau (float) – time constant for sample smoothing (simulator time units).

• tolerance (float) – convergence detection parameter

• target (float) – site displacement distance to bias towards.

• num_samples (float) – number of samples to average at each update.

• logging_filename (str) – output file

During execution, the pair distance is regularly sampled. To smooth fluctuations, a rolling average is maintained over a period tau. A measurement is recorded and the average is updated at intervals of tau/num_samples.

For additional explanation of A, see White and Voth, https://doi.org/10.1021/ct500320c