Source code for hybrid_aif.reference.envs.tmaze

"""TMaze as a positional (pymdp-style) process, tensor-identical to ``pymdp.envs.TMaze``.

Transcribed from pymdp's ``TMaze`` (pymdp/envs/tmaze.py: ``_generate_A_separate``,
``_valid_connections``, ``generate_B``, ``generate_D``; separate-cue, adjacent variant) as a
pure constructor; tests/test_envs.py checks tensor parity against it.

Classic variant: five locations (centre 0, left 1, right 2, cue 3, middle 4),
adjacent connectivity, separate cue modality. Factors: location (5, controlled)
x context/reward-condition (2, fixed). Modalities: location (identity), reward
(none/reward/punishment), cue (none/left/right). Construction is traceable in
the scalar probability arguments, so batches of param sets can be built under
``vmap`` as well as by stacking.
"""

import jax.numpy as jnp
from jax import Array

from hybrid_aif.envs._process import DiscreteProcess
from hybrid_aif.envs.generative import GenerativeEnvParams

CENTRE, LEFT, RIGHT, CUE, MIDDLE = 0, 1, 2, 3, 4
NUM_LOCATIONS = 5
_CONNECTIONS = frozenset(
    [
        (CENTRE, CUE),
        (CUE, CENTRE),
        (CENTRE, MIDDLE),
        (MIDDLE, CENTRE),
        (MIDDLE, LEFT),
        (LEFT, MIDDLE),
        (MIDDLE, RIGHT),
        (RIGHT, MIDDLE),
    ]
)


[docs] def tmaze( reward_probability: float | Array = 1.0, punishment_probability: float | Array = 1.0, cue_validity: float | Array = 0.95, reward_condition: int | None = None, ) -> tuple[DiscreteProcess, GenerativeEnvParams]: """The classic TMaze as a positional process and its parameters, tensor-identical to pymdp's. Two state factors (location, five levels, controlled; context, two levels, fixed) and three modalities (location, reward, cue; see the module docstring). ``reward_probability`` is the chance the rewarded arm pays, ``punishment_probability`` the chance the other arm punishes, ``cue_validity`` the chance the cue location shows the true context, and ``reward_condition`` fixes the context (``None``: 50/50). The probabilities may be traced, so batches of parameter sets build under ``vmap``. """ rp = jnp.asarray(reward_probability, jnp.float32) pp = jnp.asarray(punishment_probability, jnp.float32) cv = jnp.asarray(cue_validity, jnp.float32) A_loc = jnp.eye(NUM_LOCATIONS, dtype=jnp.float32) A_reward = jnp.zeros((3, NUM_LOCATIONS, 2), jnp.float32) for loc in (CENTRE, CUE, MIDDLE): A_reward = A_reward.at[0, loc, :].set(1.0) for cond, (arm, other) in enumerate(((LEFT, RIGHT), (RIGHT, LEFT))): A_reward = A_reward.at[1, arm, cond].set(rp) A_reward = A_reward.at[0, arm, cond].set(1.0 - rp) A_reward = A_reward.at[2, other, cond].set(pp) A_reward = A_reward.at[0, other, cond].set(1.0 - pp) A_cue = jnp.zeros((3, NUM_LOCATIONS, 2), jnp.float32) for loc in (CENTRE, LEFT, RIGHT, MIDDLE): A_cue = A_cue.at[0, loc, :].set(1.0) for cond in range(2): A_cue = A_cue.at[cond + 1, CUE, cond].set(cv) A_cue = A_cue.at[2 - cond, CUE, cond].set(1.0 - cv) B_loc = jnp.zeros((NUM_LOCATIONS, NUM_LOCATIONS, NUM_LOCATIONS), jnp.float32) for frm in range(NUM_LOCATIONS): for act in range(NUM_LOCATIONS): to = act if (frm, act) in _CONNECTIONS else frm B_loc = B_loc.at[to, frm, act].set(1.0) B_ctx = jnp.eye(2, dtype=jnp.float32).reshape(2, 2, 1) D_loc = jnp.zeros(NUM_LOCATIONS, jnp.float32).at[CENTRE].set(1.0) if reward_condition is None: D_ctx = jnp.full(2, 0.5, jnp.float32) else: D_ctx = jnp.zeros(2, jnp.float32).at[reward_condition].set(1.0) env = DiscreteProcess(A_deps=((0,), (0, 1), (0, 1)), B_deps=((0,), (1,))) params = GenerativeEnvParams( likelihood=(A_loc, A_reward, A_cue), transition=(B_loc, B_ctx), initial_state_prior=(D_loc, D_ctx), ) return env, params