react-cheminfo 0.2.0 → 0.4.0

package/src/orbital/core/occupancy.ts

@@ -0,0 +1,100 @@
+/**
+ * How the electrons of one atom are laid out over its orbitals, and the two
+ * adjustments a *virtual* orbital needs.
+ *
+ * Split out of `atomicOrbitals.ts` so that module stays what it says it is —
+ * the join of a configuration, a screening, a radial function and a harmonic —
+ * with none of the bookkeeping in the way.
+ */
+
+import type { SubshellOccupancy } from './electronConfiguration.ts';
+import { groupRank } from './screening.ts';
+
+/** No known element occupies a shell above n = 7. */
+const HIGHEST_SHELL = 7;
+
+/**
+ * Slater's rules can hand a badly-screened orbital a charge at or below zero —
+ * a 7p on hydrogen, say — which has no bound hydrogen-like solution. Clamping
+ * to a small positive charge keeps such an orbital enormous and diffuse, which
+ * is the honest picture, rather than throwing.
+ */
+export const MINIMUM_CHARGE = 0.3;
+
+/**
+ * Spread electrons over the orbitals of a subshell by Hund's rule.
+ * @param electrons - Electrons in the subshell.
+ * @param orbitalCount - `2ℓ + 1`.
+ * @returns One count per orbital: singles first, then pairs.
+ */
+export function hundDistribution(
+  electrons: number,
+  orbitalCount: number,
+): number[] {
+  const spread = new Array<number>(orbitalCount).fill(0);
+  const capacity = orbitalCount * 2;
+  let left = Math.min(electrons, capacity);
+  for (let pass = 0; pass < 2 && left > 0; pass++) {
+    for (let index = 0; index < orbitalCount && left > 0; index++) {
+      spread[index] = (spread[index] as number) + 1;
+      left -= 1;
+    }
+  }
+  return spread;
+}
+
+/**
+ * How far up the list goes when the caller does not say.
+ * @param valenceShell - Outermost occupied shell.
+ * @returns One shell past it, never below 4 and never above 7.
+ */
+export function defaultMaximumShell(valenceShell: number): number {
+  return Math.min(HIGHEST_SHELL, Math.max(4, valenceShell + 1));
+}
+
+/**
+ * The configuration with one electron taken out of the outermost occupied
+ * subshell — the atom as it is while one of its electrons sits in a virtual
+ * orbital.
+ * @param configuration - The ground-state configuration to reduce.
+ * @returns The reduced configuration, empty subshells dropped.
+ */
+export function withoutOutermostElectron(
+  configuration: readonly SubshellOccupancy[],
+): SubshellOccupancy[] {
+  let outermost = -1;
+  for (let index = 0; index < configuration.length; index++) {
+    const entry = configuration[index] as SubshellOccupancy;
+    const best = configuration[outermost];
+    if (
+      outermost === -1 ||
+      best === undefined ||
+      groupRank(entry) > groupRank(best)
+    ) {
+      outermost = index;
+    }
+  }
+  const reduced: SubshellOccupancy[] = [];
+  for (let index = 0; index < configuration.length; index++) {
+    const entry = configuration[index] as SubshellOccupancy;
+    const electrons =
+      index === outermost ? entry.electrons - 1 : entry.electrons;
+    if (electrons > 0) reduced.push({ ...entry, electrons });
+  }
+  return reduced;
+}
+
+/**
+ * The outermost shell an atom actually occupies.
+ * @param configuration - Its configuration.
+ * @returns The largest `n` holding an electron.
+ */
+export function outermostShell(
+  configuration: readonly SubshellOccupancy[],
+): number {
+  let outermost = 1;
+  for (const entry of configuration) {
+    if (entry.electrons > 0 && entry.n > outermost) outermost = entry.n;
+  }
+  return outermost;
+}

package/src/orbital/core/palette.ts

@@ -0,0 +1,56 @@
+/**
+ * Colours for orbital phases and nodal surfaces.
+ *
+ * Plain data: the renderer picks a palette, this module says what the hex
+ * values are. Two phase palettes ship, and both are first-class — around 8% of
+ * male students have a red/green or red/blue-at-low-luminance deficiency, so
+ * the blue/yellow pair is a supported choice, not a fallback.
+ */
+
+/** Which pair of phase colours the viewer uses. */
+export type PhasePaletteId = 'textbook' | 'colourBlindSafe';
+
+/** The colours one phase palette provides. */
+export interface PhasePalette {
+  id: PhasePaletteId;
+  /** Name shown in the palette picker. */
+  label: string;
+  /** Lobe where the wavefunction is positive. */
+  positive: string;
+  /** Lobe where the wavefunction is negative. */
+  negative: string;
+  /** Lobe drawn with the `phase` display flag off. */
+  neutral: string;
+  /** Translucent disc marking a nodal plane. */
+  node: string;
+}
+
+/**
+ * The two phase palettes.
+ *
+ * `textbook` is the blue/red of printed MO diagrams and of Jmol's signed
+ * isosurfaces; `colourBlindSafe` swaps the negative lobe for the amber of the
+ * Okabe-Ito qualitative palette, which stays separable under protanopia,
+ * deuteranopia and tritanopia.
+ */
+export const PHASE_PALETTES: Record<PhasePaletteId, PhasePalette> = {
+  textbook: {
+    id: 'textbook',
+    label: 'Blue / red (textbook)',
+    positive: '#2563eb',
+    negative: '#dc2626',
+    neutral: '#9ca3af',
+    node: '#64748b',
+  },
+  colourBlindSafe: {
+    id: 'colourBlindSafe',
+    label: 'Blue / yellow (colour-blind safe)',
+    positive: '#0072b2',
+    negative: '#e69f00',
+    neutral: '#9ca3af',
+    node: '#56606b',
+  },
+};
+
+/** Palette used until the student picks another one. */
+export const DEFAULT_PHASE_PALETTE_ID: PhasePaletteId = 'textbook';

package/src/orbital/core/realHarmonics.ts

@@ -0,0 +1,172 @@
+/**
+ * The real spherical harmonics, ℓ = 0 to 3, written as cartesian ratios.
+ *
+ * These are the angular halves of the orbitals a chemist draws: the real
+ * combinations `p_x, p_y, p_z` rather than the complex `m = −1, 0, +1`, because
+ * only the real ones have the lobes along axes that a bond can point at.
+ *
+ * Each is normalised so that `∫|Y|² dΩ = 1` over the unit sphere, and each is
+ * given `(x, y, z)` in ångström together with their length, so sampling a grid
+ * never calls `acos` or `atan2`. The number of angular nodes is exactly ℓ, and
+ * this file is where that fact becomes visible: `s` has none, every `p` has one
+ * plane, every `d` two surfaces, every `f` three.
+ *
+ * `key` is ascii and appears in a URL — `#/elements/Fe/3dx2-y2`; `label` is the
+ * typeset subscript a student reads.
+ */
+
+/** Subshell letter for an angular momentum, `s p d f`. */
+export const SUBSHELL_LETTERS = ['s', 'p', 'd', 'f'] as const;
+
+/** One real spherical harmonic. */
+export interface RealHarmonic {
+  /** Angular momentum quantum number, also the count of angular nodes. */
+  l: number;
+  /** Ascii subscript, url-safe: `x`, `z2`, `x2-y2`, `y_3x2-y2`. */
+  key: string;
+  /** Typeset subscript, e.g. `x²−y²`. Empty for `s`. */
+  label: string;
+  /**
+   * Value of the harmonic at a point.
+   * @param x - Offset from the nucleus along x, ångström.
+   * @param y - Offset from the nucleus along y, ångström.
+   * @param z - Offset from the nucleus along z, ångström.
+   * @param radius - Length of `(x, y, z)`, passed in because the caller has
+   * already computed it for the radial part.
+   * @returns The dimensionless amplitude; 0 at the nucleus for ℓ > 0.
+   */
+  evaluate: (x: number, y: number, z: number, radius: number) => number;
+}
+
+const FOUR_PI = 4 * Math.PI;
+
+const S = Math.sqrt(1 / FOUR_PI);
+const P = Math.sqrt(3 / FOUR_PI);
+const D_Z2 = Math.sqrt(5 / (16 * Math.PI));
+const D_PLANAR = Math.sqrt(15 / FOUR_PI);
+const D_X2Y2 = Math.sqrt(15 / (16 * Math.PI));
+const F_Z3 = Math.sqrt(7 / (16 * Math.PI));
+const F_XZ2 = Math.sqrt(21 / (32 * Math.PI));
+const F_ZX2Y2 = Math.sqrt(105 / (16 * Math.PI));
+const F_XYZ = Math.sqrt(105 / FOUR_PI);
+const F_CUBIC = Math.sqrt(35 / (32 * Math.PI));
+
+/**
+ * The harmonics of one shell, indexed by ℓ: `REAL_HARMONICS[2]` is the five d
+ * functions. The order inside a shell is the one the orbital list shows.
+ */
+export const REAL_HARMONICS: RealHarmonic[][] = [
+  [{ l: 0, key: '', label: '', evaluate: () => S }],
+  [
+    { l: 1, key: 'x', label: 'x', evaluate: (x, y, z, r) => (P * x) / r },
+    { l: 1, key: 'y', label: 'y', evaluate: (x, y, z, r) => (P * y) / r },
+    { l: 1, key: 'z', label: 'z', evaluate: (x, y, z, r) => (P * z) / r },
+  ],
+  [
+    {
+      l: 2,
+      key: 'z2',
+      label: 'z²',
+      evaluate: (x, y, z, r) => (D_Z2 * (3 * z * z - r * r)) / (r * r),
+    },
+    {
+      l: 2,
+      key: 'xz',
+      label: 'xz',
+      evaluate: (x, y, z, r) => (D_PLANAR * x * z) / (r * r),
+    },
+    {
+      l: 2,
+      key: 'yz',
+      label: 'yz',
+      evaluate: (x, y, z, r) => (D_PLANAR * y * z) / (r * r),
+    },
+    {
+      l: 2,
+      key: 'xy',
+      label: 'xy',
+      evaluate: (x, y, z, r) => (D_PLANAR * x * y) / (r * r),
+    },
+    {
+      l: 2,
+      key: 'x2-y2',
+      label: 'x²−y²',
+      evaluate: (x, y, z, r) => (D_X2Y2 * (x * x - y * y)) / (r * r),
+    },
+  ],
+  [
+    {
+      l: 3,
+      key: 'z3',
+      label: 'z³',
+      evaluate: (x, y, z, r) =>
+        (F_Z3 * z * (5 * z * z - 3 * r * r)) / (r * r * r),
+    },
+    {
+      l: 3,
+      key: 'xz2',
+      label: 'xz²',
+      evaluate: (x, y, z, r) => (F_XZ2 * x * (5 * z * z - r * r)) / (r * r * r),
+    },
+    {
+      l: 3,
+      key: 'yz2',
+      label: 'yz²',
+      evaluate: (x, y, z, r) => (F_XZ2 * y * (5 * z * z - r * r)) / (r * r * r),
+    },
+    {
+      l: 3,
+      key: 'xyz',
+      label: 'xyz',
+      evaluate: (x, y, z, r) => (F_XYZ * x * y * z) / (r * r * r),
+    },
+    {
+      l: 3,
+      key: 'z_x2-y2',
+      label: 'z(x²−y²)',
+      evaluate: (x, y, z, r) => (F_ZX2Y2 * z * (x * x - y * y)) / (r * r * r),
+    },
+    {
+      l: 3,
+      key: 'x_x2-3y2',
+      label: 'x(x²−3y²)',
+      evaluate: (x, y, z, r) =>
+        (F_CUBIC * x * (x * x - 3 * y * y)) / (r * r * r),
+    },
+    {
+      l: 3,
+      key: 'y_3x2-y2',
+      label: 'y(3x²−y²)',
+      evaluate: (x, y, z, r) =>
+        (F_CUBIC * y * (3 * x * x - y * y)) / (r * r * r),
+    },
+  ],
+];
+
+/**
+ * The harmonics of one subshell.
+ * @param l - Angular momentum quantum number, 0 to 3.
+ * @returns Its `2ℓ + 1` real harmonics, in list order.
+ * @throws {Error} When ℓ is outside the s, p, d and f shells this site draws.
+ */
+export function harmonicsOf(l: number): RealHarmonic[] {
+  const shell = REAL_HARMONICS[l];
+  if (shell === undefined) {
+    throw new RangeError(`no real harmonics for angular momentum ${l}`);
+  }
+  return shell;
+}
+
+/**
+ * The letter naming a subshell.
+ * @param l - Angular momentum quantum number, 0 to 3.
+ * @returns `s`, `p`, `d` or `f`.
+ * @throws {Error} When ℓ is outside them.
+ */
+export function subshellLetter(l: number): string {
+  const letter = SUBSHELL_LETTERS[l];
+  if (letter === undefined) {
+    throw new RangeError(`no subshell letter for angular momentum ${l}`);
+  }
+  return letter;
+}

package/src/orbital/core/sample.ts

@@ -0,0 +1,111 @@
+/**
+ * The one job the viewer asks for, shaped so it can cross a worker boundary.
+ *
+ * The request carries an atomic number and an orbital id, never an
+ * `AtomicOrbital`: that object holds its spherical harmonic as a
+ * function*, which the structured clone algorithm cannot copy. Rebuilding the
+ * list from two plain values costs microseconds and keeps the boundary honest.
+ *
+ * A site that would rather not spend ~25 ms of its main thread per orbital
+ * implements this contract in a worker and hands `AtomicOrbitalViewer` the
+ * `sample` prop; one that does not gets the in-process version for free.
+ */
+
+import type { AtomicGridOptions, ResolutionLimits } from './atomicGrid.ts';
+import { atomicGridResolution, sampleAtomicOrbital } from './atomicGrid.ts';
+import {
+  atomicOrbitalsOf,
+  findAtomicOrbital,
+  hydrogenicParametersOf,
+} from './atomicOrbitals.ts';
+import type { OrbitalGrid } from './grid.ts';
+import { radialNodeRadii } from './hydrogenic.ts';
+import type { OrbitalContour } from './isovalue.ts';
+import { orbitalContour } from './isovalue.ts';
+
+/** Which orbital to sample, and how finely. */
+export interface AtomicSampleRequest {
+  /** Proton count, 1 to 118. */
+  atomicNumber: number;
+  /** Which orbital of that element, e.g. `3dz2`. */
+  orbitalId: string;
+  /**
+   * Samples along each edge of the cube. The cost is the cube of this.
+   *
+   * A number fixes the resolution. {@link ResolutionLimits} lets the orbital's
+   * own shape pick one between the two, which is what a nested orbital needs —
+   * see {@link atomicGridResolution}.
+   * @default 56
+   */
+  resolution?: number | ResolutionLimits;
+}
+
+/** What one sampling job produces. */
+export interface AtomicSampleResult {
+  /** The signed field, ready for an isosurface. */
+  grid: OrbitalGrid;
+  /**
+   * The isovalue both phases are drawn at, and how far the pair reaches.
+   *
+   * Measured here rather than beside the renderer: both passes are O(samples),
+   * and at the resolutions a nested orbital asks for that is over a million of
+   * them on whichever thread runs this.
+   */
+  contour: OrbitalContour;
+  /** Radii of the orbital's radial nodes, ångström, ascending. */
+  nodeRadii: number[];
+}
+
+/**
+ * Sample one atomic orbital onto a grid.
+ *
+ * Synchronous and free of React, molstar and the DOM, so it runs unchanged on
+ * the main thread, in a worker, and under vitest.
+ * @param request - See {@link AtomicSampleRequest}.
+ * @returns The field, and where its radial nodes are.
+ * @throws {Error} When the element or the orbital id names nothing.
+ */
+export function runAtomicSample(
+  request: AtomicSampleRequest,
+): AtomicSampleResult {
+  const { atomicNumber, orbitalId, resolution } = request;
+  const orbitals = atomicOrbitalsOf(atomicNumber);
+  const orbital = findAtomicOrbital(orbitals, orbitalId);
+  if (orbital === null) {
+    throw new Error(
+      `Element ${atomicNumber} has no orbital ${orbitalId}. Known: ${orbitals
+        .map((entry) => entry.id)
+        .join(', ')}.`,
+    );
+  }
+  const options: AtomicGridOptions = {};
+  if (typeof resolution === 'number') {
+    options.resolution = resolution;
+  } else if (resolution !== undefined) {
+    options.resolution = atomicGridResolution(orbital, resolution);
+  }
+  const grid = sampleAtomicOrbital(orbital, options);
+  return {
+    grid,
+    contour: orbitalContour(grid),
+    nodeRadii: radialNodeRadii(hydrogenicParametersOf(orbital)),
+  };
+}
+
+/** How a caller supplies the sampling — in process, or through a worker. */
+export type AtomicSampler = (
+  request: AtomicSampleRequest,
+) => Promise<AtomicSampleResult>;
+
+/**
+ * The default sampler: {@link runAtomicSample}, yielded to the event loop so
+ * the spinner has painted before the main thread is taken.
+ * @param request - See {@link AtomicSampleRequest}.
+ * @returns The field, and where its radial nodes are.
+ */
+export const sampleInProcess: AtomicSampler = async (request) => {
+  await new Promise((resolve) => {
+    setTimeout(resolve, 0);
+  });
+  return runAtomicSample(request);
+};

package/src/orbital/core/screening.ts

@@ -0,0 +1,90 @@
+/**
+ * Slater's rules: how much of the nucleus an electron actually feels.
+ *
+ * A hydrogen-like orbital needs one number, the effective nuclear charge, and
+ * taking the full `Z` would draw carbon's 2p six times too small. Slater's rules
+ * estimate the shielding `S` from the other electrons, and `Z_eff = Z − S` is
+ * what the radial function is built with.
+ *
+ * They are an empirical fit from 1930, not a calculation — but they are the ones
+ * every general-chemistry course teaches, they reproduce the periodic trends
+ * that matter (Z_eff rises across a period, barely moves down a group), and a
+ * student can check the arithmetic here against the one they did by hand.
+ *
+ * The electrons are grouped as Slater grouped them, with s and p sharing a
+ * group and each d and f standing alone:
+ *
+ * ```
+ * [1s] [2s2p] [3s3p] [3d] [4s4p] [4d] [4f] [5s5p] [5d] [5f] [6s6p] [6d] [7s7p]
+ * ```
+ */
+
+import type { Subshell, SubshellOccupancy } from './electronConfiguration.ts';
+
+/** The shielding an orbital feels, and what is left of the nuclear charge. */
+export interface Screening {
+  /** Sum of the shielding contributions, `S`. */
+  shielding: number;
+  /** `Z − S`, the charge the hydrogen-like radial function is built with. */
+  effectiveCharge: number;
+}
+
+/**
+ * Apply Slater's rules to one subshell of one atom.
+ * @param atomicNumber - Proton count, the `Z` the shielding is subtracted from.
+ * @param configuration - Every occupied subshell of the atom.
+ * @param subshell - The subshell whose electron is being screened.
+ * @returns Its shielding and effective nuclear charge.
+ */
+export function slaterScreening(
+  atomicNumber: number,
+  configuration: readonly SubshellOccupancy[],
+  subshell: Subshell,
+): Screening {
+  const rank = groupRank(subshell);
+  const isCore = subshell.n === 1;
+  const isDiffuse = subshell.l >= 2;
+  let shielding = 0;
+  for (const occupied of configuration) {
+    const otherRank = groupRank(occupied);
+    if (otherRank > rank) continue;
+    if (otherRank === rank) {
+      // An electron does not shield itself, so one is left out — but only from
+      // its *own* subshell. 2s and 2p share a group, and every one of carbon's
+      // two 2s electrons shields its 2p electron in full.
+      const others = Math.max(
+        0,
+        occupied.electrons - (sameSubshell(occupied, subshell) ? 1 : 0),
+      );
+      shielding += others * (isCore ? 0.3 : 0.35);
+      continue;
+    }
+    if (isDiffuse) {
+      // A d or f electron is screened completely by everything inside it.
+      shielding += occupied.electrons;
+      continue;
+    }
+    shielding +=
+      occupied.electrons * (occupied.n === subshell.n - 1 ? 0.85 : 1);
+  }
+  return {
+    shielding,
+    effectiveCharge: atomicNumber - shielding,
+  };
+}
+
+/**
+ * Where a subshell sits in Slater's left-to-right ordering of groups.
+ *
+ * s and p of the same shell share a group, so they share a rank; d and f each
+ * get their own, placed after the s/p group of the same `n`.
+ * @param subshell - The subshell to rank.
+ * @returns A comparable rank; equal ranks mean the same Slater group.
+ */
+export function groupRank(subshell: Subshell): number {
+  return subshell.n * 10 + (subshell.l <= 1 ? 0 : subshell.l);
+}
+
+function sameSubshell(first: Subshell, second: Subshell): boolean {
+  return first.n === second.n && first.l === second.l;
+}