This page provides a list of libROM example applications. For detailed
documentation of the libROM sources, including the examples, see the online
Doxygen documentation or the
doc directory in the distribution. The goal of the example codes is to
provide a step-by-step introduction to libROM in simple model settings.
Select from the categories below to display examples and miniapps that contain
the respective feature. All examples support (arbitrarily) high-order meshes
and finite element spaces. The numerical results from the example codes can
be visualized using the GLVis or VisIt visualization tools. See the GLVis
and VisIt
websites for more details.
Users are encouraged to submit any example codes and miniapps that they have
created and would like to share. Contact a member of the libROM team to report
bugs
or post questions
or comments.
**Application (PDE)**
**Reduced order models type**
**Parameterization type**
**hyper-reduction**
**Physics code**
**Optimization solver**
Poisson Problem
This example code demonstrates the use of libROM and MFEM to define a reduced
order model for a simple isoparametric finite element discretization of the
Poisson problem
$$-\Delta u = f$$ with homogeneous Dirichlet boundary
conditions. The related tutorial YouTube video can be found
here. The example parameterizes the righthand
side with frequency variable, $\kappa$:
$$f =
\cases{
\displaystyle \sin(\kappa (x_0+x_1+x_2)) & for 3D \cr
\displaystyle \sin(\kappa (x_0+x_1)) & for 2D
}$$
The 2D solution contour plot for $\kappa=\pi$ is shown in the figure
on the right to show the effect of $\kappa$. For demonstration, we sample
solutions at $\kappa=\pi$, $1.1\pi$, and $1.2\pi$. Then a ROM is build with basis size
of 3, which is used to predict the solution for $\kappa = 1.15\pi$. The ROM is
able to achieve a speedup of $7.5$ with a relative error of $6.4\times10^{-4}$.
One can follow the command line options below to reproduce the numerical results
summarized in the table below:
The command line option -f defines a frequency of the sinusoidal right hand
side function. The relation between $kappa$ and f is defined as $\kappa = \pi
f$.
FOM solution time
ROM solution time
Speed-up
Solution relative error
0.22 sec
0.029 sec
7.5
6.4e-4
The code that generates the numerical results above can be found in
(poisson_global_rom.cpp)
and the explanation of codes is provided in
here.
The
poisson_global_rom.cpp
is based on
ex1p.cpp from
MFEM with a modification on the right hand side function.
Greedy PROM Poisson Problem
This example code demonstrates physics-informed greedy sampling procedure of
building local PROMs for the Poisson problem. $$-\Delta u = f$$ with
homogeneous Dirichlet boundary conditions.
The example parameterizes
the righthand side with frequency variable, $\kappa$:
$$f =
\cases{
\displaystyle \sin(\kappa (x_0+x_1+x_2)) & for 3D \cr
\displaystyle \sin(\kappa (x_0+x_1)) & for 2D
}$$
A set of local ROMs are built for chosen parameter sample points. The parameter
sample points are chosen through physics-informed greedy procedure, which is
explained in detail by the tutorial YouTube
video. Then the local ROMs are interpolated to
build a tailored local ROM for a predictive case. Unlike the global ROM, the
interpolated ROM has dimension that is the same as the individual local ROM.
For example, one can follow the command line options below to reproduce the
numerical results summarized in the table below:
This particular greedy step generates local PROMs at the following 8 parameter points, i.e., 0.521923, 0.743108, 1.322449, 1.754950, 2.011140, 2.281129, 2.587821, 2.950198.
with a natural insulating boundary condition $\frac{du}{dn}=0$. We linearize
the problem by using the temperature field $u$ from the previous time step to
compute the conductivity coefficient.
One can run the following command line options to reproduce the DMD results
summarized in the table below:
This example demonstrates the parametric DMD on the heat conduction
problem. The initial condition, $u_0(x)$, is
parameterized by the center of circle and the radius, i.e.,
$$u_0(x) =
\cases{
\displaystyle 2 & for |x-c| < r \cr
\displaystyle 1 & for |x-c| $\ge$ r
}$$
One can run the following command line options to reproduce the parametric DMD results
summarized in the table below:
Optimal Control DMD heat conduction with Differential Evolution
This example demonstrates the optimal control heat conduction problem with
greedy parametric DMD and differential evolution. The initial condition,
$u_0(x)$, is parameterized by the center of circle and the radius, i.e.,
$$u_0(x) =
\cases{
\displaystyle 2 & for |x-c| < r \cr
\displaystyle 1 & for |x-c| $\ge$ r
}$$
The goal of the optimal control problem is to find an initial condition that
achieves the target last time step temperature distribution. If it does not
achieve the target, then it should be closest, given the initial condition
parameterization. It is formulated mathematically as an optimization problem:
where $u_T$ denotes the last time step temperature and $u_{target}$ denotes the
target temperature. Note that $u_T$ depends on the initial condition
parameters, i.e., $c$ and $r$. It means that we obtain $u_T$ by solving a
forward heat conduction problem. As you can imagine, it needs to explore the
parameter space and try to find $c$ and $r$ that produces $u_T$ that best
matches $u_{target}$. If each solution process of heat conduction problem is
computationally expensive, the search for the optimal parameter can take a
while. Therefore, we use our parametric DMD to expedite the process and the
search algorithm is done by the differential
evolution.
Here are the steps to solve the optimal control problem. First, you must
delete any post-processed files from the previous differential evolution
run. For example,
rm -rf parameters.txt
rm -rf de_parametric_heat_conduction_greedy_*
Then create parametric DMD using a greedy approach with physics-informed error
indicator:
Then you can generate target temperature field with a specific $r$ and $c$
values. Here we used $r=0.2$, $cx=0.2$, and $cy=0.2$ to generate a target
temperature field. The target temperature field is shown in the picture above (the one on the left).
Therefore, if DMD is good enough, the differential evolution
should be able to find $c$ and $r$ values that are closed to these:
where r, cx, and cy specify the radius, the x and y coordinates of circular initial conditions.
Now you can run the differential evolution using the parametric DMD:
de_parametric_heat_conduction_greedy -r 0.2 -cx 0.2 -cy 0.2 -visit -de -de_f 0.9 -de_cr 0.9 -de_ps 50 -de_min_iter 10 -de_max_iter 100 -de_ct 0.001 (Run interpolative differential evolution to see if target FOM can be matched)
The differential evolution should be able to find the following optimal control parameters: $r=0.2006289125692826$, $cx=0.2077455594628246$, and $0.2025402158388952$, which are very close to the true parameters that were used to generate the targer temperature field. The DMD temperature field at the last time step on this control parameters is shown in the picture above (the one on the right).
with a natural insulating boundary condition $\frac{\partial v}{\partial n}=0$. The
$H(div)$-conforming Raviart-Thomas finite element space is used for the velocity function $\boldsymbol{v}$,
and the $L^2$ finite element space is used for pressure function, $p$.
This example introduces how the hyper-reduction is implemented and how the
reduced bases for two field varibles, $p$ and $\boldsymbol{v}$.
One can run the following command line options to reproduce the DMD results
summarized in the table below:
where $c$ is advection velocity.
The initial condition, $u_0(x)$, is given by
$$u_0(x) =
\cases{
\displaystyle exp\left (-log(2)\frac{(x+7)^2}{0.0009}\right ) & for -0.8 $\le$ x $\le$ -0.6 \cr
\displaystyle 1 & for -0.4 $\le$ x $\le$ -0.2 \cr
\displaystyle 1-|10(x-0.1)| & for 0 $\le$ x $\le$ 0.2 \cr
\displaystyle \sqrt{1-100(x-0.5)^2} & for 0.4 $\le$ x $\le$ 0.6 \cr
\displaystyle 0 & \text{otherwise}
}$$
The DMD is applied to accelerate the advection simulation:
FOM solution time
DMD setup time
DMD query time
3.85 sec
0.18 sec
0.027 sec
The instruction of running this simulation can be found at
the HyPar page, e.g., go to Examples -> libROM Examples -> 1D Linear Advection-Discontinuous Waves.
Advection
For a given initial condition, i.e., $u_0(x) = u(0,x)$,
DG advection solves the time-dependent advection problem:
$$\frac{\partial u}{\partial t} + v\cdot\nabla u = 0,$$
where $v$ is a given advection velocity.
We choose velocity function so that the dynamics form a spiral advection.
One can run the following command line options to reproduce the DMD results
summarized in the table below:
For a given initial condition, i.e., $u_0(x) = u(0,x)$,
DG advection solves the time-dependent advection problem:
$$\frac{\partial u}{\partial t} + v\cdot\nabla u = 0,$$
where $v$ is a given advection velocity.
We choose velocity function so that the dynamics form a spiral advection.
This example illustrates how a parametric PROM can be built through local ROM
interpolation techniques. The following sequence of command lines will let you
build such a parametric PROM, where the frequency of sinusoidal initial
condition function is used as a parameter (its value is passed by a user through -ff command line option).
Two local PROMs are constructed through -offline option with parameter values
of 1.02 and 1.08, then the local PROM operators are interpolated to build a
tailored local PROM at the frequency value of 1.05. Unlike the global ROM, the
interpolated PROM has dimension that is the same as the individual PROM, i.e.,
40 for this particular problem.
$$ \rho = \left ( 1-\frac{(\gamma-1)b^2}{8\gamma \pi^2} e^{1-r^2} \right )^{\frac{1}{r-1}}, p = \rho^\gamma$$
$$ u = u_\infty - \frac{b}{2\pi} e^{\frac{1}{2}(1-r^2)}(y-y_c)$$
$$ v = v_\infty + \frac{b}{2\pi} e^{\frac{1}{2}(1-r^2)}(x-x_c),$$
where $b=0.5$ is the vortex strength and $r = \left ( (x-x_c)^2 + (y-y_c)^2 \right )^{\frac{1}{2}}$ is the distance from the vortex center $(x_c,y_c) = (5,5)$.
The DMD is applied to accelerate the vortex convection simulation:
FOM solution time
DMD setup time
DMD query time
5.85 sec
5.25 sec
0.28 sec
The instruction of running this simulation can be found at
the HyPar page, e.g., go to Examples -> libROM Examples -> 2D Euler Equations - Isentropic Vortex Convection.
is solved. The DMD is applied to accelerate the Riemann problem:
FOM solution time
DMD setup time
DMD query time
111.1 sec
17.6 sec
1.4 sec
The instruction of running this simulation can be found at
the HyPar page, e.g., go to Examples -> libROM Examples -> 2D Euler Equations - Riemann Problem Case 4
Euler equation
For a given initial condition, i.e., $u_0(x) = u(0,x)$,
DG Euler solves the compressible Euler system of equation, i.e., a model
nonlinear hyperbolic PDE:
with a state vector $\boldsymbol{u} = [\rho,\rho v_0, \rho v_1, \rho E]$, where
$\rho$ is the density, $v_i$ is the velocity in the $i$th direction, $E$ is the
total specific energy, and $H = E + p/\rho$ is the total specific enthalpy. The
pressure, $p$ is computed through a simple equation of state (EOS) call. The
conservative hydrodynamic flux $\boldsymbol{F}$ in each direction $i$ is
The DMD is applied to accelerate the cavity flow simulation:
FOM solution time
DMD setup time
DMD query time
554.6 sec
58.6 sec
0.3 sec
The instruction of running this simulation can be found at
the HyPar page, e.g., go to Examples -> libROM Examples -> 2D Navier-Stokes Equations - Lid-Driven Square Cavity
1D-1V Vlasov Equation, Two-Stream Instability
The 1D-1V Vlasov equatoin is solved with the initial condition given by
The DMD is applied to accelerate the cavity flow simulation:
FOM solution time
DMD setup time
DMD query time
11.34 sec
2.30 sec
0.34 sec
The instruction of running this simulation can be found at
the HyPar page, e.g., go to Examples -> libROM Examples -> 2D (1D-1V) Vlasov Equation.
Linear elasticity
This example demonstrates how to apply projection-based ROM to a linear
elasticity problem. The linear elasiticity problem describes a multi-material
cantilever beam. Specifically, the following weak form is solved:
is the stress tensor corresponding to displacement field $\boldsymbol{u}$, and
$\lambda$ and $\mu$ are the material Lame constants. The Lame constants are
related to Young's modulus ($E$) and Poisson's ratio ($\nu$) as
The boundary condition are $\boldsymbol{u}=\boldsymbol{0}$ on the fixed part of the boundary with attribute 1, and $\sigma(\boldsymbol{u})\cdot n = f$ on the remainder with f being a constant pull down vector on boundary elements with attribute 2, and zero otherwise. The geometry of the domain is assumed to be as follows:
Three distinct steps are required, i.e., offline, merge, and online steps, to build global ROM for the linear elasticity problem. The general description of building a global ROM is explained in this YouTube tutorial video. We parameterized Poisson's ratio ($\nu$) from 0.2 to 0.4.
One can run the following command line options to reproduce the DMD results
summarized in the table below:
You can replace 0.XX with any value between 0.2 and 0.5. It must be strictly
less than 0.5. Note that the global ROM is able to predict the point outside of
the training region with high accuracy, i.e., $\nu=0.45$. The table below
shows the performance results for three different parameter points.
where $H$ is a hyperelastic model and $S$ is a viscosity operator of Laplacian
type. The initial displacement is set zero and the initial velocity is set as
zero except the third component which is defined:
$$v_3(0,x) = -\frac{\mu}{80}\sin(\mu x_1)$$
One can run the following command line options to build global ROM and
reproduce the results summarizedin the table below. You can replace XXX in the
fom and online phase to take any $\mu$ value between 3.9 and 4.1:
Laghos (LAGrangian High-Order Solver) is a miniapp that solves the
time-dependent Euler equations of compressible gas dynamics in a moving
Lagrangian frame using unstructured high-order finite element spatial
discretization and explicit high-order time-stepping. LaghosROM introduces
reduced order models of Laghos simulations.
A list of example problems that you can solve with LaghosROM includes Sedov
blast, Gresho vortex, Taylor-Green vortex, triple-point, and Rayleigh-Taylor
instability problems. Below are command line options for each problems and some
numerical results. For each problem, four different phases need to be taken,
i.e., the offline, hyper-reduction preprocessing, online, and restore phase. The
online phase runs necessary full order model (FOM) to generate simulation data.
libROM dynamically collects the data as the FOM simulation marches in time
domain. In the hyper-reduction preprocessing phase, the libROM builds a library
of reduced basis as well as hyper-reduction operators. The online phase runs the
ROM and the restore phase projects the ROM solutions to the full order model
dimension.
Sedov blast problem
Sedov blast problem is a three-dimensional standard shock hydrodynamic
benchmark test. An initial delta source of internal energy deposited at the
origin of a three-dimensional cube is considered. The computational domain is
the unit cube $\tilde{\Omega} = [0,1]^3$ with wall boundary conditions on all
surfaces, i.e., $v\cdot n = 0$. The initial velocity is given by $v=0$. The
initial density is given by $\rho = 1$. The initial energy is given by a delta
function at the origin. The adiabatic index in the ideal gas equations of state
is set $\gamma = 1.4$. The initial mesh is a uniform Catesian hexahedral mesh,
which deforms over time. It can be seen that the radial symmetry is maintained
in the shock wave propagation in both FOM and PROM simulations. One can
reproduce the PROM numerical result, following the command line options
described below:
One can also easily apply time-windowing DMD to Sedov blast problem easily. First, prepare tw_sedov3.csv file, which contains a sequence of time steps, {0.01, 0.02, $\ldots$, 0.79, 0.8 } in a column. Then you can follow the command line options described below:
Gresho vortex problem is a two-dimensional benchmark test for the
incompressible inviscid Navier-Stokes equations. The computational domain is
the unit square $\tilde\Omega = [-0.5,0.5]^2$ with wall boundary conditions on
all surfaces, i.e., $v\dot n = 0$. Let $(r,\phi)$ denote the polar coordinates
of a particle $\tilde{x} \in \tilde{\Omega}$. The initial angular velocity is
given by
$$v_\phi =
\cases{
\displaystyle 5r & for 0 $\leq$ r < 0.2 \cr
\displaystyle 2-5r & for 0.2 $\leq$ r < 0.4 \cr
\displaystyle 0 i & for r $\geq$ 0.4.
}$$
The initial density if given by $\rho=1$. The initial thermodynamic pressure is
given by
$$p = \cases{
5 + \frac{25}{2} r^2 & for 0 $\leq$ r < 0.2 \cr
9 - 4 \log(0.2) + \frac{25}{2} - 20r + 4 \log(r) & for 0.2 $\leq$ r < 0.4 \cr
3 + 4\log(2) & for r $\geq$ 0.4 }$$
Taylor-Green vortex problem is a three-dimensional benchmark test for the
incompressible Navier-Stokes equasions. A manufactured smooth solution is
considered by extending the steady state Taylor-Green vortex solution to the
compressible Euler equations. The computational domain is the unit cube
$\tilde{\Omega}=[0,1]^3$ with wall boundary conditions on all surfaces,
i.e., $v\cdot n = 0$. The initial velocity is given by
The initial energy is related to the pressure and the density by the equation
of state for the ideal gas, $p=(\gamma-1)\rho e$, with $\gamma = 5/3$. The
initial mesh is a uniform Cartesian hexahedral mesh, which deforms over time.
The visualized solution is given on the right. One can reproduce the
numerical result, following the command line options described below:
Triple-point problem is a three-dimensional shock test with two materials in
three states. The computational domain is $\tilde{\Omega} = [0,7] \times [0,3
] \times [0,1.5]$ with wall boundary conditions on all surfaces, i.e.,
$v\cdot n = 0$. The initial velocity is given by $v=0$. The initial density is
given by
$$\rho =
\cases{
\displaystyle 1 & for x $\leq$ 1 or y $\leq$ 1.5, \cr
\displaystyle 1/8 & for x $>$ 1 and y $>$ 1.5
}$$
The initial thermodynamic pressure is given for
$$p =
\cases{
\displaystyle 1 & for x $\leq$ 1, \cr
\displaystyle 0.1 & for x $>$ 1
}$$
The initial energy is related to the pressure and the density by the equation
of state for the ideal gas, $p=(\gamma-1)\rho e$, with
$$\gamma =
\cases{
\displaystyle 1.5 & for x $\leq$ 1 or y $>$ 1.5\cr
\displaystyle 1.4 & for x $>$ 1 and y $\leq$ 1.5
}$$
The initial mesh is a uniform Cartesian hexahedral mesh, which deforms over
time. The visualized solution is given on the right. One can reproduce the
numerical result, following the command line options described below:
