Skip to content

Environments

The repo includes a repeated matrix game and several PettingZoo-compatible gridworld suites. Each wrapped benchmark supplies one temporal formula per agent.

Factory functions and constraint wrappers are documented in the Environments API.

Stag Hunt

Location:

src/environments/matrix/stag_hunt/
notebooks/matrix/stag_hunt/

Stag Hunt is a fixed two-player repeated matrix game. Actions are Hare and Stag, with default payoffs:

  • both hare: (3, 3)
  • both stag: (4, 4)
  • one stag and one hare: (0, 3) for the stag/hare players

The primary objective is SustainedStag:

F (both_stag & X (both_stag & G !unmirrored))

The formula rewards traces that eventually reach two consecutive stag outcomes and then remain mirrored.

Pursuit

Location:

src/environments/gridworlds/pursuit/
notebooks/gridworlds/pursuit/

Pursuit contains guard and intruder objectives over gridworld collisions, goal reachability, and gap movement. The notebook variants include:

  • Classic_2_mo.py
  • Capture_2_mo.py
  • Classic_3_mo.py
  • Capture_3_mo.py

Example atoms include goal_reached, collision_ever, guard_intruder_collision, and intruder_in_gap.

Chemistry

Location:

src/environments/gridworlds/chemistry/
notebooks/gridworlds/chemistry/

Chemistry uses the repository's native PettingZoo chemistry__two_metabolic_cycles substrate. Visual experiments see pooled normalized RGB observations; render_mode=None instead exposes compact categorical object grids without rasterization. Labels are derived from metabolic rewards and native events.

Main objectives:

  • Food: F player_i_food_metabolized
  • FoodThenXY: F (player_i_food_metabolized_ever & player_i_xy_metabolized)
  • FoodThenSharedXY: F (player_i_food_metabolized_ever & xy_metabolized)

Food is the easier sanity benchmark. FoodThenXY is the harder per-agent temporal objective.

Harvest

Location:

src/environments/gridworlds/harvest/
notebooks/gridworlds/harvest/

Harvest uses the native PettingZoo commons_harvest__partnership substrate. Visual experiments receive RGB policy observations, while low-memory callers receive categorical grids and temporal labels track apple collection and punishment events.

Main objectives:

  • Harvest: F player_i_apple_collected
  • SafeHarvest: (G !player_i_punishment_received) & (F player_i_apple_collected)

The notebook-facing benchmark is SafeHarvest_4_mo.py.

Territory

Location:

src/environments/gridworlds/territory/
notebooks/gridworlds/territory/

Territory uses the native PettingZoo territory__rooms substrate. The visual policy path uses pooled RGB, while structured mode provides tile grids; side channels such as READY_TO_SHOOT and COLLECTIVE_REWARD remain available for label computation.

Current primary benchmark:

notebooks/gridworlds/territory/RoleClaim_2_mo.py

RoleClaim uses two agents:

  • player_0: (F player_0_resource_claimed) & (G !player_1_resource_claimed)
  • player_1: (G !player_1_resource_claimed) & (F player_0_resource_claimed)

This creates an asymmetric and coupled objective: player_0 must claim, and player_1 must not claim while still needing player_0 to succeed.

Gift Refinements

Location:

src/environments/gridworlds/gift_refinements/
notebooks/gridworlds/gift_refinements/

Gift Refinements uses the native six-player PettingZoo substrate. Visual experiments receive pooled RGB, structured mode receives categorical grids and scalar inventory/readiness, and labels track token consumption, refined gift receipt, native gift events, inventory, and beam readiness.

Main objectives:

  • Consume: F player_i_tokens_consumed
  • RefinedThenConsume: F (player_i_refined_gift_received_ever & player_i_tokens_consumed)

Consume is an easier sanity benchmark. RefinedThenConsume is the harder temporal and strategic benchmark.

Labeling Rule Of Thumb

Prefer agent-specific atoms when each learner should earn its own satisfaction:

player_i_apple_collected
player_i_tokens_consumed
player_i_resource_claimed

Aggregate atoms are useful only when the formula intentionally reasons about team state or shared milestones.