iphasimulator.amber_solvation
=============================
.. py:module:: iphasimulator.amber_solvation
.. autoapi-nested-parse::
Amber/OpenMM solvated systems: tleap (GAFF2 + OPC, optional ff19SB) and staged OpenMM MD.
The stage lengths, temperatures and restraints follow the GROMACS references:
POLYMER_IN_WATER_PROTOCOL the polymer benchmark (notebook 06A) and
ENZYME_POLYMER_IN_WATER_PROTOCOL the enzyme–polymer production runs (notebook 06B).
The force fields, thermostat, barostat and non-bonded settings differ (Amber/OpenMM),
so 06C results are not directly comparable with 06B. ``tleap`` and OpenMM run only
when a ``build_``/``run_`` function or the generated ``run_openmm_md.py`` is called;
everything else writes text files.
Attributes
----------
.. autoapisummary::
iphasimulator.amber_solvation.WATER_MOLARITY
iphasimulator.amber_solvation.SYSTEM_PRMTOP
iphasimulator.amber_solvation.SYSTEM_INPCRD
iphasimulator.amber_solvation.SYSTEM_PDB
iphasimulator.amber_solvation.TLEAP_INPUT
iphasimulator.amber_solvation.TLEAP_LOG
iphasimulator.amber_solvation.COUNT_INPUT
iphasimulator.amber_solvation.COUNT_LOG
iphasimulator.amber_solvation.RUN_SCRIPT
iphasimulator.amber_solvation.PROTOCOL_FILE
iphasimulator.amber_solvation.LOCAL_SCRIPT
iphasimulator.amber_solvation.HPC_SCRIPT
iphasimulator.amber_solvation.RUN_SCRIPT_SOURCE
iphasimulator.amber_solvation.ADDED_RESIDUES_PATTERN
iphasimulator.amber_solvation.ION_PARAMETERS_PATTERN
iphasimulator.amber_solvation.LEAP_ERRORS_PATTERN
iphasimulator.amber_solvation.POLYMER_IN_WATER_PROTOCOL
iphasimulator.amber_solvation.ENZYME_POLYMER_IN_WATER_PROTOCOL
iphasimulator.amber_solvation.ENZYME_SOLVATION_SETTINGS
iphasimulator.amber_solvation.LOCAL_SCRIPT_TEXT
iphasimulator.amber_solvation.HPC_SCRIPT_TEMPLATE
Classes
-------
.. autoapisummary::
iphasimulator.amber_solvation.AmberSolvationSettings
iphasimulator.amber_solvation.AmberSystemOutputs
iphasimulator.amber_solvation.TleapLogSummary
iphasimulator.amber_solvation.OpenMMProtocol
Functions
---------
.. autoapisummary::
iphasimulator.amber_solvation.salt_ion_pairs
iphasimulator.amber_solvation.density_g_per_ml
iphasimulator.amber_solvation.write_tleap_input
iphasimulator.amber_solvation.parse_tleap_log
iphasimulator.amber_solvation.build_solvated_amber_system
iphasimulator.amber_solvation.write_openmm_run_files
iphasimulator.amber_solvation.load_openmm_runner
iphasimulator.amber_solvation.run_openmm_stages
iphasimulator.amber_solvation.run_openmm_short_test
Module Contents
---------------
.. py:data:: WATER_MOLARITY
:value: 55.5
.. py:data:: SYSTEM_PRMTOP
:value: 'system.prmtop'
.. py:data:: SYSTEM_INPCRD
:value: 'system.inpcrd'
.. py:data:: SYSTEM_PDB
:value: 'system.pdb'
.. py:data:: TLEAP_INPUT
:value: 'tleap.in'
.. py:data:: TLEAP_LOG
:value: 'tleap.log'
.. py:data:: COUNT_INPUT
:value: 'tleap_count_waters.in'
.. py:data:: COUNT_LOG
:value: 'tleap_count_waters.log'
.. py:data:: RUN_SCRIPT
:value: 'run_openmm_md.py'
.. py:data:: PROTOCOL_FILE
:value: 'protocol.json'
.. py:data:: LOCAL_SCRIPT
:value: 'run_step6_local.sh'
.. py:data:: HPC_SCRIPT
:value: 'run_hpc_equilibration_production.slurm'
.. py:data:: RUN_SCRIPT_SOURCE
.. py:data:: ADDED_RESIDUES_PATTERN
.. py:data:: ION_PARAMETERS_PATTERN
.. py:data:: LEAP_ERRORS_PATTERN
.. py:class:: AmberSolvationSettings
Box and ion choices for the tleap build (lengths in nm, salt in mol/L).
.. py:attribute:: padding_nm
:type: float
:value: 1.2
.. py:attribute:: box_shape
:type: str
:value: 'box'
.. py:attribute:: cubic
:type: bool
:value: True
.. py:attribute:: salt_molar
:type: float
:value: 0.15
.. py:attribute:: cation
:type: str
:value: 'Na+'
.. py:attribute:: anion
:type: str
:value: 'Cl-'
.. py:class:: AmberSystemOutputs
.. py:attribute:: output_dir
:type: pathlib.Path
.. py:attribute:: tleap_input_path
:type: pathlib.Path
.. py:attribute:: tleap_log_path
:type: pathlib.Path
.. py:attribute:: prmtop_path
:type: pathlib.Path
.. py:attribute:: inpcrd_path
:type: pathlib.Path
.. py:attribute:: pdb_path
:type: pathlib.Path
.. py:attribute:: water_count
:type: int
.. py:attribute:: salt_ion_pairs
:type: int
.. py:attribute:: ion_parameter_files
:type: tuple[str, ...]
.. py:class:: TleapLogSummary
.. py:attribute:: water_count
:type: int | None
.. py:attribute:: ion_parameter_files
:type: tuple[str, ...]
.. py:attribute:: errors
:type: int | None
.. py:class:: OpenMMProtocol
Staged MD settings (times in ps/ns, time steps in fs, restraints in kJ mol^-1 nm^-2).
.. py:attribute:: name
:type: str
.. py:attribute:: temperature_kelvin
:type: float
.. py:attribute:: minimization_max_iterations
:type: int
.. py:attribute:: nvt_ps
:type: float
.. py:attribute:: nvt_timestep_fs
:type: float
.. py:attribute:: npt_ps
:type: float
.. py:attribute:: npt_timestep_fs
:type: float
.. py:attribute:: production_ns
:type: float
.. py:attribute:: production_frame_ps
:type: float
.. py:attribute:: production_timestep_fs
:type: float
:value: 2.0
.. py:attribute:: equilibration_frame_ps
:type: float
:value: 0.0
.. py:attribute:: report_ps
:type: float
:value: 10.0
.. py:attribute:: pressure_bar
:type: float
:value: 1.0
.. py:attribute:: cutoff_nm
:type: float
:value: 1.0
.. py:attribute:: friction_per_ps
:type: float
:value: 1.0
.. py:attribute:: barostat_frequency
:type: int
:value: 25
.. py:attribute:: minimization_tolerance
:type: float
:value: 1000.0
.. py:attribute:: backbone_restraint
:type: float
:value: 0.0
.. py:attribute:: sidechain_restraint
:type: float
:value: 0.0
.. py:attribute:: npt_frame_ps
:type: float | None
:value: None
.. py:attribute:: nvt_report_ps
:type: float | None
:value: None
.. py:attribute:: npt_report_ps
:type: float | None
:value: None
.. py:attribute:: constraint_tolerance
:type: float
:value: 1e-05
.. py:attribute:: ewald_error_tolerance
:type: float
:value: 0.0005
.. py:data:: POLYMER_IN_WATER_PROTOCOL
.. py:data:: ENZYME_POLYMER_IN_WATER_PROTOCOL
.. py:data:: ENZYME_SOLVATION_SETTINGS
.. py:function:: salt_ion_pairs(water_count: int, salt_molar: float) -> int
Ion pairs for ``salt_molar`` from the number of waters (55.5 mol/L water).
.. py:function:: density_g_per_ml(total_mass_dalton: float, volume_nm3: float) -> float
Convert a system mass in Da and a box volume in nm^3 to g/mL (1 Da/nm^3 = 1.66054e-3 g/mL).
.. py:function:: write_tleap_input(path: str | pathlib.Path, *, mol2_name: str, frcmod_name: str, settings: AmberSolvationSettings, protein_pdb_name: str | None = None, salt_pairs: int | None = None) -> str
Write a tleap input and return its text.
With ``salt_pairs=None`` the input only solvates (used to count waters);
otherwise it neutralises, adds ``salt_pairs`` ion pairs and saves the system.
.. py:function:: parse_tleap_log(text: str) -> TleapLogSummary
Waters added by the (last) solvate command, ion frcmod files loaded, error count.
.. py:function:: build_solvated_amber_system(mol2_path: str | pathlib.Path, frcmod_path: str | pathlib.Path, output_dir: str | pathlib.Path, *, protein_pdb_path: str | pathlib.Path | None = None, settings: AmberSolvationSettings = AmberSolvationSettings(), tleap: str = 'tleap', runner=subprocess.run) -> AmberSystemOutputs
Solvate the 05A polymer (optionally with a posed protein) in OPC and add ions.
Copies the inputs into a new ``output_dir``, runs tleap once to count the
waters for the requested padding, then builds the neutralised, salted system
and writes ``system.prmtop`` / ``system.inpcrd`` / ``system.pdb`` with the
tleap input and log next to them.
.. py:function:: write_openmm_run_files(system_dir: str | pathlib.Path, protocol: OpenMMProtocol, *, job_name: str, polymer_residues: tuple[str, ...] = ('PHA', )) -> tuple[pathlib.Path, ...]
Write ``run_openmm_md.py``, ``protocol.json``, ``run_step6_local.sh`` and the SLURM file.
The layout mirrors the GROMACS run folders: step 6.0 locally, then steps 6.1,
6.2 and 7 on the cluster. ``polymer_residues`` names the polymer residue(s)
restrained with the backbone force constant.
.. py:function:: load_openmm_runner()
Import the packaged ``run_openmm_md.py`` (the same file the run folders use).
.. py:function:: run_openmm_stages(system_dir: str | pathlib.Path, stages, *, platform_name: str | None = None) -> list[dict]
Run stages (e.g. ``["step6.0_minimization"]``) in ``system_dir`` with its protocol.json.
.. py:function:: run_openmm_short_test(system_dir: str | pathlib.Path, *, platform_name: str | None = None) -> list[dict]
Minimise, then 10 ps NVT and 10 ps NPT in ``system_dir/short_test`` (protocol otherwise).
.. py:data:: LOCAL_SCRIPT_TEXT
:value: Multiline-String
.. raw:: html
Show Value
.. code-block:: python
"""#!/usr/bin/env bash
set -euo pipefail
python run_openmm_md.py step6.0_minimization
"""
.. raw:: html
Show Value
.. code-block:: python
"""#!/bin/bash -l
#SBATCH --job-name={JOB_NAME}
#SBATCH --partition=gpu
#SBATCH --nodes=1
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=8
#SBATCH --gres=gpu:1
#SBATCH --mem=16G
#SBATCH --time=2-00:00
#SBATCH --output=logs/%x-%j.out
#SBATCH --error=logs/%x-%j.err
# Activate a Python environment with OpenMM (CUDA build), for example:
# module load anaconda3 && conda activate ipha_clean
set -euo pipefail
cd "${SLURM_SUBMIT_DIR:-$PWD}"
mkdir -p logs
# Steps 6.1 (NVT), 6.2 (NPT) and 7 (production); settings in protocol.json.
# Each MD stage continues from its own checkpoint; completed stages take no new steps.
python run_openmm_md.py step6.1_nvt step6.2_npt step7_production --platform CUDA
"""
.. raw:: html