API Overview¶

molecular-simulations is organized into three main subpackages corresponding to the MD workflow: building systems, running simulations, and analyzing results.

Package Structure¶

molecular_simulations/
├── build/          # System preparation
│   ├── build_amber     # AMBER system building
│   ├── build_interface # Interface utilities
│   └── build_ligand    # Small molecule parameterization
├── simulate/       # Simulation execution
│   ├── omm_simulator   # OpenMM simulation runner
│   ├── mmpbsa          # MM-PBSA calculations
│   └── parsl_settings  # HPC configuration
└── analysis/       # Trajectory analysis
    ├── autocluster         # Automatic clustering
    ├── cov_ppi             # Protein-protein interactions
    ├── fingerprinter       # Interaction fingerprinting
    ├── interaction_energy  # Energy calculations
    ├── ipSAE               # Interface scoring
    ├── sasa                # Solvent accessible surface area
    └── utils               # Shared utilities

Building Systems (`molecular_simulations.build`)¶

Classes for preparing molecular systems with AMBER force fields.

`molecular_simulations.build.ExplicitSolvent`	Build an explicit solvent system using AmberTools.
`molecular_simulations.build.ImplicitSolvent`	Build an implicit solvent system using AmberTools.
`molecular_simulations.build.LigandBuilder`	Parameterize a ligand molecule with GAFF2 force field.

ExplicitSolvent: Build explicitly solvated systems with OPC water and counterions. Supports ff19SB (proteins), OL21 (DNA), and OL3 (RNA) force fields.
ImplicitSolvent: Build systems for implicit solvent simulations using GB models.
LigandBuilder: Parameterize small molecules with GAFF2. Requires RDKit and OpenBabel.

Running Simulations (`molecular_simulations.simulate`)¶

Classes for executing MD simulations and related calculations.

`molecular_simulations.simulate.Simulator`	Class for performing OpenMM simulations on AMBER FF inputs.
`molecular_simulations.simulate.mmpbsa.MMPBSA`	Perform MM-P(G)BSA calculations with parallelization support.

Simulator: Run OpenMM simulations with automatic equilibration (NVT → NPT) and production dynamics. Supports GPU acceleration and hydrogen mass repartitioning.
MMPBSA: Calculate MM-PBSA binding free energies with frame-level parallelization.
LocalSettings: Parsl configuration for local workstations and small clusters.
PolarisSettings: Parsl configuration for ALCF Polaris supercomputer.

Analyzing Trajectories (`molecular_simulations.analysis`)¶

Classes for analyzing MD trajectories and structures.

`molecular_simulations.analysis.AutoKMeans`	Automatic clustering using KMeans++ with dimensionality reduction.
`molecular_simulations.analysis.Fingerprinter`	Calculate interaction energy fingerprints between target and binder.
`molecular_simulations.analysis.ipSAE`	Compute interaction prediction Score from Aligned Errors.
`molecular_simulations.analysis.SASA`	Compute solvent-accessible surface area using Shrake-Rupley algorithm.
`molecular_simulations.analysis.RelativeSASA`	Compute relative SASA for an AtomGroup.

AutoKMeans: Automatic KMeans clustering with elbow method for optimal k. Supports PCA and other dimensionality reduction methods.
Fingerprinter: Calculate per-residue interaction energy fingerprints (electrostatic + LJ).
PPInteractions: Analyze protein-protein interactions using covariance-based contact detection. Identifies hydrogen bonds, salt bridges, and hydrophobic contacts.
ipSAE: Score protein interfaces using AlphaFold-derived metrics: ipTM, ipSAE, pDockQ, and pDockQ2.
SASA: Calculate absolute solvent accessible surface area per residue.
RelativeSASA: Calculate relative SASA normalized by maximum accessible area.

Common Patterns¶

Most analysis classes follow a consistent interface:

# Initialize with input files
analyzer = AnalysisClass(topology, trajectory, **options)

# Run the analysis
analyzer.run()

# Save results
analyzer.save()  # or save_labels(), save_centers(), etc.

Selection Language¶

Classes that accept selections use MDAnalysis selection syntax:

# Chain selection
sel = "chainID A"

# Segment selection
sel = "segid PROA"

# Residue range
sel = "resid 1-100"

# Combined selections
sel = "chainID A and name CA"

See the MDAnalysis selection documentation for the full syntax.

Full API Reference¶

For complete documentation of all classes and methods, see molecular_simulations.