hxprobe 0.1.0__tar.gz

hxprobe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hxprobe authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hxprobe-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: hxprobe
+Version: 0.1.0
+Summary: The 50-conformer probe: residue-resolved hydrogen-exchange opening free energies from conformational ensembles
+Author: hxprobe authors
+License: MIT
+Project-URL: Homepage, https://github.com/woshuizhaol/hxprobe
+Project-URL: Source, https://github.com/woshuizhaol/hxprobe
+Project-URL: Issues, https://github.com/woshuizhaol/hxprobe/issues
+Keywords: hydrogen-deuterium exchange,protection factor,conformational ensemble,generative models,protein dynamics,free energy,structural biology
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: pandas>=1.3
+Requires-Dist: mdtraj>=1.9
+Provides-Extra: fix
+Requires-Dist: pdbfixer>=1.8; extra == "fix"
+Requires-Dist: openmm>=7.6; extra == "fix"
+Provides-Extra: diff
+Requires-Dist: torch>=1.10; extra == "diff"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# hxprobe — the 50-conformer probe
+
+**Read residue-resolved hydrogen-exchange opening free energies out of a conformational ensemble.**
+
+`hxprobe` turns a conformational ensemble (from a generative model, molecular
+dynamics, or any source) into per-residue protection factors and opening free
+energies (ΔG_open, in kcal/mol) using a white-box, two-parameter physical
+operator. It is an inexpensive, physically interpretable probe of how well an
+ensemble reproduces the *near-equilibrium local opening* that hydrogen–deuterium
+exchange measures — and it converges within roughly **50 conformers**, which is
+where the name comes from.
+
+```
+ln PF_i = β_C · ⟨N_C,i⟩ + β_H · ⟨N_H,i⟩            (ensemble average)
+ΔG_open,i = RT · ln PF_i                            (EX2 regime)
+```
+
+`N_C` counts heavy atoms near each backbone amide nitrogen and `N_H` counts the
+amide's backbone hydrogen bonds, averaged over the ensemble. The two
+coefficients are **fixed to their classical Best–Vendruscolo values** (0.35 and
+2.0) and are *not* fitted to stability data, so any residue-level signal the
+probe recovers comes from the ensemble, not from a tuned scoring function.
+
+## Install
+
+```bash
+pip install hxprobe
+```
+
+This pulls in `numpy`, `pandas`, and `mdtraj`. Two optional extras:
+
+```bash
+pip install "hxprobe[fix]"   # PDBFixer/OpenMM: repair + protonate raw structures
+pip install "hxprobe[diff]"  # PyTorch: differentiable operator for steering
+```
+
+## Quickstart
+
+```python
+import hxprobe
+
+# Score the bundled 50-conformer ubiquitin ensemble (already protonated).
+res = hxprobe.score_ensemble(hxprobe.example_ensemble_path(), protonate="none")
+print(res.to_dataframe().head())          # resSeq, resn, NC_mean, NH_mean, lnPF, dGopen_kcal
+
+# Compare to experimental native-state HX opening free energies.
+exp = hxprobe.load_experimental()          # {resSeq: dG_open}
+ref = [exp.get(int(r), float("nan")) for r in res.resSeq]
+print("Spearman vs experiment:", round(hxprobe.spearman(res.lnPF, ref), 3))
+```
+
+Score *your own* ensemble — a multi-model PDB, or a trajectory plus topology:
+
+```python
+res = hxprobe.score_ensemble("my_ensemble.pdb")               # multi-model PDB
+res = hxprobe.score_ensemble("traj.xtc", top="topology.pdb")  # trajectory + topology
+res.to_csv("opening_free_energies.csv")
+```
+
+If your structures are raw heavy-atom coordinates without hydrogens, the H-bond
+term is obtained either by a geometric amide-H placement (default, no extra
+dependencies) or, more faithfully, with PDBFixer:
+
+```python
+res = hxprobe.score_ensemble("raw_heavy_atom.pdb", protonate="pdbfixer")  # needs hxprobe[fix]
+```
+
+## Command line
+
+```bash
+hxprobe example                       # run the bundled ubiquitin demo
+hxprobe score my_ensemble.pdb         # print the per-residue table
+hxprobe score traj.xtc --top top.pdb --out dG.csv
+hxprobe converge my_ensemble.pdb      # show convergence with ensemble size
+```
+
+## What you get back
+
+`score_ensemble` returns a `ProtectionResult` with NumPy arrays and a
+`.to_dataframe()` / `.to_csv()` helper:
+
+| field | meaning |
+|---|---|
+| `resSeq`, `resn` | residue number and one-letter code |
+| `NC_mean`, `NH_mean` | ensemble-averaged contacts / hydrogen bonds |
+| `lnPF`, `log10PF` | log protection factor |
+| `dGopen_kcal` | opening free energy ΔG_open (kcal/mol) |
+
+Two further entry points:
+
+* **`convergence(ensemble)`** — Spearman correlation of the `n`-conformer
+  readout against the full-ensemble readout (and, optionally, against an
+  experimental reference), showing the plateau near ~50 conformers.
+* **`global_unfolding(ensemble)`** — `RT · min_c ⟨ln PF⟩_residues`, the
+  protection of the most-open conformer, a bounded proxy for global fold
+  stability (the unfolded-state limit of the ensemble).
+
+## How it works
+
+For each backbone amide (prolines and non-standard residues are skipped):
+
+* **`N_C`** — heavy atoms within **6.5 Å** of the amide nitrogen, sequence
+  separation `|i − j| ≥ 3`, hydrogens excluded.
+* **`N_H`** — backbone carbonyl oxygens within **2.6 Å** of the amide hydrogen,
+  sequence separation `|i − j| ≥ 2`.
+
+Counts are computed per conformer and **averaged over the ensemble before** the
+linear combination is formed, so a residue that is buried in most conformers but
+exposed in a rare open state receives the reduced mean contact count its
+protection reflects. The contact term dominates, so the readout is robust even
+when hydrogens are placed geometrically rather than with a full protonation step.
+
+## Reproducing the bundled example
+
+`hxprobe example` scores a 50-conformer leakage-free ubiquitin ensemble and
+recovers the experimental native-state opening free energies at Spearman
+ρ ≈ 0.58, with the correlation plateauing by ~25–50 conformers — the behaviour
+that motivates the probe.
+
+## Citing
+
+If you use `hxprobe`, please cite the accompanying study on residue-resolved
+hydrogen-exchange free energies as a benchmark for generative conformational
+ensembles. (Reference to be added on publication.)
+
+## License
+
+MIT.

hxprobe-0.1.0/README.md

@@ -0,0 +1,128 @@
+# hxprobe — the 50-conformer probe
+
+**Read residue-resolved hydrogen-exchange opening free energies out of a conformational ensemble.**
+
+`hxprobe` turns a conformational ensemble (from a generative model, molecular
+dynamics, or any source) into per-residue protection factors and opening free
+energies (ΔG_open, in kcal/mol) using a white-box, two-parameter physical
+operator. It is an inexpensive, physically interpretable probe of how well an
+ensemble reproduces the *near-equilibrium local opening* that hydrogen–deuterium
+exchange measures — and it converges within roughly **50 conformers**, which is
+where the name comes from.
+
+```
+ln PF_i = β_C · ⟨N_C,i⟩ + β_H · ⟨N_H,i⟩            (ensemble average)
+ΔG_open,i = RT · ln PF_i                            (EX2 regime)
+```
+
+`N_C` counts heavy atoms near each backbone amide nitrogen and `N_H` counts the
+amide's backbone hydrogen bonds, averaged over the ensemble. The two
+coefficients are **fixed to their classical Best–Vendruscolo values** (0.35 and
+2.0) and are *not* fitted to stability data, so any residue-level signal the
+probe recovers comes from the ensemble, not from a tuned scoring function.
+
+## Install
+
+```bash
+pip install hxprobe
+```
+
+This pulls in `numpy`, `pandas`, and `mdtraj`. Two optional extras:
+
+```bash
+pip install "hxprobe[fix]"   # PDBFixer/OpenMM: repair + protonate raw structures
+pip install "hxprobe[diff]"  # PyTorch: differentiable operator for steering
+```
+
+## Quickstart
+
+```python
+import hxprobe
+
+# Score the bundled 50-conformer ubiquitin ensemble (already protonated).
+res = hxprobe.score_ensemble(hxprobe.example_ensemble_path(), protonate="none")
+print(res.to_dataframe().head())          # resSeq, resn, NC_mean, NH_mean, lnPF, dGopen_kcal
+
+# Compare to experimental native-state HX opening free energies.
+exp = hxprobe.load_experimental()          # {resSeq: dG_open}
+ref = [exp.get(int(r), float("nan")) for r in res.resSeq]
+print("Spearman vs experiment:", round(hxprobe.spearman(res.lnPF, ref), 3))
+```
+
+Score *your own* ensemble — a multi-model PDB, or a trajectory plus topology:
+
+```python
+res = hxprobe.score_ensemble("my_ensemble.pdb")               # multi-model PDB
+res = hxprobe.score_ensemble("traj.xtc", top="topology.pdb")  # trajectory + topology
+res.to_csv("opening_free_energies.csv")
+```
+
+If your structures are raw heavy-atom coordinates without hydrogens, the H-bond
+term is obtained either by a geometric amide-H placement (default, no extra
+dependencies) or, more faithfully, with PDBFixer:
+
+```python
+res = hxprobe.score_ensemble("raw_heavy_atom.pdb", protonate="pdbfixer")  # needs hxprobe[fix]
+```
+
+## Command line
+
+```bash
+hxprobe example                       # run the bundled ubiquitin demo
+hxprobe score my_ensemble.pdb         # print the per-residue table
+hxprobe score traj.xtc --top top.pdb --out dG.csv
+hxprobe converge my_ensemble.pdb      # show convergence with ensemble size
+```
+
+## What you get back
+
+`score_ensemble` returns a `ProtectionResult` with NumPy arrays and a
+`.to_dataframe()` / `.to_csv()` helper:
+
+| field | meaning |
+|---|---|
+| `resSeq`, `resn` | residue number and one-letter code |
+| `NC_mean`, `NH_mean` | ensemble-averaged contacts / hydrogen bonds |
+| `lnPF`, `log10PF` | log protection factor |
+| `dGopen_kcal` | opening free energy ΔG_open (kcal/mol) |
+
+Two further entry points:
+
+* **`convergence(ensemble)`** — Spearman correlation of the `n`-conformer
+  readout against the full-ensemble readout (and, optionally, against an
+  experimental reference), showing the plateau near ~50 conformers.
+* **`global_unfolding(ensemble)`** — `RT · min_c ⟨ln PF⟩_residues`, the
+  protection of the most-open conformer, a bounded proxy for global fold
+  stability (the unfolded-state limit of the ensemble).
+
+## How it works
+
+For each backbone amide (prolines and non-standard residues are skipped):
+
+* **`N_C`** — heavy atoms within **6.5 Å** of the amide nitrogen, sequence
+  separation `|i − j| ≥ 3`, hydrogens excluded.
+* **`N_H`** — backbone carbonyl oxygens within **2.6 Å** of the amide hydrogen,
+  sequence separation `|i − j| ≥ 2`.
+
+Counts are computed per conformer and **averaged over the ensemble before** the
+linear combination is formed, so a residue that is buried in most conformers but
+exposed in a rare open state receives the reduced mean contact count its
+protection reflects. The contact term dominates, so the readout is robust even
+when hydrogens are placed geometrically rather than with a full protonation step.
+
+## Reproducing the bundled example
+
+`hxprobe example` scores a 50-conformer leakage-free ubiquitin ensemble and
+recovers the experimental native-state opening free energies at Spearman
+ρ ≈ 0.58, with the correlation plateauing by ~25–50 conformers — the behaviour
+that motivates the probe.
+
+## Citing
+
+If you use `hxprobe`, please cite the accompanying study on residue-resolved
+hydrogen-exchange free energies as a benchmark for generative conformational
+ensembles. (Reference to be added on publication.)
+
+## License
+
+MIT.

hxprobe-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hxprobe"
+version = "0.1.0"
+description = "The 50-conformer probe: residue-resolved hydrogen-exchange opening free energies from conformational ensembles"
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "hxprobe authors" }]
+keywords = [
+    "hydrogen-deuterium exchange",
+    "protection factor",
+    "conformational ensemble",
+    "generative models",
+    "protein dynamics",
+    "free energy",
+    "structural biology",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Topic :: Scientific/Engineering :: Chemistry",
+]
+dependencies = [
+    "numpy>=1.21",
+    "pandas>=1.3",
+    "mdtraj>=1.9",
+]
+
+[project.optional-dependencies]
+# Repair + protonate raw crystal/generated structures (missing heavy atoms, no hydrogens).
+fix = ["pdbfixer>=1.8", "openmm>=7.6"]
+# Differentiable operator for gradient-based ensemble steering.
+diff = ["torch>=1.10"]
+# Development / test.
+dev = ["pytest>=7", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/woshuizhaol/hxprobe"
+Source = "https://github.com/woshuizhaol/hxprobe"
+Issues = "https://github.com/woshuizhaol/hxprobe/issues"
+
+[project.scripts]
+hxprobe = "hxprobe.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+hxprobe = ["data/*.pdb.gz", "data/*.csv"]

hxprobe-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

hxprobe-0.1.0/src/hxprobe/__init__.py

@@ -0,0 +1,29 @@
+"""hxprobe -- the 50-conformer probe.
+
+Read residue-resolved hydrogen-exchange opening free energies out of a
+conformational ensemble with a white-box, two-parameter physical operator.
+"""
+from .operator import (BETA_C, BETA_H, CUT_NC_NM, CUT_NH_NM, IJ_NC, IJ_NH,
+                       R_KCAL, T_REF, ProtectionResult, compute, nc_nh_frame)
+from .ensemble import load_ensemble, optionally_protonate
+from .probe import (convergence, example_ensemble_path, global_unfolding,
+                    load_experimental, score_ensemble, spearman)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "score_ensemble",
+    "convergence",
+    "global_unfolding",
+    "compute",
+    "nc_nh_frame",
+    "ProtectionResult",
+    "load_ensemble",
+    "optionally_protonate",
+    "example_ensemble_path",
+    "load_experimental",
+    "spearman",
+    "BETA_C", "BETA_H", "CUT_NC_NM", "CUT_NH_NM", "IJ_NC", "IJ_NH",
+    "R_KCAL", "T_REF",
+]

hxprobe-0.1.0/src/hxprobe/cli.py

@@ -0,0 +1,101 @@
+"""Command-line interface for hxprobe."""
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def _add_common(p):
+    p.add_argument("ensemble", help="multi-model PDB (.pdb/.pdb.gz) or trajectory file")
+    p.add_argument("--top", default=None, help="topology file (for trajectory inputs)")
+    p.add_argument("--protonate", default="auto",
+                   choices=["auto", "none", "pdbfixer"],
+                   help="how to obtain backbone amide hydrogens (default: auto)")
+    p.add_argument("--betaC", type=float, default=None, help="contact coefficient")
+    p.add_argument("--betaH", type=float, default=None, help="H-bond coefficient")
+    p.add_argument("--temperature", type=float, default=None, help="temperature (K)")
+
+
+def _operator_kw(args):
+    from . import BETA_C, BETA_H, T_REF
+    return dict(
+        protonate=args.protonate,
+        betaC=BETA_C if args.betaC is None else args.betaC,
+        betaH=BETA_H if args.betaH is None else args.betaH,
+        temperature=T_REF if args.temperature is None else args.temperature,
+    )
+
+
+def _cmd_score(args):
+    from . import score_ensemble
+    res = score_ensemble(args.ensemble, top=args.top, **_operator_kw(args))
+    df = res.to_dataframe()
+    if args.out:
+        res.to_csv(args.out)
+        print(f"wrote {len(res)} residues to {args.out}")
+    else:
+        print(df.to_string(index=False))
+    return 0
+
+
+def _cmd_converge(args):
+    from . import convergence
+    out = convergence(args.ensemble, top=args.top, **_operator_kw(args))
+    try:
+        print(out.to_string(index=False))
+    except AttributeError:
+        for row in out:
+            print(row)
+    return 0
+
+
+def _cmd_example(args):
+    from . import (convergence, example_ensemble_path, load_experimental,
+                   score_ensemble, spearman)
+    path = example_ensemble_path()
+    exp = load_experimental()
+    print(f"bundled example: 50-conformer leakage-free ubiquitin ensemble\n  {path}")
+    res = score_ensemble(path, protonate="none")  # already protonated
+    ref = [exp.get(int(rs)) for rs in res.resSeq]
+    rho = spearman(res.lnPF, [r if r is not None else float("nan") for r in ref])
+    n_overlap = sum(1 for r in ref if r is not None)
+    print(f"\nper-residue ln PF vs experimental dG_open (native-state HX):")
+    print(f"  Spearman rho = {rho:+.3f}  over {n_overlap} measured residues")
+    print(f"\nconvergence with ensemble size:")
+    conv = convergence(path, protonate="none", reference=exp)
+    try:
+        print(conv.to_string(index=False))
+    except AttributeError:
+        for row in conv:
+            print("  ", row)
+    return 0
+
+
+def build_parser():
+    p = argparse.ArgumentParser(
+        prog="hxprobe",
+        description="The 50-conformer probe: residue-resolved hydrogen-exchange "
+                    "opening free energies from conformational ensembles.")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("score", help="per-residue opening free energies for an ensemble")
+    _add_common(s)
+    s.add_argument("--out", default=None, help="write a CSV instead of printing")
+    s.set_defaults(func=_cmd_score)
+
+    c = sub.add_parser("converge", help="convergence of the readout with ensemble size")
+    _add_common(c)
+    c.set_defaults(func=_cmd_converge)
+
+    e = sub.add_parser("example", help="run the bundled ubiquitin example")
+    e.set_defaults(func=_cmd_example)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hxprobe-0.1.0/src/hxprobe/data/ubiquitin_dgopen.csv

@@ -0,0 +1,42 @@
+resi,dGopen_kcal,grade,resn
+2,1.831,B,
+3,6.335,B,
+4,6.307,B,
+5,5.897,B,
+6,4.929,B,
+7,6.108,B,
+12,2.969,B,
+13,5.202,B,
+15,2.526,B,
+16,3.436,B,
+17,5.565,B,
+22,2.171,B,
+23,5.771,B,
+25,4.292,B,
+26,7.699,B,
+28,5.513,B,
+29,5.897,B,
+30,7.169,B,
+31,4.703,B,
+32,2.015,B,
+36,2.837,B,
+40,2.679,B,
+41,4.093,B,
+42,4.503,B,
+44,6.307,B,
+45,4.333,B,
+48,4.586,B,
+49,2.482,B,
+50,3.855,B,
+55,4.818,B,
+56,6.045,B,
+57,3.436,B,
+58,2.969,B,
+59,5.612,B,
+60,2.426,B,
+61,4.611,B,
+65,4.201,B,
+67,3.93,B,
+68,4.407,B,
+69,5.339,B,
+70,4.724,B,

hxprobe-0.1.0/src/hxprobe/diff.py

@@ -0,0 +1,68 @@
+"""Differentiable Best--Vendruscolo operator (optional, requires PyTorch).
+
+The hard contact and hydrogen-bond counts are replaced by smooth sigmoidal
+switching functions controlled by a temperature ``tau``; the discrete operator
+is recovered as ``tau -> 0``.  Because protection then becomes a differentiable
+function of atomic coordinates, the residue-level readout can in principle
+provide gradients to steer a generator toward the rare openings it
+under-populates.
+
+Install with ``pip install hxprobe[diff]``.
+"""
+from __future__ import annotations
+
+from .operator import BETA_C, BETA_H, CUT_NC_NM, CUT_NH_NM, IJ_NC, IJ_NH, R_KCAL, T_REF
+
+
+def soft_nc_nh(xyz, amideN_idx, amideH_idx, heavy_idx, O_idx, resid,
+               cut_Nc=CUT_NC_NM, cut_Nh=CUT_NH_NM, ij_Nc=IJ_NC, ij_Nh=IJ_NH,
+               tau=0.02):
+    """Differentiable per-residue (N_C, N_H) for one conformer.
+
+    Parameters
+    ----------
+    xyz : torch.Tensor ``[n_atoms, 3]`` (nanometres, requires_grad as needed)
+    amideN_idx, amideH_idx : list[int]
+        Per-residue amide N / amide H atom indices (``-1`` if absent).
+    heavy_idx, O_idx : list[int]
+        Heavy-atom and backbone-carbonyl-oxygen atom indices.
+    resid : sequence[int]
+        Residue index of every atom (used for the sequence-separation mask).
+    tau : float
+        Switching temperature; smaller is sharper (recovers the hard operator).
+
+    Returns
+    -------
+    (NC, NH) : torch.Tensor, torch.Tensor    each ``[n_res]``
+    """
+    import torch
+
+    dev = xyz.device
+    R = len(amideN_idx)
+    NC = torch.zeros(R, device=dev)
+    NH = torch.zeros(R, device=dev)
+    heavy = torch.as_tensor(heavy_idx, device=dev, dtype=torch.long)
+    hres = torch.as_tensor([resid[i] for i in heavy_idx], device=dev)
+    Os = torch.as_tensor(O_idx, device=dev, dtype=torch.long)
+    Ores = torch.as_tensor([resid[i] for i in O_idx], device=dev)
+    for r in range(R):
+        ni = amideN_idx[r]
+        if ni < 0:
+            continue
+        ri = resid[ni]
+        d = torch.norm(xyz[heavy] - xyz[ni], dim=1)
+        mask_c = (torch.abs(hres - ri) >= ij_Nc).float()
+        NC[r] = torch.sum(torch.sigmoid((cut_Nc - d) / tau) * mask_c)
+        hi = amideH_idx[r]
+        if hi >= 0:
+            dh = torch.norm(xyz[Os] - xyz[hi], dim=1)
+            mask_h = (torch.abs(Ores - ri) >= ij_Nh).float()
+            NH[r] = torch.sum(torch.sigmoid((cut_Nh - dh) / tau) * mask_h)
+    return NC, NH
+
+
+def soft_lnpf(xyz, amideN_idx, amideH_idx, heavy_idx, O_idx, resid,
+              betaC=BETA_C, betaH=BETA_H, **kw):
+    """Differentiable per-residue ln PF for one conformer."""
+    NC, NH = soft_nc_nh(xyz, amideN_idx, amideH_idx, heavy_idx, O_idx, resid, **kw)
+    return betaC * NC + betaH * NH

hxprobe-0.1.0/src/hxprobe/ensemble.py

@@ -0,0 +1,60 @@
+"""Loading conformational ensembles.
+
+Thin wrappers over MDTraj that accept the common ways an ensemble is stored:
+a multi-model PDB (optionally gzipped), or a trajectory file plus a topology.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+
+def load_ensemble(path: str, top: Optional[str] = None):
+    """Load a conformational ensemble as an ``mdtraj.Trajectory``.
+
+    Parameters
+    ----------
+    path : str
+        A multi-model PDB (``.pdb`` / ``.pdb.gz``) or a trajectory file
+        (``.xtc``, ``.dcd``, ``.h5`` ...).
+    top : str, optional
+        Topology file (e.g. a ``.pdb``); required for trajectory formats that
+        do not embed topology.
+
+    Returns
+    -------
+    mdtraj.Trajectory
+    """
+    import mdtraj as md
+
+    if top is not None:
+        return md.load(path, top=top)
+    return md.load(path)
+
+
+def optionally_protonate(traj, method: str = "auto"):
+    """Return an ensemble guaranteed to be scorable for the H-bond term.
+
+    ``method``:
+
+    * ``"none"``   -- score as-is (geometric amide-H placement is used inside
+      the operator when explicit hydrogens are absent).
+    * ``"pdbfixer"`` -- repair missing heavy atoms and add real hydrogens with
+      PDBFixer/OpenMM (the ``hxprobe[fix]`` extra). Most faithful for raw
+      crystal or heavy-atom generated structures.
+    * ``"auto"`` (default) -- use PDBFixer if it is installed and hydrogens are
+      missing, otherwise fall back to ``"none"``.
+    """
+    from .protonate import has_explicit_hydrogens, pdbfixer_protonate
+
+    if method == "none":
+        return traj
+    if has_explicit_hydrogens(traj):
+        return traj
+    if method == "pdbfixer":
+        return pdbfixer_protonate(traj)
+    if method == "auto":
+        try:
+            return pdbfixer_protonate(traj)
+        except Exception:
+            return traj
+    raise ValueError(f"unknown protonation method: {method!r}")