Frequently Asked Questions
Everything about WareMax — the deterministic RMFS simulator and RL benchmark from Skelf Research.
General & scope
What is WareMax?
WareMax is an open-source, deterministic discrete-event simulator and reinforcement-learning benchmark for task allocation in Robotic Mobile Fulfillment Systems (RMFS) — pod-to-person AMR fleets that move pods to pick stations. It is built by Skelf Research and is MIT-licensed.
What does WareMax simulate?
WareMax models RMFS dispatching: which robot handles which pick task. It simulates AMR fleets on a graph topology, pick-station queueing with lognormal service times, Poisson order arrivals, Zipf SKU popularity, inventory replicas, and node/edge traffic capacities.
What does WareMax NOT simulate?
It does not model AS/RS cranes, conveyor sortation, sorters, AGV tugger trains, fork AGVs, or human pickers walking aisles. It does not import warehouse CAD or DWG files — scenarios are YAML topology and policy definitions. It is not a real-time WMS integration.
What language is WareMax written in?
The simulation core is written in Rust (waremax-core and the surrounding workspace crates). A Python extension built with maturin/PyO3 exposes a Gymnasium environment for reinforcement learning.
What license is WareMax under?
MIT. WareMax is fully open source. The authoritative source of truth is the GitHub repository at github.com/Skelf-Research/waremax.
Determinism
Is WareMax really deterministic?
Yes — it is a tested property. Same seed and same action sequence produce a byte-identical trajectory. This is enforced by a ChaCha8 RNG seeded from a u64, canonical id-based tie-breaking everywhere, single-threaded execution per scenario, and tests in waremax-rl/tests/determinism.rs.
Why does determinism matter for dispatching studies?
It turns "was that the policy or the noise?" into an answerable question. If two runs differ, the difference is caused by the code or scenario change, not by simulator randomness — which is what makes A/B tests and regression testing meaningful.
Does determinism survive the RL worker thread?
Yes. The RL control loop wraps the simulator with a strict crossbeam ping-pong handshake between the worker thread and the agent, so exactly one side runs at a time and the trajectory remains reproducible.
Were earlier "seeded" results reproducible?
Not always. The project fixed several latent HashMap-iteration-order bugs — for example in inventory placement and heuristic tie-breaking — that had previously made seeded results silently irreproducible. Determinism is now a tested guarantee.
Reinforcement learning
How do I use WareMax for reinforcement learning?
WaremaxAllocEnv is a Gymnasium environment exposed via PyO3. It provides a Dict observation with an action mask and SMDP framing, and is designed to pair with sb3-contrib MaskablePPO and a permutation-equivariant candidate-scoring policy.
What reward modes are available?
Four: sparse (terminal reward), dense (per-step shaping), attribution (per-task causal delay decomposition), and routed (the controllable cost — assignment wait plus travel to pickup). The recommended default is routed.
Does the RL agent beat the heuristics?
On the built-in presets, no. Learned dispatching matches nearest-robot and round-robin but does not surpass them, because the simulated system is capacity- and destination-contention-bound. WareMax publishes this as a finding and provides the tunable structure to find regimes where dispatching choice has leverage.
Which heuristic baselines ship in-box?
Five: nearest_robot, least_busy, round_robin, auction, and workload-balanced. They are selectable by policy name in the scenario YAML.
Installation & usage
How do I install WareMax?
Clone the repository and run cargo install --path . to build the CLI. For the Gymnasium environment, build the PyO3 extension with maturin. See the install guide for step-by-step instructions.
How is a scenario defined?
A scenario is a YAML (or JSON) file describing the seed, robots, stations, order arrivals, traffic capacities, and policy stack. It is parsed and schema-validated by waremax-config. There is no CAD import.
Can I add my own dispatching policy?
Yes. Implement the one-method TaskAllocationPolicy Rust trait and add a one-arm change in policy_factory.rs. The same pattern applies to station assignment, batching, priority, and traffic policies.
Where is the documentation?
Authoritative documentation is at docs.skelfresearch.com/waremax/, and the source of truth is the GitHub repository at github.com/Skelf-Research/waremax.