Source code for osprey_connectors.settle

"""Wait for a written setpoint's readback to come within the bound its facility states.

Every caller that waits for a readback after a write uses this one step: the
Bluesky worker for a plan's moves, the sandbox runtime for a script's or a
measurement's steps. The bound has one rule (:func:`settle_bound`): the
setpoint's ``tolerance`` (``absolute``, or ``relative`` times the demand's
magnitude); with none stated, on the simulator only, the readback's motion
band; a caller's floor raises the bound and never lowers it. :func:`settle`
polls each readback through the connector until it is within its bound, and
fails closed with :class:`SettleTimeoutError` when the time runs out. A
readback that cannot be reached, is not a channel, or times out raises
:class:`SettleReadError`, which names it, as does one that answers no value; a
lost connector raises its own error.

This module imports only the std-lib and ``osprey_connectors.errors``, and
takes any connector with an awaitable ``read_channel(address)`` whose result
carries ``.value``.
"""

from __future__ import annotations

import asyncio
import math
import numbers
import time
from collections.abc import Awaitable, Callable, Mapping, Sequence
from dataclasses import dataclass
from typing import Any, SupportsFloat, SupportsIndex

from osprey_connectors.errors import ChannelError, ChannelReadFailedError

__all__ = [
    "Landing",
    "SettleReadError",
    "SettleTimeoutError",
    "declared_tolerance",
    "settle",
    "settle_bound",
]

#: Seconds between two reads of a readback that is not yet within its bound.
_POLL_INTERVAL_S = 0.05


def _as_float(value: object) -> float:
    """``float(value)``, refusing with ``float``'s own errors what ``float`` refuses."""
    if isinstance(value, str | bytes | bytearray | SupportsFloat | SupportsIndex):
        return float(value)
    raise TypeError(
        f"float() argument must be a string or a real number, not {type(value).__name__!r}"
    )


[docs] def declared_tolerance(record: Mapping[str, object] | None, demand: float) -> float | None: """The bound a ``tolerance`` record states for a move to ``demand``. Args: record: The setpoint's ``tolerance`` record, ``{absolute: x}`` in the channel's unit or ``{relative: f}``, a fraction of the demand. demand: The value the setpoint is driven to. Returns: ``|absolute|``, or ``|relative| x |demand|``; ``None`` when the record states neither. """ if not isinstance(record, Mapping): return None if "absolute" in record: return abs(_as_float(record["absolute"])) if "relative" in record: return abs(_as_float(record["relative"])) * abs(float(demand)) return None
[docs] def settle_bound( tolerance: Mapping[str, object] | None, demand: float, *, motion: float = 0.0, simulated: bool = False, floor: float | None = None, ) -> float | None: """How close a readback must come to ``demand`` for the move to count as settled. Args: tolerance: The setpoint's ``tolerance`` record, or ``None``. demand: The value the setpoint is driven to. motion: The readback's motion band. simulated: Whether the machine is the simulator; only there does the motion band stand in for a tolerance that is not stated. floor: The caller's floor, or ``None``. Returns: The larger of ``floor`` and the declared bound; ``None`` when nothing is declared and the caller gives no floor, so there is nothing to wait for. """ declared = declared_tolerance(tolerance, demand) if declared is None and simulated and motion > 0: declared = motion if declared is None and floor is None: return None return max(floor or 0.0, declared or 0.0)
[docs] @dataclass(frozen=True) class Landing: """One written setpoint, the readback that reports it, its demand and its bound.""" setpoint: str readback: str demand: float bound: float
[docs] class SettleTimeoutError(TimeoutError): """A readback did not come within its bound of the demand in time. Attributes: landing: The first landing that did not settle. last: Its readback's last reading. """
[docs] def __init__(self, landing: Landing, last: object, timeout_s: float) -> None: self.landing = landing self.last = last super().__init__( f"readback {landing.readback} did not settle to {landing.demand} " f"± {landing.bound:g} within {timeout_s:g}s (last read: {last})" )
[docs] class SettleReadError(ChannelReadFailedError): """A readback could not be read while settling, or answered no value. Attributes: landing: The landing whose readback could not be read. addresses: The readback, the one failed channel. causes: The readback to the exception its read raised; empty when the read answered no value. """
[docs] def __init__(self, landing: Landing, cause: BaseException | None) -> None: self.landing = landing reason = f"{type(cause).__name__}: {cause}" if cause is not None else "no value" super().__init__( [landing.readback], f"readback {landing.readback} of {landing.setpoint} could not be read: {reason}", causes={landing.readback: cause} if cause is not None else None, )
[docs] async def settle( connector: Any, landings: Sequence[Landing], *, timeout_s: float, clock: Callable[[], float] = time.monotonic, sleep: Callable[[float], Awaitable[None]] = asyncio.sleep, ) -> None: """Poll each landing's readback until it is within its bound of its demand. Every landing is read once per poll until it is inside; a settled landing is not read again. A reading with no value is a failed read; any other reading that is not a finite number is never inside. Args: connector: Reads each readback with ``await connector.read_channel(address)``. landings: The landings to wait for. timeout_s: Seconds from the call after which an unsettled landing fails. clock: The clock the deadline is measured on. sleep: The pause between two polls. Raises: SettleTimeoutError: A landing was not inside its bound once ``timeout_s`` had passed, naming the first such landing in ``landings`` order. SettleReadError: A readback read failed with a :class:`~osprey_connectors.errors.ChannelError` (it cannot be reached, is not a channel, or timed out) or answered no value, naming that readback. Any other failure, a lost connector among them, propagates as itself. """ deadline = clock() + timeout_s pending = list(landings) while pending: unsettled: list[tuple[Landing, object]] = [] for landing in pending: try: reading: object = await connector.read_channel(landing.readback) except ChannelError as exc: raise SettleReadError(landing, exc) from exc value: object = getattr(reading, "value", None) if value is None: raise SettleReadError(landing, None) if not _within(value, landing): unsettled.append((landing, value)) if not unsettled: return if clock() >= deadline: landing, last = unsettled[0] raise SettleTimeoutError(landing, last, timeout_s) pending = [landing for landing, _ in unsettled] await sleep(_POLL_INTERVAL_S)
def _within(value: object, landing: Landing) -> bool: """Whether ``value`` is a finite number within the landing's bound of its demand.""" if isinstance(value, bool) or not isinstance(value, numbers.Real): return False reading = float(value) return math.isfinite(reading) and abs(reading - landing.demand) <= landing.bound