@classytic/stage 0.2.0 → 0.4.0

package/dist/chem/molecule.d.mts

@@ -0,0 +1,154 @@
+//#region src/chem/molecule.d.ts
+/**
+ * molecule, a structure as a graph, so the rest can be worked out rather than declared.
+ *
+ * WHAT THIS IS FOR. Every chemistry lab and lesson we have declares its molecules as DRAWINGS: a
+ * chain of vertices with positions, a formula typed in as a string, a functional group named as a
+ * list of vertex indices. Nothing about that can be checked. A formula string can disagree with the
+ * structure beside it, a group can be named that the structure does not contain, and an isomer list
+ * is only as complete as whoever typed it.
+ *
+ * A graph fixes all of it at once. Declare the heavy atoms and the bonds, and the molecular formula,
+ * the relative molecular mass, the degrees of unsaturation, the functional groups and the polymer
+ * repeat unit all follow by computation.
+ *
+ * ## Hydrogens are implicit, and that is the point
+ *
+ * An author declares carbon, oxygen and nitrogen and never hydrogen, exactly as a skeletal formula
+ * is drawn. The hydrogen count comes from valence: four bonds to a carbon, three to a nitrogen, two
+ * to an oxygen, one to a halogen. So a structure cannot be declared with a hydrogen count that
+ * contradicts its own bonds, because the count is not declared at all.
+ *
+ * ## Why SMILES
+ *
+ * Because it is the notation the whole of chemistry already uses, so `CCO` is ethanol here and in
+ * every database a learner will ever meet, and because a molecule written as one short string is a
+ * molecule an author will actually declare correctly. The subset parsed here is the one A level
+ * needs: the organic elements, single, double, triple and aromatic bonds, branches, and ring
+ * closures.
+ *
+ * What is deliberately NOT here: stereochemistry, charges, isotopes and explicit bracket atoms.
+ * Those belong in the topics that use them, and a parser that accepted them without the rest of the
+ * kernel understanding them would be a promise it could not keep.
+ *
+ * Pure: no React, no pixels.
+ */
+/** The elements A level organic chemistry uses. */
+type Element = 'C' | 'N' | 'O' | 'S' | 'P' | 'F' | 'Cl' | 'Br' | 'I' | 'H';
+/** Relative atomic masses, to the precision a data booklet prints. */
+declare const ATOMIC_MASS: Readonly<Record<Element, number>>;
+interface Atom {
+  readonly id: number;
+  readonly element: Element;
+  /** Part of an aromatic ring, written lowercase in SMILES. */
+  readonly aromatic: boolean;
+  /**
+   * Bonds this atom makes to something OUTSIDE the structure, so they take no hydrogen.
+   *
+   * An attachment point. A polymer repeat unit has two, one to the unit on each side, and without
+   * them the repeat unit of poly(ethene) comes out as C2H6: opening the double bond frees a bond on
+   * each carbon, and if nothing claims it a hydrogen does. The unit is CH2-CH2, not ethane.
+   */
+  readonly openValence?: number;
+  /**
+   * Formal charge on this atom: +1 on the nitrogen of an ammonium ion, -1 on a carboxylate oxygen.
+   *
+   * It changes how many bonds the atom makes, which is the reason it has to live on the graph
+   * rather than being noted alongside it. A nitrogen makes three bonds and an ammonium nitrogen
+   * makes four, and a kernel that did not know the charge would report ammonium as NH3 with a
+   * spare bond it could not explain.
+   */
+  readonly charge?: number;
+  /**
+   * Hydrogens stated outright rather than worked out from the valence.
+   *
+   * Set only by a bracket atom, where SMILES requires the count to be written. Everywhere else the
+   * count is computed, which is what stops a structure disagreeing with its own bonds.
+   */
+  readonly explicitHydrogens?: number;
+}
+interface Bond {
+  readonly a: number;
+  readonly b: number;
+  readonly order: 1 | 2 | 3;
+  /** An aromatic bond counts as one and a half when valence is totted up. */
+  readonly aromatic: boolean;
+}
+interface Structure {
+  readonly atoms: readonly Atom[];
+  readonly bonds: readonly Bond[];
+}
+/**
+ * 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.
+ */
+declare function parseSmiles(smiles: string): Structure;
+/** Bonds touching an atom. */
+declare const bondsAt: (structure: Structure, id: number) => Bond[];
+/** The atom on the other end of a bond. */
+declare const otherEnd: (bond: Bond, id: number) => number;
+/** Atoms directly bonded to this one, excluding any explicit hydrogens. */
+declare const neighbours: (structure: Structure, id: number) => Atom[];
+/** How many bonds an atom has used, counting an aromatic bond as one and a half. */
+declare const bondOrderSum: (structure: Structure, id: number) => number;
+/**
+ * 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.
+ */
+declare function chargedValence(element: Element, charge?: number): number;
+declare function implicitHydrogens(structure: Structure, id: number): number;
+/** Total formal charge on a structure: the charge of the ion it represents. */
+declare const totalCharge: (structure: Structure) => number;
+/** Every element in the structure, counted, hydrogens included. */
+declare function atomCounts(structure: Structure): Record<string, number>;
+/**
+ * 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.
+ */
+declare function formatCounts(counts: Readonly<Record<string, number>>): string;
+declare function molecularFormula(structure: Structure): string;
+/** Relative molecular mass, from the same counts. */
+declare const relativeMass: (structure: Structure) => number;
+/**
+ * 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.
+ */
+declare function degreesOfUnsaturation(structure: Structure): number;
+/** Atoms in the structure that are carbon. */
+declare const carbonCount: (structure: Structure) => number;
+/**
+ * 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.
+ */
+declare function ringCount(structure: Structure): number;
+//#endregion
+export { ATOMIC_MASS, Atom, Bond, Element, Structure, atomCounts, bondOrderSum, bondsAt, carbonCount, chargedValence, degreesOfUnsaturation, formatCounts, implicitHydrogens, molecularFormula, neighbours, otherEnd, parseSmiles, relativeMass, ringCount, totalCharge };

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