Source code for fresh_solutions.kernel.telemetry

"""Run telemetry: a per-step objective record and a run header.

Every solver records its objective trajectory to a JSONL file: one header line per run
and one line per iteration. The store is the substrate a tuning or portfolio layer
consumes, so it lives in the shared kernel and stays free of problem-specific types.
"""

from __future__ import annotations

import json
from collections.abc import Mapping, Sequence
from pathlib import Path
from typing import Any, TextIO


[docs] class RunLogger: """Append-only JSONL telemetry for one optimization run. The file opens with one run header, then one record per search step. A search is reproducible from the header (the seed and the configuration) and the step records. Parameters ---------- path : Path The JSONL file to write. run_id : str The run identifier. config : mapping The run configuration to record in the header. auto_flush : bool, optional Flush after every record, so a live reader sees each step promptly. A header-only parent log can turn it off; a worker's own log leaves it on. """ def __init__( self, path: Path, run_id: str, config: Mapping[str, Any], *, auto_flush: bool = True, ) -> None: """Open the log and write the run header. Parameters ---------- path : Path The JSONL file to write. run_id : str The run identifier. config : mapping The run configuration to record in the header. auto_flush : bool, optional Flush after every record, so a live reader sees each step promptly. A header-only parent log can turn it off; a worker's own log leaves it on. """ self.auto_flush = auto_flush self.path = Path(path) self.path.parent.mkdir(parents=True, exist_ok=True) self._last_schedules: dict[str, dict[int, tuple[tuple[str, int], ...]]] = {} self._file: TextIO = self.path.open("w", encoding="utf-8") self._write({"type": "run", "run_id": run_id, "config": dict(config)}) def _write(self, record: Mapping[str, Any]) -> None: """Write one JSON record, flushing when the logger is configured for a live reader.""" self._file.write(json.dumps(record) + "\n") if self.auto_flush: self._file.flush()
[docs] def flush(self) -> None: """Flush buffered records to the file for a live reader.""" self._file.flush()
[docs] def step(self, iteration: int, objective: float, island: str | None = None) -> None: """Record one iteration's objective. Parameters ---------- iteration : int The iteration index. objective : float The incumbent objective at that iteration. island : str or None, optional The worker that reported it, when the search runs more than one. """ record: dict[str, Any] = { "type": "step", "iteration": iteration, "objective": objective, } if island is not None: record["island"] = island self._write(record)
[docs] def trace( self, iteration: int, objective: float, current: float, accepted: int, island: str | None = None, ) -> None: """Record one iteration's incumbent, current objective, and accepted move count. Parameters ---------- iteration : int The iteration index. objective : float The incumbent objective at that iteration. current : float The current solution's objective, which moves even while the incumbent is flat. accepted : int The number of accepted moves since the last reversion, or the run's accepted count. island : str or None, optional The worker that reported it, when the search runs more than one. """ record: dict[str, Any] = { "type": "step", "iteration": iteration, "objective": objective, "current": current, "accepted": accepted, } if island is not None: record["island"] = island self._write(record)
[docs] def targets( self, iteration: int, values: Mapping[tuple[int, str], float], island: str | None = None, ) -> None: """Record the realized value of every tracked account cell at an iteration. Parameters ---------- iteration : int The iteration index. values : mapping of (int, str) to float The realized total per ``(year, account)`` cell, as the move-based evaluator holds it. island : str or None, optional The worker that reported it, when the search runs more than one. """ record: dict[str, Any] = { "type": "targets", "iteration": iteration, "values": [ {"year": year, "account": account, "value": value} for (year, account), value in sorted(values.items()) ], } if island is not None: record["island"] = island self._write(record)
[docs] def schedule( self, iteration: int, schedule: Mapping[int, Sequence[tuple[str, int]]], island: str | None = None, ) -> None: """Record the incumbent's blocks that changed since the last snapshot. A full schedule every snapshot would be large and mostly still; the analyst needs the *movement*, so only the changed blocks are written. A block removed from the schedule is sent with an empty treatment and an offset of -1. Each worker keeps its own previous schedule, so a parallel search never reports one island's blocks as another's removal. Parameters ---------- iteration : int The iteration index. schedule : mapping of int to sequence of (str, int) The incumbent schedule: each block's treatment chain, as (treatment, offset) events. island : str or None, optional The worker that reported it, when the search runs more than one. """ key = island or "" previous = self._last_schedules.get(key, {}) current = {block: tuple(chain) for block, chain in schedule.items()} changed: list[list[object]] = [ [block, [[treatment, offset] for treatment, offset in chain]] for block, chain in current.items() if previous.get(block) != chain ] for block in sorted(set(previous) - set(current)): changed.append([block, []]) self._last_schedules[key] = current if changed: record: dict[str, Any] = { "type": "schedule", "iteration": iteration, "changed": changed, } if island is not None: record["island"] = island self._write(record)
[docs] def close(self) -> None: """Close the log.""" self._file.close()
def __enter__(self) -> RunLogger: """Return the logger.""" return self def __exit__(self, *exc: object) -> None: """Close the log on exit.""" self.close()
[docs] def read_records(path: Path) -> list[dict[str, Any]]: """Read a telemetry JSONL file. Parameters ---------- path : Path The JSONL file. Returns ------- list of dict The parsed records. """ return [ json.loads(line) for line in Path(path).read_text(encoding="utf-8").splitlines() if line.strip() ]