@classytic/stage 0.3.0 → 0.4.0

package/dist/chem/synthesis.d.mts

@@ -0,0 +1,113 @@
+//#region src/chem/synthesis.d.ts
+/**
+ * synthesis, the functional-group map: every conversion as an edge, and a route as a path.
+ *
+ * WHAT THIS IS FOR. Every synthesis question in the AS and A2 papers has one form: convert X into
+ * Y, giving the reagents and conditions for each step. A learner who has memorised the reactions as
+ * a list still cannot answer it, because the question is not "what does an alcohol do" but "which
+ * sequence of things that alcohols do gets me to an ester". That is a path-finding problem, and the
+ * reason it feels hard is that a list is the wrong shape for it.
+ *
+ * Drawn as a graph the answer is computable: the groups are places, the reagents are roads, and a
+ * synthesis is a route. {@link findRoute} returns one, with the reagent and the condition for each
+ * step, so a lesson can state a route and have it CHECKED rather than asserted.
+ *
+ * ## Why the edges carry conditions and never omit them
+ *
+ * A route is not worth marks without them. `halogenoalkane -> alcohol` and
+ * `halogenoalkane -> alkene` are the same reagent, sodium hydroxide, and differ only in the
+ * solvent. An edge naming the reagent alone would make those two roads identical, which is exactly
+ * the confusion the elimination lesson exists to prevent. So `condition` is not optional.
+ *
+ * ## Why this is in stage and not in the lab that drew it
+ *
+ * It was written inside `labs/domains/chem/synthesis-route`, which meant the only thing that could
+ * ask a question of it was the figure sitting on top of it. A course could not verify a route it
+ * claimed, a second lab could not reuse the graph without copying it, and the most useful fact in
+ * the topic, that only two reactions change the number of carbon atoms, was computable but
+ * unreachable. Dependency direction decides where a shared function lives, and everything here
+ * points inward: the graph needs nothing from the lab, and the lab needs the graph.
+ *
+ * What stayed behind is presentation. Where a group sits on the map is a layout decision made by
+ * eye for legibility, and it is not chemistry.
+ *
+ * Pure: no React, no pixels.
+ */
+/** The functional groups an AS and A2 synthesis question moves between. */
+type GroupNode = 'alkane' | 'alkene' | 'halogenoalkane' | 'alcohol' | 'nitrile' | 'aldehyde' | 'ketone' | 'acid' | 'ester' | 'acyl-chloride' | 'arene' | 'nitroarene' | 'arylamine' | 'amine' | 'amide';
+/** What a learner calls the group. The name is chemistry; where it sits on a map is not. */
+declare const GROUP_LABELS: Readonly<Record<GroupNode, string>>;
+interface RouteEdge {
+  readonly from: GroupNode;
+  readonly to: GroupNode;
+  readonly reagent: string;
+  /** Never optional: the solvent and the temperature are the marks. */
+  readonly condition: string;
+  /** Does the carbon chain change length? Only two reactions here do. */
+  readonly changesChain?: boolean;
+  /** Which class of the starting group this needs, where it matters. */
+  readonly needs?: string;
+}
+declare const ROUTE_EDGES: readonly RouteEdge[];
+/** Every group the map knows, in the order the type declares them. */
+declare const GROUP_NODES: GroupNode[];
+/** Roads leaving a group. */
+declare const edgesFrom: (id: GroupNode) => readonly RouteEdge[];
+/** The road between two groups, if there is one. */
+declare const edgeBetween: (from: GroupNode, to: GroupNode) => RouteEdge | undefined;
+/** The roads along a path of groups, so a route can be read back as an answer. */
+declare function edgesAlong(path: readonly GroupNode[]): RouteEdge[];
+/**
+ * Shortest path length between two groups, by breadth-first search.
+ *
+ * `undefined` when no route exists, which is a real answer rather than a failure: a learner
+ * hunting for a reaction that does not exist is exactly what a route map is for.
+ */
+declare function shortestSteps(from: GroupNode, to: GroupNode): number | undefined;
+/** A synthesis, as a learner would have to write it out. */
+interface Route {
+  readonly path: readonly GroupNode[];
+  readonly steps: readonly RouteEdge[];
+  /** Does this route pass through a reaction that changes the number of carbon atoms? */
+  readonly changesChain: boolean;
+}
+/**
+ * One shortest route, with the reagent and condition for every step.
+ *
+ * This is the difference between a distance and an answer. A lesson claiming "alkene to carboxylic
+ * acid in three steps" can now be checked against the route the map actually gives, and the steps
+ * it returns are the marks.
+ *
+ * ## Why a plain breadth-first search was not enough
+ *
+ * Alkene to carboxylic acid has TWO routes of three steps. One hydrates and oxidises twice and
+ * keeps the carbon skeleton. The other goes through the nitrile, and a nitrile road adds a carbon,
+ * so it arrives at an acid ONE CARBON LONGER than the target. A search that returned whichever it
+ * reached first would hand a learner the wrong molecule half the time, and would do it silently,
+ * because both routes are three steps and both are real chemistry.
+ *
+ * So among equally short routes the chain-preserving one wins. A question that wants the longer
+ * chain says so, and {@link allRoutes} still has both.
+ */
+declare function findRoute(from: GroupNode, to: GroupNode): Route | undefined;
+/**
+ * Every route from one group to another within a step budget, shortest first.
+ *
+ * Exists because the shortest route is not always the best one, which is the single most arguable
+ * point in the topic. Esterifying an acid directly is one step and an equilibrium that stops well
+ * short; going via the acyl chloride is two steps and goes to completion. Both routes have to be
+ * on the table for that to be a judgement rather than a rule.
+ *
+ * `maxSteps` is capped at six, because the map's diameter is smaller than that and an uncapped
+ * enumeration on a cyclic graph does not terminate usefully.
+ */
+declare function allRoutes(from: GroupNode, to: GroupNode, maxSteps?: number): Route[];
+/**
+ * The reactions that change the number of carbon atoms.
+ *
+ * The most useful fact in the topic and the one that is invisible in a list: to reach a target with
+ * more carbons than the starting material, a route MUST pass through one of these.
+ */
+declare const chainChangingEdges: () => readonly RouteEdge[];
+//#endregion
+export { GROUP_LABELS, GROUP_NODES, GroupNode, ROUTE_EDGES, Route, RouteEdge, allRoutes, chainChangingEdges, edgeBetween, edgesAlong, edgesFrom, findRoute, shortestSteps };

package/dist/chem/synthesis.mjs

@@ -0,0 +1,281 @@
+//#region src/chem/synthesis.ts
+/** What a learner calls the group. The name is chemistry; where it sits on a map is not. */
+const GROUP_LABELS = {
+	alkane: "alkane",
+	alkene: "alkene",
+	halogenoalkane: "halogenoalkane",
+	alcohol: "alcohol",
+	nitrile: "nitrile",
+	aldehyde: "aldehyde",
+	ketone: "ketone",
+	acid: "carboxylic acid",
+	ester: "ester",
+	"acyl-chloride": "acyl chloride",
+	arene: "arene",
+	nitroarene: "nitroarene",
+	arylamine: "aromatic amine",
+	amine: "amine",
+	amide: "amide"
+};
+const ROUTE_EDGES = [
+	{
+		from: "alkane",
+		to: "halogenoalkane",
+		reagent: "Cl₂ or Br₂",
+		condition: "ultraviolet light"
+	},
+	{
+		from: "alkene",
+		to: "halogenoalkane",
+		reagent: "HBr",
+		condition: "room temperature"
+	},
+	{
+		from: "alkene",
+		to: "alcohol",
+		reagent: "steam",
+		condition: "300 °C, 60 atm, H₃PO₄ catalyst"
+	},
+	{
+		from: "halogenoalkane",
+		to: "alcohol",
+		reagent: "NaOH",
+		condition: "aqueous, warm"
+	},
+	{
+		from: "halogenoalkane",
+		to: "alkene",
+		reagent: "NaOH",
+		condition: "in ethanol, hot, under reflux"
+	},
+	{
+		from: "halogenoalkane",
+		to: "nitrile",
+		reagent: "KCN",
+		condition: "in ethanol, under reflux",
+		changesChain: true
+	},
+	{
+		from: "nitrile",
+		to: "acid",
+		reagent: "dilute HCl",
+		condition: "heat under reflux"
+	},
+	{
+		from: "alcohol",
+		to: "alkene",
+		reagent: "conc. H₂SO₄",
+		condition: "170 °C, dehydration"
+	},
+	{
+		from: "alcohol",
+		to: "halogenoalkane",
+		reagent: "HBr or PCl₅",
+		condition: "HBr made in situ from NaBr and conc. H₂SO₄, or PCl₅ at room temperature"
+	},
+	{
+		from: "alcohol",
+		to: "aldehyde",
+		reagent: "K₂Cr₂O₇ / H⁺",
+		condition: "distil the product off as it forms",
+		needs: "a primary alcohol"
+	},
+	{
+		from: "alcohol",
+		to: "ketone",
+		reagent: "K₂Cr₂O₇ / H⁺",
+		condition: "heat under reflux",
+		needs: "a secondary alcohol"
+	},
+	{
+		from: "aldehyde",
+		to: "acid",
+		reagent: "K₂Cr₂O₇ / H⁺",
+		condition: "heat under reflux"
+	},
+	{
+		from: "aldehyde",
+		to: "alcohol",
+		reagent: "NaBH₄",
+		condition: "in aqueous ethanol"
+	},
+	{
+		from: "ketone",
+		to: "alcohol",
+		reagent: "NaBH₄",
+		condition: "in aqueous ethanol"
+	},
+	{
+		from: "acid",
+		to: "ester",
+		reagent: "an alcohol",
+		condition: "conc. H₂SO₄ catalyst, warm"
+	},
+	{
+		from: "ester",
+		to: "acid",
+		reagent: "dilute H₂SO₄",
+		condition: "heat under reflux"
+	},
+	{
+		from: "acid",
+		to: "acyl-chloride",
+		reagent: "PCl₅ or SOCl₂",
+		condition: "room temperature, in dry conditions"
+	},
+	{
+		from: "acyl-chloride",
+		to: "ester",
+		reagent: "an alcohol",
+		condition: "room temperature, no catalyst, and it goes to completion"
+	},
+	{
+		from: "acyl-chloride",
+		to: "acid",
+		reagent: "water",
+		condition: "room temperature, vigorous, fumes of HCl"
+	},
+	{
+		from: "arene",
+		to: "nitroarene",
+		reagent: "conc. HNO₃ with conc. H₂SO₄",
+		condition: "below 55 °C"
+	},
+	{
+		from: "nitroarene",
+		to: "arylamine",
+		reagent: "Sn with conc. HCl, then NaOH(aq)",
+		condition: "reflux, then make alkaline to free the amine"
+	},
+	{
+		from: "nitrile",
+		to: "amine",
+		reagent: "LiAlH₄, or H₂ with a nickel catalyst",
+		condition: "LiAlH₄ in dry ether, or H₂ at high temperature and pressure"
+	},
+	{
+		from: "acyl-chloride",
+		to: "amide",
+		reagent: "NH₃ or a primary amine",
+		condition: "room temperature, two moles of the amine"
+	},
+	{
+		from: "arylamine",
+		to: "amide",
+		reagent: "an acyl chloride",
+		condition: "room temperature"
+	}
+];
+/** Every group the map knows, in the order the type declares them. */
+const GROUP_NODES = Object.keys(GROUP_LABELS);
+/** Roads leaving a group. */
+const edgesFrom = (id) => ROUTE_EDGES.filter((edge) => edge.from === id);
+/** The road between two groups, if there is one. */
+const edgeBetween = (from, to) => ROUTE_EDGES.find((edge) => edge.from === from && edge.to === to);
+/** The roads along a path of groups, so a route can be read back as an answer. */
+function edgesAlong(path) {
+	const out = [];
+	for (let i = 0; i < path.length - 1; i += 1) {
+		const edge = edgeBetween(path[i], path[i + 1]);
+		if (edge) out.push(edge);
+	}
+	return out;
+}
+/**
+* Shortest path length between two groups, by breadth-first search.
+*
+* `undefined` when no route exists, which is a real answer rather than a failure: a learner
+* hunting for a reaction that does not exist is exactly what a route map is for.
+*/
+function shortestSteps(from, to) {
+	if (from === to) return 0;
+	const seen = new Set([from]);
+	let frontier = [from];
+	let depth = 0;
+	while (frontier.length) {
+		depth += 1;
+		const next = [];
+		for (const node of frontier) for (const edge of edgesFrom(node)) {
+			if (edge.to === to) return depth;
+			if (seen.has(edge.to)) continue;
+			seen.add(edge.to);
+			next.push(edge.to);
+		}
+		frontier = next;
+	}
+}
+const asRoute = (path) => {
+	const steps = edgesAlong(path);
+	return {
+		path,
+		steps,
+		changesChain: steps.some((s) => s.changesChain === true)
+	};
+};
+/**
+* One shortest route, with the reagent and condition for every step.
+*
+* This is the difference between a distance and an answer. A lesson claiming "alkene to carboxylic
+* acid in three steps" can now be checked against the route the map actually gives, and the steps
+* it returns are the marks.
+*
+* ## Why a plain breadth-first search was not enough
+*
+* Alkene to carboxylic acid has TWO routes of three steps. One hydrates and oxidises twice and
+* keeps the carbon skeleton. The other goes through the nitrile, and a nitrile road adds a carbon,
+* so it arrives at an acid ONE CARBON LONGER than the target. A search that returned whichever it
+* reached first would hand a learner the wrong molecule half the time, and would do it silently,
+* because both routes are three steps and both are real chemistry.
+*
+* So among equally short routes the chain-preserving one wins. A question that wants the longer
+* chain says so, and {@link allRoutes} still has both.
+*/
+function findRoute(from, to) {
+	if (from === to) return asRoute([from]);
+	const depth = shortestSteps(from, to);
+	if (depth === void 0) return void 0;
+	return allRoutes(from, to, depth).filter((r) => r.steps.length === depth).sort((a, b) => Number(a.changesChain) - Number(b.changesChain))[0];
+}
+/**
+* Every route from one group to another within a step budget, shortest first.
+*
+* Exists because the shortest route is not always the best one, which is the single most arguable
+* point in the topic. Esterifying an acid directly is one step and an equilibrium that stops well
+* short; going via the acyl chloride is two steps and goes to completion. Both routes have to be
+* on the table for that to be a judgement rather than a rule.
+*
+* `maxSteps` is capped at six, because the map's diameter is smaller than that and an uncapped
+* enumeration on a cyclic graph does not terminate usefully.
+*/
+function allRoutes(from, to, maxSteps = 4) {
+	const limit = Math.min(maxSteps, 6);
+	const found = [];
+	const walk = (path, visited) => {
+		const head = path[path.length - 1];
+		if (head === to && path.length > 1) {
+			found.push(asRoute([...path]));
+			return;
+		}
+		if (path.length - 1 >= limit) return;
+		for (const edge of edgesFrom(head)) {
+			if (visited.has(edge.to)) continue;
+			visited.add(edge.to);
+			path.push(edge.to);
+			walk(path, visited);
+			path.pop();
+			visited.delete(edge.to);
+		}
+	};
+	walk([from], new Set([from]));
+	return found.sort((a, b) => a.steps.length - b.steps.length);
+}
+/**
+* The reactions that change the number of carbon atoms.
+*
+* The most useful fact in the topic and the one that is invisible in a list: to reach a target with
+* more carbons than the starting material, a route MUST pass through one of these.
+*/
+const chainChangingEdges = () => ROUTE_EDGES.filter((edge) => edge.changesChain === true);
+
+//#endregion
+export { GROUP_LABELS, GROUP_NODES, ROUTE_EDGES, allRoutes, chainChangingEdges, edgeBetween, edgesAlong, edgesFrom, findRoute, shortestSteps };

package/dist/chem/vsepr.d.mts

@@ -0,0 +1,80 @@
+import { Centre, CentreOptions } from "./species.mjs";
+import { LewisCount } from "./lewis.mjs";
+import { Vec3 } from "../core/vec3.mjs";
+
+//#region src/chem/vsepr.d.ts
+/** The arrangement of ALL regions, lone pairs included. */
+type ElectronGeometry = 'linear' | 'trigonal planar' | 'tetrahedral' | 'trigonal bipyramidal' | 'octahedral';
+/**
+ * The directions the regions point, for each steric number.
+ *
+ * Real coordinates, so the same numbers serve a flat diagram and a three-dimensional one. The
+ * tetrahedron is built from alternate corners of a cube, which is where its angle comes from.
+ */
+declare function directionsFor(stericNumber: number): Vec3[];
+/**
+ * The angle between two directions, in DEGREES.
+ *
+ * Degrees rather than radians because every bond angle a chemist quotes is in
+ * degrees. The kernel's `angleBetween3` returns radians, as a maths kernel
+ * should; this is the one conversion, in the one place the unit is a
+ * convention of the subject rather than of the arithmetic.
+ */
+declare const angleBetween: (a: Vec3, b: Vec3) => number;
+/**
+ * Choose which positions the lone pairs take, by least repulsion.
+ *
+ * Every combination is tried and ranked on the count of close contacts, worst kind first: lone pair
+ * against lone pair, then lone pair against bond pair, then bond against bond. The first arrangement
+ * that beats the rest is returned, which is how the equatorial rule and the opposite-corners rule
+ * fall out instead of being stated.
+ */
+declare function placeLonePairs(stericNumber: number, lonePairs: number): number[];
+/** One direction out of the central atom: either a bond to something, or a lone pair. */
+interface Region {
+  readonly direction: Vec3;
+  readonly kind: 'bond' | 'lone pair';
+  /** The element at the far end, for a bond. */
+  readonly element?: string;
+}
+interface MolecularShape {
+  readonly centre: Centre;
+  readonly count: LewisCount;
+  /** The arrangement of every region, lone pairs included. */
+  readonly electronGeometry: ElectronGeometry;
+  /** The shape, which is the arrangement with the lone pairs removed. */
+  readonly shape: string;
+  /** Hybridisation implied by the steric number. */
+  readonly hybridisation: string;
+  /**
+   * The angle the arrangement would have with no lone pairs, in degrees.
+   *
+   * Geometry, so it is exact: 109.47 for a tetrahedron, not 109.5. Two values where the arrangement
+   * has two distinct angles, as a trigonal bipyramid does.
+   */
+  readonly idealAngle: readonly number[];
+  /** Every direction out of the central atom, bonds and lone pairs together. */
+  readonly regions: readonly Region[];
+  /** Just the bonds, which is what the shape is named after. */
+  readonly bondDirections: readonly Vec3[];
+}
+/**
+ * Work out the shape of a species written as a formula.
+ *
+ * `shapeOf('XeF4')`, `shapeOf('NH4+')`, `shapeOf('SO4^2-')`, `shapeOf('SF4')`.
+ */
+declare function shapeOf(formula: string, options?: CentreOptions): MolecularShape;
+/**
+ * Bond angles that have been measured, in degrees.
+ *
+ * Kept apart from the ideal angles because they are a different kind of thing. VSEPR predicts that
+ * a lone pair squeezes the remaining angle; it does not predict by how much, and the numbers below
+ * are experimental values from standard structural data, not outputs of the model.
+ *
+ * They are worth having because the pattern in them is the lesson: ammonia at 107.0 and phosphine
+ * at 93.5 are the same shape with the same number of lone pairs, and the angle collapses down the
+ * group, which is something the model alone would never suggest.
+ */
+declare const OBSERVED_ANGLES: Readonly<Record<string, number>>;
+//#endregion
+export { ElectronGeometry, MolecularShape, OBSERVED_ANGLES, Region, angleBetween, directionsFor, placeLonePairs, shapeOf };