akhileshmath/energy-stable-rom

This repository is a research pipeline for incompressible-flow reduced-order modeling, centered on a single benchmark: the 2D flow past a cylinder at Reynolds 100. The architecture is stage-based: generate full-order snapshots, compress them with POD, assemble a Galerkin ROM, optionally augment it with a trained neural closure, then evaluate trajectories, energy behavior, and error bounds.

1. Full-order simulation layer

The fem_solver/ package is the high-fidelity PDE backend. It contains mesh generation, boundary-condition setup, Navier–Stokes formulation, time stepping, and snapshot collection. This is the only part that depends directly on the finite-element stack, with DOLFINx, Gmsh, MPI, and standard scientific Python libraries.

2. Snapshot production boundary

The main output of the full-order layer is time-resolved velocity snapshot data saved under data/snapshots/. These snapshots are the interface between the PDE solver and the reduced-order pipeline; downstream components do not solve Navier–Stokes directly.

3. POD basis construction layer

The pod_rom/ package builds the reduced basis from snapshots. pod_basis.py computes the POD modes and singular values, while galerkin_projection.py projects the governing equations into reduced coordinates and assembles the reduced operators. The reduced model is driven by modal coefficients rather than the full velocity field.

4. Reduced-order dynamical core

The ROM state is the vector of POD coefficients a(t). The core reduced dynamics are a Galerkin system with linear viscous terms, nonlinear convective/modal-transfer terms, forcing, and an optional closure term. This is the central mathematical boundary in the repo: everything after POD works in reduced coordinates.

5. Neural closure subsystem

The neural_closure/ package adds a learned correction term to the ROM. architecture.py defines the closure network, and trainer.py handles training. The key architectural constraint is dissipativity in reduced coordinates, so the network is not just predictive; it is constrained to avoid spurious energy growth in the ROM.

6. Training and inference split for closure

The closure model is trained offline from reduced-state data and then injected into a separate ROM rollout. That means the training path and simulation path are distinct: snapshots feed POD, POD feeds reduced trajectories, and reduced trajectories feed closure training. The trained model is then reused in enhanced ROM runs.

7. Analysis and stability layer

The analysis/ package contains error_bounds.py, which computes a posteriori indicators and long-time error estimates. This layer does not change the ROM itself; it post-processes reduced trajectories to evaluate stability, energy behavior, and trajectory deviation. It is conceptually downstream of both the standard ROM and the neural-augmented ROM.

8. Experiment orchestration

The scripts/ directory defines the end-to-end workflow in numbered stages:

• snapshot generation

• POD basis computation

• ROM assembly

• standard ROM run

• neural closure training

• enhanced ROM run

• error-bound computation

• figure generation

run_full_pipeline.sh is the top-level orchestrator. scripts/config_utils.py suggests the scripts are configuration-driven rather than hard-coded.

9. Configuration and reproducibility boundary

configs/default.yaml and configs/cylinder_vortex.yaml provide experiment parameters, with the benchmark-specific config likely overriding the default settings for geometry, discretization, time horizon, and ROM dimensions. This configuration layer is what makes the pipeline reproducible across runs.

10. Persistent artifacts and data flow

The repository stores intermediate and final artifacts in a structured way:

• data/snapshots/ for snapshot arrays and ROM matrices

• results/tables/ for computed summary metrics

• paper/figures/ and paper/tables/ for manuscript-ready outputs

The presence of .npz files in data/snapshots/ indicates the pipeline already materializes reduced operators and POD coefficients for reuse.

11. Reporting and publication layer

The paper/ directory is a complete LaTeX manuscript that consumes outputs from the computational pipeline. Figures and tables generated by the scripts are embedded here, so the paper is effectively a downstream consumer of the numerical workflow rather than part of the solver stack.

12. Repository-level execution model

This is not a service or interactive application; it is a batch scientific computing project. The architecture depends on offline numerical simulation, offline model reduction, offline neural training, and offline analysis/plot generation. The main runtime boundary is between MPI-enabled finite-element simulation and single-process or lighter-weight reduced-model training/evaluation.

Overall, the repo is organized as a one-way scientific pipeline: finite-element snapshots → POD compression → reduced Galerkin operators → optional dissipative neural closure → ROM evaluation and error analysis → figures/tables for the manuscript.