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

Install from PyPI:

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
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.1

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.1
File	Size	Uploaded
molecular_simulations-0.5.1.tar.gz	504.3 kB	Jul 9, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for molecular-simulations 0.5.1
File	Interpreter	ABI	Platform	Reset
molecular_simulations-0.5.1-py3-none-any.whl 141.0 kB Jul 9, 2026	Python 3	none	any	Details

Total release size: 645.4 kB

Release files / molecular_simulations-0.5.1.tar.gz

Download URL	molecular_simulations-0.5.1.tar.gz
Size	504.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`87e6c2a83767c13ef49e6193e2b98231c1e2ea0ffd6b880ee1f6edb402376a85`
BLAKE2b-256 checksum How to use checksums	`b92bbbd9e342c3c54b22fc0ef7e0c42a27787eeb942744fa34fb719b7fc31c2e`
Upload date	Jul 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`

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

Download URL	molecular_simulations-0.5.1-py3-none-any.whl
Size	141.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`e86c30cf541ee6b033af41762317bada13e8b343eddd990f1940b9adb3b7b7de`
BLAKE2b-256 checksum How to use checksums	`8af3572937478178b051b395e9914dbfd86a382d409ad264457ba2ee7dcdd37c`
Upload date	Jul 9, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.13.12`