react-cheminfo 0.22.0 → 0.24.0

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

package/src/structure/core/conformerSession.ts

@@ -0,0 +1,123 @@
+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 function openConformerSession(
+  prepared: Molecule,
+  options: ConformerOptions,
+  produced: number,
+): ConformerSession {
+  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: Molecule,
+  options: ConformerOptions,
+  session: ConformerSession,
+): void {
+  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: ConformerSession): number {
+  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: ConformerStrategy): number {
+  return STRATEGY_CONSTANTS[strategy];
+}
+
+const STRATEGY_CONSTANTS: Record<ConformerStrategy, number> = {
+  '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: { key: string; session: ConformerSession } | null = null;
+
+// The atom order matters as much as the structure, so the molfile is the key.
+function sessionKey(prepared: Molecule, options: ConformerOptions): string {
+  return [
+    options.strategy,
+    options.seed,
+    options.maxTorsionSets,
+    options.use60DegreeSteps,
+    prepared.toMolfileV3(),
+  ].join('\n');
+}

package/src/structure/core/conformerShape.ts

@@ -0,0 +1,181 @@
+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 function conformerShape(molecule: Molecule): ConformerShape {
+  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: 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: Molecule): boolean {
+  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;
+
+type Vector = readonly [number, number, number];
+
+/** Second moments of the atoms about their centre: a symmetric 3×3 matrix. */
+interface Tensor {
+  xx: number;
+  yy: number;
+  zz: number;
+  xy: number;
+  xz: number;
+  yz: number;
+}
+
+// Unit eigenvector of `moment`: the longest cross product of two rows of the tensor minus `moment`.
+function principalAxis(tensor: Tensor, moment: number): Vector | null {
+  const rows: Vector[] = [
+    [tensor.xx - moment, tensor.xy, tensor.xz],
+    [tensor.xy, tensor.yy - moment, tensor.yz],
+    [tensor.xz, tensor.yz, tensor.zz - moment],
+  ];
+  let best: Vector = [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] as Vector, rows[b] as Vector);
+      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: Vector, b: Vector): Vector {
+  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: Tensor): PrincipalMoments {
+  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];
+}