@classytic/stage 0.3.0 → 0.4.0

package/dist/physics/dynamics/forces.d.mts

@@ -0,0 +1,98 @@
+import { Worked } from "../../core/worked.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/dynamics/forces.d.ts
+/** A force, stored as components so adding is addition. */
+interface Force {
+  readonly label: string;
+  readonly x: number;
+  readonly y: number;
+}
+/** `force('push', 20, 30)`: 20 N at 30° above the horizontal. */
+declare function force(label: string, magnitude: number, angleDeg: number): Force;
+/** A force given directly by its components, for one already resolved. */
+declare const forceXY: (label: string, x: number, y: number) => Force;
+/** The weight of a mass: `mg`, straight down. */
+declare const weight: (mass: number, g?: number) => Force;
+interface Resultant {
+  readonly x: number;
+  readonly y: number;
+  readonly magnitude: number;
+  /** Above the horizontal, degrees. */
+  readonly angleDeg: number;
+}
+/**
+ * Add forces by adding their components.
+ *
+ * Worth stating plainly because it is the thing that makes force problems tractable and it is
+ * routinely obscured: there is no special rule for three forces or for forces at awkward angles.
+ * You resolve, you add the two columns, and you are done.
+ */
+declare function resultant(forces: readonly Force[]): Resultant;
+/**
+ * Is this set of forces in equilibrium?
+ *
+ * The tolerance is relative to the largest force present, not absolute. A 1 mN imbalance is nothing
+ * among meganewtons and is everything among micronewtons, and a fixed epsilon gets one of those
+ * two cases wrong.
+ */
+declare function isBalanced(forces: readonly Force[], tolerance?: number): boolean;
+/** The worked resultant, set out as the two columns a mark scheme wants to see. */
+declare function resultantSteps(forces: readonly Force[], sf?: number): Worked;
+/**
+ * Lami's theorem: three forces in equilibrium satisfy `P/sin α = Q/sin β = R/sin γ`, where each
+ * angle is the one OPPOSITE its force, meaning the angle between the other two.
+ *
+ * The "opposite" is the whole theorem and is where it goes wrong, so the parameter names say it.
+ * Given two forces and the angles, the third follows.
+ *
+ * It is not a new law. Three forces in equilibrium form a closed triangle, and Lami is the sine
+ * rule for that triangle. Knowing that is worth more than knowing the formula, because the triangle
+ * also tells you the DIRECTION, which the formula does not.
+ */
+declare function lami(known: {
+  force: number;
+  oppositeAngleDeg: number;
+}, wantedOppositeAngleDeg: number, sf?: number): {
+  value: number;
+  worked: Worked;
+};
+/**
+ * A weight held by a string and pulled sideways: the tension and the angle the string makes.
+ *
+ * Their standard picture, and the reason it is here rather than left to `resultant` is that the
+ * answer people want is the ANGLE, which comes out of the ratio rather than out of the sum.
+ */
+declare function stringWithSideForce(mass: number, sideForce: number, g?: number, sf?: number): {
+  tension: number;
+  angleFromVerticalDeg: number;
+  worked: Worked;
+};
+interface LiftResult {
+  /** The push of the floor on the body: what a scale in the lift would read, in newtons. */
+  readonly reaction: number;
+  /** The unchanged, actual weight. */
+  readonly trueWeight: number;
+  /** `reaction / trueWeight`. Above 1 is heavy, below 1 is light, 0 is free fall. */
+  readonly factor: number;
+  readonly worked: Worked;
+}
+/**
+ * What the floor of an accelerating lift pushes back with.
+ *
+ * `acceleration` is SIGNED: positive is upwards, whatever the lift is currently doing. That is the
+ * whole simplification. A lift moving up and slowing down has a downward acceleration and the
+ * passenger feels light, which is the case the two printed rules `g + f` and `g − f` leave students
+ * unable to handle, because they are indexed on the direction of travel rather than on the
+ * direction of the acceleration.
+ */
+declare function apparentWeight(mass: number, acceleration: number, g?: number, sf?: number): LiftResult;
+/**
+ * The acceleration a body must have for the supporting force to be a given value.
+ *
+ * The inverse question, and a real one: a rope that can take 306 N holding a 45 kg boy means he has
+ * to slide DOWN with at least a certain acceleration, or the rope breaks.
+ */
+declare function accelerationForSupport(mass: number, support: number, g?: number): number;
+//#endregion
+export { Force, LiftResult, Resultant, accelerationForSupport, apparentWeight, force, forceXY, isBalanced, lami, resultant, resultantSteps, stringWithSideForce, weight };

package/dist/physics/dynamics/forces.mjs

@@ -0,0 +1,153 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { compose, resolve, toDegrees, toRadians } from "../vectors.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/dynamics/forces.ts
+/**
+* Forces as vectors: adding them up, recognising balance, and the lift.
+*
+* Nothing here is new physics. It is `vectors` with the bookkeeping that force problems need, kept
+* separate because the questions asked of a set of forces are specific: what is the resultant, is
+* it zero, and if the body is accelerating, what does the floor push back with.
+*
+* ONE IDEA RUNS THROUGH ALL OF IT. A body's weight never changes when a lift accelerates. What
+* changes is the REACTION, the push of the floor on the feet, and that is what a scale reads and
+* what a person feels. Textbooks print `a = g + f` and `a = g − f` as two rules for two cases, and
+* students then cannot say which to use when the lift is moving up but slowing down. There is one
+* rule, `R − W = ma` with `a` signed, and the two printed cases are it with the sign filled in.
+*
+* Pure: no React, no pixels.
+*/
+/** `force('push', 20, 30)`: 20 N at 30° above the horizontal. */
+function force(label, magnitude, angleDeg) {
+	const { x, y } = resolve(magnitude, angleDeg);
+	return {
+		label,
+		x,
+		y
+	};
+}
+/** A force given directly by its components, for one already resolved. */
+const forceXY = (label, x, y) => ({
+	label,
+	x,
+	y
+});
+/** The weight of a mass: `mg`, straight down. */
+const weight = (mass, g = G_EARTH) => ({
+	label: "weight",
+	x: 0,
+	y: -mass * g
+});
+/**
+* Add forces by adding their components.
+*
+* Worth stating plainly because it is the thing that makes force problems tractable and it is
+* routinely obscured: there is no special rule for three forces or for forces at awkward angles.
+* You resolve, you add the two columns, and you are done.
+*/
+function resultant(forces) {
+	let x = 0;
+	let y = 0;
+	for (const f of forces) {
+		x += f.x;
+		y += f.y;
+	}
+	const polar = compose(x, y);
+	return {
+		x,
+		y,
+		magnitude: polar.magnitude,
+		angleDeg: polar.angleDeg
+	};
+}
+/**
+* Is this set of forces in equilibrium?
+*
+* The tolerance is relative to the largest force present, not absolute. A 1 mN imbalance is nothing
+* among meganewtons and is everything among micronewtons, and a fixed epsilon gets one of those
+* two cases wrong.
+*/
+function isBalanced(forces, tolerance = 1e-9) {
+	const r = resultant(forces);
+	const largest = forces.reduce((m, f) => Math.max(m, Math.hypot(f.x, f.y)), 0);
+	return r.magnitude <= Math.max(largest, 1) * tolerance;
+}
+/** The worked resultant, set out as the two columns a mark scheme wants to see. */
+function resultantSteps(forces, sf = 3) {
+	const r = resultant(forces);
+	const w = calc().step("F_x = \\sum F\\cos\\theta, \\quad F_y = \\sum F\\sin\\theta", "resolve every force into the same two directions, then add each column");
+	for (const f of forces) w.step(`${f.label}: (${texSigFigs(f.x, sf)},\\; ${texSigFigs(f.y, sf)})\\ \\mathrm{N}`);
+	w.step(`\\sum F = (${texSigFigs(r.x, sf)},\\; ${texSigFigs(r.y, sf)})\\ \\mathrm{N}`, "the two totals");
+	w.step(`|F| = \\sqrt{F_x^2 + F_y^2} = ${texSigFigs(r.magnitude, sf)}\\ \\mathrm{N}`, `at ${texSigFigs(r.angleDeg, sf)}° to the horizontal`);
+	return w.done(r.magnitude);
+}
+/**
+* Lami's theorem: three forces in equilibrium satisfy `P/sin α = Q/sin β = R/sin γ`, where each
+* angle is the one OPPOSITE its force, meaning the angle between the other two.
+*
+* The "opposite" is the whole theorem and is where it goes wrong, so the parameter names say it.
+* Given two forces and the angles, the third follows.
+*
+* It is not a new law. Three forces in equilibrium form a closed triangle, and Lami is the sine
+* rule for that triangle. Knowing that is worth more than knowing the formula, because the triangle
+* also tells you the DIRECTION, which the formula does not.
+*/
+function lami(known, wantedOppositeAngleDeg, sf = 3) {
+	const sinKnown = Math.sin(toRadians(known.oppositeAngleDeg));
+	if (Math.abs(sinKnown) < 1e-12) throw new Error("Lami needs the angle opposite the known force, and that angle cannot be 0° or 180°: the three forces would be parallel and could not close into a triangle.");
+	const value = known.force * Math.sin(toRadians(wantedOppositeAngleDeg)) / sinKnown;
+	return {
+		value,
+		worked: calc().step("\\frac{P}{\\sin\\alpha} = \\frac{Q}{\\sin\\beta} = \\frac{R}{\\sin\\gamma}", "each angle is the one BETWEEN THE OTHER TWO forces, not the one at the force itself").step(`Q = P\\,\\frac{\\sin\\beta}{\\sin\\alpha} = ${texSigFigs(known.force, sf)} \\times \\frac{\\sin ${texSigFigs(wantedOppositeAngleDeg, sf)}^\\circ}{\\sin ${texSigFigs(known.oppositeAngleDeg, sf)}^\\circ}`).step(`Q = ${texSigFigs(value, sf)}\\ \\mathrm{N}`, "it is the sine rule for the triangle the three forces close into").done(value)
+	};
+}
+/**
+* A weight held by a string and pulled sideways: the tension and the angle the string makes.
+*
+* Their standard picture, and the reason it is here rather than left to `resultant` is that the
+* answer people want is the ANGLE, which comes out of the ratio rather than out of the sum.
+*/
+function stringWithSideForce(mass, sideForce, g = G_EARTH, sf = 3) {
+	const w = mass * g;
+	const tension = Math.hypot(w, sideForce);
+	const angle = toDegrees(Math.atan2(sideForce, w));
+	return {
+		tension,
+		angleFromVerticalDeg: angle,
+		worked: calc().step("T\\cos\\theta = mg, \\quad T\\sin\\theta = F", "the string must hold the weight up AND balance the sideways pull").step(`\\tan\\theta = \\frac{F}{mg} = \\frac{${texSigFigs(sideForce, sf)}}{${texSigFigs(w, sf)}}`, "dividing kills T, which is why the angle comes first").step(`\\theta = ${texSigFigs(angle, sf)}^\\circ`, "measured from the vertical").step(`T = \\sqrt{(mg)^2 + F^2} = ${texSigFigs(tension, sf)}\\ \\mathrm{N}`).done(tension)
+	};
+}
+/**
+* What the floor of an accelerating lift pushes back with.
+*
+* `acceleration` is SIGNED: positive is upwards, whatever the lift is currently doing. That is the
+* whole simplification. A lift moving up and slowing down has a downward acceleration and the
+* passenger feels light, which is the case the two printed rules `g + f` and `g − f` leave students
+* unable to handle, because they are indexed on the direction of travel rather than on the
+* direction of the acceleration.
+*/
+function apparentWeight(mass, acceleration, g = G_EARTH, sf = 3) {
+	const trueWeight = mass * g;
+	const reaction = mass * (g + acceleration);
+	if (reaction < 0) throw new Error(`A downward acceleration of ${-acceleration} m/s² is greater than g, so the floor cannot pull the body down. It leaves the floor rather than pressing on it with a negative force.`);
+	const worked = calc().step("R - W = ma", "one equation, with a signed upwards. The two rules printed for \"going up\" and \"going down\" are this with the sign already filled in").step(`R = m(g + a) = ${texSigFigs(mass, sf)}(${texSigFigs(g, sf)} + ${texSigFigs(acceleration, sf)})`).step(`R = ${texSigFigs(reaction, sf)}\\ \\mathrm{N}`, acceleration > 0 ? "more than the weight: accelerating upwards, so the floor must both hold the body up and speed it up" : acceleration < 0 ? "less than the weight: accelerating downwards, so the floor holds up less than all of it" : "exactly the weight: no acceleration, so the lift being in motion changes nothing").step(`W = mg = ${texSigFigs(trueWeight, sf)}\\ \\mathrm{N}`, "the weight itself never changed. Only the reaction did, and that is what a scale reads").done(reaction);
+	return {
+		reaction,
+		trueWeight,
+		factor: reaction / trueWeight,
+		worked
+	};
+}
+/**
+* The acceleration a body must have for the supporting force to be a given value.
+*
+* The inverse question, and a real one: a rope that can take 306 N holding a 45 kg boy means he has
+* to slide DOWN with at least a certain acceleration, or the rope breaks.
+*/
+function accelerationForSupport(mass, support, g = G_EARTH) {
+	return support / mass - g;
+}
+
+//#endregion
+export { accelerationForSupport, apparentWeight, force, forceXY, isBalanced, lami, resultant, resultantSteps, stringWithSideForce, weight };

package/dist/physics/dynamics/friction.d.mts

@@ -0,0 +1,76 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/dynamics/friction.d.ts
+interface AppliedForce {
+  readonly magnitude: number;
+  /**
+   * Above the SURFACE, in degrees, so 0 is along the slope. Positive lifts the body away from the
+   * surface (a pull), negative presses it in (a push). Measured from the surface rather than from
+   * the horizontal because it is the surface that friction cares about.
+   */
+  readonly angleDeg: number;
+}
+interface FrictionSetup {
+  readonly mass: number;
+  /** Coefficient of STATIC friction: sets the limit before it moves. */
+  readonly muStatic: number;
+  /** Coefficient of KINETIC friction. Defaults to `muStatic`; in reality it is usually smaller. */
+  readonly muKinetic?: number;
+  /** Slope angle above the horizontal. Zero is a flat surface. */
+  readonly inclineDeg?: number;
+  readonly applied?: AppliedForce;
+  readonly g?: number;
+}
+interface FrictionResult {
+  /** The push of the surface, perpendicular to it. Not `mg` unless the surface is flat and nothing pulls. */
+  readonly normal: number;
+  /** The force along the slope trying to move it: gravity's component plus any applied force. */
+  readonly driving: number;
+  /** `μs × N`: the most friction that is available before it slips. */
+  readonly limiting: number;
+  /** Whether the driving force beat the limit. */
+  readonly moves: boolean;
+  /** The friction that is ACTUALLY acting, which equals `driving` while it is still. */
+  readonly friction: number;
+  /** Along the slope, positive in the direction `driving` points. Zero while it is still. */
+  readonly acceleration: number;
+  readonly worked: Worked;
+}
+/**
+ * Work out whether it moves, and then how fast it picks up speed.
+ *
+ * ```ts
+ * frictionOn({ mass: 4, muStatic: 0.10, inclineDeg: 30 });  // a = 4.05 m/s²
+ * frictionOn({ mass: 4, muStatic: 0.80, inclineDeg: 30 });  // still: 0.8 > tan 30°
+ * ```
+ */
+declare function frictionOn(setup: FrictionSetup, sf?: number): FrictionResult;
+/**
+ * The angle of friction, `λ = arctan μ`, which is the same number as the angle of repose.
+ *
+ * They are given two names and taught in two places, and they are one fact: tilt a surface until a
+ * body just slips, and `mg sin θ = μ mg cos θ`, so `tan θ = μ` and the mass cancels. A steel block
+ * and a feather of the same material slip at the same angle, which is a good thing to make a
+ * learner predict before they see it.
+ */
+declare function angleOfFriction(mu: number, sf?: number): {
+  degrees: number;
+  worked: Worked;
+};
+/** The angle of repose IS the angle of friction. Named separately because the syllabus is. */
+declare const angleOfRepose: typeof angleOfFriction;
+/** `38.66°` as `38° 40'`, because that is how the answer is printed in this market's papers. */
+declare function degreesAndMinutes(degrees: number): string;
+/**
+ * Which is easier, pulling or pushing at the same angle and force?
+ *
+ * Returns both so a lab can put them side by side. The answer is always pulling, and the reason is
+ * the normal force rather than anything about the direction of travel, which is why asking a
+ * learner to predict it is a good question.
+ */
+declare function pullVersusPush(setup: Omit<FrictionSetup, 'applied'>, magnitude: number, angleDeg: number): {
+  pull: FrictionResult;
+  push: FrictionResult;
+};
+//#endregion
+export { AppliedForce, FrictionResult, FrictionSetup, angleOfFriction, angleOfRepose, degreesAndMinutes, frictionOn, pullVersusPush };

package/dist/physics/dynamics/friction.mjs

@@ -0,0 +1,119 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { toDegrees, toRadians } from "../vectors.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/dynamics/friction.ts
+/**
+* Friction, including the decision every friction question turns on and most solutions skip.
+*
+* STATIC FRICTION IS A RANGE, NOT A VALUE. `F ≤ μsR` is an inequality, and friction takes whatever
+* value it needs to keep the body still, up to that limit. `F = μR` is only true at the instant of
+* slipping. A block pushed with 3 N that needs 3 N to stay put experiences 3 N of friction, not
+* `μsR`, and a solution that writes `μsR` there has computed the wrong number and will usually
+* still get a plausible-looking answer.
+*
+* So this kernel does the decision FIRST and the arithmetic second: work out what is driving the
+* body, work out the largest friction available, compare them, and only then compute. That order
+* is the method, and {@link frictionOn} reports the comparison as part of its result so a lesson
+* can show it and a lab can visualise it as a bar that fills up and then gives way.
+*
+* THE OTHER THING THAT GETS MISSED: a force applied at an angle changes the NORMAL force, and so
+* changes friction. Pulling upwards at an angle lightens the body and helps twice over; pushing
+* downwards at an angle presses it into the surface and fights itself. This is why a suitcase is
+* easier to pull than to push, and it falls straight out of the equations rather than needing to be
+* remembered separately.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* Work out whether it moves, and then how fast it picks up speed.
+*
+* ```ts
+* frictionOn({ mass: 4, muStatic: 0.10, inclineDeg: 30 });  // a = 4.05 m/s²
+* frictionOn({ mass: 4, muStatic: 0.80, inclineDeg: 30 });  // still: 0.8 > tan 30°
+* ```
+*/
+function frictionOn(setup, sf = 3) {
+	const g = setup.g ?? 9.8;
+	const muKinetic = setup.muKinetic ?? setup.muStatic;
+	const slope = toRadians(setup.inclineDeg ?? 0);
+	const weight = setup.mass * g;
+	const applied = setup.applied;
+	const phi = toRadians(applied?.angleDeg ?? 0);
+	const appliedAlong = applied ? applied.magnitude * Math.cos(phi) : 0;
+	const appliedAway = applied ? applied.magnitude * Math.sin(phi) : 0;
+	const normal = weight * Math.cos(slope) - appliedAway;
+	if (normal <= 0) throw new Error(`The applied force lifts the body clear of the surface (normal force would be ${normal.toPrecision(3)} N). There is no friction because there is no contact; this is a projectile question now.`);
+	const driving = weight * Math.sin(slope) + appliedAlong;
+	const limiting = setup.muStatic * normal;
+	const moves = Math.abs(driving) > limiting;
+	const kinetic = muKinetic * normal;
+	const friction = moves ? kinetic : Math.abs(driving);
+	const acceleration = moves ? (Math.abs(driving) - kinetic) / setup.mass : 0;
+	const direction = driving < 0 ? -1 : 1;
+	const w = calc().step("R = mg\\cos\\theta" + (applied ? " - F\\sin\\phi" : ""), applied ? "the normal force first, because friction depends on it and the applied force changes it" : "the normal force first, because friction depends on it").step(`R = ${texSigFigs(normal, sf)}\\ \\mathrm{N}`).step("F_{\\text{max}} = \\mu_s R", "the MOST friction available. Static friction is an inequality, F ≤ μsR, not an equation").step(`F_{\\text{max}} = ${texSigFigs(setup.muStatic, sf)} \\times ${texSigFigs(normal, sf)} = ${texSigFigs(limiting, sf)}\\ \\mathrm{N}`).step(`\\text{driving} = ${texSigFigs(Math.abs(driving), sf)}\\ \\mathrm{N} \\;${moves ? ">" : "\\leq"}\\; ${texSigFigs(limiting, sf)}\\ \\mathrm{N}`, moves ? "the drive beats the limit, so it slips and friction drops to its kinetic value" : "the limit is not reached, so friction is exactly as large as it needs to be and no larger");
+	if (moves) {
+		w.step(`ma = ${texSigFigs(Math.abs(driving), sf)} - \\mu_k R = ${texSigFigs(Math.abs(driving), sf)} - ${texSigFigs(kinetic, sf)}`);
+		w.step(`a = ${texSigFigs(acceleration * direction, sf)}\\ \\mathrm{m\\,s^{-2}}`, `to ${sf} significant figures`);
+	} else w.step(`f = ${texSigFigs(friction, sf)}\\ \\mathrm{N}, \\quad a = 0`, "friction matches the drive exactly. Writing μsR here would be the wrong number");
+	return {
+		normal,
+		driving,
+		limiting,
+		moves,
+		friction,
+		acceleration: acceleration * direction,
+		worked: w.done(acceleration * direction)
+	};
+}
+/**
+* The angle of friction, `λ = arctan μ`, which is the same number as the angle of repose.
+*
+* They are given two names and taught in two places, and they are one fact: tilt a surface until a
+* body just slips, and `mg sin θ = μ mg cos θ`, so `tan θ = μ` and the mass cancels. A steel block
+* and a feather of the same material slip at the same angle, which is a good thing to make a
+* learner predict before they see it.
+*/
+function angleOfFriction(mu, sf = 3) {
+	const degrees = toDegrees(Math.atan(mu));
+	return {
+		degrees,
+		worked: calc().step("mg\\sin\\theta = \\mu\\, mg\\cos\\theta", "at the angle where it is just about to slip").step("\\tan\\theta = \\mu", "the mass cancels, so the angle does not depend on how heavy it is").step(`\\theta = \\arctan ${texSigFigs(mu, sf)} = ${texSigFigs(degrees, sf)}^\\circ`, `which is ${degreesAndMinutes(degrees)}`).done(degrees)
+	};
+}
+/** The angle of repose IS the angle of friction. Named separately because the syllabus is. */
+const angleOfRepose = angleOfFriction;
+/** `38.66°` as `38° 40'`, because that is how the answer is printed in this market's papers. */
+function degreesAndMinutes(degrees) {
+	const whole = Math.floor(degrees);
+	const minutes = Math.round((degrees - whole) * 60);
+	return minutes === 60 ? `${whole + 1}° 0'` : `${whole}° ${minutes}'`;
+}
+/**
+* Which is easier, pulling or pushing at the same angle and force?
+*
+* Returns both so a lab can put them side by side. The answer is always pulling, and the reason is
+* the normal force rather than anything about the direction of travel, which is why asking a
+* learner to predict it is a good question.
+*/
+function pullVersusPush(setup, magnitude, angleDeg) {
+	return {
+		pull: frictionOn({
+			...setup,
+			applied: {
+				magnitude,
+				angleDeg: Math.abs(angleDeg)
+			}
+		}),
+		push: frictionOn({
+			...setup,
+			applied: {
+				magnitude,
+				angleDeg: -Math.abs(angleDeg)
+			}
+		})
+	};
+}
+
+//#endregion
+export { angleOfFriction, angleOfRepose, degreesAndMinutes, frictionOn, pullVersusPush };

package/dist/physics/dynamics/system.d.mts

@@ -0,0 +1,68 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/dynamics/system.d.ts
+interface LinkedBody {
+  readonly label: string;
+  readonly mass: number;
+  /**
+   * The force along this body's direction of motion that does NOT come from a string, signed so
+   * that positive drives the system the way you have chosen to call forwards.
+   *
+   * A hanging mass pulling the system along has `drive = +mg`. A hanging mass on the other side of
+   * a pulley, being lifted, has `drive = -mg`. A block on a level table being pushed has
+   * `drive = +F`. That single signed number is the whole difference between the textbook's separate
+   * cases.
+   */
+  readonly drive: number;
+  /** A resisting force, always opposing motion whichever way it goes. Friction, drag, a brake. */
+  readonly resist?: number;
+}
+interface SystemResult {
+  /** Positive in the direction you called forwards. */
+  readonly acceleration: number;
+  readonly moving: boolean;
+  readonly totalMass: number;
+  readonly totalDrive: number;
+  readonly totalResist: number;
+  /**
+   * The tension in each link: `tensions[i]` joins `bodies[i]` to `bodies[i+1]`, so there is one
+   * fewer than there are bodies.
+   *
+   * Null when the system does not move. That is not a gap, it is the truth: with several bodies
+   * held still by friction, how much friction each one contributes is not determined by the
+   * equations of motion, and a single number here would be an invention. A stuck system is
+   * analysed one body at a time.
+   */
+  readonly tensions: readonly number[] | null;
+  readonly worked: Worked;
+}
+/**
+ * Solve a chain of bodies joined by inextensible strings.
+ *
+ * Order matters: `bodies[0]` is at the back and `bodies[n-1]` at the front, in the direction you
+ * called forwards, because that is what decides which side of each string is which.
+ */
+declare function linkedSystem(bodies: readonly LinkedBody[], sf?: number): SystemResult;
+interface AtwoodResult extends SystemResult {
+  /** The single tension in the string. */
+  readonly tension: number;
+  /**
+   * What the pulley's support has to hold, which is `2T` and NOT the combined weight.
+   *
+   * It is less, because the system is accelerating: some of the weight is going into the motion
+   * rather than into the support. A good prediction question, because almost everyone guesses
+   * `(m₁ + m₂)g` first.
+   */
+  readonly pulleyLoad: number;
+}
+/**
+ * Two masses over a frictionless pulley.
+ *
+ * Not a special case, and deliberately implemented by delegating rather than by its own formula:
+ * forwards is "the heavier one descends", so gravity drives one body and hinders the other, and
+ * that is the only declaration needed. If this had its own `(m₁−m₂)g/(m₁+m₂)` written out, that
+ * formula could drift away from the general solver and nothing would notice.
+ */
+declare function atwood(m1: number, m2: number, g?: number, sf?: number): AtwoodResult;
+//#endregion
+export { AtwoodResult, LinkedBody, SystemResult, atwood, linkedSystem };

package/dist/physics/dynamics/system.mjs

@@ -0,0 +1,125 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/dynamics/system.ts
+/**
+* Bodies joined by strings: one acceleration, and the tension in every link.
+*
+* THE METHOD IS THE POINT, and it is one trick used twice.
+*
+* First, add the equations for all the bodies together. Every tension appears twice with opposite
+* signs, because the string pulls the body in front backwards exactly as hard as it pulls the body
+* behind forwards, so they all cancel and what is left is
+*
+*     a = (total driving force) / (total mass)
+*
+* with no tensions in it at all. That is why the acceleration of a loaded train is easy and the
+* coupling forces are not.
+*
+* Second, to get one tension, draw a line through the system at that string and write the equation
+* for everything on one side of the line. Only that one tension crosses the line, so it is the only
+* unknown left.
+*
+* WHAT THIS COVERS, from one declaration: blocks in a row being pushed, a train and its carriages,
+* a mass on a table pulled by a hanging mass, and an Atwood machine. Those are four separate
+* "types" in a textbook, and the only thing that differs between them is which bodies have gravity
+* helping and which have it hindering. A body's `drive` says so, and the rest is identical.
+*
+* Pure: no React, no pixels.
+*/
+/**
+* Solve a chain of bodies joined by inextensible strings.
+*
+* Order matters: `bodies[0]` is at the back and `bodies[n-1]` at the front, in the direction you
+* called forwards, because that is what decides which side of each string is which.
+*/
+function linkedSystem(bodies, sf = 3) {
+	if (bodies.length === 0) throw new Error("A system needs at least one body.");
+	const totalMass = bodies.reduce((m, b) => m + b.mass, 0);
+	if (totalMass <= 0) throw new Error("Total mass must be positive.");
+	const totalDrive = bodies.reduce((f, b) => f + b.drive, 0);
+	const totalResist = bodies.reduce((f, b) => f + Math.abs(b.resist ?? 0), 0);
+	const moving = Math.abs(totalDrive) > totalResist;
+	const direction = totalDrive < 0 ? -1 : 1;
+	const acceleration = moving ? direction * (Math.abs(totalDrive) - totalResist) / totalMass : 0;
+	const w = calc().step("a = \\frac{\\sum F}{\\sum m}", "add every body’s equation: each tension appears twice with opposite signs and cancels").step(`a = \\frac{${texSigFigs(totalDrive, sf)}${totalResist ? ` - ${texSigFigs(totalResist, sf)}` : ""}}{${texSigFigs(totalMass, sf)}}`, bodies.map((b) => `${b.label} ${texSigFigs(b.drive, sf)} N`).join(", "));
+	if (!moving) {
+		/**
+		* A stationary system's tensions are determinate ONLY when nothing is resisting.
+		*
+		* With friction in it, how much each surface contributes is not fixed by the equations of
+		* motion: two blocks can share the load any number of ways and every split balances. Reporting
+		* a number there would be an invention, so it stays null.
+		*
+		* With no friction, "not moving" means the drives cancel, and each cut still has exactly one
+		* unknown crossing it. Two equal masses over a pulley are the everyday case, and refusing to
+		* give their `T = mg` would push the special case out to every caller.
+		*/
+		const determinate = totalResist === 0;
+		const held = determinate ? bodies.slice(0, -1).map((_, i) => {
+			const ahead = bodies.slice(i + 1);
+			return Math.abs(-ahead.reduce((f, b) => f + b.drive, 0));
+		}) : null;
+		w.step("\\text{driving} \\leq \\text{resisting} \\;\\Rightarrow\\; a = 0", determinate ? "it does not move, so each body is in balance and the string simply holds the load" : "it does not move, and with friction sharing the load the tensions need a body-by-body analysis rather than this one");
+		return {
+			acceleration: 0,
+			moving: false,
+			totalMass,
+			totalDrive,
+			totalResist,
+			tensions: held,
+			worked: w.done(0)
+		};
+	}
+	w.step(`a = ${texSigFigs(acceleration, sf)}\\ \\mathrm{m\\,s^{-2}}`, "the same for every body, because the string does not stretch");
+	const tensions = [];
+	for (let i = 0; i < bodies.length - 1; i++) {
+		const ahead = bodies.slice(i + 1);
+		const massAhead = ahead.reduce((m, b) => m + b.mass, 0);
+		const driveAhead = ahead.reduce((f, b) => f + b.drive, 0);
+		const resistAhead = ahead.reduce((f, b) => f + Math.abs(b.resist ?? 0), 0);
+		const signed = massAhead * acceleration - driveAhead + direction * resistAhead;
+		const tension = Math.abs(signed);
+		tensions.push(tension);
+		w.step(`T_{${i + 1}} = ${texSigFigs(massAhead, sf)}a - ${texSigFigs(driveAhead, sf)} = ${texSigFigs(tension, sf)}\\ \\mathrm{N}`, `cut the string between ${bodies[i].label} and ${bodies[i + 1].label}, then use only what is beyond the cut: only this one tension crosses it${signed < 0 ? `, and it pulls ${bodies[i + 1].label} backwards` : ""}`);
+	}
+	return {
+		acceleration,
+		moving: true,
+		totalMass,
+		totalDrive,
+		totalResist,
+		tensions,
+		worked: w.done(acceleration)
+	};
+}
+/**
+* Two masses over a frictionless pulley.
+*
+* Not a special case, and deliberately implemented by delegating rather than by its own formula:
+* forwards is "the heavier one descends", so gravity drives one body and hinders the other, and
+* that is the only declaration needed. If this had its own `(m₁−m₂)g/(m₁+m₂)` written out, that
+* formula could drift away from the general solver and nothing would notice.
+*/
+function atwood(m1, m2, g = G_EARTH, sf = 3) {
+	const heavy = Math.max(m1, m2);
+	const light = Math.min(m1, m2);
+	const result = linkedSystem([{
+		label: `descending mass ${heavy} kg`,
+		mass: heavy,
+		drive: heavy * g
+	}, {
+		label: `rising mass ${light} kg`,
+		mass: light,
+		drive: -light * g
+	}], sf);
+	const tension = result.tensions?.[0] ?? light * g;
+	return {
+		...result,
+		tension,
+		pulleyLoad: 2 * tension
+	};
+}
+
+//#endregion
+export { atwood, linkedSystem };