react-cheminfo 0.2.0 → 0.3.0

package/src/orbital/core/hydrogenic.ts

@@ -0,0 +1,222 @@
+/**
+ * Hydrogen-like atomic orbitals: the exact one-electron solutions, scaled to an
+ * element by an effective nuclear charge.
+ *
+ * `R(r) = N (2Zr/na₀)^ℓ e^(−Zr/na₀) L^(2ℓ+1)_(n−ℓ−1)(2Zr/na₀)`
+ *
+ * The associated Laguerre polynomial is the whole point. The Slater orbital a
+ * hybridisation model uses is `r^(n−1) e^(−ζr)`, which is **nodeless**: it draws
+ * a 2s exactly like a 1s, only fatter. That is fine for a hybrid lobe, where
+ * only the outer contour is ever seen, and wrong for a picture whose subject is
+ * what an orbital looks like — `n − ℓ − 1` radial nodes and ℓ angular ones is
+ * the first thing a student is asked to count.
+ *
+ * Amplitudes are in Å^(-3/2) and distances in ångström, like everything else
+ * here, so `∫|ψ|² dV` over a grid measured in ångström is 1.
+ */
+
+import { BOHR_IN_ANGSTROM, RYDBERG_ELECTRONVOLTS } from './constants.ts';
+import {
+  assertQuantumNumbers,
+  bisectRoot,
+  factorial,
+  laguerre,
+} from './numerics.ts';
+
+/** Which hydrogen-like orbital, and how strongly it is bound. */
+export interface HydrogenicParameters {
+  /** Principal quantum number, 1 and up. */
+  n: number;
+  /** Angular momentum quantum number, 0 to n − 1. */
+  l: number;
+  /** Effective nuclear charge, in units of the elementary charge. */
+  charge: number;
+}
+
+/**
+ * Radial nodes: spheres on which the wavefunction vanishes and changes sign.
+ * @param parameters - Which orbital.
+ * @returns `n − ℓ − 1`.
+ */
+export function radialNodeCount(parameters: HydrogenicParameters): number {
+  return parameters.n - parameters.l - 1;
+}
+
+/**
+ * Mean distance of the electron from the nucleus,
+ * `⟨r⟩ = a₀(3n² − ℓ(ℓ+1)) / 2Z`.
+ * @param parameters - Which orbital.
+ * @returns The expectation value in ångström.
+ */
+export function meanRadius(parameters: HydrogenicParameters): number {
+  const { n, l, charge } = parameters;
+  return (
+    (BOHR_IN_ANGSTROM * (3 * n * n - l * (l + 1))) /
+    (2 * Math.max(charge, 1e-6))
+  );
+}
+
+/**
+ * Orbital energy in the hydrogen-like model, `E = −13.6 Z²/n²` eV.
+ * @param parameters - Which orbital.
+ * @returns The energy in electronvolts, always negative.
+ */
+export function orbitalEnergy(parameters: HydrogenicParameters): number {
+  const { n, charge } = parameters;
+  return (-RYDBERG_ELECTRONVOLTS * charge * charge) / (n * n);
+}
+
+/**
+ * Build the radial function `R(r)`, with every constant hoisted out so a grid
+ * sweep pays for the exponential and the polynomial only.
+ * @param parameters - Which orbital.
+ * @returns A function taking a distance in ångström and returning Å^(-3/2).
+ * @throws {Error} When the quantum numbers are not a real orbital, i.e. `n < 1` or
+ * `ℓ` outside `0 … n − 1`, or when the charge is not positive.
+ */
+export function createRadialFunction(
+  parameters: HydrogenicParameters,
+): (distance: number) => number {
+  const { n, l, charge } = parameters;
+  assertQuantumNumbers(n, l);
+  if (!(charge > 0)) {
+    throw new RangeError(
+      `the effective charge must be positive, got ${charge}`,
+    );
+  }
+  const degree = n - l - 1;
+  const alpha = 2 * l + 1;
+  // ρ = 2Zr/(n a₀), with r in ångström, so a₀ appears once here and never again.
+  const rho = (2 * charge) / (n * BOHR_IN_ANGSTROM);
+  const normalisation = Math.sqrt(
+    rho * rho * rho * (factorial(degree) / (2 * n * factorial(n + l))),
+  );
+  return (distance) => {
+    const scaled = rho * distance;
+    return (
+      normalisation *
+      scaled ** l *
+      Math.exp(-scaled / 2) *
+      laguerre(degree, alpha, scaled)
+    );
+  };
+}
+
+/**
+ * Evaluate the radial function once.
+ * @param parameters - Which orbital.
+ * @param distance - Distance from the nucleus, ångström.
+ * @returns The radial amplitude, Å^(-3/2).
+ */
+export function radialAmplitude(
+  parameters: HydrogenicParameters,
+  distance: number,
+): number {
+  return createRadialFunction(parameters)(distance);
+}
+
+/**
+ * Where the radial nodes actually are.
+ *
+ * The `n − ℓ − 1` roots are bracketed by scanning outwards and then bisected,
+ * rather than solved for, because the Laguerre roots have no closed form past
+ * the quadratic and a bisection on a function we already evaluate cannot drift
+ * out of step with what is drawn.
+ * @param parameters - Which orbital.
+ * @param limit - Distance to search out to, ångström. Defaults to a box that
+ * comfortably holds the outermost node.
+ * @returns The node radii in ångström, ascending; empty for a nodeless orbital.
+ */
+export function radialNodeRadii(
+  parameters: HydrogenicParameters,
+  limit = meanRadius(parameters) * 3,
+): number[] {
+  const expected = radialNodeCount(parameters);
+  if (expected === 0) return [];
+  const radial = createRadialFunction(parameters);
+  const radii: number[] = [];
+  const steps = 4000;
+  let previousDistance = 1e-6;
+  let previous = radial(previousDistance);
+  for (let step = 1; step <= steps; step++) {
+    const distance = (limit * step) / steps;
+    const value = radial(distance);
+    if (previous === 0 || previous < 0 !== value < 0) {
+      radii.push(bisectRoot(radial, previousDistance, distance));
+      if (radii.length === expected) break;
+    }
+    previousDistance = distance;
+    previous = value;
+  }
+  return radii;
+}
+
+/**
+ * Smallest sphere holding a given share of the electron.
+ *
+ * Used to size the sampling box: too small clips the orbital at a face, too
+ * large wastes the grid on empty space, and both are visible on screen.
+ * @param parameters - Which orbital.
+ * @param fraction - Share of `∫ r²R² dr` to enclose, between 0 and 1.
+ * @returns The radius in ångström.
+ * @throws {Error} When `fraction` is outside `(0, 1)`.
+ */
+export function enclosingRadius(
+  parameters: HydrogenicParameters,
+  fraction: number,
+): number {
+  if (!(fraction > 0) || fraction >= 1) {
+    throw new RangeError(`the enclosed fraction must be in (0, 1)`);
+  }
+  const radial = createRadialFunction(parameters);
+  // The tail decays as e^(−2Zr/n a₀); ten mean radii is far past every node.
+  const limit = meanRadius(parameters) * 10;
+  const steps = 4000;
+  const step = limit / steps;
+  const weights = new Float64Array(steps + 1);
+  let total = 0;
+  for (let index = 0; index <= steps; index++) {
+    const distance = index * step;
+    const value = radial(distance);
+    const weight = value * value * distance * distance;
+    weights[index] = weight;
+    total += weight;
+  }
+  if (total === 0) return limit;
+  let running = 0;
+  const target = total * fraction;
+  for (let index = 0; index <= steps; index++) {
+    running += weights[index] as number;
+    if (running >= target) return index * step;
+  }
+  return limit;
+}
+
+/**
+ * Sample the radial distribution `P(r) = r²R(r)²` — the curve whose zeroes are
+ * the radial nodes and whose area is the electron.
+ * @param parameters - Which orbital.
+ * @param limit - Distance to sample out to, ångström.
+ * @param count - Number of samples, at least 2.
+ * @returns Distances and the amplitude `R`, plus `P`, at each of them.
+ * @throws {Error} When `count` is below 2.
+ */
+export function radialProfile(
+  parameters: HydrogenicParameters,
+  limit: number,
+  count: number,
+): { distances: Float64Array; amplitude: Float64Array; density: Float64Array } {
+  if (count < 2) throw new RangeError('a radial profile needs 2 samples');
+  const radial = createRadialFunction(parameters);
+  const distances = new Float64Array(count);
+  const amplitude = new Float64Array(count);
+  const density = new Float64Array(count);
+  for (let index = 0; index < count; index++) {
+    const distance = (limit * index) / (count - 1);
+    const value = radial(distance);
+    distances[index] = distance;
+    amplitude[index] = value;
+    density[index] = value * value * distance * distance;
+  }
+  return { distances, amplitude, density };
+}

package/src/orbital/core/index.ts

@@ -0,0 +1,72 @@
+export type { AtomicGridOptions } from './atomicGrid.ts';
+export {
+  atomicGridBox,
+  createAtomicOrbitalEvaluator,
+  sampleAtomicOrbital,
+} from './atomicGrid.ts';
+export type { AtomicOrbital, AtomicOrbitalOptions } from './atomicOrbitals.ts';
+export {
+  atomicOrbitalsOf,
+  defaultOrbitalId,
+  findAtomicOrbital,
+  hydrogenicParametersOf,
+  orbitalId,
+} from './atomicOrbitals.ts';
+export type { Vec3 } from './constants.ts';
+export {
+  BOHR_IN_ANGSTROM,
+  ENCLOSED_WEIGHT,
+  RYDBERG_ELECTRONVOLTS,
+} from './constants.ts';
+export type { Subshell, SubshellOccupancy } from './electronConfiguration.ts';
+export {
+  ELEMENT_ANOMALIES,
+  HIGHEST_ATOMIC_NUMBER,
+  MADELUNG_ORDER,
+  NOBLE_GASES,
+  assertAtomicNumber,
+  aufbauConfigurationOf,
+  configurationOf,
+  coreAtomicNumber,
+  formatConfiguration,
+  formatOccupancy,
+  isAnomalous,
+  subshellCapacity,
+  subshellLabel,
+  superscript,
+} from './electronConfiguration.ts';
+export type { GridBox, OrbitalEvaluator, OrbitalGrid } from './grid.ts';
+export { evaluateGrid, gridIndex } from './grid.ts';
+export type { HydrogenicParameters } from './hydrogenic.ts';
+export {
+  createRadialFunction,
+  enclosingRadius,
+  meanRadius,
+  orbitalEnergy,
+  radialAmplitude,
+  radialNodeCount,
+  radialNodeRadii,
+  radialProfile,
+} from './hydrogenic.ts';
+export {
+  hundDistribution,
+  outermostShell,
+  withoutOutermostElectron,
+} from './occupancy.ts';
+export type { PhasePalette, PhasePaletteId } from './palette.ts';
+export { DEFAULT_PHASE_PALETTE_ID, PHASE_PALETTES } from './palette.ts';
+export type { RealHarmonic } from './realHarmonics.ts';
+export {
+  REAL_HARMONICS,
+  SUBSHELL_LETTERS,
+  harmonicsOf,
+  subshellLetter,
+} from './realHarmonics.ts';
+export type {
+  AtomicSampleRequest,
+  AtomicSampleResult,
+  AtomicSampler,
+} from './sample.ts';
+export { runAtomicSample, sampleInProcess } from './sample.ts';
+export type { Screening } from './screening.ts';
+export { groupRank, slaterScreening } from './screening.ts';

package/src/orbital/core/numerics.ts

@@ -0,0 +1,79 @@
+/**
+ * The numerical machinery the radial functions are built on.
+ *
+ * Kept apart from `hydrogenic.ts` so that file reads as the physics it is —
+ * `R(r)`, `⟨r⟩`, the nodes, the enclosing sphere — with none of it buried under
+ * a polynomial recurrence and a bisection.
+ */
+
+/**
+ * The generalised Laguerre polynomial `L^α_k(x)`, by its three-term recurrence.
+ *
+ * The closed form overflows well before `n = 7`; `k` is at most 6 here.
+ * @param degree - Degree `k` of the polynomial.
+ * @param alpha - Order `α` of the polynomial.
+ * @param x - Where to evaluate it.
+ * @returns The value of the polynomial.
+ */
+export function laguerre(degree: number, alpha: number, x: number): number {
+  if (degree === 0) return 1;
+  let previous = 1;
+  let current = 1 + alpha - x;
+  for (let index = 1; index < degree; index++) {
+    const next =
+      ((2 * index + 1 + alpha - x) * current - (index + alpha) * previous) /
+      (index + 1);
+    previous = current;
+    current = next;
+  }
+  return current;
+}
+
+/**
+ * The root of a function inside a bracket it already changes sign over.
+ * @param radial - The function to find a zero of.
+ * @param low - Lower end of the bracket.
+ * @param high - Upper end.
+ * @returns The root, to about a picometre.
+ */
+export function bisectRoot(
+  radial: (distance: number) => number,
+  low: number,
+  high: number,
+): number {
+  let left = low;
+  let right = high;
+  const leftSign = radial(left) < 0;
+  for (let step = 0; step < 60 && right - left > 1e-9; step++) {
+    const middle = (left + right) / 2;
+    if (radial(middle) < 0 === leftSign) left = middle;
+    else right = middle;
+  }
+  return (left + right) / 2;
+}
+
+/**
+ * Reject quantum numbers that are not a real orbital.
+ * @param n - Principal quantum number.
+ * @param l - Angular momentum quantum number.
+ * @throws {RangeError} When `n < 1`, or ℓ is outside `0 … n − 1`.
+ */
+export function assertQuantumNumbers(n: number, l: number): void {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new RangeError(`the principal quantum number must be 1 or more`);
+  }
+  if (!Number.isInteger(l) || l < 0 || l >= n) {
+    throw new RangeError(`ℓ must be between 0 and ${n - 1} for n = ${n}`);
+  }
+}
+
+/**
+ * The factorial of a small non-negative integer.
+ * @param value - The integer.
+ * @returns Its factorial.
+ */
+export function factorial(value: number): number {
+  let result = 1;
+  for (let index = 2; index <= value; index++) result *= index;
+  return result;
+}

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