# WareMax

> WareMax is an open, deterministic discrete-event simulator and reinforcement-learning benchmark for task allocation in Robotic Mobile Fulfillment Systems (RMFS) — Kiva-style fleets of autonomous mobile robots (AMRs) that move pods to pick stations. Built by Skelf-Research; MIT-licensed.

WareMax simulates **only** pod-to-person RMFS dispatching. It does not model AS/RS cranes, conveyor sortation, AGV tugger trains, or human pickers walking aisles. Scenarios are YAML topology + station + policy definitions; warehouse CAD / DWG import is not supported.

Determinism is a tested property: same seed + same action sequence ⇒ byte-identical trajectory. The Rust core uses a ChaCha8 RNG seeded from `u64` and applies canonical (id-based) tie-breaking throughout.

## Pages

- [Home](https://waremax.skelfresearch.com/): overview, scope, scenario YAML example, links

## Product

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

## Guides

- [Guides index](https://waremax.skelfresearch.com/guides/): all how-to guides for installing, configuring, and running WareMax
- [Install and run your first scenario](https://waremax.skelfresearch.com/guides/install-and-run-first-scenario/): install the Rust CLI, run a deterministic RMFS scenario from YAML, and read the metrics
- [Writing a scenario YAML](https://waremax.skelfresearch.com/guides/writing-a-scenario-yaml/): define seed, robots, stations, order arrivals, traffic, and the policy stack in YAML
- [Plug WareMax into a Gymnasium RL loop](https://waremax.skelfresearch.com/guides/gymnasium-rl-loop/): use WaremaxAllocEnv — the Dict observation, action mask, SMDP framing, and reward modes, wired for MaskablePPO
- [Verifying determinism and replay](https://waremax.skelfresearch.com/guides/verifying-determinism/): how byte-identical trajectories are guaranteed — ChaCha8 RNG, canonical tie-breaking, single-threaded runs
- [Reading delay attribution](https://waremax.skelfresearch.com/guides/reading-delay-attribution/): the five buckets (assignment, travel, queue, congestion, service) that sum to cycle time, and using them as reward

## Use cases

- [Use cases index](https://waremax.skelfresearch.com/use-cases/): what teams use WareMax for, across ops, RL research, and consultancy
- [Sizing an AMR fleet](https://waremax.skelfresearch.com/use-cases/fleet-sizing/): sweep robot count against throughput and cycle-time tails with multi-seed confidence intervals before buying robots
- [Comparing dispatching policies](https://waremax.skelfresearch.com/use-cases/comparing-dispatching-policies/): A/B-test nearest_robot, round_robin, auction, and learned policies on a seeded scenario with Welch's t-test
- [Reproducible RL research](https://waremax.skelfresearch.com/use-cases/reproducible-rl-research/): a deterministic RL benchmark with byte-identical trajectories, a Gymnasium env, and multi-seed results
- [Stress-testing dispatching logic](https://waremax.skelfresearch.com/use-cases/stress-testing-dispatching-logic/): run seeded scenarios against every build so "policy or noise?" becomes answerable for integrators
- [3PL and consultancy modeling studies](https://waremax.skelfresearch.com/use-cases/3pl-modeling-studies/): find the regimes where dispatching has leverage by tuning load, congestion, and replicas

## Compare

- [Compare index](https://waremax.skelfresearch.com/compare/): honest comparisons with adjacent simulation tools
- [WareMax vs. AnyLogic](https://waremax.skelfresearch.com/compare/anylogic/): a multi-paradigm commercial sim suite vs. a narrow open-source RMFS benchmark with an RL interface
- [WareMax vs. a custom SimPy stack](https://waremax.skelfresearch.com/compare/simpy/): when rolling your own RMFS sim in SimPy stops being the right call — speed, determinism, and a native RL interface

## Blog

- [Blog index](https://waremax.skelfresearch.com/blog/): essays on DES, fidelity, and pilot vs. sim
- [Why discrete-event sim beats continuous for AMR planning](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, especially for the cycle-time tail
- [Reading a sim: what "high fidelity" actually buys you](https://waremax.skelfresearch.com/blog/reading-a-sim-what-high-fidelity-actually-buys-you/): fidelity as typed events, lognormal service times, canonical tie-breaking, and a delay decomposition — not pixels
- [Pilot vs. sim: where the 30% throughput surprise comes from](https://waremax.skelfresearch.com/blog/pilot-vs-sim-where-the-30-percent-throughput-surprise-comes-from/): the short list of what causes the pilot-vs-sim gap and how WareMax narrows it

## Reference

- [FAQ](https://waremax.skelfresearch.com/faq/): general/scope, determinism, RL, installation
- [Glossary](https://waremax.skelfresearch.com/glossary/): RMFS, AMR, DES, dispatching policy, Gymnasium, reward mode, attribution, and more
- [About](https://waremax.skelfresearch.com/about/): full architecture, RL interface, determinism rationale
- [Contact](https://waremax.skelfresearch.com/contact/): reach the WareMax team
- [RSS feed](https://waremax.skelfresearch.com/rss.xml)
- [Sitemap](https://waremax.skelfresearch.com/sitemap-index.xml)

## Canonical resources (off-site)

- [Source code](https://github.com/Skelf-Research/waremax)
- [Documentation](https://docs.skelfresearch.com/waremax/)

## What WareMax is for

- Operations engineers sizing AMR fleets and comparing dispatching policies before deployment
- RL researchers running reproducible experiments on warehouse dispatching
- Robotics integrators stress-testing dispatching logic on identical seeded scenarios
- 3PL / consultancy modeling teams studying when dispatching has leverage

## What is shipped in-box

- Deterministic Rust DES kernel (`waremax-core`)
- Graph topology + congestion-aware routing (`waremax-map`)
- Gymnasium environment via PyO3 (`waremax-gym`)
- Five heuristic baselines (`nearest_robot`, `least_busy`, `round_robin`, `auction`, `workload-balanced`)
- Four RL reward modes (`sparse`, `dense`, `attribution`, `routed`)
- Per-task causal delay attribution (assignment / travel / queue / congestion / service)
- A/B testing with Welch's t, parameter sweeps, benchmarking with regression detection