@classytic/stage 0.2.0 → 0.4.0

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

package/dist/chem/vsepr.mjs

@@ -0,0 +1,247 @@
+import { angleBetween3, unit3, v3 } from "../core/vec3.mjs";
+import { parseCentre } from "./species.mjs";
+import { lewisCount } from "./lewis.mjs";
+
+//#region src/chem/vsepr.ts
+/**
+* The shape of a molecule, from the electron budget.
+*
+* ## One idea, applied consistently
+*
+* Regions of electron density around an atom get as far from each other as they can. Count the
+* regions (that is the steric number) and their arrangement follows: two go opposite, three make a
+* triangle, four a tetrahedron, five a trigonal bipyramid, six an octahedron. The SHAPE is then
+* what is left when the lone pairs are made invisible, because a shape is the positions of atoms
+* and a lone pair is not an atom. That is the whole of VSEPR, and it is why ammonia and methane
+* have the same arrangement and different shapes.
+*
+* ## Where the lone pairs sit is DERIVED, not looked up
+*
+* Textbooks state that a lone pair in a trigonal bipyramid goes equatorial, and that two lone pairs
+* in an octahedron go opposite each other. Both are usually given as facts to remember. They are
+* neither arbitrary nor separate: they are what you get by trying every arrangement and keeping the
+* one with the least repulsion, ranked the way Gillespie ranks it:
+*
+*     lone pair / lone pair  is worse than
+*     lone pair / bond pair  is worse than
+*     bond pair / bond pair
+*
+* because a lone pair is held by one nucleus instead of two and so spreads out further. Only the
+* near-90-degree contacts matter; anything at 120 degrees or more is already far enough away to
+* ignore, which is why the comparison is a count and not an integral.
+*
+* {@link placeLonePairs} does that search. So a lone pair in a trigonal bipyramid comes out
+* equatorial here because an equatorial position has two neighbours at 90 degrees and an axial one
+* has three, and a learner can be shown the losing arrangement beside the winning one.
+*
+* ## Ideal angles are geometry; real angles are measurements
+*
+* The tetrahedral angle is arccos(-1/3), which is exact and is computed. The 104.5 degrees in water
+* is a measurement, and no amount of geometry will produce it, because how far a lone pair pushes is
+* not something the model predicts. The two are kept apart: {@link Geometry.idealAngle} is derived,
+* and {@link OBSERVED_ANGLES} is data with its provenance stated.
+*
+* Pure: no React, no pixels.
+*/
+const ELECTRON_GEOMETRY = {
+	2: "linear",
+	3: "trigonal planar",
+	4: "tetrahedral",
+	5: "trigonal bipyramidal",
+	6: "octahedral"
+};
+const HYBRIDISATION = {
+	2: "sp",
+	3: "sp²",
+	4: "sp³",
+	5: "sp³d",
+	6: "sp³d²"
+};
+/** The shape, which is the arrangement with the lone pairs taken away. */
+const SHAPES = {
+	"2,0": "linear",
+	"3,0": "trigonal planar",
+	"3,1": "bent",
+	"4,0": "tetrahedral",
+	"4,1": "trigonal pyramidal",
+	"4,2": "bent",
+	"5,0": "trigonal bipyramidal",
+	"5,1": "seesaw",
+	"5,2": "T-shaped",
+	"5,3": "linear",
+	"6,0": "octahedral",
+	"6,1": "square pyramidal",
+	"6,2": "square planar",
+	"6,3": "T-shaped"
+};
+const unit = (x, y, z) => unit3(v3(x, y, z));
+/**
+* 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.
+*/
+function directionsFor(stericNumber) {
+	switch (stericNumber) {
+		case 2: return [unit(1, 0, 0), unit(-1, 0, 0)];
+		case 3: return [
+			0,
+			1,
+			2
+		].map((k) => unit(Math.cos(2 * Math.PI * k / 3), Math.sin(2 * Math.PI * k / 3), 0));
+		case 4: return [
+			unit(1, 1, 1),
+			unit(1, -1, -1),
+			unit(-1, 1, -1),
+			unit(-1, -1, 1)
+		];
+		case 5: return [
+			...[
+				0,
+				1,
+				2
+			].map((k) => unit(Math.cos(2 * Math.PI * k / 3), Math.sin(2 * Math.PI * k / 3), 0)),
+			unit(0, 0, 1),
+			unit(0, 0, -1)
+		];
+		case 6: return [
+			unit(1, 0, 0),
+			unit(-1, 0, 0),
+			unit(0, 1, 0),
+			unit(0, -1, 0),
+			unit(0, 0, 1),
+			unit(0, 0, -1)
+		];
+		default: throw new Error(`steric number ${stericNumber} is outside the range this engine describes (2 to 6)`);
+	}
+}
+/**
+* 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.
+*/
+const angleBetween = (a, b) => angleBetween3(a, b) * 180 / Math.PI;
+/** Contacts close enough to matter. Anything at 120 degrees or more is already far apart. */
+const CLOSE = 100;
+/**
+* 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.
+*/
+function placeLonePairs(stericNumber, lonePairs) {
+	const directions = directionsFor(stericNumber);
+	if (lonePairs === 0) return [];
+	if (lonePairs > stericNumber) throw new Error(`cannot place ${lonePairs} lone pairs in ${stericNumber} positions`);
+	const score = (chosen) => {
+		const isLone = (i) => chosen.includes(i);
+		let loneLone = 0;
+		let loneBond = 0;
+		let bondBond = 0;
+		for (let i = 0; i < directions.length; i += 1) for (let j = i + 1; j < directions.length; j += 1) {
+			if (angleBetween(directions[i], directions[j]) >= CLOSE) continue;
+			const lones = Number(isLone(i)) + Number(isLone(j));
+			if (lones === 2) loneLone += 1;
+			else if (lones === 1) loneBond += 1;
+			else bondBond += 1;
+		}
+		return [
+			loneLone,
+			loneBond,
+			bondBond
+		];
+	};
+	const combinations = [];
+	const build = (start, picked) => {
+		if (picked.length === lonePairs) {
+			combinations.push([...picked]);
+			return;
+		}
+		for (let i = start; i < stericNumber; i += 1) build(i + 1, [...picked, i]);
+	};
+	build(0, []);
+	let best = combinations[0];
+	let bestScore = score(best);
+	for (const candidate of combinations.slice(1)) {
+		const candidateScore = score(candidate);
+		const better = candidateScore.findIndex((value, k) => value !== bestScore[k]);
+		if (better !== -1 && candidateScore[better] < bestScore[better]) {
+			best = candidate;
+			bestScore = candidateScore;
+		}
+	}
+	return best;
+}
+/** Ideal angles for an arrangement, computed from the directions themselves. */
+function idealAnglesFor(stericNumber) {
+	const directions = directionsFor(stericNumber);
+	const angles = /* @__PURE__ */ new Set();
+	for (let i = 0; i < directions.length; i += 1) for (let j = i + 1; j < directions.length; j += 1) angles.add(Math.round(angleBetween(directions[i], directions[j]) * 100) / 100);
+	return [...angles].sort((a, b) => a - b).filter((a) => a < 180 || angles.size === 1);
+}
+/**
+* Work out the shape of a species written as a formula.
+*
+* `shapeOf('XeF4')`, `shapeOf('NH4+')`, `shapeOf('SO4^2-')`, `shapeOf('SF4')`.
+*/
+function shapeOf(formula, options = {}) {
+	const centre = parseCentre(formula, options);
+	const count = lewisCount(centre);
+	if (count.impossible) throw new Error(count.impossible);
+	const { stericNumber, lonePairs } = count;
+	const electronGeometry = ELECTRON_GEOMETRY[stericNumber];
+	const shape = SHAPES[`${stericNumber},${lonePairs}`];
+	if (!electronGeometry || !shape) throw new Error(`${formula} works out to ${stericNumber} regions with ${lonePairs} lone pairs, which is outside the range this engine describes`);
+	const directions = directionsFor(stericNumber);
+	const lonePositions = new Set(placeLonePairs(stericNumber, lonePairs));
+	const bondedElements = centre.bonded.flatMap((l) => Array(l.count).fill(l.element));
+	let next = 0;
+	const regions = directions.map((direction, index) => lonePositions.has(index) ? {
+		direction,
+		kind: "lone pair"
+	} : {
+		direction,
+		kind: "bond",
+		element: bondedElements[next++] ?? centre.central
+	});
+	return {
+		centre,
+		count,
+		electronGeometry,
+		shape,
+		hybridisation: HYBRIDISATION[stericNumber],
+		idealAngle: idealAnglesFor(stericNumber),
+		regions,
+		bondDirections: regions.filter((r) => r.kind === "bond").map((r) => r.direction)
+	};
+}
+/**
+* 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.
+*/
+const OBSERVED_ANGLES = {
+	CH4: 109.5,
+	NH3: 107,
+	H2O: 104.5,
+	PH3: 93.5,
+	H2S: 92.1,
+	NF3: 102.2,
+	SO2: 119,
+	BF3: 120,
+	CO2: 180
+};
+
+//#endregion
+export { OBSERVED_ANGLES, angleBetween, directionsFor, placeLonePairs, shapeOf };