@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/cycle.mjs

@@ -0,0 +1,145 @@
+import { calc } from "../core/worked.mjs";
+import { Quantity, qty } from "../quantity/index.mjs";
+
+//#region src/chem/cycle.ts
+/**
+* cycle, an energy cycle: a list of steps whose enthalpies must sum to a known total.
+*
+* This is Hess's law as a data structure. The law says the enthalpy change between two states does
+* not depend on the route, so any two routes between the same states sum to the same number:
+*
+*     ΔH(step 1) + ΔH(step 2) + … + ΔH(step n)  =  ΔH(overall)
+*
+* Exactly one term may be unknown, anywhere in the cycle INCLUDING the total, and the kernel
+* returns it. That single rule covers three different-looking exam questions:
+*
+*   • Born-Haber      — every step known except the lattice energy.
+*   • Hess's law      — the route is known and the overall change is wanted.
+*   • enthalpy of formation from combustion data — the total is known and one step is not.
+*
+* WHY A CYCLE IS NOT A `relation`. A relation has a fixed set of named variables. A cycle has an
+* arbitrary number of steps whose only constraint is that they sum, so expressing it as a relation
+* would mean one relation per cycle shape: one for NaCl, another for MgCl₂, another for MgO.
+*
+* SIGN CONVENTION, which is where the marks are lost. Every value is the enthalpy change for the
+* step AS WRITTEN, left to right, with exothermic negative. So the electron affinity of chlorine is
+* −349 kJ mol⁻¹ and the lattice energy of NaCl is −787 kJ mol⁻¹, both being formation processes.
+* A step written in the reverse direction takes the opposite sign, and `reversed` on a term says so
+* explicitly rather than leaving the author to flip it by hand and hope.
+*
+* STOICHIOMETRY. `per` multiplies a step, because a Born-Haber cycle for MgCl₂ needs two chlorine
+* atomisations and two electron affinities. Writing `per: 2` keeps the per-mole datum visible in the
+* working, which is what the mark scheme wants to see; writing 244 instead of 2 × 122 hides it.
+*
+* Pure: no React, no pixels.
+*/
+/** kJ mol⁻¹ is what every data book and every mark scheme uses. */
+const DEFAULT_CYCLE_UNIT = "kJ/mol";
+const known = (t) => t.value !== void 0;
+var Cycle = class {
+	title;
+	unit;
+	route;
+	total;
+	constructor(spec) {
+		this.unit = spec.unit ?? "kJ/mol";
+		this.title = spec.title ?? "energy cycle";
+		this.route = spec.route;
+		this.total = spec.total;
+		if (!spec.route.length) throw new Error(`${this.title}: a cycle needs at least one step.`);
+		const unknowns = [...spec.route, spec.total].filter((t) => !known(t));
+		if (unknowns.length > 1) throw new Error(`${this.title}: ${unknowns.length} unknown terms (${unknowns.map((t) => t.label).join(", ")}). A cycle determines exactly one.`);
+		for (const t of spec.route) if (t.per !== void 0 && (!Number.isFinite(t.per) || t.per === 0)) throw new Error(`${this.title}: "${t.label}" has per = ${t.per}, which is not a count of steps.`);
+	}
+	/** The signed contribution of a term, in `this.unit`, with `per` and `reversed` applied. */
+	contribution(term) {
+		if (term.value === void 0) throw new Error(`${this.title}: "${term.label}" has no value.`);
+		return (term.value instanceof Quantity ? term.value.in(this.unit) : term.value) * (term.per ?? 1) * (term.reversed ? -1 : 1);
+	}
+	/** Sum of the steps that have values. */
+	sumKnownSteps() {
+		return this.route.filter(known).reduce((acc, t) => acc + this.contribution(t), 0);
+	}
+	/**
+	* The one unknown term.
+	*
+	* If a step is unknown: step = total − (the other steps).
+	* If the total is unknown: total = the sum of the steps.
+	*/
+	solve() {
+		const missingStep = this.route.find((t) => !known(t));
+		const totalKnown = known(this.total);
+		if (!missingStep && totalKnown) throw new Error(`${this.title}: every term is known, so there is nothing to solve. Use residual() to check consistency.`);
+		if (!totalKnown) {
+			const value = this.sumKnownSteps();
+			return this.report(this.total, value, true);
+		}
+		const per = missingStep.per ?? 1;
+		const sign = missingStep.reversed ? -1 : 1;
+		const value = (this.contribution(this.total) - this.sumKnownSteps()) / per * sign;
+		return this.report(missingStep, value, false);
+	}
+	report(term, value, isTotal) {
+		return {
+			label: term.label,
+			value,
+			unit: this.unit,
+			quantity: qty(value, this.unit),
+			exothermic: value < 0,
+			isTotal
+		};
+	}
+	/**
+	* With every term known, how far the route misses the total by.
+	*
+	* Zero is a cycle that is self-consistent. This is the check worth running over an authored
+	* lesson: five data-book enthalpies and a quoted formation enthalpy that do NOT close to within a
+	* kilojoule mean one of the six numbers is wrong, and the lesson cannot say which.
+	*/
+	residual() {
+		if (!known(this.total)) throw new Error(`${this.title}: the total is unknown, so use solve().`);
+		const missing = this.route.find((t) => !known(t));
+		if (missing) throw new Error(`${this.title}: "${missing.label}" is unknown, so use solve().`);
+		return this.sumKnownSteps() - this.contribution(this.total);
+	}
+	/** True when the cycle closes to within `tol` (default 1 kJ/mol, the data-book rounding). */
+	closes(tol = 1) {
+		return Math.abs(this.residual()) <= tol;
+	}
+	/**
+	* The working: every step with its sign, then the rearrangement and the answer.
+	*
+	* A `per` factor is shown as `2 × 122`, not as `244`, because the per-mole datum is the thing the
+	* mark scheme wants to see quoted.
+	*/
+	steps(sf = 4) {
+		const solved = this.solve();
+		const w = calc().step(`\\sum \\Delta H(\\text{route}) = \\Delta H(\\text{overall})`, `${this.title}: Hess's law, so the route and the direct change agree`);
+		for (const t of this.route) {
+			const per = t.per ?? 1;
+			if (!known(t)) {
+				w.step(`${tex(t.label)} = ?`, "the unknown");
+				continue;
+			}
+			const base = t.value instanceof Quantity ? t.value.in(this.unit) : t.value;
+			const shown = per === 1 ? fmt(base, sf) : `${per} \\times ${fmt(base, sf)}`;
+			w.step(`${tex(t.label)} = ${shown}\\ \\mathrm{${this.unit}}`, t.reversed ? "quoted for the reverse step, so the sign flips" : void 0);
+		}
+		if (known(this.total)) {
+			w.step(`${tex(this.total.label)} = ${fmt(this.contribution(this.total), sf)}\\ \\mathrm{${this.unit}}`, "the overall change");
+			w.step(`${tex(solved.label)} = ${fmt(this.contribution(this.total), sf)} - (${fmt(this.sumKnownSteps(), sf)})`, "the unknown step is the overall change minus the rest of the route");
+		}
+		w.step(`${tex(solved.label)} = ${fmt(solved.value, sf)}\\ \\mathrm{${this.unit}}`, solved.exothermic ? "negative, so the step is exothermic" : "positive, so the step is endothermic");
+		return w.done(solved.value);
+	}
+};
+const tex = (label) => `\\Delta H(\\text{${label}})`;
+function fmt(value, sf) {
+	if (!Number.isFinite(value)) return "\\text{?}";
+	return String(Number(value.toPrecision(sf)));
+}
+/** `cycle({ route: [...], total: {...} })`. */
+const cycle = (spec) => new Cycle(spec);
+
+//#endregion
+export { Cycle, DEFAULT_CYCLE_UNIT, cycle };

package/dist/chem/equation.d.mts

@@ -0,0 +1,86 @@
+//#region src/chem/equation.d.ts
+/**
+ * Balancing a chemical equation, by solving it rather than by trial and error.
+ *
+ * ## Balancing is linear algebra, and saying so is the lesson
+ *
+ * Balancing is taught as inspection: try a number, see what breaks, adjust. That works for simple
+ * equations, fails on awkward ones, and teaches nothing about why an equation can be balanced at
+ * all. It is actually a small linear system. Write one row per element and one column per species,
+ * with reactants positive and products negative, and a balanced equation is any vector of
+ * coefficients the matrix sends to zero:
+ *
+ *     Fe 3a - c = 0
+ *     O  4a - 2d = 0       for  a Fe3O4 + b CO -> c Fe + d CO2
+ *     C  b - d = 0
+ *
+ * So the coefficients are the null space of the element matrix, and the smallest whole-number
+ * answer is that vector cleared of fractions. Conservation of atoms is not a rule applied to the
+ * arithmetic, it IS the arithmetic.
+ *
+ * It also explains the cases inspection cannot. A system with no non-zero solution is an equation
+ * that cannot be balanced, which is a real answer and usually means a species is missing. A system
+ * with more than one independent solution is an equation that can be balanced in more than one way,
+ * which is also real and means the reaction as written is really two reactions.
+ *
+ * ## Exact arithmetic, because floating point cannot be trusted with this
+ *
+ * The elimination runs on fractions held as a numerator and a denominator, not on doubles. A
+ * coefficient is a whole number or the equation is wrong, and a solver that produced 2.9999999998
+ * would either have to round, which hides a genuine failure, or refuse a correct equation. Integers
+ * throughout means the answer is exactly right or honestly rejected.
+ *
+ * Pure: no React, no pixels.
+ */
+/** One species in an equation, with the coefficient balancing gave it. */
+interface Term {
+  readonly formula: string;
+  readonly coefficient: number;
+}
+interface BalancedEquation {
+  readonly reactants: readonly Term[];
+  readonly products: readonly Term[];
+  /** The elements the balance was solved over. */
+  readonly elements: readonly string[];
+}
+/** Split "a + b -> c + d" into its two sides, accepting the arrows people actually type. */
+declare function splitEquation(input: string): {
+  left: string[];
+  right: string[];
+};
+/**
+ * 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.
+ */
+declare function balance(input: string): BalancedEquation;
+/** Write a balanced equation out, leaving a coefficient of one unwritten. */
+declare function formatEquation(equation: BalancedEquation, arrow?: string): string;
+/**
+ * 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.
+ */
+declare function atomTally(equation: BalancedEquation): {
+  element: string;
+  left: number;
+  right: number;
+}[];
+/**
+ * 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.
+ */
+declare function chargeTally(equation: BalancedEquation): {
+  left: number;
+  right: number;
+};
+//#endregion
+export { BalancedEquation, Term, atomTally, balance, chargeTally, formatEquation, splitEquation };

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