Merge pull request #68 from michellab/feature-decouple-somd-3

Feature decouple somd 3 to main branch
Conflicts Resolved
- Resolved all merge conflicts between feature-decouple-somd-3 and main branch
- Integrated latest changes from main branch
- Local and CI tests pass on all supported Python versions

Ready for v0.4.0 release.

Author: Roy-Haolin-Du

.github/workflows/CI.yaml

@@ -1,5 +1,9 @@
 name: CI
 
+concurrency:
+  group: ${{ github.ref }}
+  cancel-in-progress: true
+
 on:
   # GitHub has started calling new repo's first branch "main" https://github.com/github/renaming
   # The cookiecutter uses the "--initial-branch" flag when it runs git-init
@@ -16,70 +20,37 @@ on:
     - cron: "0 0 * * 0"
 
 jobs:
-  # Check with ruff and black
-  lint_and_format:
-    name: Check for style and formatting violations with Ruff
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out code
-        uses: actions/checkout@v2
-
-      - name: Set up Python
-        uses: actions/setup-python@v2
-        with:
-          python-version: '3.10'
-
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install ruff
-
-      - name: Check style with Ruff
-        run: ruff check .
-
-      - name: Check formatting with Ruff
-        run: ruff format --check .
-
   test:
     name: Test on ${{ matrix.os }}, Python ${{ matrix.python-version }}
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         os: [ubuntu-latest]
         python-version: ['3.10', '3.11', '3.12']
-
+    container: condaforge/mambaforge:latest
+  
     steps:
-      - uses: actions/checkout@v3
+      - name: Check out code
+        uses: actions/[email protected]
 
-      - name: Additional info about the build
-        shell: bash
+      - name: Install system dependencies
         run: |
-          uname -a
-          df -h
-          ulimit -a
-
-      - uses: mamba-org/setup-micromamba@v1
-        with:
-          environment-file: devtools/conda-envs/test_env.yaml
-          environment-name: test
-          create-args: >- # beware the >- instead of |, we don't split on newlines but on spaces
-            python=${{ matrix.python-version }}
+          apt update && apt install -y git make
 
-      - name: Install package
-        # conda setup requires this special shell
-        shell: bash -l {0}
+      - name: Setup environment for Python ${{ matrix.python-version }}
         run: |
-          python -m pip install . --no-deps
-          micromamba list
+          make env-ci PYTHON_VERSION=${{ matrix.python-version }}
 
-      - name: Run tests
-        # conda setup requires this special shell
-        shell: bash -l {0}
+      - name: Run linting and tests
         run: |
-          pytest -v --cov=a3fe --cov-report=xml --color=yes a3fe/tests/
+          make lint
+          make test
+          make docs
+          make clean
 
       - name: Upload coverage reports to Codecov
         uses: codecov/[email protected]
         with:
+          file: ./coverage.xml
           token: ${{ secrets.CODECOV_TOKEN }}
           slug: michellab/a3fe

.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+# .pre-commit-config.yaml
+repos:
+# Basic file cleanup hooks
+-   repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v3.2.0
+    hooks:
+    -   id: trailing-whitespace  # delete trailing whitespace
+    -   id: end-of-file-fixer    # ensure file ends with a blank line
+    -   id: check-yaml           # check yaml syntax
+    -   id: check-added-large-files  # prevent large files from being added
+    -   id: check-merge-conflict    # check for unresolved merge conflicts
+
+# Use local commands to format and check code
+-   repo: local
+    hooks:
+    # code format hook
+    -   id: ruff
+        name: Autoformat python code
+        language: system
+        entry: bash
+        args: [-c, "make format"]
+        
+    # code check hook
+    -   id: ruff
+        name: Lint python code
+        language: system
+        entry: bash
+        args: [-c, "make lint"]

.readthedocs.yaml

@@ -13,4 +13,4 @@ sphinx:
    configuration: docs/conf.py
 
 conda:
-  environment: devtools/conda-envs/test_env.yaml
+  environment: devtools/conda-envs/ci_env.yaml

CODE_OF_CONDUCT.md

@@ -57,7 +57,7 @@ project may be further defined and clarified by project maintainers.
 ## Enforcement
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
-reported by contacting the project team at '[email protected]'. The project team will
+reported by contacting the project team at '[email protected] or [email protected]'. The project team will
 review and investigate all complaints, and will respond in a way that it deems
 appropriate to the circumstances. The project team is obligated to maintain
 confidentiality with regard to the reporter of an incident. Further details of

Makefile

@@ -0,0 +1,66 @@
+PACKAGE_NAME := a3fe
+PACKAGE_DIR  := a3fe
+
+# Only need slurm, which is linux only
+CONDA_ENV_RUN = conda run --no-capture-output --name $(PACKAGE_NAME)
+
+TEST_ARGS := -v --cov=$(PACKAGE_DIR) --cov-report=term --cov-report=xml --junitxml=unit.xml --color=yes
+
+.PHONY: env env-dev env-ci lint format test test-integration docs-build docs clean
+
+# Regular users:
+env:
+	mamba create -y --name $(PACKAGE_NAME) $(if $(PYTHON_VERSION),python=$(PYTHON_VERSION))
+	mamba env update --name $(PACKAGE_NAME) --file devtools/conda-envs/base_env.yaml
+	$(CONDA_ENV_RUN) pip install --no-deps -e .
+
+# Developers with local GROMACS
+env-dev:
+	mamba create -y --name $(PACKAGE_NAME) $(if $(PYTHON_VERSION),python=$(PYTHON_VERSION))
+	mamba env update --name $(PACKAGE_NAME) --file devtools/conda-envs/dev_env.yaml
+	$(CONDA_ENV_RUN) pip install --no-deps -e .
+	$(CONDA_ENV_RUN) pre-commit install || true
+
+# CI and developers without GROMACS
+env-ci:
+	mamba create -y --name $(PACKAGE_NAME) $(if $(PYTHON_VERSION),python=$(PYTHON_VERSION))
+	mamba env update --name $(PACKAGE_NAME) --file devtools/conda-envs/ci_env.yaml
+	$(CONDA_ENV_RUN) pip install --no-deps -e .
+	$(CONDA_ENV_RUN) pre-commit install || true
+	
+# code check
+lint:
+	$(CONDA_ENV_RUN) ruff check $(PACKAGE_DIR)
+
+# code format
+format:
+	$(CONDA_ENV_RUN) ruff format $(PACKAGE_DIR)
+	$(CONDA_ENV_RUN) ruff check --fix --select I $(PACKAGE_DIR)
+
+# run tests
+test:
+	$(CONDA_ENV_RUN) pytest $(TEST_ARGS) $(PACKAGE_DIR)/tests/
+
+# run integration tests (requires SLURM environment)
+test-integration:
+	$(CONDA_ENV_RUN) RUN_SLURM_TESTS=1 pytest $(TEST_ARGS) $(PACKAGE_DIR)/tests/ --run-integration -v
+
+# build docs
+docs-build:
+	cd docs && $(CONDA_ENV_RUN) make html
+
+docs:
+	cd docs && $(CONDA_ENV_RUN) make html
+	@echo "Documentation built in docs/_build/html/"
+
+# clean build files
+clean:
+	rm -rf docs/_build/
+	rm -rf build/
+	rm -rf dist/
+	rm -rf *.egg-info
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+# deploy docs
+# consider supporting this in the future

README.md

@@ -6,7 +6,7 @@ a3fe
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
 [![Documentation Status](https://readthedocs.org/projects/a3fe/badge/?version=latest)](https://a3fe.readthedocs.io/en/latest/?badge=latest)
 [![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
-      
+
 <img src="./a3fe_logo.png" alt="Alt text" style="width: 50%; height: 50%;">
 
 **A**utomated **A**daptive **A**bsolute alchemical **F**ree **E**nergy calculator. A package for running adaptive alchemical absolute binding free energy calculations with SOMD (distributed within [sire](https://sire.openbiosim.org/)) using adaptive protocols based on an ensemble of simulations. This requires the SLURM scheduling system. Please see the [**documentation**](https://a3fe.readthedocs.io/en/latest/?badge=latest).
@@ -19,26 +19,34 @@ For details of the algorithms and testing, please see the assocated paper:
 
 a3fe depends on SLURM for scheduling jobs, and on GROMACS for running initial equilibration simulations. Please ensure that your have sourced your GMXRC or loaded your GROMACS module before proceeding with the installation. While we recommend installing with [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html), you can substitute `mamba` with `conda` in the following commands.
 
-Now, download and install a3fe:
+Now, download and install a3fe. Choose the appropriate environment for your use case:
+
+**Regular users:**
 ```bash
 git clone https://github.com/michellab/a3fe.git
 cd a3fe
-mamba env create -f environment.yaml
+make env
 mamba activate a3fe
-python -m pip install --no-deps .
+```
+
+**Developers with local GROMACS:**
+```bash
+make env-dev
 ```
 
 ### Quick Start
 
-- Activate your a3fe conda environment 
+- Activate your a3fe conda environment
 - Create a base directory for the calculation and create an directory called `input` within this
 - Move your input files into the the input directory. For example, if you have parameterised AMBER-format input files, name these bound_param.rst7, bound_param.prm7, free_param.rst7, and free_param.prm7. For more details see the documentation. Alternatively, copy the example input files from a3fe/a3fe/data/example_run_dir to your input directory.
-- Copy run somd.sh and template_config.sh from a3fe/a3fe/data/example_run_dir to your `input` directory, making sure to the SLURM options in run_somd.sh so that the jobs will run on your cluster
 - In the calculation base directory, run the following python code, either through ipython or as a python script (you will likely want to run the script with `nohup`or use ipython through tmux to ensure that the calculation is not killed when you lose connection)
 
 ```python
-import a3fe as a3 
-calc = a3.Calculation(ensemble_size=5)
+import a3fe as a3
+calc = a3.Calculation(
+    ensemble_size=5, # Use 5 (independently equilibrated) replicate runs
+    slurm_config=a3.SlurmConfig(partition="<desired partition>"),  # Set your desired partition!
+)
 calc.setup()
 calc.get_optimal_lam_vals()
 calc.run(adaptive=False, runtime = 5) # Run non-adaptively for 5 ns per replicate
@@ -52,10 +60,10 @@ calc.save()
 
 ### Copyright
 
-Copyright (c) 2023, Finlay Clark
+Copyright (c) 2025, Finlay Clark and Roy Haolin Du
 
 
 #### Acknowledgements
- 
-Project based on the 
+
+Project based on the
 [Computational Molecular Science Python Cookiecutter](https://github.com/molssi/cookiecutter-cms) version 1.1.

a3fe/__init__.py

@@ -16,20 +16,25 @@
 from .run import (
     CalcSet,
     Calculation,
-    JobStatus,
     LamWindow,
     Leg,
-    LegType,
-    PreparationStage,
     Simulation,
     Stage,
+)
+
+from .configuration import (
+    SlurmConfig,
+    _EngineConfig,
+    SomdConfig,
+    EngineType,
+    JobStatus,
+    LegType,
+    PreparationStage,
     StageType,
-    SystemPreparationConfig,
     enums,
+    SomdSystemPreparationConfig,
 )
 
-_sys.modules["EnsEquil"] = _sys.modules["a3fe"]
-
 # A3FE can open many files due to the use of multiprocessing and
 # threading with MBAR. This can cause a "Too many open files" error.
 # The following code increases the number of open files allowed to the

a3fe/_version.py

@@ -1 +1 @@
-__version__ = "0.3.6"
+__version__ = "0.4.0"

a3fe/analyse/detect_equil.py

@@ -58,7 +58,10 @@ def check_equil_block_gradient(
     gradient_threshold = lam_win.gradient_threshold
 
     # Conversion between time and gradient indices.
-    time_to_ind = 1 / (lam_win.sims[0].timestep * lam_win.sims[0].nrg_freq)
+    time_to_ind = 1 / (
+        lam_win.sims[0].engine_config.timestep
+        * lam_win.sims[0].engine_config.energy_frequency
+    )
     idx_block_size = int(lam_win.block_size * time_to_ind)
 
     # Read dh/dl data from all simulations and calculate the gradient of the
@@ -183,7 +186,10 @@ def check_equil_chodera(
     run_nos: _List[int] = lam_win._get_valid_run_nos(run_nos)
 
     # Conversion between time and gradient indices.
-    time_to_ind = 1 / (lam_win.sims[0].timestep * lam_win.sims[0].nrg_freq)
+    time_to_ind = 1 / (
+        lam_win.sims[0].engine_config.timestep
+        * lam_win.sims[0].engine_config.energy_frequency
+    )
 
     # Read dh/dl data from all simulations
     dh_dls = []
@@ -323,7 +329,7 @@ def check_equil_multiwindow(
             equil_time = (
                 _np.sum(
                     [
-                        lam_win.get_total_simtime(run_nos=run_nos)
+                        lam_win.get_tot_simtime(run_nos=run_nos)
                         for lam_win in lambda_windows
                     ]
                 )