# @ferret/physics-combustion: API

combustion chambers, guns, rockets, piston engines, steam boilers and jets.

48 exports. Generated from the source (`packages/physics-combustion/src`), so it matches the code.

## Classes

### Boiler

*class* · `packages/physics-combustion/src/steam.ts:49`

```ts
class Boiler
```

A drum of water and steam at saturation, by its total mass and internal energy: heat in raises the temperature and the pressure along
the saturation line and boils water off into the space; steam taken out (by a valve, an engine, a turbine) leaves with its enthalpy.
Mass and energy close exactly: what went in is the drum's energy plus what left.

- `readonly volume: number`
- `mass: number`
- `U: number`
- `T: number`
- `quality: number` — steam quality (mass share of vapour) and the water's mass now
- `safety?: { pressure: number; area: number }`
- `vented: number` — steam vented by the safety valve, kg; heat put in, J; enthalpy that left with steam, J
- `heatIn: number`
- `energyOut: number`
- `constructor(d: BoilerDef)`
- `get pressure()`
- `get water()`
- `get steamEnthalpy()` — enthalpy of the saturated steam leaving, J/kg
- `flowThrough(area: number, outside = 101325, Cd = 0.9)` — Choked flow of saturated steam through an area at the drum's pressure into `outside` Pa (γ = 1.3), kg/s.
- `take(kg: number)` — Take steam out, kg (at most what is there as vapour); returns the enthalpy that left, J.
- `feed(kg: number, T = 300)` — Feed water of temperature `T` into the drum, kg: the mass and the water's own energy join the drum's, so cold feed cools it.
- `step(dt: number, heat = 0)` — Advance by dt with a heat input (W); the safety valve vents what it must.

### Chamber

*class* · `packages/physics-combustion/src/thermo.ts:97`

```ts
class Chamber
```

- `volume: number`
- `mass: number`
- `T: number`
- `readonly gas: GasSpec`
- `fuel?: PremixFuel`
- `fuelMass: number`
- `oxygenMass: number`
- `wall?: WallSpec`
- `burstPressure?: number`
- `burst: boolean`
- `ignited: boolean`
- `burnRate: number` — 1/s: how fast the premix burns once lit
- `propellant?: Propellant`
- `burnedPropellant: number`
- `lost: number` — heat that went to the wall, J
- `onBurst: ((r: BurstReport) => void) | null`
- `constructor(o: ChamberOptions)`
- `get R()`
- `get gamma()`
- `get cv()`
- `get cp()`
- `get pressure()`
- `get density()`
- `get U()` — internal energy, J
- `get sound()` — speed of sound, m/s
- `addHeat(joules: number)` — Add heat to the gas at the present volume.
- `setVolume(v: number)` — Change the volume with no heat exchange (compression and expansion do work p·dV).
- `get equivalence(): number` — The equivalence ratio of the premix: 1 is stoichiometric, above is rich.
- `ignite(): boolean` — Light the premix. It does not light outside its limits or with no oxygen or no fuel.
- `burn(dm: number): number` — Burn `dm` kg of the premix at once: the heat goes into the gas, the mass stays (fuel and oxygen become products). Returns what burned.
- `burnPropellant(dt: number): number` — Burn the propellant surface for dt: mass joins the gas at the grain temperature and brings its heat of burning. Returns the mass burned.
- `flow(orifice: Orifice, pa: number): number` — Mass flow, kg/s, through an orifice into a space at `pa`: choked when the pressure ratio is high enough, subsonic below.
- `vent(orifice: Orifice, pa: number, dt: number): number` — Let gas out through an orifice for dt. The gas left behind expands isentropically. Returns the mass out.
- `coolWall(dt: number)` — Heat through the wall for dt (exact for a wall that stays at its temperature).
- `step(dt: number)` — One fixed step: propellant, premix, the wall. Venting is the caller's (it knows the ambient pressure).
- `stored(p0 = P_STD): number` — Energy a vessel releases when it bursts (Brode): (p − p0)·V / (γ − 1), J.

### PistonEngine

*class* · `packages/physics-combustion/src/assemblies.ts:164`

```ts
class PistonEngine
```

A four-stroke engine on a crank: intake, compression, spark and a Wiebe burn, expansion, exhaust. The torque on the crank is
p·A·dx/dθ summed over the angle it turned, so the idle, the torque curve and the stall come out of the cycle.

- `readonly chamber: Chamber`
- `throttle: number`
- `running: boolean`
- `work: number` — work the gas did on the piston over its life, J, and the crank angle it has turned
- `turned: number`
- `readonly spec: Required<Pick<EngineSpec, 'advance' | 'burnDuration' | 'crankcase' | 'cycle' | 'portHalfAngle' | 'scavenging' | 'ignition' | 'autoignition'>> & EngineSpec`
- `misfires: number` — whether the last cycle lit (a diesel that was too cold to light does not)
- `constructor(spec: EngineSpec)`
- `volume(theta: number)`
- `torque(_omega: number, theta: number): number` — The torque on the crank at angle theta (the engine advances its cycle from the angle of the last call).

## Functions

### choke

*function* · `packages/physics-combustion/src/thermo.ts:95`

```ts
function choke: (g: number) => number
```

### combustion

*function* · `packages/physics-combustion/src/index.ts:33`

```ts
function combustion(): CombustionCapability
```

### equilibriumPressure

*function* · `packages/physics-combustion/src/thermo.ts:245`

```ts
function equilibriumPressure(pr: Propellant, throatArea: number, gas: GasSpec, T0: number, z = 0): number
```

Steady chamber pressure of a burning grain: rho·S·a·p^n = p·At / c*, so p^(1−n) = rho·S·a·c* / At.

### exitMach

*function* · `packages/physics-combustion/src/assemblies.ts:116`

```ts
function exitMach(areaRatio: number, gamma: number): number
```

Exit Mach number of a nozzle of the given area ratio (supersonic branch).

### fireGun

*function* · `packages/physics-combustion/src/assemblies.ts:56`

```ts
function fireGun(g: GunSpec): GunShot
```

Fire the gun: the charge burns by Vieille's law in a chamber that grows with the projectile, the mean pressure acts on its base
through the Lagrange pressure gradient, friction resists, and the muzzle velocity emerges from the charge, the mass and the barrel length.

### gasSpec

*function* · `packages/physics-combustion/src/thermo.ts:16`

```ts
function gasSpec(gas: string | Record<string, number>, T = 300): GasSpec
```

A gas as the molar mass and gamma a chamber uses. Any gas of the species library, by formula (`'CO2'`) or as a mixture of mole fractions
(`{ N2: 0.79, O2: 0.21 }`), at the temperature T: the molar mass from the formula, gamma from `cp(T)` of the species.

### latentHeat

*function* · `packages/physics-combustion/src/steam.ts:23`

```ts
function latentHeat(T: number): number
```

Latent heat of vaporisation at T, J/kg (Watson, from 2257 kJ/kg at 100 °C).

### liquidDensity

*function* · `packages/physics-combustion/src/steam.ts:25`

```ts
function liquidDensity(T: number): number
```

Density of saturated liquid water, kg/m³ (DIPPR 105).

### liquidEnergy

*function* · `packages/physics-combustion/src/steam.ts:32`

```ts
function liquidEnergy(T: number): number
```

Specific internal energy of saturated liquid from 0.01 °C, J/kg (cp of water 4.18 kJ/kg·K rising slowly with T).

### nozzle

*function* · `packages/physics-combustion/src/assemblies.ts:126`

```ts
function nozzle(gas: GasSpec, p0: number, T0: number, n: NozzleSpec, pa: number): RocketState
```

Thrust of a chamber at pressure p0 and temperature T0 through a nozzle into ambient pressure pa: F = mdot·ve + (pe − pa)·Ae.

### premixFuel

*function* · `packages/physics-combustion/src/thermo.ts:29`

```ts
function premixFuel(fuel: string, o: { efficiency?: number; limits?: [number, number] } = {}): PremixFuel
```

The fuel of a chamber from the reaction enthalpy of the library: `Q` is the lower heating value of burning the species to CO2 and water
vapour (J/kg) and `oxygenPerFuel` the stoichiometric oxygen, both from the formula and the formation enthalpies. `CH4`, `C3H8`, `H2`,
`C2H5OH(l)`, `C8H18(l)`; `efficiency` and `limits` are the chamber's own.

### resolveGas

*function* · `packages/physics-combustion/src/thermo.ts:18`

```ts
function resolveGas(g: GasSpec | string | Record<string, number>, T = 300): GasSpec
```

a `GasSpec`, a formula or a mixture, as a `GasSpec` (at the temperature T)

### saturationPressure

*function* · `packages/physics-combustion/src/steam.ts:12`

```ts
function saturationPressure(T: number): number
```

Saturation pressure at T (K), Pa.

### saturationTemperature

*function* · `packages/physics-combustion/src/steam.ts:17`

```ts
function saturationTemperature(p: number): number
```

Saturation temperature at p (Pa), K.

### steamWork

*function* · `packages/physics-combustion/src/steam.ts:121`

```ts
function steamWork(p1: number, p2: number, efficiency = 0.7): number
```

Work of steam expanded through a turbine or an engine from p1 to p2, J/kg: the isentropic drop of a perfect gas with γ = 1.3 from the
saturation temperature at p1, times the machine's efficiency. A sketch of the steam chart, not Mollier's: within about 10 % for
saturated steam expanded to a condenser.

### turbofan

*function* · `packages/physics-combustion/src/jet.ts:72`

```ts
function turbofan(spec: FanSpec, V0: number, T0 = 288.15, p0 = 101325): FanPoint
```

The same cycle with a fan: the fan lifts all the air, a fraction `bypass / (1 + bypass)` goes round the core to its own nozzle, the turbine drives
fan and compressor together, and an optional afterburner reheats the core gas to T7 before the hot nozzle. Per kg/s of core air, so `bypass = 0`,
`fanRatio = 1` and no reheat is exactly `turbojet`.

### turbojet

*function* · `packages/physics-combustion/src/jet.ts:32`

```ts
function turbojet(spec: JetSpec, V0: number, T0 = 288.15, p0 = 101325): JetPoint
```

The engine at a flight speed `V0` (m/s) in air of temperature `T0` and pressure `p0`.

### vapourVolume

*function* · `packages/physics-combustion/src/steam.ts:27`

```ts
function vapourVolume(T: number): number
```

Specific volume of saturated steam, m³/kg, from Clapeyron.

## Interfaces

### BoilerDef

*interface* · `packages/physics-combustion/src/steam.ts:34`

```ts
interface BoilerDef
```

- `volume: number` — drum volume, m³
- `water: number` — water in it, kg, and the starting temperature, K (saturated: the space above is steam)
- `T?: number`
- `safety?: { pressure: number; area: number }` — the safety valve: opening pressure (Pa) and its flow area (m²)

### BurstReport

*interface* · `packages/physics-combustion/src/thermo.ts:93`

```ts
interface BurstReport
```

- `pressure: number`
- `energy: number`
- `volume: number`
- `mass: number`
- `T: number`

### ChamberEntry

*interface* · `packages/physics-combustion/src/index.ts:24`

```ts
interface ChamberEntry
```

- `chamber: Chamber`
- `vent?: Orifice`
- `entity?: Entity`
- `casing?: number`

### ChamberOptions

*interface* · `packages/physics-combustion/src/thermo.ts:76`

```ts
interface ChamberOptions
```

- `volume: number`
- `gas?: GasSpec | string | Record<string, number>` — the gas: a `GasSpec`, or a formula / mixture of the species library (default air)
- `mass?: number` — kg of gas (with the fuel and oxygen inside it), or give a pressure with the temperature
- `pressure?: number`
- `T?: number`
- `fuel?: PremixFuel`
- `fuelMass?: number` — kg of fuel and of oxygen inside the gas
- `oxygenMass?: number`
- `wall?: WallSpec`
- `burstPressure?: number` — the chamber ruptures above this pressure

### CombustionCapability

*interface* · `packages/physics-combustion/src/index.ts:25`

```ts
interface CombustionCapability extends Capability
```

- `readonly chambers: Map<string, ChamberEntry>`
- `addChamber(name: string, chamber: Chamber, o?: { vent?: Orifice; entity?: Entity; casing?: number }): Chamber`
- `fire(name: string, spec: GunSpec, o?: { body?: RigidBody; direction?: Vec3; muzzle?: Vec3; spawn?: boolean }): GunShot` — Fire a gun; with a body the recoil impulse is applied to it opposite to `direction`, and a projectile is spawned.
- `engine?: PistonEngine`

### EngineSpec

*interface* · `packages/physics-combustion/src/assemblies.ts:135`

```ts
interface EngineSpec
```

- `bore: number` — bore and crank radius (half the stroke) and rod length, m
- `crank: number`
- `rod: number`
- `compressionRatio: number`
- `fuel: PremixFuel`
- `airFuelRatio: number` — kg of air per kg of fuel
- `advance?: number` — spark advance before top dead centre, rad, and how long the burn takes, rad of crank
- `burnDuration?: number`
- `air?: () => { pressure: number; temperature: number; oxygen: number }` — the air the engine breathes: pressure, temperature and the oxygen share by mass
- `crankcase?: number` — pressure under the piston, Pa
- `cycle?: 'four' | 'two'` — 'four' (default): intake, compression, power, exhaust over two turns; 'two': a power stroke every turn, the gas exchanged through ports near the bottom
- `portHalfAngle?: number` — two-stroke: how far each side of the bottom dead centre the ports stay open, rad of crank (1.0), and the share of the cylinder the fresh charge fills (0.8)
- `scavenging?: number`
- `ignition?: 'spark' | 'compression'` — 'spark' (default): a premixed charge lit at the advance; 'compression' (a diesel): air alone is drawn in, fuel is injected at the advance (the throttle is the fuel quantity) and lights if the compressed air is hotter than `autoignition` (K, 750)
- `autoignition?: number`

### FanPoint

*interface* · `packages/physics-combustion/src/jet.ts:60`

```ts
interface FanPoint extends JetPoint
```

- `thrustPerAir: number` — thrust per kg/s of all the air (core plus bypass), m/s; `specificThrust` is per kg/s of core air
- `fuelAfterburner: number` — fuel burned in the afterburner per kg of core air, and the exit speeds of the hot and the bypass streams
- `hotExhaust: number`
- `bypassExhaust: number`

### FanSpec

*interface* · `packages/physics-combustion/src/jet.ts:52`

```ts
interface FanSpec extends JetSpec
```

- `bypass: number` — bypass ratio: kg of air past the core per kg through it (0 = a turbojet)
- `fanRatio: number` — fan pressure ratio (the bypass stream leaves at this ratio; the core compressor adds `pressureRatio` on top) and the fan efficiency
- `etaFan?: number`
- `T7?: number` — afterburner (reheat) exit temperature, K, its combustion efficiency and total pressure ratio; absent = dry
- `etaAfterburner?: number`
- `afterburnerPressure?: number`

### GasSpec

*interface* · `packages/physics-combustion/src/thermo.ts:11`

```ts
interface GasSpec
```

- `molarMass: number`
- `gamma: number`

### GunShot

*interface* · `packages/physics-combustion/src/assemblies.ts:29`

```ts
interface GunShot
```

- `muzzleVelocity: number`
- `time: number` — s
- `peakPressure: number`
- `muzzlePressure: number`
- `kinetic: number` — kinetic energy of the projectile and the chemical energy of the charge, J
- `chemical: number`
- `projectileMomentum: number` — momentum of the projectile and of the gas in the barrel at exit (Lagrange: half of the gas mass at the projectile speed), kg·m/s
- `gasMomentum: number`
- `recoilImpulse: number` — momentum the gun takes while the projectile is in the bore: the integral of the breech force less friction
- `muzzleImpulse: number` — impulse of the gas that escapes after the muzzle, with a nozzle-less exhaust speed, kg·m/s
- `burst: boolean`
- `burned: number`
- `wallLoss: number` — heat the wall took, J
- `trace: Array<{ t: number; x: number; v: number; p: number }>`

### GunSpec

*interface* · `packages/physics-combustion/src/assemblies.ts:4`

```ts
interface GunSpec
```

- `bore: number` — bore diameter, m
- `length: number` — travel of the projectile in the barrel, m
- `projectile: number` — projectile mass, kg
- `chamberVolume: number` — empty chamber volume behind the projectile at the start, m³
- `charge: Propellant`
- `gas?: GasSpec | string | Record<string, number>`
- `startForce?: number` — force that holds the projectile until it is overcome (engraving), N, and the friction while it moves, N
- `friction?: number`
- `efficiency?: number` — share of the heat of burning that reaches the gas (the rest is lost to the walls)
- `covolume?: number` — Noble-Abel covolume of the gas, m³/kg: the molecules take room, p (V − η m) = m R T (about 1e-3 for a propellant gas; 0 = ideal)
- `wallHeat?: number` — heat the bore takes from the gas: coefficient W/(m² K) over the wetted wall (the chamber's and the bore's behind the base), and the wall temperature, K
- `wallTemperature?: number`
- `burstPressure?: number` — barrel rupture pressure, Pa
- `ambient?: number`

### JetPoint

*interface* · `packages/physics-combustion/src/jet.ts:19`

```ts
interface JetPoint
```

- `specificThrust: number` — thrust per kg/s of air, N·s/kg (the specific thrust, m/s)
- `fuelAir: number` — fuel per kg of air, and per newton of thrust per second (the thrust-specific fuel consumption), kg/(N·s)
- `tsfc: number`
- `exhaust: number` — exhaust speed, m/s, and the temperatures after compressor and turbine, K
- `T3: number`
- `T5: number`
- `thermal: number` — thermal efficiency (kinetic energy gained over fuel energy), propulsive efficiency 2 V0 / (Ve + V0) and their product
- `propulsive: number`
- `overall: number`

### JetSpec

*interface* · `packages/physics-combustion/src/jet.ts:7`

```ts
interface JetSpec
```

A turbojet as a Brayton cycle with the losses of its parts: ram compression in the inlet, a compressor of pressure ratio π_c and efficiency η_c,
a burner that heats the air to T4 (fuel from the energy balance, with its efficiency and pressure loss), a turbine that takes exactly the power
the compressor needs, and a nozzle that expands to the ambient pressure. Constant specific heat and gamma through the engine; the gas leaving
is air plus fuel. One kilogram per second of air is the unit: thrust and fuel flow scale with the mass flow.

- `pressureRatio: number` — compressor pressure ratio and the isentropic efficiencies of compressor, turbine and nozzle
- `etaCompressor?: number`
- `etaTurbine?: number`
- `etaNozzle?: number`
- `inletRecovery?: number` — pressure recovery of the inlet, pressure ratio of the burner, burner efficiency, mechanical efficiency of the shaft
- `burnerPressure?: number`
- `etaBurner?: number`
- `etaMechanical?: number`
- `T4: number` — turbine inlet temperature, K
- `lhv?: number` — heating value of the fuel, J/kg
- `gamma?: number`
- `cp?: number`

### NozzleSpec

*interface* · `packages/physics-combustion/src/assemblies.ts:113`

```ts
interface NozzleSpec
```

- `throatArea: number`
- `exitArea: number`

### Orifice

*interface* · `packages/physics-combustion/src/thermo.ts:63`

```ts
interface Orifice
```

- `area: number`
- `Cd?: number`

### PremixFuel

*interface* · `packages/physics-combustion/src/thermo.ts:35`

```ts
interface PremixFuel
```

A fuel mixed into the gas of the chamber (petrol vapour in air, hydrogen, a gas fuel).

- `Q: number` — heating value, J per kg of fuel
- `efficiency?: number` — share of it that becomes heat in the gas (combustion efficiency)
- `oxygenPerFuel: number` — stoichiometric kg of oxygen per kg of fuel
- `limits?: [number, number]` — burn only when the equivalence ratio (fuel / stoichiometric fuel for the oxygen present) lies in this range

### Propellant

*interface* · `packages/physics-combustion/src/thermo.ts:47`

```ts
interface Propellant
```

A solid propellant that burns on its surface by Vieille's law r = a·p^n.

- `density: number` — kg/m³
- `a: number` — burn rate coefficient: r in m/s with p in Pa
- `n: number`
- `Q: number` — heat of burning, J/kg
- `T?: number` — temperature of the grain before it burns, K
- `surface: (z: number) => number` — burning surface as a function of the burned fraction z (0..1), m²
- `mass: number` — total charge, kg

### RocketState

*interface* · `packages/physics-combustion/src/assemblies.ts:123`

```ts
interface RocketState
```

- `mdot: number`
- `exitVelocity: number`
- `exitPressure: number`
- `thrust: number`

### WallSpec

*interface* · `packages/physics-combustion/src/thermo.ts:65`

```ts
interface WallSpec
```

- `area: number` — m²
- `h: number` — W/(m²·K)
- `T?: number` — temperature of the wall, K; kept fixed unless it has a heat capacity
- `C?: number` — J/K of the wall; infinite when missing (the wall stays at its temperature)

## Constants

### AIR

*const* · `packages/physics-combustion/src/thermo.ts:20`

```ts
const AIR: GasSpec
```

dry air, from the species library

### COMBUSTION_DEFAULTS

*const* · `packages/physics-combustion/src/index.ts:22`

```ts
const COMBUSTION_DEFAULTS: { ambient: number; }
```

combustion and gas under pressure. Chambers are stepped with the world: the premix burns, the propellant burns by
Vieille's law, heat goes to the wall, gas leaves through its vent, and a chamber past its burst pressure ruptures into the blast of X.
Guns are fired as a whole (the interior ballistics run in a few milliseconds) and give the muzzle velocity and the recoil.

values (each at world / level / zone / entity scope):
  ambient   pressure outside the chambers, Pa      (101325)

events: `chamber:burst` { name, pressure, energy }, `combustion:out` { name }, `gun:fired` { name, shot }.

### COMBUSTION_GAS

*const* · `packages/physics-combustion/src/thermo.ts:22`

```ts
const COMBUSTION_GAS: GasSpec
```

the gas of a propellant charge, a default for when no mixture is given (a propellant's products are not species of the library)

### P_CRIT

*const* · `packages/physics-combustion/src/steam.ts:9`

```ts
const P_CRIT: 22064000
```

### P_STD

*const* · `packages/physics-combustion/src/thermo.ts:9`

```ts
const P_STD: 101325
```

### R_STEAM

*const* · `packages/physics-combustion/src/steam.ts:9`

```ts
const R_STEAM: 461.526
```

### R_UNIVERSAL

*const* · `packages/physics-combustion/src/thermo.ts:8`

```ts
const R_UNIVERSAL: 8.314462618
```

### T_CRIT

*const* · `packages/physics-combustion/src/steam.ts:9`

```ts
const T_CRIT: 647.096
```