mdprep 0.2.0__py3-none-any.whl

mdprep/__init__.py

@@ -0,0 +1,7 @@
+"""mdprep package."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

mdprep/_selftest_data/basic_protein.yaml

@@ -0,0 +1,33 @@
+project:
+  name: selftest
+  input_structure: input.pdb
+  output_dir: prepared/selftest
+
+structure:
+  keep_crystal_waters: true
+  remove_unknown_heterogens: false
+
+protein:
+  forcefield: ff14SB
+  water_model: TIP3P
+
+protonation:
+  method: manual_only
+
+disulfides:
+  auto_detect: true
+  detection_cutoff_angstrom: 2.2
+  force: []
+  forbid: []
+
+ligands: []
+metals: []
+
+solvation:
+  enabled: true
+
+validation:
+  fail_on_missing_parameters: true
+
+molecular_dynamics:
+  enabled: false

mdprep/_selftest_data/ligand_sub.mol2

@@ -0,0 +1,11 @@
+@<TRIPOS>MOLECULE
+SUB
+ 2 1 0 0 0
+SMALL
+USER_CHARGES
+
+@<TRIPOS>ATOM
+      1 C1           5.0000     5.0000     5.0000 c3          1 SUB        0.100000
+      2 O1           6.0000     5.0000     5.0000 o           1 SUB       -0.100000
+@<TRIPOS>BOND
+     1    1    2 1

mdprep/ambertools/__init__.py

@@ -0,0 +1,2 @@
+"""AmberTools command wrappers."""
+

mdprep/ambertools/antechamber.py

@@ -0,0 +1,110 @@
+"""Antechamber wrapper for ligand AM1-BCC parameterization."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mdprep.ambertools.commands import AmberToolRun, AmberToolsError
+from mdprep.config.models import LigandConfig
+from mdprep.external.discovery import which_executable
+from mdprep.external.runner import run_command
+
+
+def build_antechamber_command(
+    *,
+    executable: str,
+    input_pdb: str | Path,
+    output_mol2: str | Path,
+    residue_name: str,
+    ligand: LigandConfig,
+) -> list[str]:
+    return [
+        executable,
+        "-i",
+        str(input_pdb),
+        "-fi",
+        "pdb",
+        "-o",
+        str(output_mol2),
+        "-fo",
+        "mol2",
+        "-rn",
+        residue_name,
+        "-nc",
+        str(ligand.net_charge),
+        "-m",
+        str(ligand.multiplicity),
+        "-c",
+        "bcc",
+        "-at",
+        ligand.atom_types,
+        "-an",
+        "n",
+        "-du",
+        "n",
+        "-seq",
+        "n",
+        "-s",
+        "2",
+    ]
+
+
+def run_antechamber(
+    *,
+    ligand: LigandConfig,
+    input_pdb: str | Path,
+    output_mol2: str | Path,
+    residue_name: str,
+    work_dir: str | Path,
+    executable: str = "antechamber",
+) -> AmberToolRun:
+    exe = _resolve_executable(executable)
+    work = Path(work_dir)
+    stdout_path = work / "antechamber_stdout.txt"
+    stderr_path = work / "antechamber_stderr.txt"
+    input_path = Path(input_pdb).resolve()
+    output = Path(output_mol2).resolve()
+    command = build_antechamber_command(
+        executable=exe,
+        input_pdb=input_path,
+        output_mol2=output,
+        residue_name=residue_name,
+        ligand=ligand,
+    )
+    result = run_command(command, cwd=work)
+    stdout_path.write_text(result.stdout, encoding="utf-8")
+    stderr_path.write_text(result.stderr, encoding="utf-8")
+    if result.returncode != 0:
+        raise AmberToolsError(
+            "\n".join(
+                [
+                    f"antechamber failed with exit code {result.returncode}.",
+                    f"Command: {' '.join(result.command)}",
+                    f"See {stdout_path} and {stderr_path}.",
+                    f"stdout tail:\n{_tail(result.stdout)}",
+                    f"stderr tail:\n{_tail(result.stderr)}",
+                ]
+            )
+        )
+    if not output.exists():
+        raise AmberToolsError(f"antechamber did not produce expected mol2 file: {output}")
+    return AmberToolRun(
+        command_result=result,
+        stdout_path=stdout_path,
+        stderr_path=stderr_path,
+        output_path=output,
+    )
+
+
+def _resolve_executable(name: str) -> str:
+    found = which_executable(name)
+    if found:
+        return found
+    raise AmberToolsError(f"AmberTools executable not found: {name}")
+
+
+def _tail(text: str, *, lines: int = 20) -> str:
+    stripped = text.strip()
+    if not stripped:
+        return "<empty>"
+    return "\n".join(stripped.splitlines()[-lines:])

mdprep/ambertools/commands.py

@@ -0,0 +1,33 @@
+"""Shared AmberTools command result models."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mdprep.external.runner import CommandResult
+
+
+class AmberToolsError(RuntimeError):
+    """Raised when an AmberTools command is unavailable or fails."""
+
+
+@dataclass(frozen=True)
+class AmberToolRun:
+    command_result: CommandResult
+    stdout_path: Path
+    stderr_path: Path
+    output_path: Path
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "command": list(self.command_result.command),
+            "cwd": self.command_result.cwd,
+            "returncode": self.command_result.returncode,
+            "stdout": self.command_result.stdout,
+            "stderr": self.command_result.stderr,
+            "runtime_seconds": self.command_result.runtime_seconds,
+            "stdout_path": str(self.stdout_path),
+            "stderr_path": str(self.stderr_path),
+            "output_path": str(self.output_path),
+        }

mdprep/ambertools/mol2.py

@@ -0,0 +1,415 @@
+"""Focused Tripos mol2 parser, writer, and ligand validation."""
+
+from __future__ import annotations
+
+import csv
+import json
+from dataclasses import dataclass, replace
+from math import dist
+from pathlib import Path
+
+from mdprep.config.models import LigandConfig
+from mdprep.structure.models import AtomRecord
+from mdprep.structure.pdb import PERIODIC_ELEMENTS, infer_element
+
+
+class Mol2Error(ValueError):
+    """Raised when a mol2 file cannot be parsed or validated safely."""
+
+
+@dataclass(frozen=True)
+class Mol2Atom:
+    atom_id: int
+    name: str
+    x: float
+    y: float
+    z: float
+    atom_type: str
+    subst_id: int
+    subst_name: str
+    charge: float
+
+
+@dataclass
+class Mol2File:
+    path: Path
+    lines: list[str]
+    molecule_name: str | None
+    atoms: list[Mol2Atom]
+    atom_line_indices: list[int]
+
+    @property
+    def total_charge(self) -> float:
+        return sum(atom.charge for atom in self.atoms)
+
+
+@dataclass(frozen=True)
+class Mol2ValidationResult:
+    final_mol2_path: Path
+    charges_csv_path: Path
+    validation_json_path: Path
+    charge_sum_before_correction: float
+    charge_correction_applied: float
+    charge_sum_final: float
+    coordinate_max_deviation: float
+    atom_names_preserved: bool
+    warnings: list[str]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "final_mol2_path": str(self.final_mol2_path),
+            "charges_csv_path": str(self.charges_csv_path),
+            "validation_json_path": str(self.validation_json_path),
+            "charge_sum_before_correction": self.charge_sum_before_correction,
+            "charge_correction_applied": self.charge_correction_applied,
+            "charge_sum_final": self.charge_sum_final,
+            "coordinate_max_deviation": self.coordinate_max_deviation,
+            "atom_names_preserved": self.atom_names_preserved,
+            "warnings": self.warnings,
+        }
+
+
+def read_mol2(path: str | Path) -> Mol2File:
+    mol2_path = Path(path)
+    lines = mol2_path.read_text(encoding="utf-8").splitlines()
+    atom_start = _marker_index(lines, "@<TRIPOS>ATOM")
+    if atom_start is None:
+        raise Mol2Error(f"mol2 file is missing @<TRIPOS>ATOM section: {mol2_path}")
+    atom_end = next(
+        (index for index in range(atom_start + 1, len(lines)) if lines[index].startswith("@<TRIPOS>")),
+        len(lines),
+    )
+    atoms: list[Mol2Atom] = []
+    atom_line_indices: list[int] = []
+    for index in range(atom_start + 1, atom_end):
+        line = lines[index]
+        if not line.strip():
+            continue
+        atoms.append(_parse_atom_line(line, mol2_path))
+        atom_line_indices.append(index)
+    if not atoms:
+        raise Mol2Error(f"mol2 file has no atom records: {mol2_path}")
+    molecule_name = _molecule_name(lines)
+    return Mol2File(
+        path=mol2_path,
+        lines=lines,
+        molecule_name=molecule_name,
+        atoms=atoms,
+        atom_line_indices=atom_line_indices,
+    )
+
+
+def write_mol2(mol2: Mol2File, path: str | Path) -> None:
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    lines = list(mol2.lines)
+    for atom, line_index in zip(mol2.atoms, mol2.atom_line_indices, strict=True):
+        lines[line_index] = _format_atom(atom)
+    output.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def write_mol2_with_charges(
+    mol2_path: str | Path,
+    charges: list[float],
+    output_path: str | Path,
+) -> None:
+    mol2 = read_mol2(mol2_path)
+    if len(charges) != len(mol2.atoms):
+        raise Mol2Error(
+            f"Charge count {len(charges)} does not match mol2 atom count {len(mol2.atoms)}."
+        )
+    mol2.atoms = [
+        replace(atom, charge=float(charge))
+        for atom, charge in zip(mol2.atoms, charges, strict=True)
+    ]
+    write_mol2(mol2, output_path)
+
+
+def validate_and_write_final_mol2(
+    *,
+    mol2_path: str | Path,
+    extracted_atoms: list[AtomRecord],
+    ligand: LigandConfig,
+    final_mol2_path: str | Path,
+    charges_csv_path: str | Path,
+    validation_json_path: str | Path,
+) -> Mol2ValidationResult:
+    mol2 = read_mol2(mol2_path)
+    warnings: list[str] = []
+    if len(mol2.atoms) != len(extracted_atoms):
+        raise Mol2Error(
+            f"Ligand {ligand.id} atom-count mismatch: extracted PDB has "
+            f"{len(extracted_atoms)} atoms but mol2 has {len(mol2.atoms)} atoms."
+        )
+    _validate_element_order(mol2.atoms, extracted_atoms, ligand.id)
+    atoms = list(mol2.atoms)
+    if ligand.preserve_atom_names:
+        atoms = [
+            replace(mol2_atom, name=pdb_atom.name)
+            for mol2_atom, pdb_atom in zip(atoms, extracted_atoms, strict=True)
+        ]
+    atom_names_preserved = [atom.name for atom in atoms] == [atom.name for atom in extracted_atoms]
+    if ligand.preserve_atom_names and not ligand.allow_atom_renaming and not atom_names_preserved:
+        raise Mol2Error(f"Ligand {ligand.id} atom names could not be preserved in final mol2.")
+
+    coordinate_max_deviation = _max_coordinate_deviation(atoms, extracted_atoms)
+    if (
+        ligand.preserve_coordinates
+        and not ligand.allow_coordinate_changes
+        and coordinate_max_deviation > 0.05
+    ):
+        raise Mol2Error(
+            f"Ligand {ligand.id} mol2 coordinates deviate from extracted PDB by "
+            f"{coordinate_max_deviation:.3f} A; maximum allowed is 0.050 A."
+        )
+
+    charge_before = sum(atom.charge for atom in atoms)
+    residual = ligand.net_charge - charge_before
+    correction = 0.0
+    if abs(residual) > 0.01 + 1.0e-9:
+        raise Mol2Error(
+            f"Ligand {ligand.id} mol2 charge sum {charge_before:.6f} differs from "
+            f"target charge {ligand.net_charge} by {residual:.6f} e."
+        )
+    if abs(residual) > 1.0e-9:
+        target_index = max(range(len(atoms)), key=lambda index: abs(atoms[index].charge))
+        atoms[target_index] = replace(atoms[target_index], charge=atoms[target_index].charge + residual)
+        correction = residual
+        warnings.append(
+            f"Applied charge residual {residual:.6f} e to atom {atoms[target_index].name}."
+        )
+
+    mol2.atoms = atoms
+    final_path = Path(final_mol2_path)
+    write_mol2(mol2, final_path)
+    charges_path = Path(charges_csv_path)
+    _write_charges_csv(atoms, charges_path)
+    result = Mol2ValidationResult(
+        final_mol2_path=final_path,
+        charges_csv_path=charges_path,
+        validation_json_path=Path(validation_json_path),
+        charge_sum_before_correction=charge_before,
+        charge_correction_applied=correction,
+        charge_sum_final=sum(atom.charge for atom in atoms),
+        coordinate_max_deviation=coordinate_max_deviation,
+        atom_names_preserved=atom_names_preserved,
+        warnings=warnings,
+    )
+    result.validation_json_path.parent.mkdir(parents=True, exist_ok=True)
+    result.validation_json_path.write_text(
+        json.dumps(result.to_dict(), indent=2, sort_keys=True) + "\n",
+        encoding="utf-8",
+    )
+    return result
+
+
+def _parse_atom_line(line: str, path: Path) -> Mol2Atom:
+    fields = line.split()
+    if len(fields) < 9:
+        raise Mol2Error(f"Invalid mol2 atom record in {path}: {line!r}")
+    try:
+        return Mol2Atom(
+            atom_id=int(fields[0]),
+            name=fields[1],
+            x=float(fields[2]),
+            y=float(fields[3]),
+            z=float(fields[4]),
+            atom_type=fields[5],
+            subst_id=int(fields[6]),
+            subst_name=fields[7],
+            charge=float(fields[8]),
+        )
+    except ValueError as exc:
+        raise Mol2Error(f"Invalid mol2 atom record in {path}: {line!r}") from exc
+
+
+def _format_atom(atom: Mol2Atom) -> str:
+    return (
+        f"{atom.atom_id:7d} {atom.name:<8} "
+        f"{atom.x:10.4f} {atom.y:10.4f} {atom.z:10.4f} "
+        f"{atom.atom_type:<8} {atom.subst_id:4d} {atom.subst_name:<8} {atom.charge:10.6f}"
+    )
+
+
+def _marker_index(lines: list[str], marker: str) -> int | None:
+    for index, line in enumerate(lines):
+        if line.strip() == marker:
+            return index
+    return None
+
+
+def _molecule_name(lines: list[str]) -> str | None:
+    index = _marker_index(lines, "@<TRIPOS>MOLECULE")
+    if index is None:
+        return None
+    for line in lines[index + 1 :]:
+        stripped = line.strip()
+        if stripped:
+            return stripped
+    return None
+
+
+def _validate_element_order(mol2_atoms: list[Mol2Atom], pdb_atoms: list[AtomRecord], ligand_id: str) -> None:
+    mol2_elements = [_element_from_mol2(atom) for atom in mol2_atoms]
+    pdb_elements = [_element_from_pdb_atom(atom) for atom in pdb_atoms]
+    if mol2_elements != pdb_elements:
+        raise Mol2Error(
+            f"Ligand {ligand_id} element-order mismatch between extracted PDB and mol2: "
+            f"{pdb_elements} != {mol2_elements}."
+        )
+
+
+def _element_from_mol2(atom: Mol2Atom) -> str:
+    return _element_from_atom_type(atom.atom_type, fallback_name=atom.name)
+
+
+GAFF_LIKE_ATOM_TYPE_ELEMENTS = {
+    **{
+        atom_type: "C"
+        for atom_type in {
+            "c",
+            "c1",
+            "c2",
+            "c3",
+            "c5",
+            "c6",
+            "ca",
+            "cc",
+            "cd",
+            "ce",
+            "cf",
+            "cg",
+            "ch",
+            "cp",
+            "cq",
+            "cu",
+            "cv",
+            "cx",
+            "cy",
+            "cz",
+        }
+    },
+    **{
+        atom_type: "H"
+        for atom_type in {
+            "h",
+            "h1",
+            "h2",
+            "h3",
+            "h4",
+            "h5",
+            "ha",
+            "hc",
+            "hn",
+            "ho",
+            "hp",
+            "hs",
+            "hw",
+            "hx",
+        }
+    },
+    **{
+        atom_type: "N"
+        for atom_type in {
+            "n",
+            "n1",
+            "n2",
+            "n3",
+            "n4",
+            "na",
+            "nb",
+            "nc",
+            "nd",
+            "ne",
+            "nf",
+            "nh",
+            "ni",
+            "nj",
+            "nk",
+            "nl",
+            "nm",
+            "nn",
+            "no",
+            "np",
+            "nq",
+            "ns",
+            "nt",
+            "nx",
+            "ny",
+            "nz",
+        }
+    },
+    **{atom_type: "O" for atom_type in {"o", "oh", "os", "ow"}},
+    **{
+        atom_type: "P"
+        for atom_type in {"p", "p2", "p3", "p4", "p5", "pb", "pc", "pd", "pe", "pf", "px", "py"}
+    },
+    **{atom_type: "S" for atom_type in {"s", "s2", "s4", "s6", "sh", "ss", "sp", "sx", "sy"}},
+}
+
+LOWERCASE_ELEMENT_ATOM_TYPES = {
+    "cl": "CL",
+    "br": "BR",
+    "f": "F",
+    "i": "I",
+}
+
+
+def _element_from_atom_type(atom_type: str, *, fallback_name: str = "") -> str:
+    token = atom_type.split(".", 1)[0].strip()
+    if not token:
+        return _element_from_atom_name(fallback_name)
+    lower = token.lower()
+    if lower in LOWERCASE_ELEMENT_ATOM_TYPES:
+        return LOWERCASE_ELEMENT_ATOM_TYPES[lower]
+    if token.islower():
+        if lower in GAFF_LIKE_ATOM_TYPE_ELEMENTS:
+            return GAFF_LIKE_ATOM_TYPE_ELEMENTS[lower]
+        if lower.upper() in PERIODIC_ELEMENTS:
+            return lower.upper()
+    return _element_from_atom_name(token)
+
+
+def _element_from_pdb_atom(atom: AtomRecord) -> str:
+    if atom.element:
+        return atom.element.upper()
+    atom_field = atom.original_line[12:16] if len(atom.original_line) >= 16 else None
+    inferred = infer_element(
+        atom.name,
+        resname=atom.resname,
+        record_name=atom.record_name,
+        atom_field=atom_field,
+    )
+    return (inferred or "").upper()
+
+
+def _element_from_atom_name(name: str) -> str:
+    stripped = name.strip()
+    while stripped and stripped[0].isdigit():
+        stripped = stripped[1:]
+    upper = stripped.upper()
+    if len(upper) >= 2 and upper[:2] in PERIODIC_ELEMENTS:
+        return upper[:2]
+    if not upper:
+        return ""
+    if upper[0] in PERIODIC_ELEMENTS:
+        return upper[0]
+    return upper[0]
+
+
+def _max_coordinate_deviation(mol2_atoms: list[Mol2Atom], pdb_atoms: list[AtomRecord]) -> float:
+    if not mol2_atoms:
+        return 0.0
+    return max(
+        dist((mol2.x, mol2.y, mol2.z), (pdb.x, pdb.y, pdb.z))
+        for mol2, pdb in zip(mol2_atoms, pdb_atoms, strict=True)
+    )
+
+
+def _write_charges_csv(atoms: list[Mol2Atom], path: Path) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", encoding="utf-8", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=["atom_id", "atom_name", "charge"])
+        writer.writeheader()
+        for atom in atoms:
+            writer.writerow({"atom_id": atom.atom_id, "atom_name": atom.name, "charge": atom.charge})

mdprep/ambertools/parmchk2.py

@@ -0,0 +1,89 @@
+"""parmchk2 wrapper for ligand frcmod generation."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mdprep.ambertools.commands import AmberToolRun, AmberToolsError
+from mdprep.config.models import LigandConfig
+from mdprep.external.discovery import which_executable
+from mdprep.external.runner import run_command
+
+
+def build_parmchk2_command(
+    *,
+    executable: str,
+    input_mol2: str | Path,
+    output_frcmod: str | Path,
+    ligand: LigandConfig,
+) -> list[str]:
+    return [
+        executable,
+        "-i",
+        str(input_mol2),
+        "-f",
+        "mol2",
+        "-o",
+        str(output_frcmod),
+        "-s",
+        ligand.atom_types,
+    ]
+
+
+def run_parmchk2(
+    *,
+    ligand: LigandConfig,
+    input_mol2: str | Path,
+    output_frcmod: str | Path,
+    work_dir: str | Path,
+    executable: str = "parmchk2",
+) -> AmberToolRun:
+    exe = _resolve_executable(executable)
+    work = Path(work_dir)
+    stdout_path = work / "parmchk2_stdout.txt"
+    stderr_path = work / "parmchk2_stderr.txt"
+    input_path = Path(input_mol2).resolve()
+    output = Path(output_frcmod).resolve()
+    command = build_parmchk2_command(
+        executable=exe,
+        input_mol2=input_path,
+        output_frcmod=output,
+        ligand=ligand,
+    )
+    result = run_command(command, cwd=work)
+    stdout_path.write_text(result.stdout, encoding="utf-8")
+    stderr_path.write_text(result.stderr, encoding="utf-8")
+    if result.returncode != 0:
+        raise AmberToolsError(
+            "\n".join(
+                [
+                    f"parmchk2 failed with exit code {result.returncode}.",
+                    f"Command: {' '.join(result.command)}",
+                    f"See {stdout_path} and {stderr_path}.",
+                    f"stdout tail:\n{_tail(result.stdout)}",
+                    f"stderr tail:\n{_tail(result.stderr)}",
+                ]
+            )
+        )
+    if not output.exists():
+        raise AmberToolsError(f"parmchk2 did not produce expected frcmod file: {output}")
+    return AmberToolRun(
+        command_result=result,
+        stdout_path=stdout_path,
+        stderr_path=stderr_path,
+        output_path=output,
+    )
+
+
+def _resolve_executable(name: str) -> str:
+    found = which_executable(name)
+    if found:
+        return found
+    raise AmberToolsError(f"AmberTools executable not found: {name}")
+
+
+def _tail(text: str, *, lines: int = 20) -> str:
+    stripped = text.strip()
+    if not stripped:
+        return "<empty>"
+    return "\n".join(stripped.splitlines()[-lines:])