@driftengine/chemistry 3.61.0

package/dist/transport/radiation.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Heat crossing empty space, which is how a fire reaches anything it is not touching.
+ *
+ * **Radiation dominates every fire beyond a few centimetres, and `§10` is the argument.** A flame
+ * at 1200 K radiates about 118 kW/m², and the fourth power means halving its temperature cuts that
+ * sixteenfold. A model without it cannot make a log ignite from across a hearth — which is the
+ * scenario the whole track exists for.
+ *
+ * **The view factor is a point source: `cos θ · A / (π r²)`.** It is wrong close in, where a flame
+ * is not a point, and it is right where it matters. What it buys is the single relationship this
+ * model is built on: **flux falls as `1/r²`**, so moving a log twice as far from a fire makes it
+ * take four times as long to catch. One line of arithmetic, and without it "leading a piece of wood
+ * near the fire" has no right answer at all.
+ */
+/** W/(m²·K⁴). */
+export declare const STEFAN_BOLTZMANN = 5.670374419e-8;
+/**
+ * Radiant flux onto a surface, W/m².
+ *
+ * @param sourceTemperature K
+ * @param sourceArea m² of radiating surface
+ * @param surfaceTemperature K of the receiver
+ * @param emissivity of the receiver, 0..1
+ * @param distance m
+ * @param cosine of the angle between the receiver's normal and the line to the source
+ */
+export declare function radiantFlux(sourceTemperature: number, sourceArea: number, surfaceTemperature: number, emissivity: number, distance: number, cosine: number): number;
+/**
+ * How far a source of a given power is worth considering, m.
+ *
+ * From `P / (4π r²) = q_min`, so a **big fire reaches further than a small one** rather than every
+ * source sharing a constant radius. That is what stops a candle being tested against every parcel
+ * in a scene and a bonfire being cut off at the same distance.
+ */
+export declare function sourceRange(power: number, minimumFlux: number): number;
+/**
+ * Convective heat transfer coefficient from the local gas speed, W/(m²·K).
+ *
+ * Two to twenty-five in still air, and up to about two hundred and fifty in a gale. **Above a fire
+ * convection dominates radiation and beside one radiation dominates convection**, and the crossover
+ * is at the plume edge — which is why standing beside a bonfire is pleasant and standing in the
+ * smoke is not.
+ */
+export declare function convectiveCoefficient(gasSpeed: number): number;
+/** Whether anything solid stands between two points. */
+export type OcclusionTest = (ax: number, ay: number, az: number, bx: number, by: number, bz: number) => boolean;
+/**
+ * The radiating things in a scene this tick: flames and hot surfaces both.
+ *
+ * Gathered into columns once per tick and read many times, which is why it is a structure rather
+ * than a callback. Cleared and refilled rather than reallocated.
+ */
+export declare class RadiativeSources {
+    private x;
+    private y;
+    private z;
+    private temperature;
+    private area;
+    private range;
+    private used;
+    get count(): number;
+    clear(): void;
+    /** @param power W, which decides how far this source is worth testing against. */
+    add(x: number, y: number, z: number, temperature: number, area: number, power: number): void;
+    temperatureOf(source: number): number;
+    areaOf(source: number): number;
+    /** Whether a point is inside this source's own reach. */
+    reaches(source: number, x: number, y: number, z: number): boolean;
+    /**
+     * Total flux onto a point from every source that can see it, W/m².
+     *
+     * The receiver is treated as facing each source — a parcel is a lump rather than a plane, so
+     * there is no one normal to take a cosine against. What that costs is that a flat plate edge-on
+     * to a fire receives as much as one facing it; what it buys is not asking a consumer for a normal
+     * per parcel, which is a number most of them do not have.
+     */
+    fluxAt(x: number, y: number, z: number, surfaceTemperature: number, emissivity: number, occluded: OcclusionTest | null): number;
+    /**
+     * The temperature of the hottest source that reaches a point, or zero where none does.
+     *
+     * **What a radiative exchange is bounded by**, and the reason it has to be bounded at all: the
+     * radiative term is explicit, so a parcel whose surface shell has a small heat capacity — a coin,
+     * a nail, a leaf — can absorb more in one step than would take it past the source that is heating
+     * it, and then radiate the excess back as `T⁴` and ring itself to pieces. It was found by putting
+     * a copper coin on a hearth in `demo/dev/chemistry.ts`, where it reached 4,000 K on the first step
+     * and 100 K a minute later.
+     *
+     * Nothing can be heated past the thing heating it, so this is the equilibrium the step may reach
+     * and not exceed — which is what an implicit solve would give and costs one comparison per source.
+     */
+    hottestAt(x: number, y: number, z: number, occluded: OcclusionTest | null): number;
+    /**
+     * Whether **any** source reaches a point at all, which is the whole of the wake test.
+     *
+     * `§14`'s scan has to be coarse or sleeping saves nothing: this is a range comparison per source
+     * and no view factor, no temperature and no occlusion ray. A source's range already comes from its
+     * own power, so a bonfire wakes a parcel a candle would not.
+     */
+    reachesPoint(x: number, y: number, z: number): boolean;
+    private grow;
+}

package/dist/transport/radiation.js

@@ -0,0 +1,199 @@
+/**
+ * Heat crossing empty space, which is how a fire reaches anything it is not touching.
+ *
+ * **Radiation dominates every fire beyond a few centimetres, and `§10` is the argument.** A flame
+ * at 1200 K radiates about 118 kW/m², and the fourth power means halving its temperature cuts that
+ * sixteenfold. A model without it cannot make a log ignite from across a hearth — which is the
+ * scenario the whole track exists for.
+ *
+ * **The view factor is a point source: `cos θ · A / (π r²)`.** It is wrong close in, where a flame
+ * is not a point, and it is right where it matters. What it buys is the single relationship this
+ * model is built on: **flux falls as `1/r²`**, so moving a log twice as far from a fire makes it
+ * take four times as long to catch. One line of arithmetic, and without it "leading a piece of wood
+ * near the fire" has no right answer at all.
+ */
+/** W/(m²·K⁴). */
+export const STEFAN_BOLTZMANN = 5.670374419e-8;
+/**
+ * How close a point source may be approached before the approximation is capped.
+ *
+ * A point source's flux is unbounded at zero distance, and the honest failure there is a large
+ * number rather than an infinite one. The clamp is the scale at which a real source stops looking
+ * like a point, which is its own size.
+ */
+const MIN_DISTANCE = 0.05;
+/**
+ * Radiant flux onto a surface, W/m².
+ *
+ * @param sourceTemperature K
+ * @param sourceArea m² of radiating surface
+ * @param surfaceTemperature K of the receiver
+ * @param emissivity of the receiver, 0..1
+ * @param distance m
+ * @param cosine of the angle between the receiver's normal and the line to the source
+ */
+export function radiantFlux(sourceTemperature, sourceArea, surfaceTemperature, emissivity, distance, cosine) {
+    if (!(cosine > 0))
+        return 0;
+    const range = Math.max(distance, MIN_DISTANCE);
+    const viewFactor = (cosine * sourceArea) / (Math.PI * range * range);
+    const source = sourceTemperature * sourceTemperature * sourceTemperature * sourceTemperature;
+    const surface = surfaceTemperature * surfaceTemperature * surfaceTemperature * surfaceTemperature;
+    return emissivity * STEFAN_BOLTZMANN * viewFactor * (source - surface);
+}
+/**
+ * How far a source of a given power is worth considering, m.
+ *
+ * From `P / (4π r²) = q_min`, so a **big fire reaches further than a small one** rather than every
+ * source sharing a constant radius. That is what stops a candle being tested against every parcel
+ * in a scene and a bonfire being cut off at the same distance.
+ */
+export function sourceRange(power, minimumFlux) {
+    if (!(power > 0) || !(minimumFlux > 0))
+        return 0;
+    return Math.sqrt(power / (4 * Math.PI * minimumFlux));
+}
+/**
+ * Convective heat transfer coefficient from the local gas speed, W/(m²·K).
+ *
+ * Two to twenty-five in still air, and up to about two hundred and fifty in a gale. **Above a fire
+ * convection dominates radiation and beside one radiation dominates convection**, and the crossover
+ * is at the plume edge — which is why standing beside a bonfire is pleasant and standing in the
+ * smoke is not.
+ */
+export function convectiveCoefficient(gasSpeed) {
+    const speed = gasSpeed > 0 ? gasSpeed : 0;
+    const h = 5 + 12 * Math.sqrt(speed);
+    return h > 250 ? 250 : h;
+}
+/** Below this a source is not worth testing against anything, W/m². */
+const MINIMUM_USEFUL_FLUX = 200;
+/**
+ * The radiating things in a scene this tick: flames and hot surfaces both.
+ *
+ * Gathered into columns once per tick and read many times, which is why it is a structure rather
+ * than a callback. Cleared and refilled rather than reallocated.
+ */
+export class RadiativeSources {
+    x = new Float64Array(32);
+    y = new Float64Array(32);
+    z = new Float64Array(32);
+    temperature = new Float64Array(32);
+    area = new Float64Array(32);
+    range = new Float64Array(32);
+    used = 0;
+    get count() {
+        return this.used;
+    }
+    clear() {
+        this.used = 0;
+    }
+    /** @param power W, which decides how far this source is worth testing against. */
+    add(x, y, z, temperature, area, power) {
+        if (this.used === this.x.length)
+            this.grow();
+        const at = this.used++;
+        this.x[at] = x;
+        this.y[at] = y;
+        this.z[at] = z;
+        this.temperature[at] = temperature;
+        this.area[at] = area;
+        this.range[at] = sourceRange(power, MINIMUM_USEFUL_FLUX);
+    }
+    temperatureOf(source) {
+        return this.temperature[source];
+    }
+    areaOf(source) {
+        return this.area[source];
+    }
+    /** Whether a point is inside this source's own reach. */
+    reaches(source, x, y, z) {
+        const dx = x - this.x[source];
+        const dy = y - this.y[source];
+        const dz = z - this.z[source];
+        const reach = this.range[source];
+        return dx * dx + dy * dy + dz * dz <= reach * reach;
+    }
+    /**
+     * Total flux onto a point from every source that can see it, W/m².
+     *
+     * The receiver is treated as facing each source — a parcel is a lump rather than a plane, so
+     * there is no one normal to take a cosine against. What that costs is that a flat plate edge-on
+     * to a fire receives as much as one facing it; what it buys is not asking a consumer for a normal
+     * per parcel, which is a number most of them do not have.
+     */
+    fluxAt(x, y, z, surfaceTemperature, emissivity, occluded) {
+        let total = 0;
+        for (let source = 0; source < this.used; source++) {
+            if (!this.reaches(source, x, y, z))
+                continue;
+            const sx = this.x[source];
+            const sy = this.y[source];
+            const sz = this.z[source];
+            if (occluded !== null && occluded(sx, sy, sz, x, y, z))
+                continue;
+            const dx = x - sx;
+            const dy = y - sy;
+            const dz = z - sz;
+            total += radiantFlux(this.temperature[source], this.area[source], surfaceTemperature, emissivity, Math.sqrt(dx * dx + dy * dy + dz * dz), 1);
+        }
+        return total;
+    }
+    /**
+     * The temperature of the hottest source that reaches a point, or zero where none does.
+     *
+     * **What a radiative exchange is bounded by**, and the reason it has to be bounded at all: the
+     * radiative term is explicit, so a parcel whose surface shell has a small heat capacity — a coin,
+     * a nail, a leaf — can absorb more in one step than would take it past the source that is heating
+     * it, and then radiate the excess back as `T⁴` and ring itself to pieces. It was found by putting
+     * a copper coin on a hearth in `demo/dev/chemistry.ts`, where it reached 4,000 K on the first step
+     * and 100 K a minute later.
+     *
+     * Nothing can be heated past the thing heating it, so this is the equilibrium the step may reach
+     * and not exceed — which is what an implicit solve would give and costs one comparison per source.
+     */
+    hottestAt(x, y, z, occluded) {
+        let hottest = 0;
+        for (let source = 0; source < this.used; source++) {
+            if (!this.reaches(source, x, y, z))
+                continue;
+            const sx = this.x[source];
+            const sy = this.y[source];
+            const sz = this.z[source];
+            if (occluded !== null && occluded(sx, sy, sz, x, y, z))
+                continue;
+            const temperature = this.temperature[source];
+            if (temperature > hottest)
+                hottest = temperature;
+        }
+        return hottest;
+    }
+    /**
+     * Whether **any** source reaches a point at all, which is the whole of the wake test.
+     *
+     * `§14`'s scan has to be coarse or sleeping saves nothing: this is a range comparison per source
+     * and no view factor, no temperature and no occlusion ray. A source's range already comes from its
+     * own power, so a bonfire wakes a parcel a candle would not.
+     */
+    reachesPoint(x, y, z) {
+        for (let source = 0; source < this.used; source++) {
+            if (this.reaches(source, x, y, z))
+                return true;
+        }
+        return false;
+    }
+    grow() {
+        const size = this.x.length * 2;
+        const grow = (from) => {
+            const to = new Float64Array(size);
+            to.set(from);
+            return to;
+        };
+        this.x = grow(this.x);
+        this.y = grow(this.y);
+        this.z = grow(this.z);
+        this.temperature = grow(this.temperature);
+        this.area = grow(this.area);
+        this.range = grow(this.range);
+    }
+}

package/dist/transport/world.d.ts

@@ -0,0 +1,92 @@
+import type { AtmosphereField } from '../field/atmosphere.ts';
+import type { ParcelStore } from '../parcel/store.ts';
+import { ContactSet } from './contacts.ts';
+import { ChemistryEvents } from '../ignition/events.ts';
+import { type OcclusionTest, RadiativeSources } from './radiation.ts';
+export interface ChemistryWorldOptions {
+    /**
+     * How fast a porous parcel equalises its pore gas with the cell around it, per second.
+     *
+     * Scaled by porosity, so a substance nobody described as porous exchanges nothing. What this
+     * governs in practice: how quickly volatiles get out to burn, and how quickly oxygen gets in to
+     * burn them.
+     */
+    readonly exchangeRate?: number;
+    /** Ambient gas speed where there is no field to ask, m/s. */
+    readonly stillAir?: number;
+}
+export declare class ChemistryWorld {
+    /** The parcels this world steps. Readable, because `fingerprintChemistry` hashes them. */
+    readonly parcels: ParcelStore;
+    /** The air, or `null` for a world with none. Readable for the same reason. */
+    readonly field: AtmosphereField | null;
+    /** Refilled by the caller each tick: what is radiating. */
+    readonly sources: RadiativeSources;
+    /** Refilled by the caller each tick: what is touching what. */
+    readonly contacts: ContactSet;
+    /** Drained by the caller each tick: what happened. Cleared at the top of every `simulate`. */
+    readonly events: ChemistryEvents;
+    /** Which slice of the sleeping set this tick's wake scan looks at. See `simulate`. */
+    private scanPhase;
+    /**
+     * Whether anything solid stands between two points.
+     *
+     * Absent, every source is visible — the cheap default, and wrong indoors. A consumer supplies a
+     * raycast; `§10` budgets and caches it, which is CH-6's work rather than this phase's.
+     */
+    occluded: OcclusionTest | null;
+    private readonly exchangeRate;
+    private readonly stillAir;
+    private readonly scratch;
+    constructor(
+    /** The parcels this world steps. Readable, because `fingerprintChemistry` hashes them. */
+    parcels: ParcelStore, 
+    /** The air, or `null` for a world with none. Readable for the same reason. */
+    field?: AtmosphereField | null, options?: ChemistryWorldOptions);
+    /**
+     * One fixed step, in the order `§13` gives.
+     *
+     * **Sleeping and the tier cadence are both here rather than inside the terms they skip**, because
+     * both are decisions about *whether* a parcel is stepped at all and a term that decided for itself
+     * would be four places deciding the same thing four ways.
+     */
+    simulate(dt: number, windX?: number, windZ?: number): void;
+    /** What the fires can see of this parcel, into shell 0. */
+    private radiate;
+    /**
+     * Joules, clipped to what would bring the surface to `driving` and no further.
+     *
+     * Zero `driving` means nothing was found to be driving it, and then the joules pass through: a
+     * parcel radiating to a sky with no source in it is losing heat to the far field, and clipping
+     * that against zero kelvin would be clipping it against nothing.
+     */
+    private bounded;
+    /** What the air around it is doing to it. */
+    private convect;
+    /** Heat across the faces the caller says are touching. */
+    private conductContacts;
+    /**
+     * The pore gas in a parcel relaxes toward the air around it.
+     *
+     * **One mechanism, both directions.** Volatiles a parcel's reactions made are above the cell's
+     * concentration and leave; oxygen its reactions consumed is below and comes in. Writing those as
+     * two rules would be two things to keep in step, and the second would be found wrong on the day a
+     * fire went out with oxygen still in the room.
+     *
+     * The target is what the pore volume would hold at the cell's own density, so a dense material
+     * with little void exchanges little — which is why a log smoulders and sawdust does not.
+     */
+    private exchange;
+    /**
+     * Whether this parcel catches, keeps burning, or stops — and why.
+     *
+     * **Nothing here starts a fire.** Five conditions decide it, a pilot is one of them, and the
+     * pilot a caller supplied is spent at the end of the tick whether or not it was enough. That is
+     * `§11`, and it is why holding a match to wet wood does exactly nothing.
+     */
+    private criteria;
+    /** How close a parcel is to catching, 0 to 1. A readout; nothing branches on it. */
+    ignitionProgressOf(parcel: number): number;
+    /** Moles of each element in the parcels and the air together. Writes into `out`. */
+    elementTotals(out: Float64Array): void;
+}