@classytic/stage 0.3.0 → 0.4.0

package/dist/physics/rotation/torque.mjs

@@ -0,0 +1,134 @@
+import { calc, texSigFigs } from "../../core/worked.mjs";
+import { toRadians } from "../vectors.mjs";
+
+//#region src/physics/rotation/torque.ts
+/**
+* Torque: the rotational analogue of force, and the couple.
+*
+* THE ANALOGY IS THE POINT, and it is worth stating once rather than rediscovering per topic. Every
+* equation of rotation is a linear one with the quantities swapped:
+*
+*     s → θ      v → ω      a → α      m → I      F → τ      p → L
+*
+* so `F = ma` becomes `τ = Iα`, `p = mv` becomes `L = Iω`, and `½mv²` becomes `½Iω²`. A student who
+* has that mapping has the whole chapter and does not need to memorise a second set of formulas;
+* one who does not has to learn everything twice. {@link ROTATIONAL_ANALOGUE} exists so a lesson
+* can print it as a table.
+*
+* A COUPLE is the case worth separating out: two equal and opposite forces that do not share a line
+* of action. Their resultant FORCE is exactly zero, so the body does not accelerate anywhere, and
+* yet it turns. That is the thing a learner needs to see, because it contradicts the reasonable
+* belief that zero net force means nothing happens. A couple's moment is also the same about EVERY
+* point, which is why a steering wheel turns the same whichever part of it you hold.
+*
+* Pure: no React, no pixels.
+*/
+/** The linear quantity and its rotational counterpart, for a lesson that prints the mapping. */
+const ROTATIONAL_ANALOGUE = [
+	{
+		linear: "displacement s",
+		rotational: "angle θ",
+		relation: "s = rθ"
+	},
+	{
+		linear: "velocity v",
+		rotational: "angular velocity ω",
+		relation: "v = rω"
+	},
+	{
+		linear: "acceleration a",
+		rotational: "angular acceleration α",
+		relation: "a = rα"
+	},
+	{
+		linear: "mass m",
+		rotational: "moment of inertia I",
+		relation: "I = Σmr²"
+	},
+	{
+		linear: "force F",
+		rotational: "torque τ",
+		relation: "τ = Iα"
+	},
+	{
+		linear: "momentum p = mv",
+		rotational: "angular momentum L = Iω",
+		relation: "L = mvr"
+	},
+	{
+		linear: "kinetic energy ½mv²",
+		rotational: "rotational KE ½Iω²",
+		relation: ""
+	}
+];
+/**
+* The turning effect of one force: `τ = F r sin θ`.
+*
+* `θ` is between the force and the line from the axis to where it acts. Only the PERPENDICULAR
+* component turns anything; a force aimed straight at the hinge has no effect however large it is,
+* which is why you push a door at its edge and at right angles.
+*/
+function torque(force, distance, angleDeg = 90, sf = 3) {
+	const value = force * distance * Math.sin(toRadians(angleDeg));
+	return {
+		value,
+		worked: calc().step("\\tau = F r \\sin\\theta", "only the component at right angles to the arm turns anything").step(`\\tau = ${texSigFigs(force, sf)} \\times ${texSigFigs(distance, sf)} \\times \\sin ${texSigFigs(angleDeg, sf)}^\\circ = ${texSigFigs(value, sf)}\\ \\mathrm{N\\,m}`, angleDeg % 180 === 0 ? "aimed straight along the arm, so it turns nothing at all however hard you push" : void 0).done(value)
+	};
+}
+/**
+* The moment of a couple: `M = F d`, with `d` the perpendicular distance BETWEEN the two forces.
+*
+* Not `F × distance from some axis`, because there is no axis in it. The moment of a couple is the
+* same about every point in the plane, which is the property that makes it a couple rather than two
+* separate moments, and it is why the answer never asks you where the pivot is.
+*/
+function couple(force, separation, sf = 3) {
+	const value = force * separation;
+	return {
+		value,
+		worked: calc().step("M = F d", "d is the perpendicular distance between the two forces, and the moment is the same about EVERY point").step(`M = ${texSigFigs(force, sf)} \\times ${texSigFigs(separation, sf)} = ${texSigFigs(value, sf)}\\ \\mathrm{N\\,m}`, "the resultant force is zero, so it does not go anywhere. It only turns").done(value)
+	};
+}
+/**
+* The force a second couple needs to balance the first.
+*
+* Two couples balance when their moments are equal and opposite, so a wide couple can be held by a
+* small force and a narrow one needs a large force. That is the whole of the rectangular-plate
+* question these chapters set.
+*/
+function balancingCouple(known, separation, sf = 3) {
+	if (separation <= 0) throw new Error("The second couple needs a positive separation.");
+	const force = known.force * known.separation / separation;
+	return {
+		force,
+		worked: calc().step("M_1 = M_2", "in balance the two moments are equal in size and opposite in sense").step(`${texSigFigs(known.force, sf)} \\times ${texSigFigs(known.separation, sf)} = P \\times ${texSigFigs(separation, sf)}`).step(`P = ${texSigFigs(force, sf)}\\ \\mathrm{N}`, "a couple acting over a shorter distance needs a proportionally bigger force").done(force)
+	};
+}
+/**
+* `τ = Iα`: Newton's second law, rotated.
+*
+* Give any two and it returns the third. The same torque produces very different accelerations on
+* bodies of the same mass shaped differently, which is the thing moment of inertia is FOR.
+*/
+function angularAcceleration(torqueValue, inertia, sf = 3) {
+	if (inertia <= 0) throw new Error("Moment of inertia must be positive.");
+	const alpha = torqueValue / inertia;
+	return {
+		alpha,
+		worked: calc().step("\\tau = I\\alpha", "F = ma with every quantity replaced by its rotational counterpart").step(`\\alpha = \\frac{${texSigFigs(torqueValue, sf)}}{${texSigFigs(inertia, sf)}} = ${texSigFigs(alpha, sf)}\\ \\mathrm{rad\\,s^{-2}}`, "the same torque spins a hoop far more slowly than a disc of equal mass").done(alpha)
+	};
+}
+/**
+* The torque needed to change angular momentum at a given rate: `τ = dL/dt`.
+*
+* The more fundamental statement, and the one that survives when the moment of inertia itself is
+* changing, which `τ = Iα` does not. Supplied as a rate rather than as a derivative because that is
+* how the question arrives: "the angular momentum changes by this much in this time".
+*/
+const torqueFromRate = (deltaL, deltaT) => {
+	if (deltaT <= 0) throw new Error("The interval must be positive.");
+	return deltaL / deltaT;
+};
+
+//#endregion
+export { ROTATIONAL_ANALOGUE, angularAcceleration, balancingCouple, couple, torque, torqueFromRate };

package/dist/physics/vectors.d.mts

@@ -0,0 +1,64 @@
+import { Worked } from "../core/worked.mjs";
+
+//#region src/physics/vectors.d.ts
+declare const DEG: number;
+declare const toRadians: (deg: number) => number;
+declare const toDegrees: (rad: number) => number;
+/** A vector as a pair of perpendicular components, in whatever unit the magnitude was in. */
+interface Components {
+  /** Along the horizontal. */
+  readonly x: number;
+  /** Along the vertical, positive UPWARDS. See {@link SignConvention} to reinterpret. */
+  readonly y: number;
+}
+/** A vector as a size and a direction. */
+interface Polar {
+  readonly magnitude: number;
+  /** Above the horizontal, in degrees. Negative points below it. */
+  readonly angleDeg: number;
+}
+/**
+ * Split a magnitude at an angle above the horizontal into horizontal and vertical parts.
+ *
+ * Rounding matters here in a way it does not elsewhere: `Math.cos(Math.PI / 2)` is 6.1e-17, not 0,
+ * and a horizontal component of 6.1e-17 propagates into a range of 1.2e-16 m, which prints as
+ * `1.22 × 10^-16 m` in a derivation a student is reading. A vertical launch has zero range and the
+ * working should say zero.
+ */
+declare function resolve(magnitude: number, angleDeg: number): Components;
+/** Components back to a magnitude and a direction: the reverse of {@link resolve}. */
+declare function compose(x: number, y: number): Polar;
+/**
+ * The working for a resolution, for a lesson that wants to show it rather than assert it.
+ *
+ * The first line is the definition, not the substitution, because the point being taught is that
+ * the components come from a right-angled triangle whose hypotenuse is the vector.
+ */
+declare function resolveSteps(magnitude: number, angleDeg: number, unit: string, sf?: number): Worked;
+/** Which vertical direction the numbers in an equation are measured as positive. */
+type Positive = 'up' | 'down';
+/**
+ * A declared choice of positive direction, and the signed values that follow from it.
+ *
+ * Everything a vertical-motion question gives you arrives as a magnitude plus a direction in words
+ * ("thrown upwards at 20 m/s from 10 m up, gravity 9.8 downwards"). This turns those words into
+ * the signed numbers SUVAT needs, once, in a way that can be shown and flipped.
+ */
+declare class SignConvention {
+  readonly positive: Positive;
+  constructor(positive: Positive);
+  /** `+1` when the given direction is the positive one, `−1` when it opposes it. */
+  sign(direction: Positive): 1 | -1;
+  /** A magnitude, signed for the direction it acts in. */
+  signed(magnitude: number, direction: Positive): number;
+  /** Gravity's acceleration under this convention: negative if up is positive. */
+  gravity(g?: number): number;
+  /** The other choice, for a lab that lets a learner flip it. */
+  flipped(): SignConvention;
+  /** A sentence a lesson can print: "Taking up as positive, g = −9.8 m/s²." */
+  describe(g?: number): string;
+}
+declare const upPositive: () => SignConvention;
+declare const downPositive: () => SignConvention;
+//#endregion
+export { Components, DEG, Polar, Positive, SignConvention, compose, downPositive, resolve, resolveSteps, toDegrees, toRadians, upPositive };

package/dist/physics/vectors.mjs

@@ -0,0 +1,114 @@
+import { calc, texSigFigs } from "../core/worked.mjs";
+
+//#region src/physics/vectors.ts
+/**
+* Resolving a vector into components, and the sign convention that decides what the components
+* mean.
+*
+* Two separate ideas live here and they are usually taught as one, which is why they confuse
+* people.
+*
+* The first is geometry and has no physics in it: a magnitude at an angle is the same thing as a
+* pair of perpendicular components, `u cos θ` along and `u sin θ` across. That is true of a
+* velocity, a force, a displacement, or a ladder against a wall.
+*
+* The second is bookkeeping: before any of those components can go into an equation, somebody has
+* to say which direction counts as positive. Nothing in the world decides this. A ball thrown
+* upwards has `u = +20, a = −9.8` if up is positive and `u = −20, a = +9.8` if down is positive,
+* and BOTH give the same height at the same time, because the answer is a physical fact and the
+* sign is a choice of description. Textbook chapters that print one worked solution per convention
+* (up-positive here, down-positive there) leave students believing there are two physics.
+*
+* So {@link SignConvention} is a first-class object. A lab can let a learner flip it and watch the
+* numbers in the equation change while the trajectory does not move, which is the moment the idea
+* lands.
+*
+* Pure: no React, no pixels.
+*/
+const DEG = Math.PI / 180;
+const toRadians = (deg) => deg * DEG;
+const toDegrees = (rad) => rad / DEG;
+/**
+* Split a magnitude at an angle above the horizontal into horizontal and vertical parts.
+*
+* Rounding matters here in a way it does not elsewhere: `Math.cos(Math.PI / 2)` is 6.1e-17, not 0,
+* and a horizontal component of 6.1e-17 propagates into a range of 1.2e-16 m, which prints as
+* `1.22 × 10^-16 m` in a derivation a student is reading. A vertical launch has zero range and the
+* working should say zero.
+*/
+function resolve(magnitude, angleDeg) {
+	const a = toRadians(angleDeg);
+	return {
+		x: snap(magnitude * Math.cos(a), magnitude),
+		y: snap(magnitude * Math.sin(a), magnitude)
+	};
+}
+/** Components back to a magnitude and a direction: the reverse of {@link resolve}. */
+function compose(x, y) {
+	return {
+		magnitude: Math.hypot(x, y),
+		angleDeg: toDegrees(Math.atan2(y, x))
+	};
+}
+/**
+* Kill the floating-point dust that trigonometry leaves at the quarter turns.
+*
+* The threshold is RELATIVE to the magnitude being resolved, and that is not a refinement. A fixed
+* 1e-12 works for a vector of size 1 and quietly stops working as the numbers grow: `cos(pi/2)` is
+* 6.1e-17, so a force of 1e6 N at 90 degrees leaves a horizontal component of 6.1e-11, which sails
+* past an absolute cut-off and goes on to report that a perpendicular force did POSITIVE work. That
+* is a visible wrong answer rather than an ugly printout, which is what the absolute version was
+* guarding against. Scaling the threshold makes the guard hold at every size.
+*/
+function snap(value, scale = 1) {
+	return Math.abs(value) < Math.abs(scale) * 1e-12 ? 0 : value;
+}
+/**
+* The working for a resolution, for a lesson that wants to show it rather than assert it.
+*
+* The first line is the definition, not the substitution, because the point being taught is that
+* the components come from a right-angled triangle whose hypotenuse is the vector.
+*/
+function resolveSteps(magnitude, angleDeg, unit, sf = 3) {
+	const { x, y } = resolve(magnitude, angleDeg);
+	const u = `\\ \\mathrm{${unit}}`;
+	return calc().step(`u_x = u\\cos\\theta, \\quad u_y = u\\sin\\theta`, "the vector is the hypotenuse of a right-angled triangle").step(`u = ${texSigFigs(magnitude, sf)}${u}, \\quad \\theta = ${texSigFigs(angleDeg, sf)}^\\circ`).step(`u_x = ${texSigFigs(magnitude, sf)}\\cos ${texSigFigs(angleDeg, sf)}^\\circ = ${texSigFigs(x, sf)}${u}`).step(`u_y = ${texSigFigs(magnitude, sf)}\\sin ${texSigFigs(angleDeg, sf)}^\\circ = ${texSigFigs(y, sf)}${u}`).done(Math.hypot(x, y));
+}
+/**
+* A declared choice of positive direction, and the signed values that follow from it.
+*
+* Everything a vertical-motion question gives you arrives as a magnitude plus a direction in words
+* ("thrown upwards at 20 m/s from 10 m up, gravity 9.8 downwards"). This turns those words into
+* the signed numbers SUVAT needs, once, in a way that can be shown and flipped.
+*/
+var SignConvention = class SignConvention {
+	positive;
+	constructor(positive) {
+		this.positive = positive;
+	}
+	/** `+1` when the given direction is the positive one, `−1` when it opposes it. */
+	sign(direction) {
+		return direction === this.positive ? 1 : -1;
+	}
+	/** A magnitude, signed for the direction it acts in. */
+	signed(magnitude, direction) {
+		return this.sign(direction) * Math.abs(magnitude);
+	}
+	/** Gravity's acceleration under this convention: negative if up is positive. */
+	gravity(g = 9.8) {
+		return this.signed(g, "down");
+	}
+	/** The other choice, for a lab that lets a learner flip it. */
+	flipped() {
+		return new SignConvention(this.positive === "up" ? "down" : "up");
+	}
+	/** A sentence a lesson can print: "Taking up as positive, g = −9.8 m/s²." */
+	describe(g = 9.8) {
+		return `Taking ${this.positive} as positive, g = ${this.gravity(g)} m/s².`;
+	}
+};
+const upPositive = () => new SignConvention("up");
+const downPositive = () => new SignConvention("down");
+
+//#endregion
+export { DEG, SignConvention, compose, downPositive, resolve, resolveSteps, toDegrees, toRadians, upPositive };

package/dist/quantity/index.d.mts

@@ -0,0 +1,119 @@
+//#region src/quantity/index.d.ts
+/**
+ * quantity, a number that knows its unit.
+ *
+ * The model: every quantity is stored as its value in SI BASE UNITS plus a dimension vector over
+ * (kg, m, s, mol, K, A). A unit string is a recipe for converting to that pair, so arithmetic is
+ * ordinary arithmetic on the SI values and integer addition on the exponents:
+ *
+ *   a · b  →  si = a.si · b.si,   dim = a.dim + b.dim
+ *   a / b  →  si = a.si / b.si,   dim = a.dim − b.dim
+ *   a ± b  →  requires a.dim = b.dim
+ *
+ * Why this matters more than it looks. "Choose the right formula" is, operationally, "choose the
+ * one whose units cancel to the unit the answer is in", and cm³-against-dm³ is the single most
+ * common arithmetic error in A-level chemistry. Under this model that error cannot be made:
+ *
+ *   qty(0.100, 'mol/dm3').times(qty(24.50, 'cm3'))   →   2.45e-3 mol
+ *
+ * is simply correct, because both volumes reduce to m³ and the factors cancel. (An earlier plan
+ * said this case should THROW, on the grounds that cm³ "is not" dm³. That would be a worse design:
+ * it rejects a valid calculation and leaves the author to do the conversion by hand, which is the
+ * step that goes wrong.) What does throw is genuine nonsense: adding a mass to a volume, or asking
+ * for a mass in dm³.
+ *
+ * SCOPE, deliberately small: dimensional analysis over a fixed table of the units the Cambridge
+ * syllabuses actually use. Not a general units library, not arbitrary dimensional algebra, no
+ * user-defined units. The whole of A-level chemistry and physics fits in the table below.
+ *
+ * Pure: no React, no pixels.
+ */
+/** SI base dimensions. Everything in the table reduces to integer powers of these. */
+declare const BASE: readonly ["kg", "m", "s", "mol", "K", "A"];
+type Base = (typeof BASE)[number];
+/** Integer powers of the base dimensions. Absent key = power 0. */
+type Dimension = Readonly<Partial<Record<Base, number>>>;
+declare const DIMENSIONLESS: Dimension;
+declare const mulDim: (a: Dimension, b: Dimension) => Dimension;
+declare const divDim: (a: Dimension, b: Dimension) => Dimension;
+/** Raise a dimension to an integer power. A fractional power is legal only if it leaves every
+ *  exponent an integer, which is what makes `sqrt(Ka·c)` work and `sqrt(mol)` fail. */
+declare function powDim(a: Dimension, n: number): Dimension;
+declare const sameDim: (a: Dimension, b: Dimension) => boolean;
+declare const isDimensionless: (a: Dimension) => boolean;
+/** For error messages, where "1" would read as a number rather than as "has no units". */
+declare const describeDimension: (d: Dimension) => string;
+/**
+ * "kg·m^2/s^2·mol": readable in an error message AND parseable by `parseUnit`.
+ *
+ * Both properties are required. It names the dimension in messages, and it also names the unit of
+ * a quantity produced by arithmetic, which is then re-read the next time that quantity is used. An
+ * earlier version emitted `m2`, which reads back as an unknown unit rather than as m², so a
+ * perfectly good result became unusable one operation later.
+ */
+declare function formatDimension(d: Dimension): string;
+interface ResolvedUnit {
+  readonly dim: Dimension;
+  readonly factor: number;
+  readonly offset?: number;
+}
+/**
+ * Resolve a unit string to a dimension and a factor.
+ *
+ * Grammar: atoms separated by `·`, `*` or a space are multiplied; **every** segment after a `/` is
+ * a denominator, so `J/K/mol` is J·K⁻¹·mol⁻¹. That reading is the chemistry convention and it is
+ * stated here because `a/b/c` is genuinely ambiguous in general.
+ *
+ * An atom may carry an integer exponent written with a caret: `mol^2`, `dm3^2` (which is dm⁶, the
+ * denominator of a Ksp for a 1:2 salt). The caret is REQUIRED rather than optional, because a
+ * trailing digit is already part of the name in `dm3` and `cm3`, so `dm6` would have to be read as
+ * both a name and a power.
+ */
+declare function parseUnit(spec: string): ResolvedUnit;
+/** The units this kernel knows, for an error message or an editor. */
+declare const knownUnits: () => string[];
+/**
+ * A value with a unit. Immutable: every operation returns a new Quantity.
+ *
+ * `si` is the value in SI base units and is the single source of truth; `unit` is only how it is
+ * currently being displayed.
+ */
+declare class Quantity {
+  readonly si: number;
+  readonly dim: Dimension;
+  readonly unit: string;
+  /** True only for a Celsius temperature. Carried rather than re-derived: see `requireScale`. */
+  private readonly onScale;
+  private constructor();
+  static of(value: number, unit: string): Quantity;
+  /** Build directly from an SI value, naming the unit from the dimension. */
+  static fromSI(si: number, dim: Dimension): Quantity;
+  /** The number, expressed in `this.unit`. */
+  get value(): number;
+  /** The number, expressed in `unit`. Throws if the dimensions differ. */
+  in(unit: string): number;
+  /** The same quantity, displayed in `unit`. */
+  to(unit: string): Quantity;
+  private requireScale;
+  times(other: Quantity | number): Quantity;
+  over(other: Quantity | number): Quantity;
+  plus(other: Quantity): Quantity;
+  /**
+   * Note what this CANNOT do: subtract two Celsius temperatures. The SI difference would be right
+   * (a kelvin interval) but the result would be displayed back on the Celsius scale, where 12.5 K
+   * reads as −260.65 °C. `requireScale` refuses it, and `.to('K')` on both sides is the fix.
+   */
+  minus(other: Quantity): Quantity;
+  pow(n: number): Quantity;
+  private requireSame;
+  /** Equal within a RELATIVE tolerance (default 1e-9), after reducing both to SI. */
+  equals(other: Quantity, tol?: number): boolean;
+  /** "2.45e-3 mol", at `sf` significant figures. */
+  toString(sf?: number): string;
+}
+/** `qty(24.50, 'cm3')`. */
+declare const qty: (value: number, unit: string) => Quantity;
+/** The SI-coherent name for a dimension: 'mol', 'J', or a composed 'kg·m2/s2'. */
+declare function canonicalUnit(dim: Dimension): string;
+//#endregion
+export { Base, DIMENSIONLESS, Dimension, Quantity, canonicalUnit, describeDimension, divDim, formatDimension, isDimensionless, knownUnits, mulDim, parseUnit, powDim, qty, sameDim };