pystarc 1.1.0__py3-none-any.whl

pystarc/__init__.py

@@ -0,0 +1,9 @@
+"""
+PySTARC - Python Simulation Toolkit for Association Rate Constants
+"""
+
+__version__ = "1.1.0"
+__author__ = "Anupam Anand Ojha"
+__license__ = "MIT"
+
+from pystarc.global_defs.constants import *

pystarc/analysis/convergence.py

@@ -0,0 +1,182 @@
+"""
+Convergence analysis for Brownian Dynamics simulations
+======================================================
+
+Physical Background
+-------------------
+BD trajectories are independent Bernoulli trials. Each trajectory
+starts from a fresh random position on the b-surface with an
+independent random number seed, and terminates by either reacting
+(success, probability P_rxn) or escaping (failure, probability
+1 - P_rxn).
+
+Because the trials are independent and identically distributed
+(i.i.d.), the standard error of the mean is exact.
+
+    SE(P_rxn) = √[P_rxn × (1 - P_rxn) / N]
+
+Convergence criterion
+---------------------
+The relative standard error (RSE = SE / P_rxn) directly quantifies
+the precision of k_on.
+
+    RSE = √[(1 - P_rxn) / (N × P_rxn)]
+
+Since RSE ∝ 1/√N, the number of trajectories needed for a target
+precision is given by
+
+    N_needed = (1 - P_rxn) / (P_rxn × RSE_target²)
+
+
+
+Wilson score confidence interval
+--------------------------------
+The 95% CI on P_rxn is computed using the Wilson score interval
+
+    P ∈ [p̂ + z²/2n ± z√(p̂(1-p̂)/n + z²/4n²)] / (1 + z²/n)
+
+This is preferred over the normal approximation (p̂ ± 2σ) because
+it provides guaranteed coverage even when P_rxn << 0.05 or N is
+small.  The normal approximation gives negative lower bounds for
+small P_rxn, which is unphysical.
+"""
+
+from typing import Optional
+import math
+import json
+import os
+
+
+def analyse_convergence(
+    n_reacted: int,
+    n_escaped: int,
+    k_b: float,
+    tol: float = 0.05,
+    conv_factor: float = 6.022e8,
+    work_dir: str = ".",
+) -> dict:
+    """
+    Run convergence analysis on completed BD simulation.
+
+    Parameters
+    ----------
+    n_reacted : int
+        Total trajectories that reacted.
+    n_escaped : int
+        Total trajectories that escaped.
+    k_b : float
+        Encounter rate constant (A^3/ps).
+    tol : float
+        Relative SE threshold for convergence (default 0.05 = 5%).
+    conv_factor : float
+        Unit conversion A^3/ps -> M-1 s-1.
+    work_dir : str
+        Directory to save convergence report.
+
+    Returns
+    -------
+    dict with convergence results.
+    """
+    N = n_reacted + n_escaped
+    if N == 0:
+        return {"converged": False, "reason": "no completed trajectories"}
+    P = n_reacted / N
+    k_on = conv_factor * k_b * P
+    # SE and relative SE
+    if P > 0 and P < 1:
+        SE = math.sqrt(P * (1 - P) / N)
+        relative_SE = SE / P
+    elif P == 0:
+        SE = 0.0
+        relative_SE = float("inf")
+    else:
+        SE = 0.0
+        relative_SE = 0.0
+    SE_kon = conv_factor * k_b * SE
+    # Wilson 95% CI
+    z = 1.96
+    denom = 1 + z**2 / N
+    centre = (P + z**2 / (2 * N)) / denom
+    spread = z * math.sqrt(P * (1 - P) / N + z**2 / (4 * N**2)) / denom
+    wilson_lo = max(0.0, centre - spread)
+    wilson_hi = min(1.0, centre + spread)
+    wilson_lo_kon = conv_factor * k_b * wilson_lo
+    wilson_hi_kon = conv_factor * k_b * wilson_hi
+    # Convergence verdict
+    converged = relative_SE < tol if P > 0 else False
+    # N needed for target tolerances
+    targets = {}
+    if 0 < P < 1:
+        for target_tol in [0.10, 0.05, 0.01]:
+            n_needed = int(math.ceil((1 - P) / (P * target_tol**2)))
+            targets[f"{int(target_tol*100)}%"] = n_needed
+    result = {
+        "N": N,
+        "n_reacted": n_reacted,
+        "n_escaped": n_escaped,
+        "P_rxn": P,
+        "SE": SE,
+        "relative_SE": relative_SE,
+        "relative_SE_pct": relative_SE * 100 if P > 0 else float("inf"),
+        "k_on": k_on,
+        "SE_kon": SE_kon,
+        "wilson_CI": [wilson_lo_kon, wilson_hi_kon],
+        "wilson_CI_P": [wilson_lo, wilson_hi],
+        "converged": converged,
+        "tol": tol,
+        "tol_pct": tol * 100,
+        "N_needed": targets,
+    }
+    return result
+
+
+def print_convergence(result: dict) -> str:
+    """Print convergence analysis to terminal and return as string."""
+    lines = []
+    lines.append("")
+    lines.append("  Convergence analysis")
+    if "N" not in result:
+        lines.append(f"  {result.get('reason', 'no data')}")
+        text = "\n".join(lines)
+        print(text)
+        return text
+    lines.append(f"  N completed      = {result['N']:,}")
+    lines.append(f"  P_rxn            = {result['P_rxn']:.6f}")
+    lines.append(f"  SE(P_rxn)        = {result['SE']:.6f}")
+    if result["P_rxn"] > 0:
+        lines.append(
+            f"  Relative SE      = {result['relative_SE_pct']:.2f}%"
+            f"     - k_on known to ±{result['relative_SE_pct']:.2f}%"
+        )
+    else:
+        lines.append(f"  Relative SE      = inf (P_rxn = 0, no reactions)")
+    lines.append(
+        f"  Wilson 95% CI    = [{result['wilson_CI'][0]:.4e}, "
+        f"{result['wilson_CI'][1]:.4e}] M⁻¹s⁻¹"
+    )
+    tol_pct = result["tol_pct"]
+    if result["converged"]:
+        lines.append(
+            f"  Converged (relative SE {result['relative_SE_pct']:.2f}% < {tol_pct:.0f}% threshold)"
+        )
+    else:
+        lines.append(
+            f"  Not converged (relative SE {result['relative_SE_pct']:.2f}% > {tol_pct:.0f}% threshold)"
+        )
+    if result["N_needed"]:
+        lines.append(f"  Trajectories needed")
+        for label, n in result["N_needed"].items():
+            status = "done" if result["N"] >= n else "need more"
+            lines.append(f"    For ±{label} relative SE: {n:,} ({status})")
+    text = "\n".join(lines)
+    print(text)
+    return text
+
+
+def save_convergence(result: dict, work_dir: str = ".") -> None:
+    import json, os
+
+    path = os.path.join(work_dir, "convergence.json")
+    with open(path, "w") as f:
+        json.dump(result, f, indent=2, default=str)
+    print(f"  Convergence saved -> {path}")

pystarc/aux/aux_tools.py

@@ -0,0 +1,151 @@
+"""
+Auxiliary preprocessing tools for PySTARC.
+
+"""
+
+from __future__ import annotations
+from pystarc.structures.molecules import Atom, Molecule, BoundingBox
+from pystarc.global_defs.constants import BJERRUM_LENGTH
+from typing import List, Tuple, Optional, Dict
+from pystarc.global_defs.constants import PI
+import numpy as np
+import math
+
+
+# bounding_box
+def bounding_box(mol: Molecule, padding: float = 5.0) -> BoundingBox:
+    """
+    Compute axis-aligned bounding box of a molecule with optional padding.
+    """
+    return BoundingBox.from_molecule(mol, padding=padding)
+
+
+# surface_spheres
+def surface_spheres(
+    mol: Molecule, probe_radius: float = 1.4, n_points: int = 92
+) -> List[np.ndarray]:
+    """
+    Generate surface probe positions using a Fibonacci sphere around each atom.
+    Returns list of (x,y,z) probe positions on the molecular surface.
+    """
+    positions = []
+    golden = (1 + math.sqrt(5)) / 2
+    for atom in mol.atoms:
+        r = atom.radius + probe_radius
+        c = atom.position
+        for i in range(n_points):
+            theta = math.acos(1 - 2 * (i + 0.5) / n_points)
+            phi = 2 * PI * i / golden
+            x = c[0] + r * math.sin(theta) * math.cos(phi)
+            y = c[1] + r * math.sin(theta) * math.sin(phi)
+            z = c[2] + r * math.cos(theta)
+            # Check not inside any other atom
+            p = np.array([x, y, z])
+            buried = any(
+                np.linalg.norm(p - a.position) < a.radius + probe_radius
+                for a in mol.atoms
+                if a is not atom
+            )
+            if not buried:
+                positions.append(p)
+    return positions
+
+
+# lumped_charges
+def lumped_charges(
+    mol: Molecule, grid_spacing: float = 2.0
+) -> List[Tuple[np.ndarray, float]]:
+    """
+    Coarse-grain atomic charges onto a regular grid by nearest-grid-point.
+    Returns list of (position, charge) tuples for non-zero grid points.
+    """
+    if not mol.atoms:
+        return []
+    bb = bounding_box(mol, padding=grid_spacing)
+    # Build grid
+    xs = np.arange(bb.xmin, bb.xmax + grid_spacing, grid_spacing)
+    ys = np.arange(bb.ymin, bb.ymax + grid_spacing, grid_spacing)
+    zs = np.arange(bb.zmin, bb.zmax + grid_spacing, grid_spacing)
+    grid: Dict[Tuple[int, int, int], float] = {}
+    for atom in mol.atoms:
+        if atom.charge == 0.0:
+            continue
+        ix = int(round((atom.x - bb.xmin) / grid_spacing))
+        iy = int(round((atom.y - bb.ymin) / grid_spacing))
+        iz = int(round((atom.z - bb.zmin) / grid_spacing))
+        key = (ix, iy, iz)
+        grid[key] = grid.get(key, 0.0) + atom.charge
+    result = []
+    for (ix, iy, iz), q in grid.items():
+        if abs(q) > 1e-8:
+            pos = np.array(
+                [
+                    bb.xmin + ix * grid_spacing,
+                    bb.ymin + iy * grid_spacing,
+                    bb.zmin + iz * grid_spacing,
+                ]
+            )
+            result.append((pos, q))
+    return result
+
+
+# electrostatic_center
+def electrostatic_center(mol: Molecule) -> np.ndarray:
+    """
+    Charge-weighted center of a molecule.
+    Falls back to geometric centroid if total charge is zero.
+    """
+    total_q = sum(abs(a.charge) for a in mol.atoms)
+    if total_q < 1e-10:
+        return mol.centroid()
+    pos = mol.positions_array()
+    charges = np.abs(mol.charges_array())
+    return (pos * charges[:, None]).sum(axis=0) / total_q
+
+
+# hydrodynamic_radius
+def hydrodynamic_radius_from_rg(mol: Molecule) -> float:
+    """
+    Approximate hydrodynamic radius from radius of gyration.
+    r_h ≈ 0.77 × r_g  (empirical for globular proteins).
+    """
+    return 0.77 * mol.radius_of_gyration()
+
+
+def hydrodynamic_radius_from_surface(mol: Molecule) -> float:
+    """
+    Approximate hydrodynamic radius as bounding radius of the molecule.
+    """
+    return mol.bounding_radius()
+
+
+# contact_distances
+def contact_distances(
+    mol1: Molecule, mol2: Molecule, cutoff: float = 8.0
+) -> List[Tuple[int, int, float]]:
+    """
+    Return all atom pairs (i, j, dist) within cutoff Å.
+    Used to auto-generate reaction contacts.
+    """
+    pairs = []
+    for i, a1 in enumerate(mol1.atoms):
+        for j, a2 in enumerate(mol2.atoms):
+            d = a1.distance_to(a2)
+            if d <= cutoff:
+                pairs.append((i, j, d))
+    pairs.sort(key=lambda t: t[2])
+    return pairs
+
+
+# born_integral
+def born_integral(
+    charge: float, radius: float, eps_in: float = 4.0, eps_out: float = 78.54
+) -> float:
+    """
+    Born solvation energy of a sphere:
+    ΔG_Born = -(q²/8π ε₀) × (1/ε_in - 1/ε_out) / r   [kBT]
+    Returns energy in kBT (using Bjerrum length scale).
+    """
+    if radius < 1e-10:
+        return 0.0
+    return -(charge**2 * BJERRUM_LENGTH / (2 * radius)) * (1.0 / eps_in - 1.0 / eps_out)

pystarc/cli/main.py

@@ -0,0 +1,151 @@
+"""
+Command-line interface for PySTARC.
+"""
+
+from __future__ import annotations
+from pystarc.simulation.nam_simulator import NAMSimulator, NAMParameters
+from pystarc.hydrodynamics.rotne_prager import MobilityTensor
+from pystarc.xml_io.simulation_io import parse_reaction_xml
+from pystarc.forces.electrostatic.grid_force import DXGrid
+from pystarc.simulation.nam_simulator import zero_force
+from pystarc.structures.pqr_io import parse_pqr
+from pystarc.aux.aux_tools import bounding_box
+import xml.etree.ElementTree as ET
+from pathlib import Path
+import numpy as np
+import click
+import sys
+
+
+@click.group()
+@click.version_option(package_name="pystarc")
+def cli():
+    """PySTARC - Python Simulation Toolkit for Association Rate Constants"""
+    pass
+
+
+# nam_simulation
+@cli.command("nam_simulation")
+@click.option("--mol1", required=True, help="PQR file for molecule 1")
+@click.option("--mol2", required=True, help="PQR file for molecule 2")
+@click.option("--rxn", required=True, help="Reaction XML file")
+@click.option("--n", default=1000, show_default=True, help="Number of trajectories")
+@click.option("--dt", default=0.2, show_default=True, help="Time step (ps)")
+@click.option("--r-start", default=100.0, show_default=True, help="Start radius (Å)")
+@click.option("--dx", multiple=True, help="APBS .dx grid file(s)")
+@click.option("--seed", default=None, type=int, help="Random seed")
+@click.option("--verbose", is_flag=True, help="Print progress")
+@click.option("--output", default="results.xml", help="Output XML file")
+def nam_simulation(mol1, mol2, rxn, n, dt, r_start, dx, seed, verbose, output):
+    """Run a NAM Brownian dynamics simulation."""
+    click.echo(f"Loading molecules …")
+    m1 = parse_pqr(mol1)
+    m2 = parse_pqr(mol2)
+    click.echo(f"  mol1: {m1}")
+    click.echo(f"  mol2: {m2}")
+    pathways = parse_reaction_xml(rxn)
+    click.echo(f"  reactions: {pathways}")
+    # Mobility from bounding radii
+    r1 = m1.bounding_radius()
+    r2 = m2.bounding_radius()
+    mobility = MobilityTensor.from_radii(r1, r2)
+    click.echo(f"  mobility: {mobility}")
+    # Load DX grids if provided
+    grids = []
+    for dx_file in dx:
+        g = DXGrid.from_file(dx_file)
+        grids.append(g)
+        click.echo(f"  loaded grid: {g}")
+    # Build force function
+    if grids:
+
+        def force_fn(mol_1, mol_2):
+            force = np.zeros(3)
+            torque = np.zeros(3)
+            energy = 0.0
+            for grid in grids:
+                for atom in mol_2.atoms:
+                    if abs(atom.charge) < 1e-9:
+                        continue
+                    f = grid.force_on_charge(atom.position, atom.charge)
+                    force += f
+                    energy += grid.interpolate(atom.position) * atom.charge
+                    # torque = r × f
+                    r = atom.position - mol_2.centroid()
+                    torque += np.cross(r, f)
+            return force, torque, energy
+
+    else:
+        force_fn = zero_force
+    params = NAMParameters(
+        n_trajectories=n,
+        dt=dt,
+        r_start=r_start,
+        seed=seed,
+        verbose=verbose,
+    )
+    sim = NAMSimulator(m1, m2, mobility, pathways, params, force_fn)
+    click.echo(f"\nRunning {n} trajectories …")
+    result = sim.run()
+    click.echo(f"\n{'-'*50}")
+    click.echo(f"Results:")
+    click.echo(f"  Reacted : {result.n_reacted}")
+    click.echo(f"  Escaped : {result.n_escaped}")
+    click.echo(f"  P(rxn)  : {result.reaction_probability:.4f}")
+    D_rel = mobility.relative_translational_diffusion()
+    k = result.rate_constant(D_rel)
+    click.echo(f"  k_assoc : {k:.3e} M⁻¹s⁻¹")
+    click.echo(f"{'-'*50}")
+
+
+# bounding_box
+@cli.command("bounding_box")
+@click.argument("pqr_file")
+@click.option("--padding", default=5.0, show_default=True, help="Padding in Å")
+def bounding_box_cmd(pqr_file, padding):
+    """Print bounding box of a PQR molecule."""
+    mol = parse_pqr(pqr_file)
+    bb = bounding_box(mol, padding)
+    click.echo(f"Bounding box for {pqr_file}:")
+    click.echo(f"  x: [{bb.xmin:.3f}, {bb.xmax:.3f}]")
+    click.echo(f"  y: [{bb.ymin:.3f}, {bb.ymax:.3f}]")
+    click.echo(f"  z: [{bb.zmin:.3f}, {bb.zmax:.3f}]")
+    click.echo(f"  center: {bb.center}")
+    click.echo(f"  size:   {bb.size}")
+
+
+# pqr_to_xml
+@cli.command("pqr_to_xml")
+@click.argument("pqr_file")
+@click.option("--output", "-o", default=None, help="Output XML file")
+def pqr_to_xml(pqr_file, output):
+    """Convert a PQR file to PySTARC molecule XML format."""
+    mol = parse_pqr(pqr_file)
+    root = ET.Element("molecule", name=mol.name)
+    for a in mol.atoms:
+        ET.SubElement(
+            root,
+            "atom",
+            index=str(a.index),
+            name=a.name,
+            resname=a.residue_name,
+            resid=str(a.residue_index),
+            x=f"{a.x:.4f}",
+            y=f"{a.y:.4f}",
+            z=f"{a.z:.4f}",
+            charge=f"{a.charge:.4f}",
+            radius=f"{a.radius:.4f}",
+        )
+    tree = ET.ElementTree(root)
+    ET.indent(tree, space="  ")
+    out = output or (Path(pqr_file).stem + ".xml")
+    tree.write(out, encoding="unicode", xml_declaration=True)
+    click.echo(f"Written: {out}  ({len(mol.atoms)} atoms)")
+
+
+def main():
+    cli()
+
+
+if __name__ == "__main__":
+    main()