@driftengine/chemistry 3.61.0

package/dist/library/biological.js

@@ -0,0 +1,229 @@
+/**
+ * `@driftengine/chemistry/library/biological` — decay, fermentation and the heat they make.
+ *
+ * **Every rate here is peaked rather than monotonic, and `§8.6` refuses Arrhenius structurally.** An
+ * enzyme-catalysed rate rises to an optimum and then collapses as the enzyme denatures; modelling
+ * decay with Arrhenius gives compost that gets hotter forever, which is the single most common
+ * mistake in this area and is worth making impossible rather than discouraged.
+ *
+ * **The two enthalpies are the published ones and neither is stored.** Aerobic respiration comes out
+ * at −2,802.7 kJ/mol against `§8.6`'s quoted 2,803, and fermentation at −68.9 against a textbook
+ * −68. That the ratio is forty is the whole reason fermentation is a survival strategy and
+ * respiration is a fire hazard.
+ *
+ * **Nothing decides the aerobic/anaerobic branch.** Aerobic decay has oxygen as a reactant, so a
+ * submerged parcel cannot run it and runs the methane path instead. A fallen log rots one way and a
+ * drowned one rots the other, out of mass action.
+ */
+import { KIND_BIOLOGICAL } from '../reaction/reaction.js';
+import { SHAPE_CYLINDER, SHAPE_SPHERE } from '../parcel/shells.js';
+import { massFractions } from '../substance/composition.js';
+import { wetComposition } from '../substance/substance.js';
+import { BOIL_WATER, COMMON_REACTIONS } from './common.js';
+export const DECAY_MESOPHILIC = 'decay-mesophilic';
+export const DECAY_THERMOPHILIC = 'decay-thermophilic';
+export const DECAY_ANAEROBIC = 'decay-anaerobic';
+export const FERMENT = 'ferment';
+/**
+ * The rate at the optimum, per second, and it is **back-derived from a measured self-heating rate**.
+ *
+ * A wet bale or a fresh heap warms at roughly twenty to thirty kelvin a day in its mesophilic phase,
+ * which is a measurement anyone with a compost thermometer can make. Working back through the
+ * enthalpy of respiration, the labile sugar fraction and the heat capacity of wet organic matter
+ * gives this. There is no published pre-exponential for "decay"; there is a published temperature.
+ */
+const MESOPHILIC_PEAK = 6e-5;
+const REACTIONS = [
+    ...COMMON_REACTIONS,
+    {
+        /*
+         * `C₆H₁₂O₆ + 6 O₂ → 6 CO₂ + 6 H₂O`, and the water is **liquid** because a compost heap is wet.
+         * That is what makes the derived enthalpy 2,803 kJ/mol rather than the 2,539 it would be if the
+         * water left as steam — and 2,803 is the figure `§8.6` quotes.
+         */
+        id: DECAY_MESOPHILIC,
+        reactants: [
+            { species: 'glucose', moles: 1 },
+            { species: 'O2', moles: 6 },
+        ],
+        products: [
+            { species: 'CO2', moles: 6 },
+            { species: 'H2O(l)', moles: 6 },
+        ],
+        kinetics: {
+            type: 'cardinal',
+            peak: MESOPHILIC_PEAK,
+            minimum: 273.15,
+            optimum: 308.15,
+            maximum: 318.15,
+        },
+        kind: KIND_BIOLOGICAL,
+    },
+    {
+        /*
+         * The same reaction, a different population. **It takes over exactly where the first one dies**,
+         * which is why a heap steams: the mesophiles heat it past their own maximum and hand it on.
+         * Nothing hands it on; two bands overlap by five kelvin and the rates do the rest.
+         */
+        id: DECAY_THERMOPHILIC,
+        reactants: [
+            { species: 'glucose', moles: 1 },
+            { species: 'O2', moles: 6 },
+        ],
+        products: [
+            { species: 'CO2', moles: 6 },
+            { species: 'H2O(l)', moles: 6 },
+        ],
+        kinetics: {
+            type: 'cardinal',
+            peak: MESOPHILIC_PEAK * 3,
+            minimum: 313.15,
+            optimum: 328.15,
+            maximum: 343.15,
+        },
+        kind: KIND_BIOLOGICAL,
+    },
+    {
+        /* The swamp-gas path: no oxygen consumed, so it is the only one a submerged parcel can run, and
+           it releases a fortieth of the heat — which is why a bog does not catch fire. */
+        id: DECAY_ANAEROBIC,
+        reactants: [{ species: 'glucose', moles: 1 }],
+        products: [
+            { species: 'CH4', moles: 3 },
+            { species: 'CO2', moles: 3 },
+        ],
+        kinetics: {
+            type: 'cardinal',
+            peak: 5e-6,
+            minimum: 283.15,
+            optimum: 310.15,
+            maximum: 318.15,
+        },
+        kind: KIND_BIOLOGICAL,
+    },
+    {
+        /* Yeast, and it dies above 40 °C. The ethanol it makes is the fuel library's fuel, so a cellar
+           that ferments and then catches is two libraries meeting with nothing between them. */
+        id: FERMENT,
+        reactants: [{ species: 'glucose', moles: 1 }],
+        products: [
+            { species: 'ethanol', moles: 2 },
+            { species: 'CO2', moles: 2 },
+        ],
+        kinetics: {
+            type: 'cardinal',
+            peak: 3e-4,
+            minimum: 278.15,
+            optimum: 303.15,
+            maximum: 313.15,
+        },
+        kind: KIND_BIOLOGICAL,
+    },
+];
+const DECAY = [DECAY_MESOPHILIC, DECAY_THERMOPHILIC, DECAY_ANAEROBIC];
+export const BIOLOGICAL = {
+    id: 'biological',
+    species: [],
+    reactions: REACTIONS,
+    substances: (species) => [
+        {
+            /* Half water by mass, which is what a heap has to be for anything to live in it. */
+            id: 'compost',
+            composition: wetComposition(species, massFractions(species, {
+                cellulose: 0.35,
+                hemicellulose: 0.2,
+                lignin: 0.2,
+                glucose: 0.1,
+                protein: 0.05,
+                ash: 0.1,
+            }), 1.0),
+            density: 400,
+            conductivity: { k0: 0.15, k1: 0.0003 },
+            shells: 3,
+            shape: SHAPE_SPHERE,
+            porosity: 0.6,
+            emissivity: 0.92,
+            reactions: [BOIL_WATER, ...DECAY],
+            appearance: {
+                albedo: [0.18, 0.14, 0.1],
+                charAlbedo: [0.03, 0.03, 0.03],
+                sootYield: 0.02,
+            },
+        },
+        {
+            /*
+             * **The one the design points at.** Twenty-five percent moisture is the dangerous band: wet
+             * enough to respire and dry enough that the water is not itself the heat sink that stops it.
+             * Low conductivity and low density mean a large bale keeps what it makes.
+             */
+            id: 'hay',
+            composition: wetComposition(species, massFractions(species, {
+                cellulose: 0.36,
+                hemicellulose: 0.26,
+                lignin: 0.16,
+                glucose: 0.06,
+                protein: 0.06,
+                ash: 0.1,
+            }), 0.25),
+            density: 130,
+            conductivity: { k0: 0.05, k1: 0.0001 },
+            shells: 3,
+            shape: SHAPE_CYLINDER,
+            porosity: 0.75,
+            emissivity: 0.9,
+            reactions: [BOIL_WATER, ...DECAY],
+            /* Cellulosic, so it catches on cellulosic terms once something gets it there. */
+            ignition: { pilotedSurfaceK: 623, autoSurfaceK: 773, criticalMassFlux: 0.0035 },
+            appearance: {
+                albedo: [0.58, 0.5, 0.28],
+                charAlbedo: [0.04, 0.04, 0.04],
+                sootYield: 0.015,
+            },
+        },
+        {
+            /* Living tissue, which is the same reactions running slowly enough to be called being alive. */
+            id: 'flesh',
+            composition: wetComposition(species, massFractions(species, {
+                protein: 0.7,
+                'triglyceride(saturated)': 0.15,
+                collagen: 0.08,
+                glucose: 0.05,
+                ash: 0.02,
+            }), 2.33),
+            density: 1010,
+            conductivity: { k0: 0.49, k1: 0.0005 },
+            shells: 4,
+            shape: SHAPE_SPHERE,
+            porosity: 0.05,
+            emissivity: 0.98,
+            reactions: [BOIL_WATER, ...DECAY],
+            appearance: {
+                albedo: [0.44, 0.16, 0.14],
+                charAlbedo: [0.05, 0.03, 0.02],
+                sootYield: 0.04,
+            },
+        },
+        {
+            /* Grape must: mostly sugar and water, and it ferments rather than decays because that is what
+               the rates say at cellar temperature with no air getting in. */
+            id: 'must',
+            composition: wetComposition(species, massFractions(species, {
+                glucose: 0.85,
+                fructose: 0.1,
+                protein: 0.02,
+                ash: 0.03,
+            }), 4.0),
+            density: 1080,
+            conductivity: { k0: 0.55, k1: 0.0005 },
+            shells: 2,
+            shape: SHAPE_SPHERE,
+            emissivity: 0.96,
+            reactions: [BOIL_WATER, FERMENT, DECAY_MESOPHILIC],
+            appearance: {
+                albedo: [0.32, 0.1, 0.16],
+                charAlbedo: [0.32, 0.1, 0.16],
+                sootYield: 0.01,
+            },
+        },
+    ],
+};

package/dist/library/common.d.ts

@@ -0,0 +1,26 @@
+import { type Reaction } from '../reaction/reaction.ts';
+export declare const MELT_ICE = "melt-ice";
+export declare const BOIL_WATER = "boil-water";
+export declare const BURN_METHANE = "burn-methane";
+export declare const BURN_CARBON_MONOXIDE = "burn-carbon-monoxide";
+export declare const BURN_HYDROGEN = "burn-hydrogen";
+export declare const BURN_ETHYLENE = "burn-ethylene";
+export declare const BURN_SOOT = "burn-soot";
+export declare const SOOT_METHANE = "soot-methane";
+export declare const OXIDISE_CHAR = "oxidise-char";
+export declare const OXIDISE_CHAR_RICH = "oxidise-char-rich";
+/** The gas-phase steps, which is what a `AtmosphereField` is given rather than a parcel. */
+export declare const GAS_REACTIONS: readonly string[];
+/**
+ * How much char goes to CO rather than CO₂ at a temperature, per Arthur's measured relation.
+ *
+ * **Nothing in the model calls this.** It is here so a test can assert that the two char reactions
+ * reproduce it, and so a reader can see what the two activation energies below mean. The relation
+ * itself is `§8.5`'s, and its consequence is the one the design cares about: a cool smoulder makes
+ * mostly CO₂ and a hot one makes mostly CO, so an oxygen-starved fire in a closed room produces
+ * carbon monoxide faster than an open one would.
+ */
+export declare function arthurRatio(temperature: number): number;
+export declare const COMMON_REACTIONS: readonly Reaction[];
+/** Every char and water reaction a solid needs, which is what a burnable substance declares. */
+export declare const SOLID_COMMON: readonly string[];

package/dist/library/common.js

@@ -0,0 +1,208 @@
+/**
+ * The reactions every family reaches through: water changing phase, gas burning, char oxidising.
+ *
+ * **Not an entry point.** A consumer imports a family and gets whatever of this it needs, so
+ * `library/mineral` never pulls in a methane flame.
+ *
+ * **The activation energies are literature; the pre-exponentials are order of magnitude.** A
+ * published single-step combustion rate law carries fractional reaction orders — Westbrook and
+ * Dryer give methane as `[CH₄]^−0.3·[O₂]^1.3` — and there is no exact conversion of that into the
+ * first-order mass action this solver runs. So `Ea` is the measured barrier and `A` is chosen to put
+ * the rate in the right decade at flame temperature. Said here rather than implied, because a
+ * reader is entitled to know which half of a rate constant is a measurement.
+ *
+ * That is a bounded looseness rather than a free one: a flame's *temperature* comes from the
+ * enthalpy, which is derived, and its *extent* from the oxygen the field delivers, which is
+ * transport. What `A` sets is how thin the reaction zone is.
+ */
+import { GAS_CONSTANT } from '../reaction/rates.js';
+import { KIND_CHAR_OXIDATION, KIND_COMBUSTION, phaseChange, } from '../reaction/reaction.js';
+export const MELT_ICE = 'melt-ice';
+export const BOIL_WATER = 'boil-water';
+export const BURN_METHANE = 'burn-methane';
+export const BURN_CARBON_MONOXIDE = 'burn-carbon-monoxide';
+export const BURN_HYDROGEN = 'burn-hydrogen';
+export const BURN_ETHYLENE = 'burn-ethylene';
+export const BURN_SOOT = 'burn-soot';
+export const SOOT_METHANE = 'soot-methane';
+export const OXIDISE_CHAR = 'oxidise-char';
+export const OXIDISE_CHAR_RICH = 'oxidise-char-rich';
+/** The gas-phase steps, which is what a `AtmosphereField` is given rather than a parcel. */
+export const GAS_REACTIONS = [
+    BURN_METHANE,
+    BURN_CARBON_MONOXIDE,
+    BURN_HYDROGEN,
+    BURN_ETHYLENE,
+    BURN_SOOT,
+    SOOT_METHANE,
+];
+/**
+ * How much char goes to CO rather than CO₂ at a temperature, per Arthur's measured relation.
+ *
+ * **Nothing in the model calls this.** It is here so a test can assert that the two char reactions
+ * reproduce it, and so a reader can see what the two activation energies below mean. The relation
+ * itself is `§8.5`'s, and its consequence is the one the design cares about: a cool smoulder makes
+ * mostly CO₂ and a hot one makes mostly CO, so an oxygen-starved fire in a closed room produces
+ * carbon monoxide faster than an open one would.
+ */
+export function arthurRatio(temperature) {
+    // determinism: build-time — a substance's tabulated property, built at registration
+    return 2500 * Math.exp(-6240 / temperature);
+}
+/**
+ * The gap between the two char paths' activation energies, and it is `6240·R` exactly.
+ *
+ * That is the whole trick. `k_rich/k_lean = (A_rich/A_lean)·exp(−ΔEa/R·T)`, so setting
+ * `ΔEa = 6240·R` and `A_rich/A_lean = 2500` makes the ratio Arthur's relation identically, at every
+ * temperature, with nothing tabulated and no branch anywhere.
+ */
+const ARTHUR_GAP = 6240 * GAS_CONSTANT;
+/** Kinetically controlled char oxidation, before transport takes over above about 800 K. */
+const CHAR_A = 1e7;
+const CHAR_EA = 140000;
+/**
+ * The ceiling oxygen delivery puts on char oxidation in still air, per second.
+ *
+ * **This is what makes char glow for an hour rather than vanishing in a minute**, and `§7` is the
+ * argument. Above about 800 K the kinetic rate is orders of magnitude faster than oxygen can reach
+ * the surface, so what is being watched is transport; the solver combines the two as a series
+ * resistance and the transport half wins. It rises with the gas moving past, which is why blowing
+ * on an ember brightens it.
+ *
+ * At this value a kilogram of char lasts tens of thousands of seconds in still air, which is the
+ * hour a real bed of embers lasts.
+ */
+const CHAR_TRANSPORT = 1e-5;
+export const COMMON_REACTIONS = [
+    /*
+     * The two water transitions, as CH-6's gated reactions rather than as shape in a curve. Their
+     * latent heats are Hess's law over the formation enthalpies and are not written anywhere: 333.6
+     * kJ/kg for fusion and 2,442.6 for vaporisation, the latter being the value at 298.15 K rather
+     * than the 2,256.4 quoted at the boiling point — which is right, and is why the latent heat at any
+     * temperature is a consequence here rather than a stored number.
+     */
+    phaseChange(MELT_ICE, 'H2O(s)', 'H2O(l)', 273.15),
+    phaseChange(BOIL_WATER, 'H2O(l)', 'H2O(g)', 373.15),
+    /* Gas-phase combustion. Every flame over a solid is one of these; the solid only makes the gas. */
+    {
+        id: BURN_METHANE,
+        reactants: [
+            { species: 'CH4', moles: 1 },
+            { species: 'O2', moles: 2 },
+        ],
+        products: [
+            { species: 'CO2', moles: 1 },
+            { species: 'H2O(g)', moles: 2 },
+        ],
+        kinetics: { type: 'arrhenius', A: 2.1e11, activationEnergy: 202500 },
+        kind: KIND_COMBUSTION,
+    },
+    {
+        /* The second stage, and where a flame's blue comes from. It is also the slow one: CO burns out
+           well after the hydrocarbons, which is why a rich flame's tip is where the CO finally goes. */
+        id: BURN_CARBON_MONOXIDE,
+        reactants: [
+            { species: 'CO', moles: 1 },
+            { species: 'O2', moles: 0.5 },
+        ],
+        products: [{ species: 'CO2', moles: 1 }],
+        kinetics: { type: 'arrhenius', A: 1e10, activationEnergy: 167400 },
+        kind: KIND_COMBUSTION,
+    },
+    {
+        id: BURN_HYDROGEN,
+        reactants: [
+            { species: 'H2', moles: 1 },
+            { species: 'O2', moles: 0.5 },
+        ],
+        products: [{ species: 'H2O(g)', moles: 1 }],
+        kinetics: { type: 'arrhenius', A: 1e11, activationEnergy: 125500 },
+        kind: KIND_COMBUSTION,
+    },
+    {
+        id: BURN_ETHYLENE,
+        reactants: [
+            { species: 'C2H4', moles: 1 },
+            { species: 'O2', moles: 3 },
+        ],
+        products: [
+            { species: 'CO2', moles: 2 },
+            { species: 'H2O(g)', moles: 2 },
+        ],
+        kinetics: { type: 'arrhenius', A: 2e12, activationEnergy: 125500 },
+        kind: KIND_COMBUSTION,
+    },
+    {
+        /* Soot burning out in the flame tip, which is what stops a luminous flame smoking when there is
+           enough air — and what fails to happen when there is not. */
+        id: BURN_SOOT,
+        reactants: [
+            { species: 'C(soot)', moles: 1 },
+            { species: 'O2', moles: 1 },
+        ],
+        products: [{ species: 'CO2', moles: 1 }],
+        kinetics: { type: 'arrhenius', A: 1e6, activationEnergy: 140000 },
+        kind: KIND_COMBUSTION,
+    },
+    {
+        /*
+         * **Soot, and nothing decides when it forms.** `§8.4` says a flame is orange because it holds
+         * incandescent soot and blue because it does not, and that the difference is the equivalence
+         * ratio — but there is no gate on φ here and there does not need to be. This reaction needs no
+         * oxygen and `burn-methane` needs two, so in a cell with air the oxidation wins and in one that
+         * has run out this is the only path left. **A rich flame soots and a lean one does not, out of
+         * mass action.**
+         *
+         * `CH₄ → C(soot) + 2 H₂` is methane's real thermal decomposition, and its activation energy
+         * puts the onset near 1,000 K — which is where soot genuinely starts forming in a flame.
+         *
+         * Soot is `C(soot)`, a **species**, so the carbon stays in the element ledger. A soot channel
+         * that carried mass outside `elementTotals` would make the most valuable assertion in the track
+         * quietly wrong every time a fire made smoke.
+         */
+        id: SOOT_METHANE,
+        reactants: [{ species: 'CH4', moles: 1 }],
+        products: [
+            { species: 'C(soot)', moles: 1 },
+            { species: 'H2', moles: 2 },
+        ],
+        kinetics: { type: 'arrhenius', A: 1e13, activationEnergy: 250000 },
+        kind: KIND_COMBUSTION,
+    },
+    /*
+     * Char, the two ways. See `ARTHUR_GAP`: the pair carries the measured CO/CO₂ split in the gap
+     * between their activation energies, so the split emerges rather than being decided anywhere.
+     */
+    {
+        id: OXIDISE_CHAR,
+        reactants: [
+            { species: 'C(char)', moles: 1 },
+            { species: 'O2', moles: 1 },
+        ],
+        products: [{ species: 'CO2', moles: 1 }],
+        kinetics: {
+            type: 'diffusion',
+            A: CHAR_A,
+            activationEnergy: CHAR_EA,
+            transportLimit: CHAR_TRANSPORT,
+        },
+        kind: KIND_CHAR_OXIDATION,
+    },
+    {
+        id: OXIDISE_CHAR_RICH,
+        reactants: [
+            { species: 'C(char)', moles: 1 },
+            { species: 'O2', moles: 0.5 },
+        ],
+        products: [{ species: 'CO', moles: 1 }],
+        kinetics: {
+            type: 'diffusion',
+            A: CHAR_A * 2500,
+            activationEnergy: CHAR_EA + ARTHUR_GAP,
+            transportLimit: CHAR_TRANSPORT,
+        },
+        kind: KIND_CHAR_OXIDATION,
+    },
+];
+/** Every char and water reaction a solid needs, which is what a burnable substance declares. */
+export const SOLID_COMMON = [BOIL_WATER, OXIDISE_CHAR, OXIDISE_CHAR_RICH];

package/dist/library/food.d.ts

@@ -0,0 +1,9 @@
+import type { SubstanceLibrary } from './library.ts';
+export declare const MELT_FAT = "melt-fat";
+export declare const DENATURE_MYOSIN = "denature-myosin";
+export declare const DENATURE_ALBUMEN = "denature-albumen";
+export declare const GELATINISE_COLLAGEN = "gelatinise-collagen";
+export declare const HYDROLYSE_STARCH = "hydrolyse-starch";
+export declare const BROWN_MAILLARD = "brown-maillard";
+export declare const CARAMELISE = "caramelise";
+export declare const FOOD: SubstanceLibrary;