@classytic/stage 0.2.0 → 0.4.0

package/dist/waves/pitch.mjs

@@ -0,0 +1,158 @@
+//#region src/waves/pitch.ts
+/**
+* Pitch: turning a frequency into a note, and a note into a place on a string.
+*
+* ## Why pitch is logarithmic, and why that is not a convention
+*
+* Doubling a frequency sounds like the same step wherever you start. 220 to
+* 440 Hz and 440 to 880 Hz are both "an octave", although the second gap is
+* twice as many hertz. So the ear measures RATIOS, and anything that behaves
+* like a distance in pitch has to be a logarithm of one.
+*
+*     one octave    = ratio 2       = 1200 cents
+*     one semitone  = ratio 2^(1/12) = 100 cents
+*
+* A cent is a hundredth of a semitone and is the unit tuners actually use,
+* because "three hertz flat" means something different on a bass string and a
+* piccolo while "eight cents flat" means the same thing everywhere.
+*
+* ## The twelfth root of two, and what it costs
+*
+* Equal temperament divides the octave into twelve identical ratio steps. The
+* price is that no interval except the octave is exactly a whole-number ratio:
+*
+*     pure fifth (3:2)           701.955 cents
+*     equal-tempered fifth       700      cents
+*
+* Two cents flat, everywhere, forever. That deliberate two-cent error is what
+* buys you the ability to change key, and it is the reason a guitar is fretted
+* the way it is. `centsBetween` makes the compromise something you can measure
+* rather than a claim.
+*
+* ## Frets are geometric, not evenly spaced
+*
+* A fret shortens the vibrating length by a RATIO, so the gaps shrink as you go
+* up the neck. The twelfth fret is exactly halfway along the string, because
+* halving the length doubles the frequency: 2^(−12/12) = 1/2. That is a fact
+* you can check with a ruler on a real guitar, which is the best kind.
+*
+* Units: frequencies in hertz, lengths in metres (or any one consistent unit,
+* since `fretPosition` is a proportion of what it is given).
+*/
+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;
+};
+/** Concert A, hertz. The peg the whole system hangs from, fixed by agreement rather than physics. */
+const A4_HZ = 440;
+/** The frequency ratio of one equal-tempered semitone: the twelfth root of two. */
+const SEMITONE_RATIO = Math.pow(2, 1 / 12);
+/** Cents in one octave. A cent is a hundredth of a semitone. */
+const CENTS_PER_OCTAVE = 1200;
+/**
+* The frequency a given number of semitones away: f·2^(n/12).
+*
+* `n` may be negative for downward, and need not be a whole number: a
+* half-semitone is a perfectly good quarter tone, and bending a guitar string
+* lands you between the frets.
+*/
+const frequencyAfterSemitones = (frequency, semitones) => positive(frequency, "A frequency") * Math.pow(2, finite(semitones, "A number of semitones") / 12);
+/** How many semitones apart two frequencies are: 12·log₂(f₂/f₁). Signed. */
+const semitonesBetween = (from, to) => 12 * Math.log2(positive(to, "A frequency") / positive(from, "A frequency"));
+/**
+* The interval between two frequencies in CENTS: 1200·log₂(f₂/f₁).
+*
+* Signed, so a negative result means `to` is flat of `from`. The numbers worth
+* carrying: about 5 cents is the smallest error most people hear on a sustained
+* note, 10 to 15 cents sounds wrong, and a semitone is 100.
+*
+* This is the function that makes "how out of tune is it" answerable. A gap of
+* 3 Hz is badly out on a low E at 82 Hz and inaudible on a harmonic at 1300 Hz;
+* in cents both questions have the same answer scale.
+*/
+const centsBetween = (from, to) => CENTS_PER_OCTAVE * Math.log2(positive(to, "A frequency") / positive(from, "A frequency"));
+/** The frequency a number of cents away from a reference. The inverse of `centsBetween`. */
+const frequencyAfterCents = (frequency, cents) => positive(frequency, "A frequency") * Math.pow(2, finite(cents, "An interval in cents") / CENTS_PER_OCTAVE);
+/**
+* Whether a frequency counts as in tune against a target.
+*
+* `toleranceCents` defaults to 5, which is roughly the threshold at which a
+* sustained note starts to sound wrong to an ordinary listener. Expressed in
+* cents rather than hertz on purpose: a fixed hertz tolerance would be far too
+* strict at the top of the range and useless at the bottom.
+*/
+const isInTune = (frequency, target, toleranceCents = 5) => Math.abs(centsBetween(target, frequency)) <= positive(toleranceCents, "A tolerance");
+/**
+* The length of string still free to vibrate when a fret is held down.
+*
+* `L·2^(−n/12)`: each fret divides the length by the same ratio, which is why
+* they crowd together going up the neck.
+*/
+const frettedLength = (scaleLength, fret) => positive(scaleLength, "A scale length") * Math.pow(2, -nonNegativeFret(fret) / 12);
+/**
+* How far along the string a fret sits, measured from the nut.
+*
+* `L(1 − 2^(−n/12))`. Fret 12 comes out at exactly L/2, which is the check that
+* the formula is the right way round and the thing to verify against a real
+* instrument.
+*/
+const fretPosition = (scaleLength, fret) => positive(scaleLength, "A scale length") - frettedLength(scaleLength, fret);
+/** The gap between two consecutive frets. Always smaller than the one below it. */
+const fretSpacing = (scaleLength, fret) => fretPosition(scaleLength, nonNegativeFret(fret) + 1) - fretPosition(scaleLength, fret);
+function nonNegativeFret(fret) {
+	if (!Number.isInteger(fret) || fret < 0) throw new RangeError(`A fret number must be a whole number of at least 0, not ${fret}.`);
+	return fret;
+}
+/** The names of the twelve semitones, starting at C. Sharps only; no enharmonic choice is made. */
+const SEMITONE_NAMES = [
+	"C",
+	"C♯",
+	"D",
+	"D♯",
+	"E",
+	"F",
+	"F♯",
+	"G",
+	"G♯",
+	"A",
+	"A♯",
+	"B"
+];
+/**
+* The nearest named note to a frequency, and how far off it is.
+*
+* Returns the note with its octave number in scientific pitch notation (A4 is
+* concert A), plus the signed error in cents. The error is the useful half: a
+* tuner is a device for driving that number to zero.
+*/
+function nearestNote(frequency) {
+	const exact = semitonesBetween(440, positive(frequency, "A frequency"));
+	const steps = Math.round(exact);
+	const cents = (exact - steps) * 100;
+	const fromC0 = steps + 9 + 48;
+	const octave = Math.floor(fromC0 / 12);
+	return {
+		name: SEMITONE_NAMES[(fromC0 % 12 + 12) % 12],
+		octave,
+		cents
+	};
+}
+/**
+* The size of a just interval in cents, for comparison with the tempered one.
+*
+* `justIntervalCents(3, 2)` is the pure fifth at 701.955, against the
+* equal-tempered 700. Feeding the small whole-number ratios through this is how
+* the compromise in equal temperament stops being a story: the major third is
+* the bad one, 386.3 just against 400 tempered, nearly 14 cents sharp, and it
+* is audible.
+*/
+const justIntervalCents = (numerator, denominator) => CENTS_PER_OCTAVE * Math.log2(positive(numerator, "A ratio numerator") / positive(denominator, "A ratio denominator"));
+/** The equal-tempered size of an interval of `semitones`, in cents. Always a multiple of 100. */
+const temperedIntervalCents = (semitones) => 100 * finite(semitones, "A number of semitones");
+
+//#endregion
+export { A4_HZ, CENTS_PER_OCTAVE, SEMITONE_NAMES, SEMITONE_RATIO, centsBetween, frequencyAfterCents, frequencyAfterSemitones, fretPosition, fretSpacing, frettedLength, isInTune, justIntervalCents, nearestNote, semitonesBetween, temperedIntervalCents };

package/dist/waves/shm.d.mts

@@ -0,0 +1,170 @@
+import { Worked } from "../core/worked.mjs";
+
+//#region src/waves/shm.d.ts
+/** Angular frequency from a period: ω = 2π/T, rad/s. */
+declare const angularFrequencyFromPeriod: (periodSeconds: number) => number;
+/** Period from an angular frequency: T = 2π/ω, seconds. */
+declare const periodFromAngularFrequency: (omega: number) => number;
+/**
+ * Displacement at time t, starting from the CENTRE moving positive:
+ * x = A·sin(ωt + φ).
+ *
+ * Pass `phase = π/2` to start at maximum displacement instead, which is what a
+ * released-from-rest problem describes. Two starting conventions exist and both
+ * are called "the" SHM equation in different books, so the phase is explicit
+ * rather than baked in.
+ */
+declare function shmDisplacement(amplitude: number, omega: number, t: number, phase?: number): number;
+/** Velocity at time t: v = ωA·cos(ωt + φ), m/s. */
+declare function shmVelocity(amplitude: number, omega: number, t: number, phase?: number): number;
+/** Acceleration at time t: a = −ω²x, m/s². */
+declare function shmAcceleration(amplitude: number, omega: number, t: number, phase?: number): number;
+/**
+ * SPEED at a displacement, m/s: v = ω√(A² − x²).
+ *
+ * The workhorse. Independent of time and of where the motion started, so it
+ * answers "how fast at half amplitude" without anyone having to find t first.
+ * Returns the magnitude; the oscillator passes each point twice a cycle, once
+ * each way, and which one is a question about direction rather than speed.
+ */
+declare function speedAtDisplacement(amplitude: number, omega: number, displacement: number): number;
+/** The displacement at which the oscillator reaches a given speed, m. */
+declare function displacementAtSpeed(amplitude: number, omega: number, speed: number): number;
+/** Greatest speed, at the centre: v_max = ωA, m/s. */
+declare const maxSpeed: (amplitude: number, omega: number) => number;
+/** Greatest acceleration, at the extremes: a_max = ω²A, m/s². */
+declare const maxAcceleration: (amplitude: number, omega: number) => number;
+interface OscillatorState {
+  /** Displacement, m. */
+  displacement: number;
+  /** Velocity, m/s. Signed: the direction of travel is the point of it. */
+  velocity: number;
+  /** Acceleration, m/s². Always −ω² times the displacement. */
+  acceleration: number;
+  /** The phase ωt + φ at this instant, radians, unwrapped. */
+  phase: number;
+}
+/**
+ * Displacement, velocity and acceleration at one instant, in one call.
+ *
+ * ## Why this exists rather than three calls
+ *
+ * Because the three are ONE object, and anything that draws them has to draw
+ * them from the same instant or the picture lies. A render loop asking for
+ * displacement, then velocity, then acceleration is three chances to pass a
+ * different `t`, and the symptom is a v–t curve that is no longer a quarter
+ * cycle ahead of the x–t one: a phase error that looks like a physics error.
+ *
+ * ## The chain the three form
+ *
+ *     x = A·sin(ωt + φ)
+ *     v = ωA·cos(ωt + φ)      a quarter cycle AHEAD of x
+ *     a = −ω²A·sin(ωt + φ)    a quarter cycle ahead of v, so ANTIPHASE with x
+ *
+ * Each differentiation multiplies by ω and advances the phase by π/2. Two of
+ * them bring you back to a sine with a minus sign in front, which is the whole
+ * of a = −ω²x: the defining property of the motion falls out of differentiating
+ * twice and is not an extra assumption.
+ *
+ * `tests/waves/shm.test.ts` asserts each quarter-cycle lead against the others
+ * rather than against a formula, so the chain cannot be broken in one place
+ * only.
+ */
+declare function oscillatorStateAt(amplitude: number, omega: number, t: number, phase?: number): OscillatorState;
+interface OscillatorEnergy {
+  /** Kinetic energy at this displacement, J. */
+  kinetic: number;
+  /** Potential energy at this displacement, J. */
+  potential: number;
+  /** The total, J. The same number at every displacement. */
+  total: number;
+  /**
+   * kinetic + potential − total, J.
+   *
+   * Reported rather than asserted, following the same choice the energy ledger
+   * makes elsewhere in this package: it must be zero to within rounding, and a
+   * caller who wants to PROVE conservation gets to see the number rather than
+   * take it on trust.
+   */
+  residual: number;
+  /** Fraction of the total that is kinetic, 0 to 1. */
+  kineticFraction: number;
+}
+/**
+ * The energy split at a displacement.
+ *
+ * At x = 0 it is all kinetic, at x = ±A all potential, and at x = A/√2 exactly
+ * half each — which is the answer to "where is the energy shared equally" and
+ * is NOT at half amplitude, the usual guess.
+ */
+declare function energyAt(mass: number, amplitude: number, omega: number, displacement: number): OscillatorEnergy;
+/** Total energy of the oscillation, J: E = ½mω²A². Independent of position. */
+declare const totalEnergy: (mass: number, amplitude: number, omega: number) => number;
+/**
+ * The displacement at which kinetic and potential are equal: x = A/√2.
+ *
+ * About 0.707 of the amplitude, not 0.5. The energies go as x², so the halfway
+ * point in ENERGY is not the halfway point in distance, and that gap is the
+ * whole lesson.
+ */
+declare const equalEnergyDisplacement: (amplitude: number) => number;
+/**
+ * The energy split at a displacement, worked, in the form the question wants.
+ *
+ * Deliberately arrives at the same three numbers by TWO routes and shows both:
+ * ½mω²(A² − x²) directly, and ½mv² from the speed at that point. They must
+ * agree, and seeing them agree is the argument that the energy picture and the
+ * kinematic picture are one thing rather than two topics.
+ *
+ * The final step reports KE + PE against the total rather than asserting that
+ * they match, which is the same choice the energy ledger makes elsewhere in the
+ * package: conservation is evidence here, not a claim.
+ */
+declare function energyAtSteps(mass: number, amplitude: number, omega: number, displacement: number, sf?: number): Worked;
+/**
+ * Period of a mass on a spring: T = 2π√(m/k), seconds.
+ *
+ * Independent of amplitude, which is the surprising part and the practical one:
+ * a spring clock keeps time even as the swing dies away.
+ */
+declare const springPeriod: (mass: number, stiffness: number) => number;
+/** Angular frequency of a mass on a spring: ω = √(k/m), rad/s. */
+declare const springAngularFrequency: (mass: number, stiffness: number) => number;
+/**
+ * The period of the ENERGY, seconds: half the period of the motion.
+ *
+ * The single most reliable trap in the topic. Kinetic energy goes as cos²(ωt),
+ * and a squared sinusoid repeats twice as often as the sinusoid does: the
+ * oscillator is at full speed at the centre going one way AND going the other,
+ * and the energy cannot tell those apart because it does not carry a sign.
+ *
+ * So a question that gives you an energy-against-time graph and asks for the
+ * period of the MOTION wants twice what the graph shows. Reading the graph's
+ * own period straight off is the wrong answer, and it is wrong by exactly the
+ * factor this function applies.
+ */
+declare const energyPeriod: (period: number) => number;
+/**
+ * The amplitude implied by a displacement and a velocity at the same moment:
+ * A = √(x² + (v/ω)²).
+ *
+ * v = ω√(A² − x²) rearranged. Any snapshot of the motion fixes the amplitude,
+ * which is how a question that never mentions an amplitude can still be asking
+ * for the total energy.
+ */
+declare function amplitudeFromState(omega: number, displacement: number, velocity: number): number;
+/**
+ * The phase angle δ in x = A·sin(ωt + δ), from the state at t = 0.
+ *
+ * Returned in radians on (−π, π]. Uses `atan2` on (xω, v) rather than
+ * `asin(x₀/A)`, and that choice is the whole function: `asin` cannot tell a
+ * mass at +A/2 moving outward from one at +A/2 moving back, because they share
+ * a sine and differ only in the sign of the cosine. Half the answers from the
+ * `asin` route are the wrong one of the two, silently.
+ *
+ * The familiar special cases fall out: released from rest at full displacement
+ * gives π/2, so x = A·cos(ωt); started from the centre moving positive gives 0.
+ */
+declare function phaseFromState(omega: number, displacement: number, velocity: number): number;
+//#endregion
+export { OscillatorEnergy, OscillatorState, amplitudeFromState, angularFrequencyFromPeriod, displacementAtSpeed, energyAt, energyAtSteps, energyPeriod, equalEnergyDisplacement, maxAcceleration, maxSpeed, oscillatorStateAt, periodFromAngularFrequency, phaseFromState, shmAcceleration, shmDisplacement, shmVelocity, speedAtDisplacement, springAngularFrequency, springPeriod, totalEnergy };

package/dist/waves/shm.mjs

@@ -0,0 +1,279 @@
+import { calc, texNum, texSigFigs } from "../core/worked.mjs";
+
+//#region src/waves/shm.ts
+/**
+* Simple harmonic motion, and the energy bookkeeping that goes with it.
+*
+* ## The definition, which is the acceleration and not the sine
+*
+*     a = −ω²x
+*
+* Acceleration proportional to displacement and directed back towards the
+* centre. The sinusoid is a CONSEQUENCE of that, not the definition, and the
+* distinction matters: a pendulum at large amplitude still swings back and
+* forth sinusoidally to the eye, but its acceleration stops being proportional
+* to displacement and its period starts depending on amplitude. The defining
+* property is the one that fails first.
+*
+* ## The relation this module exists for
+*
+*     v = ±ω·√(A² − x²)
+*
+* Speed as a function of POSITION rather than of time. Nearly every question
+* that asks "how fast is it moving when it is halfway out" is this, and it is
+* the bridge to energy: square it, multiply by ½m, and the kinetic energy falls
+* out as ½mω²(A² − x²). The potential is whatever is left of the total, and the
+* total is constant. That is conservation, visible as arithmetic rather than
+* asserted.
+*
+*     KE = ½mω²(A² − x²)      max at the centre, zero at the extremes
+*     PE = ½mω²x²             zero at the centre, max at the extremes
+*     E  = ½mω²A²             constant, independent of x
+*
+* Note KE + PE = ½mω²A² identically, for every x. `energyAt` returns all three
+* and the residual, so a lab can SHOW the sum staying put while the two halves
+* trade, rather than claiming it does.
+*
+* ## Scope
+*
+* The IDEAL oscillator: no damping, no driving, and given its ω rather than
+* working one out. The three modules either side of it cover the rest:
+*
+*   springs    where k comes from, and what happens when springs are combined
+*   pendulum   the pendulum family, which is a clock, a gravimeter and a lift
+*   damping    what real oscillators do, which is stop
+*
+* They are separate because the failures are separate. Nothing in this file can
+* be wrong about a spring that was cut in half, and nothing in `springs` can be
+* wrong about where the energy went.
+*
+* Units: SI. Displacement and amplitude in metres, mass in kilograms, time in
+* seconds, ω in radians per second, energy in joules.
+*/
+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;
+};
+/**
+* Check a displacement lies within the amplitude.
+*
+* An oscillator cannot be found beyond its own amplitude, and asking for the
+* speed there gives the square root of a negative number. Returning NaN would
+* let an impossible position travel silently into a graph; the throw says which
+* number was wrong.
+*/
+const within = (displacement, amplitude) => {
+	const x = finite(displacement, "A displacement");
+	const A = positive(amplitude, "An amplitude");
+	if (Math.abs(x) > A * 1.000000000001) throw new RangeError(`A displacement of ${x} lies outside the amplitude ${A}: the oscillator never reaches there.`);
+	return Math.max(-A, Math.min(A, x));
+};
+/** Angular frequency from a period: ω = 2π/T, rad/s. */
+const angularFrequencyFromPeriod = (periodSeconds) => 2 * Math.PI / positive(periodSeconds, "A period");
+/** Period from an angular frequency: T = 2π/ω, seconds. */
+const periodFromAngularFrequency = (omega) => 2 * Math.PI / positive(omega, "An angular frequency");
+/**
+* Displacement at time t, starting from the CENTRE moving positive:
+* x = A·sin(ωt + φ).
+*
+* Pass `phase = π/2` to start at maximum displacement instead, which is what a
+* released-from-rest problem describes. Two starting conventions exist and both
+* are called "the" SHM equation in different books, so the phase is explicit
+* rather than baked in.
+*/
+function shmDisplacement(amplitude, omega, t, phase = 0) {
+	return positive(amplitude, "An amplitude") * Math.sin(positive(omega, "An angular frequency") * finite(t, "A time") + finite(phase, "A phase"));
+}
+/** Velocity at time t: v = ωA·cos(ωt + φ), m/s. */
+function shmVelocity(amplitude, omega, t, phase = 0) {
+	const w = positive(omega, "An angular frequency");
+	return w * positive(amplitude, "An amplitude") * Math.cos(w * finite(t, "A time") + finite(phase, "A phase"));
+}
+/** Acceleration at time t: a = −ω²x, m/s². */
+function shmAcceleration(amplitude, omega, t, phase = 0) {
+	const w = positive(omega, "An angular frequency");
+	return -(w * w) * shmDisplacement(amplitude, w, t, phase);
+}
+/**
+* SPEED at a displacement, m/s: v = ω√(A² − x²).
+*
+* The workhorse. Independent of time and of where the motion started, so it
+* answers "how fast at half amplitude" without anyone having to find t first.
+* Returns the magnitude; the oscillator passes each point twice a cycle, once
+* each way, and which one is a question about direction rather than speed.
+*/
+function speedAtDisplacement(amplitude, omega, displacement) {
+	const A = positive(amplitude, "An amplitude");
+	const x = within(displacement, A);
+	return positive(omega, "An angular frequency") * Math.sqrt(A * A - x * x);
+}
+/** The displacement at which the oscillator reaches a given speed, m. */
+function displacementAtSpeed(amplitude, omega, speed) {
+	const A = positive(amplitude, "An amplitude");
+	const w = positive(omega, "An angular frequency");
+	const s = finite(speed, "A speed");
+	const maximum = w * A;
+	if (Math.abs(s) > maximum * 1.000000000001) throw new RangeError(`This oscillator never exceeds ${maximum} m/s, so it is never moving at ${s} m/s.`);
+	return Math.sqrt(Math.max(0, A * A - (s / w) ** 2));
+}
+/** Greatest speed, at the centre: v_max = ωA, m/s. */
+const maxSpeed = (amplitude, omega) => positive(omega, "An angular frequency") * positive(amplitude, "An amplitude");
+/** Greatest acceleration, at the extremes: a_max = ω²A, m/s². */
+const maxAcceleration = (amplitude, omega) => positive(omega, "An angular frequency") ** 2 * positive(amplitude, "An amplitude");
+/**
+* Displacement, velocity and acceleration at one instant, in one call.
+*
+* ## Why this exists rather than three calls
+*
+* Because the three are ONE object, and anything that draws them has to draw
+* them from the same instant or the picture lies. A render loop asking for
+* displacement, then velocity, then acceleration is three chances to pass a
+* different `t`, and the symptom is a v–t curve that is no longer a quarter
+* cycle ahead of the x–t one: a phase error that looks like a physics error.
+*
+* ## The chain the three form
+*
+*     x = A·sin(ωt + φ)
+*     v = ωA·cos(ωt + φ)      a quarter cycle AHEAD of x
+*     a = −ω²A·sin(ωt + φ)    a quarter cycle ahead of v, so ANTIPHASE with x
+*
+* Each differentiation multiplies by ω and advances the phase by π/2. Two of
+* them bring you back to a sine with a minus sign in front, which is the whole
+* of a = −ω²x: the defining property of the motion falls out of differentiating
+* twice and is not an extra assumption.
+*
+* `tests/waves/shm.test.ts` asserts each quarter-cycle lead against the others
+* rather than against a formula, so the chain cannot be broken in one place
+* only.
+*/
+function oscillatorStateAt(amplitude, omega, t, phase = 0) {
+	const A = positive(amplitude, "An amplitude");
+	const w = positive(omega, "An angular frequency");
+	const angle = w * finite(t, "A time") + finite(phase, "A phase");
+	const displacement = A * Math.sin(angle);
+	return {
+		displacement,
+		velocity: w * A * Math.cos(angle),
+		acceleration: -(w * w) * displacement,
+		phase: angle
+	};
+}
+/**
+* The energy split at a displacement.
+*
+* At x = 0 it is all kinetic, at x = ±A all potential, and at x = A/√2 exactly
+* half each — which is the answer to "where is the energy shared equally" and
+* is NOT at half amplitude, the usual guess.
+*/
+function energyAt(mass, amplitude, omega, displacement) {
+	const m = positive(mass, "A mass");
+	const A = positive(amplitude, "An amplitude");
+	const w = positive(omega, "An angular frequency");
+	const x = within(displacement, A);
+	const half = .5 * m * w * w;
+	const kinetic = half * (A * A - x * x);
+	const potential = half * x * x;
+	const total = half * A * A;
+	return {
+		kinetic,
+		potential,
+		total,
+		residual: kinetic + potential - total,
+		kineticFraction: total === 0 ? 0 : kinetic / total
+	};
+}
+/** Total energy of the oscillation, J: E = ½mω²A². Independent of position. */
+const totalEnergy = (mass, amplitude, omega) => .5 * positive(mass, "A mass") * positive(omega, "An angular frequency") ** 2 * positive(amplitude, "An amplitude") ** 2;
+/**
+* The displacement at which kinetic and potential are equal: x = A/√2.
+*
+* About 0.707 of the amplitude, not 0.5. The energies go as x², so the halfway
+* point in ENERGY is not the halfway point in distance, and that gap is the
+* whole lesson.
+*/
+const equalEnergyDisplacement = (amplitude) => positive(amplitude, "An amplitude") / Math.SQRT2;
+/**
+* The energy split at a displacement, worked, in the form the question wants.
+*
+* Deliberately arrives at the same three numbers by TWO routes and shows both:
+* ½mω²(A² − x²) directly, and ½mv² from the speed at that point. They must
+* agree, and seeing them agree is the argument that the energy picture and the
+* kinematic picture are one thing rather than two topics.
+*
+* The final step reports KE + PE against the total rather than asserting that
+* they match, which is the same choice the energy ledger makes elsewhere in the
+* package: conservation is evidence here, not a claim.
+*/
+function energyAtSteps(mass, amplitude, omega, displacement, sf = 3) {
+	const m = positive(mass, "A mass");
+	const A = positive(amplitude, "An amplitude");
+	const w = positive(omega, "An angular frequency");
+	const x = within(displacement, A);
+	const split = energyAt(m, A, w, x);
+	const v = speedAtDisplacement(A, w, x);
+	const stiffness = m * w * w;
+	return calc().step(`v = \\omega\\sqrt{A^2 - x^2} = ${texSigFigs(w, sf)}\\sqrt{${texSigFigs(A, sf)}^2 - ${texSigFigs(x, sf)}^2} = ${texSigFigs(v, sf)}\\ \\mathrm{m\\,s^{-1}}`, "speed from POSITION, so the time never has to be found").step(`E_k = \\tfrac{1}{2}mv^2 = ${texSigFigs(split.kinetic, sf)}\\ \\mathrm{J}`, "the kinematic route").step(`E_k = \\tfrac{1}{2}m\\omega^2(A^2 - x^2) = ${texSigFigs(split.kinetic, sf)}\\ \\mathrm{J}`, "and the energy route, which is the same statement with v substituted").step(`E_p = \\tfrac{1}{2}m\\omega^2 x^2 = \\tfrac{1}{2}kx^2 = ${texSigFigs(split.potential, sf)}\\ \\mathrm{J}`, `with k = m\\omega^2 = ${texSigFigs(stiffness, sf)}\\ \\mathrm{N\\,m^{-1}}, the spring form of the same energy`).step(`E = \\tfrac{1}{2}m\\omega^2 A^2 = ${texSigFigs(split.total, sf)}\\ \\mathrm{J}`, "independent of x: this number is the same everywhere in the swing").step(`E_k + E_p - E = ${texNum(split.residual)}\\ \\mathrm{J}`, "the books balance, and the residual is shown rather than the balance claimed").done(split.total);
+}
+/**
+* Period of a mass on a spring: T = 2π√(m/k), seconds.
+*
+* Independent of amplitude, which is the surprising part and the practical one:
+* a spring clock keeps time even as the swing dies away.
+*/
+const springPeriod = (mass, stiffness) => 2 * Math.PI * Math.sqrt(positive(mass, "A mass") / positive(stiffness, "A spring stiffness"));
+/** Angular frequency of a mass on a spring: ω = √(k/m), rad/s. */
+const springAngularFrequency = (mass, stiffness) => Math.sqrt(positive(stiffness, "A spring stiffness") / positive(mass, "A mass"));
+/**
+* The period of the ENERGY, seconds: half the period of the motion.
+*
+* The single most reliable trap in the topic. Kinetic energy goes as cos²(ωt),
+* and a squared sinusoid repeats twice as often as the sinusoid does: the
+* oscillator is at full speed at the centre going one way AND going the other,
+* and the energy cannot tell those apart because it does not carry a sign.
+*
+* So a question that gives you an energy-against-time graph and asks for the
+* period of the MOTION wants twice what the graph shows. Reading the graph's
+* own period straight off is the wrong answer, and it is wrong by exactly the
+* factor this function applies.
+*/
+const energyPeriod = (period) => positive(period, "A period") / 2;
+/**
+* The amplitude implied by a displacement and a velocity at the same moment:
+* A = √(x² + (v/ω)²).
+*
+* v = ω√(A² − x²) rearranged. Any snapshot of the motion fixes the amplitude,
+* which is how a question that never mentions an amplitude can still be asking
+* for the total energy.
+*/
+function amplitudeFromState(omega, displacement, velocity) {
+	const w = positive(omega, "An angular frequency");
+	const x = finite(displacement, "A displacement");
+	const v = finite(velocity, "A velocity");
+	return Math.hypot(x, v / w);
+}
+/**
+* The phase angle δ in x = A·sin(ωt + δ), from the state at t = 0.
+*
+* Returned in radians on (−π, π]. Uses `atan2` on (xω, v) rather than
+* `asin(x₀/A)`, and that choice is the whole function: `asin` cannot tell a
+* mass at +A/2 moving outward from one at +A/2 moving back, because they share
+* a sine and differ only in the sign of the cosine. Half the answers from the
+* `asin` route are the wrong one of the two, silently.
+*
+* The familiar special cases fall out: released from rest at full displacement
+* gives π/2, so x = A·cos(ωt); started from the centre moving positive gives 0.
+*/
+function phaseFromState(omega, displacement, velocity) {
+	const w = positive(omega, "An angular frequency");
+	const x = finite(displacement, "A displacement");
+	const v = finite(velocity, "A velocity");
+	if (x === 0 && v === 0) throw new RangeError("An oscillator at rest at the centre has no phase: it is not oscillating.");
+	return Math.atan2(x * w, v);
+}
+
+//#endregion
+export { amplitudeFromState, angularFrequencyFromPeriod, displacementAtSpeed, energyAt, energyAtSteps, energyPeriod, equalEnergyDisplacement, maxAcceleration, maxSpeed, oscillatorStateAt, periodFromAngularFrequency, phaseFromState, shmAcceleration, shmDisplacement, shmVelocity, speedAtDisplacement, springAngularFrequency, springPeriod, totalEnergy };