@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/molecule.mjs

@@ -0,0 +1,282 @@
+//#region src/chem/molecule.ts
+/** Bonds a valence shell can make, before any is used. */
+const VALENCE = {
+	C: 4,
+	N: 3,
+	O: 2,
+	S: 2,
+	P: 3,
+	F: 1,
+	Cl: 1,
+	Br: 1,
+	I: 1,
+	H: 1
+};
+/** Relative atomic masses, to the precision a data booklet prints. */
+const ATOMIC_MASS = {
+	H: 1,
+	C: 12,
+	N: 14,
+	O: 16,
+	F: 19,
+	P: 31,
+	S: 32.1,
+	Cl: 35.5,
+	Br: 79.9,
+	I: 126.9
+};
+const TWO_LETTER = new Set(["Cl", "Br"]);
+/**
+* Parse the SMILES subset A level needs.
+*
+* `CCO` ethanol, `CC(=O)C` propanone, `c1ccccc1` benzene, `CC(=O)OCC` ethyl ethanoate.
+*
+* Refuses anything it does not fully understand rather than guessing, because a parser that
+* silently drops a feature produces a molecule that is not the one the author wrote, and every
+* number computed from it afterwards is then confidently wrong.
+*/
+function parseSmiles(smiles) {
+	const atoms = [];
+	const bonds = [];
+	const branchStack = [];
+	const ringOpen = /* @__PURE__ */ new Map();
+	let previous;
+	let pendingOrder;
+	let pendingAromatic = false;
+	const addAtom = (element, aromatic, extra = {}) => {
+		const id = atoms.length;
+		atoms.push({
+			id,
+			element,
+			aromatic,
+			...extra
+		});
+		if (previous !== void 0) {
+			const order = pendingOrder ?? 1;
+			const arom = pendingAromatic || aromatic && atoms[previous].aromatic && pendingOrder === void 0;
+			bonds.push({
+				a: previous,
+				b: id,
+				order,
+				aromatic: arom
+			});
+		}
+		previous = id;
+		pendingOrder = void 0;
+		pendingAromatic = false;
+		return id;
+	};
+	let i = 0;
+	while (i < smiles.length) {
+		const ch = smiles[i];
+		if (ch === "[") {
+			const close = smiles.indexOf("]", i);
+			if (close === -1) throw new Error(`"${smiles}": a bracket atom is never closed.`);
+			const inside = smiles.slice(i + 1, close);
+			const match = /^([A-Za-z][a-z]?)(?:H(\d*))?(?:(\+|-)(\d*))?$/.exec(inside);
+			if (!match) throw new Error(`"${smiles}": cannot read the bracket atom "[${inside}]". Write it as [element], [elementH count] or [elementH count charge], for example [NH4+] or [O-].`);
+			const symbol = match[1];
+			const aromatic = symbol[0] === symbol[0].toLowerCase() && symbol.length === 1;
+			const element = aromatic ? symbol.toUpperCase() : symbol;
+			if (!(element in VALENCE)) throw new Error(`"${smiles}": "${element}" is not an element this parser knows.`);
+			const explicitHydrogens = match[2] === void 0 ? 0 : match[2] === "" ? 1 : Number(match[2]);
+			const size = match[4] ? Number(match[4]) : 1;
+			const charge = match[3] === void 0 ? 0 : match[3] === "-" ? -size : size;
+			addAtom(element, aromatic, {
+				explicitHydrogens,
+				...charge === 0 ? {} : { charge }
+			});
+			i = close + 1;
+			continue;
+		}
+		if (ch === "(") {
+			if (previous === void 0) throw new Error(`"${smiles}": a branch cannot open the string.`);
+			branchStack.push(previous);
+			i += 1;
+			continue;
+		}
+		if (ch === ")") {
+			const back = branchStack.pop();
+			if (back === void 0) throw new Error(`"${smiles}": a branch was closed that never opened.`);
+			previous = back;
+			i += 1;
+			continue;
+		}
+		if (ch === "-" || ch === "=" || ch === "#" || ch === ":") {
+			pendingOrder = ch === "=" ? 2 : ch === "#" ? 3 : 1;
+			pendingAromatic = ch === ":";
+			i += 1;
+			continue;
+		}
+		if (ch >= "1" && ch <= "9") {
+			if (previous === void 0) throw new Error(`"${smiles}": a ring closure needs an atom first.`);
+			const open = ringOpen.get(ch);
+			if (open) {
+				ringOpen.delete(ch);
+				const order = pendingOrder ?? open.order;
+				const arom = pendingAromatic || open.aromatic || atoms[open.atom].aromatic && atoms[previous].aromatic;
+				bonds.push({
+					a: open.atom,
+					b: previous,
+					order,
+					aromatic: arom
+				});
+			} else ringOpen.set(ch, {
+				atom: previous,
+				order: pendingOrder ?? 1,
+				aromatic: pendingAromatic
+			});
+			pendingOrder = void 0;
+			pendingAromatic = false;
+			i += 1;
+			continue;
+		}
+		const two = smiles.slice(i, i + 2);
+		if (TWO_LETTER.has(two)) {
+			addAtom(two, false);
+			i += 2;
+			continue;
+		}
+		const upper = ch.toUpperCase();
+		if (upper in VALENCE) {
+			addAtom(upper, ch === ch.toLowerCase() && ch !== ch.toUpperCase());
+			i += 1;
+			continue;
+		}
+		throw new Error(`"${smiles}": "${ch}" is outside the SMILES subset this kernel parses.`);
+	}
+	if (branchStack.length) throw new Error(`"${smiles}": a branch was opened and never closed.`);
+	if (ringOpen.size) throw new Error(`"${smiles}": a ring was opened and never closed.`);
+	return {
+		atoms,
+		bonds
+	};
+}
+/** Bonds touching an atom. */
+const bondsAt = (structure, id) => structure.bonds.filter((b) => b.a === id || b.b === id);
+/** The atom on the other end of a bond. */
+const otherEnd = (bond, id) => bond.a === id ? bond.b : bond.a;
+/** Atoms directly bonded to this one, excluding any explicit hydrogens. */
+const neighbours = (structure, id) => bondsAt(structure, id).map((b) => structure.atoms[otherEnd(b, id)]);
+/** How many bonds an atom has used, counting an aromatic bond as one and a half. */
+const bondOrderSum = (structure, id) => bondsAt(structure, id).reduce((n, b) => n + (b.aromatic ? 1.5 : b.order), 0);
+/**
+* Hydrogens on an atom, from what its valence has left over.
+*
+* Never declared, which is what stops a structure disagreeing with its own formula. An aromatic
+* carbon in benzene has two aromatic bonds worth 1.5 each, leaving one hydrogen, which is right.
+*/
+/**
+* Bonds an atom can make, once its charge is taken into account.
+*
+* The two directions are not symmetrical, and the reason is what the charge did to the electrons.
+*
+* An atom with a lone pair to spare, nitrogen or oxygen or sulfur, makes an EXTRA bond when it
+* loses an electron, because the lone pair becomes a bonding pair: ammonium's nitrogen makes four
+* bonds, not three. Gaining one costs it a bond instead, which is why a carboxylate oxygen makes
+* only one.
+*
+* Carbon has no lone pair to donate, so it loses a bond whichever way it is charged. A carbocation
+* and a carbanion both make three.
+*/
+function chargedValence(element, charge = 0) {
+	const base = VALENCE[element];
+	if (charge === 0) return base;
+	if (element === "C") return base - Math.abs(charge);
+	return base + charge;
+}
+function implicitHydrogens(structure, id) {
+	const atom = structure.atoms[id];
+	if (!atom) throw new Error(`No atom ${id} in this structure.`);
+	if (atom.element === "H") return 0;
+	if (atom.explicitHydrogens !== void 0) return atom.explicitHydrogens;
+	const used = bondOrderSum(structure, id) + (atom.openValence ?? 0);
+	const valence = chargedValence(atom.element, atom.charge);
+	const left = valence - used;
+	if (left < -.01) throw new Error(`Atom ${id} (${atom.element}${atom.charge ? atom.charge > 0 ? "+" : "-" : ""}) has ${used} bonds but a valence of ${valence}.`);
+	return Math.max(0, Math.round(left));
+}
+/** Total formal charge on a structure: the charge of the ion it represents. */
+const totalCharge = (structure) => structure.atoms.reduce((sum, atom) => sum + (atom.charge ?? 0), 0);
+/** Every element in the structure, counted, hydrogens included. */
+function atomCounts(structure) {
+	const counts = {};
+	for (const atom of structure.atoms) {
+		counts[atom.element] = (counts[atom.element] ?? 0) + 1;
+		const h = implicitHydrogens(structure, atom.id);
+		if (h > 0) counts.H = (counts.H ?? 0) + h;
+	}
+	return counts;
+}
+/**
+* The molecular formula, in Hill order: carbon, then hydrogen, then everything else alphabetically.
+*
+* Hill order is what a database and a mark scheme both use, so C2H6O and never H6C2O or OC2H6.
+*/
+function formatCounts(counts) {
+	const rest = Object.keys(counts).filter((e) => e !== "C" && e !== "H" && counts[e] > 0).sort();
+	return [
+		...counts.C ? ["C"] : [],
+		...counts.H ? ["H"] : [],
+		...rest
+	].map((e) => `${e}${counts[e] > 1 ? counts[e] : ""}`).join("");
+}
+function molecularFormula(structure) {
+	return formatCounts(atomCounts(structure));
+}
+/** Relative molecular mass, from the same counts. */
+const relativeMass = (structure) => {
+	const counts = atomCounts(structure);
+	const total = Object.entries(counts).reduce((sum, [element, n]) => sum + ATOMIC_MASS[element] * n, 0);
+	return Math.round(total * 10) / 10;
+};
+/**
+* Degrees of unsaturation: how many rings plus double-bond equivalents the formula demands.
+*
+* Worth computing because it is the first thing to do with a molecular formula in a structure
+* determination, and because it is the check that catches a proposed structure that cannot exist:
+* a formula with zero degrees cannot contain a C=O however well the rest of the evidence fits.
+*
+* Oxygen does not enter the count, which surprises people every time, and the reason is that adding
+* an oxygen into a chain uses two bonds and supplies two.
+*/
+function degreesOfUnsaturation(structure) {
+	const c = atomCounts(structure);
+	const carbon = c.C ?? 0;
+	const hydrogen = c.H ?? 0;
+	const nitrogen = c.N ?? 0;
+	const halogen = (c.F ?? 0) + (c.Cl ?? 0) + (c.Br ?? 0) + (c.I ?? 0);
+	return (2 * carbon + 2 + nitrogen - hydrogen - halogen) / 2;
+}
+/** Atoms in the structure that are carbon. */
+const carbonCount = (structure) => structure.atoms.filter((a) => a.element === "C").length;
+/**
+* Rings, by the cycle rank of the graph: bonds minus atoms plus connected pieces.
+*
+* Counts independent rings rather than every closed loop, which is the number a chemist means by
+* "how many rings", and naphthalene comes out as two rather than three.
+*/
+function ringCount(structure) {
+	const seen = /* @__PURE__ */ new Set();
+	let pieces = 0;
+	for (const atom of structure.atoms) {
+		if (seen.has(atom.id)) continue;
+		pieces += 1;
+		const stack = [atom.id];
+		seen.add(atom.id);
+		while (stack.length) {
+			const at = stack.pop();
+			for (const b of bondsAt(structure, at)) {
+				const next = otherEnd(b, at);
+				if (!seen.has(next)) {
+					seen.add(next);
+					stack.push(next);
+				}
+			}
+		}
+	}
+	return structure.bonds.length - structure.atoms.length + pieces;
+}
+
+//#endregion
+export { ATOMIC_MASS, atomCounts, bondOrderSum, bondsAt, carbonCount, chargedValence, degreesOfUnsaturation, formatCounts, implicitHydrogens, molecularFormula, neighbours, otherEnd, parseSmiles, relativeMass, ringCount, totalCharge };

package/dist/chem/nmr.d.mts

@@ -0,0 +1,153 @@
+//#region src/chem/nmr.d.ts
+/**
+ * nmr, a proton spectrum predicted from the environments in a molecule.
+ *
+ * WHAT THIS IS FOR. An NMR question is four questions wearing one coat, and a learner who has been
+ * shown a finished spectrum cannot take it apart again:
+ *
+ *   how many signals?        one per proton ENVIRONMENT
+ *   where is each one?       its chemical shift, from what the protons are attached to
+ *   how tall is each one?    the integration, in proportion to the number of protons
+ *   how many lines in it?    n + 1, where n counts the protons on the neighbouring carbons
+ *
+ * All four are computed here from the same declaration, so a lesson can change one environment and
+ * watch the right things move. A spectrum drawn by hand can only assert the answer.
+ *
+ * ## Why the environments are declared and not derived
+ *
+ * Working out which protons are equivalent means perceiving the symmetry of a structure, which is a
+ * real problem and not a 9701 one. What IS 9701, and what is done here, is everything that follows
+ * once the environments are known. Declaring them is also how a question is actually set: "the three
+ * environments in ethanol" is the given, and the spectrum is the answer.
+ *
+ * The one thing a declaration must not do is let the two halves disagree, so {@link predictNmr}
+ * refuses a molecule whose neighbour counts are impossible for the environments it lists.
+ *
+ * ## Splitting is Pascal's triangle, and that is worth computing
+ *
+ * n + 1 gives the number of lines. Their relative heights are the binomial coefficients, so a
+ * quartet is 1:3:3:1 and not four equal lines. Drawing four equal lines is the commonest way a
+ * textbook figure is wrong, and it is wrong in a way that matters: the outer lines of a large
+ * multiplet vanish into the baseline, which is why a septet is often reported as a quintet.
+ *
+ * Pure: no React, no pixels.
+ */
+/** Where a proton environment absorbs, from the ranges a data booklet prints. */
+interface ShiftRange {
+  readonly from: number;
+  readonly to: number;
+  /** What the protons are attached to, as the booklet describes it. */
+  readonly environment: string;
+}
+/**
+ * Chemical shift ranges, in ppm, as the 9701 data booklet gives them.
+ *
+ * Ranges, never single values, because that is what the booklet prints and because a learner who
+ * memorises "2.2" for a ketone cannot place a shift of 2.4. The question is always which RANGE a
+ * peak falls in.
+ */
+declare const SHIFT_RANGES: Readonly<Record<string, ShiftRange>>;
+type ShiftKey = keyof typeof SHIFT_RANGES;
+/** One set of protons that the machine cannot tell apart. */
+interface ProtonEnvironment {
+  /** What a learner would point at, e.g. 'the CH3 of the ethyl group'. */
+  readonly label: string;
+  /** How many protons are in this environment. Sets the integration. */
+  readonly protons: number;
+  /** Protons on the ADJACENT carbons. Sets the splitting, through n + 1. */
+  readonly neighbours: number;
+  /** Which range of the data booklet this environment falls in. */
+  readonly shift: ShiftKey;
+  /**
+   * Where in that range the peak actually sits, in ppm.
+   *
+   * Given rather than guessed, because a range is what the booklet prints and a spectrum needs a
+   * position. {@link predictNmr} refuses a value outside its own declared range.
+   */
+  readonly ppm: number;
+  /**
+   * Does this proton exchange with D2O?
+   *
+   * The O-H and N-H protons do, which is the whole point of the D2O experiment: the peak vanishes.
+   * It is also why they are not split and do not split their neighbours.
+   */
+  readonly exchangeable?: boolean;
+}
+interface NmrMolecule {
+  readonly name: string;
+  readonly formula: string;
+  readonly environments: readonly ProtonEnvironment[];
+}
+/** The name for a number of lines. Beyond five, a spectrum is reported as a multiplet. */
+declare const MULTIPLICITY_NAMES: readonly ["singlet", "doublet", "triplet", "quartet", "quintet", "sextet", "septet"];
+type Multiplicity = (typeof MULTIPLICITY_NAMES)[number] | 'multiplet';
+/**
+ * The n + 1 rule.
+ *
+ * An exchangeable proton is always a singlet and never splits anything, because it swaps between
+ * molecules faster than the machine can see it.
+ */
+declare function multiplicityOf(neighbours: number, exchangeable?: boolean): Multiplicity;
+/**
+ * Relative heights of the lines in a multiplet: a row of Pascal's triangle.
+ *
+ * A quartet is 1:3:3:1, not four equal lines. It matters because the outer lines of a large
+ * multiplet sink into the baseline, which is why a septet is so often reported as a quintet.
+ */
+declare function splittingPattern(lines: number): number[];
+/**
+ * Integration as the smallest whole-number ratio.
+ *
+ * A spectrum reports 2:3, not 4:6, because the integration gives the RATIO of protons and never
+ * their number. That distinction is the one an exam question turns on: a 2:3 ratio fits both
+ * C2H5-OH and C4H10O2, and the molecular formula is what settles it.
+ */
+declare function integrationRatio(environments: readonly ProtonEnvironment[]): number[];
+/** One signal in the predicted spectrum. */
+interface NmrPeak {
+  readonly label: string;
+  readonly ppm: number;
+  readonly protons: number;
+  /** This peak's share of the total integration, as a whole number. */
+  readonly integration: number;
+  readonly multiplicity: Multiplicity;
+  /** Number of lines, which is n + 1. */
+  readonly lines: number;
+  /** Relative height of each line, from Pascal's triangle. */
+  readonly pattern: readonly number[];
+  readonly range: ShiftRange;
+  readonly exchangeable: boolean;
+}
+interface NmrSpectrum {
+  readonly molecule: NmrMolecule;
+  /** Downfield first, which is how a spectrum is printed: high ppm on the left. */
+  readonly peaks: readonly NmrPeak[];
+  /** Total protons, which must match the molecular formula. */
+  readonly totalProtons: number;
+}
+/**
+ * Predict the spectrum.
+ *
+ * Refuses a declaration that contradicts itself rather than drawing a spectrum nobody could have
+ * measured: a peak outside the range it claims, or an exchangeable proton given neighbours to
+ * couple to. Both are ways a hand-authored figure goes quietly wrong.
+ */
+declare function predictNmr(molecule: NmrMolecule): NmrSpectrum;
+/**
+ * The spectrum after a drop of D2O, with every exchangeable peak gone.
+ *
+ * The experiment exists to answer one question: is that broad singlet an O-H? Running it is how a
+ * learner tells an alcohol from an ether without any other evidence, and doing it as a computation
+ * rather than a second hand-drawn figure means the two spectra cannot disagree.
+ */
+declare const afterD2O: (spectrum: NmrSpectrum) => NmrSpectrum;
+/**
+ * The line positions of one peak, in ppm, given the coupling constant.
+ *
+ * `J` is in hertz and a spectrum is in ppm, so the conversion needs the spectrometer frequency.
+ * That is not a detail to hide: it is why the same molecule gives the same splitting PATTERN on
+ * every machine while the lines sit closer together on a stronger one.
+ */
+declare function linePositions(peak: NmrPeak, jHz?: number, spectrometerMHz?: number): number[];
+//#endregion
+export { MULTIPLICITY_NAMES, Multiplicity, NmrMolecule, NmrPeak, NmrSpectrum, ProtonEnvironment, SHIFT_RANGES, ShiftKey, ShiftRange, afterD2O, integrationRatio, linePositions, multiplicityOf, predictNmr, splittingPattern };

package/dist/chem/nmr.mjs

@@ -0,0 +1,165 @@
+//#region src/chem/nmr.ts
+/**
+* Chemical shift ranges, in ppm, as the 9701 data booklet gives them.
+*
+* Ranges, never single values, because that is what the booklet prints and because a learner who
+* memorises "2.2" for a ketone cannot place a shift of 2.4. The question is always which RANGE a
+* peak falls in.
+*/
+const SHIFT_RANGES = {
+	alkane: {
+		from: .9,
+		to: 1.7,
+		environment: "R-CH3, R-CH2-R, R3CH"
+	},
+	"alkyl-next-to-carbonyl": {
+		from: 2,
+		to: 2.9,
+		environment: "CH3-CO-, -CH2-CO-"
+	},
+	"alkyl-next-to-halogen": {
+		from: 3.2,
+		to: 4,
+		environment: "R-CH2-Cl or R-CH2-Br"
+	},
+	"alkyl-next-to-oxygen": {
+		from: 3.3,
+		to: 4.3,
+		environment: "R-CH2-O-"
+	},
+	alcohol: {
+		from: .5,
+		to: 6,
+		environment: "R-O-H"
+	},
+	amine: {
+		from: 1,
+		to: 5,
+		environment: "R-N-H"
+	},
+	alkene: {
+		from: 4.5,
+		to: 6,
+		environment: "R2C=CH2"
+	},
+	arene: {
+		from: 6,
+		to: 9,
+		environment: "aromatic H"
+	},
+	aldehyde: {
+		from: 9.3,
+		to: 10.5,
+		environment: "R-CHO"
+	},
+	"carboxylic-acid": {
+		from: 9,
+		to: 13,
+		environment: "R-COOH"
+	}
+};
+/** The name for a number of lines. Beyond five, a spectrum is reported as a multiplet. */
+const MULTIPLICITY_NAMES = [
+	"singlet",
+	"doublet",
+	"triplet",
+	"quartet",
+	"quintet",
+	"sextet",
+	"septet"
+];
+/**
+* The n + 1 rule.
+*
+* An exchangeable proton is always a singlet and never splits anything, because it swaps between
+* molecules faster than the machine can see it.
+*/
+function multiplicityOf(neighbours, exchangeable = false) {
+	if (exchangeable) return "singlet";
+	return MULTIPLICITY_NAMES[neighbours + 1 - 1] ?? "multiplet";
+}
+/**
+* Relative heights of the lines in a multiplet: a row of Pascal's triangle.
+*
+* A quartet is 1:3:3:1, not four equal lines. It matters because the outer lines of a large
+* multiplet sink into the baseline, which is why a septet is so often reported as a quintet.
+*/
+function splittingPattern(lines) {
+	const row = [1];
+	for (let i = 1; i < lines; i += 1) row.push(row[i - 1] * (lines - i) / i);
+	return row;
+}
+const gcd = (a, b) => b === 0 ? a : gcd(b, a % b);
+/**
+* Integration as the smallest whole-number ratio.
+*
+* A spectrum reports 2:3, not 4:6, because the integration gives the RATIO of protons and never
+* their number. That distinction is the one an exam question turns on: a 2:3 ratio fits both
+* C2H5-OH and C4H10O2, and the molecular formula is what settles it.
+*/
+function integrationRatio(environments) {
+	const counts = environments.map((e) => e.protons);
+	if (counts.length === 0) return [];
+	const divisor = counts.reduce((a, b) => gcd(a, b));
+	return counts.map((n) => n / divisor);
+}
+/**
+* Predict the spectrum.
+*
+* Refuses a declaration that contradicts itself rather than drawing a spectrum nobody could have
+* measured: a peak outside the range it claims, or an exchangeable proton given neighbours to
+* couple to. Both are ways a hand-authored figure goes quietly wrong.
+*/
+function predictNmr(molecule) {
+	const ratio = integrationRatio(molecule.environments);
+	return {
+		molecule,
+		peaks: [...molecule.environments.map((env, i) => {
+			const range = SHIFT_RANGES[env.shift];
+			if (!range) throw new Error(`${env.label}: "${env.shift}" is not a shift range in the booklet.`);
+			if (env.ppm < range.from || env.ppm > range.to) throw new Error(`${env.label}: ${env.ppm} ppm is outside the ${range.from} to ${range.to} range for ${env.shift}.`);
+			if (env.exchangeable && env.neighbours > 0) throw new Error(`${env.label}: an exchangeable proton cannot be coupled, so it must have 0 neighbours.`);
+			const multiplicity = multiplicityOf(env.neighbours, env.exchangeable);
+			const lines = env.exchangeable ? 1 : env.neighbours + 1;
+			return {
+				label: env.label,
+				ppm: env.ppm,
+				protons: env.protons,
+				integration: ratio[i],
+				multiplicity,
+				lines,
+				pattern: splittingPattern(lines),
+				range,
+				exchangeable: env.exchangeable === true
+			};
+		})].sort((a, b) => b.ppm - a.ppm),
+		totalProtons: molecule.environments.reduce((n, e) => n + e.protons, 0)
+	};
+}
+/**
+* The spectrum after a drop of D2O, with every exchangeable peak gone.
+*
+* The experiment exists to answer one question: is that broad singlet an O-H? Running it is how a
+* learner tells an alcohol from an ether without any other evidence, and doing it as a computation
+* rather than a second hand-drawn figure means the two spectra cannot disagree.
+*/
+const afterD2O = (spectrum) => ({
+	...spectrum,
+	peaks: spectrum.peaks.filter((p) => !p.exchangeable),
+	totalProtons: spectrum.peaks.filter((p) => !p.exchangeable).reduce((n, p) => n + p.protons, 0)
+});
+/**
+* The line positions of one peak, in ppm, given the coupling constant.
+*
+* `J` is in hertz and a spectrum is in ppm, so the conversion needs the spectrometer frequency.
+* That is not a detail to hide: it is why the same molecule gives the same splitting PATTERN on
+* every machine while the lines sit closer together on a stronger one.
+*/
+function linePositions(peak, jHz = 7, spectrometerMHz = 100) {
+	const spacing = jHz / spectrometerMHz;
+	const first = peak.ppm - spacing * (peak.lines - 1) / 2;
+	return Array.from({ length: peak.lines }, (_, i) => first + i * spacing);
+}
+
+//#endregion
+export { MULTIPLICITY_NAMES, SHIFT_RANGES, afterD2O, integrationRatio, linePositions, multiplicityOf, predictNmr, splittingPattern };

package/dist/chem/polymer.d.mts

@@ -0,0 +1,65 @@
+import { Structure } from "./molecule.mjs";
+
+//#region src/chem/polymer.d.ts
+type PolymerKind = 'addition' | 'condensation';
+/** What the two link points are: an ester link, an amide link, or a plain carbon-carbon bond. */
+type LinkKind = 'carbon-carbon' | 'ester' | 'amide';
+interface RepeatUnit {
+  readonly kind: PolymerKind;
+  readonly link: LinkKind;
+  /** The unit itself, with the two atoms that bond onto the neighbouring units. */
+  readonly structure: Structure;
+  /** Atom ids in `structure` that join to the previous and the next unit. */
+  readonly linkAtoms: readonly [number, number];
+  /** The molecular formula of one repeat unit. */
+  readonly formula: string;
+  readonly mass: number;
+  /** The small molecule lost per link, for a condensation. `undefined` for addition. */
+  readonly lost?: {
+    readonly formula: string;
+    readonly mass: number;
+  };
+  /** Why this monomer or pair polymerises the way it does, in the words a mark scheme uses. */
+  readonly reason: string;
+}
+/**
+ * Open the double bond of an alkene to give the addition repeat unit.
+ *
+ * Refuses a monomer with no C=C, because "it must be addition" is a guess a learner makes and a
+ * kernel should not. The formula is unchanged by construction, and the test asserts it.
+ */
+declare function addition(monomer: Structure): RepeatUnit;
+/**
+ * Can this monomer sustain a chain?
+ *
+ * Two reactive groups, or the chain stops after one join. Ethanoic acid has one and is therefore a
+ * dead end; hexanedioic acid has two and is not. This is the check most treatments leave out and
+ * the reason a learner cannot predict whether a new monomer will polymerise.
+ */
+declare const canSustainChain: (monomer: Structure) => boolean;
+/**
+ * Join two monomers and eliminate water, giving the condensation repeat unit.
+ *
+ * The pairing is decided by the groups that are actually present, not by an argument the caller
+ * passes: an acid with an alcohol gives an ester link and an acid with an amine gives an amide link,
+ * and those are the only two the syllabus needs. A pair that cannot make either is refused with the
+ * reason, because "nothing happened" is not a useful answer to a learner.
+ */
+declare function condensation(first: Structure, second: Structure): RepeatUnit;
+/**
+ * The mass of a chain of `n` repeat units.
+ *
+ * For an addition polymer it is n times the monomer. For a condensation polymer the water has
+ * already gone from the repeat unit, so the same multiplication works, and the difference between
+ * the two shows up as a mass that is not a whole multiple of the monomers.
+ */
+declare const chainMass: (unit: RepeatUnit, n: number) => number;
+/**
+ * How many repeat units a chain of this mass holds, to the nearest whole unit.
+ *
+ * The question an exam asks the other way round: a poly(ethene) sample with a relative molecular
+ * mass of 28 000 contains 1000 repeat units, and that number is what "long chain" means.
+ */
+declare const unitsInChain: (unit: RepeatUnit, chainMr: number) => number;
+//#endregion
+export { LinkKind, PolymerKind, RepeatUnit, addition, canSustainChain, chainMass, condensation, unitsInChain };