Tunables

A tunable is a claim about how real aquariums behave, held apart from the code that reads it. All of them live in src/simulation/config/, addressed as section.key.

Every tunable declares its own metadata alongside its default — a label, a unit, a spinner step and, for everything but eight nitrogen-cycle leaves, a min/max. Two writers consult that range: the CLI refuses a config set outside it, and the tunables drawer holds its field to it. The save path does not — its bounds are hand-written per leaf and mostly assert shape rather than range, so a stored digestionRate of −1 loads without complaint against a declared minimum of 0.01. A module constant elsewhere in the engine — an alert line, an action bound, a device rating — is not a tunable: it declares no range, and the config layer cannot reach it.

Sections

Section	Path prefix	Governs
Decomposition	decomposition.	How fast food, waste and the bed’s mulm rot, what temperature and oxygen do to it, and how fast food and waste settle into the bed
Nitrogen cycle	nitrogenCycle.	Ammonia to nitrite to nitrate, and the two nitrifier guilds
Gas exchange	gasExchange.	O₂ and CO₂ across the surface, and what aeration does to both
Temperature	temperature.	Drift toward the room, scaled by tank size
Evaporation	evaporation.	Water lost per day, and how warmth accelerates it
Algae	algae.	What thriving plants do to any bloom; a bloom’s own kind is its traits, and the rest of it runs on plants.
Optics	optics.	What the water column, the blooms and the leaves above take out of the light on the way down
Water chemistry	waterChemistry.	What calcite, driftwood and aqua soil do to KH and GH
Plants	plants.	Photosynthesis, the energy budget and stores, harm, income, shedding
Nutrients	nutrients.	Fertilizer formula, root tab, the bed’s leak, half-saturations, demand tiers, minerals in food
Livestock	livestock.	The food’s carbon and nitrogen, feeding, pace, toxin loads, health and repair, broods, death

The values themselves are not repeated here. They move when the model is recalibrated, and the file that holds each one carries the reference it was read off — which is the part that makes a number checkable.

Decomposition

Tunable	Meaning	Unit
rate.food · .waste · .mulm	First-order rate each pool rots at, at the reference temperature in oxygenated water — the aerobic path’s Monod maximum	/hr
q10	Factor every rot rate multiplies by per 10 °C	—
referenceTemp	Temperature the rot rates are quoted at	°C
oxygenHalfSaturation	Dissolved O₂ at which the aerobic path runs at half rate	mg/L
anaerobicShare	The anaerobic path’s pace in water with no oxygen, as a share of the aerobic	of aerobic
settlingRate	First-order rate food and standing waste settle into the bed in still water	/hr
settlingHalfTurnover	Tank turnovers per hour at which flow halves settling	turnovers/hr

Nitrogen cycle

Tunable	Meaning	Unit
bacteriaProcessingRate	Ammonia one bacteria unit oxidises per tick — the Monod maximum, at saturating ammonia and oxygen	mg/unit/tick
seedingRate	Nitrifiers settling into the tank per litre of water per tick, each guild	units/L/tick
aobGrowthRate	AOB per-capita growth at full utilization — ln 2 over the guild’s doubling time	/tick
nobGrowthRate	NOB per-capita growth at full utilization — ln 2 over the guild’s doubling time	/tick
bacteriaPerCm2	Biofilm carrying capacity — the colony’s ceiling per cm² of surface	units/cm²
bacteriaDeathRate	Maintenance loss — ln 2 over a starved colony’s half-life — charged whether or not the colony is working	/tick
q10	Factor every nitrifier rate multiplies by per 10 °C	—
referenceTemp	Temperature the nitrifier rates are quoted at	°C
aobOxygenHalfSaturation	Dissolved O₂ at which AOB oxidise and grow at half rate	mg/L
nobOxygenHalfSaturation	Dissolved O₂ at which NOB oxidise and grow at half rate	mg/L
aobAmmoniaHalfSaturation	Total ammonia, as NH₃, at which AOB oxidise at half rate	ppm
nobNitriteHalfSaturation	Nitrite, as NO₂⁻, at which NOB oxidise at half rate	ppm

The four half-saturation constants are measured concentrations and carry a range. The eight leaves above them were never given bounds, so a writer that asks gets nothing back. A test asserts exactly that split, so the gap is stated rather than discovered.

A bacteria unit is 10⁶ cells, which is what makes bacteriaPerCm2 a biofilm density you can look up rather than a score. Throughput, ceiling density and seeding rate carry an exact gauge symmetry — three numbers, two physical degrees of freedom — so one of them is a units convention, and the ceiling density is the one pinned to a real measurement.

Gas exchange

Tunable	Meaning	Unit
atmosphericCo2	CO₂ concentration the water equilibrates toward	mg/L
o2SaturationBase	O₂ saturation at the reference temperature	mg/L
o2SaturationSlope	Change in O₂ saturation per °C — warmer water holds less	mg/L/°C
o2ReferenceTemp	Temperature the saturation base is quoted at	°C
baseExchangeRate	Share of the gap to equilibrium crossed per tick at optimal flow	/tick
optimalFlowTurnover	Tank turnovers per hour at which exchange is maximal	×/hr
minFlowFactor	Floor on the flow factor, as a share of the optimal-flow rate — still-surface diffusion, so a filterless tank still breathes	×
aerationExchangeMultiplier	Multiplier on the exchange rate while aeration runs	×
aerationDirectO2	O₂ injected directly by bubble dissolution, only below saturation	mg/L/hr
aerationCo2OffgasMultiplier	Extra CO₂ off-gassing while aerating	×

Temperature

Tunable	Meaning	Unit
coolingCoefficient	Drift toward the room per °C of difference, at the reference volume	°C/hr/°C
referenceVolume	Volume the cooling coefficient is quoted at	L
volumeExponent	How drift scales with volume — the surface-to-volume ratio	—
roomDailySwing	How far the room runs above its mean at 17:00 and below it at 05:00	°C
lightWarmingPerPar	Warming a lit fixture adds to the temperature the water drifts toward, per surface PAR	°C/PAR

Evaporation

Tunable	Meaning	Unit
baseRatePerDay	Share of standing water lost per day at thermal equilibrium, before the lid	/day
tempDoublingInterval	Water–room temperature difference, either way, that doubles the rate	°C

Algae

Both kinds of bloom run on the plants’ constants, and what a kind is — its habitat, its pace, its carbon, nitrogen and phosphorus affinities, its tissue and quotas, its spores — sits in its traits, beside the plant species (Algae). What is left here holds for every kind.

Tunable	Meaning	Unit
allelopathySeverity	How hard thriving plants’ exudates cut a bloom’s assimilation: it runs at 1 / (1 + severity × rate units of thriving plant per litre); at 0 plants leave blooms alone	L/unit

Optics

Tunable	Meaning	Unit
waterAttenuationPerCm	Beer–Lambert attenuation of the water column, per cm of depth	/cm
leafAttenuationPerLai	Beer–Lambert extinction of a canopy, per unit of leaf area index; at 0 leaves shade nothing and a plant reads the water alone	/LAI

Blooms

Tunable	Meaning	Unit
algaeAttenuationPerCm	Beer–Lambert extinction a bloom suspended in the column adds at full coverage, per cm of depth; at 0 it shades nothing	/cm
algaeCoatOpticalDepth	Beer–Lambert optical depth of a full coat of bloom on a lit surface, every leaf included; at 0 it shades nothing	–

Water chemistry

Tunable	Meaning	Unit
calciteDissolutionRate	CaCO₃ one calcite rock dissolves per hour at pH 7, scaled by [H⁺]	mg/h
tanninLeachRate	Share of a driftwood piece’s remaining tannins leached per hour	/h
aquaSoilKhUptake	Share of the tank’s KH a fresh aqua soil bed takes up per hour, scaled by the buffer left — and as much GH with it	/h

Plants

Tunable	Meaning	Unit
basePhotosynthesisRate	Rate one rate unit — 500 cm² of leaf at growth rate 1 — fixes carbon at, at full carbon and saturating light	/hr
lowCo2HalfSaturation · mediumCo2HalfSaturation · highCo2HalfSaturation	CO₂ at which a species of each carbon need photosynthesises at half rate	mg/L
saturationIrradianceFactor	Multiple of a species’ band low at which its light response saturates — the Ik of the light curve	× band low
baseRespirationRate	Maintenance per rate unit of leaf at growth rate 1, as a share of the saturated rate, owed around the clock	/hr
paceQ10 · paceReferenceTemp	Factor the pace every rate of a flora’s budget runs at multiplies by per 10 °C, and the temperature it is 1 at	— · °C
oxygenHalfSaturation	Dissolved O₂ half-saturating a flora’s oxygen pace, read against saturated water — its intake and mobilisation, never its upkeep	mg/L
co2PerRateUnit	CO₂ carried by one rate unit, fixed and released alike; oxygen derives from it at the molar ratio	mg

Energy budget

Tunable	Meaning	Unit
somaShare	κ: share of a plant’s mobilised reserve that goes to its soma; the rest fills its offshoot buffer	—
growthEfficiency	κ_G: share of new structure’s cost that ends up in it; the rest is burned building it	—
reserveCapacity	[E_m]: reserve a gram of structure holds when full	g/g
healingRate · healingCost	First-order rate a flora repairs its condition deficit at, at the reference temperature, and the hours of its maintenance a point costs	/hr · h

Nutrient stores

Tunable	Meaning	Unit
storeFillDays	Days an empty store fills 63 % of the way in, from a saturating pool	days
droopEdge · nutrientDeficiencySeverity	The share of the Droop limit its full stores reach that a flora counts as fed at, so the edge sits under full stores at any quotas, and the damage at a Droop limit of 0, falling linearly to nothing at the edge	× full · %/hr
quotaMin.nitrate · .phosphate · .potassium · .iron	Q_min: each nutrient’s element in a gram of plant structure	mg/g
quotaMax.nitrate · .phosphate · .potassium · .iron	Q_max: the same, with every store full	mg/g

Harm, income, shedding

Tunable	Meaning	Unit
starvationSeverity	Damage at the hour’s upkeep wholly unpaid, scaled by the share unpaid	%/hr
lightExcessiveSeverity	Damage per PAR unit above the species’ tolerable band	%/PAR/hr
temperatureStressSeverity · phStressSeverity · ghStressSeverity	Damage per °C, pH unit or dGH outside the species’ tolerable band	%/unit/hr
nitrateStressSeverity · nitrateEdge	Damage per e-fold of NO₃ past the plant’s own edge, and where a hardiness-0 plant’s edge sits	%/e-fold/hr · ppm
co2BenefitPeak · temperatureBenefitPeak · phBenefitPeak	Recovery earned per factor at its best — temperature and pH at the band’s centre; all three run on reserve density times the Droop limit’s share of full stores’	%/hr
maxSheddingRate	Share of itself a plant sheds per hour at condition 0, falling with the square of the deficit	/hr

Every severity is pre-hardiness: a species’ hardiness scales each by 1 − hardiness, except nitrate, whose edge it carries out.

Nutrients

Tunable	Meaning	Unit
fertilizerFormula.nitrate · .phosphate · .potassium · .iron	The all-in-one fertilizer’s composition per ml	mg/ml
rootTab.nitrate · .phosphate · .potassium · .iron	What one root tab pushes into the bed	mg
bedLeakRate	Share of each nutrient the bed holds that leaks into the water per hour	/hr
halfSaturation.ammonia · .nitrate · .phosphate · .potassium · .iron	The ppm of each form — total ammonia as NH₃ — at which a full-demand plant’s stores get half what they ask of its nutrient	ppm
demand.low.* · demand.medium.* · demand.high.*	Each tier’s share of the full need, per nutrient; scales the half-saturation of every form the nutrient comes in, ammonia’s by nitrate’s	—
foodMineralContent.phosphate · .potassium · .iron	Minerals in a gram of food; its nitrogen and carbon are under Livestock	mg/g

Livestock

A fish’s energy budget — growth, reserve, maturity, brood buffer, ageing — comes from its species’ Add-my-Pet entry and is a fixed table, not a tunable. These are what the tank does with it.

Tunable	Meaning	Unit
digestionRate	First-order rate a gut digests at, at 20 °C; the species’ Arrhenius factor paces it	/hr
oxygenHalfSaturation	Dissolved O₂ at which a fish’s oxygen pace ω — its assimilation ceiling and energy conductance — is half what saturated water gives	mg/L
foodNitrogenFraction	Nitrogen in a gram of food	g N/g food
foodCarbonFraction	Carbon in a gram of food	g C/g food
temperatureStressSeverity · phStressSeverity · ghStressSeverity	Damage per °C, pH unit or dGH outside the species’ tolerable band	%/unit/hr
ammoniaStressSeverity · nitriteStressSeverity · nitrateStressSeverity · oxygenStressSeverity	Damage per e-fold past the fish’s own tolerance edge, which hardiness moves out — the toxins on its load, free NH₃ not total ammonia; oxygen counts e-folds under	%/e-fold/hr
loadRate.ammonia · .nitrite · .nitrate	Dominant rate a fish of 1 cm structural length loads and clears each toxin at, at 20 °C; its Arrhenius factor paces it and its length divides it	/hr
loadAssimilationSeverity	How hard a fish’s load, in e-folds past its own edges summed, lowers its assimilation ceiling	/e-fold
waterLevelStressSeverity · flowStressSeverity	Damage per % of capacity under the threshold, and per turnover above the species’ tolerance	%/%/hr · %/turnover/hr
waterLevelStressThreshold	Share of capacity the water-level stressor switches on under	%
starvationSeverity	Damage at a maintenance left wholly unpaid, before hardiness; the hour’s shortfall scales it	%/hr
hazardSeverity	Damage per unit of the fish’s DEB hazard, an hourly rate: what age does to health	%/hr per hazard
phBenefitPeak · oxygenBenefitPeak · plantBenefitPeak	Recovery earned per factor at its best, on a full reserve	%/hr
plantBenefitSaturationPoint	Plant power at which the planted-tank benefit stops growing	power
healingRate	First-order rate a fish repairs its health deficit at, at 20 °C, paid from its reserve	/hr
healingCost	Hours of a fish’s somatic upkeep one point of repair costs	h
maleBufferTurnover	First-order rate a male burns the brood buffer he has not spent fathering, at 20 °C	/hr
eggSensitivity	How many times harder the water harms a laid egg than a fish loaded to that water, as a share of the clutch an hour; a carried brood takes its mother’s harm	×
eggPredationRate	Share of a laid clutch an hour one gram of predator mass per litre — the grams each fish outweighs an egg — eats, before the clutch’s exposure	L/g/hr
predationRate	Damage an hour, before hardiness, one gram per litre of predator mass — the grams each larger fish outweighs the prey — does a fish at no size	%/hr per g/L
preyVulnerabilityExponent	How steeply a growing fish outgrows its predators: exposure is (1 − size / 100) to this power, size its structural length against grown	—

Fixed tables

Not everything numeric is tunable. These are catalogs rather than calibration: they describe what a thing is, so they ship as plain constants and no writer can move them at runtime.

Table	Holds
Fish species	Per species: its Add-my-Pet energy budget — or a relative’s, rescaled by hobby length, weight, maturity age and lifespan — hardiness, temperature / pH / GH / flow tolerance bands, and a breeding block — mode, clutch exposure, the male’s share of an egg’s cost
Plant species	Per species: growth rate, growth form, hardiness, CO₂ requirement, nutrient demand tier, and the PAR band it tolerates, whose low end sets its Ik and its rated day
Growth forms	Per form: what one full unit is — its height and how height grows with size, its footprint, its leaf area index — the share of its food it draws through its roots, and its plantlet’s size and name
Filters	Per type: biological surface, target turnover, flow ceiling, tank-size ceiling, and whether it is air-driven
Substrates	Per type: colony surface per litre, and the organic and KH reserves and the nutrient charge a fresh bed holds per litre; what a fresh bag’s organics are made of, one composition for every type
Fish composition	What a gram of every fish, egg and brood is made of: Add-my-Pet’s reserve for carbon and nitrogen, phosphorus at N:P 15, the default flake’s potassium and iron
Hardscape	Per type: colony surface, and the tannins a fresh piece carries
Lids	Per type: the multiplier applied to evaporation
Fixtures and pumps	The catalog of ratings a device can be built with — heater wattages, light PAR ratings, powerhead flow rates, CO₂ bubble rates, doser amounts
Chemistry	Molecular weights and the mass ratios derived from them, the degree-to-CaCO₃ conversion shared by dKH and dGH, and the CaCO₃ in an equivalent with the protons each nitrogen process moves. Derived, never quoted twice