Source code for hybrid_aif.objectives.base

"""Objective term trees: the metrics-bearing currency of the objective layer.

A term tree is a pytree ``term_name -> block_name -> Interval`` with per-policy
batch axes; it is what ``infer_policies`` returns as metrics. Leaves keep each
quantity's natural sign, and :func:`total` folds them into G (minimized) using each
term's registered sign; an unregistered term raises. Every :data:`INFOGAIN` leaf is
an information gain (higher is better, G subtracts it), a mutual information >= 0 up to
its interval's bounds. Block keys under ``infogain`` are a bare name for a state leaf
(the observing channel; the code variable on the amortized path) and slot-qualified
(``"likelihood:vision"``) for a parameter leaf. A disabled block is omitted from the
tree, never zeroed.

Design: docs/design/per-variable-infogain.md V3, V11
"""

import jax.tree_util as jtu

from hybrid_aif.interval import Interval

TermTree = dict[str, dict[str, Interval]]

#: The single epistemic term name (V3); every estimator's leaves land here.
INFOGAIN = "infogain"

_TERM_SIGNS: dict[str, float] = {
    "utility": -1.0,
    INFOGAIN: -1.0,
    "risk": 1.0,
    "ambiguity": 1.0,
}


[docs] def register_term(name: str, sign: float) -> None: """Register a term name with its sign as a contribution to G: ``+1.0`` for a cost, ``-1.0`` for a value. Any other sign raises :class:`ValueError`; registering a name again replaces its sign.""" if sign not in (1.0, -1.0): raise ValueError(f"sign must be +1.0 or -1.0, got {sign}") _TERM_SIGNS[name] = sign
def term_sign(name: str) -> float: """A registered term's sign as a contribution to G (+1 cost, −1 value). Raises :class:`KeyError` for an unregistered term. """ if name not in _TERM_SIGNS: raise KeyError(f"unregistered term {name!r}; use register_term(name, sign)") return _TERM_SIGNS[name]
[docs] def total(tree: TermTree, exclude: tuple[str, ...] = ()) -> Interval: """Fold a term tree into a single G Interval (expected free energy, minimized). Raises :class:`ValueError` when no leaves remain (e.g. a habit planner's ``{}``). """ parts = [] for term, blocks in tree.items(): if term in exclude: continue if term not in _TERM_SIGNS: raise KeyError(f"unregistered term {term!r}; use register_term(name, sign)") parts.extend(_TERM_SIGNS[term] * iv for iv in blocks.values()) if not parts: raise ValueError("term tree has no included leaves") out = parts[0] for iv in parts[1:]: out = out + iv return out
[docs] def merge(*trees: TermTree) -> TermTree: """Merge term trees block-wise, dropping empty terms. Trees sharing a term have their blocks merged; later trees win on a repeated ``(term, block)`` pair. """ out: TermTree = {} for tree in trees: for term, blocks in tree.items(): if blocks: out.setdefault(term, {}).update(blocks) return out
[docs] def map_leaves(fn, tree: TermTree) -> TermTree: """Apply ``fn`` to every Interval leaf, preserving the term/block structure.""" return jtu.tree_map(fn, tree, is_leaf=lambda x: isinstance(x, Interval))