problem_classes.masterclass

Framework for static reduced-order modeling (ROM) in finite element workflows.

Summary: Provides a complete, structured pipeline for both the offline (full-order snapshot generation) and online (ROM evaluation) stages of projection-based reduced-order modeling. Includes a base problem interface, a problem registry with factory access, and built-in support for hyper-reduction methods including DEIM, ECSW, and ECM.

Purpose: To standardize how FEM/ROM problems are defined, registered, and executed—enabling consistent offline data collection, fast online ROM evaluation, and seamless integration of hyper-reduction techniques. The registry pattern makes it straightforward to switch between problem types programmatically, which is especially useful in parameter studies and automated workflows.

Authors: Suparno Bhattacharyya, Ali Hamza Syed Abidi

Classes

Name Description
Problem Abstract base class defining the interface for any FEM/ROM problem.
fom_simulation Offline workflow for full-order snapshot generation and storage.
rom_simulation Online workflow for ROM evaluation, error tracking, and speedup analysis.

Problem

problem_classes.masterclass.Problem()

Summary: Defines the required interface that every parameterized FEM/ROM problem must implement. Users subclass Problem and provide concrete implementations of each method to describe their specific physical problem. This ensures all problem types remain interchangeable within the master class workflows.

Your subclass should provide the following:

  • Mesh construction and finite element basis setup
  • Bilinear and linear forms expressed in affine decomposition (required for ROM assembly)
  • A parameter-to-coefficient mapping describing how parameters modulate the problem
  • A method to sample from the parameter space
  • Full-order and reduced-order solvers
  • Optional hyper-reduced solvers for DEIM, ECSW, and ECM methods

bilinear_forms

problem_classes.masterclass.Problem.bilinear_forms()

Returns all component matrices of the bilinear form (e.g., stiffness contributions) expressed in affine decomposition format, as required for efficient ROM assembly.

domain

problem_classes.masterclass.Problem.domain()

Returns the mesh and finite element bases associated with the problem. This method serves as the primary source of geometric and discretization data.

fom_solver

problem_classes.masterclass.Problem.fom_solver()

Solves the full-order FEM system for a given parameter instance. This is the high-fidelity solver used during the offline stage to generate training snapshots.

hyper_rom_solver_deim

problem_classes.masterclass.Problem.hyper_rom_solver_deim()

Solves the reduced-order system using DEIM (Discrete Empirical Interpolation Method) hyper-reduction, enabling fast nonlinear term approximation during the online stage.

hyper_rom_solver_ecm

problem_classes.masterclass.Problem.hyper_rom_solver_ecm()

Solves the reduced-order system using ECM (Empirical Cubature Method) hyper-reduction, accelerating numerical integration over the reduced mesh.

hyper_rom_solver_ecsw

problem_classes.masterclass.Problem.hyper_rom_solver_ecsw()

Solves the reduced-order system using ECSW (Energy-Conserving Sampling and Weighting) hyper-reduction, preserving physical structure while reducing online cost.

linear_forms

problem_classes.masterclass.Problem.linear_forms()

Returns all component vectors of the linear form (e.g., load and forcing vectors) in affine decomposition format for use in ROM assembly.

parameters

problem_classes.masterclass.Problem.parameters()

Generates a collection of parameter samples from the problem’s parameter space. Used to drive both offline snapshot generation and online ROM testing.

properties

problem_classes.masterclass.Problem.properties()

Returns a function that computes the affine coefficients corresponding to a given parameter instance. These coefficients weight the component matrices and vectors during assembly.

rom_solver

problem_classes.masterclass.Problem.rom_solver()

Solves the reduced-order model for a given parameter, operating in the low-dimensional subspace defined by the projection basis.

fom_simulation

problem_classes.masterclass.fom_simulation(num_snapshots=32)

Summary: Implements the offline stage of the ROM pipeline. Iterates over parameter samples, solves the full-order FEM model for each, and persistently stores the resulting solutions along with timing data. Designed to be fault-tolerant and resumable, making it suitable for long-running snapshot campaigns.

Attributes

Name Type Description
num_snapshots int Number of parameter samples (and corresponding FOM solves) to generate.
param_list array_like The sampled parameter set used for snapshot generation.
fos_solutions list of ndarray Full-order solutions corresponding to each parameter sample.
fos_time list of float Wall-clock solve times recorded for each snapshot.
train_ref ndarray Mean field computed across all snapshots, used as the centering reference for ROM.

run_simulation

problem_classes.masterclass.fom_simulation.run_simulation()

Executes all full-order solves and writes each result to disk as a checkpoint. Key behaviors:

  • Checkpoint files are written atomically in .npz format after each solve.
  • If a valid checkpoint already exists for a given parameter, the solve is skipped and the result is loaded from disk—enabling seamless resumption after interruption or crash.
  • Long parameter-derived filenames are hashed to remain compatible with Windows path length limits.
  • Corrupt or unreadable checkpoints are detected, recomputed, and overwritten automatically.

rom_simulation

problem_classes.masterclass.rom_simulation(
    train_ref=None,
    test_ref=None,
    fos_solutions=None,
    train_mask=None,
    test_mask=None,
    V_sel=None,
    n_sel=None,
    N_rom_snap=None,
)

Summary: Implements the online evaluation stage of the ROM pipeline. Loads precomputed data, selects test parameters, runs the ROM (standard or hyper-reduced), reconstructs full-field solutions where required, and computes error and speedup metrics for performance assessment.

Attributes

Name Type Description
V_sel ndarray Projection basis matrix used to reconstruct full-field solutions from ROM coordinates.
n_sel int Number of ROM modes retained in the projection basis.
param_list_test array_like Parameter samples used for online ROM evaluation.
rom_error list of float Relative errors (%) between ROM and FOM solutions for each test case.
speed_up list of float Ratio of FOM to ROM solve time for each test case, measuring online acceleration.

Methods

Name Description
run_hyper_rom_simulation_deim Evaluate the ROM using DEIM hyper-reduction across all test parameters.
run_hyper_rom_simulation_ecm Evaluate the ROM using ECM hyper-reduction across all test parameters.
run_hyper_rom_simulation_ecsw Evaluate the ROM using ECSW hyper-reduction across all test parameters.
run_rom_simulation Evaluate the standard ROM (no hyper-reduction) across all test parameters.

run_hyper_rom_simulation_deim

problem_classes.masterclass.rom_simulation.run_hyper_rom_simulation_deim(
    z,
    deim_mat,
    sampled_rows,
    full_order=True,
    new_params=None,
)

Evaluates the DEIM hyper-reduced ROM across all test parameters. For each parameter, the hyper-reduced solver is invoked and—if full_order=True—the reduced coordinates are mapped back to the full solution space for error comparison. When new_params is provided, evaluation is restricted to those parameters and error/speedup metrics are not computed.

Parameters
Name Type Description Default
z array_like Weight vector from the DEIM offline workflow. required
deim_mat ndarray DEIM interpolation matrix. required
sampled_rows array_like of int DOF row indices selected by the DEIM procedure. required
full_order bool If True, reconstruct full-field solutions; if False, return reduced coordinates only. True
new_params sequence or None If provided, evaluates only for these parameters and skips error and speedup computation. None
Returns
Name Type Description
hyper_rom_error list of float Relative errors (%) for each test parameter; returned when new_params is not given.
hyper_speed_up list of float FOM-to-ROM speedup ratios; returned when new_params is not given.
hyper_rom_solutions list of ndarray Reconstructed full-field or reduced solutions; returned when new_params is given.

run_hyper_rom_simulation_ecm

problem_classes.masterclass.rom_simulation.run_hyper_rom_simulation_ecm(
    z,
    full_order=True,
    new_params=None,
)

Evaluates the ECM hyper-reduced ROM across test parameters. The ECM weight vector z (of size n_elements × n_q) defines the reduced quadrature rule. Behavior for full_order and new_params follows the same convention as run_hyper_rom_simulation_deim.

Parameters
Name Type Description Default
z array_like ECM element weights of shape (n_elements × n_q). required
full_order bool If True, reconstruct full-field solutions; if False, return reduced coordinates only. True
new_params sequence or None If provided, evaluates only for these parameters and skips error and speedup computation. None
Returns
Name Type Description
hyper_rom_error list of float Relative errors (%) for each test parameter; returned when new_params is not given.
hyper_speed_up list of float FOM-to-ROM speedup ratios; returned when new_params is not given.
hyper_rom_solutions list of ndarray Reconstructed full-field or reduced solutions; returned when new_params is given.

run_hyper_rom_simulation_ecsw

problem_classes.masterclass.rom_simulation.run_hyper_rom_simulation_ecsw(
    z,
    full_order=True,
    new_params=None,
)

Evaluates the ECSW hyper-reduced ROM across test parameters. ECSW element weights are used to construct an energy-conserving reduced integration rule. Behavior for full_order and new_params follows the same convention as the other hyper-ROM methods.

Parameters
Name Type Description Default
z array_like ECSW element weights. required
full_order bool If True, reconstruct full-field solutions; if False, return reduced coordinates only. True
new_params sequence or None If provided, evaluates only for these parameters and skips error and speedup computation. None
Returns
Name Type Description
hyper_rom_error list of float Relative errors (%) for each test parameter; returned when new_params is not given.
hyper_speed_up list of float FOM-to-ROM speedup ratios; returned when new_params is not given.
hyper_rom_solutions list of ndarray Reconstructed full-field or reduced solutions; returned when new_params is given.

run_rom_simulation

problem_classes.masterclass.rom_simulation.run_rom_simulation(
    full_order=True,
    new_params=None,
)

Evaluates the standard (non-hyper-reduced) ROM across test parameters. For each parameter, the ROM solver is invoked in the projection subspace and the solution is optionally lifted back to the full-order space. Error and speedup are computed when no custom parameter set is provided.

Parameters
Name Type Description Default
full_order bool If True, reconstruct full-field solutions; if False, return reduced coordinates only. True
new_params sequence or None If provided, evaluates only for these parameters and skips error and speedup computation. None
Returns
Name Type Description
rom_error list of float Relative errors (%) for each test parameter; returned when new_params is not given.
speed_up list of float FOM-to-ROM speedup ratios; returned when new_params is not given.
rom_solutions list of ndarray Reconstructed full-field or reduced solutions; returned when new_params is given.

Functions

Name Description
assign_properties Retrieve all key callable methods from a problem instance as an ordered tuple.
get_problem Instantiate a registered problem class by its registry key.
register_problem Decorator to register a problem class under a chosen string key.

assign_properties

problem_classes.masterclass.assign_properties(prob)

Extracts and returns an ordered tuple of all primary callable methods from a Problem instance. This is a convenience utility for workflows that need to pass method handles as a single unit.

Parameters

Name Type Description Default
prob Problem An instantiated problem object. required

Returns

Name Type Description
properties tuple Ordered tuple of: (parameters, bilinear_forms, linear_forms, domain, properties, fom_solver, rom_solver, hyper_deim_solver, hyper_ecsw_solver, hyper_ecm_solver)

get_problem

problem_classes.masterclass.get_problem(name)

Looks up the given string key in PROBLEM_REGISTRY and returns a new instance of the corresponding problem class.

Parameters

Name Type Description Default
name str Registry key identifying the desired problem class. required

Returns

Name Type Description
problem_instance Problem A freshly instantiated object of the registered class.

Raises

Type Condition
ValueError Raised if name is not found in PROBLEM_REGISTRY.

register_problem

problem_classes.masterclass.register_problem(name)

A decorator that registers a problem class in PROBLEM_REGISTRY under the specified string key. Once registered, the class can be retrieved by name via get_problem, enabling dynamic problem selection—for example, based on the current working directory name in automated pipelines.

Parameters

Name Type Description Default
name str String key under which the class will be stored in the registry. required

Returns

Name Type Description
deco callable A decorator that stores the decorated class in the registry and returns it unchanged.

Notes

Register all problem classes before invoking get_problem or launching any parallel simulation workflows. The registry supports automatic problem selection by working directory name, making it particularly useful in batch and sweep studies.