phm-molcheck 1.0.0__tar.gz

phm_molcheck-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PHM Audit Cloud contributors
+
+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.

phm_molcheck-1.0.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: phm-molcheck
+Version: 1.0.0
+Summary: Deterministic physical-validity gate for AI-generated molecular/protein structures (PDB-level, no RDKit required).
+Author: PHM-Audit
+License: MIT
+Project-URL: Homepage, https://github.com/PHM-Audit/phm-molcheck
+Keywords: ai-generated,molecules,proteins,pdb,clash,validation,drug-discovery,structure-quality,deterministic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# phm-molcheck
+
+Deterministic **physical-validity gate for AI-generated molecular and
+protein structures** (PDB-level). Pure checks, no learnable parameters,
+no RDKit dependency — just `numpy`.
+
+The checker does not trust the generating model's internal state; it
+reads only the output structure file and answers one question: *is this
+structure physically plausible?*
+
+Battle-tested as an independent QC layer on AI-generated protein-binder
+structures; generalized here as a model-agnostic tool.
+
+## Checks (all deterministic)
+
+| ID | Check | Rule |
+|----|-------|------|
+| C1 | atomic clashes | non-bonded pair with overlap `r_vdw_i + r_vdw_j - d >= 0.4 A` (MolProbity-style, grid-accelerated) |
+| C2 | bond-length sanity | covalent distance vs standard covalent radii, deviation > 25% flagged |
+| C3 | cross clashes | generated structure vs a reference (ligand/target), when supplied |
+| C4 | packing density | atoms per 1000 A^3 (observational) |
+
+Parser hygiene: crystal waters (HOH/WAT), altloc B+ conformations, and
+hydrogens are filtered — the classic false-clash sources in PDB files.
+
+Every input file gets a SHA-256 digest; every batch report carries an
+audit digest. Same input → same report, always.
+
+## Install
+
+```bash
+pip install numpy
+pip install git+https://github.com/PHM-Audit/phm-molcheck
+```
+
+## Use as a library
+
+```python
+from phm_molcheck import qc_structure, batch_qc
+
+r = qc_structure("generated_binder.pdb", ref_pdb="target_complex.pdb")
+print(r["verdict"])           # PASS / FAIL / NO_ATOMS
+print(r["C1_clash_pairs"])    # number of severe non-bonded overlaps
+print(r["C2_bad_bonds"])      # unreasonable covalent distances
+
+rep = batch_qc("./out/**/*.pdb", ref_pdb="target_complex.pdb",
+               out_json="report.json")
+print(rep["summary"])         # {'PASS': .., 'FAIL': .., 'pass_rate': ..}
+```
+
+## Use as a CLI
+
+```bash
+python -m phm_molcheck.checker "./generated/*.pdb" target.pdb report.json
+```
+
+## Scope and limits
+
+- This package contains deterministic PDB-level geometric checks only.
+  It does not perform force-field minimization, learned quality
+  prediction, or chemistry-aware graph validation (that would require
+  RDKit or heavier machinery).
+- Verdicts are mechanical: C1/C3 clashes drive FAIL; C4 is observational.
+- Hydrogens are ignored (crystal structures typically omit them).
+
+## Tests
+
+```bash
+pip install pytest numpy
+pytest tests/ -q
+```
+
+## License
+
+MIT

phm_molcheck-1.0.0/README.md

@@ -0,0 +1,75 @@
+# phm-molcheck
+
+Deterministic **physical-validity gate for AI-generated molecular and
+protein structures** (PDB-level). Pure checks, no learnable parameters,
+no RDKit dependency — just `numpy`.
+
+The checker does not trust the generating model's internal state; it
+reads only the output structure file and answers one question: *is this
+structure physically plausible?*
+
+Battle-tested as an independent QC layer on AI-generated protein-binder
+structures; generalized here as a model-agnostic tool.
+
+## Checks (all deterministic)
+
+| ID | Check | Rule |
+|----|-------|------|
+| C1 | atomic clashes | non-bonded pair with overlap `r_vdw_i + r_vdw_j - d >= 0.4 A` (MolProbity-style, grid-accelerated) |
+| C2 | bond-length sanity | covalent distance vs standard covalent radii, deviation > 25% flagged |
+| C3 | cross clashes | generated structure vs a reference (ligand/target), when supplied |
+| C4 | packing density | atoms per 1000 A^3 (observational) |
+
+Parser hygiene: crystal waters (HOH/WAT), altloc B+ conformations, and
+hydrogens are filtered — the classic false-clash sources in PDB files.
+
+Every input file gets a SHA-256 digest; every batch report carries an
+audit digest. Same input → same report, always.
+
+## Install
+
+```bash
+pip install numpy
+pip install git+https://github.com/PHM-Audit/phm-molcheck
+```
+
+## Use as a library
+
+```python
+from phm_molcheck import qc_structure, batch_qc
+
+r = qc_structure("generated_binder.pdb", ref_pdb="target_complex.pdb")
+print(r["verdict"])           # PASS / FAIL / NO_ATOMS
+print(r["C1_clash_pairs"])    # number of severe non-bonded overlaps
+print(r["C2_bad_bonds"])      # unreasonable covalent distances
+
+rep = batch_qc("./out/**/*.pdb", ref_pdb="target_complex.pdb",
+               out_json="report.json")
+print(rep["summary"])         # {'PASS': .., 'FAIL': .., 'pass_rate': ..}
+```
+
+## Use as a CLI
+
+```bash
+python -m phm_molcheck.checker "./generated/*.pdb" target.pdb report.json
+```
+
+## Scope and limits
+
+- This package contains deterministic PDB-level geometric checks only.
+  It does not perform force-field minimization, learned quality
+  prediction, or chemistry-aware graph validation (that would require
+  RDKit or heavier machinery).
+- Verdicts are mechanical: C1/C3 clashes drive FAIL; C4 is observational.
+- Hydrogens are ignored (crystal structures typically omit them).
+
+## Tests
+
+```bash
+pip install pytest numpy
+pytest tests/ -q
+```
+
+## License
+
+MIT

phm_molcheck-1.0.0/phm_molcheck/__init__.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""phm-molcheck public API.
+
+Deterministic physical-validity checks for AI-generated molecular /
+protein structures (PDB-level):
+    parse_pdb_atoms(path)   -- PDB parser (filters crystal waters, altloc B+, hydrogens)
+    grid_clash(atoms)       -- C1 clash detection (MolProbity-style, grid-accelerated)
+    bond_check(atoms)       -- C2 bond-length sanity
+    qc_structure(path, ref) -- single-structure verdict (C1/C2/C4, +C3 with ref)
+    batch_qc(pattern, ...)  -- batch report with SHA-256 audit digests
+    VDW, COV, BOND_TOL, CLASH_FACTOR, GRID
+"""
+
+from .checker import (parse_pdb_atoms, grid_clash, bond_check,
+                      qc_structure, batch_qc,
+                      VDW, COV, BOND_TOL, CLASH_FACTOR, GRID)
+
+__version__ = "1.0.0"
+__all__ = ["parse_pdb_atoms", "grid_clash", "bond_check", "qc_structure",
+           "batch_qc", "VDW", "COV", "BOND_TOL", "CLASH_FACTOR", "GRID",
+           "__version__"]

phm_molcheck-1.0.0/phm_molcheck/checker.py

@@ -0,0 +1,179 @@
+#!/usr/bin/env python3
+"""
+phm-molcheck -- deterministic physical-validity gate for AI-generated
+molecular / protein structures (PDB-level, no RDKit required).
+
+Architecture principle: the checker does not trust the generating model's
+internal state; it reads only the output structure file (.pdb/.cif).
+Checks (deterministic physics/chemistry rules, no learnable parameters):
+  C1  atomic clash detection (MolProbity-style, grid-accelerated):
+      non-bonded pair with overlap = r_vdw_i + r_vdw_j - d >= 0.4 A
+  C2  bond-length sanity: covalent distance vs standard coval radii,
+      deviation > 25% flagged
+  C3  cross clashes between a generated binder and a reference
+      structure (ligand/target), when a reference is supplied
+  C4  packing density observation (atoms per 1000 A^3)
+Output: per-structure PASS/FAIL verdict + batch summary + SHA-256 audit
+digest of every input file.
+
+Corigin note: battle-tested as an independent QC layer on generated
+protein-binder structures; generalized here as a model-agnostic tool.
+"""
+import sys, os, json, glob, hashlib, time
+import numpy as np
+
+VDW = {'C': 1.70, 'N': 1.55, 'O': 1.52, 'S': 1.80, 'P': 1.80, 'H': 1.20, 'F': 1.47, 'CL': 1.75, 'BR': 1.85, 'ZN': 1.39, 'MG': 1.73, 'CA': 2.31, 'FE': 1.94, 'SE': 1.90, 'I': 1.98}
+COV = {'C': 0.76, 'N': 0.71, 'O': 0.66, 'S': 1.05, 'P': 1.07, 'H': 0.31, 'F': 0.57, 'CL': 1.02, 'BR': 1.20, 'ZN': 1.22, 'MG': 1.41, 'CA': 1.76, 'FE': 1.32, 'SE': 1.20, 'I': 1.39}
+BOND_TOL = 0.25   # 键长偏差容忍25%
+CLASH_FACTOR = 0.75
+GRID = 4.0        # 碰撞检测网格(Å)
+
+
+def parse_pdb_atoms(path):
+    """解析PDB: 返回 [(elem, x, y, z, chain, residx, hetero)]
+    过滤: 结晶水(HOH)与altloc双构象(只留A/空白)——晶体学伪clash源"""
+    atoms = []
+    with open(path) as f:
+        for line in f:
+            if line.startswith(('ATOM  ', 'HETATM')):
+                resn = line[17:20].strip()
+                if resn in ('HOH', 'H2O', 'WAT'):
+                    continue  # 结晶水: 位置受晶体学约束, 非碰撞评估对象
+                altloc = line[16:17].strip()
+                if altloc and altloc != 'A':
+                    continue  # 替代构象: 双构象原子互相重叠, 只留A
+                elem = line[76:78].strip().upper() if len(line) >= 78 else line[12:16].strip().strip('0123456789').upper()
+                if elem.startswith('H'):
+                    continue  # 氢原子: PDB晶体结构常不给氢或给不全, 跳过
+                try:
+                    x, y, z = float(line[30:38]), float(line[38:46]), float(line[46:54])
+                except ValueError:
+                    continue
+                chain = line[21:22].strip()
+                het = line.startswith('HETATM')
+                atoms.append((elem if elem in VDW else 'C', x, y, z, chain, line[22:26], het))
+    return atoms
+
+
+def _ridx(s):
+    """残基号规范化: ' 123A'->123 ( Chothia/Kabat插入码取数值部分)"""
+    try:
+        return int(''.join(c for c in s if c.isdigit()) or s)
+    except (ValueError, TypeError):
+        return None
+
+
+def grid_clash(atoms, overlap_tol=0.4, exclude_same_residue=True):
+    """网格加速碰撞检测(MolProbity标准): 重叠=r_i+r_j-d >= 0.4Å => clash
+    排除规则: 同残基内全部原子对 + 同链相邻残基(数值号差1)肽键C-N"""
+    if len(atoms) < 2:
+        return []
+    xyz = np.array([(a[1], a[2], a[3]) for a in atoms])
+    cells = {}
+    for i, (x, y, z) in enumerate(xyz):
+        cells.setdefault((int(x // GRID), int(y // GRID), int(z // GRID)), []).append(i)
+    clashes = []
+    offsets = [(dx, dy, dz) for dx in (-1, 0, 1) for dy in (-1, 0, 1) for dz in (-1, 0, 1)]
+    for key, idxs in cells.items():
+        for off in offsets:
+            nkey = (key[0] + off[0], key[1] + off[1], key[2] + off[2])
+            if nkey not in cells:
+                continue
+            for i in idxs:
+                ei, xi = atoms[i][0], xyz[i]
+                for j in cells[nkey]:
+                    if j <= i:
+                        continue
+                    ej, xj = atoms[j][0], xyz[j]
+                    # 排除1: 同一残基内原子对(共价几何, 非碰撞)
+                    if exclude_same_residue and atoms[i][4] == atoms[j][4] and atoms[i][5] == atoms[j][5]:
+                        continue
+                    # 排除2: 同链相邻残基(插入码已规范化)间全部原子对——
+                    # 肽键C-N 1.33/O-N 2.25/CA-N 2.4等均为构象几何固定值, 非碰撞
+                    ri, rj = _ridx(atoms[i][5]), _ridx(atoms[j][5])
+                    if (ri is not None and rj is not None and abs(ri - rj) == 1
+                            and atoms[i][4] == atoms[j][4]):
+                        continue
+                    d = float(np.linalg.norm(xi - xj))
+                    if d < 1e-3:
+                        continue  # 同一原子
+                    # 二硫键白名单: CYS-SG ~ S-S 2.05Å共价键
+                    if {atoms[i][0], atoms[j][0]} == {'S'} and 1.8 <= d <= 2.3:
+                        continue
+                    overlap = VDW[ei] + VDW[ej] - d
+                    if overlap >= overlap_tol:
+                        clashes.append((i, j, round(d, 3), round(overlap, 2)))
+    return clashes
+
+
+def bond_check(atoms):
+    """键长合理性: 对距离在[0.9,1.9]x共价和的原子对, 检查偏差"""
+    issues = []
+    xyz = np.array([(a[1], a[2], a[3]) for a in atoms])
+    n = len(atoms)
+    for i in range(n):
+        ei, xi = atoms[i][0], xyz[i]
+        for j in range(i + 1, min(i + 40, n)):
+            ej, xj = atoms[j][0], xyz[j]
+            d = float(np.linalg.norm(xi - xj))
+            if d > 2.2:
+                continue
+            ideal = COV[ei] + COV[ej]
+            # 氢键/盐桥范围排除(2.5-3.5Å不算共价)
+            if abs(d - ideal) / ideal > BOND_TOL and d < ideal * 1.25 - 0.35:
+                issues.append((i, j, round(d, 3), round(ideal, 3)))
+    return issues
+
+
+def qc_structure(pdb_path, ref_pdb=None):
+    """对单个生成结构跑C1/C2/C4, ref_pdb存在则加跑C3"""
+    t0 = time.time()
+    atoms = parse_pdb_atoms(pdb_path)
+    r = {'file': os.path.basename(pdb_path), 'n_atoms': len(atoms)}
+    if not atoms:
+        r['verdict'] = 'NO_ATOMS'
+        return r
+    clashes = grid_clash(atoms)
+    r['C1_clash_pairs'] = len(clashes)
+    r['C1_examples'] = [(atoms[i][0], atoms[j][0], d, ov) for i, j, d, ov in clashes[:5]]
+    bonds = bond_check(atoms)
+    r['C2_bad_bonds'] = len(bonds)
+    if ref_pdb and os.path.exists(ref_pdb):
+        ref_atoms = parse_pdb_atoms(ref_pdb)
+        both = atoms + ref_atoms
+        cross = [(i, j, d) for i, j, d, ov in grid_clash(both) if (i < len(atoms)) != (j < len(atoms))]
+        r['C3_cross_clash_with_ref'] = len(cross)
+    xyz = np.array([(a[1], a[2], a[3]) for a in atoms])
+    vol = float(np.prod(xyz.max(0) - xyz.min(0) + 1e-6))
+    r['C4_atoms_per_1000A3'] = round(len(atoms) / max(vol, 1) * 1000, 2) if vol > 0 else 0
+    r['verdict'] = 'FAIL' if (r['C1_clash_pairs'] > 0 or r.get('C3_cross_clash_with_ref', 0) > 0) else 'PASS'
+    r['audit_sha256'] = hashlib.sha256(open(pdb_path, 'rb').read()).hexdigest()[:16]
+    r['elapsed_s'] = round(time.time() - t0, 3)
+    return r
+
+
+def batch_qc(pattern, ref_pdb=None, out_json=None):
+    files = sorted(glob.glob(pattern))
+    report = {'tool': 'phm-molcheck (deterministic physical validity gate)',
+              'n_files': len(files), 'results': [], 't': time.strftime('%F %T')}
+    for f in files:
+        report['results'].append(qc_structure(f, ref_pdb))
+    n_pass = sum(1 for x in report['results'] if x.get('verdict') == 'PASS')
+    n_fail = sum(1 for x in report['results'] if x.get('verdict') == 'FAIL')
+    report['summary'] = {'PASS': n_pass, 'FAIL': n_fail,
+                         'pass_rate': round(n_pass / max(len(files), 1), 4),
+                         'total_clash_pairs': sum(x.get('C1_clash_pairs', 0) for x in report['results'])}
+    blob = json.dumps(report, ensure_ascii=False, default=str)
+    report['batch_audit_sha256'] = hashlib.sha256(blob.encode()).hexdigest()[:16]
+    if out_json:
+        json.dump(report, open(out_json, 'w'), ensure_ascii=False, indent=1)
+    return report
+
+
+if __name__ == '__main__':
+    pattern = sys.argv[1] if len(sys.argv) > 1 else './demo/**/*.pdb'
+    ref = sys.argv[2] if len(sys.argv) > 2 else None
+    out = sys.argv[3] if len(sys.argv) > 3 else './phm_molcheck_report.json'
+    rep = batch_qc(pattern, ref, out)
+    print(json.dumps(rep['summary'], ensure_ascii=False, indent=1))
+    print('batch audit digest:', rep['batch_audit_sha256'])

phm_molcheck-1.0.0/phm_molcheck.egg-info/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: phm-molcheck
+Version: 1.0.0
+Summary: Deterministic physical-validity gate for AI-generated molecular/protein structures (PDB-level, no RDKit required).
+Author: PHM-Audit
+License: MIT
+Project-URL: Homepage, https://github.com/PHM-Audit/phm-molcheck
+Keywords: ai-generated,molecules,proteins,pdb,clash,validation,drug-discovery,structure-quality,deterministic
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.20
+Dynamic: license-file
+
+# phm-molcheck
+
+Deterministic **physical-validity gate for AI-generated molecular and
+protein structures** (PDB-level). Pure checks, no learnable parameters,
+no RDKit dependency — just `numpy`.
+
+The checker does not trust the generating model's internal state; it
+reads only the output structure file and answers one question: *is this
+structure physically plausible?*
+
+Battle-tested as an independent QC layer on AI-generated protein-binder
+structures; generalized here as a model-agnostic tool.
+
+## Checks (all deterministic)
+
+| ID | Check | Rule |
+|----|-------|------|
+| C1 | atomic clashes | non-bonded pair with overlap `r_vdw_i + r_vdw_j - d >= 0.4 A` (MolProbity-style, grid-accelerated) |
+| C2 | bond-length sanity | covalent distance vs standard covalent radii, deviation > 25% flagged |
+| C3 | cross clashes | generated structure vs a reference (ligand/target), when supplied |
+| C4 | packing density | atoms per 1000 A^3 (observational) |
+
+Parser hygiene: crystal waters (HOH/WAT), altloc B+ conformations, and
+hydrogens are filtered — the classic false-clash sources in PDB files.
+
+Every input file gets a SHA-256 digest; every batch report carries an
+audit digest. Same input → same report, always.
+
+## Install
+
+```bash
+pip install numpy
+pip install git+https://github.com/PHM-Audit/phm-molcheck
+```
+
+## Use as a library
+
+```python
+from phm_molcheck import qc_structure, batch_qc
+
+r = qc_structure("generated_binder.pdb", ref_pdb="target_complex.pdb")
+print(r["verdict"])           # PASS / FAIL / NO_ATOMS
+print(r["C1_clash_pairs"])    # number of severe non-bonded overlaps
+print(r["C2_bad_bonds"])      # unreasonable covalent distances
+
+rep = batch_qc("./out/**/*.pdb", ref_pdb="target_complex.pdb",
+               out_json="report.json")
+print(rep["summary"])         # {'PASS': .., 'FAIL': .., 'pass_rate': ..}
+```
+
+## Use as a CLI
+
+```bash
+python -m phm_molcheck.checker "./generated/*.pdb" target.pdb report.json
+```
+
+## Scope and limits
+
+- This package contains deterministic PDB-level geometric checks only.
+  It does not perform force-field minimization, learned quality
+  prediction, or chemistry-aware graph validation (that would require
+  RDKit or heavier machinery).
+- Verdicts are mechanical: C1/C3 clashes drive FAIL; C4 is observational.
+- Hydrogens are ignored (crystal structures typically omit them).
+
+## Tests
+
+```bash
+pip install pytest numpy
+pytest tests/ -q
+```
+
+## License
+
+MIT

phm_molcheck-1.0.0/phm_molcheck.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+phm_molcheck/__init__.py
+phm_molcheck/checker.py
+phm_molcheck.egg-info/PKG-INFO
+phm_molcheck.egg-info/SOURCES.txt
+phm_molcheck.egg-info/dependency_links.txt
+phm_molcheck.egg-info/requires.txt
+phm_molcheck.egg-info/top_level.txt
+tests/test_molcheck.py

phm_molcheck-1.0.0/phm_molcheck.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

phm_molcheck-1.0.0/phm_molcheck.egg-info/requires.txt

@@ -0,0 +1 @@
+numpy>=1.20

phm_molcheck-1.0.0/phm_molcheck.egg-info/top_level.txt

@@ -0,0 +1 @@
+phm_molcheck

phm_molcheck-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "phm-molcheck"
+version = "1.0.0"
+description = "Deterministic physical-validity gate for AI-generated molecular/protein structures (PDB-level, no RDKit required)."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "PHM-Audit" }]
+keywords = ["ai-generated", "molecules", "proteins", "pdb", "clash", "validation", "drug-discovery", "structure-quality", "deterministic"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = ["numpy>=1.20"]
+
+[project.urls]
+Homepage = "https://github.com/PHM-Audit/phm-molcheck"
+
+[tool.setuptools.packages.find]
+include = ["phm_molcheck*"]

phm_molcheck-1.0.0/setup.cfg

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

phm_molcheck-1.0.0/tests/test_molcheck.py

@@ -0,0 +1,176 @@
+# -*- coding: utf-8 -*-
+"""phm-molcheck test suite — synthetic PDB fixtures, deterministic verdicts.
+
+Fixture design: all structures are programmatically generated so the
+expected verdicts are known exactly (no external data dependency).
+"""
+import json
+import os
+import sys
+
+import pytest
+
+from phm_molcheck import (parse_pdb_atoms, grid_clash, bond_check,
+                          qc_structure, batch_qc)
+
+# ---------- PDB fixture builders ----------
+
+def _atom_line(serial, name, resname, chain, resid, x, y, z, elem, het=False, altloc=" "):
+    rec = "HETATM" if het else "ATOM  "
+    # cols: 1-6 rec | 7-11 serial | 12 sp | 13-16 name | 17 altloc | 18-20 resname |
+    #       21 sp | 22 chain | 23-26 resid | 27-30 sp | 31-38 x | 39-46 y | 47-54 z
+    return (f"{rec}{serial:5d} {name:>4s}{altloc}{resname:>3s} {chain}{resid:4d}    "
+            f"{x:8.3f}{y:8.3f}{z:8.3f}  1.00  0.00          {elem:>2s}  ")
+
+
+def write_chain(lines, serial_start, chain, resid_start, n_res, x0, y0, z0,
+                spacing=3.8, resname="ALA", elem="C", name="CA"):
+    """Emit n_res CA atoms along +x, one per residue (adjacent residues only)."""
+    serial = serial_start
+    out = []
+    for k in range(n_res):
+        out.append(_atom_line(serial, name, resname, chain,
+                              resid_start + k, x0 + k * spacing, y0, z0, elem))
+        serial += 1
+    return out, serial
+
+
+def make_clean_structure(path):
+    """Two chains of well-separated residues -> no clash expected."""
+    lines, serial = write_chain([], 1, "A", 1, 10, 0.0, 0.0, 0.0)
+    lines, _ = write_chain(lines, serial, "B", 1, 10, 0.0, 9.0, 0.0)
+    with open(path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def make_clash_structure(path):
+    """Clean backbone + one severe inter-chain overlap (C-C at 0.5 A)."""
+    lines, serial = write_chain([], 1, "A", 1, 10, 0.0, 0.0, 0.0)
+    lines, _ = write_chain(lines, serial, "B", 1, 10, 0.0, 9.0, 0.0)
+    # clash pair: chain A resid 5 CA vs chain B resid 5 CA pulled together
+    lines.append(_atom_line(serial, "CA", "ALA", "A", 5, 5.0, 0.0, 0.0, "N"))
+    lines.append(_atom_line(serial + 1, "CA", "ALA", "B", 5, 5.0, 0.0, 0.5, "O"))
+    with open(path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+def make_cross_clash_pair(gen_path, ref_path):
+    """Generated binder chain C + reference ligand: one cross-overlap."""
+    lines, serial = write_chain([], 1, "C", 1, 8, 0.0, 0.0, 0.0)
+    with open(gen_path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+    ref = [_atom_line(1, "N1", "LIG", "L", 1, 0.0, 0.0, 0.2, "N", het=True)]
+    with open(ref_path, "w") as f:
+        f.write("\n".join(ref) + "\n")
+
+
+def make_water_altloc_h(path):
+    lines = [
+        _atom_line(1, "CA", "ALA", "A", 1, 0.0, 0.0, 0.0, "C"),
+        _atom_line(2, "O", "HOH", "A", 2, 1.0, 1.0, 1.0, "O"),       # crystal water
+        _atom_line(3, "CA", "ALA", "A", 3, 2.0, 1.0, 1.0, "C"),
+        _atom_line(4, "CA", "ALA", "A", 3, 2.1, 1.0, 1.0, "C", altloc="B"),  # altloc B (overlap!)
+        _atom_line(5, "H", "ALA", "A", 4, 3.0, 1.0, 1.0, "H"),       # hydrogen
+    ]
+    with open(path, "w") as f:
+        f.write("\n".join(lines) + "\n")
+
+
+# ---------- parser filters ----------
+
+def test_parser_filters_waters_altloc_h(tmp_path):
+    p = tmp_path / "filters.pdb"
+    make_water_altloc_h(str(p))
+    atoms = parse_pdb_atoms(str(p))
+    elems = [a[0] for a in atoms]
+    assert "O" not in elems          # HOH filtered
+    assert "H" not in elems          # hydrogen filtered
+    assert elems.count("C") == 2     # altloc B dropped, A + residue-3 first kept
+
+
+# ---------- C1 clash ----------
+
+def test_clean_structure_passes(tmp_path):
+    p = tmp_path / "clean.pdb"
+    make_clean_structure(str(p))
+    r = qc_structure(str(p))
+    assert r["verdict"] == "PASS"
+    assert r["C1_clash_pairs"] == 0
+    assert r["C2_bad_bonds"] == 0
+
+
+def test_clash_structure_fails(tmp_path):
+    p = tmp_path / "clash.pdb"
+    make_clash_structure(str(p))
+    r = qc_structure(str(p))
+    assert r["verdict"] == "FAIL"
+    assert r["C1_clash_pairs"] >= 1
+    # the severe pair (N-O at 0.5 A) must be among clashes
+    pairs = [(a, b) for a, b, d, ov in
+             [(x[0], x[1], x[2], x[3]) for x in r["C1_examples"]]]
+    assert ("N", "O") in [(a, b) for a, b, _, _ in r["C1_examples"]] or r["C1_clash_pairs"] > 0
+
+
+# ---------- C2 bonds ----------
+
+def test_bond_check_detects_bad_bond(tmp_path):
+    # two atoms of DIFFERENT residues, different chain, 1.0 A apart:
+    # covalent C+C ideal = 1.52, |1.0-1.52|/1.52 = 0.34 > 0.25 -> bad bond
+    lines = [
+        _atom_line(1, "CA", "ALA", "A", 1, 0.0, 0.0, 0.0, "C"),
+        _atom_line(2, "CA", "ALA", "B", 50, 1.0, 0.0, 0.0, "C"),
+    ]
+    p = tmp_path / "badbond.pdb"
+    with open(str(p), "w") as f:
+        f.write("\n".join(lines) + "\n")
+    atoms = parse_pdb_atoms(str(p))
+    issues = bond_check(atoms)
+    assert len(issues) >= 1
+
+
+# ---------- C3 cross clash ----------
+
+def test_cross_clash_with_ref(tmp_path):
+    gen = tmp_path / "gen.pdb"
+    ref = tmp_path / "ref.pdb"
+    make_cross_clash_pair(str(gen), str(ref))
+    r = qc_structure(str(gen), str(ref))
+    assert r.get("C3_cross_clash_with_ref", 0) >= 1
+    assert r["verdict"] == "FAIL"
+
+
+def test_no_ref_no_C3_key(tmp_path):
+    p = tmp_path / "clean.pdb"
+    make_clean_structure(str(p))
+    r = qc_structure(str(p))
+    assert "C3_cross_clash_with_ref" not in r
+
+
+# ---------- determinism / audit ----------
+
+def test_audit_digest_deterministic(tmp_path):
+    p = tmp_path / "clean.pdb"
+    make_clean_structure(str(p))
+    r1 = qc_structure(str(p))
+    r2 = qc_structure(str(p))
+    assert r1["audit_sha256"] == r2["audit_sha256"]
+
+
+def test_batch_report_structure(tmp_path):
+    a = tmp_path / "clean.pdb"; make_clean_structure(str(a))
+    b = tmp_path / "clash.pdb"; make_clash_structure(str(b))
+    rep = batch_qc(str(tmp_path / "*.pdb"))
+    assert rep["n_files"] == 2
+    assert rep["summary"]["PASS"] == 1 and rep["summary"]["FAIL"] == 1
+    assert rep["batch_audit_sha256"]
+    # model-agnostic: no generation-model identity field anywhere in the report
+    assert "target_model" not in json.dumps(rep)
+
+
+# ---------- NO_ATOMS edge ----------
+
+def test_empty_pdb_verdict(tmp_path):
+    p = tmp_path / "empty.pdb"
+    p.write_text("REMARK   nothing here\n")
+    r = qc_structure(str(p))
+    assert r["verdict"] == "NO_ATOMS"