@classytic/stage 0.3.0 → 0.4.0

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

package/dist/circuit/ac.d.mts

@@ -0,0 +1,163 @@
+import { Edge } from "./topology.mjs";
+import { Complex } from "../math/complex.mjs";
+
+//#region src/circuit/ac.d.ts
+type ElementKind = 'R' | 'L' | 'C';
+/** One component. Ohms for R, henries for L, farads for C. */
+interface Element extends Edge {
+  kind: ElementKind;
+  value: number;
+}
+interface AcNetwork {
+  elements: Element[];
+  terminals: [string, string];
+}
+/** A resistance so small it is a wire, used to keep a division from blowing up. */
+declare const TINY = 1e-12;
+/**
+ * The impedance of one component at angular frequency ω.
+ *
+ *   R   Z = R                 real, and the same at every frequency
+ *   L   Z = jωL               purely positive-imaginary: current LAGS the voltage
+ *   C   Z = 1/(jωC) = −j/(ωC) purely negative-imaginary: current LEADS the voltage
+ *
+ * The signs are the whole content of the topic, and they are why a capacitor and an inductor can
+ * cancel each other out exactly.
+ */
+declare function impedanceOf(element: Element, omegaRadPerS: number): Complex;
+/** Reactance: the imaginary part. Positive is inductive, negative is capacitive. */
+declare const reactance: (z: Complex) => number;
+/** Resistance: the real part, which is the only part that dissipates energy. */
+declare const resistance: (z: Complex) => number;
+/** Magnitude |Z|, in ohms. */
+declare const magnitude: (z: Complex) => number;
+/** Phase of the impedance in degrees. Positive means the current lags the voltage. */
+declare const phaseDeg: (z: Complex) => number;
+/** Series impedances add. Always, for every component kind, at every frequency. */
+declare function seriesImpedance(zs: readonly Complex[]): Complex;
+/**
+ * Parallel impedances combine by adding ADMITTANCES, Y = 1/Z.
+ *
+ * An infinite impedance (a capacitor at DC) contributes zero admittance rather than breaking the
+ * sum, which is both numerically necessary and physically exactly right: an open branch in parallel
+ * changes nothing.
+ */
+declare function parallelImpedance(zs: readonly Complex[]): Complex;
+/**
+ * The equivalent impedance between the terminals at one frequency.
+ *
+ * Uses the same structural rules as the DC reducer, from `topology.ts`, because the shape of a
+ * network has nothing to do with what it is made of. Only the arithmetic differs, and here the
+ * arithmetic is complex.
+ *
+ * A reduced edge is carried as an R whose "value" is meaningless; what matters is the impedance map
+ * kept alongside. Doing it that way means a merged branch is a first-class edge for the next rule
+ * rather than a special case.
+ */
+declare function equivalentImpedance(network: AcNetwork, omegaRadPerS: number): Complex | null;
+/**
+ * The equivalent impedance of ANY network, by nodal analysis in the frequency domain.
+ *
+ * Where `equivalentImpedance` reduces by series and parallel and gives up honestly when those run
+ * out, this always answers. It injects one amp into the first terminal, grounds the second, solves
+ * the complex nodal equations and reads the voltage that appears: Z = V/I with I = 1.
+ *
+ * This is what makes the engine complete rather than merely correct. An unbalanced AC bridge has no
+ * series or parallel move anywhere in it, which is a fact about the shape and not a gap in the
+ * rules, and before this it could only be reported as unsolvable. A tool that reports defeat on a
+ * circuit an undergraduate is expected to analyse is a teaching aid, not an engine.
+ *
+ * The two coexist on purpose: the reducer narrates and this one answers, and the tests require them
+ * to agree wherever the reducer can finish.
+ */
+declare function impedanceByNodalAnalysis(network: AcNetwork, omegaRadPerS: number): Complex | null;
+/**
+ * Does an AC bridge balance?
+ *
+ * The condition is Z_P/Z_Q = Z_R/Z_S as COMPLEX numbers, which means the magnitudes must be in
+ * proportion AND the phases must match. That is two conditions, not one, and it is exactly why a
+ * real AC bridge has two adjustable components where a Wheatstone bridge has one. A student who
+ * has only met the DC bridge finds this genuinely surprising, and it falls straight out of using
+ * complex numbers rather than being an extra rule to remember.
+ */
+declare function bridgeBalances(p: Complex, q: Complex, r: Complex, s: Complex): boolean;
+/**
+ * The angular frequency at which an inductor and a capacitor cancel exactly.
+ *
+ *     ωL = 1/(ωC)   so   ω₀ = 1/√(LC)
+ *
+ * At ω₀ a series LC pair has zero net reactance, so a series RLC looks purely resistive and the
+ * current is at a maximum. That is the whole of tuning: a radio picks one station by making its
+ * circuit resonate there and nowhere else.
+ */
+declare function resonantOmega(henries: number, farads: number): number;
+/** Resonance in hertz, which is what a dial is marked in. */
+declare const resonantHz: (henries: number, farads: number) => number;
+/**
+ * The quality factor of a series RLC: how sharply it selects its resonant frequency.
+ *
+ *     Q = (1/R)·√(L/C)
+ *
+ * A high Q is a narrow peak, which is a radio that separates adjacent stations. Resistance is what
+ * spoils it, because resistance is the only part that takes energy out of the oscillation.
+ */
+declare function qualityFactor(ohms: number, henries: number, farads: number): number;
+/** The width of the resonance peak between its half-power points, in rad/s. */
+declare const bandwidthRadPerS: (ohms: number, henries: number, farads: number) => number;
+interface AcResponse {
+  omegaRadPerS: number;
+  impedance: Complex;
+  /** |Z| in ohms. */
+  magnitudeOhm: number;
+  /** Phase of Z in degrees: positive means the current lags. */
+  phaseDeg: number;
+  /** Peak current for a given peak driving voltage, in amps. */
+  currentAmp: number;
+  /** Phase of the CURRENT relative to the driving voltage, in degrees. The negative of Z's phase. */
+  currentPhaseDeg: number;
+}
+/** How a network responds to a sinusoid of a given peak voltage at one frequency. */
+declare function responseAt(network: AcNetwork, omegaRadPerS: number, drivePeakV?: number): AcResponse | null;
+/**
+ * A frequency sweep, spaced logarithmically.
+ *
+ * Log spacing is not a presentation choice. A response that matters over four decades has almost
+ * all of its structure in the first decade, and a linear sweep spends 90% of its points on the last
+ * one, where nothing happens. Every instrument that measures this sweeps logarithmically.
+ */
+declare function sweep(network: AcNetwork, omegaFrom: number, omegaTo: number, points?: number, drivePeakV?: number): AcResponse[];
+/**
+ * The power factor, cos φ.
+ *
+ * Only the resistance dissipates energy. A purely reactive component takes energy in for a quarter
+ * cycle and gives every joule back in the next, so it carries current and consumes nothing. A
+ * factory with a poor power factor pays for current it never turns into anything, which is why
+ * power factor correction is a real industrial expense rather than a textbook curiosity.
+ */
+declare const powerFactor: (z: Complex) => number;
+/** Average power actually dissipated, from RMS current: only the real part counts. */
+declare const realPowerW: (z: Complex, rmsCurrentAmp: number) => number;
+/** Apparent power, which is what the supply has to be sized for: |Z| I². */
+declare const apparentPowerVA: (z: Complex, rmsCurrentAmp: number) => number;
+/** RMS is the peak divided by root two, for a sinusoid and for nothing else. */
+declare const rmsFromPeak: (peak: number) => number;
+/** A series RLC between A and B, the circuit every resonance question is about. */
+declare function seriesRlc(ohms: number, henries: number, farads: number): AcNetwork;
+/** A first-order RC low-pass: output taken across the capacitor. */
+declare function rcLowPass(ohms: number, farads: number): AcNetwork;
+/** The −3 dB corner of a first-order RC, where |Z_C| = R and the output has fallen to 1/√2. */
+declare const rcCornerOmega: (ohms: number, farads: number) => number;
+/**
+ * The transfer function of a two-element divider: what fraction of the input appears across the
+ * second element, as a complex number carrying both size and phase shift.
+ *
+ * This is the potential divider again, with complex numbers, and recognising that is most of what
+ * makes filters approachable.
+ */
+declare function dividerGain(zSeries: Complex, zShunt: Complex): Complex;
+/** Gain expressed in decibels, which is how every frequency response is actually plotted. */
+declare const decibels: (gain: number) => number;
+/** Multiply two complex numbers, re-exported so a caller need not import the maths kernel too. */
+declare const timesC: (a: Complex, b: Complex) => Complex;
+//#endregion
+export { AcNetwork, AcResponse, Element, ElementKind, TINY, apparentPowerVA, bandwidthRadPerS, bridgeBalances, decibels, dividerGain, equivalentImpedance, impedanceByNodalAnalysis, impedanceOf, magnitude, parallelImpedance, phaseDeg, powerFactor, qualityFactor, rcCornerOmega, rcLowPass, reactance, realPowerW, resistance, resonantHz, resonantOmega, responseAt, rmsFromPeak, seriesImpedance, seriesRlc, sweep, timesC };