1. Installation

1.1 Install packages

# mamba works the same as conda.
mamba create -n grand_RE openmm openmmtools pymbar-core numpy mdanalysis openmpi=4.1.5 mpi4py parmed
# install specific openmpi/mpich on your cluster, 4.1.5 is only an example
mamba activate grand_RE
pip instal .

or use the environment.yml file

name: grand_RE
channels:
  - conda-forge
dependencies:
  - python=3.12
  - pip
  - numpy
  - openmm
  - openmmtools
  - pymbar-core
  - mdanalysis
  - openmpi=4.1.5
  - mpi4py
  - parmed
  - pip:
    - git+https://github.com/huichenggong/grand.git

mamba env create -f environment.yml

1.2 Add the kernel to jupyter notebook

mamba install ipykernel ipywidgets -y
python -m ipykernel install --user --name grand_RE

1.3 Later in the job script / on the cluster

source /home/NAME/SOFTWARE/miniforge3/bin/activate grand_RE
module add openmpi4/gcc/4.1.5 # example, be consistent with version inside the conda env
which mpirun # check if the correct mpirun is used

1.X Uninstall

jupyter kernelspec uninstall unwanted-kernel  # use the name of your jupyter kernel
conda remove -n grand_RE --all

Further development of GCMC

1.2.1

NonequilibriumGCMCSphereSamplerMultiState is added for Hamiltonian replica exchange. The implementation is validated by solvation free energy. Same results are obtained as Gromacs NPT.

The mathematical derivation is as follows.

$$\pi \left( \begin{array}{c} \textbf{r}_1, N_1, U_1, \\ \textbf{r}_2, N_2, U_2, \\ \vdots \\ \end{array} \middle\lvert \beta,\mu \right) = \frac{1}{Z_1} \frac{V^{N_1}}{\Lambda^{3N_1} N_1!} {exp \Big(-\beta \big(U_1(\textbf{r}_1) -\mu N_1 \big) \Big)} ... $$

Acceptance ratio
If all the replicas has the same temperature ($\beta$) and chemical potential ($\mu$), but different Hamiltonian ($U$).

$$\frac{\pi_b}{\pi_a} =\frac{\pi (\textbf{r}_2, N_2, U_1|\beta, \mu) \ \pi (\textbf{r}_1, N_1, U_2|\beta, \mu)} {\pi (\textbf{r}_1, N_1, U_1|\beta, \mu) \ \pi (\textbf{r}_2, N_2, U_2|\beta, \mu)} =exp(-\beta \Delta U) $$

1.1.1

Add support for Charmm force field.

Forked from Essex Lab

grand : Grand Canonical Water Sampling in OpenMM

Background

This Python module is designed to be run with OpenMM in order to simulate grand canonical Monte Carlo (GCMC) insertion and deletion moves of water molecules. This allows the particle number to vary according to a fixed chemical potential, and offers enhanced sampling of water molecules in occluded binding sites. The theory behind our work on GCMC sampling can be found in the References section below.

Installation & Usage

This module can be installed from this directory by running the following command:

python setup.py install

The unit tests can then be carried out by running the following command from this directory:

python setup.py test

The dependencies of this module can be installed as:

conda install -c conda-forge -c omnia openmmtools
pip install lxml

Many of grand's dependencies (openmm, mdtraj, pymbar, parmed) are also dependencies of openmmtools, and will be installed alongside openmmtools.

Alternatively, grand and its dependencies can be installed via conda:

conda install -c omnia -c anaconda -c conda-forge -c essexlab grand

Several (very short) examples of how this module is ran alongside OpenMM can be found in the examples/ directory. Additional examples and documentation are also available, although please note that the examples listed within the grand-paper repo are intended to be run using version 1.0.x of grand and may not work with later versions.

Citing grand

The grand module is released under the MIT licence. If results from this module contribute to a publication, we ask that you cite Refs. 1 and 2, below. Ref. 1 discusses the initial implemention while ref. 2 discusses the implementation and testing of the non-equilibrium moves. Additional references describing the theory upon which the GCMC implemention in grand is based are also provided below (Refs. 3-4).

Contributors

• Marley Samways <[email protected]>
• Hannah Bruce Macdonald
• Ollie Melling <[email protected]>
• Will Poole <[email protected]>

Contact

If you have any problems or questions regarding this module, please contact one of the contributors, or send an email to <[email protected]>.

References

1. M. L. Samways, H. E. Bruce Macdonald, J. W. Essex, J. Chem. Inf. Model., 2020, 60, 4436-4441, DOI: https://doi.org/10.1021/acs.jcim.0c00648
2. O. J. Melling, M. L. Samways, Y. Ge, D. L. Mobley, J. W. Essex, J. Chem. Theory Comput., 2023, DOI: https://doi.org/10.1021/acs.jctc.2c00823
3. G. A. Ross, M. S. Bodnarchuk, J. W. Essex, J. Am. Chem. Soc., 2015, 137, 47, 14930-14943, DOI: https://doi.org/10.1021/jacs.5b07940
4. G. A. Ross, H. E. Bruce Macdonald, C. Cave-Ayland, A. I. Cabedo Martinez, J. W. Essex, J. Chem. Theory Comput., 2017, 13, 12, 6373-6381, DOI: https://doi.org/10.1021/acs.jctc.7b00738