System#
- class hybrid_aif.System[source]#
Bases:
ModuleStatic 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 (controlsgives their node indices).state_namesnames the state factors andcontrol_namesthe control nodes;node_namesis the two in node order.B_deps,D_depsandH_depshave one entry per node;A_depshas 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.epistemicnames 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
controlledandB_control_depsare construction sugar, translated once into control nodes: each controlled state factorf(in node order) gets a nodeu_<f>, appended after the declared state factors, and the node is the last transition parent off(underB_control_deps, of every state factor listingf, 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 whenSystemParams.controlholds its box, and its readers then read a float vector (a neural transition’s input, a linear-Gaussian transition’sG uterm).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 sugarcontrolledandB_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, andsophisticated(the alternative syntax forbranch_onandplan_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
kis named aslen(B_deps) + k.
- planner: str = 'enumeration'#
The planner’s registry name:
"enumeration","cem","gradient","mixed","habit"or"sophisticated". Resolved at call time; a face’splanner=argument overrides it.
- gamma: float = 16.0#
The policy precision in q_pi ~ softmax(-gamma G + log E), read when
SystemParams.precisionisNone.
- 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". Theepistemicselector mounts each one’s own epistemic leaf (infogainorambiguity) and never touches risk.
- epistemic: bool | tuple[str, ...] = True#
The per-variable epistemic selector.
Truemounts every eligible variable,Falseor()none, and a tuple names the variables that carry an epistemic leaf: aninfogainleaf underutility_infogain, anambiguityleaf underrisk_ambiguity(risk is never touched by the selector). The grammar, shared withlearn’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 ofpose(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 underrisk_ambiguityits ambiguity isE 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 theuncertaintyterm.
- 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>(aConditionalDirichlet, directly or as the reader of a parameter variable) andparameter:<name>(every reader of the variable); orTrue, 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, asmixture_scheduleis; carried on the hybrid and the fused all-tabular paths (on the fused path abranch_onbranch 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_targetsentry (None: all unconditional; seeresolve_terminal_targets()). AsD_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’sstate_targetsentry, a modality’sobs_targetsentry), 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 aConditionalCategorical(child axis first, then one axis per parent in this order) or aConditionalGaussian(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 inB_depshas a table parent axis ofGrid.n_cellsentries, 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;
Noneat construction fills inmodality_{m}. These are the keys ofSystemParams.likelihood,obs_targetsand the term tree.
- state_names: tuple[str, ...] = None#
One name per state factor, in node order;
Noneat construction fills infactor_{i}for state factori. Withcontrol_namesandmodality_names, the single source of names and order: keys inSystemParams, 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 (obsor a slot word).
- control_names: tuple[str, ...] = None#
One name per control node, in
controlsorder;Noneat construction fills in the sugar’su_<f>per controlled state factorf(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.epistemicselects a dimension as<factor>:<name>; a state factor declared without names hasdim0,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), anddimNmay name positionNonly.
- recognition: tuple[Recognition, ...] | None = None#
The structural half of the recognition slot: which variables an amortized module infers and what each conditions on (
Recognition);Noneor(): none. The modules live inSystemParams.recognition.
- terms: tuple[str, ...] = ()#
The term selector: which estimator-registry terms G carries beyond the
infogaintermsepistemicselects (ROWS). Never inferred fromSystemParams.scoring, so the term tree’s shape is a function of the System. The grammar is the term name, optionally applied to anepistemicvariable 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.termsdoes 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 aRecognitionparent set and supplied per call (infer_states(externals={...})); the width letsparent_dimsvalidate statically.
- subsystems: tuple[tuple[str, Subsystem], ...] | None = None#
(name, Subsystem)pairs recording which state factors, modalities and control nodes came from which component of amerge()call (Nonefor 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 exactlybranch_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=Truecarries every table); declaring it beside abranch_onorplan_learningof 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 underfeedback. 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. Requiresplanning_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, itsaction_namesentry isNone, 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), andreplayandrunrealise 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 slotsobservesdoes 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 isSystemParams.emission[name]or the static identity orGridkernel 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,epistemickey,branch_onorreadingsentry 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 poolsSystemParams.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 oflearnrunsreduce()on each of them, the counter carried inLearnState.moments;Noneleaves 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
controlsorder: the node through which the decision leaves the System, a child of its control node (kernel P(a | u), a delta unlessSystemParams.actuatordeclares one). Declared with the control nodes, asmodality_nameswithA_deps, paired with them by position, both names free; the sugar’s pair for state factorfisu_<f>anda_<f>. The entry isNonefor a driven control node (an input, driven from outside throughobserves: nothing chooses it, so nothing realises it). Action nodes follow the control nodes in node order, soA_depsnames action nodekaslen(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 underrunis a custom one. A splice carries each component’s entries under its prefix. Built byblack_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 nodea_<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, thencontrol_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
Noneunless every control node is continuous (its box inparams.control).
- elapsed(action, params)[source]#
The duration of a realised round: the entry of
params.durationsat the level of the realised action of the node that carries it (1.0 when no durations are declared).actionis keyed by action node, as the environment returns it andact()emits it; under a stochastic actuator it is the realised level, not the decided one, that is looked up. Array in, array out: works underjit. Design: step-durations.md T8.
- ports(params)[source]#
The System’s ports with their types, by name.
insare 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 slotsSystem.observesnames: 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 emptyinsis not what closedness means: that is a property of the modalities alone.outsare 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.statesare the state factors’ names (the belief keys,state_names),names.controlsthe control nodes’ (control_names);names.modalitiesismodality_names;names.actionsthe action nodes’ (the action keys), one per control node in the same order, fromaction_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 fromnames.
- beliefs_from_states(params, states)[source]#
An amortized model’s filter states as the beliefs the faces take, keyed by state factor.
statesis anRSSMState(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 forimagine()’s(N, ...)start beliefs).
- to_positional(kind, keyed_value, params=None)[source]#
A name-keyed value as the positional form the internals use.
kindand 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 completepresentmapping 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 aControlStep(one entry per node) over a mixed space;"detail"→ anInferenceDetailwith tuple fields;"params"→ aSystemParams(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 inparams.control. Seehybrid_aif.system.keyed.
- from_positional(kind, positional, params=None)[source]#
Positional data as the name-keyed form every face takes (inverse of
to_positional()).kindand 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’sControlStep) → a dict by action-node name;"detail"(anInferenceDetailwith tuple fields) → the same record with dict fields;"params"(aSystemParamsor 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 inparams.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 atparameters[<name>]in the keyed form. That check compares concrete arrays only: underjitthe 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, withH_depsresolved.A terminal target is
h, the prior over intended final states, reciprocal to the initial priord. AnH_depsentry makes it aConditionalCategoricalover the designated state factor, conditional on parent state factors (undermergepossibly a higher System’s). It resolves mean-field, asD_depsdoes ininitial_priors()—Σ_parents h(· | parents) q(parents)— withq(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
CompiledSystemwith the same face methods as the System.watch=Falseturns off the retrace warning.
- initial_priors(params)[source]#
Ancestral mean-field marginals of the initial priors,
D_depsresolved, 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_statesuses this whenpriors=None; planning faces take it in place of a raw conditionalD. 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).envis aGenerativeEnv(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_paramskeys its containers by name and carriesparams.actuator, from which the env realises each action it is given. Learnable slots are lowered to their posterior mean, or withparam_keyto onesampleeach, so the env is a draw from the model’s own parameter prior. Raises on the amortized path. It ismirror()(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.inputsgives 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 withfold_in(key, CONTROL_TAG)(_free_controls()), so the key stream of the process itself is the one it has when every node is driven.statesnames the state factors to step; the others keep their values. Every emission is realised by its declared rule. Formirror(s, p)of a Systemswith no actuator kernel and every control node driven, the emissions and the state equals.as_env(p).stepunder the same key.
- emit(key, params, values)[source]#
Realise every emission from
values, keyed by emission name in declaration order.valuesholds 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) withjax.random.split(key, E)[e]for emissioneof theEemissions that have a kernel inparams.emission(the others draw fromsplit(key, E')[e]over allE'). From points,sampleconditions the kernel on the parents and draws (the draw the forward process makes of an observation),modeis the most probable level or the mean,statsthe probability vector or the(mean, covariance). From beliefs,sampledraws the parents and then the kernel (an exact predictive draw), andmodeandstatsare 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 aGridgives the cell a point falls in, or from a belief the cell index bysampleandmodeand the cell mass bystats. Nothing in inference or planning reads an emission; a modality observes one throughSystem.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,
Mean-field state posteriors for one tick’s observations:
(beliefs, detail).observationsis keyed by modality name, one entry per modality: anint32level, 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.priorsand the returned beliefs are keyed by state factor name;priors=Noneusesinitial_priors(). A discrete control node’s entry is optional inpriorsand always returned: no inference runs on it, so it passes through (its uniform prior when absent). An action node a modality observes (A_depsnaming it) is inferred like a state factor on the tabular path: its entry inpriorsis its prior (uniform when absent), and its posterior is returned under its name. Withdetail=True(a static bool) the second slot is anInferenceDetail(pre-reduction switching mixtures, per-mode and total log-evidence keyed by modality name;unsupportedkeyed by state factor name), elseNone; the beliefs are identical either way.presentsays which modalities are observed this tick, a flag per modality keyed by name: a modality it leaves out is present,Nonemeans 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 (itsdetailentries report the hypothetical update,log_evidencezeroed); a PythonFalseskips 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 withall(absent).detail.unsupportedflags each categorical state factor none of whose levels explains this tick’s tabular evidence, ashybrid_aif.inference.discrete.unsupported()defines it againstsupport_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
conditionper LG modality, sequential in modality order; exact Gaussian-sum conditioning for a mixture-carried state factor, with a mode-parent evidence message undermixture_schedule="mode_aligned"; and grow-then-reduce conditioning for a switching LG modality (categorical mode parents after the observed state factor inA_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 valueNoneis allowed for a modality no module reads (its key is still present),externalssupplies"external:<name>"parents, anddetailisNone.With
keythe 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.observationsandpresentare keyed by variable: a modality thatSystem.observesnames 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, orNone, 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,
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
MLPConditionaltakes 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 theA_depsstate factors in order.A non-frozen
MLPConditionallikelihood takes the gradient of the free energyinfer_states(detail=True)reports for the tick: the inference pass is re-run frompriors, the prior beliefsinfer_stateswas given (keyed by state factor name), with every other input held fixed, and differentiated in the decoder. Withoutpriorsthey are the prediction fromprev_beliefsandactionwhenprev_beliefsis given, else the initial priors.externalsis the mappinginfer_statestook for a recognition entry’s external parents. A modality a recognition entry covers contributes its expected negative log-likelihood under the final belief, asinfer_statesrecords it.A parameter variable several state factors read (
SystemParams.parameters) absorbs the sum of its readers’ statistics once, at the ratelr_by_slot["parameter:<name>"](defaultlr). A reader’s own key ("transition:<factor>","likelihood:<modality>") takes only a static0.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:*","*:*") at0.0excludes the referencing readers it matches only while the variable’s own rate is not named literally, so{"*:*": 0.0, "parameter:T": 1.0}learnsTfrom all its readers and{"*:*": 0.0}freezes everything; a literal0.0on 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 throughparameter:*instead.observationsis keyed by modality name,beliefsandprev_beliefsby state factor name,actionby action-node name (asact()returns it).actionis a_{t-1}, the action that produced this tick’s observations; each control node is clamped to its value.prev_beliefsandactionare required exactly when a learnable transition has a nonzero-or-traced rate (actiononly if that state factor is controlled).detailis the keyedInferenceDetailinfer_states(detail=True)returned.Returns bare params for a conjugate-only model,
(params, learn_state)when the model has a gradient slot orlearn_stateis passed. Start the carry withlearn_state=system.init_learn_state(params);Nonewith gradient slots present raises. Raises on the amortized path (train that withhybrid_aif.train.world.fit_world()).Rates.
lrapplies to every learnable slot;lr_by_slotoverrides it by slot-qualified key ("likelihood:<modality>","transition:<factor>","initial_state_prior:<factor>");decay/decay_by_slotuse the same keys. A third segment addresses one independent posterior block ("likelihood:pose:noise"/"…:head"; the jointLinearGaussianObservationMNIWhas 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.0skips 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 andobs: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.0is 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_beliefswith a traced zero rate; gate initial-prior rates to tick 0, since they accumulate once per episode.learnis unbatched; lift it withvmap.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 needsprior, the model’s prior params (the statistics a merge pools are the posterior’s beyond them, and a killed level returns to them), and alearn_statecarrying 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.observationsis keyed by variable, asinfer_states()takes it: the datum of an emission or action node a modality observes (System.observes) is the one the caller supplied toinfer_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]#
freshwith the posteriors learning put intolearnedcarried over: for an agent that rebuilds its params every step and must keep what it has learned. A block is one posteriorlearn()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 whenslotsisNone, 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 (underjit, passslotsas a static argument). Everything else comes fromfresh: point values, and a separateMatrixNormalhead, whichlearndoes 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 thatlearndoes not train (a recognition model, a scoring row, a policy module) are not carried; a gradient slot’s optimizer state is theLearnStatethe 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
statenames, or on every one whenstateisNone: 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 then_pair(defaultreduction_pairs) best by mutual expected log-likelihood, tested greedily.prioris the params the posterior was learned from, which the evidence is relative to.learnruns this everyreduction_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
statenames:observationsholds a window ofNdata,(N, …)per modality over the state factor alone. Each ofroundsrounds 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 ratelrunder the responsibilities the woken levels leave, into the state factor’s weights and its modalities.learnis this with one datum and one round.Design: docs/design/structure-learning.md S3
- init_learn_state(params)[source]#
A fresh
LearnStatefor every gradient-learnable part of this agent.One
opt_statesentry per gradient-learnable slot regardless of rate, plusscoring:<row>for each mounted row with a trainer andACTOR_KEYfor a policy module inpolicy_prior. A scoring entry’s shape is the row’s own (a row that owns a declared System carries a nestedLearnStateover its slots).momentsis 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
posteriorabsorbed fromprior, keyed aslearn()keys its rates (the per-tick data evidence of a filtering step isInferenceDetail.log_evidence, a different quantity). A slot with no closed form is unscored (natsNone,exactFalse); a conjugate slot that absorbed no mass is unscored withexactTrueand itscount. Eager, not for a jitted body. Seehybrid_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,
Build the per-call context a planner runs against (never stored).
beliefsis keyed by state factor name and must be marginals: resolve a conditional or learnableDwithinitial_priors()first (a control node’s entry is ignored). The context itself is positional (init_beliefsin state factor order, actions and policies with one column per control node), as planners index it.horizonis the plan length the planner plans to and the closures are built for (None:policy_len).keyis the plan key a stochastic planner (CEM) reads;scoring_keyis the scoring rows’ own key, under which a row that rolls a model of its own takes the sampled rollout (onlyscore_policies()passes one).aux_beliefsis 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 ofhybrid_aif.objectives.hybrid(beliefs as distributions, mixtures padded tomixture_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.presentsays 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,
Policy posterior and the EFE term tree:
(q_pi, tree), or(q_pi, tree, policies)withreturn_policies, the planner’s clamped policy set as aControlStepwith one entry per control node and leading axes(P, policy_len), in the orderq_piand the tree’s leaves follow.planneris a callable, orNonefor the System’s registry planner.metrics=Falseskips 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_keyis required by, and only by, a stochastic planner ("cem").legalis the hard constraint ofact(), keyed by control node or one bool per policy.beliefsis keyed by state factor name. The planner must return clamped (integer) policies: a belief-valued policy set raises.presentsays 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,)underhorizon=), 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 underplanning_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.
policiesis int32(P, H, K), one column per control node in node order (aspolicies()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 withtotal()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 aCategoricalover 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 aGaussian/TruncatedGaussianover 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’sG uas 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 overq(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 posteriorq_piover clamped policies, which is theq_pi-weightedtotalof 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_targetsentry on a control node scores it: ariskleaf keyed by the node’s name,−log C(u)under a clamp andKL(q(u) ‖ C)under a belief, at every step; aterminal_targetsentry scores the last step asterminal_risk.beliefsis keyed by state factor name. In either form the plan’s lengthHneed not bepolicy_len: the scoring rows are built for the plan’s own horizon.aux_beliefspasses toplanner_context().keyis 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,
Infer policies and emit an action:
(action, q_pi, metrics).beliefsis 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.keyselects the action,plan_keydrives a stochastic planner;metricsas ininfer_policies().mode=Nonetakes the first-step action marginals for discrete controls and the drawn policy’s first step for continuous ones, wheremode="marginal"raises. A planner that emits a posterior over a continuous plan (the gradient planner underposterior="laplace", a truncated Gaussian on the box) has the action drawn from that posterior’s first step underselection="stochastic", and its mode under"deterministic".selectionis the action’s realisation:"stochastic"corresponds to the realisationsample(a draw) and"deterministic"tomode(the argmax, or the mean of a continuous belief); a mixed strategy (stats) is not emitted here. Design: nesting-and-coupling.md N3.legalis 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 inq_piand the marginals. It is separate frompolicy_prior, the soft prior. The planner must return clamped policies (integer levels, or a mixed space’sControlStepof 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.
policiesis the positional policy setq_piis over (None:policies()); the level counts come fromparams’ 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.
policystays positional: int32(horizon, K), one column per control node, or float(horizon, action_dim)over an all-continuous action space; steptof the result followspolicy[t], through the transitionupdate_empirical_prior()uses (no observations enter); an action node a modality observes carries its prediction at each step, asupdate_empirical_prior()gives it.keyselects the sampled rollout, split once per step;Noneis the expected one.
- update_empirical_prior(params, beliefs, action, key=None)[source]#
Next tick’s state priors:
beliefspushed throughaction, keyed by state factor name.actionis keyed by action-node name asact()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 ofparams.actuatorat the clamped level, the one-hot of that level under the delta kernel. A continuous node enters a linear-Gaussian state factor as theG uoffset, 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 Gaussianpredict; grow thenreduce(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
keythe 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,