The Alchemical Transfer Method for OpenMM (AToM-OpenMM) is an extensible Python package for estimating absolute and relative binding free energies of molecular complexes. It implements the Alchemical Transfer Method (ATM) with OpenMM and can run on GPU workstations or cluster nodes.
This fork adds a single-YAML small-molecule RBFE workflow on top of the original AToM-OpenMM implementation. The wrapper can prepare and run complete ligand-pair calculations, select setup force fields and ligand charges, define custom equilibration protocols with Amber masks, and use either asynchronous replica exchange or an experimental nonequilibrium switching (NEQTI) protocol.
This version of AToM-OpenMM has been tested with OpenMM 8.5 and 8.4; it uses ATMForce in the 8.4.0 or later versions of OpenMM.
This software is developed and maintained by the Emilio Gallicchio's lab with support from current and past grants from the National Science Foundation (ACI 1440665 and CHE 1750511) and the National Institutes of Health (R15 GM151708).
Maintainer/Author:
- Emilio Gallicchio egallicchio@brooklyn.cuny.edu
Contributors:
- Elian Tiudic
- Sylvester Sakyi
- Stefan Doerr
- Sheenam Khuttan
- Joe Z Wu
- Solmaz Azimi
- Baofeng Zhang
- Rajat Pal
The asynchronous replica exchange method was first implemented in the AsyncRE package for the IMPACT program.
Please cite us if you use this software in your research:
-
Alchemical Transfer Approach to Absolute Binding Free Energy Estimation
-
Asynchronous Replica Exchange Software for Grid and Heterogeneous Computing
It is recommended that the installation is performed in a personal Python environment (miniforge, miniconda, conda, or similar). AToM-OpenMM requires the openmm and other Python modules.
This version of AToM-OpenMM requires OpenMM 8.4.0 or later. This conda command installs the necessary requirements:
mamba create -n atm8.5.0 -c conda-forge 'openmm>=8.4' ambertools openmmforcefields configobj setproctitle r-base espaloma
mamba activate atm8.5.0
setproctitle above is optional but useful to track the names of the processes started by AToM-OpenMM. The ambertools, openmmforcefields, and espaloma packages are not actual dependencies; they are used to prepare the molecular systems. openmmforcefields, in particular, is used to assign force field parameters using OpenFF, GAFF, or espaloma. espaloma is a machine-learning system by the Chodera lab to assign force field parameters. The r-base dependency with the UWHAM R package (see below) is required for free energy estimation in legacy workflows and will be removed in later versions. See examples for examples and tutorials.
Finally, install AToM-OpenMM:
- From the latest release:
pip install atom-openmm
- From this fork in editable mode (recommended for development):
git clone https://github.com/JuroDobias/AToM-OpenMM.git
cd AToM-OpenMM
python -m pip install -e .
Verify that the YAML wrapper was installed into the active environment:
atom-rbfe --helpAnd this will install the UWHAM R package:
Rscript -e 'install.packages("UWHAM", repos = "http://cran.us.r-project.org")'
While we strive to develop and distribute high-quality and bug-free software, keep in mind that this is research software under heavy development. AToM-OpenMM is provided without any guarantees of correctness. Please report fork-specific issues here. We welcome contributions and pull requests.
Start from examples/RBFE/cdk2/workflow.yaml. It defines the receptor, ligand SDF directory, ligand pairs, alignment atom selection, force fields, and ATM schedule in one file:
cd examples/RBFE/cdk2
atom-rbfe workflow.yamlRelative paths are resolved from the workflow file. Results for each pair are written below workflow.workdir (the example uses complexes/). Use prepare_only: true to build the pair directories without running production.
Alignment atoms can be supplied explicitly with workflow.alignments, generated from the legacy reference_ligand plus reference_alignment_atoms, or selected from a SMARTS scaffold:
workflow:
alignment:
method: smarts
smarts: "[#6]-[#6]-[#6]"
smarts_atom_ids: [1, 2, 3]
alignments_out: alignments.yamlFor SMARTS alignment, smarts_atom_ids are 1-based positions inside the SMARTS match. If the SMARTS matches symmetrically, all match combinations are evaluated for each ligand pair and the one with the smallest direct coordinate RMSD is used. No fitting, rotation, or translation is performed; input ligands should already be aligned.
The default production method is the original asynchronous replica exchange implementation. To select experimental NEQTI switching:
workflow:
production_method: neqti
neqti:
initial_equilibration_steps: 25000
n_snapshots: 10
decorrelation_steps: 5000
switch_steps_per_segment: 1000
resume: true
bootstrap_samples: 0NEQTI reuses the async-RE ATM soft-core schedule as two bidirectional half paths that meet at one shared midpoint ensemble, A<->M and B<->M. It estimates both legs with BAR and combines them as DG(A->M) - DG(B->M).
By default, ATM parameter switching and protocol-work accumulation run inside a dedicated OpenMM CustomIntegrator; openmmtools is used as a design reference but is not a runtime dependency. Set workflow.neqti.switch_integrator: python to use the slower reference path or validate_switch_integrator: true for a one-shot comparison.
See the RBFE user guide for the complete YAML schema, force-field examples, custom equilibration, restart behavior, outputs, and swapped-coordinate diagnostics.
Every ligand-pair directory also contains an atomically updated result.yaml for integration with workflow managers and databases. It uses the same schema for asynchronous replica exchange and NEQTI, reports DDG in kcal/mol and kJ/mol, records input provenance and artifacts, and exposes prepared, running, partial, completed, or failed status.
AToM-OpenMM Theory Introduction
See examples for examples, workflows, and tutorials.
See example-notebooks for example Notebooks.
This software is licensed under the terms of the GNU Lesser General Public License. See LICENSE. The AToM logo © 2023 Solmaz Azimi.