This page is part of the public contract of Battery-TA-RWARE. Results obtained with the simulator depend on these rules, so report the package version (and this model version) with every result. A change to any rule below is released as a new minor model version (2.x) and listed in CHANGELOG.md. A change that breaks existing configurations or trajectories gets a new major version.
Model 2.1 is the default (model: "2.1"). It keeps every rule on this page and adds the
operational rules in Model 2.1 below. Set model: "2.0"
(and use get_scenario(name, model="2.0") for a built-in scenario) to reproduce model 2.0 exactly; this
is verified tick by tick against release 2.0.0.
Model 2.2 is opt-in (model: "2.2", get_scenario(name, model="2.2")). It keeps every model 2.1
rule and adds one: the helper work-cell reservation.
Selecting 2.1 (the default) reproduces model 2.1 exactly; this is checked against fingerprints
recorded before 2.2 existed (python experiments/checks/identity.py). Report results of 2.1 and
2.2 separately: a difference between them is a change of the simulated warehouse, not of a policy.
Version 2 is a new engine. It is not trajectory-compatible with TA-RWARE / Battery-TA-RWARE v1
(git tag legacy-v1.1.0, branch v1), or with any study that ran on the v1 kernel. Its movement,
task, energy and observation models are all different.
- Time advances in discrete ticks.
seconds_per_tick(default 5 s) converts power to energy only. It does not change the dynamics. - Distances are in grid cells. Robots move with 4-connectivity, at most one cell per tick.
- Power is in W, energy in Wh, payload in kg. Coordinates are
(row, col).
step(actions) advances the tick counter by one and then runs these phases in a fixed order:
- Actions. Robots are processed in ascending id order. In macro mode the task board is
recomputed after every join, so an earlier robot's join changes what a later robot's slot
index refers to. A rejected action counts in
info["invalid_actions"]and has no effect. - Breakdowns. A failed robot counts down its repair time. An operational robot fails with
probability
failure.rate. A failure stops charging, keeps the robot's commitment and freezes the robot in place. - Movement: PIBT in macro mode, simultaneous moves in primitive mode (see below).
- Stage work. Tasks are processed in id order. Completing a task frees its crew and readies its dependents.
- Charging and energy. Energy is integrated over the tick from what happened in phases 3 and 4. Robots can become full or stranded here.
- Demand. New tasks and jobs are released. Tasks released in tick t can be acted on from tick t + 1.
- Rewards and episode end.
Events in info["events"] carry the tick in which they happened. Within a tick they appear in the
order above.
Macro mode. Each robot has an implicit target derived from its commitment: a stage cell (or a
standing cell within radius for adjacent roles), a charger, or a parking/queueing cell. The
robot moves towards it with PIBT (Okumura et al., AIJ 2022):
- Priority is the number of ticks spent travelling towards the current target, with ties broken by robot id.
- Candidate cells are ordered by exact remaining distance. This is a reverse BFS within the robot's
allowed zones (
zones, orzones_loadedwhile carrying) that respects one-way cells. Ties prefer unoccupied cells. - The occupant of a wanted cell inherits the priority and must move away first, recursively. A pushed robot may not step into its pusher's cell.
- A restricted swap operation (after Okumura, IJCAI 2023) is applied only when the wanted cell holds a robot trapped in a dead end. The implementation was written for this package.
- The following units are fixed obstacles for the tick: failed robots, charging robots, robots working a stage, and robots without enough speed credit.
- Joint carriers move as one unit at the speed of their slowest member.
Primitive mode. Every robot's intended move is resolved simultaneously, in the same tick:
- A stationary occupant blocks a move into its cell.
- Among robots moving into the same cell, the lowest id wins.
- Swaps (two robots exchanging cells) are rejected.
- Carriers of the same task may share a cell. No other robots may.
Speed. Each tick a unit gains speed credit, capped at 1, and moves only with at least 1
credit. A speed of 0.5 therefore means one move every two ticks.
Lifecycle: pending → ready → assigned → active → completed, plus suspended, failed and
cancelled. The allowed transitions are in battery_tarware.tasks.ALLOWED_TRANSITIONS. Every
transition is recorded with its tick, and suspended, failed or cancelled transitions also record a
reason.
pending: released, but its dependencies are not complete.ready: it can be assigned.assigned: at least one robot holds one of its roles.active: the first stage has started.suspended: the whole crew left after work had started. The task keeps its progress and resumes when a new crew arrives.- A crew released before any work started returns the task to
ready. This is a reassignment, not a failure.
Stages:
- Stages run in order. A stage advances only in ticks in which every role it needs is filled, and
every member is present (
on_cell: on the stage cell;adjacent: withinradius, Chebyshev distance) and operational. - Progress per tick is the smallest
handling_speedin the crew. A stage completes when progress reachesduration. - After a stage, roles that are not needed in the next stage are released (unless
stay: true), as are roles that no later stage needs.
Payload:
- The payload is picked up when the first stage completes and placed when the last one completes.
- A carrier that strands or is released while it has failed drops the payload on its current cell.
- A new carrier crew must gather on that cell before work continues. The
payload_pickedevent then hasreload=True. - An operational robot cannot be released while it is carrying.
Rewards:
- A completed task pays
task_completed × priority + late_per_tick × lateness, split equally across the crew at completion time. Lateness is the number of ticks past the deadline. - A completed stage pays
stage_completed, split across that stage's crew.
The power drawn in a tick is the sum of the following terms, multiplied by
seconds_per_tick / 3600 to give energy:
| Term | When |
|---|---|
idle_w |
every tick in which the robot is not stranded, including while failed or charging |
move_w |
the robot moved this tick |
payload_w_per_kg × weight / n_carriers |
the robot moved while carrying; each carrier pays for its share |
handling_w |
the robot worked a stage this tick |
Charging:
- A robot charges only while it occupies a compatible dock. One robot fits per dock.
- It gains
min(charger power_w, max_charge_w) × charge_efficiency, and the battery is capped atcapacity_wh. - Charging stops automatically when the battery is full, and the robot becomes idle. It also stops when the robot is released, reassigned, fails or strands.
Stranding: a robot whose energy reaches 0 is stranded permanently. It releases its role and drops its payload, if it has one.
terminated: the demand is finite and every released item is done, or every robot is stranded.truncated:max_stepshas been reached and the episode did not terminate.
reset(seed) derives five independent streams with numpy.random.SeedSequence(seed).spawn(5):
spawn positions, demand arrivals, task sampling (cells, weights, mixes), failures and observation
noise.
For a given package version, the same seed and the same actions reproduce a run exactly. Changing one random process (for example the failure rate) does not change the draws of the others.
Model 2.1 makes robots wait, move, cooperate and charge for reasons that follow from the task and
resource rules, instead of from artifacts of the movement implementation. Every rule below applies
only with model: "2.1".
A cell holds one robot, with exactly these exceptions:
-
Joint transport. The carriers of one task share the payload's cell while they carry it.
-
Shelf loading and unloading. A task's carrier and its crew members whose role has
presence: on_cellmay share the cell of the task's current stage (or its payload cell). In the built-in scenarios a picking robot steps onto the shelf cell beside the AGV to load or unload the tote, as in TA-RWARE. One picker works on the shelf cell; a task that needs a second picker (picker_2) has it work from a neighbouring cell. -
Separation. Robots that shared a cell under the two rules above stay together after their task releases them only until they drive apart. In the validated scenarios this takes at most 10 ticks.
-
Role alternatives. The position comes from the alternative a robot fills its role through, not from the role. For example, in
get_scenario("intermediate", substitution=True)thecasesupport slot is filled either by a picking robot on the shelf cell (it shares the cell with the carrier, as above) or by a tote AGV withload_assistfrom a neighbouring cell. A robot filling a role through anadjacentalternative never targets or works on the stage cell itself.
Occupancy compatibility is not coalition membership. Being assigned to the same task does not let a robot share every cell with its partners: only the cell where the active stage needs them together. Robots of unrelated tasks never share a cell.
- Every dock is available, reserved (assigned to a robot on its way), occupied (a robot
charges on it) or unavailable (a broken-down or stranded robot that does not hold it stands
on it).
Simulator.charger_state(charger)returns it. send_to_charger(and the macro charge action and primitiveinteract) reserves the dock. It is rejected if another robot holds the dock, or if it is unavailable. There is no implicit queue: a robot that gets no dock stays where it is, and the controller decides when to try again.- Releasing, a full battery, a breakdown or stranding frees the reservation.
- Docks are destinations only: robots are never routed through, or pushed into, a dock they are not going to charge at.
- A robot whose reserved dock is blocked by a stationed robot waits at a staging cell nearby.
map.dock_layout: baysturns every row of docks into one-cell bays off the corridor (see configuration).
Charging, broken-down and stranded robots, and robots standing on their own stage cell for their crew or their stage, are long-lived obstacles: other robots route around them (they are walls in the distance field used by PIBT). If no way around exists, a robot waits. Short-lived obstacles (a robot without enough speed credit) are waited for.
A robot pushed by a higher-priority robot steps aside rather than retreating straight ahead of it when both are equally good for it, so slow robots are not driven down corridors.
- Waiting spots. A robot that has to wait (for a busy stage cell or dock, or for its carrier) waits on a neutral cell: plain aisle or storage, never a goal, dock or custom-zone cell, and never another task's current stage or payload cell. It keeps the spot it chose while the spot stays free, and no two robots claim the same spot.
- Parking. An idle robot parks on a free wide aisle cell away from goals and work zones, keeps that spot, and does not share it.
- Shared work cells. A robot does not enter a stage cell that another task also needs until its own crew for that stage is fully assigned, and it gives such a cell up to a task whose crew is complete. This prevents hold-and-wait between tasks that share a work cell (for example a quality-check station).
Waiting and parking spots are chosen in the movement phase only; reading a robot's target from
outside the step (Simulator._target) does not change the run.
The 2.1 rules were validated against a pre-registered behavioural gate on all built-in scenarios
and their large versions (2026-11-06; the gate scripts and the pre-registration record are kept
outside the published repository). Outcome of the confirmation run: model 2.0 reproduced exactly;
no swap or dock-exclusivity violation; no new stranding; the vertex-conflict criterion as
registered failed (it did not allow the intended co-location of a carrier and its crew on their
work cell) and passed under an amended definition fixed before the confirmation run; one
no-progress and one oscillation event, both traced to legitimate waiting behind a broken-down robot.
The same occupancy, swap, dock, no-progress and oscillation checks are re-run for models 2.1 and 2.2
by experiments/model_2_2/gate.py.
Model 2.1 keeps carriers and on_cell crew off a stage cell another task needs until their own
crew is complete (Shared work cells above). It did not cover helpers that work from beside
the stage cell (presence: adjacent, e.g. the second picking robot of a large task). Such a
helper could choose, and wait on, a neighbouring cell that is another task's work cell. That task's
loaded carrier then waits for the cell next to it, in the aisle, and can block the route of the
first task's remaining crew: a hold-and-wait cycle in which no robot of either crew moves again
(reproduced by python experiments/checks/known_gridlock.py).
Model 2.2 adds one rule:
- Helper work-cell reservation. A robot filling an
adjacentrole never chooses or keeps, as its standing or waiting cell, a cell that is the current stage cell or payload cell of another open, staffed task (its own task's stage cell excepted). If every standing cell within its radius is reserved this way, it waits at a neutral staging cell nearby (Waiting spots above) until one is free. A helper already working a stage finishes it first.
Nothing else changes: no timeout, forced move or random perturbation was added, and deadlock is
prevented by not entering the conflicting state rather than by recovering from it. The rule was
validated with a gate whose criteria were fixed before it was run (experiments/model_2_2/GATE.md,
python experiments/model_2_2/gate.py): occupancy, swaps and dock exclusivity as for 2.1, helper
targets, no-progress and oscillation streaks, stranding compared with 2.1, and no suspected stall
in the order scenarios.
Set model: "2.3" (get_scenario(name, model="2.3")). It builds on 2.2 and changes only what is
listed here. 2.0-2.2 trajectories are unchanged (experiments/checks/identity.py).
Loading a tote onto an AGV and putting it back on its shelf always involves a picking robot. In the
built-in scenarios the task types that had no picker (solo in basic, tote in intermediate) get
one, standing on the shelf cell like every other picker; the spotter of the two-AGV oversize lift
also stands on the shelf cell. The picker is in the pick and return stages, not in deliver.
A task whose carrier role has two robots (count: 2) is carried by a convoy. More than two carriers
are rejected in 2.3. Primitive mode keeps the 2.0-2.2 behaviour (the pair shares one cell).
- Two cells. The two carriers never share a cell. While carrying, they always occupy two neighbouring cells and move as a rigid pair like a snake: one tick, either end leads, steps into a free neighbouring cell, and the other end moves into the cell the leading end left. A convoy can therefore back out of a shelf bay through the cell its follower stood on. Only the one newly entered cell has to be free; pushing an occupant out of it follows the usual PIBT rules.
- Leader and follower. The leader is the carrier with the lowest id. Before the payload is lifted the leader drives to the payload cell; the follower waits at a waiting spot nearby until the leader stands there, then takes the free-way cell beside it (the nearest aisle neighbour). This keeps the one way into a shelf bay open for the leader.
- Presence. A convoy is in place at a stage cell when one carrier stands on it and the other stands on a neighbouring cell that is not a shelf (the free way: an aisle cell next to a shelf slot or a goal). This is where the pick, the delivery and the return are worked. The picker of the task steps onto the stage cell beside the carrier on it, as in 2.1.
- Both carriers pay for their share of the payload while moving (unchanged), and a convoy moves at the speed of its slowest member.
- The coalition estimates still treat the follower's distance as the distance to the payload cell, so they are optimistic by at most one cell.
Simulator.goal_of(robot)returns where a robot is heading and why:pickup,stage,help,deliver(to a goal),return(to the shelf slot),queue(a waiting spot off a busy cell),charge,parkornone. The renderer draws a thin line to the goal for every robot that is going somewhere, coloured by that reason, and frames the goal a payload is delivered to (purple) apart from the shelf slot it is returned to (orange).- Idle and waiting are different states. A robot is idle when it has no commitment: it is parked
or free and is not working for anyone. It is waiting when it is committed to a task and stands
still on purpose;
Simulator.wait_reason(robot)says why:crew(in place, waiting for the rest of the crew or for the stage to start) orqueue(held at a waiting spot because its cell is busy, claimed by a task whose crew is complete, or its carrier is not in place yet). It is blocked (traffic) when it has a free way to its goal but another robot is in the way.