@classytic/stage 0.2.0 → 0.4.0

package/dist/physics/magnetism/flux.mjs

@@ -0,0 +1,313 @@
+import { add3, basisFor3, dot3, mag3, scale3, sub3, unit3, v3 } from "../../core/vec3.mjs";
+import { fieldAt } from "./biot-savart.mjs";
+
+//#region src/physics/magnetism/flux.ts
+/**
+* @classytic/stage/field/flux — magnetic flux, flux linkage and inductance,
+* computed over real geometry.
+*
+* Flux was previously only ever `B A cos(theta)` written inline wherever it was
+* needed, which works for exactly one case: a flat loop in a field that is
+* uniform across it. Every other case a student meets is outside that: a loop
+* beside a straight wire, a small coil inside a big one, a solenoid linking its
+* own turns. Those need the surface integral, and once you can do the integral
+* you get inductance for free, because inductance is nothing but flux linkage
+* per unit current.
+*
+*   Phi = integral of B . dA        Phi_linkage = N Phi        L = N Phi / I
+*
+* ── Two rules for getting a trustworthy number out of this ────────────────────
+* 1. KEEP THE LOOP INSIDE THE WINDING. A filament has no thickness, so the
+*    field diverges on it and a flux loop whose edge sits on the winding picks
+*    that up: integrating a solenoid out to 0.999 of its radius lands 2.3% low,
+*    while 0.9 of the radius is right to a part in a thousand. A real coil is
+*    wound with wire of finite thickness, which is exactly what the filament
+*    model cannot represent.
+* 2. WIND IT FINELY COMPARED WITH ITS RADIUS. A ring stack with turns spaced a
+*    tenth of a radius apart sits about 2.5% below the ideal solenoid formula
+*    and stays there however long you make the coil, because the error is
+*    radial rather than an end effect. Tighten the spacing to a fortieth of a
+*    radius and it converges to within 0.4%.
+*
+* Both are asserted in the tests, so the limits are known rather than found.
+*
+* ── Mutual inductance: drive the LARGER circuit ───────────────────────────────
+* M is reciprocal, but the two ways of computing it are not equally
+* computable. Integrating a small coil's field through a large coplanar loop
+* puts the small winding ON the integration surface, where the integrand
+* diverges and only its principal value is finite. Driving the larger circuit
+* and integrating through the smaller loop keeps the surface clear of every
+* winding, and gives the same M.
+*
+* ── Why the loop is a SHAPE and not a polygon ─────────────────────────────────
+* A rectangle and a circle cover every loop a syllabus draws, and both can be
+* integrated by a product Gauss rule over their own parameters, which converges
+* fast and has no boundary error. A general polygon would need point-in-polygon
+* tests on a grid, which is slower and least accurate exactly at the edge, where
+* a loop near a wire has its steepest field.
+*/
+/** Area of the loop, in square metres. */
+const loopArea = (loop) => loop.kind === "circle" ? Math.PI * loop.radiusM ** 2 : loop.widthM * loop.heightM;
+/**
+* Flux through a flat loop in a UNIFORM field: Phi = B A cos(theta).
+*
+* `normalToFieldDeg` is the angle between the loop's normal and the field, the
+* same convention `coilTorqueNm` uses, so the two never disagree about what the
+* angle means. The trap is the same one too: a question usually states the
+* angle from the PLANE, and flux is greatest when the plane is ACROSS the field,
+* which is exactly where the torque is zero.
+*/
+function fluxThroughUniform(fieldT, areaM2, normalToFieldDeg) {
+	if (areaM2 < 0) throw new RangeError("Area cannot be negative.");
+	return fieldT * areaM2 * Math.cos(normalToFieldDeg * Math.PI / 180);
+}
+/** Flux linkage: the flux each turn sees, times the number of turns. */
+function fluxLinkage(turns, fluxWb) {
+	if (turns < 0) throw new RangeError("Turns cannot be negative.");
+	return turns * fluxWb;
+}
+/**
+* Magnitude of the average induced e.m.f. from Faraday's law.
+*
+* Unsigned on purpose. The direction is Lenz's law, which is a separate
+* statement about what the induced current opposes, and folding a sign in here
+* would let a student produce a direction without ever thinking about the
+* opposition that gives it.
+*/
+function inducedEmfV(turns, fluxChangeWb, timeS) {
+	if (turns < 0) throw new RangeError("Turns cannot be negative.");
+	if (timeS <= 0) throw new RangeError("The time interval must be positive.");
+	return turns * Math.abs(fluxChangeWb) / timeS;
+}
+/** How close a sample may come to a current filament before the flux is called divergent. */
+const MIN_LOOP_CLEARANCE_M = 1e-4;
+/**
+* Gauss-Legendre nodes and weights on [-1, 1].
+*
+* Order 8 is right for a field that varies smoothly across the loop. Order 16
+* exists for the case where the SOURCE is much smaller than the loop, which is
+* not a smooth integrand at all: a small coil seen from a large one is close to
+* a point dipole, and a coarse rule simply steps over it.
+*/
+const GAUSS = {
+	8: {
+		nodes: [
+			-.9602898564975363,
+			-.7966664774136267,
+			-.525532409916329,
+			-.1834346424956498,
+			.1834346424956498,
+			.525532409916329,
+			.7966664774136267,
+			.9602898564975363
+		],
+		weights: [
+			.1012285362903763,
+			.2223810344533745,
+			.3137066458778873,
+			.362683783378362,
+			.362683783378362,
+			.3137066458778873,
+			.2223810344533745,
+			.1012285362903763
+		]
+	},
+	16: {
+		nodes: [
+			-.9894009349916499,
+			-.9445750230732326,
+			-.8656312023878318,
+			-.755404408355003,
+			-.6178762444026438,
+			-.4580167776572274,
+			-.2816035507792589,
+			-.0950125098376374,
+			.0950125098376374,
+			.2816035507792589,
+			.4580167776572274,
+			.6178762444026438,
+			.755404408355003,
+			.8656312023878318,
+			.9445750230732326,
+			.9894009349916499
+		],
+		weights: [
+			.0271524594117541,
+			.0622535239386479,
+			.0951585116824928,
+			.1246289712555339,
+			.1495959888165767,
+			.1691565193950025,
+			.1826034150449236,
+			.1894506104550685,
+			.1894506104550685,
+			.1826034150449236,
+			.1691565193950025,
+			.1495959888165767,
+			.1246289712555339,
+			.0951585116824928,
+			.0622535239386479,
+			.0271524594117541
+		]
+	}
+};
+/** Distance from a point to the loop's SURFACE, not merely to its plane. */
+const distanceToSurface = (p, loop, n, u, v) => {
+	const d = sub3(p, loop.centre);
+	const perp = dot3(d, n);
+	const a = dot3(d, u);
+	const b = dot3(d, v);
+	if (loop.kind === "circle") {
+		const over = Math.max(0, Math.hypot(a, b) - loop.radiusM);
+		return Math.hypot(perp, over);
+	}
+	const overU = Math.max(0, Math.abs(a) - loop.widthM / 2);
+	const overV = Math.max(0, Math.abs(b) - loop.heightM / 2);
+	return Math.sqrt(perp * perp + overU * overU + overV * overV);
+};
+/**
+* Refuse a loop whose surface runs into a current filament.
+*
+* This cannot be done by watching the quadrature samples. A Gauss rule never
+* lands on an endpoint, so it sails straight past a 1/r singularity and returns
+* a finite number for a divergent integral, which is the worst possible
+* failure: a confident wrong answer. Worse, the commonest case is a wire lying
+* IN the plane of the loop and crossing its interior, where the field is
+* antisymmetric and the samples cancel almost exactly.
+*
+* So the geometry is checked instead: every source segment is walked and its
+* distance to the loop's surface taken. A filament touching that surface makes
+* the flux genuinely infinite, and saying so is the only honest answer.
+*
+* This is also why a coil's own winding cannot be its own flux loop. Put the
+* loop just inside the winding radius: a real coil has wire of finite
+* thickness, and the filament model has no way to represent that.
+*/
+const assertClear = (sources, loop, n, u, v) => {
+	const loopReach = loop.kind === "circle" ? loop.radiusM : Math.hypot(loop.widthM / 2, loop.heightM / 2);
+	for (const path of sources) {
+		if (path.currentA === 0) continue;
+		let minX = Infinity, minY = Infinity, minZ = Infinity;
+		let maxX = -Infinity, maxY = -Infinity, maxZ = -Infinity;
+		for (const p of path.points) {
+			if (p.x < minX) minX = p.x;
+			if (p.y < minY) minY = p.y;
+			if (p.z < minZ) minZ = p.z;
+			if (p.x > maxX) maxX = p.x;
+			if (p.y > maxY) maxY = p.y;
+			if (p.z > maxZ) maxZ = p.z;
+		}
+		const centre = v3((minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2);
+		const pathReach = Math.hypot(maxX - minX, maxY - minY, maxZ - minZ) / 2;
+		if (mag3(sub3(centre, loop.centre)) > pathReach + loopReach + 1e-4) continue;
+		for (let i = 0; i + 1 < path.points.length; i += 1) {
+			const a = path.points[i];
+			const b = path.points[i + 1];
+			const steps = Math.max(2, Math.min(24, Math.ceil(mag3(sub3(b, a)) / MIN_LOOP_CLEARANCE_M)));
+			for (let k = 0; k <= steps; k += 1) if (distanceToSurface(add3(a, scale3(sub3(b, a), k / steps)), loop, n, u, v) < 1e-4) throw new RangeError("A current filament touches the loop surface, where the flux through it diverges. If this is a coil linking its own turns, put the loop just inside the winding radius.");
+		}
+	}
+};
+function fluxThroughLoop(sources, loop, order = 8) {
+	const rule = GAUSS[order];
+	if (!rule) throw new RangeError("Unsupported quadrature order.");
+	const n = unit3(loop.normal);
+	const [u, v] = basisFor3(loop.normal, loop.kind === "rectangle" ? loop.widthAxis : void 0);
+	assertClear(sources, loop, n, u, v);
+	let total = 0;
+	for (let i = 0; i < rule.nodes.length; i += 1) for (let j = 0; j < rule.nodes.length; j += 1) {
+		const a = rule.nodes[i];
+		const b = rule.nodes[j];
+		const w = rule.weights[i] * rule.weights[j];
+		let point;
+		let jacobian;
+		if (loop.kind === "rectangle") {
+			point = add3(loop.centre, add3(scale3(u, a * loop.widthM / 2), scale3(v, b * loop.heightM / 2)));
+			jacobian = loop.widthM / 2 * (loop.heightM / 2);
+		} else {
+			const r = loop.radiusM * (a + 1) / 2;
+			const theta = Math.PI * (b + 1);
+			point = add3(loop.centre, add3(scale3(u, r * Math.cos(theta)), scale3(v, r * Math.sin(theta))));
+			jacobian = r * (loop.radiusM / 2) * Math.PI;
+		}
+		total += w * jacobian * dot3(fieldAt(sources, point).field, n);
+	}
+	return total;
+}
+/**
+* Self-inductance of a coil, in henries: L = N Phi / I.
+*
+* Measured by driving the coil with a test current and integrating the flux its
+* own field puts through one turn. That the answer does not depend on the test
+* current is the definition of inductance, and it is asserted in the tests
+* rather than assumed.
+*/
+function selfInductanceH(coil, oneTurn, turns, testCurrentA = 1, order = 8) {
+	if (turns < 1) throw new RangeError("A coil needs at least one turn.");
+	if (testCurrentA === 0) throw new RangeError("The test current cannot be zero.");
+	return turns * fluxThroughLoop(coil, oneTurn, order) / testCurrentA;
+}
+/**
+* Mutual inductance between two circuits, in henries: M = N2 Phi2 / I1.
+*
+* The primary's field is integrated through one turn of the secondary. The
+* reciprocity of this quantity, that driving either side gives the same M, is a
+* real theorem and a good thing for a lesson to check rather than assert.
+*/
+function mutualInductanceH(primary, secondaryTurn, secondaryTurns, primaryCurrentA = 1, order = 8) {
+	if (secondaryTurns < 1) throw new RangeError("A secondary needs at least one turn.");
+	if (primaryCurrentA === 0) throw new RangeError("The primary current cannot be zero.");
+	return secondaryTurns * fluxThroughLoop(primary, secondaryTurn, order) / primaryCurrentA;
+}
+/**
+* Magnitude of the e.m.f. a changing current induces in its OWN circuit:
+* E = L di/dt.
+*
+* The same physics as Faraday's law with the flux written as L I, and worth
+* having separately because a question almost never gives you the flux. It
+* gives you a current that changed and a time it took.
+*/
+function emfFromSelfInductance(inductanceH, currentChangeA, timeS) {
+	if (inductanceH < 0) throw new RangeError("Inductance cannot be negative.");
+	if (timeS <= 0) throw new RangeError("The time interval must be positive.");
+	return inductanceH * Math.abs(currentChangeA) / timeS;
+}
+/**
+* Magnitude of the e.m.f. a changing current induces in a NEIGHBOURING circuit:
+* E = M di/dt.
+*
+* Identical in form to the self-inductance case, with M in place of L. That the
+* two are the same equation is the point: a transformer is not a new law, it is
+* this one with the two coils wound on the same core.
+*/
+function emfFromMutualInductance(mutualH, currentChangeA, timeS) {
+	if (mutualH < 0) throw new RangeError("Mutual inductance cannot be negative.");
+	if (timeS <= 0) throw new RangeError("The time interval must be positive.");
+	return mutualH * Math.abs(currentChangeA) / timeS;
+}
+/** Energy stored in an inductor's field, in joules: W = 1/2 L I squared. */
+function magneticEnergyJ(inductanceH, currentA) {
+	if (inductanceH < 0) throw new RangeError("Inductance cannot be negative.");
+	return .5 * inductanceH * currentA * currentA;
+}
+/** Ideal-solenoid self-inductance, for checking the integrated answer: mu0 N^2 A / l. */
+function solenoidInductanceH(turns, areaM2, lengthM) {
+	if (lengthM <= 0) throw new RangeError("A solenoid needs a positive length.");
+	return 4 * Math.PI * 1e-7 * turns * turns * areaM2 / lengthM;
+}
+/**
+* Flux through a rectangle lying beside a long straight wire, in closed form.
+*
+*   Phi = (mu0 I l / 2 pi) ln(far / near)
+*
+* A standard exam result, and the best available check on the surface integral:
+* the field varies as 1/r right across the loop, so nothing about this case is
+* forgiving of a sloppy quadrature rule.
+*/
+function fluxBesideWire(currentA, lengthM, nearM, farM) {
+	if (nearM <= 0 || farM <= nearM) throw new RangeError("Need 0 < near < far.");
+	return 4 * Math.PI * 1e-7 * currentA * lengthM / (2 * Math.PI) * Math.log(farM / nearM);
+}
+
+//#endregion
+export { MIN_LOOP_CLEARANCE_M, emfFromMutualInductance, emfFromSelfInductance, fluxBesideWire, fluxLinkage, fluxThroughLoop, fluxThroughUniform, inducedEmfV, loopArea, magneticEnergyJ, mutualInductanceH, selfInductanceH, solenoidInductanceH };

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

@@ -0,0 +1,151 @@
+//#region src/physics/magnetism/geomagnetism.d.ts
+/**
+ * @classytic/stage/field/geomagnetism — the Earth's magnetic field, as the
+ * tilted dipole it very nearly is.
+ *
+ * A textbook gives dip and declination as numbers to look up. They are not
+ * lookups: a single dipole at the centre of the Earth, tilted about 11 degrees
+ * from the spin axis, predicts both to within a few degrees almost everywhere,
+ * and predicts the field strength to within about 10%. That is worth computing
+ * rather than tabulating, because the model explains WHY dip is zero at the
+ * magnetic equator and 90 degrees at the pole, and a table never can.
+ *
+ * ── What this model does not do ────────────────────────────────────────────────
+ * The real field has non-dipole parts (roughly 10% of it) from fluid motion in
+ * the core, plus crustal magnetism, plus a daily variation from currents in the
+ * ionosphere. So a value here can be a few degrees off what a survey measures,
+ * and the discrepancy IS the non-dipole field rather than an error. Anything
+ * needing survey accuracy wants IGRF, which is a 195-coefficient spherical
+ * harmonic model and a different kind of object entirely.
+ *
+ * ── Two different "magnetic poles" ─────────────────────────────────────────────
+ * The GEOMAGNETIC pole is where the best-fit dipole's axis cuts the surface.
+ * The magnetic DIP pole is where a dip needle actually stands vertical. They
+ * are about 1000 km apart and move differently, because the non-dipole field
+ * displaces the second and not the first. This module uses the geomagnetic pole,
+ * which is the only one a dipole model has.
+ */
+/**
+ * The Earth's dipole moment, in A m^2 (IGRF epoch 2020, and falling slowly).
+ *
+ * The same quantity as a coil's N I A. A current loop of one turn enclosing the
+ * Earth's cross-section would need about 2 billion amperes to match it.
+ */
+declare const EARTH_DIPOLE_MOMENT_AM2 = 7.75e+22;
+/** Mean radius of the Earth, in metres. */
+declare const EARTH_RADIUS_M = 6371000;
+/** Where the best-fit dipole axis leaves the northern hemisphere (IGRF 2020). */
+declare const GEOMAGNETIC_NORTH_POLE: {
+  readonly latitudeDeg: 80.65;
+  readonly longitudeDeg: -72.68;
+};
+interface FieldComponents {
+  /** Horizontal component, in tesla. The part a plotting compass follows. */
+  horizontalT: number;
+  /** Vertical component, in tesla. Positive downward, as convention has it. */
+  verticalT: number;
+  /** Total field, in tesla. */
+  totalT: number;
+  /** Angle below the horizontal, in degrees. Also called inclination. */
+  dipDeg: number;
+}
+/** Resolve a known total field and dip angle into horizontal and vertical parts. */
+declare function earthComponents(totalT: number, dipDeg: number): FieldComponents;
+/** Recover the total field and dip angle from the two measured components. */
+declare function earthFromComponents(horizontalT: number, verticalT: number): FieldComponents;
+/**
+ * Apparent dip measured in a vertical plane turned `bearingDeg` out of the
+ * magnetic meridian: tan(dip') = tan(dip) / cos(bearing).
+ *
+ * Turning the dip circle only shortens the horizontal component it can see; the
+ * vertical component is unchanged because it lies in every vertical plane. So
+ * the needle always appears to dip MORE, never less, and at 90 degrees the
+ * horizontal component vanishes entirely and the needle stands upright wherever
+ * you are.
+ */
+declare function apparentDipDeg(trueDipDeg: number, bearingDeg: number): number;
+/**
+ * Recover the true dip from two apparent dips measured in perpendicular planes.
+ *
+ * This is the actual field method, and it is better than it looks: it needs no
+ * knowledge of where the magnetic meridian is, which is the hard thing to find.
+ * Turning the circle through a right angle and measuring twice is enough,
+ * because cot^2 adds.
+ */
+declare function trueDipFromTwo(apparent1Deg: number, apparent2Deg: number): number;
+interface DipoleField extends FieldComponents {
+  /** Latitude measured from the dipole's own equator, in degrees. */
+  magneticLatitudeDeg: number;
+}
+/**
+ * The field of a centred dipole at a given magnetic latitude and radius.
+ *
+ *   H = B0 cos(lat)        Z = 2 B0 sin(lat)        B0 = mu0 m / 4 pi r^3
+ *
+ * The factor of two on the vertical component is the whole character of a
+ * dipole field, and everything else follows from it: the field at the pole is
+ * twice the field at the equator, and tan(dip) = 2 tan(latitude).
+ */
+declare function dipoleFieldAt(magneticLatitudeDeg: number, radiusM?: number, momentAm2?: number): DipoleField;
+/**
+ * The dipole rule relating dip to magnetic latitude: tan(dip) = 2 tan(lat).
+ *
+ * Worth having on its own because it is the one line of this model a student is
+ * ever asked to remember, and because it says the dip reaches 45 degrees at a
+ * magnetic latitude of only 26.6 degrees, not 45.
+ */
+declare const dipFromMagneticLatitude: (latitudeDeg: number) => number;
+/** The inverse: where on the dipole you must be to see a given dip. */
+declare const magneticLatitudeFromDip: (dipDeg: number) => number;
+interface GeographicPlace {
+  latitudeDeg: number;
+  /** East positive. */
+  longitudeDeg: number;
+  label?: string;
+}
+interface LocalField extends DipoleField {
+  /**
+   * Angle from true north to magnetic north, in degrees, east positive.
+   *
+   * This is why a compass is not a map. A navigator adds it to a compass
+   * bearing to get a true one, and getting the sign wrong puts you off by twice
+   * the angle rather than leaving you where you started.
+   */
+  declinationDeg: number;
+  /** Angular distance from the geomagnetic north pole, in degrees. */
+  colatitudeDeg: number;
+}
+/**
+ * The dipole model's prediction for an actual place on the globe.
+ *
+ * Two spherical-triangle results do the work. The magnetic latitude is 90
+ * degrees minus the angular distance to the geomagnetic pole, and the
+ * declination is simply the bearing you would walk to reach that pole, because
+ * in a dipole model that bearing IS where the compass points.
+ */
+declare function fieldAtPlace(place: GeographicPlace, pole?: GeographicPlace, momentAm2?: number): LocalField;
+/**
+ * Turn a compass bearing into a true one.
+ *
+ * The rule everybody gets backwards once: true = magnetic + declination, with
+ * east declination positive. Going the other way, subtract.
+ */
+declare const trueBearingDeg: (compassBearingDeg: number, declinationDeg: number) => number;
+declare const compassBearingDeg: (trueBearing: number, declinationDeg: number) => number;
+/**
+ * A magnetic field line of a centred dipole, as magnetic latitudes along it.
+ *
+ * Dipole field lines satisfy r = L cos^2(latitude), where L is how far out the
+ * line reaches at the magnetic equator, measured in Earth radii. This is the
+ * shape that puts the aurora in a ring rather than over the pole: a line
+ * starting at high latitude reaches only a little way out, while one leaving
+ * near the equator reaches far into space and is where particles are trapped.
+ */
+declare function dipoleFieldLine(shellL: number, points?: number): Array<{
+  latitudeDeg: number;
+  radiusEarths: number;
+}>;
+/** Where a dipole field line of shell L touches down, in degrees of latitude. */
+declare const footLatitudeDeg: (shellL: number) => number;
+//#endregion
+export { DipoleField, EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, FieldComponents, GEOMAGNETIC_NORTH_POLE, GeographicPlace, LocalField, apparentDipDeg, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, fieldAtPlace, footLatitudeDeg, magneticLatitudeFromDip, trueBearingDeg, trueDipFromTwo };

package/dist/physics/magnetism/geomagnetism.mjs

@@ -0,0 +1,184 @@
+//#region src/physics/magnetism/geomagnetism.ts
+/**
+* @classytic/stage/field/geomagnetism — the Earth's magnetic field, as the
+* tilted dipole it very nearly is.
+*
+* A textbook gives dip and declination as numbers to look up. They are not
+* lookups: a single dipole at the centre of the Earth, tilted about 11 degrees
+* from the spin axis, predicts both to within a few degrees almost everywhere,
+* and predicts the field strength to within about 10%. That is worth computing
+* rather than tabulating, because the model explains WHY dip is zero at the
+* magnetic equator and 90 degrees at the pole, and a table never can.
+*
+* ── What this model does not do ────────────────────────────────────────────────
+* The real field has non-dipole parts (roughly 10% of it) from fluid motion in
+* the core, plus crustal magnetism, plus a daily variation from currents in the
+* ionosphere. So a value here can be a few degrees off what a survey measures,
+* and the discrepancy IS the non-dipole field rather than an error. Anything
+* needing survey accuracy wants IGRF, which is a 195-coefficient spherical
+* harmonic model and a different kind of object entirely.
+*
+* ── Two different "magnetic poles" ─────────────────────────────────────────────
+* The GEOMAGNETIC pole is where the best-fit dipole's axis cuts the surface.
+* The magnetic DIP pole is where a dip needle actually stands vertical. They
+* are about 1000 km apart and move differently, because the non-dipole field
+* displaces the second and not the first. This module uses the geomagnetic pole,
+* which is the only one a dipole model has.
+*/
+/** Permeability of free space, in T m A^-1. */
+const MU_0 = 4 * Math.PI * 1e-7;
+/**
+* The Earth's dipole moment, in A m^2 (IGRF epoch 2020, and falling slowly).
+*
+* The same quantity as a coil's N I A. A current loop of one turn enclosing the
+* Earth's cross-section would need about 2 billion amperes to match it.
+*/
+const EARTH_DIPOLE_MOMENT_AM2 = 775e20;
+/** Mean radius of the Earth, in metres. */
+const EARTH_RADIUS_M = 6371e3;
+/** Where the best-fit dipole axis leaves the northern hemisphere (IGRF 2020). */
+const GEOMAGNETIC_NORTH_POLE = {
+	latitudeDeg: 80.65,
+	longitudeDeg: -72.68
+};
+const radians = (deg) => deg * Math.PI / 180;
+const degrees = (rad) => rad * 180 / Math.PI;
+/** Resolve a known total field and dip angle into horizontal and vertical parts. */
+function earthComponents(totalT, dipDeg) {
+	const dip = radians(dipDeg);
+	return {
+		horizontalT: totalT * Math.cos(dip),
+		verticalT: totalT * Math.sin(dip),
+		totalT,
+		dipDeg
+	};
+}
+/** Recover the total field and dip angle from the two measured components. */
+function earthFromComponents(horizontalT, verticalT) {
+	return {
+		horizontalT,
+		verticalT,
+		totalT: Math.hypot(horizontalT, verticalT),
+		dipDeg: degrees(Math.atan2(verticalT, horizontalT))
+	};
+}
+/**
+* Apparent dip measured in a vertical plane turned `bearingDeg` out of the
+* magnetic meridian: tan(dip') = tan(dip) / cos(bearing).
+*
+* Turning the dip circle only shortens the horizontal component it can see; the
+* vertical component is unchanged because it lies in every vertical plane. So
+* the needle always appears to dip MORE, never less, and at 90 degrees the
+* horizontal component vanishes entirely and the needle stands upright wherever
+* you are.
+*/
+function apparentDipDeg(trueDipDeg, bearingDeg) {
+	const cos = Math.cos(radians(bearingDeg));
+	if (Math.abs(cos) < 1e-12) return 90;
+	return degrees(Math.atan(Math.tan(radians(trueDipDeg)) / cos));
+}
+/**
+* Recover the true dip from two apparent dips measured in perpendicular planes.
+*
+* This is the actual field method, and it is better than it looks: it needs no
+* knowledge of where the magnetic meridian is, which is the hard thing to find.
+* Turning the circle through a right angle and measuring twice is enough,
+* because cot^2 adds.
+*/
+function trueDipFromTwo(apparent1Deg, apparent2Deg) {
+	const c1 = 1 / Math.tan(radians(apparent1Deg));
+	const c2 = 1 / Math.tan(radians(apparent2Deg));
+	return degrees(Math.atan(1 / Math.sqrt(c1 * c1 + c2 * c2)));
+}
+/**
+* The field of a centred dipole at a given magnetic latitude and radius.
+*
+*   H = B0 cos(lat)        Z = 2 B0 sin(lat)        B0 = mu0 m / 4 pi r^3
+*
+* The factor of two on the vertical component is the whole character of a
+* dipole field, and everything else follows from it: the field at the pole is
+* twice the field at the equator, and tan(dip) = 2 tan(latitude).
+*/
+function dipoleFieldAt(magneticLatitudeDeg, radiusM = EARTH_RADIUS_M, momentAm2 = EARTH_DIPOLE_MOMENT_AM2) {
+	if (radiusM <= 0) throw new RangeError("Radius must be positive.");
+	const equatorialT = MU_0 * momentAm2 / (4 * Math.PI * radiusM ** 3);
+	const lat = radians(magneticLatitudeDeg);
+	const horizontalT = equatorialT * Math.cos(lat);
+	const verticalT = 2 * equatorialT * Math.sin(lat);
+	return {
+		horizontalT,
+		verticalT,
+		totalT: equatorialT * Math.sqrt(1 + 3 * Math.sin(lat) ** 2),
+		dipDeg: degrees(Math.atan2(verticalT, horizontalT)),
+		magneticLatitudeDeg
+	};
+}
+/**
+* The dipole rule relating dip to magnetic latitude: tan(dip) = 2 tan(lat).
+*
+* Worth having on its own because it is the one line of this model a student is
+* ever asked to remember, and because it says the dip reaches 45 degrees at a
+* magnetic latitude of only 26.6 degrees, not 45.
+*/
+const dipFromMagneticLatitude = (latitudeDeg) => degrees(Math.atan(2 * Math.tan(radians(latitudeDeg))));
+/** The inverse: where on the dipole you must be to see a given dip. */
+const magneticLatitudeFromDip = (dipDeg) => degrees(Math.atan(Math.tan(radians(dipDeg)) / 2));
+/**
+* The dipole model's prediction for an actual place on the globe.
+*
+* Two spherical-triangle results do the work. The magnetic latitude is 90
+* degrees minus the angular distance to the geomagnetic pole, and the
+* declination is simply the bearing you would walk to reach that pole, because
+* in a dipole model that bearing IS where the compass points.
+*/
+function fieldAtPlace(place, pole = GEOMAGNETIC_NORTH_POLE, momentAm2 = EARTH_DIPOLE_MOMENT_AM2) {
+	const lat = radians(place.latitudeDeg);
+	const poleLat = radians(pole.latitudeDeg);
+	const deltaLong = radians(pole.longitudeDeg - place.longitudeDeg);
+	const cosDistance = Math.sin(lat) * Math.sin(poleLat) + Math.cos(lat) * Math.cos(poleLat) * Math.cos(deltaLong);
+	const colatitudeDeg = degrees(Math.acos(Math.min(1, Math.max(-1, cosDistance))));
+	const magneticLatitudeDeg = 90 - colatitudeDeg;
+	const declinationDeg = degrees(Math.atan2(Math.sin(deltaLong) * Math.cos(poleLat), Math.cos(lat) * Math.sin(poleLat) - Math.sin(lat) * Math.cos(poleLat) * Math.cos(deltaLong)));
+	return {
+		...dipoleFieldAt(magneticLatitudeDeg, EARTH_RADIUS_M, momentAm2),
+		declinationDeg,
+		colatitudeDeg
+	};
+}
+/**
+* Turn a compass bearing into a true one.
+*
+* The rule everybody gets backwards once: true = magnetic + declination, with
+* east declination positive. Going the other way, subtract.
+*/
+const trueBearingDeg = (compassBearingDeg, declinationDeg) => ((compassBearingDeg + declinationDeg) % 360 + 360) % 360;
+const compassBearingDeg = (trueBearing, declinationDeg) => ((trueBearing - declinationDeg) % 360 + 360) % 360;
+/**
+* A magnetic field line of a centred dipole, as magnetic latitudes along it.
+*
+* Dipole field lines satisfy r = L cos^2(latitude), where L is how far out the
+* line reaches at the magnetic equator, measured in Earth radii. This is the
+* shape that puts the aurora in a ring rather than over the pole: a line
+* starting at high latitude reaches only a little way out, while one leaving
+* near the equator reaches far into space and is where particles are trapped.
+*/
+function dipoleFieldLine(shellL, points = 120) {
+	if (shellL < 1) throw new RangeError("A field line must reach at least the surface, so L >= 1.");
+	const footLat = Math.acos(Math.sqrt(1 / shellL));
+	const count = points % 2 === 0 ? points + 1 : points;
+	return Array.from({ length: count }, (_, i) => {
+		const lat = -footLat + 2 * footLat * i / (count - 1);
+		return {
+			latitudeDeg: degrees(lat),
+			radiusEarths: shellL * Math.cos(lat) ** 2
+		};
+	});
+}
+/** Where a dipole field line of shell L touches down, in degrees of latitude. */
+const footLatitudeDeg = (shellL) => {
+	if (shellL < 1) throw new RangeError("A field line must reach at least the surface, so L >= 1.");
+	return degrees(Math.acos(Math.sqrt(1 / shellL)));
+};
+
+//#endregion
+export { EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, GEOMAGNETIC_NORTH_POLE, apparentDipDeg, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, fieldAtPlace, footLatitudeDeg, magneticLatitudeFromDip, trueBearingDeg, trueDipFromTwo };

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

@@ -0,0 +1,12 @@
+import { CurrentPath, FieldContribution, FieldResult, MIN_DISTANCE_M, MU_0, Streamline, StreamlineOptions, arcCentreT, circularArc, coilAxisT, coilCentreT, fieldAt, finiteWireT, flatCoil, helmholtzPair, longWire, longWireT, pathField, rectangularLoop, segmentField, solenoid, solenoidRings, solenoidT, straightWire, toroidT, traceFieldLine, traceFullFieldLine } from "./biot-savart.mjs";
+import { FluxLoop, MIN_LOOP_CLEARANCE_M, emfFromMutualInductance, emfFromSelfInductance, fluxBesideWire, fluxLinkage, fluxThroughLoop, fluxThroughUniform, inducedEmfV, loopArea, magneticEnergyJ, mutualInductanceH, selfInductanceH, solenoidInductanceH } from "./flux.mjs";
+import { ForceOnPathOptions, PathForce, WireForce, angleFromPlaneDeg, coilTorqueNm, forceOnPath, forcePerMetreOnWire, magneticMomentAm2, momentOfLoop, parallelWireForce, torqueFromMoment } from "./magnetic-force.mjs";
+import { DipoleField, EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, FieldComponents, GEOMAGNETIC_NORTH_POLE, GeographicPlace, LocalField, apparentDipDeg, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, fieldAtPlace, footLatitudeDeg, magneticLatitudeFromDip, trueBearingDeg, trueDipFromTwo } from "./geomagnetism.mjs";
+import { SpatialFieldMode, fieldsFor, lorentzForce3D, traceLorentz } from "./lorentz.mjs";
+
+//#region src/physics/magnetism/index.d.ts
+declare namespace index_d_exports {
+  export { CurrentPath, DipoleField, EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, FieldComponents, FieldContribution, FieldResult, FluxLoop, ForceOnPathOptions, GEOMAGNETIC_NORTH_POLE, GeographicPlace, LocalField, MIN_DISTANCE_M, MIN_LOOP_CLEARANCE_M, MU_0, PathForce, SpatialFieldMode, Streamline, StreamlineOptions, WireForce, angleFromPlaneDeg, apparentDipDeg, arcCentreT, circularArc, coilAxisT, coilCentreT, coilTorqueNm, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, emfFromMutualInductance, emfFromSelfInductance, fieldAt, fieldAtPlace, fieldsFor, finiteWireT, flatCoil, fluxBesideWire, fluxLinkage, fluxThroughLoop, fluxThroughUniform, footLatitudeDeg, forceOnPath, forcePerMetreOnWire, helmholtzPair, inducedEmfV, longWire, longWireT, loopArea, lorentzForce3D, magneticEnergyJ, magneticLatitudeFromDip, magneticMomentAm2, momentOfLoop, mutualInductanceH, parallelWireForce, pathField, rectangularLoop, segmentField, selfInductanceH, solenoid, solenoidInductanceH, solenoidRings, solenoidT, straightWire, toroidT, torqueFromMoment, traceFieldLine, traceFullFieldLine, traceLorentz, trueBearingDeg, trueDipFromTwo };
+}
+//#endregion
+export { CurrentPath, DipoleField, EARTH_DIPOLE_MOMENT_AM2, EARTH_RADIUS_M, FieldComponents, FieldContribution, FieldResult, FluxLoop, ForceOnPathOptions, GEOMAGNETIC_NORTH_POLE, GeographicPlace, LocalField, MIN_DISTANCE_M, MIN_LOOP_CLEARANCE_M, MU_0, PathForce, SpatialFieldMode, Streamline, StreamlineOptions, WireForce, angleFromPlaneDeg, apparentDipDeg, arcCentreT, circularArc, coilAxisT, coilCentreT, coilTorqueNm, compassBearingDeg, dipFromMagneticLatitude, dipoleFieldAt, dipoleFieldLine, earthComponents, earthFromComponents, emfFromMutualInductance, emfFromSelfInductance, fieldAt, fieldAtPlace, fieldsFor, finiteWireT, flatCoil, fluxBesideWire, fluxLinkage, fluxThroughLoop, fluxThroughUniform, footLatitudeDeg, forceOnPath, forcePerMetreOnWire, helmholtzPair, index_d_exports, inducedEmfV, longWire, longWireT, loopArea, lorentzForce3D, magneticEnergyJ, magneticLatitudeFromDip, magneticMomentAm2, momentOfLoop, mutualInductanceH, parallelWireForce, pathField, rectangularLoop, segmentField, selfInductanceH, solenoid, solenoidInductanceH, solenoidRings, solenoidT, straightWire, toroidT, torqueFromMoment, traceFieldLine, traceFullFieldLine, traceLorentz, trueBearingDeg, trueDipFromTwo };