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 run_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: str) str
Get the directory for however far you want to go down the directory tree.
- Parameters
level – one of ‘top’, ‘ensemble_num’, ‘iteration’, or ‘phase’. See the directory structure example provided at the beginning of this class.
- Return type
the path to the specified directory ‘level’ as a str.
metadata
Abstract class for handling all BRER metadata.
State and PairData classes inherit from this class.
- class run_brer.metadata.MetaData(name)
Construct metadata object. and give it a name.
- Parameters
name – Give your MetaData class a descriptive name.
- get(key)
Get the value of a parameter of the class.
- Parameters
key (str) – The name of the parameter you wish to get.
- Return type
The value of the parameter associated with the key.
- get_as_dictionary()
Get all of the current parameters of the class as a dictionary.
- Returns
dictionary of class parameters
- Return type
- get_missing_keys()
Gets all of the required parameters that have not been set.
- Returns
A list of required parameter names that have not been set.
- Return type
- get_requirements()
Gets the set of required parameters for the class. This is quite useful for checking if there are any missing parameters before beginning a run.
- Returns
required parameters of the class
- Return type
- set(key=None, value=None, **kwargs)
Sets a parameter of the class. Checks whether or not the parameter is required and reports information about requirements. You can pass the key,value pairs either as a key and value or as a set of
**kwargs.- Parameters
key (str, optional) – parameter name, by default None
value (any, optional) – parameter value, by default None
- class run_brer.metadata.MultiMetaData
A single class that handles multiple MetaData classes (useful when restraining multiple atom-atom pairs).
- add_metadata(metadata: MetaData)
Appends new MetaData object to self._metadata.
- Parameters
metadata (MetaData) – metadata to append
- id_to_name(id)
Converts the index of one of the MetaData classes to it’s associated name.
- name_to_id(name)
Converts the name of one of the MetaData classes to it’s associated list index (it’s idx in self._metadata)
- Parameters
name (str) – the name of a MetaData class.
- Returns
the index of the MetaData class in the self._metadata list.
- Return type
- Raises
IndexError – Raise IndexError if no metadata have been loaded.
- property names
getter for names.
- Returns
list of names
- Return type
- Raises
IndexError – Raise IndexError if no metadata have been loaded.
pair_data
Classes to handle 1) pair metadata 2) resampling from DEER distributions at each new BRER iteration.
- class run_brer.pair_data.PairData(name)
Class to handle pair metadata (distribution, bins, atom ids)
Construct metadata object. and give it a name.
- Parameters
name – Give your MetaData class a descriptive name.
plugin_configs
Classes used to build gmxapi plugins for all phases of a BRER iteration.
Each class corresponds to ONE restraint since gmxapi plugins each correspond to one restraint.
- class run_brer.plugin_configs.PluginConfig
Abstract class used to build training, convergence, and production plugins.
Construct metadata object. and give it a name.
- Parameters
name – Give your MetaData class a descriptive name.
- abstract build_plugin()
Abstract method for building a plugin.
To be determined by the phase of the simulation (training, convergence, production)
- scan_dictionary(dictionary)
Scans a dictionary and stores whatever parameters it needs for the build_plugin.
- Parameters
dictionary (dict) – a dictionary containing metadata, some of which may be needed for the run. The dictionary may contain extra data, i.e., this can be a superset of the needed plugin data.
- scan_metadata(data)
This scans a RunData or PairData obj and stores whatever parameters it needs for a run.
- Parameters
data – either type RunData or type PairData
- class run_brer.plugin_configs.TrainingPluginConfig
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.
Construct metadata object. and give it a name.
- Parameters
name – Give your MetaData class a descriptive name.
- class run_brer.plugin_configs.ConvergencePluginConfig
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.
Construct metadata object. and give it a name.
- Parameters
name – Give your MetaData class a descriptive name.
- class run_brer.plugin_configs.ProductionPluginConfig
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.
Construct metadata object. and give it a name.
- Parameters
name – Give your MetaData class a descriptive name.