How the AquaSage engine thinks

The inch-per-gallon rule treats one 25 cm oscar like twenty-five neon tetras, so we don't use it. Each species carries a bioload factor calibrated to adult body mass raised to the ¾ power, times an activity adjustment — Kleiber's metabolic scaling, computed by script from researched mass estimates, never hand-guessed.

Tank capacity starts from volume and is then shaped by your real setup: filtration turnover (clamped 0.5–1.5× around a 4×/hour nominal), water-surface area (gas exchange — a tall column holds less life than its litres suggest), your maintenance regimen (0.6–1.15×), and healthy plant mass, which offsets up to 30% of load — scaled down when a plant's CO2 needs aren't met.

The capacity meter shows a ±10% uncertainty band, and prints the assumptions it is making. A point estimate would be false precision.

For temperature, pH, GH and KH the engine intersects every species' tolerable band. Averaging is how a coldwater fish and a warm-water fish end up 'compatible' at a temperature neither enjoys. If the shared band is a knife's edge — narrower than 1 °C, 0.3 pH or 2 °d — that's a warning, not a pass.

Numeric overlap isn't enough on its own: a coldwater species and a tropical species never score green together, whatever the band arithmetic says. And if your tap water sits outside the group's range, the verdict says so and tells you what to adjust.

Some failures can't be bought back with filtration or water changes: no shared water band, a tank too small for the adult fish (minimum volume, length, floor area and height are separate gates — a tall 200-litre column still fails a long-bodied swimmer), too many conspecifics (two male bettas), and predation. Any hard-gate failure caps the health score at 35, no matter how good everything else looks.

Every animal pair is scored through a 6×6 temperament matrix (peaceful, timid, semi-aggressive, territorial, aggressive, predatory), with an extra penalty when fin-nippers meet long-finned, slow fish — the classic betta-and-tiger-barb mistake.

Aquascape is part of the model: dense planting relieves up to 20% of conflict and hardscape up to 15% more, capped at 35%. Add cover in the planner and watch a warning soften in real time — that's real husbandry, not a gimmick.

On top of the computed score sit curated rules for documented cases the matrix can't see — bettas hunting dwarf shrimp, pea puffers and snails. Each rule carries its own sources.

A predator flag plus an adult-size ratio at or above the species' threshold (default 2×) is a red gate — a committed predator with a big enough mouth will eat the tankmate. A small gape downgrades certain-lunch to risk. Separately, shrimp and other vulnerable prey are flagged against any fish that dwarfs them 2.5-fold, however 'peaceful' its temperament.

Shoaling species below their minimum group size, swimming-zone crowding (top, mid and bottom each have their own share of capacity), lids for jumpers, flow and substrate preferences, copper sensitivity of invertebrates, and a GH floor for molting — 15 checks in all, each with its own card in the verdict.

Every one of our species profiles cites its sources and carries a confidence badge. Bioload factors are computed from researched mass estimates by script. When a claim of ours contradicts a source you trust, tell us at hello@aquasage.app — data corrections ship fast.

Most stocking tools reduce a tank to one number — litres consumed versus litres available. That model cannot see species pairs, so it happily accepts a betta with a shoal of tiger barbs; it cannot see water, so coldwater and tropical fish pass together; and it cannot see shape, so a tall column 'fits' a fish that has nowhere to swim. AquaSage checks each of those separately, and shows its work.

A verdict is an informed starting point, not gospel. Individual fish have individual temperaments; a tank's history, feeding and stability matter in ways no calculator can measure. Several thresholds are estimates under active calibration, and where the engine is uncertain it errs conservative on purpose — for the sake of the fish.

The engine is versioned, so a verdict you saw last month can be reproduced today. When the model changes, the version changes.