Metadata-Version: 2.4
Name: woda
Version: 0.1.0
Summary: World Ocean Dynamics Arena — fluid-environment benchmark for SwarmOpt
Author-email: Siobhan K Cronin <siobhankcronin@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/SioKCronin/woda
Project-URL: Source, https://github.com/SioKCronin/woda
Project-URL: Issues, https://github.com/SioKCronin/woda/issues
Project-URL: Documentation, https://github.com/SioKCronin/woda#readme
Keywords: swarm optimization,benchmark,ocean simulation,particle swarm,multi-agent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=1.19.0
Requires-Dist: PyYAML>=5.4
Provides-Extra: viz
Requires-Dist: matplotlib>=3.3.0; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: matplotlib>=3.3.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Provides-Extra: swarm
Provides-Extra: all
Requires-Dist: matplotlib>=3.3.0; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Dynamic: license-file

# WODA — World Ocean Dynamics Arena

A **test environment and benchmark suite** for [SwarmOpt](https://github.com/SioKCronin/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 **W**aves, **O**rbits, **D**ispersion, and **A**gents interact—not a closed-form benchmark function, but a dynamical search landscape.

![WODA water world: cross-section of fluid layers with currents, plus 3D cutaway](docs/media/woda_water_world.png)

*`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.*

<details>
<summary>Flat simulator view (2D domain)</summary>

![WODA spring_tide ocean: viscosity zones with penny track and tide speed field](docs/media/woda_ocean_preview.png)

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

</details>

---

## 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)

```text
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](docs/DEVELOPMENT_PLAN.md).  
Physics notes: [docs/physics.md](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](docs/physics.md).

---

## Install

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

From a git checkout (editable): `pip install -e ".[dev]"` — see [docs/SETUP.md](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):

```bash
./start
```

Optional world / flags:

```bash
./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](docs/SETUP.md). Short version:

```bash
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](LICENSE.md).  
Contribution guidelines: [CONTRIBUTING.md](CONTRIBUTING.md).

---

## Status

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

```bash
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](docs/DEVELOPMENT_PLAN.md).
