@classytic/stage 0.2.0 → 0.4.0

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

package/dist/circuit/ac.mjs

@@ -0,0 +1,452 @@
+import { complex_exports } from "../math/complex.mjs";
+import { findBridgeShape, findDangling, findParallelGroup, findSelfLoop, findSeriesPair, isReduced, mergedId, validateTopology } from "./topology.mjs";
+
+//#region src/circuit/ac.ts
+/**
+* @classytic/stage/circuit/ac-impedance — AC steady state: impedance, phasors, resonance and the frequency response of a network.
+*
+* This is the engine the DC ones were a special case of, and saying that plainly is the point of
+* the file. `network-reduction` showed that resistors and capacitors reduce by the same rules with
+* the arithmetic swapped. The swap was never real. It was an artefact of insisting on real numbers:
+*
+*     Z_R = R          Z_L = jωL          Z_C = 1/(jωC)
+*
+* and with those, series ALWAYS adds impedance and parallel always adds admittance, for every
+* component at every frequency. The reciprocal that looked like a special rule for capacitors is
+* just what 1/(jωC) does when you add it up.
+*
+* ── What this buys that DC could not ────────────────────────────────────────────────────────────
+* Everything that depends on frequency, which is most of what a circuit is actually used for:
+* filters, resonance, tuning, coupling, the reason a loudspeaker crossover works, the reason an
+* oscilloscope probe is compensated. It is the core of an undergraduate circuits course and it is
+* on A2 physics as the LCR circuit.
+*
+* ── How it is checked ───────────────────────────────────────────────────────────────────────────
+* Phasor algebra is easy to get subtly wrong in the sign of the reactance, and a test that compares
+* the algebra with itself would never notice. So the tests integrate the governing ODE of a driven
+* series RLC forward in time and measure the steady-state amplitude and phase off the waveform,
+* then compare that with what this file predicts. Time domain against frequency domain is the
+* strongest independent check available for this, and it catches a sign error immediately: a
+* current that should lag would be measured leading.
+*/
+/**
+* The complex kernel is NAMESPACED on purpose, and must stay that way here.
+*
+* `@classytic/stage/math` re-exports it as `export * as complex` because `complex` and `poly` both
+* export an `add` and a `mul` that mean entirely different things. Importing them flat compiles and
+* then silently resolves to whichever the bundler saw last. `C.add` costs two characters and
+* removes the possibility.
+*/
+const { abs, add, argDeg, cx, div, mul, sub } = complex_exports;
+const finitePositive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive`);
+	return value;
+};
+const finiteNonNegative = (value, what) => {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`${what} must be zero or more`);
+	return value;
+};
+/** A resistance so small it is a wire, used to keep a division from blowing up. */
+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.
+*/
+function impedanceOf(element, omegaRadPerS) {
+	const omega = finiteNonNegative(omegaRadPerS, "angular frequency");
+	switch (element.kind) {
+		case "R": return cx(finiteNonNegative(element.value, `resistor ${element.id}`), 0);
+		case "L": return cx(0, omega * finiteNonNegative(element.value, `inductor ${element.id}`));
+		case "C": {
+			const c = finitePositive(element.value, `capacitor ${element.id}`);
+			if (omega === 0) return cx(Infinity, 0);
+			return cx(0, -1 / (omega * c));
+		}
+	}
+}
+/** Reactance: the imaginary part. Positive is inductive, negative is capacitive. */
+const reactance = (z) => z.im;
+/** Resistance: the real part, which is the only part that dissipates energy. */
+const resistance = (z) => z.re;
+/** Magnitude |Z|, in ohms. */
+const magnitude = (z) => abs(z);
+/** Phase of the impedance in degrees. Positive means the current lags the voltage. */
+const phaseDeg = (z) => argDeg(z);
+/** Series impedances add. Always, for every component kind, at every frequency. */
+function seriesImpedance(zs) {
+	return zs.reduce((sum, z) => add(sum, z), cx(0, 0));
+}
+/**
+* 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.
+*/
+function parallelImpedance(zs) {
+	let y = cx(0, 0);
+	for (const z of zs) {
+		if (!Number.isFinite(z.re) || !Number.isFinite(z.im)) continue;
+		if (abs(z) < 1e-12) return cx(0, 0);
+		y = add(y, div(cx(1, 0), z));
+	}
+	if (abs(y) < 1e-12) return cx(Infinity, 0);
+	return div(cx(1, 0), y);
+}
+const asTopology = (network) => ({
+	edges: network.elements,
+	terminals: network.terminals
+});
+/**
+* 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.
+*/
+function equivalentImpedance(network, omegaRadPerS) {
+	validateTopology(asTopology(network));
+	const omega = finiteNonNegative(omegaRadPerS, "angular frequency");
+	let edges = network.elements.map((e) => ({
+		id: e.id,
+		a: e.a,
+		b: e.b
+	}));
+	const z = /* @__PURE__ */ new Map();
+	for (const element of network.elements) z.set(element.id, impedanceOf(element, omega));
+	const terminals = network.terminals;
+	const zOf = (edge) => z.get(edge.id) ?? cx(0, 0);
+	let guard = edges.length * 4 + 8;
+	while (guard-- > 0) {
+		const t = {
+			edges,
+			terminals
+		};
+		if (isReduced(t)) break;
+		const dangling = findDangling(t);
+		if (dangling) {
+			edges = edges.filter((e) => e.id !== dangling.edge.id);
+			continue;
+		}
+		const loop = findSelfLoop(t);
+		if (loop) {
+			edges = edges.filter((e) => e.id !== loop.id);
+			continue;
+		}
+		const group = findParallelGroup(t);
+		if (group) {
+			const id = mergedId(t, group);
+			const combined = parallelImpedance(group.map(zOf));
+			const ids = new Set(group.map((e) => e.id));
+			edges = [...edges.filter((e) => !ids.has(e.id)), {
+				id,
+				a: group[0].a,
+				b: group[0].b
+			}];
+			z.set(id, combined);
+			continue;
+		}
+		const pair = findSeriesPair(t);
+		if (pair) {
+			const id = mergedId(t, pair.edges);
+			const combined = seriesImpedance(pair.edges.map(zOf));
+			const ids = new Set(pair.edges.map((e) => e.id));
+			edges = [...edges.filter((e) => !ids.has(e.id)), {
+				id,
+				a: pair.ends[0],
+				b: pair.ends[1]
+			}];
+			z.set(id, combined);
+			continue;
+		}
+		const shape = findBridgeShape(t);
+		if (shape && bridgeBalances(zOf(shape.p), zOf(shape.q), zOf(shape.r), zOf(shape.s))) {
+			edges = edges.filter((e) => e.id !== shape.bridge.id);
+			continue;
+		}
+		return null;
+	}
+	const only = edges[0];
+	return only ? zOf(only) : null;
+}
+/**
+* Complex Gaussian elimination with partial pivoting.
+*
+* `solveLinear` in `@classytic/stage/circuit` does this for real matrices and cannot be reused:
+* every entry here is a complex admittance, and pivoting has to compare MAGNITUDES rather than
+* signed values. Small enough to own, and the alternative is to represent each complex unknown as
+* two real ones and solve a system of twice the size, which doubles the work and makes every
+* intermediate unreadable.
+*/
+function solveComplexLinear(matrix, rhs) {
+	const n = rhs.length;
+	const a = matrix.map((row, i) => [...row, rhs[i]]);
+	for (let col = 0; col < n; col++) {
+		let best = col;
+		for (let row = col + 1; row < n; row++) if (abs(a[row][col]) > abs(a[best][col])) best = row;
+		if (abs(a[best][col]) < 1e-18) return null;
+		if (best !== col) {
+			const swap = a[best];
+			a[best] = a[col];
+			a[col] = swap;
+		}
+		const pivot = a[col][col];
+		for (let row = col + 1; row < n; row++) {
+			const factor = div(a[row][col], pivot);
+			if (abs(factor) === 0) continue;
+			for (let k = col; k <= n; k++) a[row][k] = sub(a[row][k], mul(factor, a[col][k]));
+		}
+	}
+	const out = new Array(n).fill(cx(0, 0));
+	for (let row = n - 1; row >= 0; row--) {
+		let sum = a[row][n];
+		for (let col = row + 1; col < n; col++) sum = sub(sum, mul(a[row][col], out[col]));
+		out[row] = div(sum, a[row][row]);
+	}
+	return out;
+}
+/** Admittance of one element, with the two degenerate cases handled explicitly. */
+function admittanceOf(element, omega) {
+	const z = impedanceOf(element, omega);
+	if (!Number.isFinite(z.re) || !Number.isFinite(z.im)) return cx(0, 0);
+	if (abs(z) < 1e-12) return cx(1 / TINY, 0);
+	return div(cx(1, 0), z);
+}
+/**
+* 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.
+*/
+function impedanceByNodalAnalysis(network, omegaRadPerS) {
+	validateTopology(asTopology(network));
+	const omega = finiteNonNegative(omegaRadPerS, "angular frequency");
+	const [source, ground] = network.terminals;
+	const index = /* @__PURE__ */ new Map();
+	for (const element of network.elements) for (const node of [element.a, element.b]) if (node !== ground && !index.has(node)) index.set(node, index.size);
+	const driven = index.get(source);
+	if (driven === void 0) return null;
+	const n = index.size;
+	const build = (gmin) => {
+		const y = Array.from({ length: n }, () => Array.from({ length: n }, () => cx(0, 0)));
+		for (let k = 0; k < n; k++) y[k][k] = cx(gmin, 0);
+		for (const element of network.elements) {
+			const ya = admittanceOf(element, omega);
+			const i = element.a === ground ? -1 : index.get(element.a);
+			const j = element.b === ground ? -1 : index.get(element.b);
+			if (i === j) continue;
+			if (i >= 0) y[i][i] = add(y[i][i], ya);
+			if (j >= 0) y[j][j] = add(y[j][j], ya);
+			if (i >= 0 && j >= 0) {
+				y[i][j] = sub(y[i][j], ya);
+				y[j][i] = sub(y[j][i], ya);
+			}
+		}
+		return y;
+	};
+	const current = Array.from({ length: n }, (_, k) => k === driven ? cx(1, 0) : cx(0, 0));
+	/**
+	* A dangling branch leaves its far node connected to nothing else, which makes the matrix
+	* singular even though the network has a perfectly good answer. A tiny conductance to ground on
+	* every node fixes exactly that, and is what every circuit simulator does for the same reason.
+	* It is tried SECOND so an ordinary network is solved with no perturbation at all.
+	*/
+	const solved = solveComplexLinear(build(0), current) ?? solveComplexLinear(build(1e-12), current);
+	if (!solved) return null;
+	const v = solved[driven];
+	return v && Number.isFinite(v.re) && Number.isFinite(v.im) ? v : 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.
+*/
+function bridgeBalances(p, q, r, s) {
+	if (abs(q) < 1e-12 || abs(s) < 1e-12) return false;
+	const left = div(p, q);
+	const right = div(r, s);
+	const scale = Math.max(1, abs(left), abs(right));
+	return abs({
+		re: left.re - right.re,
+		im: left.im - right.im
+	}) < 1e-9 * scale;
+}
+/**
+* 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.
+*/
+function resonantOmega(henries, farads) {
+	return 1 / Math.sqrt(finitePositive(henries, "inductance") * finitePositive(farads, "capacitance"));
+}
+/** Resonance in hertz, which is what a dial is marked in. */
+const resonantHz = (henries, farads) => resonantOmega(henries, farads) / (2 * Math.PI);
+/**
+* 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.
+*/
+function qualityFactor(ohms, henries, farads) {
+	const r = finitePositive(ohms, "resistance");
+	return Math.sqrt(finitePositive(henries, "inductance") / finitePositive(farads, "capacitance")) / r;
+}
+/** The width of the resonance peak between its half-power points, in rad/s. */
+const bandwidthRadPerS = (ohms, henries, farads) => resonantOmega(henries, farads) / qualityFactor(ohms, henries, farads);
+/** How a network responds to a sinusoid of a given peak voltage at one frequency. */
+function responseAt(network, omegaRadPerS, drivePeakV = 1) {
+	/**
+	* Uses the GENERAL solver, not the reducer.
+	*
+	* A frequency response is not a teaching narrative, it is an answer, and an unbalanced bridge has
+	* one even though series and parallel cannot find it. Reaching for the reducer here would make
+	* whole families of perfectly ordinary circuits unplottable.
+	*/
+	const impedance = impedanceByNodalAnalysis(network, omegaRadPerS);
+	if (!impedance) return null;
+	const magnitudeOhm = abs(impedance);
+	const drive = finiteNonNegative(drivePeakV, "driving voltage");
+	return {
+		omegaRadPerS,
+		impedance,
+		magnitudeOhm,
+		phaseDeg: argDeg(impedance),
+		currentAmp: magnitudeOhm > 1e-12 && Number.isFinite(magnitudeOhm) ? drive / magnitudeOhm : 0,
+		currentPhaseDeg: -argDeg(impedance)
+	};
+}
+/**
+* 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.
+*/
+function sweep(network, omegaFrom, omegaTo, points = 120, drivePeakV = 1) {
+	const from = finitePositive(omegaFrom, "start frequency");
+	const to = finitePositive(omegaTo, "end frequency");
+	if (to <= from) throw new RangeError("the sweep must end above where it started");
+	const n = Math.max(2, Math.floor(points));
+	const out = [];
+	for (let i = 0; i < n; i++) {
+		const response = responseAt(network, from * (to / from) ** (i / (n - 1)), drivePeakV);
+		if (response) out.push(response);
+	}
+	return out;
+}
+/**
+* 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.
+*/
+const powerFactor = (z) => {
+	const m = abs(z);
+	return m < 1e-12 ? 1 : z.re / m;
+};
+/** Average power actually dissipated, from RMS current: only the real part counts. */
+const realPowerW = (z, rmsCurrentAmp) => finiteNonNegative(rmsCurrentAmp, "current") ** 2 * z.re;
+/** Apparent power, which is what the supply has to be sized for: |Z| I². */
+const apparentPowerVA = (z, rmsCurrentAmp) => finiteNonNegative(rmsCurrentAmp, "current") ** 2 * abs(z);
+/** RMS is the peak divided by root two, for a sinusoid and for nothing else. */
+const rmsFromPeak = (peak) => finiteNonNegative(peak, "peak") / Math.SQRT2;
+/** A series RLC between A and B, the circuit every resonance question is about. */
+function seriesRlc(ohms, henries, farads) {
+	return {
+		terminals: ["A", "B"],
+		elements: [
+			{
+				id: "R",
+				kind: "R",
+				value: ohms,
+				a: "A",
+				b: "M"
+			},
+			{
+				id: "L",
+				kind: "L",
+				value: henries,
+				a: "M",
+				b: "N"
+			},
+			{
+				id: "C",
+				kind: "C",
+				value: farads,
+				a: "N",
+				b: "B"
+			}
+		]
+	};
+}
+/** A first-order RC low-pass: output taken across the capacitor. */
+function rcLowPass(ohms, farads) {
+	return {
+		terminals: ["A", "B"],
+		elements: [{
+			id: "R",
+			kind: "R",
+			value: ohms,
+			a: "A",
+			b: "M"
+		}, {
+			id: "C",
+			kind: "C",
+			value: farads,
+			a: "M",
+			b: "B"
+		}]
+	};
+}
+/** The −3 dB corner of a first-order RC, where |Z_C| = R and the output has fallen to 1/√2. */
+const rcCornerOmega = (ohms, farads) => 1 / (finitePositive(ohms, "resistance") * finitePositive(farads, "capacitance"));
+/**
+* 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.
+*/
+function dividerGain(zSeries, zShunt) {
+	const total = add(zSeries, zShunt);
+	if (abs(total) < 1e-12) return cx(0, 0);
+	return div(zShunt, total);
+}
+/** Gain expressed in decibels, which is how every frequency response is actually plotted. */
+const decibels = (gain) => gain <= 0 ? -Infinity : 20 * Math.log10(gain);
+/** Multiply two complex numbers, re-exported so a caller need not import the maths kernel too. */
+const timesC = mul;
+
+//#endregion
+export { 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 };