react-cheminfo 0.2.0 → 0.4.0

package/src/orbital/core/atomicGrid.ts

@@ -0,0 +1,167 @@
+/**
+ * Sampling one atomic orbital onto the scalar field the isosurface renderer
+ * consumes.
+ *
+ * The box is sized from the orbital itself rather than fixed: a 1s on fluorine
+ * and a 4f on caesium differ by more than an order of magnitude in extent, and a
+ * box that suits one either buries the other in empty space or slices its lobes
+ * off at a face. {@link enclosingRadius} gives the sphere holding almost all of
+ * the electron, and the cube is drawn around that.
+ *
+ * Pure: no React, no molstar. `src/viewer` turns the returned field into a
+ * surface, and the worker calls this off the main thread.
+ */
+
+import type { AtomicOrbital } from './atomicOrbitals.ts';
+import { hydrogenicParametersOf } from './atomicOrbitals.ts';
+import type { GridBox, OrbitalEvaluator, OrbitalGrid } from './grid.ts';
+import { evaluateGrid } from './grid.ts';
+import {
+  createRadialFunction,
+  enclosingRadius,
+  radialNodeRadii,
+} from './hydrogenic.ts';
+
+/** How finely, and how far out, an orbital is sampled. */
+export interface AtomicGridOptions {
+  /**
+   * Samples along each edge of the cube. The cost is the cube of this, and 56
+   * resolves the radial node of a 3s while staying near 30 ms.
+   * @default 56
+   */
+  resolution?: number;
+  /**
+   * Share of `∫ r²R² dr` the box must contain before padding.
+   * @default 0.985
+   */
+  enclosedFraction?: number;
+  /**
+   * Multiplier applied to the enclosing radius, so the surface closes inside
+   * the box instead of touching a face.
+   * @default 1.15
+   */
+  padding?: number;
+}
+
+/**
+ * Sample an atomic orbital onto a cubic grid centred on its nucleus.
+ * @param orbital - The orbital to draw.
+ * @param options - See {@link AtomicGridOptions}.
+ * @returns The signed field, its layout and its statistics.
+ * @throws {Error} When the resolution is below 2.
+ */
+export function sampleAtomicOrbital(
+  orbital: AtomicOrbital,
+  options: AtomicGridOptions = {},
+): OrbitalGrid {
+  const {
+    resolution = DEFAULT_RESOLUTION,
+    enclosedFraction = DEFAULT_ENCLOSED_FRACTION,
+    padding = DEFAULT_PADDING,
+  } = options;
+  return evaluateGrid(
+    createAtomicOrbitalEvaluator(orbital),
+    atomicGridBox(orbital, enclosedFraction, padding),
+    resolution,
+  );
+}
+
+/**
+ * Build `ψ(x, y, z) = R(r) Y(x, y, z)` for one orbital, centred on the origin.
+ * @param orbital - The orbital to evaluate.
+ * @returns An allocation-free evaluator in ångström, returning Å^(-3/2).
+ */
+export function createAtomicOrbitalEvaluator(
+  orbital: AtomicOrbital,
+): OrbitalEvaluator {
+  const radial = createRadialFunction(hydrogenicParametersOf(orbital));
+  const angular = orbital.harmonic.evaluate;
+  // Every ℓ > 0 harmonic divides by the radius, and the nucleus is a grid point
+  // whenever the resolution is odd, so the singularity is real and is answered
+  // here: only an s orbital has amplitude at r = 0.
+  const atNucleus = orbital.l === 0 ? radial(0) * angular(0, 0, 0, 1) : 0;
+  return (x, y, z) => {
+    const squared = x * x + y * y + z * z;
+    if (squared === 0) return atNucleus;
+    const radius = Math.sqrt(squared);
+    return radial(radius) * angular(x, y, z, radius);
+  };
+}
+
+/**
+ * The cube one orbital is sampled over.
+ * @param orbital - The orbital to fit.
+ * @param enclosedFraction - Share of the electron to contain.
+ * @param padding - Multiplier applied to the enclosing radius.
+ * @returns A cube centred on the nucleus.
+ */
+export function atomicGridBox(
+  orbital: AtomicOrbital,
+  enclosedFraction = DEFAULT_ENCLOSED_FRACTION,
+  padding = DEFAULT_PADDING,
+): GridBox {
+  const half =
+    enclosingRadius(hydrogenicParametersOf(orbital), enclosedFraction) *
+    padding;
+  return {
+    origin: { x: -half, y: -half, z: -half },
+    size: { x: 2 * half, y: 2 * half, z: 2 * half },
+  };
+}
+
+/** How finely one orbital may be sampled, whatever its shape asks for. */
+export interface ResolutionLimits {
+  /** Samples per edge no orbital drops below. */
+  floor: number;
+  /** Samples per edge no orbital exceeds. */
+  cap: number;
+}
+
+/**
+ * How finely this particular orbital has to be sampled.
+ *
+ * One resolution for a whole periodic table draws the nested orbitals badly.
+ * The box is sized by the outermost lobe, but a `4p` also has to separate two
+ * inner shells packed against the nucleus, and at 56 samples per edge xenon's
+ * innermost 4p lobe spans **6.6 voxels** while the outer one spans 41 — the
+ * inner shells come out as lumps and the outer surface visibly faceted. What
+ * sets the requirement is therefore the ratio between the box and the smallest
+ * feature in it, not the orbital's size, which is why a nodeless orbital
+ * (every `1s`, `2p`, `3d`, `4f`) stays on the floor and costs nothing extra.
+ *
+ * The cap is not a budget cheat: the innermost lobe of caesium's `7s` would
+ * need 858 samples per edge, and no uniform grid the browser can afford
+ * resolves it. Those orbitals are drawn as well as the cap allows.
+ * @param orbital - The orbital to draw.
+ * @param limits - See {@link ResolutionLimits}.
+ * @returns Samples along each edge of the cube.
+ */
+export function atomicGridResolution(
+  orbital: AtomicOrbital,
+  limits: ResolutionLimits,
+): number {
+  const { floor, cap } = limits;
+  const parameters = hydrogenicParametersOf(orbital);
+  const innermost = radialNodeRadii(parameters)[0];
+  if (innermost === undefined || !(innermost > 0)) return Math.min(floor, cap);
+  const half = atomicGridBox(orbital).size.x / 2;
+  // The samples span the box edge to edge, so `resolution - 1` of them cover
+  // it: a lobe of radius r gets `r (resolution - 1) / half` across its diameter.
+  const needed = Math.ceil((INNER_LOBE_SAMPLES * half) / innermost) + 1;
+  return Math.min(cap, Math.max(floor, needed));
+}
+
+/** Samples per edge; the cost is the cube of it. */
+const DEFAULT_RESOLUTION = 56;
+
+/**
+ * Samples the innermost radial lobe is asked to span, edge to edge. Below
+ * about eight, marching cubes turns a sphere into a faceted blob.
+ */
+const INNER_LOBE_SAMPLES = 12;
+
+/** A tail past this holds too little density to change the surface. */
+const DEFAULT_ENCLOSED_FRACTION = 0.985;
+
+/** Room for the surface to close before the box ends. */
+const DEFAULT_PADDING = 1.15;

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