Observables

observables

Public records and evaluator contracts for named latent observables.

CompiledObservable

Bases: NamedTuple

Native evaluator and explicit fixed-layout scientific metadata.

Attributes:

Name	Type	Description
definition	ObservableDefinition	Backend-neutral expression and reduction description.
output_shape	tuple[int, ...]	Shape in definition.axes order; empty for a scalar.
coordinates	tuple[tuple[str, tuple[str, ...]], ...]	Coordinate labels for each output axis, in output order.
state_dependencies	tuple[str, ...]	Referenced state base names, in sorted order.
parameter_shapes	tuple[tuple[str, tuple[int, ...]], ...]	Required parameters and their complete input shapes. Scalars have empty shapes; these are separate from RHS requirements.
time_dependent	bool	Whether the expression explicitly references t.
measure_requirements	tuple[tuple[str, AxisMeasure], ...]	Physical measures applied exactly once per axis.
eval_fn	ObservableEvalFn	Evaluator for a complete flat state vector.
pytree_eval_fn	ObservablePytreeEvalFn	Evaluator for complete shaped state buffers.

ObservableDefinition

Bases: NamedTuple

Backend-neutral definition of one instantaneous latent observable.

Attributes:

Name	Type	Description
name	str	Unique output name within a compiled model.
expression	str	Restricted pointwise state/parameter/time expression.
axes	tuple[str, ...]	Output axes, after any explicit reduction.
reduction	ObservableReduction | None	Optional unweighted sum or physical integral.
units	str | None	Optional declared output units, without dimensional verification.
description	str | None	Optional human-readable interpretation.

from_mapping(name, value) classmethod

Validate the bounded observable schema.

Parameters:

Name	Type	Description	Default
name	str	Output identifier.	required
value	object	Mapping with expr, optional axes/reduction/units/description.	required

Returns:

Type	Description
ObservableDefinition	Detached immutable definition.

Raises:

Type	Description
InvalidRhsSpecError	If identifiers, fields or reductions are invalid.

Source code in src/op_system/_observables.py

@classmethod
def from_mapping(cls, name: str, value: object) -> ObservableDefinition:
    """Validate the bounded observable schema.

    Args:
        name: Output identifier.
        value: Mapping with expr, optional axes/reduction/units/description.

    Returns:
        Detached immutable definition.

    Raises:
        InvalidRhsSpecError: If identifiers, fields or reductions are invalid.
    """
    if not _identifier(name):
        raise InvalidRhsSpecError(detail="observable names must be identifiers")
    if not isinstance(value, Mapping) or set(value) - {
        "expr",
        "axes",
        "reduction",
        "units",
        "description",
    }:
        raise InvalidRhsSpecError(detail=f"observable {name!r} has invalid fields")
    expression = _text(value, "expr", required=True)
    axes = _axes(value.get("axes", ()))
    reduction = None
    if "reduction" in value:
        raw = value["reduction"]
        if not isinstance(raw, Mapping) or set(raw) != {"kind", "axes"}:
            raise InvalidRhsSpecError(
                detail="observable reduction needs kind and axes"
            )
        kind = raw["kind"]
        reduction_axes = _axes(raw["axes"])
        if (
            not isinstance(kind, str)
            or kind not in {"sum", "integral"}
            or not reduction_axes
        ):
            raise InvalidRhsSpecError(
                detail="observable reduction must be a nonempty sum or integral"
            )
        reduction = ObservableReduction(
            cast('Literal["sum", "integral"]', kind), reduction_axes
        )
        if set(axes) & set(reduction_axes):
            raise InvalidRhsSpecError(
                detail="observable output and reduction axes must be disjoint"
            )
    return cls(
        name,
        cast("str", expression),
        axes,
        reduction,
        _text(value, "units"),
        _text(value, "description"),
    )

ObservableEvalFn

Bases: Protocol

Evaluate an instantaneous observable from a native flat state array.

ObservablePytreeEvalFn

Bases: Protocol

Evaluate an instantaneous observable from complete shaped state buffers.

ObservableReduction

Bases: NamedTuple

Explicit reduction independent of legacy equation quadrature.

Attributes:

Name	Type	Description
kind	Literal['sum', 'integral']	Unweighted sum or integral with declared physical measures.
axes	tuple[str, ...]	Named axes to remove, in the declared reduction order.