m/market labResearch, with a record.
Source on GitHub ↗

pacer.py

1"""Turn-based pacing: the market waits while the Agent works, then moves to its next turn.23In a turn-based Agent experiment the shared clock never moves with real time. The4TurnPacer, a thread in the owning process, advances it. It moves the clock only when the5whole experiment is settled at the current time:67- the execution owner has processed every market event up to it;8- the Runtime has received every market notification published so far;9- the Runtime has fully stepped at this time, so any work that was due or triggered has10  already started; and11- the Agent has no work running and no model reply outstanding.1213An order or cancel the Agent submits while the market waits is stamped with the current14time, and the owner executes commands stamped before its clock. So whenever commands are15pending, the pacer moves the clock on by one nanosecond: the command executes at the same16instant, and the Agent gets its result without the market moving.1718Then it jumps to the earliest of: the Runtime's next own time (scheduled work, a wait,19a retry, the end), the next market event, or the experiment end. The execution owner20processes every event in between in order, exactly as in Live mode. While the Agent21works, market time stands still, so its thinking and model latency cost nothing.2223A model request whose reply has not arrived within the attempt timeout in real time is24given its deadline: the clock jumps to it so the Runtime times the attempt out.25"""2627from __future__ import annotations28import logging2930import time31from threading import Event, Thread32from typing import TYPE_CHECKING, Any, Callable, Dict, Optional, Tuple3334_log = logging.getLogger(__name__)3536if TYPE_CHECKING:  # Annotation only.37    from sim_platform.experiments.execution.session import ExperimentSession38    from sim_platform.experiments.scheduling.clock import SharedExperimentClock3940# How often the pacer looks at the experiment (seconds).41POLL_SECONDS = 0.00242TERMINAL = ('completed', 'stopped', 'failed')43# Attempt states with a model reply still outstanding.44WAITING_FOR_MODEL = ('running', 'expiry_pending')454647class TurnPacer:48    """Advance a turn-based experiment clock between the Agent's turns.4950    Args:51        clock: The experiment's turn-based SharedExperimentClock (paced=True).52        session: The execution owner whose market events the clock releases.53        runtime: Returns the Runtime's latest published snapshot.54        published: Returns how many market notification batches have been published55            to the Runtime.56        timeout_ns: The model attempt timeout, applied in real time while paced.57    """5859    def __init__(60        self,61        clock: SharedExperimentClock,62        session: ExperimentSession,63        runtime: Callable[[], Dict[str, Any]],64        published: Callable[[], int],65        timeout_ns: int,66    ) -> None:67        self.clock, self.owner = clock, session68        self._runtime, self._published = runtime, published69        self._timeout_ns = timeout_ns70        self._stop = Event()71        self._thread: Optional[Thread] = None72        # (attempt id, real time it was first seen outstanding).73        self._outstanding: Optional[Tuple[str, int]] = None74        self.turns = 075        self.error: Optional[BaseException] = None7677    def start(self) -> None:78        if self._thread is None:79            self._thread = Thread(target=self._run, name='turn-pacer', daemon=True)80            self._thread.start()8182    def stop(self) -> None:83        self._stop.set()84        if self._thread is not None and self._thread.is_alive():85            self._thread.join(timeout=1)8687    def _run(self) -> None:88        try:89            while not self._stop.is_set():90                if self.owner.snapshot()['state'] in TERMINAL:91                    return92                target = self.next_target()93                if target is not None:94                    self.clock.advance_to(target)95                    self.turns += 196                    self.owner.wake()97                else:98                    self._stop.wait(POLL_SECONDS)99        except BaseException as exc:  # Surfaced through snapshot(); the run then stalls visibly.100            _log.warning('Handled failure in _run', exc_info=True)101            self.error = exc102103    def next_target(self) -> Optional[int]:104        """The time to advance to now, or None while the experiment is not settled."""105        if self.owner.snapshot()['state'] != 'running':106            return None107        now = self.clock.target_ns()108        end = self.owner.end_ns109        if now >= end:110            return None111        timeline, reader = self.owner.timeline, self.owner.reader112        upcoming = (113            reader.event_time(timeline.cursor)114            if timeline.cursor < reader.manifest['frames']115            else None116        )117        if upcoming is not None and upcoming < now:118            return None  # The owner is still processing market events before now.119        if upcoming == now:120            # Like commands, an event executes once the clock is past its time.121            return now + 1122        if self.owner.sequencer.queued_at_or_after(now):123            # The owner executes commands stamped before the current time; one nanosecond124            # lets the Agent's order or cancel made at this instant execute now, while it125            # waits for the result.126            return now + 1127        if self.owner.sequencer.snapshot()['pending']:128            return None  # A command is executing; its result reaches the Agent next.129        runtime = self._runtime()130        stepped = runtime.get('stepped_ns')131        if stepped is None or int(stepped) < now:132            return None133        if int(runtime.get('event_sequence', 0)) < self._published():134            return None135        attempt = runtime.get('attempt') or {}136        if attempt.get('state') in WAITING_FOR_MODEL:137            return self._model_deadline(attempt)138        self._outstanding = None139        if attempt.get('state') == 'retrying' and attempt.get('retry_due_ns') is not None:140            return max(now + 1, int(attempt['retry_due_ns']))141        if (runtime.get('work') or {}).get('state') == 'running':142            return None143        times = [end]144        if runtime.get('next_ns') is not None:145            times.append(int(runtime['next_ns']))146        if upcoming is not None:147            times.append(upcoming)148        later = [t for t in times if t > now]149        return min(later) if later else None150151    def _model_deadline(self, attempt: Dict[str, Any]) -> Optional[int]:152        """The attempt's deadline once it has been outstanding longer than the timeout."""153        identity = str(attempt.get('attempt_id'))154        started = time.monotonic_ns()155        if self._outstanding is None or self._outstanding[0] != identity:156            self._outstanding = (identity, started)157            return None158        if started - self._outstanding[1] < self._timeout_ns or attempt.get('deadline_ns') is None:159            return None160        return int(attempt['deadline_ns'])161162    def snapshot(self) -> Dict[str, Any]:163        return dict(turns=self.turns, error=repr(self.error) if self.error else None)