User API

run_brer

RunConfig class handles the actual workflow logic.

class run_brer.run_config.RunConfig(tpr: Union[str, Path, Sequence[Union[str, Path]]], ensemble_dir, ensemble_num: Optional[int] = None, pairs_json='pair_data.json')

Run configuration for single BRER ensemble member.

The run configuration specifies the files and directory structure used for the run. It determines whether the run is in the training, convergence, or production phase, then performs the run.

Parameters

  • tpr (str) – path (or paths) to tpr input. Must be compatible with the GROMACS version providing gmxapi.

  • ensemble_dir (str) – path to top directory which contains the full ensemble.

  • ensemble_num (int, optional) – the ensemble member to run, by default 1

  • pairs_json (str, optional) – path to file containing ALL the pair metadata. An example of what such a file should look like is provided in the data directory, by default ‘pair_data.json’

  • input (Note that all instances of RunConfig need the same sized array of TPR) –

  • of (files across all ranks in an MPI ensemble because they must all be capable) –

  • description. (constructing a compatible copy of the ensemble simulation work) –

build_plugins(plugin_config: PluginConfig)

Builds the plugin configuration. For each pair-wise restraint, populate the plugin with data: both the “general” data and the data unique to that restraint.

Parameters

plugin_config (PluginConfig) – the particular plugin configuration (Training, Convergence, Production) for the run.

run(tpr_file=None, **kwargs)

Perform the MD simulations.

Each Python interpreter process runs a separate ensemble member.

Parameters

  • tpr_file (str, optional) – If provided, use this input file instead of the input from the main configuration.

  • **kwargs (optional) – Additional key word arguments are passed on to the simulator.

After the first “iteration”, run_brer bootstraps the training and convergence phase’s trajectory with the checkpoint file from the previous iteration’s production phase.

At the beginning of a production phase (when there is not yet a checkpoint file), the checkpoint file from the convergence phase is used to start the production trajectory unless tpr_file is given.

When tpr_file is not None, run() does not look for a bootstrapping checkpoint file. This can be helpful if a checkpoint file is corrupted or unavailable. In general, this means that the tpr_file argument should include the starting configuration you intend for the phase that you are about to run(). If you are providing the tpr_file because you are changing parameters that render existing checkpoints incompatible, you need to either generate the file with the checkpoint from which you want to continue, or you may remove the checkpoint file from the phase directory and restart that phase.

Example

>>> config_params = {
...     "tpr": "{}/topol.tpr".format(data_dir),
...     "ensemble_num": 1,
...     "ensemble_dir": tmpdir,
...     "pairs_json": "{}/pair_data.json".format(data_dir)
... }
>>> rc = RunConfig(**config_params)
>>> assert rc.run_data.get('phase') == 'training'
>>> rc.run(threads=2)
>>> assert rc.run_data.get('phase') == 'convergence'
>>> rc.run()
>>> assert rc.run_data.get('phase') == 'production'
>>> rc.run(tpr_file=new_tpr, max_hours=23.9)

run_config

Class that handles the simulation data for BRER simulations.

class run_brer.run_data.RunData

Stores (and manipulates, to a lesser extent) all the metadata for a BRER run.

The full set of metadata for a single BRER run include both the general parameters and the pair-specific parameters.

as_dictionary()

Get the run metadata as a heirarchical dictionary:

Returns

heirarchical dictionary of metadata

Return type

type

Examples

>>> ├── pair parameters
>>> │   ├── name of pair 1
>>> │   │   ├── alpha
>>> │   │   ├── target
>>> │   │   └── ...
>>> │   ├── name of pair 2
>>> |
>>> ├── general parameters
>>>     ├── A
>>>     ├── tau
>>>     ├── ...
clear_pair_data()

Removes all the pair parameters, replace with empty dict.

from_dictionary(data: dict)

Loads metadata into the class from a dictionary.

Parameters

data (dict) – RunData metadata as a dictionary.

from_pair_data(pd: PairData)

Load some of the run metadata from a PairData object. Useful at the beginning of a run.

Parameters

pd (PairData) – object from which metadata are loaded

get(key, *, name=None)

get either a general or a pair-specific parameter.

Parameters

  • key (str) – the parameter to get.

  • name (str) – if getting a pair-specific parameter, specify the restraint name. (Default value = None)

Return type

the parameter value.

load_config(fnm='state.json')

Load state parameters from file.

Parameters

fnm (str, optional) – log file of state parameters, by default ‘state.json’

save_config(fnm='state.json')

Saves the run parameters to a log file.

Parameters

fnm (str, optional) – log file for state parameters, by default ‘state.json’

set(name=None, **kwargs)

method used to set either general or a pair-specific parameter.

Parameters

name (str, optional) – restraint name. These are the same identifiers that are used in the RunConfig, by default None

Raises

ValueError – if you provide a name and try to set a general parameter or don’t provide a name and try to set a pair-specific parameter.