react-cheminfo 0.23.0 → 0.24.0

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

@@ -0,0 +1,62 @@
+/** The four torsion-set strategies OpenChemLib's `ConformerGenerator` offers. */
+export declare const CONFORMER_STRATEGIES: readonly ["adaptive-random", "likely-random", "pure-random", "likely-systematic"];
+/** One of {@link CONFORMER_STRATEGIES}. */
+export type ConformerStrategy = (typeof CONFORMER_STRATEGIES)[number];
+/** Short names for the strategy picker. */
+export declare const STRATEGY_LABELS: Record<ConformerStrategy, string>;
+/** One sentence per strategy, shown as help text next to the picker. */
+export declare const STRATEGY_DETAILS: Record<ConformerStrategy, string>;
+/** Force fields offered for the optional minimisation step. */
+export declare const MINIMISATION_ALGORITHMS: readonly ["none", "MMFF94", "MMFF94s", "MMFF94s+"];
+/** One of {@link MINIMISATION_ALGORITHMS}. */
+export type MinimisationAlgorithm = (typeof MINIMISATION_ALGORITHMS)[number];
+/** Short names for the minimisation picker. */
+export declare const MINIMISATION_LABELS: Record<MinimisationAlgorithm, string>;
+/** Everything a conformer run needs, in one serialisable object. */
+export interface ConformerOptions {
+    /** Which torsion-set strategy the generator follows. */
+    strategy: ConformerStrategy;
+    /** Upper bound on the number of conformers kept. */
+    maxConformers: number;
+    /** Upper bound on the distinct torsion sets the strategy will try. */
+    maxTorsionSets: number;
+    /** Rotate every rotatable bond in 60° steps instead of using the torsion database. */
+    use60DegreeSteps: boolean;
+    /** Seed of the generator's random source, so a run is reproducible. */
+    seed: number;
+    /** Force field used to relax each conformer; `none` leaves the energies unknown. */
+    minimisation: MinimisationAlgorithm;
+    /** Iteration budget of a single minimisation. */
+    maxIterations: number;
+    /** Wall-clock budget of the whole run, in seconds. */
+    timeoutSeconds: number;
+}
+/** The settings a first-time visitor gets. */
+export declare const DEFAULT_CONFORMER_OPTIONS: ConformerOptions;
+/**
+ * Whether two option sets would run the same calculation.
+ * @param first - One option set.
+ * @param second - The other.
+ * @returns `true` when every option is equal.
+ */
+export declare function sameConformerOptions(first: ConformerOptions, second: ConformerOptions): boolean;
+/**
+ * Rotatable-bond count above which the conformer space is large enough that the
+ * run is worth warning about before it starts.
+ */
+export declare const ROTATABLE_BOND_WARNING = 12;
+/**
+ * Narrow an arbitrary string, typically a URL parameter or a stored preference,
+ * to a strategy id.
+ * @param value - Text to test.
+ * @returns Whether `value` is one of {@link CONFORMER_STRATEGIES}.
+ */
+export declare function isConformerStrategy(value: string): value is ConformerStrategy;
+/**
+ * Narrow an arbitrary string, typically a stored preference, to a force-field
+ * id.
+ * @param value - Text to test.
+ * @returns Whether `value` is one of {@link MINIMISATION_ALGORITHMS}.
+ */
+export declare function isMinimisationAlgorithm(value: string): value is MinimisationAlgorithm;
+//# sourceMappingURL=conformerOptions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformerOptions.d.ts","sourceRoot":"","sources":["../../../src/structure/core/conformerOptions.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,eAAO,MAAM,oBAAoB,mFAKvB,CAAC;AAEX,2CAA2C;AAC3C,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEtE,2CAA2C;AAC3C,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAK7D,CAAC;AAEF,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,iBAAiB,EAAE,MAAM,CAS9D,CAAC;AAEF,+DAA+D;AAC/D,eAAO,MAAM,uBAAuB,oDAK1B,CAAC;AAEX,8CAA8C;AAC9C,MAAM,MAAM,qBAAqB,GAAG,CAAC,OAAO,uBAAuB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7E,+CAA+C;AAC/C,eAAO,MAAM,mBAAmB,EAAE,MAAM,CAAC,qBAAqB,EAAE,MAAM,CAKrE,CAAC;AAEF,oEAAoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,wDAAwD;IACxD,QAAQ,EAAE,iBAAiB,CAAC;IAC5B,oDAAoD;IACpD,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB,sFAAsF;IACtF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,YAAY,EAAE,qBAAqB,CAAC;IACpC,iDAAiD;IACjD,aAAa,EAAE,MAAM,CAAC;IACtB,sDAAsD;IACtD,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,8CAA8C;AAC9C,eAAO,MAAM,yBAAyB,EAAE,gBASvC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAKT;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,iBAAiB,CAE7E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,GACZ,KAAK,IAAI,qBAAqB,CAEhC"}

package/lib/structure/core/conformerOptions.js

@@ -0,0 +1,83 @@
+/** The four torsion-set strategies OpenChemLib's `ConformerGenerator` offers. */
+export const CONFORMER_STRATEGIES = [
+    'adaptive-random',
+    'likely-random',
+    'pure-random',
+    'likely-systematic',
+];
+/** Short names for the strategy picker. */
+export const STRATEGY_LABELS = {
+    'adaptive-random': 'Adaptive random',
+    'likely-random': 'Likely random',
+    'pure-random': 'Pure random',
+    'likely-systematic': 'Likely systematic',
+};
+/** One sentence per strategy, shown as help text next to the picker. */
+export const STRATEGY_DETAILS = {
+    'adaptive-random': 'Draws torsions at random but steers away from the combinations that already collided, which covers a flexible molecule fastest.',
+    'likely-random': 'Draws torsions at random from the torsion database, weighted by how often each angle is seen in crystal structures.',
+    'pure-random': 'Draws every torsion uniformly at random, ignoring how likely the angle is — the widest spread and the least realistic set.',
+    'likely-systematic': 'Walks the torsion combinations in decreasing likelihood, so the first conformers are the most probable ones and the set is reproducible.',
+};
+/** Force fields offered for the optional minimisation step. */
+export const MINIMISATION_ALGORITHMS = [
+    'none',
+    'MMFF94',
+    'MMFF94s',
+    'MMFF94s+',
+];
+/** Short names for the minimisation picker. */
+export const MINIMISATION_LABELS = {
+    none: 'None (no energies)',
+    MMFF94: 'MMFF94',
+    MMFF94s: 'MMFF94s',
+    'MMFF94s+': 'MMFF94s+',
+};
+/** The settings a first-time visitor gets. */
+export const DEFAULT_CONFORMER_OPTIONS = {
+    strategy: 'adaptive-random',
+    maxConformers: 10,
+    maxTorsionSets: 10_000,
+    use60DegreeSteps: false,
+    seed: 42,
+    minimisation: 'MMFF94s+',
+    maxIterations: 4000,
+    timeoutSeconds: 10,
+};
+/**
+ * Whether two option sets would run the same calculation.
+ * @param first - One option set.
+ * @param second - The other.
+ * @returns `true` when every option is equal.
+ */
+export function sameConformerOptions(first, second) {
+    for (const key of Object.keys(first)) {
+        if (first[key] !== second[key])
+            return false;
+    }
+    return true;
+}
+/**
+ * Rotatable-bond count above which the conformer space is large enough that the
+ * run is worth warning about before it starts.
+ */
+export const ROTATABLE_BOND_WARNING = 12;
+/**
+ * Narrow an arbitrary string, typically a URL parameter or a stored preference,
+ * to a strategy id.
+ * @param value - Text to test.
+ * @returns Whether `value` is one of {@link CONFORMER_STRATEGIES}.
+ */
+export function isConformerStrategy(value) {
+    return CONFORMER_STRATEGIES.includes(value);
+}
+/**
+ * Narrow an arbitrary string, typically a stored preference, to a force-field
+ * id.
+ * @param value - Text to test.
+ * @returns Whether `value` is one of {@link MINIMISATION_ALGORITHMS}.
+ */
+export function isMinimisationAlgorithm(value) {
+    return MINIMISATION_ALGORITHMS.includes(value);
+}
+//# sourceMappingURL=conformerOptions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformerOptions.js","sourceRoot":"","sources":["../../../src/structure/core/conformerOptions.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,iBAAiB;IACjB,eAAe;IACf,aAAa;IACb,mBAAmB;CACX,CAAC;AAKX,2CAA2C;AAC3C,MAAM,CAAC,MAAM,eAAe,GAAsC;IAChE,iBAAiB,EAAE,iBAAiB;IACpC,eAAe,EAAE,eAAe;IAChC,aAAa,EAAE,aAAa;IAC5B,mBAAmB,EAAE,mBAAmB;CACzC,CAAC;AAEF,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAAsC;IACjE,iBAAiB,EACf,iIAAiI;IACnI,eAAe,EACb,qHAAqH;IACvH,aAAa,EACX,4HAA4H;IAC9H,mBAAmB,EACjB,0IAA0I;CAC7I,CAAC;AAEF,+DAA+D;AAC/D,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,MAAM;IACN,QAAQ;IACR,SAAS;IACT,UAAU;CACF,CAAC;AAKX,+CAA+C;AAC/C,MAAM,CAAC,MAAM,mBAAmB,GAA0C;IACxE,IAAI,EAAE,oBAAoB;IAC1B,MAAM,EAAE,QAAQ;IAChB,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,UAAU;CACvB,CAAC;AAsBF,8CAA8C;AAC9C,MAAM,CAAC,MAAM,yBAAyB,GAAqB;IACzD,QAAQ,EAAE,iBAAiB;IAC3B,aAAa,EAAE,EAAE;IACjB,cAAc,EAAE,MAAM;IACtB,gBAAgB,EAAE,KAAK;IACvB,IAAI,EAAE,EAAE;IACR,YAAY,EAAE,UAAU;IACxB,aAAa,EAAE,IAAI;IACnB,cAAc,EAAE,EAAE;CACnB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAClC,KAAuB,EACvB,MAAwB;IAExB,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAkC,EAAE,CAAC;QACtE,IAAI,KAAK,CAAC,GAAG,CAAC,KAAK,MAAM,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC/C,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,EAAE,CAAC;AAEzC;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAa;IAC/C,OAAQ,oBAA0C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACrE,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAa;IAEb,OAAQ,uBAA6C,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AACxE,CAAC"}

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

@@ -0,0 +1,104 @@
+import type { ConformerSet } from './conformers.ts';
+import type { GeometryRelaxer, RelaxerOptions } from './geometryRelaxer.ts';
+/** What refining one conformer produced, on top of its force-field numbers. */
+export interface ConformerRefinement {
+    /**
+     * The rank this conformer held before the refinement, which is the `id` it
+     * carried in the force-field set. Refinement hands the ids out again, so this
+     * is what a reader compares the new rank against and what a caller uses to
+     * find again the conformer that was on screen.
+     */
+    forceFieldId: number;
+    /** Total energy at the relaxed geometry, kcal/mol. */
+    energy: number;
+    /** Energy above the most stable refined conformer of the set, kcal/mol. */
+    relativeEnergy: number;
+    /**
+     * The dispersion term of {@link ConformerRefinement.energy}, kcal/mol, or
+     * `null` from a method that has none.
+     */
+    dispersionEnergy: number | null;
+    /**
+     * The force-field energy this conformer had before, kcal/mol, `null` when it
+     * had none. Kept so the two rankings can be read against each other, which is
+     * the whole reason to refine.
+     */
+    forceFieldEnergy: number | null;
+    /** How far the atoms moved from the force-field geometry, RMSD in ångström. */
+    rmsd: number;
+    /** Optimizer cycles spent. */
+    cycles: number;
+    /** Whether the optimizer met its convergence criteria. */
+    converged: boolean;
+}
+/** What a whole refinement pass produced, recorded on the set. */
+export interface ConformerSetRefinement {
+    /** The method, as it is shown to a reader, e.g. `GFN2-xTB`. */
+    method: string;
+    /** Wall-clock duration of the pass, in milliseconds. */
+    elapsedMilliseconds: number;
+    /** How many conformers were dropped as duplicates of a kept minimum. */
+    merged: number;
+    /**
+     * How many conformers the refined ranking put at a different position,
+     * degenerate conformers swapping places included — so it is a fact about the
+     * two orders, not a measure of how much the methods disagree. The two relative
+     * energies are what a reader should be shown.
+     */
+    reordered: number;
+}
+/** How a refinement pass is tuned, watched and cancelled. */
+export interface RefineConformersOptions extends RelaxerOptions {
+    /**
+     * Name of the method, for the label the UI shows.
+     * @default 'GFN2-xTB'
+     */
+    method?: string;
+    /**
+     * Energy gap in kcal/mol under which two refined conformers are taken to be
+     * one minimum.
+     * @default REFINED_SAME_ENERGY_TOLERANCE
+     */
+    sameEnergyTolerance?: number;
+}
+/**
+ * Energy gap in kcal/mol under which two relaxed conformers can be one minimum.
+ *
+ * Measured with `benchmark/conformerRefine.js scatter`: one butane minimum
+ * reached from six geometries perturbed by up to 0.02 Å lands within 4.9e-6
+ * kcal/mol, in 8 to 20 optimizer cycles. So 1e-4 is twenty times the scatter of
+ * one minimum, and ten times below the closest gap between two real minima seen
+ * on a flexible molecule — ibuprofen has distinct conformers 1e-3 kcal/mol
+ * apart. The energy is only the cheap half of the test in any case: what decides
+ * that two conformers are one minimum is the shape.
+ */
+export declare const REFINED_SAME_ENERGY_TOLERANCE = 0.0001;
+/** What is shown when a conformer set is ranked by the refined energies. */
+export declare const REFINED_RANKING = "refined";
+/**
+ * Relax every conformer of a set with a better method and rank the set by what
+ * that method says.
+ *
+ * This is the opt-in second stage of a conformer search, opt-in because it costs
+ * seconds where the force field costs milliseconds. MMFF94 places the atoms well
+ * but ranks conformers badly — it has no dispersion and no electronic structure,
+ * and those are what decide which conformer is lowest. So both numbers are kept:
+ * `conformer.energy` stays the force field's, `conformer.refinement.energy` is
+ * the new one, and `set.rankedBy` says which of the two the order follows.
+ *
+ * Refinement changes the set, not only its order: conformers the force field
+ * held apart can relax into one minimum, and the first of them is the one that
+ * survives. Ids are handed out again over the ranked result, so a caller holding
+ * an id must look its conformer up again.
+ *
+ * A conformer without a force-field energy is refined like any other; its
+ * `forceFieldEnergy` is `null` and it takes its place by the refined energy.
+ * @param set - The set to refine. Not modified.
+ * @param relax - The engine, e.g. `xtbRelaxer` from `react-cheminfo/xtb`.
+ * @param options - Method name, duplicate tolerance, progress and cancellation.
+ * @returns A new set, ranked by the refined energies.
+ * @throws {Error} When the relaxer fails or is cancelled, or answers with the
+ * wrong number of geometries.
+ */
+export declare function refineConformers(set: ConformerSet, relax: GeometryRelaxer, options?: RefineConformersOptions): Promise<ConformerSet>;
+//# sourceMappingURL=conformerRefine.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformerRefine.d.ts","sourceRoot":"","sources":["../../../src/structure/core/conformerRefine.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAa,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/D,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EACf,MAAM,sBAAsB,CAAC;AAQ9B,+EAA+E;AAC/E,MAAM,WAAW,mBAAmB;IAClC;;;;;OAKG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,cAAc,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,kEAAkE;AAClE,MAAM,WAAW,sBAAsB;IACrC,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,wDAAwD;IACxD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wEAAwE;IACxE,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,uBAAwB,SAAQ,cAAc;IAC7D;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,6BAA6B,SAAO,CAAC;AAElD,4EAA4E;AAC5E,eAAO,MAAM,eAAe,YAAY,CAAC;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,YAAY,EACjB,KAAK,EAAE,eAAe,EACtB,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,YAAY,CAAC,CAqGvB"}

package/lib/structure/core/conformerRefine.js

@@ -0,0 +1,130 @@
+import { Molecule } from 'openchemlib';
+import { ordinal } from "../../format/core/words.js";
+import { isRefinedDuplicate, rankByRefinedEnergy, } from "./conformerRefineRank.js";
+import { conformerShape } from "./conformerShape.js";
+import { centredRmsd, readRelaxableGeometry, writeRelaxedCoordinates, } from "./moleculeCoordinates.js";
+import { toMolfileExport } from "./molfileExport.js";
+/**
+ * Energy gap in kcal/mol under which two relaxed conformers can be one minimum.
+ *
+ * Measured with `benchmark/conformerRefine.js scatter`: one butane minimum
+ * reached from six geometries perturbed by up to 0.02 Å lands within 4.9e-6
+ * kcal/mol, in 8 to 20 optimizer cycles. So 1e-4 is twenty times the scatter of
+ * one minimum, and ten times below the closest gap between two real minima seen
+ * on a flexible molecule — ibuprofen has distinct conformers 1e-3 kcal/mol
+ * apart. The energy is only the cheap half of the test in any case: what decides
+ * that two conformers are one minimum is the shape.
+ */
+export const REFINED_SAME_ENERGY_TOLERANCE = 1e-4;
+/** What is shown when a conformer set is ranked by the refined energies. */
+export const REFINED_RANKING = 'refined';
+/**
+ * Relax every conformer of a set with a better method and rank the set by what
+ * that method says.
+ *
+ * This is the opt-in second stage of a conformer search, opt-in because it costs
+ * seconds where the force field costs milliseconds. MMFF94 places the atoms well
+ * but ranks conformers badly — it has no dispersion and no electronic structure,
+ * and those are what decide which conformer is lowest. So both numbers are kept:
+ * `conformer.energy` stays the force field's, `conformer.refinement.energy` is
+ * the new one, and `set.rankedBy` says which of the two the order follows.
+ *
+ * Refinement changes the set, not only its order: conformers the force field
+ * held apart can relax into one minimum, and the first of them is the one that
+ * survives. Ids are handed out again over the ranked result, so a caller holding
+ * an id must look its conformer up again.
+ *
+ * A conformer without a force-field energy is refined like any other; its
+ * `forceFieldEnergy` is `null` and it takes its place by the refined energy.
+ * @param set - The set to refine. Not modified.
+ * @param relax - The engine, e.g. `xtbRelaxer` from `react-cheminfo/xtb`.
+ * @param options - Method name, duplicate tolerance, progress and cancellation.
+ * @returns A new set, ranked by the refined energies.
+ * @throws {Error} When the relaxer fails or is cancelled, or answers with the
+ * wrong number of geometries.
+ */
+export async function refineConformers(set, relax, options = {}) {
+    const startedAt = performance.now();
+    const method = options.method ?? 'GFN2-xTB';
+    if (set.conformers.length === 0) {
+        return {
+            ...set,
+            rankedBy: REFINED_RANKING,
+            refinement: { method, elapsedMilliseconds: 0, merged: 0, reordered: 0 },
+        };
+    }
+    const prepared = [];
+    for (const conformer of set.conformers) {
+        const molecule = Molecule.fromMolfile(conformer.molfile.data);
+        prepared.push({
+            conformer,
+            molecule,
+            geometry: readRelaxableGeometry(molecule),
+        });
+    }
+    const relaxed = await relax(prepared.map((entry) => entry.geometry), {
+        onSettled: options.onSettled,
+        signal: options.signal,
+    });
+    if (relaxed.length !== set.conformers.length) {
+        throw new Error(`The relaxer answered with ${relaxed.length} geometries for ${set.conformers.length} conformers.`);
+    }
+    const tolerance = options.sameEnergyTolerance ?? REFINED_SAME_ENERGY_TOLERANCE;
+    const warnings = [...set.warnings];
+    const kept = [];
+    const minima = [];
+    let merged = 0;
+    for (const [index, entry] of prepared.entries()) {
+        const result = relaxed[index];
+        if (result === undefined)
+            continue;
+        const { conformer, molecule, geometry } = entry;
+        writeRelaxedCoordinates(molecule, result.coordinates);
+        const candidate = {
+            energy: result.energy,
+            shape: conformerShape(molecule),
+        };
+        if (isRefinedDuplicate(candidate, minima, tolerance)) {
+            merged++;
+            continue;
+        }
+        for (const warning of result.warnings) {
+            warnings.push(`The ${ordinal(conformer.id)} conformer: ${warning}`);
+        }
+        if (!result.converged) {
+            warnings.push(`The ${ordinal(conformer.id)} conformer did not reach a ${method} minimum in ${result.cycles} cycles, so its refined energy is an upper bound.`);
+        }
+        kept.push({
+            ...conformer,
+            molfile: toMolfileExport(molecule),
+            refinement: {
+                forceFieldId: conformer.id,
+                energy: result.energy,
+                relativeEnergy: 0,
+                dispersionEnergy: result.dispersionEnergy,
+                forceFieldEnergy: conformer.energy,
+                rmsd: centredRmsd(geometry.coordinates, result.coordinates),
+                cycles: result.cycles,
+                converged: result.converged,
+            },
+        });
+        minima.push(candidate);
+    }
+    if (merged > 0) {
+        warnings.push(`${merged} conformer(s) relaxed into a ${method} minimum the set already held, so they were dropped.`);
+    }
+    const ranked = rankByRefinedEnergy(kept);
+    return {
+        ...set,
+        conformers: ranked.conformers,
+        warnings,
+        rankedBy: REFINED_RANKING,
+        refinement: {
+            method,
+            elapsedMilliseconds: performance.now() - startedAt,
+            merged,
+            reordered: ranked.reordered,
+        },
+    };
+}
+//# sourceMappingURL=conformerRefine.js.map

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

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

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

@@ -0,0 +1,36 @@
+import type { ConformerShape } from './conformerShape.ts';
+import type { Conformer } from './conformers.ts';
+/** A refined conformer's energy and shape, which is what tells two minima apart. */
+export interface RefinedMinimum {
+    /** Refined total energy, kcal/mol. */
+    energy: number;
+    shape: ConformerShape;
+}
+/** A ranked set, and how far it moved from the order it came in. */
+export interface RefinedRanking {
+    /** The conformers, most stable first, renumbered from one in that order. */
+    conformers: Conformer[];
+    /** How many conformers ended up at a different position than they came in at. */
+    reordered: number;
+}
+/**
+ * Order refined conformers from the most stable down, number them from one in
+ * that order, and measure every refined energy from the lowest.
+ *
+ * `reordered` counts the conformers whose position changed, which is the number
+ * worth showing: it says how much the better method disagreed with the force
+ * field.
+ * @param conformers - The refined conformers, in the force field's own order.
+ * @returns The ranked conformers and the disagreement count.
+ */
+export declare function rankByRefinedEnergy(conformers: readonly Conformer[]): RefinedRanking;
+/**
+ * Whether a refined conformer landed in a minimum one of `kept` already holds:
+ * the same energy within `tolerance`, and the same shape.
+ * @param candidate - The refined conformer's energy and shape.
+ * @param kept - The minima kept so far.
+ * @param tolerance - Energy gap in kcal/mol under which two energies are one.
+ * @returns `true` when one of them is the same minimum.
+ */
+export declare function isRefinedDuplicate(candidate: RefinedMinimum, kept: readonly RefinedMinimum[], tolerance: number): boolean;
+//# sourceMappingURL=conformerRefineRank.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformerRefineRank.d.ts","sourceRoot":"","sources":["../../../src/structure/core/conformerRefineRank.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC1D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,oFAAoF;AACpF,MAAM,WAAW,cAAc;IAC7B,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,oEAAoE;AACpE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,SAAS,EAAE,GAC/B,cAAc,CAsBhB;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,cAAc,EACzB,IAAI,EAAE,SAAS,cAAc,EAAE,EAC/B,SAAS,EAAE,MAAM,GAChB,OAAO,CAMT"}

package/lib/structure/core/conformerRefineRank.js

@@ -0,0 +1,69 @@
+import { isSameShape } from "./conformerMinimum.js";
+/**
+ * Order refined conformers from the most stable down, number them from one in
+ * that order, and measure every refined energy from the lowest.
+ *
+ * `reordered` counts the conformers whose position changed, which is the number
+ * worth showing: it says how much the better method disagreed with the force
+ * field.
+ * @param conformers - The refined conformers, in the force field's own order.
+ * @returns The ranked conformers and the disagreement count.
+ */
+export function rankByRefinedEnergy(conformers) {
+    let lowest = Number.POSITIVE_INFINITY;
+    for (const conformer of conformers) {
+        const energy = conformer.refinement?.energy;
+        if (energy !== undefined && energy < lowest)
+            lowest = energy;
+    }
+    const ranked = conformers.toSorted(compareRefined);
+    const result = [];
+    let reordered = 0;
+    for (const [index, conformer] of ranked.entries()) {
+        if (conformer.id !== index + 1)
+            reordered++;
+        const refinement = conformer.refinement;
+        result.push({
+            ...conformer,
+            id: index + 1,
+            refinement: refinement === null
+                ? null
+                : { ...refinement, relativeEnergy: refinement.energy - lowest },
+        });
+    }
+    return { conformers: result, reordered };
+}
+/**
+ * Whether a refined conformer landed in a minimum one of `kept` already holds:
+ * the same energy within `tolerance`, and the same shape.
+ * @param candidate - The refined conformer's energy and shape.
+ * @param kept - The minima kept so far.
+ * @param tolerance - Energy gap in kcal/mol under which two energies are one.
+ * @returns `true` when one of them is the same minimum.
+ */
+export function isRefinedDuplicate(candidate, kept, tolerance) {
+    for (const entry of kept) {
+        if (Math.abs(candidate.energy - entry.energy) > tolerance)
+            continue;
+        if (isSameShape(candidate.shape, entry.shape))
+            return true;
+    }
+    return false;
+}
+/**
+ * Order two conformers by refined energy; one without a refinement ranks after
+ * every one that has one.
+ * @param a - One conformer.
+ * @param b - The other.
+ * @returns Negative when `a` is the more stable, positive when `b` is.
+ */
+function compareRefined(a, b) {
+    const energyA = a.refinement?.energy;
+    const energyB = b.refinement?.energy;
+    if (energyA === undefined)
+        return energyB === undefined ? 0 : 1;
+    if (energyB === undefined)
+        return -1;
+    return energyA - energyB;
+}
+//# sourceMappingURL=conformerRefineRank.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformerRefineRank.js","sourceRoot":"","sources":["../../../src/structure/core/conformerRefineRank.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAmBpD;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,UAAgC;IAEhC,IAAI,MAAM,GAAG,MAAM,CAAC,iBAAiB,CAAC;IACtC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5C,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,GAAG,MAAM;YAAE,MAAM,GAAG,MAAM,CAAC;IAC/D,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IACnD,MAAM,MAAM,GAAgB,EAAE,CAAC;IAC/B,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,KAAK,MAAM,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,MAAM,CAAC,OAAO,EAAE,EAAE,CAAC;QAClD,IAAI,SAAS,CAAC,EAAE,KAAK,KAAK,GAAG,CAAC;YAAE,SAAS,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,SAAS,CAAC,UAAU,CAAC;QACxC,MAAM,CAAC,IAAI,CAAC;YACV,GAAG,SAAS;YACZ,EAAE,EAAE,KAAK,GAAG,CAAC;YACb,UAAU,EACR,UAAU,KAAK,IAAI;gBACjB,CAAC,CAAC,IAAI;gBACN,CAAC,CAAC,EAAE,GAAG,UAAU,EAAE,cAAc,EAAE,UAAU,CAAC,MAAM,GAAG,MAAM,EAAE;SACpE,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAyB,EACzB,IAA+B,EAC/B,SAAiB;IAEjB,KAAK,MAAM,KAAK,IAAI,IAAI,EAAE,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,GAAG,SAAS;YAAE,SAAS;QACpE,IAAI,WAAW,CAAC,SAAS,CAAC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;IAC7D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;GAMG;AACH,SAAS,cAAc,CAAC,CAAY,EAAE,CAAY;IAChD,MAAM,OAAO,GAAG,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC;IACrC,MAAM,OAAO,GAAG,CAAC,CAAC,UAAU,EAAE,MAAM,CAAC;IACrC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC,CAAC;IACrC,OAAO,OAAO,GAAG,OAAO,CAAC;AAC3B,CAAC"}

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

@@ -0,0 +1,50 @@
+import type { Molecule } from 'openchemlib';
+import { ConformerGenerator } from 'openchemlib';
+import type { ConformerOptions, ConformerStrategy } from './conformerOptions.ts';
+/** A generator, positioned after the conformers it has already handed back. */
+export interface ConformerSession {
+    generator: ConformerGenerator;
+    /** Conformers handed back so far, kept or dropped. */
+    produced: number;
+    /**
+     * A conformer drawn from the generator but not yet processed, because the
+     * deadline passed while it was drawn. Not counted in `produced`.
+     */
+    pending: Molecule | null;
+}
+/**
+ * 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 declare function openConformerSession(prepared: Molecule, options: ConformerOptions, produced: number): ConformerSession;
+/**
+ * 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 declare function keepConformerSession(prepared: Molecule, options: ConformerOptions, session: ConformerSession): void;
+/**
+ * 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 declare function readPotentialCount(session: ConformerSession): number;
+/**
+ * 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 declare function strategyConstant(strategy: ConformerStrategy): number;
+//# sourceMappingURL=conformerSession.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"conformerSession.d.ts","sourceRoot":"","sources":["../../../src/structure/core/conformerSession.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEjD,OAAO,KAAK,EACV,gBAAgB,EAChB,iBAAiB,EAClB,MAAM,uBAAuB,CAAC;AAE/B,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,kBAAkB,CAAC;IAC9B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,QAAQ,EAAE,MAAM,GACf,gBAAgB,CA2BlB;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,gBAAgB,EACzB,OAAO,EAAE,gBAAgB,GACxB,IAAI,CAEN;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,GAAG,MAAM,CAMpE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,GAAG,MAAM,CAEpE"}