Source code for hybrid_aif.reads

"""The declaration of an emission: an output of a System realised from the state it carries.

An :class:`Emission` is a variable a System generates. Its parents are state factors (and control
nodes) of the System, its kernel is what turns them into a value, and its realisation says which
value: a draw, the most probable value, or the statistics. A System realises its emissions from
whatever it carries: a point (a world's state) or a belief (a planner's posterior).

An emission is also how a System reads its own belief. A modality of the System may observe an
emission of it (``System(observes=...)``), and the value realised after one round is the
observation of the next: the modality is explained by its own parents, so a factor can emit what
the model just believed. A belief read across components (a ``Link`` of
:mod:`hybrid_aif.composition.merge` with a ``realise``) declares the same pair on the source and
the reader.

Design: docs/design/nesting-and-coupling.md N3, N5; docs/design/engine-consolidation.md.
"""

from typing import NamedTuple

from hybrid_aif.cells import Grid

#: The realisations an emission takes: a draw, the most probable value (the argmax of a
#: categorical, the mean of a continuous belief), or the sufficient statistics (the probability
#: vector of a categorical; the mean and covariance of a Gaussian kernel's predictive).
REALISATIONS = ("sample", "mode", "stats")

#: The tag a step's key is folded with before its emissions are realised from it, so an
#: emission's draw is a function of the key it is given and independent of the step's other uses
#: of that key.
EMIT_TAG = 0x454D4954

#: The static kernel of an out-port of a black box (:attr:`System.black_box`): the emission has no
#: parents and no kernel the System states; its value is what the black box's step returns, and its
#: type is the one ``System.black_box`` declares.
BLACK_BOX = "black_box"


[docs] class Emission(NamedTuple): """The declaration of an emission: an output of a System realised from its state factors. Declared in ``System.emissions`` as ``name -> parents`` (a draw through the params' kernel) or ``name -> Emission(parents, realise, kernel)``. Design: docs/design/nesting-and-coupling.md N5; docs/design/engine-consolidation.md. """ #: The state factors and control nodes the emission is conditioned on, in the order of its #: kernel's parent axes. parents: tuple[str, ...] #: How the emission is realised: ``"sample"`` (a draw from the kernel), ``"mode"`` (its most #: probable level, or its mean) or ``"stats"`` (its probability vector, or its mean and #: covariance). realise: str = "sample" #: The emission's static kernel: #: #: - ``None``: the kernel is ``SystemParams.emission[name]``, a likelihood of any family, which #: must be there; #: - ``"identity"``: the emission is its one state factor. A categorical state factor gives a #: level port (its level, or under ``stats`` its probability vector), and a continuous one a #: float port of the state factor's width (its location under ``mode``, a draw under #: ``sample``; ``stats`` is not defined); #: - a :class:`~hybrid_aif.cells.Grid`: an indicator likelihood over the cells of the grid of #: one continuous state factor, a level port with as many levels as the grid has cells: from #: a point the cell the point falls in, from a belief the belief's mass in each cell #: (:func:`~hybrid_aif.cells.cell_mass`), of which ``mode`` is the largest cell, ``stats`` #: the vector and ``sample`` a draw; #: - :data:`BLACK_BOX` (``"black_box"``): an out-port of a black box, with no parents; nothing #: in the library realises it, the black box's step returns its value, and its type is its #: entry in ``System.black_box``. kernel: "Grid | None" = None