rust-simulation-tools 0.2.4__tar.gz → 0.2.5__tar.gz

{rust_simulation_tools-0.2.4 → rust_simulation_tools-0.2.5}/Cargo.lock

@@ -38,6 +38,12 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
 
+[[package]]
+name = "bitflags"
+version = "2.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+
 [[package]]
 name = "bumpalo"
 version = "3.19.1"
@@ -187,6 +193,45 @@ version = "1.15.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
 
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+
+[[package]]
+name = "getrandom"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "wasi",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "r-efi",
+ "wasip2",
+]
+
 [[package]]
 name = "half"
 version = "2.7.1"
@@ -258,6 +303,12 @@ version = "0.2.176"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "58f929b4d672ea937a23a1ab494143d968337a5f47e56d0815df1e0890ddf174"
 
+[[package]]
+name = "linux-raw-sys"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df1d3c3b53da64cf5760482273a98e575c651a67eec7f77df96b5b642de8f039"
+
 [[package]]
 name = "log"
 version = "0.4.29"
@@ -433,6 +484,24 @@ version = "1.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "f84267b20a16ea918e43c6a88433c2d54fa145c92a811b5b047ccbe153674483"
 
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "primal-check"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc0d895b311e3af9902528fbb8f928688abbd95872819320517cc24ca6b2bd08"
+dependencies = [
+ "num-integer",
+]
+
 [[package]]
 name = "proc-macro2"
 version = "1.0.101"
@@ -514,6 +583,42 @@ dependencies = [
  "proc-macro2",
 ]
 
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "rand"
+version = "0.8.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
+dependencies = [
+ "libc",
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.6.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
+dependencies = [
+ "getrandom 0.2.17",
+]
+
 [[package]]
 name = "rawpointer"
 version = "0.2.1"
@@ -569,6 +674,22 @@ version = "0.8.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7a2d987857b319362043e95f5353c0535c1f58eec5336fdfcf626430af7def58"
 
+[[package]]
+name = "rst-am1"
+version = "0.1.0"
+dependencies = [
+ "nalgebra",
+]
+
+[[package]]
+name = "rst-antechamber"
+version = "0.1.0"
+dependencies = [
+ "log",
+ "rst-am1",
+ "rst-core",
+]
+
 [[package]]
 name = "rst-bindings"
 version = "0.2.1"
@@ -577,8 +698,13 @@ dependencies = [
  "numpy",
  "pyo3",
  "rayon",
+ "rst-am1",
+ "rst-antechamber",
  "rst-core",
+ "rst-ipsae",
+ "rst-minimize",
  "rst-mmpbsa",
+ "rst-tleap",
  "rustc-hash 2.1.1",
 ]
 
@@ -592,6 +718,25 @@ dependencies = [
  "rayon",
 ]
 
+[[package]]
+name = "rst-ipsae"
+version = "0.1.0"
+dependencies = [
+ "rayon",
+]
+
+[[package]]
+name = "rst-minimize"
+version = "0.1.0"
+dependencies = [
+ "log",
+ "rayon",
+ "rst-core",
+ "rustfft",
+ "tempfile",
+ "thiserror",
+]
+
 [[package]]
 name = "rst-mmpbsa"
 version = "0.1.0"
@@ -603,6 +748,17 @@ dependencies = [
  "thiserror",
 ]
 
+[[package]]
+name = "rst-tleap"
+version = "0.1.0"
+dependencies = [
+ "log",
+ "rand",
+ "rst-antechamber",
+ "rst-core",
+ "thiserror",
+]
+
 [[package]]
 name = "rustc-hash"
 version = "1.1.0"
@@ -615,6 +771,33 @@ version = "2.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
 
+[[package]]
+name = "rustfft"
+version = "6.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21db5f9893e91f41798c88680037dba611ca6674703c1a18601b01a72c8adb89"
+dependencies = [
+ "num-complex",
+ "num-integer",
+ "num-traits",
+ "primal-check",
+ "strength_reduce",
+ "transpose",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cd15f8a2c5551a84d56efdc1cd049089e409ac19a3072d5037a17fd70719ff3e"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys",
+]
+
 [[package]]
 name = "rustversion"
 version = "1.0.22"
@@ -695,6 +878,12 @@ dependencies = [
  "wide",
 ]
 
+[[package]]
+name = "strength_reduce"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fe895eb47f22e2ddd4dabc02bce419d2e643c8e3b585c78158b349195bc24d82"
+
 [[package]]
 name = "syn"
 version = "2.0.106"
@@ -712,6 +901,19 @@ version = "0.12.16"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1"
 
+[[package]]
+name = "tempfile"
+version = "3.23.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2d31c77bdf42a745371d260a26ca7163f1e0924b64afa0b688e61b5a9fa02f16"
+dependencies = [
+ "fastrand",
+ "getrandom 0.3.4",
+ "once_cell",
+ "rustix",
+ "windows-sys",
+]
+
 [[package]]
 name = "thiserror"
 version = "2.0.18"
@@ -742,6 +944,16 @@ dependencies = [
  "serde_json",
 ]
 
+[[package]]
+name = "transpose"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1ad61aed86bc3faea4300c7aee358b4c6d0c8d6ccc36524c96e4c92ccf26e77e"
+dependencies = [
+ "num-integer",
+ "strength_reduce",
+]
+
 [[package]]
 name = "typenum"
 version = "1.18.0"
@@ -770,6 +982,21 @@ dependencies = [
  "winapi-util",
 ]
 
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.2+wasi-0.2.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9517f9239f02c069db75e65f174b3da828fe5f5b945c4dd26bd25d89c03ebcf5"
+dependencies = [
+ "wit-bindgen",
+]
+
 [[package]]
 name = "wasm-bindgen"
 version = "0.2.108"
@@ -859,6 +1086,12 @@ dependencies = [
  "windows-link",
 ]
 
+[[package]]
+name = "wit-bindgen"
+version = "0.51.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d7249219f66ced02969388cf2bb044a09756a083d0fab1e566056b04d9fbcaa5"
+
 [[package]]
 name = "zerocopy"
 version = "0.8.36"

rust_simulation_tools-0.2.5/Cargo.toml

@@ -0,0 +1,8 @@
+[workspace]
+members = ["crates/core", "crates/bindings", "crates/mmpbsa", "crates/ipsae", "crates/tleap", "crates/minimize", "crates/am1", "crates/antechamber"]
+resolver = "2"
+
+[profile.release]
+opt-level = 3
+lto = true
+codegen-units = 1

{rust_simulation_tools-0.2.4 → rust_simulation_tools-0.2.5}/PKG-INFO

@@ -1,9 +1,9 @@
 Metadata-Version: 2.4
 Name: rust_simulation_tools
-Version: 0.2.4
+Version: 0.2.5
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
-Requires-Dist: numpy>=1.26
+Requires-Dist: numpy>=2.0
 Summary: Fast algorithms for MD trajectories
 Author-email: Matt Sinclair <msinclair@anl.gov>
 Requires-Python: >=3.10
@@ -37,11 +37,15 @@ maturin develop --release
 
 ## Features
 
-- **File I/O**: AMBER topology/coordinates, DCD and MDCRD trajectories
+- **File I/O**: AMBER topology/coordinates, DCD and MDCRD trajectories; PDB, mmCIF, mol2, SDF structures
+- **System building**: tleap-style `SystemBuilder` — force fields, solvation, ions, prmtop/inpcrd output
+- **Ligand parameterization**: built-in antechamber — GAFF2 atom typing + AM1-BCC charges (no AmberTools needed)
 - **Selections**: VMD-style atom selection with property access
 - **Analysis**: SASA, trajectory unwrapping, Kabsch alignment
 - **Fingerprints**: Per-residue interaction energies (LJ + electrostatic)
+- **Minimization**: Steepest-descent + conjugate-gradient with optional restraints
 - **MM-PBSA/GBSA**: Binding free energy with per-residue decomposition
+- **Interface scoring**: ipSAE, pDockQ, pDockQ2, LIS, ipTM for predicted complexes
 
 ## Quick Start
 
@@ -59,6 +63,58 @@ dcd = DcdReader("trajectory.dcd")
 trajectory, boxes = dcd.read_all()
 ```
 
+### Build a System
+
+The `SystemBuilder` parameterizes structures and writes simulation-ready AMBER
+files — no AmberTools install required.
+
+```python
+from rust_simulation_tools import SystemBuilder
+
+builder = SystemBuilder()
+builder.load_protein_ff19sb()   # protein force field
+builder.load_gaff2()            # small-molecule force field
+builder.load_water_opc()        # OPC water model
+
+# Load structures (PDB / mmCIF for proteins, mol2/SDF for ligands)
+protein = builder.load_pdb("protein.pdb")
+ligand  = builder.load_ligand("ligand.sdf", net_charge=0)  # auto GAFF2 + AM1-BCC
+
+# Combine, solvate, ionize
+system = builder.combine([protein, ligand])
+builder.solvate_box(system, buffer=12.0)
+builder.add_salt(system, "Na+", "Cl-", concentration=0.150)  # neutralize + 150 mM
+
+# Write output
+builder.write_amber(system, "complex.prmtop", "complex.inpcrd")
+builder.write_pdb(system, "complex.pdb")
+```
+
+For implicit solvent, skip `load_water_opc`/solvation and write the topology
+directly. See `examples/example_explicit_solvent.py`,
+`example_implicit_solvent.py`, and `example_protein_ligand.py`.
+
+### Parameterize a Ligand
+
+```python
+import rust_simulation_tools as rst
+
+# Standalone: write a parameterized mol2 (GAFF2 types + charges)
+rst.parameterize_ligand(
+    "ligand.sdf", "ligand_gaff2.mol2",
+    net_charge=0,
+    charge_method="am1bcc",   # or "gasteiger" (faster, less accurate)
+)
+
+# Raw AM1 Mulliken charges from atomic numbers + coordinates
+import numpy as np
+charges = rst.compute_am1_charges(
+    np.array([8, 1, 1], dtype=np.int64),          # O, H, H
+    np.array([[0, 0, 0], [0, 0.757, 0.587], [0, -0.757, 0.587]], dtype=float),
+    charge=0,
+)
+```
+
 ### Atom Selection
 
 Select atoms using VMD-style expressions. The `select()` method returns a `Selection` object with direct property access.
@@ -97,9 +153,12 @@ from rust_simulation_tools import compute_sasa_from_topology
 
 # Single frame
 sasa = compute_sasa_from_topology(topo, coords)
-print(f"Total SASA: {sasa['total']:.1f} A^2")
-print(f"Per-atom: {sasa['per_atom'].shape}")
-print(f"Per-residue: {sasa['per_residue']}")  # dict of residue_idx -> area
+print(f"Total SASA: {sasa['total']:.1f} A^2")          # float
+print(f"Per-atom: {sasa['per_atom'].shape}")           # ndarray (n_atoms,)
+print(f"Per-residue: {sasa['per_residue'].shape}")     # ndarray (n_residues,), by residue index
+
+# Trajectory: total -> ndarray (n_frames,), per_residue -> list of per-frame dicts
+traj_sasa = compute_sasa_trajectory_from_topology(topo, trajectory)
 ```
 
 ### Trajectory Alignment
@@ -187,6 +246,53 @@ for res in sorted(decomp.receptor_residues, key=lambda r: r.total())[:5]:
     print(f"{res.residue_label}{res.residue_index}: {res.total():.2f} kcal/mol")
 ```
 
+### Energy Minimization
+
+Steepest-descent + conjugate-gradient minimization with optional positional
+restraints and a full energy-component breakdown.
+
+```python
+from rust_simulation_tools import minimize, MinimizeConfig
+
+config = MinimizeConfig(
+    max_cycles=5000,
+    sd_cycles=100,           # initial steepest-descent steps
+    convergence_rms=0.01,
+    cutoff=10.0,
+    restraint_mask="backbone",  # optional; omit for unrestrained
+    restraint_weight=10.0,
+)
+
+result = minimize("system.prmtop", "system.inpcrd", config=config, output="min.inpcrd")
+print(f"Energy: {result.final_energy:.2f} kcal/mol  converged={result.converged}")
+
+ec = result.energy_components       # bond, angle, dihedral, vdw,
+print(ec.total(), ec.vdw, ec.elec_recip)   # elec_direct, elec_recip, vdw_14, elec_14
+```
+
+Use `minimize_topology(topo, "system.inpcrd", ...)` to reuse a pre-loaded
+topology. See `examples/example_minimization.py`.
+
+### Interface Scoring (ipSAE)
+
+Score predicted complexes (AlphaFold-Multimer, Boltz, Chai) from pLDDT and PAE.
+
+```python
+import numpy as np
+from rust_simulation_tools import compute_ipsae
+
+plddt = np.load("plddt.npy")            # per-residue, 0-100 scale, shape (N,)
+pae = np.load("pae.npy").flatten()      # predicted aligned error, flattened (N*N,)
+
+results = compute_ipsae("model.pdb", plddt, pae)   # PDB or CIF
+for pair in results["max_pairs"]:       # also "directed_pairs"
+    print(f"{pair['chain1']}-{pair['chain2']}: "
+          f"ipSAE={pair['ipSAE']:.3f} pDockQ={pair['pDockQ']:.3f} LIS={pair['LIS']:.3f}")
+```
+
+`compute_ipsae_from_arrays(coords, chains, chain_types, plddt, pae)` does the same
+from in-memory arrays. See `examples/example_ipsae.py`.
+
 ## API Reference
 
 ### File I/O
@@ -198,6 +304,31 @@ for res in sorted(decomp.receptor_residues, key=lambda r: r.total())[:5]:
 | `DcdReader(path)` | DCD trajectory reader |
 | `MdcrdReader(path, n_atoms, has_box)` | AMBER ASCII trajectory reader |
 
+### System Building
+
+| Method | Description |
+|--------|-------------|
+| `SystemBuilder()` | Create a tleap-style builder |
+| `.load_protein_ff19sb()`, `.load_gaff2()`, `.load_water_opc()` | Load force fields / water model |
+| `.load_custom_frcmod(path)`, `.load_custom_lib(path)` | Load custom ligand parameters |
+| `.load_pdb(path)`, `.load_mmcif(path)`, `.load_mol2(path)` | Load a structure, returns `System` |
+| `.load_ligand(path, net_charge=0)` | Load + parameterize a ligand (GAFF2 + AM1-BCC) |
+| `.combine([systems])` | Merge systems into one `System` |
+| `.solvate_box(system, buffer=12.0, closeness=1.0)` | Solvate in an OPC water box |
+| `.add_ions(system, ion, count=None)` | Add ions (`"neutralize"`, int count, or float conc.) |
+| `.add_salt(system, cation="Na+", anion="Cl-", concentration=0.150)` | Neutralize + add salt |
+| `.write_amber(system, prmtop, inpcrd)`, `.write_prmtop/.write_inpcrd/.write_pdb` | Write output |
+
+`System` exposes `.n_atoms`, `.n_residues`, `.total_charge`, `.box_dimensions`,
+`.box_angles`.
+
+### Parameterization
+
+| Function | Description |
+|----------|-------------|
+| `parameterize_ligand(input, output, net_charge=0, charge_method="am1bcc")` | Write a GAFF2/charge-assigned mol2 (`"am1bcc"` or `"gasteiger"`) |
+| `compute_am1_charges(atomic_numbers, coords, charge=0)` | Raw AM1 Mulliken charges |
+
 ### AmberTopology
 
 | Property/Method | Description |
@@ -234,10 +365,24 @@ for res in sorted(decomp.receptor_residues, key=lambda r: r.total())[:5]:
 | Function | Description |
 |----------|-------------|
 | `compute_sasa_from_topology(topo, coords)` | SASA using topology for radii |
+| `compute_sasa_trajectory_from_topology(topo, trajectory)` | Per-frame SASA over a trajectory |
 | `calculate_sasa(coords, radii, residue_indices)` | SASA with explicit radii |
 | `kabsch_align(trajectory, reference, align_indices)` | RMSD-minimizing alignment |
 | `unwrap_dcd(path)` | Remove PBC artifacts from DCD |
 | `unwrap_system(trajectory, boxes)` | Remove PBC artifacts |
+| `FingerprintSession(prmtop, trajectory)` | Per-residue LJ/electrostatic fingerprints |
+
+### Minimization
+
+| Function | Description |
+|----------|-------------|
+| `minimize(prmtop, inpcrd, config=None, output=None)` | Minimize from files, returns `MinimizeResult` |
+| `minimize_topology(topo, inpcrd, config=None, output=None)` | Minimize with a pre-loaded topology |
+| `MinimizeConfig(max_cycles, sd_cycles, convergence_rms, cutoff, restraint_mask, restraint_weight, initial_step_size)` | Minimization settings |
+
+`MinimizeResult` exposes `.final_energy`, `.final_rms`, `.cycles`, `.converged`,
+`.energy_components` (`.bond`, `.angle`, `.dihedral`, `.vdw`, `.elec_direct`,
+`.elec_recip`, `.vdw_14`, `.elec_14`, `.total()`).
 
 ### MM-PBSA/GBSA
 
@@ -249,7 +394,27 @@ for res in sorted(decomp.receptor_residues, key=lambda r: r.total())[:5]:
 | `compute_mm_energy(topo, coords)` | Molecular mechanics energy |
 | `compute_gb_energy(topo, coords, params)` | GB solvation energy |
 | `compute_pb_energy(topo, coords, params)` | PB solvation energy |
-| `interaction_entropy(frames, temperature)` | Entropy correction |
+| `compute_sa_energy(topo, coords, params)` | Nonpolar surface-area energy |
+| `interaction_entropy(frames, temperature)` | Interaction-entropy correction |
+| `quasi_harmonic_entropy(...)` | Quasi-harmonic entropy estimate |
+
+Parameter objects: `GbParams`, `PbParams`, `SaParams`, `GbModel`.
+
+### Interface Scoring
+
+| Function | Description |
+|----------|-------------|
+| `compute_ipsae(structure_path, plddt, pae, pdockq_cutoff=8.0, pae_cutoff=12.0)` | ipSAE/pDockQ/LIS/ipTM from a PDB/CIF file |
+| `compute_ipsae_from_arrays(coords, chains, chain_types, plddt, pae, ...)` | Same, from in-memory arrays |
+
+## Agent Skills
+
+The [`skills/`](skills) directory contains [agent skills](skills/README.md) that
+teach AI coding assistants (e.g. Claude Code) how to use this package — system
+building, ligand parameterization, trajectory analysis, MM-PBSA, minimization,
+and ipSAE scoring. They are mirrored under `.claude/skills/` so they load
+automatically when working in this repo. See [`skills/README.md`](skills/README.md)
+for the full list and how to install them elsewhere.
 
 ## Development