Coordinates

coordinates

Explicit mixed identity/log solver coordinates with natural-state outputs.

The original CompiledRhs remains in physical coordinates. Construct a view once, encode initial states, and use its evaluator for deterministic integration.

CoordinateResult

Bases: NamedTuple, Generic[_StateT]

Transformed state and a namespace-native scalar domain flag.

Attributes:

Name	Type	Description
state	_StateT	Array or PyTree after transformation; no floor or clamp is applied.
valid	Array	Finite state with strictly positive selected physical components. For decoding this also flags exp underflow to zero and overflow.

StateCoordinateView(natural, log_indices, log_bases, eval_fn, pytree_eval_fn, block_pytree_eval_fn, observables) dataclass

Deterministic evaluators in explicitly selected solver coordinates.

Natural model state, reactions, scientific declarations and observations remain available on natural. This view does not export jump artifacts, balance laws or original derivative-affinity claims in solver coordinates.

Attributes:

Name	Type	Description
natural	CompiledRhs	Source model, in natural coordinates (possibly gauge-fixed).
log_indices	tuple[int, ...]	Selected expanded flat state components.
log_bases	tuple[str, ...]	State bases using log coordinates, shared over their templates.
eval_fn	EvalFn	Coordinate derivative, with the source flat evaluator contract.
pytree_eval_fn	PytreeEvalFn | None	Optional coordinate derivative for shaped state buffers.
block_pytree_eval_fn	PytreeEvalFn | None	Optional coordinate derivative for stripped blocks.
observables	Mapping[str, CompiledObservable]	Natural-scale observables evaluated from encoded states.

Examples:

>>> import numpy as np
>>> from op_system import compile_spec
>>> model = compile_spec({
...     "kind": "expr",
...     "state": ["x"],
...     "state_metadata": {"x": {"scale": "log"}},
...     "equations": {"x": "-rate*x"},
... })
>>> view = model.coordinate_view()
>>> z0 = view.encode(np.array([2.0]))
>>> np.allclose(view.eval_fn(0, z0, rate=0.5), [-0.5])
True
>>> np.allclose(view.decode(z0), [2.0])
True

param_names property

Source equation parameter requirements, omitting gauge anchors.

state_names property

Source component order; selected values now store log states.

__post_init__()

Cache component selection once, independently of execution namespace.

Source code in src/op_system/coordinates.py

def __post_init__(self) -> None:
    """Cache component selection once, independently of execution namespace."""
    selected = frozenset(self.log_indices)
    object.__setattr__(
        self,
        "_mask",
        tuple(index in selected for index in range(len(self.natural.state_names))),
    )

__reduce__()

Rebuild evaluators from the retained natural source when unpickling.

Returns:

Type	Description
tuple[object, tuple[CompiledRhs]]	Module factory and source model, without serialized closures.

Source code in src/op_system/coordinates.py

def __reduce__(self) -> tuple[object, tuple[CompiledRhs]]:
    """Rebuild evaluators from the retained natural source when unpickling.

    Returns:
        Module factory and source model, without serialized closures.
    """
    return _build_state_coordinates, (self.natural,)

bind(params)

Bind source parameters to the coordinate derivative.

Returns:

Type	Description
Callable[[object, object], Float64Array]	A two-argument deterministic RHS, with solver-coordinate state.

Source code in src/op_system/coordinates.py

def bind(
    self, params: Mapping[str, object]
) -> Callable[[object, object], Float64Array]:
    """Bind source parameters to the coordinate derivative.

    Returns:
        A two-argument deterministic RHS, with solver-coordinate state.
    """
    values = dict(params)

    def evaluate(t: object, state: object) -> Float64Array:
        return self.eval_fn(t, state, **values)

    return evaluate

decode(state, *, state_axis=0)

Return native decoded values without an eager domain check.

Parameters:

Name	Type	Description	Default
state	Array	Floating solver coordinates.	required
state_axis	int	Component axis; use 1 for output trajectories.	0

Returns:

Type	Description
Array	Natural-scale array, for transformed computations and observations.
Array	Use decode_native or decode_checked when checking representation.

Source code in src/op_system/coordinates.py

def decode(self, state: Array, *, state_axis: int = 0) -> Array:
    """Return native decoded values without an eager domain check.

    Args:
        state: Floating solver coordinates.
        state_axis: Component axis; use 1 for output trajectories.

    Returns:
        Natural-scale array, for transformed computations and observations.
        Use decode_native or decode_checked when checking representation.
    """
    return self.decode_native(state, state_axis=state_axis).state

decode_checked(state, *, state_axis=0)

Decode and eagerly reject underflow/overflow or invalid values.

Parameters:

Name	Type	Description	Default
state	Array	Floating solver coordinates.	required
state_axis	int	Component axis in source order.	0

Returns:

Type	Description
Array	A finite natural state, positive in selected components.

Source code in src/op_system/coordinates.py

def decode_checked(self, state: Array, *, state_axis: int = 0) -> Array:
    """Decode and eagerly reject underflow/overflow or invalid values.

    Args:
        state: Floating solver coordinates.
        state_axis: Component axis in source order.

    Returns:
        A finite natural state, positive in selected components.
    """
    result = self.decode_native(state, state_axis=state_axis)
    _require_valid(result.valid, "decode")
    return result.state

decode_native(state, *, state_axis=0)

Decode natural values and flag finite-precision representation failures.

Parameters:

Name	Type	Description	Default
state	Array	Floating solver coordinates.	required
state_axis	int	Component axis; use 1 for output trajectories.	0

Returns:

Type	Description
CoordinateResult[Array]	Natural values and finite/positive-domain flag. exp can underflow or
CoordinateResult[Array]	overflow; the flag is not an integration-accuracy assessment.

Source code in src/op_system/coordinates.py

def decode_native(
    self, state: Array, *, state_axis: int = 0
) -> CoordinateResult[Array]:
    """Decode natural values and flag finite-precision representation failures.

    Args:
        state: Floating solver coordinates.
        state_axis: Component axis; use 1 for output trajectories.

    Returns:
        Natural values and finite/positive-domain flag. exp can underflow or
        overflow; the flag is not an integration-accuracy assessment.
    """
    return _native_flat(state, self._mask, state_axis, encode=False)

decode_pytree_native(state)

Decode complete buffers and return native representation flags.

Returns:

Type	Description
CoordinateResult[dict[str, Array]]	Natural buffers with a native finite/positive flag.

Source code in src/op_system/coordinates.py

def decode_pytree_native(
    self, state: Mapping[str, Array]
) -> CoordinateResult[dict[str, Array]]:
    """Decode complete buffers and return native representation flags.

    Returns:
        Natural buffers with a native finite/positive flag.
    """
    return self._tree(state, encode=False)

encode(state, *, state_axis=0)

Check a physical initial state eagerly before taking logarithms.

Parameters:

Name	Type	Description	Default
state	Array	Finite floating natural state, positive in selected components.	required
state_axis	int	Component axis, in source order.	0

Returns:

Type	Description
Array	Initial state in solver coordinates. Use encode_native under JIT/AD.

Source code in src/op_system/coordinates.py

def encode(self, state: Array, *, state_axis: int = 0) -> Array:
    """Check a physical initial state eagerly before taking logarithms.

    Args:
        state: Finite floating natural state, positive in selected components.
        state_axis: Component axis, in source order.

    Returns:
        Initial state in solver coordinates. Use encode_native under JIT/AD.
    """
    xp = array_namespace(state)
    values, mask = _array_and_mask(state, self._mask, state_axis)
    valid = xp.logical_and(
        xp.all(xp.isfinite(values)),
        xp.all(xp.logical_or(xp.logical_not(mask), xp.greater(values, 0))),
    )
    _require_valid(valid, "encode")
    return self.encode_native(state, state_axis=state_axis).state

encode_native(state, *, state_axis=0)

Map physical arrays to selected log coordinates, with native flags.

Parameters:

Name	Type	Description	Default
state	Array	Real floating natural state, with component axis in source order.	required
state_axis	int	Component axis; use 1 for output trajectories.	0

Returns:

Type	Description
CoordinateResult[Array]	Encoded state and scalar flag without host extraction. Invalid
CoordinateResult[Array]	selected inputs produce nonfinite logarithms; no floor is applied.

Source code in src/op_system/coordinates.py

def encode_native(
    self, state: Array, *, state_axis: int = 0
) -> CoordinateResult[Array]:
    """Map physical arrays to selected log coordinates, with native flags.

    Args:
        state: Real floating natural state, with component axis in source order.
        state_axis: Component axis; use 1 for output trajectories.

    Returns:
        Encoded state and scalar flag without host extraction. Invalid
        selected inputs produce nonfinite logarithms; no floor is applied.
    """
    return _native_flat(state, self._mask, state_axis, encode=True)

encode_pytree_native(state)

Encode complete buffers and return native finite/positive flags.

Returns:

Type	Description
CoordinateResult[dict[str, Array]]	Solver-coordinate buffers with a native domain flag.

Source code in src/op_system/coordinates.py

def encode_pytree_native(
    self, state: Mapping[str, Array]
) -> CoordinateResult[dict[str, Array]]:
    """Encode complete buffers and return native finite/positive flags.

    Returns:
        Solver-coordinate buffers with a native domain flag.
    """
    return self._tree(state, encode=True)