Source code for hybrid_aif.envs.base

"""Pure-functional environment interface (pymdp's ``Env``, with value semantics).

An :class:`Env` is an ``equinox.Module`` carrying only static structure; every
array-valued parameter travels in a separate ``params`` pytree passed to each
call, so one env instance vmaps across a batch of per-agent parameter sets.

Conventions (chosen to compose with :func:`hybrid_aif.inference.discrete.fpi`):

- observations: tuple of scalar ``int32`` indices, one per modality — the
  list-of-index-arrays form ``fpi`` consumes directly;
- state: tuple of scalar ``int32`` indices, one per factor;
- action: ``int32`` array of shape ``(num_states,)``, one action level per
  factor (uncontrolled factors expose a single no-op action).

``reset`` and ``step`` are pure and unjitted; callers jit/vmap/scan them.
:meth:`System.as_env <hybrid_aif.system.System.as_env>` wraps its process in a
:class:`~hybrid_aif.envs.GenerativeEnv`, which speaks name-keyed mappings instead.
"""

import abc
from typing import Any

import equinox as eqx
import jax.numpy as jnp
from jax import Array

Obs = tuple[Array, ...]
State = tuple[Array, ...]


[docs] class Env(eqx.Module): """Abstract functional environment (pymdp's ``Env``, with value semantics). An ``Env`` is an ``equinox.Module`` carrying only static structure; every array-valued parameter travels in a separate ``params`` pytree passed to each call, so one instance vmaps across a batch of parameter sets. :meth:`reset` and :meth:`step` are pure and unjitted (callers jit, vmap or scan them). In the positional convention an observation is a tuple of scalar ``int32`` indices, one per modality; a state a tuple of scalar ``int32`` indices, one per state factor; and an action an ``int32`` ``(num_states,)`` array, one level per state factor (an uncontrolled state factor exposes a single no-op action). A :class:`~hybrid_aif.envs.GenerativeEnv` speaks name-keyed mappings instead. """ @property @abc.abstractmethod def num_states(self) -> int: """Number of state factors."""
[docs] def null_action(self) -> Any: """The no-op action, with the structure and shape every action this env takes. Default: the level-index action, ``(num_states,)`` int32 zeros. """ return jnp.zeros((self.num_states,), jnp.int32)
[docs] @abc.abstractmethod def reset(self, key: Array, params: Any) -> tuple[Obs, State]: """Sample an initial state and an observation of it."""
[docs] @abc.abstractmethod def step(self, key: Array, state: State, action: Array, params: Any) -> tuple[Obs, State]: """Sample the next state given ``action``, and an observation of it."""