molecular_simulations.simulate.cph_simulation module

Constant pH molecular dynamics simulations using OpenMM.

This module provides classes and functions for running constant pH simulations with replica exchange across different pH values. It uses Parsl for distributed execution of simulation replicas.

molecular_simulations.simulate.cph_simulation.run_cph_sim(params, temperature, n_cycles, n_steps, log_params, path)

Run a constant pH simulation as a Parsl python app.

This function executes a single constant pH simulation replica, performing Monte Carlo titration steps between MD propagation cycles.

Parameters:

• params (dict[str, Any]) – Dictionary of ConstantPH parameters including topology, coordinates, residue variants, and reference energies.

• temperature (kelvin) – Simulation temperature with OpenMM units.

• n_cycles (int) – Number of MD/MC cycles to perform.

• n_steps (int) – Number of MD steps per cycle.

• log_params (dict[str, str]) – Dictionary containing logging configuration with run_id, task_id, and log_dir.

• path (str) – Path to the simulation directory for logging purposes.

Return type:

None

molecular_simulations.simulate.cph_simulation.setup_worker_logger(self, worker_id, log_dir)

Set up a JSON logger for a simulation worker.

Creates a logger that writes JSON-formatted log entries to a worker-specific file.

Parameters:

• worker_id (str) – Unique identifier for the worker.

• log_dir (Path) – Directory path where log files will be written.

Return type:

Logger

Returns:

Configured logging.Logger instance for the worker.

class molecular_simulations.simulate.cph_simulation.ConstantPHEnsemble(paths, reference_energies, parsl_config, log_dir, pHs=[0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5, 11.5, 12.5, 13.5], temperature=300.0, variant_sel=None)

Bases: object

Orchestrator for running constant pH simulation ensembles.

Manages distributed execution of multiple constant pH simulation replicas using Parsl. Each replica can sample across a range of pH values with Monte Carlo titration moves.

Initialize the constant pH ensemble.

Parameters:

• paths (list[Path]) – List of paths to simulation directories, each containing system.prmtop and system.inpcrd files.

• reference_energies (dict[str, list[float]]) – Dictionary mapping residue names to lists of reference free energies for each protonation state.

• parsl_config (Config) – Parsl configuration for distributed execution.

• log_dir (Path) – Directory path for writing simulation logs.

• pHs (list[float]) – List of pH values to sample. Defaults to [0.5, 1.5, …, 13.5].

• temperature (float) – Simulation temperature in Kelvin. Defaults to 300.

• variant_sel (Optional[str]) – Optional MDAnalysis selection string to limit which titratable residues are included. Defaults to None.

__init__(paths, reference_energies, parsl_config, log_dir, pHs=[0.5, 1.5, 2.5, 3.5, 4.5, 5.5, 6.5, 7.5, 8.5, 9.5, 10.5, 11.5, 12.5, 13.5], temperature=300.0, variant_sel=None)

Initialize the constant pH ensemble.

Parameters:

• paths (list[Path]) – List of paths to simulation directories, each containing system.prmtop and system.inpcrd files.

• reference_energies (dict[str, list[float]]) – Dictionary mapping residue names to lists of reference free energies for each protonation state.

• parsl_config (Config) – Parsl configuration for distributed execution.

• log_dir (Path) – Directory path for writing simulation logs.

• pHs (list[float]) – List of pH values to sample. Defaults to [0.5, 1.5, …, 13.5].

• temperature (float) – Simulation temperature in Kelvin. Defaults to 300.

• variant_sel (Optional[str]) – Optional MDAnalysis selection string to limit which titratable residues are included. Defaults to None.

initialize()

Initialize Parsl for distributed simulation execution.

Return type:

None

shutdown()

Clean up Parsl resources after simulation completion.

Return type:

None

load_files(path)

Load topology and coordinates from AMBER files.

Parameters:

path (Path) – Directory containing system.prmtop and system.inpcrd files.

Return type:

tuple[Topology, ndarray]

Returns:

Tuple of (OpenMM Topology, atomic positions array).

build_dicts(path, top)

Build residue variant and reference energy dictionaries.

Identifies titratable residues in the topology and maps them to their possible protonation states and corresponding reference energies.

Parameters:

• path (Path) – Path to the structure file for MDAnalysis loading.

• top (Topology) – OpenMM Topology object containing residue information.

Return type:

tuple[dict[str, list[str]], dict[int, list[float]]]

Returns:

Tuple of (variants dict, reference_energies dict) where variants maps residue indices to lists of residue name variants and reference_energies maps residue indices to lists of reference free energies in kJ/mol.

run(n_cycles=500, n_steps=500)

Run the constant pH simulation ensemble.

Distributes simulation replicas across available resources using Parsl and waits for all replicas to complete.

Parameters:

• n_cycles (int) – Number of MD/MC cycles per replica. Defaults to 500.

• n_steps (int) – Number of MD steps per cycle. Defaults to 500.

Return type:

None

get_params(path)

Build the parameter dictionary for ConstantPH initialization.

Parameters:

path (Path) – Directory containing system.prmtop and system.inpcrd files.

Return type:

dict[str, Any]

Returns:

Dictionary containing all parameters needed to initialize a ConstantPH simulation including file paths, pH values, integrators, and force field parameters for both explicit and implicit solvent.