System#

class hybrid_aif.System[source]#

Bases: Module

Static structure of a System: discrete, continuous or mixed.

Every field is static; a table with field defaults and meanings is in docs/composing-systems.md. A System’s variables are its nodes: the state factors first, then the control nodes, which the System sets by decision (controls gives their node indices). state_names names the state factors and control_names the control nodes; node_names is the two in node order. B_deps, D_deps and H_deps have one entry per node; A_deps has one entry per modality, listing the state factors it observes. A transition reads its state parents from the previous step and its control parents at the step the control is chosen; a control node’s levels are its readers’ table axes. epistemic names variables: naming a state factor mounts the infogain of every modality that observes it, so switching one state factor off means naming the others.

The pymdp-style keywords controlled and B_control_deps are construction sugar, translated once into control nodes: each controlled state factor f (in node order) gets a node u_<f>, appended after the declared state factors, and the node is the last transition parent of f (under B_control_deps, of every state factor listing f, at the listed position), so every table keeps its layout. A System built from the sugar equals the one that declares those nodes natively. The sugar is readable back (controlled, B_control_deps) on a sugar-shaped System. A discrete node’s level count is its readers’ parent axis (policies()); a node is continuous when SystemParams.control holds its box, and its readers then read a float vector (a neural transition’s input, a linear-Gaussian transition’s G u term).

The fields fall in these groups (each field’s entry below gives its meaning):

  • the graph: B_deps, A_deps, D_deps, H_deps, C_deps, cells, controls, action_names, emissions, observes, black_box, and the sugar controlled and B_control_deps;

  • names: state_names, control_names, modality_names, dims;

  • planning and the objective: policy_len, planner, gamma, decomposition, epistemic, terms, scoring, branch_on, planning_belief, feedback, and sophisticated (the alternative syntax for branch_on and plan_learning);

  • inference: num_iters, mixture_k, mixture_schedule, plan_learning, recognition, external_inputs;

  • learning: readings, reduction_period, reduction_pairs;

  • provenance: subsystems.

A field written by name at construction (a dict) is stored as a tuple of pairs, because static fields must hash; dict(system.<field>) reads it back.

Design: docs/design/control-states.md C1, C4, C6, C11.

B_deps: tuple[tuple[int, ...], ...]#

One entry per node: the node indices each state factor’s transition conditions on (its state parents, read from the previous step, and its control parents). The length fixes the node count. A continuous state factor may name only earlier categorical state factors (never itself), since state factors are computed within a step in declaration order.

A_deps: tuple[tuple[int, ...], ...] = ()#

One entry per modality: the state factors it observes, by node index; the length fixes the modality count. Action node k is named as len(B_deps) + k.

planner: str = 'enumeration'#

The planner’s registry name: "enumeration", "cem", "gradient", "mixed", "habit" or "sophisticated". Resolved at call time; a face’s planner= argument overrides it.

gamma: float = 16.0#

The policy precision in q_pi ~ softmax(-gamma G + log E), read when SystemParams.precision is None.

num_iters: int = 16#

The number of mean-field fixed-point sweeps in infer_states.

decomposition: Literal['utility_infogain', 'risk_ambiguity'] = 'utility_infogain'#

Which decomposition of the expected free energy G the term tree carries: "utility_infogain" or "risk_ambiguity". The epistemic selector mounts each one’s own epistemic leaf (infogain or ambiguity) and never touches risk.

epistemic: bool | tuple[str, ...] = True#

The per-variable epistemic selector. True mounts every eligible variable, False or () none, and a tuple names the variables that carry an epistemic leaf: an infogain leaf under utility_infogain, an ambiguity leaf under risk_ambiguity (risk is never touched by the selector). The grammar, shared with learn’s rate keys (hybrid_aif.system.selectors):

<state>                a state variable, by bare state factor name ("pose_cell")
<state>:<dim>          one dimension of a continuous state factor ("pose:b1"),
                       named by ``dims`` or dim0, dim1, ... by position
obs:<modality>         an observation variable ("obs:cue")
<slot>:<name>          a declaration's parameter variables as a group, the slot
                       one of likelihood, transition, initial_state_prior
<slot>:<name>:<block>  one independent posterior block ("likelihood:pose:noise")

Any segment may be *, matching that whole segment (no partial globs): ("*",) is every state variable, ("*:*",) every parameter variable, ("obs:*",) every observation variable, ("pose:*",) every dimension of pose (the whole state factor). A wildcarded first segment ranges over the parameter slots only. Selection is a union. A wildcard never validates less than its literal part; only a class empty through its wildcarded segment resolves silently to nothing.

A state name mounts every modality that observes it, and a modality’s leaf is its information about the selected parents, the unselected ones marginalised (its ambiguity likewise); obs:<modality> scores the modality over all its parents. Dimension keys on one state factor select one sub-block: on a Gaussian-carried state factor each modality’s leaf is its information about those dimensions, the others marginalised, and under risk_ambiguity its ambiguity is E H[y | x_S]; a sub-block of a mixture-carried state factor raises. Selecting every dimension selects the state factor. A continuous state factor no modality observes has no information to gain: named literally it raises, and the drive toward a sharper belief about it is the uncertainty term.

mixture_k: int | None = None#

The shared Runnalls budget: the number of components every mixture-carried belief keeps. Required as soon as any state factor carries a MixtureGaussian.

mixture_schedule: Literal['runnalls', 'mode_aligned'] = 'runnalls'#

The mixture compression (the reduce half of grow and reduce): "runnalls", or "mode_aligned", which keeps each component owned by one mode (needed to filter a state factor whose transition switches).

plan_learning: bool | tuple[str, ...] = ()#

The learnable tables a plan reads as learned within the plan: carried through the planning scan as working counts, seeded from the posterior the plan starts from and absorbing each imagined step’s expected count statistic (the model’s joint over child and parents), so a later read of a row predicts through the counts the plan has imagined and its novelty declines (the Pólya urn). A tuple of keys in the grammar of learn’s rates: transition:<factor>, likelihood:<modality> (a ConditionalDirichlet, directly or as the reader of a parameter variable) and parameter:<name> (every reader of the variable); or True, every learnable table. Readers of one parameter variable learned within the plan share one working table. () (the default) reads every table frozen at its posterior mean within a plan, pymdp’s convention. An inference setting, as mixture_schedule is; carried on the hybrid and the fused all-tabular paths (on the fused path a branch_on branch absorbs its own outcome), refused on the amortized path. Design: docs/design/parameters-within-the-plan.md D1, D2, A3.

D_deps: tuple[tuple[int, ...], ...] | None = None#

Hierarchical conditional priors: the parent state factors of each state factor’s initial prior (None: all unconditional). Ancestral: parents must be earlier, of tabular families.

H_deps: tuple[tuple[int, ...], ...] | None = None#

The parent state factors of each state factor’s terminal_targets entry (None: all unconditional; see resolve_terminal_targets()). As D_deps, except that parents need not be declared earlier and a state factor may not parent its own terminal target.

C_deps: tuple[tuple[str, tuple[str, ...]], ...] = ()#

The parents of each conditional per-step target, by name: {"lane": ("u_option",), "cue": ("context",)} at construction, keyed by the targeted node (a state factor’s state_targets entry, a modality’s obs_targets entry), each parent a discrete control node or a categorical state factor; stored as (key, parents) pairs sorted by key. The target under a key is a ConditionalCategorical (child axis first, then one axis per parent in this order) or a ConditionalGaussian (loc (*levels, d), chol (*levels, d, d); control parents only). At each step of a plan the target is resolved under its parents, a clamped control node’s level selecting its own distribution and a state parent averaging mean-field, then scored as an unconditional target is. Design: step-durations.md T5.

cells: tuple[tuple[str, Grid], ...] = ()#

The grid of each continuous state factor that a tabular state factor reads as a parent, by name: {"x": Grid(...)} at construction, stored as (state factor, Grid) pairs in node order. A tabular state factor naming such a state factor in B_deps has a table parent axis of Grid.n_cells entries, the cell the parent’s belief falls in, flattened in C order. Design: terrain-field.md.

modality_names: tuple[str, ...] = None#

One name per modality, in modality order; None at construction fills in modality_{m}. These are the keys of SystemParams.likelihood, obs_targets and the term tree.

state_names: tuple[str, ...] = None#

One name per state factor, in node order; None at construction fills in factor_{i} for state factor i. With control_names and modality_names, the single source of names and order: keys in SystemParams, targets and rate maps refer to them and are validated at every face. No node is named after a reserved first segment of the key grammar (obs or a slot word).

control_names: tuple[str, ...] = None#

One name per control node, in controls order; None at construction fills in the sugar’s u_<f> per controlled state factor f (u_factor_{i} under generated state names) and is refused on a System that declares its control nodes natively (controls=), whose nodes need names of their own. Under the sugar, a given tuple must equal the generated one.

dims: tuple[tuple[str, tuple[str, ...]], ...] = ()#

Names for the dimensions of continuous state factors: {factor: (name, ...)} at construction ({"pose": ("x", "y", "yaw", "b1", "b2")}), stored as pairs in node order. epistemic selects a dimension as <factor>:<name>; a state factor declared without names has dim0, dim1, … by position, which change meaning when the state is reordered. Names are unique within a state factor, one per dimension, single key segments (no :, ., * or brackets), and dimN may name position N only.

recognition: tuple[Recognition, ...] | None = None#

The structural half of the recognition slot: which variables an amortized module infers and what each conditions on (Recognition); None or (): none. The modules live in SystemParams.recognition.

terms: tuple[str, ...] = ()#

The term selector: which estimator-registry terms G carries beyond the infogain terms epistemic selects (ROWS). Never inferred from SystemParams.scoring, so the term tree’s shape is a function of the System. The grammar is the term name, optionally applied to an epistemic variable key:

<term>                   a term with no target ("g_tail", or a term scoring the
                         whole rollout against a model of its own)
<term>:<slot>:<name>     a term on a declared kernel ("occupancy:transition:stoch")
<term>:obs:<modality>    a term on an observation modality
                         ("predicted_reward:obs:reward")
<term>:<state>           a term on a state variable ("uncertainty:pose")
<term>:<state>:<dim>     a term on dimensions of a continuous state variable
                         ("uncertainty:pose:b1"; keys on one state factor are one
                         sub-block, as under epistemic)

The term segment is always literal; the variable part may wildcard where the term declares a target class ("occupancy:transition:*"). Selection is a union. A term mounts on a target only if the registry has an estimator for that variable’s family.

scoring: tuple[tuple[str, object], ...] = ()#

The structural half of the scoring slot, keyed by term name (the parameters live in SystemParams.scoring): for example a term’s preference model that is itself a declared System; dict(system.scoring) reads it. terms does the mounting: an entry whose term it does not mount raises.

external_inputs: tuple[tuple[str, int], ...] = ()#

(name, width) vectors that a recognition module may condition on but this System does not declare, spelled "external:<name>" in a Recognition parent set and supplied per call (infer_states(externals={...})); the width lets parent_dims validate statically.

subsystems: tuple[tuple[str, Subsystem], ...] | None = None#

(name, Subsystem) pairs recording which state factors, modalities and control nodes came from which component of a merge() call (None for a hand-declared System); dict(system.subsystems) reads it. No face computes from it; a refusal reads it to name what a node a binding removed became.

branch_on: tuple[str, ...] = ()#

The observation modalities, by name, whose outcomes the "sophisticated" planner branches on (hybrid_aif.planning.sophisticated): each categorical, over categorical parents only. Empty for every other planner, which never reads it.

sophisticated: tuple[str, ...] | None = None#

The alternative syntax for the two halves of sophisticated planning, in epistemic’s selector grammar: "obs:<modality>" branches the plan on that modality’s outcomes (the state half, branch_on), and "transition:<factor>", "likelihood:<modality>" and "parameter:<name>" carry that table’s counts within the plan (the parameter half, plan_learning). sophisticated=("obs:fix", "transition:terrain") is exactly branch_on=("fix",), plan_learning=("transition:terrain",). The two fields are the canonical form: construction lowers this tuple into them, every face reads them, and a description writes them alone; this field keeps what was written. A tuple of literal keys (plan_learning=True carries every table); declaring it beside a branch_on or plan_learning of one’s own is refused. None (the default): not used. Design: docs/design/parameters-within-the-plan.md A1.

planning_belief: Literal['prior', 'posterior'] = 'prior'#

Which belief a plan’s information-gain leaves read on a Gaussian-carried state factor: "prior", the predictive belief (predict only); "posterior", a second chain that conditions on the observations expected along the plan, so a linear-Gaussian modality’s leaf is the gain of its observation given the plan’s earlier ones. Every other leaf reads the predictive belief, except a Gaussian target under feedback. Design: planning-with-observations.md D1, D2; closed-loop-planning.md.

feedback: Literal['linear_quadratic'] | None = None#

How a plan’s Gaussian targets are scored. None: open loop, on the predictive belief. "linear_quadratic": closed loop, as the policy that follows the plan and corrects deviations from it by the linear-quadratic regulator’s feedback on the estimate. Each Gaussian state, terminal and linear-Gaussian observation target on a Gaussian-carried state factor is then scored by its cross-entropy on the closed-loop state distribution (the epistemic chain’s posterior plus the estimate spread the corrections leave), and a Gaussian target on a continuous control node also charges the corrections. Requires planning_belief="posterior". Design: closed-loop-planning.md.

observes: tuple[tuple[str, str], ...] = ()#

Which variable each slot observes: (slot, variable) pairs, given as {"cell_obs": "cell"} at construction. A slot is a modality or a control node; a variable is an action node or an emission of this System (the variables it generates), and the slot’s port type must equal the variable’s. A control node named as a slot is driven: the variable’s realised value is its level, its action_names entry is None, and no planner chooses it. A slot the map does not name observes the variable of its own name, so it is an in-port of the System (ports()).

The datum of an observed variable is an observation like any other: the caller supplies it, keyed by the variable (infer_states() fans it out to every slot observing it), and replay and run realise the emissions after a round and feed them back as the next round’s observation. An own-belief read: emissions={"cell": Emission(("x",), realise="mode", kernel=GRID)}, observes={"cell_obs": "cell"}. The variable set (state factors, control nodes, action nodes, emissions and the slots observes does not name) is derived from the declarations, never stored. Design: engine-consolidation.md; structure-learning.md S8; nesting-and-coupling.md N3.

emissions: tuple[tuple[str, Emission], ...] = ()#

The outputs the System draws from its state factors, by name: {"fix": ("x",), "img": Emission(("x", "terrain"), realise="mode")} at construction (a tuple of parents is a draw), stored as (name, Emission) pairs in the order given (the order fixes the key each emission draws with). An emission is the action node of a state factor: its parents are state factors and control nodes (a control parent reads the node’s realised level), its kernel is SystemParams.emission[name] or the static identity or Grid kernel its declaration names, and its port type is read off that kernel.

An emission has no node index: nothing in the model reads or scores it, so no A_deps, target, C_deps, H_deps, epistemic key, branch_on or readings entry may name it. A modality may observe it (observes), which is the only way the model reads it. Design: nesting-and-coupling.md N5.

readings: tuple[tuple[str, str], ...] = ()#

(state factor or modality, control node) pairs: the named learnable table’s one reading at a step pools SystemParams.readings[name][level] fast readings, the level being the control node’s at that step, and its novelty term is scaled by that count. A table not named pools one. Design: step-durations.md T10.

reduction_period: int | None = None#

The schedule of Bayesian model reduction on the growable state factors: every reduction_period-th call of learn runs reduce() on each of them, the counter carried in LearnState.moments; None leaves reduction to explicit calls. Design: structure-learning.md S4.

reduction_pairs: int = 8#

How many candidate pairs a reduction tests, chosen greedily as the best-scoring by mutual expected log-likelihood.

controls: tuple[int, ...] = ()#

The control nodes, by node index, ascending: the nodes the System sets by decision rather than by inference. They follow every state factor; each is read by a transition or sized by another declaration that names it (a target, a modality, durations). A control node has no parents, initial prior or terminal target of its own. A policy carries one column per control node, in this order.

action_names: tuple[str, ...] = None#

One action node per control node, in controls order: the node through which the decision leaves the System, a child of its control node (kernel P(a | u), a delta unless SystemParams.actuator declares one). Declared with the control nodes, as modality_names with A_deps, paired with them by position, both names free; the sugar’s pair for state factor f is u_<f> and a_<f>. The entry is None for a driven control node (an input, driven from outside through observes: nothing chooses it, so nothing realises it). Action nodes follow the control nodes in node order, so A_deps names action node k as len(B_deps) + k.

black_box: tuple[tuple[str, tuple[str, int]], ...] = ()#

The ports of a black box (an external process declared by its ports alone), by name: {"v": (FLOAT, 2), "gauge": (LEVEL, 4)} at construction, stored as (port, (kind, size)) pairs in the order given. An in-port is a control node no declaration reads and no action node realises (a link into it drives it); an out-port is an emission with no parents whose kernel is "black_box". Nothing between them is stated, so no face that needs the inside (inference, planning, learning, sampling, as_env, mirror, joint_planner) runs on a System that holds one, and its step under run is a custom one. A splice carries each component’s entries under its prefix. Built by black_box(); docs/composing-systems.md, “External processes”.

policy_len: int#

The planning horizon: the number of steps in a policy (for the enumeration planner, the policy length).

property controlled#

Sugar: per state factor, whether it gets a control node u_<f> (with action node a_<f>).

property B_control_deps#

Sugar: per state factor, the controlled state factors whose nodes slice its transition, in axis order (None: each controlled state factor reads its own node alone). Design: docs/design/control-states.md (Timing; C6).

property node_names: tuple[str, ...]#

Every node’s name in node order: state_names, then control_names. The index-based fields (B_deps, A_deps, D_deps, H_deps, controls) index into this tuple.

action_dim(params)[source]#

Width of the flat continuous action vector, or None unless every control node is continuous (its box in params.control).

elapsed(action, params)[source]#

The duration of a realised round: the entry of params.durations at the level of the realised action of the node that carries it (1.0 when no durations are declared).

action is keyed by action node, as the environment returns it and act() emits it; under a stochastic actuator it is the realised level, not the decided one, that is looked up. Array in, array out: works under jit. Design: step-durations.md T8.

ports(params)[source]#

The System’s ports with their types, by name.

ins are the in-ports: each modality, typed by its likelihood, and each control node under its own name (a node the System chooses is listed as well, since a link into it makes it driven), typed (LEVEL, levels) or (FLOAT, width), except the slots System.observes names: a slot that observes a variable of the System is no in-port, since the System feeds it. A control node nothing drives is listed even where its own planner chooses it, since it can be driven, so empty ins is not what closedness means: that is a property of the modalities alone. outs are the out-ports: each action node, typed as its control node, and each emission, typed by its kernel (the identity’s is its parent’s, a Grid’s is a level per cell). A type is (LEVEL, levels) for a table and (FLOAT, dimension) for a linear-Gaussian or neural kernel. There is no node index for a port: a port is its name.

property names: Names#

A read-only view of the System’s names, every tuple in node-index order.

names.states are the state factors’ names (the belief keys, state_names), names.controls the control nodes’ (control_names); names.modalities is modality_names; names.actions the action nodes’ (the action keys), one per control node in the same order, from action_names. Node-index order is the order of every positional structure (tables, policy columns, what the converters produce); iterating a mapping gives no such guarantee, so take order from names.

beliefs_from_states(params, states)[source]#

An amortized model’s filter states as the beliefs the faces take, keyed by state factor.

states is an RSSMState (e.g. posterior_states()): the carry’s vector and the code’s tensor, by state factor name, leading batch and time axes passing through (flatten them for imagine()’s (N, ...) start beliefs).

to_positional(kind, keyed_value, params=None)[source]#

A name-keyed value as the positional form the internals use.

kind and what comes back: "beliefs" → a tuple of the state factors’ beliefs, in state factor order (a control node’s entry is left out); "observations" → a tuple in modality order (a complete present mapping converts as observations); "actions" (keyed by action node) → an int32 (..., K) level array, one column per action node in node order, the flat float (..., action_dim) vector when every node is continuous, or a ControlStep (one entry per node) over a mixed space; "detail" → an InferenceDetail with tuple fields; "params" → a SystemParams (or environment params) with tuple containers. Missing or unknown keys raise. params (keyed) is needed to convert a continuous node’s value, whose box lives in params.control. See hybrid_aif.system.keyed.

from_positional(kind, positional, params=None)[source]#

Positional data as the name-keyed form every face takes (inverse of to_positional()).

kind and what comes back: "beliefs" / "observations" (a tuple in node order) → a dict by state factor / modality name; "actions" (an (..., K) level array, one column per action node, the flat continuous vector, or a mixed space’s ControlStep) → a dict by action-node name; "detail" (an InferenceDetail with tuple fields) → the same record with dict fields; "params" (a SystemParams or environment params with tuple containers) → the same object with dict containers. params (keyed) is needed to convert a continuous node’s value, whose box lives in params.control. For params with parameter variables, the positional form holds a variable’s table at every reader’s position; a reader position that differs from the variable’s entry raises, and the edit is made at parameters[<name>] in the keyed form. That check compares concrete arrays only: under jit the arrays are traced and it cannot run, so an edit made at a reader position is not detected there.

resolve_terminal_targets(params, final_beliefs)[source]#

The effective terminal designations at final_beliefs, with H_deps resolved.

A terminal target is h, the prior over intended final states, reciprocal to the initial prior d. An H_deps entry makes it a ConditionalCategorical over the designated state factor, conditional on parent state factors (under merge possibly a higher System’s). It resolves mean-field, as D_deps does in initial_priors() — Σ_parents h(· | parents) q(parents) — with q(parents) read from the final predicted beliefs of the rollout being scored, so a parent the plan can steer makes the target plan-dependent. Learnable and continuous conditional targets raise.

Design: docs/design/nesting-systems.md N1.

compiled(*, watch=True)[source]#

This System’s faces compiled once, behind input canonicalisation.

Returns a CompiledSystem with the same face methods as the System. watch=False turns off the retrace warning.

initial_priors(params)[source]#

Ancestral mean-field marginals of the initial priors, D_deps resolved, by state factor.

A conditional prior is averaged over its parents’ resolved marginals in declaration order, unconditional priors pass through, and a learnable prior contributes its posterior-mean point(). infer_states uses this when priors=None; planning faces take it in place of a raw conditional D. On the amortized path it returns the episode-start values: each carry’s learned initial value, and each code’s transition read at it.

as_env(params, param_key=None)[source]#

The same tensors run forward: (env, env_params).

env is a GenerativeEnv (observations by modality name, states by state factor name, actions by action-node name) over the discrete process (probability tables) for an all-tabular System, the hybrid one (the declarations themselves) otherwise; env_params keys its containers by name and carries params.actuator, from which the env realises each action it is given. Learnable slots are lowered to their posterior mean, or with param_key to one sample each, so the env is a draw from the model’s own parameter prior. Raises on the amortized path. It is mirror() (each modality an emission), lowered, run forward by the positional process, with the env’s faces keyed by this System’s names; a System that declares emissions has no such mirror and is refused.

sample_initial(key, params, state=None)[source]#

Draw an initial state (or take state, one point per state factor) and the emissions of it: (emitted, state), both keyed by name. The forward process’s reset, over the emissions in place of modalities, each emission realised by its declared rule; a control node an emission reads is at level 0 (the zero vector when continuous).

sample_step(key, params, state, inputs=None, states=None)[source]#

One round forward from state: (emitted, next state), keyed by name.

inputs gives the value of each control node an input drives (a level, or a float vector); a control node it does not name is free and is drawn first with fold_in(key, CONTROL_TAG) (_free_controls()), so the key stream of the process itself is the one it has when every node is driven. states names the state factors to step; the others keep their values. Every emission is realised by its declared rule. For mirror(s, p) of a System s with no actuator kernel and every control node driven, the emissions and the state equal s.as_env(p).step under the same key.

emit(key, params, values)[source]#

Realise every emission from values, keyed by emission name in declaration order.

values holds each parent of an emission by name: a state factor as a point (a level, or a float vector: a world’s state) or as a belief (an agent’s posterior), a control node as its realised level. Each emission is realised by its own rule (Emission.realise) with jax.random.split(key, E)[e] for emission e of the E emissions that have a kernel in params.emission (the others draw from split(key, E')[e] over all E'). From points, sample conditions the kernel on the parents and draws (the draw the forward process makes of an observation), mode is the most probable level or the mean, stats the probability vector or the (mean, covariance). From beliefs, sample draws the parents and then the kernel (an exact predictive draw), and mode and stats are those of the predictive distribution (hybrid_aif.system.emissions). Learnable kernels act at their posterior mean. A static kernel realises its parent directly: the identity gives the state factor’s level, probability vector or location, and a Grid gives the cell a point falls in, or from a belief the cell index by sample and mode and the cell mass by stats. Nothing in inference or planning reads an emission; a modality observes one through System.observes, its datum then supplied to the faces.

infer_states(
params,
observations,
priors=None,
detail=False,
externals=None,
present=None,
support_floor=-27.631021115928547,
key=None,
)[source]#

Mean-field state posteriors for one tick’s observations: (beliefs, detail).

observations is keyed by modality name, one entry per modality: an int32 level, a one-hot or a probability vector over the levels (a soft observation: the expected log-likelihood under the vector) for a categorical modality, a float array for an LG one. Design: nesting-and-coupling.md N8. priors and the returned beliefs are keyed by state factor name; priors=None uses initial_priors(). A discrete control node’s entry is optional in priors and always returned: no inference runs on it, so it passes through (its uniform prior when absent). An action node a modality observes (A_deps naming it) is inferred like a state factor on the tabular path: its entry in priors is its prior (uniform when absent), and its posterior is returned under its name. With detail=True (a static bool) the second slot is an InferenceDetail (pre-reduction switching mixtures, per-mode and total log-evidence keyed by modality name; unsupported keyed by state factor name), else None; the beliefs are identical either way.

present says which modalities are observed this tick, a flag per modality keyed by name: a modality it leaves out is present, None means all are, and an unknown key raises. An absent modality is not clamped: its value is ignored and its state factors keep what the other modalities leave them; all absent is a predict-only tick. A traced flag computes the update and selects against it (its detail entries report the hypothetical update, log_evidence zeroed); a Python False skips it statically. On the amortized path the modalities the recognition modules read are present or absent together: static flags splitting them raise, traced ones reduce with all (absent).

detail.unsupported flags each categorical state factor none of whose levels explains this tick’s tabular evidence, as hybrid_aif.inference.discrete.unsupported() defines it against support_floor; the posterior is left as computed.

Hybrid Systems run one structured sweep in declaration order: the discrete FPI over the categorical sub-model; exact LG condition per LG modality, sequential in modality order; exact Gaussian-sum conditioning for a mixture-carried state factor, with a mode-parent evidence message under mixture_schedule="mode_aligned"; and grow-then-reduce conditioning for a switching LG modality (categorical mode parents after the observed state factor in A_deps), under either schedule. A modality that observes a mixture-carried state factor directly (one whose transition switches) raises under "runnalls" and needs "mode_aligned"; non-LG likelihoods on continuous state factors raise.

On the amortized path this runs the recognition modules in order (hybrid_aif.inference.amortized.recognize()): the value None is allowed for a modality no module reads (its key is still present), externals supplies "external:<name>" parents, and detail is None.

With key the posterior is collapsed onto one draw, as a belief of its own family (one-particle filtering; amortized carries pass through; on a predict-only tick it is the prior that collapses). See docs/composing-systems.md.

observations and present are keyed by variable: a modality that System.observes names takes the datum of the variable it observes (an emission or an action node of this System), and one datum feeds every slot observing the variable; a key naming a slot the map renames is refused, naming the variable. The datum of an observed variable is optional: a slot whose variable is left out, or None, is absent that tick (the first tick of an own-belief read has none). Design: nesting-and-coupling.md N3.

learn(
params,
observations,
beliefs,
prev_beliefs=None,
action=None,
lr=1.0,
decay=1.0,
lr_by_slot=None,
decay_by_slot=None,
detail=None,
learn_state=None,
prior=None,
priors=None,
externals=None,
)[source]#

One tick’s parameter update: every learnable slot absorbs this tick’s statistic.

A slot holding a distribution over its parameters absorbs its conjugate sufficient statistic; point-valued slots are not learnable. A non-frozen MLPConditional takes an optax step on its negative log-density at point evidence from the beliefs (posterior means, probability vectors for discrete variables, a one-hot action). A transition net’s parents are its state factor’s previous value then the action one-hot if controlled; a likelihood net’s are the A_deps state factors in order.

A non-frozen MLPConditional likelihood takes the gradient of the free energy infer_states(detail=True) reports for the tick: the inference pass is re-run from priors, the prior beliefs infer_states was given (keyed by state factor name), with every other input held fixed, and differentiated in the decoder. Without priors they are the prediction from prev_beliefs and action when prev_beliefs is given, else the initial priors. externals is the mapping infer_states took for a recognition entry’s external parents. A modality a recognition entry covers contributes its expected negative log-likelihood under the final belief, as infer_states records it.

A parameter variable several state factors read (SystemParams.parameters) absorbs the sum of its readers’ statistics once, at the rate lr_by_slot["parameter:<name>"] (default lr). A reader’s own key ("transition:<factor>", "likelihood:<modality>") takes only a static 0.0, which keeps that reader’s statistic out of the variable; any other value raises, naming the variable’s key. A reader with no observed child counts its predictive belief like any state factor does, which is why this exclusion exists: a scheduler that reads a table it never observes would otherwise add its own predictions to the counts. A literal key outranks a pattern, for readers as for rates: a pattern ("transition:*", "*:*") at 0.0 excludes the referencing readers it matches only while the variable’s own rate is not named literally, so {"*:*": 0.0, "parameter:T": 1.0} learns T from all its readers and {"*:*": 0.0} freezes everything; a literal 0.0 on a reader excludes it either way. A nonzero value from a pattern with a literal slot raises on a referencing reader, and a fully wildcarded nonzero pattern reaches the variable through parameter:* instead.

observations is keyed by modality name, beliefs and prev_beliefs by state factor name, action by action-node name (as act() returns it). action is a_{t-1}, the action that produced this tick’s observations; each control node is clamped to its value. prev_beliefs and action are required exactly when a learnable transition has a nonzero-or-traced rate (action only if that state factor is controlled). detail is the keyed InferenceDetail infer_states(detail=True) returned.

Returns bare params for a conjugate-only model, (params, learn_state) when the model has a gradient slot or learn_state is passed. Start the carry with learn_state=system.init_learn_state(params); None with gradient slots present raises. Raises on the amortized path (train that with hybrid_aif.train.world.fit_world()).

Rates. lr applies to every learnable slot; lr_by_slot overrides it by slot-qualified key ("likelihood:<modality>", "transition:<factor>", "initial_state_prior:<factor>"); decay/decay_by_slot use the same keys. A third segment addresses one independent posterior block ("likelihood:pose:noise" / "…:head"; the joint LinearGaussianObservationMNIW has none, and its sub-block keys raise). Any segment may be *; the most specific match (most literal segments) wins, and equal-specificity matches on one variable raise:

decay_by_slot={"*:*": 0.999, "likelihood:pose": 0.97}
lr_by_slot={"likelihood:pose": 0.0, "likelihood:pose:noise": 1.0}  # head frozen

A static Python 0.0 skips the slot at trace time, decay included; a traced rate multiplies the statistic (jnp.where(t < 1000, 1.0, 0.0)). jnp.float32(0.0) is traced, and a frozen slot that should still drift under decay needs a traced zero. State and obs: keys are not rate-addressable and raise.

Decay is α ← decay·α + (1−decay)·anchor + lr·stats, anchored at the declaration’s own anchor (its prior, a uniform table, or an array it was built with); decay == 1.0 is exact conjugacy and reads no anchor; any other decay, traced included, raises on a declaration without one and on a neural slot.

Timing. The transition statistic is the product of filtered marginals (an approximation). At tick 0 pass a dummy prev_beliefs with a traced zero rate; gate initial-prior rates to tick 0, since they accumulate once per episode. learn is unbatched; lift it with vmap.

Growth. A growable state factor (a memoryless state factor whose weights carry a growth propensity) runs its growth step first: the tick’s data scored under every level, the first dead level woken when the best live level explains them worse than the prior does by the propensity’s margin, the woken level taking the datum hard and seeded from it by the ordinary update. Every reduction_period-th call then reduces each growable state factor (reduce()), which needs prior, the model’s prior params (the statistics a merge pools are the posterior’s beyond them, and a killed level returns to them), and a learn_state carrying the counter (init_learn_state()). Both move with the weights: a tick where no modality over the state factor is present grows nothing, and the weights’ rate (transition:<factor>) gates growth and reduction, a static zero freezing the state factor’s structure and a traced zero skipping it at run time.

observations is keyed by variable, as infer_states() takes it: the datum of an emission or action node a modality observes (System.observes) is the one the caller supplied to infer_states, and a slot whose datum is absent teaches its likelihood slot nothing that tick. Design: nesting-and-coupling.md N3.

Design: docs/design/parameter-learning.md D1 D3 D4 D5 D7 D8; docs/design/per-variable-infogain.md V1 V7; docs/design/amortization.md A2; docs/design/structure-learning.md S3 S4.

carry(fresh, learned, slots=None)[source]#

fresh with the posteriors learning put into learned carried over: for an agent that rebuilds its params every step and must keep what it has learned. A block is one posterior learn() updates (a Dirichlet or conditional Dirichlet, a matrix-normal inverse-Wishart emission, a linear-Gaussian observation’s learnable noise, a trainable neural conditional), carried whole, its anchors and growth propensity included. Every block is carried when slots is None, else the ones the keys name: "likelihood:<modality>", "transition:<factor>", "initial_state_prior:<factor>", "parameter:<name>" (a named parameter variable, the one block of every state factor and modality that reads it) or "likelihood:<modality>:noise", without wildcards (under jit, pass slots as a static argument). Everything else comes from fresh: point values, and a separate MatrixNormal head, which learn does not update. A block whose family, shape or dtype differs between the two raises, as do a selected slot that holds a posterior on one side only, a key that names no posterior, and a selection that would split a growable state factor’s blocks, which growth and reduction keep in step. Trainable slots that learn does not train (a recognition model, a scoring row, a policy module) are not carried; a gradient slot’s optimizer state is the LearnState the agent already carries.

The carry is exact when what was learned means the same thing in the rebuilt params, as counts over the same levels do. A posterior over a parameter the rebuild re-expresses (a head in a frame that moves with the agent) is carried in its old expression, and is then wrong.

Design: docs/design/parameter-learning.md D9

reduce(params, prior, state=None, n_pair=None)[source]#

Bayesian model reduction on the growable state factor state names, or on every one when state is None: two live levels are merged when the evidence of their pooled statistics, in every slot the state factor is an axis of, is no lower than that of the separate levels. The merged level keeps its own prior once and both levels’ data; the other returns to dead, its weight zero and its emissions at their prior. Candidate pairs are the n_pair (default reduction_pairs) best by mutual expected log-likelihood, tested greedily. prior is the params the posterior was learned from, which the evidence is relative to. learn runs this every reduction_period-th call.

Design: docs/design/structure-learning.md S4

grow(params, observations, state, rounds=1, lr=1.0)[source]#

The batch form of growth on the growable state factor state names: observations holds a window of N data, (N, …) per modality over the state factor alone. Each of rounds rounds scores every datum under every level, takes the worst-explained one and wakes the first dead level for it while it falls below the growth threshold, seeding the level from that datum; the window is then absorbed at rate lr under the responsibilities the woken levels leave, into the state factor’s weights and its modalities. learn is this with one datum and one round.

Design: docs/design/structure-learning.md S3

init_learn_state(params)[source]#

A fresh LearnState for every gradient-learnable part of this agent.

One opt_states entry per gradient-learnable slot regardless of rate, plus scoring:<row> for each mounted row with a trainer and ACTOR_KEY for a policy module in policy_prior. A scoring entry’s shape is the row’s own (a row that owns a declared System carries a nested LearnState over its slots). moments is seeded with every running statistic a mounted row’s trainer carries (scoring_moments()), so the carry’s structure is complete at init.

log_evidence(prior, posterior)[source]#

Every slot’s parameter evidence: the closed-form log marginal likelihood of the statistics posterior absorbed from prior, keyed as learn() keys its rates (the per-tick data evidence of a filtering step is InferenceDetail.log_evidence, a different quantity). A slot with no closed form is unscored (nats None, exact False); a conjugate slot that absorbed no mass is unscored with exact True and its count. Eager, not for a jitted body. See hybrid_aif.learning.evidence.log_evidence().

policies(params)[source]#

The enumerated policy set, int32 (P, policy_len, K): one column per control node, in node order, over each node’s levels (read off the tables at trace time), ordered as pymdp orders its policies (time-major, the last column at the last step fastest).

Discrete control nodes only: raises under continuous ones. Under the sophisticated planner it is the first step’s control assignments.

planner_context(
params,
beliefs,
key=None,
aux_beliefs=None,
scoring_key=None,
horizon=None,
present=None,
)[source]#

Build the per-call context a planner runs against (never stored).

beliefs is keyed by state factor name and must be marginals: resolve a conditional or learnable D with initial_priors() first (a control node’s entry is ignored). The context itself is positional (init_beliefs in state factor order, actions and policies with one column per control node), as planners index it. horizon is the plan length the planner plans to and the closures are built for (None: policy_len). key is the plan key a stochastic planner (CEM) reads; scoring_key is the scoring rows’ own key, under which a row that rolls a model of its own takes the sampled rollout (only score_policies() passes one). aux_beliefs is keyed by scoring-row name; each value is the belief carry of that row’s own model, keyed by the nested System’s state factor names (amortized path only).

All-tabular Systems get the compiled prob-space closures (hybrid_aif.objectives.compiled, beliefs as probability vectors); any other declaration gets the family-dispatched closures of hybrid_aif.objectives.hybrid (beliefs as distributions, mixtures padded to mixture_k); the amortized path is _amortized_context(). _term_targets() decides which variables carry which epistemic leaf. When a step term reads the previous step’s beliefs, the closures carry (qs, qs_prev) pairs (_carry_prev()). Tables are rebuilt per call, so a context cached across learning ticks goes stale.

present says which modalities the plan observes, keyed by name: a bool for the whole plan, a (horizon,) bool array, or a one-key mapping from a discrete control node’s name to a bool per level, read at each step’s level of the node; a modality left out is present. An absent modality’s leaves are zero at that step on every path.

infer_policies(
params,
beliefs,
planner=None,
use_bound='midpoint',
metrics=True,
plan_key=None,
legal=None,
present=None,
return_policies=False,
)[source]#

Policy posterior and the EFE term tree: (q_pi, tree), or (q_pi, tree, policies) with return_policies, the planner’s clamped policy set as a ControlStep with one entry per control node and leading axes (P, policy_len), in the order q_pi and the tree’s leaves follow.

planner is a callable, or None for the System’s registry planner. metrics=False skips the tree (None); the posterior is the same up to float reassociation. A planner that selects without building a tree ("habit") returns {}; score_policies() gives the tree G would assign its plan. plan_key is required by, and only by, a stochastic planner ("cem"). legal is the hard constraint of act(), keyed by control node or one bool per policy. beliefs is keyed by state factor name. The planner must return clamped (integer) policies: a belief-valued policy set raises. present says which modalities the plan expects to observe at each step, keyed by name: a bool for the whole plan, a per-step bool array ((policy_len,), or (horizon,) under horizon=), or a one-key mapping from a discrete control node’s name to a bool per level ({"answer": {"u_option": (False, True)}}), read at each step’s level of the node; a modality left out is present throughout. An absent modality’s leaves are zero at that step, and under planning_belief="posterior" the epistemic chain is not conditioned on it there.

score_policies(params, beliefs, policies, aux_beliefs=None, key=None)[source]#

The EFE term tree for a given policy set, without a planner.

policies is int32 (P, H, K), one column per control node in node order (as policies() gives them), or one (H, K) policy whose per-policy axis is then squeezed from every leaf. Over an all-continuous action space it takes float (P, H, action_dim) or (H, action_dim). Fold the tree with total() for per-policy G. Scoring a habit planner’s plan here reads the G it would get (hybrid_aif.planning.habit).

A policy may instead be a mapping keyed by control-node name, one entry per node. A discrete node’s entry is its levels as an int (P, H) (or (H,)) array, a clamp, or a Categorical over its levels with batch shape (P, H) (or (H,)), a belief. A continuous node’s entry is its values as a float (P, H, d) (or (H, d)) array, a clamp, or a Gaussian / TruncatedGaussian over them with batch shape (P, H) (or (H,)), a belief. A mapping is how a space mixing discrete and continuous nodes is scored. The type of each entry selects, statically, how its node is read: a level indexes the tables, a belief mixes them, a continuous value enters a linear-Gaussian state factor’s G u as an offset and a Gaussian belief over it pushes through exactly (a truncated one by its closed moments), a nonlinear state factor’s map reads a value as an input and a belief through its moments, and every leaf is computed under the result. The tree is then the objective of committing to the randomised policy that draws each node’s level from its belief, step by step: a term linear in the control (utility, ambiguity, the predicted state) is the mixture of its clamped values, a nonlinear one (risk, info gain) is not. Under a belief, transition novelty is the mean-field mixture (the novelty weights averaged over q(u), contracted with the mixed prediction) and occupancy is the entropy of the mixed transition, H[Σ_u q(u) B_u]. That is a different quantity from the expected objective under a policy posterior q_pi over clamped policies, which is the q_pi-weighted total of the clamped tree. A one-hot belief scores as its clamp; an all-clamp mapping is the positional policy. A belief on a discrete node is read by categorical (tabular) transitions; a continuous state factor reading a belief-valued discrete node raises, as does a neural transition reading a belief-valued continuous one.

A state_targets entry on a control node scores it: a risk leaf keyed by the node’s name, −log C(u) under a clamp and KL(q(u) ‖ C) under a belief, at every step; a terminal_targets entry scores the last step as terminal_risk.

beliefs is keyed by state factor name. In either form the plan’s length H need not be policy_len: the scoring rows are built for the plan’s own horizon. aux_beliefs passes to planner_context(). key is the scoring rows’ key: rows that roll a model of their own take the sampled rollout under it, the expected one without.

act(
key,
params,
beliefs,
selection='stochastic',
alpha=None,
mode=None,
planner=None,
use_bound='midpoint',
metrics=True,
plan_key=None,
legal=None,
)[source]#

Infer policies and emit an action: (action, q_pi, metrics).

beliefs is keyed by state factor name; the action by action-node name, one entry per action node, the intended value of its control node (a level, or a continuous node’s float value): a draw (or the mode) from each control node’s posterior, sampled over the policy set the planner returned. key selects the action, plan_key drives a stochastic planner; metrics as in infer_policies(). mode=None takes the first-step action marginals for discrete controls and the drawn policy’s first step for continuous ones, where mode="marginal" raises. A planner that emits a posterior over a continuous plan (the gradient planner under posterior="laplace", a truncated Gaussian on the box) has the action drawn from that posterior’s first step under selection="stochastic", and its mode under "deterministic". selection is the action’s realisation: "stochastic" corresponds to the realisation sample (a draw) and "deterministic" to mode (the argmax, or the mean of a continuous belief); a mixed strategy (stats) is not emitted here. Design: nesting-and-coupling.md N3. legal is this tick’s hard constraint: a mapping keyed by control-node name, each entry a boolean mask over that node’s levels ((levels,) for the first step, (policy_len, levels) per step; a node left out is unrestricted, an unknown key raises), or one bool per policy of the planner’s set. An illegal level gets exactly zero mass in q_pi and the marginals. It is separate from policy_prior, the soft prior. The planner must return clamped policies (integer levels, or a mixed space’s ControlStep of clamps, from which the action is drawn as one policy’s first step): a belief-valued policy set raises.

Design: docs/design/action-legality.md.

action_marginals(params, q_pi, policies=None)[source]#

First-step marginal posterior over each control node’s levels, by control-node name: the posterior an action is drawn from.

policies is the positional policy set q_pi is over (None: policies()); the level counts come from params’ tables. Discrete controls only.

predict_beliefs(params, beliefs, policy, key=None)[source]#

Open-loop prediction: the beliefs, keyed by state factor name, after each step of one policy.

policy stays positional: int32 (horizon, K), one column per control node, or float (horizon, action_dim) over an all-continuous action space; step t of the result follows policy[t], through the transition update_empirical_prior() uses (no observations enter); an action node a modality observes carries its prediction at each step, as update_empirical_prior() gives it. key selects the sampled rollout, split once per step; None is the expected one.

update_empirical_prior(params, beliefs, action, key=None)[source]#

Next tick’s state priors: beliefs pushed through action, keyed by state factor name.

action is keyed by action-node name as act() returns it ({} when nothing is controlled): a level per discrete node, a float vector per continuous one, the two kinds side by side over a mixed space. Each control node is clamped to its action’s value at this step (an efference copy): each discrete node’s returned entry is its prior for the next step, uniform over its levels. An action node a modality observes gets an entry too, the agent’s prediction of its action: the column of params.actuator at the clamped level, the one-hot of that level under the delta kernel. A continuous node enters a linear-Gaussian state factor as the G u offset, a neural one as part of its input, a nonlinear one as an entry of its map’s controls. Hybrid state factors go through their own transitions (exact Gaussian predict; grow then reduce(mixture_k) for mode-coupled state factors), the closure the planner uses for one step. On the amortized path each carry advances, then each code is read off its transition at this step’s parents.

Without key the result is the expected belief. With one it is the sampled belief: one draw per state factor as a belief of its family (hybrid_aif.inference.sample). That is a legal carry but a point mass: a collapsed Gaussian or mixture cannot be conditioned and has no finite entropy. See docs/composing-systems.md.

__init__(
B_deps,
A_deps=(),
planner='enumeration',
gamma=16.0,
num_iters=16,
decomposition='utility_infogain',
epistemic=True,
mixture_k=None,
mixture_schedule='runnalls',
plan_learning=(),
D_deps=None,
H_deps=None,
C_deps=(),
cells=(),
modality_names=None,
state_names=None,
control_names=None,
dims=(),
recognition=None,
terms=(),
scoring=(),
external_inputs=(),
subsystems=None,
branch_on=(),
sophisticated=None,
planning_belief='prior',
feedback=None,
observes=(),
emissions=(),
readings=(),
reduction_period=None,
reduction_pairs=8,
controls=(),
action_names=None,
black_box=(),
*,
policy_len,
controlled=None,
B_control_deps=None,
)#