@driftengine/chemistry 3.61.0

package/src/element/elements.ts

@@ -0,0 +1,80 @@
+/**
+ * The closed element set, and the atomic weights every molar mass is derived from.
+ *
+ * Fifteen elements, and the set is closed deliberately rather than for want of typing. Every
+ * species this package can hold is built from these, so the species-by-element matrix has a fixed
+ * width, `elementTotals` reduces into a fixed-length array, and the conservation assertion that
+ * `§6` of the design calls the most valuable test in the track is a comparison of two vectors of
+ * fifteen doubles rather than a walk over a dictionary.
+ *
+ * **Adding a sixteenth is a deliberate act with a cost**: every `Float64Array` sized by
+ * `ELEMENT_COUNT` grows, and a stored conservation baseline taken before the change no longer
+ * compares. That is the right amount of friction for a decision that widens the model's universe.
+ *
+ * The values are IUPAC conventional atomic weights in g/mol. They are *conventional* rather than
+ * the interval form the tables now publish, because a molar mass is arithmetic here and an interval
+ * would make every derived mass an interval too — which is honest and useless.
+ */
+
+/**
+ * The elements, in the order the design lists them: organic first, then the rest.
+ *
+ * The order is the wire format of every matrix row and every totals vector in this package, so it
+ * is frozen. Reordering it invalidates any baseline a consumer has stored, in exactly the way
+ * `AGENTS.md` says the RNG sequence is frozen.
+ */
+export const ELEMENTS = [
+  'C',
+  'H',
+  'O',
+  'N',
+  'S',
+  'Cl',
+  'Si',
+  'Ca',
+  'Fe',
+  'Al',
+  'Mg',
+  'Cu',
+  'Na',
+  'K',
+  'P',
+] as const;
+
+export type ElementSymbol = (typeof ELEMENTS)[number];
+
+export const ELEMENT_COUNT = ELEMENTS.length;
+
+/** Conventional atomic weights, g/mol, indexed the way `ELEMENTS` is. */
+export const ATOMIC_MASS = new Float64Array([
+  12.011, // C
+  1.008, // H
+  15.999, // O
+  14.007, // N
+  32.06, // S
+  35.45, // Cl
+  28.085, // Si
+  40.078, // Ca
+  55.845, // Fe
+  26.9815384, // Al
+  24.305, // Mg
+  63.546, // Cu
+  22.98976928, // Na
+  39.0983, // K
+  30.973761998, // P
+]);
+
+/*
+ * A map rather than an `indexOf`, and case-sensitive rather than folded.
+ *
+ * Case is load-bearing in chemical notation: `Co` is cobalt and `CO` is carbon monoxide, so a
+ * lookup that folded case would accept a molecule where an element was wanted and silently produce
+ * a molar mass for the wrong thing. Nothing here runs in a frame, so the map is for legibility
+ * rather than speed.
+ */
+const INDEX = new Map<string, number>(ELEMENTS.map((symbol, at) => [symbol, at]));
+
+/** The index of an element symbol, or `-1` for anything this package does not carry. */
+export function elementIndex(symbol: string): number {
+  return INDEX.get(symbol) ?? -1;
+}

package/src/element/matrix.ts

@@ -0,0 +1,89 @@
+/**
+ * Moles of each element per mole of each species, as one growable table.
+ *
+ * This is the law `§6` of the design rests on. A reaction balances when the sum of its reactants'
+ * rows equals the sum of its products'; a world conserves matter when the sum of every parcel's
+ * composition through this table is constant. Both are one reduction over one `Float64Array`, and
+ * that is only true because `ELEMENT_COUNT` is fixed and the storage is dense.
+ *
+ * **Dense rather than sparse, and it is not close.** Sixty species over fifteen elements is 900
+ * doubles, or 7.2 KB. A sparse structure would save perhaps two thirds of that and cost an
+ * indirection in the innermost loop of every conservation check. The dense table is smaller than
+ * one texture tile.
+ *
+ * Row-major, species-major: a species' fifteen elements are adjacent, because every consumer of
+ * this table walks one species at a time.
+ */
+import { ELEMENT_COUNT } from './elements.ts';
+
+/** Rows the table holds before its first growth. Doubles from here. */
+const INITIAL_ROWS = 64;
+
+export class SpeciesElementMatrix {
+  private store = new Float64Array(INITIAL_ROWS * ELEMENT_COUNT);
+  private used = 0;
+
+  get rows(): number {
+    return this.used;
+  }
+
+  /** Append a zeroed row and return its index. */
+  addRow(): number {
+    if ((this.used + 1) * ELEMENT_COUNT > this.store.length) {
+      const grown = new Float64Array(this.store.length * 2);
+      grown.set(this.store);
+      this.store = grown;
+    }
+    return this.used++;
+  }
+
+  set(row: number, element: number, moles: number): void {
+    this.check(row, element);
+    this.store[row * ELEMENT_COUNT + element] = moles;
+  }
+
+  at(row: number, element: number): number {
+    this.check(row, element);
+    return this.store[row * ELEMENT_COUNT + element] as number;
+  }
+
+  /**
+   * A row as a view of fifteen, sharing storage rather than copying.
+   *
+   * **A view is invalidated by a later `addRow` that grows the table**, because growth reallocates.
+   * Every caller in this package takes a view inside a loop that registers nothing, which is the
+   * only safe pattern and is why this is not handed out as a promise.
+   */
+  rowView(row: number): Float64Array {
+    this.check(row, 0);
+    return this.store.subarray(row * ELEMENT_COUNT, (row + 1) * ELEMENT_COUNT);
+  }
+
+  /**
+   * `out[e] += scale * this[row][e]`, for all fifteen. Allocates nothing.
+   *
+   * The primitive every conservation check is built from, and it exists rather than a loop over
+   * `at` for one reason: `rowView` would be the natural way to write that loop and `subarray`
+   * allocates a view object per call, which is an allocation per species per tick. It adds rather
+   * than replaces so a caller sums a whole world into one vector without a second accumulator.
+   */
+  addScaledRow(row: number, scale: number, out: Float64Array): void {
+    this.check(row, 0);
+    if (out.length !== ELEMENT_COUNT) {
+      throw new Error(`a totals vector is ${ELEMENT_COUNT} wide, not ${out.length}`);
+    }
+    const base = row * ELEMENT_COUNT;
+    for (let e = 0; e < ELEMENT_COUNT; e++) {
+      out[e] = (out[e] as number) + scale * (this.store[base + e] as number);
+    }
+  }
+
+  private check(row: number, element: number): void {
+    if (!Number.isInteger(row) || row < 0 || row >= this.used) {
+      throw new Error(`species row ${row} is outside a matrix of ${this.used}`);
+    }
+    if (!Number.isInteger(element) || element < 0 || element >= ELEMENT_COUNT) {
+      throw new Error(`element ${element} is outside the set of ${ELEMENT_COUNT}`);
+    }
+  }
+}

package/src/field/ambient.ts

@@ -0,0 +1,111 @@
+/**
+ * The far field: what the air is where nothing has happened to it.
+ *
+ * A consumer's constant, and everything downstream adjusts to it without a feature. A low-oxygen
+ * atmosphere makes fire hard to start and easy to put out; a high-oxygen one makes everything
+ * terrifying; a thin one lowers every boiling point in the world. None of those needed code.
+ */
+import type { SpeciesRegistry } from '../species/registry.ts';
+
+/** Pa. */
+export const STANDARD_PRESSURE_PA = 101325;
+
+/** J/(mol·K). */
+export const GAS_CONSTANT = 8.314462618;
+
+export interface AmbientState {
+  readonly temperature: number;
+  readonly pressure: number;
+  /** Relative humidity, 0..1. Added to the dry composition when a cell is filled. */
+  readonly humidity: number;
+  /** Dry mass fractions over gas species, summing to one. */
+  readonly composition: Readonly<Record<string, number>>;
+}
+
+/**
+ * Dry air at 20 °C and one atmosphere, at 50% relative humidity.
+ *
+ * **Argon is lumped into nitrogen**, per the species table's own note: it is 0.93% of air and
+ * chemically inert, so all it contributes is heat capacity and dilution. What that costs is
+ * measurable and small — the mean molar mass comes out at 28.86 g/mol against air's real 28.96,
+ * which is 0.4% — and what it buys is not carrying a sixteenth element for a gas that never reacts.
+ *
+ * The mass fractions are chosen so the *volume* fraction of oxygen comes back at 20.95%, because
+ * that is the number every extinction criterion in `§12` is written against.
+ */
+export const STANDARD_AIR: AmbientState = {
+  temperature: 293.15,
+  pressure: STANDARD_PRESSURE_PA,
+  humidity: 0.5,
+  composition: { N2: 0.767074, O2: 0.232285, CO2: 0.000641 },
+};
+
+/** The gas species a field tracks unless a consumer names its own. */
+export const STANDARD_FIELD_SPECIES: readonly string[] = [
+  'O2',
+  'N2',
+  'CO2',
+  'H2O(g)',
+  'CO',
+  'CH4',
+  'H2',
+  'C2H4',
+  'NH3',
+  'HCN',
+  'HCl',
+  'SO2',
+];
+
+/**
+ * Saturation vapour pressure of water, Pa, by the Magnus form.
+ *
+ * Authoring-time: it calls `exp`, and `§7` keeps transcendentals off the tick. A field fills a new
+ * cell from the ambient, which is a discrete event rather than a per-tick one, and CH-5's
+ * evaporation will need this tabulated the way every rate already is.
+ */
+export function saturationVapourPressure(temperature: number): number {
+  const celsius = temperature - 273.15;
+  // determinism: build-time — a field fills a new cell from the ambient, which is a discrete event
+  return 610.94 * Math.exp((17.625 * celsius) / (celsius + 243.04));
+}
+
+/**
+ * Mass of each tracked species in one cell of ambient air, kg.
+ *
+ * From the ideal gas law at the ambient temperature and pressure, with the humidity turned into
+ * water vapour by its partial pressure. Writes into `out`, one entry per field species.
+ */
+export function ambientCellMass(
+  registry: SpeciesRegistry,
+  fieldSpecies: Int32Array,
+  ambient: AmbientState,
+  volume: number,
+  out: Float64Array,
+): void {
+  const vapourPressure = ambient.humidity * saturationVapourPressure(ambient.temperature);
+  const dryPressure = Math.max(0, ambient.pressure - vapourPressure);
+  const totalMoles = (ambient.pressure * volume) / (GAS_CONSTANT * ambient.temperature);
+  const vapourMoles = (vapourPressure * volume) / (GAS_CONSTANT * ambient.temperature);
+  const dryMoles = totalMoles - vapourMoles;
+
+  /* The dry composition is by mass, so its mean molar mass is what converts moles to kilograms. */
+  let inverseMean = 0;
+  for (const [id, fraction] of Object.entries(ambient.composition)) {
+    const species = registry.indexOf(id);
+    if (species < 0) throw new Error(`ambient names "${id}", which is not a registered species`);
+    inverseMean += fraction / registry.molarMass(species);
+  }
+  const meanMolarMass = 1 / inverseMean;
+  const dryMass = dryMoles * meanMolarMass;
+
+  out.fill(0);
+  for (let i = 0; i < fieldSpecies.length; i++) {
+    const id = registry.idOf(fieldSpecies[i] as number);
+    const fraction = ambient.composition[id];
+    if (fraction !== undefined) out[i] = fraction * dryMass;
+    if (id === 'H2O(g)') {
+      out[i] = (out[i] as number) + vapourMoles * registry.molarMass(fieldSpecies[i] as number);
+    }
+  }
+  void dryPressure;
+}