react-cheminfo 0.23.0 → 0.25.0

package/src/shared/ui/MenuButton.tsx

@@ -11,8 +11,9 @@ const HOLDER_STYLE: CSSProperties = {
 /** What every button of a site header takes, whatever its menu holds. */
 export interface HeaderButtonProps {
   /**
-   * Whether the button is reduced to its icon — no text, no caret — for a
-   * header that has run out of room. The icon still opens the same menu.
+   * Whether the text is left out of the button altogether, rather than only
+   * hidden: a bar that has run out of room drops the caret with it. The glyph
+   * names itself through its tooltip either way.
    * @default false
    */
   compact?: boolean;
@@ -60,7 +61,7 @@ export function MenuButton(props: MenuButtonProps): ReactElement {
           endIcon={compact ? undefined : 'caret-down'}
           text={compact ? undefined : label}
           aria-label={label}
-          title={compact ? label : undefined}
+          title={label}
         />
       </PopoverNext>
     </span>

package/src/structure/core/conformerMinimise.ts

@@ -0,0 +1,99 @@
+import type { Molecule } from 'openchemlib';
+import { ForceFieldMMFF94 } from 'openchemlib';
+
+import { ordinal } from '../../format/core/words.ts';
+
+import type { ConformerOptions } from './conformerOptions.ts';
+
+/**
+ * Relax one conformer in place and return its energy.
+ *
+ * Minimisation is best-effort. MMFF94 cannot type every element (boron, for
+ * one), so a conformer it refuses gets a `null` energy and a warning rather
+ * than an exception. A non-zero return code from `minimise()` is *not* a
+ * failure: ethyne returns 2 with a perfect geometry.
+ *
+ * Warnings count the conformers the generator handed back, kept or not, so one
+ * number never means two things — a row number would, once one is dropped.
+ * @param conformer - The conformer to relax. Mutated.
+ * @param options - Force field and iteration budget.
+ * @param produced - 1-based position of the conformer in the generator's output.
+ * @param warnings - Receives one sentence when the energy is unknown.
+ * @returns Total energy in kcal/mol, or `null` when none was computed.
+ */
+export function minimiseConformer(
+  conformer: Molecule,
+  options: ConformerOptions,
+  produced: number,
+  warnings: string[],
+): number | null {
+  const algorithm = options.minimisation;
+  if (algorithm === 'none') return null;
+  let energy: number;
+  try {
+    const forceField = new ForceFieldMMFF94(conformer, algorithm, {});
+    forceField.minimise({ maxIts: options.maxIterations });
+    energy = forceField.getTotalEnergy();
+  } catch (error) {
+    warnings.push(
+      `The ${ordinal(produced)} conformer produced could not be minimised with ${algorithm} (${readable(error)}), so its energy is unknown.`,
+    );
+    return null;
+  }
+  if (!Number.isFinite(energy)) {
+    warnings.push(
+      `The ${ordinal(produced)} conformer produced minimised to a non-finite ${algorithm} energy, so its energy is unknown.`,
+    );
+    return null;
+  }
+  return energy;
+}
+
+/** What {@link rankByEnergy} reads and rewrites on a conformer. */
+export interface RankedConformer {
+  id: number;
+  energy: number | null;
+  relativeEnergy: number | null;
+}
+
+/**
+ * Order a set from the most stable conformer down, number it from one in that
+ * order, and measure every known energy from the lowest.
+ *
+ * A conformer without an energy ranks after every one that has one; equal
+ * energies, and conformers without one, keep the order they came in.
+ * @param conformers - The set. Each `id` and `relativeEnergy` is rewritten in place.
+ * @returns The same conformers, most stable first.
+ */
+export function rankByEnergy<T extends RankedConformer>(
+  conformers: readonly T[],
+): T[] {
+  assignRelativeEnergies(conformers);
+  const ranked = conformers.toSorted(compareEnergy);
+  for (const [index, conformer] of ranked.entries()) conformer.id = index + 1;
+  return ranked;
+}
+
+function compareEnergy(a: RankedConformer, b: RankedConformer): number {
+  if (a.energy === null) return b.energy === null ? 0 : 1;
+  if (b.energy === null) return -1;
+  return a.energy - b.energy;
+}
+
+function assignRelativeEnergies(conformers: readonly RankedConformer[]): void {
+  let lowest = Number.POSITIVE_INFINITY;
+  for (const conformer of conformers) {
+    const energy = conformer.energy;
+    if (energy !== null && energy < lowest) lowest = energy;
+  }
+  if (lowest === Number.POSITIVE_INFINITY) return;
+  for (const conformer of conformers) {
+    const energy = conformer.energy;
+    if (energy !== null) conformer.relativeEnergy = energy - lowest;
+  }
+}
+
+function readable(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.replace(/^\w+\$\w+: /, '');
+}

package/src/structure/core/conformerMinimum.ts

@@ -0,0 +1,125 @@
+import { Molecule } from 'openchemlib';
+
+import type { ConformerShape } from './conformerShape.ts';
+import { conformerShape } from './conformerShape.ts';
+
+/** What {@link isKeptMinimum} and {@link minimisedShapes} read of a conformer. */
+export interface KeptConformer {
+  /** Total energy in kcal/mol, `null` when it was not computed. */
+  energy: number | null;
+  /** The 3D structure, as molfile text. */
+  molfile: { data: string };
+}
+
+/**
+ * Energy gap, in kcal/mol, under which two minimised conformers can be the
+ * same minimum. Copies of one minimum agree to about 1e-7; distinct minima
+ * that close in energy differ in shape by more than a percent.
+ */
+export const SAME_ENERGY_TOLERANCE = 1e-3;
+
+/** Gap between principal moments, relative to the largest, under which two shapes are one. */
+export const SAME_SHAPE_TOLERANCE = 1e-3;
+
+/**
+ * Gap in chirality under which two shapes are one. Copies of one minimum agree
+ * to about 1e-4 and a shape that is its own mirror image reads within 1e-3 of
+ * zero, while the mirror images of a chiral minimum usually sit tenths apart.
+ */
+export const SAME_CHIRALITY_TOLERANCE = 1e-2;
+
+/**
+ * Whether two minimised conformers are one energy minimum: the same energy,
+ * the same principal moments and the same chirality. The two mirror-image
+ * gauche butanes are two minima; the two chairs of cyclohexane, each its own
+ * mirror image, are one.
+ * @param energyA - Total energy of the first conformer, kcal/mol.
+ * @param shapeA - Shape of the first conformer.
+ * @param energyB - Total energy of the second conformer, kcal/mol.
+ * @param shapeB - Shape of the second conformer.
+ * @returns `true` when both agree within {@link SAME_ENERGY_TOLERANCE}, {@link SAME_SHAPE_TOLERANCE} and {@link SAME_CHIRALITY_TOLERANCE}.
+ */
+export function isSameMinimum(
+  energyA: number,
+  shapeA: ConformerShape,
+  energyB: number,
+  shapeB: ConformerShape,
+): boolean {
+  if (Math.abs(energyA - energyB) > SAME_ENERGY_TOLERANCE) return false;
+  return isSameShape(shapeA, shapeB);
+}
+
+/**
+ * Whether two conformers have the same shape: the same principal moments and
+ * the same chirality, energies not consulted. Two mirror images share the
+ * moments and not the chirality, so they are two shapes.
+ * @param shapeA - Shape of one conformer.
+ * @param shapeB - Shape of the other.
+ * @returns `true` when both agree within {@link SAME_SHAPE_TOLERANCE} and {@link SAME_CHIRALITY_TOLERANCE}.
+ */
+export function isSameShape(
+  shapeA: ConformerShape,
+  shapeB: ConformerShape,
+): boolean {
+  if (
+    Math.abs(shapeA.chirality - shapeB.chirality) > SAME_CHIRALITY_TOLERANCE
+  ) {
+    return false;
+  }
+  const momentsA = shapeA.moments;
+  const momentsB = shapeB.moments;
+  const scale = Math.max(momentsA[2], momentsB[2]);
+  for (let axis = 0; axis < 3; axis++) {
+    const gap = Math.abs((momentsA[axis] ?? 0) - (momentsB[axis] ?? 0));
+    if (gap > SAME_SHAPE_TOLERANCE * scale) return false;
+  }
+  return true;
+}
+
+/**
+ * Whether a minimised conformer lands in a minimum one of `kept` already holds.
+ * @param energy - Total energy of the candidate, kcal/mol.
+ * @param shape - Shape of the candidate.
+ * @param kept - The conformers kept so far.
+ * @param keptShapes - Their shapes, index for index; `null` where there is no energy.
+ * @returns `true` when one of them is the same minimum.
+ */
+export function isKeptMinimum(
+  energy: number,
+  shape: ConformerShape,
+  kept: readonly KeptConformer[],
+  keptShapes: ReadonlyArray<ConformerShape | null>,
+): boolean {
+  for (let index = 0; index < kept.length; index++) {
+    const keptEnergy = kept[index]?.energy ?? null;
+    const keptShape = keptShapes[index] ?? null;
+    if (
+      keptEnergy !== null &&
+      keptShape !== null &&
+      isSameMinimum(energy, shape, keptEnergy, keptShape)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Shapes of conformers read back from their molfiles, so a continuation
+ * compares new conformers with the ones a previous run kept.
+ * @param conformers - Conformers of an earlier run.
+ * @returns Their shapes, index for index; `null` for one without an energy.
+ */
+export function minimisedShapes(
+  conformers: readonly KeptConformer[],
+): Array<ConformerShape | null> {
+  const shapes: Array<ConformerShape | null> = [];
+  for (const conformer of conformers) {
+    shapes.push(
+      conformer.energy === null
+        ? null
+        : conformerShape(Molecule.fromMolfile(conformer.molfile.data)),
+    );
+  }
+  return shapes;
+}

package/src/structure/core/conformerOptions.ts

@@ -0,0 +1,125 @@
+/** The four torsion-set strategies OpenChemLib's `ConformerGenerator` offers. */
+export const CONFORMER_STRATEGIES = [
+  'adaptive-random',
+  'likely-random',
+  'pure-random',
+  'likely-systematic',
+] as const;
+
+/** One of {@link CONFORMER_STRATEGIES}. */
+export type ConformerStrategy = (typeof CONFORMER_STRATEGIES)[number];
+
+/** Short names for the strategy picker. */
+export const STRATEGY_LABELS: Record<ConformerStrategy, string> = {
+  '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: Record<ConformerStrategy, string> = {
+  '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+',
+] as const;
+
+/** One of {@link MINIMISATION_ALGORITHMS}. */
+export type MinimisationAlgorithm = (typeof MINIMISATION_ALGORITHMS)[number];
+
+/** Short names for the minimisation picker. */
+export const MINIMISATION_LABELS: Record<MinimisationAlgorithm, string> = {
+  none: 'None (no energies)',
+  MMFF94: 'MMFF94',
+  MMFF94s: 'MMFF94s',
+  'MMFF94s+': 'MMFF94s+',
+};
+
+/** 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 const DEFAULT_CONFORMER_OPTIONS: ConformerOptions = {
+  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: ConformerOptions,
+  second: ConformerOptions,
+): boolean {
+  for (const key of Object.keys(first) as Array<keyof ConformerOptions>) {
+    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: string): value is ConformerStrategy {
+  return (CONFORMER_STRATEGIES as readonly string[]).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: string,
+): value is MinimisationAlgorithm {
+  return (MINIMISATION_ALGORITHMS as readonly string[]).includes(value);
+}

package/src/structure/core/conformerRefine.ts

@@ -0,0 +1,234 @@
+import { Molecule } from 'openchemlib';
+
+import { ordinal } from '../../format/core/words.ts';
+
+import type { RefinedMinimum } from './conformerRefineRank.ts';
+import {
+  isRefinedDuplicate,
+  rankByRefinedEnergy,
+} from './conformerRefineRank.ts';
+import { conformerShape } from './conformerShape.ts';
+import type { Conformer, ConformerSet } from './conformers.ts';
+import type {
+  GeometryRelaxer,
+  RelaxableGeometry,
+  RelaxerOptions,
+} from './geometryRelaxer.ts';
+import {
+  centredRmsd,
+  readRelaxableGeometry,
+  writeRelaxedCoordinates,
+} from './moleculeCoordinates.ts';
+import { toMolfileExport } from './molfileExport.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 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: ConformerSet,
+  relax: GeometryRelaxer,
+  options: RefineConformersOptions = {},
+): Promise<ConformerSet> {
+  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: Array<{
+    conformer: Conformer;
+    molecule: Molecule;
+    geometry: RelaxableGeometry;
+  }> = [];
+  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: Conformer[] = [];
+  const minima: RefinedMinimum[] = [];
+  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: RefinedMinimum = {
+      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,
+    },
+  };
+}

package/src/structure/core/conformerRefineRank.ts

@@ -0,0 +1,89 @@
+import { isSameShape } from './conformerMinimum.ts';
+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 function rankByRefinedEnergy(
+  conformers: readonly Conformer[],
+): RefinedRanking {
+  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: Conformer[] = [];
+  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: RefinedMinimum,
+  kept: readonly RefinedMinimum[],
+  tolerance: number,
+): boolean {
+  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: Conformer, b: Conformer): number {
+  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;
+}