Livestock

What it models

Every fish is an individual whose body is its energy budget (DEB, Kooijman): structure, reserve, maturity and a brood buffer, in grams. Food fills the gut; what the gut digests feeds the reserve; the reserve pays maintenance first, and a fixed share κ of the rest buys growth while the remainder matures the fish and then fills its brood buffer. Mass and size are read off the budget. Health is the damage axis: the water, the toxins the fish loads from it and its own budget harm it, benefits and paid repair restore it. Old age is DEB ageing — a hazard that accumulates into a survival the fish dies under. A brood is a clutch of eggs the water and the tank’s fish thin, and the larger fish hunt the young that hatch.

Status

Mechanic	Status	Why
Energy budget	settled	Add-my-Pet parameters, converted once to grams and hours; every species reaches its entry’s implied weight, puberty, hatch and lifespan.
Pace	settled	Arrhenius on each species’ T_A; oxygen scales only the supply side. Temperature has no falling limb past the optimum yet.
The gut	settled	One stock, holding a day of the fish’s appetite — its assimilation ceiling — digested first order.
Mass ledger	settled	Feces, the meal’s excess, burn, bodies and eggs close against food element by element: carbon, nitrogen and every mineral.
Body composition	settled	One composition for every fish, egg and brood — Add-my-Pet’s reserve for carbon and nitrogen, phosphorus at N:P 15 — against food’s own: a meal builds reserve only as far as its scarcest element.
Stress hooks	scaffolding	The load drives assimilation’s; the maintenance, growth and egg multipliers exist and nothing drives them yet.
Serving	settled	Every fish eats at once; short food splits in proportion to the room in each gut.
Toxin loads	settled	GUTS-RED: one load per toxin in the water’s ppm, following the water at the toxin’s dominant rate.
Water quality	settled	Log-dose harm from each fish’s own edge, the toxins charged on its load. Chloride, which blunts nitrite, is not modelled.
Load on appetite	scaffolding	First-pass, not fitted: one severity across the toxins.
Hardiness	settled	Scales stressors, never benefits.
Starvation	settled	The hour’s unpaid maintenance as a damage rate; the buffer, then structure, pay it.
Repair	settled	A first-order share of the deficit, paid from reserve; condition past 100 is lost.
Old age	settled	The DEB hazard damages health and accumulates into survival against a per-fish threshold.
Broods	settled	From the brood buffer, in bouts: an egg-layer spawns once her buffer holds a clutch, a livebearer carries one brood; males pay their share from their own buffers.
Tolerance-band benefits	settled	Graded to zero at every edge; damage starts at the edge.
Clutches	settled	A stock of eggs thinned by water harm and predation, developing at the species’ age at birth under τ.
Predation	settled	A damage rate on any fish short of grown length from the larger fish per litre; kills are eaten.
Colonies	missing	Snails and shrimp do not exist; uneaten food only rots.
General hardness	scaffolding	A damage-only band per species, one pooled GH rather than calcium and magnesium.
Dissolved CO₂	missing	Fish carry no carbon stressor.

How it works

The roster

Each species runs on its Add-my-Pet entry where the entry fits its own data; otherwise on its closest relative’s, rescaled by hobby length, weight, maturity age and lifespan. Grown figures are a female fed without limit; ages are read at the species’ mid-range temperature, hatching at 25 °C.

Species	Budget	Grown	Stocked (80 %)	Puberty	Median lifespan	Hatches in	Egg · hatchling size
Neon Tetra	entry	2.6 cm · 0.22 g	0.11 g · 199 d old	57 d	7.7 y	7.7 d	0.52 mg · 13 %
Guppy	entry	5.7 cm · 1.1 g	0.55 g · 511 d old	79 d	2.7 y	27 d, carried	2.7 mg · 13 %
Betta	proxy	5.5 cm · 3.0 g	1.5 g · 336 d old	120 d	3.0 y	1.3 d	0.011 mg · 1.5 %
Corydoras	entry	7.8 cm · 3.1 g	1.6 g · 218 d old	165 d	6.0 y	3.2 d	0.67 mg · 6 %
Angelfish	entry	15 cm · 27 g	14 g · 327 d old, juvenile	392 d	10.7 y	5.6 d	1.0 mg · 3 %

Species	Hardiness	Temperature	pH	GH	Max turnover
Neon Tetra	0.5	22–⁠28 °C	5.0–⁠7.8	1–⁠12 dGH	10 ×/h
Guppy	0.8	22–⁠28 °C	6.5–⁠8.5	6–⁠25 dGH	13 ×/h
Betta	0.6	24–⁠30 °C	6.0–⁠8.0	3–⁠15 dGH	5 ×/h
Corydoras	0.7	22–⁠26 °C	6.0–⁠8.0	2–⁠15 dGH	15 ×/h
Angelfish	0.4	24–⁠30 °C	6.0–⁠8.0	3–⁠15 dGH	10 ×/h

pH and GH bands are generous hobby care-sheet ranges. Flow tolerance is a turnover — flow divided by standing water — so a fixed-output powerhead is harsher in a small tank.

The budget

Every energy-like quantity is grams of organics; structure is a volume V in cm³ with structural length L = V^⅓. Per hour, with τ the species’ Arrhenius factor (1 at 20 °C) and ω the oxygen pace:

Flux	Per hour
Assimilation ceiling	{p_Am} × L² × τ × ω, lowered by the fish’s load
Assimilated	the meal’s reserve yield × what it takes of the gut’s offer, ceiling / κ_X at most; the rest of the offer returns to the gut
Mobilised	E × (ω·v·[E_G]·L² + [p_M]·V) × τ / ([E_G]·V + κ·E)
Maintenance	[p_M] × V × τ, paid from the soma share κ × mobilised
Growth	what the soma share leaves, at [E_G] a cm³; the overhead 1 − κ_G is burned
Maturity	k_J × E_H × τ paid from the other share; the rest matures the fish until puberty, then fills the brood buffer
Shortfall	maintenance its share could not pay — drawn from the buffer, then from structure, which shrinks

Wet mass is V + (E + E_R) / d_V; size is 100 × L / L_m. A fish reads as an adult once its maturity reaches puberty, at any size; short of it, as fry under half its grown length and as a juvenile from there. Reserve density E / ([E_m] × V), capped at 1, is how well fed it is. ω is a Monod on dissolved oxygen against saturated water, so a healthy tank reads 1; it scales only supply, so a fish longer than ω × L_m cannot pay its maintenance however well it is fed.

Feeding and the gut

A fish’s appetite is its assimilation ceiling in food, ceiling / κ_X; its gut holds a day of it, so a fry eats more for its weight than its parents. Every fish wants the room left in its gut; when food runs short each takes the same share of its room. The gut digests first order at digestionRate × τ. A stocked fish and a hatchling arrive with empty guts and full reserves.

The ledger

A fish is made of one composition and its food of another:

A gram of	Carbon	Nitrogen	Phosphorus	Potassium · iron
Fish — body, eggs, brood	0.503 g, CH₁.₈O₀.₅N₀.₁₅	0.088 g	0.013 g, at N:P 15	the default flake’s
The default flake	0.45 g	0.08 g	0.012 g	8 · 0.2 mg

Of the food the budget takes, κ_P passes undigested as feces, at the meal’s composition, to the waste pool. The rest builds reserve at the fish’s own — its reserve yield, κ_X of the meal at most and less where the meal’s scarcest element runs out. What it digested and did not build is the meal’s excess, excreted as it is assimilated: its nitrogen as gill ammonia with its minerals beside it, its carbon breathed out as CO₂. A food richer in nitrogen than the fish makes more ammonia; one leaner in any element builds less reserve a gram, so the ration that pays upkeep grows. The default flake builds at κ_X, carbon its closest element.

Reserve leaves only as structure, buffer or burn: maintenance, maturity upkeep and development, every conversion overhead, repair, and structure a starving fish loses. Every gram burned draws the 1.456 g of O₂ its reserve’s formula takes, breathes its carbon out as CO₂, and excretes its nitrogen as gill ammonia with its minerals beside it. A cm³ of structure holds κ_G × [E_G] grams. Eggs hold E_0; what an embryo spends reaching its hatchling is burned at hatching. A stocked fish brings its body in; a removed or sold one takes its body, gut and carried brood out; a dead one leaves them all.

Stocks

The fish’s own stocks; what it reads and writes in the tank is under Seams.

Stock	Fills it	Drains it	Unit
health	Benefits; repair paid from reserve	Stressors	%, normal at 100
gut	Eating, up to a day of appetite; what the budget hands back; eggs and fry it eats	Digestion, first order	g, with what it ate
budget.structure	Growth	A shortfall the buffer cannot pay	cm³
budget.reserve	Assimilation	Mobilisation; repair	g
budget.maturity	The maturity share, until puberty	Unpaid maturity upkeep, short of puberty	g
budget.broodBuffer	The maturity share after puberty	Spawning; fathering; a male’s turnover; a shortfall	g
budget.wearLoad · budget.hazard	Mobilisation	Dilution as the fish grows	1/h² · 1/h
survival	—	× e^−hazard each hour	share of a cohort alive
load	The water’s level above it, first order	The water’s level below it, the same way	ppm, one per toxin
clutch eggs	A brood	Water harm and predation, first order; hatching	eggs
clutch development	τ / incubation each hour	Hatching, at 1	share of the way to hatching
age	One tick per hour	—	ticks

The load

A fish carries one load per toxin — free NH₃, nitrite, nitrate — in the water’s own ppm, GUTS-RED’s scaled internal concentration. Each hour it moves toward the water’s level at the toxin’s dominant rate, the slower of what the gills pass and what the body repairs, paced by τ and divided by the fish’s structural length, so a small or warm fish loads and clears faster. A stocked fish arrives unloaded; a hatchling carries the load its clutch read.

Toxin	Half-time at 1 cm, 20 °C
Free NH₃	≈ 2 d
Nitrite	≈ 1 d
Nitrate	≈ 1 week

Health’s toxin stressors read the load, so a spike barely registers on a big fish, a held level bites, and harm outlives a water change while the load clears. The load’s e-folds past the fish’s own edges, summed, lower its assimilation ceiling — DEBtox’s assimilation mode — so appetite falls with it and a full ration still bites: the budget takes up less of it. A laid clutch reads the water itself, an egg being the fast limit of the same law; a carried brood reads its mother’s load.

Health

Health runs the vitality step and the repair rule every organism shares: the fish asks a first-order share of its deficit at healingRate and its pace, priced at healingCost hours of its upkeep a point and paid from its reserve at the hour’s oxygen; an empty reserve repairs nothing. A fish is sick while its damage outruns what it earns and repairs.

Stressor	Activates	Per
Temperature	outside the species range	°C
pH	outside the species range	pH unit
GH	outside the species range	dGH
Free NH₃	its load of the unionized fraction, read off pH and temperature, past the fish’s own edge	e-fold over
Nitrite	its load past the fish’s own edge	e-fold over
Nitrate	its load past the fish’s own edge	e-fold over
Oxygen	under the fish’s own edge	e-fold under
Water level	below waterLevelStressThreshold of capacity	% under
Flow	above the species maxTurnover	tank volumes/h over
Starvation	maintenance the hour left unpaid	share of the hour’s upkeep
Hunted	larger fish in the tank, on any fish short of grown length	g of them per litre
Age	always: hazardSeverity × hazard	—

Hardiness scales stressors as 1 − hardiness, except water quality, where it moves the edge, and age, which nothing shields. Every benefit is its peak times the fish’s reserve density.

Benefit	Earns when	Peak
pH	inside the species range, most at its centre and nothing at its edges	phBenefitPeak
Oxygen	rising on log scale from 4 mg/L, full from 6	oxygenBenefitPeak
Plants	plant power, saturating at plantBenefitSaturationPoint	plantBenefitPeak

Water quality

Toxicity runs on log dose: each toxin charges its severity per e-fold of its load past the fish’s edge, oxygen per e-fold of the water under it, offset 0.1 mg/L so harm stays finite at zero. A fish’s edge sits 2^hardiness past the alert’s (below it, for oxygen), with effective hardiness clamped to [0.1, 0.95]. Each severity is set so a mid-hardiness fish loaded to its 96-hour LC50 loses one %/h net.

Reading	Alert edge	A mid-hardiness fish is harmed from	Breaks even	LC50
Free NH₃	0.02 ppm	0.028 ppm	≈ 0.17 ppm	≈ 1 ppm
Nitrite	0.5 ppm	0.71 ppm	≈ 2.7 ppm	≈ 10 ppm
Nitrate	80 ppm	113 ppm	≈ 300 ppm	≈ 800 ppm
Oxygen	4 mg/L	2.8 mg/L	≈ 2.2 mg/L	≈ 1.5 mg/L

Predation

Every larger fish hunts a smaller one by the grams it outweighs it. Vulnerability reads the prey’s size — its length against what its species grows to — so only the young are hunted:

predator mass = Σ over every fish of max(0, its mass − prey mass)
hunted        = predationRate × predator mass / water × (1 − size / 100)^preyVulnerabilityExponent

hardened by 1 − hardiness. A fed fry earning past it grows out of reach; a hungry or crowded one dies — so a tank breeds until its own fish hold the fry back.

Ageing

Wear accrues with mobilisation, dq = (q × V/V_m × s_G + h_a × τ²) × mobilised / ([E_m] × V), and drives the hazard, dh = q, both diluted as the fish grows. The hazard damages health at hazardSeverity, so an old fish is frail and sickens first; and each hour survival keeps e^−hazard of itself. A fish dies of old age when its survival falls below the threshold it drew at creation, so a cohort follows its species’ survival curve — half gone at its median lifespan — and a fish kept warm ages faster.

Individual variation

Sex, a hardiness offset of ±15 % of the species baseline, a small health jitter and a survival threshold are sampled once at construction. Stocked and hatched fish come from the same factory.

A stocked fish was grown in the shop: stocking names a size in % of grown length — from its hatchling’s, 80 by default, up to 90, since grown length is an asymptote — and its budget is the one its species reaches at that size fed without limit at its mid-range temperature, its broods spent along the way. Its age, wear and survival are that upbringing’s, whatever tank buys it. Its threshold is drawn under the survival it arrives with. A hatchling starts at L_b on a full reserve at E_Hb.

Broods

Spawning comes in bouts. Eggs ready are ⌊κ_R × E_R / E_0⌋; an egg-layer spawns once they reach her species’ clutch, a livebearer once a whole egg is ready and only while she carries no brood, so she conceives what her buffer gathered through the last gestation. She draws every egg ready. The males of her species father as many as their buffers pay for at their species’ maleShare of an egg’s cost, maleShare × E_0 / κ_R, shared back to each ready female in proportion to her eggs, each male paying the same share of what his could. Fathered eggs become her clutch; she resorbs the rest, and resorbed eggs, the overhead 1 − κ_R and the males’ payment are burned. A male burns his unspent buffer at maleBufferTurnover × τ, so he holds about a week of it. A starving fish’s buffer pays its maintenance first, so breeding stops before it shrinks. Breeding is uncapped: the stocking ceiling gates only the keeper’s hand.

Clutches

A clutch is a count of eggs, each holding E_0 and weighing its hatchling. Every hour two competing first-order losses thin it and one rate develops it:

Rate	Per hour
Harm	eggSensitivity × Σ water stressors / 100 at the species’ hardiness, on the water’s toxins; a carried brood’s on its mother’s hardiness and load, without eggSensitivity
Predation	eggPredationRate × exposure × predator mass / water, every fish by the grams it outweighs an egg; none on a carried brood
Development	τ / incubation, the species’ age at birth at 20 °C

At development 1 each whole egg left hatches; the part egg goes to waste. Eggs the water kills go to waste, at the fish’s composition; eaten eggs go into the eaters’ guts by the grams each outweighs an egg, as room allows, the rest to waste.

Species	Mode	Clutch	Exposure	Male share
Guppy	livebearer	what her buffer holds	0	0.2
Neon Tetra	egg-scatterer	80	1	0.2
Betta	bubble-nester	150	0.3	0.6
Corydoras	egg-depositor	20	1	0.2
Angelfish	substrate-spawner	300	0.5	0.5

Clutch is the hobby figure for the eggs a bout lays, the least an egg-layer’s buffer holds before she spawns. Exposure is how much of the tank’s predation reaches a laid clutch. A carried brood dies or leaves the tank with its mother.

Death

Health reaching zero, or survival falling under the fish’s threshold, removes it. A death the survival threshold fired, or mostly of age damage, is logged as old age; one mostly of starvation as starved; one mostly of predators as eaten. Its remains — body and any carried brood at the fish’s composition, and its gut — go to waste, less the share its surviving predators eat: their share of its dying hour’s damage, into their guts by weight as room allows.

Key tunables

The tunables are listed in the reference under Livestock, the food’s minerals under Nutrients.

Seams

Neighbour	Read	Written
Nitrogen cycle	ammonia, nitrite and nitrate, which each fish’s loads follow and a laid clutch reads past its edge	food eaten; ammonia, phosphate, potassium and iron through the gills on every gram burned and a meal’s excess; waste as feces, dead bodies and dead eggs
Water & gases	oxygen against saturation as the oxygen pace ω, a stressor and a benefit; pH, from co2 and kh, and gh, as tolerance bands	oxygen drawn and co2 exhaled on every gram burned and a meal’s excess, kh returned on the gill ammonia
Environment	temperature as a tolerance band and through each species’ Arrhenius factor; water for every ppm and the water-level stressor	—
Equipment	flow, divided by standing water into a turnover; food the feeder drops	—
Plants	Plant power — the shelter benefit, saturating	—
Actions	food put in the tank by feeding	Stocking, removal and selling fry write the array directly
Alerts & logging	—	fish-died, eggs-laid, eggs-hatched and — a livebearer’s birth — fry-born entries; all but deaths carry a count
State & persistence	The tank’s draw stream, for sex, hardiness offset, health jitter, survival threshold and every id	The advanced stream position

Source

src/simulation/livestock/ — the roster and its Add-my-Pet entries, construction, the per-tick pipeline and the clutches’ and broods’ step after it; src/simulation/systems/ — the energy budget, metabolism, digestion, fish health and broods; src/simulation/config/ — the tunables and their declared ranges.