@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/stereo.d.mts

@@ -0,0 +1,108 @@
+import { Structure } from "./molecule.mjs";
+
+//#region src/chem/stereo.d.ts
+/**
+ * Compare two branches by CIP priority.
+ *
+ * Returns a negative number when the first outranks the second, positive when the second does, and
+ * `undefined` when they cannot be separated within the spheres explored, which for a real molecule
+ * means they are the same branch.
+ *
+ * The comparison walks outward one sphere at a time. At each sphere both branches offer a list of
+ * atoms sorted heaviest first; the lists are compared position by position, and the first
+ * difference decides it. Only if they are identical does the walk go further out.
+ */
+declare function comparePriority(structure: Structure, centre: number, firstAtom: number, secondAtom: number, maxSpheres?: number): number | undefined;
+/**
+ * The same comparison, for two branches hanging off DIFFERENT atoms.
+ *
+ * Needed by the meso check, where the two branches being weighed against each other belong to the
+ * two ends of the molecule rather than to one centre. Passing both to {@link comparePriority} with
+ * a single centre let each walk escape backwards through the other's parent, so two branches that
+ * are plainly the same came out different and no meso form was ever found.
+ */
+declare function compareBranches(structure: Structure, firstAtom: number, firstFrom: number, secondAtom: number, secondFrom: number, maxSpheres?: number): number | undefined;
+interface RankedSubstituent {
+  readonly atom: number;
+  readonly element: string;
+  /** 1 is highest priority. */
+  readonly rank: number;
+}
+/**
+ * The substituents of an atom in priority order, highest first.
+ *
+ * Returns undefined when two of them cannot be separated, which is the honest answer: a carbon with
+ * two identical groups on it has no handedness, and saying so is more useful than an arbitrary
+ * ordering that would then produce a confident R or S for a molecule that is neither.
+ */
+declare function rankSubstituents(structure: Structure, centre: number): RankedSubstituent[] | undefined;
+interface Stereocentre {
+  readonly atom: number;
+  readonly substituents: readonly RankedSubstituent[];
+}
+/**
+ * Every carbon with four different groups on it.
+ *
+ * The definition, applied rather than paraphrased. A carbon qualifies when the four things attached
+ * to it can all be told apart by the priority rules, which is a stronger statement than "four
+ * different atoms" and is why 3-methylhexane has a stereocentre and 3-methylpentane does not: in
+ * the second, two of the branches are both ethyl.
+ */
+declare function stereocentres(structure: Structure): Stereocentre[];
+/**
+ * How many stereoisomers a molecule has, from its stereocentre count.
+ *
+ * Two arrangements at each centre, independently, so 2^n. This is the upper bound: see
+ * {@link stereoisomerCount} for the number a molecule with an internal mirror plane actually has.
+ */
+declare const maximumStereoisomers: (centres: number) => number;
+interface StereoisomerCount {
+  readonly centres: number;
+  /** Two arrangements at each centre, independently. */
+  readonly maximum: number;
+  /** What the molecule actually has. */
+  readonly actual: number;
+  /** True when one arrangement is its own mirror image and so is not a separate substance. */
+  readonly hasMeso: boolean;
+  readonly because: string;
+}
+/**
+ * How many stereoisomers a molecule really has.
+ *
+ * The rule of 2^n over-counts whenever the molecule has an internal mirror plane. Tartaric acid has
+ * two stereocentres and three isomers, not four: the arrangement with one centre left-handed and
+ * the other right-handed is superimposable on its own reflection, so the two that 2^n counts
+ * separately are one substance, and that substance is not optically active at all.
+ *
+ * Detected by asking whether the centres are mirror images of one another, which is checkable with
+ * the machinery already here: the branches leading away from each centre have to be
+ * indistinguishable, and indistinguishable is exactly what {@link comparePriority} reports when it
+ * cannot separate two branches.
+ *
+ * Restricted to the two-centre case, which is the one syllabuses set. A molecule with more centres
+ * and partial symmetry needs a full search over configurations, and this reports the maximum for
+ * those rather than guessing.
+ */
+declare function stereoisomerCount(structure: Structure): StereoisomerCount;
+type DoubleBondShape = 'E' | 'Z';
+interface DoubleBondStereo {
+  readonly a: number;
+  readonly b: number;
+  /** The higher-priority substituent on each carbon. */
+  readonly higherOnA: number;
+  readonly higherOnB: number;
+}
+/**
+ * Double bonds that can show E/Z, with the higher-priority group on each end identified.
+ *
+ * A double bond has a shape worth naming only when BOTH its carbons carry two different groups. If
+ * either end has two of the same thing, swapping them changes nothing and there is only one
+ * compound, which is why 1,1-dichloroethene has no isomers and 1,2-dichloroethene has two.
+ *
+ * Which arrangement is E and which is Z cannot be read off the connection table: it depends on
+ * where the groups actually are in space, which a graph does not record. So this reports WHICH
+ * group wins on each end, and the geometry has to say the rest.
+ */
+declare function stereogenicDoubleBonds(structure: Structure): DoubleBondStereo[];
+//#endregion
+export { DoubleBondShape, DoubleBondStereo, RankedSubstituent, Stereocentre, StereoisomerCount, compareBranches, comparePriority, maximumStereoisomers, rankSubstituents, stereocentres, stereogenicDoubleBonds, stereoisomerCount };

package/dist/chem/stereo.mjs

@@ -0,0 +1,286 @@
+import { elementBySymbol } from "../atomic/elements.mjs";
+import { bondsAt, implicitHydrogens, otherEnd } from "./molecule.mjs";
+
+//#region src/chem/stereo.ts
+/**
+* Stereochemistry: which carbons have a handedness, and which way round each one is.
+*
+* ## The question, and why ranking is the whole of it
+*
+* Two molecules can have the same atoms joined in the same order and still be different substances,
+* because four different groups around one carbon can be arranged two ways that are mirror images
+* and cannot be superimposed. Telling those two apart needs a rule for which group outranks which,
+* and that rule is the Cahn-Ingold-Prelog priority.
+*
+* Almost every treatment gives the rule as "highest atomic number first, and if there is a tie,
+* look further out". The second half is where all the difficulty lives and it is where textbooks
+* stop. Looking further out means comparing two whole branches, and the comparison has a definite
+* shape: gather the atoms at distance one from each branch, sort them heaviest first, compare the
+* two lists; if they match, gather distance two, and so on. It is a breadth-first comparison of
+* trees, and written that way it is neither vague nor hard.
+*
+* {@link comparePriority} does exactly that, so a learner can be shown the sphere at which two
+* branches finally differed rather than being told the answer.
+*
+* ## Double bonds are duplicated, which is the part that looks like a trick
+*
+* A doubly bonded oxygen counts twice. That is not a convention invented to break ties: the rule is
+* that an atom joined by a double bond is treated as joined to two of that atom, because a double
+* bond is two connections. So the carbon of an aldehyde carries (O, O, H) and the carbon of an
+* alcohol carries (O, H, H), and the aldehyde outranks it for a reason rather than by decree.
+*
+* ## What this covers, and what it refuses
+*
+* Tetrahedral carbon centres, and double bonds for E/Z. The priority comparison explores outward
+* through the whole molecule, so it settles the cases that matter at this level.
+*
+* It does NOT implement the auxiliary descriptors CIP needs for rings that are symmetric until
+* several spheres out, or for deciding between two branches that are identical in constitution and
+* differ only in their own stereochemistry. Those exist, they are genuinely intricate, and a
+* kernel that guessed at them would be wrong quietly. {@link comparePriority} returns undefined
+* where it cannot separate two branches, and everything above it reports that rather than picking.
+*
+* Pure: no React, no pixels.
+*/
+/** Proton number, which is what "higher atomic number wins" is comparing. */
+const protons = (element) => elementBySymbol(element)?.Z ?? 0;
+/**
+* The atoms one step out from `atom`, coming from `cameFrom`, heaviest first.
+*
+* Doubly and triply bonded neighbours appear as many times as the bond order, which is the
+* duplication rule. Implicit hydrogens are included, because a hydrogen is a substituent and
+* leaving it out would make a CH2 look like a CH.
+*/
+function neighbours(structure, atom, cameFrom) {
+	const out = [];
+	for (const bond of bondsAt(structure, atom)) {
+		const other = otherEnd(bond, atom);
+		const element = structure.atoms[other].element;
+		const order = bond.aromatic ? 2 : bond.order;
+		if (other !== cameFrom) out.push({
+			element,
+			id: other
+		});
+		for (let k = 1; k < order; k += 1) out.push({
+			element,
+			id: void 0
+		});
+	}
+	for (let k = 0; k < implicitHydrogens(structure, atom); k += 1) out.push({
+		element: "H",
+		id: void 0
+	});
+	return out.sort((a, b) => protons(b.element) - protons(a.element));
+}
+/**
+* Compare two branches by CIP priority.
+*
+* Returns a negative number when the first outranks the second, positive when the second does, and
+* `undefined` when they cannot be separated within the spheres explored, which for a real molecule
+* means they are the same branch.
+*
+* The comparison walks outward one sphere at a time. At each sphere both branches offer a list of
+* atoms sorted heaviest first; the lists are compared position by position, and the first
+* difference decides it. Only if they are identical does the walk go further out.
+*/
+function comparePriority(structure, centre, firstAtom, secondAtom, maxSpheres = 12) {
+	return compareBranches(structure, firstAtom, centre, secondAtom, centre, maxSpheres);
+}
+/**
+* The same comparison, for two branches hanging off DIFFERENT atoms.
+*
+* Needed by the meso check, where the two branches being weighed against each other belong to the
+* two ends of the molecule rather than to one centre. Passing both to {@link comparePriority} with
+* a single centre let each walk escape backwards through the other's parent, so two branches that
+* are plainly the same came out different and no meso form was ever found.
+*/
+function compareBranches(structure, firstAtom, firstFrom, secondAtom, secondFrom, maxSpheres = 12) {
+	const first = protons(structure.atoms[firstAtom].element);
+	const second = protons(structure.atoms[secondAtom].element);
+	if (first !== second) return second - first;
+	let frontA = [{
+		atom: firstAtom,
+		cameFrom: firstFrom
+	}];
+	let frontB = [{
+		atom: secondAtom,
+		cameFrom: secondFrom
+	}];
+	for (let sphere = 0; sphere < maxSpheres; sphere += 1) {
+		if (frontA.length === 0 && frontB.length === 0) return void 0;
+		const expand = (front) => {
+			const list = [];
+			const next = [];
+			for (const node of front) for (const n of neighbours(structure, node.atom, node.cameFrom)) {
+				list.push(n.element);
+				if (n.id !== void 0) next.push({
+					atom: n.id,
+					cameFrom: node.atom
+				});
+			}
+			return {
+				list,
+				next
+			};
+		};
+		const a = expand(frontA);
+		const b = expand(frontB);
+		const sortedA = [...a.list].sort((x, y) => protons(y) - protons(x));
+		const sortedB = [...b.list].sort((x, y) => protons(y) - protons(x));
+		const length = Math.max(sortedA.length, sortedB.length);
+		for (let k = 0; k < length; k += 1) {
+			const pa = protons(sortedA[k] ?? "");
+			const pb = protons(sortedB[k] ?? "");
+			if (pa !== pb) return pb - pa;
+		}
+		frontA = a.next;
+		frontB = b.next;
+	}
+}
+/**
+* The substituents of an atom in priority order, highest first.
+*
+* Returns undefined when two of them cannot be separated, which is the honest answer: a carbon with
+* two identical groups on it has no handedness, and saying so is more useful than an arbitrary
+* ordering that would then produce a confident R or S for a molecule that is neither.
+*/
+function rankSubstituents(structure, centre) {
+	const attached = bondsAt(structure, centre).map((bond) => otherEnd(bond, centre));
+	const hydrogens = implicitHydrogens(structure, centre);
+	if (attached.length + hydrogens !== 4) return void 0;
+	const sorted = [...attached];
+	for (let i = 0; i < sorted.length; i += 1) for (let j = i + 1; j < sorted.length; j += 1) {
+		const order = comparePriority(structure, centre, sorted[i], sorted[j]);
+		if (order === void 0) return void 0;
+		if (order > 0) [sorted[i], sorted[j]] = [sorted[j], sorted[i]];
+	}
+	const ranked = sorted.map((atom, index) => ({
+		atom,
+		element: structure.atoms[atom].element,
+		rank: index + 1
+	}));
+	if (hydrogens === 1) return ranked;
+	if (hydrogens === 0) return ranked;
+}
+/**
+* Every carbon with four different groups on it.
+*
+* The definition, applied rather than paraphrased. A carbon qualifies when the four things attached
+* to it can all be told apart by the priority rules, which is a stronger statement than "four
+* different atoms" and is why 3-methylhexane has a stereocentre and 3-methylpentane does not: in
+* the second, two of the branches are both ethyl.
+*/
+function stereocentres(structure) {
+	const found = [];
+	for (const atom of structure.atoms) {
+		if (atom.element !== "C" || atom.aromatic) continue;
+		const substituents = rankSubstituents(structure, atom.id);
+		if (substituents) found.push({
+			atom: atom.id,
+			substituents
+		});
+	}
+	return found;
+}
+/**
+* How many stereoisomers a molecule has, from its stereocentre count.
+*
+* Two arrangements at each centre, independently, so 2^n. This is the upper bound: see
+* {@link stereoisomerCount} for the number a molecule with an internal mirror plane actually has.
+*/
+const maximumStereoisomers = (centres) => 2 ** centres;
+/**
+* Whether two stereocentres are mirror images of each other through the middle of the molecule.
+*
+* True when the branches leading away from each centre are the same on both sides, which is what
+* makes the molecule superimposable on its own reflection.
+*/
+function centresArePaired(structure, first, second) {
+	const branchesOf = (centre, away) => bondsAt(structure, centre).map((bond) => otherEnd(bond, centre)).filter((id) => id !== away);
+	const a = branchesOf(first, second);
+	const b = branchesOf(second, first);
+	if (a.length !== b.length) return false;
+	const spare = [...b];
+	for (const branch of a) {
+		const match = spare.findIndex((other) => compareBranches(structure, branch, first, other, second) === void 0);
+		if (match === -1) return false;
+		spare.splice(match, 1);
+	}
+	return true;
+}
+/**
+* How many stereoisomers a molecule really has.
+*
+* The rule of 2^n over-counts whenever the molecule has an internal mirror plane. Tartaric acid has
+* two stereocentres and three isomers, not four: the arrangement with one centre left-handed and
+* the other right-handed is superimposable on its own reflection, so the two that 2^n counts
+* separately are one substance, and that substance is not optically active at all.
+*
+* Detected by asking whether the centres are mirror images of one another, which is checkable with
+* the machinery already here: the branches leading away from each centre have to be
+* indistinguishable, and indistinguishable is exactly what {@link comparePriority} reports when it
+* cannot separate two branches.
+*
+* Restricted to the two-centre case, which is the one syllabuses set. A molecule with more centres
+* and partial symmetry needs a full search over configurations, and this reports the maximum for
+* those rather than guessing.
+*/
+function stereoisomerCount(structure) {
+	const centres = stereocentres(structure);
+	const maximum = maximumStereoisomers(centres.length);
+	if (centres.length !== 2) return {
+		centres: centres.length,
+		maximum,
+		actual: maximum,
+		hasMeso: false,
+		because: centres.length < 2 ? "with fewer than two stereocentres there is no internal mirror plane to lose an isomer to" : "more than two centres are not searched for internal symmetry here, so this is the upper bound"
+	};
+	const paired = centresArePaired(structure, centres[0].atom, centres[1].atom);
+	return {
+		centres: 2,
+		maximum,
+		actual: paired ? maximum - 1 : maximum,
+		hasMeso: paired,
+		because: paired ? "the two centres carry the same groups, so the arrangement with one of each handedness is superimposable on its own mirror image: that meso form is one substance rather than two, and it is not optically active" : "the two centres carry different groups, so every one of the four arrangements is a distinct substance"
+	};
+}
+/**
+* Double bonds that can show E/Z, with the higher-priority group on each end identified.
+*
+* A double bond has a shape worth naming only when BOTH its carbons carry two different groups. If
+* either end has two of the same thing, swapping them changes nothing and there is only one
+* compound, which is why 1,1-dichloroethene has no isomers and 1,2-dichloroethene has two.
+*
+* Which arrangement is E and which is Z cannot be read off the connection table: it depends on
+* where the groups actually are in space, which a graph does not record. So this reports WHICH
+* group wins on each end, and the geometry has to say the rest.
+*/
+function stereogenicDoubleBonds(structure) {
+	const found = [];
+	for (const bond of structure.bonds) {
+		if (bond.order !== 2 || bond.aromatic) continue;
+		const higher = (end, far) => {
+			const groups = bondsAt(structure, end).map((b) => otherEnd(b, end)).filter((id) => id !== far);
+			const hydrogens = implicitHydrogens(structure, end);
+			if (groups.length + hydrogens !== 2) return void 0;
+			if (groups.length === 1 && hydrogens === 1) return groups[0];
+			if (groups.length !== 2) return void 0;
+			const order = comparePriority(structure, end, groups[0], groups[1]);
+			if (order === void 0) return void 0;
+			return order < 0 ? groups[0] : groups[1];
+		};
+		const higherOnA = higher(bond.a, bond.b);
+		const higherOnB = higher(bond.b, bond.a);
+		if (higherOnA === void 0 || higherOnB === void 0) continue;
+		found.push({
+			a: bond.a,
+			b: bond.b,
+			higherOnA,
+			higherOnB
+		});
+	}
+	return found;
+}
+
+//#endregion
+export { compareBranches, comparePriority, maximumStereoisomers, rankSubstituents, stereocentres, stereogenicDoubleBonds, stereoisomerCount };

package/dist/chem/stoichiometry.d.mts

@@ -0,0 +1,95 @@
+import { BalancedEquation } from "./equation.mjs";
+
+//#region src/chem/stoichiometry.d.ts
+/** How much of a substance is present, in whichever way it was measured. */
+interface Amount {
+  /** Grams. */
+  readonly mass?: number;
+  /** Moles, if they are known directly. */
+  readonly moles?: number;
+  /** Volume in cubic decimetres, for something in solution. */
+  readonly volumeDm3?: number;
+  /** Concentration in mol per cubic decimetre, used with the volume. */
+  readonly concentration?: number;
+}
+/** Moles of a substance from however it was given. */
+declare function molesOf(formula: string, amount: Amount): number;
+interface ReactantState {
+  readonly formula: string;
+  readonly coefficient: number;
+  readonly moles: number;
+  /**
+   * Moles available divided by the coefficient: how many times the equation can run on this one.
+   *
+   * The number the whole calculation turns on, and the one a mass comparison never reaches.
+   */
+  readonly equationRuns: number;
+  readonly limiting: boolean;
+  /** Moles of this reactant left when the limiting one is spent. */
+  readonly leftOver: number;
+}
+interface ProductState {
+  readonly formula: string;
+  readonly coefficient: number;
+  readonly moles: number;
+  readonly mass: number;
+}
+interface Reaction {
+  readonly equation: BalancedEquation;
+  /** How many times the equation as written can proceed. */
+  readonly runs: number;
+  readonly reactants: readonly ReactantState[];
+  readonly products: readonly ProductState[];
+  readonly limiting: ReactantState;
+}
+/**
+ * Work a reaction out from the amounts given.
+ *
+ * The equation is balanced here rather than taken on trust, because every mole ratio below depends
+ * on the coefficients and an unbalanced equation would make all of them confidently wrong.
+ */
+declare function react(equation: string, amounts: Readonly<Record<string, Amount>>): Reaction;
+/** The most of a product the equation allows, in grams. */
+declare function theoreticalYield(reaction: Reaction, product: string): number;
+interface YieldReport {
+  /** Measured over theoretical, as a percentage. Reported even when it is impossible. */
+  readonly percent: number;
+  /** Why this figure cannot be a yield, when it cannot be. */
+  readonly impossible?: string;
+}
+/**
+ * The measured mass as a percentage of the theoretical one, whatever it comes to.
+ *
+ * Reports rather than refuses, because a figure above a hundred per cent is a real thing that comes
+ * out of a real balance and is the single most useful measurement in the topic: it is the one that
+ * tells you something is wrong with the sample. A lab teaching that has to be able to SHOW 112 per
+ * cent before asking what it means.
+ *
+ * What it must not do is call that a yield. So the number comes back with the reason it is not one
+ * attached, and {@link percentageYield} is the strict form built on this for the places where the
+ * value has to be legitimate.
+ */
+declare function apparentYield(theoretical: number, measured: number): YieldReport;
+/**
+ * The fraction of the theoretical yield actually obtained, as a percentage.
+ *
+ * Refuses anything above a hundred. A flask cannot produce more than the equation allows, so a
+ * figure above it is evidence about the sample rather than about the reaction, and reporting it as
+ * a yield hides the one piece of information the number actually carries. Use {@link apparentYield}
+ * where that figure needs to be shown rather than accepted.
+ */
+declare function percentageYield(theoretical: number, measured: number): number;
+/**
+ * The mass of one reactant needed to use up a given amount of another exactly.
+ *
+ * What a preparation asks: how much of this do I weigh out so nothing is wasted.
+ */
+declare function amountNeeded(equation: string, have: {
+  formula: string;
+  amount: Amount;
+}, want: string): {
+  moles: number;
+  mass: number;
+};
+//#endregion
+export { Amount, ProductState, ReactantState, Reaction, YieldReport, amountNeeded, apparentYield, molesOf, percentageYield, react, theoreticalYield };

package/dist/chem/stoichiometry.mjs

@@ -0,0 +1,145 @@
+import { molarMass } from "./formula.mjs";
+import { balance } from "./equation.mjs";
+
+//#region src/chem/stoichiometry.ts
+/**
+* How much of what: limiting reagent, theoretical yield, and what is left over.
+*
+* ## The whole subject is one division
+*
+* Every quantitative question reduces to the same move. Convert what you have into moles, divide
+* each by its coefficient, and whichever comes out smallest runs out first. That ratio, the moles
+* available per unit of equation, is the only number that matters: it says how many times the
+* reaction as written can proceed, and everything else is that number multiplied by a coefficient.
+*
+* So {@link react} computes it once and reads every answer off it. There is no separate method for
+* limiting reagent, for yield, for excess: they are three questions about one quantity.
+*
+* ## The limiting reagent is not the one there is least of
+*
+* The most common mistake in the topic, and it is a mistake about what "least" means. Ten grams of
+* hydrogen and twenty-five of oxygen: there is less hydrogen by mass and far more by moles, and the
+* oxygen runs out first because the equation needs two hydrogens for every oxygen. Comparing masses
+* answers a question nobody asked, and comparing moles without dividing by the coefficients answers
+* a different wrong one.
+*
+* ## Yield is measured, and the theoretical figure is not a prediction of it
+*
+* The theoretical yield is what the equation permits. What comes out of a flask is always less:
+* some product stays in solution, some is lost in transfer, the reaction may not finish. So
+* {@link percentageYield} takes a measured mass and compares, and a yield above a hundred per cent
+* is refused rather than reported, because it means the product is wet or impure and the useful
+* answer is to say so.
+*
+* Pure: no React, no pixels.
+*/
+/** Moles of a substance from however it was given. */
+function molesOf(formula, amount) {
+	if (amount.moles !== void 0) return amount.moles;
+	if (amount.mass !== void 0) return amount.mass / molarMass(formula);
+	if (amount.volumeDm3 !== void 0 && amount.concentration !== void 0) return amount.volumeDm3 * amount.concentration;
+	throw new Error(`not enough to work out the moles of ${formula}: give a mass, a number of moles, or a volume together with a concentration`);
+}
+/**
+* Work a reaction out from the amounts given.
+*
+* The equation is balanced here rather than taken on trust, because every mole ratio below depends
+* on the coefficients and an unbalanced equation would make all of them confidently wrong.
+*/
+function react(equation, amounts) {
+	const balanced = balance(equation);
+	const named = new Set(Object.keys(amounts));
+	const missing = balanced.reactants.filter((r) => !named.has(r.formula));
+	if (missing.length > 0) throw new Error(`no amount given for ${missing.map((r) => r.formula).join(" or ")}: every reactant needs one, since the limiting one cannot be found without them all`);
+	const withRuns = balanced.reactants.map((term) => {
+		const moles = molesOf(term.formula, amounts[term.formula]);
+		return {
+			term,
+			moles,
+			equationRuns: moles / term.coefficient
+		};
+	});
+	const runs = Math.min(...withRuns.map((r) => r.equationRuns));
+	const limitingRuns = runs;
+	const reactants = withRuns.map(({ term, moles, equationRuns }) => ({
+		formula: term.formula,
+		coefficient: term.coefficient,
+		moles,
+		equationRuns,
+		limiting: equationRuns === limitingRuns,
+		leftOver: moles - limitingRuns * term.coefficient
+	}));
+	return {
+		equation: balanced,
+		runs,
+		reactants,
+		products: balanced.products.map((term) => ({
+			formula: term.formula,
+			coefficient: term.coefficient,
+			moles: runs * term.coefficient,
+			mass: runs * term.coefficient * molarMass(term.formula)
+		})),
+		limiting: reactants.find((r) => r.limiting)
+	};
+}
+/** The most of a product the equation allows, in grams. */
+function theoreticalYield(reaction, product) {
+	const found = reaction.products.find((p) => p.formula === product);
+	if (!found) throw new Error(`${product} is not a product of this reaction: it makes ${reaction.products.map((p) => p.formula).join(", ")}`);
+	return found.mass;
+}
+/**
+* The measured mass as a percentage of the theoretical one, whatever it comes to.
+*
+* Reports rather than refuses, because a figure above a hundred per cent is a real thing that comes
+* out of a real balance and is the single most useful measurement in the topic: it is the one that
+* tells you something is wrong with the sample. A lab teaching that has to be able to SHOW 112 per
+* cent before asking what it means.
+*
+* What it must not do is call that a yield. So the number comes back with the reason it is not one
+* attached, and {@link percentageYield} is the strict form built on this for the places where the
+* value has to be legitimate.
+*/
+function apparentYield(theoretical, measured) {
+	if (theoretical <= 0) throw new Error("a theoretical yield of zero has no percentage");
+	if (measured < 0) throw new Error("a measured mass cannot be negative");
+	const percent = measured / theoretical * 100;
+	if (percent > 100.0001) return {
+		percent,
+		impossible: `${measured} g is ${percent.toFixed(1)} per cent of the ${theoretical.toFixed(3)} g the equation allows. A reaction cannot make more than its theoretical maximum, so the product is wet or impure, or the balance is wrong.`
+	};
+	return { percent };
+}
+/**
+* The fraction of the theoretical yield actually obtained, as a percentage.
+*
+* Refuses anything above a hundred. A flask cannot produce more than the equation allows, so a
+* figure above it is evidence about the sample rather than about the reaction, and reporting it as
+* a yield hides the one piece of information the number actually carries. Use {@link apparentYield}
+* where that figure needs to be shown rather than accepted.
+*/
+function percentageYield(theoretical, measured) {
+	const report = apparentYield(theoretical, measured);
+	if (report.impossible) throw new Error(report.impossible);
+	return report.percent;
+}
+/**
+* The mass of one reactant needed to use up a given amount of another exactly.
+*
+* What a preparation asks: how much of this do I weigh out so nothing is wasted.
+*/
+function amountNeeded(equation, have, want) {
+	const balanced = balance(equation);
+	const from = balanced.reactants.find((r) => r.formula === have.formula);
+	const to = balanced.reactants.find((r) => r.formula === want);
+	if (!from) throw new Error(`${have.formula} is not a reactant in this equation`);
+	if (!to) throw new Error(`${want} is not a reactant in this equation`);
+	const moles = molesOf(have.formula, have.amount) / from.coefficient * to.coefficient;
+	return {
+		moles,
+		mass: moles * molarMass(want)
+	};
+}
+
+//#endregion
+export { amountNeeded, apparentYield, molesOf, percentageYield, react, theoreticalYield };