`@ferret/physics-chemistry`

reactions with rate laws in well-stirred vessels, heat of reaction, pressure, venting.

85 exports · source in packages/physics-chemistry/src

Classes

Chemistry class

class Chemistry

`readonly species: SpeciesLibrary`
`readonly reactions: Map<string, Reaction>`
`method: 'trapezoid' \| 'euler' \| undefined`	The integrator of the vessels: `trapezoid` (second order, adaptive, for burns) or `euler` (implicit Euler with a relative-change step limit: first order but L-stable, for the stiff ionic equilibria of solutions). Left undefined, each vessel picks: `euler` when a reaction that can run in it involves an ion, `trapezoid` otherwise.
`constructor(species: SpeciesLibrary = new SpeciesLibrary())`
`add(name: string, r: ReactionDef): this`	Add a reaction, as an object or as an equation: `add('burn', 'CH4 + 2 O2 -> CO2 + 2 H2O', { A: 1e7, Ea: 100e3 })`. An equation must be balanced as written (use `balanceEquation` to find the coefficients); `<=>` makes it reversible.
`add(name: string, equation: string, params: ReactionParams): this`	Add a reaction, as an object or as an equation: `add('burn', 'CH4 + 2 O2 -> CO2 + 2 H2O', { A: 1e7, Ea: 100e3 })`. An equation must be balanced as written (use `balanceEquation` to find the coefficients); `<=>` makes it reversible.
`add(name: string, r: ReactionDef \| string, params?: ReactionParams): this`	Add a reaction, as an object or as an equation: `add('burn', 'CH4 + 2 O2 -> CO2 + 2 H2O', { A: 1e7, Ea: 100e3 })`. An equation must be balanced as written (use `balanceEquation` to find the coefficients); `<=>` makes it reversible.
`remove(name: string): boolean`	Take a reaction out.
`reactionFromEquation(equation: string, params: ReactionParams): ReactionDef`	The reaction an equation says (species resolved through the library by name or formula); the rate parameters come from `params`.
`balanceEquation(equation: string): { reactants: Record<string, number>; products: Record<string, number>; reversible: boolean; equation: string }`	The smallest whole coefficients that balance an equation written without them (or with wrong ones): `C3H8 + O2 -> CO2 + H2O` gives 1, 5, 3, 4. Species may be library names or any formula. Refuses what cannot be balanced or is not fixed; never applied to `add`.
`formatEquation(r: Pick<ReactionDef, 'reactants' \| 'products' \| 'reversible'>): string`	The text of a reaction: `CH4 + 2 O2 → CO2 + 2 H2O` (species by their names in the library).
`balance(r: ReactionDef): string[]`	Atoms and charge that do not balance, as messages (empty when the reaction is balanced).
`nu(r: ReactionDef): Map<string, number>`	Signed coefficients: negative for reactants.
`dH(r: ReactionDef, T = T_REF): number`	Reaction enthalpy at T, J/mol of reaction.
`dS(r: ReactionDef, T = T_REF): number`
`dG(r: ReactionDef, T = T_REF): number`	Standard Gibbs energy of the reaction at T, J/mol.
`K(r: ReactionDef, T = T_REF): number`	Equilibrium constant in activities (gas: p/p°, solute: c/c°, pure solids and liquids: 1).

packages/physics-chemistry/src/chem.ts:215

EquationError class

class EquationError extends Error

constructor(readonly equation: string, message: string)

packages/physics-chemistry/src/equation.ts:12

FormulaError class

class FormulaError extends Error

constructor(readonly text: string, readonly position: number, message: string)

packages/physics-chemistry/src/formula.ts:13

SpeciesLibrary class

class SpeciesLibrary

`readonly loaded: Set<string>`	Sets loaded so far, by name.
`constructor(initial: Record<string, SpeciesInput> \| string[] = EXAMPLE_SPECIES)`
`loadSet(set: string, keepExisting = false): this`	Add the species of a standard set (a species already here is replaced by the set's: the later load wins; with `keepExisting` it stays).
`add(name: string, s: SpeciesInput)`	Add a species. Its atoms come from its `formula`, or from `atoms`, or from its name when that is a formula (`{ phase: 'g', ... }` under the key `NH3`). When more than one is given they must agree. An ion's `cp` may be negative (a partial molar value); every other phase needs one above zero.
`find(formula: string, phase?: Phase): string \| undefined`	The name of the species with this formula (`"H2O(l)"`, `"NH4+"`), or undefined. A phase in the text or given narrows the search; an exact name wins.
`remove(name: string): boolean`	Take a species out of the library (reactions and vessels that use it must be dealt with first).
`get(name: string): SpeciesDef`
`has(name: string)`
`names()`
`molarMass(name: string): number`	kg/mol

packages/physics-chemistry/src/chem.ts:97

Vessel class

class Vessel

`readonly name: string`
`readonly chem: Chemistry`
`volume: number`
`liquidVolume: number`
`T: number`
`hA: number`
`Tenv: number`
`wallC: number`
`isothermal: boolean`
`holdPressure?: number`	Pa; when set the gas volume follows n R T / p and the energy balance is on the enthalpy
`amounts: Map<string, number>`
`extent: Map<string, number>`	extent of each reaction so far, mol
`lost: number`	heat the surroundings took, J (negative = in)
`dTdt: number`	the largest temperature rise rate over the accepted sub-steps of the last step, K/s (never negative; not the average, so it does not depend on the step length)
`runaway?: number`
`ignition?: number`
`burstPressure?: number`
`entity?: string`
`position?: [number, number, number]`
`method?: 'trapezoid' \| 'euler'`	the integrator of this vessel; the chemistry's choice, or the automatic one (see `Chemistry.method`), when missing
`settled: boolean`
`tolerance: number`
`maxSubsteps: number`
`constructor(chem: Chemistry, o: VesselOptions)`
`add(species: string, mol: number)`
`remove(species: string, mol: number)`
`amount(species: string)`
`get mass(): number`	kg
`get pressure(): number`	Pa
`get capacity(): number`	Heat capacity of the contents (constant volume for gases), J/K.
`get U(): number`	Internal energy of the contents and the wall, relative to the elements at T_REF, J.
`get pH(): number \| undefined`	pH of the solution: -log10 of the H+ concentration (mol/L, ideal dilute solution: no activity coefficients), or undefined when the vessel holds no H+ species or none of it.
`atoms(el: string): number`	Atoms of an element in the vessel (conserved).
`rates(n: number[], T: number): number[]`	The rate of every reaction (mol/s of reaction) at the amounts and temperature given.
`react(dt: number): StepStats`	Advance dt seconds with adaptive sub-steps (implicit trapezoid, step doubling for the error).
`setEnergy(U: number)`	Set the temperature at which the contents hold the internal energy `U` (bisection; the energy rises with the temperature).
`vent(to: Vessel, dt: number, o: { area: number; Cd?: number; length?: number; friction?: number }): number`	Gas through an orifice into another vessel for `dt` seconds: choked above the critical pressure ratio, subsonic below, with the mixture's own gamma and molar mass. The gas leaves carrying its enthalpy, so the vessel it leaves cools as it blows down and the one it enters is heated by it; the internal energy of the two together is kept exactly. A `length` (with a Darcy `friction` factor, 0.02 by default) makes it a pipe: the same flow law with the pipe's losses. Returns the moles moved (negative when the flow runs backwards).
`pour(to: Vessel, fraction: number)`	Move a fraction of the contents (amounts and the heat they carry) into another vessel: a pipe that carries species.

packages/physics-chemistry/src/chem.ts:367

Functions

ACIDS_BASES_SET function

function ACIDS_BASES_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/aqueous.ts:78

addAqueousReactions function

function addAqueousReactions(chem: Chemistry, o: AqueousOptions = {}): string[]

Add the water equilibrium, the acid and base dissociations (water, strong acids and bases, acetic acid, ammonium, the carbonate and phosphate systems) and the solubility of the salts, for every reaction whose species are all in the library. The rate constants are game-grade (fast enough that a solution is at equilibrium within milliseconds); the positions of the equilibria follow exactly from the species data. A vessel in which an ion can appear is integrated with the stiff method (Chemistry.method). Returns the names added.

packages/physics-chemistry/src/sets/aqueous.ts:127

addFlameEquilibria function

function addFlameEquilibria(c: { add(name: string, eq: string, p: { A: number; Ea: number }): unknown; species: SpeciesLibrary; reactions: Map<string, ReactionDef>; dH(r: ReactionDef, T?: number): number }): void

The dissociations and the nitric oxide equilibrium that hold a real flame below its ideal temperature: H2O to H2 and OH, CO2 to CO, H2 and O2 to atoms, N2 + O2 to NO. Fast and reversible (they sit at equilibrium in a flame); their position is exact from the species data. Needs the core and combustion sets.

packages/physics-chemistry/src/sets/index.ts:45

addPhaseChanges function

function addPhaseChanges(chem: Chemistry, o: PhaseOptions = {}): string[]

Add the melting and boiling of the substances of the library as fast reversible reactions melt-X (X(s) <=> X(l)) and boil-X (X(l) <=> X(g)). The phases the library does not hold are made from the data; one it holds is corrected only where its entropy puts the change more than half a kelvin from the tabulated temperature (the gas of a substance is never touched). Returns the names added.

packages/physics-chemistry/src/sets/phases.ts:67

addStandardReactions function

function addStandardReactions(chem: Chemistry, o: StandardReactionOptions = {}): string[]

Add the library reactions whose species are all loaded; returns their names. A game's own reaction with the same name stays.

packages/physics-chemistry/src/sets/families.ts:183

airMoles function

function airMoles(total: number): Record<string, number>

packages/physics-chemistry/src/sets/index.ts:38

AQUEOUS_SET function

function AQUEOUS_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/aqueous.ts:66

chemistry function

function chemistry(chem: Chemistry = new Chemistry()): ChemistryCapability

packages/physics-chemistry/src/index.ts:50

COMBUSTION_SET function

function COMBUSTION_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/index.ts:26

CORE_SET function

function CORE_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/index.ts:19

cpAt function

function cpAt: (d: SpeciesDef, T: number) => number

cp at T, and the enthalpy and entropy gained from T_REF to T, of one species.

packages/physics-chemistry/src/chem.ts:68

dHs function

function dHs: (d: SpeciesDef, T: number) => number

packages/physics-chemistry/src/chem.ts:69

dissolvedName function

function dissolvedName: (gas: string) => string

The aqueous species a dissolved gas becomes (CO2 to CO2(aq)), when the library has one.

packages/physics-chemistry/src/sets/aqueous.ts:161

dSs function

function dSs: (d: SpeciesDef, T: number) => number

packages/physics-chemistry/src/chem.ts:70

ENERGETICS_SET function

function ENERGETICS_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/families.ts:93

findGas function

function findGas(formula: string): GasData | undefined

the data of a gas by formula; undefined when the library holds no such gas

packages/physics-chemistry/src/gases.ts:41

formatFormula function

function formatFormula(atoms: Record<string, number>, charge = 0): string

The canonical text of a composition: Hill order (C, then H, then alphabetical; alphabetical when there is no C), then the charge (^2-, +).

packages/physics-chemistry/src/formula.ts:116

formulaMass function

function formulaMass(atoms: Record<string, number>): number

g/mol of a composition.

packages/physics-chemistry/src/formula.ts:126

fuelHeat function

function fuelHeat(fuel: string, lib: SpeciesLibrary = gasLibrary()): { Q: number; oxygenPerFuel: number; molarMass: number }

The heat of burning a fuel, from the reaction enthalpy of the library: C to CO2 and H to H2O (vapour: the lower heating value), per kg of fuel, and the kg of oxygen it takes. The fuel is any species of the library made of C, H and O (CH4, C3H8, C2H5OH(l), C8H18(l), H2).

packages/physics-chemistry/src/gases.ts:84

gasLibrary function

function gasLibrary(): SpeciesLibrary

packages/physics-chemistry/src/gases.ts:33

gasNames function

function gasNames(): string[]

every gas formula the library holds (and the old name steam)

packages/physics-chemistry/src/gases.ts:38

gasOf function

function gasOf(formula: string, where = 'pneumatics'): GasData

the data of a gas, or an error that names the gases there are

packages/physics-chemistry/src/gases.ts:64

HALOGENS_SET function

function HALOGENS_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/families.ts:44

henryConstant function

function henryConstant(gas: string, T = T_REF): number

Henry's constant of a gas in water at T, mol/(m³·Pa); 0 when the table does not hold the gas.

packages/physics-chemistry/src/sets/aqueous.ts:156

METALS_SET function

function METALS_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/families.ts:56

methaneFlame function

function methaneFlame(c: { add(name: string, r: ReactionDef): unknown }, dissociation = true)

Add to a chemistry the burning of methane and the two dissociations of its products (fast and reversible, so at equilibrium in a flame).

packages/physics-chemistry/src/chem.ts:86

mixtureProps function

function mixtureProps(mix: string | Record<string, number>, T = 293.15): { molarMass: number; cp: number; gamma: number }

Molar mass, cp and gamma of a gas mixture (mole fractions; a formula alone is a pure gas) at T.

packages/physics-chemistry/src/gases.ts:71

nasaCp function

function nasaCp(n: Nasa7, T: number): number

cp, J/(mol·K), at T (held at its end value beyond the range)

packages/physics-chemistry/src/chem.ts:47

nasaH function

function nasaH(n: Nasa7, T: number): number

absolute enthalpy H(T), J/mol (formation enthalpy included; linear in T beyond the range)

packages/physics-chemistry/src/chem.ts:52

nasaS function

function nasaS(n: Nasa7, T: number): number

absolute entropy S(T), J/(mol·K) at the standard pressure

packages/physics-chemistry/src/chem.ts:58

NITROGEN_SET function

function NITROGEN_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/families.ts:30

NOBLE_SET function

function NOBLE_SET: () => Record<string, SpeciesInput>

The noble gases that are not in the GRI table: monatomic ideal gases (cp = 5/2 R, S from the Sackur-Tetrode values at 298.15 K).

packages/physics-chemistry/src/sets/families.ts:197

ORGANICS_SET function

function ORGANICS_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/families.ts:84

parseEquation function

function parseEquation(eq: string): ParsedEquation

Split an equation into its terms. The species tokens are not resolved here.

packages/physics-chemistry/src/equation.ts:19

parseFormula function

function parseFormula(input: string): ParsedFormula

Parse a formula with an optional charge and phase. e- is the electron: no atoms, charge -1.

packages/physics-chemistry/src/formula.ts:26

registerSpeciesSet function

function registerSpeciesSet(name: string, make: () => Record<string, SpeciesInput>): void

packages/physics-chemistry/src/chem.ts:95

SULFUR_SET function

function SULFUR_SET: () => Record<string, SpeciesInput>

packages/physics-chemistry/src/sets/families.ts:37

useGasLibrary function

function useGasLibrary(lib: SpeciesLibrary | undefined)

use another library for every gas (clears what was looked up)

packages/physics-chemistry/src/gases.ts:35

waterMoles function

function waterMoles: (volume: number) => number

Moles of liquid water in a volume (m³) at 25 °C (997 kg/m³).

packages/physics-chemistry/src/sets/aqueous.ts:23

Interfaces

AqueousOptions interface

interface AqueousOptions

`recombination?: number`	m³/(mol·s): the rate constant of the recombination of ions (the diffusion-limited order of magnitude is 1e8); the dissociation rate follows from K
`dissolution?: number`	mol/(m³·s): how fast a solid dissolves while it is present and the solution is far from saturated (a game-grade value)

packages/physics-chemistry/src/sets/aqueous.ts:114

ChemistryCapability interface

interface ChemistryCapability extends Capability

`readonly chemistry: Chemistry`
`readonly vessels: Map<string, VesselEntry>`
`addVessel(name: string, o: VesselOptions): Vessel`
`thresholds(name: string): Thresholds`	The values that decide this vessel's events, with the scope each comes from (for tuning).
`check(): string[]`	Atom, mass and charge-free audit: a list of problems with the reactions of the library (empty when sound).

packages/physics-chemistry/src/index.ts:40

Element interface

interface Element

The periodic table: all 118 elements with their IUPAC standard atomic weights (abridged), and for an element without a stable isotope the mass number of its longest-lived isotope (approx: true). The eighteen elements the library knew before keep the values it always used, so no molar mass in the engine moves. It is one table, so @ferret/physics-nuclear may read the same symbols.

`number: number`
`symbol: string`
`name: string`
`mass: number`
`approx?: boolean`

packages/physics-chemistry/src/elements.ts:6

EquationTerm interface

interface EquationTerm

`coefficient: number`
`token: string`

packages/physics-chemistry/src/equation.ts:9

GasData interface

interface GasData

`readonly name: string`	the library's name
`readonly molarMass: number`	kg/mol
`cp(T: number): number`	cp(T), J/(mol·K)
`cv(T: number): number`	cv(T) = cp − R
`u(T: number): number`	internal energy of a mole, J/mol: cv(T0)·T0 plus the integral of cv from T0 (for a constant cv exactly cv·T)
`h(T: number): number`	enthalpy of a mole carried by a flow, u + R·T
`gamma(T: number): number`	cp/cv at T
`s(T: number): number`	entropy gained from T_REF at constant pressure, J/(mol·K)

packages/physics-chemistry/src/gases.ts:14

Nasa7 interface

interface Nasa7

NASA 7-coefficient polynomials: low from Tmin to Tmid, high from Tmid to Tmax. Outside the range cp stays at its end value.

`Tmin: number`
`Tmid: number`
`Tmax: number`
`low: number[]`
`high: number[]`

packages/physics-chemistry/src/chem.ts:43

ParsedEquation interface

interface ParsedEquation

`reactants: EquationTerm[]`
`products: EquationTerm[]`
`reversible: boolean`

packages/physics-chemistry/src/equation.ts:10

ParsedFormula interface

interface ParsedFormula

`atoms: Record<string, number>`
`charge: number`
`phase?: FormulaPhase`

packages/physics-chemistry/src/formula.ts:11

PhaseOptions interface

interface PhaseOptions

`substances?: string[]`	the substances (keys of `PHASE_DATA`) to add; every one whose condensed phase is in the library by default
`rate?: number`	mol/(m³·s): the rate constant of the change, fast against anything a game heats (default 1e5)
`liquidReactions?: boolean`	also copy every reaction that burns or consumes a solid as a reaction of its liquid (`lithium-water~Li(l)`), default true
`data?: Record<string, PhaseSubstance>`	extra or replacement data by substance

packages/physics-chemistry/src/sets/phases.ts:39

PhaseSubstance interface

interface PhaseSubstance

`s?: string`	names of the phases in the library (made when missing)
`l?: string`
`g?: string`
`Tm?: number`	melting: temperature K and enthalpy J/mol, at 1 bar
`Hfus?: number`
`Tb?: number`	boiling: temperature K at 1 bar and enthalpy J/mol
`Hvap?: number`
`cpl?: number`	heat capacity J/(mol·K) of the liquid and the vapour that are made (the solid's, and 5/2 R for a monatomic vapour, when missing)
`cpg?: number`

packages/physics-chemistry/src/sets/phases.ts:10

Reaction interface

interface Reaction extends ReactionDef

name: string

packages/physics-chemistry/src/chem.ts:213

ReactionDef interface

interface ReactionDef

`reactants: Record<string, number>`	stoichiometric coefficients, positive
`products: Record<string, number>`
`A: number`	rate k = A·exp(−Ea / R T), in mol, m³ and s for the concentrations in the rate law
`Ea: number`
`orders?: Record<string, number>`	reaction orders by reactant (the stoichiometric coefficients when missing; give {} for zero order)
`reversible?: boolean`	runs both ways and settles at the equilibrium of ΔG
`phase?: 'gas' \| 'solution'`	which volume the rate is per: the gas of the vessel or its solution
`stiff?: boolean`	a fast equilibrium (a phase change): the vessel integrates it with the stiff method
`catalysts?: Array<{ species: string; delta: number; minimum?: number }>`	species that speed it up by lowering Ea by `delta` J/mol while present (not consumed)

packages/physics-chemistry/src/chem.ts:191

SpeciesDef interface

interface SpeciesDef

`atoms: Record<string, number>`	atoms by element
`phase: Phase`
`Hf: number`	standard enthalpy of formation, J/mol, and standard entropy, J/(mol·K)
`S?: number`
`cp: number`	molar heat capacity at constant pressure, J/(mol·K), at 298 K
`cpT?: [number, number]`	cp rising with temperature, cp(T) = a + b·T (J/(mol·K)): what keeps a flame from running far too hot; constant `cp` when missing
`charge?: number`	charge, for ions (atoms and charge are both balanced)
`nasa?: Nasa7`	NASA 7-coefficient polynomials in two ranges (cp, H and S for the whole range; used instead of `cpT` and `cp` when present)
`formula?: string`	the canonical formula (Hill order, with the charge), filled in when the species is added

packages/physics-chemistry/src/chem.ts:23

StandardReaction interface

interface StandardReaction extends ReactionParams

`name: string`
`equation: string`
`family: 'combustion' \| 'nitrogen' \| 'sulfur' \| 'halogens' \| 'metals' \| 'energetics' \| 'catalysis'`	family, for `addStandardReactions(chem, { families })`
`dH: number`	the tabulated heat of reaction at 298.15 K, kJ per mole of the reaction as written (CRC / NBS tables; the published heat of explosion for the energetics)
`note: string`	where the rate parameters come from and how far to trust them

packages/physics-chemistry/src/sets/families.ts:111

StandardReactionOptions interface

interface StandardReactionOptions

`families?: StandardReaction['family'][]`	only these families (all by default)
`skip?: string[]`	names that are not added

packages/physics-chemistry/src/sets/families.ts:175

StepStats interface

interface StepStats

`substeps: number`
`rejected: number`
`extent: Record<string, number>`

packages/physics-chemistry/src/chem.ts:365

VesselEntry interface

interface VesselEntry

`vessel: Vessel`
`burstPressure?: number`
`burst: boolean`
`hot: boolean`
`lit: boolean`

packages/physics-chemistry/src/index.ts:39

VesselOptions interface

interface VesselOptions

`name?: string`
`volume: number`	m³ of gas space
`liquidVolume?: number`	m³ of solution (defaults to the gas volume)
`T?: number`
`contents?: Record<string, number>`
`hA?: number`	heat exchange with the surroundings: h·A in W/K, and their temperature
`Tenv?: number`
`wallC?: number`	J/K of vessel material that warms with the contents
`isothermal?: boolean`	hold the temperature (an isothermal reactor)
`pressure?: number`	Pa: let the gas space move (a piston or an open top) so that the pressure stays here; the expansion work goes to the surroundings. `volume` is the start value.
`runaway?: number`	thresholds of this vessel alone (they beat every scope of the capability): thermal runaway and ignition rise rates, K/s, and the bursting pressure, Pa
`ignition?: number`
`burstPressure?: number`
`entity?: string`	the entity the vessel belongs to (its scope: entity and zone values of the capability), and where it stands when it has no entity
`position?: [number, number, number]`
`method?: 'trapezoid' \| 'euler'`	integrator: see `Chemistry.method`

packages/physics-chemistry/src/chem.ts:337

Types

FormulaPhase type

type FormulaPhase = 'g' | 'l' | 's' | 'aq'

packages/physics-chemistry/src/formula.ts:10

Phase type

type Phase = 'g' | 'l' | 's' | 'aq'

packages/physics-chemistry/src/chem.ts:21

ReactionParams type

type ReactionParams = Omit<ReactionDef, 'reactants' | 'products'>

The rate parameters that go with an equation.

packages/physics-chemistry/src/chem.ts:211

SpeciesInput type

type SpeciesInput = Omit<SpeciesDef, 'atoms' | 'phase'> & { atoms?: Record<string, number>; phase?: Phase }

What SpeciesLibrary.add takes: the atoms, or a formula they follow from (or neither, when the name itself is a formula).

packages/physics-chemistry/src/chem.ts:65

ThresholdKey type

type ThresholdKey = 'runaway' | 'ignition' | 'burstPressure'

packages/physics-chemistry/src/index.ts:35

Thresholds type

type Thresholds = Record<ThresholdKey, { value: number | undefined; scope: ThresholdScope | undefined }>

packages/physics-chemistry/src/index.ts:37

ThresholdScope type

type ThresholdScope = 'vessel' | 'entity' | 'zone' | 'level' | 'world' | 'default'

packages/physics-chemistry/src/index.ts:36

Constants

AIR const

const AIR: Readonly<Record<string, number>>

Dry air by moles: the mixture helper of the core set. Multiply by the total moles.

packages/physics-chemistry/src/sets/index.ts:37

ATOMIC_MASS const

const ATOMIC_MASS: Record<string, number>

g/mol by symbol

packages/physics-chemistry/src/elements.ts:34

C_STANDARD const

const C_STANDARD: 1000

standard concentration of a solute, mol/m³ (1 mol/L)

packages/physics-chemistry/src/chem.ts:10

CHEMISTRY_DEFAULTS const

const CHEMISTRY_DEFAULTS: { runaway: number; ignition: number; }

chemical reactions. Vessels are well-stirred reactors stepped with the world: the species react by their rate laws, the heat of reaction changes the temperature, and the gas moles give the pressure.

values, narrowest first (a vessel's own value, then the scopes of host.config('chemistry'): entity, zone, level, world, then the defaults):

  runaway        temperature rise rate that counts as a thermal runaway, K/s   (50)
  ignition       temperature rise rate that counts as ignition, K/s            (1000)
  burstPressure  Pa; a vessel bursts at this pressure                           (none)

A vessel's own values are set in addVessel or by vessel.set. Its scope comes from its entity (the entity's own values and, from the entity's position, the zone it stands in) or, with no entity, from its position. The rise rate is the peak over the sub-steps of the world step, so the events do not depend on the step length.

The level's physics.chemistry block may also carry the library of that level (applied when the level loads, undone when it goes):

  sets        names of standard species sets to load (a species the game already has stays as it is)
  species     { name: { formula?, phase?, Hf, S?, cp, ... } } added, replacing a species of the same name for the life of the level
  reactions   { name: { equation, A, Ea, ... } or { reactants, products, A, Ea, ... } }
  aqueous     true or { recombination?, dissolution? }: `addAqueousReactions`
  standard    true or a list of families: `addStandardReactions`
  phases      true or { substances?, rate?, liquidReactions? }: `addPhaseChanges` (melting and boiling as fast reversible reactions; after `standard`)

The editor writes it with edit.chemistry.*.

events: chem:ignite { name, T, rate }, chem:runaway { name, T, rate }, chem:equilibrium { name }, chem:burst { name, pressure }; each also carries entity when the vessel has one.

packages/physics-chemistry/src/index.ts:33

ELEMENTS const

const ELEMENTS: readonly Element[]

packages/physics-chemistry/src/elements.ts:26

EXAMPLE_SPECIES const

const EXAMPLE_SPECIES: Record<string, SpeciesDef>

packages/physics-chemistry/src/chem.ts:169

FLAME_SPECIES const

const FLAME_SPECIES: Record<string, SpeciesDef>

The gases of a flame with cp rising with temperature (a + b·T fitted to the JANAF values at 298 K and 1500 K, within a few percent to 2500 K), and carbon monoxide, so a flame can dissociate (CO2 ⇌ CO + ½O2, H2O ⇌ H2 + ½O2) and land near a real flame's temperature.

packages/physics-chemistry/src/chem.ts:76

HENRY_WATER const

const HENRY_WATER: Record<string, { k: number; C: number; }>

Henry's law: the dissolved amount at equilibrium is k·p per m³ of water, mol/(m³·Pa) at 298.15 K, with k(T) = k298·exp(C·(1/T − 1/298.15)) (Sander, 2015 compilation; C = −ΔH_solution/R in K). The constant belongs to the gas and the solvent; the pneumatic Dissolver and the aqueous vessel read the same table, and a dissolved gas that reacts (CO2 to carbonic acid, then the pH) is the same amount in both.

packages/physics-chemistry/src/sets/aqueous.ts:150

P_STANDARD const

const P_STANDARD: 100000

packages/physics-chemistry/src/chem.ts:8

PHASE_DATA const

const PHASE_DATA: Record<string, PhaseSubstance>

Melting and boiling data of common substances (CRC Handbook; the heats are per mole at the transition). Key: the formula without a phase.

packages/physics-chemistry/src/sets/phases.ts:22

R_GAS const

const R_GAS: 8.314462618

Species, reactions and well-stirred vessels. A reaction moves amounts between species by a rate law; the heat of reaction comes from the formation enthalpies and the heat capacities, and the temperature follows from the conservation of internal energy, so atoms, mass and energy are conserved by construction and checked by check.

packages/physics-chemistry/src/chem.ts:6

SOLID_EPS const

const SOLID_EPS: 1e-12

a pure solid or liquid counts as present (activity 1) once its amount is well above this many moles, and as absent well below it

packages/physics-chemistry/src/chem.ts:12

SOLUBLE_SOLIDS const

const SOLUBLE_SOLIDS: Record<string, SpeciesInput>

The solids that dissolve and precipitate (NBS standard values).

packages/physics-chemistry/src/sets/aqueous.ts:56

SPECIES_SETS const

const SPECIES_SETS: Map<string, () => Record<string, SpeciesInput>>

The standard sets of species: name -> a function making the table; a set module registers itself.

packages/physics-chemistry/src/chem.ts:94

STANDARD_REACTIONS const

const STANDARD_REACTIONS: StandardReaction[]

The reaction library. Every entry balances, has a tabulated heat of reaction and is added when all its species are loaded.

packages/physics-chemistry/src/sets/families.ts:126

T_REF const

const T_REF: 298.15

packages/physics-chemistry/src/chem.ts:7