SystemParams#
- class hybrid_aif.SystemParams[source]#
Bases:
ModuleAll numeric state of a System: generative tensors, designations and the closed-loop factors.
A
Systemholds the static structure; itsSystemParamsholds every array, as a pytree passed to each face (a method ofSystemthat takes the params, such asinfer_states,actorlearn) and returned by those that update it.Keying.
likelihoodis keyed by modality name,transitionandinitial_state_priorby state factor name (params.likelihood["position"]); every face takes and returns them so, and a positional (tuple) container raises, namingSystem.from_positional("params", params). Inside, the System reads a positional view (tuples in node order), built by name lookup.recognitionandscoringjoin the slot-qualified key space (recognition:stoch,scoring:g_tail) and namespace undermerge().Families. Declaration types carry the family: tabular declarations give a discrete System; linear-Gaussian declarations (
hybrid_aif.factors) and Gaussian or mixture priors give a continuous or mixed one. Alikelihood,transitionorinitial_state_priorentry is a point declaration, a distribution over its parameters (ConditionalDirichlet,Dirichlet), learnable bySystem.learn()and samplable byas_env(param_key=...), or a parametrized function (MLPConditional), learnable by gradient.Groups. The fields fall in three groups, plus the per-leaf record of a composite:
the declared model:
transition,likelihood,initial_state_prior,control,actuator,durations,parameters,references,readings,emission;the closed-loop factors (the two factors of the loop that return the distribution the loop acts on):
recognitionandpolicy_prior;scoring material:
obs_targets,state_targets,terminal_targets,scoringandprecision;parts, each leaf’s own planner parameters when the System is a splice of leaves.
tests/test_scoring_slot.pyasserts the partition. The AIF lettersA,B,DandEare read-only aliases oflikelihood,transition,initial_state_priorandpolicy_prior. A table of the fields is indocs/composing-systems.md.Design: docs/design/system.md (SystemParams groups); docs/design/parameter-learning.md D3; docs/design/amortization.md A1 A2 A11 A12.
- transition: Mapping[str, ConditionalCategorical | ConditionalDirichlet | LinearGaussianTransition | NonlinearGaussianTransition | MLPConditional | Deterministic | MLPCategorical | Parameter]#
AIF’s B: the transition of each state factor, keyed by state factor name. The trailing parent axis is the control (tables), the conditioned innovations (linear-Gaussian), or a one-hot or continuous action parent (neural, deterministic). A
Deterministicentry is a carry node (its own previous value is the map’s carry, not a parent); anMLPCategoricalentry is a factored-categorical code whose parents are read within the step (the two make the neural state-space pair). AParameter(name)entry reads the table held undernameinparameters.
- initial_state_prior: Mapping[str, Categorical | ConditionalCategorical | Dirichlet | ConditionalDirichlet | Gaussian | MixtureGaussian | LearnedVector | DerivedInitial]#
AIF’s D: the initial prior of each state factor, keyed by state factor name. A
LearnedVectoris a carry node’s episode-start value; aDerivedInitialsays “read it off my own transition at t=0”.
- likelihood: Mapping[str, ConditionalCategorical | ConditionalDirichlet | LinearGaussianObservation | MLPConditional | PredictorHead | Parameter]#
AIF’s A: the likelihood of each modality, keyed by modality name. An entry is a child-first
(num_obs, *dep_sizes)table (a point table or a Dirichlet over one), a linear-Gaussian(H, c, R_chol)head, a neural conditional, aPredictorHead(a trunk and a named loss:symlog_mse,symlog_discorbinary), or aParameter(name)reading the table held undernameinparameters. Default{}: an open-loop model observes nothing.
- recognition: dict[str, object]#
The amortized inference modules, keyed by the variable each infers, for example
{"stoch": posterior_net, "embed": encoder}. Their structure (what each module infers and conditions on) isSystem.recognition.
- obs_targets: dict[str, Distribution]#
Standing preferences over observations (AIF’s C), keyed by modality name: a
Categoricalover a tabular modality’s levels, or aGaussianorMixtureGaussianover a linear-Gaussian modality’s observation space (the covariance is the tolerance). An entry for a neural modality raises. AConditionalCategoricalorConditionalGaussianentry is a target conditional on the parentsSystem.C_depsnames under its key, one distribution per parent configuration.
- state_targets: dict[str, Distribution]#
Standing preferences over states, scored as risk, keyed by state factor name. A conditional entry is as in
obs_targets; aCategoricalunder a discrete control node’s name is that node’s fixed cost per level.
- terminal_targets: dict[str, Distribution | ConditionalCategorical]#
Terminal preferences, scored at the end of the horizon (the H of Friston et al. 2023 and of SPM’s
spm_MDP_VB_XXX), keyed by state factor name. AConditionalCategoricalentry is a conditional terminal target and needs aSystem.H_depsentry naming its parent state factors (seeSystem.resolve_terminal_targets()).
- scoring: dict[str, object]#
The parameters of the objective terms that carry their own (entries of the estimator registry), keyed by term name, for example
{"g_tail": (critic, slow), "ensemble_disagreement": (m0, m1, m2, m3)}; a term that owns a declared model holds that model’s params. The structure isSystem.termsandSystem.scoring.
- policy_prior: Array | Categorical | object | None = None#
The prior over policies (AIF’s E, read-only alias
E): a log-space array or aCategoricalover an enumerated policy set, or a policy module (beliefs to an action distribution) that the"habit"planner acts from. Since q_pi ~ softmax(-gamma G + log E), E does not depend on gamma: habits belong here; costs that must trade against utilities belong in the targets (inside G).
- control: dict[str, Box]#
The box of each continuous control node, keyed by the node’s name (
params.control["u_x"]): aBoxof per-dimension bounds, the node’s support, which the CEM and gradient planners search inside. A node with an entry is continuous (its readers read a float vector of the box’s width); a node without one is discrete. Design: docs/design/control-states.md C4.
- actuator: dict[str, Array]#
The kernel P(a | u) of each action node that is not a delta, keyed by the action node’s name (
params.actuator["a_x"]): a(levels, levels)probability table whose columnuis the distribution of the realised action given the decisionu(discrete control nodes only). An action node without an entry realises its control node’s decision exactly. The action node is realised once per tick, by a draw from the kernel (sample;System.act’sselectiongives the other realisation,mode, for the decision itself), bySystem.as_envwhen the environment is stepped on its own and by the driver underrunandcouple; the control node stays clamped to the decision. Design: docs/design/control-states.md C12, C13; nesting-and-coupling.md N3, N5.
- durations: dict[str, Array]#
A round’s duration per level of one discrete control node, keyed by the node’s name (
params.durations["u_option"]): a positive float(levels,)array, or a scalar for every level, in the unit the model’s preferences are per. A round steps every state factor once, so a round has one duration and at most one node carries it; the engine checks positivity only. The objective never reads it;System.elapsed()returns the realised action’s duration for an outer loop’s clock (1 when none is declared). Design: docs/design/step-durations.md T1, T4, T8.
- precision: Array | None = None#
The policy precision gamma, an optional scalar array: q_pi ~ softmax(-precision G + log E). When present the planners read it in place of
System.gamma(the static default, read when this isNone); being a parameter leaf it flows traced through every face, so changing its value recompiles nothing. Design: docs/design/recompilation.md R5.
- readings: dict[str, Array]#
The reading counts of
System.readings, keyed by the named state factor or modality: one positive count per level of its control node, the number of fast readings one slow reading pools under that level. Read only by the novelty term of that table. Design: step-durations.md T10.
- parameters: dict[str, ConditionalCategorical | ConditionalDirichlet | InverseGamma | InverseWishart]#
Named parameter variables, keyed by name: a tabular declaration (a table, or a Dirichlet over one) that several
transitionorlikelihoodentries read throughParameter(name); an entry that is itself a table is that state factor’s or modality’s own variable. Every reader of one name reads one table;System.learn()sums the readers’ count statistics and updates the named table once, under the rate keyparameter:<name>. The faces return the references, never copies of the table. A variable may instead hold a noise prior (anInverseGammaorInverseWishart), read by one field of a declaration: a Gaussian transition’snoise_prioror aLinearGaussianObservation’snoiseholdingParameter(name); its readers’ residual statistics sum into one update the same way. Design: docs/design/shared-parameters.md; process-noise-learning.md D4.
- references: tuple[tuple[str, int, str], ...] = ()#
The positional view’s record of which reader positions hold a resolved reference, as
(slot, index, parameter name)triples; empty in the keyed form every face takes and returns, where the entries are theParametertokens themselves.
- noise_references: tuple[tuple[str, int, str], ...] = ()#
The positional view’s record of which readers hold a resolved noise variable in one field (a transition’s
noise_prior, a likelihood’snoise), as(slot, index, parameter name)triples; empty in the keyed form, where the field holds theParametertoken.
- emission: dict[str, object]#
The kernel of each emission (an output the System draws from its state factors,
System.emissions), keyed by emission name: a likelihood of any family (a table, a linear-Gaussian or neural conditional, a learnable form, or aParameterreference to a named parameter variable), over the emission’s parents in the orderSystem.emissionslists them. The emitted port’s type is read off the kernel, as a modality’s is. No inference, planning or learning face reads it. Design: nesting-and-coupling.md N5.
- parts: dict[str, PartParams]#
The leaves’ own planner parameters in a composite, keyed by leaf name (
PartParams: habit, precision, durations and scoring parameters); empty for a System that is not a splice of leaves. A leaf’s entry holds its own; a composite node holds none. Design: engine-consolidation.md.
- property A#
AIF-letter alias for
likelihood.
- property B#
AIF-letter alias for
transition.
- property D#
AIF-letter alias for
initial_state_prior.
- property E#
AIF-letter alias for
policy_prior(read-only; the field is the writable name).