@classytic/stage 0.2.0 → 0.4.0

package/dist/physics/projectile.mjs

@@ -0,0 +1,185 @@
+import { calc, texSigFigs } from "../core/worked.mjs";
+import { compose, resolve, toDegrees, toRadians } from "./vectors.mjs";
+import { G_EARTH, vertical } from "./kinematics/free-fall.mjs";
+import { MOTION_UNITS_TEX } from "./kinematics/equations.mjs";
+import { motion, timeToReach } from "./kinematics/solve.mjs";
+
+//#region src/physics/projectile.ts
+/**
+* Projectile motion, as what it actually is: TWO straight-line motions sharing one clock.
+*
+* Every formula in a projectile chapter is a consequence of three sentences:
+*
+*   1. Horizontally there is no force, so the horizontal velocity never changes: `x = u_x t`.
+*   2. Vertically there is gravity and nothing else, so it is ordinary SUVAT with `a = −g`.
+*   3. The two motions share `t`, and that is the only thing connecting them.
+*
+* So this module declares almost no formulas of its own. It resolves the launch into components
+* with `vectors`, hands the vertical part to `kinematics`, and multiplies the horizontal one out.
+* A chapter's worth of results, range and time of flight and maximum height, fall out of that,
+* and crucially they fall out IN THE SAME WAY for the cases textbooks separate into different
+* "types": launched from the ground, launched from a cliff, launched downwards. Those are the same
+* three sentences with a different starting height, and building them as one thing rather than as
+* three is the whole point.
+*
+* The two-motion structure is also what makes the derivations honest. When {@link flightSteps}
+* shows a time of flight, the quadratic and its rejected root come from the kinematics kernel, not
+* from a projectile-shaped formula that hides them.
+*
+* Pure: no React, no pixels.
+*/
+const gravityOf = (launch) => launch.g ?? 9.8;
+const heightOf = (launch) => launch.height ?? 0;
+/** The launch speed split into its horizontal and vertical parts. */
+const launchVelocity = (launch) => resolve(launch.speed, launch.angleDeg);
+/** The vertical half of a flight, as the signed SUVAT a falling-body question would use. */
+const verticalHalf = (uy, fallsBy, g) => vertical({
+	speed: Math.abs(uy),
+	direction: uy >= 0 ? "up" : "down",
+	fallsBy,
+	g
+});
+/**
+* Everything about one flight.
+*
+* The time of flight goes through the kinematics solver rather than through a closed form, because
+* with a launch height it IS a quadratic with a root to reject, and routing it through the same
+* code path as the level-ground case means the level-ground case cannot quietly be a different
+* piece of physics.
+*/
+function flight(launch) {
+	const g = gravityOf(launch);
+	const h = heightOf(launch);
+	const { x: ux, y: uy } = launchVelocity(launch);
+	const timeOfFlight = motion("t", verticalHalf(uy, h, g)).value;
+	const range = ux * timeOfFlight;
+	const timeToPeak = uy > 0 ? uy / g : 0;
+	const peakRise = uy > 0 ? uy * uy / (2 * g) : 0;
+	const impact = velocityAt(launch, timeOfFlight);
+	const { magnitude, angleDeg } = compose(impact.x, impact.y);
+	return {
+		launchVelocity: {
+			x: ux,
+			y: uy
+		},
+		timeOfFlight,
+		range,
+		timeToPeak,
+		peakRise,
+		maxHeight: h + peakRise,
+		impactSpeed: magnitude,
+		impactAngleDeg: -angleDeg
+	};
+}
+/** Where the projectile is at time `t`, measured from the launch point. */
+function positionAt(launch, t) {
+	const g = gravityOf(launch);
+	const { x: ux, y: uy } = launchVelocity(launch);
+	return {
+		x: ux * t,
+		y: uy * t - .5 * g * t * t
+	};
+}
+/** How fast and which way it is going at time `t`. Horizontal never changes; that is the point. */
+function velocityAt(launch, t) {
+	const g = gravityOf(launch);
+	const { x: ux, y: uy } = launchVelocity(launch);
+	return {
+		x: ux,
+		y: uy - g * t
+	};
+}
+/** The arc, sampled for drawing. Always includes the landing point exactly. */
+function arc(launch, samples = 64) {
+	const total = flight(launch).timeOfFlight;
+	const points = [];
+	for (let i = 0; i <= samples; i++) points.push(positionAt(launch, total * i / samples));
+	return points;
+}
+/**
+* Every moment the projectile is at a given height above the LAUNCH point.
+*
+* Usually two, and that is the interesting part: on the way up and on the way down. A lab that
+* draws both, and a lesson that says why there are two, turns a confusing quadratic into the
+* obvious fact that the arc is symmetric.
+*/
+function timeAtHeight(launch, heightAboveLaunch) {
+	const g = gravityOf(launch);
+	const { y: uy } = launchVelocity(launch);
+	return timeToReach(heightAboveLaunch, {
+		u: uy,
+		a: -g
+	});
+}
+/**
+* The launch angles that put a projectile a given distance away on level ground.
+*
+* There are normally TWO, one low and flat and one high and lobbed, and they are complementary
+* (they add to 90°). That pair is the most under-taught fact in the topic: a mortar and a rifle
+* hitting the same target is the same equation twice. Returns null when the target is out of
+* range at that speed, which is the honest answer and the one a game needs.
+*/
+function anglesForRange(range, speed, g = G_EARTH) {
+	const sin2theta = range * g / (speed * speed);
+	if (sin2theta > 1 || sin2theta < -1) return null;
+	const low = toDegrees(Math.asin(sin2theta)) / 2;
+	return {
+		low,
+		high: 90 - low
+	};
+}
+/**
+* The smallest launch speed that can reach a distance on level ground, and the angle that does it.
+*
+* `R = v² sin 2θ / g` is largest for a given speed when `sin 2θ = 1`, so the cheapest shot is
+* always at 45° and needs `v = √(Rg)`. Worth having as its own function because "what is the
+* minimum speed" is a standard exam question and because the answer explains why 45° is the angle
+* everybody remembers.
+*/
+function minimumSpeedForRange(range, g = G_EARTH) {
+	return {
+		speed: Math.sqrt(range * g),
+		angleDeg: 45
+	};
+}
+/**
+* The launch angle at which the range equals the maximum height.
+*
+* `R = H` gives `tan θ = 4`, independent of speed and of gravity, which is a genuinely surprising
+* result and a good lab question: the learner predicts whether firing harder changes the angle,
+* and it does not.
+*/
+const angleWhereRangeEqualsHeight = () => toDegrees(Math.atan(4));
+/**
+* The worked solution for a flight, as a lesson would set it out.
+*
+* Structured as resolve, then vertical, then horizontal, in that order and labelled as such,
+* because that ordering IS the method. A derivation that jumps to `R = u² sin 2θ / g` gives a
+* student a formula to memorise; this one gives them something they can redo when the question has
+* a cliff in it and the memorised formula does not apply.
+*/
+function flightSteps(launch, sf = 3) {
+	const g = gravityOf(launch);
+	const h = heightOf(launch);
+	const { x: ux, y: uy } = launchVelocity(launch);
+	const f = flight(launch);
+	const w = calc();
+	const SPEED = MOTION_UNITS_TEX.u;
+	w.step(`u_x = u\\cos\\theta = ${texSigFigs(launch.speed, sf)}\\cos ${texSigFigs(launch.angleDeg, sf)}^\\circ = ${texSigFigs(ux, sf)}\\ ${SPEED}`, "step 1: split the launch into two motions");
+	w.step(`u_y = u\\sin\\theta = ${texSigFigs(launch.speed, sf)}\\sin ${texSigFigs(launch.angleDeg, sf)}^\\circ = ${texSigFigs(uy, sf)}\\ ${SPEED}`);
+	const verticalSolve = motion("t", verticalHalf(uy, h, g), sf);
+	w.step(`\\text{up is positive} \\;\\Rightarrow\\; a = -g, \\quad s = ${h > 0 ? "-h" : "0"}`, h > 0 ? "step 2: the vertical motion. It lands below the launch point, so its displacement is negative" : "step 2: the vertical motion. It lands back at launch height, so its displacement is zero");
+	for (const step of verticalSolve.worked.steps.slice(1)) w.step(step.tex, step.note);
+	w.step(`x = u_x t = ${texSigFigs(ux, sf + 1)} \\times ${texSigFigs(f.timeOfFlight, sf + 1)} = ${texSigFigs(f.range, sf + 1)}\\ \\mathrm{m}`, "step 3: the horizontal motion, which never accelerated, over that same time");
+	return w.done(f.range);
+}
+/** The working for the peak: why the highest point is where the vertical velocity is zero. */
+function peakSteps(launch, sf = 3) {
+	const g = gravityOf(launch);
+	const { y: uy } = launchVelocity(launch);
+	const f = flight(launch);
+	return calc().step(`v_y = 0 \\text{ at the top}`, "it is still moving horizontally, but for that instant it is going neither up nor down").step(`t = \\frac{u_y}{g} = \\frac{${texSigFigs(uy, sf)}}{${texSigFigs(g, sf)}} = ${texSigFigs(f.timeToPeak, sf)}\\ \\mathrm{s}`, "from v = u + at with v = 0").step(`H = \\frac{u_y^2}{2g} = ${texSigFigs(f.peakRise, sf)}\\ \\mathrm{m}`, "from v² = u² + 2as with v = 0").done(f.peakRise);
+}
+
+//#endregion
+export { angleWhereRangeEqualsHeight, anglesForRange, arc, flight, flightSteps, launchVelocity, minimumSpeedForRange, peakSteps, positionAt, timeAtHeight, velocityAt };

package/dist/physics/rotation/angular.d.mts

@@ -0,0 +1,85 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/rotation/angular.d.ts
+/** Revolutions per second to radians per second. */
+declare const fromRevsPerSecond: (n: number) => number;
+/** Revolutions per minute to radians per second. */
+declare const fromRPM: (rpm: number) => number;
+/** `L = Iω`, for a body whose moment of inertia you know. */
+declare const angularMomentum: (inertia: number, omega: number) => number;
+/**
+ * `L = mvr` for a point mass on a string, which is `Iω` with `I = mr²` written out.
+ *
+ * Kept because that is how the question is posed, and because seeing the two forms give the same
+ * number is what makes `I = mr²` feel like a definition rather than another formula.
+ */
+declare function angularMomentumOfPoint(mass: number, speed: number, radius: number, sf?: number): {
+  value: number;
+  worked: Worked;
+};
+interface SpinChange {
+  readonly omega2: number;
+  readonly energyBefore: number;
+  readonly energyAfter: number;
+  /** Positive when the body ends up with MORE energy, which pulling in always does. */
+  readonly workDone: number;
+  readonly worked: Worked;
+}
+/**
+ * The skater: `I₁ω₁ = I₂ω₂` when nothing external twists the system.
+ *
+ * Returns the energy on both sides as well as the new spin rate, because the energy is the
+ * interesting half and a function that returned only `ω₂` would hide it.
+ */
+declare function conserveSpin(inertia1: number, omega1: number, inertia2: number, sf?: number): SpinChange;
+/**
+ * The shape factor `k²/r²` for the bodies a rolling question uses.
+ *
+ * Derived from the standard results rather than listed as folklore: a solid disc is `½MR²`, so
+ * `k²/r² = ½`, and so on. Everything about a rolling race follows from this one column.
+ */
+declare const ROLLING_SHAPES: {
+  readonly hoop: {
+    readonly label: "hoop or thin ring";
+    readonly factor: 1;
+  };
+  readonly disc: {
+    readonly label: "solid disc or cylinder";
+    readonly factor: 0.5;
+  };
+  readonly sphere: {
+    readonly label: "solid sphere";
+    readonly factor: 0.4;
+  };
+  readonly shell: {
+    readonly label: "hollow sphere";
+    readonly factor: number;
+  };
+};
+type RollingShape = keyof typeof ROLLING_SHAPES;
+interface RollingEnergy {
+  readonly translational: number;
+  readonly rotational: number;
+  readonly total: number;
+  /** The fraction of the energy that is in the spin. Shape alone decides it. */
+  readonly spinShare: number;
+  readonly worked: Worked;
+}
+/** How a rolling body's kinetic energy divides between going along and going round. */
+declare function rollingEnergy(mass: number, speed: number, shape: RollingShape, sf?: number): RollingEnergy;
+/**
+ * The speed a body reaches rolling from rest down a height `h`.
+ *
+ * `v = √(2gh / (1 + k²/r²))`. Mass and radius cancel completely, so the race down a slope is
+ * decided by shape and nothing else: sphere, then disc, then hollow sphere, then hoop, every time,
+ * whatever they weigh. Worth having a learner predict first, because the intuition is that the
+ * heavy one wins.
+ */
+declare function rollingSpeedFromHeight(height: number, shape: RollingShape, g?: number, sf?: number): {
+  speed: number;
+  worked: Worked;
+};
+/** Order a set of shapes by how fast they finish a roll: the race, as a prediction to check. */
+declare const rollingRace: (shapes?: readonly RollingShape[]) => RollingShape[];
+//#endregion
+export { ROLLING_SHAPES, RollingEnergy, RollingShape, SpinChange, angularMomentum, angularMomentumOfPoint, conserveSpin, fromRPM, fromRevsPerSecond, rollingEnergy, rollingRace, rollingSpeedFromHeight };

package/dist/physics/rotation/angular.mjs

@@ -0,0 +1,130 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+
+//#region src/physics/rotation/angular.ts
+/**
+* Angular momentum, rotational energy, and rolling.
+*
+* THE SKATER. Angular momentum is conserved when no external torque acts, and `L = Iω` means that
+* pulling your arms in cuts `I` and so must raise `ω`. Everyone has seen this and almost nobody is
+* told the surprising half: the kinetic energy goes UP, not stays the same. `E = ½Iω²` and `L = Iω`
+* together give `E = L²/2I`, so halving `I` at constant `L` DOUBLES the energy. It comes from the
+* skater's muscles doing work pulling the arms in against the outward pull, which is a real,
+* checkable, slightly startling fact and a much better question than "what is the new ω".
+*
+* ROLLING. A rolling body carries its energy in two places at once, `½mv²` in its motion and `½Iω²`
+* in its spin, and the split depends only on SHAPE. `v = rω` links them, so
+*
+*     E = ½mv²(1 + k²/r²)
+*
+* where `k` is the radius of gyration. A hoop puts half its energy into spin and a sphere only
+* two-sevenths, so racing them down a slope sorts them by shape with mass and radius cancelling
+* out entirely. That cancellation is the best prediction question in the topic, because everybody
+* guesses the heavy one wins.
+*
+* Pure: no React, no pixels.
+*/
+/** Revolutions per second to radians per second. */
+const fromRevsPerSecond = (n) => 2 * Math.PI * n;
+/** Revolutions per minute to radians per second. */
+const fromRPM = (rpm) => 2 * Math.PI * rpm / 60;
+/** `L = Iω`, for a body whose moment of inertia you know. */
+const angularMomentum = (inertia, omega) => inertia * omega;
+/**
+* `L = mvr` for a point mass on a string, which is `Iω` with `I = mr²` written out.
+*
+* Kept because that is how the question is posed, and because seeing the two forms give the same
+* number is what makes `I = mr²` feel like a definition rather than another formula.
+*/
+function angularMomentumOfPoint(mass, speed, radius, sf = 3) {
+	const value = mass * speed * radius;
+	return {
+		value,
+		worked: calc().step("L = I\\omega = (mr^2)\\left(\\frac{v}{r}\\right) = mvr", "the same thing written two ways").step(`L = ${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)} \\times ${texSigFigs(radius, sf)} = ${texSigFigs(value, sf)}\\ \\mathrm{kg\\,m^2\\,s^{-1}}`).done(value)
+	};
+}
+/**
+* The skater: `I₁ω₁ = I₂ω₂` when nothing external twists the system.
+*
+* Returns the energy on both sides as well as the new spin rate, because the energy is the
+* interesting half and a function that returned only `ω₂` would hide it.
+*/
+function conserveSpin(inertia1, omega1, inertia2, sf = 3) {
+	if (inertia1 <= 0 || inertia2 <= 0) throw new Error("Moments of inertia must be positive.");
+	const omega2 = inertia1 * omega1 / inertia2;
+	const energyBefore = .5 * inertia1 * omega1 * omega1;
+	const energyAfter = .5 * inertia2 * omega2 * omega2;
+	const worked = calc().step("I_1\\omega_1 = I_2\\omega_2", "no external torque, so the angular momentum cannot change").step(`\\omega_2 = \\frac{${texSigFigs(inertia1, sf)} \\times ${texSigFigs(omega1, sf)}}{${texSigFigs(inertia2, sf)}} = ${texSigFigs(omega2, sf)}\\ \\mathrm{rad\\,s^{-1}}`).step(`E = \\frac{L^2}{2I}: ${texSigFigs(energyBefore, sf)} \\to ${texSigFigs(energyAfter, sf)}\\ \\mathrm{J}`, energyAfter > energyBefore + 1e-12 ? "the energy ROSE, and it came from the muscles pulling the arms in against the outward pull" : energyAfter < energyBefore - 1e-12 ? "the energy fell: letting the arms out, work is done BY the body" : "unchanged, because the moment of inertia did not change").done(omega2);
+	return {
+		omega2,
+		energyBefore,
+		energyAfter,
+		workDone: energyAfter - energyBefore,
+		worked
+	};
+}
+/**
+* The shape factor `k²/r²` for the bodies a rolling question uses.
+*
+* Derived from the standard results rather than listed as folklore: a solid disc is `½MR²`, so
+* `k²/r² = ½`, and so on. Everything about a rolling race follows from this one column.
+*/
+const ROLLING_SHAPES = {
+	hoop: {
+		label: "hoop or thin ring",
+		factor: 1
+	},
+	disc: {
+		label: "solid disc or cylinder",
+		factor: .5
+	},
+	sphere: {
+		label: "solid sphere",
+		factor: .4
+	},
+	shell: {
+		label: "hollow sphere",
+		factor: 2 / 3
+	}
+};
+/** How a rolling body's kinetic energy divides between going along and going round. */
+function rollingEnergy(mass, speed, shape, sf = 3) {
+	const { factor, label } = ROLLING_SHAPES[shape];
+	const translational = .5 * mass * speed * speed;
+	const rotational = factor * translational;
+	const total = translational + rotational;
+	const worked = calc().step("E = \\tfrac{1}{2}mv^2 + \\tfrac{1}{2}I\\omega^2 = \\tfrac{1}{2}mv^2\\left(1 + \\frac{k^2}{r^2}\\right)", `v = rω links the two, and for a ${label} the shape factor is ${factor}`).step(`E = ${texSigFigs(translational, sf)} + ${texSigFigs(rotational, sf)} = ${texSigFigs(total, sf)}\\ \\mathrm{J}`, `${texSigFigs(100 * (rotational / total), sf)}% of it is in the spin, and that share depends on SHAPE alone`).done(total);
+	return {
+		translational,
+		rotational,
+		total,
+		spinShare: rotational / total,
+		worked
+	};
+}
+/**
+* The speed a body reaches rolling from rest down a height `h`.
+*
+* `v = √(2gh / (1 + k²/r²))`. Mass and radius cancel completely, so the race down a slope is
+* decided by shape and nothing else: sphere, then disc, then hollow sphere, then hoop, every time,
+* whatever they weigh. Worth having a learner predict first, because the intuition is that the
+* heavy one wins.
+*/
+function rollingSpeedFromHeight(height, shape, g = 9.8, sf = 3) {
+	if (height < 0) throw new Error("The drop must not be negative.");
+	const { factor, label } = ROLLING_SHAPES[shape];
+	const speed = Math.sqrt(2 * g * height / (1 + factor));
+	return {
+		speed,
+		worked: calc().step("mgh = \\tfrac{1}{2}mv^2\\left(1 + \\frac{k^2}{r^2}\\right)", "all the lost height becomes both kinds of motion").step("v = \\sqrt{\\frac{2gh}{1 + k^2/r^2}}", "the mass cancels, and so does the radius: only the SHAPE is left").step(`v = ${texSigFigs(speed, sf)}\\ \\mathrm{m\\,s^{-1}}`, `for a ${label}. A body that puts more energy into spinning arrives slower, whatever it weighs`).done(speed)
+	};
+}
+/** Order a set of shapes by how fast they finish a roll: the race, as a prediction to check. */
+const rollingRace = (shapes = [
+	"sphere",
+	"disc",
+	"shell",
+	"hoop"
+]) => [...shapes].sort((a, b) => ROLLING_SHAPES[a].factor - ROLLING_SHAPES[b].factor);
+
+//#endregion
+export { ROLLING_SHAPES, angularMomentum, angularMomentumOfPoint, conserveSpin, fromRPM, fromRevsPerSecond, rollingEnergy, rollingRace, rollingSpeedFromHeight };

package/dist/physics/rotation/circular.d.mts

@@ -0,0 +1,79 @@
+import { Worked } from "../../core/worked.mjs";
+
+//#region src/physics/rotation/circular.d.ts
+/** `a = v²/r = ω²r`, directed at the centre. */
+declare const centripetalAcceleration: (speed: number, radius: number) => number;
+/** `F = mv²/r`: not an extra force, but what the real ones have to add up to. */
+declare function centripetalForce(mass: number, speed: number, radius: number, sf?: number): {
+  value: number;
+  acceleration: number;
+  worked: Worked;
+};
+/** The same thing from a spin rate: `F = mω²r`, which is what a whirled string question gives. */
+declare const centripetalFromOmega: (mass: number, omega: number, radius: number) => number;
+/**
+ * The fastest a vehicle can take a FLAT bend before it slides.
+ *
+ * Friction is the only thing pointing at the centre, so `μmg ≥ mv²/r` and the mass cancels: a
+ * loaded lorry and an empty one slide at the same speed, which is not what anyone expects.
+ */
+declare function maxSpeedFlat(radius: number, mu: number, g?: number, sf?: number): {
+  speed: number;
+  worked: Worked;
+};
+/**
+ * The angle a bend should be banked to, so that no friction is needed at all: `tan θ = v²/rg`.
+ *
+ * At this angle the track's normal force alone leans inward enough to turn the vehicle, and the
+ * tyres do no sideways work. It is the design speed of the bend, and again the mass cancels, so one
+ * bank angle serves a bicycle and a lorry.
+ */
+declare function bankingAngle(speed: number, radius: number, g?: number, sf?: number): {
+  degrees: number;
+  worked: Worked;
+};
+/**
+ * How much higher the outer rail must sit, given the gauge.
+ *
+ * The railway form of the same question: the bank angle is set by raising one rail, so
+ * `h = gauge · sin θ`. Their worked example is a 98 m bend at 9.8 m/s on a 1.525 m gauge.
+ */
+declare function railCant(speed: number, radius: number, gauge: number, g?: number, sf?: number): {
+  height: number;
+  degrees: number;
+  worked: Worked;
+};
+/**
+ * The fastest a vehicle can take a BANKED bend that also has friction.
+ *
+ * Both help: the bank leans the normal force inward and friction adds to it. The denominator is
+ * what makes this interesting, because `cos θ − μ sin θ` goes to zero at `μ = cot θ` and the
+ * predicted speed goes to infinity. That is not a bug in the algebra, it is the statement that a
+ * bend banked steeply enough, with grippy enough tyres, cannot be slid out of at any speed. Real
+ * tracks do not go that far, and the function says so rather than returning Infinity quietly.
+ */
+declare function maxSpeedBanked(radius: number, angleDeg: number, mu: number, g?: number, sf?: number): {
+  speed: number;
+  worked: Worked;
+};
+/**
+ * The tension in a string whirling a mass in a VERTICAL circle, at any angle from the top.
+ *
+ * `T = mv²/r − mg cos φ` measuring `φ` from the top, so the string is slackest at the top and
+ * tightest at the bottom, with the difference `2mg`. Gravity helps provide the centripetal force at
+ * the top and fights it at the bottom, and that single sentence is the whole of the topic.
+ */
+declare function verticalCircleTension(mass: number, speed: number, radius: number, angleFromTopDeg: number, g?: number): number;
+/**
+ * The slowest a mass can go round a vertical circle without the string going slack at the top.
+ *
+ * At the critical speed the string carries nothing and gravity alone supplies the whole centripetal
+ * requirement: `mg = mv²/r`, so `v = √(gr)`. Below it the string cannot push, so the mass leaves
+ * the circular path, which is why a bucket of water must be swung fast enough and not merely swung.
+ */
+declare function minimumSpeedAtTop(radius: number, g?: number, sf?: number): {
+  speed: number;
+  worked: Worked;
+};
+//#endregion
+export { bankingAngle, centripetalAcceleration, centripetalForce, centripetalFromOmega, maxSpeedBanked, maxSpeedFlat, minimumSpeedAtTop, railCant, verticalCircleTension };

package/dist/physics/rotation/circular.mjs

@@ -0,0 +1,131 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { toDegrees, toRadians } from "../vectors.mjs";
+import { G_EARTH } from "../kinematics/free-fall.mjs";
+
+//#region src/physics/rotation/circular.ts
+/**
+* Going round in a circle: what holds you in, and how fast you can take the bend.
+*
+* ONE CORRECTION FIRST, because it is the misconception the whole topic trips on. There is no
+* outward force. A body moving in a circle is ACCELERATING, towards the centre, and something real
+* has to supply that: friction on tyres, tension in a string, gravity on a satellite. The outward
+* push a passenger feels is their own inertia continuing in a straight line while the car turns
+* under them. "Centrifugal force" names that feeling, not a force, and a diagram that draws it
+* alongside the real forces has two arrows where physics has one.
+*
+* So `F = mv²/r` is never an extra force to add. It is what the forces you already have must SUM
+* TO. Every question in the topic is that one sentence: find the real forces, resolve them towards
+* the centre, set the total equal to `mv²/r`.
+*
+* Pure: no React, no pixels.
+*/
+/** `a = v²/r = ω²r`, directed at the centre. */
+const centripetalAcceleration = (speed, radius) => {
+	if (radius <= 0) throw new Error("The radius must be positive.");
+	return speed * speed / radius;
+};
+/** `F = mv²/r`: not an extra force, but what the real ones have to add up to. */
+function centripetalForce(mass, speed, radius, sf = 3) {
+	const acceleration = centripetalAcceleration(speed, radius);
+	const value = mass * acceleration;
+	return {
+		value,
+		acceleration,
+		worked: calc().step("\\sum F_{\\text{towards centre}} = \\frac{mv^2}{r}", "the REQUIREMENT, not an extra arrow. Something real has to supply it").step(`\\frac{mv^2}{r} = \\frac{${texSigFigs(mass, sf)} \\times ${texSigFigs(speed, sf)}^2}{${texSigFigs(radius, sf)}} = ${texSigFigs(value, sf)}\\ \\mathrm{N}`).done(value)
+	};
+}
+/** The same thing from a spin rate: `F = mω²r`, which is what a whirled string question gives. */
+const centripetalFromOmega = (mass, omega, radius) => mass * omega * omega * radius;
+/**
+* The fastest a vehicle can take a FLAT bend before it slides.
+*
+* Friction is the only thing pointing at the centre, so `μmg ≥ mv²/r` and the mass cancels: a
+* loaded lorry and an empty one slide at the same speed, which is not what anyone expects.
+*/
+function maxSpeedFlat(radius, mu, g = G_EARTH, sf = 3) {
+	if (radius <= 0 || mu < 0) throw new Error("Radius must be positive and friction cannot be negative.");
+	const speed = Math.sqrt(mu * radius * g);
+	return {
+		speed,
+		worked: calc().step("\\mu m g \\geq \\frac{mv^2}{r}", "friction is the only force pointing at the centre").step("v \\leq \\sqrt{\\mu r g}", "the mass cancels: how heavily loaded it is makes no difference").step(`v_{\\max} = ${texSigFigs(speed, sf)}\\ \\mathrm{m\\,s^{-1}}`).done(speed)
+	};
+}
+/**
+* The angle a bend should be banked to, so that no friction is needed at all: `tan θ = v²/rg`.
+*
+* At this angle the track's normal force alone leans inward enough to turn the vehicle, and the
+* tyres do no sideways work. It is the design speed of the bend, and again the mass cancels, so one
+* bank angle serves a bicycle and a lorry.
+*/
+function bankingAngle(speed, radius, g = G_EARTH, sf = 3) {
+	if (radius <= 0) throw new Error("The radius must be positive.");
+	const ratio = speed * speed / (radius * g);
+	const degrees = toDegrees(Math.atan(ratio));
+	return {
+		degrees,
+		worked: calc().step("N\\sin\\theta = \\frac{mv^2}{r}, \\quad N\\cos\\theta = mg", "the track pushes perpendicular to itself; tilt it and part of that push aims at the centre").step("\\tan\\theta = \\frac{v^2}{rg}", "dividing kills both N and m, so one angle suits every vehicle").step(`\\theta = \\arctan ${texSigFigs(ratio, sf)} = ${texSigFigs(degrees, sf)}^\\circ`, "at this speed the tyres need no sideways grip at all").done(degrees)
+	};
+}
+/**
+* How much higher the outer rail must sit, given the gauge.
+*
+* The railway form of the same question: the bank angle is set by raising one rail, so
+* `h = gauge · sin θ`. Their worked example is a 98 m bend at 9.8 m/s on a 1.525 m gauge.
+*/
+function railCant(speed, radius, gauge, g = G_EARTH, sf = 3) {
+	const { degrees } = bankingAngle(speed, radius, g);
+	const height = gauge * Math.sin(toRadians(degrees));
+	return {
+		height,
+		degrees,
+		worked: calc().step("\\tan\\theta = \\frac{v^2}{rg}", "the bank angle the bend needs").step(`\\theta = ${texSigFigs(degrees, sf)}^\\circ`).step(`h = L\\sin\\theta = ${texSigFigs(gauge, sf)}\\sin ${texSigFigs(degrees, sf)}^\\circ = ${texSigFigs(height, sf)}\\ \\mathrm{m}`, "raise the outer rail by this and the train leans into the bend on its own").done(height)
+	};
+}
+/**
+* The fastest a vehicle can take a BANKED bend that also has friction.
+*
+* Both help: the bank leans the normal force inward and friction adds to it. The denominator is
+* what makes this interesting, because `cos θ − μ sin θ` goes to zero at `μ = cot θ` and the
+* predicted speed goes to infinity. That is not a bug in the algebra, it is the statement that a
+* bend banked steeply enough, with grippy enough tyres, cannot be slid out of at any speed. Real
+* tracks do not go that far, and the function says so rather than returning Infinity quietly.
+*/
+function maxSpeedBanked(radius, angleDeg, mu, g = G_EARTH, sf = 3) {
+	if (radius <= 0) throw new Error("The radius must be positive.");
+	const theta = toRadians(angleDeg);
+	const denominator = Math.cos(theta) - mu * Math.sin(theta);
+	if (denominator <= 1e-9) throw new Error(`With a bank of ${angleDeg}° and μ = ${mu}, cos θ − μ sin θ is zero or negative, so this model predicts no upper speed limit at all: the bank and the grip together can hold any speed. That is the algebra being honest about an extreme case, not a defect.`);
+	const speed = Math.sqrt(radius * g * (Math.sin(theta) + mu * Math.cos(theta)) / denominator);
+	return {
+		speed,
+		worked: calc().step("v \\leq \\sqrt{\\frac{rg(\\sin\\theta + \\mu\\cos\\theta)}{\\cos\\theta - \\mu\\sin\\theta}}", "the bank and the friction both help, so the two effects appear together").step(`v_{\\max} = ${texSigFigs(speed, sf)}\\ \\mathrm{m\\,s^{-1}}`).done(speed)
+	};
+}
+/**
+* The tension in a string whirling a mass in a VERTICAL circle, at any angle from the top.
+*
+* `T = mv²/r − mg cos φ` measuring `φ` from the top, so the string is slackest at the top and
+* tightest at the bottom, with the difference `2mg`. Gravity helps provide the centripetal force at
+* the top and fights it at the bottom, and that single sentence is the whole of the topic.
+*/
+function verticalCircleTension(mass, speed, radius, angleFromTopDeg, g = G_EARTH) {
+	return mass * centripetalAcceleration(speed, radius) - mass * g * Math.cos(toRadians(angleFromTopDeg));
+}
+/**
+* The slowest a mass can go round a vertical circle without the string going slack at the top.
+*
+* At the critical speed the string carries nothing and gravity alone supplies the whole centripetal
+* requirement: `mg = mv²/r`, so `v = √(gr)`. Below it the string cannot push, so the mass leaves
+* the circular path, which is why a bucket of water must be swung fast enough and not merely swung.
+*/
+function minimumSpeedAtTop(radius, g = G_EARTH, sf = 3) {
+	if (radius <= 0) throw new Error("The radius must be positive.");
+	const speed = Math.sqrt(g * radius);
+	return {
+		speed,
+		worked: calc().step("T + mg = \\frac{mv^2}{r}", "at the top, gravity points the same way as the centripetal requirement").step("T = 0 \\;\\Rightarrow\\; mg = \\frac{mv^2}{r}", "the critical case is the string carrying nothing at all").step(`v_{\\min} = \\sqrt{gr} = ${texSigFigs(speed, sf)}\\ \\mathrm{m\\,s^{-1}}`, "any slower and the string would have to PUSH, which a string cannot do, so the mass falls inward").done(speed)
+	};
+}
+
+//#endregion
+export { bankingAngle, centripetalAcceleration, centripetalForce, centripetalFromOmega, maxSpeedBanked, maxSpeedFlat, minimumSpeedAtTop, railCant, verticalCircleTension };