@classytic/stage 0.2.0 → 0.4.0

package/dist/chem/complex.mjs

@@ -0,0 +1,234 @@
+//#region src/chem/complex.ts
+/**
+* complex, the geometry and colour of a transition-metal complex ion.
+*
+* Three questions the syllabus asks about every complex, and they are all answered from the same
+* declaration: what shape is it, how many isomers has it, and why is it that colour.
+*
+* ## Coordination number is not the number of ligands
+*
+* It is the number of COORDINATE BONDS, so a bidentate ligand counts twice. That single sentence
+* settles a question learners routinely get wrong: [Cu(en)₂]²⁺ has two ligands and a coordination
+* number of four, and [Cr(C₂O₄)₃]³⁻ has three ligands and a coordination number of six.
+*
+* ## Why shape follows from the number and not from the metal, except when it does not
+*
+* Six is octahedral and two is linear, with no exceptions worth teaching. Four is the interesting
+* one: usually tetrahedral, but square planar for platinum and palladium. That is not a detail. A
+* square-planar complex shows cis-trans isomerism and a tetrahedral one CANNOT, because in a
+* tetrahedron every position is adjacent to every other, so there is no "opposite" to be trans to.
+*
+* Cisplatin is the case that matters: it is the cis isomer of a square-planar platinum complex and
+* it is a cancer drug, while the trans isomer is not. Had the geometry been tetrahedral there would
+* have been no two isomers to tell apart.
+*
+* ## Colour is what is NOT absorbed
+*
+* A d-block ion's d orbitals split, and the gap ΔE corresponds to a wavelength in the visible
+* range. The ion absorbs that wavelength and what reaches the eye is the rest, which is why copper
+* sulfate is blue BECAUSE it absorbs orange. Stating it the other way round, that it is blue
+* because it absorbs blue, is the commonest sentence in a wrong answer.
+*
+* Pure: no React, no pixels.
+*/
+/** Planck constant, J s. */
+const PLANCK = 6626e-37;
+/** Speed of light, m/s. */
+const LIGHT_SPEED = 2998e5;
+/** Avogadro constant, per mole. */
+const AVOGADRO = 6022e20;
+const ligand = (name, formula, charge, denticity = 1) => ({
+	name,
+	formula,
+	charge,
+	denticity
+});
+/** The ligands the syllabus actually uses. */
+const LIGANDS = {
+	water: ligand("water", "H2O", 0),
+	ammonia: ligand("ammonia", "NH3", 0),
+	chloride: ligand("chloride", "Cl", -1),
+	cyanide: ligand("cyanide", "CN", -1),
+	hydroxide: ligand("hydroxide", "OH", -1),
+	/** 1,2-diaminoethane, the standard neutral bidentate ligand. */
+	en: ligand("1,2-diaminoethane", "en", 0, 2),
+	/** Ethanedioate, the standard charged bidentate ligand. */
+	ethanedioate: ligand("ethanedioate", "C2O4", -2, 2)
+};
+/** Metals that are square planar at coordination number four. */
+const SQUARE_PLANAR = new Set(["Pt", "Pd"]);
+/** Coordinate bonds, NOT the number of ligands. A bidentate ligand counts twice. */
+const coordinationNumber = (spec) => spec.ligands.reduce((n, l) => n + l.count * l.ligand.denticity, 0);
+/** Overall charge: the metal's oxidation number plus every ligand's own charge. */
+const complexCharge = (spec) => spec.ligands.reduce((q, l) => q + l.count * l.ligand.charge, spec.oxidation);
+function geometryOf(spec) {
+	if (spec.geometry) return spec.geometry;
+	const n = coordinationNumber(spec);
+	if (n === 6) return "octahedral";
+	if (n === 2) return "linear";
+	if (n === 4) return SQUARE_PLANAR.has(spec.metal) ? "square-planar" : "tetrahedral";
+	throw new Error(`Coordination number ${n} for ${spec.metal} has no shape in this kernel. The syllabus uses 2, 4 and 6.`);
+}
+/** The bond angle a shape gives, in degrees. */
+function bondAngle(geometry) {
+	switch (geometry) {
+		case "linear": return 180;
+		case "tetrahedral": return 109.5;
+		case "square-planar": return 90;
+		case "octahedral": return 90;
+	}
+}
+/** `[Cu(H2O)6]2+`, with the charge written the way a data book writes it. */
+function complexFormula(spec) {
+	const inner = spec.ligands.map((l) => l.count === 1 ? `(${l.ligand.formula})` : `(${l.ligand.formula})${l.count}`).join("");
+	const q = complexCharge(spec);
+	const sign = q === 0 ? "" : q > 0 ? `${Math.abs(q) === 1 ? "" : Math.abs(q)}+` : `${Math.abs(q) === 1 ? "" : Math.abs(q)}-`;
+	return `[${spec.metal}${inner}]${sign}`;
+}
+/**
+* How many stereoisomers a complex has, and what kind.
+*
+* Covers the shapes the syllabus sets and refuses to guess beyond them. The important NEGATIVE
+* result is the tetrahedral one: no cis-trans isomerism at any composition, because a tetrahedron
+* has no two positions opposite each other.
+*/
+function stereoisomers(spec) {
+	const geometry = geometryOf(spec);
+	const mono = spec.ligands.filter((l) => l.ligand.denticity === 1);
+	const bi = spec.ligands.filter((l) => l.ligand.denticity === 2);
+	const counts = mono.map((l) => l.count).sort((a, b) => b - a);
+	const biTotal = bi.reduce((n, l) => n + l.count, 0);
+	if (geometry === "linear") return {
+		count: 1,
+		kinds: [],
+		reason: "Two ligands on a straight line have only one arrangement."
+	};
+	if (geometry === "tetrahedral") return {
+		count: 1,
+		kinds: [],
+		reason: "A tetrahedron has no two positions opposite each other, so there is nothing for a ligand to be trans to. Tetrahedral complexes show no cis-trans isomerism at all."
+	};
+	if (geometry === "square-planar") {
+		if (counts.length === 2 && counts[0] === 2 && counts[1] === 2) return {
+			count: 2,
+			kinds: ["cis", "trans"],
+			reason: "Two pairs in a square: the identical ligands are either adjacent (cis) or opposite (trans). This is the cisplatin case, where only the cis isomer is the drug."
+		};
+		return {
+			count: 1,
+			kinds: [],
+			reason: "Only one arrangement of these ligands in a square."
+		};
+	}
+	if (biTotal === 3) return {
+		count: 2,
+		kinds: ["optical pair"],
+		reason: "Three bidentate ligands around an octahedron make a propeller, and a propeller has a handedness. The two forms are non-superimposable mirror images."
+	};
+	if (biTotal === 2 && counts.length === 1 && counts[0] === 2) return {
+		count: 3,
+		kinds: ["cis (optical pair)", "trans"],
+		reason: "The two single ligands are adjacent or opposite. The trans form has a mirror plane; the cis form does not, so it is itself a pair of optical isomers. Two plus one is three."
+	};
+	if (counts.length === 2 && counts[0] === 4 && counts[1] === 2) return {
+		count: 2,
+		kinds: ["cis", "trans"],
+		reason: "The two odd ligands sit next to each other (cis) or on opposite corners (trans)."
+	};
+	if (counts.length === 2 && counts[0] === 3 && counts[1] === 3) return {
+		count: 2,
+		kinds: ["fac", "mer"],
+		reason: "Three and three: the matching set occupies one triangular face (fac) or a meridian running around the ion (mer)."
+	};
+	if (counts.length === 1) return {
+		count: 1,
+		kinds: [],
+		reason: "Six identical ligands have one arrangement."
+	};
+	return {
+		count: 1,
+		kinds: [],
+		reason: "No stereoisomerism for this combination in the cases the syllabus sets."
+	};
+}
+/** The splitting energy ΔE for light of this wavelength, in joules per photon. */
+const splittingEnergy = (wavelengthNm) => PLANCK * LIGHT_SPEED / (wavelengthNm * 1e-9);
+/** The same energy per mole, in kJ/mol, which is the form a question asks for. */
+const splittingEnergyPerMole = (wavelengthNm) => splittingEnergy(wavelengthNm) * AVOGADRO / 1e3;
+/** The wavelength whose photon energy is ΔE joules. */
+const wavelengthFor = (joules) => PLANCK * LIGHT_SPEED / joules / 1e-9;
+const WHEEL = [
+	{
+		from: 400,
+		to: 435,
+		absorbed: "violet",
+		seen: "yellow-green"
+	},
+	{
+		from: 435,
+		to: 480,
+		absorbed: "blue",
+		seen: "yellow"
+	},
+	{
+		from: 480,
+		to: 490,
+		absorbed: "green-blue",
+		seen: "orange"
+	},
+	{
+		from: 490,
+		to: 500,
+		absorbed: "blue-green",
+		seen: "red"
+	},
+	{
+		from: 500,
+		to: 560,
+		absorbed: "green",
+		seen: "purple"
+	},
+	{
+		from: 560,
+		to: 580,
+		absorbed: "yellow-green",
+		seen: "violet"
+	},
+	{
+		from: 580,
+		to: 595,
+		absorbed: "yellow",
+		seen: "blue"
+	},
+	{
+		from: 595,
+		to: 650,
+		absorbed: "orange",
+		seen: "blue-green"
+	},
+	{
+		from: 650,
+		to: 750,
+		absorbed: "red",
+		seen: "green-blue"
+	}
+];
+/**
+* What colour a solution looks, given the wavelength it absorbs.
+*
+* The answer is the COMPLEMENTARY colour, never the absorbed one. Copper sulfate absorbs orange
+* light at about 600 nm and therefore looks blue, and a learner who says it looks blue because it
+* absorbs blue has the physics exactly backwards.
+*/
+function observedColour(wavelengthNm) {
+	const band = WHEEL.find((b) => wavelengthNm >= b.from && wavelengthNm < b.to);
+	if (!band) throw new Error(`${wavelengthNm} nm is outside the visible range (400-750 nm), so the complex would look colourless.`);
+	return {
+		absorbed: band.absorbed,
+		seen: band.seen,
+		wavelengthNm
+	};
+}
+
+//#endregion
+export { AVOGADRO, LIGANDS, LIGHT_SPEED, PLANCK, bondAngle, complexCharge, complexFormula, coordinationNumber, geometryOf, observedColour, splittingEnergy, splittingEnergyPerMole, stereoisomers, wavelengthFor };

package/dist/chem/cycle.d.mts

@@ -0,0 +1,75 @@
+import { Quantity } from "../quantity/index.mjs";
+import { Worked } from "../core/worked.mjs";
+
+//#region src/chem/cycle.d.ts
+/** kJ mol⁻¹ is what every data book and every mark scheme uses. */
+declare const DEFAULT_CYCLE_UNIT = "kJ/mol";
+interface CycleTerm {
+  /** "first ionisation energy of Na". Shown in the working. */
+  readonly label: string;
+  /** The enthalpy change for this step as written. Omit for the unknown. */
+  readonly value?: number | Quantity;
+  /** Stoichiometric multiplier, e.g. 2 chlorine atomisations in MgCl₂. Default 1. */
+  readonly per?: number;
+  /** The datum is quoted for the REVERSE of the step as written, so negate it. */
+  readonly reversed?: boolean;
+}
+interface CycleSpec {
+  readonly title?: string;
+  /** Unit for bare numbers. Default kJ/mol. */
+  readonly unit?: string;
+  /** The route: the steps that must sum to the total. */
+  readonly route: readonly CycleTerm[];
+  /** The overall change the route must add up to. */
+  readonly total: CycleTerm;
+}
+interface CycleSolution {
+  readonly label: string;
+  readonly value: number;
+  readonly unit: string;
+  readonly quantity: Quantity;
+  /** Negative is exothermic, by the convention above. */
+  readonly exothermic: boolean;
+  /** True when the solved term was the overall change rather than a step. */
+  readonly isTotal: boolean;
+}
+declare class Cycle {
+  readonly title: string;
+  readonly unit: string;
+  readonly route: readonly CycleTerm[];
+  readonly total: CycleTerm;
+  constructor(spec: CycleSpec);
+  /** The signed contribution of a term, in `this.unit`, with `per` and `reversed` applied. */
+  contribution(term: CycleTerm): number;
+  /** Sum of the steps that have values. */
+  private sumKnownSteps;
+  /**
+   * 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(): CycleSolution;
+  private report;
+  /**
+   * 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(): number;
+  /** True when the cycle closes to within `tol` (default 1 kJ/mol, the data-book rounding). */
+  closes(tol?: number): boolean;
+  /**
+   * 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?: number): Worked;
+}
+/** `cycle({ route: [...], total: {...} })`. */
+declare const cycle: (spec: CycleSpec) => Cycle;
+//#endregion
+export { Cycle, CycleSolution, CycleSpec, CycleTerm, DEFAULT_CYCLE_UNIT, cycle };

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