Feature GCMC

.github/workflows/main.yaml

@@ -3,11 +3,9 @@ name: Build and test
 on:
   workflow_dispatch:
   push:
-    branches:
-      - "**"
+    branches: [devel, main]
   pull_request:
-    branches:
-      - "main"
+    branches: [devel, main]
 
 jobs:
   pre_job:
@@ -36,6 +34,8 @@ jobs:
     defaults:
       run:
         shell: ${{ matrix.platform.shell }}
+    env:
+      ENVIRONMENT_FILE: ${{ matrix.platform.name == 'macos' && 'environment_macos.yaml' || 'environment.yaml' }}
     steps:
 #
       - name: Checkout the repository (commit)
@@ -53,7 +53,7 @@ jobs:
           auto-update-conda: true
           python-version: ${{ matrix.python-version }}
           activate-environment: somd2
-          environment-file: environment.yaml
+          environment-file: ${{ env.ENVIRONMENT_FILE }}
           miniforge-version: latest
           run-post: ${{ matrix.platform.name != 'windows' }}
 #

README.md

@@ -16,6 +16,9 @@ conda env create -f environment.yaml
 
 (We recommend using [Miniforge](https://github.com/conda-forge/miniforge).)
 
+> [!NOTE]
+> On macOS, you will need to use the `environment_macos.yaml` file instead.
+
 Now install `somd2` into the environment:
 
 ```
@@ -33,8 +36,10 @@ somd2 --help
 
 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](https://github.com/OpenBioSim/biosimspace). For example, following the tutorial
-[here](https://biosimspace.openbiosim.org/versions/2023.4.0/tutorials/hydration_freenrg.html). Once the system is created, it can be streamed to file using, e.g.:
+This can be created using [BioSimSpace](https://github.com/OpenBioSim/biosimspace).
+For example, following the tutorial
+[here](https://biosimspace.openbiosim.org/versions/2023.4.0/tutorials/hydration_freenrg.html).
+Once the system is created, it can be streamed to file using, e.g.:
 
 ```python
 import BioSimSpace as BSS
@@ -112,12 +117,31 @@ the value of `--rest2-scale`. By passing multiple values for `--rest2-scale`, th
 user can fully control the schedule. When doing so, the number of values must
 match the number of lambda windows.
 
+## GCMC
+
+SOMD2 also supports grand canonical Monte Carlo (GCMC) water sampling using
+the [loch](https://github.com/OpenBioSim/loch) package. This can be enabled
+using the `--gcmc` option. To define a GCMC region, use the `--gcmc-selection`
+option, which should be a `Sire` selection string that specifies the atoms
+defining the centre of geometry for the GCMC region. The radius of the GCMC
+sphere can be controlled using the `--gcmc-radius` option. To see all GCMC
+related options, run:
+
+```
+somd2 --help | grep -A2 '  --gcmc'
+```
+
+> [!NOTE]
+> GCMC is currently only supported when using the CUDA platform and isn't
+> available on macOS, where the `pycuda` package is not available.
+
 ## 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](https://github.com/OpenBioSim/biosimspace) as follows:
+[Parquet files](https://en.wikipedia.org/wiki/Apache_Parquet) for the energy
+trajectories of each λ window. These can be processed using
+[BioSimSpace](https://github.com/OpenBioSim/biosimspace) as follows:
 
 ```python
 import BioSimSpace as BSS
@@ -149,6 +173,15 @@ can be controlled via the `--null-energy` option. The number of neighbours shoul
 be chosen as a trade off between accuracy and computational cost. A value of around
 20% of the number of replicas has been found to be a good starting point.
 
+## Ghost atom modifications
+
+We support modification of ghost atom bonded terms to avoid spurious coupling
+to the physical system using the approach described in
+[this](https://pubs.acs.org/doi/10.1021/acs.jctc.0c01328) paper.
+These are enabled by default, but can be disabled using the ``--no-ghost-modifications``
+option. Modifications are implemented using the [ghostly](https://gitbub.com/OpenBioSim/ghostly)
+package.
+
 ## Note for SOMD1 users
 
 For existing users of `somd1`, it's possible to generate input for `somd2` by passing
@@ -186,5 +219,42 @@ 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.)
 
 If you want to load an existing system from a perturbation file and use the
-new `somd2` ghost atom bonded-term modifications, then simply omit the
-`--somd1-compatibility` option.
+new `somd2` [ghost atom bonded-term modifications](https://github.com/OpenBioSim/ghostly),
+then simply omit the `--somd1-compatibility` option.
+
+## GPU oversubscription
+
+If you have an NVIDIA GPU that supports the multi-process service (MPS), you can
+oversubscibe the GPU to run multiple OpenMM contexts on the same GPU at once,
+increasing the throughput of your simulation. To do this, you will need to first
+enable MPS by running the following command:
+
+```
+nvidia-cuda-mps-control -d
+```
+
+The number of contexts that can be run in parallel is then controlled by the
+`--oversubscription-factor` option, which defaults to 1.
+
+More details on MPS, including tuning options, can be found in the following
+[techical blog](https://developer.nvidia.com/blog/maximizing-openmm-molecular-dynamics-throughput-with-nvidia-multi-process-service/).
+
+## Python API
+
+``SOMD2`` can also be used as a Python API, allowing it to be embedded
+within other Python scripts. When doing so, it is important to to wrap
+code within a ``if __name__ == "__main__":`` block since multiprocessing
+is used with the ``spawn`` start method.
+
+**## Known issues**
+
+If using the regular `Runner` class via the Python API, then you will need to
+guard calls to its `run()` method within a `if __name__ == "__main__":` block
+since it uses multiprocessing with the `spawn` start method.
+
+During a checkpoint cycle trajectory frames are stored in memory before being
+paged to disk. When running replica exchange simulations with a large number
+of replicas this can lead to exceeding the temporary file storage limit on
+some systems, causing the simulation to hang. This can be resolved by either
+reducing the frequency at which frames are stored, or checkpointing more.
+(Frames are written to disk and cleared from memory at each checkpoint.)

environment.yaml

@@ -7,5 +7,10 @@ channels:
 dependencies:
   - biosimspace
   - git
+  - filelock
   - loguru
   - numba
+  - pycuda
+  - pip:
+      - git+https://github.com/openbiosim/ghostly
+      - git+https://github.com/openbiosim/loch

environment_macos.yaml

@@ -0,0 +1,14 @@
+name: somd2
+
+channels:
+  - conda-forge
+  - openbiosim/label/dev
+
+dependencies:
+  - biosimspace
+  - git
+  - filelock
+  - loguru
+  - numba
+  - pip:
+      - git+https://github.com/openbiosim/ghostly

pyproject.toml

@@ -20,7 +20,7 @@ dynamic = ["version"]
 license-files = ["LICENSE"]
 
 [project.scripts]
-somd2 = "somd2.app:cli"
+somd2 = "somd2.app:somd2"
 
 [project.urls]
 repository = "https://github.com/OpenBioSim/somd2"