WODA — World Ocean Dynamics Arena

A test environment and benchmark suite for SwarmOpt: swarms must recover a target (“the penny”) dropped into a multi-fluid ocean on a moon-tide world. Deployments happen on arbitrary schedules; algorithms are ranked by time-to-convergence under heterogeneous physics and swarm-separation constraints.

WODA (working name): a world where Waves, Orbits, Dispersion, and Agents interact—not a closed-form benchmark function, but a dynamical search landscape.

spring_tide as planned — distinct liquid layers (brine, thin channel, open ocean, syrup) with different tide currents in each. Fast channel jet vs slow syrup shear (drag ∝ ν); right panel is the same stack in 3D cutaway.

Flat simulator view (2D domain)

Left: viscosity map, tide quiver, and penny path on the 2D grid. Right: tide speed magnitude at mid-episode.

---

Intent

SwarmOpt already excels at comparing algorithms on analytic landscapes (sphere, Rastrigin, multi-objective fronts). WODA asks a different question:

How do swarms perform when the “fitness landscape” is really a fluid environment—changing in space, time, and viscosity—and agents cannot crowd arbitrarily close together?

Underneath the benchmark is a teaching goal: build intuition for collective movement strategy—the kinds of coordination our species (and other social animals) use under currents, crowding, and uneven ground—by feeling them in a world you can watch and, later, inhabit in VR.

We throw a penny into the ocean. The penny is the global attractor: minimum “cost” is proximity to its true position (possibly unknown until sensed). The ocean is not uniform:

• Regions differ in liquid type and kinematic viscosity (and thus drag, diffusion, and effective swim speed).
• Tides from eight moons superpose; flow fields shift on periods we can compute from orbital parameters.
• Swarms are launched after arbitrary intervals—some agents may enter during calm water, others into a rip current.

The research metric is which swarm designs reach the penny fastest (and how reliably). The product arc is the same physics as a playable / VR experience: players or algorithms wear suits in the fluid world and learn why spread, timing, and local conditions beat blind clumping.

This is deliberately challenging for swarms that assume:

• homogeneous dynamics across particles,
• unconstrained particle overlap,
• static or gradient-only objectives.

---

Scenario (narrative spec)

Ocean world
├── Surface mesh / zones (N liquid types, each with ν, density, optional barriers)
├── Tide field T(x, y, t) = Σᵢ Aᵢ(x,y) · sin(ωᵢ t + φᵢ)   # 8 moon-driven components
├── Penny event at (x*, y*, t_drop) — target for all swarms
└── Episode clock — swarm injections at user-defined intervals

Swarm deployment
├── Wave 1 at t₀, Wave 2 at t₀ + Δ₁, …  (arbitrary intervals)
├── Per-agent: max speed capped by local ν, optional min pairwise distance d_min
└── Sensing: penny range/noise model (full, delayed, or partial)

Scoring
├── Primary: time-to-threshold ε (first epoch where best agent < ε of penny)
├── Secondary: success rate, path length, energy, violation of d_min
└── Stratify by tide phase bucket and viscosity zone at spawn

Design goals, phases, benchmark protocol, and open questions: docs/DEVELOPMENT_PLAN.md.
Physics notes: docs/physics.md.

WODA is a downstream consumer of SwarmOpt—not a fork. Agents wear a suit: SwarmOpt chooses intent; the suit + ocean enact motion. See docs/physics.md.

---

Install

pip install woda
# optional realtime viewer deps:
pip install "woda[viz]"

From a git checkout (editable): pip install -e ".[dev]" — see docs/SETUP.md.

---

Development setup

Local path: ~/code/woda
Git remote: https://github.com/SioKCronin/woda

Run the realtime simulator

From the repo root (creates .venv, installs WODA, opens the viewer):

./start

Optional world / flags:

./start configs/worlds/calm.yaml
./start configs/worlds/spring_tide.yaml --realtime 3 --gain 1.5

Keys: p / space pause, r restart, q quit.

No module named woda means the package isn’t installed in your current Python — use ./start (or pip install -e ".[viz]" inside an activated venv) instead of calling python scripts/run_realtime.py alone.

Dev install & tests

See docs/SETUP.md. Short version:

python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

Dependency (expected later): swarmopt via pip install -e ../swarmopt.

License & contributing

WODA is released under the MIT License.
Contribution guidelines: CONTRIBUTING.md.

---

Status

Phase 0–3 underway — ocean + suits + thin SwarmOpt adapter + benchmark snapshots (scripts/run_benchmark.py). See docs/benchmark-protocol.md.

python scripts/run_benchmark.py --t-max 25 --seeds 0,1,2

Next step: tighten SwarmOpt→suit coupling and Phase 4 leaderboard polish. See the development plan.