trnrun 0.4.0__py3-none-win_amd64.whl

trnrun/__init__.py

@@ -0,0 +1,7 @@
+from trnrun.config import SimulationConfig
+from trnrun.manager import SimulationManager
+from trnrun.simulation import Simulation
+
+__version__ = "0.4.0"
+
+__all__ = ["SimulationConfig", "SimulationManager", "Simulation"]

trnrun/config.py

@@ -0,0 +1,161 @@
+"""Configuration for launching a TRNRun process."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+# -----------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------
+# `trnrun.exe` is bundled inside this package under `bin/`.
+_PACKAGE_DIR = Path(__file__).resolve().parent
+BUNDLED_TRNRUN_PATH = _PACKAGE_DIR / "bin" / "trnrun.exe"
+
+DEFAULT_TRNEXE_PATH = Path(r"C:\TRNSYS18\Exe\TrnEXE64.exe")
+
+
+# -----------------------------------------------------------------
+# Configuration
+# -----------------------------------------------------------------
+@dataclass
+class SimulationConfig:
+    r"""Configuration used to launch TRNRun.
+
+    Each field maps to a `trnrun.exe` command-line flag (noted below as
+    `--flag`). Flags are passed as `--name:value`. These defaults mirror
+    trnrun's own CLI defaults: the `detect`/`watch`/`stall` timeouts are
+    `0` (unlimited/disabled), progress tracking (`watch_tmp`) is off, and
+    `clean_on_success`, `write_log`, and both kill-on-* behaviors are
+    disabled.
+
+    Attributes
+    ----------
+    trnrun_path : Path, default `BUNDLED_TRNRUN_PATH`
+        Path to the `trnrun.exe` executable to invoke. Defaults to the copy
+        bundled with this package.
+    trnexe_path : Path, default `DEFAULT_TRNEXE_PATH`
+    Path to the TRNSYS executable (`TrnEXE64.exe` or `TrnEXE.exe`),
+    passed as `--trnexePath`. trnrun's own fallback is
+    `C:\\TRNSYS18\\Exe\\TrnEXE64.exe`; set this if TRNSYS is installed
+        elsewhere.
+    gui_visibility : str, default `"hidden"`
+    TRNSYS window behavior, passed as `--guiVisibility`. One of:
+
+        - `keep`/`keepOpen`    - visible, stays open after the run.
+        - `auto`/`autoClose`   - visible, closes after the run.
+        - `min`/`minimized`    - minimized, stays open after the run.
+        - `minAuto`/`minimizedAuto` - minimized, closes after the run.
+        - `hidden`               - no window, closes after the run.
+
+    wait_for_gui : bool, default `True`
+        Wait for a TRNSYS GUI as part of launch detection (`--waitForGui`).
+        Launch detection determines when startup has completed so the global
+        mutex can be released for the next simulation.
+    wait_for_lst : bool, default `True`
+    Wait for a specific string to appear in the `*.lst` file during
+    launch detection (`--waitForLst`).
+    wait_for_tmp : bool, default `False`
+    Wait for the `*.tmp` file to appear during launch detection
+    (`--waitForTmp`). Requires a Progress Tracker (Type3830) in the deck.
+    detect_timeout_ms : int, default `0`
+        Timeout in milliseconds for the launch-detection stages
+        (`--detectTimeout`). `0` means unlimited. Combined with
+        `kill_on_timeout`, exceeding this yields a `TIMEOUT` status.
+    extra_delay_ms : int, default `0`
+        Additional delay in milliseconds applied after detection passes
+        (`--extraDelay`).
+    poll_ms : int, default `100`
+        Polling interval in milliseconds for the output files and the process
+        (`--pollMs`).
+    watch_log : bool, default `True`
+    Stream `*.log` entries as `LOG` events (`--watchLog`).
+    watch_tmp : bool, default `False`
+    Stream `*.tmp` updates as `CONFIG`/`PROGRESS` events
+    (`--watchTmp`). Requires Type3830. This also gates progress-derived
+    outcomes: without it, `CANCELLED` and `STALLED` cannot be detected
+    and an early exit is reported as `DONE` instead.
+    watch_timeout_ms : int, default `0`
+        Maximum runtime-monitoring duration in milliseconds
+        (`--watchTimeout`). `0` means unlimited. Exceeding it corresponds
+        to a `TIMEOUT` status / exit code 124.
+    stall_timeout_ms : int, default `0`
+        Maximum wall-clock time in milliseconds with no simulation-time
+        progress before the run is considered stalled (`--stallTimeout`).
+        `0` disables the check. Requires `watch_tmp=True`. A stall yields a
+        `STALLED` status / exit code 125.
+    clean_on_success : bool, default `False`
+    On a successful run, delete the `*.tmp`, `*.log`, `*.lst`, and
+    `*.PTI` artifacts (`--clean`).
+    kill_on_timeout : bool, default `False`
+        Kill the TRNSYS process on a detection or watch timeout
+        (`--killOnTimeout`). If `False`, the runner waits for it to exit.
+    kill_on_stall : bool, default `False`
+    Kill the TRNSYS process when a stall is detected (`--killOnStall`).
+    If `False`, the runner waits for it to exit.
+    severity : str, default `"Notice"`
+    Minimum log severity to emit (`--severity`), one of `"Notice"`,
+    `"Warning"`, or `"Fatal"`.
+    write_log : bool, default `False`
+    Also append every emitted event to `<deckFile>.jsonl`
+    (`--writeLog`).
+    """
+
+    trnrun_path: Path = BUNDLED_TRNRUN_PATH
+    trnexe_path: Path = DEFAULT_TRNEXE_PATH
+    gui_visibility: str = "hidden"
+    wait_for_gui: bool = True
+    wait_for_lst: bool = True
+    wait_for_tmp: bool = False
+    detect_timeout_ms: int = 0
+    extra_delay_ms: int = 0
+    poll_ms: int = 100
+    watch_log: bool = True
+    watch_tmp: bool = False
+    watch_timeout_ms: int = 0
+    stall_timeout_ms: int = 0
+    clean_on_success: bool = False
+    kill_on_timeout: bool = False
+    kill_on_stall: bool = False
+    severity: str = "Notice"
+    write_log: bool = False
+
+    def validate(self) -> None:
+        """Check that both executables exist.
+
+        Raises
+        ------
+        FileNotFoundError
+            If `trnrun_path` or `trnexe_path` is not a file.
+        """
+        if not self.trnrun_path.is_file():
+            raise FileNotFoundError(f"TRNRun executable not found: {self.trnrun_path}")
+        if not self.trnexe_path.is_file():
+            raise FileNotFoundError(f"TrnEXE executable not found: {self.trnexe_path}")
+
+    def to_cli_args(self) -> list[str]:
+        """Convert configuration into `trnrun.exe` command-line arguments."""
+
+        def boolean(value: bool) -> str:
+            return "true" if value else "false"
+
+        return [
+            f"--trnexePath:{self.trnexe_path}",
+            f"--guiVisibility:{self.gui_visibility}",
+            f"--waitForGui:{boolean(self.wait_for_gui)}",
+            f"--waitForLst:{boolean(self.wait_for_lst)}",
+            f"--waitForTmp:{boolean(self.wait_for_tmp)}",
+            f"--detectTimeout:{self.detect_timeout_ms}",
+            f"--extraDelay:{self.extra_delay_ms}",
+            f"--pollMs:{self.poll_ms}",
+            f"--watchLog:{boolean(self.watch_log)}",
+            f"--watchTmp:{boolean(self.watch_tmp)}",
+            f"--watchTimeout:{self.watch_timeout_ms}",
+            f"--stallTimeout:{self.stall_timeout_ms}",
+            f"--clean:{boolean(self.clean_on_success)}",
+            f"--killOnTimeout:{boolean(self.kill_on_timeout)}",
+            f"--killOnStall:{boolean(self.kill_on_stall)}",
+            f"--severity:{self.severity}",
+            f"--writeLog:{boolean(self.write_log)}",
+        ]

trnrun/display.py

@@ -0,0 +1,170 @@
+"""Terminal display for TRNRun-manager simulations using Rich.
+
+Provides live terminal output for running simulations and prints final
+results when they complete. The display does not own simulation state; it
+only renders the state provided by ``SimulationManager``.
+"""
+
+# pyright: reportUnusedCallResult=false
+
+from __future__ import annotations
+
+from threading import Lock
+
+from rich.console import Console, Group
+from rich.live import Live
+from rich.text import Text
+
+from trnrun.simulation import Simulation, SimulationSnapshot
+from trnrun.utils import format_hhmmss, truncate_left
+
+# -----------------------------------------------------------------
+# Constants
+# -----------------------------------------------------------------
+COLOR_MAP: dict[str, str | None] = {
+    "PENDING": None,
+    "RUNNING": None,
+    "DONE": "green",
+    "ERROR": "red",
+    "TIMEOUT": "red",
+    "STALLED": "red",
+    "CANCELLED": "yellow",
+}
+
+PATH_WIDTH = 32
+PROGRESS_BAR_WIDTH = 20
+MS_PER_SECOND = 1000
+
+
+# -----------------------------------------------------------------
+# Null Display
+# -----------------------------------------------------------------
+class NullDisplay:
+    """Display that renders nothing; for headless runs and tests."""
+
+    def simulation_started(self, _simulation: Simulation) -> None:
+        """Ignore simulation start events."""
+
+    def simulation_finished(self, _simulation: Simulation) -> None:
+        """Ignore simulation finish events."""
+
+
+# -----------------------------------------------------------------
+# Display
+# -----------------------------------------------------------------
+class Display:
+    """Live terminal view of currently running simulations.
+
+    Parameters
+    ----------
+    refresh_interval : float, optional
+        Time in seconds between live region refreshes. Must be positive.
+    """
+
+    def __init__(self, refresh_interval: float = 1.0) -> None:
+        if refresh_interval <= 0:
+            raise ValueError("refresh_interval must be positive")
+
+        self.console: Console = Console()
+
+        self._lock: Lock = Lock()
+        self._live_lock: Lock = Lock()
+
+        self._active: dict[int, Simulation] = {}
+        self._refresh_per_second: float = 1 / refresh_interval
+        self._live: Live | None = None
+
+    # -----------------------------------------------------------------
+    # Event Handlers
+    # -----------------------------------------------------------------
+    def simulation_started(self, simulation: Simulation) -> None:
+        """Add a simulation to the live display."""
+        with self._live_lock:
+            with self._lock:
+                self._active[simulation.id] = simulation
+
+            if self._live is None:
+                live = self._make_live()
+                live.start()
+                self._live = live
+
+    def simulation_finished(self, simulation: Simulation) -> None:
+        """Remove a simulation and print its final state."""
+        with self._live_lock:
+            with self._lock:
+                self._active.pop(simulation.id, None)
+                empty = not self._active
+
+            self.console.print(self._render_line(simulation.snapshot()))
+
+            if empty and self._live is not None:
+                live, self._live = self._live, None
+                live.stop()
+
+    # -----------------------------------------------------------------
+    # Rendering
+    # -----------------------------------------------------------------
+    def _make_live(self) -> Live:
+        """Build a fresh transient live display."""
+        return Live(
+            get_renderable=self._render_all,
+            console=self.console,
+            refresh_per_second=self._refresh_per_second,
+            transient=True,
+        )
+
+    def _progress_bar(self, percent: float, width: int = PROGRESS_BAR_WIDTH) -> str:
+        """Return a fixed-width ASCII completion bar."""
+        filled = min(max(int(width * percent), 0), width)
+        return "[" + "#" * filled + "-" * (width - filled) + "]"
+
+    def _render_line(self, sim: SimulationSnapshot) -> Text:
+        """Render one simulation snapshot."""
+        path = truncate_left(str(sim.deck_path), PATH_WIDTH)
+
+        status = sim.status.status if sim.status else "PENDING"
+        status_style = COLOR_MAP.get(status.upper())
+
+        logs = f"N:{sim.notices} W:{sim.warnings} F:{sim.fatals}"
+
+        progress = sim.progress
+
+        elapsed = format_hhmmss(progress.elapsed / MS_PER_SECOND if progress else None)
+        eta = format_hhmmss(progress.eta / MS_PER_SECOND if progress else None)
+
+        sim_time = progress.time if progress else None
+        percent = progress.percent if progress else None
+
+        config = sim.config_event
+        sim_stop = config.stop if config else None
+
+        if percent is None:
+            bar = "[" + "-" * PROGRESS_BAR_WIDTH + "]"
+            sim_percent = ""
+        else:
+            bar = self._progress_bar(percent)
+            sim_percent = f"({percent * 100:.0f}%)"
+
+        sim_progress = "- / -" if sim_time is None or sim_stop is None else f"{sim_time:6,.0f} / {sim_stop:6,.0f}"
+
+        text = Text()
+        text.append(f"[{sim.id}] ")
+        text.append(f"{path:<{PATH_WIDTH}} │ ")
+        text.append("Status: ")
+        text.append(f"{status:<10}", style=status_style)
+        text.append(" │ ")
+        text.append(f"Logs: {logs:<12} │ ")
+        text.append(f"Elapsed: {elapsed:<8} │ ETA: {eta:<8} │ ")
+        text.append(f"{bar} {sim_progress} {sim_percent:6}")
+
+        if sim.error is not None:
+            text.append(f" │ error: {sim.error}", style="red")
+
+        return text
+
+    def _render_all(self) -> Group:
+        """Render all active simulations."""
+        with self._lock:
+            active = list(self._active.values())
+
+        return Group(*(self._render_line(sim.snapshot()) for sim in active))

trnrun/events.py

@@ -0,0 +1,307 @@
+"""Typed events emitted by TRNRun on stdout, and their JSONL parsers.
+
+TRNRun writes one JSON object per line. ``parse_event`` turns a single
+line into a typed event; ``stream_events`` does the same for an entire
+stream of lines.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable, Iterator
+from dataclasses import dataclass
+from typing import Final, cast
+
+
+# -----------------------------------------------------------------
+# Exceptions
+# -----------------------------------------------------------------
+class EventParseError(ValueError):
+    """Raised when a JSON line cannot be parsed into a TRNRun event."""
+
+
+# -----------------------------------------------------------------
+# Events
+# -----------------------------------------------------------------
+@dataclass(frozen=True)
+class StatusEvent:
+    """A STATUS event reporting the run's current state.
+
+    Attributes
+    ----------
+    status : str
+        State reported by TRNRun.
+    timestamp : str
+        Timestamp attached to the event by TRNRun.
+    """
+
+    status: str
+    timestamp: str
+
+
+@dataclass(frozen=True)
+class ProgressEvent:
+    """A PROGRESS event reporting run completion and timing.
+
+    Attributes
+    ----------
+    time : float
+        Current simulation time.
+    percent : float
+        Completion of the run as a fraction from 0 to 1.
+    elapsed : float
+        Wall-clock milliseconds elapsed since the run started.
+    eta : float
+        Estimated wall-clock milliseconds remaining.
+    timestamp : str
+        Timestamp attached to the event by TRNRun.
+    """
+
+    time: float
+    percent: float
+    elapsed: float
+    eta: float
+    timestamp: str
+
+
+@dataclass(frozen=True)
+class ConfigEvent:
+    """A CONFIG event reporting the run's sweep parameters.
+
+    Attributes
+    ----------
+    start : float
+        Simulation start time.
+    stop : float
+        Simulation stop time.
+    step : float
+        Simulation time step.
+    timestamp : str
+        Timestamp attached to the event by TRNRun.
+    """
+
+    start: float
+    stop: float
+    step: float
+    timestamp: str
+
+
+@dataclass(frozen=True)
+class LogEvent:
+    """A LOG event carrying a severity-tagged message.
+
+    Only ``severity`` and ``timestamp`` are guaranteed; the remaining
+    fields depend on what TRNRun attaches to the message.
+
+    Attributes
+    ----------
+    severity : str
+        Severity tag, e.g. ``"notice"``, ``"warning"`` or ``"fatal"``.
+    timestamp : str
+        Timestamp attached to the event by TRNRun.
+    time : float or None
+        Simulation time at which the message was produced.
+    unit_id : int or None
+        Unit that emitted the message.
+    type_id : int or None
+        Type of the unit that emitted the message.
+    message_code : int or None
+        Numeric code identifying the message.
+    message : str or None
+        Human-readable message text.
+    information : str or None
+        Additional detail attached to the message.
+    """
+
+    severity: str
+    timestamp: str
+    time: float | None = None
+    unit_id: int | None = None
+    type_id: int | None = None
+    message_code: int | None = None
+    message: str | None = None
+    information: str | None = None
+
+
+type TrnRunEvent = StatusEvent | ProgressEvent | ConfigEvent | LogEvent
+
+
+# -----------------------------------------------------------------
+# Validation Helpers
+# -----------------------------------------------------------------
+def _required(data: dict[str, object], key: str) -> object:
+    """Return a required field, raising ``EventParseError`` if missing."""
+    try:
+        return data[key]
+    except KeyError as e:
+        raise EventParseError(f"missing required field '{key}'") from e
+
+
+def _require_str(data: dict[str, object], key: str) -> str:
+    """Return a required string field."""
+    value = _required(data, key)
+
+    if not isinstance(value, str):
+        raise EventParseError(f"field '{key}' must be a string")
+
+    return value
+
+
+def _require_float(data: dict[str, object], key: str) -> float:
+    """Return a required numeric field as a float, rejecting booleans."""
+    value = _required(data, key)
+
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise EventParseError(f"field '{key}' must be a number")
+
+    return float(value)
+
+
+def _require_int(data: dict[str, object], key: str) -> int:
+    """Return a required integer field, rejecting booleans."""
+    value = _required(data, key)
+
+    if isinstance(value, bool) or not isinstance(value, int):
+        raise EventParseError(f"field '{key}' must be an integer")
+
+    return value
+
+
+def _optional_str(data: dict[str, object], key: str) -> str | None:
+    """Return an optional string field, treating JSON null as absent."""
+    return None if data.get(key) is None else _require_str(data, key)
+
+
+def _optional_float(data: dict[str, object], key: str) -> float | None:
+    """Return an optional numeric field, treating JSON null as absent."""
+    return None if data.get(key) is None else _require_float(data, key)
+
+
+def _optional_int(data: dict[str, object], key: str) -> int | None:
+    """Return an optional integer field, treating JSON null as absent."""
+    return None if data.get(key) is None else _require_int(data, key)
+
+
+# -----------------------------------------------------------------
+# Event Parsers
+# -----------------------------------------------------------------
+def _parse_status(data: dict[str, object]) -> StatusEvent:
+    """Parse a STATUS event."""
+    return StatusEvent(
+        status=_require_str(data, "status"),
+        timestamp=_require_str(data, "timestamp"),
+    )
+
+
+def _parse_progress(data: dict[str, object]) -> ProgressEvent:
+    """Parse a PROGRESS event."""
+    return ProgressEvent(
+        time=_require_float(data, "time"),
+        percent=_require_float(data, "percent"),
+        elapsed=_require_float(data, "elapsed"),
+        eta=_require_float(data, "eta"),
+        timestamp=_require_str(data, "timestamp"),
+    )
+
+
+def _parse_config(data: dict[str, object]) -> ConfigEvent:
+    """Parse a CONFIG event."""
+    return ConfigEvent(
+        start=_require_float(data, "start"),
+        stop=_require_float(data, "stop"),
+        step=_require_float(data, "step"),
+        timestamp=_require_str(data, "timestamp"),
+    )
+
+
+def _parse_log(data: dict[str, object]) -> LogEvent:
+    """Parse a LOG event."""
+    return LogEvent(
+        severity=_require_str(data, "severity"),
+        timestamp=_require_str(data, "timestamp"),
+        time=_optional_float(data, "time"),
+        unit_id=_optional_int(data, "unitId"),
+        type_id=_optional_int(data, "typeId"),
+        message_code=_optional_int(data, "messageCode"),
+        message=_optional_str(data, "message"),
+        information=_optional_str(data, "information"),
+    )
+
+
+# Dispatch table mapping an event's "kind" to its parser.
+_PARSERS: Final[dict[str, Callable[[dict[str, object]], TrnRunEvent]]] = {
+    "STATUS": _parse_status,
+    "PROGRESS": _parse_progress,
+    "CONFIG": _parse_config,
+    "LOG": _parse_log,
+}
+
+
+# -----------------------------------------------------------------
+# Parsing
+# -----------------------------------------------------------------
+def parse_event(line: str) -> TrnRunEvent:
+    """Parse one JSON-encoded TRNRun event.
+
+    Parameters
+    ----------
+    line : str
+        A single line of TRNRun stdout containing one JSON object.
+
+    Returns
+    -------
+    TrnRunEvent
+        The typed event corresponding to the object's ``kind``.
+
+    """
+    try:
+        value = cast("object", json.loads(line))
+    except json.JSONDecodeError as e:
+        raise EventParseError(f"invalid JSON: {e}") from e
+
+    if not isinstance(value, dict):
+        raise EventParseError("event must be a JSON object")
+
+    data = cast("dict[str, object]", value)
+
+    kind = _require_str(data, "kind").upper()
+
+    try:
+        parser = _PARSERS[kind]
+    except KeyError as e:
+        raise EventParseError(f"unknown event kind '{kind}'") from e
+
+    return parser(data)
+
+
+def stream_events(
+    lines: Iterable[str],
+    *,
+    skip_invalid: bool = False,
+) -> Iterator[TrnRunEvent]:
+    """Yield parsed events from a JSONL stream, skipping blank lines.
+
+    Parameters
+    ----------
+    lines : Iterable[str]
+        Lines of TRNRun stdout, one JSON object per line.
+    skip_invalid : bool, optional
+        If true, silently drop lines that fail to parse instead of
+        raising. Defaults to False.
+
+    Yields
+    ------
+    TrnRunEvent
+        One typed event per successfully parsed line.
+    """
+    for raw_line in lines:
+        line = raw_line.strip()
+
+        if not line:
+            continue
+
+        try:
+            yield parse_event(line)
+        except EventParseError:
+            if not skip_invalid:
+                raise