@classytic/stage 0.3.0 → 0.4.0

package/dist/circuit/dc.mjs

@@ -0,0 +1,333 @@
+//#region src/circuit/dc.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);
+}
+
+//#endregion
+export { elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient };

package/dist/circuit/index.d.mts

@@ -1,92 +1,5 @@
-//#region src/circuit/index.d.ts
-/**
- * @classytic/stage/circuit, a small, dependency-free circuit-solver kernel (a
- * mini-SPICE) built on Modified Nodal Analysis (MNA). Like the `field` and `math`
- * kernels it is pure, deterministic engine machinery: you describe a netlist of
- * elements (resistors, sources, capacitors, inductors) and it returns the node
- * voltages and branch currents, the correct numbers, so a current-electricity
- * lab shows real results instead of hand-rolled per-lab arithmetic.
- *
- *   • solveDC       , DC operating point (capacitors open, inductors short).
- *   • solveTransient, time-stepped response (RC / RL / RLC) via Backward-Euler
- *                      companion models: each reactive element becomes a
- *                      conductance Geq in parallel with a current source Ieq each
- *                      step, exactly how real simulators integrate the ODEs.
- *
- * Node 0 is ground (the reference). MNA stamps are additive, so parallel elements
- * just sum. Nonlinear devices (diodes / transistors via Newton-Raphson) are the
- * next layer and slot into the same stamping helpers.
- *
- * Conventions (validated against the MNA / Qucs companion-model references):
- *   • Resistor R between (n1,n2): conductance g = 1/R.
- *   • Current source I: drives `value` amps from n1 to n2 (injected into n2).
- *   • Voltage source V: value volts, n1 is + relative to n2 (adds a branch current
- *     unknown). Its solved current is positive flowing n1 → n2 inside the source.
- */
-type NodeId = number;
-interface Elem {
-  kind: 'R' | 'V' | 'I' | 'C' | 'L' | 'D' | 'M';
-  /** diode: n1=anode, n2=cathode. NMOS 'M': n1=drain, n2=source, n3=gate. */
-  n1: NodeId;
-  n2: NodeId;
-  /** gate node for an NMOS 'M'. */
-  n3?: NodeId;
-  /** ohms (R) / volts (V) / amps (I) / farads (C) / henries (L). Ignored for D / M. */
-  value: number;
-  /** diode saturation current Is (default 1e-12 A). */
-  is?: number;
-  /** diode ideality factor n (default 1). */
-  nIdeal?: number;
-  /** MOSFET threshold voltage Vth (default 2 V; for a PMOS the magnitude is used). */
-  vth?: number;
-  /** MOSFET transconductance parameter k = µCox·W/L (default 0.5 A/V²). */
-  k?: number;
-  /** P-channel MOSFET (conducts when the gate is LOW vs the source). Default NMOS. */
-  pmos?: boolean;
-  /** optional label, used to key the returned branch currents. */
-  id?: string;
-}
-/** Solve A x = b by Gaussian elimination with partial pivoting. Returns null if singular. */
-declare function solveLinear(A: number[][], b: number[]): number[] | null;
-interface DCResult {
-  /** node voltages indexed by node id; [0] is ground = 0. */
-  nodeV: number[];
-  /** current through each branch element (V sources, and inductors), keyed by id. */
-  current: Record<string, number>;
-  ok: boolean;
-}
-/** DC operating point: capacitors open, inductors short. Routes to the nonlinear solver for diodes / MOSFETs. */
-declare function solveDC(elems: readonly Elem[]): DCResult;
-/**
- * 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.
- */
-declare function solveDCNonlinear(elems: readonly Elem[], opts?: {
-  maxIter?: number;
-  tol?: number;
-}): DCResult;
-/** Current through an element given solved node voltages (R/I directly; C/L need state). */
-declare function elementCurrent(e: Elem, nodeV: number[]): number;
-interface TransientStep {
-  t: number;
-  nodeV: number[];
-}
-interface TransientOpts {
-  dt: number;
-  steps: number;
-  /** initial voltages across reactive elements, keyed by element index (default 0). */
-  initialV?: Map<number, number>;
-}
-/**
- * Time-stepped transient (Backward Euler). Returns the node-voltage trajectory,
- * including t = 0. Reactive elements use companion models rebuilt every step.
- */
-declare function solveTransient(elems: readonly Elem[], opts: TransientOpts): TransientStep[];
-/** Equivalent resistance of resistors in series. */
-declare function seriesR(...rs: number[]): number;
-/** Equivalent resistance of resistors in parallel. */
-declare function parallelR(...rs: number[]): number;
-//#endregion
-export { DCResult, Elem, NodeId, TransientOpts, TransientStep, elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient };
+import { DCResult, Elem, NodeId, TransientOpts, TransientStep, elementCurrent, parallelR, seriesR, solveDC, solveDCNonlinear, solveLinear, solveTransient } from "./dc.mjs";
+import { BridgeShape, Edge, SeriesPair, Topology, degrees, findBridgeShape, findDangling, findParallelGroup, findSelfLoop, findSeriesPair, isReduced, isTerminal, mergedId, pairKey, validateTopology } from "./topology.mjs";
+import { Component, NEGLIGIBLE, Network, Quantity, Reduction, ReductionRule, ReductionStep, combineParallel, combineSeries, deltaFromStar, equivalentByNodalAnalysis, infiniteLadderOhm, reduce, starFromDelta, symbolFor, unitFor, validateNetwork } from "./network.mjs";
+import { 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 } from "./ac.mjs";
+export { AcNetwork, AcResponse, BridgeShape, Component, DCResult, Edge, Elem, Element, ElementKind, NEGLIGIBLE, Network, NodeId, Quantity, Reduction, ReductionRule, ReductionStep, SeriesPair, TINY, Topology, TransientOpts, TransientStep, 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 };