GraphicalVisualizer#

class lumopt2.utils.graphical_visualizer.GraphicalVisualizer(panels: List[Panel] | None = None, layout: Tuple[int, int] | None = None, figsize: Tuple[float, float] = (12, 5), update_interval: int = 1, block_on_end: bool = False, save_plots: bool = True, save_dpi: int = 150, filename_prefix: str = 'optimization_plot', show_window: bool = True)#

Callback that visualizes optimization progress with live matplotlib plots.

The visualizer arranges a list of Panel instances on a grid of subplots and dispatches the standard panel lifecycle calls (setup, update, on_optimization_end) on every iteration. Users compose figures by passing any combination of built-in panels (FomPanel, GradientNormPanel, GeometryPanel, MonitorPanel) and their own Panel subclasses.

Parameters:

panelslist of Panel, optional

Panels to render. Panels are laid out on the grid in row-major order: panels[0] goes in the top-left cell, the rest of the first row is filled left-to-right, then the next row, and so on until panels[-1] lands in the bottom-right area. When None (default), a sensible default list is built at on_optimization_start():

FomPanel is always included.
GradientNormPanel is always included; it falls back to an “N/A” title when no gradient data flows in.
GeometryPanel is included only when project.parametrization exposes a callable visualize(ax, params, initial_params) method.

Pass an empty list ([]) to disable plotting entirely while still keeping the visualizer in the callback chain.

layouttuple of int, optional

Explicit (rows, cols) grid. When None (default), an approximately square grid is picked automatically. Must satisfy rows * cols >= len(panels).

figsizetuple of float, optional

Figure size in inches. When layout is None, the height is multiplied by the auto-picked row count so figures with many rows stay readable. When layout is explicit, figsize is used as-is (default: (12, 5)).

update_intervalint, optional

Refresh the figure every N iterations. Set to 1 for live updates; values > 1 reduce overhead on long runs (default: 1).

block_on_endbool, optional

If True, keep the plot window open and block at the end of on_optimization_end() until the user closes it (default: False).

save_plotsbool, optional

If True, save the full figure as a PNG into the project folder after every refresh (default: True).

save_dpiint, optional

DPI used for saved PNGs (default: 150).

filename_prefixstr, optional

Prefix for the saved PNG filenames; the full pattern is {filename_prefix}_iter_{iteration:04d}.png (default: "optimization_plot"). When two or more GraphicalVisualizer instances are active in the same Python session and resolve to the same save folder (e.g. two visualizers attached to the same Optimization without explicit prefixes), the visualizer auto-appends _2, _3, … to the second and later prefixes so the instances do not overwrite each other’s PNGs. A warning is logged whenever such auto-disambiguation kicks in. Pass an explicit unique prefix per visualizer to opt out of the warning entirely.

show_windowbool, optional

If True (default), pop the matplotlib figure on screen and refresh it interactively as the optimization progresses. Set to False to keep the figure offscreen – useful when running headless / batch optimizations with save_plots=True where the user only cares about the saved PNGs. When show_window is False, block_on_end is silently ignored (there is no window to block on).

Attributes:

panelslist of Panel: The panels currently registered on the visualizer. Mutating the list before on_optimization_start() is fine; mutating it later has no effect (the figure is laid out once).
layouttuple of int or None
figsizetuple of float
update_intervalint
block_on_endbool
save_plotsbool
save_dpiint
filename_prefixstr
show_windowbool

Raises:

ValueError: If save_dpi or update_interval is not positive, if layout is not a positive (rows, cols) tuple, or if the layout has fewer cells than panels.
TypeError: If any element of panels is not a Panel instance.

Notes

The plot window updates incrementally during optimization. Closing the window does not stop the optimization; the visualizer simply silently fails to redraw subsequent updates.

Examples

Default visualizer (FOM + gradient norm + geometry where applicable):

>>> visualizer = lmpt.GraphicalVisualizer()

Explicit panel composition:

>>> from lumopt2 import (FomPanel, GradientNormPanel,
...                      GeometryPanel, MonitorPanel)
>>> visualizer = lmpt.GraphicalVisualizer(
...     figsize=(14, 6),
...     layout=(3, 2),
...     panels=[
...         FomPanel(),
...         GradientNormPanel(),
...         GeometryPanel(),
...         MonitorPanel(monitor_name='field_monitor',
...                      result_name='Ey', operation='real'),
...         MonitorPanel(monitor_name='FDTD::ports::port_h_out',
...                      result_name='S', operation='abs^2'),
...     ],
...     save_plots=True,
...     block_on_end=True,
... )

Methods

`GraphicalVisualizer.on_function_eval`(...[, ...])	Record the initial parameter vector on the first evaluation.
`GraphicalVisualizer.on_iteration_end`(...[, ...])	Append history, refresh the figure, and (optionally) save it.
`GraphicalVisualizer.on_iteration_start`(...)	No-op iteration-start hook (kept for symmetry with BaseCallback).
`GraphicalVisualizer.on_optimization_end`(...)	Render the final state, dispatch end hooks, optionally block.
`GraphicalVisualizer.on_optimization_start`(...)	Resolve default panels, set up the figure, configure the save dir.