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."""