@classytic/stage 0.2.0 → 0.4.0

package/dist/circuit/index.mjs

@@ -1,333 +1,6 @@
-//#region src/circuit/index.ts
-/** NMOS square-law operating point: drain current + its small-signal conductances. */
-function nmosOp(Vgs, Vds, vth, k) {
-	const Vov = Vgs - vth;
-	if (Vov <= 0) return {
-		Id: 0,
-		gm: 0,
-		gds: GMIN
-	};
-	if (Vds < Vov) return {
-		Id: k * (Vov * Vds - .5 * Vds * Vds),
-		gm: k * Vds,
-		gds: k * (Vov - Vds) + GMIN
-	};
-	return {
-		Id: .5 * k * Vov * Vov,
-		gm: k * Vov,
-		gds: GMIN
-	};
-}
-const VT = .025852;
-const GMIN = 1e-12;
-function nodeCount(elems) {
-	let max = 0;
-	for (const e of elems) max = Math.max(max, e.n1, e.n2, e.n3 ?? 0);
-	return max + 1;
-}
-/** Solve A x = b by Gaussian elimination with partial pivoting. Returns null if singular. */
-function solveLinear(A, b) {
-	const n = b.length;
-	const M = A.map((row, i) => [...row, b[i]]);
-	for (let col = 0; col < n; col++) {
-		let piv = col;
-		for (let r = col + 1; r < n; r++) if (Math.abs(M[r][col]) > Math.abs(M[piv][col])) piv = r;
-		if (Math.abs(M[piv][col]) < 1e-18) return null;
-		[M[col], M[piv]] = [M[piv], M[col]];
-		const pivVal = M[col][col];
-		for (let r = 0; r < n; r++) {
-			if (r === col) continue;
-			const f = M[r][col] / pivVal;
-			if (f === 0) continue;
-			for (let c = col; c <= n; c++) M[r][c] -= f * M[col][c];
-		}
-	}
-	const x = new Array(n);
-	for (let i = 0; i < n; i++) x[i] = M[i][n] / M[i][i];
-	return x;
-}
-/** Build the MNA system A x = z for one solve (DC if no dt, else one transient step). */
-function buildMNA(elems, opts) {
-	const N = nodeCount(elems);
-	const dc = opts.dt === void 0;
-	const vbranch = [];
-	elems.forEach((e) => {
-		if (e.kind === "V" || e.kind === "L" && dc) vbranch.push({
-			elem: e,
-			row: 0
-		});
-	});
-	const n = N - 1 + vbranch.length;
-	vbranch.forEach((vb, j) => {
-		vb.row = N - 1 + j;
-	});
-	const A = Array.from({ length: n }, () => new Array(n).fill(0));
-	const z = new Array(n).fill(0);
-	const ix = (node) => node - 1;
-	const stampG = (a, b, g) => {
-		if (a >= 0) A[a][a] += g;
-		if (b >= 0) A[b][b] += g;
-		if (a >= 0 && b >= 0) {
-			A[a][b] -= g;
-			A[b][a] -= g;
-		}
-	};
-	const stampI = (a, b, I) => {
-		if (a >= 0) z[a] -= I;
-		if (b >= 0) z[b] += I;
-	};
-	for (let k = 1; k < N; k++) A[ix(k)][ix(k)] += GMIN;
-	let vi = 0;
-	elems.forEach((e, idx) => {
-		const a = ix(e.n1), b = ix(e.n2);
-		if (e.kind === "R") stampG(a, b, 1 / e.value);
-		else if (e.kind === "I") stampI(a, b, e.value);
-		else if (e.kind === "V" || e.kind === "L" && dc) {
-			const row = vbranch[vi++].row;
-			const E = e.kind === "V" ? e.value : 0;
-			if (a >= 0) {
-				A[a][row] += 1;
-				A[row][a] += 1;
-			}
-			if (b >= 0) {
-				A[b][row] -= 1;
-				A[row][b] -= 1;
-			}
-			z[row] += E;
-		} else if (e.kind === "C" && !dc) {
-			const Geq = e.value / opts.dt;
-			const Ieq = -Geq * (opts.prevV?.get(idx) ?? 0);
-			stampG(a, b, Geq);
-			stampI(a, b, Ieq);
-		} else if (e.kind === "L" && !dc) {
-			const Geq = opts.dt / e.value;
-			const Ieq = opts.prevI?.get(idx) ?? 0;
-			stampG(a, b, Geq);
-			stampI(a, b, Ieq);
-		} else if (e.kind === "D") {
-			const Is = e.is ?? 1e-12, nvt = (e.nIdeal ?? 1) * VT;
-			const V = opts.diodeV?.get(idx) ?? 0;
-			const Id = Is * (Math.exp(Math.min(V / nvt, 80)) - 1);
-			const gd = (Id + Is) / nvt + GMIN;
-			const Ieq = Id - gd * V;
-			stampG(a, b, gd);
-			stampI(a, b, Ieq);
-		} else if (e.kind === "M") {
-			const D = a, S = b, G = ix(e.n3 ?? 0);
-			const nv = opts.prevNodeV;
-			const Vg = nv?.[e.n3 ?? 0] ?? 0, Vd = nv?.[e.n1] ?? 0, Vs = nv?.[e.n2] ?? 0;
-			if (e.pmos) {
-				const { Id, gm, gds } = nmosOp(Vs - Vg, Vs - Vd, Math.abs(e.vth ?? 2), e.k ?? .5);
-				const Ieq = Id - gm * (Vs - Vg) - gds * (Vs - Vd);
-				stampG(S, D, gds);
-				if (S >= 0) A[S][S] += gm;
-				if (S >= 0 && G >= 0) A[S][G] -= gm;
-				if (D >= 0 && S >= 0) A[D][S] -= gm;
-				if (D >= 0 && G >= 0) A[D][G] += gm;
-				stampI(S, D, Ieq);
-			} else {
-				const { Id, gm, gds } = nmosOp(Vg - Vs, Vd - Vs, e.vth ?? 2, e.k ?? .5);
-				const Ieq = Id - gm * (Vg - Vs) - gds * (Vd - Vs);
-				stampG(D, S, gds);
-				if (D >= 0 && G >= 0) A[D][G] += gm;
-				if (D >= 0 && S >= 0) A[D][S] -= gm;
-				if (S >= 0 && G >= 0) A[S][G] -= gm;
-				if (S >= 0) A[S][S] += gm;
-				stampI(D, S, Ieq);
-			}
-		}
-	});
-	return {
-		A,
-		z,
-		N,
-		vbranch
-	};
-}
-/** DC operating point: capacitors open, inductors short. Routes to the nonlinear solver for diodes / MOSFETs. */
-function solveDC(elems) {
-	if (elems.some((e) => e.kind === "D" || e.kind === "M")) return solveDCNonlinear(elems);
-	const { A, z, N, vbranch } = buildMNA(elems, {});
-	const x = solveLinear(A, z);
-	const nodeV = new Array(N).fill(0);
-	const current = {};
-	if (!x) return {
-		nodeV,
-		current,
-		ok: false
-	};
-	for (let k = 1; k < N; k++) nodeV[k] = x[k - 1];
-	vbranch.forEach((vb) => {
-		if (vb.elem.id) current[vb.elem.id] = x[vb.row];
-	});
-	return {
-		nodeV,
-		current,
-		ok: true
-	};
-}
-/**
-* Nonlinear DC via Newton-Raphson: each iteration linearizes every nonlinear device
-* (diode Shockley with pnjlim limiting; NMOS square-law about the previous node
-* voltages) into a companion conductance + current source, solves the linear system,
-* and repeats until the solution settles.
-*/
-function solveDCNonlinear(elems, opts = {}) {
-	const maxIter = opts.maxIter ?? 100, tol = opts.tol ?? 1e-7;
-	const N0 = nodeCount(elems);
-	const diodes = elems.map((e, i) => ({
-		e,
-		i
-	})).filter((x) => x.e.kind === "D");
-	const mosfets = elems.map((e, i) => ({
-		e,
-		i
-	})).filter((x) => x.e.kind === "M");
-	const diodeV = /* @__PURE__ */ new Map();
-	diodes.forEach((d) => diodeV.set(d.i, 0));
-	let prevNodeV = new Array(N0).fill(0);
-	let x = null;
-	let N = N0;
-	let vbranch = [];
-	let converged = false;
-	for (let iter = 0; iter < maxIter; iter++) {
-		const built = buildMNA(elems, {
-			diodeV,
-			prevNodeV
-		});
-		N = built.N;
-		vbranch = built.vbranch;
-		const sol = solveLinear(built.A, built.z);
-		if (!sol) break;
-		x = sol;
-		const newNodeV = new Array(N).fill(0);
-		for (let k = 1; k < N; k++) newNodeV[k] = sol[k - 1];
-		if (mosfets.length > 0) {
-			const VMAXSTEP = 2;
-			for (let k = 1; k < N; k++) {
-				const old = prevNodeV[k] ?? 0;
-				const dv = (newNodeV[k] ?? 0) - old;
-				if (Math.abs(dv) > VMAXSTEP) newNodeV[k] = old + Math.sign(dv) * VMAXSTEP;
-			}
-		}
-		let maxDelta = 0;
-		for (const d of diodes) {
-			let Vnew = (newNodeV[d.e.n1] ?? 0) - (newNodeV[d.e.n2] ?? 0);
-			const nvt = (d.e.nIdeal ?? 1) * VT, Is = d.e.is ?? 1e-12;
-			const Vold = diodeV.get(d.i);
-			const Vcrit = nvt * Math.log(nvt / (Is * Math.SQRT2));
-			if (Vnew > Vcrit && Vnew > Vold) Vnew = Vold + nvt * Math.log(1 + (Vnew - Vold) / nvt);
-			maxDelta = Math.max(maxDelta, Math.abs(Vnew - Vold));
-			diodeV.set(d.i, Vnew);
-		}
-		for (let k = 1; k < N; k++) maxDelta = Math.max(maxDelta, Math.abs((newNodeV[k] ?? 0) - (prevNodeV[k] ?? 0)));
-		prevNodeV = newNodeV;
-		if (maxDelta < tol) {
-			converged = true;
-			break;
-		}
-	}
-	const nodeV = new Array(N).fill(0);
-	const current = {};
-	if (!x || !converged) return {
-		nodeV,
-		current,
-		ok: false
-	};
-	for (let k = 1; k < N; k++) nodeV[k] = x[k - 1];
-	vbranch.forEach((vb) => {
-		if (vb.elem.id) current[vb.elem.id] = x[vb.row];
-	});
-	diodes.forEach((d) => {
-		if (!d.e.id) return;
-		const nvt = (d.e.nIdeal ?? 1) * VT, Is = d.e.is ?? 1e-12;
-		current[d.e.id] = Is * (Math.exp(Math.min((diodeV.get(d.i) ?? 0) / nvt, 80)) - 1);
-	});
-	mosfets.forEach((m) => {
-		if (!m.e.id) return;
-		const Vg = nodeV[m.e.n3 ?? 0] ?? 0, Vd = nodeV[m.e.n1] ?? 0, Vs = nodeV[m.e.n2] ?? 0;
-		current[m.e.id] = m.e.pmos ? nmosOp(Vs - Vg, Vs - Vd, Math.abs(m.e.vth ?? 2), m.e.k ?? .5).Id : nmosOp(Vg - Vs, Vd - Vs, m.e.vth ?? 2, m.e.k ?? .5).Id;
-	});
-	return {
-		nodeV,
-		current,
-		ok: true
-	};
-}
-/** Current through an element given solved node voltages (R/I directly; C/L need state). */
-function elementCurrent(e, nodeV) {
-	const v = (nodeV[e.n1] ?? 0) - (nodeV[e.n2] ?? 0);
-	if (e.kind === "R") return v / e.value;
-	if (e.kind === "I") return e.value;
-	return NaN;
-}
-/**
-* Time-stepped transient (Backward Euler). Returns the node-voltage trajectory,
-* including t = 0. Reactive elements use companion models rebuilt every step.
-*/
-function solveTransient(elems, opts) {
-	const { dt, steps } = opts;
-	const N = nodeCount(elems);
-	const prevV = /* @__PURE__ */ new Map();
-	const prevI = /* @__PURE__ */ new Map();
-	elems.forEach((e, i) => {
-		if (e.kind === "C" || e.kind === "L") prevV.set(i, opts.initialV?.get(i) ?? 0);
-		if (e.kind === "L") prevI.set(i, 0);
-	});
-	const out = [];
-	const record = (t, nodeV) => {
-		out.push({
-			t,
-			nodeV: [...nodeV]
-		});
-	};
-	let nodeV = new Array(N).fill(0);
-	if (!elems.some((e) => e.kind === "D" || e.kind === "M")) {
-		const { A, z } = buildMNA(elems.map((e, i) => e.kind === "C" ? {
-			...e,
-			kind: "V",
-			value: opts.initialV?.get(i) ?? 0
-		} : e.kind === "L" ? {
-			...e,
-			kind: "I",
-			value: prevI.get(i) ?? 0
-		} : e), {});
-		const x = solveLinear(A, z);
-		if (x) for (let k = 1; k < N; k++) nodeV[k] = x[k - 1] ?? 0;
-	}
-	record(0, nodeV);
-	for (let s = 1; s <= steps; s++) {
-		const { A, z } = buildMNA(elems, {
-			dt,
-			prevV,
-			prevI
-		});
-		const x = solveLinear(A, z);
-		if (!x) break;
-		nodeV = new Array(N).fill(0);
-		for (let k = 1; k < N; k++) nodeV[k] = x[k - 1];
-		elems.forEach((e, i) => {
-			if (e.kind === "C" || e.kind === "L") {
-				const v = (nodeV[e.n1] ?? 0) - (nodeV[e.n2] ?? 0);
-				prevV.set(i, v);
-				if (e.kind === "L") {
-					const Geq = dt / e.value;
-					prevI.set(i, Geq * v + (prevI.get(i) ?? 0));
-				}
-			}
-		});
-		record(s * dt, nodeV);
-	}
-	return out;
-}
-/** Equivalent resistance of resistors in series. */
-function seriesR(...rs) {
-	return rs.reduce((a, r) => a + r, 0);
-}
-/** Equivalent resistance of resistors in parallel. */
-function parallelR(...rs) {
-	return 1 / rs.reduce((a, r) => a + 1 / r, 0);
-}
+import { elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient } from "./dc.mjs";
+import { degrees, findBridgeShape, findDangling, findParallelGroup, findSelfLoop, findSeriesPair, isReduced, isTerminal, mergedId, pairKey, validateTopology } from "./topology.mjs";
+import { NEGLIGIBLE, combineParallel, combineSeries, deltaFromStar, equivalentByNodalAnalysis, infiniteLadderOhm, reduce, starFromDelta, symbolFor, unitFor, validateNetwork } from "./network.mjs";
+import { 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 } from "./ac.mjs";
 
-//#endregion
-export { elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient };
+export { NEGLIGIBLE, TINY, apparentPowerVA, bandwidthRadPerS, bridgeBalances, combineParallel, combineSeries, decibels, degrees, deltaFromStar, dividerGain, elementCurrent, equivalentByNodalAnalysis, equivalentImpedance, findBridgeShape, findDangling, findParallelGroup, findSelfLoop, findSeriesPair, impedanceByNodalAnalysis, impedanceOf, infiniteLadderOhm, isReduced, isTerminal, magnitude, mergedId, pairKey, parallelImpedance, parallelR, phaseDeg, powerFactor, qualityFactor, rcCornerOmega, rcLowPass, reactance, realPowerW, reduce, resistance, resonantHz, resonantOmega, responseAt, rmsFromPeak, seriesImpedance, seriesR, seriesRlc, solveDC, solveDCNonlinear, solveLinear, solveTransient, starFromDelta, sweep, symbolFor, timesC, unitFor, validateNetwork, validateTopology };

package/dist/circuit/network.d.mts

@@ -0,0 +1,99 @@
+//#region src/circuit/network.d.ts
+/** Which quantity the network is made of. The rules are shared; only the arithmetic swaps. */
+type Quantity = 'resistance' | 'capacitance';
+/** One component, between two named nodes. Nodes are names, not indices, so a step can say "at C". */
+interface Component {
+  id: string;
+  a: string;
+  b: string;
+  /** Ohms for a resistance network, microfarads for a capacitance one. */
+  value: number;
+}
+interface Network {
+  quantity: Quantity;
+  components: Component[];
+  /** The two points the equivalent value is measured between. */
+  terminals: [string, string];
+}
+type ReductionRule = 'dangling' | 'shorted' | 'parallel' | 'series' | 'balanced-bridge';
+interface ReductionStep {
+  rule: ReductionRule;
+  /** The components this step consumed, in the order they appeared. */
+  consumed: Component[];
+  /** What replaced them, or null when the step was a deletion. */
+  produced: Component | null;
+  /** The node the step eliminated, when it eliminated one. */
+  at: string | null;
+  /** One sentence a student could have said out loud. */
+  reason: string;
+  /** The sum, written out as LaTeX. Empty for a deletion, which has no arithmetic. */
+  arithmetic: string;
+  /** The network as it stands AFTER the step, so a scene can redraw it. */
+  after: Network;
+}
+interface Reduction {
+  steps: ReductionStep[];
+  /** The equivalent value, or null if these rules could not finish. */
+  value: number | null;
+  /** What was left when the rules ran out. Null on success. */
+  stuck: Network | null;
+}
+/** Combine components that are in series, for this quantity. */
+declare function combineSeries(quantity: Quantity, values: readonly number[]): number;
+/** Combine components that are in parallel, for this quantity. */
+declare function combineParallel(quantity: Quantity, values: readonly number[]): number;
+/** A value so small the step narrative should treat it as a degenerate component. */
+declare const NEGLIGIBLE = 1e-9;
+declare function validateNetwork(network: Network): Network;
+/**
+ * Reduce until one component spans the terminals, or until no rule applies.
+ *
+ * The step cap guards against a rule that fails to shrink the network rather than imposing a real
+ * limit: every rule above removes at least one component, so a network of n finishes in under n
+ * steps and the cap should never be reached.
+ */
+declare function reduce(input: Network): Reduction;
+/**
+ * Equivalent value straight from the nodal solver: put 1 V across the terminals, read the current,
+ * divide.
+ *
+ * This is what the reduction narrative is checked against. It shares no code with the rules above,
+ * which is the entire point: if a rule were wrong, agreeing with itself would prove nothing.
+ *
+ * A CAPACITANCE network is solved by handing the matrix the elastances, 1/C, as if they were
+ * resistances. That is not a trick: a capacitor's impedance is proportional to 1/C, so a network of
+ * capacitors combines exactly as a network of resistors of value 1/C does, and inverting the answer
+ * gives the equivalent capacitance. It also means capacitance is checked by a solver that has never
+ * heard of a capacitor, which is the strongest form this check can take.
+ */
+declare function equivalentByNodalAnalysis(input: Network): number | null;
+/**
+ * An UNBALANCED five-component bridge, by the star-delta transform.
+ *
+ * Series and parallel genuinely cannot touch this network: no two components share both ends, and
+ * every internal node joins three. That is not a gap in the rules, it is a fact about the shape,
+ * and it is the honest reason star-delta is taught at all.
+ *
+ * Stated for resistance, which is where the syllabus uses it. The same numbers serve a capacitive
+ * bridge if the arms are given as elastances, for the reason spelled out above.
+ */
+declare function starFromDelta(ab: number, bc: number, ca: number): [number, number, number];
+declare function deltaFromStar(a: number, b: number, c: number): [number, number, number];
+/**
+ * The classic infinite ladder: `series` in each arm and `shunt` across, repeating forever.
+ *
+ * Solved the way the textbook does, by noticing that adding one more section leaves the network
+ * looking exactly as it did:
+ *
+ *     x = series + (shunt · x) / (shunt + x)
+ *
+ * which rearranges to a quadratic whose positive root is the answer. Included because it is the one
+ * network where the reduction rules are useless and the INSIGHT is the whole method, and because
+ * students meet it in every admission paper.
+ */
+declare function infiniteLadderOhm(series: number, shunt: number): number;
+/** The unit a quantity is quoted in, for a scene that has to label it. */
+declare const unitFor: (quantity: Quantity) => string;
+declare const symbolFor: (quantity: Quantity) => string;
+//#endregion
+export { Component, NEGLIGIBLE, Network, Quantity, Reduction, ReductionRule, ReductionStep, combineParallel, combineSeries, deltaFromStar, equivalentByNodalAnalysis, infiniteLadderOhm, reduce, starFromDelta, symbolFor, unitFor, validateNetwork };