Merge pull request #64 from Pressio/63-end-to-end-1-d-burgers-equation

#63:  End-To-End 1-D Burgers' Equation

Author: cwschilly

CMakeLists.txt

@@ -62,3 +62,6 @@ set(CMAKE_CXX_EXTENSIONS OFF)
 
 enable_testing()
 add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/end-to-end-roms)
+
+# Build the standalone full tutorial (burgers example)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/full-tutorial)

docs/build_requirements.txt

@@ -1,6 +1,6 @@
-Sphinx==5.0.1
-furo==2022.6.4.1
-myst-parser==0.18.0
+Sphinx>=7.2.0
+furo>=2024.1.29
+myst-parser>=2.0.0
 sphinx-copybutton==0.5.0
 m2r2==0.3.2
 sphinx-design

docs/source/build.rst

@@ -36,7 +36,7 @@ Verify the build
 
 .. code-block:: cpp
 
-   cd $BUIlDDIR
+   cd $BUILDDIR
    ctest
 
 Then what?

docs/source/index.rst

@@ -39,19 +39,21 @@ Find us on `Slack <https://pressioteam.slack.com>`_.
 
 .. toctree::
    :maxdepth: 1
-   :hidden:
 
    build
-   Join our Slack <https://pressioteam.slack.com>
-   GitHub Repo <https://github.com/Pressio/pressio-tutorials>
-   Open an issue/feature req. <https://github.com/Pressio/pressio-tutorials/issues>
    license
 
+.. toctree::
+   :maxdepth: 0
+   :hidden:
+   :caption: 1. Full Tutorial: 1-D Burgers' Equation
+
+   ./tutorial/overview
 
 .. toctree::
    :maxdepth: 0
    :hidden:
-   :caption: 1. End-to-end ROMs using pressio-demoapps
+   :caption: 2. End-to-end ROMs Using pressio-demoapps
 
    ./endtoend/readthisfirst
    ./endtoend/swe_galerkin_default

docs/source/tutorial/background.rst

@@ -0,0 +1,29 @@
+Background
+==========
+
+Reduced-order models (ROMs) can be used to simulate a variety of physical phenomena
+modeled by partial differential equations (PDEs). In this tutorial, we will focus
+on the 1-D Burgers' equation as a representative example.
+
+1-D Burgers' Equation
+----------------------
+
+The 1-D Burgers' equation is a fundamental partial differential equation
+that models various physical phenomena, including fluid dynamics and traffic flow.
+It is given by:
+
+.. math::
+
+   \frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} = \nu \frac{\partial^2 u}{\partial x^2}
+
+where :math:`u` is the velocity field, :math:`t` is time, :math:`x` is the spatial coordinate,
+and :math:`\nu` is the viscosity coefficient.
+
+While a more comprehensive introduction to the Burgers' equation is beyond the scope of this tutorial,
+numerical methods for solving it typically involve discretizing the spatial domain
+using finite difference or finite volume methods, and then integrating the resulting
+system of ordinary differential equations (ODEs) in time using methods such as
+Forward Euler, Runge-Kutta, or implicit schemes.
+
+In this tutorial, we will focus on setting up a reduced-order model (ROM)
+for the 1-D Burgers' equation using the Pressio library.

docs/source/tutorial/hyperreduction.rst

@@ -0,0 +1,127 @@
+Hyper-Reduction
+===============
+
+This tutorial builds off of the information presented in
+:doc:`understand` to demonstrate how to set up and run a hyper-reduced
+reduced-order model (ROM) for the 1-D Burgers' equation using the Pressio library.
+
+If you have not completed that initial tutorial, please do so before proceeding.
+
+This page will follow the same structure as the previous tutorial,
+going through the enumerated steps but only highlighting the differences
+needed to implement hyper-reduction.
+
+First: Why use hyper-reduction?
+-------------------------------
+
+As discussed above, a typical ROM uses only the state snapshots
+to build the reduced basis.
+
+This reduces the dimensionality of the system, but
+we still evaluate the full-order RHS at each time step,
+which can be computationally expensive. **Hyper-reduction**
+addresses this issue by approximating the RHS using a
+reduced basis constructed from the RHS snapshots.
+
+So instead of a reduced state basis alone, we will
+also build a reduced basis for the RHS using the
+RHS snapshots we collected earlier.
+
+With this, we can begin the tutorial.
+
+Steps 0-1: As Before
+--------------------
+
+Setting up Pressio and constructing your FOM is done exactly
+the same, regardless of the type of ROM you will build.
+
+Step 2: Run the FOM to generate snapshots
+-----------------------------------------
+
+In the original tutorial, we defined a ``SnapshotSet``
+to collect snapshots for both the ``state`` and the
+right-hand side ``rhs`` of the full-order model (FOM).
+
+You may have noticed that the default ROM did not use
+the RHS snapshots at all. However, for hyper-reduction,
+we will need these RHS snapshots to build the
+hyper-reduction basis.
+
+We will explain this further in subsequent steps.
+
+If you are not implementing hyper-reduction, there is no
+need to store the RHS snapshots. You can simply return
+the state snapshots directly.
+
+Step 3: Build the ROM from the snapshot matrix
+----------------------------------------------
+
+The process begins identically to before: we use the
+state snapshots to compute the trial space, and then use
+that to get the reduced state. We will also use the same
+``ForwardEuler`` time stepper as before.
+
+The key difference is in the definition of a **hyper-reducer**.
+
+The hyper-reducer is a functor that takes in a sampled
+FOM RHS vector and projects it into a reduced space.
+
+The process is similar to that of the trial space: we
+compute a POD basis from the RHS snapshots using SVD,
+and then use that basis to project the FOM RHS onto
+a lower-dimensional subspace.
+
+There are refined techniques for selecting which rows
+of the RHS to sample, such as the Discrete Empirical
+Interpolation Method (DEIM). For simplicity in this tutorial,
+we will use a basic sampling approach that selects rows at
+a uniform interval (or stride).
+
+Here is a general outline of how the hyper-reducer functor
+is defined:
+
+.. code-block:: cpp
+
+    auto svdRhs = /* compute SVD of RHS snapshot matrix */;
+    auto rhsBasis = /* extract leading left singular vectors from SVD */;
+
+    auto sampleIndices = /* select sample indices uniformly */;
+    auto sampledBasis = /* extract rows of rhsBasis at sampleIndices */;
+
+    auto trialBasis /* aka Phi */ = trialSpace.basisOfTranslatedSpace();
+    auto hypredMatrix = /* (Phi^T rhsBasis) * pinv(sampledBasis) */;
+
+    // Construct hyperreducer functor
+    ExplicitGalerkinHyperReducer hyperReducer(hypredMatrix, sampleIndices);
+
+This code is implemented fully in the ``hyperreduction.h`` file
+by the ``buildHyperReducer`` function.
+
+The ``ExplicitGalerkinHyperReducer`` above is a
+user-defined functor that implements an ``operator()`` method
+that takes in a sampled FOM RHS vector and outputs the reduced RHS vector.
+
+Like with the other Pressio interfaces, you can define your
+hyperreducer in any way you like, as long as it meets the API requirements.
+
+Now that we have defined the hyper-reducer, we can
+build the ROM almost identically to before, but passing
+the hyperreducer functor as an additional argument:
+
+.. code-block:: cpp
+
+    auto rom = pressio::rom::galerkin::create_default_problem_with_hyperreduction(
+        stepScheme,
+        trialSpace,
+        fom,
+        hyperReducer
+    );
+
+Step 4-6: As Before
+-------------------
+
+The rest of the steps are identical regardless of whether
+you are using hyper-reduction or not. You can refer to the
+:doc:`understand` page for details on how to run the ROM,
+reconstruct the full-order solution, compare to the FOM,
+and examine the output files.

docs/source/tutorial/overview.rst

@@ -0,0 +1,24 @@
+End-to-end Tutorial: 1-D Burgers' Equation
+==========================================
+
+This tutorial demonstrates how to set up and run a reduced order model (ROM)
+for the 1-D Burgers' equation using the Pressio library. The tutorial covers
+the following key steps:
+
+1. Setting up the full order model (FOM).
+2. Running the FOM to generate a snapshot matrix.
+3. Building both basic and hyper-reduced ROMs.
+4. Running the ROMs and capturing trajectories.
+5. Comparing the ROM solutions with the FOM solution.
+6. Writing trajectories to CSV files for further analysis.
+
+The tutorial is implemented in C++ and leverages Pressio's capabilities for
+model reduction and time integration.
+
+.. toctree::
+   :maxdepth: 1
+
+   background
+   start
+   understand
+   hyperreduction

docs/source/tutorial/start.rst

@@ -0,0 +1,60 @@
+Quick Start
+===========
+
+These instructions assume the following env variables
+are set:
+
+.. code-block:: bash
+
+   export SRC=<path-to-your-cloned-repo>
+   export BUILD=<path-to-your-build-directory>
+
+The main driver for the tutorial is defined in
+``$SRC/full-tutorial/burgers.cpp``.
+It is fully commented to help you understand each
+step of the implementation.
+
+
+Additionally, a full discussion of the tutorial can be found
+in the :doc:`understand` page.
+
+Build
+-----
+
+
+The full tutorial will build with the rest of the repository.
+See :doc:`../build` for instructions. Be sure to install the Python dependencies
+listed in ``py_requirements.txt`` in order to use the plotting
+utility at the end of the tutorial.
+
+Once you have built the repository, the tutorial will be in
+``$BUILD/full-tutorial/burgers``.
+
+.. note::
+
+   This tutorial requires C++20 support in your compiler.
+
+Run
+---
+
+Run the tutorial with:
+
+.. code-block:: bash
+
+    cd $BUILD/full-tutorial
+   ./burgers
+
+This will run the tutorial and generate output files
+in the ``output/`` subdirectory.
+
+You can generate plots with the output by running the
+python script in the same directory. It is hard-coded
+to find the output files in the ``output/`` subdirectory.
+
+.. code-block:: bash
+
+   cd $BUILD/full-tutorial
+   python plot.py
+
+For a detailed breakdown of what you just ran, see
+the :doc:`understand` page.