Package: brer-md
Source:https://github.com/kassonlab/brer-mdDocumentation:https://kassonlab.github.io/brer-md/Thebrer-mdPython package provides a set of scripts for running
Bias-Resampling Ensemble Refinement (BRER) simulations usinggmxapi. Details of the BRER
method may be found in:Hays, J. M., Cafiso, D. S., & Kasson, P. M. Hybrid Refinement of
Heterogeneous Conformational Ensembles using Spectroscopic Data.The
Journal of Physical Chemistry Letters. DOI:10.1021/acs.jpclett.9b01407InstallationRequirementsIf you’re going to use a pip or a conda environment, you’ll need:Python 3.8 or newer.A GROMACS installation supporting client software builds.gmxapifor GROMACS.brer-mdincludes a simple C++ extension module that can be attached to a GROMACS
molecular dynamics (MD) simulator through the gmxapi Python interface.
GROMACS installations (and GROMACS dependencies) can be built rather specifically
for their computing environments. Thebrerpackage is distributed as source
code that must be built for a specific GROMACS installation.NoteFor several recent versions of GROMACS, the “legacy API” needs
to be enabledexplicitlywhen GROMACS is configured.
TheGMX_INSTALL_LEGACY_APIGROMACS CMake variable isnot documented.
Example:cmake /path/to/gromacs/sources -DGMX_INSTALL_LEGACY_API=ON -DGMX_THREAD_MPI=ONPython environmentWe recommend using a separate Python virtual environment for each research project,
tied to specific versions of the software tools you use. If your computing
environment provides Python packages such asmpi4pythat may be difficult
to configure, you should try to use the provided packages in your virtual environment.
Example:python3 -m venv --system-site-packages myprojectvenv
. myprojectvenv/bin/activate
myprojectvenv/bin/python -m pip install --upgrade pipThen, follow the installation instructions for GROMACS andgmxapi.Build and InstallWe recommend installing the package withpip.Generally,pipwill automatically install any package dependencies.If a GROMACS installation is discoverable (you have “sourced” a GMXRC file or
defined a GROMACS_DIR environment variable), then thegmxapiPython package
will be installed automatically with thebrerpackage.
Simply:pip install --pre brer-md
# or
pip install git+https://github.com/kassonlab/brer-md.gitIf you prefer to installgmxapiseparately (such as to specify an older
package version), you can provide--no-depsand--no-build-isolationtopip install, and the existinggmxapiinstallation will be used.You can pre-install (other) required packages using therequirements.txtfile.
Therequirements.txtfile does not include thegmxapidependency.Example:pip show gmxapi |grep Version
# Version: 0.3.1
wget https://github.com/kassonlab/brer-md/blob/main/requirements.txt
pip install -r requirements.txt
pip install --no-deps --no-build-isolation brerThe Python package builder will manage compilation of the C++ GROMACS client
usingcmake
documentation.
If the GROMACS installation or C++ toolchain cannot be determined automatically,
you may need to provide additional hints.
See alsoGROMACS release
notes.Example:gmx --version |grep prefix
# Data prefix:  /Users/eric/install/gromacs2022
CMAKE_ARGS="-C /Users/eric/install/gromacs2022/share/cmake/gromacs/gromacs-hints.cmake" \
pip install brerRunning BRERLaunching a single ensemble member.An example script,run.py, is provided for ensemble simulations.Let’s work through it piece by piece.#!/usr/bin/env python

"""
Example run script
for BRER simulations
"""

import brer.run_config as rc
import sysTheimport brer.run_configstatement imports aRunConfigobject, which handles the following thingsfor a single ensemble
member:Initializing/setting up parameters for the BRER run.Launching the run.Then we provide some files and directory paths to theRunConfigobject.init = {
    'tpr': '/home/jennifer/Git/brer-md/tests/syx.tpr',
    'ensemble_dir': '/home/jennifer/test-brer',
    'ensemble_num': 5,
    'pairs_json': '/home/jennifer/Git/brer-md/tests/pair_data.json'
}

config = rc.RunConfig(**init)In order to run a BRER simulation, we need to provide :atpr(compatible with GROMACS 2019).The path to our ensemble. This directory should contain
subdirectories of the formmem_<my ensemble number>The ensemble number. This is an integer used to identify which
ensemble member we are running and thus, the subdirectory in which we
will be running our simulations.The path to the DEER metadata. Please see the example json in this
repository:src/brer/data/pair_data.jsonFinally, we launch the run!config.run()You may change various parameters before launching the run usingconfig.set(**kwargs). For example:config = rc.RunConfig(**init)
config.set(A=100)
config.run()resets the energy constant A to 100 kcal/mol/nm^2 before launching a
run.Launching an ensembleRight now, the way to launch an ensemble is to launch multiple jobs. We
hope to soon use thegmxapifeatures that allow a user to
launch many ensemble members in one job.TroubleshootingMismatched compiler toolchainOne of the most common installation problems is related to incompatible
compiler toolchains between GROMACS, gmxapi, and the plugin module. *
CMake may warn “You are compiling with a different C++ compiler from the
one that was used to compile GROMACS.” * When youimportthebrermodule, you may get an error like the following.ImportError:dlopen(...):symbol not found in flat namespace '__ZN6gmxapi10MDWorkSpec9addModuleENSt3__110shared_ptrINS_8MDModuleEEE'You can either set theCMAKE_CXX_COMPILER, explicitly, or you can
use the GROMACS-installed CMake hints file.You will have to rebuild and reinstall thebrermodule.Remove any cached built packages:pip cache remove brerIf you previously installed without build isolation you may havebuildordistdirectories that should be removed, as well.When attempting to build the package again, provide extra hints to CMake through
the Python package builder by adding strings to the CMAKE_ARGS environment
variable.For GROMACS 2022 and newer, you would invokecmakewith something
like the following. (The exact path will depend on your installation.)CMAKE_ARGS="-C /path/to/gromacs_installation/share/cmake/gromacs/gromacs-hints.cmake" \
pip install brerFor GROMACS 2021 and older,CMAKE_ARGS="-DCMAKE_TOOLCHAIN_FILE=/path/to/gromacs_installation/share/cmake/gromacs/gromacs-toolchain.cmake" \
pip install brerSeeGROMACS release
notes.Problems building a GROMACS 2019 stackFor some C++ standard library installations, GROMACS 2019 exhibits compiler errors.
The sources need to be patched. You can use theci_scripts/limits.patchfile in this
repository as a guide to manually edit the source, or use thepatchcommand line tool.
Example:cd /path/to/gromacs2019/sources
wget https://raw.githubusercontent.com/kassonlab/brer-md/main/ci_scripts/limits.patch
patch -p1 < limits.patchFor GROMACS 2019, you will need gmxapi 0.0.7.
Seehttps://gmxapi.readthedocs.io/en/release-0_0_7/.You will have to preventbrer-mdfrom trying to install a more recent version of gmxapi.
Install the dependencies explicitly, then suppress automatic dependency resolution
when installing brer-md.
Exxample:wget https://raw.githubusercontent.com/kassonlab/brer-md/main/requirements.txt
pip install -r requirements.txt
pip install --no-deps brer-mdReferencesHays, J. M., Cafiso, D. S., & Kasson, P. M. Hybrid Refinement of
Heterogeneous Conformational Ensembles using Spectroscopic Data.The
Journal of Physical Chemistry Letters2019. DOI:10.1021/acs.jpclett.9b01407Irrgang, M. E., Hays, J. M., & Kasson, P. M. gmxapi: a high-level
interface for advanced control and extension of molecular dynamics
simulations.Bioinformatics2018. DOI:10.1093/bioinformatics/bty484