Skip to content
Python package for running bias-resampling ensemble refinement (BRER) simulations
Python Shell Dockerfile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


Documentation Status Language grade: Python Total alerts


Build Status codecov


Build Status codecov

Set of scripts for running BRER simulations using gmxapi. Details of this method may be found at:

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.9b01407



If you're going to use a pip or a conda environment, you'll need:

  • Python 3.X

  • An installation of gromacs-gmxapi. Currently, gmxapi does not support domain decomposition with MPI, so if you want these simulations to run fast, be sure to compile with GPU support.

  • An installation of gmxapi. This code has only been tested with Gromacs 2019.

  • The plugin code for BRER. Please make sure you install the corr-struct branch, NOT master .

Otherwise, you can just use a Singularity container!


By far the easiest option! If you are working with an older Singularity version (< 3), pull the container hosted on singularity hub:

singularity pull -name myimage.simg shub://jmhays/singularity-brer

If you have the latest and greatest Singuarity (v > 3), you can pull the container from the new cloud repository:

singularity pull library://jmhays/default/brer:latest

For instructions on using the container, please see this repository.

Conda environment

I suggest running this in a conda environment rather than pip install . The following conda command will handle all the gmxapi and sample_restraint python dependencies, as well as the ones for this repository.

  1. conda create -n BRER numpy scipy networkx setuptools mpi4py cmake

    If you want to run the tests, then install pytest as well.

  2. Source the environment and then pip install:

source activate BRER
git clone https: //
cd run_brer
pip install .

Running BRER

Launching a single ensemble member.

An example script, , is provided for ensemble simulations.

Let's work through it piece by piece.

#!/usr/bin/env python

Example run script
for BRER simulations

import run_brer.run_config as rc
import sys

The import run_brer.run_config statement imports a RunConfig object, which handles the following things for a single ensemble member:

  1. Initializing/setting up parameters for the BRER run.
  2. Launching the run.

Then we provide some files and directory paths to the RunConfig object.

init = {
    'tpr': '/home/jennifer/Git/run_brer/tests/syx.tpr',
    'ensemble_dir': '/home/jennifer/test-brer',
    'ensemble_num': 5,
    'pairs_json': '/home/jennifer/Git/run_brer/tests/pair_data.json'

config = rc.RunConfig( ** init)

In order to run a BRER simulation, we need to provide :

  1. a tpr (compatible with GROMACS 2019).
  2. The path to our ensemble. This directory should contain subdirectories of the form mem_<my ensemble number>
  3. 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.
  4. The path to the DEER metadata. Please see the example json in this repository: run_brer/data/pair_data.json

Finally, we launch the run!

You may change various parameters before launching the run using config.set(**kwargs) . For example:

config = rc.RunConfig( ** init)
config.set(A = 100)

resets the energy constant A to 100 kcal/mol/nm^2 before launching a run.

Launching an ensemble

Right now, the way to launch an ensemble is to launch multiple jobs. We hope to soon use the gmxapi features that allow a user to launch many ensemble members in one job.

You can’t perform that action at this time.