Skip to content

salvus.flow.ng.progress_display

salvus.flow.ng.progress_display salvus flow ng progress_display

Environment-adapted, one-way progress display for an in-process run.

run_in_process/NGInProcessJob.display() pick a frontend based on where the code runs — a live ipywidgets panel in Jupyter (WidgetDisplay), a rich TUI panel on an interactive terminal (PanelDisplay), a single-line tqdm bar otherwise (TqdmDisplay), or nothing extra at all (PlainDisplay, a no-op — _build_progress_hooks’s own verbosity-gated print callback already covers this case, unchanged since P6). Every live frontend is fed from NGInProcessJob.telemetry_stream() on its own daemon thread (DisplayHandle), independent of whichever thread is actually running the solve — this only works because the native session bindings release the GIL during advance()/run_segment() (see session_binding.hpp), so the display thread can keep rendering while a solve chunk is in flight.

This is a ONE-WAY display: the only interactive element anywhere is a Cancel action (job.cancel()), never a general two-way control surface.

Threading note on WidgetDisplay: ipywidgets traitlet assignments (.value = ... etc.) from a background thread are the documented pattern for reflecting long-running work in a widget — the Comm layer serializes the update, it does not require the assigning thread to be the one that created the widget or to hold any special lock. This module relies on that documented behavior; it has not been independently re-verified against a live browser frontend in this environment (no notebook kernel is running here), only that the widget’s own model values update correctly under a driven sequence of snapshots (see test_progress_display.py).

Functions

build_frontend()

def build_frontend(
    kind: FrontendKind | typing.Literal["plain"],
) -> ProgressDisplay: ...

Construct the ProgressDisplay for one already-resolved kind.

Parameters
  • kind FrontendKind | typing.Literal['plain'] — "widget", "panel", "tqdm", "plain", or "none" (the latter two both build a PlainDisplay, a no-op).
Returns ProgressDisplay — A fresh, unstarted display.

detect_frontend()

def detect_frontend(verbosity: int = 1) -> FrontendKind: ...

Pick a frontend for the environment this call is made in.

Parameters
  • verbosity int = 1 — <= 0 always resolves to "none", before probing the environment at all — a quiet run does not even attempt to import ipywidgets.
Returns FrontendKind — "widget" in a Jupyter notebook kernel (salvus.utils. notebook_utils.in_notebook()); "panel" on an interactive terminal (sys.stdout.isatty()); "tqdm" otherwise (logs, CI, a plain script); "none" when verbosity <= 0.

Classes

DisplayHandle

class DisplayHandle(builtins.object):
    def __init__(
        self, job: NGInProcessJob, display: ProgressDisplay
    ) -> None: ...

Drives one ProgressDisplay from job.telemetry_stream() on its own daemon thread, started by start() and self-closing once the stream reaches a terminal snapshot.

Parameters
  • job NGInProcessJob — The job to stream telemetry from.
  • display ProgressDisplay — The frontend to drive.
Methods
close()
def close(self) -> None: ...

Force-close the underlying display. A no-op if it already self-closed (ProgressDisplay.close() implementations here are all idempotent).

Returns None
join()
def join(self, timeout: float | None = None) -> None: ...

Block until the display thread has finished, if it ran at all.

Parameters
  • timeout float | None = None — Maximum seconds to wait, as threading.Thread.join. None (the default) waits indefinitely.
Returns None
start()
def start(self) -> None: ...

Start the display. If the job has ALREADY reached a terminal status (e.g. job.display() called after wait()), renders that final snapshot once, synchronously, and never starts the background thread at all.

Returns None

PanelDisplay

class PanelDisplay(builtins.object):
    def __init__(
        self, console: rich.console.Console | None = None
    ) -> None: ...

A rich TUI panel, refreshed from rich.live.Live — the same fields as WidgetDisplay, as a table plus a text progress bar.

render() is a pure function of one snapshot (no Live involved) so it can be tested directly against a recording Console, without depending on Live’s own terminal-detection and refresh timing.

Parameters
  • console rich.console.Console | None = None — The rich console to render to. None (the default) builds a fresh one bound to the real stdout.
Methods
close()
def close(self) -> None: ...

Stop the underlying Live display.

Returns None
finish()
def finish(self, snapshot: TelemetrySnapshot) -> None: ...

Refresh the Live display with render(snapshot).

Parameters
  • snapshot TelemetrySnapshot — The run’s final (terminal-status) snapshot.
Returns None
render()
def render(
    self, snapshot: TelemetrySnapshot
) -> rich.console.RenderableType: ...

Build the panel rich renders for one snapshot — a pure function of snapshot, with no Live involved (see this class’ own docstring for why that matters for testing).

Parameters
  • snapshot TelemetrySnapshot — The snapshot to render.
Returns rich.console.RenderableType — The panel, ready to print() or hand to a Live.
start()
def start(self, job: NGInProcessJob) -> None: ...

Start the underlying Live display.

Parameters
  • job NGInProcessJob — Unused.
Returns None
update()
def update(self, snapshot: TelemetrySnapshot) -> None: ...

Refresh the Live display with render(snapshot).

Parameters
  • snapshot TelemetrySnapshot — The newly-published, non-terminal snapshot.
Returns None

PlainDisplay

class PlainDisplay(builtins.object):
    def __init__(self): ...

The "plain"/"none" frontend: does nothing. run_in_process’s own pre-existing, verbosity-gated print callback (_build_progress_hooks, unchanged since P6) is the only output in this case.

Methods
close()
def close(self) -> None: ...

A no-op.

Returns None
finish()
def finish(self, snapshot: TelemetrySnapshot) -> None: ...

A no-op.

Parameters
  • snapshot TelemetrySnapshot — Unused.
Returns None
start()
def start(self, job: NGInProcessJob) -> None: ...

A no-op.

Parameters
  • job NGInProcessJob — Unused.
Returns None
update()
def update(self, snapshot: TelemetrySnapshot) -> None: ...

A no-op.

Parameters
  • snapshot TelemetrySnapshot — Unused.
Returns None

ProgressDisplay

class ProgressDisplay(typing.Protocol):
    def __init__(self):
        ...

Something that renders a live sequence of TelemetrySnapshots.

Every method is called from DisplayHandle’s own daemon thread, never the solve thread — implementations must be safe to update from a background thread (true of ipywidgets’ traitlets, rich’s Live, and tqdm’s own bar, all by design).

Methods
close()
def close(self) -> None: ...

Release any display resources (stop a Live, close a tqdm bar). Called exactly once, after the last update/finish.

Returns None
finish()
def finish(self, snapshot: TelemetrySnapshot) -> None: ...

Called once, for the run’s terminal snapshot.

Parameters
  • snapshot TelemetrySnapshot — The run’s final (terminal-status) snapshot.
Returns None
start()
def start(self, job: NGInProcessJob) -> None: ...

Called once, before the first update/finish.

Parameters
  • job NGInProcessJob — The job this display is being started for.
Returns None
update()
def update(self, snapshot: TelemetrySnapshot) -> None: ...

Called for every non-terminal snapshot.

Parameters
  • snapshot TelemetrySnapshot — The newly-published, non-terminal snapshot.
Returns None

TqdmDisplay

class TqdmDisplay(builtins.object):
    def __init__(self) -> None: ...

A single-line tqdm bar with ETA/RSS in its postfix — used outside a TTY (logs, CI) where a live panel would just spam scrollback with redraws.

Methods
close()
def close(self) -> None: ...

Close the bar, if one was ever created.

Returns None
finish()
def finish(self, snapshot: TelemetrySnapshot) -> None: ...

Update the bar one last time, then close it.

Parameters
  • snapshot TelemetrySnapshot — The run’s final (terminal-status) snapshot.
Returns None
start()
def start(self, job: NGInProcessJob) -> None: ...

A no-op — the bar is created lazily, once n_steps is known.

Parameters
  • job NGInProcessJob — Unused.
Returns None
update()
def update(self, snapshot: TelemetrySnapshot) -> None: ...

Update the bar’s position and postfix.

Parameters
  • snapshot TelemetrySnapshot — The newly-published, non-terminal snapshot.
Returns None

WidgetDisplay

class WidgetDisplay(builtins.object):
    def __init__(self) -> None: ...

An ipywidgets panel: a progress bar, a status badge, run/resource stats, a collapsible live timer tree, an outputs table, and a Cancel button wired to job.cancel().

Methods
close()
def close(self) -> None: ...

Drop this display’s reference to the job.

Returns None
finish()
def finish(self, snapshot: TelemetrySnapshot) -> None: ...

Update every widget model value from snapshot and disable the Cancel button.

Parameters
  • snapshot TelemetrySnapshot — The run’s final (terminal-status) snapshot.
Returns None
start()
def start(self, job: NGInProcessJob) -> None: ...

Display the widget in the current notebook cell.

Parameters
  • job NGInProcessJob — The job this display is being started for.
Returns None
update()
def update(self, snapshot: TelemetrySnapshot) -> None: ...

Update every widget model value from snapshot.

Parameters
  • snapshot TelemetrySnapshot — The newly-published, non-terminal snapshot.
Returns None