react-cheminfo 0.1.0 → 0.3.0

package/src/orbital/core/atomicOrbitals.ts

@@ -0,0 +1,212 @@
+/**
+ * Every orbital of one element, assembled from the four parts that describe it.
+ *
+ * The configuration says which subshells hold electrons, Slater's rules say how
+ * strongly each is bound, the hydrogen-like radial function gives it a size and
+ * its radial nodes, and a real spherical harmonic gives it a shape. This module
+ * is only the join — it computes nothing itself, which is what keeps each of
+ * those four testable on its own.
+ *
+ * Electrons inside a subshell are spread by Hund's rule: every orbital of the
+ * subshell takes one before any takes a second. That is why nitrogen shows
+ * three singly-occupied 2p orbitals and oxygen one pair and two singles.
+ */
+
+import {
+  MADELUNG_ORDER,
+  configurationOf,
+  subshellLabel,
+} from './electronConfiguration.ts';
+import type { HydrogenicParameters } from './hydrogenic.ts';
+import { meanRadius, orbitalEnergy, radialNodeCount } from './hydrogenic.ts';
+import {
+  MINIMUM_CHARGE,
+  defaultMaximumShell,
+  hundDistribution,
+  outermostShell,
+  withoutOutermostElectron,
+} from './occupancy.ts';
+import type { RealHarmonic } from './realHarmonics.ts';
+import { harmonicsOf, subshellLetter } from './realHarmonics.ts';
+import { slaterScreening } from './screening.ts';
+
+/** One atomic orbital of one element: a shape, a size and an occupancy. */
+export interface AtomicOrbital {
+  /** Url-safe and unique within the element, e.g. `3dx2-y2`. */
+  id: string;
+  n: number;
+  /** Angular momentum quantum number: 0 = s, 1 = p, 2 = d, 3 = f. */
+  l: number;
+  /** Which of the `2ℓ + 1` real harmonics of the subshell. */
+  harmonic: RealHarmonic;
+  /** Subshell name without the subscript, e.g. `3d`. */
+  shell: string;
+  /** Electrons in this one orbital: 0, 1 or 2, after Hund's rule. */
+  electrons: number;
+  /** Electrons in the whole subshell. */
+  subshellElectrons: number;
+  /** Effective nuclear charge from Slater's rules. */
+  effectiveCharge: number;
+  /** Shielding `S` those rules produced. */
+  shielding: number;
+  /** `−13.6 Z_eff²/n²`, electronvolts. */
+  energy: number;
+  /** `n − ℓ − 1` spheres on which the wavefunction changes sign. */
+  radialNodes: number;
+  /** ℓ planes or cones on which it changes sign. */
+  angularNodes: number;
+  /** `⟨r⟩`, ångström. */
+  meanRadius: number;
+  /** True when the subshell is empty in the ground state. */
+  isVirtual: boolean;
+  /** True when this is the outermost occupied shell. */
+  isValence: boolean;
+}
+
+/** Options for {@link atomicOrbitalsOf}. */
+export interface AtomicOrbitalOptions {
+  /**
+   * Highest principal quantum number to include. Defaults to one shell past
+   * the outermost occupied one, and never below 4 — a hydrogen atom whose list
+   * stopped at 2p would be missing exactly the 3d and 4f pictures it is famous
+   * for.
+   * @default max(4, outermost occupied n + 1), capped at 7
+   */
+  maximumShell?: number;
+}
+
+/**
+ * Every orbital of an element, in Madelung (roughly energetic) order.
+ * @param atomicNumber - Proton count, 1 to 118.
+ * @param options - See {@link AtomicOrbitalOptions}.
+ * @returns The orbitals, occupied ones first in filling order and the empty
+ * ones after them in the same order.
+ * @throws {Error} When the atomic number is outside the periodic table.
+ */
+export function atomicOrbitalsOf(
+  atomicNumber: number,
+  options: AtomicOrbitalOptions = {},
+): AtomicOrbital[] {
+  const configuration = configurationOf(atomicNumber);
+  const valenceShell = outermostShell(configuration);
+  const { maximumShell = defaultMaximumShell(valenceShell) } = options;
+  const occupancies = new Map<string, number>();
+  for (const entry of configuration) {
+    occupancies.set(`${entry.n}.${entry.l}`, entry.electrons);
+  }
+  const promoted = withoutOutermostElectron(configuration);
+
+  const orbitals: AtomicOrbital[] = [];
+  for (const subshell of MADELUNG_ORDER) {
+    if (subshell.n > maximumShell) continue;
+    const subshellElectrons =
+      occupancies.get(`${subshell.n}.${subshell.l}`) ?? 0;
+    // An empty orbital is the one an electron would be *promoted* into, so the
+    // electron doing the promoting is not also left behind to screen it. This
+    // is what makes hydrogen's 3s and 4f come out as the exact hydrogen
+    // orbitals every textbook draws, rather than as unbound ones: screened by
+    // its own single electron, hydrogen's 3s would see a nuclear charge of zero.
+    const screening = slaterScreening(
+      atomicNumber,
+      subshellElectrons === 0 ? promoted : configuration,
+      subshell,
+    );
+    // Slater's rules can still over-screen a far virtual orbital; a charge at
+    // or below zero has no bound radial function at all.
+    const charge = Math.max(screening.effectiveCharge, MINIMUM_CHARGE);
+    const parameters: HydrogenicParameters = {
+      n: subshell.n,
+      l: subshell.l,
+      charge,
+    };
+    const harmonics = harmonicsOf(subshell.l);
+    const spread = hundDistribution(subshellElectrons, harmonics.length);
+    for (let index = 0; index < harmonics.length; index++) {
+      const harmonic = harmonics[index] as RealHarmonic;
+      orbitals.push({
+        id: orbitalId(subshell.n, subshell.l, harmonic),
+        n: subshell.n,
+        l: subshell.l,
+        harmonic,
+        shell: subshellLabel(subshell),
+        electrons: spread[index] as number,
+        subshellElectrons,
+        effectiveCharge: charge,
+        shielding: screening.shielding,
+        energy: orbitalEnergy(parameters),
+        radialNodes: radialNodeCount(parameters),
+        angularNodes: subshell.l,
+        meanRadius: meanRadius(parameters),
+        isVirtual: subshellElectrons === 0,
+        isValence: subshellElectrons > 0 && subshell.n === valenceShell,
+      });
+    }
+  }
+  return orbitals;
+}
+
+/**
+ * Find one orbital of an element by its id.
+ * @param orbitals - What {@link atomicOrbitalsOf} returned.
+ * @param id - Orbital id, e.g. `2px`.
+ * @returns The orbital, or `null` when the id names none.
+ */
+export function findAtomicOrbital(
+  orbitals: readonly AtomicOrbital[],
+  id: string,
+): AtomicOrbital | null {
+  for (const orbital of orbitals) {
+    if (orbital.id === id) return orbital;
+  }
+  return null;
+}
+
+/**
+ * The hydrogen-like parameters an orbital is drawn from.
+ * @param orbital - The orbital.
+ * @returns Its principal quantum number, ℓ and effective charge.
+ */
+export function hydrogenicParametersOf(
+  orbital: AtomicOrbital,
+): HydrogenicParameters {
+  return { n: orbital.n, l: orbital.l, charge: orbital.effectiveCharge };
+}
+
+/**
+ * The id of one orbital, as it appears in a URL.
+ * @param n - Principal quantum number.
+ * @param l - Angular momentum quantum number.
+ * @param harmonic - Which real harmonic of the subshell.
+ * @returns The id, e.g. `4fxyz`.
+ */
+export function orbitalId(
+  n: number,
+  l: number,
+  harmonic: RealHarmonic,
+): string {
+  return `${n}${subshellLetter(l)}${harmonic.key}`;
+}
+
+/**
+ * The orbital a student should land on when they pick an element: the first
+ * one of the outermost occupied subshell, which is what the element's chemistry
+ * is about.
+ * @param orbitals - What {@link atomicOrbitalsOf} returned.
+ * @returns Its id, or `null` when the list is empty.
+ */
+export function defaultOrbitalId(
+  orbitals: readonly AtomicOrbital[],
+): string | null {
+  let candidate: AtomicOrbital | null = null;
+  for (const orbital of orbitals) {
+    if (orbital.electrons === 0) continue;
+    if (candidate === null) {
+      candidate = orbital;
+    } else if (orbital.n > candidate.n) {
+      candidate = orbital;
+    } else if (orbital.n === candidate.n && orbital.l > candidate.l) {
+      candidate = orbital;
+    }
+  }
+  return (candidate ?? orbitals[0])?.id ?? null;
+}

package/src/orbital/core/constants.ts

@@ -0,0 +1,36 @@
+/**
+ * The two physical constants the orbital maths is written in, and the units
+ * everything else here follows.
+ *
+ * Distances are **ångström** and amplitudes **Å^(-3/2)** throughout, so
+ * `∫|ψ|² dV` over a grid measured in ångström is one and nothing has to be
+ * converted on the way to a renderer. The Bohr radius therefore appears exactly
+ * once, in `hydrogenic.ts`.
+ */
+
+/** The Bohr radius in ångström (CODATA 2018). */
+export const BOHR_IN_ANGSTROM = 0.529_177_210_903;
+
+/** One rydberg in electronvolts (CODATA 2018). */
+export const RYDBERG_ELECTRONVOLTS = 13.605_693_122_994;
+
+/**
+ * Share of an orbital's weight the default isosurface encloses.
+ *
+ * 0.85 is the contour a textbook draws: tight enough that the lobes are
+ * separate shapes, loose enough that the outer one of a 3s is still there.
+ */
+export const ENCLOSED_WEIGHT = 0.85;
+
+/**
+ * A point in space, ångström.
+ *
+ * Declared here rather than taken from a geometry package: three numbers are
+ * not worth a dependency, and this one crosses a worker boundary as a plain
+ * object.
+ */
+export interface Vec3 {
+  x: number;
+  y: number;
+  z: number;
+}

package/src/orbital/core/electronConfiguration.ts

@@ -0,0 +1,242 @@
+/**
+ * Ground-state electron configurations, by the Aufbau principle and the twenty
+ * elements that ignore it.
+ *
+ * Subshells fill in Madelung order — increasing `n + ℓ`, and increasing `n`
+ * within a tie — which is why 4s fills before 3d. That rule gets 98 of the 118
+ * elements right; the rest are measured, not derived, and live in
+ * {@link ELEMENT_ANOMALIES}. Chromium is the canonical one: Aufbau predicts
+ * `[Ar]3d⁴4s²` and the atom is `[Ar]3d⁵4s¹`.
+ *
+ * Configurations are returned sorted by `n` then `ℓ`, the order a textbook
+ * writes them in — `[Ar]3d⁵4s¹`, not `[Ar]4s¹3d⁵`.
+ */
+
+import { subshellLetter } from './realHarmonics.ts';
+
+/** One subshell, e.g. `{ n: 3, l: 2 }` for 3d. */
+export interface Subshell {
+  n: number;
+  /** Angular momentum quantum number: 0 = s, 1 = p, 2 = d, 3 = f. */
+  l: number;
+}
+
+/** A subshell and how many electrons sit in it. */
+export interface SubshellOccupancy extends Subshell {
+  electrons: number;
+}
+
+/** No known element occupies a shell above n = 7. */
+const MAXIMUM_PRINCIPAL_NUMBER = 7;
+
+/** Protons in the heaviest element that has been made. */
+export const HIGHEST_ATOMIC_NUMBER = 118;
+
+/** The atomic numbers of the noble gases, which a configuration abbreviates on. */
+export const NOBLE_GASES: readonly number[] = [2, 10, 18, 36, 54, 86, 118];
+
+/**
+ * Reject an atomic number outside the periodic table.
+ * @param atomicNumber - Proton count to check.
+ * @throws {Error} When it is not an integer between 1 and 118.
+ */
+export function assertAtomicNumber(atomicNumber: number): void {
+  if (
+    !Number.isInteger(atomicNumber) ||
+    atomicNumber < 1 ||
+    atomicNumber > HIGHEST_ATOMIC_NUMBER
+  ) {
+    throw new RangeError(`no element with atomic number ${atomicNumber}`);
+  }
+}
+
+/**
+ * Subshells in the order they fill, `s` to `f` and up to n = 7 — everything the
+ * 118 known elements use, plus the empty subshells a light atom's virtual
+ * orbitals come from.
+ */
+export const MADELUNG_ORDER: Subshell[] = buildMadelungOrder();
+
+/**
+ * How many electrons a subshell holds: `2(2ℓ + 1)`.
+ * @param l - Angular momentum quantum number.
+ * @returns The capacity, `2(2ℓ + 1)`.
+ */
+export function subshellCapacity(l: number): number {
+  return 2 * (2 * l + 1);
+}
+
+/**
+ * The measured ground states that Madelung order gets wrong, as the occupancy
+ * beyond the preceding noble gas.
+ *
+ * Half-filled and filled d shells are unusually stable, which is the story for
+ * Cr, Cu, Mo, Ag, Au and Gd; the early actinides are relativistic and 6d/5f sit
+ * almost on top of each other. Configurations past lawrencium are calculated
+ * rather than observed, so nothing beyond Z = 103 is listed here.
+ */
+export const ELEMENT_ANOMALIES: Record<number, SubshellOccupancy[]> = {
+  24: [o(3, 2, 5), o(4, 0, 1)],
+  29: [o(3, 2, 10), o(4, 0, 1)],
+  41: [o(4, 2, 4), o(5, 0, 1)],
+  42: [o(4, 2, 5), o(5, 0, 1)],
+  44: [o(4, 2, 7), o(5, 0, 1)],
+  45: [o(4, 2, 8), o(5, 0, 1)],
+  46: [o(4, 2, 10)],
+  47: [o(4, 2, 10), o(5, 0, 1)],
+  57: [o(5, 2, 1), o(6, 0, 2)],
+  58: [o(4, 3, 1), o(5, 2, 1), o(6, 0, 2)],
+  64: [o(4, 3, 7), o(5, 2, 1), o(6, 0, 2)],
+  78: [o(4, 3, 14), o(5, 2, 9), o(6, 0, 1)],
+  79: [o(4, 3, 14), o(5, 2, 10), o(6, 0, 1)],
+  89: [o(6, 2, 1), o(7, 0, 2)],
+  90: [o(6, 2, 2), o(7, 0, 2)],
+  91: [o(5, 3, 2), o(6, 2, 1), o(7, 0, 2)],
+  92: [o(5, 3, 3), o(6, 2, 1), o(7, 0, 2)],
+  93: [o(5, 3, 4), o(6, 2, 1), o(7, 0, 2)],
+  96: [o(5, 3, 7), o(6, 2, 1), o(7, 0, 2)],
+  103: [o(5, 3, 14), o(7, 0, 2), o(7, 1, 1)],
+};
+
+/**
+ * The ground-state configuration of a neutral atom.
+ * @param atomicNumber - Proton count, 1 to 118.
+ * @returns Its occupied subshells, sorted by `n` then `ℓ`.
+ * @throws {Error} When the atomic number is outside the table.
+ */
+export function configurationOf(atomicNumber: number): SubshellOccupancy[] {
+  assertAtomicNumber(atomicNumber);
+  const anomaly = ELEMENT_ANOMALIES[atomicNumber];
+  if (anomaly === undefined) return sortByShell(aufbauFill(atomicNumber));
+  const core = coreAtomicNumber(atomicNumber);
+  return sortByShell([
+    ...aufbauFill(core),
+    ...anomaly.map((entry) => ({ ...entry })),
+  ]);
+}
+
+/**
+ * Whether an element's ground state departs from Madelung order.
+ * @param atomicNumber - Proton count.
+ * @returns True for the twenty listed in {@link ELEMENT_ANOMALIES}.
+ */
+export function isAnomalous(atomicNumber: number): boolean {
+  return atomicNumber in ELEMENT_ANOMALIES;
+}
+
+/**
+ * What Madelung order alone predicts, so the UI can show the two side by side.
+ * @param atomicNumber - Proton count, 1 to 118.
+ * @returns The predicted occupied subshells, sorted by `n` then `ℓ`.
+ */
+export function aufbauConfigurationOf(
+  atomicNumber: number,
+): SubshellOccupancy[] {
+  return sortByShell(aufbauFill(atomicNumber));
+}
+
+/**
+ * The noble gas a configuration is abbreviated against.
+ * @param atomicNumber - Proton count.
+ * @returns The largest noble gas strictly below it, or 0 for hydrogen and
+ * helium, which are written out in full.
+ */
+export function coreAtomicNumber(atomicNumber: number): number {
+  let core = 0;
+  for (const noble of NOBLE_GASES) {
+    if (noble >= atomicNumber) break;
+    core = noble;
+  }
+  return core;
+}
+
+/**
+ * Write a configuration the way a textbook does.
+ * @param occupancies - Subshells to write, in the order they should appear.
+ * @returns A string such as `1s² 2s² 2p⁶`.
+ */
+export function formatConfiguration(
+  occupancies: readonly SubshellOccupancy[],
+): string {
+  const parts: string[] = [];
+  for (const occupancy of occupancies) parts.push(formatOccupancy(occupancy));
+  return parts.join(' ');
+}
+
+/**
+ * Write one subshell, e.g. `3d⁵`.
+ * @param occupancy - The subshell and its electron count.
+ * @returns The label with a superscript electron count.
+ */
+export function formatOccupancy(occupancy: SubshellOccupancy): string {
+  return `${subshellLabel(occupancy)}${superscript(occupancy.electrons)}`;
+}
+
+/**
+ * Write one subshell without its electron count, e.g. `3d`.
+ * @param subshell - The subshell.
+ * @returns The principal quantum number followed by the subshell letter.
+ */
+export function subshellLabel(subshell: Subshell): string {
+  return `${subshell.n}${subshellLetter(subshell.l)}`;
+}
+
+/**
+ * Render a number in unicode superscript digits.
+ * @param value - A non-negative integer.
+ * @returns The digits as superscripts, e.g. `14` becomes `¹⁴`.
+ */
+export function superscript(value: number): string {
+  let text = '';
+  for (const digit of String(value)) {
+    text += SUPERSCRIPT_DIGITS[Number(digit)] ?? digit;
+  }
+  return text;
+}
+
+const SUPERSCRIPT_DIGITS = ['⁰', '¹', '²', '³', '⁴', '⁵', '⁶', '⁷', '⁸', '⁹'];
+
+function o(n: number, l: number, electrons: number): SubshellOccupancy {
+  return { n, l, electrons };
+}
+
+/**
+ * Fill `count` electrons into {@link MADELUNG_ORDER}, lowest subshell first.
+ * @param count - Electrons to place.
+ * @returns The filled subshells, in Madelung order.
+ */
+function aufbauFill(count: number): SubshellOccupancy[] {
+  const filled: SubshellOccupancy[] = [];
+  let left = count;
+  for (const subshell of MADELUNG_ORDER) {
+    if (left <= 0) break;
+    const electrons = Math.min(left, subshellCapacity(subshell.l));
+    filled.push({ n: subshell.n, l: subshell.l, electrons });
+    left -= electrons;
+  }
+  return filled;
+}
+
+function sortByShell(occupancies: SubshellOccupancy[]): SubshellOccupancy[] {
+  return occupancies.toSorted((first, second) =>
+    first.n === second.n ? first.l - second.l : first.n - second.n,
+  );
+}
+
+/**
+ * Madelung order: ascending `n + ℓ`, then ascending `n`. Capped at ℓ = 3 — the
+ * g subshells a Madelung diagram shows after 8s are unoccupied in every known
+ * element, and this site has no g harmonics to draw them with.
+ * @returns The subshells, in filling order.
+ */
+function buildMadelungOrder(): Subshell[] {
+  const order: Subshell[] = [];
+  for (let sum = 1; sum <= 10; sum++) {
+    for (let l = Math.min(3, Math.ceil(sum / 2) - 1); l >= 0; l--) {
+      const n = sum - l;
+      if (n > MAXIMUM_PRINCIPAL_NUMBER || n <= l) continue;
+      order.push({ n, l });
+    }
+  }
+  return order;
+}

package/src/orbital/core/grid.ts

@@ -0,0 +1,126 @@
+/**
+ * Sampling a wavefunction onto a dense scalar field for the isosurface renderer.
+ *
+ * The memory order is a hard contract with molstar: `Tensor.Space([nx, ny, nz],
+ * [0, 1, 2])` reads `dataOffset = x·ny·nz + y·nz + z`, so **z varies fastest**.
+ * The loops below are written in exactly that order and
+ * {@link gridIndex} is the single place the arithmetic is spelled out.
+ */
+
+import type { Vec3 } from './constants.ts';
+
+/** An axis-aligned sampling box, ångström. */
+export interface GridBox {
+  /** Lowest corner. */
+  origin: Vec3;
+  /** Edge lengths along x, y and z. */
+  size: Vec3;
+}
+
+/**
+ * A wavefunction, sampled at one point.
+ * @param x - Offset from the origin along x, ångström.
+ * @param y - Offset along y.
+ * @param z - Offset along z.
+ * @returns The amplitude, Å^(-3/2).
+ */
+export type OrbitalEvaluator = (x: number, y: number, z: number) => number;
+
+/** A sampled scalar field plus the statistics an isovalue is chosen from. */
+export interface OrbitalGrid {
+  /** `nx·ny·nz` samples, z varying fastest. */
+  data: Float32Array;
+  /** `[nx, ny, nz]`. */
+  dimensions: [number, number, number];
+  /** Position of sample `(0, 0, 0)`, ångström. */
+  origin: Vec3;
+  /** Distance between neighbouring samples on every axis, ångström. */
+  spacing: number;
+  min: number;
+  max: number;
+  mean: number;
+  /** Population standard deviation of the samples. */
+  sigma: number;
+}
+
+/**
+ * Sample a wavefunction over a box.
+ * @param evaluate - the wavefunction, cartesian ångström in, amplitude out.
+ * @param box - the region to cover.
+ * @param resolution - samples along the longest edge; the spacing it implies is
+ * used on all three axes, so the voxels stay cubic.
+ * @returns the field, its layout and its single-pass statistics.
+ * @throws {Error} when `resolution` is below 2 or the box has no volume.
+ */
+export function evaluateGrid(
+  evaluate: OrbitalEvaluator,
+  box: GridBox,
+  resolution: number,
+): OrbitalGrid {
+  if (resolution < 2) {
+    throw new Error('a grid needs at least 2 samples per axis');
+  }
+  const { origin, size } = box;
+  const longestEdge = Math.max(size.x, size.y, size.z);
+  if (!(longestEdge > 0)) {
+    throw new Error('the sampling box must have a non-zero edge');
+  }
+  const spacing = longestEdge / (resolution - 1);
+  const countX = axisCount(size.x, spacing);
+  const countY = axisCount(size.y, spacing);
+  const countZ = axisCount(size.z, spacing);
+  const data = new Float32Array(countX * countY * countZ);
+  let min = Infinity;
+  let max = -Infinity;
+  let sum = 0;
+  let sumSquares = 0;
+  let index = 0;
+  for (let indexX = 0; indexX < countX; indexX++) {
+    const x = origin.x + indexX * spacing;
+    for (let indexY = 0; indexY < countY; indexY++) {
+      const y = origin.y + indexY * spacing;
+      for (let indexZ = 0; indexZ < countZ; indexZ++) {
+        const value = Math.fround(evaluate(x, y, origin.z + indexZ * spacing));
+        data[index++] = value;
+        if (value < min) min = value;
+        if (value > max) max = value;
+        sum += value;
+        sumSquares += value * value;
+      }
+    }
+  }
+  const count = data.length;
+  const mean = sum / count;
+  const variance = sumSquares / count - mean * mean;
+  return {
+    data,
+    dimensions: [countX, countY, countZ],
+    origin: { x: origin.x, y: origin.y, z: origin.z },
+    spacing,
+    min,
+    max,
+    mean,
+    sigma: Math.sqrt(Math.max(variance, 0)),
+  };
+}
+
+/**
+ * Flat offset of a sample, the layout molstar expects.
+ * @param dimensions - `[nx, ny, nz]` of the grid.
+ * @param indexX - sample index along x.
+ * @param indexY - sample index along y.
+ * @param indexZ - sample index along z, the fastest-varying axis.
+ * @returns the index into {@link OrbitalGrid.data}.
+ */
+export function gridIndex(
+  dimensions: [number, number, number],
+  indexX: number,
+  indexY: number,
+  indexZ: number,
+): number {
+  return (indexX * dimensions[1] + indexY) * dimensions[2] + indexZ;
+}
+
+function axisCount(edge: number, spacing: number): number {
+  return Math.max(2, Math.round(edge / spacing) + 1);
+}