README.md

SOMD2

Open-source GPU accelerated molecular dynamics engine for alchemical free-energy simulations. Built on top of Sire and OpenMM. The code is still under active development and is not yet ready for general use.

Installation

First create a conda environment using the provided environment file:

conda env create -f environment.yaml

(We recommend using Miniforge.)

Now install somd2 into the environment:

conda activate somd2
pip install --editable .

You should now have a somd2 executable in your path. To test, run:

somd2 --help

Usage

In order to run an alchemical free-energy simulation you will need to first create a stream file containing the perturbable system of interest. This can be created using BioSimSpace. For example, following the tutorial here. Once the system is created, it can be streamed to file using, e.g.:

import BioSimSpace as BSS

BSS.Stream.save(system, "perturbable_system")

You can then run a simulation with:

somd2 perturtbable_system.bss

The help message provides information on all of the supported options, along with their default values. Options can be specified on the command line, or using a YAML configuration file, passed with the --config option. Any options explicity set on the command line will override those set via the config file.

An example perturbable system for a methane to ethanol perturbation in solvent can be found here. This is a bzip2 compressed file that will need to be extracted before use.

Running SOMD2 using one or more GPUs

In order to run using GPUs you will first need to set the relevant environment variable. For example, to run using 4 CUDA enabled GPUS set CUDA_VISIBLE_DEVICES=0,1,2,3 (for openCL and HIP use OPENCL_VISIBLE_DEVICES and HIP_VISIBLE_DEVICES respectively).

By default SOMD2 will run using the CPU platform, however if the relevant environment variable has been set (as above) the new platform will be detected and set. In the case that this detection fails, or if there are multiple platforms available, the --platform option can be set (for example --platform cuda).

By default, SOMD2 will automatically manage the distribution of lambda windows across all listed devices. In order to restrict the number of devices used the --max_gpus option can be set, for example setting max_gpus=2 while CUDA_VISIBLE_DEVICES are set as above would restrict SOMD2 to using only GPUs 0 and 1.

Analysis

Simulation output will be written to the directory specified using the --output-directory parameter. This will contain a number of files, including Parquet files for the energy trajectories of each λ window. These can be processed using BioSimSpace as follows:

import BioSimSpace as BSS

pmf1, overlap1 = BSS.FreeEnergy.Relative.analyse("output1")

(Here we assume that the output directory is called output1.)

To compute the relative free-energy difference between two legs, e.g. legs 1 and 2, you can use:

pmf2, overlap2 = BSS.FreeEnergy.Relative.analyse("output2")

free_nrg = BSS.FreeEnergy.Relative.difference(pmf1, pmf2)

Note for SOMD1 users

For existing users of somd1, it's possible to generate input for somd2 by passing --somd2 True to the prepareFEP.py setup script. This will write a somd2 compatible stream file.

Additionally, somd2 can be run in somd1 compatibility mode by passing the --somd1-compatibility command-line option to the somd2 executable. This ensures that the perturbation used is consistent with the approach from somd1, i.e. it uses the same modifications for bonded-terms involving dummy atoms as somd1.

Finally, it is also possible to run somd2 using an existing somd1 perturbation file. To do so, you will also need to create a stream file representating the λ = 0 state. For existing input generated by prepareFEP.py, this can be done as follows. (This assumes that the output has a prefix somd1.)

import BioSimSpace as BSS

# Load the lambda = 0 state from prepareFEP.py
system = BSS.IO.readMolecules(["somd1.prm7", "somd1.rst7"])

# Write a stream file.
BSS.Stream.save(system, "somd1")

(This will write a stream file called somd1.bss.)

This can then be run with somd2 using the following:

somd2 somd1.bss --pert-file somd1.pert --somd1-compatibility

(This only shows the limited options required. Others will take default values and can be set accordingly.)