FluidLife 🌊🫧

FluidLife is a small ecosystem simulation where simple organisms try to persist inside a dynamic, incompressible flow field. It is intentionally environment-first: agents drift, consume, and reproduce locally while most structure emerges from the fluid and transported resources.

What the simulation models

• Incompressible fluid flow using a stable Jos-Stam style solver (diffuse → project → advect → project) that keeps mass conserved while allowing local velocity impulses. The flow is further shaped by seasonal direction changes, pulsed amplitude, occasional shocks, and optional shear bands to create gradients and eddies.
• Transported scalar fields. Nutrients (and optional waste/memory) are injected by emitters, pulled out by sinks/boundaries, diffused, and advected by the flow. Transport masks can create bottlenecks to restrict movement of resources.
• Minimal agents. Organisms drift with the flow, add a weak swim bias (either riding the current or pushing upstream), metabolize, enter dormancy when flow/nutrients are low, and reproduce when energetic enough. Traits mutate slightly to create lineage diversity.
• Emergence over control. Populations rise and fall based on environmental capacity: fast channels become deserts, eddies become refuges, and sudden flow shocks can cause die-offs.

Features

• Dynamic flow controller with seasonal rotation, pulses, shocks, and optional shear zones.
• Nutrient sources/sinks with periodic upwelling support, decay, and boundary loss; optional waste and memory feedback fields.
• Transport masks to create corridors/bottlenecks.
• Lineage tracking with species grouping and an optional lineage report on exit.
• Live overlays for nutrients, waste, or flow stress plus population/species charts in the side panel.
• Adjustable simulation presets (balanced, harsh, sandbox) via SimConfig(preset=...).

Run locally

Requires Python 3.10+.

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -e .
python -m fluidlife

Controls

• Mouse drag in the main field: inject nutrients and a small velocity impulse
• N: toggle nutrients vs dye view
• W: toggle waste view
• S: toggle flow stress view
• R: reset the world
• Esc or window close: quit (writes a lineage report to the cwd)

Presets

SimConfig now supports named presets so you can pick how forgiving the world should be without tweaking each knob:

• Balanced (default): softer flow, randomised starting season, more persistent nutrient sources, lighter sinks.
• Harsh: mirrors the older defaults with strong eastward start, rapid boundary loss, and sparse nutrients.
• Sandbox: gentle flow with abundant nutrients and no sinks/mask for quick visual experiments.

Example:

from fluidlife.sim.config import SimConfig

config = SimConfig(preset="harsh")  # or "balanced", "sandbox"

Quick tuning guide

If agents still die off quickly, try nudging these parameters:

• Lower base_flow_speed or pulse_strength to reduce drift.
• Increase nutrient_source_rate/nutrient_source_radius or add more nutrient_sources.
• Disable sinks (enable_nutrient_sinks=False) or set boundary_nutrient_loss to 0.0.
• Reduce nutrient_decay so plumes last longer.

Screenshots