The Environment

Before any organism can grow, feed, or die, it needs a physical world to live in. The simulator builds that world from a handful of parameters: a container of water with air above it, a light that switches on and off, a temperature that governs how fast everything happens, and surfaces where organisms can attach and hide. These physical conditions shape every biological outcome — and they often matter more than the species list for determining whether an ecosystem survives.

The Container

The simulation models a small, sealed (or partially sealed) container of water -- picture a mason jar, a test tube, or a laboratory flask. The container has two zones:

Water volume -- the liquid where all the organisms live. Specified in liters (for example, 0.1 L for a test tube or 1 L for a jar).
Headspace -- the pocket of air (or gas mixture) above the water surface. Also specified in liters. Gases like oxygen and CO2 move back and forth between the water and the headspace based on how saturated the water is.

The ratio of water to headspace matters a lot. A large headspace acts as a gas buffer: if the water runs low on oxygen at night, it can pull more from the air above. A tiny headspace means there is very little reserve.

Sealed vs. Open Systems

The container can be completely sealed or partially open to the outside atmosphere.

Sealed: No gas enters or leaves the system. The only oxygen and CO2 available is what was trapped inside when the jar was sealed. This is the scenario for a truly closed ecosystem.
Leaky / open: The headspace slowly exchanges gas with the outside atmosphere, at a configurable leak rate — the faster the leak, the faster the exchange. This models containers with loose lids, cotton plugs, or any setup that is not airtight.

In a sealed system, total oxygen (water plus headspace combined) can only change through biology -- photosynthesis produces it, respiration consumes it. If you see water oxygen dropping, check whether the total system oxygen is also dropping or whether oxygen simply moved into the headspace.

Evaporation

In open-top containers, water evaporates into the surrounding air. Over weeks to months this can meaningfully reduce water volume, concentrating all dissolved nutrients and increasing salinity proportionally. The model computes evaporation rate from the vapour pressure deficit between the water surface and room air, scaled by a ventilation factor that captures how exposed the water surface is to air movement. Sealed containers have no evaporation. Open-top containers can lose enough water to noticeably concentrate solutes over several months, depending on temperature, humidity, and ventilation. A volume floor at 20% of the initial volume prevents numerical issues in very long simulations.

Floating macrophytes suppress evaporation. A dense mat of Salvinia or duckweed creates a humid microclimate at the water surface, reducing the effective area available for evaporation. At full surface coverage, evaporation approaches zero -- consistent with observations that dense floating-plant mats reduce open-water evaporation by 30-90% in tropical ponds (Lind & Cottam 1969).

Light

Light follows a simple on/off schedule. It is on for a set number of hours each day (the "photoperiod") and off for the rest. There is no dawn or dusk -- it switches instantly. During the light period, its intensity is constant at a configured brightness level, measured in micromoles of photons per square meter per second (a standard unit called PAR -- photosynthetically active radiation). Typical values range from about 55 (indirect window light) to several hundred (direct sun or grow lights).

Light is the energy source that drives the entire ecosystem. Without it, there is no photosynthesis, no oxygen production, and no new biomass. The length of the photoperiod matters enormously: during the light hours, algae and plants produce more oxygen than everything consumes, so dissolved oxygen rises. At night, photosynthesis stops but every organism keeps respiring, so oxygen falls. If nighttime oxygen consumption exceeds what was produced during the day, the system slowly suffocates. A longer photoperiod gives producers more time to build up that oxygen reserve.

Light also drives the photodegradation of dissolved organic matter (a purely chemical UV-driven process that releases nutrients back into the water) and influences which form of nitrogen algae prefer to absorb -- they use nitrate more readily in bright conditions because the reduction enzyme that processes it requires light energy.

As planktonic algae grow denser in the water, they absorb light and shade everything below them. The model calculates this using the Beer-Lambert law: light intensity decreases exponentially with depth, and the rate of decrease depends on how much algal biomass is suspended in the water column. In a jar of dense green algae, most light is absorbed near the surface and very little reaches the bottom. This self-shading is an important natural brake on algal growth -- the denser they get, the less light each cell receives on average.

Floating macrophytes add a second layer of shading above the water column. Because they sit at the air-water interface, they intercept light before it enters the water at all. A dense mat of Salvinia or duckweed can block over 95% of incident light, starving everything submerged of the energy it needs to grow. The combined effect of planktonic shading, floating canopy, and the slow accumulation of light-absorbing refractory dissolved organic matter (which stains the water brown over time) means that light availability in a mature system can be dramatically lower than the nominal lamp intensity would suggest.

Temperature

Temperature can be held constant throughout a simulation or varied on a daily cycle (a smooth cosine wave that peaks in the afternoon and bottoms out before dawn). It affects the speed of virtually every biological and chemical process in the model.

The general rule is captured by a concept called Q10: for every 10°C increase in temperature, most biological rates roughly double. A Q10 of 2.0 -- the most common default -- means that a process running at a given speed at 25°C runs at half that speed at 15°C and double that speed at 35°C. This applies to respiration, decomposition, bacterial growth, grazing, and more. The practical consequence is that warming a jar speeds up everything -- organisms grow faster but also burn through their energy reserves and consume oxygen faster. Warmer water also holds less dissolved oxygen and CO2 (gas solubility decreases with temperature), so a warm jar can become oxygen-limited more easily than a cool one even with the same amount of photosynthesis.

Photosynthesis follows a different temperature pattern. Instead of simple Q10 scaling, each producer has a thermal optimum -- a temperature where photosynthesis is fastest. Below the optimum, photosynthesis increases with warming. Above the optimum, it declines linearly toward zero at a lethal temperature. This means cool-adapted species like diatoms (optimum around 20°C) actually photosynthesize less at 28°C than at 20°C, even though their respiration costs are higher at the warmer temperature. The mismatch between rising respiration costs and declining photosynthesis at high temperatures is what makes heat waves dangerous for cool-adapted species.

Each species has a comfortable temperature range defined by four thresholds: a low-stress and high-stress boundary (the safe zone, where temperature causes no extra mortality), and a low-lethal and high-lethal boundary (where mortality reaches its maximum rate). Between the stress and lethal boundaries, mortality ramps up linearly. Different species have very different ranges -- diatoms are comfortable at 8-25°C, while heterotrophic bacteria tolerate 5-35°C.

Salinity

The simulation tracks salinity in PSU (practical salinity units, roughly equivalent to parts per thousand). Freshwater systems use values near 0, while standard seawater is 35 PSU. Salinity affects gas solubility (saltier water holds less dissolved oxygen and CO2, an effect called salting out) and the carbonate chemistry that determines pH. The model uses salinity-blended carbonate equilibrium constants: freshwater constants (Plummer & Busenberg 1982) below 1 PSU, saltwater constants (Millero 2010) above 5 PSU, and a smooth transition between them for the estuarine range. Species have their own salinity tolerances, and being far from their preferred salinity increases their metabolic costs (through osmoregulation) and can cause mortality.

General Hardness (GH)

General hardness (GH) measures the total concentration of divalent cations in the water, primarily Ca²⁺ and Mg²⁺. It is set directly in the scenario, in degrees of general hardness (°dGH), with a default of 6 °dGH (1 °dGH ≈ 0.179 mmol/L of total divalent cations). GH is distinct from alkalinity: alkalinity captures the water's buffering capacity, while GH captures divalent cation availability for biological structure-building.

The model splits GH into 65% Ca²⁺ and 35% Mg²⁺ (molar), matching typical freshwater tap water ratios. At the default 6 °dGH this gives ~28 mg Ca/L and ~9.1 mg Mg/L.

Calcium availability is biologically important for:

CaCO₃ shell building in bladder snails (growth rate halved below ~2.8 °dGH Ca equivalent)
Exoskeleton hardening in Neocaridina shrimp (molting stressed below ~2 °dGH Ca equivalent)

Magnesium is currently tracked as a conservative pool (no biological sinks). Its primary role is contributing to the overall GH reading alongside calcium. Because calcium is consumed by shell-building organisms while magnesium is not, GH declines over time primarily through Ca depletion.

For more detail on how Ca²⁺ interacts with carbonate chemistry and the CaCO₃ precipitation process, see The Carbonate System.

Surfaces

Surfaces are the solid objects submerged in the water -- jar walls, gravel, ceramic sticks, sand. In any real aquatic system, submerged surfaces are quickly colonized by biofilms: thin layers of algae, bacteria, and organic matter. The model tracks this colonization explicitly because surface-attached organisms behave very differently from free-floating ones.

Attached algae receive different amounts of light depending on how deep the surface sits and how much planktonic algae shade the water above. They are limited by how much physical space the surface provides. And critically, surface texture determines how much protection organisms get from grazers. Algae growing on the smooth open face of a glass wall are almost fully exposed -- a copepod can scrape off 95% of them. But algae tucked into the pores of a rough ceramic surface, or nestled between gravel particles, are partially or fully protected. These protected zones, called refugia, are one of the most important mechanisms for ecosystem stability: they guarantee that some prey always survives no matter how intense the grazing pressure.

There are two kinds of surface. Static surfaces have a fixed area — a piece of ceramic or a glass wall stays the same size regardless of what grows on it. Dynamic surfaces grow and shrink with the organisms that create them. The model's one dynamic surface is the aggregated macrophyte canopy: as Hornwort, Vallisneria, and Cryptocoryne fronds expand, their leaves provide an increasing colonizable area for periphyton, nitrifiers, and biofilm bacteria. A dense canopy can multiply the colonizable area by 10× over the jar walls and substrate alone — see Surfaces for the per-species specific-leaf-area values.

Each surface has properties that shape the community growing on it: roughness (how easily organisms attach), carrying capacity (how dense the biofilm can get), light exposure (orientation and depth below the water surface), and grazer access (how easily consumers can reach the organisms growing there). These properties vary widely -- smooth glass promotes easy grazer access and high detachment, while porous ceramic promotes dense, well-protected biofilms. The choice of surfaces has a large impact on which species thrive and whether the ecosystem is stable.