react-cheminfo 0.23.0 → 0.24.0

package/lib/structure/core/conformerSession.js

@@ -0,0 +1,88 @@
+import { ConformerGenerator } from 'openchemlib';
+/**
+ * A generator for a prepared structure, positioned after `produced` conformers.
+ *
+ * The generator is seeded, so the same structure and options always hand back
+ * the same sequence. The last session is kept, and resumed when it is exactly
+ * where the caller left it; otherwise a fresh generator is initialised and the
+ * first `produced` conformers are drawn and discarded, which yields the same
+ * position without their minimisation.
+ * @param prepared - The hydrogen-saturated copy the run embeds.
+ * @param options - The options that fixed the sequence: strategy, seed, torsion sets.
+ * @param produced - How far into the sequence the caller already is.
+ * @returns The session, to be handed back through {@link keepConformerSession}.
+ * @throws {Error} When OpenChemLib refuses to initialise the structure.
+ */
+export function openConformerSession(prepared, options, produced) {
+    const key = sessionKey(prepared, options);
+    if (produced > 0 && last?.key === key && last.session.produced === produced) {
+        const session = last.session;
+        last = null;
+        return session;
+    }
+    last = null;
+    const generator = new ConformerGenerator(options.seed);
+    const initialised = generator.initializeConformers(prepared, {
+        strategy: strategyConstant(options.strategy),
+        maxTorsionSets: options.maxTorsionSets,
+        use60degreeSteps: options.use60DegreeSteps,
+    });
+    if (!initialised) {
+        throw new Error(`OpenChemLib could not set up conformer generation for ${prepared.getMolecularFormula().formula}. The structure has a problem the generator cannot resolve, such as an impossible valence or an over-constrained ring.`);
+    }
+    let skipped = 0;
+    while (skipped < produced &&
+        generator.getNextConformerAsMolecule() !== null) {
+        skipped++;
+    }
+    return { generator, produced: skipped, pending: null };
+}
+/**
+ * Keep a session so the next continuation of the same run resumes it.
+ * @param prepared - The structure the session was opened on.
+ * @param options - The options it was opened with.
+ * @param session - The session, positioned where the run stopped.
+ */
+export function keepConformerSession(prepared, options, session) {
+    last = { key: sessionKey(prepared, options), session };
+}
+/**
+ * OpenChemLib's estimate of the conformers a session can reach.
+ * @param session - A freshly opened session.
+ * @returns The estimate, or `-1` when the generator declines to make one.
+ */
+export function readPotentialCount(session) {
+    try {
+        return session.generator.getPotentialConformerCount();
+    }
+    catch {
+        return -1;
+    }
+}
+/**
+ * Map one of our strategy ids onto the `ConformerGenerator` constant it stands
+ * for.
+ * @param strategy - The id stored in the preferences.
+ * @returns The numeric constant OpenChemLib expects.
+ */
+export function strategyConstant(strategy) {
+    return STRATEGY_CONSTANTS[strategy];
+}
+const STRATEGY_CONSTANTS = {
+    'adaptive-random': ConformerGenerator.STRATEGY_ADAPTIVE_RANDOM,
+    'likely-random': ConformerGenerator.STRATEGY_LIKELY_RANDOM,
+    'pure-random': ConformerGenerator.STRATEGY_PURE_RANDOM,
+    'likely-systematic': ConformerGenerator.STRATEGY_LIKELY_SYSTEMATIC,
+};
+let last = null;
+// The atom order matters as much as the structure, so the molfile is the key.
+function sessionKey(prepared, options) {
+    return [
+        options.strategy,
+        options.seed,
+        options.maxTorsionSets,
+        options.use60DegreeSteps,
+        prepared.toMolfileV3(),
+    ].join('\n');
+}
+//# sourceMappingURL=conformerSession.js.map

package/lib/structure/core/conformerSession.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformerSession.js","sourceRoot":"","sources":["../../../src/structure/core/conformerSession.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAmBjD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAkB,EAClB,OAAyB,EACzB,QAAgB;IAEhB,MAAM,GAAG,GAAG,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC1C,IAAI,QAAQ,GAAG,CAAC,IAAI,IAAI,EAAE,GAAG,KAAK,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC5E,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,GAAG,IAAI,CAAC;QACZ,OAAO,OAAO,CAAC;IACjB,CAAC;IACD,IAAI,GAAG,IAAI,CAAC;IACZ,MAAM,SAAS,GAAG,IAAI,kBAAkB,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,MAAM,WAAW,GAAG,SAAS,CAAC,oBAAoB,CAAC,QAAQ,EAAE;QAC3D,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,QAAQ,CAAC;QAC5C,cAAc,EAAE,OAAO,CAAC,cAAc;QACtC,gBAAgB,EAAE,OAAO,CAAC,gBAAgB;KAC3C,CAAC,CAAC;IACH,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CACb,yDAAyD,QAAQ,CAAC,mBAAmB,EAAE,CAAC,OAAO,wHAAwH,CACxN,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,OACE,OAAO,GAAG,QAAQ;QAClB,SAAS,CAAC,0BAA0B,EAAE,KAAK,IAAI,EAC/C,CAAC;QACD,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACzD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,QAAkB,EAClB,OAAyB,EACzB,OAAyB;IAEzB,IAAI,GAAG,EAAE,GAAG,EAAE,UAAU,CAAC,QAAQ,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,OAAyB;IAC1D,IAAI,CAAC;QACH,OAAO,OAAO,CAAC,SAAS,CAAC,0BAA0B,EAAE,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,CAAC,CAAC,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA2B;IAC1D,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED,MAAM,kBAAkB,GAAsC;IAC5D,iBAAiB,EAAE,kBAAkB,CAAC,wBAAwB;IAC9D,eAAe,EAAE,kBAAkB,CAAC,sBAAsB;IAC1D,aAAa,EAAE,kBAAkB,CAAC,oBAAoB;IACtD,mBAAmB,EAAE,kBAAkB,CAAC,0BAA0B;CACnE,CAAC;AAEF,IAAI,IAAI,GAAsD,IAAI,CAAC;AAEnE,8EAA8E;AAC9E,SAAS,UAAU,CAAC,QAAkB,EAAE,OAAyB;IAC/D,OAAO;QACL,OAAO,CAAC,QAAQ;QAChB,OAAO,CAAC,IAAI;QACZ,OAAO,CAAC,cAAc;QACtB,OAAO,CAAC,gBAAgB;QACxB,QAAQ,CAAC,WAAW,EAAE;KACvB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/lib/structure/core/conformerShape.d.ts

@@ -0,0 +1,36 @@
+import type { Molecule } from 'openchemlib';
+/** Principal second moments of a conformer's atoms, in increasing order. */
+export type PrincipalMoments = readonly [number, number, number];
+/** What tells two minimised conformers of one energy apart. */
+export interface ConformerShape {
+    /** Principal second moments, smallest first. */
+    moments: PrincipalMoments;
+    /** Handedness in [-1, 1]: opposite for mirror images, 0 for a shape that is its own mirror image. */
+    chirality: number;
+}
+/**
+ * Shape of a conformer: the principal second moments of its atoms, weighted by
+ * atomic number, about their weighted centre, and the handedness of the atoms
+ * in that principal frame.
+ *
+ * Neither changes when the conformer is turned or has its symmetry-equivalent
+ * atoms numbered differently, which is how the generator hands back the same
+ * minimum twice, as with a cyclohexane chair and its flipped copy. A mirror
+ * image keeps the moments and flips the sign of the chirality, so gauche butane
+ * and its mirror image share the one and not the other.
+ *
+ * The chirality is Σ w·u₁u₂u₃ over Σ w·|u₁u₂u₃|, u being the coordinates along
+ * right-handed principal axes. A mirror plane or an inversion centre makes it
+ * vanish. It is 0 as well for a flat conformer, and when the principal axes
+ * cannot be drawn.
+ * @param molecule - A conformer with 3D coordinates.
+ * @returns Its moments, smallest first, and its chirality.
+ */
+export declare function conformerShape(molecule: Molecule): ConformerShape;
+/**
+ * Whether every atom of a conformer sits at finite coordinates.
+ * @param conformer - A conformer with 3D coordinates.
+ * @returns `false` as soon as one coordinate is `NaN` or infinite.
+ */
+export declare function hasFiniteCoordinates(conformer: Molecule): boolean;
+//# sourceMappingURL=conformerShape.d.ts.map

package/lib/structure/core/conformerShape.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformerShape.d.ts","sourceRoot":"","sources":["../../../src/structure/core/conformerShape.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C,4EAA4E;AAC5E,MAAM,MAAM,gBAAgB,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAEjE,+DAA+D;AAC/D,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,OAAO,EAAE,gBAAgB,CAAC;IAC1B,qGAAqG;IACrG,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,QAAQ,GAAG,cAAc,CAuDjE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,QAAQ,GAAG,OAAO,CAYjE"}

package/lib/structure/core/conformerShape.js

@@ -0,0 +1,150 @@
+/**
+ * Shape of a conformer: the principal second moments of its atoms, weighted by
+ * atomic number, about their weighted centre, and the handedness of the atoms
+ * in that principal frame.
+ *
+ * Neither changes when the conformer is turned or has its symmetry-equivalent
+ * atoms numbered differently, which is how the generator hands back the same
+ * minimum twice, as with a cyclohexane chair and its flipped copy. A mirror
+ * image keeps the moments and flips the sign of the chirality, so gauche butane
+ * and its mirror image share the one and not the other.
+ *
+ * The chirality is Σ w·u₁u₂u₃ over Σ w·|u₁u₂u₃|, u being the coordinates along
+ * right-handed principal axes. A mirror plane or an inversion centre makes it
+ * vanish. It is 0 as well for a flat conformer, and when the principal axes
+ * cannot be drawn.
+ * @param molecule - A conformer with 3D coordinates.
+ * @returns Its moments, smallest first, and its chirality.
+ */
+export function conformerShape(molecule) {
+    const atomCount = molecule.getAllAtoms();
+    let total = 0;
+    let centreX = 0;
+    let centreY = 0;
+    let centreZ = 0;
+    for (let atom = 0; atom < atomCount; atom++) {
+        const weight = molecule.getAtomicNo(atom);
+        total += weight;
+        centreX += weight * molecule.getAtomX(atom);
+        centreY += weight * molecule.getAtomY(atom);
+        centreZ += weight * molecule.getAtomZ(atom);
+    }
+    if (total === 0)
+        return { moments: [0, 0, 0], chirality: 0 };
+    centreX /= total;
+    centreY /= total;
+    centreZ /= total;
+    const tensor = { xx: 0, yy: 0, zz: 0, xy: 0, xz: 0, yz: 0 };
+    for (let atom = 0; atom < atomCount; atom++) {
+        const weight = molecule.getAtomicNo(atom);
+        const x = molecule.getAtomX(atom) - centreX;
+        const y = molecule.getAtomY(atom) - centreY;
+        const z = molecule.getAtomZ(atom) - centreZ;
+        tensor.xx += weight * x * x;
+        tensor.yy += weight * y * y;
+        tensor.zz += weight * z * z;
+        tensor.xy += weight * x * y;
+        tensor.xz += weight * x * z;
+        tensor.yz += weight * y * z;
+    }
+    const moments = symmetricEigenvalues(tensor);
+    const first = principalAxis(tensor, moments[0]);
+    const third = principalAxis(tensor, moments[2]);
+    if (first === null || third === null)
+        return { moments, chirality: 0 };
+    const second = cross(third, first);
+    let signed = 0;
+    let absolute = 0;
+    for (let atom = 0; atom < atomCount; atom++) {
+        const weight = molecule.getAtomicNo(atom);
+        const x = molecule.getAtomX(atom) - centreX;
+        const y = molecule.getAtomY(atom) - centreY;
+        const z = molecule.getAtomZ(atom) - centreZ;
+        const product = (x * first[0] + y * first[1] + z * first[2]) *
+            (x * second[0] + y * second[1] + z * second[2]) *
+            (x * third[0] + y * third[1] + z * third[2]);
+        signed += weight * product;
+        absolute += weight * Math.abs(product);
+    }
+    const radius = Math.sqrt((moments[0] + moments[1] + moments[2]) / total);
+    if (absolute <= FLAT_TOLERANCE * total * radius * radius * radius) {
+        return { moments, chirality: 0 };
+    }
+    return { moments, chirality: signed / absolute };
+}
+/**
+ * Whether every atom of a conformer sits at finite coordinates.
+ * @param conformer - A conformer with 3D coordinates.
+ * @returns `false` as soon as one coordinate is `NaN` or infinite.
+ */
+export function hasFiniteCoordinates(conformer) {
+    const atomCount = conformer.getAllAtoms();
+    for (let atom = 0; atom < atomCount; atom++) {
+        if (!Number.isFinite(conformer.getAtomX(atom)) ||
+            !Number.isFinite(conformer.getAtomY(atom)) ||
+            !Number.isFinite(conformer.getAtomZ(atom))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Σ w·|u₁u₂u₃|, relative to the total weight times the cubed radius of
+ * gyration, under which a conformer is flat: its handedness is rounding noise.
+ */
+const FLAT_TOLERANCE = 1e-4;
+// Unit eigenvector of `moment`: the longest cross product of two rows of the tensor minus `moment`.
+function principalAxis(tensor, moment) {
+    const rows = [
+        [tensor.xx - moment, tensor.xy, tensor.xz],
+        [tensor.xy, tensor.yy - moment, tensor.yz],
+        [tensor.xz, tensor.yz, tensor.zz - moment],
+    ];
+    let best = [0, 0, 0];
+    let bestLength = 0;
+    for (let a = 0; a < 3; a++) {
+        for (let b = a + 1; b < 3; b++) {
+            const candidate = cross(rows[a], rows[b]);
+            const length = Math.hypot(candidate[0], candidate[1], candidate[2]);
+            if (length > bestLength) {
+                best = candidate;
+                bestLength = length;
+            }
+        }
+    }
+    if (bestLength === 0)
+        return null;
+    return [best[0] / bestLength, best[1] / bestLength, best[2] / bestLength];
+}
+function cross(a, b) {
+    return [
+        a[1] * b[2] - a[2] * b[1],
+        a[2] * b[0] - a[0] * b[2],
+        a[0] * b[1] - a[1] * b[0],
+    ];
+}
+// Closed-form eigenvalues of a symmetric 3×3 matrix (Smith, 1961).
+function symmetricEigenvalues(tensor) {
+    const { xx, yy, zz, xy, xz, yz } = tensor;
+    const mean = (xx + yy + zz) / 3;
+    const offDiagonal = xy * xy + xz * xz + yz * yz;
+    const spread = (xx - mean) * (xx - mean) +
+        (yy - mean) * (yy - mean) +
+        (zz - mean) * (zz - mean) +
+        2 * offDiagonal;
+    if (spread === 0)
+        return [mean, mean, mean];
+    const p = Math.sqrt(spread / 6);
+    const a = (xx - mean) / p;
+    const b = (yy - mean) / p;
+    const c = (zz - mean) / p;
+    const d = xy / p;
+    const e = xz / p;
+    const f = yz / p;
+    const halfDeterminant = (a * (b * c - f * f) - d * (d * c - f * e) + e * (d * f - b * e)) / 2;
+    const angle = Math.acos(Math.min(1, Math.max(-1, halfDeterminant))) / 3;
+    const largest = mean + 2 * p * Math.cos(angle);
+    const smallest = mean + 2 * p * Math.cos(angle + (2 * Math.PI) / 3);
+    return [smallest, 3 * mean - largest - smallest, largest];
+}
+//# sourceMappingURL=conformerShape.js.map

package/lib/structure/core/conformerShape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformerShape.js","sourceRoot":"","sources":["../../../src/structure/core/conformerShape.ts"],"names":[],"mappings":"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"}

package/lib/structure/core/conformers.d.ts

@@ -0,0 +1,107 @@
+import type { Molecule } from 'openchemlib';
+import type { ConformerOptions, MinimisationAlgorithm } from './conformerOptions.ts';
+import type { ConformerRefinement, ConformerSetRefinement } from './conformerRefine.ts';
+import type { MolfileExport } from './molfileExport.ts';
+export { strategyConstant } from './conformerSession.ts';
+/** One conformer of the input structure, ready to display and to export. */
+export interface Conformer {
+    /** 1-based position in {@link ConformerSet.conformers}. */
+    id: number;
+    /** The 3D structure, as a molfile the viewer can parse. */
+    molfile: MolfileExport;
+    /** Total force-field energy in kcal/mol, `null` when it was not computed. */
+    energy: number | null;
+    /** Energy above the lowest conformer of the set, `null` without an energy. */
+    relativeEnergy: number | null;
+    /**
+     * What a better method said about this conformer, once `refineConformers` has
+     * relaxed it. `null` until then, which is what a plain force-field run leaves.
+     * @default null
+     */
+    refinement: ConformerRefinement | null;
+}
+/**
+ * Which energies a set is ordered by: the force field's own, or the ones a
+ * refinement pass produced.
+ */
+export type ConformerRanking = 'force-field' | 'refined';
+/** Why {@link generateConformers} stopped asking for more conformers. */
+export type StopReason = 'exhausted' | 'count' | 'timeout';
+/** The complete outcome of one conformer run. */
+export interface ConformerSet {
+    /** The conformers kept, most stable first; one without an energy follows every one that has one. */
+    conformers: Conformer[];
+    /** OpenChemLib's estimate of the reachable conformers, `-1` when unavailable. */
+    potentialConformerCount: number;
+    /** Which of the three limits ended the run. */
+    stoppedBy: StopReason;
+    /** Wall-clock duration of the run, initialisation and continuations included. */
+    elapsedMilliseconds: number;
+    /** Plain sentences about conformers that were dropped or left unminimised. */
+    warnings: string[];
+    /** The force field that was asked for, echoed so a reader knows what the energies mean. */
+    minimisation: MinimisationAlgorithm;
+    /** Conformers the generator handed back, dropped ones included: where a continuation resumes. */
+    produced: number;
+    /** The options of the run, so a continuation draws from the same sequence. */
+    options: ConformerOptions;
+    /** Which of the two energies {@link ConformerSet.conformers} is ordered by. */
+    rankedBy: ConformerRanking;
+    /**
+     * What the refinement pass did, `null` for a set no better method has seen.
+     * @default null
+     */
+    refinement: ConformerSetRefinement | null;
+}
+/** The two options a continuation takes from the caller rather than from the run. */
+export type ConformerLimits = Pick<ConformerOptions, 'maxConformers' | 'timeoutSeconds'>;
+/**
+ * Generate conformers of a structure, optionally relaxing each one with MMFF94.
+ *
+ * The caller's molecule is never touched: the run works on a compact copy that
+ * receives the explicit hydrogens the generator needs.
+ *
+ * The run ends on the first of three limits — the generator runs out of new
+ * torsion sets, `maxConformers` conformers are in hand, or the time budget is
+ * spent. **A timeout is not an error**: whatever was produced is returned, with
+ * `stoppedBy` saying why there is not more.
+ *
+ * The budget covers the whole call, initialisation included, and is read again
+ * once a conformer is in hand, so no further minimisation starts past the
+ * deadline. The one step already running cannot be cut short, so a caller
+ * waiting from another thread must allow one step on top of `timeoutSeconds`.
+ *
+ * Minimisation is best-effort: a conformer MMFF94 refuses is kept with a `null`
+ * energy and a warning rather than lost. A minimised conformer that lands in a
+ * minimum already kept, such as the flipped copy of a cyclohexane chair, is
+ * not kept a second time; the mirror image of a chiral minimum, such as the
+ * second gauche butane, is a minimum of its own.
+ * @param molecule - Structure to embed. Not mutated.
+ * @param options - Strategy, limits, seed and force field.
+ * @param now - Clock used for the time budget, injectable for tests.
+ * @returns Every conformer kept, most stable first, with relative energies and any warnings.
+ * @throws {Error} When the structure is empty or OpenChemLib refuses to initialise it.
+ */
+export declare function generateConformers(molecule: Molecule, options: ConformerOptions, now?: () => number): ConformerSet;
+/**
+ * Ask the run that produced `previous` for more conformers.
+ *
+ * The continuation draws from the same seeded sequence with the same force
+ * field, so the result is the set a single larger run would have produced:
+ * the new conformers are ranked among the previous ones, the ids follow that
+ * order, and every relative energy is measured again from the lowest of all.
+ * A refined set cannot be extended: its molfiles hold the relaxed geometries
+ * while its `energy` fields still hold the force field's numbers, so the two
+ * would no longer describe one conformer and the duplicate check would compare
+ * shapes against energies that do not belong to them. Generate a larger set and
+ * refine that instead.
+ * @param molecule - The structure `previous` was generated from. Not mutated.
+ * @param previous - The set to extend. Not mutated.
+ * @param limits - How many more conformers to find, and the time budget of this call.
+ * @param now - Clock used for the time budget, injectable for tests.
+ * @returns The extended set, its duration the sum of both runs.
+ * @throws {Error} When the structure is empty, when `previous` has been refined,
+ * or when OpenChemLib refuses to initialise it.
+ */
+export declare function continueConformers(molecule: Molecule, previous: ConformerSet, limits: ConformerLimits, now?: () => number): ConformerSet;
+//# sourceMappingURL=conformers.d.ts.map

package/lib/structure/core/conformers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformers.d.ts","sourceRoot":"","sources":["../../../src/structure/core/conformers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAM5C,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACtB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,sBAAsB,CAAC;AAS9B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,4EAA4E;AAC5E,MAAM,WAAW,SAAS;IACxB,2DAA2D;IAC3D,EAAE,EAAE,MAAM,CAAC;IACX,2DAA2D;IAC3D,OAAO,EAAE,aAAa,CAAC;IACvB,6EAA6E;IAC7E,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B;;;;OAIG;IACH,UAAU,EAAE,mBAAmB,GAAG,IAAI,CAAC;CACxC;AAED;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,aAAa,GAAG,SAAS,CAAC;AAEzD,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAAG,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC;AAE3D,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,oGAAoG;IACpG,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,iFAAiF;IACjF,uBAAuB,EAAE,MAAM,CAAC;IAChC,+CAA+C;IAC/C,SAAS,EAAE,UAAU,CAAC;IACtB,iFAAiF;IACjF,mBAAmB,EAAE,MAAM,CAAC;IAC5B,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,2FAA2F;IAC3F,YAAY,EAAE,qBAAqB,CAAC;IACpC,iGAAiG;IACjG,QAAQ,EAAE,MAAM,CAAC;IACjB,8EAA8E;IAC9E,OAAO,EAAE,gBAAgB,CAAC;IAC1B,+EAA+E;IAC/E,QAAQ,EAAE,gBAAgB,CAAC;IAC3B;;;OAGG;IACH,UAAU,EAAE,sBAAsB,GAAG,IAAI,CAAC;CAC3C;AAED,qFAAqF;AACrF,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,gBAAgB,EAChB,eAAe,GAAG,gBAAgB,CACnC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,GAAG,GAAE,MAAM,MAAqB,GAC/B,YAAY,CAEd;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,eAAe,EACvB,GAAG,GAAE,MAAM,MAAqB,GAC/B,YAAY,CAOd"}

package/lib/structure/core/conformers.js

@@ -0,0 +1,149 @@
+import { ordinal } from "../../format/core/words.js";
+import { minimiseConformer, rankByEnergy } from "./conformerMinimise.js";
+import { isKeptMinimum, minimisedShapes } from "./conformerMinimum.js";
+import { keepConformerSession, openConformerSession, readPotentialCount, } from "./conformerSession.js";
+import { conformerShape, hasFiniteCoordinates } from "./conformerShape.js";
+import { toMolfileExport } from "./molfileExport.js";
+export { strategyConstant } from "./conformerSession.js";
+/**
+ * Generate conformers of a structure, optionally relaxing each one with MMFF94.
+ *
+ * The caller's molecule is never touched: the run works on a compact copy that
+ * receives the explicit hydrogens the generator needs.
+ *
+ * The run ends on the first of three limits — the generator runs out of new
+ * torsion sets, `maxConformers` conformers are in hand, or the time budget is
+ * spent. **A timeout is not an error**: whatever was produced is returned, with
+ * `stoppedBy` saying why there is not more.
+ *
+ * The budget covers the whole call, initialisation included, and is read again
+ * once a conformer is in hand, so no further minimisation starts past the
+ * deadline. The one step already running cannot be cut short, so a caller
+ * waiting from another thread must allow one step on top of `timeoutSeconds`.
+ *
+ * Minimisation is best-effort: a conformer MMFF94 refuses is kept with a `null`
+ * energy and a warning rather than lost. A minimised conformer that lands in a
+ * minimum already kept, such as the flipped copy of a cyclohexane chair, is
+ * not kept a second time; the mirror image of a chiral minimum, such as the
+ * second gauche butane, is a minimum of its own.
+ * @param molecule - Structure to embed. Not mutated.
+ * @param options - Strategy, limits, seed and force field.
+ * @param now - Clock used for the time budget, injectable for tests.
+ * @returns Every conformer kept, most stable first, with relative energies and any warnings.
+ * @throws {Error} When the structure is empty or OpenChemLib refuses to initialise it.
+ */
+export function generateConformers(molecule, options, now = defaultClock) {
+    return runConformers(molecule, options, null, now);
+}
+/**
+ * Ask the run that produced `previous` for more conformers.
+ *
+ * The continuation draws from the same seeded sequence with the same force
+ * field, so the result is the set a single larger run would have produced:
+ * the new conformers are ranked among the previous ones, the ids follow that
+ * order, and every relative energy is measured again from the lowest of all.
+ * A refined set cannot be extended: its molfiles hold the relaxed geometries
+ * while its `energy` fields still hold the force field's numbers, so the two
+ * would no longer describe one conformer and the duplicate check would compare
+ * shapes against energies that do not belong to them. Generate a larger set and
+ * refine that instead.
+ * @param molecule - The structure `previous` was generated from. Not mutated.
+ * @param previous - The set to extend. Not mutated.
+ * @param limits - How many more conformers to find, and the time budget of this call.
+ * @param now - Clock used for the time budget, injectable for tests.
+ * @returns The extended set, its duration the sum of both runs.
+ * @throws {Error} When the structure is empty, when `previous` has been refined,
+ * or when OpenChemLib refuses to initialise it.
+ */
+export function continueConformers(molecule, previous, limits, now = defaultClock) {
+    const options = {
+        ...previous.options,
+        maxConformers: limits.maxConformers,
+        timeoutSeconds: limits.timeoutSeconds,
+    };
+    return runConformers(molecule, options, previous, now);
+}
+function defaultClock() {
+    return performance.now();
+}
+function runConformers(molecule, options, previous, now) {
+    if (previous?.refinement != null) {
+        throw new Error(`This set was refined with ${previous.refinement.method}, so it cannot be extended. Generate a larger set, then refine it again.`);
+    }
+    const prepared = molecule.getCompactCopy();
+    prepared.addImplicitHydrogens();
+    if (prepared.getAllAtoms() === 0) {
+        throw new Error('The structure is empty: there is nothing to embed in 3D.');
+    }
+    // Setting up the torsion sets is the slow half of a flexible run — seconds on
+    // a long chain — so it is inside both the budget and the reported duration.
+    const start = now();
+    const session = openConformerSession(prepared, options, previous?.produced ?? 0);
+    const potentialConformerCount = previous?.potentialConformerCount ?? readPotentialCount(session);
+    const conformers = previous === null ? [] : copyConformers(previous.conformers);
+    const into = {
+        conformers,
+        shapes: minimisedShapes(conformers),
+        warnings: previous === null ? [] : [...previous.warnings],
+    };
+    const budget = Math.max(options.timeoutSeconds * 1000, 0);
+    const stoppedBy = collect(session, options, into.conformers.length + options.maxConformers, () => now() - start >= budget, into);
+    keepConformerSession(prepared, options, session);
+    return {
+        conformers: rankByEnergy(into.conformers),
+        potentialConformerCount,
+        stoppedBy,
+        elapsedMilliseconds: (previous?.elapsedMilliseconds ?? 0) + now() - start,
+        warnings: into.warnings,
+        minimisation: options.minimisation,
+        produced: session.produced,
+        options,
+        rankedBy: 'force-field',
+        refinement: null,
+    };
+}
+function collect(session, options, target, spent, into) {
+    while (true) {
+        if (into.conformers.length >= target)
+            return 'count';
+        if (spent())
+            return 'timeout';
+        const conformer = session.pending ?? session.generator.getNextConformerAsMolecule();
+        session.pending = null;
+        if (conformer === null)
+            return 'exhausted';
+        // Minimisation runs to completion once entered, so a conformer that arrives
+        // past the deadline is kept aside for a continuation rather than bought now.
+        if (spent()) {
+            session.pending = conformer;
+            return 'timeout';
+        }
+        session.produced++;
+        if (!hasFiniteCoordinates(conformer)) {
+            into.warnings.push(`The ${ordinal(session.produced)} conformer produced was dropped: the generator placed some of its atoms at non-finite coordinates.`);
+            continue;
+        }
+        const energy = minimiseConformer(conformer, options, session.produced, into.warnings);
+        const shape = energy === null ? null : conformerShape(conformer);
+        if (energy !== null &&
+            shape !== null &&
+            isKeptMinimum(energy, shape, into.conformers, into.shapes)) {
+            continue;
+        }
+        into.conformers.push({
+            id: into.conformers.length + 1,
+            molfile: toMolfileExport(conformer),
+            energy,
+            relativeEnergy: null,
+            refinement: null,
+        });
+        into.shapes.push(shape);
+    }
+}
+function copyConformers(conformers) {
+    const copies = [];
+    for (const conformer of conformers)
+        copies.push({ ...conformer });
+    return copies;
+}
+//# sourceMappingURL=conformers.js.map

package/lib/structure/core/conformers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conformers.js","sourceRoot":"","sources":["../../../src/structure/core/conformers.ts"],"names":[],"mappings":"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"}

package/lib/structure/core/geometryRelaxer.d.ts

@@ -0,0 +1,66 @@
+/**
+ * A geometry a relaxer is handed: element symbols plus flat Cartesian
+ * coordinates in ångström, `x,y,z` per atom.
+ */
+export interface RelaxableGeometry {
+    /** Element symbol per atom, explicit hydrogens included. */
+    elements: string[];
+    /** Flat `x,y,z` per atom in ångström, length `3 · elements.length`. */
+    coordinates: Float64Array;
+}
+/** What a relaxer reports for one structure. */
+export interface RelaxedGeometry {
+    /**
+     * The relaxed coordinates, in the input's atom order. Translated freely;
+     * never rotated, which is what lets {@link RelaxedGeometry} be compared with
+     * the geometry it came from by removing both centroids.
+     */
+    coordinates: Float64Array;
+    /**
+     * Total energy at `coordinates`, **in kcal/mol**, so it can be read against a
+     * force-field energy without a second unit in the UI.
+     */
+    energy: number;
+    /**
+     * The dispersion term of `energy`, kcal/mol, or `null` from a method that has
+     * none. It is the part a force field of the MMFF94 era does not model at all,
+     * and a large part of why conformers re-rank.
+     * @default null
+     */
+    dispersionEnergy: number | null;
+    /** Optimizer cycles spent. `0` when there was nothing to relax. */
+    cycles: number;
+    /** Whether the optimizer met its convergence criteria. */
+    converged: boolean;
+    /** Plain sentences about anything the caller should know. */
+    warnings: string[];
+}
+/** How a relaxation run is watched and cancelled. */
+export interface RelaxerOptions {
+    /**
+     * Called as each structure finishes, so a caller can show progress over a
+     * batch that runs for seconds.
+     * @default undefined
+     */
+    onSettled?: (done: number, total: number) => void;
+    /**
+     * Gives the run up. A relaxer is not obliged to be able to interrupt a
+     * structure already in flight.
+     * @default undefined
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Something that relaxes geometries with a real electronic structure behind it,
+ * and reports the energy **at the geometry it returns**.
+ *
+ * This is the seam between a site and the semi-empirical engine: nothing in
+ * `react-cheminfo/core` imports one, so a site that never refines a geometry
+ * downloads no WebAssembly. `xtbRelaxer` from `react-cheminfo/xtb` is the
+ * implementation, GFN2-xTB through `xtb-wasm`.
+ *
+ * An implementation must return one result per request, in request order, and
+ * must keep each structure's atom order.
+ */
+export type GeometryRelaxer = (geometries: readonly RelaxableGeometry[], options?: RelaxerOptions) => Promise<RelaxedGeometry[]>;
+//# sourceMappingURL=geometryRelaxer.d.ts.map

package/lib/structure/core/geometryRelaxer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometryRelaxer.d.ts","sourceRoot":"","sources":["../../../src/structure/core/geometryRelaxer.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,uEAAuE;IACvE,WAAW,EAAE,YAAY,CAAC;CAC3B;AAED,gDAAgD;AAChD,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,WAAW,EAAE,YAAY,CAAC;IAC1B;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;IACnB,6DAA6D;IAC7D,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,qDAAqD;AACrD,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClD;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,UAAU,EAAE,SAAS,iBAAiB,EAAE,EACxC,OAAO,CAAC,EAAE,cAAc,KACrB,OAAO,CAAC,eAAe,EAAE,CAAC,CAAC"}

package/lib/structure/core/geometryRelaxer.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=geometryRelaxer.js.map

package/lib/structure/core/geometryRelaxer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"geometryRelaxer.js","sourceRoot":"","sources":["../../../src/structure/core/geometryRelaxer.ts"],"names":[],"mappings":""}