---
name: ferret-physics-chemistry-nuclear
description: Use for reactions and radiation in Ferret: well-stirred vessels with rate laws, equilibrium, heat of reaction, pressure and runaway; radioactive decay, dose through shielding, Geiger counters, reactors with rods and scram, critical assemblies, activation and fallout.
---

# Chemistry and nuclear

## When to use
A cold pack, a batch that runs away, a flame, a radiation hazard map, a reactor that must be scrammed, a bomb's yield.

## The model
**Chemistry:** species and balanced `Reaction`s with Arrhenius rates, in `Vessel`s (volume, temperature, heat exchange `hA`); equilibrium by reversible reactions; only gas moles make pressure; `chem:runaway` fires when heating passes a rate. **Nuclear:** `Inventory` of isotopes with decay chains, `doseRate` through layers of shielding (half-value layers), `Fallout` grid, `Reactor` with prompt and delayed neutrons, rods, xenon, decay heat, `Assembly` against critical mass.

## Steps
1. Chemistry: build `Chemistry` with a `SpeciesLibrary`, `add` reactions (balanced), create `Vessel`s, `react(dt)`.
2. Join to heat with `vesselInPart` (`ferret-physics-links`); burst pressure hands over to `detonate`.
3. Nuclear: add isotopes, sources, shields; `reactor.rods`, `reactor.scram`, `reactor.state`; `radiation.dose`, `radiation.map`.
4. Coasts: coarse `maxSubstep` (0.25–1) for long, slow processes.
5. Commands: `chem.check|info|react`, `isotope.add`, `nuclear.info`.

## Check afterwards
A reversible reaction reaches the same `Kp` at different volumes; dose falls by half per half-value layer; without coolant the scrammed fuel still melts, with flow it does not.

## What usually goes wrong
- `reaction "x" is not balanced`: atoms or charge differ.
- Nothing reacts: `Ea` too high, or the wrong `phase`.
- A flame far too hot: constant heat capacity; use `FLAME_SPECIES` and `methaneFlame`.
- Stable isotopes have no activity: use `add(atoms)`.
- A reactor will not stay critical: rods not at `rodsCritical`.

## Files

- `reference/chemistry.md` — Mixtures that react: reactions with rate laws and equilibrium, catalysts, heat of reaction, pressure in a closed vessel, thermal runaway and bursts.
- `reference/nuclear.md` — Radioactive decay, radiation dose through shielding, Geiger counters, reactors you can run and scram, critical masses, activation and fallout.
- `reference/api-physics-chemistry.md` — every export of `@ferret/physics-chemistry` with signature and doc comment
- `reference/api-physics-nuclear.md` — every export of `@ferret/physics-nuclear` with signature and doc comment
- `reference/commands.md` — 23 commands of these packages with their arguments
- `recipes/reactions-and-radiation.md` — Six recipes: how much lead, a hot patch that fades and washes, a reactor without cooling, equilibrium shifted by squeezing, a rocket that gains with altitude, a barrel that bursts.
- `recipes/chemistry-with-formulas.md` — Six recipes: a substance is a formula, an equation balances itself, a bottle of acid, a piece of lithium in water, lime heating its water, sodium through its melting point.
- `recipes/loss-of-coolant.md` — A reactor runs a turbine, a generator and a lamp. The coolant pump stops; the lamp dies, the trip scrams the core, and decay heat warms the containment.