@classytic/stage 0.3.0 → 0.4.0

package/dist/waves/doppler.mjs

@@ -0,0 +1,125 @@
+//#region src/waves/doppler.ts
+const finitePositive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive and finite`);
+	return value;
+};
+/**
+* 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.
+*/
+function radialSpeed(source, observer, velocity) {
+	const dx = observer.x - source.x;
+	const dy = observer.y - source.y;
+	const distance = Math.hypot(dx, dy);
+	if (distance === 0) return 0;
+	return (velocity.x * dx + velocity.y * dy) / distance;
+}
+/**
+* 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.
+*/
+function observedFrequencyMovingSource(sourceFrequency, waveSpeed, radialSourceSpeed) {
+	finitePositive(sourceFrequency, "source frequency");
+	finitePositive(waveSpeed, "wave speed");
+	if (!Number.isFinite(radialSourceSpeed)) throw new RangeError("radial speed must be finite");
+	const denominator = waveSpeed - radialSourceSpeed;
+	if (denominator === 0) return Number.POSITIVE_INFINITY;
+	return sourceFrequency * waveSpeed / denominator;
+}
+/**
+* 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.
+*/
+function observedFrequencyMovingObserver(sourceFrequency, waveSpeed, radialObserverSpeed) {
+	finitePositive(sourceFrequency, "source frequency");
+	finitePositive(waveSpeed, "wave speed");
+	if (!Number.isFinite(radialObserverSpeed)) throw new RangeError("radial speed must be finite");
+	return sourceFrequency * (waveSpeed + radialObserverSpeed) / waveSpeed;
+}
+/**
+* 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.
+*/
+function observedFrequency(sourceFrequency, waveSpeed, radialSourceSpeed, radialObserverSpeed = 0) {
+	finitePositive(sourceFrequency, "source frequency");
+	const v = finitePositive(waveSpeed, "wave speed");
+	const denominator = v - radialSourceSpeed;
+	if (denominator === 0) return Number.POSITIVE_INFINITY;
+	return sourceFrequency * (v + radialObserverSpeed) / denominator;
+}
+/** Wavelength in the medium ahead of a moving source: `(v - v_s) / f_s`. Goes to zero at Mach 1. */
+function wavelengthAhead(sourceFrequency, waveSpeed, sourceSpeed) {
+	finitePositive(sourceFrequency, "source frequency");
+	finitePositive(waveSpeed, "wave speed");
+	return (waveSpeed - sourceSpeed) / sourceFrequency;
+}
+/** Wavelength behind a moving source: `(v + v_s) / f_s`. */
+function wavelengthBehind(sourceFrequency, waveSpeed, sourceSpeed) {
+	finitePositive(sourceFrequency, "source frequency");
+	finitePositive(waveSpeed, "wave speed");
+	return (waveSpeed + sourceSpeed) / sourceFrequency;
+}
+/**
+* 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.
+*/
+function frequencyShiftAsymmetry(waveSpeed, sourceSpeed) {
+	const v = finitePositive(waveSpeed, "wave speed");
+	if (!Number.isFinite(sourceSpeed) || sourceSpeed < 0) throw new RangeError("source speed must be >= 0");
+	const approaching = sourceSpeed === v ? Number.POSITIVE_INFINITY : v / (v - sourceSpeed);
+	const receding = v / (v + sourceSpeed);
+	return {
+		approaching,
+		receding,
+		riseOverFall: sourceSpeed === 0 ? 1 : (approaching - 1) / (1 - receding)
+	};
+}
+/** Mach number: source speed as a multiple of the wave speed. */
+function machNumber(sourceSpeed, waveSpeed) {
+	return sourceSpeed / finitePositive(waveSpeed, "wave speed");
+}
+/**
+* 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.
+*/
+function machConeHalfAngle(mach) {
+	if (!Number.isFinite(mach) || mach < 1) return null;
+	return Math.asin(1 / mach);
+}
+/** Radius a wavefront has reached, given when it left and the time now. */
+function wavefrontRadius(waveSpeed, emittedAt, now) {
+	finitePositive(waveSpeed, "wave speed");
+	return Math.max(0, waveSpeed * (now - emittedAt));
+}
+/**
+* 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.
+*/
+function sourceSpeedFromShift(sourceFrequency, observedFrequency, waveSpeed) {
+	finitePositive(sourceFrequency, "source frequency");
+	finitePositive(observedFrequency, "observed frequency");
+	return finitePositive(waveSpeed, "wave speed") * (1 - sourceFrequency / observedFrequency);
+}
+
+//#endregion
+export { frequencyShiftAsymmetry, machConeHalfAngle, machNumber, observedFrequency, observedFrequencyMovingObserver, observedFrequencyMovingSource, radialSpeed, sourceSpeedFromShift, wavefrontRadius, wavelengthAhead, wavelengthBehind };

package/dist/waves/index.d.mts

@@ -0,0 +1,10 @@
+import { Vec2 } from "../core/vec.mjs";
+import { Direction, Wave, angularFrequency, displacement, frequencyFromAngular, frequencyFromPeriod, frequencyFromSpeed, intensityRatio, interferenceAt, maxParticleSpeed, particleAcceleration, particleVelocity, pathFromPhase, period, phaseAt, phaseFromPath, sampleWave, speedOf, waveNumber, waveSpeed, wavelengthFromSpeed, wavelengthFromWaveNumber } from "./wave.mjs";
+import { OscillatorEnergy, OscillatorState, amplitudeFromState, angularFrequencyFromPeriod, displacementAtSpeed, energyAt, energyAtSteps, energyPeriod, equalEnergyDisplacement, maxAcceleration, maxSpeed, oscillatorStateAt, periodFromAngularFrequency, phaseFromState, shmAcceleration, shmDisplacement, shmVelocity, speedAtDisplacement, springAngularFrequency, springPeriod, totalEnergy } from "./shm.mjs";
+import { cutSpringStiffness, splitSpringStiffness, springExtension, springForce, springPeriodFromExtension, staticExtension, stiffnessFromAngularFrequency, stiffnessFromExtension, stiffnessFromExtensionSteps, stiffnessInParallel, stiffnessInSeries } from "./springs.mjs";
+import { SECONDS_PER_DAY, clockDriftPerDay, clockDriftSteps, effectiveGravityInLift, graphSlopeForGravity, gravityFromGraphSlope, gravityFromPendulumSteps, gravityFromPeriod, gravityFromPeriodRatio, liftAccelerationFromPeriod, pendulumAmplitudeCorrection, pendulumAngularFrequency, pendulumLength, pendulumPeriod, periodAtGravity, periodForDailyDrift, secondsPendulumLength } from "./pendulum.mjs";
+import { DampingRegime, amplificationFactor, amplitudeRatioPerCycle, criticalDamping, dampedAmplitude, dampedAngularFrequency, dampedDisplacement, dampedEnergy, dampedVelocity, dampingRatio, dampingRatioFromDecrement, dampingRegime, decayTimeConstant, drivenAmplitude, drivenPhaseLag, logarithmicDecrement, mechanicalQ, qFromDampingRatio, resonantAngularFrequency, settlingTime } from "./damping.mjs";
+import { A4_HZ, CENTS_PER_OCTAVE, SEMITONE_NAMES, SEMITONE_RATIO, centsBetween, frequencyAfterCents, frequencyAfterSemitones, fretPosition, fretSpacing, frettedLength, isInTune, justIntervalCents, nearestNote, semitonesBetween, temperedIntervalCents } from "./pitch.mjs";
+import { BoundaryKind, TwoSourcePoint, antinodePositions, beatDisplacement, beatEnvelope, beatFrequency, harmonicFrequency, harmonicSeries, harmonicWavelength, nodePositions, nodeSpacing, standingWave, stringWaveSpeed, superpose, twoSourceDisplacement, twoSourceEnvelope, twoSourceField } from "./superposition.mjs";
+import { frequencyShiftAsymmetry, machConeHalfAngle, machNumber, observedFrequency, observedFrequencyMovingObserver, observedFrequencyMovingSource, radialSpeed, sourceSpeedFromShift, wavefrontRadius, wavelengthAhead, wavelengthBehind } from "./doppler.mjs";
+export { A4_HZ, BoundaryKind, CENTS_PER_OCTAVE, DampingRegime, Direction, OscillatorEnergy, OscillatorState, SECONDS_PER_DAY, SEMITONE_NAMES, SEMITONE_RATIO, TwoSourcePoint, type Vec2, Wave, amplificationFactor, amplitudeFromState, amplitudeRatioPerCycle, angularFrequency, angularFrequencyFromPeriod, antinodePositions, beatDisplacement, beatEnvelope, beatFrequency, centsBetween, clockDriftPerDay, clockDriftSteps, criticalDamping, cutSpringStiffness, dampedAmplitude, dampedAngularFrequency, dampedDisplacement, dampedEnergy, dampedVelocity, dampingRatio, dampingRatioFromDecrement, dampingRegime, decayTimeConstant, displacement, displacementAtSpeed, drivenAmplitude, drivenPhaseLag, effectiveGravityInLift, energyAt, energyAtSteps, energyPeriod, equalEnergyDisplacement, frequencyAfterCents, frequencyAfterSemitones, frequencyFromAngular, frequencyFromPeriod, frequencyFromSpeed, frequencyShiftAsymmetry, fretPosition, fretSpacing, frettedLength, graphSlopeForGravity, gravityFromGraphSlope, gravityFromPendulumSteps, gravityFromPeriod, gravityFromPeriodRatio, harmonicFrequency, harmonicSeries, harmonicWavelength, intensityRatio, interferenceAt, isInTune, justIntervalCents, liftAccelerationFromPeriod, logarithmicDecrement, machConeHalfAngle, machNumber, maxAcceleration, maxParticleSpeed, maxSpeed, mechanicalQ, nearestNote, nodePositions, nodeSpacing, observedFrequency, observedFrequencyMovingObserver, observedFrequencyMovingSource, oscillatorStateAt, particleAcceleration, particleVelocity, pathFromPhase, pendulumAmplitudeCorrection, pendulumAngularFrequency, pendulumLength, pendulumPeriod, period, periodAtGravity, periodForDailyDrift, periodFromAngularFrequency, phaseAt, phaseFromPath, phaseFromState, qFromDampingRatio, radialSpeed, resonantAngularFrequency, sampleWave, secondsPendulumLength, semitonesBetween, settlingTime, shmAcceleration, shmDisplacement, shmVelocity, sourceSpeedFromShift, speedAtDisplacement, speedOf, splitSpringStiffness, springAngularFrequency, springExtension, springForce, springPeriod, springPeriodFromExtension, standingWave, staticExtension, stiffnessFromAngularFrequency, stiffnessFromExtension, stiffnessFromExtensionSteps, stiffnessInParallel, stiffnessInSeries, stringWaveSpeed, superpose, temperedIntervalCents, totalEnergy, twoSourceDisplacement, twoSourceEnvelope, twoSourceField, waveNumber, waveSpeed, wavefrontRadius, wavelengthAhead, wavelengthBehind, wavelengthFromSpeed, wavelengthFromWaveNumber };

package/dist/waves/index.mjs

@@ -0,0 +1,10 @@
+import { amplitudeFromState, angularFrequencyFromPeriod, displacementAtSpeed, energyAt, energyAtSteps, energyPeriod, equalEnergyDisplacement, maxAcceleration, maxSpeed, oscillatorStateAt, periodFromAngularFrequency, phaseFromState, shmAcceleration, shmDisplacement, shmVelocity, speedAtDisplacement, springAngularFrequency, springPeriod, totalEnergy } from "./shm.mjs";
+import { angularFrequency, displacement, frequencyFromAngular, frequencyFromPeriod, frequencyFromSpeed, intensityRatio, interferenceAt, maxParticleSpeed, particleAcceleration, particleVelocity, pathFromPhase, period, phaseAt, phaseFromPath, sampleWave, speedOf, waveNumber, waveSpeed, wavelengthFromSpeed, wavelengthFromWaveNumber } from "./wave.mjs";
+import { cutSpringStiffness, splitSpringStiffness, springExtension, springForce, springPeriodFromExtension, staticExtension, stiffnessFromAngularFrequency, stiffnessFromExtension, stiffnessFromExtensionSteps, stiffnessInParallel, stiffnessInSeries } from "./springs.mjs";
+import { SECONDS_PER_DAY, clockDriftPerDay, clockDriftSteps, effectiveGravityInLift, graphSlopeForGravity, gravityFromGraphSlope, gravityFromPendulumSteps, gravityFromPeriod, gravityFromPeriodRatio, liftAccelerationFromPeriod, pendulumAmplitudeCorrection, pendulumAngularFrequency, pendulumLength, pendulumPeriod, periodAtGravity, periodForDailyDrift, secondsPendulumLength } from "./pendulum.mjs";
+import { amplificationFactor, amplitudeRatioPerCycle, criticalDamping, dampedAmplitude, dampedAngularFrequency, dampedDisplacement, dampedEnergy, dampedVelocity, dampingRatio, dampingRatioFromDecrement, dampingRegime, decayTimeConstant, drivenAmplitude, drivenPhaseLag, logarithmicDecrement, mechanicalQ, qFromDampingRatio, resonantAngularFrequency, settlingTime } from "./damping.mjs";
+import { A4_HZ, CENTS_PER_OCTAVE, SEMITONE_NAMES, SEMITONE_RATIO, centsBetween, frequencyAfterCents, frequencyAfterSemitones, fretPosition, fretSpacing, frettedLength, isInTune, justIntervalCents, nearestNote, semitonesBetween, temperedIntervalCents } from "./pitch.mjs";
+import { antinodePositions, beatDisplacement, beatEnvelope, beatFrequency, harmonicFrequency, harmonicSeries, harmonicWavelength, nodePositions, nodeSpacing, standingWave, stringWaveSpeed, superpose, twoSourceDisplacement, twoSourceEnvelope, twoSourceField } from "./superposition.mjs";
+import { frequencyShiftAsymmetry, machConeHalfAngle, machNumber, observedFrequency, observedFrequencyMovingObserver, observedFrequencyMovingSource, radialSpeed, sourceSpeedFromShift, wavefrontRadius, wavelengthAhead, wavelengthBehind } from "./doppler.mjs";
+
+export { A4_HZ, CENTS_PER_OCTAVE, SECONDS_PER_DAY, SEMITONE_NAMES, SEMITONE_RATIO, amplificationFactor, amplitudeFromState, amplitudeRatioPerCycle, angularFrequency, angularFrequencyFromPeriod, antinodePositions, beatDisplacement, beatEnvelope, beatFrequency, centsBetween, clockDriftPerDay, clockDriftSteps, criticalDamping, cutSpringStiffness, dampedAmplitude, dampedAngularFrequency, dampedDisplacement, dampedEnergy, dampedVelocity, dampingRatio, dampingRatioFromDecrement, dampingRegime, decayTimeConstant, displacement, displacementAtSpeed, drivenAmplitude, drivenPhaseLag, effectiveGravityInLift, energyAt, energyAtSteps, energyPeriod, equalEnergyDisplacement, frequencyAfterCents, frequencyAfterSemitones, frequencyFromAngular, frequencyFromPeriod, frequencyFromSpeed, frequencyShiftAsymmetry, fretPosition, fretSpacing, frettedLength, graphSlopeForGravity, gravityFromGraphSlope, gravityFromPendulumSteps, gravityFromPeriod, gravityFromPeriodRatio, harmonicFrequency, harmonicSeries, harmonicWavelength, intensityRatio, interferenceAt, isInTune, justIntervalCents, liftAccelerationFromPeriod, logarithmicDecrement, machConeHalfAngle, machNumber, maxAcceleration, maxParticleSpeed, maxSpeed, mechanicalQ, nearestNote, nodePositions, nodeSpacing, observedFrequency, observedFrequencyMovingObserver, observedFrequencyMovingSource, oscillatorStateAt, particleAcceleration, particleVelocity, pathFromPhase, pendulumAmplitudeCorrection, pendulumAngularFrequency, pendulumLength, pendulumPeriod, period, periodAtGravity, periodForDailyDrift, periodFromAngularFrequency, phaseAt, phaseFromPath, phaseFromState, qFromDampingRatio, radialSpeed, resonantAngularFrequency, sampleWave, secondsPendulumLength, semitonesBetween, settlingTime, shmAcceleration, shmDisplacement, shmVelocity, sourceSpeedFromShift, speedAtDisplacement, speedOf, splitSpringStiffness, springAngularFrequency, springExtension, springForce, springPeriod, springPeriodFromExtension, standingWave, staticExtension, stiffnessFromAngularFrequency, stiffnessFromExtension, stiffnessFromExtensionSteps, stiffnessInParallel, stiffnessInSeries, stringWaveSpeed, superpose, temperedIntervalCents, totalEnergy, twoSourceDisplacement, twoSourceEnvelope, twoSourceField, waveNumber, waveSpeed, wavefrontRadius, wavelengthAhead, wavelengthBehind, wavelengthFromSpeed, wavelengthFromWaveNumber };

package/dist/waves/pendulum.d.mts

@@ -0,0 +1,130 @@
+import { Worked } from "../core/worked.mjs";
+
+//#region src/waves/pendulum.d.ts
+/** Seconds in a day, the unit clock-drift questions are posed in. */
+declare const SECONDS_PER_DAY = 86400;
+/**
+ * Period of a simple pendulum: T = 2π√(L/g), seconds.
+ *
+ * An APPROXIMATION, valid while sin θ ≈ θ. The true period is larger, by about
+ * 0.2 % at 10 degrees and 1.7 % at 30, so a pendulum swung wide runs slow. The
+ * mass does not appear, which is why a pendulum clock is not affected by the
+ * weight of its bob and is affected by the temperature of its rod.
+ */
+declare const pendulumPeriod: (length: number, gravity?: number) => number;
+/** Angular frequency of a simple pendulum: ω = √(g/L), rad/s. */
+declare const pendulumAngularFrequency: (length: number, gravity?: number) => number;
+/** The length that gives a wanted period, metres: L = gT²/4π². */
+declare const pendulumLength: (period: number, gravity?: number) => number;
+/**
+ * The length of a SECONDS pendulum, metres: the one that beats once a second.
+ *
+ * Its period is TWO seconds, not one, because a beat is half a swing: the bob
+ * passes the centre once each way. That factor of two is the whole trap in the
+ * name, and it is why the answer is about 0.99 m rather than 0.25 m.
+ */
+declare const secondsPendulumLength: (gravity?: number) => number;
+/**
+ * The first correction to the pendulum period, as a multiplier.
+ *
+ * T = T₀·(1 + θ₀²/16 + …) for an amplitude θ₀ in radians. Exposed so a lab can
+ * SHOW the small-angle approximation breaking rather than only warning that it
+ * does.
+ */
+declare function pendulumAmplitudeCorrection(amplitudeRad: number): number;
+/**
+ * The gravity a pendulum in an accelerating lift behaves as if it were in.
+ *
+ * `acceleration` is the lift's, positive UPWARD. Going up: the floor pushes
+ * harder, the bob hangs heavier, g_eff = g + a and the pendulum runs FAST.
+ * Going down: g_eff = g − a and it runs slow. In free fall a = g, g_eff = 0,
+ * and the pendulum stops swinging altogether: it has nothing to fall back
+ * towards. That limiting case is the one worth showing, because it is where
+ * the equivalence principle stops being a slogan.
+ *
+ * Note the sign convention is on the LIFT'S acceleration, not on its velocity.
+ * A lift moving upward while slowing down has a downward acceleration and its
+ * pendulum runs slow, which catches almost everybody.
+ */
+declare function effectiveGravityInLift(gravity: number, acceleration: number): number;
+/**
+ * Gravity from one length and one timing: g = 4π²L/T².
+ *
+ * Correct, and a poor experiment. A single pair of readings carries every one
+ * of its errors straight into the answer, which is why the practical plots a
+ * graph instead. Use `gravityFromGraphSlope` where there is more than one
+ * reading.
+ */
+declare const gravityFromPeriod: (length: number, period: number) => number;
+/**
+ * Gravity from the gradient of a T²-against-L graph: g = 4π²/slope.
+ *
+ * T² = (4π²/g)·L is a straight line through the origin, so the gradient is
+ * 4π²/g and every reading contributes to it. This is the version the practical
+ * is actually marked on, and the reason the graph is drawn at all: a systematic
+ * error in measuring the length shifts the intercept and leaves the gradient,
+ * and therefore g, untouched.
+ *
+ * `slope` is in s²/m.
+ */
+declare const gravityFromGraphSlope: (slope: number) => number;
+/**
+ * The lift acceleration a measured period implies, m/s². Positive means upward.
+ *
+ * The pendulum used backwards, as an accelerometer. A period SHORTER than the
+ * one the same pendulum has at rest means the lift is accelerating upward.
+ */
+declare const liftAccelerationFromPeriod: (length: number, period: number, gravity?: number) => number;
+/** The gradient a T²-against-L graph should have for a given g, s²/m. The inverse of the above. */
+declare const graphSlopeForGravity: (gravity?: number) => number;
+/**
+ * The gravity implied by a pendulum's period changing: g₂ = g₁(T₁/T₂)².
+ *
+ * The seam to `gravitation`. Take the same pendulum somewhere else, time it,
+ * and this says what g is there without the length ever being needed, because
+ * the length is the thing that did not change.
+ *
+ * To answer "how high is the mountain", compose: this gives g at the top, and
+ * `gravitation`'s `heightForGravity` turns that into a height. The
+ * inverse-square law is deliberately not repeated here.
+ */
+declare const gravityFromPeriodRatio: (gravity: number, period: number, newPeriod: number) => number;
+/** The period the same pendulum would have where gravity is `newGravity`: T₂ = T₁√(g₁/g₂). */
+declare const periodAtGravity: (period: number, gravity: number, newGravity: number) => number;
+/**
+ * Seconds a pendulum clock gains (+) or loses (−) per day, from its wrong period.
+ *
+ * The clock counts each swing as `truePeriod` seconds whatever the pendulum
+ * actually does, so in a real day of 86,400 s it makes 86400/T' swings and
+ * displays 86400·T/T' seconds.
+ *
+ *     drift = 86400·(T − T')/T'
+ *
+ * A pendulum running SLOW (T' > T) gives a negative drift: the clock loses. The
+ * sensitivity is the part worth seeing: a period wrong by one part in ten
+ * thousand costs 8.6 seconds a day, so a clock that is right to a second a day
+ * has a pendulum right to one part in a hundred thousand.
+ */
+declare function clockDriftPerDay(truePeriod: number, actualPeriod: number): number;
+/**
+ * The period a clock must be running at to drift by a given amount per day.
+ *
+ * `drift` is signed the same way as `clockDriftPerDay`: positive gains, negative
+ * loses. The exact inverse, so a question posed either way round is one call.
+ */
+declare function periodForDailyDrift(truePeriod: number, drift: number): number;
+/**
+ * The pendulum-as-gravimeter question, worked.
+ *
+ * Reports the single-reading value and the gradient value side by side so the
+ * gap between "correct" and "good experiment" is visible rather than asserted.
+ */
+declare function gravityFromPendulumSteps(length: number, period: number, sf?: number): Worked;
+/**
+ * The clock-drift question, worked, in the direction it is usually asked:
+ * the pendulum has changed length or moved, and how far out is the clock by
+ * bedtime.
+ */
+declare function clockDriftSteps(truePeriod: number, actualPeriod: number, sf?: number): Worked;
+//#endregion
+export { SECONDS_PER_DAY, clockDriftPerDay, clockDriftSteps, effectiveGravityInLift, graphSlopeForGravity, gravityFromGraphSlope, gravityFromPendulumSteps, gravityFromPeriod, gravityFromPeriodRatio, liftAccelerationFromPeriod, pendulumAmplitudeCorrection, pendulumAngularFrequency, pendulumLength, pendulumPeriod, periodAtGravity, periodForDailyDrift, secondsPendulumLength };

package/dist/waves/pendulum.mjs

@@ -0,0 +1,211 @@
+import { calc, texSigFigs } from "../core/worked.mjs";
+import { G_EARTH } from "../physics/kinematics/free-fall.mjs";
+
+//#region src/waves/pendulum.ts
+/**
+* The simple pendulum, and the three things it is actually used for.
+*
+* ## It is a clock
+*
+*     T = 2π√(L/g)
+*
+* No mass. A pendulum clock is not affected by the weight of its bob, and IS
+* affected by the temperature of its rod, because only the length appears.
+* `clockDriftPerDay` turns a wrong period into the seconds a clock gains or
+* loses in a day, which is the form every exam question asks for and is a
+* surprisingly large number: one part in 10,000 is nine seconds a day.
+*
+* ## It is a gravimeter
+*
+* Rearranged, g = 4π²L/T², and that is a real measurement rather than a
+* contrivance: timing a pendulum is how g was mapped before anyone had an
+* accelerometer. `gravityFromGraphSlope` is the honest version of it, because
+* the school practical plots T² against L and takes the gradient rather than
+* trusting a single pair of readings.
+*
+* ## It is an accelerometer
+*
+* Hang it in a lift and it does not know the difference between gravity and
+* acceleration, so its period measures g + a. `effectiveGravityInLift` is that,
+* and it is the equivalence principle doing something useful.
+*
+* ## Where this module stops
+*
+* It does NOT compute how g varies with height, depth or latitude. That is
+* `@classytic/stage/physics`'s `gravitation` module, and a pendulum question
+* about a mountain top is those two composed: gravitation says what g is up
+* there, this module says what the pendulum then does. `gravityFromPeriodRatio`
+* is the seam, and keeping it a seam is what stops a second copy of the
+* inverse-square law growing here.
+*
+* ## Scope
+*
+* SMALL AMPLITUDE. The pendulum is only approximately harmonic, and
+* `pendulumAmplitudeCorrection` says by how much it is not. Units are SI.
+*/
+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;
+};
+/** Seconds in a day, the unit clock-drift questions are posed in. */
+const SECONDS_PER_DAY = 86400;
+/**
+* Period of a simple pendulum: T = 2π√(L/g), seconds.
+*
+* An APPROXIMATION, valid while sin θ ≈ θ. The true period is larger, by about
+* 0.2 % at 10 degrees and 1.7 % at 30, so a pendulum swung wide runs slow. The
+* mass does not appear, which is why a pendulum clock is not affected by the
+* weight of its bob and is affected by the temperature of its rod.
+*/
+const pendulumPeriod = (length, gravity = G_EARTH) => 2 * Math.PI * Math.sqrt(positive(length, "A pendulum length") / positive(gravity, "A gravitational field strength"));
+/** Angular frequency of a simple pendulum: ω = √(g/L), rad/s. */
+const pendulumAngularFrequency = (length, gravity = G_EARTH) => Math.sqrt(positive(gravity, "A gravitational field strength") / positive(length, "A pendulum length"));
+/** The length that gives a wanted period, metres: L = gT²/4π². */
+const pendulumLength = (period, gravity = G_EARTH) => positive(gravity, "A gravitational field strength") * positive(period, "A period") ** 2 / (4 * Math.PI ** 2);
+/**
+* The length of a SECONDS pendulum, metres: the one that beats once a second.
+*
+* Its period is TWO seconds, not one, because a beat is half a swing: the bob
+* passes the centre once each way. That factor of two is the whole trap in the
+* name, and it is why the answer is about 0.99 m rather than 0.25 m.
+*/
+const secondsPendulumLength = (gravity = G_EARTH) => pendulumLength(2, gravity);
+/**
+* The first correction to the pendulum period, as a multiplier.
+*
+* T = T₀·(1 + θ₀²/16 + …) for an amplitude θ₀ in radians. Exposed so a lab can
+* SHOW the small-angle approximation breaking rather than only warning that it
+* does.
+*/
+function pendulumAmplitudeCorrection(amplitudeRad) {
+	const theta = Math.abs(finite(amplitudeRad, "An angular amplitude"));
+	if (theta >= Math.PI) throw new RangeError("A pendulum swinging past vertical is not oscillating.");
+	return 1 + theta * theta / 16;
+}
+/**
+* The gravity a pendulum in an accelerating lift behaves as if it were in.
+*
+* `acceleration` is the lift's, positive UPWARD. Going up: the floor pushes
+* harder, the bob hangs heavier, g_eff = g + a and the pendulum runs FAST.
+* Going down: g_eff = g − a and it runs slow. In free fall a = g, g_eff = 0,
+* and the pendulum stops swinging altogether: it has nothing to fall back
+* towards. That limiting case is the one worth showing, because it is where
+* the equivalence principle stops being a slogan.
+*
+* Note the sign convention is on the LIFT'S acceleration, not on its velocity.
+* A lift moving upward while slowing down has a downward acceleration and its
+* pendulum runs slow, which catches almost everybody.
+*/
+function effectiveGravityInLift(gravity, acceleration) {
+	const g = positive(gravity, "A gravitational field strength");
+	const a = finite(acceleration, "An acceleration");
+	const effective = g + a;
+	if (effective <= 0) throw new RangeError(`A lift falling at ${-a} m/s² leaves an effective gravity of ${effective}: the pendulum is weightless and does not oscillate.`);
+	return effective;
+}
+/**
+* Gravity from one length and one timing: g = 4π²L/T².
+*
+* Correct, and a poor experiment. A single pair of readings carries every one
+* of its errors straight into the answer, which is why the practical plots a
+* graph instead. Use `gravityFromGraphSlope` where there is more than one
+* reading.
+*/
+const gravityFromPeriod = (length, period) => 4 * Math.PI ** 2 * positive(length, "A pendulum length") / positive(period, "A period") ** 2;
+/**
+* Gravity from the gradient of a T²-against-L graph: g = 4π²/slope.
+*
+* T² = (4π²/g)·L is a straight line through the origin, so the gradient is
+* 4π²/g and every reading contributes to it. This is the version the practical
+* is actually marked on, and the reason the graph is drawn at all: a systematic
+* error in measuring the length shifts the intercept and leaves the gradient,
+* and therefore g, untouched.
+*
+* `slope` is in s²/m.
+*/
+const gravityFromGraphSlope = (slope) => 4 * Math.PI ** 2 / positive(slope, "A graph gradient");
+/**
+* The lift acceleration a measured period implies, m/s². Positive means upward.
+*
+* The pendulum used backwards, as an accelerometer. A period SHORTER than the
+* one the same pendulum has at rest means the lift is accelerating upward.
+*/
+const liftAccelerationFromPeriod = (length, period, gravity = G_EARTH) => gravityFromPeriod(length, period) - positive(gravity, "A gravitational field strength");
+/** The gradient a T²-against-L graph should have for a given g, s²/m. The inverse of the above. */
+const graphSlopeForGravity = (gravity = G_EARTH) => 4 * Math.PI ** 2 / positive(gravity, "A gravitational field strength");
+/**
+* The gravity implied by a pendulum's period changing: g₂ = g₁(T₁/T₂)².
+*
+* The seam to `gravitation`. Take the same pendulum somewhere else, time it,
+* and this says what g is there without the length ever being needed, because
+* the length is the thing that did not change.
+*
+* To answer "how high is the mountain", compose: this gives g at the top, and
+* `gravitation`'s `heightForGravity` turns that into a height. The
+* inverse-square law is deliberately not repeated here.
+*/
+const gravityFromPeriodRatio = (gravity, period, newPeriod) => positive(gravity, "A gravitational field strength") * (positive(period, "A period") / positive(newPeriod, "A period")) ** 2;
+/** The period the same pendulum would have where gravity is `newGravity`: T₂ = T₁√(g₁/g₂). */
+const periodAtGravity = (period, gravity, newGravity) => positive(period, "A period") * Math.sqrt(positive(gravity, "A gravitational field strength") / positive(newGravity, "A gravitational field strength"));
+/**
+* Seconds a pendulum clock gains (+) or loses (−) per day, from its wrong period.
+*
+* The clock counts each swing as `truePeriod` seconds whatever the pendulum
+* actually does, so in a real day of 86,400 s it makes 86400/T' swings and
+* displays 86400·T/T' seconds.
+*
+*     drift = 86400·(T − T')/T'
+*
+* A pendulum running SLOW (T' > T) gives a negative drift: the clock loses. The
+* sensitivity is the part worth seeing: a period wrong by one part in ten
+* thousand costs 8.6 seconds a day, so a clock that is right to a second a day
+* has a pendulum right to one part in a hundred thousand.
+*/
+function clockDriftPerDay(truePeriod, actualPeriod) {
+	const target = positive(truePeriod, "A period");
+	const actual = positive(actualPeriod, "A period");
+	return SECONDS_PER_DAY * (target - actual) / actual;
+}
+/**
+* The period a clock must be running at to drift by a given amount per day.
+*
+* `drift` is signed the same way as `clockDriftPerDay`: positive gains, negative
+* loses. The exact inverse, so a question posed either way round is one call.
+*/
+function periodForDailyDrift(truePeriod, drift) {
+	const target = positive(truePeriod, "A period");
+	const d = finite(drift, "A daily drift");
+	if (d <= -86400) throw new RangeError(`A clock cannot lose ${-d} seconds in a day: that is more than the day holds.`);
+	return SECONDS_PER_DAY * target / (SECONDS_PER_DAY + d);
+}
+/**
+* The pendulum-as-gravimeter question, worked.
+*
+* Reports the single-reading value and the gradient value side by side so the
+* gap between "correct" and "good experiment" is visible rather than asserted.
+*/
+function gravityFromPendulumSteps(length, period, sf = 3) {
+	const L = positive(length, "A pendulum length");
+	const T = positive(period, "A period");
+	const g = gravityFromPeriod(L, T);
+	return calc().step("T = 2\\pi\\sqrt{\\frac{L}{g}}", "no mass appears, so the bob can be anything").step("T^2 = \\frac{4\\pi^2}{g}L", "square it, and T² against L is a straight line through the origin").step(`g = \\frac{4\\pi^2 L}{T^2} = \\frac{4\\pi^2 \\times ${texSigFigs(L, sf)}}{${texSigFigs(T, sf)}^2} = ${texSigFigs(g, sf)}\\ \\mathrm{m\\,s^{-2}}`).step(`\\text{gradient} = \\frac{4\\pi^2}{g} = ${texSigFigs(graphSlopeForGravity(g), sf)}\\ \\mathrm{s^2\\,m^{-1}}`, "from several readings, take the gradient instead: a constant error in L then misses g entirely").done(g);
+}
+/**
+* The clock-drift question, worked, in the direction it is usually asked:
+* the pendulum has changed length or moved, and how far out is the clock by
+* bedtime.
+*/
+function clockDriftSteps(truePeriod, actualPeriod, sf = 3) {
+	const target = positive(truePeriod, "A period");
+	const actual = positive(actualPeriod, "A period");
+	const drift = clockDriftPerDay(target, actual);
+	const verb = drift >= 0 ? "gains" : "loses";
+	return calc().step(`n = \\frac{86400}{T'} = \\frac{86400}{${texSigFigs(actual, sf)}}`, "swings the pendulum really makes in one real day").step(`\\text{displayed} = nT = 86400 \\times \\frac{${texSigFigs(target, sf)}}{${texSigFigs(actual, sf)}}\\ \\mathrm{s}`, "the clock counts every swing as T seconds, whatever the pendulum is doing").step(`\\Delta t = 86400\\,\\frac{T - T'}{T'} = ${texSigFigs(drift, sf)}\\ \\mathrm{s}`, `so the clock ${verb} about ${Math.abs(drift).toFixed(0)} s a day`).done(drift);
+}
+
+//#endregion
+export { SECONDS_PER_DAY, clockDriftPerDay, clockDriftSteps, effectiveGravityInLift, graphSlopeForGravity, gravityFromGraphSlope, gravityFromPendulumSteps, gravityFromPeriod, gravityFromPeriodRatio, liftAccelerationFromPeriod, pendulumAmplitudeCorrection, pendulumAngularFrequency, pendulumLength, pendulumPeriod, periodAtGravity, periodForDailyDrift, secondsPendulumLength };

package/dist/waves/pitch.d.mts

@@ -0,0 +1,125 @@
+//#region src/waves/pitch.d.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).
+ */
+/** Concert A, hertz. The peg the whole system hangs from, fixed by agreement rather than physics. */
+declare const A4_HZ = 440;
+/** The frequency ratio of one equal-tempered semitone: the twelfth root of two. */
+declare const SEMITONE_RATIO: number;
+/** Cents in one octave. A cent is a hundredth of a semitone. */
+declare 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.
+ */
+declare const frequencyAfterSemitones: (frequency: number, semitones: number) => number;
+/** How many semitones apart two frequencies are: 12·log₂(f₂/f₁). Signed. */
+declare const semitonesBetween: (from: number, to: number) => number;
+/**
+ * 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.
+ */
+declare const centsBetween: (from: number, to: number) => number;
+/** The frequency a number of cents away from a reference. The inverse of `centsBetween`. */
+declare const frequencyAfterCents: (frequency: number, cents: number) => number;
+/**
+ * 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.
+ */
+declare const isInTune: (frequency: number, target: number, toleranceCents?: number) => boolean;
+/**
+ * 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.
+ */
+declare const frettedLength: (scaleLength: number, fret: number) => number;
+/**
+ * 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.
+ */
+declare const fretPosition: (scaleLength: number, fret: number) => number;
+/** The gap between two consecutive frets. Always smaller than the one below it. */
+declare const fretSpacing: (scaleLength: number, fret: number) => number;
+/** The names of the twelve semitones, starting at C. Sharps only; no enharmonic choice is made. */
+declare const SEMITONE_NAMES: readonly ["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.
+ */
+declare function nearestNote(frequency: number): {
+  name: string;
+  octave: number;
+  cents: number;
+};
+/**
+ * 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.
+ */
+declare const justIntervalCents: (numerator: number, denominator: number) => number;
+/** The equal-tempered size of an interval of `semitones`, in cents. Always a multiple of 100. */
+declare const temperedIntervalCents: (semitones: number) => number;
+//#endregion
+export { A4_HZ, CENTS_PER_OCTAVE, SEMITONE_NAMES, SEMITONE_RATIO, centsBetween, frequencyAfterCents, frequencyAfterSemitones, fretPosition, fretSpacing, frettedLength, isInTune, justIntervalCents, nearestNote, semitonesBetween, temperedIntervalCents };