@classytic/stage 0.3.0 → 0.4.0

package/dist/_virtual/_rolldown/runtime.mjs

@@ -0,0 +1,18 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (!no_symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll };

package/dist/atomic/aufbau.d.mts

@@ -0,0 +1,144 @@
+//#region src/atomic/aufbau.d.ts
+/**
+ * Electron configuration, built by the rules rather than looked up.
+ *
+ * ## The filling order is generated, not memorised
+ *
+ * Textbooks print the sequence 1s 2s 2p 3s 3p 4s 3d 4p 5s 4d 5p 6s 4f … and expect it to be learnt,
+ * usually with a diagonal-arrow diagram. It is not a sequence to learn. It is one rule:
+ *
+ *     lower (n + l) fills first; where two subshells tie, the lower n fills first
+ *
+ * That is the Madelung rule, and {@link fillingOrder} generates the sequence from it. So 4s fills
+ * before 3d because 4 + 0 = 4 beats 3 + 2 = 5, which is the explanation, and the arrow diagram is
+ * only a way of reading the same rule off a grid. Ask for more shells than any book prints and the
+ * order keeps going, correctly.
+ *
+ * ## Hund's rule is about orbitals, not subshells
+ *
+ * Electrons occupy the orbitals of a subshell singly, with parallel spins, before any orbital takes
+ * a second. {@link orbitalDiagram} places them that way, which is what makes the boxes-and-arrows
+ * diagram derivable instead of drawn by hand, and it is why nitrogen has three unpaired electrons.
+ *
+ * ## The exceptions are real physics, and they are listed rather than derived
+ *
+ * Chromium is [Ar]3d⁵4s¹, not 3d⁴4s². A filled or half-filled d subshell is lower in energy than
+ * the plain filling order predicts, by enough to move one electron. That effect is not something
+ * the Madelung rule contains, so pretending to derive it would be a lie: {@link ANOMALIES} states
+ * each one with its reason, and {@link configurationOf} applies them.
+ *
+ * ## Ions lose their outermost electrons, not the last one added
+ *
+ * The single most-missed point in this topic. Iron fills 4s before 3d, so it is tempting to empty
+ * 3d first on the way back out. It does not: once 3d is occupied it drops below 4s, so Fe²⁺ is
+ * [Ar]3d⁶ with 4s empty, not [Ar]3d⁴4s². {@link ionConfigurationOf} removes from the highest n
+ * first, and the doc on it says so, because a learner who gets this wrong gets every transition
+ * metal wrong.
+ *
+ * Pure: no React, no pixels.
+ */
+/** One occupied subshell. */
+interface Occupancy {
+  readonly n: number;
+  readonly l: number;
+  /** How many electrons are in it. */
+  readonly electrons: number;
+}
+/**
+ * A full electron configuration, in SHELL order.
+ *
+ * Subshells fill in one order and are written in another, and conflating the two is a real source
+ * of confusion. Iron fills 4s before 3d, but it is written 3d⁶ 4s², grouped by shell, because that
+ * is how the data booklet prints it and because grouping by shell is what makes the outer shell
+ * visible at the end of the line. {@link fillingOrder} is the other order, kept separate.
+ */
+type Configuration = readonly Occupancy[];
+/**
+ * Subshells in the order they fill, by the Madelung (n+l) rule.
+ *
+ * Generated, so it does not stop where a printed table stops.
+ */
+declare function fillingOrder(maxN?: number): {
+  n: number;
+  l: number;
+}[];
+/** How a subshell is written: 3d. */
+declare const occupancyLabel: (o: {
+  n: number;
+  l: number;
+}) => string;
+/**
+ * A configuration as it is written: 1s² 2s² 2p⁶.
+ *
+ * The electron count is SUPERSCRIPTED, because "1s2 2s2 2p6" reads as a string of digits and the
+ * whole notation depends on the counts being visibly above the line.
+ */
+declare const formatConfiguration: (configuration: Configuration) => string;
+/**
+ * The plain filling order applied to Z electrons, with no anomalies.
+ *
+ * Exported because "what the rule predicts" is half of what makes chromium interesting: the other
+ * half is {@link configurationOf}, and a learner needs to see both to see that they differ.
+ */
+declare function aufbauConfiguration(electrons: number): Configuration;
+interface Anomaly {
+  /** Proton number. */
+  readonly Z: number;
+  /** The subshells that differ from the plain filling order, as {label: electrons}. */
+  readonly actual: Readonly<Record<string, number>>;
+  /** Why the electron moves. Stated, because the filling rule does not predict it. */
+  readonly reason: string;
+}
+/**
+ * Ground states that the filling order gets wrong.
+ *
+ * Each is a measured fact, not a derivation. The list is the commonly examined set plus the ones
+ * that follow the same two reasons; an element not listed follows the plain order.
+ */
+declare const ANOMALIES: readonly Anomaly[];
+/** The anomaly for this element, if it has one. */
+declare const anomalyFor: (Z: number) => Anomaly | undefined;
+/**
+ * The ground-state configuration of a neutral atom: the filling order, with any anomaly applied.
+ *
+ * The anomaly is applied by OVERRIDING the named subshells and giving the electrons they release to
+ * the subshells the anomaly names, so the total is checked rather than assumed. A configuration
+ * that did not conserve electrons would be a silent error in a table nobody recounts.
+ */
+declare function configurationOf(Z: number): Configuration;
+/**
+ * The configuration written from the last noble gas: [Ar] 3d⁵ 4s¹.
+ *
+ * This is how a chemist writes it, because the core is the part that never takes part in anything.
+ */
+declare function condensedConfiguration(Z: number): string;
+/**
+ * The configuration of an ion.
+ *
+ * Electrons are removed from the HIGHEST n first, and within that from the highest l. This is the
+ * point everyone loses marks on: iron fills 4s before 3d, but it empties 4s before 3d too, because
+ * once 3d is occupied it sits below 4s. So Fe²⁺ is [Ar]3d⁶, never [Ar]3d⁴4s².
+ *
+ * A negative charge adds electrons in the ordinary filling order.
+ */
+declare function ionConfigurationOf(Z: number, charge: number): Configuration;
+/** One orbital in a diagram: how many electrons, and which way they point. */
+interface OrbitalBox {
+  readonly m: number;
+  /** 0, 1 or 2 electrons. */
+  readonly electrons: number;
+  /** true when the box holds two opposed electrons. */
+  readonly paired: boolean;
+}
+/**
+ * The boxes-and-arrows diagram for one subshell, placed by Hund's rule.
+ *
+ * Every orbital takes one electron, all with the same spin, before any takes a second. So the
+ * diagram is derived from the electron count, and a 2p³ is three separate up arrows rather than one
+ * pair and a single, which is the whole reason nitrogen behaves as it does.
+ */
+declare function orbitalDiagram(l: number, electrons: number): OrbitalBox[];
+/** How many unpaired electrons an atom has, which is what makes it paramagnetic. */
+declare function unpairedElectrons(Z: number): number;
+//#endregion
+export { ANOMALIES, Anomaly, Configuration, Occupancy, OrbitalBox, anomalyFor, aufbauConfiguration, condensedConfiguration, configurationOf, fillingOrder, formatConfiguration, ionConfigurationOf, occupancyLabel, orbitalDiagram, unpairedElectrons };

package/dist/atomic/aufbau.mjs

@@ -0,0 +1,384 @@
+import { magneticNumbers, subshellCapacity, subshellLetter } from "./shells.mjs";
+
+//#region src/atomic/aufbau.ts
+/**
+* Electron configuration, built by the rules rather than looked up.
+*
+* ## The filling order is generated, not memorised
+*
+* Textbooks print the sequence 1s 2s 2p 3s 3p 4s 3d 4p 5s 4d 5p 6s 4f … and expect it to be learnt,
+* usually with a diagonal-arrow diagram. It is not a sequence to learn. It is one rule:
+*
+*     lower (n + l) fills first; where two subshells tie, the lower n fills first
+*
+* That is the Madelung rule, and {@link fillingOrder} generates the sequence from it. So 4s fills
+* before 3d because 4 + 0 = 4 beats 3 + 2 = 5, which is the explanation, and the arrow diagram is
+* only a way of reading the same rule off a grid. Ask for more shells than any book prints and the
+* order keeps going, correctly.
+*
+* ## Hund's rule is about orbitals, not subshells
+*
+* Electrons occupy the orbitals of a subshell singly, with parallel spins, before any orbital takes
+* a second. {@link orbitalDiagram} places them that way, which is what makes the boxes-and-arrows
+* diagram derivable instead of drawn by hand, and it is why nitrogen has three unpaired electrons.
+*
+* ## The exceptions are real physics, and they are listed rather than derived
+*
+* Chromium is [Ar]3d⁵4s¹, not 3d⁴4s². A filled or half-filled d subshell is lower in energy than
+* the plain filling order predicts, by enough to move one electron. That effect is not something
+* the Madelung rule contains, so pretending to derive it would be a lie: {@link ANOMALIES} states
+* each one with its reason, and {@link configurationOf} applies them.
+*
+* ## Ions lose their outermost electrons, not the last one added
+*
+* The single most-missed point in this topic. Iron fills 4s before 3d, so it is tempting to empty
+* 3d first on the way back out. It does not: once 3d is occupied it drops below 4s, so Fe²⁺ is
+* [Ar]3d⁶ with 4s empty, not [Ar]3d⁴4s². {@link ionConfigurationOf} removes from the highest n
+* first, and the doc on it says so, because a learner who gets this wrong gets every transition
+* metal wrong.
+*
+* Pure: no React, no pixels.
+*/
+/** Written order: by shell, then by subshell within it. */
+const byShell = (a, b) => a.n - b.n || a.l - b.l;
+/**
+* Subshells in the order they fill, by the Madelung (n+l) rule.
+*
+* Generated, so it does not stop where a printed table stops.
+*/
+function fillingOrder(maxN = 8) {
+	const all = [];
+	for (let n = 1; n <= maxN; n += 1) for (let l = 0; l < n; l += 1) all.push({
+		n,
+		l
+	});
+	return all.sort((a, b) => a.n + a.l - (b.n + b.l) || a.n - b.n);
+}
+/** How a subshell is written: 3d. */
+const occupancyLabel = (o) => `${o.n}${subshellLetter(o.l)}`;
+const SUPERSCRIPT = "⁰¹²³⁴⁵⁶⁷⁸⁹";
+const superscript = (value) => String(value).split("").map((d) => SUPERSCRIPT[Number(d)] ?? d).join("");
+/**
+* A configuration as it is written: 1s² 2s² 2p⁶.
+*
+* The electron count is SUPERSCRIPTED, because "1s2 2s2 2p6" reads as a string of digits and the
+* whole notation depends on the counts being visibly above the line.
+*/
+const formatConfiguration = (configuration) => configuration.map((o) => `${occupancyLabel(o)}${superscript(o.electrons)}`).join(" ");
+/**
+* The plain filling order applied to Z electrons, with no anomalies.
+*
+* Exported because "what the rule predicts" is half of what makes chromium interesting: the other
+* half is {@link configurationOf}, and a learner needs to see both to see that they differ.
+*/
+function aufbauConfiguration(electrons) {
+	if (!Number.isInteger(electrons) || electrons < 0) throw new Error(`electron count must be a non-negative whole number, got ${electrons}`);
+	const filled = [];
+	let left = electrons;
+	for (const { n, l } of fillingOrder()) {
+		if (left <= 0) break;
+		const take = Math.min(left, subshellCapacity(l));
+		filled.push({
+			n,
+			l,
+			electrons: take
+		});
+		left -= take;
+	}
+	if (left > 0) throw new Error(`${electrons} electrons do not fit in the shells this engine enumerates`);
+	return filled.sort(byShell);
+}
+const HALF_FILLED = "a half-filled subshell is unusually stable, so one s electron moves into it";
+const FILLED = "a filled subshell is unusually stable, so one s electron moves into it";
+const D_BEFORE_F = "the first d electron is lower in energy here than the first f electron, so d fills first";
+/**
+* Ground states that the filling order gets wrong.
+*
+* Each is a measured fact, not a derivation. The list is the commonly examined set plus the ones
+* that follow the same two reasons; an element not listed follows the plain order.
+*/
+const ANOMALIES = [
+	{
+		Z: 24,
+		actual: {
+			"3d": 5,
+			"4s": 1
+		},
+		reason: HALF_FILLED
+	},
+	{
+		Z: 29,
+		actual: {
+			"3d": 10,
+			"4s": 1
+		},
+		reason: FILLED
+	},
+	{
+		Z: 41,
+		actual: {
+			"4d": 4,
+			"5s": 1
+		},
+		reason: "the 4d and 5s levels are so close that a single s electron is enough to lower the total"
+	},
+	{
+		Z: 42,
+		actual: {
+			"4d": 5,
+			"5s": 1
+		},
+		reason: HALF_FILLED
+	},
+	{
+		Z: 44,
+		actual: {
+			"4d": 7,
+			"5s": 1
+		},
+		reason: "the 4d and 5s levels are nearly equal, so the d subshell takes the extra electron"
+	},
+	{
+		Z: 45,
+		actual: {
+			"4d": 8,
+			"5s": 1
+		},
+		reason: "the 4d and 5s levels are nearly equal, so the d subshell takes the extra electron"
+	},
+	{
+		Z: 46,
+		actual: {
+			"4d": 10,
+			"5s": 0
+		},
+		reason: "the only atom whose outermost s subshell is empty: filling 4d completely pays for both s electrons"
+	},
+	{
+		Z: 47,
+		actual: {
+			"4d": 10,
+			"5s": 1
+		},
+		reason: FILLED
+	},
+	{
+		Z: 57,
+		actual: {
+			"4f": 0,
+			"5d": 1
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 58,
+		actual: {
+			"4f": 1,
+			"5d": 1
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 64,
+		actual: {
+			"4f": 7,
+			"5d": 1
+		},
+		reason: HALF_FILLED
+	},
+	{
+		Z: 78,
+		actual: {
+			"5d": 9,
+			"6s": 1
+		},
+		reason: "the 5d and 6s levels are nearly equal, so the d subshell takes the extra electron"
+	},
+	{
+		Z: 79,
+		actual: {
+			"5d": 10,
+			"6s": 1
+		},
+		reason: FILLED
+	},
+	{
+		Z: 89,
+		actual: {
+			"5f": 0,
+			"6d": 1
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 90,
+		actual: {
+			"5f": 0,
+			"6d": 2
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 91,
+		actual: {
+			"5f": 2,
+			"6d": 1
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 92,
+		actual: {
+			"5f": 3,
+			"6d": 1
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 93,
+		actual: {
+			"5f": 4,
+			"6d": 1
+		},
+		reason: D_BEFORE_F
+	},
+	{
+		Z: 96,
+		actual: {
+			"5f": 7,
+			"6d": 1
+		},
+		reason: HALF_FILLED
+	}
+];
+/** The anomaly for this element, if it has one. */
+const anomalyFor = (Z) => ANOMALIES.find((a) => a.Z === Z);
+/**
+* The ground-state configuration of a neutral atom: the filling order, with any anomaly applied.
+*
+* The anomaly is applied by OVERRIDING the named subshells and giving the electrons they release to
+* the subshells the anomaly names, so the total is checked rather than assumed. A configuration
+* that did not conserve electrons would be a silent error in a table nobody recounts.
+*/
+function configurationOf(Z) {
+	const base = aufbauConfiguration(Z);
+	const anomaly = anomalyFor(Z);
+	if (!anomaly) return base;
+	const byLabel = new Map(base.map((o) => [occupancyLabel(o), o]));
+	for (const [label, electrons] of Object.entries(anomaly.actual)) {
+		const existing = byLabel.get(label);
+		if (existing) byLabel.set(label, {
+			...existing,
+			electrons
+		});
+		else {
+			const n = Number(label[0]);
+			const l = "spdfghi".indexOf(label.slice(1));
+			byLabel.set(label, {
+				n,
+				l,
+				electrons
+			});
+		}
+	}
+	const result = [...byLabel.values()].filter((o) => o.electrons > 0).sort(byShell);
+	const total = result.reduce((sum, o) => sum + o.electrons, 0);
+	if (total !== Z) throw new Error(`the anomaly for Z=${Z} accounts for ${total} electrons, not ${Z}`);
+	return result;
+}
+/** Proton numbers of the noble gases, used to abbreviate a configuration. */
+const NOBLE_GASES = [
+	{
+		Z: 2,
+		symbol: "He"
+	},
+	{
+		Z: 10,
+		symbol: "Ne"
+	},
+	{
+		Z: 18,
+		symbol: "Ar"
+	},
+	{
+		Z: 36,
+		symbol: "Kr"
+	},
+	{
+		Z: 54,
+		symbol: "Xe"
+	},
+	{
+		Z: 86,
+		symbol: "Rn"
+	}
+];
+/**
+* The configuration written from the last noble gas: [Ar] 3d⁵ 4s¹.
+*
+* This is how a chemist writes it, because the core is the part that never takes part in anything.
+*/
+function condensedConfiguration(Z) {
+	const core = [...NOBLE_GASES].reverse().find((g) => g.Z < Z);
+	const full = configurationOf(Z);
+	if (!core) return formatConfiguration(full);
+	const outer = full.filter((o) => {
+		const inCore = configurationOf(core.Z).find((c) => c.n === o.n && c.l === o.l);
+		return !inCore || inCore.electrons !== o.electrons;
+	});
+	return `[${core.symbol}] ${formatConfiguration(outer)}`;
+}
+/**
+* The configuration of an ion.
+*
+* Electrons are removed from the HIGHEST n first, and within that from the highest l. This is the
+* point everyone loses marks on: iron fills 4s before 3d, but it empties 4s before 3d too, because
+* once 3d is occupied it sits below 4s. So Fe²⁺ is [Ar]3d⁶, never [Ar]3d⁴4s².
+*
+* A negative charge adds electrons in the ordinary filling order.
+*/
+function ionConfigurationOf(Z, charge) {
+	if (charge <= 0) return aufbauConfiguration(Z - charge);
+	if (charge > Z) throw new Error(`cannot remove ${charge} electrons from an atom with ${Z}`);
+	const shells = configurationOf(Z).map((o) => ({ ...o }));
+	let toRemove = charge;
+	while (toRemove > 0) {
+		const outermost = shells.filter((o) => o.electrons > 0).sort((a, b) => b.n - a.n || b.l - a.l)[0];
+		if (!outermost) throw new Error("ran out of electrons");
+		const take = Math.min(toRemove, outermost.electrons);
+		outermost.electrons -= take;
+		toRemove -= take;
+	}
+	return shells.filter((o) => o.electrons > 0).sort(byShell);
+}
+/**
+* The boxes-and-arrows diagram for one subshell, placed by Hund's rule.
+*
+* Every orbital takes one electron, all with the same spin, before any takes a second. So the
+* diagram is derived from the electron count, and a 2p³ is three separate up arrows rather than one
+* pair and a single, which is the whole reason nitrogen behaves as it does.
+*/
+function orbitalDiagram(l, electrons) {
+	const capacity = subshellCapacity(l);
+	if (electrons > capacity) throw new Error(`a ${subshellLetter(l)} subshell holds ${capacity} electrons, not ${electrons}`);
+	const boxes = magneticNumbers(l).map((m) => ({
+		m,
+		electrons: 0
+	}));
+	for (let placed = 0; placed < electrons; placed += 1) {
+		const box = boxes[placed % boxes.length];
+		box.electrons += 1;
+	}
+	return boxes.map((b) => ({
+		m: b.m,
+		electrons: b.electrons,
+		paired: b.electrons === 2
+	}));
+}
+/** How many unpaired electrons an atom has, which is what makes it paramagnetic. */
+function unpairedElectrons(Z) {
+	return configurationOf(Z).reduce((total, o) => total + orbitalDiagram(o.l, o.electrons).filter((b) => b.electrons === 1).length, 0);
+}
+
+//#endregion
+export { ANOMALIES, anomalyFor, aufbauConfiguration, condensedConfiguration, configurationOf, fillingOrder, formatConfiguration, ionConfigurationOf, occupancyLabel, orbitalDiagram, unpairedElectrons };

package/dist/atomic/elements.d.mts

@@ -0,0 +1,67 @@
+//#region src/atomic/elements.d.ts
+/**
+ * The elements: proton number, symbol, name and standard atomic weight.
+ *
+ * ## Why this is data and the rest of the engine is not
+ *
+ * Everything about WHERE an element sits is computed from its electrons, so this file holds none of
+ * it: no groups, no periods, no blocks, no families. What it holds is the part that cannot be
+ * derived, only measured, and that has to come from somewhere authoritative.
+ *
+ * Standard atomic weights are the IUPAC Commission on Isotopic Abundances and Atomic Weights (CIAAW)
+ * 2021 conventional values, which is what exam data booklets are built from. For elements with no
+ * stable isotope the convention is the mass number of the longest-lived one, and those are marked,
+ * because a value in brackets means something different from a measured average and a learner who
+ * treats [98] as a weighted mean has misunderstood what they are holding.
+ *
+ * ## The order is not monotonic, and that is the point
+ *
+ * Atomic weight mostly rises with proton number and in four places it does not: argon above
+ * potassium, cobalt above nickel, tellurium above iodine, thorium above protactinium. Mendeleev
+ * ordered by weight and had to put tellurium before iodine anyway to make the chemistry work, which
+ * is the historical evidence that proton number, not weight, is what orders the table. A test
+ * asserts exactly these four inversions and no others, so a transcription slip anywhere in this
+ * file shows up as a fifth.
+ *
+ * Pure: no React, no pixels.
+ */
+interface ElementRecord {
+  /** Proton number, which is what orders the table. */
+  readonly Z: number;
+  readonly symbol: string;
+  readonly name: string;
+  /**
+   * Standard atomic weight, IUPAC CIAAW 2021 conventional value.
+   *
+   * For an element with no stable isotope this is a MASS NUMBER, not a weighted mean over isotopes.
+   * {@link ElementRecord.weightIsMassNumber} says which, because the two are different quantities
+   * that happen to be printed in the same column.
+   */
+  readonly atomicWeight: number;
+  readonly weightIsMassNumber: boolean;
+}
+/** Every element, in proton-number order. */
+declare const ELEMENTS: readonly ElementRecord[];
+/** The element with this proton number. */
+declare const elementOf: (Z: number) => ElementRecord | undefined;
+/** Look up by symbol, case-insensitively, so "NA", "Na" and "na" all find sodium. */
+declare const elementBySymbol: (symbol: string) => ElementRecord | undefined;
+/** Look up by name, spelled as IUPAC spells it. */
+declare const elementByName: (name: string) => ElementRecord | undefined;
+/** The symbol for a proton number, which is what a decay equation needs. */
+declare const symbolOf: (Z: number) => string | undefined;
+/**
+ * The four places where MEASURED atomic weight falls as proton number rises.
+ *
+ * Kept as a named export rather than buried in a test, because these pairs ARE the evidence that
+ * the table is ordered by proton number: Mendeleev ordered by weight and still had to place
+ * tellurium before iodine to keep the chemistry right, which was the anomaly that proton number
+ * later explained.
+ *
+ * Measured weights only. An element with no stable isotope carries the mass number of its
+ * longest-lived one, and which isotope lives longest does not rise smoothly with proton number, so
+ * those steps down are not inversions in this sense and are not listed.
+ */
+declare const MASS_INVERSIONS: readonly (readonly [string, string])[];
+//#endregion
+export { ELEMENTS, ElementRecord, MASS_INVERSIONS, elementByName, elementBySymbol, elementOf, symbolOf };