# @ferret/physics-heat: API

temperature of parts, conduction, convection, radiation, phase change, expansion and melting.

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

## Classes

### HeatLibrary

*class* · `packages/physics-heat/src/material.ts:47`

```ts
class HeatLibrary
```

- `constructor(initial: Record<string, HeatMaterial> = EXAMPLE_HEAT_MATERIALS)`
- `add(name: string, m: HeatMaterial)`
- `get(name: string): HeatMaterial`
- `has(name: string)`
- `names()`

### HeatNetwork

*class* · `packages/physics-heat/src/network.ts:108`

```ts
class HeatNetwork
```

Lumped parts joined by conductances, with convection and radiation to the surroundings. Stepped by Crank-Nicolson (second order,
stable at any step); the state is the enthalpy, so a phase change holds the temperature while latent heat is paid and the energy
balance closes exactly. Order is fixed (insertion), so a replay gives the same temperatures.

- `readonly parts: Part[]`
- `readonly links: Link[]`
- `ambient: number`
- `onEvent: ((e: HeatEvent) => void) | null` — called for phase changes and passed limits
- `boundary: number` — heat that crossed the boundary (surroundings, fixed parts), J: lets a test check the balance
- `addPart(d: PartDef): Part`
- `removePart(p: Part)`
- `join(a: Part, b: Part, G: number): Link`
- `unjoin(l: Link)`
- `part(name: string): Part | undefined`
- `add(p: Part, joules: number)` — Put heat into a part now (J).
- `setTemperature(p: Part, T: number)`
- `stored(): number` — Thermal energy stored in all free parts, J.
- `ambientOf(p: Part)`
- `stress(p: Part): number` — Thermal stress in a held bar (Pa, negative = compression) and the free growth of a bar.
- `strength(p: Part): number`
- `grown(p: Part): number`
- `step(dt: number)`
- `grid(o: { name: string; material: HeatMaterial; nx: number; ny?: number; dx: number; dy?: number; thickness: number; T?: number; edge?: { left?: number; right?: number } }): Part[][]` — A bar, a slab or a plate as a grid of parts (cells), joined along the faces: `ny` = 1 makes a rod. The cell at (0, j) can be held at a temperature with `edge`. Returns the cells by [j][i].

## Functions

### enthalpy

*function* · `packages/physics-heat/src/network.ts:77`

```ts
function enthalpy(m: HeatMaterial, mass: number, T: number): number
```

### erfc

*function* · `packages/physics-heat/src/material.ts:91`

```ts
function erfc(x: number): number
```

Complementary error function (Abramowitz-Stegun 7.1.26, error under 1.5e-7).

### expansion

*function* · `packages/physics-heat/src/material.ts:74`

```ts
function expansion: (m: HeatMaterial, length: number, dT: number) => number
```

Free thermal growth of a bar: dL = alpha·L·dT.

### heat

*function* · `packages/physics-heat/src/index.ts:40`

```ts
function heat(o: { network?: HeatNetwork; materials?: HeatLibrary } = {}): HeatCapability
```

### strengthFactor

*function* · `packages/physics-heat/src/material.ts:65`

```ts
function strengthFactor(m: HeatMaterial, T: number): number
```

Strength factor 0..1 of a material at a temperature, from its curve (linear between points, flat beyond).

### temperatureOf

*function* · `packages/physics-heat/src/network.ts:86`

```ts
function temperatureOf(m: HeatMaterial, mass: number, H: number): { T: number; phase: Phase; cap: number }
```

Temperature and phase for an enthalpy: the plateaus hold the melting and boiling points.

### thermalStress

*function* · `packages/physics-heat/src/material.ts:76`

```ts
function thermalStress: (m: HeatMaterial, dT: number) => number
```

Stress in a bar held at both ends: sigma = E·alpha·dT (compression when heated).

### wallConductance

*function* · `packages/physics-heat/src/material.ts:79`

```ts
function wallConductance(layers: Array<{ thickness: number; k: number }>, area: number): number
```

Conductance of a wall of layers in series, W/K: A / sum(L_i / k_i).

## Interfaces

### AttachDef

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

```ts
interface AttachDef extends Omit<PartDef, 'material' | 'name'>
```

- `material: string`
- `name?: string`

### HeatCapability

*interface* · `packages/physics-heat/src/index.ts:26`

```ts
interface HeatCapability extends Capability
```

- `readonly network: HeatNetwork`
- `readonly materials: HeatLibrary`
- `attach(entity: Entity, def: AttachDef): Part` — Give a body's entity a temperature.
- `partOf(entity: Entity): Part | undefined`

### HeatMaterial

*interface* · `packages/physics-heat/src/material.ts:2`

```ts
interface HeatMaterial
```

A material's thermal record: the same data for a rod, a wall, a block of ice and a brake disc.

- `density: number` — kg/m³
- `c: number` — specific heat of the solid, J/(kg·K)
- `k: number` — thermal conductivity, W/(m·K)
- `emissivity?: number` — surface emissivity, 0..1
- `melt?: { T: number; latent: number; c: number }` — melting and boiling: the temperature (K), the latent heat (J/kg) and the specific heat of what comes after
- `boil?: { T: number; latent: number; c: number }`
- `alpha?: number` — linear thermal expansion, 1/K, and Young's modulus, Pa
- `E?: number`
- `sigmaMax?: number` — stress (Pa) the material holds at room temperature, and its fall with temperature as [K, factor] points
- `strengthCurve?: Array<[number, number]>`
- `ignition?: number` — ignition temperature, K

### Link

*interface* · `packages/physics-heat/src/network.ts:62`

```ts
interface Link
```

- `a: Part`
- `b: Part`
- `G: number`
- `id: number`

### Part

*interface* · `packages/physics-heat/src/network.ts:35`

```ts
interface Part
```

- `readonly id: number`
- `readonly name: string`
- `readonly mass: number`
- `readonly material: HeatMaterial`
- `T: number`
- `H: number` — enthalpy, J, from 0 K as a solid
- `area: number`
- `h: number`
- `radiates: boolean`
- `fixed: boolean`
- `ambient?: number`
- `power: number`
- `length: number`
- `held: boolean`
- `reference: number`
- `limit?: number`
- `limitHit: boolean`
- `userData?: unknown`
- `entity?: string` — the entity this part belongs to (a vessel standing in it takes its thresholds from that entity's scope)
- `phase: Phase`
- `flowed: number` — energy that has flowed into the part from its links and surroundings, J (negative = out)

### PartDef

*interface* · `packages/physics-heat/src/network.ts:5`

```ts
interface PartDef
```

- `name: string`
- `mass?: number` — kg; or give `volume` and the density of the material is used
- `volume?: number`
- `material: HeatMaterial`
- `T?: number` — starting temperature, K
- `area?: number` — area exposed to the surroundings, m²
- `h?: number` — convection coefficient to the surroundings, W/(m²·K); 0 = none
- `radiates?: boolean` — emissivity; the material's when missing (and radiation is only counted when `radiates` is true)
- `fixed?: boolean` — held at its temperature (a heat bath, a wall face at a given temperature)
- `ambient?: number` — surroundings of this part, K; the network's ambient when missing
- `power?: number` — continuous heating, W
- `length?: number` — length (m) and whether both ends are held: a bar that cannot grow carries a thermal stress
- `held?: boolean`
- `reference?: number` — installed (stress-free) temperature, K
- `limit?: number` — a limit of temperature (K) that raises `over` once
- `userData?: unknown`

## Types

### HeatEvent

*type* · `packages/physics-heat/src/network.ts:64`

```ts
type HeatEvent = | { kind: 'phase'; part: Part; to: Phase; from: Phase } | { kind: 'over'; part: Part; limit: 'temperature' | 'stress'; value: number }
```

### Phase

*type* · `packages/physics-heat/src/network.ts:3`

```ts
type Phase = 'solid' | 'melting' | 'liquid' | 'boiling' | 'gas'
```

## Constants

### EXAMPLE_CONVECTION

*const* · `packages/physics-heat/src/material.ts:84`

```ts
const EXAMPLE_CONVECTION: Record<string, (v: number) => number>
```

Convection coefficient, W/(m²·K), of a medium at a flow speed: still values plus a velocity term (McAdams-type, as data).

### EXAMPLE_HEAT_MATERIALS

*const* · `packages/physics-heat/src/material.ts:24`

```ts
const EXAMPLE_HEAT_MATERIALS: Record<string, HeatMaterial>
```

### HEAT_DEFAULTS

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

```ts
const HEAT_DEFAULTS: { ambient: number; frictionToHeat: number; contactConductance: number; }
```

temperature. Every part (a body, a wall, a gas, a reservoir) has a temperature; heat moves by conduction between
parts, by convection and radiation to the surroundings, and a phase change holds the temperature while its latent heat is paid.
Work lost in contacts (friction, rolling, inelastic hits) becomes heat in the parts that touched, so the energy balance closes.

values (each at world / level / zone / entity scope):
  ambient              temperature of the surroundings, K                                   (293.15)
  frictionToHeat       share of the mechanical energy lost in a contact that becomes heat    (1)
  contactConductance   W/K between two parts that touch; 0 = no conduction at contacts       (0)

events: `heat:phase` { part, to, from }, `heat:over` { part, limit, value }, `heat:ignite` { part }.

### SIGMA

*const* · `packages/physics-heat/src/material.ts:61`

```ts
const SIGMA: 5.670374419e-8
```

### T_ROOM

*const* · `packages/physics-heat/src/material.ts:62`

```ts
const T_ROOM: 293.15
```