mdprep 0.2.0__py3-none-any.whl

mdprep/metals/mcpb_compat.py

@@ -0,0 +1,125 @@
+"""Numerically neutral compatibility adapter for MCPB.py Seminario parsing.
+
+Some real, symmetric Cartesian Hessians yield complex-conjugate eigenpairs for
+MCPB.py's non-symmetric 3x3 interatomic blocks.  Their projected force constant
+can be exactly real but retain NumPy's complex scalar type, which MCPB.py cannot
+round.  This adapter converts only negligible-imaginary scalar results to real
+numbers and fails on any material imaginary component.
+"""
+
+from __future__ import annotations
+
+import argparse
+import runpy
+import sys
+from collections.abc import Callable, Sequence
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+class McpbSeminarioCompatibilityError(ValueError):
+    """Raised when a projected MCPB value is materially complex."""
+
+
+def coerce_negligible_imaginary(
+    value: Any,
+    *,
+    label: str,
+    relative_tolerance: float = 1.0e-10,
+) -> Any:
+    """Return the real part only when the imaginary residual is negligible."""
+
+    if not np.iscomplexobj(value):
+        return value
+    scalar = complex(value)
+    limit = relative_tolerance * max(1.0, abs(scalar.real))
+    if abs(scalar.imag) > limit:
+        raise McpbSeminarioCompatibilityError(
+            f"{label} is materially complex: {scalar!r}; allowed imaginary "
+            f"magnitude is {limit:.3e}. The Hessian cannot be passed safely to MCPB.py."
+        )
+    return float(scalar.real)
+
+
+def _coerce_result(value: Any, *, label: str, counter: list[int]) -> Any:
+    if isinstance(value, tuple):
+        return tuple(
+            _coerce_result(item, label=f"{label}[{index}]", counter=counter)
+            for index, item in enumerate(value)
+        )
+    converted = coerce_negligible_imaginary(value, label=label)
+    if converted is not value:
+        counter[0] += 1
+    return converted
+
+
+def run_mcpb_with_compatibility(
+    mcpb_script: str | Path,
+    mcpb_args: Sequence[str],
+) -> None:
+    """Run MCPB.py after installing the strict scalar-type compatibility shim."""
+
+    script = Path(mcpb_script).resolve()
+    if not script.is_file() or script.stat().st_size == 0:
+        raise McpbSeminarioCompatibilityError(
+            f"MCPB.py script is missing or empty: {script}"
+        )
+    try:
+        from pymsmt.mcpb import gene_final_frcmod_file as seminario
+    except Exception as exc:  # pragma: no cover - depends on external AmberTools
+        raise McpbSeminarioCompatibilityError(
+            "MCPB.py compatibility adapter could not import pymsmt from the active "
+            "Python environment. Run mdprep from the AmberTools environment."
+        ) from exc
+
+    counter = [0]
+    originals = {
+        "get_bond_fc_with_sem": seminario.get_bond_fc_with_sem,
+        "get_ang_fc": seminario.get_ang_fc,
+        "get_mod_ang_fc": seminario.get_mod_ang_fc,
+    }
+
+    def wrap(name: str) -> Callable[..., Any]:
+        original = originals[name]
+
+        def compatible(*args: Any, **kwargs: Any) -> Any:
+            return _coerce_result(
+                original(*args, **kwargs),
+                label=name,
+                counter=counter,
+            )
+
+        return compatible
+
+    for name in originals:
+        setattr(seminario, name, wrap(name))
+    previous_argv = sys.argv
+    sys.argv = [str(script), *mcpb_args]
+    try:
+        runpy.run_path(str(script), run_name="__main__")
+    finally:
+        sys.argv = previous_argv
+        for name, original in originals.items():
+            setattr(seminario, name, original)
+        print(
+            "[mdprep] MCPB Seminario compatibility adapter converted "
+            f"{counter[0]} negligible-imaginary scalar value(s) to real values."
+        )
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--mcpb-script", required=True)
+    parser.add_argument("mcpb_args", nargs=argparse.REMAINDER)
+    options = parser.parse_args(argv)
+    mcpb_args = list(options.mcpb_args)
+    if mcpb_args[:1] == ["--"]:
+        mcpb_args = mcpb_args[1:]
+    run_mcpb_with_compatibility(options.mcpb_script, mcpb_args)
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover - exercised through MCPB external tests
+    raise SystemExit(main())

mdprep/metals/nonbonded.py

@@ -0,0 +1,294 @@
+"""Amber Li/Merz nonbonded ion parameter preparation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import shutil
+
+from mdprep.config.models import MetalSiteConfig
+from mdprep.metals.coordination import ResolvedMetalIon, ResolvedMetalSite
+
+
+class NonbondedMetalError(ValueError):
+    """Raised when the requested Amber ion model is unavailable or inconsistent."""
+
+
+@dataclass(frozen=True)
+class AmberIonParameter:
+    element: str
+    charge: int
+    atom_type: str
+    mass: float
+    rmin_over_2_angstrom: float
+    epsilon_kcal_mol: float
+    parameter_set: str
+    water_model: str
+    frcmod_name: str
+    frcmod_path: Path
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "element": self.element,
+            "charge": self.charge,
+            "atom_type": self.atom_type,
+            "mass": self.mass,
+            "rmin_over_2_angstrom": self.rmin_over_2_angstrom,
+            "epsilon_kcal_mol": self.epsilon_kcal_mol,
+            "parameter_set": self.parameter_set,
+            "water_model": self.water_model,
+            "frcmod_name": self.frcmod_name,
+            "frcmod_path": str(self.frcmod_path),
+        }
+
+
+@dataclass(frozen=True)
+class NonbondedIonArtifact:
+    ion: ResolvedMetalIon
+    parameter: AmberIonParameter
+    mol2_path: Path
+    leap_variable: str
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            **self.ion.to_dict(),
+            "parameter": self.parameter.to_dict(),
+            "mol2_path": str(self.mol2_path),
+            "leap_variable": self.leap_variable,
+        }
+
+
+@dataclass(frozen=True)
+class NonbondedSiteResult:
+    site_id: str
+    parameter_set: str
+    ions: tuple[NonbondedIonArtifact, ...]
+    leap_commands: tuple[str, ...]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "site_id": self.site_id,
+            "model": "nonbonded",
+            "parameter_set": self.parameter_set,
+            "ions": [ion.to_dict() for ion in self.ions],
+            "leap_commands": list(self.leap_commands),
+        }
+
+
+def prepare_nonbonded_site(
+    site: ResolvedMetalSite,
+    *,
+    water_model: str,
+    output_dir: str | Path,
+    amberhome: str | Path | None = None,
+) -> NonbondedSiteResult:
+    if site.config.model != "nonbonded" or site.config.nonbonded is None:
+        raise NonbondedMetalError(f"Metal site {site.config.id!r} is not a nonbonded site.")
+    # Metal setup commands are composed into tleap scripts executed from
+    # several different stage directories. Resolve generated templates once
+    # so every preserved script remains independently runnable.
+    output = Path(output_dir).resolve()
+    output.mkdir(parents=True, exist_ok=True)
+    parameter_set = _canonical_parameter_set(site.config.nonbonded.parameter_set)
+    amber_root = resolve_amberhome(amberhome)
+
+    artifacts: list[NonbondedIonArtifact] = []
+    commands: list[str] = []
+    defined_types: set[str] = set()
+    loaded_frcmods: set[Path] = set()
+    residue_templates: dict[str, tuple[str, int, str]] = {}
+    for index, ion in enumerate(site.ions, start=1):
+        parameter = load_amber_ion_parameter(
+            element=ion.element,
+            charge=ion.charge,
+            water_model=water_model,
+            parameter_set=parameter_set,
+            amberhome=amber_root,
+        )
+        residue_name = ion.residue.id.resname
+        atom_name = ion.atom.name
+        signature = (ion.element, ion.charge, atom_name)
+        previous = residue_templates.get(residue_name)
+        if previous is not None and previous != signature:
+            raise NonbondedMetalError(
+                f"Metal residue name {residue_name!r} is used with incompatible ion templates: "
+                f"{previous} and {signature}. Use distinct PDB residue names."
+            )
+        residue_templates[residue_name] = signature
+        mol2_path = output / f"{site.config.id}.{index}.{residue_name}.mol2"
+        write_single_ion_mol2(ion, parameter, mol2_path)
+        variable = _leap_variable(site.config, index, residue_name)
+        if parameter.atom_type not in defined_types:
+            commands.extend(
+                [
+                    "addAtomTypes {",
+                    f'    {{ "{parameter.atom_type}" "{ion.element}" "sp3" }}',
+                    "}",
+                ]
+            )
+            defined_types.add(parameter.atom_type)
+        if parameter.frcmod_path not in loaded_frcmods:
+            commands.append(f"loadamberparams {parameter.frcmod_path}")
+            loaded_frcmods.add(parameter.frcmod_path)
+        if previous is None:
+            commands.append(f"{variable} = loadmol2 {mol2_path}")
+            if variable != residue_name:
+                commands.append(f"{residue_name} = {variable}")
+        artifacts.append(
+            NonbondedIonArtifact(
+                ion=ion,
+                parameter=parameter,
+                mol2_path=mol2_path,
+                leap_variable=variable,
+            )
+        )
+    return NonbondedSiteResult(
+        site_id=site.config.id,
+        parameter_set=parameter_set,
+        ions=tuple(artifacts),
+        leap_commands=tuple(commands),
+    )
+
+
+def ion_frcmod_name(*, charge: int, water_model: str, parameter_set: str) -> str:
+    """Return the exact AmberTools Li/Merz frcmod filename."""
+
+    if charge not in {1, 2, 3, 4}:
+        raise NonbondedMetalError("Amber Li/Merz ion models support charges +1 through +4.")
+    water = water_model.lower()
+    if water not in {"tip3p", "opc"}:
+        raise NonbondedMetalError(
+            f"mdprep supports Li/Merz metal parameters only for configured TIP3P or OPC, not {water_model}."
+        )
+    family = _canonical_parameter_set(parameter_set)
+    suffix = {"12_6": "126", "12_6_4": "1264", "hfe": "hfe", "iod": "iod"}[family]
+    if water == "opc":
+        return f"frcmod.ionslm_{suffix}_opc"
+    if charge == 1:
+        if family in {"12_6", "hfe"}:
+            return "frcmod.ions1lm_126_tip3p"
+        if family == "iod":
+            return "frcmod.ions1lm_iod"
+        return "frcmod.ions1lm_1264_tip3p"
+    return f"frcmod.ions234lm_{suffix}_tip3p"
+
+
+def load_amber_ion_parameter(
+    *,
+    element: str,
+    charge: int,
+    water_model: str,
+    parameter_set: str,
+    amberhome: str | Path,
+) -> AmberIonParameter:
+    name = ion_frcmod_name(
+        charge=charge,
+        water_model=water_model,
+        parameter_set=parameter_set,
+    )
+    path = Path(amberhome) / "dat" / "leap" / "parm" / name
+    if not path.is_file():
+        raise NonbondedMetalError(f"Amber ion parameter file is missing: {path}")
+    atom_type = f"{element}{charge}+"
+    mass, radius, epsilon = _parse_frcmod_ion(path, atom_type)
+    return AmberIonParameter(
+        element=element,
+        charge=charge,
+        atom_type=atom_type,
+        mass=mass,
+        rmin_over_2_angstrom=radius,
+        epsilon_kcal_mol=epsilon,
+        parameter_set=_canonical_parameter_set(parameter_set),
+        water_model=water_model,
+        frcmod_name=name,
+        frcmod_path=path.resolve(),
+    )
+
+
+def resolve_amberhome(explicit: str | Path | None = None) -> Path:
+    candidates: list[Path] = []
+    if explicit is not None:
+        candidates.append(Path(explicit))
+    for variable in ("AMBERHOME", "CONDA_PREFIX"):
+        value = os.environ.get(variable)
+        if value:
+            candidates.append(Path(value))
+    tleap = shutil.which("tleap")
+    if tleap:
+        candidates.append(Path(tleap).resolve().parent.parent)
+    for candidate in candidates:
+        if (candidate / "dat" / "leap" / "parm").is_dir():
+            return candidate.resolve()
+    raise NonbondedMetalError(
+        "Could not locate AmberTools data. Set AMBERHOME or run mdprep in an AmberTools environment."
+    )
+
+
+def write_single_ion_mol2(
+    ion: ResolvedMetalIon,
+    parameter: AmberIonParameter,
+    path: str | Path,
+) -> None:
+    atom = ion.atom
+    residue = ion.residue.id.resname
+    text = (
+        "@<TRIPOS>MOLECULE\n"
+        f"{residue}\n"
+        "1 0 1 0 0\n"
+        "SMALL\n"
+        "USER_CHARGES\n"
+        "\n"
+        "@<TRIPOS>ATOM\n"
+        f"{1:7d} {atom.name:<8s} {atom.x:12.6f} {atom.y:12.6f} {atom.z:12.6f} "
+        f"{parameter.atom_type:<8s} {1:4d} {residue:<8s} {float(ion.charge):12.6f}\n"
+        "@<TRIPOS>BOND\n"
+        "@<TRIPOS>SUBSTRUCTURE\n"
+        f"{1:6d} {residue:<8s} {1:6d} GROUP             0 ****  ****    0 ROOT\n"
+    )
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(text, encoding="utf-8")
+
+
+def _parse_frcmod_ion(path: Path, atom_type: str) -> tuple[float, float, float]:
+    section = ""
+    mass: float | None = None
+    radius: float | None = None
+    epsilon: float | None = None
+    for raw in path.read_text(encoding="utf-8").splitlines():
+        stripped = raw.strip()
+        if stripped in {"MASS", "BOND", "ANGLE", "DIHE", "IMPROPER", "NONBON"}:
+            section = stripped
+            continue
+        fields = stripped.split()
+        if not fields or fields[0] != atom_type:
+            continue
+        try:
+            if section == "MASS":
+                mass = float(fields[1])
+            elif section == "NONBON":
+                radius = float(fields[1])
+                epsilon = float(fields[2])
+        except (IndexError, ValueError) as exc:
+            raise NonbondedMetalError(
+                f"Malformed {section} entry for {atom_type} in {path}."
+            ) from exc
+    if mass is None or radius is None or epsilon is None:
+        raise NonbondedMetalError(
+            f"Amber parameter set {path.name} has no complete MASS/NONBON entry for "
+            f"{atom_type}; choose a supported element, oxidation state, and parameter family."
+        )
+    return mass, radius, epsilon
+
+
+def _canonical_parameter_set(value: str) -> str:
+    return "12_6" if value == "cm" else value
+
+
+def _leap_variable(site: MetalSiteConfig, index: int, residue_name: str) -> str:
+    safe = "".join(character if character.isalnum() else "_" for character in site.id.upper())
+    safe = safe.strip("_") or "METAL"
+    if safe[0].isdigit():
+        safe = "M_" + safe
+    return f"{safe}_{index}_{residue_name}"