"""Interval-typed scalars: uncertainty measures that carry their own error bars.
Quantities with no closed form for some families (mixture entropies and KLs) are an
``Interval``, a (lower, upper) pair of arrays; exact quantities are zero-width
(``Interval.exact``). Two orthogonal axes: width (point vs spread) and warrant
(:attr:`Interval.derived`, whether a derivation guarantees the enclosure) and the model read
(:attr:`Interval.approximate`, whether that model is a linearised or quadrature reading of the
declared one).
Design: docs/design/amortization.md A4; docs/design/recognition-beside-analytic.md L7
"""
import equinox as eqx
import jax.numpy as jnp
from jax import Array
[docs]
class Interval(eqx.Module):
"""A closed interval [lower, upper], broadcastable like its member arrays.
The two flags are static fields, so they cannot be traced and must agree across a
``lax.scan`` carry; each combinator below propagates them.
"""
#: The lower end.
lower: Array
#: The upper end.
upper: Array
#: Whether the enclosure is guaranteed, given a correct implementation, on the model the
#: planner was handed; ``False`` marks a number a net produced, which nothing bounds. A result
#: is derived iff every input is (an AND through every combinator). Estimators declare it once
#: at registration (:mod:`hybrid_aif.objectives.registry`).
derived: bool = eqx.field(static=True, default=True)
#: Whether that model is a linearised or quadrature reading of the declared one (a nonlinear
#: transition or a neural likelihood), so the enclosure holds for the reading, not for the
#: declaration. ORed through every combinator: a result is approximate iff any input is.
approximate: bool = eqx.field(static=True, default=False)
[docs]
@classmethod
def exact(cls, value: Array, derived: bool = True, approximate: bool = False) -> "Interval":
"""A zero-width interval: the estimate is a point.
``derived=False`` is the amortized leaf, a point estimate with no warrant (a critic's value,
an ensemble's Monte-Carlo info gain). ``approximate=True`` marks a point read off a
linearised or quadrature model.
"""
value = jnp.asarray(value)
return cls(lower=value, upper=value, derived=derived, approximate=approximate)
@property
def midpoint(self) -> Array:
return 0.5 * (self.lower + self.upper)
@property
def width(self) -> Array:
return self.upper - self.lower
def __add__(self, other: "Interval | Array | float") -> "Interval":
if isinstance(other, Interval):
return Interval(
self.lower + other.lower,
self.upper + other.upper,
self.derived and other.derived,
self.approximate or other.approximate,
)
return Interval(self.lower + other, self.upper + other, self.derived, self.approximate)
__radd__ = __add__
def __neg__(self) -> "Interval":
return Interval(-self.upper, -self.lower, self.derived, self.approximate)
def __sub__(self, other: "Interval | Array | float") -> "Interval":
return self + (-other if isinstance(other, Interval) else -jnp.asarray(other))
[docs]
def clip_lower(self, x: "Array | float") -> "Interval":
"""Clamp both bounds below at ``x`` (elementwise); keeps lower <= upper."""
return Interval(
jnp.maximum(self.lower, x), jnp.maximum(self.upper, x), self.derived, self.approximate
)
def __mul__(self, scalar: float) -> "Interval":
"""Multiply by a python scalar; a negative scalar flips the bounds."""
lo, hi = self.lower * scalar, self.upper * scalar
if scalar >= 0:
return Interval(lo, hi, self.derived, self.approximate)
return Interval(hi, lo, self.derived, self.approximate)
__rmul__ = __mul__