iphasimulator.charmmgui_import

Helpers for CHARMM-GUI / CGenFF outputs (CHARMM/GROMACS route).

Nothing here modifies a CHARMM-GUI download. The prepare_* functions write only into a new folder chosen by the caller, and gmx runs only when the run_* functions are called explicitly.

Classes

`PenaltyEntry`	One penalised atom charge or bonded parameter.
`CGenFFPenaltyReport`	Penalty scores parsed from a Ligand Reader & Modeler `lig/` folder.
`ItpAtom`
`ItpMolecule`	One `[ moleculetype ]` with its atoms and bonds (0-based indices).
`GroAtom`
`CheckResult`	One PASS/FAIL/SKIP line with the evidence behind it.
`MinimizationResult`
`SignedVolume`
`MdpStage`
`CharmmPolymerWaterFolder`

Functions

`penalty_category`(→ str)	Classify a CGenFF penalty with the thresholds printed in CGenFF output.
`penalty_grade`(→ str)	GOOD (< 10), CHECK (10-50) or POOR (> 50) for a CGenFF penalty.
`read_cgenff_penalties`(→ CGenFFPenaltyReport)	Parse penalty scores from `lig.rtf`, `lig_g.rtf` and `lig.prm`.
`format_cgenff_penalty_report`(→ str)	Return a short plain-text summary suitable for notebook output.
`format_checks`(→ str)	Return one line per check, followed by an overall verdict.
`read_topology_molecules`(→ dict[str, ItpMolecule])	Read every `[ moleculetype ]` in a topology and its `#include` files.
`read_topology_defaults`(→ tuple[str, ...] \| None)	Return the first `[ defaults ]` line found in the topology or its includes.
`read_topology_molecule_counts`(→ dict[str, int])	Read the `[ molecules ]` table in order.
`read_gro`(→ tuple[tuple[GroAtom, ...], tuple[float, ...]])	Read atoms (positions in nm) and box vectors from a `.gro` file.
`check_charmm_defaults`(→ CheckResult)
`check_includes`(→ CheckResult)
`check_atom_counts`(→ CheckResult)
`check_molecule_counts`(→ CheckResult)
`check_net_charge`(→ CheckResult)
`check_cgenff_types`(→ CheckResult)
`check_ligand_atom_order`(→ CheckResult)
`ligand_stereocentres`(→ list[tuple[str, str]])	CIP labels of the ligand in `gro_path`, using the SDF only for bond orders.
`check_ligand_stereocentres`(→ CheckResult)
`find_lig_topology`(→ pathlib.Path \| None)	The CGenFF topology in a `lig/` folder: `lig_g.rtf`, or `lig.rtf` when there
`read_rtf_charges`(→ dict[str, tuple[str, float]])	Atom name -> (CGenFF type, charge) from the ATOM lines of a CHARMM `.rtf`.
`read_cgenff_version`(→ tuple[str \| None, str \| None])	(CGenFF program version, topology/parameter files version) from a `lig.rtf`/`lig.prm` header.
`check_cgenff_penalties`(→ CheckResult)	CGenFF parameter and charge penalties from `lig/`: PASS < 10, WARN 10-50, FAIL > 50.
`check_ligand_charges_match_rtf`(→ CheckResult)	Every LIG atom in the GROMACS topology has the type and charge from the rtf
`ligand_signed_volumes`(→ list[SignedVolume])	Handedness of each `centre_type` stereocentre in the GROMACS coordinates vs the SDF.
`check_ligand_signed_volumes`(→ CheckResult)
`check_gromacs_run_files`(→ CheckResult)
`validate_dry_ligand_folder`(→ list[CheckResult])	Read-only checks for a folder made by `prepare_dry_ligand_folder()`.
`validate_charmm_gui_run_folder`(→ list[CheckResult])	Read-only checks for a folder made by `prepare_charmm_gui_run_folder()`.
`prepare_dry_ligand_folder`(→ pathlib.Path)	Build a solvent-free GROMACS folder from a Ligand Reader & Modeler download.
`prepare_charmm_gui_run_folder`(→ pathlib.Path)	Turn a Solution Builder download into a run folder, as in the production runs.
`read_mdp_stage`(→ MdpStage)	Length and main settings of one mdp file (length = nsteps x dt).
`describe_run_folder_protocol`(→ list[MdpStage])	The step6.0–step7 stages of a run folder, as set in its mdp files.
`annotate_slurm_stage_lengths`(→ str)	Rewrite the `# Step 6.1/6.2/7 — ...` comments from the folder's mdp files.
`run_dry_minimization`(→ MinimizationResult)	Run `grompp` + `mdrun` for the dry folder and return Epot and Fmax.
`read_minimization_result`(→ MinimizationResult)	Read the final potential energy and maximum force from an `mdrun` log.
`prepare_charmm_dry_polymer_folder`(→ pathlib.Path)	Write `gromacs_dir/dry_polymer`: the CGenFF PHA ready for GROMACS, no solvent.
`write_charmm_polymer_solvation_files`(...)	Write `gromacs_dir/solvated_polymer` from `dry_polymer` like the polymer benchmark.
`prepare_charmm_polymer_water_folder`(...)	Both steps at once: `prepare_charmm_dry_polymer_folder()`, then
`run_charmm_polymer_solvation`(→ subprocess.CompletedProcess)	Run `run_solvate_local.sh` (editconf, solvate, genion, grompp check) in `solvated_dir`.
`validate_charmm_polymer_water_folder`(→ list[CheckResult])	Read-only checks for a solvated folder from `prepare_charmm_polymer_water_folder()`.

Module Contents

iphasimulator.charmmgui_import.RESI_PENALTY_PATTERN

iphasimulator.charmmgui_import.PARAMETER_PENALTY_PATTERN

iphasimulator.charmmgui_import.PROGRAM_VERSION_PATTERN

iphasimulator.charmmgui_import.FILES_VERSION_PATTERN

iphasimulator.charmmgui_import.TOPOLOGY_FILES = ('lig.rtf', 'lig_g.rtf')

iphasimulator.charmmgui_import.PARAMETER_FILE = 'lig.prm'

class iphasimulator.charmmgui_import.PenaltyEntry

One penalised atom charge or bonded parameter.

source: str

label: str

penalty: float

class iphasimulator.charmmgui_import.CGenFFPenaltyReport

Penalty scores parsed from a Ligand Reader & Modeler lig/ folder.

lig_dir: pathlib.Path

files_read: tuple[str, ...]

program_version: str | None

parameter_files_version: str | None

resi_penalties: dict[str, tuple[float, float]]

charge_penalties: tuple[PenaltyEntry, ...]

parameter_penalties: tuple[PenaltyEntry, ...]

property max_charge_penalty: float | None

property max_parameter_penalty: float | None

top_charge_penalties(n: int = 5) → tuple[PenaltyEntry, ...]

top_parameter_penalties(n: int = 5) → tuple[PenaltyEntry, ...]

iphasimulator.charmmgui_import.penalty_category(penalty: float | None) → str: Classify a CGenFF penalty with the thresholds printed in CGenFF output.

iphasimulator.charmmgui_import.PENALTY_GRADE_RULES

iphasimulator.charmmgui_import.penalty_grade(penalty: float) → str: GOOD (< 10), CHECK (10-50) or POOR (> 50) for a CGenFF penalty.

iphasimulator.charmmgui_import.read_cgenff_penalties(lig_dir: str | pathlib.Path) → CGenFFPenaltyReport

Parse penalty scores from lig.rtf, lig_g.rtf and lig.prm.

Missing files are skipped; at least one of them must exist.

iphasimulator.charmmgui_import.format_cgenff_penalty_report(report: CGenFFPenaltyReport, top: int = 5) → str: Return a short plain-text summary suitable for notebook output.

iphasimulator.charmmgui_import.CHARMM_GROMACS_TEMPLATE_DIR

iphasimulator.charmmgui_import.CHARMM_GROMACS_MDP_FILES = ('step6.0_minimization.mdp', 'step6.1_nvt.mdp', 'step6.2_npt.mdp', 'step7_production.mdp')

iphasimulator.charmmgui_import.LOCAL_SCRIPT = 'run_step6_local.sh'

iphasimulator.charmmgui_import.HPC_SCRIPT = 'run_hpc_equilibration_production.slurm'

iphasimulator.charmmgui_import.HPC_SCRIPT_TEMPLATE = 'run_hpc_equilibration_production.slurm.template'

iphasimulator.charmmgui_import.CHARMM_GUI_INDEX_GROUPS = ('SOLU', 'SOLV')

iphasimulator.charmmgui_import.CHARMM_DEFAULTS = ('1', '2', 'yes', 1.0, 1.0)

iphasimulator.charmmgui_import.CGENFF_TYPE_PATTERN

iphasimulator.charmmgui_import.WATER_MOLECULES = ('TIP3', 'SOL', 'HOH', 'WAT')

iphasimulator.charmmgui_import.ION_MOLECULES = ('SOD', 'CLA', 'POT', 'NA', 'CL')

iphasimulator.charmmgui_import.DRY_COORDINATES = 'lig.gro'

iphasimulator.charmmgui_import.DRY_MDP = 'dry_minimization.mdp'

iphasimulator.charmmgui_import.DRY_DEFFNM = 'dry_minimization'

iphasimulator.charmmgui_import.DRY_MINIMIZATION_MDP = Multiline-String

Show Value

"""; Dry (no solvent) steepest-descent minimisation of the CGenFF polymer.
; Sanity check only: GROMACS' Verlet scheme needs a periodic box, so
; the molecule sits alone in a box larger than twice the cut-off.
integrator              = steep
emtol                   = 100.0
emstep                  = 0.01
nsteps                  = 5000
nstlist                 = 10
cutoff-scheme           = Verlet
pbc                     = xyz
rlist                   = 1.2
vdwtype                 = Cut-off
vdw-modifier            = Force-switch
rvdw_switch             = 1.0
rvdw                    = 1.2
coulombtype             = PME
rcoulomb                = 1.2
constraints             = h-bonds
constraint_algorithm    = LINCS
"""

iphasimulator.charmmgui_import.POTENTIAL_ENERGY_PATTERN

iphasimulator.charmmgui_import.MAXIMUM_FORCE_PATTERN

iphasimulator.charmmgui_import.ELEMENT_BY_MASS

class iphasimulator.charmmgui_import.ItpAtom

name: str

type: str

charge: float

mass: float

class iphasimulator.charmmgui_import.ItpMolecule

One [ moleculetype ] with its atoms and bonds (0-based indices).

name: str

atoms: tuple[ItpAtom, ...]

bonds: tuple[tuple[int, int], ...]

property charge: float

class iphasimulator.charmmgui_import.GroAtom

residue_number: int

residue_name: str

atom_name: str

position: tuple[float, float, float]

class iphasimulator.charmmgui_import.CheckResult

One PASS/FAIL/SKIP line with the evidence behind it.

name: str

status: str

evidence: str

property passed: bool

class iphasimulator.charmmgui_import.MinimizationResult

log_path: pathlib.Path

potential_energy: float | None

maximum_force: float | None

iphasimulator.charmmgui_import.format_checks(results: list[CheckResult]) → str: Return one line per check, followed by an overall verdict.

iphasimulator.charmmgui_import.read_topology_molecules(topology_path: str | pathlib.Path) → dict[str, ItpMolecule]: Read every [ moleculetype ] in a topology and its #include files.

iphasimulator.charmmgui_import.read_topology_defaults(topology_path: str | pathlib.Path) → tuple[str, ...] | None: Return the first [ defaults ] line found in the topology or its includes.

iphasimulator.charmmgui_import.read_topology_molecule_counts(topology_path: str | pathlib.Path) → dict[str, int]: Read the [ molecules ] table in order.

iphasimulator.charmmgui_import.read_gro(gro_path: str | pathlib.Path) → tuple[tuple[GroAtom, ...], tuple[float, ...]]: Read atoms (positions in nm) and box vectors from a .gro file.

iphasimulator.charmmgui_import.check_charmm_defaults(topology_path: str | pathlib.Path) → CheckResult

iphasimulator.charmmgui_import.check_includes(folder: str | pathlib.Path, topology_name: str = 'topol.top') → CheckResult

iphasimulator.charmmgui_import.check_atom_counts(folder: str | pathlib.Path, coordinate_name: str, topology_name: str = 'topol.top') → CheckResult

iphasimulator.charmmgui_import.check_molecule_counts(topology_path: str | pathlib.Path, *, ligand: str = 'LIG', require_water: bool) → CheckResult

iphasimulator.charmmgui_import.check_net_charge(topology_path: str | pathlib.Path, tolerance: float = 0.001) → CheckResult

iphasimulator.charmmgui_import.check_cgenff_types(topology_path: str | pathlib.Path, ligand: str = 'LIG') → CheckResult

iphasimulator.charmmgui_import.check_ligand_atom_order(gro_path: str | pathlib.Path, topology_path: str | pathlib.Path, ligand: str = 'LIG') → CheckResult

iphasimulator.charmmgui_import.ligand_stereocentres(gro_path: str | pathlib.Path, topology_path: str | pathlib.Path, sdf_path: str | pathlib.Path, ligand: str = 'LIG') → list[tuple[str, str]]

CIP labels of the ligand in gro_path, using the SDF only for bond orders.

The ligand graph comes from the .itp bonds and its geometry from the .gro coordinates (made whole across the box), so the labels describe the structure GROMACS will simulate, not the uploaded SDF.

iphasimulator.charmmgui_import.check_ligand_stereocentres(gro_path: str | pathlib.Path, topology_path: str | pathlib.Path, sdf_path: str | pathlib.Path | None, ligand: str = 'LIG', expected: str = 'R') → CheckResult

iphasimulator.charmmgui_import.find_lig_topology(lig_dir: str | pathlib.Path | None) → pathlib.Path | None: The CGenFF topology in a lig/ folder: lig_g.rtf, or lig.rtf when there is no lig_g.rtf (the charges are identical). None when neither exists.

iphasimulator.charmmgui_import.read_rtf_charges(rtf_path: str | pathlib.Path) → dict[str, tuple[str, float]]: Atom name -> (CGenFF type, charge) from the ATOM lines of a CHARMM .rtf.

iphasimulator.charmmgui_import.read_cgenff_version(path: str | pathlib.Path) → tuple[str | None, str | None]: (CGenFF program version, topology/parameter files version) from a lig.rtf/lig.prm header.

iphasimulator.charmmgui_import.check_cgenff_penalties(lig_dir: str | pathlib.Path | None) → CheckResult: CGenFF parameter and charge penalties from lig/: PASS < 10, WARN 10-50, FAIL > 50.

iphasimulator.charmmgui_import.check_ligand_charges_match_rtf(topology_path: str | pathlib.Path, rtf_path: str | pathlib.Path | None, ligand: str = 'LIG', tolerance: float = 0.001) → CheckResult: Every LIG atom in the GROMACS topology has the type and charge from the rtf (lig_g.rtf or lig.rtf; their charges are identical).

class iphasimulator.charmmgui_import.SignedVolume

atom: str

neighbours: str

volume_md: float

volume_sdf: float

sdf_label: str

label: str

iphasimulator.charmmgui_import.ligand_signed_volumes(gro_path: str | pathlib.Path, topology_path: str | pathlib.Path, sdf_path: str | pathlib.Path, ligand: str = 'LIG', centre_type: str = 'CG311') → list[SignedVolume]

Handedness of each centre_type stereocentre in the GROMACS coordinates vs the SDF.

For every CG311 carbon (the PHA backbone CH), the signed volume of its three heavy neighbours (O, CH2, CH3 for PHB; O, CH2, CH2 for longer side chains), taken in the same order in both structures, is compared with the SDF. The same sign means the same configuration as the SDF (R for an R-configured SDF).

iphasimulator.charmmgui_import.check_ligand_signed_volumes(gro_path: str | pathlib.Path, topology_path: str | pathlib.Path, sdf_path: str | pathlib.Path | None, ligand: str = 'LIG', expected: str = 'R') → CheckResult

iphasimulator.charmmgui_import.check_gromacs_run_files(folder: str | pathlib.Path, index_groups: tuple[str, ...] = CHARMM_GUI_INDEX_GROUPS) → CheckResult

iphasimulator.charmmgui_import.validate_dry_ligand_folder(folder: str | pathlib.Path, *, sdf_path: str | pathlib.Path | None = None, ligand: str = 'LIG') → list[CheckResult]: Read-only checks for a folder made by prepare_dry_ligand_folder().

iphasimulator.charmmgui_import.validate_charmm_gui_run_folder(folder: str | pathlib.Path, *, sdf_path: str | pathlib.Path | None = None, ligand: str = 'LIG') → list[CheckResult]: Read-only checks for a folder made by prepare_charmm_gui_run_folder().

iphasimulator.charmmgui_import.prepare_dry_ligand_folder(ligand_reader_dir: str | pathlib.Path, output_dir: str | pathlib.Path, *, padding_nm: float = 1.7) → pathlib.Path

Build a solvent-free GROMACS folder from a Ligand Reader & Modeler download.

Copies gromacs/topol.top, charmm36.itp and LIG.itp, writes lig.gro from ligandrm.pdb centred in a cubic box of the molecule’s extent plus 2 * padding_nm, and writes dry_minimization.mdp.

Turn a Solution Builder download into a run folder, as in the production runs.

Copies gromacs/ (topology, toppar/, index.ndx, coordinates) into the new run_dir, renames step3_input.gro to step5_input.gro, leaves out CHARMM-GUI’s step4.x/step5 mdp files, and adds the CHARMM/GROMACS mdp files and scripts from template_dir (default: the packaged CHARMM/GROMACS templates). The SLURM job name defaults to the run folder’s name, and the SLURM stage comments are written from the copied mdp files (nsteps x dt).

iphasimulator.charmmgui_import.SLURM_STAGES = (('step6.1_nvt', 'Step 6.1', 'NVT'), ('step6.2_npt', 'Step 6.2', 'NPT'), ('step7_production',...

class iphasimulator.charmmgui_import.MdpStage

name: str

integrator: str

nsteps: int

dt_ps: float | None

temperature: str | None

pressure_coupling: str | None

position_restraints: bool

property length_ps: float | None

length_text() → str

iphasimulator.charmmgui_import.read_mdp_stage(mdp_path: str | pathlib.Path) → MdpStage: Length and main settings of one mdp file (length = nsteps x dt).

iphasimulator.charmmgui_import.describe_run_folder_protocol(folder: str | pathlib.Path) → list[MdpStage]: The step6.0–step7 stages of a run folder, as set in its mdp files.

iphasimulator.charmmgui_import.annotate_slurm_stage_lengths(text: str, folder: str | pathlib.Path) → str: Rewrite the # Step 6.1/6.2/7 — ... comments from the folder’s mdp files.

iphasimulator.charmmgui_import.run_dry_minimization(folder: str | pathlib.Path, *, gmx: str = 'gmx', runner=subprocess.run) → MinimizationResult: Run grompp + mdrun for the dry folder and return Epot and Fmax.

iphasimulator.charmmgui_import.read_minimization_result(log_path: str | pathlib.Path) → MinimizationResult: Read the final potential energy and maximum force from an mdrun log.

iphasimulator.charmmgui_import.CHARMM_POLYMER_TEMPLATE_DIR

iphasimulator.charmmgui_import.WATER_ION_ATOMTYPES_INCLUDE = 'tip3_ions_atomtypes.itp'

iphasimulator.charmmgui_import.WATER_ION_MOLECULE_INCLUDES = ('TIP3_SOL.itp', 'SOD.itp', 'CLA.itp')

iphasimulator.charmmgui_import.SOLVATE_SCRIPT = 'run_solvate_local.sh'

class iphasimulator.charmmgui_import.CharmmPolymerWaterFolder

run_dir: pathlib.Path

dry_dir: pathlib.Path

solvated_dir: pathlib.Path

solvate_script_path: pathlib.Path

local_script_path: pathlib.Path

hpc_script_path: pathlib.Path

iphasimulator.charmmgui_import.prepare_charmm_dry_polymer_folder(ligand_reader_dir: str | pathlib.Path, gromacs_dir: str | pathlib.Path) → pathlib.Path

Write gromacs_dir/dry_polymer: the CGenFF PHA ready for GROMACS, no solvent.

The Ligand Reader topology (topol.top, charmm36.itp, LIG.itp) with the packaged CHARMM TIP3P/SOD/CLA files included, step5_input.gro and index.ndx (the same files prepare_gromacs_run_folder writes for a GAFF2 PHA), plus lig.gro and dry_minimization.mdp for an optional solvent-free minimisation.

iphasimulator.charmmgui_import.write_charmm_polymer_solvation_files(gromacs_dir: str | pathlib.Path, *, box_padding_nm: float = 1.2, ion_concentration_molar: float = 0.15, job_name: str | None = None) → CharmmPolymerWaterFolder

Write gromacs_dir/solvated_polymer from dry_polymer like the polymer benchmark.

Copies the topology include files and the CHARMM polymer mdp set, then calls write_gromacs_solvation_files() for the benchmark’s run_solvate_local.sh (box, water, ions), run_step6_local.sh and SLURM script. Nothing is solvated until run_solvate_local.sh runs.

iphasimulator.charmmgui_import.prepare_charmm_polymer_water_folder(ligand_reader_dir: str | pathlib.Path, run_dir: str | pathlib.Path, *, box_padding_nm: float = 1.2, ion_concentration_molar: float = 0.15, job_name: str | None = None) → CharmmPolymerWaterFolder: Both steps at once: prepare_charmm_dry_polymer_folder(), then write_charmm_polymer_solvation_files(), in a new run_dir.

iphasimulator.charmmgui_import.run_charmm_polymer_solvation(solvated_dir: str | pathlib.Path, *, runner=subprocess.run) → subprocess.CompletedProcess: Run run_solvate_local.sh (editconf, solvate, genion, grompp check) in solvated_dir.

iphasimulator.charmmgui_import.validate_charmm_polymer_water_folder(solvated_dir: str | pathlib.Path, *, sdf_path: str | pathlib.Path | None = None, ligand: str = 'LIG') → list[CheckResult]: Read-only checks for a solvated folder from prepare_charmm_polymer_water_folder().

`RESI_PENALTY_PATTERN`
`PARAMETER_PENALTY_PATTERN`
`PROGRAM_VERSION_PATTERN`
`FILES_VERSION_PATTERN`
`TOPOLOGY_FILES`
`PARAMETER_FILE`
`PENALTY_GRADE_RULES`
`CHARMM_GROMACS_TEMPLATE_DIR`
`CHARMM_GROMACS_MDP_FILES`
`LOCAL_SCRIPT`
`HPC_SCRIPT`
`HPC_SCRIPT_TEMPLATE`
`CHARMM_GUI_INDEX_GROUPS`
`CHARMM_DEFAULTS`
`CGENFF_TYPE_PATTERN`
`WATER_MOLECULES`
`ION_MOLECULES`
`DRY_COORDINATES`
`DRY_MDP`
`DRY_DEFFNM`
`DRY_MINIMIZATION_MDP`
`POTENTIAL_ENERGY_PATTERN`
`MAXIMUM_FORCE_PATTERN`
`ELEMENT_BY_MASS`
`SLURM_STAGES`
`CHARMM_POLYMER_TEMPLATE_DIR`
`WATER_ION_ATOMTYPES_INCLUDE`
`WATER_ION_MOLECULE_INCLUDES`
`SOLVATE_SCRIPT`

iphasimulator.charmmgui_import

Attributes

Classes

Functions

Module Contents