rom.rom_error_est_t

Purpose: Provides automated computation and visualization of ROM error metrics for comparing full-order and reduced-order solutions stored as flat (vectorized) NumPy arrays. Supports both steady-state and time-dependent data, with configurable axis layout and a comprehensive set of standard accuracy measures.

Summary: Offers three functions covering the full error analysis workflow: compute_rom_error_metrics_flat for computing a broad set of scalar and time-resolved error metrics, generate_rom_error_report for printing a structured human-readable summary, and plot_rom_param_diagnostics_t for producing diagnostic visualizations including bar charts, boxplots, scatter plots, and raincloud distributions. Together these utilities support publication-quality error reporting, debugging, and iterative ROM improvement.

Notes on Data Shapes

The functions in this module accept solution arrays u (full-order) and u_rom (ROM) in two supported layouts:

(n_snapshots, n_space): Each row is a spatial solution for one parametric sample; for steady-state problems.
(n_snapshots, n_time, n_space): Each entry is a spatial solution at one timestep for one parametric sample; for time-dependent problems.

If your data uses a non-standard axis ordering, use the keyword arguments snapshot_axis, time_axis, and space_axis to specify which array axis corresponds to each dimension.

Functions

Name	Description
compute_rom_error_metrics_flat	Compute a comprehensive set of error metrics between full-order and ROM solutions.
generate_rom_error_report	Print a structured, human-readable summary of ROM error metrics.
plot_rom_param_diagnostics_t	Generate diagnostic plots for parameter- and time-resolved ROM error analysis.

compute_rom_error_metrics_flat

rom.rom_error_est_t.compute_rom_error_metrics_flat(
    u,
    u_rom,
    K=None,
    *,
    snapshot_axis=0,
    time_axis=None,
    space_axis=-1,
    eps=1e-30,
)

Summary: Computes a comprehensive set of error metrics between the full-order solution array u and the ROM solution array u_rom, evaluated across all snapshots and—for 3D arrays—across all timesteps. Supported metrics include L2 norm error, L∞ norm error, RMSE, MAE, R² score, explained variance, quantile statistics, and optionally the energy norm when a stiffness matrix K is provided. For time-dependent data of shape (n_snapshots, n_time, n_space), time-resolved metrics are returned with shape (n_snapshots, n_time) in addition to global aggregates.

Parameters

Name	Type	Description	Default
u	array_like	Full-order solution array of shape `(n_snapshots, n_space)` or `(n_snapshots, n_time, n_space)`.	required
u_rom	array_like	ROM solution array with the same shape as `u`.	required
K	array_like or None	Optional stiffness matrix of shape `(n_space, n_space)` for computing energy-norm errors.	`None`
snapshot_axis	int	Axis index corresponding to the snapshot/parameter dimension; adjust if data layout differs from the default.	`0`
time_axis	int or None	Axis index corresponding to the time dimension; set to `None` for steady-state (2D) data.	`None`
space_axis	int	Axis index corresponding to the spatial dimension; adjust if data layout differs from the default.	`-1`
eps	float	Small regularization value added to denominators to prevent divide-by-zero in relative error computations.	`1e-30`

Returns

Name	Type	Description
metrics	dict	Dictionary of global and (for 3D data) time-dependent error metrics. Time-resolved entries have shape `(n_snapshots, n_time)`.

generate_rom_error_report

rom.rom_error_est_t.generate_rom_error_report(
    metrics,
    name='ROM Accuracy Report',
)

Summary: Prints a clean, well-structured report of all ROM error metrics from the dictionary returned by compute_rom_error_metrics_flat. The output is formatted for readability and is suitable for console logging, log files, or quick diagnostic review during iterative ROM development.

Parameters

Name	Type	Description	Default
metrics	dict	Metrics dictionary returned by `compute_rom_error_metrics_flat`.	required
name	str	Title displayed at the top of the printed report.	`'ROM Accuracy Report'`

plot_rom_param_diagnostics_t

rom.rom_error_est_t.plot_rom_param_diagnostics_t(
    u,
    u_rom,
    *,
    l2_per_param=None,
    speedup_per_param=None,
    param_labels=None,
    eps=1e-16,
    log_error=True,
    use_raincloud=True,
)

Summary: Generates a suite of diagnostic visualizations for ROM solutions stored in arrays of shape (p, t, dof), where p is the number of parameters/snapshots, t is the number of timesteps, and dof is the number of spatial degrees of freedom. The following plots are produced:

Per-parameter error bar chart: Summarizes the aggregate error for each snapshot/parameter.
Per-parameter, per-timestep boxplot: Shows how the error evolves across timesteps for each parameter.
Error vs. speedup scatter plot: Produced when speedup_per_param is provided; visualizes the accuracy–efficiency trade-off.
L2-norm bar plot: Produced when l2_per_param is provided; compares L2 norms across parameters.
Raincloud plots (when use_raincloud=True): Display the full distribution of:
- Per-parameter relative error (rel_err_p)
- Per-parameter, per-timestep relative error grouped by parameter (rel_err_pt)
- Speedup values per parameter (when speedup_per_param is provided)

These visualizations collectively enable identification of poorly performing parameter cases, assessment of temporal error growth, and inspection of the error and speedup distributions across the test set.

Parameters

Name	Type	Description	Default
u	array_like, shape (p, t, dof)	Full-order solution array.	required
u_rom	array_like, shape (p, t, dof)	ROM solution array with the same shape as `u`.	required
l2_per_param	array_like or None	Precomputed L2 norms per parameter; if provided, generates an additional bar plot.	`None`
speedup_per_param	array_like or None	Precomputed speedup values per parameter; if provided, generates the error-vs-speedup scatter plot and raincloud.	`None`
param_labels	sequence of str or None	Labels for each parameter/snapshot used in plot axis annotations.	`None`
eps	float	Small value added to denominators to prevent divide-by-zero when computing plotted error quantities.	`1e-16`
log_error	bool	If `True`, uses logarithmic scaling on error axes.	`True`
use_raincloud	bool	If `True`, generates raincloud distribution plots for errors and speedup in addition to bar and box plots.	`True`