@driftengine/chemistry 3.61.0

package/dist/parcel/store.d.ts

@@ -0,0 +1,395 @@
+import type { SubstanceRegistry } from '../substance/registry.ts';
+import { type Tier } from './tier.ts';
+import type { AppearanceModel } from '../substance/substance.ts';
+import type { IgnitionModel } from '../ignition/criteria.ts';
+/**
+ * A parcel made of more than one phase at once, which is most of them.
+ *
+ * Not a `Phase`, because it is not one: wet wood is a solid and a liquid together, and the design's
+ * `§20.3` gives it its own value rather than making a consumer guess which half was reported.
+ */
+export declare const PHASE_MIXED = 3;
+/**
+ * What a parcel is made of and how big it is. An object rather than seven positional arguments,
+ * which is how `PhysicsWorld.addBody` takes a body and for the same reason.
+ */
+export interface ParcelSpec {
+    readonly substance: number;
+    readonly mass: number;
+    /** K. Every shell starts here. */
+    readonly temperature: number;
+    /**
+     * Exposed surface area, m². Optional, and **conduction refuses a parcel without one**, naming it:
+     * a characteristic depth is volume over area, so a parcel with no area has no depth and there is
+     * no honest default to invent. `parcelFromBounds` supplies it from a bounding box in CH-9.
+     */
+    readonly area?: number;
+    readonly x?: number;
+    readonly y?: number;
+    readonly z?: number;
+}
+export declare class ParcelStore {
+    private readonly substances;
+    private readonly species;
+    private substance;
+    private mass;
+    /** Strided by `MAX_SHELLS`: shell `s` of parcel `p` is at `p * MAX_SHELLS + s`, in joules. */
+    private enthalpy;
+    private area;
+    private x;
+    private y;
+    private z;
+    private live;
+    /** `FLAG_BURNING | FLAG_SMOULDERING | FLAG_PILOT`. */
+    private flags;
+    /** kg/(m²·s) of gas leaving the surface, and of the combustible part of it. */
+    private flux;
+    private fuelFlux;
+    /**
+     * Watts the reactions put into this parcel over the last `react`, and it is a *readout*.
+     *
+     * **A fire's size is its heat release rate**, not its temperature — every fire-engineering figure
+     * in the design is quoted in kilowatts — and it cannot be recovered from outside, because
+     * conduction and a radiative source change the same enthalpy in the same tick. So it is measured
+     * where only reactions are running, by summing the thermal enthalpy either side of them. That sum
+     * is one pass over at most sixteen shells, which is nothing against the reaction step it brackets.
+     */
+    private release;
+    /** Which of `§14`'s four tiers each parcel is being simulated at. */
+    private tier;
+    /** Shells actually resolved right now, which a tier may reduce below what the substance declared. */
+    private shells;
+    /** Seconds owed to a parcel its cadence has been skipping, handed over when its turn comes. */
+    private owed;
+    /** Consecutive ticks a parcel has been still. At `QUIET_TICKS` it sleeps. */
+    private quiet;
+    /**
+     * Where each parcel's composition block starts, and the block itself.
+     *
+     * A block is `shells × the substance's own species count` kilograms — **dense over the few
+     * species that substance can hold**, not a row over all sixty-eight. Blocks are appended and
+     * never moved, which is what makes an offset stable; compaction is a budget question and belongs
+     * with the rest of them in CH-6.
+     */
+    private compositionOffset;
+    private composition;
+    private compositionUsed;
+    private used;
+    constructor(substances: SubstanceRegistry, species?: import("../index.ts").SpeciesRegistry);
+    /** Handles ever issued, live or not. A destroyed parcel still occupies its index. */
+    get count(): number;
+    spawn(spec: ParcelSpec): number;
+    /** m², what the environment touches. Zero means the caller has not said, and conduction refuses. */
+    areaOf(parcel: number): number;
+    destroy(parcel: number): void;
+    alive(parcel: number): boolean;
+    substanceOf(parcel: number): number;
+    massOf(parcel: number): number;
+    /** m³, from mass and the substance's density. Shrinks as mass leaves, which is why a log burns down. */
+    volumeOf(parcel: number): number;
+    /** How many shells this parcel's substance divides it into. */
+    /**
+     * Shells resolved right now, which a level-of-detail tier may have reduced.
+     *
+     * Everything that walks a parcel's depth reads this rather than the substance's declared count, so
+     * a `Distant` log is one shell everywhere at once and nothing has to be told which tier it is at.
+     */
+    shellCount(parcel: number): number;
+    /** What the substance asked for, which is the resolution `Hero` restores to. */
+    declaredShellsOf(parcel: number): number;
+    tierOf(parcel: number): Tier;
+    /** Ticks between updates at this parcel's tier. `§14`'s cadence column. */
+    cadenceOf(parcel: number): number;
+    /** The most sub-steps a reaction solve will take at this parcel's tier. */
+    substepsOf(parcel: number): number;
+    /**
+     * Move a parcel to a tier, **conserving mass, every element and enthalpy exactly**.
+     *
+     * `§14`: "a tier change does not lose or gain mass or energy... which is the property that makes
+     * the LOD safe to apply to a burning object mid-burn." Shells are equal-mass by construction, so a
+     * fold is a proportional redistribution — target `j` takes source shells `[j·n/m, (j+1)·n/m)`,
+     * splitting one where the ratio is not an integer — and the targets come out equal-mass too.
+     *
+     * **What it loses is the profile inside a fold**, which is the point of a tier: two shells at
+     * 400 K and 300 K become one at their mass-weighted mean, and going back up hands each of them the
+     * same mean. Resolution in depth is what a distant object gives away.
+     */
+    setTier(parcel: number, tier: Tier): void;
+    /**
+     * Redistribute a parcel's `from` shells into `to`, exactly.
+     *
+     * One pass into scratch and one pass back, because a fold reads every source before it has written
+     * any target and doing it in place would read a slot it had already overwritten.
+     */
+    private refold;
+    /** Total joules held across every shell, not joules per kilogram. */
+    enthalpyOf(parcel: number): number;
+    shellEnthalpyOf(parcel: number, shell: number): number;
+    /**
+     * The temperature of one shell, K. Shell 0 is the surface and the last is the core.
+     *
+     * **`surfaceTemperatureOf` is what decides ignition and `coreTemperatureOf` is what decides
+     * doneness**, and the gap between them is the whole reason shells exist.
+     */
+    shellTemperatureOf(parcel: number, shell: number): number;
+    surfaceTemperatureOf(parcel: number): number;
+    coreTemperatureOf(parcel: number): number;
+    positionX(parcel: number): number;
+    positionY(parcel: number): number;
+    positionZ(parcel: number): number;
+    move(parcel: number, x: number, y: number, z: number): void;
+    /**
+     * The temperature this parcel would have if it were stirred, K.
+     *
+     * A read rather than a stored field, and that is the design. Nothing writes a temperature except
+     * `setTemperature`, which writes the enthalpy that produces one — so a parcel on a plateau simply
+     * does not move, and no code anywhere had to know a plateau exists.
+     *
+     * **The temperature of the total enthalpy**, not the mean of the shell temperatures. The two
+     * differ wherever the curve bends, and only this one has the property that matters: heat in,
+     * temperature out, with nothing lost between them.
+     */
+    temperatureOf(parcel: number): number;
+    /** Joules in, spread evenly through the depth. Negative cools. A microwave, or a stirred pot. */
+    addHeat(parcel: number, joules: number): void;
+    /**
+     * Joules into shell 0 alone, which is what a flux from outside actually does.
+     *
+     * Every radiative, convective and contact term in CH-5 lands here. The difference between this
+     * and `addHeat` is the difference between a log in front of a fire and a log in an oven.
+     */
+    addSurfaceHeat(parcel: number, joules: number): void;
+    /**
+     * Conduct heat inward one step of `dt` seconds.
+     *
+     * Conserves this parcel's total enthalpy exactly — the arithmetic is in `conduction.ts` and so is
+     * the reason.
+     */
+    conduct(parcel: number, dt: number): void;
+    /**
+     * Force a temperature by writing the enthalpy that produces it.
+     *
+     * For authoring and for tests. **Not for a tick**: it discards whatever enthalpy the parcel held,
+     * so a boiling parcel set to its own boiling point loses however much of the plateau it had
+     * crossed, and the energy budget does not close across the call.
+     */
+    setTemperature(parcel: number, temperature: number): void;
+    /** Force one shell's temperature. Authoring and tests only, for the reason above. */
+    setShellTemperature(parcel: number, shell: number, temperature: number): void;
+    /** Kilograms of one species in one shell. Zero where the substance cannot hold it at all. */
+    speciesMassOf(parcel: number, shell: number, species: number): number;
+    /** The same, summed over every shell. */
+    parcelSpeciesMass(parcel: number, species: number): number;
+    /** Kilograms in one shell, summed over its species. Invariant under reaction. */
+    shellMassOf(parcel: number, shell: number): number;
+    /** Moles of each element this parcel holds. Writes into `out`, allocates nothing. */
+    elementTotalsOf(parcel: number, out: Float64Array): void;
+    /**
+     * Energy locked in this parcel's chemical bonds, J.
+     *
+     * Neither this nor the thermal enthalpy is conserved on its own — a reaction moves energy between
+     * them. **Their sum is**, exactly, because the same number is added to one and taken from the
+     * other in `reactShell`.
+     */
+    chemicalEnergyOf(parcel: number): number;
+    /** Run this parcel's reactions in every shell for `dt` seconds. */
+    react(parcel: number, dt: number, transportFactor?: number): void;
+    /** Joules of sensible heat across a parcel's shells. One pass over at most sixteen doubles. */
+    private thermalEnthalpy;
+    /**
+     * Whether this parcel is being skipped entirely.
+     *
+     * `§14`'s thermal quiescence, and the vocabulary is deliberately Track B's. A cold stone floor is a
+     * thousand of these and costs a bounded scan.
+     */
+    sleeping(parcel: number): boolean;
+    /**
+     * Wake it, and reset the count that would put it back.
+     *
+     * **Called by everything that could change what a parcel is**: heat arriving, water poured on,
+     * mass added, a contact, or a source coming within range. Cheap enough — a flag and an integer —
+     * that a caller never has to decide whether it is worth it.
+     */
+    wake(parcel: number): void;
+    /**
+     * Decide whether this parcel is still enough to sleep, and put it to sleep if it has been for long
+     * enough. Returns whether it is now asleep.
+     *
+     * **A burning or smouldering parcel never sleeps, whatever its numbers say.** A steady flame is a
+     * *steady* parcel by every measure here, and sleeping one would put out a fire by optimising it.
+     */
+    settle(parcel: number): boolean;
+    /**
+     * Seconds this parcel is owed by its cadence, and whether its turn has come.
+     *
+     * A `Far` parcel is stepped every fourth tick with four ticks of `dt`, so the same seconds are
+     * integrated either way — which is what makes a cadence conserving for free rather than by care.
+     */
+    accrue(parcel: number, dt: number): number;
+    /** Whether a flame stands over this parcel. */
+    burning(parcel: number): boolean;
+    /** Whether its char is glowing, which needs no flame and far less oxygen. */
+    smouldering(parcel: number): boolean;
+    /** Whether a pilot is present this tick. */
+    piloted(parcel: number): boolean;
+    /**
+     * Supply a pilot for one tick. **This does not start a fire**, and `§11` is why.
+     *
+     * Ignition is five conditions, and a pilot is one of them. Holding a match to wet wood does
+     * exactly nothing here, which is correct and is the API telling the truth about what a match is.
+     */
+    ignite(parcel: number): void;
+    /** Put the flame out. Embers survive, which is the point — see `§12`. */
+    douse(parcel: number): void;
+    setBurning(parcel: number, burning: boolean): void;
+    setSmouldering(parcel: number, smouldering: boolean): void;
+    clearPilot(parcel: number): void;
+    /** kg/(m²·s) of gas leaving the surface, all of it. */
+    massFluxOf(parcel: number): number;
+    /**
+     * And of the part of it that can burn — which is the criterion ignition turns on.
+     *
+     * The two differ by exactly what a wet log gives off. Steam leaving a surface counts toward
+     * diluting the mixture above it and not toward feeding it, which is why 60% moisture stops a log
+     * catching in front of a fire that lights a seasoned one in eighty seconds.
+     */
+    fuelFluxOf(parcel: number): number;
+    setMassFlux(parcel: number, total: number, fuel: number): void;
+    /**
+     * Watts the reactions released last step: positive exothermic, negative endothermic.
+     *
+     * **A fire's size is its heat release rate**, which is what every figure in the design is quoted
+     * against and is not the temperature. A pyrolysing surface reads *negative* here while it is
+     * gasifying, which is right and is why a flame has to keep feeding heat back to sustain one.
+     */
+    heatReleaseOf(parcel: number): number;
+    /**
+     * Kilograms of water per kilogram of dry matter — **the dry basis, which is how it is quoted**.
+     *
+     * "12% moisture content" means twelve kilograms of water per hundred of dry wood, and
+     * `wetComposition` folded that into a wet-basis 0.107 to store it. Undoing the same conversion
+     * here is what makes a script comparing against the 0.25 that decides whether a log is worth
+     * burning read the quantity the author wrote.
+     *
+     * Ice counts as water. A frozen log is not a dry one.
+     */
+    moistureOf(parcel: number): number;
+    /**
+     * `PHASE_SOLID`, `PHASE_LIQUID`, `PHASE_GAS`, or `PHASE_MIXED` where no one of them dominates.
+     *
+     * Mixed is a real answer rather than a failure to decide: wet wood is wood and water at once, and
+     * calling it either would be a lie a consumer would then draw.
+     */
+    parcelPhaseOf(parcel: number): number;
+    /**
+     * Kilograms of **free** water on the surface, per square metre of it.
+     *
+     * **Free, meaning beyond what the material holds as its own moisture**, and that distinction is
+     * the whole reading. A seasoned oak log carries 12% water on a dry basis and is not glossy; a log
+     * somebody threw a bucket over is. Reporting the shell's total water would make the two identical
+     * and every piece of wood in a scene look rained on.
+     *
+     * **Derived rather than a column**, because `wet` puts real water in the surface shell rather than
+     * setting a flag — so `§17`'s wet-film roughness reads a quantity the boiling reaction is
+     * simultaneously consuming, which is what makes drying visible.
+     */
+    wetnessOf(parcel: number): number;
+    /**
+     * Pour water on it: liquid water into the surface shell, where the boiling reaction will find it.
+     *
+     * **Not a flag, and that is the whole point.** The heat sink `§12` describes is the same
+     * 2.44 MJ/kg every other drop of water in this model carries, so a doused fire goes out for the
+     * reason a real one does and a light sprinkling on a hot ember does not.
+     *
+     * Refused, naming the substance, where that substance cannot hold water at all — which means it
+     * declares no reaction that touches it. Silently doing nothing would make "I poured a bucket on
+     * it" and "this material has no water in its model" indistinguishable.
+     */
+    wet(parcel: number, kilograms: number): void;
+    /** Take surface water away: a cloth, a hot dry pan, or wind. Never below what is there. */
+    dry(parcel: number, kilograms: number): void;
+    /**
+     * Metres of char measured inward from the surface.
+     *
+     * The shells that are mostly carbon, summed by their own thickness. A shell counts once it is past
+     * half char, which is a threshold on a continuum and is said out loud: a finer answer needs a char
+     * *front* within a shell, which is a sub-shell quantity this model does not carry.
+     */
+    charDepthOf(parcel: number): number;
+    /**
+     * How much of this parcel is still load-bearing, 1 down to 0.
+     *
+     * **`§18` refuses structural failure in writing and this is the refusal reporting.** A beam whose
+     * char depth has eaten a fraction of its thickness has lost that fraction of its strength, and
+     * what happens next — a joint releasing, a body splitting, a building coming down — belongs to
+     * whoever owns the solver. This package writes the scalar, emits an event at a threshold, and
+     * breaks nothing.
+     */
+    structuralIntegrityOf(parcel: number): number;
+    /**
+     * Pour `from` into `into`; `from` is consumed. Mass, elements and enthalpy all conserved exactly.
+     *
+     * **Both must be the same substance, and two that are not are refused naming both.** Two
+     * substances are two species sets and two shell counts, so mixing them would silently discard
+     * whichever set was narrower — and a stew is not a substance change. What a consumer combining two
+     * genuinely different materials wants is a third substance that is the mixture, authored as one.
+     */
+    mix(from: number, into: number): void;
+    /**
+     * Joules into one named shell.
+     *
+     * The difference between this and `addSurfaceHeat` is a microwave and an oven: one deposits where
+     * the field penetrates to, the other at the surface. Nothing here decides which is physical.
+     */
+    addShellHeat(parcel: number, shell: number, joules: number): void;
+    /**
+     * What fraction of its original volume is left, as mass leaves it.
+     *
+     * **The number a shrinking log is drawn from.** A parcel's volume is its mass over its substance's
+     * density, and the density does not change — so this is simply what share of the mass is still
+     * here, which falls as volatiles leave and rises for nothing.
+     */
+    volumeShareOf(parcel: number): number;
+    /**
+     * Joules per kelvin of the surface shell, from what it is made of right now.
+     *
+     * **What every explicit surface term has to be bounded against.** A flux times an area times a
+     * step is joules, and joules into a small enough shell is an arbitrarily large temperature change
+     * — so a term that does not know this number cannot tell the difference between heating something
+     * and destroying it. `ChemistryWorld` uses it to stop a radiative or convective step carrying a
+     * surface past the thing driving it.
+     */
+    surfaceHeatCapacityOf(parcel: number): number;
+    /** What this parcel's substance looks like, or `null` where nobody said. */
+    appearanceOf(parcel: number): AppearanceModel | null;
+    /** Share of this parcel's mass that is char, 0..1. */
+    charFractionOf(parcel: number): number;
+    /** Add (or with a negative value, remove) mass of one species in one shell. */
+    addSpeciesMass(parcel: number, shell: number, species: number, kilograms: number): void;
+    /** How many substances this store's registry holds. `fingerprintChemistry` covers all of them. */
+    get substanceCount(): number;
+    /**
+     * A number standing for what a registered substance *is*, for the fingerprint.
+     *
+     * Its density, porosity, emissivity, shell count and the species it can hold — enough that two
+     * libraries differing anywhere disagree here, and cheap enough to compute once a tick. `§15` asks
+     * for the registry to be covered because two worlds with different substances are different
+     * worlds, and a replay crossing them should say so rather than diverge later.
+     */
+    substanceDigestOf(substance: number): number;
+    /** Global species indices this parcel's substance can hold. */
+    speciesSetOf(substance: number): Int32Array;
+    idOfSpecies(species: number): string;
+    phaseOf(species: number): number;
+    emissivityOf(parcel: number): number;
+    /** When this parcel's substance catches, or `null` where nobody said it does. */
+    ignitionOf(substance: number): IgnitionModel | null;
+    porosityOf(parcel: number): number;
+    /** W/(m·K) at a temperature, or zero where the substance never said. */
+    conductivityOf(parcel: number, temperature: number): number;
+    /** Metres from the outside of shell `shell` to the inside of it. */
+    shellDepthOf(parcel: number, shell: number): number;
+    private checkShell;
+    private grow;
+    private check;
+}