@classytic/stage 0.3.0 → 0.4.0

package/dist/thermo/calorimetry.mjs

@@ -0,0 +1,345 @@
+import { JOULES_PER_CALORIE, STANDARD_GRAVITY } from "../core/constants.mjs";
+
+//#region src/thermo/calorimetry.ts
+/**
+* Calorimetry: heat in, temperature and phase out.
+*
+* THE MODEL. Energy delivered to a body goes into exactly one of two things at
+* any moment, and which one depends only on whether it is sitting at a
+* transition temperature:
+*
+*   warming a phase    q = m·c·Δθ     temperature rises
+*   changing phase     q = m·L        temperature is FLAT
+*
+* Everything here follows from putting those two in a row. A body's ENTHALPY
+* LADDER is the alternating sequence of sloped runs and flat plateaus from a
+* cold datum up to any temperature, and once you have the ladder you can ask
+* either direction: how much heat to reach this temperature, or what
+* temperature this much heat reaches.
+*
+* THE METHOD, and why it is exact. Total enthalpy H(θ) is piecewise LINEAR in
+* temperature, with an upward jump of m·L at each transition. So the mixture
+* problem, find the θ at which the bodies' enthalpies sum to what they started
+* with, is the inversion of a piecewise-linear monotone function. That is
+* solved by walking the brackets and doing one division, with no iteration and
+* no tolerance. Bisection would also work and would be worse: it converges
+* slowly exactly where the interesting answers are, at the plateaus, because
+* there the function is flat in the inverse direction.
+*
+* This matters because it is what lets the solver answer the question a student
+* actually cannot do by hand: mix ice below freezing with water above it, and
+* the outcome is a case analysis (all ice, ice and water at 0 °C, all water)
+* that the algebra hides. Here it falls out of which bracket the answer lands
+* in.
+*
+* UNITS: SI. Mass in kg, specific heat capacity in J/(kg·K), latent heat in
+* J/kg, energy in joules. Temperatures are in DEGREES CELSIUS, because every
+* transition point a lesson names is quoted that way and the differences that
+* appear in m·c·Δθ are identical in either scale.
+*
+* SCOPE. One-dimensional in temperature: no pressure dependence, so the boiling
+* point is a constant rather than a function of the ambient pressure, and
+* sublimation is not modelled. Specific heats are constant within a phase.
+*/
+/**
+* Materials that appear in the standard problems.
+*
+* Water's numbers are worth reading as a set: the latent heat of vaporisation
+* is 2.26 MJ/kg against 4.18 kJ/(kg·K) for warming, so boiling a kilogram away
+* costs the same as heating it through 540 °C. That ratio is the whole reason
+* sweating works and the reason a steam burn is worse than a boiling-water
+* burn, and it is visible in the table before any lab draws it.
+*/
+const MATERIALS = {
+	water: {
+		name: "Water",
+		cSolid: 2090,
+		cLiquid: 4180,
+		cGas: 2010,
+		latentFusion: 334e3,
+		latentVaporisation: 226e4,
+		meltingPointC: 0,
+		boilingPointC: 100
+	},
+	ethanol: {
+		name: "Ethanol",
+		cSolid: 1200,
+		cLiquid: 2440,
+		cGas: 1420,
+		latentFusion: 108e3,
+		latentVaporisation: 855e3,
+		meltingPointC: -114,
+		boilingPointC: 78
+	},
+	lead: {
+		name: "Lead",
+		cSolid: 130,
+		cLiquid: 140,
+		cGas: 140,
+		latentFusion: 24500,
+		latentVaporisation: 866e3,
+		meltingPointC: 327,
+		boilingPointC: 1749
+	},
+	iron: {
+		name: "Iron",
+		cSolid: 450,
+		cLiquid: 820,
+		cGas: 820,
+		latentFusion: 247e3,
+		latentVaporisation: 609e4,
+		meltingPointC: 1538,
+		boilingPointC: 2862
+	},
+	copper: {
+		name: "Copper",
+		cSolid: 385,
+		cLiquid: 495,
+		cGas: 495,
+		latentFusion: 209e3,
+		latentVaporisation: 473e4,
+		meltingPointC: 1085,
+		boilingPointC: 2562
+	},
+	aluminium: {
+		name: "Aluminium",
+		cSolid: 900,
+		cLiquid: 1180,
+		cGas: 1180,
+		latentFusion: 397e3,
+		latentVaporisation: 105e5,
+		meltingPointC: 660,
+		boilingPointC: 2470
+	}
+};
+const finite = (value, what) => {
+	if (!Number.isFinite(value)) throw new RangeError(`${what} must be a finite number.`);
+	return value;
+};
+const positive = (value, what) => {
+	if (!Number.isFinite(value) || value <= 0) throw new RangeError(`${what} must be positive.`);
+	return value;
+};
+/**
+* Heat to warm a mass through a temperature change: q = m·c·Δθ.
+*
+* Δθ is SIGNED, so cooling returns a negative number rather than an absolute
+* one. That is what makes the mixture bookkeeping add up to zero instead of
+* needing a hand-placed minus sign on whichever body happened to be hotter.
+*/
+function heatToWarmJ(massKg, specificHeat, deltaT) {
+	return positive(massKg, "Mass") * positive(specificHeat, "Specific heat capacity") * finite(deltaT, "A temperature change");
+}
+/** Heat to change the state of a mass at its transition temperature: q = m·L. */
+function heatToChangeStateJ(massKg, latentHeat) {
+	return positive(massKg, "Mass") * positive(latentHeat, "Latent heat");
+}
+/** The inverse of q = m·c·Δθ, solved for the temperature change. */
+function temperatureRiseK(heatJ, massKg, specificHeat) {
+	return finite(heatJ, "Heat") / (positive(massKg, "Mass") * positive(specificHeat, "Specific heat capacity"));
+}
+/** The inverse of q = m·c·Δθ, solved for the specific heat capacity. */
+function specificHeatFromJ(heatJ, massKg, deltaT) {
+	const dT = finite(deltaT, "A temperature change");
+	if (dT === 0) throw new RangeError("No temperature change, so this measurement cannot determine a specific heat capacity.");
+	return finite(heatJ, "Heat") / (positive(massKg, "Mass") * dT);
+}
+/**
+* The water equivalent of a calorimeter, kg: the mass of water with the same
+* heat capacity.
+*
+* Lets a calorimeter be folded into a mixture as if it were more water, which
+* is exactly how the textbook method handles it.
+*/
+function waterEquivalentKg(massKg, specificHeat) {
+	return positive(massKg, "Mass") * positive(specificHeat, "Specific heat capacity") / MATERIALS.water.cLiquid;
+}
+/**
+* The enthalpy of a mass of material at temperature θ, J, measured from a datum
+* of absolute zero with the material solid.
+*
+* The datum is arbitrary and cancels out of every difference, which is the only
+* reason it is allowed to be as unphysical as "solid water at −273 °C". What
+* matters is that the SAME datum is used for every body in a mixture.
+*
+* At a transition temperature this returns the value approached from BELOW, so
+* `enthalpyJ(m, water, 0)` is solid ice at 0 °C with none of it melted. The
+* jump of m·L lives between this value and `enthalpyJ` an epsilon higher, and
+* the mixture solver resolves partial melting by landing inside that jump
+* rather than by nudging the temperature.
+*/
+function enthalpyJ(massKg, material, celsius) {
+	const m = positive(massKg, "Mass");
+	const theta = finite(celsius, "A temperature");
+	const datum = -273.15;
+	const { meltingPointC: mp, boilingPointC: bp } = material;
+	if (theta <= mp) return m * material.cSolid * (theta - datum);
+	let total = m * material.cSolid * (mp - datum) + m * material.latentFusion;
+	if (theta <= bp) return total + m * material.cLiquid * (theta - mp);
+	total += m * material.cLiquid * (bp - mp) + m * material.latentVaporisation;
+	return total + m * material.cGas * (theta - bp);
+}
+/** The phase a material is in at a temperature, taking a transition point as the lower phase. */
+function phaseAt(material, celsius) {
+	if (celsius <= material.meltingPointC) return "solid";
+	if (celsius <= material.boilingPointC) return "liquid";
+	return "gas";
+}
+/**
+* The equilibrium temperature of bodies placed in a perfectly insulated
+* container, and what state each ends in.
+*
+* Solves ΣH_i(θ) = ΣH_i(θ_i) exactly, by walking the piecewise-linear total
+* enthalpy curve bracket by bracket. The brackets are the distinct transition
+* temperatures of the materials present; inside one, every body is in a fixed
+* phase and the total is linear, so the crossing point is one division.
+*
+* ASSUMES the container itself has no heat capacity. Fold a real calorimeter in
+* as an extra body, or use `waterEquivalentKg` to express it as more water.
+*/
+function mixtureEquilibrium(bodies) {
+	if (bodies.length === 0) throw new RangeError("A mixture needs at least one body.");
+	const target = bodies.reduce((sum, b) => sum + enthalpyJ(b.massKg, b.material, finite(b.temperatureC, "A starting temperature")), 0);
+	const breaks = [...new Set(bodies.flatMap((b) => [b.material.meltingPointC, b.material.boilingPointC]))].sort((a, b) => a - b);
+	const totalAt = (theta) => bodies.reduce((sum, b) => sum + enthalpyJ(b.massKg, b.material, theta), 0);
+	const totalJustAbove = (theta) => bodies.reduce((sum, b) => {
+		let h = enthalpyJ(b.massKg, b.material, theta);
+		if (b.material.meltingPointC === theta) h += b.massKg * b.material.latentFusion;
+		if (b.material.boilingPointC === theta) h += b.massKg * b.material.latentVaporisation;
+		return sum + h;
+	}, 0);
+	let finalTemperatureC = null;
+	let lower = Number.NEGATIVE_INFINITY;
+	for (const theta of breaks) {
+		if (target < totalAt(theta)) {
+			finalTemperatureC = solveWithin(bodies, target, lower, theta);
+			break;
+		}
+		if (target <= totalJustAbove(theta)) {
+			finalTemperatureC = theta;
+			break;
+		}
+		lower = theta;
+	}
+	if (finalTemperatureC === null) finalTemperatureC = solveWithin(bodies, target, lower, Number.POSITIVE_INFINITY);
+	const results = bodies.map((b) => {
+		const start = enthalpyJ(b.massKg, b.material, b.temperatureC);
+		const end = shareOfJump(b, bodies, target, finalTemperatureC);
+		return {
+			label: b.label,
+			heatGainedJ: end.enthalpy - start,
+			startPhase: phaseAt(b.material, b.temperatureC),
+			endPhase: end.phase,
+			transitionFraction: end.fraction
+		};
+	});
+	return {
+		finalTemperatureC,
+		bodies: results,
+		netHeatJ: results.reduce((sum, r) => sum + r.heatGainedJ, 0),
+		partialTransition: results.some((r) => r.transitionFraction !== null)
+	};
+}
+/**
+* Solve for the temperature within one sloped run of the enthalpy curve, given
+* the bracket `(lower, upper)` the answer lies in.
+*
+* Inside a run every body's phase is fixed, so the slope is Σ m·c over the
+* current phases and the total enthalpy is a straight line. The slope is read
+* off the materials directly rather than by differencing the curve: a finite
+* difference would need a step small enough not to cross the next break, and
+* "small enough" is a tolerance this problem does not otherwise need.
+*
+* One end of the bracket is always finite, because every material contributes
+* two breaks, so the run is anchored at whichever end exists. The outermost
+* runs are unbounded on one side and that side is never the anchor.
+*/
+function solveWithin(bodies, target, lower, upper) {
+	const at = (theta) => bodies.reduce((sum, b) => sum + enthalpyJ(b.massKg, b.material, theta), 0);
+	const probe = Number.isFinite(lower) ? Number.isFinite(upper) ? (lower + upper) / 2 : lower + 1 : upper - 1;
+	const slope = bodies.reduce((sum, b) => {
+		const phase = phaseAt(b.material, probe);
+		const c = phase === "solid" ? b.material.cSolid : phase === "liquid" ? b.material.cLiquid : b.material.cGas;
+		return sum + b.massKg * c;
+	}, 0);
+	if (slope <= 0) throw new RangeError("The mixture has no heat capacity, so it has no equilibrium temperature.");
+	if (Number.isFinite(upper)) return upper - (at(upper) - target) / slope;
+	return lower + (target - bodies.reduce((sum, b) => {
+		let h = enthalpyJ(b.massKg, b.material, lower);
+		if (b.material.meltingPointC === lower) h += b.massKg * b.material.latentFusion;
+		if (b.material.boilingPointC === lower) h += b.massKg * b.material.latentVaporisation;
+		return sum + h;
+	}, 0)) / slope;
+}
+/**
+* One body's share of a partial transition, and the enthalpy it ended with.
+*
+* When the mixture settles inside a jump, the heat available has to be split
+* across every body transitioning at that temperature. They share it in
+* proportion to the latent heat each one needs, which is the only division that
+* leaves them all at the same fraction: physically they are in contact at one
+* temperature, so no body can get ahead of another.
+*/
+function shareOfJump(body, bodies, target, finalC) {
+	const base = enthalpyJ(body.massKg, body.material, finalC);
+	const latentOf = (b) => b.material.meltingPointC === finalC ? b.massKg * b.material.latentFusion : b.material.boilingPointC === finalC ? b.massKg * b.material.latentVaporisation : 0;
+	const jumpTotal = bodies.reduce((sum, b) => sum + latentOf(b), 0);
+	const mine = latentOf(body);
+	if (jumpTotal === 0 || mine === 0) return {
+		enthalpy: base,
+		phase: phaseAt(body.material, finalC),
+		fraction: null
+	};
+	const floor = bodies.reduce((sum, b) => sum + enthalpyJ(b.massKg, b.material, finalC), 0);
+	const fraction = Math.max(0, Math.min(1, (target - floor) / jumpTotal));
+	const phase = fraction >= 1 ? body.material.meltingPointC === finalC ? "liquid" : "gas" : phaseAt(body.material, finalC);
+	return {
+		enthalpy: base + fraction * mine,
+		phase,
+		fraction: fraction > 0 && fraction < 1 ? fraction : null
+	};
+}
+/**
+* The temperature rise when a fraction of a moving body's kinetic energy turns
+* into heat inside it: f·½mv² = m·c·Δθ.
+*
+* The mass cancels, which is the point and the thing students are surprised by:
+* a bullet's temperature rise on impact depends on its SPEED and its material,
+* not on how big it is. `fraction` is how much of the energy stays in the body
+* rather than going into the target, the air, or sound.
+*/
+function temperatureRiseFromSpeedK(speedMs, specificHeat, fraction = 1) {
+	if (fraction < 0 || fraction > 1) throw new RangeError("The fraction retained must be between 0 and 1.");
+	const v = finite(speedMs, "Speed");
+	return fraction * .5 * v * v / positive(specificHeat, "Specific heat capacity");
+}
+/**
+* The temperature rise when a fraction of a falling body's potential energy
+* turns into heat inside it: f·mgh = m·c·Δθ.
+*
+* The mass cancels here too, so the answer depends only on the DROP. This is
+* Joule's paddle-wheel experiment read backwards, and the classic worked
+* example is the waterfall: the 4.2 kJ it takes to warm a kilogram of water by
+* one degree is the same energy as dropping it 428 m.
+*/
+function temperatureRiseFromDropK(heightM, specificHeat, fraction = 1, gravity = STANDARD_GRAVITY) {
+	if (fraction < 0 || fraction > 1) throw new RangeError("The fraction retained must be between 0 and 1.");
+	return fraction * gravity * finite(heightM, "A height") / positive(specificHeat, "Specific heat capacity");
+}
+/**
+* The mass melted when a fraction of a falling body's potential energy becomes
+* heat in it: f·mgh = m'·L.
+*
+* Unlike the two above, this one keeps the mass, because the answer is a mass.
+*/
+function massMeltedFromDropKg(massKg, heightM, latentHeat, fraction = 1, gravity = STANDARD_GRAVITY) {
+	if (fraction < 0 || fraction > 1) throw new RangeError("The fraction retained must be between 0 and 1.");
+	return fraction * positive(massKg, "Mass") * gravity * finite(heightM, "A height") / positive(latentHeat, "Latent heat");
+}
+/** Calories to joules, through the thermochemical definition. */
+const caloriesToJoules = (calories) => finite(calories, "An energy in calories") * JOULES_PER_CALORIE;
+/** Joules to calories, through the thermochemical definition. */
+const joulesToCalories = (joules) => finite(joules, "An energy in joules") / JOULES_PER_CALORIE;
+
+//#endregion
+export { MATERIALS, caloriesToJoules, enthalpyJ, heatToChangeStateJ, heatToWarmJ, joulesToCalories, massMeltedFromDropKg, mixtureEquilibrium, phaseAt, specificHeatFromJ, temperatureRiseFromDropK, temperatureRiseFromSpeedK, temperatureRiseK, waterEquivalentKg };

package/dist/thermo/cycles.d.mts

@@ -0,0 +1,142 @@
+import { GasState, ProcessResult } from "./processes.mjs";
+
+//#region src/thermo/cycles.d.ts
+type CycleDirection = 'engine' | 'refrigerator' | 'neutral';
+interface CycleSummary {
+  legs: ProcessResult[];
+  /** Net work done BY the gas over the cycle, J. Negative when work is done ON it. */
+  WnetJ: number;
+  /** Total heat absorbed on the legs that absorbed any, J (positive). */
+  QinJ: number;
+  /** Total heat rejected on the legs that rejected any, J (positive). */
+  QoutJ: number;
+  /**
+   * Clockwise on the p–V diagram is an engine, anticlockwise a refrigerator.
+   * Read from the sign of the net work rather than declared by the caller.
+   */
+  direction: CycleDirection;
+  /**
+   * Thermal efficiency W_net/Q_in, or `null` for a cycle that is not an engine.
+   *
+   * Null rather than a negative number, because "efficiency" is not defined for
+   * a refrigerator and returning something for it would invite the comparison
+   * that the coefficient of performance exists to avoid.
+   */
+  efficiency: number | null;
+  /** Q_cold/|W| for a refrigerator, or `null` for an engine. */
+  coefficientOfPerformance: number | null;
+  /** Q_hot/|W| for a heat pump: the same machine, sold for its warm end. */
+  heatPumpCOP: number | null;
+  /** ΣΔU round the cycle, J. Must be zero: reported so a lab can show it is. */
+  internalEnergyResidualJ: number;
+  /** ΣΔS round the cycle, J/K. Zero for a reversible cycle. */
+  entropyResidualJ: number;
+  /** How far the last leg ends from where the first began, as a fractional volume gap. */
+  closureError: number;
+}
+/**
+ * Totals, direction and figures of merit for any list of legs.
+ *
+ * Works on a cycle assembled from `runProcess`, on one built by hand, and on
+ * one that does not close, which is why the closure error is reported rather
+ * than enforced: a lab that lets a student build a cycle leg by leg needs to
+ * show them it has not closed yet, not refuse to draw it.
+ */
+declare function cycleSummary(legs: readonly ProcessResult[]): CycleSummary;
+/**
+ * Carnot efficiency, 1 − T_c/T_h.
+ *
+ * The ceiling on every heat engine working between these two temperatures,
+ * whatever its working substance and however it is built. That universality is
+ * the content of the second law, and it is why this depends on nothing but the
+ * two temperatures.
+ */
+declare function carnotEfficiency(hotK: number, coldK: number): number;
+/** Efficiency from the heats alone, 1 − Q_out/Q_in: the measurable version. */
+declare function efficiencyFromHeat(QinJ: number, QoutJ: number): number;
+/**
+ * Coefficient of performance of a refrigerator, T_c/(T_h − T_c).
+ *
+ * Not called an efficiency, and greater than 1 in any working fridge, because
+ * what you get out (heat removed from the cold space) is not the same kind of
+ * thing as what you put in (work). A COP of 5 moves five joules of heat per
+ * joule of electricity, and nothing is being created.
+ */
+declare function refrigeratorCOP(hotK: number, coldK: number): number;
+/**
+ * Coefficient of performance of a heat pump, T_h/(T_h − T_c).
+ *
+ * Exactly one more than the refrigerator's, because the heat delivered to the
+ * warm end is the heat taken from the cold end PLUS the work. That is why a
+ * heat pump beats a resistive heater: the electricity arrives as heat either
+ * way, and the pump also brings the outside in.
+ */
+declare function heatPumpCOP(hotK: number, coldK: number): number;
+/**
+ * Otto (petrol engine) efficiency, 1 − r^(1−γ), for a compression ratio r.
+ *
+ * Says compression ratio is the only thing that matters, which is true of the
+ * ideal cycle and is why the real limit is knock rather than thermodynamics.
+ */
+declare function ottoEfficiency(compressionRatio: number, gamma?: number): number;
+/**
+ * Diesel efficiency for a compression ratio r and cut-off ratio rc:
+ *
+ *   η = 1 − (1/r^(γ−1)) · (rc^γ − 1) / (γ(rc − 1))
+ *
+ * Always below an Otto cycle at the SAME compression ratio, which surprises
+ * people; the diesel wins in practice because it can use a compression ratio
+ * the petrol engine cannot.
+ */
+declare function dieselEfficiency(compressionRatio: number, cutoffRatio: number, gamma?: number): number;
+interface CarnotResult {
+  /** The four legs in order: hot isothermal expansion, adiabatic expansion,
+   *  cold isothermal compression, adiabatic compression back to the start. */
+  legs: ProcessResult[];
+  Th: number;
+  Tc: number;
+  /** Heat absorbed from the hot reservoir, J (>0). */
+  Qh: number;
+  /** Heat rejected to the cold reservoir, J (>0). */
+  Qc: number;
+  /** Net work done by the engine over the cycle, J ( = Qh − Qc = enclosed p–V area). */
+  Wnet: number;
+  /** Thermal efficiency = 1 − Tc/Th = Wnet/Qh. */
+  efficiency: number;
+}
+/**
+ * A Carnot cycle starting at `(V1, Th)`: isothermal expansion V1→V2 at Th, then
+ * adiabatic expansion to Tc, isothermal compression at Tc, and adiabatic
+ * compression back to the start. V3 and V4 are fixed by the closure condition.
+ */
+declare function carnotCycle(n: number, Th: number, Tc: number, V1: number, V2: number, gamma?: number): CarnotResult;
+/**
+ * An Otto cycle: adiabatic compression, isochoric heating (the spark),
+ * adiabatic expansion (the power stroke), isochoric cooling (the exhaust).
+ *
+ * `compressionRatio` is V_max/V_min, and `peakTemperatureK` is how hot the
+ * burning mixture gets, which is what sets the heat input.
+ */
+declare function ottoCycle(n: number, intakeK: number, peakTemperatureK: number, Vmax: number, compressionRatio: number, gamma?: number): ProcessResult[];
+/**
+ * A Stirling cycle: isothermal expansion at Th, isochoric cooling, isothermal
+ * compression at Tc, isochoric heating.
+ *
+ * Reaches Carnot efficiency only with a perfect regenerator, because the heat
+ * dumped on the cooling leg is exactly the heat needed on the heating leg. With
+ * no regenerator, `cycleSummary` counts that heat as fresh input and the
+ * efficiency drops sharply, which is the honest answer and the reason the
+ * regenerator was the invention.
+ */
+declare function stirlingCycle(n: number, Th: number, Tc: number, Vmin: number, Vmax: number, gamma?: number): ProcessResult[];
+/**
+ * The internal energy an ideal gas holds at a state, J, for reading a cycle's
+ * corners off a p–V diagram.
+ *
+ * Exists so a lab can label the corners of a cycle with U as well as p, V and
+ * T, which is what makes "ΔU round the loop is zero" visible rather than
+ * asserted.
+ */
+declare function stateInternalEnergyJ(state: GasState, gamma?: number): number;
+//#endregion
+export { CarnotResult, CycleDirection, CycleSummary, carnotCycle, carnotEfficiency, cycleSummary, dieselEfficiency, efficiencyFromHeat, heatPumpCOP, ottoCycle, ottoEfficiency, refrigeratorCOP, stateInternalEnergyJ, stirlingCycle };