react-cheminfo 0.22.0 → 0.24.0

package/src/scatter/core/pointShape.ts

@@ -0,0 +1,80 @@
+import { chartRoundPixel } from '../../chart/core/chartScale.ts';
+import type { OverlayMarkShape } from '../../overlay/core/overlayMarks.ts';
+
+/**
+ * The outline of a mark drawn as a filled polygon — a sample shaped by a
+ * second grouping, or a marker drawn in one of those shapes — as SVG path data.
+ *
+ * Every shape covers the area of the disc it stands in for. The eye weighs a
+ * mark by its ink, so a square drawn in the disc's own box would make its
+ * group read as the heavier one — which is a claim about the data that nothing
+ * in the data supports.
+ * @param shape - The shape.
+ * @param x - Horizontal centre, in pixels.
+ * @param y - Vertical centre, in pixels.
+ * @param radius - Radius of the disc the shape stands in for, in pixels.
+ * @returns The path data, or `null` for a disc, which is drawn as a circle,
+ * and for every mark that is not a filled polygon.
+ */
+export function pointShapePath(
+  shape: OverlayMarkShape,
+  x: number,
+  y: number,
+  radius: number,
+): string | null {
+  if (shape === 'square') {
+    const half = SQUARE_HALF * radius;
+    return polygon([
+      [x - half, y - half],
+      [x + half, y - half],
+      [x + half, y + half],
+      [x - half, y + half],
+    ]);
+  }
+  if (shape === 'diamond') {
+    const reach = DIAMOND_REACH * radius;
+    return polygon([
+      [x, y - reach],
+      [x + reach, y],
+      [x, y + reach],
+      [x - reach, y],
+    ]);
+  }
+  if (shape === 'triangle' || shape === 'triangle-down') {
+    // The centroid sits on the point, so the triangle is balanced on the
+    // sample rather than hanging from it.
+    const tip = TRIANGLE_TIP * radius;
+    const half = TRIANGLE_HALF_BASE * radius;
+    const base = (TRIANGLE_TIP / 2) * radius;
+    const flip = shape === 'triangle' ? 1 : -1;
+    return polygon([
+      [x, y - flip * tip],
+      [x + half, y + flip * base],
+      [x - half, y + flip * base],
+    ]);
+  }
+  return null;
+}
+
+function polygon(corners: ReadonlyArray<readonly [number, number]>): string {
+  let path = '';
+  for (const [x, y] of corners) {
+    path += `${path === '' ? 'M' : 'L'}${chartRoundPixel(x)} ${chartRoundPixel(y)}`;
+  }
+  return `${path}Z`;
+}
+
+/** Half the side of a square as large as a disc of radius one: √π / 2. */
+const SQUARE_HALF = Math.sqrt(Math.PI) / 2;
+
+/** How far a diamond as large as that disc reaches from its centre: √(π / 2). */
+const DIAMOND_REACH = Math.sqrt(Math.PI / 2);
+
+/**
+ * The side of an equilateral triangle as large as that disc is √(4π / √3). Its
+ * tip stands side / √3 from the centroid, and its base half as far on the other
+ * side.
+ */
+const TRIANGLE_SIDE = Math.sqrt((4 * Math.PI) / Math.sqrt(3));
+const TRIANGLE_TIP = TRIANGLE_SIDE / Math.sqrt(3);
+const TRIANGLE_HALF_BASE = TRIANGLE_SIDE / 2;

package/src/scatter/ui/ScatterPlot.tsx

@@ -32,7 +32,8 @@ import { useScatterLabels } from './useScatterLabels.ts';
  */
 export function ScatterPlot(props: ScatterPlotProps): ReactElement {
   const { x, y, width, height, xAxis, yAxis, groupOf, groups } = props;
-  const { mutedGroups, ellipse = null, ellipseMinimumPoints } = props;
+  const { mutedGroups, shapeOf, shapes } = props;
+  const { ellipse = null, ellipseMinimumPoints } = props;
   const { ellipseFillOpacity, showGroupMeans, markers } = props;
   const { pointRadius = 3.5, outlinedFrom, pointLabels } = props;
   const { showGroupLabels = false, selected, defaultSelected } = props;
@@ -127,6 +128,8 @@ export function ScatterPlot(props: ScatterPlotProps): ReactElement {
             groupOf={groupOf}
             colors={ink.colors}
             opacities={ink.opacities}
+            shapeOf={shapeOf}
+            shapes={shapes}
             radius={pointRadius}
             outlinedFrom={outlinedFrom}
           />

package/src/scatter/ui/ScatterPointLayer.tsx

@@ -3,6 +3,8 @@ import { memo } from 'react';
 
 import { chartGroupIndex } from '../../chart/core/chartGroups.ts';
 import { chartRoundPixel } from '../../chart/core/chartScale.ts';
+import type { OverlaySampleShape } from '../../overlay/core/overlayMarks.ts';
+import { pointShapePath } from '../core/pointShape.ts';
 import type { ScreenPoints } from '../core/screenPoints.ts';
 
 /** What {@link ScatterPointLayer} draws. */
@@ -31,6 +33,17 @@ export interface ScatterPointLayerProps {
    * @default undefined — every group is drawn at full strength
    */
   opacities?: readonly number[];
+  /**
+   * Which shape each point takes, as an index into `shapes`. An entry of `-1`,
+   * or one outside the range, is a disc.
+   * @default undefined — every point is a disc
+   */
+  shapeOf?: ArrayLike<number>;
+  /**
+   * The shapes, in the order `shapeOf` names them.
+   * @default undefined
+   */
+  shapes?: readonly OverlaySampleShape[];
   /**
    * Colour of a point belonging to no group. It has to be the one ink on the
    * plot that names nothing, or a reader counts it as one more group.
@@ -77,7 +90,8 @@ export interface ScatterPointLayerProps {
  *
  * A hollow dot is the same dot at the same radius with its colour moved from
  * the fill to the stroke, so the two read as one kind of thing seen at two
- * levels of confidence rather than as two unrelated marks.
+ * levels of confidence rather than as two unrelated marks. A shaped point
+ * follows the same rule, and covers the area of the disc it stands in for.
  * @param props - See {@link ScatterPointLayerProps}.
  * @returns The cloud.
  */
@@ -89,6 +103,8 @@ export const ScatterPointLayer = memo(function ScatterPointLayer(
     groupOf,
     colors,
     opacities,
+    shapeOf,
+    shapes,
     fallbackColor = 'var(--text-faint)',
     radius = 3.5,
     radii,
@@ -102,6 +118,7 @@ export const ScatterPointLayer = memo(function ScatterPointLayer(
   const steps = order === undefined ? count : Math.min(count, order.length);
   const hollowFrom = outlineStart(outlinedFrom, count);
   const groups = colors?.length ?? 0;
+  const shapeCount = shapes?.length ?? 0;
   const ink = groupInk(colors, opacities, fallbackColor);
 
   const dots: ReactElement[] = [];
@@ -115,17 +132,28 @@ export const ScatterPointLayer = memo(function ScatterPointLayer(
     const color = ink.colors[slot] ?? fallbackColor;
     const hollow = index >= hollowFrom;
     const size = radii?.[index];
+    const reach = size === undefined ? radius : chartRoundPixel(size);
+    const shape = shapes?.[chartGroupIndex(shapeOf, index, shapeCount)];
+    const outline =
+      shape === undefined ? null : pointShapePath(shape, x, y, reach);
+    const paint = {
+      fill: hollow ? 'none' : color,
+      stroke: hollow ? color : undefined,
+      strokeWidth: hollow ? OUTLINE_WIDTH : undefined,
+      opacity: ink.opacities[slot],
+    };
     dots.push(
-      <circle
-        key={index}
-        cx={chartRoundPixel(x)}
-        cy={chartRoundPixel(y)}
-        r={size === undefined ? radius : chartRoundPixel(size)}
-        fill={hollow ? 'none' : color}
-        stroke={hollow ? color : undefined}
-        strokeWidth={hollow ? OUTLINE_WIDTH : undefined}
-        opacity={ink.opacities[slot]}
-      />,
+      outline === null ? (
+        <circle
+          key={index}
+          cx={chartRoundPixel(x)}
+          cy={chartRoundPixel(y)}
+          r={reach}
+          {...paint}
+        />
+      ) : (
+        <path key={index} d={outline} {...paint} />
+      ),
     );
   }
 

package/src/scatter/ui/scatterFigureProps.ts

@@ -9,6 +9,7 @@
 
 import type { ReactNode } from 'react';
 
+import type { OverlaySampleShape } from '../../overlay/core/overlayMarks.ts';
 import type { ScatterSelectionMode } from '../core/scatterSelection.ts';
 
 import type { SelectionChange } from './useScatterSelection.ts';
@@ -61,6 +62,18 @@ export interface ScatterGroupProps {
    * @default undefined — every group is drawn in full
    */
   mutedGroups?: ReadonlySet<string>;
+  /**
+   * Which shape each point takes, as an index into `shapes`: a second
+   * grouping of the same points, drawn while colour keeps the first. A point
+   * with `-1`, `NaN`, or an index outside the range, is a disc.
+   * @default undefined — every point is a disc
+   */
+  shapeOf?: ArrayLike<number>;
+  /**
+   * The shapes, in the order `shapeOf` names them.
+   * @default undefined
+   */
+  shapes?: readonly OverlaySampleShape[];
   /**
    * Radius of a dot, in pixels. A cloud draws the dot at the middle of its box
    * at this size, one at the front larger and one at the back smaller.

package/src/scatter/ui/scatterMarkGlyph.tsx

@@ -10,6 +10,7 @@ import type { ReactElement } from 'react';
 
 import { chartRoundPixel } from '../../chart/core/chartScale.ts';
 import type { OverlayMarkShape } from '../../overlay/core/overlayMarks.ts';
+import { pointShapePath } from '../core/pointShape.ts';
 
 /** A point drawn over the cloud that is not a sample, already in pixels. */
 export interface ScatterPixelMark {
@@ -32,7 +33,8 @@ export interface ScatterPixelMark {
  * One mark, drawn as the glyph its shape asks for.
  *
  * A rule laid across the cloud names no point, so the two rule shapes are
- * drawn as the default cross.
+ * drawn as the default cross. The three filled polygons are the shapes a
+ * sample can take, drawn as large as the disc they stand in for.
  * @param mark - What to draw, already in the frame's pixels.
  * @param size - Side of the square the glyph is drawn in, in pixels.
  * @param key - What React reconciles the glyph by.
@@ -81,6 +83,12 @@ export function markGlyph(
       />
     );
   }
+  const polygon = pointShapePath(shape, x, y, half);
+  if (polygon !== null) {
+    return (
+      <path key={key} {...shared} d={polygon} fill={color} stroke="none" />
+    );
+  }
   return (
     <path
       key={key}

package/src/scatter3d/ui/ScatterCloud.tsx

@@ -47,6 +47,7 @@ import { useOrbitDrag } from './useOrbitDrag.ts';
 export function ScatterCloud(props: ScatterCloudProps): ReactElement {
   const { x, y, z, width, height, xLabel, yLabel, zLabel } = props;
   const { groupOf, groups, mutedGroups, ellipsoid = null } = props;
+  const { shapeOf, shapes } = props;
   const { ellipsoidMinimumPoints, ellipsoidFillOpacity } = props;
   const { showGroupLabels = false, pointLabels, pointRadius = 3.5 } = props;
   const { outlinedFrom, selected, defaultSelected, onSelectionChange } = props;
@@ -198,6 +199,8 @@ export function ScatterCloud(props: ScatterCloudProps): ReactElement {
           groupOf={groupOf}
           colors={ink.colors}
           opacities={ink.opacities}
+          shapeOf={shapeOf}
+          shapes={shapes}
           radius={pointRadius}
           outlinedFrom={outlinedFrom}
         />

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);
+}