Skip to content

Commit 8203118

Browse files
cwschillycwschilly
committed
#63: add full write-up to docs
1 parent bd97a12 commit 8203118

File tree

8 files changed

+648
-10
lines changed

8 files changed

+648
-10
lines changed

‎docs/source/build.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,7 @@ Verify the build
3636

3737
.. code-block:: cpp
3838
39-
cd $BUIlDDIR
39+
cd $BUILDDIR
4040
ctest
4141
4242
Then what?

‎docs/source/index.rst‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -39,19 +39,21 @@ Find us on `Slack <https://pressioteam.slack.com>`_.
3939

4040
.. toctree::
4141
:maxdepth: 1
42-
:hidden:
4342

4443
build
45-
Join our Slack <https://pressioteam.slack.com>
46-
GitHub Repo <https://github.com/Pressio/pressio-tutorials>
47-
Open an issue/feature req. <https://github.com/Pressio/pressio-tutorials/issues>
4844
license
4945

46+
.. toctree::
47+
:maxdepth: 0
48+
:hidden:
49+
:caption: 1. Full Tutorial: 1-D Burgers' Equation
50+
51+
./tutorial/overview
5052

5153
.. toctree::
5254
:maxdepth: 0
5355
:hidden:
54-
:caption: 1. End-to-end ROMs using pressio-demoapps
56+
:caption: 2. End-to-end ROMs Using pressio-demoapps
5557

5658
./endtoend/readthisfirst
5759
./endtoend/swe_galerkin_default

‎docs/source/tutorial/background.rst‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
Background
2+
==========
3+
4+
1-D Burgers' Equation
5+
----------------------
6+
7+
The 1-D Burgers' equation is a fundamental partial differential equation
8+
that models various physical phenomena, including fluid dynamics and traffic flow.
9+
It is given by:
10+
11+
.. math::
12+
13+
\frac{\partial u}{\partial t} + u \frac{\partial u}{\partial x} = \nu \frac{\partial^2 u}{\partial x^2}
14+
15+
where :math:`u` is the velocity field, :math:`t` is time, :math:`x` is the spatial coordinate,
16+
and :math:`\nu` is the viscosity coefficient.
17+
18+
While a more comprehensive introduction to the Burgers' equation is beyond the scope of this tutorial,
19+
numerical methods for solving it typically involve discretizing the spatial domain
20+
using finite difference or finite volume methods, and then integrating the resulting
21+
system of ordinary differential equations (ODEs) in time using methods such as
22+
Forward Euler, Runge-Kutta, or implicit schemes.
23+
24+
In this tutorial, we will focus on setting up a reduced-order model (ROM)
25+
for the 1-D Burgers' equation using the Pressio library.

‎docs/source/tutorial/hyperreduction.rst‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
Hyper-Reduction
2+
===============
3+
4+
This tutorial builds off of the information presented in
5+
:doc:`understand` to demonstrate how to set up and run a hyper-reduced
6+
reduced-order model (ROM) for the 1-D Burgers' equation using the Pressio library.
7+
8+
If you have not completed that initial tutorial, please do so before proceeding.
9+
10+
This page will follow the same structure as the previous tutorial,
11+
going through the enumerated steps but only highlighting the differences
12+
needed to implement hyper-reduction.
13+
14+
Step 2: Run the FOM to generate snapshots
15+
-----------------------------------------
16+
17+
In the original tutorial, we defined a ``SnapshotSet``
18+
to collect snapshots for both the ``state`` and the
19+
right-hand side ``rhs`` of the full-order model (FOM).
20+
21+
You may have noticed that the default ROM did not use
22+
the RHS snapshots at all. However, for hyper-reduction,
23+
we will need these RHS snapshots to build the
24+
hyper-reduction basis.
25+
26+
We will explain this further in subsequent steps.
27+
28+
If you are not implementing hyper-reduction, there is no
29+
need to store the RHS snapshots. You can simply return
30+
the state snapshots directly.
31+
32+
Step 3: Build the ROM from the snapshot matrix
33+
----------------------------------------------
34+
35+
A typical ROM uses only the state snapshots to build
36+
the reduced basis via Proper Orthogonal Decomposition (POD).
37+
38+
This reduces the dimensionality of the system, but
39+
we still evaluate the full-order RHS at each time step,
40+
which can be computationally expensive. **Hyper-reduction**
41+
addresses this issue by approximating the RHS using a
42+
reduced basis constructed from the RHS snapshots.
43+
44+
So instead of a reduced state basis alone, we will
45+
also build a reduced basis for the RHS using the
46+
RHS snapshots we collected earlier.
47+
48+
The process begins identically to before: we use the
49+
state snapshots to compute the trial space, and then use
50+
that to get the reduced state. We will also use the same
51+
``ForwardEuler`` time stepper as before.
52+
53+
The key difference is in the definition of a **hyper-reducer**.
54+
55+
The hyper-reducer is a functor that takes in a sampled
56+
FOM RHS vector and projects it into a reduced space.
57+
58+
The process is similar to that of the trial space: we
59+
compute a POD basis from the RHS snapshots using SVD,
60+
and then use that basis to project the FOM RHS onto
61+
a lower-dimensional subspace.
62+
63+
There are refined techniques for selecting which rows
64+
of the RHS to sample, such as the Discrete Empirical
65+
Interpolation Method (DEIM). For simplicity in this tutorial,
66+
we will use a basic sampling approach that selects rows at
67+
a uniform interval (or stride).
68+
69+
Here is a general outline of how the hyper-reducer functor
70+
is defined:
71+
72+
.. code-block:: cpp
73+
74+
auto svdRhs = /* compute SVD of RHS snapshot matrix */;
75+
auto rhsBasis = /* extract leading left singular vectors from SVD */;
76+
77+
auto sampleIndices = /* select sample indices uniformly */;
78+
auto sampledBasis = /* extract rows of rhsBasis at sampleIndices */;
79+
80+
auto trialBasis /* aka Phi */ = trialSpace.basisOfTranslatedSpace();
81+
auto hypredMatrix = /* (Phi^T rhsBasis) * pinv(sampledBasis) */;
82+
83+
// Construct hyperreducer functor
84+
ExplicitGalerkinHyperReducer hyperReducer(hypredMatrix, sampleIndices);
85+
86+
This code is implemented fully in the ``hyperreduction.h`` file
87+
by the ``buildHyperReducer`` function.
88+
89+
The ``ExplicitGalerkinHyperReducer`` above is a
90+
user-defined functor that implements an ``operator()`` method
91+
that takes in a sampled FOM RHS vector and outputs the reduced RHS vector.
92+
93+
Like with the other Pressio interfaces, you can define your
94+
hyperreducer in any way you like, as long as it meets the API requirements.
95+
96+
Now that we have defined the hyper-reducer, we can
97+
build the ROM almost identically to before, but passing
98+
the hyperreducer functor as an additional argument:
99+
100+
.. code-block:: cpp
101+
102+
auto rom = pressio::rom::galerkin::create_default_problem_with_hyperreduction(
103+
stepScheme,
104+
trialSpace,
105+
fom,
106+
hyperReducer
107+
);
108+
109+
Step 4-6: As Before
110+
-------------------
111+
112+
The rest of the steps are identical regardless of whether
113+
you are using hyper-reduction or not. You can refer to the
114+
:doc:`understand` page for details on how to run the ROM,
115+
reconstruct the full-order solution, compare to the FOM,
116+
and examine the output files.

‎docs/source/tutorial/overview.rst‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
End-to-end Tutorial: 1-D Burgers' Equation
2+
==========================================
3+
4+
This tutorial demonstrates how to set up and run a reduced order model (ROM)
5+
for the 1-D Burgers' equation using the Pressio library. The tutorial covers
6+
the following key steps:
7+
8+
1. Setting up the full order model (FOM) and generating snapshots.
9+
2. Constructing the reduced basis using Proper Orthogonal Decomposition (POD).
10+
3. Building both default and hyper-reduced ROMs.
11+
4. Running the ROMs and capturing trajectories.
12+
5. Comparing the ROM solutions with the FOM solution.
13+
6. Writing trajectories to CSV files for further analysis.
14+
15+
The tutorial is implemented in C++ and leverages Pressio's capabilities for
16+
model reduction and time integration.
17+
18+
.. toctree::
19+
:maxdepth: 1
20+
21+
background
22+
start
23+
understand
24+
hyperreduction

‎docs/source/tutorial/start.rst‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
Quick Start
2+
===========
3+
4+
These instructions assume the following env variables
5+
are set:
6+
7+
.. code-block:: bash
8+
9+
export SRC=<path-to-your-cloned-repo>
10+
export BUILD=<path-to-your-build-directory>
11+
12+
The main driver for the tutorial is defined in
13+
``$SRC/full-tutorial/burgers.cpp``.
14+
It is fully commented to help you understand each
15+
step of the implementation.
16+
17+
18+
Additionally, a full discussion of the tutorial can be found
19+
in the :doc:`understand` page.
20+
21+
Build
22+
-----
23+
24+
25+
The full tutorial will build with the rest of the repository.
26+
See :doc:`../build` for instructions. Be sure to install the Python dependencies
27+
listed in ``py_requirements.txt`` in order to use the plotting
28+
utility at the end of the tutorial.
29+
30+
Once you have built the repository, the tutorial will be in
31+
``$BUILD/full-tutorial/burgers``.
32+
33+
.. note::
34+
35+
This tutorial requires C++20 support in your compiler.
36+
37+
Run
38+
---
39+
40+
Run the tutorial with:
41+
42+
.. code-block:: bash
43+
44+
cd $BUILD/full-tutorial
45+
./burgers
46+
47+
This will run the tutorial and generate output files
48+
in the ``output/`` subdirectory.
49+
50+
You can generate plots with the output by running the
51+
python script in the same directory. It is hard-coded
52+
to find the output files in the ``output/`` subdirectory.
53+
54+
.. code-block:: bash
55+
56+
cd $BUILD/full-tutorial
57+
python plot.py
58+
59+
For a detailed breakdown of what you just ran, see
60+
the :doc:`understand` page.

0 commit comments

Comments
 (0)