@classytic/stage 0.2.0 → 0.4.0

package/dist/chem/redox.mjs

@@ -0,0 +1,328 @@
+//#region src/chem/redox.ts
+/** Parse `'Cr2O7^2-'` into its element counts and charge. See the docblock on the caret rule. */
+function parseSpecies(input) {
+	const formula = input.trim();
+	if (!formula) throw new Error("Empty species");
+	let body = formula;
+	let charge = 0;
+	const caret = body.lastIndexOf("^");
+	if (caret >= 0) {
+		const tail = body.slice(caret + 1);
+		const m = /^(\d*)([+-])$/.exec(tail);
+		if (!m) throw new Error(`Cannot read the charge "${tail}" in "${formula}". Write it as ^2- or ^3+.`);
+		charge = (m[1] ? Number(m[1]) : 1) * (m[2] === "+" ? 1 : -1);
+		body = body.slice(0, caret);
+	} else {
+		const m = /([+-])$/.exec(body);
+		if (m) {
+			charge = m[1] === "+" ? 1 : -1;
+			body = body.slice(0, body.length - 1);
+			if (/^[A-Z][a-z]?\d+$/.test(body)) {
+				const split = /^([A-Z][a-z]?)(\d+)$/.exec(body);
+				throw new Error(`"${formula}" is ambiguous: the ${split[2]} could be a subscript or the charge. Write it as "${split[1]}^${split[2]}${m[1]}".`);
+			}
+		}
+	}
+	const elements = {};
+	const add = (symbol, n) => {
+		elements[symbol] = (elements[symbol] ?? 0) + n;
+	};
+	const walk = (text, multiplier) => {
+		let i = 0;
+		while (i < text.length) {
+			if (text[i] === "(") {
+				let depth = 1;
+				let j = i + 1;
+				while (j < text.length && depth > 0) {
+					if (text[j] === "(") depth++;
+					if (text[j] === ")") depth--;
+					j++;
+				}
+				if (depth !== 0) throw new Error(`Unclosed bracket in "${formula}"`);
+				const inner = text.slice(i + 1, j - 1);
+				const digits = /^\d+/.exec(text.slice(j));
+				walk(inner, multiplier * (digits ? Number(digits[0]) : 1));
+				i = j + (digits ? digits[0].length : 0);
+				continue;
+			}
+			const sym = /^[A-Z][a-z]?/.exec(text.slice(i));
+			if (!sym) throw new Error(`Cannot read "${text.slice(i)}" in "${formula}"`);
+			i += sym[0].length;
+			const digits = /^\d+/.exec(text.slice(i));
+			const count = digits ? Number(digits[0]) : 1;
+			i += digits ? digits[0].length : 0;
+			add(sym[0], count * multiplier);
+		}
+	};
+	walk(body, 1);
+	return {
+		formula,
+		elements,
+		charge
+	};
+}
+const ALWAYS = {
+	F: -1,
+	Li: 1,
+	Na: 1,
+	K: 1,
+	Rb: 1,
+	Cs: 1,
+	Be: 2,
+	Mg: 2,
+	Ca: 2,
+	Sr: 2,
+	Ba: 2
+};
+/**
+* Oxidation number of every element in a species.
+*
+* `peroxide` forces O to −1, for H₂O₂ and its salts. It is an argument rather than a detection
+* rule, because H₂O₂ and H₂O differ only in a subscript and guessing from the formula would make
+* the kernel wrong in exactly the case the syllabus asks about.
+*/
+function oxidationNumbers(input, opts = {}) {
+	const species = typeof input === "string" ? parseSpecies(input) : input;
+	const symbols = Object.keys(species.elements);
+	if (symbols.length === 1 && species.charge === 0) return { [symbols[0]]: 0 };
+	if (symbols.length === 1 && species.elements[symbols[0]] === 1) return { [symbols[0]]: species.charge };
+	const known = {};
+	const unknown = [];
+	for (const symbol of symbols) if (symbol in ALWAYS) known[symbol] = ALWAYS[symbol];
+	else if (symbol === "O") known.O = opts.peroxide ? -1 : -2;
+	else if (symbol === "H") known.H = opts.hydride ? -1 : 1;
+	else unknown.push(symbol);
+	if (unknown.length === 0) return known;
+	if (unknown.length > 1) throw new Error(`"${species.formula}" has ${unknown.length} elements with no fixed oxidation number (${unknown.join(", ")}), so none of them is determined. Split the species or state one.`);
+	const target = unknown[0];
+	let sum = 0;
+	for (const [symbol, value] of Object.entries(known)) sum += value * species.elements[symbol];
+	known[target] = (species.charge - sum) / species.elements[target];
+	return known;
+}
+const SUPER = {
+	"0": "⁰",
+	"1": "¹",
+	"2": "²",
+	"3": "³",
+	"4": "⁴",
+	"5": "⁵",
+	"6": "⁶",
+	"7": "⁷",
+	"8": "⁸",
+	"9": "⁹",
+	"+": "⁺",
+	"-": "⁻"
+};
+const SUB = {
+	"0": "₀",
+	"1": "₁",
+	"2": "₂",
+	"3": "₃",
+	"4": "₄",
+	"5": "₅",
+	"6": "₆",
+	"7": "₇",
+	"8": "₈",
+	"9": "₉"
+};
+/**
+* `'Cr2O7^2-'` → `'Cr₂O₇²⁻'`, for display.
+*
+* The caret is an input convention forced by ASCII ambiguity, and a learner should never see it.
+*
+* ## The one place the caret is not needed
+*
+* After a closing bracket. `[Cu(H2O)6]2+` has no ambiguity at all, because a digit cannot be the
+* subscript of a `]`, and that is the form `complexFormula` emits. Without this case a complex ion
+* came back as `[Cu(H₂O)₆]₂⁺`, with its charge written as a subscript: the same class of defect as a
+* formatter producing a string its sibling parser cannot read.
+*/
+function speciesToUnicode(formula) {
+	const bracketed = /^(.*\])(\d+)([+-])$/.exec(formula);
+	if (bracketed) return bracketed[1].replace(/\d/g, (d) => SUB[d]) + ([...bracketed[2]].map((d) => SUPER[d]).join("") + SUPER[bracketed[3]]);
+	const caret = formula.lastIndexOf("^");
+	const body = caret >= 0 ? formula.slice(0, caret) : formula.replace(/[+-]+$/, "");
+	const tail = caret >= 0 ? formula.slice(caret + 1) : /[+-]+$/.exec(formula)?.[0] ?? "";
+	return body.replace(/\d/g, (d) => SUB[d]) + [...tail].map((c) => SUPER[c] ?? c).join("");
+}
+/** Positive when oxidised, negative when reduced, for `element` between two species. */
+function oxidationChange(element, from, to) {
+	const a = oxidationNumbers(from)[element];
+	const b = oxidationNumbers(to)[element];
+	if (a === void 0 || b === void 0) throw new Error(`"${element}" is not in both ${from} and ${to}`);
+	return b - a;
+}
+const gcd = (a, b) => b === 0 ? Math.abs(a) : gcd(b, a % b);
+const WATER = parseSpecies("H2O");
+const PROTON = parseSpecies("H+");
+const HYDROXIDE = parseSpecies("OH-");
+const term = (coeff, species) => ({
+	coeff,
+	species
+});
+function countIn(terms, element) {
+	return terms.reduce((n, t) => n + t.coeff * (t.species.elements[element] ?? 0), 0);
+}
+const chargeOf = (terms) => terms.reduce((q, t) => q + t.coeff * t.species.charge, 0);
+/**
+* Balance one half-equation, in acid or in alkali.
+*
+* `balanceHalf('MnO4-', 'Mn2+')` → MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O.
+*
+* Alkali is not a second procedure: the equation is balanced in acid and then neutralised, which is
+* exactly what a mark scheme wants written.
+*/
+function balanceHalf(from, to, medium = "acid") {
+	const a = parseSpecies(from);
+	const b = parseSpecies(to);
+	const key = Object.keys(a.elements).filter((s) => s !== "O" && s !== "H");
+	let coeffA = 1;
+	let coeffB = 1;
+	for (const element of key) {
+		const inA = a.elements[element] ?? 0;
+		const inB = b.elements[element] ?? 0;
+		if (inA === 0 || inB === 0) continue;
+		const g = gcd(inA, inB);
+		coeffA = Math.max(coeffA, inB / g);
+		coeffB = Math.max(coeffB, inA / g);
+	}
+	let left = [term(coeffA, a)];
+	let right = [term(coeffB, b)];
+	const dO = countIn(left, "O") - countIn(right, "O");
+	if (dO > 0) right.push(term(dO, WATER));
+	else if (dO < 0) left.push(term(-dO, WATER));
+	const dH = countIn(left, "H") - countIn(right, "H");
+	if (dH > 0) right.push(term(dH, PROTON));
+	else if (dH < 0) left.push(term(-dH, PROTON));
+	const dQ = chargeOf(left) - chargeOf(right);
+	const electrons = Math.abs(dQ);
+	const electronSide = dQ > 0 ? "left" : "right";
+	if (medium === "alkali") {
+		const protons = [...left, ...right].find((t) => t.species.formula === "H+");
+		if (protons) {
+			const n = protons.coeff;
+			const protonsOnLeft = left.includes(protons);
+			left = left.filter((t) => t !== protons);
+			right = right.filter((t) => t !== protons);
+			if (protonsOnLeft) {
+				left.push(term(n, WATER));
+				right.push(term(n, HYDROXIDE));
+			} else {
+				right.push(term(n, WATER));
+				left.push(term(n, HYDROXIDE));
+			}
+			left = mergeWater(left);
+			right = mergeWater(right);
+			cancelWater(left, right);
+		}
+	}
+	return {
+		left: left.filter((t) => t.coeff > 0),
+		right: right.filter((t) => t.coeff > 0),
+		electrons,
+		electronSide,
+		medium
+	};
+}
+function mergeWater(terms) {
+	const water = terms.filter((t) => t.species.formula === "H2O");
+	if (water.length < 2) return terms;
+	const total = water.reduce((n, t) => n + t.coeff, 0);
+	return [...terms.filter((t) => t.species.formula !== "H2O"), term(total, WATER)];
+}
+/** Water on both sides cancels, which is the tidying step a mark scheme expects. */
+function cancelWater(left, right) {
+	const l = left.findIndex((t) => t.species.formula === "H2O");
+	const r = right.findIndex((t) => t.species.formula === "H2O");
+	if (l < 0 || r < 0) return;
+	const shared = Math.min(left[l].coeff, right[r].coeff);
+	left[l] = term(left[l].coeff - shared, WATER);
+	right[r] = term(right[r].coeff - shared, WATER);
+	if (left[l].coeff === 0) left.splice(l, 1);
+	const r2 = right.findIndex((t) => t.species.formula === "H2O" && t.coeff === 0);
+	if (r2 >= 0) right.splice(r2, 1);
+}
+/**
+* "MnO₄⁻ + 8H⁺ + 5e⁻ → Mn²⁺ + 4H₂O", for display.
+*
+* Built from the TERMS, not by running `speciesToUnicode` over the finished string. That was tried
+* and is wrong: a coefficient is a normal-size number and a separator is a plus sign, so formatting
+* the whole line turns `2Cr^3+ + 7H2O` into subscripted coefficients and superscripted plus signs.
+* Chemistry typography is per-species, so the formatter has to be too.
+*/
+function halfToUnicode(half) {
+	const side = (terms, withElectrons) => {
+		const parts = terms.map((t) => (t.coeff === 1 ? "" : String(t.coeff)) + speciesToUnicode(t.species.formula));
+		if (withElectrons && half.electrons > 0) parts.push((half.electrons === 1 ? "" : String(half.electrons)) + "e⁻");
+		return parts.join(" + ");
+	};
+	return `${side(half.left, half.electronSide === "left")} → ${side(half.right, half.electronSide === "right")}`;
+}
+/** "MnO₄⁻ + 8H⁺ + 5Fe²⁺ → Mn²⁺ + 4H₂O + 5Fe³⁺", for display. */
+function ionicToUnicode(equation) {
+	const side = (terms) => terms.map((t) => (t.coeff === 1 ? "" : String(t.coeff)) + speciesToUnicode(t.species.formula)).join(" + ");
+	return `${side(equation.left)} → ${side(equation.right)}`;
+}
+/** "MnO4- + 8H+ + 5e- -> Mn2+ + 4H2O" */
+function halfToString(half) {
+	const side = (terms, withElectrons) => {
+		const parts = terms.map((t) => t.coeff === 1 ? t.species.formula : `${t.coeff}${t.species.formula}`);
+		if (withElectrons && half.electrons > 0) parts.push(half.electrons === 1 ? "e-" : `${half.electrons}e-`);
+		return parts.join(" + ");
+	};
+	return `${side(half.left, half.electronSide === "left")} -> ${side(half.right, half.electronSide === "right")}`;
+}
+/**
+* Combine a reduction and an oxidation into the full ionic equation.
+*
+* Each half is scaled so the electrons cancel exactly, which is the step the whole topic exists to
+* teach: electrons are not created, so the number lost must equal the number gained.
+*/
+function combineHalves(a, b) {
+	const reduction = a.electronSide === "left" ? a : b;
+	const oxidation = a.electronSide === "left" ? b : a;
+	if (reduction.electronSide !== "left" || oxidation.electronSide !== "right") throw new Error("combineHalves needs one reduction and one oxidation, not two of the same.");
+	const g = gcd(reduction.electrons, oxidation.electrons) || 1;
+	const lcm = reduction.electrons * oxidation.electrons / g;
+	const scaleR = lcm / reduction.electrons;
+	const scaleO = lcm / oxidation.electrons;
+	const scale = (terms, by) => terms.map((t) => term(t.coeff * by, t.species));
+	const left = collect([...scale(reduction.left, scaleR), ...scale(oxidation.left, scaleO)]);
+	const right = collect([...scale(reduction.right, scaleR), ...scale(oxidation.right, scaleO)]);
+	cancelCommon(left, right);
+	return {
+		left,
+		right,
+		transferred: lcm
+	};
+}
+function collect(terms) {
+	const out = [];
+	for (const t of terms) {
+		const found = out.findIndex((u) => u.species.formula === t.species.formula);
+		if (found >= 0) out[found] = term(out[found].coeff + t.coeff, t.species);
+		else out.push(t);
+	}
+	return out;
+}
+/** A species on both sides is a spectator of the combination and is cancelled. */
+function cancelCommon(left, right) {
+	for (let i = left.length - 1; i >= 0; i--) {
+		const j = right.findIndex((t) => t.species.formula === left[i].species.formula);
+		if (j < 0) continue;
+		const shared = Math.min(left[i].coeff, right[j].coeff);
+		left[i] = term(left[i].coeff - shared, left[i].species);
+		right[j] = term(right[j].coeff - shared, right[j].species);
+		if (right[j].coeff === 0) right.splice(j, 1);
+		if (left[i].coeff === 0) left.splice(i, 1);
+	}
+}
+/** "2MnO4- + 16H+ + 10Fe2+ -> 2Mn2+ + 8H2O + 10Fe3+" */
+function ionicToString(equation) {
+	const side = (terms) => terms.map((t) => t.coeff === 1 ? t.species.formula : `${t.coeff}${t.species.formula}`).join(" + ");
+	return `${side(equation.left)} -> ${side(equation.right)}`;
+}
+
+//#endregion
+export { balanceHalf, combineHalves, halfToString, halfToUnicode, ionicToString, ionicToUnicode, oxidationChange, oxidationNumbers, parseSpecies, speciesToUnicode };

package/dist/chem/relations.d.mts

@@ -0,0 +1,183 @@
+import { Relation } from "../relation/index.mjs";
+
+//#region src/chem/relations.d.ts
+/** `n = m / M`, moles from a mass weighed out. */
+declare const molesFromMass: () => Relation;
+/** `n = c * V`, moles in a volume of solution. Give V in cm3 and the conversion looks after itself. */
+declare const molesFromSolution: () => Relation;
+/** `n = N / L`, moles from a number of particles. */
+declare const molesFromParticles: () => Relation;
+/**
+ * `n = V / Vm`, moles of a gas from its volume at a stated molar volume.
+ *
+ * The molar volume is a variable rather than a constant baked in, because it is not one: it depends
+ * on temperature and pressure, and quoting 22.4 dm3/mol without saying "at standard temperature and
+ * pressure" is where a great many wrong answers begin.
+ */
+declare const molesFromGasVolume: () => Relation;
+/** `P * V = n * R * T`, the ideal gas equation. Temperature in kelvin, as it must be. */
+declare const idealGas: () => Relation;
+/** `P1 * V1 / T1 = P2 * V2 / T2`, one gas under two sets of conditions. */
+declare const combinedGasLaw: () => Relation;
+/** `c = n / V`, concentration from moles and volume. */
+declare const concentration: () => Relation;
+/**
+ * `c1 * V1 = c2 * V2`, dilution.
+ *
+ * True because the moles do not change when water is added, which is the whole of the derivation
+ * and is worth saying every time it is used.
+ */
+declare const dilution: () => Relation;
+/** `m_conc = c * V * M`, the mass to weigh out to make up a standard solution. */
+declare const massForSolution: () => Relation;
+/**
+ * `b = n / m_solvent`, molality: moles of solute per kilogram of SOLVENT.
+ *
+ * Not per kilogram of solution, and not per litre of anything. The distinction from molarity is the
+ * point of having both: molality uses a mass, so it does not change when the temperature does,
+ * which is why it is the one that appears in freezing point and boiling point work.
+ */
+declare const molality: () => Relation;
+/** `rho = m / V`, density, which is what converts between a volume and a mass of solution. */
+declare const density: () => Relation;
+/**
+ * `A = eps * c * l`, the Beer-Lambert law.
+ *
+ * Absorbance is dimensionless: it is a logarithm of a ratio of intensities, so it has no unit, and
+ * the molar absorptivity carries whatever is needed to cancel the concentration and the path
+ * length. Declaring it that way is what lets the units check pass, and it is also the honest
+ * description of what absorbance is.
+ *
+ * Solving it for the concentration is the entire quantitative use of a colorimeter: measure the
+ * absorbance of a coloured solution, and read its concentration off.
+ */
+declare const beerLambert: () => Relation;
+/**
+ * `A = log10(I0 / I)`, absorbance from the light that went in and the light that came out.
+ *
+ * The definition the law above is built on, and the reason absorbance has no unit.
+ */
+declare const absorbanceFromIntensity: () => Relation;
+/** `q = m * c * dT`, the heat a measured temperature change accounts for. */
+declare const heatEnergy: () => Relation;
+/**
+ * The values these relations are usually fed, kept as data with their units attached.
+ *
+ * Passed in rather than compiled into the relations. A molar volume of 24 dm3/mol is only right at
+ * room temperature and 22.4 only at standard temperature and pressure, and a relation that hid
+ * either inside itself would give a confidently wrong answer under the other conditions.
+ */
+declare const CONSTANTS: {
+  /** Avogadro constant, per mole. */readonly avogadro: 6.02214076e+23; /** Molar gas constant, J per mole per kelvin. */
+  readonly gasConstant: number; /** Molar volume of an ideal gas at 273.15 K and 100 kPa, dm3 per mole. */
+  readonly molarVolumeStp: 22.7; /** Molar volume at 298 K and 100 kPa, dm3 per mole: the figure room-temperature questions use. */
+  readonly molarVolumeRoom: 24; /** Specific heat capacity of water, J per gram per kelvin. */
+  readonly waterHeatCapacity: 4.18;
+};
+/** Kelvin from degrees Celsius. One line, and the source of a great many wrong gas answers. */
+declare const kelvinFrom: (celsius: number) => number;
+/**
+ * The derivations, so a lesson can say why a formula is true and not only how to use it.
+ *
+ * Three kinds, and the difference between them is worth as much as the formulae. A definition has
+ * nothing underneath it. A derived relation follows from others plus something held fixed, and the
+ * chain is executable, so the claim is checked rather than asserted. A measured one was observed by
+ * somebody, and saying so is the difference between teaching chemistry and teaching a formula
+ * sheet.
+ */
+declare const DERIVATIONS: {
+  /**
+   * Dilution, the one everyone memorises and nobody can justify.
+   *
+   * The argument is three sentences long. Adding water changes the volume and changes the
+   * concentration, and does not change the number of moles. So `n = cV` holds at both ends with the
+   * same n, and that is the rule.
+   */
+  readonly dilution: {
+    readonly kind: "derived";
+    readonly summary: "Adding water changes how much there is of the solution and how concentrated it is, and changes nothing about how much solute is in it.";
+    readonly invariant: "the number of moles of solute, which water does not create or destroy";
+    readonly arrivesAt: "c2";
+    readonly steps: readonly [{
+      readonly relation: () => Relation;
+      readonly solveFor: "n";
+      readonly using: {
+        readonly c: "c1";
+        readonly V: "V1";
+      };
+      readonly gives: "n";
+      readonly because: "first find how many moles the stock solution you measured out actually contains";
+    }, {
+      readonly relation: () => Relation;
+      readonly solveFor: "c";
+      readonly using: {
+        readonly n: "n";
+        readonly V: "V2";
+      };
+      readonly gives: "c2";
+      readonly because: "those same moles are now spread through the larger volume, so the concentration is what they make up in it";
+    }];
+  };
+  /**
+   * The mass to weigh out for a standard solution.
+   *
+   * Two definitions laid end to end, which is worth showing because learners meet it as a third
+   * formula rather than as the two they already have.
+   */
+  readonly massForSolution: {
+    readonly kind: "derived";
+    readonly summary: "You cannot weigh out moles, so work out how many moles the solution needs and then what that many moles weigh.";
+    readonly invariant: "nothing is held fixed here: this is two definitions used one after the other";
+    readonly arrivesAt: "m";
+    readonly steps: readonly [{
+      readonly relation: () => Relation;
+      readonly solveFor: "n";
+      readonly using: {
+        readonly c: "c";
+        readonly V: "V";
+      };
+      readonly gives: "n";
+      readonly because: "the volume you are making up, at the concentration you want, needs this many moles";
+    }, {
+      readonly relation: () => Relation;
+      readonly solveFor: "m";
+      readonly using: {
+        readonly n: "n";
+        readonly M: "M";
+      };
+      readonly gives: "m";
+      readonly because: "and that many moles of this substance weigh this much, which is what goes on the balance";
+    }];
+  };
+  readonly concentration: {
+    readonly kind: "definition";
+    readonly summary: "Concentration is how many moles are dissolved in each unit of volume. That is what the word means.";
+  };
+  readonly molesFromMass: {
+    readonly kind: "definition";
+    readonly summary: "Molar mass is defined as the mass of one mole, so dividing a mass by it counts how many moles that mass is.";
+  };
+  /**
+   * The Beer-Lambert law, which is measured and is usually taught as though it were not.
+   *
+   * It is stated as a formula with no hint that anyone ever checked it, and it does in fact fail:
+   * at high concentrations absorbance stops rising in step, which is why a calibration curve is
+   * drawn and a sample too dark to read is diluted before it is measured.
+   */
+  readonly beerLambert: {
+    readonly kind: "measured";
+    readonly summary: "Each layer of a solution takes the same FRACTION of the light reaching it, so the light left falls away multiplicatively and its logarithm falls in step with both the concentration and the distance travelled.";
+    readonly evidence: "Measured: double the concentration of a coloured solution, or double the length of the cell, and the absorbance doubles. It stops holding at high concentrations, which is why a calibration curve is plotted rather than assumed and why a dark sample is diluted before it is read.";
+  };
+  readonly idealGas: {
+    readonly kind: "measured";
+    readonly summary: "Pressure times volume divided by temperature comes to the same thing for any gas, once there is enough of it to average over and the particles are far enough apart to ignore each other.";
+    readonly evidence: "Measured, and by three separate people on three separate pairs of variables before anyone combined them. It is a limit rather than a law: every real gas departs from it as it is compressed or cooled toward its boiling point, which is exactly when its particles stop being far apart.";
+  };
+  readonly heatEnergy: {
+    readonly kind: "definition";
+    readonly summary: "Specific heat capacity is defined as the energy one gram needs to warm by one kelvin, so the total is that energy times the grams times the kelvin.";
+  };
+};
+//#endregion
+export { CONSTANTS, DERIVATIONS, absorbanceFromIntensity, beerLambert, combinedGasLaw, concentration, density, dilution, heatEnergy, idealGas, kelvinFrom, massForSolution, molality, molesFromGasVolume, molesFromMass, molesFromParticles, molesFromSolution };