Plants

What it models

Each plant is one unit of its growth form — a carpet patch, a sword, a rhizome clump — with a condition and an energy budget, on the vitality model. It reads light at its own height, under whatever crowns and green water stand above it and through the film on its leaves, and what that light fixes fills its reserve. Uptake fills four nutrient stores from the water and the bed. The reserve pays maintenance first, then growth, paced by the emptiest store, and a plantlet built on the parent and cut loose at its form’s size. Low condition sheds tissue.

Status

Mechanic	Status	Why
Photosynthesis on PAR	settled	Jassby–Platt tanh(PAR/Ik), per plant, on the light at its own mean leaf against its own saturating irradiance.
Rated by leaf	settled	Photosynthesis, maintenance, plant power and tissue run on leaf area, in rate units of 500 cm², so a full sword counts for more than a full carpet patch.
Metabolic pace	settled	Every flora fixes and burns at its growth rate against a leaf at 1, so a monte carlo’s leaf runs 1.8×, an anubias’s 0.3×, green water 10× and film 4×. Maintenance, mobilisation, uptake and repair run on one Q10.
Temperature on photosynthesis	missing	What a plant fixes carries no temperature pace, so a cold tank’s flora fix at the reference pace and burn at their Q10.
Carbon–oxygen exchange	settled	One yield, run both ways: what the reserve takes in is fixed and everything burned releases it, oxygen derived at the molar ratio rather than from a second constant.
Maintenance	settled	Owed around the clock and paid first. Oxygen paces only what a plant takes in and mobilises, never the upkeep it owes.
The shortfall	settled	Maintenance the reserve cannot pay is a damage rate off the hour’s own budget: a plant starves when its reserve runs out, not when a day runs dark.
Reserve	settled	Photosynthate in grams, up to full per gram of tissue. A full reserve caps photosynthesis, and it carries a plant through the night.
Stores	settled	One per nutrient, above what the tissue itself carries, filled toward Q_max past need: a planting is a nitrate sink between doses.
Plantlet	settled	The reserve’s other share builds the next unit on the parent, hour by hour, and cuts it loose the hour it holds its form’s size.
Size of a unit	settled	Size is the tissue a unit holds against a grown one. Growth tapers to nothing at 100, so no ceiling clamps it.
Self-shading	settled	A unit’s own crown shades its leaves, so a plant too big for its light sheds to a size its light holds, with no switch.
Vigour	settled	Each unit draws its own offset on its assimilation ceiling at birth, so clones in like light grow and bud apart.
Shedding	settled	A rate reading a stock — the square of the condition deficit, zero at full condition, with no threshold in it. The store a shed leaf held stays with the plant.
Death	settled	Condition reaching 0, as for a fish. A unit shed to a speck lives while it has condition: it repairs and regrows, or keeps losing condition and dies.
Epiphyte footprint	scaffolding	A java fern or anubias on the rock claims floor like a rooted plant; there is no hardscape budget.
Nitrate	settled	Log dose past the plant’s own edge, the fish shape at an edge only a runaway doser reaches.
Uptake	settled	Each store asks what it lacks; every form meets it on its own Monod against a per-species demand, in the water and the bed. Growth answers the emptiest store, never a reading off the water.
Nitrogen form	settled	Ammonia first, at a fraction of nitrate’s half-saturation, and nitrate for what ammonia leaves. Each form is drawn on its own pooled Monod, so neither is overdrawn.
Root feeding	settled	A fixed root share by growth form: a sword fills most of its stores from the bed, a carpet half, an epiphyte none. No species is refused a bed — a rooted plant in untabbed gravel runs its stores down until tabbed.
Carbon limitation	settled	Monod on dissolved CO₂, half rate at the species’ carbon-need half-saturation. It scales photosynthesis and the CO₂ income channel, and never damages: a carbon-short plant fixes and grows less.
Tolerance bands	settled	Temperature and pH earn most at the band’s centre and nothing at its edge, where damage starts from zero: net is continuous across every edge.
Shaded by the blooms	settled	Through light alone: green water in the column darkens a leaf by the depth above it, film coats every leaf at its coverage (Light). A bloom costs a plant photosynthate — never a damage of its own.
Composition	settled	Tissue and reserve are carbohydrate, CH₂O, and tissue carries Q_min of each nutrient, the culture floors of the macrophyte literature; its stores run to Q_max. Every species shares one composition, far under food’s.
Plant nutrient loop	settled	A plant holds what it took up, in tissue and stores; shed tissue returns as waste at Q_min, a dead plant’s stores with it, and rots back to the water. Carbon, N, P, K and Fe are conserved by construction.
General hardness	scaffolding	A damage-only tolerance band per species, and a small draw beside the nitrate that tissue never returns — waste carries no calcium. Calcium has no store, so soft water stresses a plant but never starves it.

How it works

The species roster

Five species, each of one growth form, in three tables: how each grows, the light it lives on, and the water it tolerates.

Species	Growth rate	CO₂ need	Nutrient demand	Hardiness
Anubias	0.3	low	low	0.75
Java Fern	0.5	low	low	0.7
Amazon Sword	1.0	medium	medium	0.5
Dwarf Hairgrass	1.5	high	high	0.3
Monte Carlo	1.8	high	high	0.3

Anubias and java fern attach to the scape; the sword and the carpets root in the bed.

Species	Tolerable PAR	Saturates at, Ik	Rated day
Anubias	8–⁠70	16	0.23
Java Fern	10–⁠90	20	0.29
Amazon Sword	20–⁠120	40	0.58
Dwarf Hairgrass	25–⁠200	50	0.72
Monte Carlo	30–⁠200	60	0.86

PAR is in µmol/m²/s and the rated day — the day of light the species is rated to live on — in mol/m²/d. Both derive from the band’s low end — saturation and the day’s light on Light.

Species	Temperature	pH	GH
Anubias	18–⁠30 °C	5.0–⁠8.0	1–⁠20 dGH
Java Fern	18–⁠30 °C	5.0–⁠8.0	1–⁠20 dGH
Amazon Sword	20–⁠28 °C	5.5–⁠7.8	2–⁠20 dGH
Dwarf Hairgrass	20–⁠28 °C	5.0–⁠7.8	1–⁠18 dGH
Monte Carlo	20–⁠28 °C	5.0–⁠7.8	1–⁠15 dGH

pH and GH bands are the generous published ranges, wide enough for aqua soil under CO₂ and hard tap alike. Past an edge the damage grows linearly with the distance, per °C, pH unit or dGH (temperatureStressSeverity, phStressSeverity, ghStressSeverity). pH is already a log scale, so linear in pH is log in acidity. Temperature and pH also earn inside their bands; GH is damage alone.

Growth forms

A plant’s size is how full one unit of its growth form is, in % — 100 is a grown patch, specimen or clump — read off the tissue its budget holds. The form fixes what that means.

Form	Carpet	Rosette	Attached
Species	Dwarf Hairgrass, Monte Carlo	Amazon Sword	Anubias, Java Fern
One unit is	a patch	a specimen	a rhizome clump
Full height	5 cm	40 cm	20 cm
Height grows as	full at any size — it spreads across	size^⅓	size^⅓
Footprint	100 cm²	700 cm²	200 cm²
Leaf area index	2.5	2.0	2.5
Rate units at full	0.5	2.8	1.0
Plantlet	a runner rooting a tuft, 5 % of a patch	a runner plantlet, 10 %	a rhizome branch on three or four fronds, 25 %
Root share r	0.5 — half from each	0.7 — feeds mostly from the bed	0 — feeds from the water

Leaf area is the form’s leaf area index over its footprint, in proportion to size, and a rate unit is 500 cm² of it, weighing 3 g of organic matter. Size says how full the unit is: it drives growth’s taper, the height and the self-shading. Leaf area says how much plant there is: it drives every flux the tank sees, and the plant’s metabolism runs it at its growth rate. No crown stands taller than the water.

Photosynthesis

Each plant’s carbon capacity is its leaf in rate units at its growth rate, times the light response at its mean leaf and its oxygen pace. The planting, the blooms and their spores draw on the dissolved CO₂ together, each on its own Monod read at the CO₂ the hour leaves, so a dense planting slows its own draw and never takes the water’s last milligram. Species differ in how much carbon they need to run near their ceiling, not in a floor that kills:

CO₂ need	On 4 mg/L	On 25 mg/L
low	73 %	94 %
medium	57 %	89 %
high	33 %	76 %

So a carpet in an uninjected tank grows slowly on a thin carbon income, and a sword or an epiphyte hardly notices the injector.

What is offered fills the reserve, and only what the reserve takes is fixed: a plant with a full reserve takes only what it burns, so a plant whose stores can’t pay for growth fills with carbon it cannot spend and draws little CO₂.

The carbon–oxygen exchange

Direction	Carbon	Oxygen
Photosynthesis	the CO₂ fixed into what the reserve takes	derived from the carbon fixed, at CO2_TO_O2_MASS_RATIO
Respiration	everything the budget burns — maintenance, the overhead of building, repair, tissue burned starving	derived from the carbon released, same ratio

One reaction run both ways, so one yield, and the oxygen partner is not a second knob. A carbon-starved tank stops producing oxygen because there was no carbon to pay for it.

Maintenance is quoted against the rate at saturating light and carbon; on the 4 mg/L an uninjected tank holds it is 4–9 % of what a plant actually fixes, at or just below the bottom of the 5–15 % the macrophyte literature reports. A planting under a fixture too dim to clear that burns more than it fixes and draws oxygen with the lamps on.

Stocks and rates

Stock	Fills it	Drains it	Unit
Units	Planting; a plantlet cut loose	Death; removal	plants
budget.structure	Growth	Shedding; maintenance nothing else pays; trimming	g — size is it over a grown unit’s
budget.reserve	Photosynthesis, up to full	Maintenance, growth, the plantlet’s buffer, repair	g
budget.offshootBuffer	The reserve’s other share	A plantlet cut loose; maintenance the release leaves unpaid	g of plantlet
budget.stores	Uptake from the water and the bed	Growth and a plantlet cut loose, at Q_min; into waste at death	mg of each nutrient
condition	Benefits; repair paid from the reserve	Stressors	%, normal at 100
oxygen · co2	Photosynthesis · respiration	Respiration · photosynthesis	mg/L
ammonia	Fish and rot, elsewhere	The stores’ nitrogen, before nitrate’s, from what the colony left; AOB oxidation, elsewhere	mg, as NH₃
nitrate · phosphate · potassium · iron	Dosing; the bed’s leak; nitrification for NO₃, and rot and fish excretion for the rest, elsewhere	The stores — nitrate only for the nitrogen ammonia leaves	mg
The bed’s nutrients	Aqua soil and root tabs (Equipment)	Root feeders’ stores; the leak	mg
waste	Shed tissue, at Q_min with its reserve; a dead plant, stores and all	Rot and settling, elsewhere	g, with its content

A plant is planted fed and stocked, as a shop sells it: its reserve full, every store full, nothing toward a plantlet, at full condition.

The budget

The plant’s hour is a Dynamic Energy Budget (DEB, Kooijman) on Droop cell quotas, the same one a fish’s is, with nutrient stores beside the carbon one, paced by the hour’s Q10.

Step	What happens
Uptake	Each store asks what it lacks of full, closing first order at storeFillDays from saturating water; the pools deliver at their own Monod share (Uptake)
Photosynthesis	Fills the reserve, up to reserveCapacity grams a gram of tissue
Mobilisation	The reserve releases at DEB’s rate — a fuller reserve releases more — and the oxygen pace slows it in water short of air
Soma	somaShare, κ, of the release pays maintenance first, then builds tissue at its price, 1 / growthEfficiency grams of reserve a gram — through the taper and at the Droop limit, taking its Q_min out of the stores
Plantlet	The other share builds the next unit in the offshoot buffer, at the same price and Droop limit
Shortfall	Maintenance the soma’s share cannot pay is drawn from the plantlet’s share, then its buffer, then tissue burned — and the share left unpaid is a damage rate
Repair	The reserve pays for the hour’s repair at the plant’s pace (Vitality)

What growth and the plantlet can’t use stays in the reserve, so a plant whose stores run low holds its photosynthate rather than spending it. The hour is integrated in slices, each reading its own reserve and stores, so the budget holds at any pace.

The Droop limit is each store’s density read as a Monod against Q_min, the emptiest store ruling. It never reaches 1: on full stores a plant runs at about 0.73, nitrogen ruling. Growth runs at it; income and harm read it as a share of that full-store limit.

The taper is the room a unit has left: growth slows as it fills and stops at 100, so size approaches full and nothing clamps it. Leaf area scales with tissue, so growth runs in proportion to the plant — DEB’s V1-morph — and a young unit grows on a logistic toward full. A planting compounds by adding units.

Uptake

A plant feeds on two pools: the water column and the bed’s store. Its growth form’s root share r fixes how much of its stores it fills through its roots. Every form a pool holds saturates on its own Monod curve, at the plant’s demand tier times the form’s half-saturation, and the two pools weigh in by where the plant feeds.

Ammonia goes straight into protein where nitrate has to be reduced first, so a plant takes ammonia first, half-saturating at a twentieth of nitrate’s ppm, and asks nitrate only for what ammonia leaves, in the same hour. The bed holds its nitrogen as nitrate, and its ppm reads its store against the tank’s capacity. A dry tank feeds nothing from either pool.

Demand tier	NH₃ and NO₃ · PO₄	K · Fe
Low	0.3	0.05
Medium	0.6	0.15
High	1	1

Demand scales how little a plant can make do with. An Anubias fills its potassium and iron stores at half pace on a twentieth of the ppm a carpet needs, so the trace fish food leaves in an undosed tank goes a long way for it.

The stores ask; the pools decide how much arrives. Each pool delivers each form through one Monod over every request on it, plants and blooms in the same call (Algae), so nothing is served before anything else, every request is met at the same fraction of its share, and no pool goes below zero.

A plant keeps taking up past need until its stores are full — luxury uptake. Between doses a high-tech planting draws 0.2–1 ppm of nitrate a day, and a lightly stocked planted tank runs its water down to no nitrate or phosphate.

Calcium and magnesium are drawn from the water on their own Monod curve, off the nitrogen actually taken from either pool, counted as nitrate (under Key tunables), and are not returned. The nitrogen moves KH as it goes in: a proton out per ammonia, one in per nitrate (Water & gases).

Composition

Tissue is the organic matter it rots into: carbohydrate, 0.40 g of carbon a gram, carrying Q_min of each nutrient — the subsistence quota, the culture floors of the macrophyte literature — and the stores hold what is taken up above it, up to Q_max. Food’s 8 % nitrogen is past a macrophyte’s luxury top; a plant’s floor is a fraction of it.

	N	P	K	Fe
Q_min, mg/g	12	0.8	4	0.05
Q_max, mg/g	45	6	25	0.25

Every species shares one composition, its sources cited beside the values in the config; each kind of bloom carries its own (Algae).

Income and harm

Every benefit channel is earned on the plant’s reserve density times that share of its Droop limit: good water is worth nothing to a plant that has burned its reserve or run its stores dry. Three peaks of 0.125 %/h make a budget of 0.375 %/h on a full reserve, full stores and band centre. Light reaches income through the reserve it fills, so a fed plant earns through the night.

Channel	Earns when	At its best
CO₂	scales with the species’ carbon Monod	co2BenefitPeak
Temperature	inside tolerableTemp, most at its centre, nothing at its edges	temperatureBenefitPeak
pH	inside tolerablePH, most at its centre, nothing at its edges	phBenefitPeak

Stressor	Charges	Per
Starvation	maintenance the hour left unpaid	share of the hour’s upkeep
Light high	PAR at the crown top over the band’s high end, while the lamp is on	PAR
Temperature · pH · GH	outside the species band	°C · pH unit · dGH
Nutrient deficiency	the Droop limit short of droopEdge of its full stores’	share of the edge
Nitrate	past the plant’s own edge	e-fold over

Deficiency starts under droopEdge of the limit full stores reach — 0.3 for a plant, where its nitrogen store has fallen to a sixth of full, near the critical 1.3 % of Gerloff & Krombholz — so the edge sits under full stores at any quotas. Hardiness scales every stressor by 1 − hardiness except nitrate, whose edge it carries out by the same factor a fish’s is.

Starving in the dark

A plant starves on its reserve, not on the day: the reserve carries it through the night, and in the dark it pays maintenance as long as it can. As it runs low the soma’s share stops covering maintenance: growth stops, and the share unpaid harms the plant at starvationSeverity while the plantlet’s share pays it, then the plantlet’s buffer, and last tissue burned for fuel. Budding stops next, and low condition sheds.

Stocked, in total darkness	Reserve under a tenth	Condition starts to fall	Dead
Monte Carlo	3.2 d	4.2 d	17 d
Dwarf Hairgrass	3.9 d	5.0 d	18 d
Amazon Sword	5.8 d	7.5 d	26 d
Java Fern	11.6 d	15 d	48 d
Anubias	19 d	25 d	68 d

Reserve turns over with growth rate and hardiness stretches the melt, so the slow growers outlast the fast. The hobby’s three-day blackout leaves even a carpet’s condition whole.

Light at its own height

A plant reads light at its own height, through the water and the crowns above its leaves — the canopy — and the thinner its own crown, the more of that light its leaves get. The blooms take their share on the way (Light): green water the more the deeper a leaf stands, so a carpet goes dark before a sword, and film the same share of every leaf, which costs a light-hungry plant more than one that lives on little.

That gives a starved plant a size it can hold. A plant too big for its light cannot pay its upkeep: its reserve drains, the shortfall harms it, and it sheds; its crown thins, its leaves read more light, and it stops where a day’s photosynthate meets a day’s maintenance. A plant with light to spare grows, and growth shades it again. Between the two it settles — smaller, not dead. Only light too dim for even a sparse unit to break even kills it.

Crowding and carrying capacity

Every other crown that reaches above a plant’s mean leaf shades it, at odds set by that crown’s share of the floor (the canopy): a tall planting darkens what grows under it, and carpet patches side by side shade each other. Shedding relieves only a plant’s own shade, so an understory plant under taller crowns stays in their shade as it shrinks. A planting therefore spreads until its lowest units sit at break-even — short units lose first, and the tank carries as much leaf as its light holds. An overgrown tank is dark, not dead.

Reading	Is	The keeper lowers it by
Floor cover	every unit’s footprint over the floor, Σ footprint / (2 × depth²); past 1 the planting has outgrown its floor	thinning — removing units
Floor shade	the share of the substrate light the canopy takes before the floor (Light)	trimming or thinning
Floor light	the fixture’s rating carried to the floor through the water, the green water and the canopy	trimming, thinning, or clearing green water

The plantlet

The reserve’s other share, 1 − somaShare, builds the next unit in the offshoot buffer as growth builds the parent. Once the buffer holds a unit at its growth form’s plantlet size and the stores hold its Q_min, it is cut loose, after vitality and losses settle.

• A new unit of the family. Its parent’s species and family, at full condition, with its own vigour and its share of the parent’s reserve and of the stores past Q_min, so parent and plantlet stand at one density of both. It acts from the next hour.
• Cadence is the budget’s. Grown and fed freely, a carpet patch sends a runner every two days, a sword throws a plantlet every six, a java fern branches every month and an anubias every fifty days. In the setup tanks a sword parent buds about every 18 days, a java fern every 55 and an anubias every 78.
• Propagation never tests space. Plantlets land whatever the floor cover; crowding and the canopy decide which of them live.

The form sets the plantlet’s shape and the words its plant-propagated log entry uses — “Amazon Sword threw a plantlet”. Every form builds it the same way.

Lineage, family, age and vigour

Field	Is
parentId	The unit whose plantlet this is; null for anything planted or seeded
familyId	The founder’s id, inherited down the line, so a family outlives its founder
age	Hours in this tank. A seeded plant can start older. No rate reads it
vigour	An offset on its assimilation ceiling, drawn once at birth within ±VIGOUR_SPAN (0.15)

Vigour scales the most a unit’s leaves fix at any light, so clones side by side grow and bud apart, by about as much as their vigour differs.

The floor budget and trim

The keeper plants by floor. A new unit fits when its footprint fits the floor the planting leaves free, and each unit claims its form’s full footprint at any size — the territory a keeper spaces for — so seedlings can’t pack a tank. An epiphyte on the rock claims its plan view like any other.

Trimming cuts units down to a size: one unit, one family, or every plant above the target. It takes the budget down in proportion — tissue, reserve, stores and the plantlet’s buffer — lowers leaf area, and the height of anything but a carpet, and reopens the taper, so the soma’s share goes back into regrowth. Trim for light, or let the plant spread. Which units a thinning pulls is the keeper’s choice. The verbs are on Actions.

Shedding and death

Shedding is what low condition does to a plant: a share of its tissue an hour, maxSheddingRate times the square of the condition deficit — 0.5 %/h at condition 50 and 0.08 %/h at 80, so a plant relit or cleaned up before its condition collapses keeps most of itself. The tissue leaves as waste at Q_min, with its share of the reserve; the store it held is resorbed and stays with the plant. A failing plant drops its oldest leaves, which is why melting plants foul the water.

A plant dies at condition 0, as a fish does, and leaves the array. Its tissue, reserve and plantlet’s buffer become waste, so a melting sword fouls the water more than a carpet patch of the same size, and its stores go with them, so what it took up comes back as ammonia and minerals as that waste rots.

Key tunables

The tunables are listed in the reference under Plants, the half-saturations and demand tiers under Nutrients, and the canopy’s own constant, leafAttenuationPerLai, under Optics.

Constant	Meaning	Value
GH per nitrate drawn	Calcium and magnesium taken up per mg of nitrogen actually taken, counted as nitrate, off leaf-tissue ratios; a constant	0.28 mg CaCO₃/mg
GH half-saturation	GH, as CaCO₃, at which that uptake runs at half; a constant	1 mg/L

Seams

Neighbour	Read	Written
Light	light and lightByHour, read at each plant’s own height through the canopy: PAR at the mean leaf drives photosynthesis, and the day’s light there reads against its rated day; PAR at the crown top charges the light-high stressor	Every unit’s crown, which shades the plants below it
Water & gases	co2 for the carbon Monod, oxygen for the oxygen pace, pH and gh for the tolerance bands	oxygen and co2, both directions, on one carbon yield; gh drawn with the nutrients; kh by the form their nitrogen comes in
Nitrogen cycle	ammonia and nitrate, and the phosphate, potassium and iron rot releases beside the ammonia	ammonia first and nitrate for the rest, with the other three, into the stores — the ammonia from what the colony left; waste from shedding and death, a dead plant’s stores with it
Environment	temperature for the Q10 on every rate of the budget, water for every ppm, the box’s depth and floor	—
Equipment	substrate.nutrients — the bed’s store, for root feeders	The same store, drawn down as root feeders’ stores fill
Algae	The light the blooms take at each leaf, as the hour starts — green water by the depth above it, film as a coat; each bloom’s share of the pooled uptake and of the CO₂	Plant power per litre, whose exudates lower a bloom’s assimilation ceiling; the canopy over the floor, film’s light there
Livestock	—	Plant power, saturating the fish shelter benefit
Actions	—	Planting against the floor, removal and trimming write the array and the budget directly; dosing fills the four nutrient pools in the water, root tabs the bed’s
Alerts & logging	—	A plant-died entry per plant lost, a plant-propagated entry per plantlet
State & persistence	The tank’s draw stream, for every unit’s vigour and id; seeded plantings, at a named size and age, stocked on the plants config, each founding its family	The advanced stream position

Source

src/simulation/plants/ — the roster, the growth forms, the canopy and construction; src/simulation/flora/ — the hour’s pass, beside the blooms, and each kind’s budget parameters; src/simulation/systems/ — the flora law the blooms share, the budget and the reserve core it shares with the fish, photosynthesis, the pace, uptake, vitality and lifecycle; src/simulation/config/ — the tunables and their declared ranges.