rom.rom_error_est

Purpose: Provides automated computation and visualization of error metrics for comparing full-order and reduced-order model (ROM) solutions stored as flat, non-time-dependent NumPy arrays. Designed for validation, tuning, and publication-quality reporting of ROM accuracy across a set of parametric snapshots.

Summary: Offers three functions covering the complete error analysis workflow for steady-state ROM data: compute_rom_error_metrics_flat for computing a comprehensive set of per-snapshot and global accuracy metrics, generate_rom_error_report for printing a structured human-readable summary, and plot_rom_error_diagnostics_flat for producing diagnostic visualizations including true-vs-ROM scatter plots, spatial field comparisons, and raincloud distributions of errors and speedups. Supports optional energy-norm error assessment when a stiffness matrix is available.

Note: This module targets flat, non-time-dependent data of shape (n_snapshots, n_space). For time-dependent data of shape (n_snapshots, n_time, n_space), use rom.rom_error_est_t.

Author: Suparno Bhattacharyya

Functions

Name	Description
compute_rom_error_metrics_flat	Compute standard error metrics between full-order and ROM solution arrays.
generate_rom_error_report	Print a structured, human-readable summary of ROM error metrics.
plot_rom_error_diagnostics_flat	Generate diagnostic scatter, spatial, and distribution plots for ROM results.

compute_rom_error_metrics_flat

rom.rom_error_est.compute_rom_error_metrics_flat(u, u_rom, K=None)

Purpose: Computes a comprehensive set of error metrics between the full-order solution array u and the ROM reconstruction u_rom, covering per-snapshot diagnostics and global aggregate accuracy measures. When a stiffness matrix K is provided, an additional energy-norm error is computed to assess physically weighted accuracy. Particularly useful for validation, hyperparameter tuning, and formal accuracy reporting.

Parameters

Name	Type	Description	Default
u	array_like, shape (n_snapshots, n_space)	Full-order solution array; each row is one parametric snapshot.	required
u_rom	array_like, shape (n_snapshots, n_space)	ROM reconstruction array with the same shape as `u`.	required
K	array_like, shape (n_space, n_space) or None	Optional stiffness matrix for computing the energy-norm error ( \| e \|_K = ).	`None`

Returns

Name	Type	Description
metrics	dict	Dictionary of computed error metrics, organized as follows.

Per-snapshot metrics (arrays of length n_snapshots):

Key	Description
`L2_error_time`	Absolute L2 norm error per snapshot.
`relative_L2_error_time`	Relative L2 error per snapshot.
`RMSE_time`	Root mean square error per snapshot.
`MAE_time`	Mean absolute error per snapshot.

Global metrics (scalars):

Key	Description
`L2_error`	Global L2 norm error across all snapshots.
`relative_L2_error`	Overall relative L2 error.
`Linf_error`	Maximum absolute error (L∞ norm).
`relative_Linf_error`	Maximum relative error.
`RMSE`	Overall root mean square error.
`MAE`	Overall mean absolute error.
`R2`	R² coefficient of determination.
`explained_variance`	Fraction of total variance captured by the ROM.
`quantiles`	Dictionary with `median_error` and `p95_error` (95th percentile error).
`energy_norm_error`	Energy norm error (only present when `K` is provided).

generate_rom_error_report

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

Purpose: 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'`

Returns

Type	Description
None	Prints the report to standard output; returns no value.

plot_rom_error_diagnostics_flat

rom.rom_error_est.plot_rom_error_diagnostics_flat(
    u,
    u_rom,
    rom_relative_error,
    rom_speed_up,
    sim_axis,
    metrics,
    spatial_shape=None,
)

Purpose: Generates a suite of diagnostic visualizations for comparing full-order and ROM solutions across all parametric snapshots. Produces the following plots:

True vs. ROM scatter plot: Point-by-point comparison of full-order and ROM values, annotated with axis labels from sim_axis.
Spatial snapshot comparison: Side-by-side field plots of the full-order and ROM solutions; when spatial_shape is provided, fields are reshaped into 2D grids for color map visualization.
Raincloud / box / scatter plots: Show the full distribution and spread of per-snapshot relative errors and speedup factors across the test set, combining individual data points, box statistics, and kernel density estimates.

Parameters

Name	Type	Description	Default
u	array_like, shape (n_snapshots, n_space)	Full-order solution array used as ground truth.	required
u_rom	array_like, shape (n_snapshots, n_space)	ROM output array matching `u` in shape.	required
rom_relative_error	array_like, shape (n_snapshots,)	Precomputed relative error, one value per snapshot.	required
rom_speed_up	array_like, shape (n_snapshots,)	Precomputed speedup factor per snapshot (ROM time / FOM time).	required
sim_axis	tuple of str	Two-element tuple `("True label", "ROM label")` used to annotate the scatter plot axes.	required
metrics	dict	Metrics dictionary from `compute_rom_error_metrics_flat`, used to annotate plots with scalar accuracy summaries.	required
spatial_shape	tuple of int or None	Optional shape `(nx, ny)` for reshaping spatial fields into 2D grids for color map visualization.	`None`

Returns

Type	Description
None	Renders plots inline or to the active Matplotlib backend; returns no value.