@kent-tokyo/chematic 0.18.0 → 0.20.0

package/README.md

@@ -122,13 +122,34 @@ const response = JSON.parse(embed_pipeline_v2_json(mol, JSON.stringify({
   forceFieldPolicy: "none",
   forceFieldMaxIterations: 200,
   gateMmff94TorsionOop: false,
+  gateMmff94StretchBend: false,
   ringTorsionPolicy: "fail_closed",
   totalTimeoutMs: null,
+  enforceChirality: false,
+  expandImplicitHThroughPipeline: false,
 })));
 // response.ok, response.result / response.error — same shape as
 // Mol.embed_pipeline_v2() in the Python binding.
 ```
 
+For ring-fused declared stereocenters (e.g. testosterone, cholesterol) that
+`enforceChirality` alone can't repair, `stereoPolicy: "repair_and_verify"` +
+`enforceChirality: true` + `expandImplicitHThroughPipeline: true` are needed
+*together* (issue #291/#383) — `pipeline_v2_stereo_safe_config_json` builds
+that exact combination so a caller can't set one and forget another:
+
+```js
+const configResponse = JSON.parse(pipeline_v2_stereo_safe_config_json(
+  "mmff94_with_uff_fallback", "fail_closed"
+));
+// configResponse.ok, configResponse.config (or configResponse.error, same
+// shape as embed_pipeline_v2_json's own error) — modify configResponse.config
+// (e.g. a different embedSeed) before passing it to embed_pipeline_v2_json.
+const response = JSON.parse(
+  embed_pipeline_v2_json(mol, JSON.stringify(configResponse.config))
+);
+```
+
 Verified working end-to-end under real WASM (both `wasm-pack --target nodejs`
 and `--target web`, the latter being what this package's npm build actually
 uses) — success, typed-failure, and typed-timeout paths all return real

package/chematic_wasm.d.ts

@@ -593,6 +593,15 @@ export function canonical_tautomer_with_blocked_atoms_json(mol: MolHandle, block
  */
 export function cdxml_to_smiles_json(cdxml: string): string;
 
+/**
+ * The `chematic-wasm` crate version (matches the workspace release version).
+ *
+ * Lets callers (e.g. the browser playground demo) display the running
+ * version without hardcoding it — `demo/index.html` previously had a
+ * static version string that silently went stale across releases.
+ */
+export function chematic_version(): string;
+
 /**
  * CIP stereo assignments via the accurate hierarchical-digraph engine, as a JSON
  * array of `{atomIdx, cipCode}` objects -- same shape as [`cip_assignments_json`],
@@ -1349,8 +1358,13 @@ export function minimize_mmff94_lbfgs_json(mol: MolHandle, max_iter: number): st
  * `coords_json` — JSON array of `[x,y,z]` arrays (Å), one per atom.
  * `max_iter` — maximum iterations (0 = default 500).
  *
- * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool}`
- * or `{"error":"<msg>"}` on failure.
+ * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool, "sound":bool}`
+ * or `{"error":"<msg>"}` on failure. `sound` is all-finite coordinates and
+ * no bond stretched past a sane covalent-bond length — independent of
+ * `converged`, since steepest descent often reports `converged:false` on
+ * geometries that are perfectly fine but simply haven't hit the tight
+ * RMS-gradient threshold yet. Check `sound`, not just `converged`, before
+ * trusting a result.
  */
 export function minimize_uff_json(smiles: string, coords_json: string, max_iter: number): string;
 
@@ -1835,6 +1849,30 @@ export function pharmacophore_fp_2d_summary(mol: MolHandle): string;
  */
 export function pharmacophore_fp_3d_summary(mol: MolHandle): string;
 
+/**
+ * Returns a ready-to-use `embed_pipeline_v2_json` config JSON string for the
+ * "stereo-safe" configuration (issue #291/#383): `stereoPolicy:
+ * "repair_and_verify"`, `enforceChirality: true`, and
+ * `expandImplicitHThroughPipeline: true` together -- the exact combination
+ * measured to correctly handle ring-fused declared stereocenters (e.g.
+ * testosterone, cholesterol) that `enforceChirality` alone cannot repair.
+ * Mirrors `PipelineV2Config::stereo_safe`/the Python binding's
+ * `PipelineV2Config.stereo_safe(...)` -- prefer this over setting those three
+ * fields individually: they only work correctly as a set, and forgetting one
+ * silently falls back to a configuration issue #291 measured as unsound for
+ * that molecule class. `forceFieldPolicy`/`ringTorsionPolicy` are still
+ * required, explicit arguments; everything else takes the same conservative
+ * defaults `embed_pipeline_v2_json`'s own documented examples do. The caller
+ * may parse and further override individual fields before passing the result
+ * to `embed_pipeline_v2_json` (e.g. a different `embedSeed`).
+ *
+ * Never throws, matching `embed_pipeline_v2_json`'s own convention: an
+ * unknown `force_field`/`ring_torsion_policy` string returns the same
+ * `{"ok": false, "error": {...}}` shape `embed_pipeline_v2_json` would for an
+ * invalid config, tagged `schemaVersion: 1`.
+ */
+export function pipeline_v2_stereo_safe_config_json(force_field: string, ring_torsion_policy: string): string;
+
 /**
  * Cartesian coordinates from a PQR file, in the SAME atom order
  * [`mol_from_pqr`] returns topology for. Returns JSON `[[x,y,z],...]` (Å).
@@ -2480,6 +2518,7 @@ 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 chematic_version: () => [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];
@@ -2712,6 +2751,7 @@ export interface InitOutput {
     readonly pharmacophore_features_json: (a: number) => [number, number];
     readonly pharmacophore_fp_2d_summary: (a: number) => [number, number];
     readonly pharmacophore_fp_3d_summary: (a: number) => [number, number];
+    readonly pipeline_v2_stereo_safe_config_json: (a: number, b: number, c: number, d: number) => [number, number];
     readonly pqr_coords_json: (a: number, b: number) => [number, number, number, number];
     readonly pqr_infer_element: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number];
     readonly pqr_to_json: (a: number, b: number) => [number, number, number, number];

package/chematic_wasm.js

@@ -1398,6 +1398,27 @@ export function cdxml_to_smiles_json(cdxml) {
     }
 }
 
+/**
+ * The `chematic-wasm` crate version (matches the workspace release version).
+ *
+ * Lets callers (e.g. the browser playground demo) display the running
+ * version without hardcoding it — `demo/index.html` previously had a
+ * static version string that silently went stale across releases.
+ * @returns {string}
+ */
+export function chematic_version() {
+    let deferred1_0;
+    let deferred1_1;
+    try {
+        const ret = wasm.chematic_version();
+        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 via the accurate hierarchical-digraph engine, as a JSON
  * array of `{atomIdx, cipCode}` objects -- same shape as [`cip_assignments_json`],
@@ -3259,8 +3280,13 @@ export function minimize_mmff94_lbfgs_json(mol, max_iter) {
  * `coords_json` — JSON array of `[x,y,z]` arrays (Å), one per atom.
  * `max_iter` — maximum iterations (0 = default 500).
  *
- * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool}`
- * or `{"error":"<msg>"}` on failure.
+ * Returns JSON: `{"coords":[[x,y,z],...], "energy":float, "iterations":int, "converged":bool, "sound":bool}`
+ * or `{"error":"<msg>"}` on failure. `sound` is all-finite coordinates and
+ * no bond stretched past a sane covalent-bond length — independent of
+ * `converged`, since steepest descent often reports `converged:false` on
+ * geometries that are perfectly fine but simply haven't hit the tight
+ * RMS-gradient threshold yet. Check `sound`, not just `converged`, before
+ * trusting a result.
  * @param {string} smiles
  * @param {string} coords_json
  * @param {number} max_iter
@@ -4563,6 +4589,48 @@ export function pharmacophore_fp_3d_summary(mol) {
     }
 }
 
+/**
+ * Returns a ready-to-use `embed_pipeline_v2_json` config JSON string for the
+ * "stereo-safe" configuration (issue #291/#383): `stereoPolicy:
+ * "repair_and_verify"`, `enforceChirality: true`, and
+ * `expandImplicitHThroughPipeline: true` together -- the exact combination
+ * measured to correctly handle ring-fused declared stereocenters (e.g.
+ * testosterone, cholesterol) that `enforceChirality` alone cannot repair.
+ * Mirrors `PipelineV2Config::stereo_safe`/the Python binding's
+ * `PipelineV2Config.stereo_safe(...)` -- prefer this over setting those three
+ * fields individually: they only work correctly as a set, and forgetting one
+ * silently falls back to a configuration issue #291 measured as unsound for
+ * that molecule class. `forceFieldPolicy`/`ringTorsionPolicy` are still
+ * required, explicit arguments; everything else takes the same conservative
+ * defaults `embed_pipeline_v2_json`'s own documented examples do. The caller
+ * may parse and further override individual fields before passing the result
+ * to `embed_pipeline_v2_json` (e.g. a different `embedSeed`).
+ *
+ * Never throws, matching `embed_pipeline_v2_json`'s own convention: an
+ * unknown `force_field`/`ring_torsion_policy` string returns the same
+ * `{"ok": false, "error": {...}}` shape `embed_pipeline_v2_json` would for an
+ * invalid config, tagged `schemaVersion: 1`.
+ * @param {string} force_field
+ * @param {string} ring_torsion_policy
+ * @returns {string}
+ */
+export function pipeline_v2_stereo_safe_config_json(force_field, ring_torsion_policy) {
+    let deferred3_0;
+    let deferred3_1;
+    try {
+        const ptr0 = passStringToWasm0(force_field, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(ring_torsion_policy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.pipeline_v2_stereo_safe_config_json(ptr0, len0, ptr1, len1);
+        deferred3_0 = ret[0];
+        deferred3_1 = ret[1];
+        return getStringFromWasm0(ret[0], ret[1]);
+    } finally {
+        wasm.__wbindgen_free(deferred3_0, deferred3_1, 1);
+    }
+}
+
 /**
  * Cartesian coordinates from a PQR file, in the SAME atom order
  * [`mol_from_pqr`] returns topology for. Returns JSON `[[x,y,z],...]` (Å).

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.18.0",
+  "version": "0.20.0",
   "license": "MIT OR Apache-2.0",
   "repository": {
     "type": "git",