SystemParams#

class hybrid_aif.SystemParams[source]#

Bases: Module

All numeric state of a System: generative tensors, designations and the closed-loop factors.

A System holds the static structure; its SystemParams holds every array, as a pytree passed to each face (a method of System that takes the params, such as infer_states, act or learn) and returned by those that update it.

Keying. likelihood is keyed by modality name, transition and initial_state_prior by state factor name (params.likelihood["position"]); every face takes and returns them so, and a positional (tuple) container raises, naming System.from_positional("params", params). Inside, the System reads a positional view (tuples in node order), built by name lookup. recognition and scoring join the slot-qualified key space (recognition:stoch, scoring:g_tail) and namespace under merge().

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. A likelihood, transition or initial_state_prior entry is a point declaration, a distribution over its parameters (ConditionalDirichlet, Dirichlet), learnable by System.learn() and samplable by as_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): recognition and policy_prior;

  • scoring material: obs_targets, state_targets, terminal_targets, scoring and precision;

  • parts, each leaf’s own planner parameters when the System is a splice of leaves.

tests/test_scoring_slot.py asserts the partition. The AIF letters A, B, D and E are read-only aliases of likelihood, transition, initial_state_prior and policy_prior. A table of the fields is in docs/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 Deterministic entry is a carry node (its own previous value is the map’s carry, not a parent); an MLPCategorical entry is a factored-categorical code whose parents are read within the step (the two make the neural state-space pair). A Parameter(name) entry reads the table held under name in parameters.

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 LearnedVector is a carry node’s episode-start value; a DerivedInitial says “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, a PredictorHead (a trunk and a named loss: symlog_mse, symlog_disc or binary), or a Parameter(name) reading the table held under name in parameters. 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) is System.recognition.

obs_targets: dict[str, Distribution]#

Standing preferences over observations (AIF’s C), keyed by modality name: a Categorical over a tabular modality’s levels, or a Gaussian or MixtureGaussian over a linear-Gaussian modality’s observation space (the covariance is the tolerance). An entry for a neural modality raises. A ConditionalCategorical or ConditionalGaussian entry is a target conditional on the parents System.C_deps names 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; a Categorical under 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. A ConditionalCategorical entry is a conditional terminal target and needs a System.H_deps entry naming its parent state factors (see System.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 is System.terms and System.scoring.

policy_prior: Array | Categorical | object | None = None#

The prior over policies (AIF’s E, read-only alias E): a log-space array or a Categorical over 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"]): a Box of 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 column u is the distribution of the realised action given the decision u (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’s selection gives the other realisation, mode, for the decision itself), by System.as_env when the environment is stepped on its own and by the driver under run and couple; 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 is None); 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 transition or likelihood entries read through Parameter(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 key parameter:<name>. The faces return the references, never copies of the table. A variable may instead hold a noise prior (an InverseGamma or InverseWishart), read by one field of a declaration: a Gaussian transition’s noise_prior or a LinearGaussianObservation’s noise holding Parameter(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 the Parameter tokens 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’s noise), as (slot, index, parameter name) triples; empty in the keyed form, where the field holds the Parameter token.

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 a Parameter reference to a named parameter variable), over the emission’s parents in the order System.emissions lists 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.

__init__(*args, **kwargs)[source]#
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).