@classytic/stage 0.2.0 → 0.4.0

package/dist/view/Stage.mjs

@@ -31,7 +31,7 @@ function Stage({ view = DEFAULT_VIEW, width, height, aspectRatio, pad = 12, pres
 	}), [
 		w,
 		h,
-		view,
+		`${view.xMin} ${view.xMax} ${view.yMin} ${view.yMax}`,
 		pad,
 		preserveAspect
 	]);
@@ -43,8 +43,7 @@ function Stage({ view = DEFAULT_VIEW, width, height, aspectRatio, pad = 12, pres
 	} : void 0;
 	return /* @__PURE__ */ jsx("div", {
 		ref: wrapRef,
-		className,
-		style: { width: "100%" },
+		className: ["stage-root", className].filter(Boolean).join(" "),
 		children: /* @__PURE__ */ jsxs("svg", {
 			ref: svgRef,
 			width: w,
@@ -53,14 +52,8 @@ function Stage({ view = DEFAULT_VIEW, width, height, aspectRatio, pad = 12, pres
 			role: "group",
 			"aria-label": ariaLabel,
 			onPointerDown: handlePointer,
-			style: {
-				display: "block",
-				background,
-				borderRadius: 12,
-				border: "1px solid var(--stage-grid)",
-				userSelect: "none",
-				touchAction: "none"
-			},
+			className: "stage-canvas",
+			style: { background },
 			children: [/* @__PURE__ */ jsx("defs", { children: /* @__PURE__ */ jsx("marker", {
 				id: "stage-arrow",
 				viewBox: "0 0 10 10",

package/dist/waves/damping.d.mts

@@ -0,0 +1,224 @@
+//#region src/waves/damping.d.ts
+/**
+ * Damped and driven oscillation: why a car does not bounce, and why a bridge
+ * sometimes does.
+ *
+ * ## One number decides everything
+ *
+ *     ζ = c / (2√(mk))
+ *
+ * The damping ratio. It is dimensionless, and it sorts every oscillator into
+ * one of three behaviours with no room for anything in between:
+ *
+ *   ζ < 1   UNDERDAMPED   overshoots and rings                a worn shock absorber
+ *   ζ = 1   CRITICAL      returns fastest, without overshoot  a good one
+ *   ζ > 1   OVERDAMPED    returns slowly, without overshoot   a door closer
+ *
+ * The suspension of a car is deliberately set a little under 1, because
+ * perfectly critical feels dead and a slight overshoot reads as comfortable.
+ * The spring alone would leave ζ = 0 and the car would bounce down the road;
+ * the damper is the entire reason it does not.
+ *
+ * ## Critical damping is not "the most damping"
+ *
+ * It is the BOUNDARY, and the standard misreading is that more damping always
+ * settles faster. It does not. Past ζ = 1 the oscillator crawls back, and an
+ * overdamped car would still be sinking into the dip long after it had left it.
+ * `settlingTime` is the function that shows this turning round.
+ *
+ * ## Driving it, and where the peak actually is
+ *
+ * Push an oscillator at a frequency near its own and the amplitude climbs. The
+ * peak is NOT at ω₀ once there is damping: it sits at
+ *
+ *     ω_peak = ω₀√(1 − 2ζ²)
+ *
+ * and for ζ above 1/√2 ≈ 0.707 there is no peak at all, only a curve that falls
+ * from the start. Both of those are routinely taught as "resonance is at the
+ * natural frequency", which is the undamped limit of a more interesting fact.
+ *
+ * ## Relation to the RLC circuit
+ *
+ * A series RLC is the same equations with m↔L, k↔1/C, c↔R, so `mechanicalQ`
+ * here and `qualityFactor` in `@classytic/stage/circuit` are the same quantity
+ * for the same reason. They are kept apart because the arguments are different
+ * physical things, not because the mathematics differs, and
+ * `tests/waves/damping.test.ts` checks that the two agree under the analogy so
+ * they cannot drift.
+ *
+ * Units: SI. The damping coefficient `c` is in N·s/m, so that cv is a force.
+ */
+/** How an oscillator returns to rest. The three cases are exhaustive. */
+type DampingRegime = 'underdamped' | 'critically damped' | 'overdamped';
+/**
+ * The damping coefficient that sits exactly on the boundary: c_c = 2√(mk).
+ *
+ * The target a shock absorber is designed against. Quoted in N·s/m, and for a
+ * quarter of a family car (around 300 kg on a 30 kN/m spring) it comes out near
+ * 6,000 N·s/m. A real damper is fitted at roughly a third of that, because the
+ * car is deliberately left underdamped: see the module note above.
+ */
+declare const criticalDamping: (mass: number, stiffness: number) => number;
+/** The damping ratio ζ = c/c_c. Dimensionless, and the only number that matters. */
+declare const dampingRatio: (mass: number, stiffness: number, coefficient: number) => number;
+/**
+ * Which of the three behaviours a damping ratio produces.
+ *
+ * The boundary is tested with a tolerance because exact equality is not
+ * something a measured ζ ever achieves, and a ratio of 0.9999999 behaves like
+ * critical damping in every way that a learner or a graph can see.
+ */
+declare function dampingRegime(ratio: number, tolerance?: number): DampingRegime;
+/**
+ * The frequency a damped oscillator actually rings at: ω_d = ω₀√(1 − ζ²).
+ *
+ * LOWER than the natural frequency, always. Damping slows the ringing as well
+ * as shrinking it, though only slightly until ζ gets large: at ζ = 0.1 the
+ * frequency is down by half a percent, which is why the effect is usually
+ * ignored and why ignoring it is usually fine.
+ *
+ * Throws at ζ ≥ 1, where there is no ringing left to have a frequency.
+ */
+declare function dampedAngularFrequency(naturalOmega: number, ratio: number): number;
+/**
+ * Displacement of a damped oscillator released from rest at `amplitude`.
+ *
+ * x(0) = A, v(0) = 0: pulled aside and let go, which is the car meeting a bump
+ * and the door being pushed open. All three regimes are handled, and they are
+ * three different formulas rather than one with a parameter:
+ *
+ *   under      A·e^(−ζω₀t)·[cos ω_d t + (ζω₀/ω_d)·sin ω_d t]
+ *   critical   A·e^(−ω₀t)·(1 + ω₀t)
+ *   over       A·e^(−ζω₀t)·[cosh rt + (ζω₀/r)·sinh rt],  r = ω₀√(ζ² − 1)
+ *
+ * The critical case is not a special case of the other two: at ζ = 1 both ω_d
+ * and r are zero and both expressions become 0/0. Evaluating the underdamped
+ * form at ζ = 0.99999 gives the right answer only because floating point has
+ * not quite reached the singularity yet, which is not a thing to rely on. The
+ * tests check that the three agree as ζ approaches 1 from either side, which is
+ * what makes the seam safe.
+ */
+declare function dampedDisplacement(amplitude: number, naturalOmega: number, ratio: number, t: number): number;
+/**
+ * Velocity of that same released oscillator, m/s.
+ *
+ * Worth having separately rather than differencing the displacement, because
+ * the interesting question about a suspension is how hard it throws you, and
+ * that is a rate rather than a position. Every regime collapses to the same
+ * tidy form once differentiated:
+ *
+ *   under      −A·(ω₀²/ω_d)·e^(−ζω₀t)·sin ω_d t
+ *   critical   −A·ω₀²·t·e^(−ω₀t)
+ *   over       −A·(ω₀²/r)·e^(−ζω₀t)·sinh rt
+ */
+declare function dampedVelocity(amplitude: number, naturalOmega: number, ratio: number, t: number): number;
+/**
+ * The mechanical quality factor: Q = √(mk)/c = 1/(2ζ).
+ *
+ * How many radians of oscillation it takes to lose most of the energy, near
+ * enough. A tuning fork has a Q in the thousands and rings for seconds; a car
+ * suspension has a Q near 1 and does not ring at all, which is the entire
+ * design intent.
+ */
+declare const mechanicalQ: (mass: number, stiffness: number, coefficient: number) => number;
+/** Q directly from a damping ratio: Q = 1/(2ζ). */
+declare const qFromDampingRatio: (ratio: number) => number;
+/**
+ * The steady amplitude of an oscillator driven at ω by a force of amplitude F₀.
+ *
+ *     A(ω) = (F₀/m) / √((ω₀² − ω²)² + (2ζω₀ω)²)
+ *
+ * The resonance curve. At ω far below ω₀ it settles to the static deflection
+ * F₀/k, which is the sanity check worth knowing: push slowly and the spring
+ * just stretches. At ω far above, the mass cannot keep up and the amplitude
+ * falls away as 1/ω².
+ *
+ * With ζ = 0 and ω = ω₀ the denominator is zero and the amplitude is infinite.
+ * That is not a bug to guard against: it is the statement that an undriven,
+ * undamped resonance has no limit, which is why every real structure has
+ * damping designed into it.
+ */
+declare function drivenAmplitude(forceAmplitude: number, mass: number, naturalOmega: number, ratio: number, omega: number): number;
+/**
+ * Amplitude as a multiple of the static deflection F₀/k, dimensionless.
+ *
+ * The shape of the resonance curve with the units taken out, so two oscillators
+ * of different size can be compared on one graph. It is 1 at ω = 0 by
+ * construction, which anchors the curve at a value a learner can reason about
+ * instead of a bare number.
+ */
+declare function amplificationFactor(naturalOmega: number, ratio: number, omega: number): number;
+/**
+ * The driving frequency that gives the LARGEST amplitude: ω₀√(1 − 2ζ²).
+ *
+ * Below ω₀, and noticeably so once ζ is appreciable. Above ζ = 1/√2 there is no
+ * peak: the amplitude only falls as the driving frequency rises, so a heavily
+ * damped system cannot be made to resonate at all. Throws there rather than
+ * returning the square root of a negative number, because "there is no
+ * resonant frequency" is the answer and NaN does not say it.
+ */
+declare function resonantAngularFrequency(naturalOmega: number, ratio: number): number;
+/**
+ * The phase by which the oscillator lags the driving force, radians, 0 to π.
+ *
+ *     tan φ = 2ζ(ω/ω₀) / (1 − (ω/ω₀)²)
+ *
+ * Exactly π/2 AT ω₀, whatever the damping, and that is the sharpest way to find
+ * a resonance in practice: the amplitude peak moves with ζ and is broad, but the
+ * quarter-cycle lag sits at ω₀ and crosses steeply. Well below resonance the
+ * mass follows the force in step; well above, it moves exactly opposite to it,
+ * which is why a spinning machine mounted softly enough transmits almost
+ * nothing to its floor.
+ */
+declare function drivenPhaseLag(naturalOmega: number, ratio: number, omega: number): number;
+/**
+ * How long until a released oscillator stays within `band` of its amplitude.
+ *
+ * `band` is a fraction, so 0.05 is the usual "settled to within 5 %". Found by
+ * stepping rather than solved, because the crossing has no closed form once the
+ * oscillation is still ringing through the band.
+ *
+ * The reason this function exists is to make the turning point visible: sweep ζ
+ * and the settling time falls to a minimum near 1 and climbs again after it.
+ * That minimum is what a suspension engineer is buying.
+ */
+declare function settlingTime(naturalOmega: number, ratio: number, band?: number, maxPeriods?: number): number;
+/**
+ * The fraction of its amplitude an underdamped oscillator keeps each cycle.
+ *
+ *     ratio = e^(−2πζ/√(1 − ζ²))
+ *
+ * Successive peaks fall by the same FACTOR, never the same amount, so the decay
+ * is a geometric sequence. The natural logarithm of this is the logarithmic
+ * decrement, which is how ζ is measured off a real trace: count the peaks.
+ */
+declare function amplitudeRatioPerCycle(ratio: number): number;
+/**
+ * The decay time constant, seconds: τ = 1/(ζω₀).
+ *
+ * The bridge between the two ways this topic is parameterised. Engineering
+ * states damping as ζ; the light-damping treatment in most physics courses
+ * states it as an envelope A₀·e^(−t/τ) and never mentions ζ at all. They are
+ * the same oscillator, and this is the conversion, so neither vocabulary needs
+ * its own copy of the decay.
+ */
+declare const decayTimeConstant: (naturalOmega: number, ratio: number) => number;
+/**
+ * Amplitude of a lightly damped oscillator after a time: A = A₀·e^(−t/τ).
+ *
+ * The ENVELOPE, not the displacement: the oscillation rings inside this curve
+ * and touches it at the peaks. `dampedDisplacement` is the thing itself.
+ *
+ * The energy falls as the SQUARE of the amplitude, so it decays twice as fast:
+ * an oscillator that has lost half its amplitude has lost three quarters of its
+ * energy. That factor of two is the thing most often dropped.
+ */
+declare function dampedAmplitude(initialAmplitude: number, timeConstant: number, t: number): number;
+/** Energy of a lightly damped oscillator after a time: E = E₀·e^(−2t/τ). */
+declare function dampedEnergy(initialEnergy: number, timeConstant: number, t: number): number;
+/** The logarithmic decrement δ = 2πζ/√(1 − ζ²), read off a decaying trace. */
+declare const logarithmicDecrement: (ratio: number) => number;
+/** The damping ratio implied by a measured logarithmic decrement: ζ = δ/√(4π² + δ²). */
+declare function dampingRatioFromDecrement(decrement: number): number;
+//#endregion
+export { DampingRegime, amplificationFactor, amplitudeRatioPerCycle, criticalDamping, dampedAmplitude, dampedAngularFrequency, dampedDisplacement, dampedEnergy, dampedVelocity, dampingRatio, dampingRatioFromDecrement, dampingRegime, decayTimeConstant, drivenAmplitude, drivenPhaseLag, logarithmicDecrement, mechanicalQ, qFromDampingRatio, resonantAngularFrequency, settlingTime };

package/dist/waves/damping.mjs

@@ -0,0 +1,317 @@
+//#region src/waves/damping.ts
+/**
+* Damped and driven oscillation: why a car does not bounce, and why a bridge
+* sometimes does.
+*
+* ## One number decides everything
+*
+*     ζ = c / (2√(mk))
+*
+* The damping ratio. It is dimensionless, and it sorts every oscillator into
+* one of three behaviours with no room for anything in between:
+*
+*   ζ < 1   UNDERDAMPED   overshoots and rings                a worn shock absorber
+*   ζ = 1   CRITICAL      returns fastest, without overshoot  a good one
+*   ζ > 1   OVERDAMPED    returns slowly, without overshoot   a door closer
+*
+* The suspension of a car is deliberately set a little under 1, because
+* perfectly critical feels dead and a slight overshoot reads as comfortable.
+* The spring alone would leave ζ = 0 and the car would bounce down the road;
+* the damper is the entire reason it does not.
+*
+* ## Critical damping is not "the most damping"
+*
+* It is the BOUNDARY, and the standard misreading is that more damping always
+* settles faster. It does not. Past ζ = 1 the oscillator crawls back, and an
+* overdamped car would still be sinking into the dip long after it had left it.
+* `settlingTime` is the function that shows this turning round.
+*
+* ## Driving it, and where the peak actually is
+*
+* Push an oscillator at a frequency near its own and the amplitude climbs. The
+* peak is NOT at ω₀ once there is damping: it sits at
+*
+*     ω_peak = ω₀√(1 − 2ζ²)
+*
+* and for ζ above 1/√2 ≈ 0.707 there is no peak at all, only a curve that falls
+* from the start. Both of those are routinely taught as "resonance is at the
+* natural frequency", which is the undamped limit of a more interesting fact.
+*
+* ## Relation to the RLC circuit
+*
+* A series RLC is the same equations with m↔L, k↔1/C, c↔R, so `mechanicalQ`
+* here and `qualityFactor` in `@classytic/stage/circuit` are the same quantity
+* for the same reason. They are kept apart because the arguments are different
+* physical things, not because the mathematics differs, and
+* `tests/waves/damping.test.ts` checks that the two agree under the analogy so
+* they cannot drift.
+*
+* Units: SI. The damping coefficient `c` is in N·s/m, so that cv is a force.
+*/
+const finite = (value, what) => {
+	if (!Number.isFinite(value)) throw new RangeError(`${what} must be a finite number.`);
+	return value;
+};
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive.`);
+	return value;
+};
+const nonNegative = (value, what) => {
+	if (!Number.isFinite(value) || value < 0) throw new RangeError(`${what} cannot be negative.`);
+	return value;
+};
+/**
+* The damping coefficient that sits exactly on the boundary: c_c = 2√(mk).
+*
+* The target a shock absorber is designed against. Quoted in N·s/m, and for a
+* quarter of a family car (around 300 kg on a 30 kN/m spring) it comes out near
+* 6,000 N·s/m. A real damper is fitted at roughly a third of that, because the
+* car is deliberately left underdamped: see the module note above.
+*/
+const criticalDamping = (mass, stiffness) => 2 * Math.sqrt(positive(mass, "A mass") * positive(stiffness, "A spring stiffness"));
+/** The damping ratio ζ = c/c_c. Dimensionless, and the only number that matters. */
+const dampingRatio = (mass, stiffness, coefficient) => nonNegative(coefficient, "A damping coefficient") / criticalDamping(mass, stiffness);
+/**
+* Which of the three behaviours a damping ratio produces.
+*
+* The boundary is tested with a tolerance because exact equality is not
+* something a measured ζ ever achieves, and a ratio of 0.9999999 behaves like
+* critical damping in every way that a learner or a graph can see.
+*/
+function dampingRegime(ratio, tolerance = 1e-9) {
+	const zeta = nonNegative(ratio, "A damping ratio");
+	if (Math.abs(zeta - 1) <= tolerance) return "critically damped";
+	return zeta < 1 ? "underdamped" : "overdamped";
+}
+/**
+* The frequency a damped oscillator actually rings at: ω_d = ω₀√(1 − ζ²).
+*
+* LOWER than the natural frequency, always. Damping slows the ringing as well
+* as shrinking it, though only slightly until ζ gets large: at ζ = 0.1 the
+* frequency is down by half a percent, which is why the effect is usually
+* ignored and why ignoring it is usually fine.
+*
+* Throws at ζ ≥ 1, where there is no ringing left to have a frequency.
+*/
+function dampedAngularFrequency(naturalOmega, ratio) {
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	if (zeta >= 1) throw new RangeError(`At a damping ratio of ${zeta} the motion does not oscillate, so it has no damped frequency.`);
+	return w0 * Math.sqrt(1 - zeta * zeta);
+}
+/**
+* Displacement of a damped oscillator released from rest at `amplitude`.
+*
+* x(0) = A, v(0) = 0: pulled aside and let go, which is the car meeting a bump
+* and the door being pushed open. All three regimes are handled, and they are
+* three different formulas rather than one with a parameter:
+*
+*   under      A·e^(−ζω₀t)·[cos ω_d t + (ζω₀/ω_d)·sin ω_d t]
+*   critical   A·e^(−ω₀t)·(1 + ω₀t)
+*   over       A·e^(−ζω₀t)·[cosh rt + (ζω₀/r)·sinh rt],  r = ω₀√(ζ² − 1)
+*
+* The critical case is not a special case of the other two: at ζ = 1 both ω_d
+* and r are zero and both expressions become 0/0. Evaluating the underdamped
+* form at ζ = 0.99999 gives the right answer only because floating point has
+* not quite reached the singularity yet, which is not a thing to rely on. The
+* tests check that the three agree as ζ approaches 1 from either side, which is
+* what makes the seam safe.
+*/
+function dampedDisplacement(amplitude, naturalOmega, ratio, t) {
+	const A = finite(amplitude, "An amplitude");
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	const time = nonNegative(t, "A time");
+	const decay = Math.exp(-zeta * w0 * time);
+	if (dampingRegime(zeta) === "critically damped") return A * decay * (1 + w0 * time);
+	if (zeta < 1) {
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		return A * decay * (Math.cos(wd * time) + zeta * w0 / wd * Math.sin(wd * time));
+	}
+	const r = w0 * Math.sqrt(zeta * zeta - 1);
+	return A * decay * (Math.cosh(r * time) + zeta * w0 / r * Math.sinh(r * time));
+}
+/**
+* Velocity of that same released oscillator, m/s.
+*
+* Worth having separately rather than differencing the displacement, because
+* the interesting question about a suspension is how hard it throws you, and
+* that is a rate rather than a position. Every regime collapses to the same
+* tidy form once differentiated:
+*
+*   under      −A·(ω₀²/ω_d)·e^(−ζω₀t)·sin ω_d t
+*   critical   −A·ω₀²·t·e^(−ω₀t)
+*   over       −A·(ω₀²/r)·e^(−ζω₀t)·sinh rt
+*/
+function dampedVelocity(amplitude, naturalOmega, ratio, t) {
+	const A = finite(amplitude, "An amplitude");
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	const time = nonNegative(t, "A time");
+	const decay = Math.exp(-zeta * w0 * time);
+	if (dampingRegime(zeta) === "critically damped") return -A * w0 * w0 * time * decay;
+	if (zeta < 1) {
+		const wd = w0 * Math.sqrt(1 - zeta * zeta);
+		return -A * (w0 * w0) * decay * Math.sin(wd * time) / wd;
+	}
+	const r = w0 * Math.sqrt(zeta * zeta - 1);
+	return -A * (w0 * w0) * decay * Math.sinh(r * time) / r;
+}
+/**
+* The mechanical quality factor: Q = √(mk)/c = 1/(2ζ).
+*
+* How many radians of oscillation it takes to lose most of the energy, near
+* enough. A tuning fork has a Q in the thousands and rings for seconds; a car
+* suspension has a Q near 1 and does not ring at all, which is the entire
+* design intent.
+*/
+const mechanicalQ = (mass, stiffness, coefficient) => 1 / (2 * dampingRatio(mass, stiffness, coefficient));
+/** Q directly from a damping ratio: Q = 1/(2ζ). */
+const qFromDampingRatio = (ratio) => 1 / (2 * positive(ratio, "A damping ratio"));
+/**
+* The steady amplitude of an oscillator driven at ω by a force of amplitude F₀.
+*
+*     A(ω) = (F₀/m) / √((ω₀² − ω²)² + (2ζω₀ω)²)
+*
+* The resonance curve. At ω far below ω₀ it settles to the static deflection
+* F₀/k, which is the sanity check worth knowing: push slowly and the spring
+* just stretches. At ω far above, the mass cannot keep up and the amplitude
+* falls away as 1/ω².
+*
+* With ζ = 0 and ω = ω₀ the denominator is zero and the amplitude is infinite.
+* That is not a bug to guard against: it is the statement that an undriven,
+* undamped resonance has no limit, which is why every real structure has
+* damping designed into it.
+*/
+function drivenAmplitude(forceAmplitude, mass, naturalOmega, ratio, omega) {
+	const F0 = nonNegative(forceAmplitude, "A driving force amplitude");
+	const m = positive(mass, "A mass");
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	const w = nonNegative(omega, "A driving angular frequency");
+	const denominator = Math.hypot(w0 * w0 - w * w, 2 * zeta * w0 * w);
+	return denominator === 0 ? Number.POSITIVE_INFINITY : F0 / m / denominator;
+}
+/**
+* Amplitude as a multiple of the static deflection F₀/k, dimensionless.
+*
+* The shape of the resonance curve with the units taken out, so two oscillators
+* of different size can be compared on one graph. It is 1 at ω = 0 by
+* construction, which anchors the curve at a value a learner can reason about
+* instead of a bare number.
+*/
+function amplificationFactor(naturalOmega, ratio, omega) {
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	const r = nonNegative(omega, "A driving angular frequency") / w0;
+	const denominator = Math.hypot(1 - r * r, 2 * zeta * r);
+	return denominator === 0 ? Number.POSITIVE_INFINITY : 1 / denominator;
+}
+/**
+* The driving frequency that gives the LARGEST amplitude: ω₀√(1 − 2ζ²).
+*
+* Below ω₀, and noticeably so once ζ is appreciable. Above ζ = 1/√2 there is no
+* peak: the amplitude only falls as the driving frequency rises, so a heavily
+* damped system cannot be made to resonate at all. Throws there rather than
+* returning the square root of a negative number, because "there is no
+* resonant frequency" is the answer and NaN does not say it.
+*/
+function resonantAngularFrequency(naturalOmega, ratio) {
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	if (zeta >= Math.SQRT1_2) throw new RangeError(`At a damping ratio of ${zeta} the amplitude peaks at zero frequency: above 1/√2 there is no resonance to find.`);
+	return w0 * Math.sqrt(1 - 2 * zeta * zeta);
+}
+/**
+* The phase by which the oscillator lags the driving force, radians, 0 to π.
+*
+*     tan φ = 2ζ(ω/ω₀) / (1 − (ω/ω₀)²)
+*
+* Exactly π/2 AT ω₀, whatever the damping, and that is the sharpest way to find
+* a resonance in practice: the amplitude peak moves with ζ and is broad, but the
+* quarter-cycle lag sits at ω₀ and crosses steeply. Well below resonance the
+* mass follows the force in step; well above, it moves exactly opposite to it,
+* which is why a spinning machine mounted softly enough transmits almost
+* nothing to its floor.
+*/
+function drivenPhaseLag(naturalOmega, ratio, omega) {
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	const r = nonNegative(omega, "A driving angular frequency") / w0;
+	const lag = Math.atan2(2 * zeta * r, 1 - r * r);
+	return lag < 0 ? lag + Math.PI : lag;
+}
+/**
+* How long until a released oscillator stays within `band` of its amplitude.
+*
+* `band` is a fraction, so 0.05 is the usual "settled to within 5 %". Found by
+* stepping rather than solved, because the crossing has no closed form once the
+* oscillation is still ringing through the band.
+*
+* The reason this function exists is to make the turning point visible: sweep ζ
+* and the settling time falls to a minimum near 1 and climbs again after it.
+* That minimum is what a suspension engineer is buying.
+*/
+function settlingTime(naturalOmega, ratio, band = .05, maxPeriods = 200) {
+	const w0 = positive(naturalOmega, "A natural angular frequency");
+	const zeta = nonNegative(ratio, "A damping ratio");
+	if (!(band > 0 && band < 1)) throw new RangeError("A settling band must be a fraction between 0 and 1.");
+	if (zeta === 0) return Number.POSITIVE_INFINITY;
+	const horizon = maxPeriods * 2 * Math.PI / w0;
+	const step = 2 * Math.PI / w0 / 400;
+	let settledAt = Number.POSITIVE_INFINITY;
+	for (let t = 0; t <= horizon; t += step) if (Math.abs(dampedDisplacement(1, w0, zeta, t)) > band) settledAt = Number.POSITIVE_INFINITY;
+	else if (settledAt === Number.POSITIVE_INFINITY) settledAt = t;
+	return settledAt;
+}
+/**
+* The fraction of its amplitude an underdamped oscillator keeps each cycle.
+*
+*     ratio = e^(−2πζ/√(1 − ζ²))
+*
+* Successive peaks fall by the same FACTOR, never the same amount, so the decay
+* is a geometric sequence. The natural logarithm of this is the logarithmic
+* decrement, which is how ζ is measured off a real trace: count the peaks.
+*/
+function amplitudeRatioPerCycle(ratio) {
+	const zeta = nonNegative(ratio, "A damping ratio");
+	if (zeta >= 1) throw new RangeError(`At a damping ratio of ${zeta} there are no successive peaks to compare.`);
+	return Math.exp(-2 * Math.PI * zeta / Math.sqrt(1 - zeta * zeta));
+}
+/**
+* The decay time constant, seconds: τ = 1/(ζω₀).
+*
+* The bridge between the two ways this topic is parameterised. Engineering
+* states damping as ζ; the light-damping treatment in most physics courses
+* states it as an envelope A₀·e^(−t/τ) and never mentions ζ at all. They are
+* the same oscillator, and this is the conversion, so neither vocabulary needs
+* its own copy of the decay.
+*/
+const decayTimeConstant = (naturalOmega, ratio) => 1 / (positive(naturalOmega, "A natural angular frequency") * positive(ratio, "A damping ratio"));
+/**
+* Amplitude of a lightly damped oscillator after a time: A = A₀·e^(−t/τ).
+*
+* The ENVELOPE, not the displacement: the oscillation rings inside this curve
+* and touches it at the peaks. `dampedDisplacement` is the thing itself.
+*
+* The energy falls as the SQUARE of the amplitude, so it decays twice as fast:
+* an oscillator that has lost half its amplitude has lost three quarters of its
+* energy. That factor of two is the thing most often dropped.
+*/
+function dampedAmplitude(initialAmplitude, timeConstant, t) {
+	return positive(initialAmplitude, "An amplitude") * Math.exp(-Math.max(0, finite(t, "A time")) / positive(timeConstant, "A time constant"));
+}
+/** Energy of a lightly damped oscillator after a time: E = E₀·e^(−2t/τ). */
+function dampedEnergy(initialEnergy, timeConstant, t) {
+	return positive(initialEnergy, "An energy") * Math.exp(-2 * Math.max(0, finite(t, "A time")) / positive(timeConstant, "A time constant"));
+}
+/** The logarithmic decrement δ = 2πζ/√(1 − ζ²), read off a decaying trace. */
+const logarithmicDecrement = (ratio) => -Math.log(amplitudeRatioPerCycle(ratio));
+/** The damping ratio implied by a measured logarithmic decrement: ζ = δ/√(4π² + δ²). */
+function dampingRatioFromDecrement(decrement) {
+	const d = positive(decrement, "A logarithmic decrement");
+	return d / Math.sqrt(4 * Math.PI ** 2 + d * d);
+}
+
+//#endregion
+export { amplificationFactor, amplitudeRatioPerCycle, criticalDamping, dampedAmplitude, dampedAngularFrequency, dampedDisplacement, dampedEnergy, dampedVelocity, dampingRatio, dampingRatioFromDecrement, dampingRegime, decayTimeConstant, drivenAmplitude, drivenPhaseLag, logarithmicDecrement, mechanicalQ, qFromDampingRatio, resonantAngularFrequency, settlingTime };

package/dist/waves/doppler.d.mts

@@ -0,0 +1,72 @@
+import { Vec2 } from "../core/vec.mjs";
+
+//#region src/waves/doppler.d.ts
+/**
+ * Component of a velocity along the line from source to observer, positive when closing.
+ *
+ * This is what turns the one-dimensional textbook formula into something a scene can use: only the
+ * radial part shifts the pitch, so a source passing to one side is at its unshifted frequency at
+ * the moment of closest approach, when all of its motion is transverse. That instant is the thing a
+ * learner should see and almost never does.
+ */
+declare function radialSpeed(source: Vec2, observer: Vec2, velocity: Vec2): number;
+/**
+ * Observed frequency for a source moving through a still medium: `f_s v / (v - v_r)`.
+ *
+ * `radialSourceSpeed` is positive when the source is closing on the observer. Returns `Infinity` at
+ * exactly Mach 1 (see the header) and a NEGATIVE frequency above it, which is the honest reading of
+ * the formula in a regime where it no longer describes anything: past the sound barrier the wave
+ * arrives before the source does, and this expression stops being the right model. Callers should
+ * branch on `machNumber >= 1` rather than trusting the number.
+ */
+declare function observedFrequencyMovingSource(sourceFrequency: number, waveSpeed: number, radialSourceSpeed: number): number;
+/**
+ * Observed frequency for an observer moving through a still medium: `f_s (v + v_r) / v`.
+ *
+ * Note the different shape: this one cannot diverge, because the observer cannot outrun the wave
+ * into a zero denominator. Racing away at exactly the wave speed gives zero, which is right, as the
+ * crests never catch up.
+ */
+declare function observedFrequencyMovingObserver(sourceFrequency: number, waveSpeed: number, radialObserverSpeed: number): number;
+/**
+ * Both moving, the general case: `f_s (v + v_o) / (v - v_s)`.
+ *
+ * Provided because a scene with a moving listener needs it, not because the syllabus asks. Radial
+ * speeds are positive when closing, for both.
+ */
+declare function observedFrequency(sourceFrequency: number, waveSpeed: number, radialSourceSpeed: number, radialObserverSpeed?: number): number;
+/** Wavelength in the medium ahead of a moving source: `(v - v_s) / f_s`. Goes to zero at Mach 1. */
+declare function wavelengthAhead(sourceFrequency: number, waveSpeed: number, sourceSpeed: number): number;
+/** Wavelength behind a moving source: `(v + v_s) / f_s`. */
+declare function wavelengthBehind(sourceFrequency: number, waveSpeed: number, sourceSpeed: number): number;
+/**
+ * The rise coming and the fall going, as multiples of the source frequency.
+ *
+ * Returns `{ approaching, receding, riseOverFall }`. The third number is the one worth showing: it
+ * is never 1, and it grows with speed, so "the pitch drops as it passes" is only half the story.
+ */
+declare function frequencyShiftAsymmetry(waveSpeed: number, sourceSpeed: number): {
+  approaching: number;
+  receding: number;
+  riseOverFall: number;
+};
+/** Mach number: source speed as a multiple of the wave speed. */
+declare function machNumber(sourceSpeed: number, waveSpeed: number): number;
+/**
+ * Half-angle of the Mach cone, radians: `asin(1 / M)`.
+ *
+ * `null` below Mach 1, because there is no cone: the wavefronts still nest inside one another and
+ * nothing piles up. Returning null rather than NaN lets a scene ask "is there a cone" by asking.
+ */
+declare function machConeHalfAngle(mach: number): number | null;
+/** Radius a wavefront has reached, given when it left and the time now. */
+declare function wavefrontRadius(waveSpeed: number, emittedAt: number, now: number): number;
+/**
+ * Speed of a source from a measured frequency shift, which is the direction the astronomy and radar
+ * uses run in: you have `f_o` and want `v`.
+ *
+ * `v_s = v (1 - f_s / f_o)`, positive when closing.
+ */
+declare function sourceSpeedFromShift(sourceFrequency: number, observedFrequency: number, waveSpeed: number): number;
+//#endregion
+export { frequencyShiftAsymmetry, machConeHalfAngle, machNumber, observedFrequency, observedFrequencyMovingObserver, observedFrequencyMovingSource, radialSpeed, sourceSpeedFromShift, wavefrontRadius, wavelengthAhead, wavelengthBehind };