@classytic/stage 0.3.0 → 0.4.0

package/dist/physics/gravitation/orbit.d.mts

@@ -0,0 +1,119 @@
+import { Worked } from "../../core/worked.mjs";
+import { CentralBody } from "./body.mjs";
+
+//#region src/physics/gravitation/orbit.d.ts
+/** Speed of a circular orbit of a given radius: `v = √(mu/r)`. Radius from the CENTRE, not the surface. */
+declare const orbitalSpeed: (mu: number, radius: number) => number;
+/** Period of a circular orbit: `T = 2π√(r³/mu)`. */
+declare const orbitalPeriod: (mu: number, radius: number) => number;
+/** The radius whose circular orbit has a given period: `r = (mu·T²/4π²)^{1/3}`. */
+declare const orbitRadiusForPeriod: (mu: number, period: number) => number;
+/**
+ * The orbital speed derivation, with the centripetal step shown rather than assumed.
+ *
+ * Calls `centripetalAcceleration` to compute the requirement that gravity is being asked to meet, so
+ * the returned working can state both sides as numbers and show them matching. That is not
+ * decoration: "gravity supplies the centripetal force" is a sentence students repeat without ever
+ * having seen the two quantities agree.
+ */
+declare function orbitalSpeedSteps(body: CentralBody, radius: number, sf?: number): Worked;
+/**
+ * The geostationary orbit of a rotating body: the one radius whose period matches the body's day.
+ *
+ * Three conditions define it and questions penalise forgetting the last two: the period must match
+ * the SIDEREAL day, the orbit must be EQUATORIAL, and it must go the same way round as the rotation.
+ * A 24-hour orbit tilted 30° is geoSYNCHRONOUS, not geostationary, and traces a figure of eight in
+ * the sky rather than hanging still.
+ *
+ * Uses the sidereal period from the body, which for Earth is 86164 s rather than 86400. Using the
+ * solar day instead puts the orbit about 80 km too high, and four minutes a day is not a rounding
+ * error when a dish is pointed at it.
+ */
+declare function geostationaryOrbit(body: CentralBody, sf?: number): {
+  radius: number;
+  height: number;
+  speed: number;
+  worked: Worked;
+};
+interface OrbitalEnergy {
+  readonly kinetic: number;
+  readonly potential: number;
+  readonly total: number;
+  /** Energy needed to escape from this orbit, which is exactly `−total`. */
+  readonly bindingEnergy: number;
+}
+/**
+ * The three energy stores of a circular orbit, in joules.
+ *
+ * The relations `E = −E_k` and `E_p = 2E` fall straight out and are the most useful shortcut in the
+ * topic: given any one of the three you have the other two without touching a formula. The binding
+ * energy is returned alongside because "how much more energy to escape from here?" is the standard
+ * follow-up, and the answer is just the total with its sign flipped.
+ */
+declare function orbitalEnergy(mu: number, mass: number, radius: number): OrbitalEnergy;
+/**
+ * The same, worked, ending on the paradox.
+ *
+ * The last two steps are the point of the function. A satellite moved to a higher orbit has MORE
+ * total energy and LESS kinetic energy, so it is moving more slowly despite the engine having fired.
+ * Stating that as a consequence of `E = −E_k` turns it from a piece of space-flight trivia into an
+ * unavoidable arithmetic fact, which is the difference between a student remembering it and not.
+ */
+declare function orbitalEnergySteps(mu: number, mass: number, radius: number, sf?: number): Worked;
+/**
+ * The vis-viva equation: `v² = mu(2/r − 1/a)`.
+ *
+ * THE MOST POWERFUL SINGLE EQUATION IN ORBITAL MECHANICS, and it contains almost everything above as
+ * special cases. Put `a = r` and it gives the circular speed. Let `a → ∞` and it gives escape speed.
+ * Anything elliptical is the general case. A learner who meets it after the special cases sees six
+ * formulas collapse into one, which is the moment the topic stops being a list.
+ *
+ * `a` is the semi-major axis, and for a hyperbolic path it is negative, which the formula handles
+ * without a special case.
+ */
+declare function visViva(mu: number, radius: number, semiMajorAxis: number): number;
+/** The shape a launch at a given speed produces. */
+type TrajectoryKind = 'sub-orbital' | 'circular' | 'elliptical' | 'parabolic' | 'hyperbolic';
+/**
+ * What happens to something launched HORIZONTALLY at a given speed from a given radius.
+ *
+ * The ladder every textbook prints as five separate cases, computed from one comparison. Below the
+ * circular speed the ellipse it enters has its far side inside the planet, so it comes down;
+ * exactly at it, a circle; between that and escape, an ellipse rising on the far side; exactly at
+ * escape, a parabola; above, a hyperbola that never returns.
+ *
+ * The tolerance matters: floating point will never hand you exactly the circular speed, so "circular"
+ * has to mean "within a whisker", and a lab that tests for equality will report an ellipse forever.
+ */
+declare function trajectoryKind(mu: number, radius: number, speed: number, tolerance?: number): TrajectoryKind;
+/**
+ * A Hohmann transfer between two circular orbits: the cheapest two-burn route, and the reason
+ * launch windows exist.
+ *
+ * Two burns, at opposite ends of an ellipse that just touches both circles. Returns each burn's
+ * `Δv` and the transfer time, which is half the ellipse's period. Beyond most school syllabuses and
+ * included because it is the first question a curious student asks after "what is an orbit", and
+ * because it is where the raise-your-orbit-and-slow-down paradox becomes operational: both burns
+ * are prograde, both add energy, and you arrive moving more slowly than you set off.
+ */
+declare function hohmannTransfer(mu: number, fromRadius: number, toRadius: number): {
+  burn1: number;
+  burn2: number;
+  totalDeltaV: number;
+  transferTimeS: number;
+  semiMajorAxis: number;
+};
+/**
+ * The speed of a satellite skimming the surface, and the period it would have.
+ *
+ * `v = √(gR)`, about 7.9 km/s for the Earth, and 84 minutes to go round. Worth its own function
+ * because it is the natural unit of the whole topic: every real orbit is slower than this and every
+ * escape is `√2` faster, so a learner with this one number in their head can sanity-check anything.
+ * It is also the same 84 minutes as `spinPeriodForWeightlessness`, for the same reason.
+ */
+declare function surfaceSkimmingOrbit(body: CentralBody): {
+  speed: number;
+  periodS: number;
+};
+//#endregion
+export { OrbitalEnergy, TrajectoryKind, geostationaryOrbit, hohmannTransfer, orbitRadiusForPeriod, orbitalEnergy, orbitalEnergySteps, orbitalPeriod, orbitalSpeed, orbitalSpeedSteps, surfaceSkimmingOrbit, trajectoryKind, visViva };

package/dist/physics/gravitation/orbit.mjs

@@ -0,0 +1,202 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { centripetalAcceleration } from "../rotation/circular.mjs";
+import { surfaceGravity } from "./body.mjs";
+import { escapeSpeed, gravitationalPotentialEnergy } from "./potential.mjs";
+
+//#region src/physics/gravitation/orbit.ts
+/**
+* Circular orbits, orbital energy, and the transfer between two orbits.
+*
+* ── An orbit is not a new topic ─────────────────────────────────────────────────────────────────
+* The entire derivation is one substitution: gravity SUPPLIES the centripetal requirement.
+*
+*     GMm/r² = mv²/r      →      v = √(GM/r)
+*
+* That is it. The centripetal side is `rotation/circular.ts`'s and is imported rather than rewritten,
+* because the point of having taught circular motion is that this is then not a new skill, it is the
+* old skill with a particular force named. A learner who cannot see the substitution is memorising
+* `√(GM/r)` as a twenty-first formula.
+*
+* Note what cancels: the satellite's mass, on both sides. An orbit does not care what is in it,
+* which is why a space station and a bolt that fell off it stay side by side.
+*
+* ── The fact that makes orbits strange, and it is worth the shock ───────────────────────────────
+* Higher orbits are SLOWER. `v = √(GM/r)` falls as `r` grows, so the Moon dawdles at 1 km/s while
+* the Space Station races at 7.7 km/s. Every instinct says the opposite, because on Earth going
+* further up costs effort and arriving faster feels like the reward.
+*
+* It gets worse, and this is the genuine paradox of the chapter. Firing your engine FORWARDS raises
+* your orbit and leaves you moving SLOWER than before. Firing backwards drops you and you speed up.
+* A spacecraft chasing another in the same orbit must therefore slow down to catch up. The energy
+* accounting below is what resolves it: thrusting adds total energy, the potential store takes more
+* than all of it, and the kinetic store pays the difference.
+*
+* ── The energy relations, which are three facts in one line ─────────────────────────────────────
+*     E_k = +GMm/2r        E_p = −GMm/r        E = E_k + E_p = −GMm/2r
+*
+* So `E = −E_k` and `E_p = 2E`. The total is NEGATIVE, and that negativity is the definition of
+* being bound: an orbit is a debt you cannot pay off. Zero total energy is exactly escape, which is
+* why escape speed is `√2` times orbital speed and not something that needs separate memorising.
+*
+* Pure: no React, no pixels.
+*/
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive and finite`);
+	return value;
+};
+/** Speed of a circular orbit of a given radius: `v = √(mu/r)`. Radius from the CENTRE, not the surface. */
+const orbitalSpeed = (mu, radius) => Math.sqrt(positive(mu, "gravitational parameter") / positive(radius, "radius"));
+/** Period of a circular orbit: `T = 2π√(r³/mu)`. */
+const orbitalPeriod = (mu, radius) => 2 * Math.PI * Math.sqrt(positive(radius, "radius") ** 3 / positive(mu, "gravitational parameter"));
+/** The radius whose circular orbit has a given period: `r = (mu·T²/4π²)^{1/3}`. */
+const orbitRadiusForPeriod = (mu, period) => Math.cbrt(positive(mu, "gravitational parameter") * positive(period, "period") ** 2 / (4 * Math.PI ** 2));
+/**
+* The orbital speed derivation, with the centripetal step shown rather than assumed.
+*
+* Calls `centripetalAcceleration` to compute the requirement that gravity is being asked to meet, so
+* the returned working can state both sides as numbers and show them matching. That is not
+* decoration: "gravity supplies the centripetal force" is a sentence students repeat without ever
+* having seen the two quantities agree.
+*/
+function orbitalSpeedSteps(body, radius, sf = 3) {
+	const r = positive(radius, "radius");
+	const value = orbitalSpeed(body.mu, r);
+	const required = centripetalAcceleration(value, r);
+	return calc().step("\\frac{GMm}{r^2} = \\frac{mv^2}{r}", "gravity is not an extra force here, it IS the centripetal force. Nothing else is acting").step("v = \\sqrt{\\frac{GM}{r}}", "the satellite mass m cancels: an orbit does not care what is in it").step(`v = \\sqrt{\\frac{${texSigFigs(body.mu, sf)}}{${texSigFigs(r, sf)}}} = ${texSigFigs(value, sf)}\\ \\mathrm{m\\,s^{-1}}`).step(`a_c = \\frac{v^2}{r} = ${texSigFigs(required, sf)}\\ \\mathrm{m\\,s^{-2}}`, "and the field strength at that radius is the same number, which is what \"supplies\" means").step("v \\propto \\frac{1}{\\sqrt{r}}", "so HIGHER orbits are SLOWER. The Moon crawls at 1 km/s while the Space Station does 7.7").done(value);
+}
+/**
+* The geostationary orbit of a rotating body: the one radius whose period matches the body's day.
+*
+* Three conditions define it and questions penalise forgetting the last two: the period must match
+* the SIDEREAL day, the orbit must be EQUATORIAL, and it must go the same way round as the rotation.
+* A 24-hour orbit tilted 30° is geoSYNCHRONOUS, not geostationary, and traces a figure of eight in
+* the sky rather than hanging still.
+*
+* Uses the sidereal period from the body, which for Earth is 86164 s rather than 86400. Using the
+* solar day instead puts the orbit about 80 km too high, and four minutes a day is not a rounding
+* error when a dish is pointed at it.
+*/
+function geostationaryOrbit(body, sf = 4) {
+	if (body.rotationPeriodS === void 0) throw new RangeError(`${body.name} has no rotation period, so no synchronous orbit is defined`);
+	const T = body.rotationPeriodS;
+	const radius = orbitRadiusForPeriod(body.mu, T);
+	const worked = calc().step("\\frac{GMm}{r^2} = m\\omega^2 r,\\quad \\omega = \\frac{2\\pi}{T}", "the orbit must keep step with the ground below it").step("r^3 = \\frac{GMT^2}{4\\pi^2}", "which is Kepler III with the period chosen rather than measured").step(`r = \\sqrt[3]{\\frac{${texSigFigs(body.mu, sf)} \\times (${texSigFigs(T, sf)})^2}{4\\pi^2}} = ${texSigFigs(radius, sf)}\\ \\mathrm{m}`, `T is the SIDEREAL day, ${texSigFigs(T, 6)} s, not 86400`).step(`h = r - R = ${texSigFigs(radius - body.radius, sf)}\\ \\mathrm{m}`, "the question almost always wants the HEIGHT, and the equation gives the radius").done(radius);
+	return {
+		radius,
+		height: radius - body.radius,
+		speed: orbitalSpeed(body.mu, radius),
+		worked
+	};
+}
+/**
+* The three energy stores of a circular orbit, in joules.
+*
+* The relations `E = −E_k` and `E_p = 2E` fall straight out and are the most useful shortcut in the
+* topic: given any one of the three you have the other two without touching a formula. The binding
+* energy is returned alongside because "how much more energy to escape from here?" is the standard
+* follow-up, and the answer is just the total with its sign flipped.
+*/
+function orbitalEnergy(mu, mass, radius) {
+	const r = positive(radius, "radius");
+	const m = positive(mass, "mass");
+	const kinetic = mu * m / (2 * r);
+	const potential = gravitationalPotentialEnergy(mu, m, r);
+	const total = kinetic + potential;
+	return {
+		kinetic,
+		potential,
+		total,
+		bindingEnergy: -total
+	};
+}
+/**
+* The same, worked, ending on the paradox.
+*
+* The last two steps are the point of the function. A satellite moved to a higher orbit has MORE
+* total energy and LESS kinetic energy, so it is moving more slowly despite the engine having fired.
+* Stating that as a consequence of `E = −E_k` turns it from a piece of space-flight trivia into an
+* unavoidable arithmetic fact, which is the difference between a student remembering it and not.
+*/
+function orbitalEnergySteps(mu, mass, radius, sf = 3) {
+	const e = orbitalEnergy(mu, mass, radius);
+	return calc().step("E_k = \\tfrac{1}{2}mv^2 = \\tfrac{1}{2}m\\cdot\\frac{GM}{r} = \\frac{GMm}{2r}", "using the orbital speed").step("E_p = -\\frac{GMm}{r}", "measured from infinity, so negative").step(`E = E_k + E_p = -\\frac{GMm}{2r} = ${texSigFigs(e.total, sf)}\\ \\mathrm{J}`, "NEGATIVE, and that is what \"bound\" means: you cannot leave without being given energy").step("E = -E_k, \\qquad E_p = 2E", "so any one of the three gives you the other two. Worth more than it looks in an exam").step(`\\text{to escape: } ${texSigFigs(e.bindingEnergy, sf)}\\ \\mathrm{J}`, "exactly the total energy with its sign flipped, since escape means reaching zero").step("r \\uparrow \\Rightarrow E \\uparrow \\text{ but } E_k \\downarrow", "raising an orbit costs energy and leaves the satellite moving SLOWER. To catch something ahead of you, slow down").done(e.total);
+}
+/**
+* The vis-viva equation: `v² = mu(2/r − 1/a)`.
+*
+* THE MOST POWERFUL SINGLE EQUATION IN ORBITAL MECHANICS, and it contains almost everything above as
+* special cases. Put `a = r` and it gives the circular speed. Let `a → ∞` and it gives escape speed.
+* Anything elliptical is the general case. A learner who meets it after the special cases sees six
+* formulas collapse into one, which is the moment the topic stops being a list.
+*
+* `a` is the semi-major axis, and for a hyperbolic path it is negative, which the formula handles
+* without a special case.
+*/
+function visViva(mu, radius, semiMajorAxis) {
+	const r = positive(radius, "radius");
+	const speedSquared = positive(mu, "gravitational parameter") * (2 / r - 1 / semiMajorAxis);
+	if (speedSquared < 0) throw new RangeError("that radius lies outside the orbit described");
+	return Math.sqrt(speedSquared);
+}
+/**
+* What happens to something launched HORIZONTALLY at a given speed from a given radius.
+*
+* The ladder every textbook prints as five separate cases, computed from one comparison. Below the
+* circular speed the ellipse it enters has its far side inside the planet, so it comes down;
+* exactly at it, a circle; between that and escape, an ellipse rising on the far side; exactly at
+* escape, a parabola; above, a hyperbola that never returns.
+*
+* The tolerance matters: floating point will never hand you exactly the circular speed, so "circular"
+* has to mean "within a whisker", and a lab that tests for equality will report an ellipse forever.
+*/
+function trajectoryKind(mu, radius, speed, tolerance = 1e-9) {
+	const r = positive(radius, "radius");
+	const circular = orbitalSpeed(mu, r);
+	const escape = escapeSpeed(mu, r);
+	if (Math.abs(speed - circular) <= tolerance * circular) return "circular";
+	if (Math.abs(speed - escape) <= tolerance * escape) return "parabolic";
+	if (speed > escape) return "hyperbolic";
+	if (speed < circular) return 2 * (1 / (2 / r - speed * speed / mu)) - r < r ? "sub-orbital" : "elliptical";
+	return "elliptical";
+}
+/**
+* A Hohmann transfer between two circular orbits: the cheapest two-burn route, and the reason
+* launch windows exist.
+*
+* Two burns, at opposite ends of an ellipse that just touches both circles. Returns each burn's
+* `Δv` and the transfer time, which is half the ellipse's period. Beyond most school syllabuses and
+* included because it is the first question a curious student asks after "what is an orbit", and
+* because it is where the raise-your-orbit-and-slow-down paradox becomes operational: both burns
+* are prograde, both add energy, and you arrive moving more slowly than you set off.
+*/
+function hohmannTransfer(mu, fromRadius, toRadius) {
+	const r1 = positive(fromRadius, "radius");
+	const r2 = positive(toRadius, "radius");
+	const a = (r1 + r2) / 2;
+	const burn1 = Math.abs(visViva(mu, r1, a) - orbitalSpeed(mu, r1));
+	const burn2 = Math.abs(orbitalSpeed(mu, r2) - visViva(mu, r2, a));
+	return {
+		burn1,
+		burn2,
+		totalDeltaV: burn1 + burn2,
+		transferTimeS: Math.PI * Math.sqrt(a ** 3 / mu),
+		semiMajorAxis: a
+	};
+}
+/**
+* The speed of a satellite skimming the surface, and the period it would have.
+*
+* `v = √(gR)`, about 7.9 km/s for the Earth, and 84 minutes to go round. Worth its own function
+* because it is the natural unit of the whole topic: every real orbit is slower than this and every
+* escape is `√2` faster, so a learner with this one number in their head can sanity-check anything.
+* It is also the same 84 minutes as `spinPeriodForWeightlessness`, for the same reason.
+*/
+function surfaceSkimmingOrbit(body) {
+	return {
+		speed: Math.sqrt(surfaceGravity(body) * body.radius),
+		periodS: orbitalPeriod(body.mu, body.radius)
+	};
+}
+
+//#endregion
+export { geostationaryOrbit, hohmannTransfer, orbitRadiusForPeriod, orbitalEnergy, orbitalEnergySteps, orbitalPeriod, orbitalSpeed, orbitalSpeedSteps, surfaceSkimmingOrbit, trajectoryKind, visViva };

package/dist/physics/gravitation/potential.d.mts

@@ -0,0 +1,114 @@
+import { Worked } from "../../core/worked.mjs";
+import { CentralBody } from "./body.mjs";
+
+//#region src/physics/gravitation/potential.d.ts
+/**
+ * Gravitational field strength at a distance from a point or spherical mass: `E = mu/r²`.
+ *
+ * Numerically identical to the free-fall acceleration there, and that identity is worth naming
+ * rather than leaving implicit: N/kg and m/s² are the same unit, and the two names exist because the
+ * quantity answers two different questions. Returned as a positive magnitude; the direction is
+ * always towards the mass, which is the one thing gravity never varies.
+ */
+declare const gravitationalFieldStrength: (mu: number, distance: number) => number;
+/**
+ * Gravitational potential at a distance: `V = −mu/r`, in J/kg.
+ *
+ * NEGATIVE, and increasing towards zero as you move away. Per kilogram, so it is a property of the
+ * PLACE and not of whatever you put there, which is what makes it worth defining at all.
+ */
+declare const gravitationalPotential: (mu: number, distance: number) => number;
+/**
+ * The potential energy of a mass at a distance: `U = −mu·m/r`, in joules.
+ *
+ * Distinct from `gravitationalPE` in `energy/store.ts`, and the pair is worth holding side by side:
+ * that one is `mgh` measured from a level you chose and can be positive or negative, this one is
+ * measured from infinity and is always negative. They are the same quantity under different
+ * conventions, and `gravitationalWork` in that file shows one collapsing into the other.
+ */
+declare const gravitationalPotentialEnergy: (mu: number, mass: number, distance: number) => number;
+/**
+ * The potential difference between two radii, and the work per kilogram it represents.
+ *
+ * `ΔV = V_b − V_a = mu(1/r_a − 1/r_b)`. Positive when moving outwards, because you are paying off
+ * debt. The sign discipline here is the whole of the topic's marking: a question asking for "the
+ * work done in moving a mass from A to B" wants `m·ΔV`, and the commonest error is taking the
+ * difference the wrong way round and reporting a rescue mission as an energy source.
+ */
+declare function potentialDifference(mu: number, fromRadius: number, toRadius: number, sf?: number): Worked;
+/** Where a point sits relative to a body, which is what decides which formula applies. */
+type ShellRegion = 'inside' | 'surface' | 'outside';
+/**
+ * Field and potential of a thin HOLLOW SHELL, in every region.
+ *
+ * The full statement of the theorem as a single function, because the discontinuity is the lesson:
+ * the field jumps from zero to its full surface value as you cross the wall, while the potential
+ * passes through smoothly. A graph of the two, drawn together, is the single most useful picture in
+ * the topic and a lab can draw it straight from this.
+ */
+declare function shellFieldAndPotential(shellMass: number, shellRadius: number, distance: number, G?: number): {
+  field: number;
+  potential: number;
+  region: ShellRegion;
+};
+/**
+ * Field and potential of a SOLID sphere of uniform density, in every region.
+ *
+ * Outside, it is a point mass. Inside, only the sphere beneath you counts, which gives a field
+ * rising LINEARLY from zero at the centre, and a potential following
+ *
+ *     V = −GM(3R² − r²) / 2R³
+ *
+ * which at the centre is `−3GM/2R`, one and a half times the surface value. That factor of 3/2 is a
+ * favourite exam number and it comes from integrating the shells, not from anywhere mysterious.
+ */
+declare function sphereFieldAndPotential(mass: number, radius: number, distance: number, G?: number): {
+  field: number;
+  potential: number;
+  region: ShellRegion;
+};
+/**
+ * The gravitational self-energy of a uniform sphere: `U = −3GM²/5R`.
+ *
+ * The energy released in assembling the body shell by shell from infinite dispersion, and equally
+ * the energy needed to disperse it again. Beyond most syllabuses, but it is where a star's heat
+ * comes from before fusion starts, so it is the bridge from this chapter to astrophysics, and the
+ * 3/5 is the same integral as the 3/2 above.
+ */
+declare const sphereSelfEnergy: (mass: number, radius: number, G?: number) => number;
+/**
+ * Escape speed from a distance: `v = √(2·mu/r)`.
+ *
+ * DOES NOT DEPEND ON THE ESCAPING MASS, which is the fact worth stopping on: a pebble and a
+ * battleship need the same 11.2 km/s. The mass cancels because both the energy you must supply and
+ * the energy you have scale with it, and that cancellation is the same one that makes everything
+ * fall at the same rate.
+ *
+ * Nor does it depend on DIRECTION, as long as you miss the ground: escape is an energy condition,
+ * not a trajectory. Sideways at 11.2 km/s escapes exactly as well as straight up, which is the
+ * detail that makes it clear this is a potential-energy argument and not a ballistics one.
+ */
+declare const escapeSpeed: (mu: number, distance: number) => number;
+/**
+ * Escape speed from a body's surface, worked, in all three of the forms a syllabus prints.
+ *
+ * `√(2GM/R)`, `√(2gR)` and `R√(8πGρ/3)` are the same number reached from whichever pair of
+ * quantities a question supplies, and a student who knows only the first stalls when handed a
+ * density. The working shows them as one expression rewritten, not as three formulas to memorise.
+ *
+ * The final step gives the ratio to circular orbital speed, which is exactly `√2` at every radius
+ * around every body: escaping costs twice the KINETIC ENERGY of circling, never twice the speed.
+ */
+declare function escapeSpeedSteps(body: CentralBody, sf?: number): Worked;
+/**
+ * How high a body thrown up at a given speed reaches, when `g` cannot be treated as constant.
+ *
+ * `h = R / (v_e²/v² − 1)`, from energy conservation with the true `1/r` potential. The reason it
+ * exists is that `v²/2g` is wrong for anything fast: at 5 km/s the constant-`g` answer is about
+ * 1274 km and the true answer is about 1600 km, a 25% error, and the gap widens without limit as
+ * the speed approaches escape. Throws if the speed reaches escape speed, because then there is no
+ * highest point.
+ */
+declare function riseHeight(body: CentralBody, launchSpeed: number, sf?: number): Worked;
+//#endregion
+export { ShellRegion, escapeSpeed, escapeSpeedSteps, gravitationalFieldStrength, gravitationalPotential, gravitationalPotentialEnergy, potentialDifference, riseHeight, shellFieldAndPotential, sphereFieldAndPotential, sphereSelfEnergy };

package/dist/physics/gravitation/potential.mjs

@@ -0,0 +1,202 @@
+import { GRAVITATIONAL_CONSTANT } from "../../core/constants.mjs";
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { surfaceGravity } from "./body.mjs";
+
+//#region src/physics/gravitation/potential.ts
+/**
+* Field, potential, the shell theorem, and escape speed.
+*
+* ── The hardest idea in the chapter, and it is a sign ───────────────────────────────────────────
+* Gravitational potential is NEGATIVE EVERYWHERE, and students treat that as a quirk of notation to
+* be memorised. It is not notation, it is the physics, and it says something a learner can feel:
+* the zero of potential is at INFINITY, because that is the only place in the universe that is
+* special. Every other point is somewhere you had to fall into, so getting back out costs energy,
+* so you are in debt. `V = −GM/r` is a statement about a debt, and it gets deeper as you approach.
+*
+* This is also the answer to the question that stalls everyone: why does `mgh` have no minus sign
+* and this does? Because `mgh` measures from a level YOU chose, near which the debt is roughly
+* constant, and only the CHANGE was ever physical. `energy/store.ts` makes that point on the near
+* side; this file makes it on the far side. They are one idea, and `gravitationalWork` there is the
+* bridge: `W = GMm(1/r_a − 1/r_b)` collapses to `mgh` when the two radii barely differ.
+*
+* ── Why field and potential are not the same thing, said once ───────────────────────────────────
+* Field is a VECTOR and goes as `1/r²`; potential is a SCALAR and goes as `1/r`. They are related by
+* `E = −dV/dr`, which is the only relation in the chapter worth being able to state in words: the
+* field is the STEEPNESS of the potential. A flat potential means no force, which is exactly what
+* happens inside a hollow shell, and that is not a coincidence, it is the same fact twice.
+*
+* When several bodies act, the potentials ADD AS NUMBERS and the fields add as ARROWS. That makes
+* potential the easier of the two to compute and is the reason energy methods beat force methods on
+* any question with more than one source.
+*
+* ── The shell theorem, which everything else has been quietly assuming ──────────────────────────
+* Every formula in this kernel treats a planet as a point at its centre. That is licensed by
+* Newton's shell theorem, and the theorem has TWO halves, of which the second is the surprising one:
+*
+*   1. Outside a uniform shell, it pulls exactly as if all its mass were at the centre.
+*   2. Inside it, the field is EXACTLY ZERO everywhere, not merely small and not merely at the centre.
+*
+* The second half is why `g` falls linearly to zero as you descend (`variation.ts`): the shell above
+* you stops counting entirely. The intuition is that a nearby patch of shell pulls harder but
+* subtends a smaller solid angle, and the `1/r²` in the force cancels the `r²` in the area exactly.
+* Inverse-square is the only power for which that happens, which is why this is a test of the law
+* and not just a consequence of it.
+*
+* Note the potential inside the shell is NOT zero: it is constant, at its surface value. Zero field
+* means flat potential, not absent potential. Students confuse these two constantly, and the
+* confusion is exactly the `E = −dV/dr` relation not being believed.
+*
+* Pure: no React, no pixels.
+*/
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive and finite`);
+	return value;
+};
+/**
+* Gravitational field strength at a distance from a point or spherical mass: `E = mu/r²`.
+*
+* Numerically identical to the free-fall acceleration there, and that identity is worth naming
+* rather than leaving implicit: N/kg and m/s² are the same unit, and the two names exist because the
+* quantity answers two different questions. Returned as a positive magnitude; the direction is
+* always towards the mass, which is the one thing gravity never varies.
+*/
+const gravitationalFieldStrength = (mu, distance) => positive(mu, "gravitational parameter") / positive(distance, "distance") ** 2;
+/**
+* Gravitational potential at a distance: `V = −mu/r`, in J/kg.
+*
+* NEGATIVE, and increasing towards zero as you move away. Per kilogram, so it is a property of the
+* PLACE and not of whatever you put there, which is what makes it worth defining at all.
+*/
+const gravitationalPotential = (mu, distance) => -positive(mu, "gravitational parameter") / positive(distance, "distance");
+/**
+* The potential energy of a mass at a distance: `U = −mu·m/r`, in joules.
+*
+* Distinct from `gravitationalPE` in `energy/store.ts`, and the pair is worth holding side by side:
+* that one is `mgh` measured from a level you chose and can be positive or negative, this one is
+* measured from infinity and is always negative. They are the same quantity under different
+* conventions, and `gravitationalWork` in that file shows one collapsing into the other.
+*/
+const gravitationalPotentialEnergy = (mu, mass, distance) => -positive(mu, "gravitational parameter") * positive(mass, "mass") / positive(distance, "distance");
+/**
+* The potential difference between two radii, and the work per kilogram it represents.
+*
+* `ΔV = V_b − V_a = mu(1/r_a − 1/r_b)`. Positive when moving outwards, because you are paying off
+* debt. The sign discipline here is the whole of the topic's marking: a question asking for "the
+* work done in moving a mass from A to B" wants `m·ΔV`, and the commonest error is taking the
+* difference the wrong way round and reporting a rescue mission as an energy source.
+*/
+function potentialDifference(mu, fromRadius, toRadius, sf = 3) {
+	const a = positive(fromRadius, "radius");
+	const b = positive(toRadius, "radius");
+	const value = gravitationalPotential(mu, b) - gravitationalPotential(mu, a);
+	return calc().step("V = -\\frac{GM}{r}", "measured from infinity, where V is zero. So V is negative everywhere else").step("\\Delta V = V_b - V_a = GM\\left(\\frac{1}{r_a} - \\frac{1}{r_b}\\right)").step(`\\Delta V = ${texSigFigs(mu, sf)}\\left(\\frac{1}{${texSigFigs(a, sf)}} - \\frac{1}{${texSigFigs(b, sf)}}\\right)`).step(`\\Delta V = ${texSigFigs(value, sf)}\\ \\mathrm{J\\,kg^{-1}}`, value > 0 ? "positive: moving outwards, so an outside agent must do work" : "negative: moving inwards, so gravity does the work and energy is released").done(value);
+}
+const regionOf = (distance, radius) => distance < radius ? "inside" : distance > radius ? "outside" : "surface";
+/**
+* Field and potential of a thin HOLLOW SHELL, in every region.
+*
+* The full statement of the theorem as a single function, because the discontinuity is the lesson:
+* the field jumps from zero to its full surface value as you cross the wall, while the potential
+* passes through smoothly. A graph of the two, drawn together, is the single most useful picture in
+* the topic and a lab can draw it straight from this.
+*/
+function shellFieldAndPotential(shellMass, shellRadius, distance, G = GRAVITATIONAL_CONSTANT) {
+	const R = positive(shellRadius, "shell radius");
+	const r = positive(distance, "distance");
+	const mu = G * positive(shellMass, "mass");
+	const region = regionOf(r, R);
+	if (region === "inside") return {
+		field: 0,
+		potential: -mu / R,
+		region
+	};
+	return {
+		field: mu / (r * r),
+		potential: -mu / r,
+		region
+	};
+}
+/**
+* Field and potential of a SOLID sphere of uniform density, in every region.
+*
+* Outside, it is a point mass. Inside, only the sphere beneath you counts, which gives a field
+* rising LINEARLY from zero at the centre, and a potential following
+*
+*     V = −GM(3R² − r²) / 2R³
+*
+* which at the centre is `−3GM/2R`, one and a half times the surface value. That factor of 3/2 is a
+* favourite exam number and it comes from integrating the shells, not from anywhere mysterious.
+*/
+function sphereFieldAndPotential(mass, radius, distance, G = GRAVITATIONAL_CONSTANT) {
+	const R = positive(radius, "radius");
+	const r = positive(distance, "distance");
+	const mu = G * positive(mass, "mass");
+	const region = regionOf(r, R);
+	if (region === "inside") return {
+		field: mu * r / R ** 3,
+		potential: -mu * (3 * R * R - r * r) / (2 * R ** 3),
+		region
+	};
+	return {
+		field: mu / (r * r),
+		potential: -mu / r,
+		region
+	};
+}
+/**
+* The gravitational self-energy of a uniform sphere: `U = −3GM²/5R`.
+*
+* The energy released in assembling the body shell by shell from infinite dispersion, and equally
+* the energy needed to disperse it again. Beyond most syllabuses, but it is where a star's heat
+* comes from before fusion starts, so it is the bridge from this chapter to astrophysics, and the
+* 3/5 is the same integral as the 3/2 above.
+*/
+const sphereSelfEnergy = (mass, radius, G = GRAVITATIONAL_CONSTANT) => -3 * G * positive(mass, "mass") ** 2 / (5 * positive(radius, "radius"));
+/**
+* Escape speed from a distance: `v = √(2·mu/r)`.
+*
+* DOES NOT DEPEND ON THE ESCAPING MASS, which is the fact worth stopping on: a pebble and a
+* battleship need the same 11.2 km/s. The mass cancels because both the energy you must supply and
+* the energy you have scale with it, and that cancellation is the same one that makes everything
+* fall at the same rate.
+*
+* Nor does it depend on DIRECTION, as long as you miss the ground: escape is an energy condition,
+* not a trajectory. Sideways at 11.2 km/s escapes exactly as well as straight up, which is the
+* detail that makes it clear this is a potential-energy argument and not a ballistics one.
+*/
+const escapeSpeed = (mu, distance) => Math.sqrt(2 * positive(mu, "gravitational parameter") / positive(distance, "distance"));
+/**
+* Escape speed from a body's surface, worked, in all three of the forms a syllabus prints.
+*
+* `√(2GM/R)`, `√(2gR)` and `R√(8πGρ/3)` are the same number reached from whichever pair of
+* quantities a question supplies, and a student who knows only the first stalls when handed a
+* density. The working shows them as one expression rewritten, not as three formulas to memorise.
+*
+* The final step gives the ratio to circular orbital speed, which is exactly `√2` at every radius
+* around every body: escaping costs twice the KINETIC ENERGY of circling, never twice the speed.
+*/
+function escapeSpeedSteps(body, sf = 3) {
+	const g = surfaceGravity(body);
+	const value = escapeSpeed(body.mu, body.radius);
+	return calc().step("\\tfrac{1}{2}mv^2 = \\frac{GMm}{R}", "give it exactly enough kinetic energy to pay off the whole potential debt, arriving at infinity with nothing left").step("v_e = \\sqrt{\\frac{2GM}{R}}", "the escaping mass m cancels. A pebble and a rocket need the same speed").step(`v_e = \\sqrt{2gR} = \\sqrt{2 \\times ${texSigFigs(g, sf)} \\times ${texSigFigs(body.radius, sf)}}`, "since g = GM/R², the same expression written from the surface gravity instead").step("v_e = R\\sqrt{\\tfrac{8}{3}\\pi G \\rho}", "and again from the density, for questions that give you what a planet is made of").step(`v_e = ${texSigFigs(value, sf)}\\ \\mathrm{m\\,s^{-1}}`).step("\\frac{v_e}{v_{orbit}} = \\sqrt{2}", "true at every radius around every body. Escape needs twice the kinetic energy of a circular orbit, not twice the speed").done(value);
+}
+/**
+* How high a body thrown up at a given speed reaches, when `g` cannot be treated as constant.
+*
+* `h = R / (v_e²/v² − 1)`, from energy conservation with the true `1/r` potential. The reason it
+* exists is that `v²/2g` is wrong for anything fast: at 5 km/s the constant-`g` answer is about
+* 1274 km and the true answer is about 1600 km, a 25% error, and the gap widens without limit as
+* the speed approaches escape. Throws if the speed reaches escape speed, because then there is no
+* highest point.
+*/
+function riseHeight(body, launchSpeed, sf = 3) {
+	const v = positive(launchSpeed, "speed");
+	const ve = escapeSpeed(body.mu, body.radius);
+	if (v >= ve) throw new RangeError("at or above escape speed the body never turns round");
+	const value = body.radius / (ve * ve / (v * v) - 1);
+	const naive = v * v / (2 * surfaceGravity(body));
+	return calc().step("\\tfrac{1}{2}mv^2 - \\frac{GMm}{R} = -\\frac{GMm}{R+h}", "all the kinetic energy has become potential at the top, where it is momentarily still").step("\\frac{v^2}{2} = GM\\left(\\frac{1}{R} - \\frac{1}{R+h}\\right)").step(`h = \\frac{R}{\\frac{v_e^2}{v^2} - 1} = \\frac{${texSigFigs(body.radius, sf)}}{${texSigFigs(ve * ve / (v * v), sf)} - 1}`).step(`h = ${texSigFigs(value, sf)}\\ \\mathrm{m}`).step(`\\text{constant-}g\\text{: } \\frac{v^2}{2g} = ${texSigFigs(naive, sf)}\\ \\mathrm{m}`, `treating g as constant is out by ${texSigFigs(100 * (value - naive) / value, 2)}% here, because g weakens on the way up`).done(value);
+}
+
+//#endregion
+export { escapeSpeed, escapeSpeedSteps, gravitationalFieldStrength, gravitationalPotential, gravitationalPotentialEnergy, potentialDifference, riseHeight, shellFieldAndPotential, sphereFieldAndPotential, sphereSelfEnergy };