@kent-tokyo/chematic 0.4.29 → 0.5.0

package/chematic_wasm.d.ts

@@ -593,6 +593,17 @@ export function canonical_tautomer_with_blocked_atoms_json(mol: MolHandle, block
  */
 export function cdxml_to_smiles_json(cdxml: string): string;
 
+/**
+ * CIP stereo assignments via the accurate hierarchical-digraph engine, as a JSON
+ * array of `{atomIdx, cipCode}` objects -- same shape as [`cip_assignments_json`],
+ * but merges the accurate engine's tetrahedral R/S (~99.6% oracle-stable agreement,
+ * see `docs/cip_accurate_rfc.md`) with legacy's E/Z and allene answers (the accurate
+ * engine computes neither). Atoms it can't resolve are omitted here -- see
+ * [`cip_unresolved_json`] -- never a silently-guessed label. Returns `"null"` on an
+ * internal engine error (budget-independent computations should not normally hit this).
+ */
+export function cip_assignments_accurate_json(mol: MolHandle): string;
+
 /**
  * CIP stereo assignments as a JSON array of `{atomIdx, cipCode}` objects.
  *
@@ -601,6 +612,15 @@ export function cdxml_to_smiles_json(cdxml: string): string;
  */
 export function cip_assignments_json(mol: MolHandle): string;
 
+/**
+ * Atoms the accurate CIP engine could not resolve a tetrahedral R/S for, as a JSON
+ * array of `{atomIdx, reason}` objects. `reason` is `"tied"` (a genuine CIP-rule tie,
+ * not a missing rule) or `"budgetExceeded"`. Always `[]` for the legacy engine (see
+ * [`cip_assignments_json`]) -- it never reports "I don't know". Returns `"null"` on
+ * an internal engine error.
+ */
+export function cip_unresolved_json(mol: MolHandle): string;
+
 /**
  * Compare multiple SMILES strings (up to 256 by default).
  * Accepts a delimiter-separated list (e.g., newline or comma).
@@ -1179,7 +1199,33 @@ export function mmff94_charges_json(mol: MolHandle): string;
 export function mmff94_charges_typed_json(mol: MolHandle): string;
 
 /**
- * Compute MMFF94 energy breakdown for current rule-based 3D geometry.
+ * Compute MMFF94 energy breakdown for EXPLICIT, caller-supplied 3D
+ * coordinates -- unlike `mmff94_energy_breakdown_json`, this reads the
+ * geometry the caller actually has (e.g. from `pdb_coords_json`,
+ * `generate_3d_coords_json`, `generate_3d_etkdg_coords_json`, or an
+ * externally computed conformer) instead of silently generating a fresh
+ * rule-based one, matching the Python binding's
+ * `mol.mmff94_energy_breakdown(coords)` contract (issue #90).
+ *
+ * `coords_json` -- JSON array of `[x,y,z]` arrays (Å), one per heavy atom,
+ * in the same atom order as `mol`.
+ *
+ * Returns JSON `{"bond":B,"angle":A,"stretch_bend":S,"torsion":T,"oop":O,
+ * "vdw":V,"electrostatic":E,"total":X}` at full `f64` round-trip precision
+ * (not rounded -- this API exists specifically for oracle comparison
+ * against the Python binding, where 4-decimal rounding would mask
+ * sub-1e-4 discrepancies), or `{"error":"<msg>"}` on malformed JSON, a
+ * non-finite coordinate, or a coordinate-count/atom-count mismatch. Never
+ * falls back to a generated conformer.
+ */
+export function mmff94_energy_breakdown_from_coords_json(mol: MolHandle, coords_json: string): string;
+
+/**
+ * Computes energy on an internally generated conformer.
+ * `MolHandle` stores topology only; coordinates previously read from PDB/XYZ
+ * are not used by this function.
+ * Use [`mmff94_energy_breakdown_from_coords_json`] for explicit coordinates.
+ *
  * Returns JSON: {"bond":B,"angle":A,"torsion":T,"vdw":V,"elec":E,"total":X} or {"error":"..."}.
  */
 export function mmff94_energy_breakdown_json(mol: MolHandle): string;
@@ -1259,7 +1305,10 @@ export function mol_from_cml(cml: string): MolHandle;
 export function mol_from_moljson(json: string): MolHandle;
 
 /**
- * Parse a PDB file and return a `MolHandle` (topology only; coordinates are discarded).
+ * Parse a PDB file and return a `MolHandle` (topology only; coordinates are
+ * discarded -- use [`pdb_coords_json`] to recover them in the SAME atom
+ * order, and [`mmff94_energy_breakdown_from_coords_json`] to score them
+ * without chematic regenerating a fresh conformer).
  *
  * Uses CONECT records for connectivity if present; otherwise infers bonds from
  * atom distances (the same heuristic as the internal `pdb_to_molecule` function).
@@ -1430,6 +1479,19 @@ export function parse_cxsmiles_json(s: string): string;
  */
 export function parse_smiles(s: string): MolHandle;
 
+/**
+ * Extract the atomic coordinates from a PDB block, in the SAME atom order
+ * `mol_from_pdb` returns topology for (both read the identical underlying
+ * parse via `parse_pdb_molecule_and_coords`, so atom-index correspondence
+ * between the two calls is structural, not just conventional -- issue #90).
+ *
+ * Returns JSON `[[x,y,z],...]` (full `f64` precision, not rounded -- for
+ * oracle comparison against the Python binding) or `{"error":"<msg>"}` --
+ * including when a coordinate field parsed to a non-finite value (see
+ * `coords_all_finite`'s doc comment), rather than emitting invalid JSON.
+ */
+export function pdb_coords_json(pdb: string): string;
+
 /**
  * PEOE_VSA descriptors (14 bins) as a JSON array.
  */
@@ -1872,7 +1934,9 @@ export interface InitOutput {
     readonly canonical_tautomer: (a: number) => number;
     readonly canonical_tautomer_with_blocked_atoms_json: (a: number, b: number, c: number) => [number, number];
     readonly cdxml_to_smiles_json: (a: number, b: number) => [number, number, number, number];
+    readonly cip_assignments_accurate_json: (a: number) => [number, number];
     readonly cip_assignments_json: (a: number) => [number, number];
+    readonly cip_unresolved_json: (a: number) => [number, number];
     readonly compare_molecules_batch_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly compare_molecules_json: (a: number, b: number, c: number, d: number) => [number, number, number, number];
     readonly conformer_ensemble_json: (a: number, b: number, c: number) => [number, number];
@@ -1965,6 +2029,7 @@ export interface InitOutput {
     readonly minimize_uff_json: (a: number, b: number, c: number, d: number, e: number) => [number, number];
     readonly mmff94_charges_json: (a: number) => [number, number];
     readonly mmff94_charges_typed_json: (a: number) => [number, number];
+    readonly mmff94_energy_breakdown_from_coords_json: (a: number, b: number, c: number) => [number, number];
     readonly mmff94_energy_breakdown_json: (a: number) => [number, number];
     readonly mmff94_partial_charges_json: (a: number) => [number, number];
     readonly mmp_pairs_json: (a: number, b: number) => [number, number, number, number];
@@ -2069,6 +2134,7 @@ export interface InitOutput {
     readonly parse_cxsmarts_json: (a: number, b: number) => [number, number, number, number];
     readonly parse_cxsmiles_json: (a: number, b: number) => [number, number, number, number];
     readonly parse_smiles: (a: number, b: number) => [number, number, number];
+    readonly pdb_coords_json: (a: number, b: number) => [number, number];
     readonly peoe_vsa_json: (a: number) => [number, number];
     readonly pharmacophore_features_json: (a: number) => [number, number];
     readonly pharmacophore_fp_2d_summary: (a: number) => [number, number];

package/chematic_wasm.js

@@ -1398,6 +1398,31 @@ export function cdxml_to_smiles_json(cdxml) {
     }
 }
 
+/**
+ * CIP stereo assignments via the accurate hierarchical-digraph engine, as a JSON
+ * array of `{atomIdx, cipCode}` objects -- same shape as [`cip_assignments_json`],
+ * but merges the accurate engine's tetrahedral R/S (~99.6% oracle-stable agreement,
+ * see `docs/cip_accurate_rfc.md`) with legacy's E/Z and allene answers (the accurate
+ * engine computes neither). Atoms it can't resolve are omitted here -- see
+ * [`cip_unresolved_json`] -- never a silently-guessed label. Returns `"null"` on an
+ * internal engine error (budget-independent computations should not normally hit this).
+ * @param {MolHandle} mol
+ * @returns {string}
+ */
+export function cip_assignments_accurate_json(mol) {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ret = wasm.cip_assignments_accurate_json(mol.__wbg_ptr);
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * CIP stereo assignments as a JSON array of `{atomIdx, cipCode}` objects.
  *
@@ -1420,6 +1445,29 @@ export function cip_assignments_json(mol) {
     }
 }
 
+/**
+ * Atoms the accurate CIP engine could not resolve a tetrahedral R/S for, as a JSON
+ * array of `{atomIdx, reason}` objects. `reason` is `"tied"` (a genuine CIP-rule tie,
+ * not a missing rule) or `"budgetExceeded"`. Always `[]` for the legacy engine (see
+ * [`cip_assignments_json`]) -- it never reports "I don't know". Returns `"null"` on
+ * an internal engine error.
+ * @param {MolHandle} mol
+ * @returns {string}
+ */
+export function cip_unresolved_json(mol) {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ret = wasm.cip_unresolved_json(mol.__wbg_ptr);
+        deferred1_0 = ret[0];
+        deferred1_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+    }
+}
+
 /**
  * Compare multiple SMILES strings (up to 256 by default).
  * Accepts a delimiter-separated list (e.g., newline or comma).
@@ -2922,7 +2970,50 @@ export function mmff94_charges_typed_json(mol) {
 }
 
 /**
- * Compute MMFF94 energy breakdown for current rule-based 3D geometry.
+ * Compute MMFF94 energy breakdown for EXPLICIT, caller-supplied 3D
+ * coordinates -- unlike `mmff94_energy_breakdown_json`, this reads the
+ * geometry the caller actually has (e.g. from `pdb_coords_json`,
+ * `generate_3d_coords_json`, `generate_3d_etkdg_coords_json`, or an
+ * externally computed conformer) instead of silently generating a fresh
+ * rule-based one, matching the Python binding's
+ * `mol.mmff94_energy_breakdown(coords)` contract (issue #90).
+ *
+ * `coords_json` -- JSON array of `[x,y,z]` arrays (Å), one per heavy atom,
+ * in the same atom order as `mol`.
+ *
+ * Returns JSON `{"bond":B,"angle":A,"stretch_bend":S,"torsion":T,"oop":O,
+ * "vdw":V,"electrostatic":E,"total":X}` at full `f64` round-trip precision
+ * (not rounded -- this API exists specifically for oracle comparison
+ * against the Python binding, where 4-decimal rounding would mask
+ * sub-1e-4 discrepancies), or `{"error":"<msg>"}` on malformed JSON, a
+ * non-finite coordinate, or a coordinate-count/atom-count mismatch. Never
+ * falls back to a generated conformer.
+ * @param {MolHandle} mol
+ * @param {string} coords_json
+ * @returns {string}
+ */
+export function mmff94_energy_breakdown_from_coords_json(mol, coords_json) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        _assertClass(mol, MolHandle);
+        const ptr0 = passStringToWasm0(coords_json, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.mmff94_energy_breakdown_from_coords_json(mol.__wbg_ptr, ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
+/**
+ * Computes energy on an internally generated conformer.
+ * `MolHandle` stores topology only; coordinates previously read from PDB/XYZ
+ * are not used by this function.
+ * Use [`mmff94_energy_breakdown_from_coords_json`] for explicit coordinates.
+ *
  * Returns JSON: {"bond":B,"angle":A,"torsion":T,"vdw":V,"elec":E,"total":X} or {"error":"..."}.
  * @param {MolHandle} mol
  * @returns {string}
@@ -3138,7 +3229,10 @@ export function mol_from_moljson(json) {
 }
 
 /**
- * Parse a PDB file and return a `MolHandle` (topology only; coordinates are discarded).
+ * Parse a PDB file and return a `MolHandle` (topology only; coordinates are
+ * discarded -- use [`pdb_coords_json`] to recover them in the SAME atom
+ * order, and [`mmff94_energy_breakdown_from_coords_json`] to score them
+ * without chematic regenerating a fresh conformer).
  *
  * Uses CONECT records for connectivity if present; otherwise infers bonds from
  * atom distances (the same heuristic as the internal `pdb_to_molecule` function).
@@ -3608,6 +3702,34 @@ export function parse_smiles(s) {
     return MolHandle.__wrap(ret[0]);
 }
 
+/**
+ * Extract the atomic coordinates from a PDB block, in the SAME atom order
+ * `mol_from_pdb` returns topology for (both read the identical underlying
+ * parse via `parse_pdb_molecule_and_coords`, so atom-index correspondence
+ * between the two calls is structural, not just conventional -- issue #90).
+ *
+ * Returns JSON `[[x,y,z],...]` (full `f64` precision, not rounded -- for
+ * oracle comparison against the Python binding) or `{"error":"<msg>"}` --
+ * including when a coordinate field parsed to a non-finite value (see
+ * `coords_all_finite`'s doc comment), rather than emitting invalid JSON.
+ * @param {string} pdb
+ * @returns {string}
+ */
+export function pdb_coords_json(pdb) {
+    let deferred2_0;
+    let deferred2_1;
+    try {
+        const ptr0 = passStringToWasm0(pdb, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ret = wasm.pdb_coords_json(ptr0, len0);
+        deferred2_0 = ret[0];
+        deferred2_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred2_0, deferred2_1, 1);
+    }
+}
+
 /**
  * PEOE_VSA descriptors (14 bins) as a JSON array.
  * @param {MolHandle} mol

package/package.json

@@ -5,7 +5,7 @@
     "kent-tokyo <kent-tokyo@users.noreply.github.com>"
   ],
   "description": "WebAssembly bindings for chematic — use chematic from JavaScript/TypeScript",
-  "version": "0.4.29",
+  "version": "0.5.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",