@driftengine/chemistry 3.61.0

package/src/reaction/reaction.ts

@@ -0,0 +1,235 @@
+/**
+ * What a reaction is: stoichiometry, a rate law, and what kind of change it represents.
+ *
+ * **No enthalpy field**, and that is the same decision `SpeciesDefinition` makes about molar mass.
+ * A reaction's `ΔH` is derived from its species' formation enthalpies by Hess's law at
+ * registration, so a number that disagreed with its own species cannot exist. `§5` of the design is
+ * the argument, and CH-0's heating-value test is what makes the underlying numbers trustworthy.
+ *
+ * **No gates yet.** The design's `ReactionGates` — a minimum oxygen fraction, a phase requirement,
+ * a moisture ceiling — are refused in this phase rather than stubbed: an oxygen gate without a gas
+ * field to read is a constant pretending to be physics, and the field is CH-4. The network here
+ * runs on mass action alone.
+ */
+
+export const KIND_DRYING = 0;
+export const KIND_PYROLYSIS = 1;
+export const KIND_COMBUSTION = 2;
+export const KIND_CHAR_OXIDATION = 3;
+export const KIND_CALCINATION = 4;
+export const KIND_CORROSION = 5;
+export const KIND_DISSOLUTION = 6;
+export const KIND_DENATURATION = 7;
+export const KIND_BROWNING = 8;
+export const KIND_BIOLOGICAL = 9;
+export const KIND_PHASE_CHANGE = 10;
+
+export type ReactionKind =
+  | typeof KIND_DRYING
+  | typeof KIND_PYROLYSIS
+  | typeof KIND_COMBUSTION
+  | typeof KIND_CHAR_OXIDATION
+  | typeof KIND_CALCINATION
+  | typeof KIND_CORROSION
+  | typeof KIND_DISSOLUTION
+  | typeof KIND_DENATURATION
+  | typeof KIND_BROWNING
+  | typeof KIND_BIOLOGICAL
+  | typeof KIND_PHASE_CHANGE;
+
+export interface SpeciesAmount {
+  readonly species: string;
+  /** Moles per unit of reaction extent. Fractional is allowed and often necessary. */
+  readonly moles: number;
+}
+
+/**
+ * `k(T) = A · T^n · exp(−Ea / R·T)`. Monotonic in temperature, which is right for everything a
+ * flame does and wrong for everything an enzyme does.
+ */
+export interface ArrheniusKinetics {
+  readonly type: 'arrhenius';
+  readonly A: number;
+  /** J/mol. */
+  readonly activationEnergy: number;
+  readonly n?: number;
+}
+
+/**
+ * A peaked curve: zero below `minimum`, one at `optimum`, zero above `maximum`.
+ *
+ * **Enzyme-catalysed rates are not Arrhenius**, and using one gives compost that heats forever.
+ * `§8.6` is the argument; this is where the shape lives.
+ */
+export interface CardinalKinetics {
+  readonly type: 'cardinal';
+  /** The rate at the optimum. */
+  readonly peak: number;
+  readonly minimum: number;
+  readonly optimum: number;
+  readonly maximum: number;
+}
+
+/**
+ * Arrhenius, capped by how fast the reactant can physically reach the surface.
+ *
+ * **This is what makes char glow for an hour instead of vanishing in seconds, and `§7` says why.**
+ * Above about 800 K the chemistry of carbon oxidation outruns oxygen delivery by an order of
+ * magnitude, so what you are actually watching is transport. The kinetic rate alone gives char that
+ * disappears; the cap gives char that sits there glowing, which is what char does.
+ *
+ * The two combine as a **series resistance** — `1/k = 1/k_kinetic + 1/k_transport` — which is the
+ * same arithmetic a shell boundary uses for the same reason, and it means neither side has to know
+ * about the other. And the transport half rises with the gas moving past, so **blowing on embers
+ * makes them brighter and stops when you stop**.
+ */
+export interface DiffusionKinetics {
+  readonly type: 'diffusion';
+  readonly A: number;
+  /** J/mol. */
+  readonly activationEnergy: number;
+  readonly n?: number;
+  /** The ceiling transport puts on it in still air, per second. */
+  readonly transportLimit: number;
+}
+
+/** As fast as the reactants allow: the clamp in the solver is the only thing limiting it. */
+export interface InstantKinetics {
+  readonly type: 'instant';
+}
+
+export type Kinetics = ArrheniusKinetics | CardinalKinetics | DiffusionKinetics | InstantKinetics;
+
+/**
+ * When a reaction is allowed to run at all.
+ *
+ * Separate from the rate law because it is a different kind of statement: kinetics say how fast,
+ * a gate says whether. Ice does not melt at all below 273.15 K, and expressing that as a very small
+ * Arrhenius rate would be a lie that leaks a trickle of water into every freezer.
+ */
+export interface ReactionGates {
+  /** K. Below this, nothing. */
+  readonly minTemperature?: number;
+  /** K. Above this, nothing. */
+  readonly maxTemperature?: number;
+  /**
+   * K over which a gate opens rather than snapping: upward from `minTemperature`, and downward from
+   * `maxTemperature` where there is one.
+   *
+   * Zero for a pure substance. A few kelvin for a mixture: butter softens over about three, because
+   * it is triglycerides with different melting points, and that band is what makes fat render
+   * slowly instead of switching from solid to liquid.
+   *
+   * **One number for both ends**, because no reaction here wants a sharp ceiling over a soft floor
+   * and a second field would be a knob nobody turns. A reaction with both gates set tapers
+   * symmetrically and is fully open only between them.
+   */
+  readonly width?: number;
+}
+
+export interface Reaction {
+  readonly id: string;
+  readonly reactants: readonly SpeciesAmount[];
+  readonly products: readonly SpeciesAmount[];
+  readonly kinetics: Kinetics;
+  readonly kind: ReactionKind;
+  readonly gates?: ReactionGates;
+}
+
+/**
+ * A phase change, as the reaction it actually is.
+ *
+ * **Its enthalpy is not given here and must not be**: Hess's law over CH-0's formation enthalpies
+ * gives 333,611 J/kg for ice melting against a literature 333,550, and — the part that settles the
+ * design — 2,442,631 J/kg for water boiling, which is the value **at 298.15 K** rather than the
+ * 2,256,400 quoted at the boiling point. That is right, and it means the latent heat at any
+ * temperature stops being stored and becomes a consequence of the heat capacities either side,
+ * varying the way the real one does.
+ *
+ * **A fast finite rate rather than `Instant`, and the difference is the whole plateau.** Instant
+ * kinetics would let the clamp convert every gram of water it could reach in a single sub-step —
+ * two and a half megajoules absorbed at once, and a temperature that falls hundreds of kelvin below
+ * the boiling point rather than sitting on it. A finite rate through an opening gate is a
+ * proportional controller instead: the further above the transition the temperature strays, the
+ * more converts, the more heat is absorbed, and it settles just above with an overshoot
+ * proportional to the flux arriving. That settling *is* the plateau, and it comes out of the
+ * substep-and-clamp solver rather than out of a table.
+ *
+ * `activationEnergy: 0` makes the Arrhenius form a constant, so no second kinetics kind was needed.
+ */
+export function phaseChange(
+  id: string,
+  from: string,
+  to: string,
+  temperature: number,
+  width = PHASE_GATE_WIDTH,
+  rate = PHASE_RATE,
+): Reaction {
+  return {
+    id,
+    reactants: [{ species: from, moles: 1 }],
+    products: [{ species: to, moles: 1 }],
+    kinetics: { type: 'arrhenius', A: rate, activationEnergy: 0 },
+    kind: KIND_PHASE_CHANGE,
+    gates: { minTemperature: temperature, width },
+  };
+}
+
+/**
+ * A phase change the other way up: the one that runs as something *cools*.
+ *
+ * **`phaseChange` is "heat arrives" and this is "heat leaves", and the pair is not symmetric by
+ * accident.** Everything the library had until now was the first kind — ice melts, water boils, wax
+ * vaporises — because a fire is heat arriving. A vapour condensing is the same mechanism read
+ * backwards: it runs *below* a temperature rather than above one, its gate closes as the
+ * temperature rises through the transition, and its enthalpy comes out with the opposite sign
+ * because Hess's law over the two species already carries it.
+ *
+ * **The gate closes over `width` rather than snapping**, and `gateOpening` grew the upper taper for
+ * this. Without it the pair rings: the temperature falls through the transition, the gate opens
+ * fully, latent heat is released, the temperature rises back through it, and the gate slams. That
+ * is `PHASE_GATE_WIDTH`'s argument with the signs reversed, so it takes the same answer.
+ *
+ * **A condensation wants a reverse reaction and its caller must write one.** Nothing here pairs
+ * them, because a pair is two entries in a network and the network is data. A condensation with no
+ * evaporation is a one-way sink: droplets that drift back into a flame stay droplets, and the smoke
+ * over a fire never turns black again.
+ */
+export function condensation(
+  id: string,
+  from: string,
+  to: string,
+  temperature: number,
+  width = PHASE_GATE_WIDTH,
+  rate = PHASE_RATE,
+): Reaction {
+  return {
+    id,
+    reactants: [{ species: from, moles: 1 }],
+    products: [{ species: to, moles: 1 }],
+    kinetics: { type: 'arrhenius', A: rate, activationEnergy: 0 },
+    kind: KIND_PHASE_CHANGE,
+    gates: { maxTemperature: temperature, width },
+  };
+}
+
+/**
+ * How fast a phase change runs with its gate fully open, per second.
+ *
+ * **A gain, not a physical constant, and it is bounded from both sides.** Too high and one step
+ * converts more than the arriving heat can pay for, so the temperature undershoots and the pair
+ * rings. Too low and the phase change cannot keep up with a real flux — at this value a kilogram
+ * boils at up to half a gram a second per kelvin of overshoot, which is about 1.2 kW and rises with
+ * the overshoot, so a kettle settles a thousandth of a kelvin above its boiling point and a blowtorch
+ * settles further above it. That the band widens with the flux is correct rather than a compromise.
+ */
+export const PHASE_RATE = 0.5;
+
+/**
+ * K over which a phase change's gate opens, for a pure substance.
+ *
+ * Not zero, and that is what keeps the plateau a plateau rather than a sawtooth: a gate that snapped
+ * fully open a hair above the transition would convert far more than the arriving heat can pay for,
+ * undershoot, snap shut, and ring. Half a kelvin is the band the temperature is then held within.
+ */
+export const PHASE_GATE_WIDTH = 0.5;

package/src/reaction/registry.ts

@@ -0,0 +1,257 @@
+/**
+ * The reactions a world knows about, balanced and costed at registration.
+ *
+ * Two things happen here that cannot happen later, and both are refusals rather than warnings.
+ *
+ * **Every reaction is checked against the element matrix**, and one that does not balance is
+ * refused naming the element and the size of the gap. An unbalanced reaction invents or destroys
+ * matter every time it runs, and every symptom of that is subtle — a fire that will not go out, a
+ * mass that quietly grows, smoke that never clears. CH-0 built the matrix for exactly this moment.
+ *
+ * **Every reaction's enthalpy is derived by Hess's law** from the formation enthalpies CH-0 stores,
+ * rather than typed in. A `ΔH` that disagreed with its own species would conserve energy in the
+ * code and lose it against the world, with nothing to detect it. Derived, the two cannot disagree,
+ * and a wrong formation enthalpy shows up in every reaction that touches the species at once —
+ * which is a bug that can be found.
+ */
+import { ELEMENT_COUNT, ELEMENTS } from '../element/elements.ts';
+import type { SpeciesRegistry } from '../species/registry.ts';
+import { type RateTable, tabulateArrhenius, tabulateCardinal } from './rates.ts';
+import type { Reaction, ReactionKind, SpeciesAmount } from './reaction.ts';
+
+export * from './reaction.ts';
+
+/** How far a reaction may be from balancing, in moles of an element per unit extent. */
+const BALANCE_TOLERANCE = 1e-9;
+
+/** `instant` has no table; the solver's clamp is what bounds it. A huge constant stands in. */
+const INSTANT_RATE = 1e12;
+
+export class ReactionRegistry {
+  private readonly ids: string[] = [];
+  private readonly byId = new Map<string, number>();
+  private readonly kinds: ReactionKind[] = [];
+  private readonly gateMin: number[] = [];
+  private readonly gateMax: number[] = [];
+  private readonly gateWidth: number[] = [];
+  private readonly transport: number[] = [];
+  private readonly enthalpies: number[] = [];
+  private readonly tables: (RateTable | null)[] = [];
+  private readonly reactantIndex: Int32Array[] = [];
+  private readonly reactantAmount: Float64Array[] = [];
+  private readonly productIndex: Int32Array[] = [];
+  private readonly productAmount: Float64Array[] = [];
+
+  /* Scratch for the balance check. Registration-time, so this is tidiness rather than a hot path. */
+  private readonly balance = new Float64Array(ELEMENT_COUNT);
+
+  constructor(private readonly species: SpeciesRegistry) {}
+
+  get count(): number {
+    return this.ids.length;
+  }
+
+  register(reaction: Reaction): number {
+    const { id } = reaction;
+    if (this.byId.has(id)) throw new Error(`reaction "${id}" is already registered`);
+    if (reaction.reactants.length === 0) throw new Error(`reaction "${id}" has no reactants`);
+    if (reaction.products.length === 0) throw new Error(`reaction "${id}" has no products`);
+
+    const resolve = (side: readonly SpeciesAmount[], what: string): [Int32Array, Float64Array] => {
+      const index = new Int32Array(side.length);
+      const amount = new Float64Array(side.length);
+      for (let i = 0; i < side.length; i++) {
+        const entry = side[i] as SpeciesAmount;
+        const at = this.species.indexOf(entry.species);
+        if (at < 0) {
+          throw new Error(
+            `reaction "${id}" names ${what} "${entry.species}", which is not a registered species`,
+          );
+        }
+        if (!Number.isFinite(entry.moles) || entry.moles <= 0) {
+          throw new Error(
+            `reaction "${id}" gives ${what} "${entry.species}" a coefficient of ${entry.moles}`,
+          );
+        }
+        index[i] = at;
+        amount[i] = entry.moles;
+      }
+      return [index, amount];
+    };
+
+    const [reactantIndex, reactantAmount] = resolve(reaction.reactants, 'reactant');
+    const [productIndex, productAmount] = resolve(reaction.products, 'product');
+
+    /* Products minus reactants, element by element. Zero everywhere or it does not run. */
+    this.balance.fill(0);
+    for (let i = 0; i < productIndex.length; i++) {
+      this.species.elements.addScaledRow(
+        productIndex[i] as number,
+        productAmount[i] as number,
+        this.balance,
+      );
+    }
+    for (let i = 0; i < reactantIndex.length; i++) {
+      this.species.elements.addScaledRow(
+        reactantIndex[i] as number,
+        -(reactantAmount[i] as number),
+        this.balance,
+      );
+    }
+    for (let e = 0; e < ELEMENT_COUNT; e++) {
+      const gap = this.balance[e] as number;
+      if (Math.abs(gap) > BALANCE_TOLERANCE) {
+        const side = gap > 0 ? 'more' : 'less';
+        throw new Error(
+          `reaction "${id}" does not balance: its products hold ${Math.abs(gap)} mol ${side} ` +
+            `${ELEMENTS[e]} than its reactants`,
+        );
+      }
+    }
+
+    /* Hess's law: the products' formation enthalpies less the reactants'. */
+    let enthalpy = 0;
+    for (let i = 0; i < productIndex.length; i++) {
+      enthalpy +=
+        (productAmount[i] as number) * this.species.formationEnthalpyOf(productIndex[i] as number);
+    }
+    for (let i = 0; i < reactantIndex.length; i++) {
+      enthalpy -=
+        (reactantAmount[i] as number) *
+        this.species.formationEnthalpyOf(reactantIndex[i] as number);
+    }
+
+    const kinetics = reaction.kinetics;
+    let table: RateTable | null;
+    let transportLimit = 0;
+    switch (kinetics.type) {
+      case 'arrhenius':
+        table = tabulateArrhenius(kinetics.A, kinetics.activationEnergy, kinetics.n ?? 0);
+        break;
+      case 'diffusion':
+        table = tabulateArrhenius(kinetics.A, kinetics.activationEnergy, kinetics.n ?? 0);
+        transportLimit = kinetics.transportLimit;
+        if (!(transportLimit > 0)) {
+          throw new Error(`reaction "${id}" is transport-limited at ${transportLimit} per second`);
+        }
+        break;
+      case 'cardinal':
+        table = tabulateCardinal(
+          kinetics.peak,
+          kinetics.minimum,
+          kinetics.optimum,
+          kinetics.maximum,
+        );
+        break;
+      case 'instant':
+        table = null;
+        break;
+    }
+
+    const index = this.ids.length;
+    this.ids.push(id);
+    this.byId.set(id, index);
+    this.kinds.push(reaction.kind);
+    const gates = reaction.gates;
+    this.gateMin.push(gates?.minTemperature ?? Number.NEGATIVE_INFINITY);
+    this.gateMax.push(gates?.maxTemperature ?? Number.POSITIVE_INFINITY);
+    this.gateWidth.push(gates?.width ?? 0);
+    this.enthalpies.push(enthalpy);
+    this.tables.push(table);
+    this.transport.push(transportLimit);
+    this.reactantIndex.push(reactantIndex);
+    this.reactantAmount.push(reactantAmount);
+    this.productIndex.push(productIndex);
+    this.productAmount.push(productAmount);
+    return index;
+  }
+
+  indexOf(id: string): number {
+    return this.byId.get(id) ?? -1;
+  }
+
+  idOf(reaction: number): string {
+    return this.ids[this.check(reaction)] as string;
+  }
+
+  kindOf(reaction: number): ReactionKind {
+    return this.kinds[this.check(reaction)] as ReactionKind;
+  }
+
+  /** J per unit extent. Negative releases heat; positive absorbs it. */
+  enthalpyOf(reaction: number): number {
+    return this.enthalpies[this.check(reaction)] as number;
+  }
+
+  rateTableOf(reaction: number): RateTable {
+    const table = this.tables[this.check(reaction)];
+    if (table === null) {
+      throw new Error(`reaction "${this.ids[reaction]}" is instant and has no rate table`);
+    }
+    return table;
+  }
+
+  /** K below which this reaction does not run at all. */
+  minTemperatureOf(reaction: number): number {
+    return this.gateMin[this.check(reaction)] as number;
+  }
+
+  /** K above which it does not run at all. */
+  maxTemperatureOf(reaction: number): number {
+    return this.gateMax[this.check(reaction)] as number;
+  }
+
+  /** K over which the lower gate opens rather than snapping. */
+  gateWidthOf(reaction: number): number {
+    return this.gateWidth[this.check(reaction)] as number;
+  }
+
+  /** The ceiling transport puts on this reaction in still air, per second. Zero means none. */
+  transportLimitOf(reaction: number): number {
+    return this.transport[this.check(reaction)] as number;
+  }
+
+  /** The table, or `null` where the reaction is instant. What the localiser packs. */
+  rateTableOrNull(reaction: number): RateTable | null {
+    return this.tables[this.check(reaction)] as RateTable | null;
+  }
+
+  /** The rate constant at a temperature. An instant reaction answers with a very large number. */
+  rateOf(reaction: number, temperature: number): number {
+    const table = this.tables[this.check(reaction)];
+    if (table === null) return INSTANT_RATE;
+    if (temperature <= table.minTemperature) return table.rate[table.knots - 1] as number;
+    if (temperature >= table.maxTemperature) return table.rate[0] as number;
+    const position =
+      ((1 / temperature - table.inverseMin) / (table.inverseMax - table.inverseMin)) *
+      (table.knots - 1);
+    const low = Math.floor(position);
+    const high = low + 1;
+    if (high >= table.knots) return table.rate[table.knots - 1] as number;
+    const at = position - low;
+    return (table.rate[low] as number) * (1 - at) + (table.rate[high] as number) * at;
+  }
+
+  reactantSpecies(reaction: number): Int32Array {
+    return this.reactantIndex[this.check(reaction)] as Int32Array;
+  }
+
+  reactantMoles(reaction: number): Float64Array {
+    return this.reactantAmount[this.check(reaction)] as Float64Array;
+  }
+
+  productSpecies(reaction: number): Int32Array {
+    return this.productIndex[this.check(reaction)] as Int32Array;
+  }
+
+  productMoles(reaction: number): Float64Array {
+    return this.productAmount[this.check(reaction)] as Float64Array;
+  }
+
+  private check(reaction: number): number {
+    if (!Number.isInteger(reaction) || reaction < 0 || reaction >= this.ids.length) {
+      throw new Error(`reaction ${reaction} is outside a registry of ${this.ids.length}`);
+    }
+    return reaction;
+  }
+}