# WareMax — full reference for language models

> Open-source deterministic discrete-event simulator and reinforcement-learning benchmark for task allocation in Robotic Mobile Fulfillment Systems (RMFS). From Skelf-Research; MIT-licensed. Source: https://github.com/Skelf-Research/waremax. Docs: https://docs.skelfresearch.com/waremax/.

This file is for AI agents and assistants that want a single dense reference to WareMax. It is intentionally repetitive of the README and pages on the marketing site; the canonical source of truth remains the repository.

---

## One-line description

WareMax is a high-performance discrete-event simulator (DES) for Robotic Mobile Fulfillment Systems (RMFS) — fleets of autonomous mobile robots (AMRs) that move inventory to pick stations, in the style of Kiva / Amazon Robotics — bundled with a Gymnasium-style reinforcement-learning environment exposing the task-allocation decision as a semi-Markov decision process (SMDP), with PyO3 bindings.

## Scope (what is and is not modeled)

**In scope:**
- Pod-to-person Robotic Mobile Fulfillment Systems
- Autonomous Mobile Robot (AMR) fleets on a graph topology
- Pick-station service with concurrency and lognormal service-time distributions
- Order arrival via Poisson process; negative-binomial lines per order; Zipf SKU popularity
- Inventory replicas across the topology
- Traffic / congestion via node and edge capacities with a `wait_at_node` policy
- Congestion-aware routing when `congestion_weight > 0`
- Charging stations and battery models

**Explicitly out of scope:**
- AS/RS cranes
- Conveyor sortation systems
- AGV tugger trains, fork AGVs
- Human pickers walking aisles
- Warehouse CAD / DWG import (scenarios are YAML topology, not CAD)
- Real-time WMS integration (the Axum REST/WS API is for sim control, not WMS sync)

## Determinism guarantee

WareMax tests reproducibility as a property: same seed + same action sequence ⇒ byte-identical trajectory.

Implementation:
- Single-threaded simulator core (per scenario)
- ChaCha8 RNG seeded from `u64`
- Canonical (id-based) tie-breaking throughout — inventory placement, station / charging selection, every heuristic policy
- Strict crossbeam ping-pong handshake between the agent and the simulator in the RL control loop, so exactly one side runs at a time
- Tests in `crates/waremax-rl/tests/determinism.rs`

History: prior to the determinism work, the simulator had several `HashMap`-iteration-dependent bugs in inventory placement and heuristic tie-breaking that made supposedly-seeded results silently irreproducible. Those have been fixed.

## Crate layout (Cargo workspace)

```
waremax/
├── src/                        # CLI binary (`waremax` command)
└── crates/
    ├── waremax-core            # DES kernel, event queue, IDs, SimTime, ChaCha-seeded RNG
    ├── waremax-map             # Graph topology, shortest-path & congestion-aware routing, traffic
    ├── waremax-storage         # Racks, bins, SKUs, inventory replicas
    ├── waremax-entities        # Robot, Order, Task, Station, ChargingStation
    ├── waremax-policies        # Allocation, station assignment, batching, priority, traffic policies
    ├── waremax-config          # YAML/JSON scenario parsing + schema validation
    ├── waremax-metrics         # Event log, time-series, CSV/JSON export, HTML/PDF reports
    ├── waremax-sim             # SimulationRunner, World, EventHandler, policy factory
    ├── waremax-testing         # Presets, ScenarioBuilder, BatchRunner, A/B testing, benchmarking
    ├── waremax-analysis        # Delay attribution, critical-path analysis, bottlenecks, RCA
    ├── waremax-statemachine    # Generic state-machine primitives
    ├── waremax-api             # Axum-based REST/WebSocket API
    ├── waremax-api-server      # API server binary
    ├── waremax-rl              # RL control seam (Gym-style env, attribution/routed rewards)
    └── waremax-gym             # PyO3 bindings + Python wrapper + training scripts
```

## CLI commands

- `waremax run <scenario.yaml>` — execute a simulation
- `waremax validate <scenario.yaml>` — validate configuration
- `waremax demo` — run a demo scenario
- `waremax sweep` — parameter exploration
- `waremax compare` — compare configurations
- `waremax ab-test` — statistical comparison (Welch's t)
- `waremax benchmark` — performance regression detection
- `waremax analyze` — analyze report directories
- `waremax list-presets` — show built-in scenario presets

## Scenario YAML — minimal example

```yaml
seed: 12345
simulation:
  duration_minutes: 60
  warmup_minutes: 5

robots:
  count: 10
  max_speed_mps: 1.5

stations:
  - id: S1
    node: "30"
    type: pick
    concurrency: 2
    service_time_s:
      distribution: lognormal
      base: 12.0
      per_item: 3.0

orders:
  arrival_process:
    type: poisson
    rate_per_min: 1.0
  lines_per_order:
    type: negative_binomial
    mean: 2.0
  sku_popularity:
    type: zipf
    alpha: 1.1
  due_times:
    type: fixed
    minutes: 30

policies:
  task_allocation: { type: routed }       # or nearest_robot, least_busy, round_robin, auction, rl_agent
  station_assignment: { type: least_queue }
  batching: { type: none }
  priority: { type: strict_priority }
  smart_bins: false                        # re-pick the in-stock replica nearest to the chosen robot
  inventory_skus: 100                      # smaller => more spread replicas per SKU

traffic:
  policy: wait_at_node
  node_capacity_default: 4
  edge_capacity_default: 4
  congestion_weight: 0.0                   # > 0 enables occupancy-weighted routing
```

## Reinforcement-learning interface

- Environment class: `WaremaxAllocEnv`
- Standard `gymnasium.Env` API
- Observation: `Dict({"robots": (64, 8), "task": (6,), "action_mask": (64,)})`
- Action: index into masked candidates
- Recommended algorithm: `sb3-contrib.MaskablePPO`
- Recommended policy: permutation-equivariant *candidate-scoring* policy
- SMDP framing: time between decisions varies

Four reward modes:
- `sparse` — baseline; reward at terminal events only
- `dense` — baseline; per-step shaping
- `attribution` — per-task causal delay decomposition (assignment / travel / queue / congestion / service)
- `routed` — per-decision *controllable* cost: assignment wait + travel to pickup

Recommended default: `routed`. `attribution` is also strong. `dense` and `sparse` are baselines, not recommendations.

## Delay attribution buckets

Per-task cycle time decomposes into five causal buckets that sum to cycle time exactly:

1. assignment wait — `ORDER_NEW` → `TASK_ASSIGN`
2. travel — `TASK_ASSIGN` → arrival at pickup bin
3. station queue — wait at station before service began
4. congestion — wait at nodes or on edges due to traffic policy
5. service — station service time

## Heuristic baselines

Selectable in the scenario YAML by name:
- `nearest_robot`
- `least_busy`
- `round_robin`
- `auction`
- `workload-balanced`
- `rl_agent` (the slot for a trained RL policy)
- `routed` (a heuristic that incorporates routing cost)

## Research finding (from the paper)

*"When Does Learning to Dispatch Help? A Deterministic Benchmark and a Controllability Principle for Reward Design in Warehouse Robotics."*

Headline findings, each backed by multi-seed committed data under `crates/waremax-gym/python/results/`:

1. **Representation × reward interaction.** A permutation-equivariant candidate-scoring policy paired with a reward targeting the delay the decision controls reaches strong-heuristic SLA attainment (~97% on-time); a flattened MLP — or a naive dense/sparse reward — plateaus near the weakest heuristic (~82–85%). Neither ingredient suffices alone.
2. **Controllability principle for reward design.** Restricting attribution to delay the agent can *control* (assignment wait, travel-to-pickup) is directionally better than additionally penalizing the *uncontrollable* delay (congestion, station queue). Reported with Welch's t.
3. **Bounded leverage.** Across four control levers (allocation, congestion-aware routing, reward design, pickup-bin choice) and a range of regimes, learned dispatching matches but does not beat simple heuristics here, because the system is capacity- and destination-contention-bound; state-blind round-robin is near-optimal.

## Comparison vs. other tools

vs. **AnyLogic**: AnyLogic is a commercial multi-paradigm sim suite. WareMax is open-source and narrowly RMFS. AnyLogic has a graphical IDE; WareMax does not. WareMax has a native Gymnasium environment and a tested determinism property; AnyLogic supports reproducibility but does not guarantee it as a tested property.

vs. **a custom SimPy stack**: SimPy is a process-based Python DES library. Rolling your own RMFS sim on SimPy is fine for small studies. WareMax pays back when you need the Rust core's speed, an out-of-the-box RL interface, or determinism as a tested property rather than as something you would have to engineer yourself.

vs. **FlexSim**: not compared on this site; FlexSim's primary mode is graphical 3D modeling for general manufacturing/logistics. If RMFS dispatching with a Gymnasium env is your goal, WareMax is the closer fit.

vs. **RAWSim-O**: per the README, WareMax targets three properties prior RMFS simulators do not jointly provide: exact determinism (byte-identical replay), a first-class RL interface (Gymnasium + PyO3), and instrumented delay attribution usable as a reward signal.

## Audience framing

- Operations engineers sizing AMR fleets
- Robotics integrators validating dispatching logic
- RL / academic researchers running reproducible warehouse-dispatching experiments
- 3PL and warehouse-design consultancies needing per-scenario sensitivity analysis
- AMR vendors validating throughput claims on a neutral benchmark

## License

MIT.

## Citation

```bibtex
@unpublished{waremax2026,
  title  = {When Does Learning to Dispatch Help? A Deterministic Benchmark
            and a Controllability Principle for Reward Design in Warehouse Robotics},
  author = {Sarkar, Dipankar},
  note   = {WareMax benchmark; \url{https://github.com/Skelf-Research/waremax}},
  year   = {2026}
}
```

## Site page index

Every content page on the marketing site, grouped by section. Trailing slashes are canonical.

Home:
- https://waremax.skelfresearch.com/ — overview, scope, scenario YAML example, links

Product:
- https://waremax.skelfresearch.com/features/ — deterministic DES kernel, replay, Gymnasium env, baselines, reward modes, attribution
- https://waremax.skelfresearch.com/how-it-works/ — architecture diagram, the workspace crates, and the determinism mechanism
- https://waremax.skelfresearch.com/quickstart/ — install the CLI and run a first deterministic scenario

Guides:
- https://waremax.skelfresearch.com/guides/ — all how-to guides
- https://waremax.skelfresearch.com/guides/install-and-run-first-scenario/ — install the Rust CLI, run a deterministic scenario from YAML, read the metrics
- https://waremax.skelfresearch.com/guides/writing-a-scenario-yaml/ — define seed, robots, stations, order arrivals, traffic, and the policy stack in YAML
- https://waremax.skelfresearch.com/guides/gymnasium-rl-loop/ — WaremaxAllocEnv: Dict observation, action mask, SMDP framing, reward modes, wired for MaskablePPO
- https://waremax.skelfresearch.com/guides/verifying-determinism/ — byte-identical trajectories via ChaCha8 RNG, canonical tie-breaking, single-threaded runs
- https://waremax.skelfresearch.com/guides/reading-delay-attribution/ — the five delay buckets that sum to cycle time, and using them as reward

Use cases:
- https://waremax.skelfresearch.com/use-cases/ — what teams use WareMax for
- https://waremax.skelfresearch.com/use-cases/fleet-sizing/ — sweep robot count against throughput and cycle-time tails before buying robots
- https://waremax.skelfresearch.com/use-cases/comparing-dispatching-policies/ — A/B-test heuristic and learned policies on a seeded scenario with Welch's t-test
- https://waremax.skelfresearch.com/use-cases/reproducible-rl-research/ — a deterministic RL benchmark with byte-identical trajectories and multi-seed results
- https://waremax.skelfresearch.com/use-cases/stress-testing-dispatching-logic/ — run seeded scenarios against every build so "policy or noise?" is answerable
- https://waremax.skelfresearch.com/use-cases/3pl-modeling-studies/ — find the regimes where dispatching has leverage by tuning load, congestion, and replicas

Compare:
- https://waremax.skelfresearch.com/compare/ — honest comparisons with adjacent simulation tools
- https://waremax.skelfresearch.com/compare/anylogic/ — WareMax vs. AnyLogic (multi-paradigm commercial suite vs. narrow open-source RMFS benchmark)
- https://waremax.skelfresearch.com/compare/simpy/ — WareMax vs. a custom SimPy stack (when rolling your own stops being the right call)

Blog:
- https://waremax.skelfresearch.com/blog/ — essays on DES, fidelity, and pilot vs. sim
- https://waremax.skelfresearch.com/blog/why-discrete-event-sim-beats-continuous-for-amr-planning/ — why DES is the right level of detail for fleet sizing and dispatching
- https://waremax.skelfresearch.com/blog/reading-a-sim-what-high-fidelity-actually-buys-you/ — fidelity as typed events and a delay decomposition, not pixels
- https://waremax.skelfresearch.com/blog/pilot-vs-sim-where-the-30-percent-throughput-surprise-comes-from/ — what causes the pilot-vs-sim gap and how WareMax narrows it

Reference:
- https://waremax.skelfresearch.com/faq/ — general/scope, determinism, RL, installation
- https://waremax.skelfresearch.com/glossary/ — RMFS, AMR, DES, dispatching policy, Gymnasium, reward mode, attribution, and more
- https://waremax.skelfresearch.com/about/ — full architecture, RL interface, determinism rationale
- https://waremax.skelfresearch.com/contact/ — reach the WareMax team

## Canonical links

- Source: https://github.com/Skelf-Research/waremax
- Docs: https://docs.skelfresearch.com/waremax/
- Marketing site: https://waremax.skelfresearch.com/
- RSS: https://waremax.skelfresearch.com/rss.xml
- Sitemap: https://waremax.skelfresearch.com/sitemap-index.xml