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()
build_frontend()def build_frontend(
kind: FrontendKind | typing.Literal["plain"],
) -> ProgressDisplay: ...Construct the ProgressDisplay for one already-resolved kind.
kindFrontendKind | typing.Literal['plain'] —"widget","panel","tqdm","plain", or"none"(the latter two both build aPlainDisplay, a no-op).
detect_frontend()
detect_frontend()def detect_frontend(verbosity: int = 1) -> FrontendKind: ...Pick a frontend for the environment this call is made in.
verbosityint —<= 0always resolves to"none", before probing the environment at all — a quiet run does not even attempt to importipywidgets.
"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
DisplayHandleclass 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.
jobNGInProcessJob — The job to stream telemetry from.displayProgressDisplay — The frontend to drive.
close()
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).
join()
join()def join(self, timeout: float | None = None) -> None: ...Block until the display thread has finished, if it ran at all.
timeoutfloat | None — Maximum seconds to wait, asthreading.Thread.join.None(the default) waits indefinitely.
start()
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.
PanelDisplay
PanelDisplayclass 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.
consolerich.console.Console | None — Therichconsole to render to.None(the default) builds a fresh one bound to the real stdout.
close()
close()def close(self) -> None: ...Stop the underlying Live display.
finish()
finish()def finish(self, snapshot: TelemetrySnapshot) -> None: ...Refresh the Live display with render(snapshot).
snapshotTelemetrySnapshot — The run’s final (terminal-status) snapshot.
render()
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).
snapshotTelemetrySnapshot — The snapshot to render.
print() or hand to a Live.start()
start()def start(self, job: NGInProcessJob) -> None: ...Start the underlying Live display.
jobNGInProcessJob — Unused.
update()
update()def update(self, snapshot: TelemetrySnapshot) -> None: ...Refresh the Live display with render(snapshot).
snapshotTelemetrySnapshot — The newly-published, non-terminal snapshot.
PlainDisplay
PlainDisplayclass 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.
close()
close()def close(self) -> None: ...A no-op.
finish()
finish()def finish(self, snapshot: TelemetrySnapshot) -> None: ...A no-op.
snapshotTelemetrySnapshot — Unused.
start()
start()def start(self, job: NGInProcessJob) -> None: ...A no-op.
jobNGInProcessJob — Unused.
update()
update()def update(self, snapshot: TelemetrySnapshot) -> None: ...A no-op.
snapshotTelemetrySnapshot — Unused.
ProgressDisplay
ProgressDisplayclass 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).
close()
close()def close(self) -> None: ...Release any display resources (stop a Live, close a tqdm
bar). Called exactly once, after the last update/finish.
finish()
finish()def finish(self, snapshot: TelemetrySnapshot) -> None: ...Called once, for the run’s terminal snapshot.
snapshotTelemetrySnapshot — The run’s final (terminal-status) snapshot.
start()
start()def start(self, job: NGInProcessJob) -> None: ...Called once, before the first update/finish.
jobNGInProcessJob — The job this display is being started for.
update()
update()def update(self, snapshot: TelemetrySnapshot) -> None: ...Called for every non-terminal snapshot.
snapshotTelemetrySnapshot — The newly-published, non-terminal snapshot.
TqdmDisplay
TqdmDisplayclass 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.
close()
close()def close(self) -> None: ...Close the bar, if one was ever created.
finish()
finish()def finish(self, snapshot: TelemetrySnapshot) -> None: ...Update the bar one last time, then close it.
snapshotTelemetrySnapshot — The run’s final (terminal-status) snapshot.
start()
start()def start(self, job: NGInProcessJob) -> None: ...A no-op — the bar is created lazily, once n_steps is known.
jobNGInProcessJob — Unused.
update()
update()def update(self, snapshot: TelemetrySnapshot) -> None: ...Update the bar’s position and postfix.
snapshotTelemetrySnapshot — The newly-published, non-terminal snapshot.
WidgetDisplay
WidgetDisplayclass 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().
close()
close()def close(self) -> None: ...Drop this display’s reference to the job.
finish()
finish()def finish(self, snapshot: TelemetrySnapshot) -> None: ...Update every widget model value from snapshot and disable
the Cancel button.
snapshotTelemetrySnapshot — The run’s final (terminal-status) snapshot.
start()
start()def start(self, job: NGInProcessJob) -> None: ...Display the widget in the current notebook cell.
jobNGInProcessJob — The job this display is being started for.
update()
update()def update(self, snapshot: TelemetrySnapshot) -> None: ...Update every widget model value from snapshot.
snapshotTelemetrySnapshot — The newly-published, non-terminal snapshot.