molecular-simulations

CI/CD

A comprehensive Python toolkit for building, running, and analyzing molecular dynamics simulations using the AMBER force field ecosystem and OpenMM.

📖 Full Documentation

Features

🔨 System Building

Explicit solvent systems with OPC water model
Implicit solvent support for faster calculations
Small molecule parameterization via GAFF2

⚡ Simulation Engine

OpenMM integration (v8.0+) with GPU acceleration
Advanced simulations Constant-pH and Empirical Valence Bond
HPC deployment via Parsl for PBS schedulers
MM-PBSA calculations for binding free energy estimation in parallel
Flexible configuration for various cluster environments

📊 Analysis Tools

Automatic clustering with KMeans++ and dimensionality reduction (PCA)
Protein-protein interaction analysis using covariance matrix approach
Interaction energy fingerprinting (electrostatic + Lennard-Jones)
Linear interaction energy calculations (static and dynamic)
Interface scoring with ipTM, ipSAE, pDockQ, and pDockQ2
SASA calculations (absolute and relative) via MDAnalysis
Residue energy footprinting for binding site characterization

Installation

Note: molecular-simulations uses AmberTools (for system building with tleap), which is not distributed on PyPI. If you don't already have an AmberTools installation to point at, the easiest way to get one is via a conda-forge-based package manager (Anaconda/Miniconda, Mamba, or Pixi) alongside pip install molecular-simulations.

If you already have AmberTools installed elsewhere (e.g. a shared cluster module, an existing conda env, or a source build), you don't need a second copy — just set the AMBERHOME environment variable, or pass amberhome='/path/to/amber' directly to the relevant classes (ExplicitSolvent, MMPBSA, etc.), and skip straight to pip install molecular-simulations below.

Using conda / mamba

conda create -n molsim python=3.12
conda activate molsim
conda install -c dacase -c conda-forge ambertools-dac openmm
pip install molecular-simulations

dacase::ambertools-dac is the official channel maintained by the AmberTools developers and tracks the current AmberTools release; the community-maintained conda-forge::ambertools package also works if you prefer to stay on a single channel. mamba is a drop-in replacement for conda (mamba create ..., mamba install ...) and resolves environments much faster.

Using pixi

pixi init molsim
cd molsim
pixi workspace channel add dacase
pixi add python=3.12 ambertools-dac openmm
pixi add --pypi molecular-simulations

Installing the package alone from PyPI

If you already have AmberTools available (via AMBERHOME/amberhome=..., see above) or only need OpenMM-based simulation/analysis features without system building, you can install just the Python package:

pip install molecular-simulations

For small molecule support (requires RDKit and OpenBabel):

pip install "molecular-simulations[ligand]"

For development:

pip install "molecular-simulations[dev]"

Quick Start

Building a Solvated System

from molecular_simulations.build import ExplicitSolvent
from pathlib import Path

# Build an explicitly solvated system
pdb_file = Path('/path/to/protein.pdb')
output_dir = Path('/path/to/outputs')

builder = ExplicitSolvent(output_dir, pdb_file)
builder.build()

# Outputs: topology (.prmtop) and coordinates (.inpcrd)

Running a Simulation

from molecular_simulations.simulate import Simulator

# Initialize and run simulation
sim = Simulator(
    path=builder.out.parent, # Directory containing simulation inputs
)
sim.run()

Analyzing Trajectories

Interaction Energy Fingerprinting

from molecular_simulations.analysis import Fingerprinter

fp = Fingerprinter(
    topology='/path/to/system.prmtop',
    trajectory='/path/to/trajectory.dcd',
    target_selection='segid A',
    binder_selection='segid B'
)
fp.run()
fp.save()  # Saves to fingerprint.npz

Automatic Clustering

from molecular_simulations.analysis import AutoKMeans

clusterer = AutoKMeans(
    data_directory='/path/to/features/', # should be populated with .npy files
    max_clusters=10,
    reduction_algorithm='PCA',
    reduction_kws={'n_components': 2}
)
clusterer.run()
clusterer.save_labels()   # Saves cluster assignments
clusterer.save_centers()  # Saves cluster centroids

MM-PBSA implementation

from molecular_simulations.simulate.mmpbsa import MMPBSA

mmpbsa = MMPBSA(
    top='/path/to/file.prmtop',
    dcd='/path/to/traj.dcd',
    selections=[':1-100', ':101-200'], # cpptraj-style selections
    n_cpus=1,                          # CPU-based parallelism supported
    amberhome='/path/to/dir',          # should be above /bin/cpptraj
    parallel_mode='frame'              # frame or serial
)

Protein-Protein Interaction Analysis

from molecular_simulations.analysis import PPInteractions

ppi = PPInteractions(
    top='/path/to/topology.prmtop',
    traj='/path/to/trajectory.dcd',
    out='/path/to/outputs/',
    sel1='chainID A',
    sel2='chainID B'
)
ppi.run()  # Analyzes H-bonds, salt bridges, hydrophobic contacts

Interface Scoring (ipSAE/pDockQ)

from molecular_simulations.analysis import ipSAE

scorer = ipSAE(
    structure_file='/path/to/complex.pdb',
    pae_file='/path/to/pae.json',  # AlphaFold PAE matrix
    plddt_file='/path/to/plddt.json'
)
scores = scorer.run()
# Returns: ipTM, ipSAE, pDockQ, pDockQ2 scores

SASA Calculations

from molecular_simulations.analysis import SASA, RelativeSASA

# Absolute SASA
sasa = SASA(universe, selection='protein')
sasa.run()
results = sasa.measure_sasa()

# Relative SASA (normalized by max accessible area)
rsasa = RelativeSASA(universe, selection='protein')
rsasa.run()

Supported Force Fields

|==============AMBER==============|

Component	Force Field	Notes
Proteins	ff19SB	Fixed-charge, recommended
Proteins	ff15ipq	Polarizable
DNA	OL21	Latest AMBER DNA parameters
RNA	OL3	Standard RNA parameters
Small molecules	GAFF2	General AMBER Force Field 2
Water (explicit)	OPC	4-point model
Water (polarizable)	SPC/Eb	For ff15ipq systems

|=============CHARMM=============| See OpenMM documentation on providing parameter sets. CHARMM does not translate very well to the pre-build XML files for unusual lipids, small molecules, etc.

Requirements

Python ≥ 3.10
OpenMM ≥ 8.0
MDAnalysis ≥ 2.7
Parsl ≥ 2024.1.29
NumPy, SciPy, scikit-learn, Polars
AmberTools (not available on PyPI — install via conda/mamba/pixi, or point at an existing install via AMBERHOME; see Installation)
Optional: RDKit, OpenBabel (for ligand parameterization)

Known Issues

OpenMM versions 8.0-8.1 may exhibit slower integration times for larger systems due to a known bug
Advanced features are tested but not all edge cases have been encountered, please open an Issue if you find one

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

Citation

If you use this software in your research, please cite:

@software{molecular_simulations,
  author = {Sinclair, Matt},
  title = {molecular-simulations: A Python toolkit for MD simulation and analysis},
  url = {https://github.com/msinclair-py/molecular-simulations},
  year = {2025}
}

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

OpenMM for molecular dynamics engine
MDAnalysis for trajectory analysis
Parsl for parallel workflow execution
AMBER force field developers

Release files for molecular-simulations 0.5.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for molecular-simulations 0.5.2
File	Size	Uploaded
molecular_simulations-0.5.2.tar.gz	506.6 kB	Sep 25, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for molecular-simulations 0.5.2
File	Interpreter	ABI	Platform	Reset
molecular_simulations-0.5.2-py3-none-any.whl 141.8 kB Sep 25, 2026	Python 3	none	any	Details

Total release size: 648.4 kB

Release files / molecular_simulations-0.5.2.tar.gz

Download URL	molecular_simulations-0.5.2.tar.gz
Size	506.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`a2188d842e7388ba5d8e52a4f3a40076fef382436ac33b96f0e5b65de00632b5`
BLAKE2b-256 checksum How to use checksums	`7987d1b49619671ff43cff5a56895700c65485cbaa9f75a3e2b759c501d6cc32`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / molecular_simulations-0.5.2-py3-none-any.whl

Download URL	molecular_simulations-0.5.2-py3-none-any.whl
Size	141.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8bee403f009214f2aa3e3bf0d0f5c80ecbe42ec4b3c3727e00db63f812c3d082`
BLAKE2b-256 checksum How to use checksums	`93bf4d4a967ded256e01f6138b713f8b0dc01e6f29272208a3eddb5ad5b2ea15`
Upload date	Sep 25, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`