@driftengine/chemistry 3.61.0

package/src/library/polymer.ts

@@ -0,0 +1,243 @@
+/**
+ * `@driftengine/chemistry/library/polymer` — six plastics, and what each one does in a fire.
+ *
+ * **The interesting numbers here are the two that are not enthalpies.** PVC's limiting oxygen index
+ * is 0.45, more than twice what air provides, so it burns only while something else holds a flame to
+ * it — which is the whole reason it goes in walls. And PVC's chlorine and polyurethane's nitrogen
+ * come out as HCl and HCN because their formulas say so, which is why a burning sofa is the
+ * dangerous one and why nothing here had to be told that.
+ *
+ * **The per-kilogram gasification endotherms run high**, and `library.ts`'s header says why: this
+ * species set stops at C₂ where real polyolefin volatiles are C₁₀-C₄₀ waxes. Polyethylene's *molar*
+ * depolymerisation enthalpy is right — 106.6 kJ/mol against a published 92-108 — and per kilogram it
+ * is 3.8 MJ against a measured 1.8-2.2. The total heat released once the volatiles burn is exact
+ * either way; the cap moves where it is released, not how much.
+ */
+import { KIND_PYROLYSIS, type Reaction } from '../reaction/reaction.ts';
+import { SHAPE_SLAB } from '../parcel/shells.ts';
+import { massFractions } from '../substance/composition.ts';
+import type { SubstanceThermal } from '../substance/substance.ts';
+import type { SubstanceLibrary } from './library.ts';
+import { COMMON_REACTIONS, GAS_REACTIONS, OXIDISE_CHAR, OXIDISE_CHAR_RICH } from './common.ts';
+
+/** Nothing new: everything these polymers give off is already in the common set. */
+export const POLYMER_GAS_REACTIONS: readonly string[] = GAS_REACTIONS;
+
+const REACTIONS: readonly Reaction[] = [
+  ...COMMON_REACTIONS,
+  {
+    /* Unzips to its own monomer and leaves nothing behind — measured char yield zero, and the
+       stoichiometry has no way to produce any. */
+    id: 'pyrolyse-polyethylene',
+    reactants: [{ species: 'polyethylene', moles: 1 }],
+    products: [{ species: 'C2H4', moles: 1 }],
+    kinetics: { type: 'arrhenius', A: 1e16, activationEnergy: 250000 },
+    kind: KIND_PYROLYSIS,
+  },
+  {
+    /* Forty kelvin below polyethylene, because a tertiary carbon is easier to break. */
+    id: 'pyrolyse-polypropylene',
+    reactants: [{ species: 'polypropylene', moles: 1 }],
+    products: [{ species: 'C2H4', moles: 1.5 }],
+    kinetics: { type: 'arrhenius', A: 1e16, activationEnergy: 235000 },
+    kind: KIND_PYROLYSIS,
+  },
+  {
+    /*
+     * Dehydrochlorination at about 275 °C, and what is left is a carbon backbone that chars.
+     * Modelled as one step rather than the real two, because the second one — the polyene charring
+     * at 400 °C — has the same products and nothing here distinguishes them.
+     */
+    id: 'pyrolyse-pvc',
+    reactants: [{ species: 'PVC', moles: 1 }],
+    products: [
+      { species: 'HCl', moles: 1 },
+      { species: 'C(char)', moles: 2 },
+      { species: 'H2', moles: 1 },
+    ],
+    kinetics: { type: 'arrhenius', A: 1e9, activationEnergy: 130000 },
+    kind: KIND_PYROLYSIS,
+  },
+  {
+    /* The aromatic ring survives depolymerisation and becomes char and soot, which is why a
+       polystyrene fire is the black one. */
+    id: 'pyrolyse-polystyrene',
+    reactants: [{ species: 'polystyrene', moles: 1 }],
+    products: [
+      { species: 'C2H4', moles: 2 },
+      { species: 'C(char)', moles: 4 },
+    ],
+    kinetics: { type: 'arrhenius', A: 1e13, activationEnergy: 200000 },
+    kind: KIND_PYROLYSIS,
+  },
+  {
+    /* The one polyolefin whose derived heat of gasification lands on the measurement — 1.99 MJ/kg
+       against 1.6 — because its ester group leaves as CO₂ and takes the oxygen with it. */
+    id: 'pyrolyse-pmma',
+    reactants: [{ species: 'PMMA', moles: 1 }],
+    products: [
+      { species: 'C2H4', moles: 2 },
+      { species: 'CO2', moles: 1 },
+    ],
+    kinetics: { type: 'arrhenius', A: 1e13, activationEnergy: 190000 },
+    kind: KIND_PYROLYSIS,
+  },
+  {
+    /* Two nitrogens per repeat unit, and they leave as cyanide and ammonia. Foam decomposes at
+       250-350 °C, far below any of the others, which is why furniture is the first thing to go. */
+    id: 'pyrolyse-polyurethane',
+    reactants: [{ species: 'polyurethane', moles: 1 }],
+    products: [
+      { species: 'C(char)', moles: 12 },
+      { species: 'CO', moles: 0.8 },
+      { species: 'CO2', moles: 2 },
+      { species: 'CH4', moles: 9 },
+      { species: 'HCN', moles: 1.2 },
+      { species: 'NH3', moles: 0.8 },
+      { species: 'H2O(g)', moles: 1.2 },
+    ],
+    kinetics: { type: 'arrhenius', A: 1e12, activationEnergy: 160000 },
+    kind: KIND_PYROLYSIS,
+  },
+];
+
+const CHAR = [OXIDISE_CHAR, OXIDISE_CHAR_RICH];
+
+export const POLYMER: SubstanceLibrary = {
+  id: 'polymer',
+  species: [],
+  reactions: REACTIONS,
+  substances: (species): readonly SubstanceThermal[] => [
+    {
+      id: 'polyethylene',
+      composition: massFractions(species, { polyethylene: 1 }),
+      density: 940,
+      conductivity: { k0: 0.4, k1: 0 },
+      shells: 3,
+      shape: SHAPE_SLAB,
+      emissivity: 0.92,
+      reactions: ['pyrolyse-polyethylene'],
+      ignition: {
+        pilotedSurfaceK: 613,
+        autoSurfaceK: 623,
+        criticalMassFlux: 0.011,
+        limitingOxygen: 0.174,
+      },
+      appearance: {
+        albedo: [0.78, 0.78, 0.76],
+        charAlbedo: [0.05, 0.05, 0.05],
+        sootYield: 0.06,
+      },
+    },
+    {
+      id: 'polypropylene',
+      composition: massFractions(species, { polypropylene: 1 }),
+      density: 905,
+      conductivity: { k0: 0.22, k1: 0 },
+      shells: 3,
+      shape: SHAPE_SLAB,
+      emissivity: 0.92,
+      reactions: ['pyrolyse-polypropylene'],
+      ignition: {
+        pilotedSurfaceK: 610,
+        autoSurfaceK: 660,
+        criticalMassFlux: 0.011,
+        limitingOxygen: 0.175,
+      },
+      appearance: {
+        albedo: [0.76, 0.76, 0.74],
+        charAlbedo: [0.05, 0.05, 0.05],
+        sootYield: 0.06,
+      },
+    },
+    {
+      /* **The limiting oxygen index is the whole substance.** 0.45 against air's 0.209, so a flame
+         cannot be sustained on it at all and it stops the moment the pilot does. */
+      id: 'pvc',
+      composition: massFractions(species, { PVC: 1 }),
+      density: 1400,
+      conductivity: { k0: 0.19, k1: 0 },
+      shells: 3,
+      shape: SHAPE_SLAB,
+      emissivity: 0.93,
+      reactions: ['pyrolyse-pvc', ...CHAR],
+      ignition: {
+        pilotedSurfaceK: 664,
+        autoSurfaceK: 727,
+        criticalMassFlux: 0.016,
+        limitingOxygen: 0.45,
+      },
+      appearance: {
+        albedo: [0.6, 0.6, 0.58],
+        charAlbedo: [0.03, 0.03, 0.03],
+        sootYield: 0.17,
+      },
+    },
+    {
+      id: 'polystyrene',
+      composition: massFractions(species, { polystyrene: 1 }),
+      density: 1050,
+      conductivity: { k0: 0.16, k1: 0 },
+      shells: 3,
+      shape: SHAPE_SLAB,
+      emissivity: 0.92,
+      reactions: ['pyrolyse-polystyrene', ...CHAR],
+      ignition: {
+        pilotedSurfaceK: 630,
+        autoSurfaceK: 763,
+        criticalMassFlux: 0.013,
+        limitingOxygen: 0.18,
+      },
+      appearance: {
+        albedo: [0.84, 0.84, 0.82],
+        charAlbedo: [0.03, 0.03, 0.03],
+        sootYield: 0.16,
+      },
+    },
+    {
+      id: 'pmma',
+      composition: massFractions(species, { PMMA: 1 }),
+      density: 1180,
+      conductivity: { k0: 0.19, k1: 0 },
+      shells: 3,
+      shape: SHAPE_SLAB,
+      emissivity: 0.93,
+      reactions: ['pyrolyse-pmma'],
+      ignition: {
+        pilotedSurfaceK: 651,
+        autoSurfaceK: 723,
+        criticalMassFlux: 0.0044,
+        limitingOxygen: 0.173,
+      },
+      appearance: {
+        albedo: [0.88, 0.88, 0.88],
+        charAlbedo: [0.1, 0.1, 0.1],
+        sootYield: 0.022,
+      },
+    },
+    {
+      /* Thirty kilograms a cubic metre and a conductivity ten times lower than the solid: a foam is
+         mostly air, which is why it heats through in seconds and why a sofa goes up so fast. */
+      id: 'polyurethane-foam',
+      composition: massFractions(species, { polyurethane: 1 }),
+      density: 30,
+      conductivity: { k0: 0.026, k1: 0.00005 },
+      shells: 3,
+      shape: SHAPE_SLAB,
+      porosity: 0.95,
+      emissivity: 0.9,
+      reactions: ['pyrolyse-polyurethane', ...CHAR],
+      ignition: {
+        pilotedSurfaceK: 553,
+        autoSurfaceK: 673,
+        criticalMassFlux: 0.0045,
+        limitingOxygen: 0.165,
+      },
+      appearance: {
+        albedo: [0.8, 0.74, 0.55],
+        charAlbedo: [0.03, 0.03, 0.03],
+        sootYield: 0.19,
+      },
+    },
+  ],
+};

package/src/parcel/conduction.ts

@@ -0,0 +1,188 @@
+/**
+ * One-dimensional conduction inward through a parcel's shells.
+ *
+ * **Explicit, sub-stepped, and in enthalpy rather than temperature** — and that last part is what
+ * rules out the obvious alternative. A tridiagonal implicit solve would be unconditionally stable
+ * and is twenty lines, but it solves for *temperature*, and on a phase plateau temperature does not
+ * respond to heat at all. An implicit step there is asking a solver to invert an infinite heat
+ * capacity. The enthalpy formulation is the reason this model works, so the integrator bends to it.
+ *
+ * **The plateau helps rather than hurts.** A shell part-way through melting absorbs heat without
+ * changing temperature, which is the most stable thing a cell can do — the stiffness is all in the
+ * dry segments, where the sub-step estimate below is what handles it.
+ *
+ * **Energy is conserved exactly, whatever the step does.** Conduction *moves* energy: whatever
+ * leaves shell `i` enters shell `i + 1`, computed once and applied to both. An under-resolved step
+ * can oscillate, and it can never gain or lose a joule. That is why an explicit integrator is safe
+ * here, and `conduction.test.ts` asserts it over five thousand ticks rather than arguing it.
+ *
+ * **The interface conductivity is the harmonic mean**, because a boundary between two materials is
+ * a series resistance and series resistances add reciprocals. It matters as soon as the two sides
+ * differ — and they will: char is roughly half the conductivity of the wood beneath it, which is
+ * the whole late-stage story of a burning log. An arithmetic mean would make the char blanket
+ * insulate far less than it does.
+ */
+import { STANDARD_TEMPERATURE } from '../species/species.ts';
+import { temperatureFromCapacity } from '../species/thermal.ts';
+import type { SubstanceReactions } from '../reaction/solver.ts';
+import type { ShellGeometry } from './shells.ts';
+import { MAX_SHELLS } from './shells.ts';
+
+/** W/(m·K): `k0` at the standard state, rising by `k1` per kelvin. */
+export interface Conductivity {
+  readonly k0: number;
+  readonly k1: number;
+}
+
+/** Everything about conduction that is a property of the substance, resolved once at registration. */
+export interface ConductionModel {
+  readonly geometry: ShellGeometry;
+  readonly conductivity: Conductivity | null;
+}
+
+/**
+ * The most sub-steps one call will take.
+ *
+ * Past this the step is under-resolved, and what happens then is decided by the clamp below rather
+ * than by this number: a pair may not exchange more heat than would equalise it, so an
+ * under-resolved step relaxes toward the right answer instead of overshooting past it.
+ *
+ * **This note used to say the failure was a ring and that a ring was the right failure.** It is not.
+ * A copper coin on the hearth in `demo/dev/chemistry.ts` — 400 W/(m·K) across a 0.3 mm shell, which
+ * wants seven hundred sub-steps — reached 4,000 K on its first step and 100 K a minute later, and
+ * *the energy was conserved the whole time*. Conservation is not enough: an ignition criterion reads
+ * a surface temperature and `present/` draws a glow from one, so an oscillation nothing loses energy
+ * to is still a fire that starts in the wrong place.
+ */
+const MAX_SUBSTEPS = 64;
+
+/* Module-scope scratch, so a tick allocates nothing. Not reentrant, and nothing here nests. */
+const temperature = new Float64Array(MAX_SHELLS);
+const coefficient = new Float64Array(MAX_SHELLS);
+/** Each shell's `dh/dT`, so the clamp knows what equalising a pair would cost. */
+const capacity = new Float64Array(MAX_SHELLS);
+
+/**
+ * Move heat inward one step. `enthalpy` holds this parcel's shells at `offset`, in joules.
+ *
+ * @param shellMass kg in each shell — equal by construction, which is what equal-mass shells buy
+ * @param area m² of exposed surface
+ * @param depth m, the characteristic depth: `depthFactor × volume / area`
+ */
+export function conductShells(
+  enthalpy: Float64Array,
+  offset: number,
+  model: ConductionModel,
+  thermal: SubstanceReactions,
+  composition: Float64Array,
+  compositionOffset: number,
+  shellMass: number,
+  area: number,
+  depth: number,
+  dt: number,
+): void {
+  const { geometry, conductivity } = model;
+  const count = geometry.count;
+  if (count < 2 || conductivity === null || dt <= 0) return;
+
+  /* Each shell's temperature from **its own** composition, which is what CH-6 bought: a shell part
+     way through charring has a different heat capacity from the one beside it, and a single curve
+     built at registration could not know. */
+  const width = thermal.speciesCount;
+  let smallestCapacity = Number.POSITIVE_INFINITY;
+  const read = (): void => {
+    smallestCapacity = Number.POSITIVE_INFINITY;
+    for (let i = 0; i < count; i++) {
+      const base = compositionOffset + i * width;
+      let A = 0;
+      let B = 0;
+      for (let s = 0; s < width; s++) {
+        const mass = composition[base + s] as number;
+        if (mass === 0) continue;
+        A += mass * (thermal.cpA[s] as number);
+        B += mass * (thermal.cpB[s] as number);
+      }
+      temperature[i] = temperatureFromCapacity(A, B, enthalpy[offset + i] as number);
+      /* `dh/dT` at this shell's own temperature, which is `A + B·ΔT` for a `cp` linear in `T`. */
+      const rise = (temperature[i] as number) - STANDARD_TEMPERATURE;
+      const slope = A + B * rise;
+      capacity[i] = slope > 0 ? slope : A > 0 ? A : shellMass;
+      if (A > 0 && A < smallestCapacity) smallestCapacity = A;
+    }
+    if (!Number.isFinite(smallestCapacity)) smallestCapacity = shellMass;
+  };
+
+  /* Conductances, W/K, from the temperatures the step starts at. Recomputed per sub-step, because
+     the whole point of a temperature-dependent `k` is that it moves as the front does. */
+  const conductances = (): number => {
+    let worst = 0;
+    for (let i = 0; i < count - 1; i++) {
+      const kHot =
+        conductivity.k0 + conductivity.k1 * ((temperature[i] as number) - STANDARD_TEMPERATURE);
+      const kCold =
+        conductivity.k0 + conductivity.k1 * ((temperature[i + 1] as number) - STANDARD_TEMPERATURE);
+      const total = kHot + kCold;
+      const effective = total > 0 ? (2 * kHot * kCold) / total : 0;
+      const face = area * (geometry.areaFactor[i] as number);
+      const span =
+        depth *
+        (((geometry.thicknessFraction[i] as number) +
+          (geometry.thicknessFraction[i + 1] as number)) /
+          2);
+      const conductance = span > 0 ? (effective * face) / span : 0;
+      coefficient[i] = conductance;
+      if (conductance > worst) worst = conductance;
+    }
+    return worst;
+  };
+
+  read();
+  const worst = conductances();
+  if (!(worst > 0)) return;
+
+  /*
+   * The explicit stability limit, as a sub-step count.
+   *
+   * A shell's temperature responds to a flux at `1 / (m·c)`, so a step is resolved while
+   * `dt · conductance / (m · c) ≤ 1/2`. `minHeatCapacity` is the smallest `dh/dT` anywhere on the
+   * substance's curve, which makes this conservative everywhere and exact at the worst point.
+   */
+  /* The sub-step estimate uses the smallest heat capacity actually present, which is the shell
+     that responds fastest to a flux and therefore the one that sets the limit. */
+  const limit = (2 * dt * worst) / smallestCapacity;
+  const substeps = Math.min(MAX_SUBSTEPS, Math.max(1, Math.ceil(limit)));
+  const step = dt / substeps;
+
+  for (let pass = 0; pass < substeps; pass++) {
+    if (pass > 0) {
+      read();
+      conductances();
+    }
+    for (let i = 0; i < count - 1; i++) {
+      const gap = (temperature[i] as number) - (temperature[i + 1] as number);
+      let joules = (coefficient[i] as number) * gap * step;
+      /*
+       * **Clamped at the point the two shells would be equal**, which is unconditionally stable and
+       * changes nothing whenever the step was resolved anyway.
+       *
+       * Heat moves down a temperature difference until there is no difference left; a step that
+       * would carry the cold shell *past* the hot one has moved more heat than exists to move, and
+       * doing that repeatedly is the oscillation `MAX_SUBSTEPS` used to permit. The equalising
+       * amount for two capacities in series is `ΔT · CaCb/(Ca+Cb)`, and it is the same arithmetic
+       * two conductivities in series already use.
+       */
+      const ca = capacity[i] as number;
+      const cb = capacity[i + 1] as number;
+      const total = ca + cb;
+      if (total > 0) {
+        const equalising = (gap * ca * cb) / total;
+        if (joules > 0 && joules > equalising) joules = equalising;
+        else if (joules < 0 && joules < equalising) joules = equalising;
+      }
+      /* Computed once and applied to both, which is what makes conservation exact rather than
+         approximate: the same double is subtracted here and added there. */
+      enthalpy[offset + i] = (enthalpy[offset + i] as number) - joules;
+      enthalpy[offset + i + 1] = (enthalpy[offset + i + 1] as number) + joules;
+    }
+  }
+}

package/src/parcel/shells.ts

@@ -0,0 +1,100 @@
+/**
+ * A parcel's depth, as nested shells of equal mass.
+ *
+ * **Without this a fire model cannot be right, and `§4` is the argument.** The time for a heat
+ * front to reach depth `d` goes as `ρ·c·d²/k`. For wood that is about six seconds at one
+ * millimetre and four hours at fifty, so a parcel with a single temperature is wrong by that whole
+ * factor — in the direction that flashes every log in the world over at once. Thin things ignite
+ * and thick things do not, and nothing else in the model produces that.
+ *
+ * **Equal mass rather than equal thickness**, which for a cylinder or a sphere puts the resolution
+ * where the gradient is: the outer shell of a large object is thin and the core is fat. For a slab
+ * the two are the same thing, because a slab's cross-section does not shrink inward.
+ *
+ * Shell 0 is the surface and shell `count - 1` is the core.
+ *
+ * The fractions here are pure functions of a shape and a count, so they are computed **once per
+ * substance at registration** and multiplied by a parcel's own depth at use. That is not tidiness:
+ * `Math.cbrt` is not exactly specified by ECMAScript, and `§15` keeps every operation the
+ * specification declines to pin down off the simulation path.
+ */
+
+export const SHAPE_SLAB = 0;
+export const SHAPE_CYLINDER = 1;
+export const SHAPE_SPHERE = 2;
+
+export type Shape = typeof SHAPE_SLAB | typeof SHAPE_CYLINDER | typeof SHAPE_SPHERE;
+
+/**
+ * The most shells a parcel may have.
+ *
+ * Sixteen because that is the design's `Hero` tier in `§14`, and because a parcel's enthalpy column
+ * is strided by this constant: every parcel pays sixteen doubles whether it uses them or not, which
+ * is 128 bytes and is the price of not needing a per-parcel offset table.
+ */
+export const MAX_SHELLS = 16;
+
+export interface ShellGeometry {
+  readonly shape: Shape;
+  readonly count: number;
+  /** Radius of shell `i`'s **inner** boundary, as a fraction of the characteristic depth. */
+  readonly innerFraction: Float64Array;
+  /** Area of that boundary, as a fraction of the exposed surface area. */
+  readonly areaFactor: Float64Array;
+  /** Shell `i`'s own thickness, as a fraction of the characteristic depth. These sum to one. */
+  readonly thicknessFraction: Float64Array;
+  /**
+   * Characteristic depth is this times volume over area: 1 for a slab, 2 for a cylinder, 3 for a
+   * sphere. It is what makes `V/A` mean "half-thickness" for a cylinder and "a third of the radius"
+   * for a sphere, which is the same relation fire engineering uses.
+   */
+  readonly depthFactor: number;
+}
+
+/** The exponent relating enclosed volume to radius: `V ∝ r^(m+1)`. */
+function volumeExponent(shape: Shape): number {
+  switch (shape) {
+    case SHAPE_SLAB:
+      return 1;
+    case SHAPE_CYLINDER:
+      return 2;
+    case SHAPE_SPHERE:
+      return 3;
+    default:
+      throw new Error(`shape ${shape} is not a slab, a cylinder or a sphere`);
+  }
+}
+
+export function shellGeometry(shape: Shape, count: number): ShellGeometry {
+  if (!Number.isInteger(count) || count < 1 || count > MAX_SHELLS) {
+    throw new Error(`a parcel has between 1 and ${MAX_SHELLS} shells, not ${count}`);
+  }
+  const exponent = volumeExponent(shape);
+
+  const innerFraction = new Float64Array(count);
+  const areaFactor = new Float64Array(count);
+  const thicknessFraction = new Float64Array(count);
+
+  /* Shell `i`'s inner boundary encloses `(count - 1 - i) / count` of the volume, which is what
+     equal mass means, and radius follows by the shape's own exponent. */
+  // determinism: build-time — shell geometry is computed at registration, per §15 of the design
+  const radiusAt = (volumeFraction: number): number => volumeFraction ** (1 / exponent);
+
+  for (let i = 0; i < count; i++) {
+    const inner = radiusAt((count - 1 - i) / count);
+    const outer = radiusAt((count - i) / count);
+    innerFraction[i] = inner;
+    // determinism: build-time — the same registration-time geometry as the line above
+    areaFactor[i] = inner ** (exponent - 1);
+    thicknessFraction[i] = outer - inner;
+  }
+
+  return {
+    shape,
+    count,
+    innerFraction,
+    areaFactor,
+    thicknessFraction,
+    depthFactor: exponent,
+  };
+}