mdprep 0.2.0__py3-none-any.whl

mdprep/charges/esp_grid.py

@@ -0,0 +1,190 @@
+"""Deterministic layered Merz-Kollman ESP grid generation."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from math import cos, pi, sin, sqrt
+from pathlib import Path
+
+import numpy as np
+
+
+class EspGridError(ValueError):
+    """Raised when an ESP grid cannot be generated safely."""
+
+
+VDW_RADII = {
+    "H": 1.20,
+    "C": 1.70,
+    "N": 1.55,
+    "O": 1.52,
+    "S": 1.80,
+    "P": 1.80,
+    "F": 1.47,
+    "CL": 1.75,
+    "BR": 1.85,
+    "I": 1.98,
+    "FE": 2.00,
+    "ZN": 2.10,
+    "MG": 1.73,
+    "NA": 2.27,
+    "K": 2.75,
+    "CA": 2.31,
+}
+
+
+@dataclass(frozen=True)
+class EspGrid:
+    points: np.ndarray
+    atom_indices: list[int]
+    shell_scales: list[float]
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "point_count": int(len(self.points)),
+            "atom_indices": self.atom_indices,
+            "shell_scales": self.shell_scales,
+        }
+
+
+def generate_merz_kollman_grid(
+    *,
+    elements: list[str],
+    coordinates: np.ndarray,
+    vdw_scale_factors: list[float],
+    point_density_per_square_angstrom: float,
+    exclude_inside_vdw_scale: float,
+    max_points: int,
+) -> EspGrid:
+    coords = np.asarray(coordinates, dtype=float)
+    if coords.shape != (len(elements), 3):
+        raise EspGridError("Coordinate array shape does not match element list.")
+    if not elements:
+        raise EspGridError("Cannot generate an ESP grid for zero atoms.")
+    if not np.all(np.isfinite(coords)):
+        raise EspGridError("ESP-grid coordinates contain non-finite values.")
+    if not vdw_scale_factors or any(
+        not np.isfinite(scale) or scale <= 0 for scale in vdw_scale_factors
+    ):
+        raise EspGridError("ESP-grid vdW scale factors must be finite, positive, and non-empty.")
+    if not np.isfinite(point_density_per_square_angstrom) or point_density_per_square_angstrom <= 0:
+        raise EspGridError("ESP-grid surface-point density must be finite and positive.")
+    if not np.isfinite(exclude_inside_vdw_scale) or exclude_inside_vdw_scale <= 0:
+        raise EspGridError("ESP-grid exclusion scale must be finite and positive.")
+    if max_points < len(elements) + 1:
+        raise EspGridError("ESP-grid max_points is too small for the number of fitted atoms.")
+
+    points: list[np.ndarray] = []
+    atom_indices: list[int] = []
+    shell_scales: list[float] = []
+    radii = np.asarray([vdw_radius(element) for element in elements], dtype=float)
+    for atom_index, center in enumerate(coords):
+        for scale in vdw_scale_factors:
+            shell_radius = radii[atom_index] * scale
+            point_count = max(
+                6,
+                int(round(4.0 * pi * shell_radius * shell_radius * point_density_per_square_angstrom)),
+            )
+            unit_sphere = _fibonacci_sphere(point_count)
+            for unit_point in unit_sphere:
+                point = center + unit_point * shell_radius
+                if _inside_other_atom(
+                    point,
+                    coords,
+                    radii,
+                    parent_index=atom_index,
+                    exclude_scale=exclude_inside_vdw_scale,
+                ):
+                    continue
+                points.append(point)
+                atom_indices.append(atom_index)
+                shell_scales.append(scale)
+    if not points:
+        raise EspGridError("No ESP grid points survived vdW exclusion.")
+
+    deduped_points, deduped_atoms, deduped_scales = _dedupe(points, atom_indices, shell_scales)
+    if len(deduped_points) < len(elements) + 1:
+        raise EspGridError("Too few ESP grid points were generated for charge fitting.")
+    if len(deduped_points) > max_points:
+        raise EspGridError(
+            f"Merz-Kollman grid contains {len(deduped_points)} points, exceeding "
+            f"grid.max_points={max_points}; refusing to thin the RESP sampling grid."
+        )
+    return EspGrid(
+        points=np.asarray(deduped_points, dtype=float),
+        atom_indices=deduped_atoms,
+        shell_scales=deduped_scales,
+    )
+
+
+def vdw_radius(element: str) -> float:
+    key = element.strip().upper()
+    if key not in VDW_RADII:
+        raise EspGridError(f"No vdW radius is configured for element {element!r}.")
+    return VDW_RADII[key]
+
+
+def write_grid_xyz(grid: EspGrid, path: str | Path) -> None:
+    output = Path(path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    lines = [str(len(grid.points)), "mdprep ESP grid"]
+    for point in grid.points:
+        lines.append(f"X {point[0]:.8f} {point[1]:.8f} {point[2]:.8f}")
+    output.write_text("\n".join(lines) + "\n", encoding="utf-8")
+
+
+def read_grid_xyz(path: str | Path) -> np.ndarray:
+    lines = Path(path).read_text(encoding="utf-8").splitlines()
+    data = []
+    for line in lines[2:]:
+        fields = line.split()
+        if len(fields) == 4:
+            data.append([float(fields[1]), float(fields[2]), float(fields[3])])
+    return np.asarray(data, dtype=float)
+
+
+def _fibonacci_sphere(count: int) -> np.ndarray:
+    points = []
+    golden_angle = pi * (3.0 - sqrt(5.0))
+    for index in range(count):
+        y = 1.0 - (2.0 * index + 1.0) / count
+        radius = sqrt(max(0.0, 1.0 - y * y))
+        theta = golden_angle * index
+        points.append([cos(theta) * radius, y, sin(theta) * radius])
+    return np.asarray(points, dtype=float)
+
+
+def _inside_other_atom(
+    point: np.ndarray,
+    coords: np.ndarray,
+    radii: np.ndarray,
+    *,
+    parent_index: int,
+    exclude_scale: float,
+) -> bool:
+    for index, center in enumerate(coords):
+        if index == parent_index:
+            continue
+        if np.linalg.norm(point - center) < radii[index] * exclude_scale:
+            return True
+    return False
+
+
+def _dedupe(
+    points: list[np.ndarray],
+    atom_indices: list[int],
+    shell_scales: list[float],
+) -> tuple[list[np.ndarray], list[int], list[float]]:
+    seen: set[tuple[int, int, int]] = set()
+    deduped_points: list[np.ndarray] = []
+    deduped_atoms: list[int] = []
+    deduped_scales: list[float] = []
+    for point, atom_index, scale in zip(points, atom_indices, shell_scales, strict=True):
+        key = tuple(int(round(value * 10000.0)) for value in point)
+        if key in seen:
+            continue
+        seen.add(key)
+        deduped_points.append(point)
+        deduped_atoms.append(atom_index)
+        deduped_scales.append(scale)
+    return deduped_points, deduped_atoms, deduped_scales

mdprep/cli.py

@@ -0,0 +1,451 @@
+"""Typer command-line interface for mdprep."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from mdprep import __version__
+from mdprep.config.loader import load_manifest
+from mdprep.config.models import McpbParameterComparisonConfig
+from mdprep.metals.parameter_comparison import (
+    McpbParameterComparisonError,
+    compare_mcpb_parameter_files,
+)
+from mdprep.md.roe_brooks import RoeBrooksError, run_roe_brooks
+from mdprep.structure.inspect import InspectionSummary
+from mdprep.structure.normalize import StructureNormalizationError
+from mdprep.structure.pdb import PdbParseError, VALID_ALTLOC_POLICIES
+from mdprep.workflows.init import generate_starter_manifest
+from mdprep.workflows.inspect import inspect_structure
+from mdprep.workflows.prepare import PrepareWorkflowError, prepare_system
+from mdprep.workflows.selftest import run_selftest
+from mdprep.workflows.validate import validate_system
+
+
+app = typer.Typer(
+    name="mdprep",
+    help="Reproducible Amber MD preparation workflow manager.",
+    no_args_is_help=True,
+)
+console = Console()
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.print(f"mdprep {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def callback(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        callback=_version_callback,
+        is_eager=True,
+        help="Print the mdprep version and exit.",
+    ),
+) -> None:
+    return None
+
+
+@app.command("config-check")
+def config_check(
+    paths: list[Path] = typer.Argument(..., help="One or more YAML manifest paths."),
+) -> None:
+    """Validate one or more manifest files."""
+
+    table = Table(title="Manifest validation")
+    table.add_column("File")
+    table.add_column("Status")
+    table.add_column("Message")
+
+    failed = False
+    for path in paths:
+        try:
+            load_manifest(path)
+        except Exception as exc:
+            failed = True
+            table.add_row(str(path), "FAIL", str(exc))
+        else:
+            table.add_row(str(path), "PASS", "valid")
+
+    console.print(table)
+    if failed:
+        raise typer.Exit(1)
+
+
+@app.command("inspect")
+def inspect_command(
+    input_structure: Path = typer.Argument(..., help="Input PDB file."),
+    altloc_policy: str | None = typer.Option(
+        None,
+        "--altloc-policy",
+        help="Alternate-location policy: highest_occupancy, first, or fail.",
+    ),
+    disulfide_cutoff: float | None = typer.Option(
+        None,
+        "--disulfide-cutoff",
+        help="SG-SG distance cutoff for possible disulfides.",
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print machine-readable JSON."),
+    config: Path | None = typer.Option(
+        None,
+        "--config",
+        help="Manifest path to supply structure and disulfide inspection defaults.",
+    ),
+) -> None:
+    """Inspect an input structure."""
+
+    try:
+        config_altloc_policy = None
+        config_disulfide_cutoff = None
+        if config is not None:
+            manifest = load_manifest(config)
+            config_altloc_policy = manifest.structure.altloc_policy
+            config_disulfide_cutoff = manifest.disulfides.detection_cutoff_angstrom
+
+        selected_altloc_policy = altloc_policy or config_altloc_policy or "highest_occupancy"
+        selected_disulfide_cutoff = disulfide_cutoff or config_disulfide_cutoff or 2.2
+        if selected_altloc_policy not in VALID_ALTLOC_POLICIES:
+            raise ValueError(
+                f"Invalid altloc policy {selected_altloc_policy!r}; expected one of {sorted(VALID_ALTLOC_POLICIES)}"
+            )
+
+        summary = inspect_structure(
+            input_structure,
+            altloc_policy=selected_altloc_policy,  # type: ignore[arg-type]
+            disulfide_cutoff_angstrom=selected_disulfide_cutoff,
+        )
+        if json_output:
+            console.print(json.dumps(summary.to_dict(), indent=2, sort_keys=True))
+        else:
+            _render_inspection(summary)
+    except (FileNotFoundError, PdbParseError, ValueError) as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+
+
+@app.command("init")
+def init_command(
+    input_structure: Path = typer.Argument(..., help="Input PDB/mmCIF file."),
+    output: Path = typer.Option(Path("system.yaml"), "-o", "--output", help="Output YAML path."),
+    overwrite: bool = typer.Option(
+        False,
+        "--overwrite",
+        "--force",
+        help="Overwrite an existing output manifest.",
+    ),
+    forcefield: str = typer.Option("ff14SB", "--forcefield", help="Protein force field."),
+    water_model: str = typer.Option("TIP3P", "--water-model", help="Water model."),
+    ph: float = typer.Option(7.0, "--ph", help="Target pH for starter manifest defaults."),
+    protonation_method: str = typer.Option(
+        "manual_only",
+        "--protonation-method",
+        help="Initial protonation method: manual_only, propka, or propka_xtb_his.",
+    ),
+    output_dir: str | None = typer.Option(
+        None,
+        "--output-dir",
+        help="Preparation output directory. Defaults to prepared/<input stem>.",
+    ),
+    include_ligand_placeholders: bool = typer.Option(
+        False,
+        "--include-ligand-placeholders",
+        help="Add active placeholder ligand blocks for detected ligands. Review net charges before use.",
+    ),
+) -> None:
+    """Create an initial manifest from an input structure."""
+
+    if forcefield not in {"ff14SB", "ff19SB"}:
+        console.print("[red]Error:[/red] --forcefield must be ff14SB or ff19SB")
+        raise typer.Exit(1)
+    if water_model not in {"TIP3P", "OPC"}:
+        console.print("[red]Error:[/red] --water-model must be TIP3P or OPC")
+        raise typer.Exit(1)
+    if protonation_method not in {"manual_only", "propka", "propka_xtb_his"}:
+        console.print("[red]Error:[/red] --protonation-method must be manual_only, propka, or propka_xtb_his")
+        raise typer.Exit(1)
+    try:
+        manifest_path = generate_starter_manifest(
+            input_structure,
+            output_path=output,
+            overwrite=overwrite,
+            forcefield=forcefield,
+            water_model=water_model,
+            ph=ph,
+            output_dir=output_dir,
+            protonation_method=protonation_method,
+            include_ligand_placeholders=include_ligand_placeholders,
+        )
+    except (FileExistsError, FileNotFoundError, PdbParseError, ValueError) as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print(f"Wrote starter manifest: {manifest_path}")
+
+
+@app.command("prepare")
+def prepare_command(
+    manifest: Path = typer.Argument(..., help="YAML manifest path."),
+    stop_after: str | None = typer.Option(
+        None,
+        "--stop-after",
+        help=(
+            "Stop after a supported workflow stage: structure, protonation, refinement, "
+            "ligands, metals, tleap, or md."
+        ),
+    ),
+    overwrite: bool = typer.Option(False, "--overwrite", help="Overwrite mdprep-generated outputs."),
+    resume: bool = typer.Option(
+        False,
+        "--resume",
+        help=(
+            "Resume from a matching converged ASH refinement after an interrupted "
+            "downstream stage."
+        ),
+    ),
+    quiet: bool = typer.Option(False, "--quiet", help="Reduce command output."),
+) -> None:
+    """Prepare an Amber system from a manifest."""
+
+    try:
+        result = prepare_system(
+            manifest,
+            stop_after=stop_after,
+            overwrite=overwrite,
+            resume=resume,
+        )
+    except (
+        PrepareWorkflowError,
+        StructureNormalizationError,
+        FileExistsError,
+        FileNotFoundError,
+        PdbParseError,
+        ValueError,
+    ) as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    if not quiet:
+        console.print(f"Wrote output PDB: {result.output_path}")
+
+
+@app.command("validate")
+def validate_command(
+    prmtop: Path = typer.Argument(..., help="Amber topology file."),
+    inpcrd: Path = typer.Argument(..., help="Amber coordinate file."),
+) -> None:
+    """Validate a prepared Amber system."""
+
+    try:
+        validate_system(prmtop, inpcrd)
+    except ValueError as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print("Validation passed")
+
+
+@app.command("run-md")
+def run_md_command(
+    manifest_path: Path = typer.Argument(..., help="Manifest containing molecular_dynamics settings."),
+    prmtop: Path | None = typer.Option(
+        None,
+        "--prmtop",
+        help="Amber topology; defaults to <project.output_dir>/final/system.prmtop.",
+    ),
+    inpcrd: Path | None = typer.Option(
+        None,
+        "--inpcrd",
+        help="Amber coordinates; defaults to <project.output_dir>/final/system.inpcrd.",
+    ),
+    output_dir: Path | None = typer.Option(
+        None,
+        "--output-dir",
+        help="MD output directory; defaults to <project.output_dir>/md/roe_brooks_2020.",
+    ),
+) -> None:
+    """Run manifest-configured Roe--Brooks MD from an existing Amber system."""
+
+    try:
+        manifest = load_manifest(manifest_path, resolve_paths=True)
+        project_output = Path(manifest.project.output_dir)
+        result = run_roe_brooks(
+            prmtop_path=prmtop or project_output / "final" / "system.prmtop",
+            inpcrd_path=inpcrd or project_output / "final" / "system.inpcrd",
+            output_dir=(
+                output_dir
+                or project_output / "md" / "roe_brooks_2020"
+            ),
+            config=manifest.molecular_dynamics,
+        )
+    except (FileNotFoundError, RoeBrooksError, ValueError) as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    console.print(
+        f"MD completed on {result.platform}; final coordinates: {result.final_pdb}"
+    )
+
+
+@app.command("compare-mcpb")
+def compare_mcpb_command(
+    candidate_frcmod: Path = typer.Argument(
+        ..., help="Candidate MCPB.py-generated frcmod file."
+    ),
+    reference_frcmod: Path = typer.Argument(
+        ..., help="Selected reference MCPB.py-generated frcmod file."
+    ),
+    output_dir: Path = typer.Option(
+        Path("mcpb_parameter_comparison"),
+        "--output-dir",
+        help="Directory for JSON, CSV, and Markdown comparison reports.",
+    ),
+    candidate_label: str = typer.Option("xTB MCPB", "--candidate-label"),
+    reference_label: str = typer.Option("MCPB reference", "--reference-label"),
+    require_exact_term_set: bool = typer.Option(
+        True,
+        "--require-exact-term-set/--allow-term-set-difference",
+        help="Require candidate and reference to contain identical MCPB Seminario terms.",
+    ),
+    max_bond_relative_rmse: float | None = typer.Option(
+        None, "--max-bond-relative-rmse"
+    ),
+    max_angle_relative_rmse: float | None = typer.Option(
+        None, "--max-angle-relative-rmse"
+    ),
+    max_bond_distance_rmse: float | None = typer.Option(
+        None, "--max-bond-distance-rmse"
+    ),
+    max_angle_value_rmse: float | None = typer.Option(
+        None, "--max-angle-value-rmse"
+    ),
+    report_only: bool = typer.Option(
+        False,
+        "--report-only",
+        help="Write a failing report without returning a nonzero exit status.",
+    ),
+) -> None:
+    """Compare MCPB Seminario bond/angle terms against a selected reference."""
+
+    try:
+        config = McpbParameterComparisonConfig(
+            reference_frcmod=str(reference_frcmod),
+            candidate_label=candidate_label,
+            reference_label=reference_label,
+            require_exact_term_set=require_exact_term_set,
+            max_bond_force_constant_relative_rmse=max_bond_relative_rmse,
+            max_angle_force_constant_relative_rmse=max_angle_relative_rmse,
+            max_bond_equilibrium_distance_rmse_angstrom=max_bond_distance_rmse,
+            max_angle_equilibrium_value_rmse_degrees=max_angle_value_rmse,
+            fail_on_thresholds=not report_only,
+        )
+        result = compare_mcpb_parameter_files(
+            candidate_frcmod,
+            config=config,
+            output_dir=output_dir,
+        )
+    except (McpbParameterComparisonError, ValueError) as exc:
+        console.print(f"[red]Error:[/red] {exc}")
+        raise typer.Exit(1) from exc
+    status = {
+        "pass": "PASS",
+        "fail": "FAIL (report only)",
+        "report_only": "REPORT ONLY (no numeric acceptance thresholds)",
+    }[result.status]
+    console.print(f"MCPB parameter comparison: {status}")
+    console.print(f"Wrote report: {result.json_path}")
+
+
+@app.command("selftest")
+def selftest_command(
+    quick: bool = typer.Option(False, "--quick", help="Run package-level checks only."),
+) -> None:
+    """Run package self-tests that do not require external chemistry tools."""
+
+    summary = run_selftest(quick=quick, console=console)
+    if not summary.passed:
+        raise typer.Exit(1)
+
+
+def main() -> None:
+    app()
+
+
+def _render_inspection(summary: InspectionSummary) -> None:
+    data = summary.to_dict()
+    counts = data["counts"]
+    assert isinstance(counts, dict)
+
+    overview = Table(title="Structure summary")
+    overview.add_column("Field")
+    overview.add_column("Value")
+    overview.add_row("Path", str(data["path"]))
+    overview.add_row("Atoms", str(data["total_atoms"]))
+    overview.add_row("Residues", str(data["total_residues"]))
+    overview.add_row("MODEL records", str(data["model_count"]))
+    overview.add_row("Used MODEL", str(data["used_model"]))
+    overview.add_row("Protein residues", str(counts["protein_residues"]))
+    overview.add_row("Water residues", str(counts["water_residues"]))
+    overview.add_row("Heterogen residues", str(counts["heterogen_residues"]))
+    overview.add_row("Likely ligands/cofactors", str(counts["likely_ligands"]))
+    console.print(overview)
+
+    chains = Table(title="Chains")
+    chains.add_column("Chain ID")
+    chains.add_column("Display")
+    for chain in data["chains"]:
+        assert isinstance(chain, dict)
+        chains.add_row(str(chain["chain_id"]), str(chain["display"]))
+    console.print(chains)
+
+    _render_residue_table("Likely ligands/cofactors", summary.likely_ligands)
+    _render_residue_table("Histidines", summary.histidines)
+    _render_residue_table("Titratable residues", summary.titratable_residues)
+    _render_disulfide_table(summary)
+
+    if summary.structure.warnings:
+        warnings = Table(title="Warnings")
+        warnings.add_column("Message")
+        for warning in summary.structure.warnings:
+            warnings.add_row(warning)
+        console.print(warnings)
+
+
+def _render_residue_table(title: str, residues: list[object]) -> None:
+    table = Table(title=title)
+    table.add_column("Chain")
+    table.add_column("Resname")
+    table.add_column("Resid")
+    table.add_column("Icode")
+    table.add_column("Atoms")
+    for residue in residues:
+        residue_id = residue.id  # type: ignore[attr-defined]
+        table.add_row(
+            residue_id.chain_id or "<blank>",
+            residue_id.resname,
+            str(residue_id.resid),
+            residue_id.icode or "",
+            str(len(residue.atoms)),  # type: ignore[attr-defined]
+        )
+    console.print(table)
+
+
+def _render_disulfide_table(summary: InspectionSummary) -> None:
+    table = Table(title="Possible disulfides")
+    table.add_column("Residue A")
+    table.add_column("Residue B")
+    table.add_column("Distance (angstrom)")
+    for candidate in summary.possible_disulfides:
+        table.add_row(
+            candidate.a.display(),
+            candidate.b.display(),
+            f"{candidate.distance_angstrom:.3f}",
+        )
+    console.print(table)
+
+
+if __name__ == "__main__":
+    main()

mdprep/config/__init__.py

@@ -0,0 +1,9 @@
+"""Configuration models and loading helpers."""
+
+from __future__ import annotations
+
+from mdprep.config.loader import load_manifest
+from mdprep.config.models import ManifestConfig
+
+__all__ = ["ManifestConfig", "load_manifest"]
+