@classytic/stage 0.2.0 → 0.4.0

package/dist/atomic/shells.d.mts

@@ -0,0 +1,137 @@
+//#region src/atomic/shells.d.ts
+/**
+ * Shells, subshells and orbitals, enumerated from the four quantum numbers.
+ *
+ * ## Why this is computed and not typed out
+ *
+ * Every textbook prints the same table: shell K/L/M/N, subshells 1s / 2s2p / 3s3p3d, the m values,
+ * how many orbitals, 2(2l+1) electrons each, 2n² in the shell. It is printed because it is tedious,
+ * and because it is printed it stops at n=4 and cannot be re-asked with different numbers.
+ *
+ * It is not a table. It is four rules:
+ *
+ *     n  = 1, 2, 3, …                  which shell
+ *     l  = 0 … n-1                     which subshell, named s p d f g h
+ *     m  = -l … +l                     which orbital in it, so 2l+1 of them
+ *     s  = +1/2 or -1/2                which of the two electrons in that orbital
+ *
+ * Everything else follows. 2l+1 orbitals holding two electrons each is 2(2l+1) per subshell, and
+ * summing that over l = 0…n-1 is 2n², which is why the shell capacities are 2, 8, 18, 32 and why
+ * they are not four numbers to memorise.
+ *
+ * ## What Pauli actually says here
+ *
+ * No two electrons in one atom share all four numbers. Since n, l and m name a single orbital, and
+ * s has two values, an orbital holds at most two electrons and they must be opposed. So the
+ * exclusion principle is not an extra fact on top of the table: it is the reason the table has the
+ * capacities it has, and {@link isPauliValid} enforces it rather than restating it.
+ *
+ * Pure: no React, no pixels.
+ */
+/**
+ * Subshell letters in l order.
+ *
+ * s, p, d and f are historical, from the spectral lines they were first seen in: sharp, principal,
+ * diffuse, fundamental. From g onward the sequence is simply alphabetical, except that j is skipped
+ * because it was too easily confused with i in print.
+ *
+ * It runs to l=7 so that the (n+l) filling order can be generated for n=8, which is past every
+ * element that exists but is where a generated sequence naturally stops.
+ */
+declare const SUBSHELL_LETTERS: readonly ["s", "p", "d", "f", "g", "h", "i", "k"];
+type SubshellLetter = (typeof SUBSHELL_LETTERS)[number];
+/** The letter for a subshell, so l=2 reads as "d" rather than as a number. */
+declare function subshellLetter(l: number): SubshellLetter;
+/** The shell letter, K for n=1. Undefined past Q, which no atom reaches. */
+declare const shellLetter: (n: number) => string | undefined;
+/** How many orbitals a subshell has: 2l+1, one for each m from -l to +l. */
+declare const orbitalsInSubshell: (l: number) => number;
+/**
+ * Electrons one orbital can hold, which is the Pauli exclusion principle and nothing else.
+ *
+ * Named rather than written as a bare 2, because that 2 is the principle itself and appears in
+ * every capacity in this file. An orbital is fixed by n, l and m; the only quantum number left free
+ * is spin, which has two values; no two electrons may share all four. So an orbital holds two
+ * electrons with opposed spins, a subshell holds 2(2l+1), and a shell holds 2n². Those are not
+ * three facts to learn, they are one fact counted three ways.
+ *
+ * {@link isPauliValid} enforces the same principle on an explicit set of electrons, which is the
+ * form it takes when the question is whether a given arrangement is allowed.
+ */
+declare const ELECTRONS_PER_ORBITAL = 2;
+/** The m values of a subshell, in the order they are conventionally written. */
+declare function magneticNumbers(l: number): number[];
+/** Electrons a subshell holds: two per orbital, so 2(2l+1). */
+declare const subshellCapacity: (l: number) => number;
+/**
+ * Electrons a shell holds.
+ *
+ * Returned as the SUM over its subshells rather than as the formula 2n², because the sum is the
+ * reason and the formula is the consequence. A test asserts the two agree, which is the only place
+ * 2n² is written down.
+ */
+declare const shellCapacity: (n: number) => number;
+/** The l values present in shell n: 0 up to n-1, which is why n=1 has only an s subshell. */
+declare function subshellsOf(n: number): number[];
+interface Subshell {
+  /** Principal quantum number. */
+  readonly n: number;
+  /** Azimuthal quantum number, 0 for s. */
+  readonly l: number;
+  /** How it is written: "3d". */
+  readonly label: string;
+  /** The m value of each orbital, -l to +l. */
+  readonly magnetic: readonly number[];
+  readonly orbitals: number;
+  readonly capacity: number;
+}
+/** One subshell, described. */
+declare function subshell(n: number, l: number): Subshell;
+interface Shell {
+  readonly n: number;
+  /** K, L, M, N. Undefined past Q. */
+  readonly letter: string | undefined;
+  readonly subshells: readonly Subshell[];
+  readonly orbitals: number;
+  readonly capacity: number;
+}
+/**
+ * One shell and everything in it: the row of the table every textbook prints, for any n.
+ *
+ * Nothing here is looked up. Ask for n=7 and you get a correct row that no book contains.
+ */
+declare function shell(n: number): Shell;
+/** A complete address for one electron. */
+interface QuantumNumbers {
+  readonly n: number;
+  readonly l: number;
+  readonly m: number;
+  /** Spin, +1/2 or -1/2. */
+  readonly s: number;
+}
+/**
+ * Why a set of four quantum numbers cannot describe an electron, or undefined if it can.
+ *
+ * Returns the REASON rather than a boolean, because "which of these sets is impossible" is the
+ * standard exam question and the mark is for saying which rule is broken. A checker that answers
+ * true or false can mark the question but cannot teach it.
+ */
+declare function quantumNumbersRefusal(q: QuantumNumbers): string | undefined;
+/** Whether four quantum numbers describe a possible electron. */
+declare const isValidQuantumNumbers: (q: QuantumNumbers) => boolean;
+/**
+ * Whether a set of electrons could coexist in one atom.
+ *
+ * Two electrons sharing all four numbers is the exclusion principle violated. This is what limits
+ * an orbital to two electrons, so it is checked here rather than asserted as a separate capacity.
+ */
+declare function isPauliValid(electrons: readonly QuantumNumbers[]): boolean;
+/** Every orbital in a shell, as its address. Used to lay out an orbital diagram. */
+declare function orbitalsOf(n: number): {
+  n: number;
+  l: number;
+  m: number;
+  label: string;
+}[];
+//#endregion
+export { ELECTRONS_PER_ORBITAL, QuantumNumbers, SUBSHELL_LETTERS, Shell, Subshell, SubshellLetter, isPauliValid, isValidQuantumNumbers, magneticNumbers, orbitalsInSubshell, orbitalsOf, quantumNumbersRefusal, shell, shellCapacity, shellLetter, subshell, subshellCapacity, subshellLetter, subshellsOf };

package/dist/atomic/shells.mjs

@@ -0,0 +1,170 @@
+//#region src/atomic/shells.ts
+/**
+* Shells, subshells and orbitals, enumerated from the four quantum numbers.
+*
+* ## Why this is computed and not typed out
+*
+* Every textbook prints the same table: shell K/L/M/N, subshells 1s / 2s2p / 3s3p3d, the m values,
+* how many orbitals, 2(2l+1) electrons each, 2n² in the shell. It is printed because it is tedious,
+* and because it is printed it stops at n=4 and cannot be re-asked with different numbers.
+*
+* It is not a table. It is four rules:
+*
+*     n  = 1, 2, 3, …                  which shell
+*     l  = 0 … n-1                     which subshell, named s p d f g h
+*     m  = -l … +l                     which orbital in it, so 2l+1 of them
+*     s  = +1/2 or -1/2                which of the two electrons in that orbital
+*
+* Everything else follows. 2l+1 orbitals holding two electrons each is 2(2l+1) per subshell, and
+* summing that over l = 0…n-1 is 2n², which is why the shell capacities are 2, 8, 18, 32 and why
+* they are not four numbers to memorise.
+*
+* ## What Pauli actually says here
+*
+* No two electrons in one atom share all four numbers. Since n, l and m name a single orbital, and
+* s has two values, an orbital holds at most two electrons and they must be opposed. So the
+* exclusion principle is not an extra fact on top of the table: it is the reason the table has the
+* capacities it has, and {@link isPauliValid} enforces it rather than restating it.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* Subshell letters in l order.
+*
+* s, p, d and f are historical, from the spectral lines they were first seen in: sharp, principal,
+* diffuse, fundamental. From g onward the sequence is simply alphabetical, except that j is skipped
+* because it was too easily confused with i in print.
+*
+* It runs to l=7 so that the (n+l) filling order can be generated for n=8, which is past every
+* element that exists but is where a generated sequence naturally stops.
+*/
+const SUBSHELL_LETTERS = [
+	"s",
+	"p",
+	"d",
+	"f",
+	"g",
+	"h",
+	"i",
+	"k"
+];
+/** Spectroscopic shell names, still used for X-ray notation. K is n=1, not n=0. */
+const SHELL_LETTERS = [
+	"K",
+	"L",
+	"M",
+	"N",
+	"O",
+	"P",
+	"Q"
+];
+/** The letter for a subshell, so l=2 reads as "d" rather than as a number. */
+function subshellLetter(l) {
+	const letter = SUBSHELL_LETTERS[l];
+	if (!letter) throw new Error(`no subshell letter for l=${l}: only l=0..${SUBSHELL_LETTERS.length - 1} are named`);
+	return letter;
+}
+/** The shell letter, K for n=1. Undefined past Q, which no atom reaches. */
+const shellLetter = (n) => SHELL_LETTERS[n - 1];
+/** How many orbitals a subshell has: 2l+1, one for each m from -l to +l. */
+const orbitalsInSubshell = (l) => 2 * l + 1;
+/**
+* Electrons one orbital can hold, which is the Pauli exclusion principle and nothing else.
+*
+* Named rather than written as a bare 2, because that 2 is the principle itself and appears in
+* every capacity in this file. An orbital is fixed by n, l and m; the only quantum number left free
+* is spin, which has two values; no two electrons may share all four. So an orbital holds two
+* electrons with opposed spins, a subshell holds 2(2l+1), and a shell holds 2n². Those are not
+* three facts to learn, they are one fact counted three ways.
+*
+* {@link isPauliValid} enforces the same principle on an explicit set of electrons, which is the
+* form it takes when the question is whether a given arrangement is allowed.
+*/
+const ELECTRONS_PER_ORBITAL = 2;
+/** The m values of a subshell, in the order they are conventionally written. */
+function magneticNumbers(l) {
+	if (l < 0 || !Number.isInteger(l)) throw new Error(`l must be a non-negative integer, got ${l}`);
+	return Array.from({ length: orbitalsInSubshell(l) }, (_, k) => k - l);
+}
+/** Electrons a subshell holds: two per orbital, so 2(2l+1). */
+const subshellCapacity = (l) => 2 * orbitalsInSubshell(l);
+/**
+* Electrons a shell holds.
+*
+* Returned as the SUM over its subshells rather than as the formula 2n², because the sum is the
+* reason and the formula is the consequence. A test asserts the two agree, which is the only place
+* 2n² is written down.
+*/
+const shellCapacity = (n) => subshellsOf(n).reduce((total, l) => total + subshellCapacity(l), 0);
+/** The l values present in shell n: 0 up to n-1, which is why n=1 has only an s subshell. */
+function subshellsOf(n) {
+	if (n < 1 || !Number.isInteger(n)) throw new Error(`n must be a positive integer, got ${n}`);
+	return Array.from({ length: n }, (_, l) => l);
+}
+/** One subshell, described. */
+function subshell(n, l) {
+	if (l >= n) throw new Error(`no ${n}${SUBSHELL_LETTERS[l] ?? `l=${l}`} subshell: l must be less than n`);
+	const magnetic = magneticNumbers(l);
+	return {
+		n,
+		l,
+		label: `${n}${subshellLetter(l)}`,
+		magnetic,
+		orbitals: magnetic.length,
+		capacity: subshellCapacity(l)
+	};
+}
+/**
+* One shell and everything in it: the row of the table every textbook prints, for any n.
+*
+* Nothing here is looked up. Ask for n=7 and you get a correct row that no book contains.
+*/
+function shell(n) {
+	const subshells = subshellsOf(n).map((l) => subshell(n, l));
+	return {
+		n,
+		letter: shellLetter(n),
+		subshells,
+		orbitals: subshells.reduce((total, s) => total + s.orbitals, 0),
+		capacity: subshells.reduce((total, s) => total + s.capacity, 0)
+	};
+}
+/**
+* Why a set of four quantum numbers cannot describe an electron, or undefined if it can.
+*
+* Returns the REASON rather than a boolean, because "which of these sets is impossible" is the
+* standard exam question and the mark is for saying which rule is broken. A checker that answers
+* true or false can mark the question but cannot teach it.
+*/
+function quantumNumbersRefusal(q) {
+	if (!Number.isInteger(q.n) || q.n < 1) return "n must be a whole number of at least 1: there is no shell below the first";
+	if (!Number.isInteger(q.l) || q.l < 0) return "l must be a whole number of at least 0";
+	if (q.l >= q.n) return `l must be less than n, so shell ${q.n} has no ${subshellLetter(q.l) ?? "such"} subshell`;
+	if (!Number.isInteger(q.m)) return "m must be a whole number";
+	if (Math.abs(q.m) > q.l) return `m must lie between -l and +l, so a ${subshellLetter(q.l)} subshell has no m = ${q.m}`;
+	if (Math.abs(q.s) !== .5) return "spin is +1/2 or -1/2 and has no other value";
+}
+/** Whether four quantum numbers describe a possible electron. */
+const isValidQuantumNumbers = (q) => quantumNumbersRefusal(q) === void 0;
+/**
+* Whether a set of electrons could coexist in one atom.
+*
+* Two electrons sharing all four numbers is the exclusion principle violated. This is what limits
+* an orbital to two electrons, so it is checked here rather than asserted as a separate capacity.
+*/
+function isPauliValid(electrons) {
+	if (electrons.some((e) => !isValidQuantumNumbers(e))) return false;
+	return new Set(electrons.map((e) => `${e.n}|${e.l}|${e.m}|${e.s}`)).size === electrons.length;
+}
+/** Every orbital in a shell, as its address. Used to lay out an orbital diagram. */
+function orbitalsOf(n) {
+	return subshellsOf(n).flatMap((l) => magneticNumbers(l).map((m) => ({
+		n,
+		l,
+		m,
+		label: `${n}${subshellLetter(l)}`
+	})));
+}
+
+//#endregion
+export { ELECTRONS_PER_ORBITAL, SUBSHELL_LETTERS, isPauliValid, isValidQuantumNumbers, magneticNumbers, orbitalsInSubshell, orbitalsOf, quantumNumbersRefusal, shell, shellCapacity, shellLetter, subshell, subshellCapacity, subshellLetter, subshellsOf };

package/dist/atomic/trends.d.mts

@@ -0,0 +1,148 @@
+//#region src/atomic/trends.d.ts
+/**
+ * Periodic trends, read off the measurements rather than asserted.
+ *
+ * ## Why a trend should be found and not stated
+ *
+ * A book prints "atomic radius decreases across a period" with an arrow, and the statement is the
+ * whole of the teaching. But the statement is a CONCLUSION, and handing someone a conclusion is
+ * the one thing that guarantees they never do the work that produces it. If the measurements are
+ * there instead, a learner can lay them out, see the direction for themselves, predict the next
+ * one, and be told whether they were right. {@link trendOf} is what makes that possible: it takes
+ * a run of real values and reports which way they go and where they break.
+ *
+ * So nothing in this file stores a trend. Every direction below comes out of the numbers.
+ *
+ * ## The exceptions are the point, not the small print
+ *
+ * First ionisation energy rises across period 3, except twice. Between magnesium and aluminium it
+ * falls, and between phosphorus and sulfur it falls again. Those two dips are usually taught as
+ * things to remember. They are the opposite: they are the evidence.
+ *
+ * The first dip happens because aluminium's outer electron is in a 3p orbital, higher in energy
+ * than magnesium's filled 3s, so it comes away more easily despite the greater nuclear charge. That
+ * is a direct measurement of the fact that a shell has subshells inside it. The second happens
+ * because sulfur has its first PAIRED p electron, and two electrons sharing one orbital repel each
+ * other, so one leaves more easily than from phosphorus's half-filled subshell. That is a direct
+ * measurement of electron pairing.
+ *
+ * Neither could be deduced from the filling rules. Both are visible in the numbers. So
+ * {@link IONISATION_ANOMALIES} carries them with the reasoning attached, and a test asserts that
+ * these are the ONLY breaks in the run, which also means a mistyped energy anywhere shows up as a
+ * third.
+ *
+ * ## Bond character is a curve, not a table
+ *
+ * The usual table says a difference under 0.5 is non-polar, up to 1.7 is polar, and above that is
+ * ionic. Those boundaries are conventions drawn across something continuous. Pauling's own relation
+ * gives the proportion of ionic character directly, and the familiar 1.7 is simply where it passes
+ * a half. {@link ionicCharacter} computes it, and the band names are labels put on the curve rather
+ * than the thing itself.
+ *
+ * Pure: no React, no pixels.
+ */
+/** A property that can be plotted across a period or down a group. */
+type PropertyName = 'covalentRadius' | 'firstIonisationEnergy' | 'electronegativity';
+interface DataPoint {
+  readonly Z: number;
+  readonly symbol: string;
+  readonly value: number;
+}
+/**
+ * A property across one period, in group order.
+ *
+ * Elements with no measurement are left out rather than given a zero, so a gap in the data shows as
+ * a shorter run and never as a spurious plunge to the axis.
+ */
+declare function acrossPeriod(period: number, property: PropertyName): DataPoint[];
+/** A property down one group, in period order. */
+declare function downGroup(group: number, property: PropertyName): DataPoint[];
+type Direction = 'rising' | 'falling' | 'flat';
+interface Trend {
+  readonly direction: Direction;
+  /** Steps that go against the overall direction, as the pair they sit between. */
+  readonly exceptions: readonly (readonly [string, string])[];
+  readonly points: readonly DataPoint[];
+}
+/**
+ * Which way a run of measurements goes, and where it breaks.
+ *
+ * The direction is decided by the whole run rather than step by step, so a couple of dips do not
+ * flip a rise into "no pattern". The dips come back as exceptions instead, which is the shape the
+ * chemistry actually has: a strong trend with a small number of informative breaks in it.
+ */
+declare function trendOf(points: readonly DataPoint[]): Trend;
+interface IonisationAnomaly {
+  /** The element before the dip. */
+  readonly before: string;
+  /** The element whose ionisation energy is lower than the one before it. */
+  readonly after: string;
+  /** What the dip is evidence OF. */
+  readonly reason: string;
+}
+/**
+ * Every place first ionisation energy falls as it crosses a period, with what it demonstrates.
+ *
+ * Four of them, two per period, and they are the same two causes each time: a new subshell starting,
+ * and a p orbital taking its second electron.
+ */
+declare const IONISATION_ANOMALIES: readonly IonisationAnomaly[];
+/** The anomaly between two named elements, if there is one. */
+declare const ionisationAnomalyFor: (before: string, after: string) => IonisationAnomaly | undefined;
+interface ShellEvidence {
+  /** Electrons in the outermost shell, which is the group for a main-group element. */
+  readonly outerElectrons: number;
+  /** How many times bigger the jump is than the step before it. */
+  readonly jumpRatio: number;
+  /** The ionisation the jump happens at, counting from one. */
+  readonly atIonisation: number;
+}
+/**
+ * Read the number of outer-shell electrons off a run of successive ionisation energies.
+ *
+ * The argument for shells, run as a calculation. Removing electrons from the outer shell gets
+ * steadily harder; breaking into the shell beneath is suddenly far harder, because that shell is
+ * closer to the nucleus and fully shielded. So the position of the big jump counts the outer shell.
+ *
+ * Returns undefined when no jump in the data is decisive. That is the honest answer for a run that
+ * stops before it reaches the next shell, which is exactly what published runs for neon and argon
+ * do: eight ionisation energies, all from the same shell, and no break to find. Returning a number
+ * anyway would be inventing a conclusion the measurements do not support.
+ */
+declare function outerElectronsFromIonisation(energies: readonly number[], minimumRatio?: number): ShellEvidence | undefined;
+/** The same, for an element this engine has a published run for. */
+declare function outerElectronsOf(symbol: string): ShellEvidence | undefined;
+/** The gap in electronegativity between two elements, which sets how a bond between them behaves. */
+declare function electronegativityGap(a: string, b: string): number;
+/**
+ * The proportion of ionic character in a bond, from Pauling's relation.
+ *
+ * ionic character = 1 - exp(-(difference / 2)^2)
+ *
+ * A curve, not a table. The familiar boundary at a difference of 1.7 is simply where this passes a
+ * half, and it is a convention placed on something continuous rather than a line the physics draws.
+ */
+declare const ionicCharacter: (difference: number) => number;
+type BondCharacter = 'nonpolar covalent' | 'polar covalent' | 'ionic';
+/**
+ * The name usually given to a bond with this electronegativity difference.
+ *
+ * The boundaries are the conventional ones. They are labels on {@link ionicCharacter}'s curve, and
+ * a bond just either side of one of them is very nearly the same bond, which is worth saying out
+ * loud whenever this function's answer is shown to anyone.
+ */
+declare function bondCharacter(difference: number): BondCharacter;
+/** The character of the bond between two named elements. */
+declare const bondBetween: (a: string, b: string) => BondCharacter;
+/**
+ * Which of two elements holds its outer electrons more tightly, and why.
+ *
+ * Answers with the reasoning, because "which has the higher ionisation energy" is never the real
+ * question: the real question is what about their positions makes it so.
+ */
+declare function compareIonisationEnergy(a: string, b: string): {
+  higher: string;
+  reason: string;
+} | undefined;
+//#endregion
+export { BondCharacter, DataPoint, Direction, IONISATION_ANOMALIES, IonisationAnomaly, PropertyName, ShellEvidence, Trend, acrossPeriod, bondBetween, bondCharacter, compareIonisationEnergy, downGroup, electronegativityGap, ionicCharacter, ionisationAnomalyFor, outerElectronsFromIonisation, outerElectronsOf, trendOf };

package/dist/atomic/trends.mjs

@@ -0,0 +1,225 @@
+import { groupOf, periodOf } from "./periodic.mjs";
+import { elementBySymbol, symbolOf } from "./elements.mjs";
+import { PROPERTIES, SUCCESSIVE_IONISATION_ENERGIES, covalentRadius, electronegativity, firstIonisationEnergy } from "./properties.mjs";
+
+//#region src/atomic/trends.ts
+/**
+* Periodic trends, read off the measurements rather than asserted.
+*
+* ## Why a trend should be found and not stated
+*
+* A book prints "atomic radius decreases across a period" with an arrow, and the statement is the
+* whole of the teaching. But the statement is a CONCLUSION, and handing someone a conclusion is
+* the one thing that guarantees they never do the work that produces it. If the measurements are
+* there instead, a learner can lay them out, see the direction for themselves, predict the next
+* one, and be told whether they were right. {@link trendOf} is what makes that possible: it takes
+* a run of real values and reports which way they go and where they break.
+*
+* So nothing in this file stores a trend. Every direction below comes out of the numbers.
+*
+* ## The exceptions are the point, not the small print
+*
+* First ionisation energy rises across period 3, except twice. Between magnesium and aluminium it
+* falls, and between phosphorus and sulfur it falls again. Those two dips are usually taught as
+* things to remember. They are the opposite: they are the evidence.
+*
+* The first dip happens because aluminium's outer electron is in a 3p orbital, higher in energy
+* than magnesium's filled 3s, so it comes away more easily despite the greater nuclear charge. That
+* is a direct measurement of the fact that a shell has subshells inside it. The second happens
+* because sulfur has its first PAIRED p electron, and two electrons sharing one orbital repel each
+* other, so one leaves more easily than from phosphorus's half-filled subshell. That is a direct
+* measurement of electron pairing.
+*
+* Neither could be deduced from the filling rules. Both are visible in the numbers. So
+* {@link IONISATION_ANOMALIES} carries them with the reasoning attached, and a test asserts that
+* these are the ONLY breaks in the run, which also means a mistyped energy anywhere shows up as a
+* third.
+*
+* ## Bond character is a curve, not a table
+*
+* The usual table says a difference under 0.5 is non-polar, up to 1.7 is polar, and above that is
+* ionic. Those boundaries are conventions drawn across something continuous. Pauling's own relation
+* gives the proportion of ionic character directly, and the familiar 1.7 is simply where it passes
+* a half. {@link ionicCharacter} computes it, and the band names are labels put on the curve rather
+* than the thing itself.
+*
+* Pure: no React, no pixels.
+*/
+const READERS = {
+	covalentRadius,
+	firstIonisationEnergy,
+	electronegativity
+};
+const pointsFor = (elements, property) => elements.map((Z) => ({
+	Z,
+	symbol: symbolOf(Z),
+	value: READERS[property](Z)
+})).filter((p) => p.value !== void 0);
+/**
+* A property across one period, in group order.
+*
+* Elements with no measurement are left out rather than given a zero, so a gap in the data shows as
+* a shorter run and never as a spurious plunge to the axis.
+*/
+function acrossPeriod(period, property) {
+	return pointsFor(PROPERTIES.map((p) => p.Z).filter((Z) => periodOf(Z) === period).sort((a, b) => groupOf(a) - groupOf(b)), property);
+}
+/** A property down one group, in period order. */
+function downGroup(group, property) {
+	return pointsFor(PROPERTIES.map((p) => p.Z).filter((Z) => groupOf(Z) === group).sort((a, b) => periodOf(a) - periodOf(b)), property);
+}
+/**
+* Which way a run of measurements goes, and where it breaks.
+*
+* The direction is decided by the whole run rather than step by step, so a couple of dips do not
+* flip a rise into "no pattern". The dips come back as exceptions instead, which is the shape the
+* chemistry actually has: a strong trend with a small number of informative breaks in it.
+*/
+function trendOf(points) {
+	if (points.length < 2) return {
+		direction: "flat",
+		exceptions: [],
+		points
+	};
+	const overall = points[points.length - 1].value - points[0].value;
+	const span = Math.abs(points[0].value) || 1;
+	const direction = Math.abs(overall) / span < .02 ? "flat" : overall > 0 ? "rising" : "falling";
+	const exceptions = [];
+	for (let i = 1; i < points.length; i += 1) {
+		const step = points[i].value - points[i - 1].value;
+		if (direction === "rising" ? step < 0 : direction === "falling" ? step > 0 : false) exceptions.push([points[i - 1].symbol, points[i].symbol]);
+	}
+	return {
+		direction,
+		exceptions,
+		points
+	};
+}
+/**
+* Every place first ionisation energy falls as it crosses a period, with what it demonstrates.
+*
+* Four of them, two per period, and they are the same two causes each time: a new subshell starting,
+* and a p orbital taking its second electron.
+*/
+const IONISATION_ANOMALIES = [
+	{
+		before: "Be",
+		after: "B",
+		reason: "boron's outermost electron is in a 2p orbital, which is higher in energy than beryllium's filled 2s, so it comes away more easily despite boron having the larger nuclear charge. The dip is evidence that a shell contains subshells."
+	},
+	{
+		before: "N",
+		after: "O",
+		reason: "oxygen has the first PAIRED electron in its 2p subshell, and two electrons sharing one orbital repel each other, so one of them leaves more easily than any electron in nitrogen's half-filled subshell. The dip is evidence of electron pairing."
+	},
+	{
+		before: "Mg",
+		after: "Al",
+		reason: "aluminium's outermost electron is in a 3p orbital, higher in energy than magnesium's filled 3s, so it comes away more easily. The same subshell effect as beryllium to boron, one period down."
+	},
+	{
+		before: "P",
+		after: "S",
+		reason: "sulfur has the first paired electron in its 3p subshell, and the repulsion between the two electrons in that orbital makes one easier to remove than any in phosphorus's half-filled subshell. The same pairing effect as nitrogen to oxygen."
+	}
+];
+/** The anomaly between two named elements, if there is one. */
+const ionisationAnomalyFor = (before, after) => IONISATION_ANOMALIES.find((a) => a.before === before && a.after === after);
+/**
+* Read the number of outer-shell electrons off a run of successive ionisation energies.
+*
+* The argument for shells, run as a calculation. Removing electrons from the outer shell gets
+* steadily harder; breaking into the shell beneath is suddenly far harder, because that shell is
+* closer to the nucleus and fully shielded. So the position of the big jump counts the outer shell.
+*
+* Returns undefined when no jump in the data is decisive. That is the honest answer for a run that
+* stops before it reaches the next shell, which is exactly what published runs for neon and argon
+* do: eight ionisation energies, all from the same shell, and no break to find. Returning a number
+* anyway would be inventing a conclusion the measurements do not support.
+*/
+function outerElectronsFromIonisation(energies, minimumRatio = 2) {
+	if (energies.length < 2) return void 0;
+	let best = {
+		ratio: 0,
+		at: 0
+	};
+	for (let i = 1; i < energies.length; i += 1) {
+		const ratio = energies[i] / energies[i - 1];
+		if (ratio > best.ratio) best = {
+			ratio,
+			at: i
+		};
+	}
+	if (best.ratio < minimumRatio) return void 0;
+	return {
+		outerElectrons: best.at,
+		jumpRatio: best.ratio,
+		atIonisation: best.at + 1
+	};
+}
+/** The same, for an element this engine has a published run for. */
+function outerElectronsOf(symbol) {
+	const energies = SUCCESSIVE_IONISATION_ENERGIES[symbol];
+	if (!energies) throw new Error(`no successive ionisation energies for ${symbol}`);
+	return outerElectronsFromIonisation(energies);
+}
+/** The gap in electronegativity between two elements, which sets how a bond between them behaves. */
+function electronegativityGap(a, b) {
+	const first = elementBySymbol(a);
+	const second = elementBySymbol(b);
+	if (!first || !second) throw new Error(`no element with symbol "${first ? b : a}"`);
+	const x = electronegativity(first.Z);
+	const y = electronegativity(second.Z);
+	if (x === void 0 || y === void 0) throw new Error(`the Pauling scale has no value for ${x === void 0 ? a : b}, so no difference can be taken`);
+	return Math.abs(x - y);
+}
+/**
+* The proportion of ionic character in a bond, from Pauling's relation.
+*
+* ionic character = 1 - exp(-(difference / 2)^2)
+*
+* A curve, not a table. The familiar boundary at a difference of 1.7 is simply where this passes a
+* half, and it is a convention placed on something continuous rather than a line the physics draws.
+*/
+const ionicCharacter = (difference) => 1 - Math.exp(-((difference / 2) ** 2));
+/**
+* The name usually given to a bond with this electronegativity difference.
+*
+* The boundaries are the conventional ones. They are labels on {@link ionicCharacter}'s curve, and
+* a bond just either side of one of them is very nearly the same bond, which is worth saying out
+* loud whenever this function's answer is shown to anyone.
+*/
+function bondCharacter(difference) {
+	if (difference < .5) return "nonpolar covalent";
+	if (difference < 1.7) return "polar covalent";
+	return "ionic";
+}
+/** The character of the bond between two named elements. */
+const bondBetween = (a, b) => bondCharacter(electronegativityGap(a, b));
+/**
+* Which of two elements holds its outer electrons more tightly, and why.
+*
+* Answers with the reasoning, because "which has the higher ionisation energy" is never the real
+* question: the real question is what about their positions makes it so.
+*/
+function compareIonisationEnergy(a, b) {
+	const first = elementBySymbol(a);
+	const second = elementBySymbol(b);
+	if (!first || !second) return void 0;
+	const x = firstIonisationEnergy(first.Z);
+	const y = firstIonisationEnergy(second.Z);
+	if (x === void 0 || y === void 0) return void 0;
+	const higher = x > y ? a : b;
+	const anomaly = ionisationAnomalyFor(a, b) ?? ionisationAnomalyFor(b, a);
+	if (anomaly) return {
+		higher,
+		reason: anomaly.reason
+	};
+	return {
+		higher,
+		reason: periodOf(first.Z) === periodOf(second.Z) ? "they are in the same period, so the electron comes from the same shell, and the one further right has more protons pulling on it" : "the one lower down has its outer electron in a shell further from the nucleus and better shielded by the shells between, so it is held less tightly"
+	};
+}
+
+//#endregion
+export { IONISATION_ANOMALIES, acrossPeriod, bondBetween, bondCharacter, compareIonisationEnergy, downGroup, electronegativityGap, ionicCharacter, ionisationAnomalyFor, outerElectronsFromIonisation, outerElectronsOf, trendOf };