Merge pull request #4 from OpenBioSim/feature_logging

Initial SOMD2 prototype
OpenBioSim · Nov 2, 2023 · 42129f2 · 42129f2
2 parents dd65e1a + 3c730d1
commit 42129f2
Show file tree

Hide file tree

Showing 22 changed files with 4,020 additions and 8 deletions.
diff --git a/.github/workflows/main.yaml b/.github/workflows/main.yaml
@@ -0,0 +1,58 @@
+name: Build and test
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - "**"
+  pull_request:
+    branches:
+      - "main"
+
+jobs:
+  build:
+    name: build (${{ matrix.python-version }}, ${{ matrix.platform.name }})
+    runs-on: ${{ matrix.platform.os }}
+    strategy:
+      max-parallel: 9
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+        platform:
+          - { name: "windows", os: "windows-latest", shell: "pwsh" }
+          - { name: "linux", os: "ubuntu-latest", shell: "bash -l {0}" }
+          - { name: "macos", os: "macos-latest", shell: "bash -l {0}" }
+    defaults:
+      run:
+        shell: ${{ matrix.platform.shell }}
+    steps:
+#
+      - name: Checkout the repository (commit)
+        uses: actions/checkout@v4
+        if: github.event_name != 'pull_request'
+#
+      - name: Checkout the repository (PR)
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+        if: github.event_name == 'pull_request'
+#
+      - uses: conda-incubator/setup-miniconda@v2
+        with:
+          auto-update-conda: true
+          python-version: ${{ matrix.python-version }}
+          activate-environment: somd2
+          environment-file: environment.yaml
+          miniforge-version: latest
+          miniforge-variant: Mambaforge
+          use-mamba: true
+          run-post: ${{ matrix.platform.name != 'windows' }}
+#
+      - name: Install pytest
+        run: mamba install pytest
+#
+      - name: Install the package
+        run: pip install .
+#
+      - name: Run the tests
+        run: python -m pytest -svvv --color=yes tests
diff --git a/README.md b/README.md
@@ -1,2 +1,73 @@
-# somd2
-OpenBioSim - SOMD2 molecular dynamics for free energy calculations
+# SOMD2
+
+[![GitHub Actions](https://github.com/openbiosim/somd2/actions/workflows/main.yaml/badge.svg)](https://github.com/openbiosim/somd2/actions/workflows/main.yaml)
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+
+Open-source GPU accelerated molecular dynamics engine for alchemical free-energy
+simulations. Built on top of [Sire](https://github.com/OpenBioSim/sire) and [OpenMM](https://github.com/openmm/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:
+
+```
+mamba create -f environment.yaml
+```
+
+(We recommend using [Mambaforge](https://github.com/conda-forge/miniforge#mambaforge).)
+
+Now install `somd2` into the environment:
+
+```
+mamba 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](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
+
+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 with override those set via the config file.
+
+An example perturbable system for a methane to ethanol perturbation in solvent
+can be found [here](https://sire.openbiosim.org/m/merged_molecule.s3.bz2).
+This is a `bzip2` compressed file that will need to be extracted before use.
+
+## 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:
+
+```python
+import BioSimSpace as BSS
+
+pmf, overlap = BSS.FreeEnergy.Relative.analyse("output")
+```
+
+(Here we assume that the output directory is called `output`.)
diff --git a/demo/bubble_tyk2.ipynb b/demo/bubble_tyk2.ipynb
@@ -0,0 +1,179 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "d086ec3c-3d0c-45b1-949f-0224e68043fe",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sire as sr"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c2e8df62-7bcd-4028-a97e-51ed67530ce0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mols = sr.stream.load(\"bound_31_42.bss\")\n",
+    "mols.add_shared_property(\"space\", mols.property(\"space\"))\n",
+    "timestep = \"1fs\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "169dbf60-fb80-469f-9859-d36ce6187ab4",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# link reference properties to main properties\n",
+    "for mol in mols.molecules(\"molecule property is_perturbable\"):\n",
+    "    mols.update(mol.perturbation().link_to_reference().commit())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "ccde94f0",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ligand = mols[\"molecule with property is_perturbable\"]\n",
+    "ligand"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "f8dbad46",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "ligand_center = ligand.evaluate().center()\n",
+    "radius = \"15 A\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "0e3a9d11",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "restraints = sr.restraints.positional(\n",
+    "    mols,\n",
+    "    f\"residues within {radius} of {ligand_center}\",\n",
+    "    position=ligand_center,\n",
+    "    r0=radius,\n",
+    "    k=\"10 kcal mol-1 A-2\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "9f711a43",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "restraints"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "72927a60",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mols = (\n",
+    "    mols.minimisation(\n",
+    "        fixed=f\"not (residues within {radius} of {ligand_center})\",\n",
+    "        restraints=restraints,\n",
+    "        map={\"ignore_perturbations\": True},\n",
+    "    )\n",
+    "    .run()\n",
+    "    .commit()\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "648ece01",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "d = mols.dynamics(\n",
+    "    timestep=timestep,\n",
+    "    temperature=\"25oC\",\n",
+    "    restraints=restraints,\n",
+    "    fixed=f\"not (residues within {radius} of {ligand_center})\",\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "460f5a9c",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "d.run(\"200ps\", save_frequency=\"1ps\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "8c297b9d",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mols = d.commit()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "a3af4a74",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sr.save(mols.trajectory()[0], \"tyk2_bubble\", format=[\"pdb\"])"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "c39e1ee9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sr.save(mols.trajectory(), \"tyk2_bubble\", format=[\"DCD\"])"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}