@classytic/stage 0.3.0 → 0.4.0

package/dist/physics/magnetism/index.mjs

@@ -0,0 +1,74 @@
+import { __exportAll } from "../../_virtual/_rolldown/runtime.mjs";
+import { MIN_DISTANCE_M, MU_0, arcCentreT, circularArc, coilAxisT, coilCentreT, fieldAt, finiteWireT, flatCoil, helmholtzPair, longWire, longWireT, pathField, rectangularLoop, segmentField, solenoid, solenoidRings, solenoidT, straightWire, toroidT, traceFieldLine, traceFullFieldLine } from "./biot-savart.mjs";
+import { MIN_LOOP_CLEARANCE_M, emfFromMutualInductance, emfFromSelfInductance, fluxBesideWire, fluxLinkage, fluxThroughLoop, fluxThroughUniform, inducedEmfV, loopArea, magneticEnergyJ, mutualInductanceH, selfInductanceH, solenoidInductanceH } from "./flux.mjs";
+import { angleFromPlaneDeg, coilTorqueNm, forceOnPath, forcePerMetreOnWire, magneticMomentAm2, momentOfLoop, parallelWireForce, torqueFromMoment } from "./magnetic-force.mjs";
+import { EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, GEOMAGNETIC_NORTH_POLE, apparentDipDeg, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, fieldAtPlace, footLatitudeDeg, magneticLatitudeFromDip, trueBearingDeg, trueDipFromTwo } from "./geomagnetism.mjs";
+import { fieldsFor, lorentzForce3D, traceLorentz } from "./lorentz.mjs";
+
+//#region src/physics/magnetism/index.ts
+var magnetism_exports = /* @__PURE__ */ __exportAll({
+	EARTH_DIPOLE_MOMENT_AM2: () => EARTH_DIPOLE_MOMENT_AM2,
+	EARTH_RADIUS_M: () => EARTH_RADIUS_M,
+	GEOMAGNETIC_NORTH_POLE: () => GEOMAGNETIC_NORTH_POLE,
+	MIN_DISTANCE_M: () => MIN_DISTANCE_M,
+	MIN_LOOP_CLEARANCE_M: () => MIN_LOOP_CLEARANCE_M,
+	MU_0: () => MU_0,
+	angleFromPlaneDeg: () => angleFromPlaneDeg,
+	apparentDipDeg: () => apparentDipDeg,
+	arcCentreT: () => arcCentreT,
+	circularArc: () => circularArc,
+	coilAxisT: () => coilAxisT,
+	coilCentreT: () => coilCentreT,
+	coilTorqueNm: () => coilTorqueNm,
+	compassBearingDeg: () => compassBearingDeg,
+	dipFromMagneticLatitude: () => dipFromMagneticLatitude,
+	dipoleFieldAt: () => dipoleFieldAt,
+	dipoleFieldLine: () => dipoleFieldLine,
+	earthComponents: () => earthComponents,
+	earthFromComponents: () => earthFromComponents,
+	emfFromMutualInductance: () => emfFromMutualInductance,
+	emfFromSelfInductance: () => emfFromSelfInductance,
+	fieldAt: () => fieldAt,
+	fieldAtPlace: () => fieldAtPlace,
+	fieldsFor: () => fieldsFor,
+	finiteWireT: () => finiteWireT,
+	flatCoil: () => flatCoil,
+	fluxBesideWire: () => fluxBesideWire,
+	fluxLinkage: () => fluxLinkage,
+	fluxThroughLoop: () => fluxThroughLoop,
+	fluxThroughUniform: () => fluxThroughUniform,
+	footLatitudeDeg: () => footLatitudeDeg,
+	forceOnPath: () => forceOnPath,
+	forcePerMetreOnWire: () => forcePerMetreOnWire,
+	helmholtzPair: () => helmholtzPair,
+	inducedEmfV: () => inducedEmfV,
+	longWire: () => longWire,
+	longWireT: () => longWireT,
+	loopArea: () => loopArea,
+	lorentzForce3D: () => lorentzForce3D,
+	magneticEnergyJ: () => magneticEnergyJ,
+	magneticLatitudeFromDip: () => magneticLatitudeFromDip,
+	magneticMomentAm2: () => magneticMomentAm2,
+	momentOfLoop: () => momentOfLoop,
+	mutualInductanceH: () => mutualInductanceH,
+	parallelWireForce: () => parallelWireForce,
+	pathField: () => pathField,
+	rectangularLoop: () => rectangularLoop,
+	segmentField: () => segmentField,
+	selfInductanceH: () => selfInductanceH,
+	solenoid: () => solenoid,
+	solenoidInductanceH: () => solenoidInductanceH,
+	solenoidRings: () => solenoidRings,
+	solenoidT: () => solenoidT,
+	straightWire: () => straightWire,
+	toroidT: () => toroidT,
+	torqueFromMoment: () => torqueFromMoment,
+	traceFieldLine: () => traceFieldLine,
+	traceFullFieldLine: () => traceFullFieldLine,
+	traceLorentz: () => traceLorentz,
+	trueBearingDeg: () => trueBearingDeg,
+	trueDipFromTwo: () => trueDipFromTwo
+});
+
+//#endregion
+export { EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, GEOMAGNETIC_NORTH_POLE, MIN_DISTANCE_M, MIN_LOOP_CLEARANCE_M, MU_0, angleFromPlaneDeg, apparentDipDeg, arcCentreT, circularArc, coilAxisT, coilCentreT, coilTorqueNm, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, emfFromMutualInductance, emfFromSelfInductance, fieldAt, fieldAtPlace, fieldsFor, finiteWireT, flatCoil, fluxBesideWire, fluxLinkage, fluxThroughLoop, fluxThroughUniform, footLatitudeDeg, forceOnPath, forcePerMetreOnWire, helmholtzPair, inducedEmfV, longWire, longWireT, loopArea, lorentzForce3D, magneticEnergyJ, magneticLatitudeFromDip, magneticMomentAm2, magnetism_exports, momentOfLoop, mutualInductanceH, parallelWireForce, pathField, rectangularLoop, segmentField, selfInductanceH, solenoid, solenoidInductanceH, solenoidRings, solenoidT, straightWire, toroidT, torqueFromMoment, traceFieldLine, traceFullFieldLine, traceLorentz, trueBearingDeg, trueDipFromTwo };

package/dist/physics/magnetism/lorentz.d.mts

@@ -0,0 +1,28 @@
+import { Vec3 } from "../../core/vec3.mjs";
+
+//#region src/physics/magnetism/lorentz.d.ts
+type SpatialFieldMode = 'electric' | 'magnetic' | 'crossed';
+/**
+ * The Lorentz force on a point charge: F = q(E + v x B).
+ *
+ * Both halves in one expression on purpose. A velocity selector works because
+ * the two can cancel, and splitting them into separate functions makes that
+ * cancellation something a lab has to arrange rather than something the law
+ * already says.
+ */
+declare function lorentzForce3D(q: number, v: Vec3, e: Vec3, b: Vec3): Vec3;
+/**
+ * RK4 trajectory for constant fields, in normalised teaching units.
+ *
+ * Not SI: the point of this one is the SHAPE of the path (a circle in a pure
+ * magnetic field, a helix when the velocity has a component along it, a
+ * straight line when E and v x B cancel), and real electron masses would put
+ * every interesting radius outside any sensible viewport.
+ */
+declare function traceLorentz(q: number, m: number, v0: Vec3, e: Vec3, b: Vec3, steps?: number, dt?: number): Vec3[];
+declare function fieldsFor(mode: SpatialFieldMode, strength: number): {
+  e: Vec3;
+  b: Vec3;
+};
+//#endregion
+export { SpatialFieldMode, fieldsFor, lorentzForce3D, traceLorentz };

package/dist/physics/magnetism/lorentz.mjs

@@ -0,0 +1,88 @@
+import { add3, cross3, scale3 } from "../../core/vec3.mjs";
+
+//#region src/physics/magnetism/lorentz.ts
+/**
+* @classytic/stage/physics/magnetism/lorentz — the force a field puts on a
+* moving CHARGE, and the path that follows.
+*
+* The companion to `magnetic-force.ts`, which does the same for a current.
+* They are the same physics at two scales: a current is drifting charge, so
+* `F = qv x B` summed over the carriers in a wire IS `F = I l x B`.
+*/
+const add = (a, b, s = 1) => add3(a, scale3(b, s));
+/**
+* The Lorentz force on a point charge: F = q(E + v x B).
+*
+* Both halves in one expression on purpose. A velocity selector works because
+* the two can cancel, and splitting them into separate functions makes that
+* cancellation something a lab has to arrange rather than something the law
+* already says.
+*/
+function lorentzForce3D(q, v, e, b) {
+	const c = cross3(v, b);
+	return {
+		x: q * (e.x + c.x),
+		y: q * (e.y + c.y),
+		z: q * (e.z + c.z)
+	};
+}
+/**
+* RK4 trajectory for constant fields, in normalised teaching units.
+*
+* Not SI: the point of this one is the SHAPE of the path (a circle in a pure
+* magnetic field, a helix when the velocity has a component along it, a
+* straight line when E and v x B cancel), and real electron masses would put
+* every interesting radius outside any sensible viewport.
+*/
+function traceLorentz(q, m, v0, e, b, steps = 180, dt = .025) {
+	let p = {
+		x: 0,
+		y: 0,
+		z: 0
+	}, v = { ...v0 };
+	const out = [p];
+	for (let i = 0; i < steps; i++) {
+		const a = (x) => {
+			const f = lorentzForce3D(q, x, e, b);
+			return {
+				x: f.x / m,
+				y: f.y / m,
+				z: f.z / m
+			};
+		};
+		const k1 = a(v), k2 = a(add(v, k1, dt / 2)), k3 = a(add(v, k2, dt / 2)), k4 = a(add(v, k3, dt));
+		v = add(v, {
+			x: (k1.x + 2 * k2.x + 2 * k3.x + k4.x) / 6,
+			y: (k1.y + 2 * k2.y + 2 * k3.y + k4.y) / 6,
+			z: (k1.z + 2 * k2.z + 2 * k3.z + k4.z) / 6
+		}, dt);
+		p = add(p, v, dt);
+		out.push(p);
+	}
+	return out;
+}
+function fieldsFor(mode, strength) {
+	return {
+		e: mode === "magnetic" ? {
+			x: 0,
+			y: 0,
+			z: 0
+		} : {
+			x: 0,
+			y: strength,
+			z: 0
+		},
+		b: mode === "electric" ? {
+			x: 0,
+			y: 0,
+			z: 0
+		} : {
+			x: 0,
+			y: 0,
+			z: strength
+		}
+	};
+}
+
+//#endregion
+export { fieldsFor, lorentzForce3D, traceLorentz };

package/dist/physics/magnetism/magnetic-force.d.mts

@@ -0,0 +1,102 @@
+import { Vec3 } from "../../core/vec3.mjs";
+import { CurrentPath } from "./biot-savart.mjs";
+
+//#region src/physics/magnetism/magnetic-force.d.ts
+interface ForceOnPathOptions {
+  /** A uniform background field, added to whatever the current sources make. */
+  uniformT?: Vec3;
+  /** Point the torque is taken about. Defaults to the origin. */
+  about?: Vec3;
+  /**
+   * Quadrature points per segment of the test path.
+   *
+   * A straight segment in a slowly varying field needs one; a segment that is
+   * part of a polygon approximating a circle, sitting close to another
+   * conductor, needs several.
+   */
+  samplesPerSegment?: number;
+}
+interface PathForce {
+  /** Net force on the test path, in newtons. */
+  force: Vec3;
+  /** Its magnitude, in newtons. */
+  newtons: number;
+  /** Net torque about `about`, in newton metres. */
+  torque: Vec3;
+  /**
+   * Where the force acts, segment by segment.
+   *
+   * Kept because the interesting thing about a coil in a uniform field is that
+   * the net force is zero while the individual forces are not: a lesson has to
+   * be able to draw the parts to make the couple visible.
+   */
+  contributions: Array<{
+    at: Vec3;
+    force: Vec3;
+  }>;
+}
+/**
+ * Force and torque on one current path, in the field of any others plus an
+ * optional uniform background.
+ *
+ * The test path is NOT a source of its own field. A filament's self-force is
+ * divergent and, for a rigid circuit, is not what anybody means by "the force
+ * on the coil" anyway.
+ */
+declare function forceOnPath(sources: readonly CurrentPath[], test: CurrentPath, options?: ForceOnPathOptions): PathForce;
+/**
+ * Force per unit length on a long straight test wire, for comparing against the
+ * textbook result.
+ *
+ * Measured over a short span at the MIDDLE of the test wire, because the ends of
+ * any finite wire feel less than the middle does and averaging over the whole
+ * thing would quietly build that end effect into the answer.
+ */
+declare function forcePerMetreOnWire(sources: readonly CurrentPath[], through: Vec3, direction: Vec3, currentA: number, spanM?: number): Vec3;
+/** Torque on a closed circuit from its magnetic moment: tau = m x B. */
+declare function torqueFromMoment(momentAm2: Vec3, fieldT: Vec3): Vec3;
+/**
+ * Magnetic moment of a planar closed loop, as a vector: m = I A n.
+ *
+ * Computed from the loop's own geometry by the surface-vector form of the
+ * shoelace formula, so it needs no separate area argument and gets the normal's
+ * direction from the order the loop is walked. That is the right-hand rule made
+ * arithmetic.
+ */
+declare function momentOfLoop(loop: CurrentPath): Vec3;
+interface WireForce {
+  /** Force per unit length, in newtons per metre. Always positive. */
+  newtonsPerMetre: number;
+  /** Currents the same way attract; opposite ways repel. */
+  sense: 'attract' | 'repel';
+}
+/**
+ * Force per metre between two long parallel wires: mu0 I1 I2 / 2 pi d.
+ *
+ * This is the definition of the ampere, and it is the cleanest demonstration
+ * that a current both makes a field and feels one: wire 1's field at wire 2,
+ * times wire 2's I L.
+ */
+declare function parallelWireForce(current1A: number, current2A: number, separationM: number): WireForce;
+/** Magnetic dipole moment of a coil: M = N I A, in A m^2. */
+declare function magneticMomentAm2(turns: number, currentA: number, areaM2: number): number;
+/**
+ * Torque on a current-carrying coil in a uniform field: tau = N I A B sin(theta),
+ * where theta is the angle between the coil's NORMAL and the field.
+ *
+ * The angle is the standard trap. A question almost always states the angle the
+ * coil's PLANE makes with the field, which is the complement. Rather than pick
+ * a convention and hope, this takes the physically correct angle and
+ * `angleFromPlaneDeg` does the conversion in the open.
+ */
+declare function coilTorqueNm(fieldT: number, turns: number, currentA: number, areaM2: number, normalToFieldDeg: number): number;
+/**
+ * Convert "the coil's plane makes this angle with B" into the normal-to-field
+ * angle that `coilTorqueNm` wants.
+ *
+ * A coil whose plane lies along the field (0 degrees) has its normal across the
+ * field (90 degrees), which is where the torque is greatest.
+ */
+declare const angleFromPlaneDeg: (planeToFieldDeg: number) => number;
+//#endregion
+export { ForceOnPathOptions, PathForce, WireForce, angleFromPlaneDeg, coilTorqueNm, forceOnPath, forcePerMetreOnWire, magneticMomentAm2, momentOfLoop, parallelWireForce, torqueFromMoment };

package/dist/physics/magnetism/magnetic-force.mjs

@@ -0,0 +1,169 @@
+import { ZERO3, add3, cross3, mag3, scale3, sub3 } from "../../core/vec3.mjs";
+import { MU_0, fieldAt } from "./biot-savart.mjs";
+
+//#region src/physics/magnetism/magnetic-force.ts
+/**
+* @classytic/stage/field/magnetic-force — the force a magnetic field puts on a
+* current, over arbitrary geometry.
+*
+* `parallelWireForce` answers one case in closed form: two infinite straight
+* wires. Everything else a real circuit does -- a loop beside a wire, a coil
+* inside another coil, a rectangular armature in a magnet's gap -- needs the
+* line integral that case was derived from:
+*
+*   F = integral of I dl x B
+*
+* With that, the closed form stops being a separate fact and becomes a check.
+*
+* ── A uniform background field is a first-class source ────────────────────────
+* Almost every exam question puts a conductor in "a uniform field of 0.35 T"
+* without saying what makes it. Demanding a current geometry for that would be
+* pedantry: the uniform field is the idealisation the question is posed in. So
+* it is an explicit option, added to whatever the current sources contribute.
+*
+* ── Why the torque needs an origin, and when it does not ──────────────────────
+* Torque is about a point, so `about` has to be given. The exception is the
+* case that matters most: when the NET FORCE is zero, as it is for any closed
+* circuit in a uniform field, the torque is the same about every point. That is
+* what makes "the torque on a coil" a well-posed phrase at all, and it is
+* asserted in the tests rather than assumed.
+*/
+const radians = (deg) => deg * Math.PI / 180;
+const segmentsOf = (path) => {
+	const pairs = [];
+	const points = path.points;
+	for (let i = 0; i + 1 < points.length; i += 1) {
+		const from = points[i];
+		const to = points[i + 1];
+		if (from && to) pairs.push([from, to]);
+	}
+	if (path.closed && points.length > 2) {
+		const last = points[points.length - 1];
+		const first = points[0];
+		if (last && first) pairs.push([last, first]);
+	}
+	return pairs;
+};
+/**
+* Force and torque on one current path, in the field of any others plus an
+* optional uniform background.
+*
+* The test path is NOT a source of its own field. A filament's self-force is
+* divergent and, for a rigid circuit, is not what anybody means by "the force
+* on the coil" anyway.
+*/
+function forceOnPath(sources, test, options = {}) {
+	const { uniformT = ZERO3, about = ZERO3, samplesPerSegment = 4 } = options;
+	if (samplesPerSegment < 1) throw new RangeError("A segment needs at least one sample.");
+	if (sources.some((s) => s.id === test.id)) throw new RangeError("A path cannot be its own source: a filament self-force diverges.");
+	let force = ZERO3;
+	let torque = ZERO3;
+	const contributions = [];
+	for (const [from, to] of segmentsOf(test)) {
+		const along = sub3(to, from);
+		const piece = scale3(along, 1 / samplesPerSegment);
+		let segmentForce = ZERO3;
+		let segmentTorque = ZERO3;
+		let segmentMidpoint = ZERO3;
+		for (let k = 0; k < samplesPerSegment; k += 1) {
+			const at = add3(from, scale3(along, (k + .5) / samplesPerSegment));
+			const dF = scale3(cross3(piece, add3(uniformT, fieldAt(sources, at).field)), test.currentA);
+			segmentForce = add3(segmentForce, dF);
+			segmentTorque = add3(segmentTorque, cross3(sub3(at, about), dF));
+			segmentMidpoint = add3(segmentMidpoint, scale3(at, 1 / samplesPerSegment));
+		}
+		force = add3(force, segmentForce);
+		torque = add3(torque, segmentTorque);
+		contributions.push({
+			at: segmentMidpoint,
+			force: segmentForce
+		});
+	}
+	return {
+		force,
+		newtons: mag3(force),
+		torque,
+		contributions
+	};
+}
+/**
+* Force per unit length on a long straight test wire, for comparing against the
+* textbook result.
+*
+* Measured over a short span at the MIDDLE of the test wire, because the ends of
+* any finite wire feel less than the middle does and averaging over the whole
+* thing would quietly build that end effect into the answer.
+*/
+function forcePerMetreOnWire(sources, through, direction, currentA, spanM = .001) {
+	const len = mag3(direction);
+	if (len === 0) throw new RangeError("A wire needs a direction.");
+	const half = scale3(direction, spanM / (2 * len));
+	return scale3(forceOnPath(sources, {
+		id: "force-probe",
+		currentA,
+		points: [sub3(through, half), add3(through, half)]
+	}, { samplesPerSegment: 8 }).force, 1 / spanM);
+}
+/** Torque on a closed circuit from its magnetic moment: tau = m x B. */
+function torqueFromMoment(momentAm2, fieldT) {
+	return cross3(momentAm2, fieldT);
+}
+/**
+* Magnetic moment of a planar closed loop, as a vector: m = I A n.
+*
+* Computed from the loop's own geometry by the surface-vector form of the
+* shoelace formula, so it needs no separate area argument and gets the normal's
+* direction from the order the loop is walked. That is the right-hand rule made
+* arithmetic.
+*/
+function momentOfLoop(loop) {
+	const points = loop.points;
+	if (points.length < 3) throw new RangeError("A loop needs at least three vertices.");
+	const origin = points[0];
+	let area = ZERO3;
+	const pairs = segmentsOf(loop);
+	for (const [from, to] of pairs) area = add3(area, scale3(cross3(sub3(from, origin), sub3(to, origin)), .5));
+	return scale3(area, loop.currentA);
+}
+/**
+* Force per metre between two long parallel wires: mu0 I1 I2 / 2 pi d.
+*
+* This is the definition of the ampere, and it is the cleanest demonstration
+* that a current both makes a field and feels one: wire 1's field at wire 2,
+* times wire 2's I L.
+*/
+function parallelWireForce(current1A, current2A, separationM) {
+	if (separationM <= 0) throw new RangeError("Two wires need a positive separation.");
+	return {
+		newtonsPerMetre: MU_0 * Math.abs(current1A * current2A) / (2 * Math.PI * separationM),
+		sense: current1A * current2A >= 0 ? "attract" : "repel"
+	};
+}
+/** Magnetic dipole moment of a coil: M = N I A, in A m^2. */
+function magneticMomentAm2(turns, currentA, areaM2) {
+	if (turns < 0 || areaM2 < 0) throw new RangeError("Turns and area cannot be negative.");
+	return turns * currentA * areaM2;
+}
+/**
+* Torque on a current-carrying coil in a uniform field: tau = N I A B sin(theta),
+* where theta is the angle between the coil's NORMAL and the field.
+*
+* The angle is the standard trap. A question almost always states the angle the
+* coil's PLANE makes with the field, which is the complement. Rather than pick
+* a convention and hope, this takes the physically correct angle and
+* `angleFromPlaneDeg` does the conversion in the open.
+*/
+function coilTorqueNm(fieldT, turns, currentA, areaM2, normalToFieldDeg) {
+	return magneticMomentAm2(turns, currentA, areaM2) * fieldT * Math.sin(radians(normalToFieldDeg));
+}
+/**
+* Convert "the coil's plane makes this angle with B" into the normal-to-field
+* angle that `coilTorqueNm` wants.
+*
+* A coil whose plane lies along the field (0 degrees) has its normal across the
+* field (90 degrees), which is where the torque is greatest.
+*/
+const angleFromPlaneDeg = (planeToFieldDeg) => 90 - planeToFieldDeg;
+
+//#endregion
+export { angleFromPlaneDeg, coilTorqueNm, forceOnPath, forcePerMetreOnWire, magneticMomentAm2, momentOfLoop, parallelWireForce, torqueFromMoment };

package/dist/physics/momentum/collide.d.mts

@@ -0,0 +1,77 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/momentum/collide.d.ts
+interface CollisionInput {
+  readonly m1: number;
+  readonly u1: number;
+  readonly m2: number;
+  readonly u2: number;
+  /**
+   * Coefficient of restitution, 0 to 1. Defaults to 1, perfectly elastic.
+   *
+   * Not clamped silently: a value outside the range means the bodies separate faster than they
+   * approached, which needs an energy source the collision does not have, and that is a mistake
+   * worth reporting rather than rounding away.
+   */
+  readonly restitution?: number;
+}
+interface CollisionOutcome {
+  readonly v1: number;
+  readonly v2: number;
+  readonly restitution: number;
+  readonly momentumBefore: number;
+  readonly momentumAfter: number;
+  readonly kineticBefore: number;
+  readonly kineticAfter: number;
+  /** Energy turned into heat, sound and deformation. Zero only at `e = 1`. */
+  readonly kineticLost: number;
+  /** The closing speed, and the separating speed, whose ratio IS `e`. */
+  readonly approachSpeed: number;
+  readonly separationSpeed: number;
+  readonly worked: Worked;
+}
+/**
+ * Solve a head-on collision.
+ *
+ * ```ts
+ * collide({ m1: 5, u1: 2, m2: 3, u2: 0 });                  // elastic
+ * collide({ m1: 0.025, u1: 400, m2: 1.975, u2: 0, restitution: 0 });  // bullet into a block
+ * ```
+ */
+declare function collide(input: CollisionInput, sf?: number): CollisionOutcome;
+/**
+ * The restitution a collision actually had, measured from what happened.
+ *
+ * The inverse, and the one an experiment produces: drop a ball, measure the bounce, divide. Worth
+ * having because it turns `e` from a number in a formula into something a learner has measured.
+ */
+declare function restitutionOf(u1: number, u2: number, v1: number, v2: number): number;
+/**
+ * A ball bouncing on the ground: `e = √(h_bounce / h_drop)`.
+ *
+ * The standard measurement, and the square root is the part that surprises people. Restitution is a
+ * ratio of SPEEDS and height goes as speed squared, so a ball returning to half its height has
+ * `e = 0.71`, not 0.5.
+ */
+declare function restitutionFromBounce(dropHeight: number, bounceHeight: number, sf?: number): {
+  value: number;
+  worked: Worked;
+};
+/**
+ * Bodies that start together and fly apart: an explosion, a recoiling gun, a person stepping off a
+ * boat.
+ *
+ * Not a different law. Total momentum before is whatever it was, usually zero, and it is still that
+ * afterwards, so the fragments' momenta must cancel. Give every fragment's velocity except one and
+ * this returns the missing one.
+ */
+declare function separateFrom(initialMomentum: number, known: readonly {
+  label: string;
+  mass: number;
+  velocity: number;
+}[], unknownMass: number, sf?: number): {
+  velocity: number;
+  worked: Worked;
+};
+//#endregion
+export { CollisionInput, CollisionOutcome, collide, restitutionFromBounce, restitutionOf, separateFrom };

package/dist/physics/momentum/collide.mjs

@@ -0,0 +1,115 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+
+//#region src/physics/momentum/collide.ts
+/**
+* Collisions in one dimension, with elastic and perfectly inelastic as the ENDS OF ONE SCALE.
+*
+* Textbooks present two types with two sets of formulas, and students memorise which to use. They
+* are the same collision with one number changed. That number is the coefficient of restitution,
+*
+*     e = (speed of separation) / (speed of approach) = (v₂ − v₁) / (u₁ − u₂)
+*
+* and it runs from 1 (perfectly elastic, nothing lost, they separate as fast as they closed) to 0
+* (perfectly inelastic, they move off together). Every real collision is somewhere in between, and
+* no real collision is either. A slider from 0 to 1 is a better teaching object than two formulas,
+* because it shows the kinetic energy draining away continuously as `e` falls and being exactly
+* conserved only at the single point `e = 1`.
+*
+* TWO EQUATIONS, TWO UNKNOWNS, always. Momentum is conserved in every collision without exception,
+* which gives one equation; restitution gives the second; and the pair solves for both final
+* velocities. Energy is NOT an input, it is a RESULT, and the amount lost is what `e` is really
+* telling you.
+*
+* Signs matter and are not negotiable: velocities are along one axis, positive one way. Two bodies
+* approaching each other have opposite signs.
+*
+* Pure: no React, no pixels.
+*/
+const kinetic = (m, v) => .5 * m * v * v;
+/**
+* Solve a head-on collision.
+*
+* ```ts
+* collide({ m1: 5, u1: 2, m2: 3, u2: 0 });                  // elastic
+* collide({ m1: 0.025, u1: 400, m2: 1.975, u2: 0, restitution: 0 });  // bullet into a block
+* ```
+*/
+function collide(input, sf = 3) {
+	const { m1, u1, m2, u2 } = input;
+	const e = input.restitution ?? 1;
+	if (m1 <= 0 || m2 <= 0) throw new Error("Both masses must be positive.");
+	if (e < 0 || e > 1) throw new Error(`A coefficient of restitution of ${e} is not physical: it must lie between 0 (they stay together) and 1 (nothing is lost). Above 1 the bodies would leave faster than they arrived.`);
+	const total = m1 + m2;
+	const v1 = (m1 * u1 + m2 * u2 + m2 * e * (u2 - u1)) / total;
+	const v2 = (m1 * u1 + m2 * u2 + m1 * e * (u1 - u2)) / total;
+	const momentumBefore = m1 * u1 + m2 * u2;
+	const momentumAfter = m1 * v1 + m2 * v2;
+	const kineticBefore = kinetic(m1, u1) + kinetic(m2, u2);
+	const kineticAfter = kinetic(m1, v1) + kinetic(m2, v2);
+	const approachSpeed = u1 - u2;
+	const separationSpeed = v2 - v1;
+	const w = calc().step("m_1u_1 + m_2u_2 = m_1v_1 + m_2v_2", "momentum is conserved in EVERY collision, elastic or not. This is the equation that never changes").step("e = \\frac{v_2 - v_1}{u_1 - u_2}", `restitution supplies the second equation. Here e = ${texSigFigs(e, sf)}${e === 1 ? ", perfectly elastic" : e === 0 ? ", perfectly inelastic: they move off together" : ""}`).step(`u_1 = ${texSigFigs(u1, sf)},\\quad u_2 = ${texSigFigs(u2, sf)}\\ \\mathrm{m\\,s^{-1}}`, "signed along one axis: bodies approaching each other have opposite signs").step(`v_1 = ${texSigFigs(v1, sf)},\\quad v_2 = ${texSigFigs(v2, sf)}\\ \\mathrm{m\\,s^{-1}}`, "two equations, two unknowns").step(`E_k: ${texSigFigs(kineticBefore, sf)} \\to ${texSigFigs(kineticAfter, sf)}\\ \\mathrm{J}`, kineticBefore - kineticAfter < 1e-9 ? "nothing lost, which happens at e = 1 and nowhere else" : `${texSigFigs(kineticBefore - kineticAfter, sf)} J became heat, sound and deformation. Energy is a RESULT here, not an input`);
+	return {
+		v1,
+		v2,
+		restitution: e,
+		momentumBefore,
+		momentumAfter,
+		kineticBefore,
+		kineticAfter,
+		kineticLost: kineticBefore - kineticAfter,
+		approachSpeed,
+		separationSpeed,
+		worked: w.done(v1)
+	};
+}
+/**
+* The restitution a collision actually had, measured from what happened.
+*
+* The inverse, and the one an experiment produces: drop a ball, measure the bounce, divide. Worth
+* having because it turns `e` from a number in a formula into something a learner has measured.
+*/
+function restitutionOf(u1, u2, v1, v2) {
+	const approach = u1 - u2;
+	if (Math.abs(approach) < 1e-12) throw new Error("They were not approaching each other, so there is no collision to measure.");
+	return (v2 - v1) / approach;
+}
+/**
+* A ball bouncing on the ground: `e = √(h_bounce / h_drop)`.
+*
+* The standard measurement, and the square root is the part that surprises people. Restitution is a
+* ratio of SPEEDS and height goes as speed squared, so a ball returning to half its height has
+* `e = 0.71`, not 0.5.
+*/
+function restitutionFromBounce(dropHeight, bounceHeight, sf = 3) {
+	if (dropHeight <= 0) throw new Error("The drop height must be positive.");
+	if (bounceHeight < 0 || bounceHeight > dropHeight) throw new Error("The bounce cannot be higher than the drop, or negative.");
+	const value = Math.sqrt(bounceHeight / dropHeight);
+	return {
+		value,
+		worked: calc().step("v = \\sqrt{2gh}", "the speed at the ground, from the drop and from the rebound").step("e = \\frac{v_{up}}{v_{down}} = \\sqrt{\\frac{h_{bounce}}{h_{drop}}}", "the g and the 2 cancel").step(`e = \\sqrt{\\frac{${texSigFigs(bounceHeight, sf)}}{${texSigFigs(dropHeight, sf)}}} = ${texSigFigs(value, sf)}`, "a ratio of SPEEDS, so the height ratio is squared: half the height is e = 0.707, not 0.5").done(value)
+	};
+}
+/**
+* Bodies that start together and fly apart: an explosion, a recoiling gun, a person stepping off a
+* boat.
+*
+* Not a different law. Total momentum before is whatever it was, usually zero, and it is still that
+* afterwards, so the fragments' momenta must cancel. Give every fragment's velocity except one and
+* this returns the missing one.
+*/
+function separateFrom(initialMomentum, known, unknownMass, sf = 3) {
+	if (unknownMass <= 0) throw new Error("The remaining mass must be positive.");
+	const accounted = known.reduce((p, k) => p + k.mass * k.velocity, 0);
+	const velocity = (initialMomentum - accounted) / unknownMass;
+	const w = calc().step("\\sum p_{\\text{before}} = \\sum p_{\\text{after}}", initialMomentum === 0 ? "it started at rest, so the pieces’ momenta must cancel exactly" : "total momentum is unchanged, however many pieces there now are");
+	for (const k of known) w.step(`${k.label}: ${texSigFigs(k.mass, sf)} \\times ${texSigFigs(k.velocity, sf)} = ${texSigFigs(k.mass * k.velocity, sf)}\\ \\mathrm{kg\\,m\\,s^{-1}}`);
+	w.step(`v = \\frac{${texSigFigs(initialMomentum, sf)} - ${texSigFigs(accounted, sf)}}{${texSigFigs(unknownMass, sf)}} = ${texSigFigs(velocity, sf)}\\ \\mathrm{m\\,s^{-1}}`, "the sign says which way it goes, and it is opposite to whatever the others did");
+	return {
+		velocity,
+		worked: w.done(velocity)
+	};
+}
+
+//#endregion
+export { collide, restitutionFromBounce, restitutionOf, separateFrom };