@classytic/stage 0.2.0 → 0.4.0

package/dist/chem/equation.mjs

@@ -0,0 +1,168 @@
+import { readFormula } from "./species.mjs";
+
+//#region src/chem/equation.ts
+/**
+* Strip a trailing state symbol.
+*
+* `(aq)` looks exactly like a bracketed group to the formula reader, which would take the a and the
+* q for elements. It has to come off before the formula is read, and only from the END, because
+* `Fe(OH)3` has a bracketed group in the middle that must survive.
+*/
+const STATE_SYMBOL = /\((?:g|l|s|aq)\)\s*$/i;
+const withoutState = (species) => species.replace(STATE_SYMBOL, "").trim();
+const gcd = (a, b) => b === 0 ? Math.abs(a) : gcd(b, a % b);
+function fraction(n, d = 1) {
+	if (d === 0) throw new Error("a fraction cannot have a denominator of zero");
+	const sign = d < 0 ? -1 : 1;
+	const divisor = gcd(n, d) || 1;
+	return {
+		n: sign * n / divisor,
+		d: sign * d / divisor
+	};
+}
+const sub = (a, b) => fraction(a.n * b.d - b.n * a.d, a.d * b.d);
+const mul = (a, b) => fraction(a.n * b.n, a.d * b.d);
+const div = (a, b) => {
+	if (b.n === 0) throw new Error("cannot divide by zero while balancing");
+	return fraction(a.n * b.d, a.d * b.n);
+};
+const isZero = (f) => f.n === 0;
+const ZERO = {
+	n: 0,
+	d: 1
+};
+const ONE = {
+	n: 1,
+	d: 1
+};
+/** Split "a + b -> c + d" into its two sides, accepting the arrows people actually type. */
+function splitEquation(input) {
+	const parts = input.split(/->|=>|→|⟶|=/);
+	if (parts.length !== 2) throw new Error(`"${input}" is not an equation: it needs exactly one arrow, written as -> or = or →`);
+	const side = (text) => text.split(/\s+\+\s+/).map((s) => s.trim()).map((s) => s.replace(/^\d+(?=[A-Z([])/, "")).filter((s) => s !== "");
+	const left = side(parts[0]);
+	const right = side(parts[1]);
+	if (left.length === 0 || right.length === 0) throw new Error(`"${input}" has nothing on one side of the arrow`);
+	return {
+		left,
+		right
+	};
+}
+/**
+* Balance an equation, returning the smallest whole-number coefficients.
+*
+* `balance('Fe3O4 + CO -> Fe + CO2')`, `balance('C3H8 + O2 -> CO2 + H2O')`.
+*
+* Coefficients already written into the input are ignored: the whole point is to compute them, and
+* accepting them would let a wrong one through unchallenged.
+*/
+function balance(input) {
+	const { left, right } = splitEquation(input);
+	const species = [...left, ...right];
+	const read = species.map((formula) => readFormula(withoutState(formula)));
+	const compositions = read.map((r) => r.counts);
+	const elements = [...new Set(compositions.flatMap((c) => c.map((e) => e.element)))];
+	/** Reactants count positive and products negative, so a balance sums to zero. */
+	const signed = (column, value) => fraction(column < left.length ? value : -value);
+	const rows = elements.map((element) => compositions.map((composition, column) => signed(column, composition.find((e) => e.element === element)?.count ?? 0)));
+	if (read.some((r) => r.charge !== 0)) rows.push(read.map((r, column) => signed(column, r.charge)));
+	const whole = clearFractions(nullSpaceVector(rows, species.length, input));
+	if (whole.some((value) => value <= 0)) throw new Error(`${input} cannot be balanced as written: the only solution needs a coefficient of zero or below, which usually means a species is on the wrong side or one is missing`);
+	return {
+		reactants: left.map((formula, i) => ({
+			formula,
+			coefficient: whole[i]
+		})),
+		products: right.map((formula, i) => ({
+			formula,
+			coefficient: whole[left.length + i]
+		})),
+		elements
+	};
+}
+/**
+* The one direction the element matrix sends to zero.
+*
+* Gaussian elimination to reduced row echelon form, then the single free column is set to one and
+* the others read off. More than one free column means the equation has more than one independent
+* balance, which is refused with that as the reason rather than by picking one of them.
+*/
+function nullSpaceVector(rows, columns, input) {
+	const matrix = rows.map((row) => [...row]);
+	const pivotOf = [];
+	let pivotRow = 0;
+	for (let column = 0; column < columns && pivotRow < matrix.length; column += 1) {
+		const found = matrix.findIndex((row, i) => i >= pivotRow && !isZero(row[column]));
+		if (found === -1) continue;
+		[matrix[pivotRow], matrix[found]] = [matrix[found], matrix[pivotRow]];
+		const pivot = matrix[pivotRow][column];
+		matrix[pivotRow] = matrix[pivotRow].map((value) => div(value, pivot));
+		for (let r = 0; r < matrix.length; r += 1) {
+			if (r === pivotRow || isZero(matrix[r][column])) continue;
+			const factor = matrix[r][column];
+			matrix[r] = matrix[r].map((value, c) => sub(value, mul(factor, matrix[pivotRow][c])));
+		}
+		pivotOf.push(column);
+		pivotRow += 1;
+	}
+	const free = [...Array(columns).keys()].filter((c) => !pivotOf.includes(c));
+	if (free.length === 0) throw new Error(`${input} cannot be balanced: no set of coefficients conserves every element, so a species is missing or a formula is wrong`);
+	if (free.length > 1) throw new Error(`${input} can be balanced in more than one independent way, which means it describes more than one reaction. Split it into separate equations.`);
+	const solution = Array(columns).fill(ZERO);
+	solution[free[0]] = ONE;
+	pivotOf.forEach((column, row) => {
+		solution[column] = mul(matrix[row][free[0]], {
+			n: -1,
+			d: 1
+		});
+	});
+	return solution;
+}
+/** Scale a set of fractions to the smallest whole numbers with the same ratios. */
+function clearFractions(values) {
+	const lcm = (a, b) => Math.abs(a * b) / (gcd(a, b) || 1);
+	const denominator = values.reduce((total, f) => lcm(total, f.d), 1);
+	const scaled = values.map((f) => f.n * denominator / f.d);
+	const divisor = scaled.reduce((total, v) => gcd(total, v), 0) || 1;
+	return scaled.map((v) => v / divisor);
+}
+/** Write a balanced equation out, leaving a coefficient of one unwritten. */
+function formatEquation(equation, arrow = "->") {
+	const side = (terms) => terms.map((t) => `${t.coefficient === 1 ? "" : t.coefficient}${t.formula}`).join(" + ");
+	return `${side(equation.reactants)} ${arrow} ${side(equation.products)}`;
+}
+/**
+* How many atoms of each element sit on each side.
+*
+* For showing the check rather than doing it: the balance is exact by construction, and a learner
+* still has to see both columns match before they believe it.
+*/
+function atomTally(equation) {
+	const count = (terms, element) => terms.reduce((total, term) => {
+		const composition = readFormula(withoutState(term.formula)).counts;
+		return total + term.coefficient * (composition.find((e) => e.element === element)?.count ?? 0);
+	}, 0);
+	return equation.elements.map((element) => ({
+		element,
+		left: count(equation.reactants, element),
+		right: count(equation.products, element)
+	}));
+}
+/**
+* Total charge on each side.
+*
+* Separate from the atom tally because it is a different conservation law, and because showing it
+* beside the atoms is what makes an ionic equation make sense: the two sides of a precipitation
+* carry the same charge as well as the same atoms, and a learner who only counts atoms will balance
+* it wrongly and never see why.
+*/
+function chargeTally(equation) {
+	const total = (terms) => terms.reduce((sum, term) => sum + term.coefficient * readFormula(withoutState(term.formula)).charge, 0);
+	return {
+		left: total(equation.reactants),
+		right: total(equation.products)
+	};
+}
+
+//#endregion
+export { atomTally, balance, chargeTally, formatEquation, splitEquation };

package/dist/chem/formula.d.mts

@@ -0,0 +1,90 @@
+//#region src/chem/formula.d.ts
+/**
+ * Chemical formulae: what is in them, what they weigh, and what they weigh per element.
+ *
+ * ## One parser, because two would disagree
+ *
+ * A formula turns up in every quantitative question there is, and each of them needs the same three
+ * answers: which atoms, how many, and what that comes to. Writing a small reader for each caller is
+ * how a kernel ends up telling two different stories about Ca(NO3)2, so everything reads formulae
+ * here.
+ *
+ * What it understands:
+ *
+ *   Ca(NO3)2            groups in brackets, with a multiplier
+ *   K4[Fe(CN)6]         square brackets, nested
+ *   CuSO4.5H2O          a hydrate, written with a dot and a leading count
+ *   MgCl2.KCl.6H2O      a double salt, as many parts as it takes
+ *
+ * ## Masses come from the element table, and a formula that names nothing is refused
+ *
+ * Relative atomic masses are the IUPAC values the atomic engine already holds, so a mass computed
+ * here cannot disagree with one computed anywhere else. A symbol that is not an element stops the
+ * parse: `Xy2O3` is a typo, and a parser that skipped it would return a mass for a substance that
+ * does not exist, which is worse than no answer at all.
+ *
+ * ## The empirical formula is a search, not a division
+ *
+ * Dividing by the smallest mole count is only the first half. It lands on whole numbers for some
+ * compounds and on 1.5 or 1.33 for others, and the answer is to scale until every ratio is close to
+ * a whole number. {@link empiricalFormula} tries multipliers in order and takes the first that
+ * works, which is exactly the step a learner is told to do "by inspection" and is the step most
+ * often fudged.
+ *
+ * Pure: no React, no pixels.
+ */
+/** One element and how many of its atoms the formula contains. */
+interface ElementCount {
+  readonly element: string;
+  readonly count: number;
+}
+/**
+ * The atoms in a formula, in the order they are written.
+ *
+ * Hydrates and double salts are split on the dot, each part parsed on its own and multiplied by its
+ * leading count, then added together. So CuSO4.5H2O has ten hydrogens, nine oxygens, one copper and
+ * one sulfur, which is what it weighs as.
+ */
+declare function parseFormula(input: string): ElementCount[];
+/**
+ * Relative molecular mass, from the IUPAC atomic weights the element table holds.
+ *
+ * Called relative FORMULA mass for anything ionic, since sodium chloride has no molecules, and the
+ * arithmetic is identical either way.
+ */
+declare function molarMass(formula: string): number;
+interface MassFraction {
+  readonly element: string;
+  /** Mass of this element in one formula unit. */
+  readonly mass: number;
+  /** Its share of the total, as a percentage. */
+  readonly percent: number;
+}
+/** What fraction of a compound's mass each element accounts for. */
+declare function percentComposition(formula: string): MassFraction[];
+/**
+ * The empirical formula implied by a composition.
+ *
+ * Takes percentages by mass, or any set of masses in the same unit: only the ratios matter, so the
+ * numbers do not have to add to a hundred and a set of measured masses works directly.
+ *
+ * The scaling step is the one that is usually waved through. Dividing by the smallest mole count
+ * can land on 1.5 or 1.33, and the ratios then have to be multiplied up until they are all close to
+ * whole numbers. That search is done here rather than left to inspection, and if no multiplier up
+ * to eight works the composition is refused rather than rounded into something tidy.
+ */
+declare function empiricalFormula(composition: Readonly<Record<string, number>>): ElementCount[];
+/**
+ * How many empirical units make up the real molecule.
+ *
+ * Rounded, because the ratio of a measured molar mass to an exact empirical mass never comes out
+ * whole. Refuses when it is not close to one, since a value of 2.4 means the molar mass or the
+ * composition is wrong and multiplying by 2 would bury that.
+ */
+declare function unitsInMolecule(empirical: readonly ElementCount[], relativeMolecularMass: number): number;
+/** The molecular formula: the empirical formula multiplied up to fit the measured mass. */
+declare const molecularFormulaFor: (empirical: readonly ElementCount[], relativeMolecularMass: number) => ElementCount[];
+/** Write counts back out as a formula, leaving a count of one unwritten. */
+declare const formatFormula: (counts: readonly ElementCount[]) => string;
+//#endregion
+export { ElementCount, MassFraction, empiricalFormula, formatFormula, molarMass, molecularFormulaFor, parseFormula, percentComposition, unitsInMolecule };

package/dist/chem/formula.mjs

@@ -0,0 +1,201 @@
+import { elementBySymbol } from "../atomic/elements.mjs";
+
+//#region src/chem/formula.ts
+/**
+* Chemical formulae: what is in them, what they weigh, and what they weigh per element.
+*
+* ## One parser, because two would disagree
+*
+* A formula turns up in every quantitative question there is, and each of them needs the same three
+* answers: which atoms, how many, and what that comes to. Writing a small reader for each caller is
+* how a kernel ends up telling two different stories about Ca(NO3)2, so everything reads formulae
+* here.
+*
+* What it understands:
+*
+*   Ca(NO3)2            groups in brackets, with a multiplier
+*   K4[Fe(CN)6]         square brackets, nested
+*   CuSO4.5H2O          a hydrate, written with a dot and a leading count
+*   MgCl2.KCl.6H2O      a double salt, as many parts as it takes
+*
+* ## Masses come from the element table, and a formula that names nothing is refused
+*
+* Relative atomic masses are the IUPAC values the atomic engine already holds, so a mass computed
+* here cannot disagree with one computed anywhere else. A symbol that is not an element stops the
+* parse: `Xy2O3` is a typo, and a parser that skipped it would return a mass for a substance that
+* does not exist, which is worse than no answer at all.
+*
+* ## The empirical formula is a search, not a division
+*
+* Dividing by the smallest mole count is only the first half. It lands on whole numbers for some
+* compounds and on 1.5 or 1.33 for others, and the answer is to scale until every ratio is close to
+* a whole number. {@link empiricalFormula} tries multipliers in order and takes the first that
+* works, which is exactly the step a learner is told to do "by inspection" and is the step most
+* often fudged.
+*
+* Pure: no React, no pixels.
+*/
+const isUpper = (c) => c >= "A" && c <= "Z";
+const isLower = (c) => c >= "a" && c <= "z";
+const isDigit = (c) => c >= "0" && c <= "9";
+function readNumber(r) {
+	let digits = "";
+	while (r.at < r.text.length && isDigit(r.text[r.at])) digits += r.text[r.at++];
+	return digits === "" ? 1 : Number(digits);
+}
+const CLOSERS = {
+	"(": ")",
+	"[": "]"
+};
+/** Parse one group, stopping at a closing bracket or the end of the text. */
+function readGroup(r, closer) {
+	const counts = /* @__PURE__ */ new Map();
+	const add = (element, n) => void counts.set(element, (counts.get(element) ?? 0) + n);
+	while (r.at < r.text.length) {
+		const c = r.text[r.at];
+		if (closer && c === closer) {
+			r.at += 1;
+			return counts;
+		}
+		if (c === "(" || c === "[") {
+			r.at += 1;
+			const inner = readGroup(r, CLOSERS[c]);
+			const multiplier = readNumber(r);
+			for (const [element, n] of inner) add(element, n * multiplier);
+			continue;
+		}
+		if (c === ")" || c === "]") throw new Error(`cannot read "${r.text}": a closing bracket at position ${r.at} opens nothing`);
+		if (!isUpper(c)) throw new Error(`cannot read "${r.text}": expected an element symbol at position ${r.at}, found "${c}"`);
+		let symbol = r.text[r.at++];
+		if (r.at < r.text.length && isLower(r.text[r.at])) symbol += r.text[r.at++];
+		if (!elementBySymbol(symbol)) throw new Error(`cannot read "${r.text}": "${symbol}" is not an element`);
+		add(symbol, readNumber(r));
+	}
+	if (closer) throw new Error(`cannot read "${r.text}": a bracket is never closed`);
+	return counts;
+}
+/**
+* The atoms in a formula, in the order they are written.
+*
+* Hydrates and double salts are split on the dot, each part parsed on its own and multiplied by its
+* leading count, then added together. So CuSO4.5H2O has ten hydrogens, nine oxygens, one copper and
+* one sulfur, which is what it weighs as.
+*/
+function parseFormula(input) {
+	const text = input.replace(/\s+/g, "");
+	if (text === "") throw new Error("an empty formula has no composition");
+	const total = /* @__PURE__ */ new Map();
+	text.split(".").forEach((part, index) => {
+		if (part === "") throw new Error(`cannot read "${input}": an empty part between dots`);
+		const r = {
+			text: part,
+			at: 0
+		};
+		const multiplier = index === 0 ? 1 : readNumber(r);
+		for (const [element, n] of readGroup(r)) total.set(element, (total.get(element) ?? 0) + n * multiplier);
+	});
+	return [...total].map(([element, count]) => ({
+		element,
+		count
+	}));
+}
+/**
+* Relative molecular mass, from the IUPAC atomic weights the element table holds.
+*
+* Called relative FORMULA mass for anything ionic, since sodium chloride has no molecules, and the
+* arithmetic is identical either way.
+*/
+function molarMass(formula) {
+	return parseFormula(formula).reduce((total, { element, count }) => total + elementBySymbol(element).atomicWeight * count, 0);
+}
+/** What fraction of a compound's mass each element accounts for. */
+function percentComposition(formula) {
+	const total = molarMass(formula);
+	return parseFormula(formula).map(({ element, count }) => {
+		const mass = elementBySymbol(element).atomicWeight * count;
+		return {
+			element,
+			mass,
+			percent: mass / total * 100
+		};
+	});
+}
+/**
+* How close a scaled ratio has to be to a whole number before it counts as one.
+*
+* Fixed, and deliberately not loosened as the multiplier grows. Scaling the tolerance with the
+* multiplier made every larger multiplier more forgiving than the last, so a composition that fits
+* nothing would always find some multiple that looked close enough, and the refusal below could
+* never fire.
+*/
+const WHOLE_TOLERANCE = .1;
+/** Multipliers tried when the first division does not land on whole numbers. */
+const MULTIPLIERS = [
+	1,
+	2,
+	3,
+	4,
+	5,
+	6,
+	8
+];
+/**
+* The empirical formula implied by a composition.
+*
+* Takes percentages by mass, or any set of masses in the same unit: only the ratios matter, so the
+* numbers do not have to add to a hundred and a set of measured masses works directly.
+*
+* The scaling step is the one that is usually waved through. Dividing by the smallest mole count
+* can land on 1.5 or 1.33, and the ratios then have to be multiplied up until they are all close to
+* whole numbers. That search is done here rather than left to inspection, and if no multiplier up
+* to eight works the composition is refused rather than rounded into something tidy.
+*/
+function empiricalFormula(composition) {
+	const entries = Object.entries(composition).filter(([, amount]) => amount > 0);
+	if (entries.length === 0) throw new Error("a composition with nothing in it has no formula");
+	const moles = entries.map(([element, amount]) => {
+		const record = elementBySymbol(element);
+		if (!record) throw new Error(`"${element}" is not an element`);
+		return {
+			element,
+			moles: amount / record.atomicWeight
+		};
+	});
+	const smallest = Math.min(...moles.map((m) => m.moles));
+	const ratios = moles.map((m) => m.moles / smallest);
+	for (const multiplier of MULTIPLIERS) {
+		const scaled = ratios.map((r) => r * multiplier);
+		if (scaled.every((value) => Math.abs(value - Math.round(value)) <= WHOLE_TOLERANCE)) return moles.map((m, i) => ({
+			element: m.element,
+			count: Math.round(scaled[i])
+		}));
+	}
+	throw new Error(`this composition does not reduce to a whole-number ratio: ${ratios.map((r, i) => `${moles[i].element} ${r.toFixed(3)}`).join(", ")}. Check the percentages add up and that no element is missing.`);
+}
+/**
+* How many empirical units make up the real molecule.
+*
+* Rounded, because the ratio of a measured molar mass to an exact empirical mass never comes out
+* whole. Refuses when it is not close to one, since a value of 2.4 means the molar mass or the
+* composition is wrong and multiplying by 2 would bury that.
+*/
+function unitsInMolecule(empirical, relativeMolecularMass) {
+	const empiricalMass = empirical.reduce((total, { element, count }) => total + elementBySymbol(element).atomicWeight * count, 0);
+	const ratio = relativeMolecularMass / empiricalMass;
+	const whole = Math.round(ratio);
+	if (whole < 1 || Math.abs(ratio - whole) > .1) throw new Error(`a relative molecular mass of ${relativeMolecularMass} is ${ratio.toFixed(2)} times the empirical mass of ${empiricalMass.toFixed(1)}, which is not a whole number of units`);
+	return whole;
+}
+/** The molecular formula: the empirical formula multiplied up to fit the measured mass. */
+const molecularFormulaFor = (empirical, relativeMolecularMass) => {
+	const n = unitsInMolecule(empirical, relativeMolecularMass);
+	return empirical.map(({ element, count }) => ({
+		element,
+		count: count * n
+	}));
+};
+/** Write counts back out as a formula, leaving a count of one unwritten. */
+const formatFormula = (counts) => counts.map(({ element, count }) => `${element}${count === 1 ? "" : count}`).join("");
+
+//#endregion
+export { empiricalFormula, formatFormula, molarMass, molecularFormulaFor, parseFormula, percentComposition, unitsInMolecule };

package/dist/chem/functional-groups.d.mts

@@ -0,0 +1,31 @@
+import { Structure } from "./molecule.mjs";
+
+//#region src/chem/functional-groups.d.ts
+type GroupKind = 'alkene' | 'alkyne' | 'arene' | 'alcohol' | 'halogenoalkane' | 'aldehyde' | 'ketone' | 'carboxylic-acid' | 'ester' | 'acyl-chloride' | 'amide' | 'amine' | 'nitrile';
+interface FoundGroup {
+  readonly kind: GroupKind;
+  /** The atoms that make up the group, so a figure can highlight exactly these. */
+  readonly atoms: readonly number[];
+  /**
+   * Primary, secondary or tertiary, where the syllabus distinguishes them.
+   *
+   * Alcohols and halogenoalkanes, because the class decides the mechanism, and amines, because it
+   * decides the basicity.
+   */
+  readonly klass?: 'primary' | 'secondary' | 'tertiary';
+}
+/**
+ * Every functional group in the structure.
+ *
+ * An atom may appear in more than one group only when the chemistry really has two: an amino acid
+ * genuinely has both a carboxylic acid and an amine, and reporting one would lose the point of the
+ * molecule. What never happens is the same atoms being reported twice under different names, which
+ * is what the carbonyl classification exists to prevent.
+ */
+declare function functionalGroups(structure: Structure): FoundGroup[];
+/** Does the structure contain this group? The question a reagent test actually asks. */
+declare const hasGroup: (structure: Structure, kind: GroupKind) => boolean;
+/** Group kinds present, each once, in the order they were found. */
+declare const groupKinds: (structure: Structure) => GroupKind[];
+//#endregion
+export { FoundGroup, GroupKind, functionalGroups, groupKinds, hasGroup };

package/dist/chem/functional-groups.mjs

@@ -0,0 +1,187 @@
+import { bondsAt, implicitHydrogens, otherEnd } from "./molecule.mjs";
+
+//#region src/chem/functional-groups.ts
+/**
+* functional-groups, found in a structure rather than declared beside it.
+*
+* WHAT THIS IS FOR. Every lab that highlights a functional group currently does it by listing vertex
+* indices, which means the highlight and the structure are two independent claims and nothing checks
+* that they agree. Worse, it means a learner is shown "here is the carbonyl" rather than being
+* taught what makes a carbonyl a carbonyl, because the recognition was done by the author.
+*
+* Perception closes both. A group is a small pattern in the graph, and finding it is the same work
+* the learner is being asked to do.
+*
+* ## Why the order matters
+*
+* Several groups share a C=O and are told apart only by what else is on that carbon. An ester, an
+* acid, an amide, an acyl chloride, an aldehyde and a ketone all contain one. So the carbonyl is
+* classified ONCE, by looking at its other neighbours, and the more specific answer wins: a
+* structure with a C=O and an O-H on the same carbon is a carboxylic acid and is not reported as a
+* ketone with an alcohol attached.
+*
+* That ordering is not an implementation detail. It is exactly the reasoning an exam question wants,
+* and stating it as a sequence of tests is what makes it teachable.
+*
+* Pure: no React, no pixels.
+*/
+const isC = (s, id) => s.atoms[id].element === "C";
+/** Carbons attached to this atom. */
+const carbonNeighbours = (s, id) => bondsAt(s, id).map((b) => otherEnd(b, id)).filter((n) => isC(s, n));
+/** An oxygen bonded to exactly one heavy atom, so its other bond is to hydrogen. */
+const isHydroxyl = (s, id) => s.atoms[id].element === "O" && bondsAt(s, id).length === 1 && implicitHydrogens(s, id) === 1;
+/** Primary, secondary or tertiary, from the carbons attached to the carbon bearing the group. */
+function classify(s, carbon, exclude) {
+	const others = carbonNeighbours(s, carbon).filter((n) => n !== exclude).length;
+	return others <= 1 ? "primary" : others === 2 ? "secondary" : "tertiary";
+}
+/**
+* Classify one carbonyl carbon by what else is attached to it.
+*
+* The whole of the carbonyl family, in the order an exam question works through it: look for the
+* second oxygen first, because that is what separates the acid and the ester from everything else.
+*/
+function carbonylKind(s, carbon, oxygen) {
+	const attached = bondsAt(s, carbon).map((b) => otherEnd(b, carbon)).filter((n) => n !== oxygen);
+	const hydrogens = implicitHydrogens(s, carbon);
+	const hydroxyl = attached.find((n) => isHydroxyl(s, n));
+	if (hydroxyl !== void 0) return {
+		kind: "carboxylic-acid",
+		atoms: [
+			carbon,
+			oxygen,
+			hydroxyl
+		]
+	};
+	const etherO = attached.find((n) => s.atoms[n].element === "O" && bondsAt(s, n).length === 2);
+	if (etherO !== void 0) return {
+		kind: "ester",
+		atoms: [
+			carbon,
+			oxygen,
+			etherO
+		]
+	};
+	const chlorine = attached.find((n) => s.atoms[n].element === "Cl");
+	if (chlorine !== void 0) return {
+		kind: "acyl-chloride",
+		atoms: [
+			carbon,
+			oxygen,
+			chlorine
+		]
+	};
+	const nitrogen = attached.find((n) => s.atoms[n].element === "N");
+	if (nitrogen !== void 0) return {
+		kind: "amide",
+		atoms: [
+			carbon,
+			oxygen,
+			nitrogen
+		]
+	};
+	const carbons = attached.filter((n) => isC(s, n)).length;
+	if (hydrogens >= 1 || carbons <= 1) return {
+		kind: "aldehyde",
+		atoms: [carbon, oxygen]
+	};
+	return {
+		kind: "ketone",
+		atoms: [carbon, oxygen]
+	};
+}
+/**
+* Every functional group in the structure.
+*
+* An atom may appear in more than one group only when the chemistry really has two: an amino acid
+* genuinely has both a carboxylic acid and an amine, and reporting one would lose the point of the
+* molecule. What never happens is the same atoms being reported twice under different names, which
+* is what the carbonyl classification exists to prevent.
+*/
+function functionalGroups(structure) {
+	const found = [];
+	const carbonylOxygens = /* @__PURE__ */ new Set();
+	const groupedO = /* @__PURE__ */ new Set();
+	const groupedN = /* @__PURE__ */ new Set();
+	for (const bond of structure.bonds) {
+		if (bond.order !== 2 || bond.aromatic) continue;
+		const pair = [bond.a, bond.b];
+		const carbon = pair.find((n) => isC(structure, n));
+		const oxygen = pair.find((n) => structure.atoms[n].element === "O");
+		if (carbon === void 0 || oxygen === void 0) continue;
+		const group = carbonylKind(structure, carbon, oxygen);
+		if (!group) continue;
+		found.push(group);
+		carbonylOxygens.add(oxygen);
+		for (const id of group.atoms) {
+			if (structure.atoms[id].element === "O") groupedO.add(id);
+			if (structure.atoms[id].element === "N") groupedN.add(id);
+		}
+	}
+	for (const bond of structure.bonds) {
+		if (bond.aromatic) continue;
+		const bothCarbon = isC(structure, bond.a) && isC(structure, bond.b);
+		if (bothCarbon && bond.order === 2) found.push({
+			kind: "alkene",
+			atoms: [bond.a, bond.b]
+		});
+		if (bothCarbon && bond.order === 3) found.push({
+			kind: "alkyne",
+			atoms: [bond.a, bond.b]
+		});
+		if (bond.order === 3 && !bothCarbon) {
+			const carbon = [bond.a, bond.b].find((n) => isC(structure, n));
+			const nitrogen = [bond.a, bond.b].find((n) => structure.atoms[n].element === "N");
+			if (carbon !== void 0 && nitrogen !== void 0) {
+				found.push({
+					kind: "nitrile",
+					atoms: [carbon, nitrogen]
+				});
+				groupedN.add(nitrogen);
+			}
+		}
+	}
+	if (structure.atoms.some((a) => a.aromatic)) found.push({
+		kind: "arene",
+		atoms: structure.atoms.filter((a) => a.aromatic).map((a) => a.id)
+	});
+	for (const atom of structure.atoms) {
+		if (atom.element === "O" && !groupedO.has(atom.id) && isHydroxyl(structure, atom.id)) {
+			const carbon = carbonNeighbours(structure, atom.id)[0];
+			if (carbon !== void 0) found.push({
+				kind: "alcohol",
+				atoms: [carbon, atom.id],
+				klass: classify(structure, carbon, atom.id)
+			});
+		}
+		if ([
+			"F",
+			"Cl",
+			"Br",
+			"I"
+		].includes(atom.element)) {
+			const carbon = carbonNeighbours(structure, atom.id)[0];
+			if (carbon !== void 0 && !found.some((g) => g.kind === "acyl-chloride" && g.atoms.includes(atom.id))) found.push({
+				kind: "halogenoalkane",
+				atoms: [carbon, atom.id],
+				klass: classify(structure, carbon, atom.id)
+			});
+		}
+		if (atom.element === "N" && !groupedN.has(atom.id)) {
+			const carbons = carbonNeighbours(structure, atom.id);
+			if (carbons.length >= 1) found.push({
+				kind: "amine",
+				atoms: [atom.id, ...carbons],
+				klass: carbons.length === 1 ? "primary" : carbons.length === 2 ? "secondary" : "tertiary"
+			});
+		}
+	}
+	return found;
+}
+/** Does the structure contain this group? The question a reagent test actually asks. */
+const hasGroup = (structure, kind) => functionalGroups(structure).some((g) => g.kind === kind);
+/** Group kinds present, each once, in the order they were found. */
+const groupKinds = (structure) => [...new Set(functionalGroups(structure).map((g) => g.kind))];
+
+//#endregion
+export { functionalGroups, groupKinds, hasGroup };