molecular_simulations.simulate.mmpbsa module¶

class molecular_simulations.simulate.mmpbsa.MMPBSASettings(top, dcd, selections, first_frame=0, last_frame=-1, stride=1, n_cpus=1, out='mmpbsa', solvent_probe=1.4, offset=0, gb_surften=0.0072, gb_surfoff=0.0)[source]¶

Bases: object

Settings dataclass for MMPBSA calculations.

top¶: Path to topology file.

dcd¶: Path to trajectory file.

selections¶: List of residue selections for receptor and ligand.

first_frame¶: First frame to analyze.

last_frame¶: Last frame to analyze (-1 for all).

stride¶: Frame stride.

n_cpus¶: Number of parallel processes.

out¶: Output prefix/path.

solvent_probe¶: Probe radius for SASA.

offset¶: SASA offset parameter.

gb_surften¶: GB surface tension parameter.

gb_surfoff¶: GB surface offset parameter.

top: Path | str¶

dcd: Path | str¶

selections: list[str] | None¶

first_frame: int = 0¶

last_frame: int = -1¶

stride: int = 1¶

n_cpus: int = 1¶

out: str = 'mmpbsa'¶

solvent_probe: float = 1.4¶

offset: int = 0¶

gb_surften: float = 0.0072¶

gb_surfoff: float = 0.0¶

__init__(top, dcd, selections, first_frame=0, last_frame=-1, stride=1, n_cpus=1, out='mmpbsa', solvent_probe=1.4, offset=0, gb_surften=0.0072, gb_surfoff=0.0)¶

class molecular_simulations.simulate.mmpbsa.MMPBSA(top, dcd, selections, first_frame=0, last_frame=-1, stride=1, n_cpus=1, out='mmpbsa', solvent_probe=1.4, offset=0, gb_surften=0.0072, gb_surfoff=0.0, amberhome=None, parallel_mode='frame', **kwargs)[source]¶

Bases: MMPBSASettings

Perform MM-P(G)BSA calculations with parallelization support.

A reconstructed implementation of AMBER’s MM-P(G)BSA workflow with improved documentation and parallelization options. Supports both Generalized Born (GB) and Poisson-Boltzmann (PB) solvation methods.

path¶: Working directory for calculations.

fh¶: FileHandler instance for file management.

analyzer¶: OutputAnalyzer instance for parsing results.

free_energy¶: Final binding free energy after run().

Parameters:

top (Path | str) – Path to solvated system topology (prmtop).
dcd (Path | str) – Path to trajectory file (DCD or MDCRD).
selections (list[str]) – List of two residue ID selections for receptor and ligand, formatted for cpptraj (e.g., ‘:1-10’).
first_frame (int) – First frame to analyze. Defaults to 0.
last_frame (int) – Last frame (-1 for all). Defaults to -1.
stride (int) – Frame stride. Defaults to 1.
n_cpus (int) – Number of parallel processes. Defaults to 1.
out (str) – Output prefix or path. Defaults to ‘mmpbsa’.
solvent_probe (float) – Probe radius for SASA in Angstroms. Defaults to 1.4.
offset (int) – SASA offset. Defaults to 0.
gb_surften (float) – GB surface tension. Defaults to 0.0072.
gb_surfoff (float) – GB surface offset. Defaults to 0.0.
amberhome (str | None) – Path to AMBERHOME. If None, uses $AMBERHOME env var.
parallel_mode (Literal['frame', 'serial']) – ‘frame’ for frame-level parallelization (recommended), ‘serial’ for sequential processing.
**kwargs – Additional keyword arguments stored as attributes.

Example

>>> mmpbsa = MMPBSA(
...     "system.prmtop", "traj.dcd", [":1-100", ":101-150"], n_cpus=4
... )
>>> mmpbsa.run()
>>> print(mmpbsa.free_energy)

Initialize the MMPBSA calculator.

Parameters:

top (Path | str) – Path to topology file.
dcd (Path | str) – Path to trajectory file.
selections (list[str]) – Receptor and ligand selections.
first_frame (int) – Starting frame.
last_frame (int) – Ending frame.
stride (int) – Frame stride.
n_cpus (int) – Number of CPUs.
out (str) – Output path/prefix.
solvent_probe (float) – SASA probe radius.
offset (int) – SASA offset.
gb_surften (float) – GB surface tension.
gb_surfoff (float) – GB surface offset.
amberhome (str | None) – AMBER installation path.
parallel_mode (Literal['frame', 'serial']) – Parallelization strategy.
**kwargs – Additional attributes.

__init__(top, dcd, selections, first_frame=0, last_frame=-1, stride=1, n_cpus=1, out='mmpbsa', solvent_probe=1.4, offset=0, gb_surften=0.0072, gb_surfoff=0.0, amberhome=None, parallel_mode='frame', **kwargs)[source]¶

Initialize the MMPBSA calculator.

Parameters:

top (Path | str) – Path to topology file.
dcd (Path | str) – Path to trajectory file.
selections (list[str]) – Receptor and ligand selections.
first_frame (int) – Starting frame.
last_frame (int) – Ending frame.
stride (int) – Frame stride.
n_cpus (int) – Number of CPUs.
out (str) – Output path/prefix.
solvent_probe (float) – SASA probe radius.
offset (int) – SASA offset.
gb_surften (float) – GB surface tension.
gb_surfoff (float) – GB surface offset.
amberhome (str | None) – AMBER installation path.
parallel_mode (Literal['frame', 'serial']) – Parallelization strategy.
**kwargs – Additional attributes.

run()[source]¶

Execute the complete MM-PBSA workflow.

Runs file preparation, energy calculations, and result analysis using the configured parallelization mode.

Return type:: None

calculate_sasa(pre, prm, trj)[source]¶

Calculate SASA using cpptraj’s molsurf command.

Parameters:

pre (Path | str) – Prefix for output SASA file.
prm (Path | str) – Path to prmtop file.
trj (Path | str) – Path to CRD trajectory file.

Return type:

None

calculate_energy(pre, prm, trj, pdb, mdin, suf)[source]¶

Run mmpbsa_py_energy to compute system energy.

Parameters:

pre (Path | str) – Prefix for output file.
prm (Path | str) – Path to prmtop file.
trj (Path | str) – Path to CRD trajectory file.
pdb (Path | str) – Path to PDB file.
mdin (Path | str) – Path to configuration file.
suf (str) – Suffix for output file (‘gb’ or ‘pb’).

Return type:

None

write_mdins()[source]¶

Write configuration files for mmpbsa_py_energy.

Return type:: tuple[Path, Path]
Returns:: Tuple of (gb_mdin_path, pb_mdin_path).

get_selections()[source]¶

If AMBER-style selections not provided, we will naively infer them to be all chains up to the last, against the last chain. This involves identifying all OXT termini atoms to demarcate separation of chains.

Return type:: list[str]

static format_for_cpptraj(resids)[source]¶

Formats a list of resids into AMBER-style selections. The general format is a colon followed by stretches of continous amino acids represented by a dash (e.g. :1-10; :1-10,25-43)

Return type:: str

class molecular_simulations.simulate.mmpbsa.OutputAnalyzer(path, surface_tension=0.0072, sasa_offset=0.0, _tolerance=0.005, log=True)[source]¶

Bases: object

Analyze and summarize MM-PBSA output files.

Parses energy output files and computes binding free energies for both GB and PB solvation methods.

path¶: Working directory path.

surften¶: Surface tension parameter.

offset¶: SASA offset parameter.

free_energy¶: Final [mean, std] after parse_outputs().

gb¶: Polars DataFrame of GB results.

pb¶: Polars DataFrame of PB results.

Parameters:

path (Path | str) – Path to output directory.
surface_tension (float) – GB surface tension. Defaults to 0.0072.
sasa_offset (float) – SASA offset. Defaults to 0.0.
_tolerance (float) – Tolerance for sanity checks. Defaults to 0.005.
log (bool) – Whether to log results. Defaults to True.

Initialize the OutputAnalyzer.

Parameters:

path (Path | str) – Output directory path.
surface_tension (float) – GB surface tension.
sasa_offset (float) – SASA offset.
_tolerance (float) – Sanity check tolerance.
log (bool) – Whether to log results.

__init__(path, surface_tension=0.0072, sasa_offset=0.0, _tolerance=0.005, log=True)[source]¶

Initialize the OutputAnalyzer.

Parameters:

path (Path | str) – Output directory path.
surface_tension (float) – GB surface tension.
sasa_offset (float) – SASA offset.
_tolerance (float) – Sanity check tolerance.
log (bool) – Whether to log results.

parse_outputs()[source]¶

Parse all output files and compute binding free energies.

Return type:: None

read_sasa(_file)[source]¶

Read cpptraj SASA calculation results.

Parameters:: _file (Path | str) – Path to SASA data file.
Return type:: Series
Returns:: Polars Series of rescaled SASA energies.

read_GB(_file, system)[source]¶

Read GB mdout file and parse energy terms.

Parameters:

_file (Path | str) – Path to GB energy file.
system (str) – System label (‘complex’, ‘receptor’, or ‘ligand’).

Return type:

DataFrame

Returns:

Polars DataFrame of parsed energy data.

read_PB(_file, system)[source]¶

Read PB mdout file and parse energy terms.

Parameters:

_file (Path | str) – Path to PB energy file.
system (str) – System label (‘complex’, ‘receptor’, or ‘ligand’).

Return type:

DataFrame

Returns:

Polars DataFrame of parsed energy data.

parse_energy_file(file_contents, data, system)[source]¶

Parse energy file contents.

Parameters:

file_contents (list[str]) – Lines from the energy file.
data (dict[str, list]) – Dictionary to populate with energy values.
system (str) – System label.

Return type:

DataFrame

Returns:

Polars DataFrame of energy data.

check_bonded_terms()[source]¶

Verify bonded terms cancel correctly between systems.

Raises:: ValueError – If bonded terms don’t cancel.
Return type:: None

generate_summary()[source]¶

Generate and save summary statistics to JSON file.

Return type:: None

compute_dG()[source]¶

Compute binding free energy (ΔG) for GB and PB methods.

Return type:: None

pretty_print(dfs)[source]¶

Print and save formatted energy results.

Parameters:: dfs (list[DataFrame]) – List of DataFrames for GB and PB results.
Return type:: None

static parse_line(line)[source]¶

Parse an energy line from mmpbsa_energy output.

Parameters:: line – Line from the energy output file.
Returns:: Zip iterator of (term_names, values).
Return type:: zip[tuple[str, float]]

class molecular_simulations.simulate.mmpbsa.FileHandler(top, traj, path, sels, first, last, stride, cpptraj_binary, n_chunks=1)[source]¶

Bases: object

Handle file preprocessing for MM-PBSA calculations.

Manages trajectory conversion, topology slicing, and file organization.

top¶: Path to topology file.

traj¶: Path to trajectory file.

path¶: Working directory.

selections¶: Receptor and ligand selections.

topologies¶: List of generated topology paths.

trajectories¶: List of generated trajectory paths.

pdbs¶: List of generated PDB paths.

trajectory_chunks¶: Dictionary of chunked trajectories.

Parameters:

top (Path) – Path to topology file.
traj (Path) – Path to trajectory file.
path (Path) – Working directory.
sels (list[str]) – Residue selections.
first (int) – First frame.
last (int) – Last frame.
stride (int) – Frame stride.
cpptraj_binary (Path | str) – Path to cpptraj executable.
n_chunks (int) – Number of trajectory chunks.

Initialize the FileHandler.

Parameters:

top (Path) – Topology file path.
traj (Path) – Trajectory file path.
path (Path) – Working directory.
sels (list[str]) – Selections list.
first (int) – First frame.
last (int) – Last frame.
stride (int) – Frame stride.
cpptraj_binary (Path | str) – cpptraj path.
n_chunks (int) – Number of chunks.

__init__(top, traj, path, sels, first, last, stride, cpptraj_binary, n_chunks=1)[source]¶

Initialize the FileHandler.

Parameters:

top (Path) – Topology file path.
traj (Path) – Trajectory file path.
path (Path) – Working directory.
sels (list[str]) – Selections list.
first (int) – First frame.
last (int) – Last frame.
stride (int) – Frame stride.
cpptraj_binary (Path | str) – cpptraj path.
n_chunks (int) – Number of chunks.

prepare_topologies()[source]¶

Slice sub-topologies for complex, receptor, and ligand.

Return type:: None

prepare_trajectories()[source]¶

Convert DCD trajectory to AMBER CRD format.

Return type:: None

property files: zip[tuple[Path, Path, Path, Path]]¶

Get file paths for each system.

Returns:: Zip of (prefix, topology, trajectory, pdb) for each system.

property files_chunked: list[tuple]¶

Get file paths with chunked trajectories.

Returns:: List of (prefix, topology, trajectory_chunks, pdb) tuples.

static write_file(lines, filepath)[source]¶

Write lines to a file.

Parameters:

lines (list[str] | str) – Input lines (list or string).
filepath (Path | str) – Output file path.

Return type:

None