Callbacks and diagnostics¶
Run callbacks¶
ProgressLogger(*, every: int = 1)
Print iteration progress every every completed iterations.
CheckpointEvery(every: int, directory: Path)
Write a resumable checkpoint to directory every every iterations.
CsvLogger(path: Path)
Append iteration, objective, and elapsed time records to a CSV file.
StopOnPlateau(
patience: int, *, minimum_improvement: float = 0.0
)
Stop after objective improvement remains too small for patience records.
minimum_improvement is the nonnegative absolute objective decrease
required to reset the patience counter.
SaveImageEvery(every: int, directory: Path)
Save object amplitude and phase PNG files at an iteration interval.
SavePupilEvery(every: int, directory: Path)
Save pupil amplitude and phase PNG files at an iteration interval.
SaveResidualsEvery(every: int, directory: Path)
Save the current per-frame residual stack at an iteration interval.
IterationCallback(
callable: Callable[[Mapping[str, Any]], object],
*,
every: int = 1,
)
Call Python with a read-only step mapping every every iterations.
The callable may return False to stop or any other object to continue.
The mapping contains iteration, objective, algorithm_metrics,
problem_name, and physical_illumination_calibration. The last value
is an IlluminationCalibrationState snapshot for joint runs and None
for ordinary reconstruction.
Unlike Rust-backed callbacks, this callback reacquires the GIL for each
invocation and therefore has interpreter-crossing overhead.
DiagnosticRecorder(mode: str = 'basic', *, every: int = 1)
Collect structured reconstruction diagnostics entirely in Rust.
mode is one of "minimal", "basic", "debug", or
"simulation". every is the positive iteration-recording interval.
Add the recorder to callbacks and query it after the run.
diagnostics() -> dict[str, Any]
Return a new dictionary containing all records gathered so far.
Diagnostic I/O and reports¶
Diagnostics loading, reporting, and lightweight text summaries.
ensure_output_dir(path: str | Path) -> Path
Create path and missing parents, then return it as a Path.
coerce_diagnostics(
value: Mapping[str, Any] | str | Path,
) -> dict[str, Any]
Copy a diagnostics mapping or load one from a JSON filesystem path.
load_diagnostics(path: str | Path) -> dict[str, Any]
Load a diagnostics JSON object from path.
Raises FileNotFoundError for a missing path and ValueError when the
file is invalid JSON or its top level is not an object.
savefig(path: str | Path, dpi: int = 180) -> None
Save Matplotlib's current figure with tight bounds at dpi resolution.
make_diagnostic_report(
diagnostics: Mapping[str, Any] | str | Path,
output_dir: str | Path = "diagnostic_report",
) -> None
Create available diagnostic plots and text summaries in output_dir.
diagnostics may be a recorder mapping or a JSON path. Plot files whose
required diagnostic section is absent are skipped. Existing files with the
standard report names are replaced.
write_ground_truth_metrics(
diag: dict[str, Any], output_dir: str | Path
) -> None
Write available ground-truth scalars to ground_truth_metrics.txt.
No file is produced when diag has no nonempty ground_truth_metrics
mapping. The output directory is created when needed.
write_summary(
diag: dict[str, Any], output_dir: str | Path
) -> None
Write diagnostic counts, final iteration values, and worst frame to text.
Plotting functions import Matplotlib lazily and return (figure, axes). Install
the plot extra before using them. Diagnostic I/O accepts either a recorder
dictionary or a JSON path where documented.
Matplotlib rendering helpers for reconstruction results and diagnostics.
module-attribute
¶
PlotResult
Matplotlib figure and mapping of stable axis names to axes.
plot_reconstruction(
truth: ndarray,
result: ReconstructionResult,
*,
layout: Sequence[Sequence[str]] | str | None = None,
figsize: tuple[float, float] = (13.0, 7.0),
) -> PlotResult
Plot ground truth, reconstruction, and objective history.
truth is a complex 2D field matching result.object. layout may
be a Matplotlib subplot-mosaic specification containing the required named
axes. Returns the figure and those axes; invalid shapes or layouts raise
ValueError.
plot_convergence(
diagnostics: DiagnosticsData,
*,
figsize: tuple[float, float] = (13.0, 9.0),
) -> PlotResult | None
Plot objective, relative-change, frame, and timing histories.
Returns the figure and named axes, or None when
iteration_diagnostics is absent or empty.
plot_frame_residuals(
diagnostics: DiagnosticsData,
*,
figsize: tuple[float, float] = (13.0, 9.0),
) -> PlotResult | None
Plot residual summaries from the latest recorded iteration.
Returns the figure and named axes, or None when no frame diagnostics
are available.
plot_raw_stack_stats(
diagnostics: DiagnosticsData,
*,
figsize: tuple[float, float] = (13.0, 9.0),
) -> PlotResult | None
Plot per-frame mean, spread, extrema, saturation, and zero counts.
Returns the figure and named axes, or None when
raw_frame_statistics is absent or empty.
plot_fourier_coverage(
diagnostics: DiagnosticsData,
*,
figsize: tuple[float, float] = (8.5, 8.5),
) -> PlotResult | None
Plot shifted pupil disks and illumination NA in Fourier-pixel coordinates.
Returns the figure and a {"coverage": axis} mapping, or None when
coverage centers or the positive pupil radius are unavailable.
plot_crop_indices(
diagnostics: DiagnosticsData,
*,
figsize: tuple[float, float] = (8.5, 8.5),
) -> PlotResult | None
Plot compiled Fourier crop boxes and centers in pixel coordinates.
Returns the figure and a {"crop_indices": axis} mapping, or None
when no valid crop records are available.
plot_residuals_on_fourier_centers(
diagnostics: DiagnosticsData,
*,
figsize: tuple[float, float] = (8.5, 8.5),
) -> PlotResult | None
Map latest normalized frame residuals onto illumination Fourier centers.
Returns the figure and a named axis, or None when coverage or matching
per-frame residuals are unavailable.