neuralqx.callbacks.live_monitoring module¶
Live monitoring utilities for neuraLQX optimisation runs.
This module implements a lightweight Dash/Plotly web UI for streaming scalar metrics during training (objective/loss plus optional observables). A training-side callback enqueues compact scalar payloads into a thread-safe queue, while a background server thread consumes the queue and renders live plots and a “latest values” stats bar.
The UI runs only on the global MPI master process. It also exposes an “Abort simulation” button; when pressed, a server-side flag is set and the training callback can request termination by returning False to the driver.
- class LiveMonitor(host='127.0.0.1', port=8050, *, objective_label='Constraint', x_label='Iteration', y_label='<C>', update_interval_ms=100)¶
Bases:
objectDash server plus in-memory time-series store for live training visualisation.
The training side pushes only small scalar payloads into an internal thread-safe queue. A background server thread periodically drains the queue, appends points to per-metric time series, and updates a Plotly figure plus a “latest values” stats bar.
- Parameters:
host (
str) – Interface to bind the Dash server to.port (
int) – Preferred starting port for the Dash server. The monitor searches for an available port in [port, _MAX_PORT].objective_label (
str) – Display name for the objective/loss trace (always shown).x_label (
str) – Label for the x-axis (typically iteration/step).y_label (
str) – Label for the y-axis (typically objective expectation).update_interval_ms (
int) – UI polling interval in milliseconds. If no port is available, the monitor disables itself (not running).
- log(step, objective=None, observables=None, log_data=None)¶
Enqueue a compact scalar payload for the UI.
- Preferred usage:
log(step, objective=(mean, sigma), observables={“E”: (m, s), …})
- Backwards compatible usage:
log(step, log_data={“Loss”: stats_obj, “Obs”: stats_obj, …})
When using log_data, entries are parsed via _as_scalar_stat, only parsable scalar values are forwarded. If monitoring is not running, this method is a no-op.
- Parameters:
step (
int) – Integer optimisation step associated with the payload.objective (
tuple[float,float] |None) – Optional (mean, sigma) pair for the objective/loss.observables (
dict[str,tuple[float,float]] |None) – Optional mapping name -> (mean, sigma) for additional traces.log_data (
dict[str,Any] |None) – Optional legacy mapping name -> Stats-like object to be parsed.
- Return type:
- property is_running: bool¶
Whether the monitor is actively running and accepting updates.
- Returns:
True if a port was successfully bound and UI updates are active, otherwise False.
- shutdown()¶
Stop UI updates and attempt to shut down the Dash/Flask server.
This is best-effort and intentionally non-blocking. It disables updates immediately, then tries a short-timeout HTTP POST to the internal shutdown route, and finally attempts to join the server thread with a short timeout.
- Return type:
- static find_available_port(start_port, max_port)¶
Find the first available TCP port in a given inclusive range.
Ports are tested by attempting to bind a local socket. If binding fails, the search continues until max_port is exceeded.
- property abort_requested: bool¶
Whether the UI has requested an abort of the running simulation.
This flag is set when the user presses the abort button. It is intended to be polled by the training-side callback, which may stop optimisation by returning False to the driver.
- Returns:
True if an abort has been requested, otherwise False.
- class LiveMonitoringCallback(host='127.0.0.1', port=8050, *, objective_label='Constraint')¶
Bases:
objectNetKet callback that streams scalar metrics into a
LiveMonitor.This callback is designed to be registered with a NetKet/neuraLQX driver. On each iteration it extracts a scalar objective statistic and any scalar observables from the driver log, then enqueues them into the live monitor. If the UI requested an abort, it returns False to ask the driver to stop.
- Parameters: