Water & gases

What it models

Oxygen and CO₂ are stored as concentrations and relax toward equilibrium at a rate flow and aeration set. Between those relaxations sits the tick’s real budget: every aerobic process in the tank — fish, plants at night, rot, both nitrifier guilds — takes its oxygen out of the same stock, and each one’s rate saturates against what is left, but for the maintenance a fish owes whatever the water holds. Carbon carries it: what oxidises organic matter breathes its carbon out as CO₂ and draws the oxygen that carbon’s formula takes. Carbonate hardness (KH) is the third stock and general hardness (GH) the fourth, and pH is not a stock at all: it is read off CO₂ against KH wherever something needs it.

Status

Mechanic	Status	Why
Oxygen limits every aerobic path	settled	One Monod factor per process, each quoting its own half-saturation, so demand falls with supply. A fish’s and a flora’s is its oxygen pace ω, which limits what it takes in and mobilises, never the maintenance it owes.
Gas exchange	scaffolding	A fraction of the distance to equilibrium per tick, scaled by turnover — and nothing caps that fraction. At full flow with aeration the CO₂ rate reaches 1.125 × the gap, so CO₂ crosses atmospheric and rings back across it rather than approaching it.
O₂ saturation vs temperature	settled	A linear Henry’s-law fit, 10.08 mg/L at 15 °C falling 0.17 per °C — inside 5 % of measured values across the aquarium band.
Gases from carbon	settled	Both gases are read off the carbon a process moves: CO₂ at 44/12 of the carbon oxidised, oxygen at what its formula takes — 32/12 for carbohydrate’s carbon, 1.456 mg a mg of a fish’s reserve burned — and 0.727 mg released per mg of CO₂ fixed. Anaerobic rot breathes its carbon out without drawing any.
Carbon conservation	settled	Every organic pool, every body and the dissolved CO₂ close per atom: carbon enters as food, injected CO₂, the tap’s and the air’s, and stocked fish and plants, and leaves through the surface, water changes, the gravel vac and what is taken out.
Still-water diffusion floor	settled	A filterless tank still exchanges across its surface, at 10 % of the full-flow rate. A rate that starts from a floor, not a switch.
Aeration	scaffolding	A boolean. Any aerating fitting multiplies exchange by exactly 3, off-gasses CO₂ 1.5× faster and injects the same 0.05 mg/L/hr, whatever the tank.
pH from CO₂ and KH	settled	The hobby relation CO₂ = 3 × KH × 10^(7 − pH), derived on read and never stored, so it cannot lag or drift.
Soft-water floor	scaffolding	A fixed 0.1 dKH of background buffer and 0.1 mg/L of residual CO₂ keep pH finite at KH 0 and CO₂ 0. Stand-ins for the phosphate and humic buffers a real tank carries.
Nitrogen moves KH by its charge	settled	Stoichiometric: minting ammonia, nitrifying it, and the flora’s uptake each move an equivalent per proton they take up or release — see KH and pH.
Nitrification at KH 0	scaffolding	Nitrifiers never run short of carbonate: at KH 0 they keep making nitrate and the kh floor absorbs the acid, so a soft tank’s nitrate outgrows its charge. A cycled seed does the same — aqua soil over 0.5 dKH tap seeds 0 dKH beside nitrate its KH never paid for.
Tap, top-off and evaporation	settled	KH and GH are masses, so evaporation concentrates them and every litre of tap water brings tapKh and tapGh with it.
Hardscape and substrate	scaffolding	Hand-set rates and reserves. Calcite dissolves in proportion to [H⁺] and never runs out; driftwood’s tannins and aqua soil’s buffer are finite and taper as they are spent.
Calcite and soil move GH with KH	settled	Stoichiometric: CaCO₃ dissolves into equal CaCO₃-equivalents of Ca²⁺ and carbonate, and soil’s cation exchange takes up Ca²⁺ and Mg²⁺ for the H⁺ that spends carbonate.
Plant uptake of GH	scaffolding	A fixed share of the macronutrients drawn, off leaf-tissue ratios — the figure is on Plants. Calcium has no store and never limits growth.
Bicarbonate uptake by plants	missing	Plants take only free CO₂, so a CO₂-starved planted tank never pulls its KH down or its pH up past the residual.
Calcium and magnesium apart	missing	GH is one pooled stock; no species or plant reads Ca and Mg separately, and nothing models shells.
Supersaturation	missing	Oxygen above saturation is resisted only by the same linear relaxation and then truncated at the 20 mg/L resource bound, which discards the mass. No ebullition.

How it works

Storage

Gases are stored as concentration in mg/L, and nitrogen compounds as mass in mg. That asymmetry is deliberate and it decides who divides: an organism system answers a biological question and returns a mass, so plants, fish and rot each divide their gas mass by standing water before pushing the effect. It is why the same planting moves a nano further than it moves a 300 L.

Alkalinity and general hardness are stored as mass too, both in mg of CaCO₃, and read as dKH and dGH: a German degree is 10 mg/L of CaO, so 10 × MW_CaCO₃ / MW_CaO mg/L of CaCO₃ for either.

Bounds clamp oxygen to 0–20 mg/L, CO₂ to 0–100 and KH and GH to no less than zero.

Gas exchange

saturation = 10.08 − 0.17 × (temperature − 15)      mg/L, floored at 4
turnovers  = flow / capacity
flowFactor = max(minFlowFactor, min(1, turnovers / optimalFlowTurnover))
delta      = baseExchangeRate × aerationFactor × flowFactor × (target − current)

Oxygen’s target is that saturation; CO₂’s is a flat atmospheric 4.0 mg/L. Aeration multiplies the rate by 3, and for CO₂ by a further 1.5 — which is the mechanism behind the oldest trade-off in a planted tank, since an air stone buys oxygen by stripping the carbon.

Temperature	O₂ saturation
18 °C	9.57 mg/L
22 °C	8.89 mg/L
25 °C	8.38 mg/L
28 °C	7.87 mg/L
30 °C	7.53 mg/L

100 L setup	Flow factor	Effective rate	Half-life of a gas deficit
Nothing running	0.10 — the diffusion floor	2.5 %/h	27 h
Canister, no aeration	0.80	20 %/h	3.1 h
Sponge filter, which aerates	0.30 × 3	22.5 %/h	2.7 h
Canister + powerhead	1.00	25 %/h	2.4 h
Canister + powerhead + air pump	1.00 × 3	75 %/h	0.5 h

A sponge filter beats a bare canister on gas exchange in the same tank while moving well under half the water, because it aerates and the canister does not. Aeration, not flow, is the dominant lever.

Injected CO₂

The injector meters a mass (its figure is on Equipment); off-gassing is the CO₂ half of the exchange above. The tank settles where the two balance, less what the plants fix:

steady CO₂ ≈ atmospheric + (injection − plant uptake) / (volume × baseExchangeRate × flowFactor)

The high-tech scenario — 40 gal, canister, 2 bps from an hour before the lights — climbs from ~5 mg/L at dawn to ~29 by lights-off, and pH swings ~0.75 over the day across the KH its soil has stripped.

The tick’s carbon–oxygen budget

Every aerobic draw but an organism’s maintenance multiplies its rate by O₂ / (K + O₂) and quotes its own K; maintenance burns reserve regardless, a fish’s or a flora’s oxygen pace scaling only what it takes in and mobilises. Both gases are read off the carbon each process moves, so each is one reaction rather than two coefficients.

Process	Oxygen	Carbon	K (mg/L)
Photosynthesis	+ fixed CO₂ × 0.727	− each fixer’s Monod draw on the dissolved pool	0.50, on what it fixes (Plants)
Spores	+ fixed CO₂ × 0.727	− the CO₂ they are built of, on their bloom’s Monod beside every fixer	—
Flora respiration	− CO₂ released × 0.727	+	0.50, on mobilisation and repair
Fish metabolism	− 1.456 mg per mg of reserve burned; − 2.664 per mg of carbon in a meal’s excess	+ 3.664 per mg of carbon either releases	1.00, on intake and mobilisation only (Livestock)
Aerobic rot	− 2.664 per mg of carbon oxidised	+ 3.664 per mg of carbon	0.20
Anaerobic rot	—	+ 3.664 per mg of carbon	slides in as the aerobic path runs short
Ammonia oxidation	− 2.819 mg per mg NH₃	—	0.30
Nitrite oxidation	− 0.348 mg per mg NO₂⁻	—	1.10
Aeration bubbles	+ 0.05 mg/L/hr, capped by the gap to saturation	—	—
Gas exchange	± toward saturation	± toward atmospheric	—

K	Rate left at 8.38 mg/L	Rate left at 2.0 mg/L
0.20 — rot	97.7 %	90.9 %
0.30 — AOB	96.5 %	87.0 %
1.10 — NOB	88.4 %	64.5 %

Three consequences, and all three are the point. Demand falls with supply — but for maintenance, a tank cannot draw oxygen it does not have, because the draw shrinks as the stock does. Rot slows rather than stops — as the oxygen runs out it slides to its anaerobic pace, a fifth of the aerobic by default, drawing none and still breathing its carbon out as CO₂. The guild that needs the most air suffers first — NOB carry nearly four times AOB’s constant, which is where standing nitrite in an under-aerated tank comes from. Fish and flora are the draws that never stop: their oxygen pace, read against saturated water, starves them of intake and growth as the water empties, while their maintenance burns whatever the oxygen.

Every base rate multiplied by that factor is a Monod maximum, reached only at infinite oxygen, so what a tank at air saturation reproduces is the fourth column above rather than the constant itself.

Ordering within the tick

Environment and equipment settle first, so CO₂ injection is in the water before plants run. Plants, the blooms and their spores fix and respire carbon in one pass, drawing on one CO₂ stock together, each on its own Monod read at the CO₂ the hour leaves — one solve, so no fixer gets first pick and together they never take the last milligram. Then livestock apply theirs. Gas exchange, rot and the nitrogen cycle run last on one oxygen solve: every aerobic process in the tier runs on the oxygen there is, gas exchange included — each reads its Monod at the level all their draws and the air leave the water at as the hour ends.

KH and pH

dKH = kh / water / CACO3_PER_DEGREE
pH  = 7 − log10((co2 + 0.1) / (3 × (dKH + 0.1)))

pH follows CO₂ and KH the moment either moves: a unit per tenfold change in their ratio. KH is the buffer — the same CO₂ plume swings a soft tank much further than a hard one — and without it pH falls toward ~5.9 rather than without limit.

CO₂	KH 0	KH 1	KH 4	KH 8
4 mg/L — atmospheric	5.86	6.91	7.48	7.77
15 mg/L	5.30	6.34	6.91	7.21
30 mg/L — injected	5.00	6.04	6.61	6.91

What moves KH:

Flow	Direction	Rate
Tap water	+	tapKh per litre added — a fill, a water change, a top-off or the ATO
Evaporation	concentrates	the mass stays, the water goes
Nitrogen	− or +	an equivalent, CACO3_PER_EQUIVALENT = MW_CaCO3 / 2, per proton — below
Calcite rock	+	calciteDissolutionRate per rock at pH 7, ×10 per pH unit lower
Driftwood	−	tanninLeachRate of the piece’s remaining tannins per hour
Aqua soil	−	aquaSoilKhUptake of the tank’s KH per hour, scaled by the share of the bed’s buffer left

Nitrogen moves KH by its charge: KH gains an equivalent for each proton a process takes from the water and loses one for each it releases.

Process	Protons taken per nitrogen
Ammonia minted from organic nitrogen — at the gills, or out of a rotting pool: NH₃ + H⁺ → NH₄⁺	+1
Nitrification, NH₄⁺ → NO₂⁻ (Nitrogen cycle)	−2
Plants and the blooms taking ammonia	−1
Plants and the blooms taking nitrate, from the water or the bed	+1

While KH lasts, these processes move it exactly with the charge on the inorganic nitrogen in the water and the bed, so organic nitrogen carried to nitrate nets one equivalent spent, whatever flora it passes through on the way. Every other flow here — and a fertiliser dose or a water change — moves KH and that charge independently.

Four hobby behaviours fall out. A heavily stocked tank left without water changes drains its KH and its pH sags — old tank syndrome. A lightly stocked one topped off with hard tap water creeps the other way. A calcite scape settles where dissolution, slowing as pH climbs, balances what the tank spends. And a fresh soil tank starts acidic and drifts toward tap chemistry over the months its buffer takes to run down — the reserves themselves are on Equipment. Plants slow the first: a planting that keeps pace with its stocking holds its KH.

GH

GH is calcium and magnesium, the hardness species tolerate and plants build with. It has no chemistry of its own in the tick — the tolerance bands and plant uptake read it — and it moves with KH wherever the two share a cause:

Flow	Direction	Rate
Tap water	+	tapGh per litre added, wherever tap KH arrives
Evaporation	concentrates	the mass stays, the water goes
Calcite rock	+	the same mg as its KH — one flow, written to both
Aqua soil	−	the same mg as its KH uptake, never more than the water holds of either
Plants	−	a fixed share of the nutrients they draw, on Plants

Driftwood and nitrification spend carbonate, not calcium, so a tank that drains its KH keeps its GH. A cycled soil tank sits as far below the tap in GH as the soil took KH, and its KH lower still by the nitrate its month made.

Stocks and rates

Stock	Fills it	Drains it	Unit
oxygen	Gas exchange toward saturation; aeration bubbles; photosynthesis and spores	Fish, flora respiration, aerobic rot, both nitrifier guilds	mg/L
co2	Injection; fish, flora respiration, rot	Off-gassing toward atmospheric; photosynthesis and spores	mg/L
kh	Tap water; calcite; ammonia minted from organic nitrogen; nitrate the flora take	Nitrification; ammonia the flora take; driftwood; aqua soil; the old water a change removes	mg CaCO₃
gh	Tap water; calcite	Aqua soil; plants; the old water a change removes	mg CaCO₃

Key tunables

The tunables are listed in the reference under Gas exchange and Water chemistry, and rot’s pace and oxygen half-saturation under Decomposition.

Seams

Neighbour	Read	Written
Environment	temperature sets O₂ saturation; standing water is the divisor every gas mass passes through; tapKh and tapGh	—
Equipment	flow and aeration set the exchange rate	Hardscape and substrate set the KH and GH flows; the ATO blends oxygen and co2 toward tap values and adds tap kh and gh as it refills
Nitrogen cycle	pH, for the free-ammonia fraction	Rot draws oxygen on its aerobic share and releases co2 from its carbon; both guilds draw oxygen, and their Monod factor is what standing nitrite is made of; rot returns kh on the ammonia it mints, AOB spend it
Light	—	Indirectly: the photoperiod is what makes oxygen and CO₂ swing across a day
Plants	pH and GH, against each species’ band	Photosynthesis adds oxygen and takes co2 and a little gh; respiration does the reverse, day and night; the nitrogen their stores take moves kh
Livestock	pH and GH, against each species’ band	Fish draw oxygen and exhale co2 on every gram they burn and on a meal’s excess, and excrete their ammonia, which returns kh
Algae	pH, against its band	Photosynthesis, its spores’ too, on the plants’ CO₂ stock, respiration day and night — a dense bloom strips CO₂ by day and draws oxygen down by night; the nitrogen its stores take moves kh
Actions	—	A water change blends oxygen and co2 toward tap values and moves kh and gh toward the tap; a top-off adds tap kh and gh
Alerts & logging	—	Oxygen below 4 mg/L and CO₂ above 40 mg/L each raise an alert once per crossing

Source

src/simulation/systems/ for gas exchange, src/simulation/equipment/ for what the scape does to KH and GH, src/simulation/core/ for the molecular weights, the carbonate relation and the Monod and Q10 shapes, src/simulation/config/ for the tunables.