@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/formula.mjs

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

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

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

package/dist/chem/functional-groups.mjs

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

package/dist/chem/hazard.d.mts

@@ -0,0 +1,94 @@
+//#region src/chem/hazard.d.ts
+/**
+ * hazard, what a reagent does to you and the precaution that follows from it.
+ *
+ * ## Why this is a kernel and not a sticker on each lab
+ *
+ * Our labs put learners in front of concentrated ammonia, acidified manganate(VII) and nickel salts
+ * and said nothing about any of them. A simulation that teaches a learner to reach for a reagent
+ * without ever meeting its hazard has taught half of a practical skill, and the missing half is the
+ * half that hurts.
+ *
+ * Hazard is a property of a SUBSTANCE, so it is declared once here and read by whoever needs it. A
+ * warning written into each lab would drift, would be missing wherever someone forgot, and could
+ * never be checked.
+ *
+ * ## The three-part statement, enforced by the type
+ *
+ * An examiner credits a hazard statement only when it names three things: the substance, its
+ * specific hazard, and a precaution that FOLLOWS from that hazard. "Wear safety goggles and a lab
+ * coat" is what almost every candidate writes and it scores nothing, because it is true of every
+ * experiment ever performed and therefore says nothing about this one.
+ *
+ * So a `Hazard` cannot be constructed without all three parts, and {@link isGenericPrecaution}
+ * exists to refuse the ones that score nothing. A test asserts that no precaution in this file is
+ * generic, which means the data cannot quietly rot into a list of goggles.
+ *
+ * ## Concentration is part of the identity
+ *
+ * Dilute sulfuric acid is an irritant. Concentrated sulfuric acid is corrosive and reacts violently
+ * with water. They are different entries here, because a learner who writes "corrosive" for the
+ * dilute acid in a Paper 5 answer has not scored: the statement has to match the concentration that
+ * was planned.
+ *
+ * ## What this is not
+ *
+ * Teaching data, matched to what a school laboratory actually does and to what a mark scheme
+ * credits. It is not a risk assessment, and nothing here replaces the one a real practical needs.
+ *
+ * Pure: no React, no pixels.
+ */
+/** The GHS classes a school syllabus uses by name. */
+type HazardClass = 'corrosive' | 'irritant' | 'flammable' | 'toxic' | 'harmful' | 'oxidising' | 'explosive' | 'carcinogenic' | 'environmental';
+interface Hazard {
+  readonly hazard: HazardClass;
+  /** What the substance does, in the words a mark scheme credits. */
+  readonly statement: string;
+  /**
+   * The precaution that follows from THIS hazard.
+   *
+   * Never a generic one. A precaution that would be true of any experiment is not creditable and,
+   * more to the point, does not change what the learner does next.
+   */
+  readonly precaution: string;
+}
+/** How the reagent is supplied, because the hazard depends on it. */
+type Strength = 'dilute' | 'concentrated' | 'solid' | 'gas' | 'solution';
+interface Reagent {
+  readonly id: string;
+  /** As a learner would write it in a method. */
+  readonly name: string;
+  readonly formula: string;
+  readonly strength: Strength;
+  readonly hazards: readonly Hazard[];
+}
+/**
+ * True when a precaution is one of the generic ones and would score nothing on its own.
+ *
+ * Note the "on its own": gloves are a real precaution when they follow from a named corrosive
+ * substance, which is why the entries below that use them say what they are for.
+ */
+declare const isGenericPrecaution: (text: string) => boolean;
+/**
+ * The reagents our chemistry labs actually put in a learner's hand.
+ *
+ * Added to when a lab needs one, never speculatively: an entry nobody reads is an entry nobody
+ * checks.
+ */
+declare const REAGENTS: readonly Reagent[];
+declare const reagentById: (id: string) => Reagent | undefined;
+/** Every reagent carrying a given hazard class, for a lesson that groups by hazard. */
+declare const reagentsWith: (hazard: HazardClass) => Reagent[];
+/**
+ * The creditable sentence: substance, hazard, precaution.
+ *
+ * Built rather than authored, so that every lab and every lesson states a hazard the same way and
+ * a learner meets the same three-part shape every time. That repetition is the teaching: the shape
+ * of the sentence is what the exam pays for.
+ */
+declare const hazardSentence: (reagent: Reagent, hazard: Hazard) => string;
+/** Every creditable sentence for a reagent. */
+declare const hazardSentences: (reagent: Reagent) => string[];
+declare function worstHazard(reagent: Reagent): Hazard;
+//#endregion
+export { Hazard, HazardClass, REAGENTS, Reagent, Strength, hazardSentence, hazardSentences, isGenericPrecaution, reagentById, reagentsWith, worstHazard };