MOOSE Workshop - MOOSE Framework

MOOSE Workshop - MOOSE Framework
MOOSE Workshop
How to get stuff done
Table of Contents I
Overview . . . . . . . . . . .
Finite Elements: The MOOSE Way . . . .
The MOOSE Framework . . . . . . .
The Input File . . . . . . . . . .
Mesh Types
. . . . . . . . . .
The Outputs Block
. . . . . . . .
InputParameters and MOOSE Types . . .
Kernels . . . . . . . . . . . .
. . . . . . . . . . .
Boundary Conditions . . . . . . . .
Mesh Adaptivity
. . . . . . . . .
Executioners . . . . . . . . . .
Initial Conditions . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
Auxiliary System . . . . . . . . .
. . . . . . . . .
Functions . . . . . . . . . . .
. . . . . . . . .
Parallel-Agnostic Random Number Generation
. . . . . . . . . .
Testing . . . . . . . . . . . .
MOOSE Modules . . . . . . . . .
2 / 313
Table of Contents II
MOOSE Internal SVN Development
MOOSE External GitHub Development
Visualization Tools
. . . . .
. . . . . . . . .
Custom Actions (Advanced) . . .
TimeSteppers (Advanced)
. . .
Dirac Kernels (Advanced)
. . .
Scalar Kernels (Advanced) . . .
Geometric Search (Advanced) . .
Dampers (Advanced) . . . . .
Discontinuous Galerkin (Advanced)
UserObjects (Advanced) . . . .
MultiApps (Advanced)
. . . .
Transfers (Advanced) . . . . .
Debugging (Advanced) . . . .
3 / 313
MOOSE Overview
Core MOOSE Team
• Derek Gaston
– [email protected]
– @friedmud
• Cody Permann
– [email protected]
– @permcody
• David Andrs
– [email protected]
– @andrsdave
• John Peterson
– [email protected]
– @peterson512
• Andrew Slaughter
– [email protected]
– @aeslaughter98
• Jason Miller
– [email protected]
– @mjmiller96
5 / 313
MOOSE: Multiphysics Object Oriented Simulation
• A framework for solving computational engineering
problems in a well-planned, managed, and coordinated
– Leveraged across multiple programs
• Designed to significantly reduce the expense and time
required to develop new applications
• Designed to develop analysis tools
– Uses very robust solution methods
– Designed to be easily extended and maintained
– Efficient on both a few and many processors
6 / 313
• 1D, 2D and 3D
– User code agnostic of dimension
• Finite Element Based
– Continuous and Discontinuous Galerkin (and Petrov Galerkin)
• Fully Coupled, Fully Implicit
• Unstructured Mesh
– All shapes (Quads, Tris, Hexes, Tets, Pyramids, Wedges, . . . )
– Higher order geometry (curvilinear, etc.)
– Reads and writes multiple formats
• Mesh Adaptivity
• Parallel
– User code agnostic of parallelism
• High Order
– User code agnostic of shape functions
– p-Adaptivity
• Built-in Postprocessing
And much more . . .
7 / 313
MOOSE solves problems that challenge others
Profile of A concentration at 4480 s
Profile of C concentration at 4480 s
Weak coupling – excellent agreement between fully-coupled and operator-split approaches
Strong coupling – better agreement between fully-coupled and the reference solution
8 / 313
MOOSE Ecosystem
4 months
Thermo-mechanics, Chemical, diffusion,
coupled mesoscale
Neutronics, Porous flow, eigenvalue
3 months
4th order phasefield mesoscale
1 month
Porous ReActive Transport
1 month
Geo-mechanics, coupled mesoscale
3 months
Chem. Rxn, Precipitation, Porous Flow
5 weeks
phase field, ZrH precipitation
3 months
9 / 313
Code Platform
• MOOSE is a simulation framework
allowing rapid development of new
simulations tools.
– Specifically designed to simplify
development of multiphysics tools.
Thermal Solid Mechanics Fluid Reac:on Diffusion • Provides an object-oriented,
pluggable system for defining all
aspects of a simulation tool.
– Leverages multiple DOE
developed scientific computational
Mesh Finite Element Method Input / Output • Allows scientists and engineers to
develop state of the art simulation
Solvers Interface
PETSc SNES Trilinos NOX – Maximize Science/$
• Currently ∼64,000 lines of code.
10 / 313
Current MOOSE Architecture
Fluid Flow
Aux Physics
Custom UI
U = x*y + 2
L2 Error
11 / 313
MOOSE Software Quality Practices
• MOOSE currently meets all NQA-1 (Nuclear Quality Assurance Level 1)
• All commits to MOOSE undergo review using GitHub Pull Requests and
must pass a set of application regression tests before they are available to
our users.
• All changes must be accompanied by issue numbers and assessed an
appropriate risk level.
• We maintain a regression test code coverage level of 80% or better at all
• We follow strict code style and formatting guidelines (available on our wiki).
• We monitor code comments with third party tools for better readability.
12 / 313
MOOSE produces results
1. M. Tonks, D. Gaston, P. Millett, D. Andrs, and P. Talbot. An object-oriented finite element framework for multiphysics phase field
simulations. Comp. Mat. Sci, 51(1):20–29, 2012.
2. R. Williamson, J. Hales, S. Novascone, M. Tonks, D. Gaston, C. Permann, D. Andrs, and R. Martineau. Multidimensional Multiphysics
Simulation of Nuclear Fuel Behavior. Submitted J. Nuclear Materials, 2011.
3. M. Tonks, D. Gaston, C. Permann, P. Millett, G. Hansen, C. Newman, and D. Wolf. A coupling methodology for mesoscale-informed
nuclear fuel performance codes. Nucl. Engrg. Design, 240:2877–2883, 2010.
4. D. Gaston, G. Hansen, S. Kadioglu, D. Knoll, C. Newman, H. Park, C. Permann, and W. Taitano. Parallel multiphysics algorithms and
software for computational nuclear engineering. Journal of Physics: Conference Series, 180(1):012012, 2009.
5. M. Tonks, G. Hansen, D. Gaston, C. Permann, P. Millett, and D. Wolf. Fully-coupled engineering and mesoscale simulations of thermal
conductivity in UO2 fuel using an implicit multiscale approach. Journal of Physics: Conference Series, 180(1):012078, 2009.
6. C. Newman, G. Hansen, and D. Gaston. Three dimensional coupled simulation of thermomechanics, heat, and oxygen diffusion in
UO2 nuclear fuel rods. Journal of Nuclear Materials, 392:6–15, 2009.
7. D. Gaston, C. Newman, G. Hansen, and D. Lebrun-Grandie. MOOSE: A parallel computational framework for coupled systems of
nonlinear equations. Nucl. Engrg. Design, 239:1768–1778, 2009.
8. G. Hansen, C. Newman, D. Gaston, and C. Permann. An implicit solution framework for reactor fuel performance simulation. In 20th
International Conference on Structural Mechanics in Reactor Technology (SMiRT 20), paper 2045, Espoo (Helsinki), Finland, August 9–14
9. G. Hansen, R. Martineau, C. Newman, and D. Gaston. Framework for simulation of pellet cladding thermal interaction (PCTI) for fuel
performance calculations. In American Nuclear Society 2009 International Conference on Advances in Mathematics, Computational
Methods, and Reactor Physics, Saratoga Springs, NY, May 3–7 2009.
10. C. Newman, D. Gaston, and G. Hansen. Computational foundations for reactor fuel performance modeling. In American Nuclear Society
2009 International Conference on Advances in Mathematics, Computational Methods, and Reactor Physics, Saratoga Springs, NY, May 3–7
11. D. Gaston, C. Newman, and G. Hansen. MOOSE: a parallel computational framework for coupled systems of nonlinear equations. In
American Nuclear Society 2009 International Conference on Advances in Mathematics, Computational Methods, and Reactor Physics,
Saratoga Springs, NY, May 3–7 2009.
12. L. Guo, H. Huang, D. Gaston, and G. Redden. Modeling of calcite precipitation driven by bacteria-facilitated urea hydrolysis in a flow
column using a fully coupled, fully implicit parallel reactive transport simulator. In Eos Transactions American Geophysical Union,
90(52), Fall Meeting Supplement, AGU 90(52), San Francisco, CA, Dec 14-18 2009.
13. R. Podgorney, H. Huang, and D. Gaston. Massively parallel fully coupled implicit modeling of coupled
thermal-hydrological-mechanical processes for enhanced geothermal system reservoirs. In Proceedings, 35th Stanford Geothermal
Workshop, Stanford University, Palo Alto, CA, Feb 1-3 2010.
14. H. Park, D. Knoll, D. Gaston, and R. Martineau. Tightly Coupled Multiphysics Algorithms for Pebble Bed Reactors. Nuclear Science and
Engineering, 166(2):118-133, 2010.
13 / 313
Finite Elements
The MOOSE way
Polynomial Fitting
• To introduce the idea of finding coefficients to functions, let’s consider
simple polynomial fitting.
• In polynomial fitting (or interpolation) you have a set of points and you are
looking for the coefficients to a function that has the form:
f (x) = a + bx + cx 2 + . . .
• Where a, b and c are scalar coefficients and 1, x, x 2 are “basis functions”.
• The idea is to find a, b, c, etc. such that f (x) passes through the points you
are given.
• More generally you are looking for:
f (x) =
ci x i
• where the ci are coefficients to be determined.
• f (x) is unique and interpolary if d + 1 is the same as the number of points
you need to fit.
• Need to solve a linear system to find the coefficients.
15 / 313
x y
1 4
3 1
4 2
Linear System
   
1 1 1
1 3 9  b = 1
1 4 16
f (x) = 8 −
− 29 
 6
x + x2
16 / 313
Example Continued
• First, note that the coefficients themselves don’t mean anything.
– By themselves they are just numbers.
• Second, the solution is not the coefficients, but rather the function they
create when they are multiplied by their respective basis functions and
• Yes, f (x) does go through the points we were given, but it is also defined
everywhere in between.
• We can evaluate f (x) at the point x = 2 (say) by computing:
f (2) =
ci 2i , or more generically: f (2) =
ci gi (2)
where the ci correspond to the coefficients in the solution vector, and the gi
are the respective functions.
• Finally: Note that the matrix consists of evaluating the functions at the
17 / 313
Finite Elements Simplified
• A method for numerically approximating the solution to Partial Differential
Equations (PDEs).
• Works by finding a solution function that is made up of “shape functions”
multiplied by coefficients and added together.
– Just like in polynomial fitting, except the functions aren’t typically as simple as
x i (although they can be!).
• The Galerkin Finite Element method is different from finite difference and
finite volume methods because it finds a piecewise continuous function
which is an approximate solution to the governing PDE.
– Just as in polynomial fitting you can evaluate a finite element solution anywhere
in the domain.
– You do it the same way: by adding up “shape functions” evaluated at the point
and multiplied by their coefficient.
• FEM is widely applicable for a large range of PDEs and domains.
• It is supported by a rich mathematical theory with proofs about accuracy,
stability, convergence and solution uniqueness.
18 / 313
Weak Form
• Using FE to find the solution to a PDE starts with forming a “weighted
residual” or “variational statement” or “weak form”.
– We typically refer to this process as generating a Weak Form.
• The idea behind generating a weak form is to give us some flexibility, both
mathematically and numerically.
• A weak form is what you need to input into MOOSE in order to solve a new
• Generating a weak form generally involves these steps:
1. Write down strong form of PDE.
2. Rearrange terms so that zero is on the right of the equals sign.
3. Multiply the whole equation by a “test” function (ψ).
4. Integrate the whole equation over the domain (Ω).
5. Integrate by parts (use the divergence theorem) to get the desired derivative
order on your functions and simultaneously generate boundary integrals.
6. Code up with MOOSE . . . and run!
19 / 313
Refresher: The divergence theorem
• Transforms a volume integral into a surface integral:
∇ · F dx =
F · n̂ ds
• In finite element calculations, for example with F = −k (x)∇u, the
divergence theorem implies:
− ψ (∇ · k (x)∇u) dx =
∇ψ · k (x)∇u dx −
ψ (k (x)∇u · n̂) ds
• In this talk, we will use the following inner product notation to represent
integrals since it is more compact:
− (ψ, ∇ · k(x)∇u) = (∇ψ, k (x)∇u) − hψ, k (x)∇u · n̂i
20 / 313
Example: Convection Diffusion
1. −∇ · k∇u + β · ∇u = f
2. −∇ · k∇u + β · ∇u − f = 0
3. −ψ (∇ · k ∇u) + ψ (β · ∇u) − ψf = 0
4. − ψ (∇ · k ∇u) +
ψ (β · ∇u) −
ψf = 0
∇ψ · k∇u −
ψ (k ∇u · n̂) +
ψ (β · ∇u) −
ψf = 0
6. (∇ψ, k ∇u) − hψ, k ∇u · n̂i + (ψ, β · ∇u) − (ψ, f ) = 0
} |
} |
} | {z }
21 / 313
More Depth
• While the weak form is essentially what you need for adding physics to
MOOSE, in traditional finite element software more work is necessary.
• The next step is to discretize the weak form by selecting an expansion of u:
u ≈ uh =
uj φj
– The φj are generally called “shape functions”
– In the expansion of uh , the φj are sometimes called “trial functions”
– Analogous to the x n we used earlier
• The gradient of u can be expanded similarly:
∇u ≈ ∇uh =
uj ∇φj
• In the Galerkin finite element method, the same shape functions are used
for both the trial and test functions
ψ = {φi }Ni=1
22 / 313
More Depth
• Substituting these expansions back into our weak form, we get:
(∇ψi , k ∇uh ) − hψi , k ∇uh · n̂i + (ψi , β · ∇uh ) − (ψi , f ) = 0,
i = 1, . . . , N
• The left-hand side of the equation above is what we generally refer to as
the i th component of our “Residual Vector” and write as Ri (uh ).
23 / 313
Shape Functions
• “Shape Functions” are the functions that get multiplied by coefficients and
added up to form our solution.
• They are akin to the x n functions from polynomial fitting (in fact, you can
use those as shape functions!).
• Typical shape function families: Lagrange, Hermite, Hierarchic, Monomial,
– MOOSE has support for all of these.
• Lagrange are the most common.
– They are interpolary at the nodes.
– This means the coefficients correspond to the values of the functions at the
24 / 313
2D Lagrange Shape Functions
• Some biquadratic basis functions defined on the Quad9 element:
• ψ0 is associated to a “corner” node, it is zero on the opposite edges.
• ψ4 is associated to a “mid-edge” node, it is zero on all other edges.
• ψ8 is associated to the “center” node, it is symmetric and ≥ 0 on the
25 / 313
Numerical Integration
• The only analytical piece left in the weak form are the integrals.
• To allow a computer to numerically compute these integrals we use quadrature
(typically “Gaussian Quadrature”).
• Quadrature approximates continuous integrals by discrete sums:
f (x) ≈
f (x qp )wqp
– Here x qp is the position of the quadrature point, and wqp is the associated weight.
• Under certain common situations, the approximation (1) is exact!
– Ex: In 1 dimension, Gaussian Quadrature can exactly integrate polynomials of order
2n − 1 with n quadrature points.
26 / 313
Numerical Integration
• Note that sampling u for quadrature amounts to:
u(x qp ) ≈ uh (x qp ) =
uj φj (x qp )
∇u(x qp ) ≈ ∇uh (x qp ) =
uj ∇φj (x qp )
• And our weak form becomes:
Ri (uh ) =
wqp ∇ψi (x qp ) · k (x qp )∇uh (x qp )
wqpface ψi (x qpface )k (x qpface )∇uh (x qpface ) · n(x qpface )
wqp ψi (x qp ) (β(x qp ) · ∇uh (x qp ))
wqp ψi (x qp )f (x qp )
27 / 313
Newton’s Method
• We now have a nonlinear system of equations,
Ri (uh ) = 0,
i = 1, . . . , N
to solve for the coefficients uj , j = 1, . . . , N.
• Newton’s method has good convergence properties, we use it to solve this
system of nonlinear equations.
• Newton’s method is a “root finding” method: it finds zeros of nonlinear
• Newton’s Method in “Update Form” for f (x) : R → R
f 0 (xn )δxn+1 = −f (xn )
xn+1 = xn + δxn+1
28 / 313
Newton’s Method Continued
• We don’t have just one scalar equation: we have a system of nonlinear
• This leads to the following form of Newton’s Method:
J(u n )δu n+1 = −R(u n )
u n+1 = u n + δu n+1
• Where J(u n ) is the Jacobian matrix evaluated at the current iterate:
Jij (u n ) =
∂Ri (u n )
• Note that:
X ∂
(uk φk ) = φj
X ∂
∂ (∇uh )
(uk ∇φk ) = ∇φj
29 / 313
Newton For A Simple Equation
• Consider the convection-diffusion equation with nonlinear k , β and f :
−∇ · k∇u + β · ∇u = f
• The i th component of the residual vector is:
Ri (uh ) = (∇ψi , k ∇uh ) − hψi , k ∇uh · n̂i + (ψi , β · ∇uh ) − (ψi , f )
• Using the previously defined rules for
∂(∇uh )
the (i, j) entry of the
Jacobian is then:
Jij (uh ) = ∇ψi ,
∇uh + (∇ψi , k∇φj ) − ψi ,
∇uh · n̂ − hψi , k ∇φj · n̂i
+ ψi ,
· ∇uh + (ψi , β · ∇φj ) − ψi ,
• Note that even for this “simple” equation the Jacobian entries are nontrivial,
especially when the partial derivatives of k , β and f are actually expanded.
• In a multiphysics setting with many coupled equations and complicated
material properties, the Jacobian might be extremely difficult to determine.
30 / 313
Jacobian Free Newton Krylov
• J(u n )δu n+1 = −R(u n ) is a linear system of equations to solve during each
Newton step.
• Lots of choices but we typically employ GMRES (a Krylov subspace
– Scales well in parallel.
– Effective on a diverse set of problems.
• In a Krylov iterative method (such as GMRES) we have the representation:
δu n+1,k = a0 r 0 + a1 Jr 0 + a2 J 2 r 0 + · · · + ak J k r 0
• Note that J is never explicitly needed. Instead, only the action of J on a
vector needs to be computed.
• This action can be approximated by:
Jv ≈
R(u + v ) − R(u)
• This form has many advantages:
– No need to do analytic derivatives to form J
– No time needed to compute J (just residual computations)
– No space needed to store J
31 / 313
Wrap Up
• The Finite Element Method is a way of numerically approximating the
solution to PDEs.
• Just like polynomial fitting, FEM finds coefficients for basis functions.
• The “solution” is the combination of the coefficients and the basis functions,
and just like polynomial fitting the solution can be sampled anywhere in the
• We can numerically find the values of integrals using quadrature.
• Newton’s Method provides a mechanism for solving a system of nonlinear
• The Jacobian Free Newton Krylov (JFNK) method allows us to circumvent
tedious (and error prone) derivative calculations.
32 / 313
The MOOSE Framework
MOOSE Requirements
• MOOSE requires several pieces of software to be in place before it will
Hypre (Optionally if you want to use AMG)
• If you are working on your own workstation you will have to compile / install
all of these.
• We maintain binary builds of these packages for the following operating
– Ubuntu (deb), OpenSUSE (rpm), tarball installer coming soon
– OS X 10.7, 10.8, and 10.9
– Getting Started Instructions
– Issue System
– Documentation, Blog, and Wiki
34 / 313
• Any MOOSE-based application should have the following directory
... (same stuff as src)
35 / 313
Looking at MOOSE
• All classes are separated out into directories associated with that set of
etc. . .
36 / 313
The Input File
The Input File
• By default MOOSE uses a hierarchical, block-structured input file.
• Within each block, any number of name/value pairs can be listed.
• The syntax is completely customizable, or replaceable.
• To specify a simple problem, you will need to populate five or six top-level
• We will briefly cover a few of these blocks in this section and will illustrate
the usage of the remaining blocks throughout this manual.
38 / 313
Main Input File Blocks
• MOOSE expects the following basic blocks for a simple problem:
– [Mesh]
– [Variables]
– [Kernels]
– [BCs]
– [Executioner]
– [Outputs]
39 / 313
Hierarchical Block-Structure
active = ’u v’
order = FIRST
family = LAGRANGE
order = FIRST
family = LAGRANGE
{ active = u v }!
order = FIRST!
family = LAGRANGE!
order = FIRST!
family = LAGRANGE!
40 / 313
The Mesh Block
• The Mesh block is generally associated
# Optional Type
type = <FileMesh | GeneratedMesh>
# FileMesh
file = <filename>
# Some other commonly used options
uniform_refine = <n>
second_order = <true|false>
with an Action that reads and/or
constructs the mesh for the simulation.
• The default type, FileMesh, is
suitable for reading any normal mesh
format from a file.
• The base class MooseMesh can be
extended to construct or modify your
own Meshes during runtime as
• There are additional advanced options
for this and the following blocks which
are not listed in this section. . .
41 / 313
The Variables Block
• The Variables block declares the
order = <FIRST | SECOND | ...>
family = <LAGRANGE | HERMITE | ...>
nonlinear variables that will be solved
for in the simulation.
• The default order and family are FIRST
and LAGRANGE, respectively.
42 / 313
The Kernels Block
• The Kernels block declares PDE
type = <Any Registered Kernel>
variable = <Nonlinear Variable Name>
operators that will be used in the
• The type parameter is used to specify
the type of kernel to instantiate.
43 / 313
The Boundary Conditions Block
• The BCs block declares the boundary
type = <Any Registered BC>
variable = <Nonlinear Variable Name>
conditions that will be used in the
• The type parameter is used to specify
the type of boundary condition to
44 / 313
The Executioner Block
• The Executioner block declares the
type = <Steady | Transient | ...>
executioner that will be used in the
• The type parameter is used to specify
the type of executioner to instantiate.
45 / 313
The Outputs Block
• The Outputs block controls the
file_base = <base_file_name>
exodus = true
console = true
various output (to screen and file) used
in the simulation.
46 / 313
Example Input File
file = mug.e
active = ’diffused’
order = FIRST
family = LAGRANGE
type = Steady
file_base = out
exodus = true
console = true
active = ’diff’
type = Diffusion
variable = diffused
active = ’bottom top’
type = DirichletBC
variable = diffused
boundary = ’bottom’
value = 1
type = DirichletBC
variable = diffused
boundary = ’top’
value = 0
47 / 313
Look at Example 1 (page E3)
48 / 313
Example 1 Output
49 / 313
The Mesh Block and Types
Creating a Mesh
• For complicated geometries, we generally use CUBIT from Sandia National
• CUBIT can be licensed from CSimSoft for a fee depending on the type of
organization you work for.
• Other mesh generators can work as long as they output a file format that
libMesh reads (next slide).
• If you have a specific mesh format that you like, we can take a look at
adding support for it to libMesh.
51 / 313
CUBIT Interface
Boundary Condition
Line Interface
52 / 313
• FileMesh is the default type when the “type” parameter is omitted from the
Mesh section.
• MOOSE supports reading and writing a large number of formats and could
be extended to read more.
.e, .exd
.n, .nem
.xda, .xdr
Tecplot ASCII file
Sandia’s ExodusII format
ACDL’s surface triangulation file
LANL’s GMV (General Mesh Viewer) format
Matlab triangular ASCII file (read only)
GMSH ASCII file (write only)
Sandia’s Nemesis format
Tecplot binary file (write only)
TetGen ASCII file (write only)
Abaqus .inp format (read only)
AVS’s ASCII UCD format
I-deas Universal format
libMesh formats
Visualization Toolkit
53 / 313
Generated Mesh
• type = GeneratedMesh
• Built-in mesh generation is implemented for lines, rectangles, and
rectangular prisms (“boxes”) but could be extended.
• The sides of a GeneratedMesh are named in a logical way (bottom, top,
left, right, front, and back).
• The length, width, and height of the domain, and the number of elements in
each direction can be specified independently.
54 / 313
Named Entity Support
• Human-readable names can be
file = three_block.e
# These names will be applied on the
# fly to the mesh so that they can be
# used in the input file. In addition
# they will be written to the output
# file
block id = ’1 2 3’
block name = ’wood steel copper’
boundary id = ’1 2’
boundary name = ’left right’
assigned to blocks, sidesets and
nodesets. These names will be
automatically read in and can be used
throughout the input file.
• This is typically done inside of Cubit.
• Any parameter that takes entity IDs in
the input file will accept either numbers
or “names”.
• Names can also be assigned to IDs
on-the-fly in existing meshes to ease
input file maintenance (see example).
• On-the-fly names will also be written to
Exodus/XDA/XDR files.
55 / 313
Parallel Mesh
• Useful when the mesh data structure dominates memory usage.
• Only the pieces of the mesh “owned” by processor N are actually stored by
processor N.
• If the mesh is too large to even read in on a single processor, it can be split
prior to the simulation.
– Copy the mesh to a large memory machine (Eos at the INL).
– Use a tool to split the mesh into n pieces (SEACAS, loadbal).
– Copy the pieces to your working directory on the cluster.
– Use the Nemesis reader to read the mesh using n processors.
• See nemesis test.i in the moose test directory for a working
56 / 313
Displaced Mesh
• Calculations can take place in either the initial mesh configuration or the
“displaced” configuration when requested.
• To enable displacements, simply supply a vector of variables representing
displacements for each spatial dimension in the Mesh section:
displacements = ’disp x disp y disp z’
• Once enabled, the parameter use displaced mesh can be set on
individual MooseObjects which will enable them to use displaced
coordinates during calculations:
InputParameters validParams<SomeKernel>()
InputParameters params = validParams<Kernel>();
params.set<bool>("use_displaced_mesh") = true;
return params;
• This can also be set in the input file, but it’s a good idea to do it in code if
you have a pure Lagrangian formulation.
57 / 313
Mesh Modifiers
• [MeshModifiers] perform additional manipulations to a mesh after it has
been set up.
• This can range from adding an additional node set to performing a complex
set of transformations.
• MOOSE has a pluggable system for adding your own modifiers
• Inherit from MeshModifier and implement modify()
• A few built-ins:
– AddExtraNodeset
– SideSetFromNormals, SideSetFromPoints
– Transform - Scale, Rotate, Translate
– MeshExtruder
58 / 313
• type = MeshExtruder
• Takes a 1D or 2D mesh and
extrudes it to 2D or 3D respectively.
• Triangles are extruded to prisms
• Quadrilaterals are extruded to
• Sidesets are extruded and
• Top and bottom sidesets can be
• The extrusion vector should be
specified (direction and length).
Extruded Mesh result from MAMBA courtesy of Michael
59 / 313
The Outputs Block
The Outputs Block
• The output system is like any other system in
MOOSE: modular and expandable.
• It is possible to create multiple output objects
each outputting at different intervals, different
variables, or varying file types.
• Supports ‘short-cut‘ syntax, common
parameters, and sub-blocks
file_base = <base_file_name>
exodus = true
console = true
output_initial = true
vtk = true
type = Console
perf_log = true
type = Exodus
output_initial = false
type = Exodus
file_base = displaced
use_displaced = true
interval = 3
61 / 313
Supported Formats
Short-cut Syntax
Sub-block Type
Console (screen)
Exodus II
console = true
exodus = true
vtk = true
gmv = true
nemesis = true
tecplot = true
xda = true
xdr = true
csv = true
gnuplot = true
checkpoint = true
62 / 313
Over Sampling
• None of the generally available visualization
packages currently display higher-order
solutions (quadratic, cubic, etc.) natively.
• To work around this limitation, MOOSE can
“oversample” a higher-order solution by
projecting it onto a finer mesh of linear
console = true
file_base = out_oversample
type = Exodus
oversample = true
refinements = 3
• Note: This is not mesh adaptivity, nor does it
improve the solution’s accuracy in general.
• The following slide shows a sequence of
solutions oversampled from a base solution on
second-order Lagrange elements.
63 / 313
Over Sampling Refinements: 0 to 5 levels
64 / 313
Over Sampling (Cont.)
• It’s important to note that oversampling will not improve the solution!
• The solution on the left is solved on a “coarse” grid.
• The solution in the center is the same as on the left, but has been
oversampled for visualization purposes.
• The solution on the right is for the same problem, but solved on a finer
mesh (and is therefore closer to the true solution).
65 / 313
Input Parameters and MOOSE
Valid Parameters
• A set of custom parameters (InputParameters) is used to construct
every MOOSE object.
• Every MOOSE-derived object must specify a validParams function.
• In this function you must start with the parameters from your parent class
(like Kernel) and then specify additional parameters.
• This function must return a set of parameters that the corresponding object
requires in order to be constructed.
• This design allows users to control any and all parameters they need for
constructing objects while leaving all C++ constructors uniform and
67 / 313
Defining Valid Parameters
In the .h file:
class Convection;
InputParameters validParams<Convection>();
class Convection : public Kernel
In the .C file:
InputParameters validParams<Convection>()
InputParameters params = validParams<Kernel>(); // Must get from parent
params.addRequiredParam<RealVectorValue>("velocity", "Velocity Vector");
params.addParam<Real>("coefficient", "Diffusion coefficient");
return params;
68 / 313
On the Fly Documentation
• The parser object is capable of generating documentation from the
validParams functions for each class that specializes that function.
• Option 1: Generate a complete tree of registered objects
– CLI option --dump [optional search string]
– The search string may contain wildcard characters
– Searches both block names and parameters
– All parameters are printed for a matching block
• Option 2: Generate a tree based on your input file
– CLI option --show-input
• Option 3: View it online
69 / 313
The InputParameters Object
• The parser and Peacock work with the InputParameters object to read
almost any kind of parameter.
• Built-in types and std::vector are supported via templated methods:
– addRequiredParam<Real>("required const", "doc");
– addParam<int>("count", 1, "doc"); // default supplied
– addParam<unsigned int>("another num", "doc");
– addRequiredParam<std::vector<int> >("vec", "doc");
• Other supported parameter types include:
– Point
– RealVectorValue
– RealTensorValue
– SubdomainID
– BoundaryID
• For the complete list of supported types see
70 / 313
The InputParameters Object (cont.)
• MOOSE uses a large number of string types to make Peacock more
context-aware. All of these types can be treated just like strings, but will
cause compile errors if mixed improperly in the template functions.
• For a complete list, see the instantiations at the bottom of MooseTypes.h
71 / 313
Default and Range-checked Parameters
• You may supply a default value for all optional parameters (not required)
addParam<RealVectorValue>("direction", RealVectorValue(0,1,0), "doc");
• The
following types allow you to supply scalar defaults in place of object:
Any coupled variable
Postprocessors (PostprocessorName)
Functions (FunctionName)
• You may supply an expression to perform range checking within the
parameter system.
• You should use the name of your parameter in the expression.
addRangeCheckedParam<Real>("temp", "temp>=300 & temp<=330", "doc");
• Function Parser Syntax
72 / 313
• MOOSE includes a “smart” enum utility to overcome many of the
deficiencies in the standard C++ enum type.
• It works in both integer and string contexts and is self-checked for
#include "MooseEnum.h"
// The valid options are specified in a comma separated list.
// You can optionally supply the default value as a second argument.
// MooseEnums are case preserving but case-insensitive.
MooseEnum option_enum("first=1, second, fourth=4", "second");
// Use in a string context
if (option_enum == "first")
// Use in an integer context
case 1: ... break;
case 2: ... break;
case 4: ... break;
default: ... ;
73 / 313
Using MooseEnum with InputParameters
• Objects that have a specific set of named options should use a MooseEnum
so that parsing and error checking code can be omitted.
InputParameters validParams<MyObject>()
InputParameters params = validParams<ParentObject>();
MooseEnum component("X, Y, Z"); // No default supplied
params.addRequiredParam<MooseEnum>("component", component,
"The X, Y, or Z component");
return params;
// Assume we’ve saved off our MooseEnum into a instance variable: _component
Real value = 0.0;
if (_component.isValid())
value = _some_vector[ component];
• Peacock will automatically create a drop box when using MooseEnum.
• If the user supplies an invalid option, the parser will automatically catch it
and throw an informative message.
74 / 313
• A “Kernel” is a piece of physics.
– It can represent one or more operators / terms in a PDE.
• A Kernel MUST override computeQpResidual()
• A Kernel can optionally override:
– computeQpJacobian()
– computeQpOffDiagJacobian()
76 / 313
Anatomy of a MOOSE object
#ifndef MYOBJECT_H
#define MYOBJECT_H
#include "BaseClass.h"
class MyObject;
InputParameters validParams<MyObject>();
class MyObject : public BaseClass
MyObject(const std::string & name,
InputParameters params);
virtual SomeType inheritedMethod();
#include "MyObject.h"
InputParameters validParams<MyObject>()
InputParameters params = validParams<BaseClass>();
return params;
MyObject::MyObject(const std::string & name,
InputParameters params):
BaseClass(name, params)
// Do Stuff!
#endif // MYOBJECT_H
77 / 313
(Some) Values Available to Kernels
grad u
– Value and gradient of variable this Kernel is operating on.
grad phi
– Value (φ) and gradient (∇φ) of the trial functions at the q-points.
grad test
– Value (ψ) and gradient (∇ψ) of the test functions at the q-points.
q point
– XYZ coordinates of the current q-point.
– Current shape functions for test and trial functions respectively.
current elem
– Current quadrature point index.
– A pointer to the current element that is being operated on.
• And more!
78 / 313
−∇ · ∇u − f = 0
u|∂Ω1 = g1
∇u · n̂|∂Ω2 = g2
• Multiply by test function, integrate
(−∇ · ∇u, ψi ) − (f , ψi ) = 0
• Integrate by parts
(∇u, ∇ψi ) − (f , ψi ) − hg2 , ψi i = 0
• Jacobian
(∇φj , ∇ψi )
79 / 313
#include "Kernel.h"
class Diffusion;
InputParameters validParams<Diffusion>();
class Diffusion : public Kernel
Diffusion(const std::string & name,
InputParameters params);
virtual Real computeQpResidual();
virtual Real computeQpJacobian();
#endif // DIFFUSION_H
#include "Diffusion.h"
InputParameters validParams<Diffusion>()
InputParameters params = validParams<Kernel>();
return params;
Diffusion::Diffusion(const std::string & name,
InputParameters params):
Kernel(name, params)
return _grad_test[_i][_qp]*_grad_u[_qp];
return _grad_test[_i][_qp]*_grad_phi[_j][_qp];
80 / 313
Kernel Registration
• Before a Kernel is available for use, it must be registered with the
Factory inside your main application .C file (e.g., SomeApp.C).
#include "Diffusion.h"
int SomeApp::registerObjects(Factory & factory)
81 / 313
Convection Diffusion
• In Example 2, we will register and add a new Convection Kernel
• Strong Form:
 −∇ · ∇u + v · ∇u = 0
• Multiply by test function ψi and integrate over the domain:
(−∇ · ∇u, ψi ) + (v · ∇u, ψi ) = 0
• Integrate the first term by parts to get our final weak form:
(∇u, ∇ψi ) − h∇u · n̂, ψi i + (v · ∇u, ψi ) = 0
82 / 313
Look at Example 2 (page E11)
83 / 313
Example 2 Output
84 / 313
Multiphysics Coupling
Multiphysics Coupling – Nonlinear Transient Heat
• Strong form:
− ∇ · k ∇T − q = 0
 ρCp ∂T
• Weak form:
Dirichlet BCs
, ψi + (k ∇T , ∇ψi ) − (q, ψi ) = 0
86 / 313
Multiphysics Coupling – Nonlinear Transient Oxygen
• Strong form:
Dirichlet BCs
− ∇ · D ∇s +
sQ ∗
• Weak form:
, ψi
sQ ∗
+ D ∇s +
87 / 313
Multiphysics Coupling (Steady form)
• Coupled steady heat conduction / steady oxygen diffusion
• Fully coupled nonlinear residual
(k (T , s) ∇T , ∇ψi ) − (q, ψi )
R i (T , s) = 
(D (T , s) (∇s + f (T , s) ∇T ) , ∇ψi )
• Apply JFNK to this residual
88 / 313
Simplified Coupling Example
• Weak forms:
(∇u, ∇ψi ) + (∇v · ∇u, ψi ) = 0
(∇v , ∇ψi ) = 0
• Each “physics” sums into residual
• One-way coupling: u-equation depends on v
89 / 313
Coupling Parameters
• To couple a Kernel (or any other MOOSE object) to other variables you
must declare the coupling in the validParams method:
params.addCoupledVar("temperature", "doc_string");
• You may then specify your coupling in the input file:
order = FIRST
family = LAGRANGE
type = ExampleDiffusion
variable = u
temperature = temp
• Important!
– “temp” is the (arbitrary) name of the variable in the input file
– “temperature” is the name used by the kernel (always the same)
90 / 313
Coupling in Kernels
• The coupling of values and gradients into Kernels is done by calling the
following functions in the initialization list of the constructor:
• These functions return references that you hold onto in the class.
• The references are then used in computeQpResidual() /
91 / 313
Default Coupling Parameters
• To aid in rapid development, debugging, and flexibility, MOOSE allows you
to supply default scalar values where you might expect a coupled value.
params.addCoupledVar("temperature", 300, "doc_string");
• If a variable is not supplied through the input file, a properly sized variable
containing the default value will be made available to you at each
integration point in your domain.
• Additionally, you may also supply a Real value in the input file in lieu of a
coupled variable name.
• Consider using this feature to decouple your non-linear problems for
92 / 313
Convection.h / .C
#include "Convection.h"
#include "Kernel.h"
class Convection;
InputParameters validParams<Convection>();
class Convection : public Kernel
Convection(const std::string & name,
InputParameters parameters);
virtual Real computeQpResidual();
virtual Real computeQpJacobian();
VariableGradient &
grad some variable;
InputParameters validParams<Convection>()
InputParameters params = validParams<Kernel>();
params.addRequiredCoupledVar("some variable", "Doc");
return params;
Convection::Convection(const std::string & name,
InputParameters parameters):
Kernel(name, parameters),
_grad_some_variable(coupledGradient("some variable"))
Real Convection::computeQpResidual()
return _test[_i][_qp]*( grad some variable[ qp]*_grad_u[_qp]);
Real Convection::computeQpJacobian()
return _test[_i][_qp]*( grad some variable[ qp]*_grad_phi[_j][_qp]);
93 / 313
Look at Example 3 (page E19)
94 / 313
Example 3 Output
95 / 313
Example 3: 1D exact solution
• A simplified 1D analog of this problem is given by
d 2u
dx 2
u(0) = 0
u(1) = 1
ε = 0.1
ε = 0.01
• The exact solution
to this problem is
exp x − 1
exp 1 − 1
96 / 313
Kernel Inheritance
97 / 313
Boundary Conditions
Boundary Condition
• A BoundaryCondition provides a residual (and optionally a Jacobian)
on a side of a domain.
• The
structure is very similar to kernels
computeQpResidual / Jacobian()
• The only difference is that some BCs are NOT integrated over the
boundary... and instead specify values on boundaries (Dirichlet).
• IntegratedBCs inherit from IntegratedBC.
• Non-integrated BCs inherit from NodalBC.
99 / 313
(Some) Values Available to BCs
Integrated BCs:
• u, grad u: Value and gradient of variable this BC is
operating on.
phi, grad phi: Value (φ) and gradient (∇φ) of the trial
functions at the q-points.
test, grad test: Value (ψ) and gradient (∇ψ) of the test
functions at the q-points.
Non-Integrated BCs:
boundary id
current node: A pointer to the
current node that is being operated on.
And more!
q point: XYZ coordinates of the current q-point.
i, j: Current shape function indices for test and trial
functions respectively.
qp: Current quadrature point index.
normals: Normal vector at the current quadrature point.
boundary id: The boundary ID this BC is currently
computing on.
current elem: A pointer to the element that is being
computed on.
current side: The side number of current elem that is
currently being computed on.
100 / 313
Coupling and BCs
• The coupling of values and gradients into BCs is done the same way as in
kernels and materials:
101 / 313
Dirichlet BCs
• Set a condition on the value of a variable on a boundary.
• Usually... these are NOT integrated over the boundary.
• Non-integrated BCs can’t provide a Jacobian!
u = g1
on ∂Ω1
u − g1 = 0
• In the following example:
u = αv
on ∂Ω2
And therefore:
u − αv = 0
on ∂Ω2
102 / 313
CoupledDirichletBC.h / .C
#include "NodalBC.h"
//Forward Declarations
class CoupledDirichletBC;
InputParameters validParams<CoupledDirichletBC>();
class CoupledDirichletBC : public NodalBC
CoupledDirichletBC(const std::string & name,
InputParameters parameters);
virtual Real computeQpResidual();
Real _alpha;
VariableValue & _some_var_val;
#include "CoupledDirichletBC.h"
InputParameters validParams<CoupledDirichletBC>()
InputParameters params = validParams<NodalBC>();
params.addParam<Real>("alpha", 0.0, "Doc");
params.addRequiredCoupledVar("some_var", "Doc");
return params;
CoupledDirichletBC(const std::string & name,
InputParameters parameters) :
NodalBC(name, parameters),
return _u[_qp] - _alpha*_some_var_val[_qp];
103 / 313
Integrated BCs
• Integrated BCs (including Neumann BCs) are actually integrated over the
external face of an element.
• Their residuals look similar to kernels:
(∇u, ∇ψi ) − (f , ψi ) − h∇u · n̂, ψi i = 0
∇u · n̂ = g1 on ∂Ω
(∇u, ∇ψi ) − (f , ψi ) − hg1 , ψi i = 0
• Also note that if ∇u · n̂ = 0 then the boundary integral is zero (sometimes
known as the “natural boundary condition”).
• In the following example, g1 = αv .
104 / 313
Look at Example 4 (page E25)
105 / 313
106 / 313
Periodic BCs
• Periodic boundary conditions are useful for modeling quasi-infinite domains
and systems with conserved quantities.
• MOOSE has full support for Periodic BCs
– 1D, 2D, and 3D.
– With mesh adaptivity.
– Can be restricted to specific variables.
– Supports arbitrary translation vectors for defining periodicity.
107 / 313
Periodic BCs
variable = u
# Works for any regular orthogonal
# mesh with defined boundaries
auto_direction = ’x y’
• Normal usage: with an
axis-aligned mesh, use
auto direction to supply the
coordinate directions to wrap.
• Advanced usage: specify a
translation or transformation
primary = 1
secondary = 4
transform_func = ’tr_x tr_y’
inv_transform_func = ’itr_x itr_y’
variable = u
primary = ’left’
secondary = ’right’
translation = ’10 0 0’
108 / 313
Periodic BCs Output
109 / 313
• h-Adaptivity attempts to cluster mesh in areas of relatively high error in an
effort to better capture the solution.
• The idea is to put more DOFs where the error is highest... not wasting
effort anywhere the solution is already well captured.
• This is achieved through refinement (splitting cells into smaller cells) and
coarsening (undoing refinement to create larger elements).
• In order to know where to refine, an Indicator must be employed.
– These attempt to report the relative error in each cell.
• Next, a Marker is utilized to decide which cells to refine and which to
• This process can be repeated for steady state solves, or done every time
step during a transient simulation.
111 / 313
Refinement Patterns
• MOOSE employs “self-similar”,
isotropic refinement patterns.
• When an element is marked for
refinement it is split into elements
of the same type.
• For example, when using Quad4
elements, four “children” elements
are created when the element is
• Coarsening happens in reverse,
removing children to get back to
the “parent” element.
• The original mesh starts at
refinement level “0”.
• Every time an element is split, its
children gain a refinement level.
112 / 313
• Indicators attempt to report a relative amount of
“error” for each element.
• Built-in Indicators include:
– GradientJumpIndicator: Jump in the
gradient of a variable across element edges
(pictured to the right). A good “curvature”
indicator that works well over a wide range of
– FluxJumpIndicator: Same as
GradientJump except it can multiply by a scalar
diffusivity (like thermal conductivity) to
compute the real “flux” jump.
– LaplacianJumpIndicator: Jump in the
second derivative of a variable. Only useful for C 1
shape functions.
– AnalyticIndicator: Computes the difference
between the finite element solution and a given
Function that usually represents the analytic
solution to the problem.
Elem Error 1 1.2 2 5.7 3 4.5 • In higher dimensions, the gradient jump is integrated
around element edges to find contributions to each
connected element.
113 / 313
• After an Indicator has computed the error for each
element, a decision to refine or coarsen elements must
be made.
• The Marker class is used for this purpose. Built-in
Markers include:
– ErrorFractionMarker: Selects elements
based on how much each element contributes to
the total error (pictured to right).
– ErrorToleranceMaker: Refine if error over a
specified value. Coarsen if under.
– ValueThresholdMarker: Refine if variable
value is above a specific value. Coarsen if under.
– UniformMarker: Refine or coarsen all
– BoxMarker: Refine or coarsen inside or outside
a given box.
– ComboMarker: Combine several Markers into
Elem Error 7 27 9 20 6 12 1 8 4 6 8 5 10 5 2 4 3 2 Refine
Total:89 • Markers produce an element field that can be viewed
in your visualization utility.
• Custom Markers are easy to create by inheriting from
the Marker base class.
114 / 313
Input File Syntax
• To enable adaptivity, create an
marker = errorfrac
steps = 2
type = GradientJumpIndicator
variable = convected
type = ErrorFractionMarker
refine = 0.5
coarsen = 0
indicator = error
Adaptivity block.
• The Adaptivity block itself has
several parameters:
– marker: (Optional) Name of the
Marker to use. If not set, no mesh
adaptivity will be done.
– steps: Number of refinement steps to
do in a steady state calculation.
Ignored in transient.
• Adaptivity has two sub-blocks:
Indicators and Markers. Within
these blocks, you can specify multiple
Indicators and Markers that will
be active in the simulation.
115 / 313
Look at Example 5 (page E39)
116 / 313
Initial grid
117 / 313
Adaptivity Steps
118 / 313
Example 5 Output
119 / 313
Built-in Executioners
• There are two main types of Executioners: Steady and Transient.
• MOOSE provides a number of built-in executioners, but you can extend this
system and add your own.
121 / 313
Steady-state Executioner
• Steady-state executioners generally solve the nonlinear system just once.
• However, our steady-state executioner can solve the nonlinear system
multiple times while adapting the mesh to better fit the solution as was seen
in the previous example.
122 / 313
Some Common Options for All Executioners
• There a number of options that appear in the executioner block that control
the solver. The best way to view these is through peacock. Here are a few
common options:
l tol
l max its
nl rel tol
nl max its
Linear Tolerance
Max Linear Iterations
Nonlinear Relative Tolerance
Max Nonlinear Iterations
123 / 313
Transient Executioners
• Transient executioners solve the nonlinear system at least once per time
• Frequently used options Transient Executioners
num steps
start time
end time
Starting time step size
Number of time steps
The start time of the simulation
The end time of the simulation
Time integration scheme (discussed next)
124 / 313
Transient Analysis
• Currently MOOSE includes support for these TimeIntegrator objects:
1. Backward Euler
2. BDF2
3. Crank-Nicolson
4. Implicit-Euler
5. Explicit-Euler
• Each one of these supports adaptive time stepping.
• They are treated as TimeDerivative kernels for the time derivative
terms that appear in PDEs:
− ∇ · ∇u + v · ∇u = 0
, ψi
+ (∇u, ∇ψi ) − h∇u · n̂, ψi i + (v · ∇u, ψi ) = 0
125 / 313
Custom Time Kernel
• If you need to provide a coefficient to the transient term (such as
density*specific heat for heat conduction) inherit from one of the
TimeDerivative kernels that are in MOOSE.
• In computeQpResidual/Jacobian() multiply your coefficient by
126 / 313
Custom Time Kernel
#include "ExampleTimeDerivative.h"
InputParameters validParams<ExampleTimeDerivative>()
InputParameters params = validParams<TimeDerivative>();
params.addParam<Real>("time_coefficient", 1.0, "Time Coefficient");
return params;
ExampleTimeDerivative::ExampleTimeDerivative(const std::string & name,
InputParameters parameters):
TimeDerivative(name, parameters),
// This kernel expects an input parameter named "time_coefficient"
return _time_coefficient*TimeDerivative::computeQpResidual();
return _time_coefficient*TimeDerivative::computeQpJacobian();
127 / 313
Transient Input Syntax
• Add appropriate time derivative Kernels.
• Switch your executioner type to “Transient”
• Add a few required parameters to the Executioner block
Real time:
Real dt:
int t step:
string scheme:
The start time for the simulation.
The initial time step size.
The initial time step
Time integrator scheme
– ’crank-nicolson’
– ’backward-euler’ – default if you do not specify the scheme
– ’bdf2’
128 / 313
Convergence Rates
• Test problem:
− ∇ · ∇u − f = 0 in Ω
where f is chosen so the exact solution is given by u = t 3 (x 2 + y 2 ).
129 / 313
Adaptive Time Step
• Set TimeStepper type to DT2
• Algorithm
– Takes a time step of size dt to get ûn+1 from un
– Takes two time steps of length dt/2 to get un+1 from un
– Calculate local relative time discretization error estimate
ên ≡
||un+1 − ûn+1 ||2
max(||un+1 ||2 , ||ûn+1 ||2 )
– Obtain global relative time dicretization error estimate en ≡ êdtn
– Adaptivity is based on target error tolerance eTOL and a maximum acceptable
error tolerance eMAX .
• If we achieve en < eMAX , then we continue with a new time step size
eTOL 1/p
dtn+1 ≡ dtn ·
where p is the global convergence rate of the time stepping scheme.
• If we do not achieve en < eMAX , or if the nonlinear solver fails, we reject the time
step and shrink dt.
• Parameters eTOL and eMAX can be specified in the input file as e tol and
e max (in the Executioner block).
130 / 313
Look at Example 6 (page E45)
131 / 313
Watch the Movie Using Paraview On a Laptop.
132 / 313
Initial Conditions
Initial Condition System
• Allows for creation of arbitrary initial conditions.
– Can be spatially dependent.
• Allows for selection of initial condition from input file.
• If using an ExodusII mesh you can read the value of a variable from a
previous simulation
• Allows initial conditions to be coupled together
– Automatic dependency resolution
134 / 313
Base Class
• value(const Point & p)
– Returns the value the variable should have at point p.
– All InitialCondition classes MUST override this!
135 / 313
#include "InitialCondition.h"
class ExampleIC;
InputParameters validParams<ExampleIC>();
class ExampleIC : public InitialCondition
ExampleIC(const std::string & name,
InputParameters parameters);
#include "ExampleIC.h"
InputParameters validParams<ExampleIC>()
InputParameters params = validParams<InitialCondition>();
params.addRequiredParam<Real>("coefficient", "A coef");
return params;
ExampleIC::ExampleIC(const std::string & name,
InputParameters parameters):
InitialCondition(name, parameters),
virtual Real value(const Point & p);
Real _coefficient;
#endif //EXAMPLEIC_H
ExampleIC::value(const Point & p)
// 2.0 * c * |x|
return 2.0*_coefficient*std::abs(p(0));
136 / 313
Using ExampleIC
Now Register It:
#include "ExampleIC.h"
And use it in an input file:
type = ExampleIC
variable = u
coefficient = 2.0
block = 1
type = ExampleIC
variable = u
coefficient = 10.0
block = 2
137 / 313
Initial Condition Shortcut Syntax
Constant Initial Conditions
“Restart” from an existing solution
active = ’u’
active = ’u’
order = FIRST
family = LAGRANGE
# For simple constant ICs
initial condition = 10
order = FIRST
family = LAGRANGE
# For reading a solution
# from an ExodusII file
initial from file var = diffused
initial from file timestep = 2
138 / 313
Look at Example 7 (page E53)
139 / 313
Example 7 Output
(a) t = 0
(b) t = 1
140 / 313
• Material objects declare coefficients for use by kernels.
• Use declareProperty<TYPE>() to declare a material property
• One virtual to override: computeQpProperties()
– Compute all of the declared properties at one quadrature point.
• Can use coupled variables using the same functions that Kernel uses. (like
coupledValue() et al.)
• To use a material property use getMaterialProperty<TYPE>() in a
142 / 313
Example 8 Overview
• This is a convection-diffusion problem with a non-linear material property.
• The ExampleDiffusion kernel uses a coefficient produced from a
linearly interpolated tabulated Material property.
• The ExampleMaterial object couples in the gradient of the “diffused”
variable and uses it to make a gradient material property that will be
coupled into the “convected” variable.
• The Convection kernel uses the gradient material property as a velocity
143 / 313
#include "Material.h"
#include "LinearInterpolation.h"
//Forward Declarations
class ExampleMaterial;
InputParameters validParams<ExampleMaterial>();
class ExampleMaterial : public Material
ExampleMaterial(const std::string & name,
InputParameters parameters);
virtual void computeQpProperties();
MaterialProperty<Real> & diffusivity;
MaterialProperty<RealGradient> & conv vel;
// Nonlinear coupling
VariableGradient & diffusion gradient;
// Table data property
LinearInterpolation piecewise func;
#include "ExampleMaterial.h"
InputParameters validParams<ExampleMaterial>()
InputParameters params = validParams<Material>();
params.addRequiredParam<std::vector<Real> >("independent_vals", "");
params.addRequiredParam<std::vector<Real> >("dependent_vals", "");
params.addCoupledVar("diffusion_gradient", "Doc");
return params;
ExampleMaterial::ExampleMaterial(const std::string & name,
InputParameters parameters):
Material(name, parameters),
// Declare that this material is going to provide a Real prop
// Declare that this material is going to provide a RealGradient
conv vel(declareProperty<RealGradient>("convection velocity")),
// Get the reference to the variable coupled into this Material
diffusion gradient(isCoupled("diffusion gradient") ?
coupledGradient("diffusion gradient") :
grad zero),
piecewise func(getParam<std::vector<Real> >("independent vals"),
getParam<std::vector<Real> >("dependent vals"))
// sample the function using the z coordinate
_diffusivity[_qp] = _piecewise_func.sample(_q_point[_qp](2));
_conv_vel[_qp] = _diffusion_gradient[_qp];
144 / 313
ExampleDiffusion.h/.C with Material Property
#include "Diffusion.h"
//Forward Declarations
class ExampleDiffusion;
InputParameters validParams<ExampleDiffusion>();
class ExampleDiffusion : public Diffusion
ExampleDiffusion(const std::string & name,
InputParameters parameters);
virtual Real computeQpResidual();
virtual Real computeQpJacobian();
MaterialProperty<Real> & diffusivity;
#include "ExampleDiffusion.h"
InputParameters validParams<ExampleDiffusion>()
InputParameters params = validParams<Diffusion>();
return params;
ExampleDiffusion::ExampleDiffusion(const std::string & name,
InputParameters parameters):
return diffusivity[ qp]*Diffusion::computeQpResidual();
return diffusivity[ qp]*Diffusion::computeQpJacobian();
145 / 313
Convection.h/.C with Material Property
#include "Convection.h"
InputParameters validParams<Convection>()
InputParameters params = validParams<Kernel>();
return params;
#include "Kernel.h"
class Convection;
InputParameters validParams<Convection>();
class Convection : public Kernel
Convection::Convection(const std::string & name,
InputParameters parameters) :
Kernel(name, parameters),
// Retrieve a gradient material property to use for
// the convection velocity
("convection velocity"))
Convection(const std::string & name,
InputParameters parameters);
virtual Real computeQpResidual();
virtual Real computeQpJacobian();
Real Convection::computeQpResidual()
return _test[_i][_qp]*(_velocity[_qp]*_grad_u[_qp]);
MaterialProperty<RealGradient> &
Real Convection::computeQpJacobian()
return _test[_i][_qp]*(_velocity[_qp]*_grad_phi[_j][_qp]);
146 / 313
Look at Example 8 (page E59)
147 / 313
Example 8 Output
148 / 313
Material Property Output
• Material properties may be automatically output via the input file.
– outputs = none
Disables outputting of all properties to all possible outputs (default)
– outputs = all
Enables outputting of all properties to all possible outputs
– outputs = ’exodus’
Enables outputting of all properties to the output named “exodus” from the
“[Outputs]” block
– output properties = ’property1 property2’
Limits the output to the properties listed
• Supported types include: Real, RealVectorValue, and
149 / 313
Stateful Material Properties
• It can sometimes be useful to have properties at quadrature points that
have old values.
• This situation often arises in solid mechanics for constitutive models like
• Traditionally this type of value is called a “state variable”.
• In MOOSE they are “Stateful Material Properties”. . . i.e. material properties
that have old values.
• To provide a material property with an old state just use
declarePropertyOld<TYPE>() and
declarePropertyOlder<TYPE>() passing in the same name as you
did with declareProperty<TYPE>().
• This will use more memory.
150 / 313
Stateful ExampleMaterial
#include "Material.h"
//Forward Declarations
class ExampleMaterial;
InputParameters validParams<ExampleMaterial>();
* Example material class that defines a few properties.
class ExampleMaterial : public Material
ExampleMaterial(const std::string & name,
InputParameters parameters);
#include "ExampleMaterial.h"
InputParameters validParams<ExampleMaterial>()
InputParameters params = validParams<Material>();
params.addParam<Real>("initial_diffusivity", 1.0, "Doc");
return params;
ExampleMaterial::ExampleMaterial(const std::string & name,
InputParameters parameters):
Material(name, parameters),
// Get a parameter value for the diffusivity
// Declare that this material is going to have a Real
// valued property named "diffusivity" that Kernels can use.
virtual void computeQpProperties();
// Declare that we are going to have an old value of diffusivity
// Note: this is _expensive_. Only do this if you REALLY need it!
virtual void initQpStatefulProperties();
Real _initial_diffusivity;
* Create two MooseArray Refs to hold the current
* and previous material properties respectively
MaterialProperty<Real> & _diffusivity;
MaterialProperty<Real> & diffusivity old;
// init the diffusivity property (this will become
// _diffusivity_old in the first call of computeProperties)
_diffusivity[_qp] = _initial_diffusivity;
_diffusivity[_qp] = diffusivity old[ qp] * 2;
151 / 313
Look at Example 9 (page E69)
152 / 313
153 / 313
Peacock: The MOOSE GUI
Input File Syntax
• As MOOSE grows, so does the amount of input file syntax.
• Remembering it all is definitely out of the question.
• Capabilities do exist to help you out:
– Any MOOSE-based application can be run using ./app-opt --dump to
dump out the input file syntax.
– You can pass another optional argument to --dump and the syntax will be
searched for that string.
– On the Wiki an up to date set of searchable syntax is automatically rebuilt for
every application we know about.
• Each of those solutions requires that you go out of your way to find out
about a piece of input file syntax.
155 / 313
• Peacock is a an integrated Graphical User Interface (GUI) for building input
files and interacting with a MOOSE-based application.
• It is built using PyQt and will look like a native application on Mac, Linux
(and even Windows!).
• It is located under moose/gui/.
• We recommend you add that path to your PATH environment variable.
• Peacock will automatically mold itself to the MOOSE-based application you
are trying to use.
• It will intelligently try to pick up the executable you are trying to use, but it
can also be specified with -e.
• Peacock caches the input file syntax for the application the first time you
run it.
• To re-cache use (in case the syntax has changed for the app) use -r.
156 / 313
Input File Editor
• The main “tab” is the input file
• You can Create/Open/Edit/Save
any MOOSE-based application’s
input file.
• Add a “subsection” (for instance, a
Kernel) by double-clicking the main
section to open the Parameter
• To edit an existing subsection
double-click it.
• Main blocks with parameters use a
“ParentParams” subsection holding
the parameters for that block.
• Check boxes indicate “active”
• The box on the right updates to
show the changing input file.
157 / 313
• The second tab allows you
to execute the input file.
• You don’t need to save the
input file.
• MPI procs and threads are
easily set.
• Other command-line
options can be passed.
• The output of the run is
captured and can be
• A progress bar will appear
during the run.
• The “Kill” button will stop
the currently running job.
158 / 313
Auxiliary Variables
Aux Variables
• The auxiliary system’s purpose is to allow explicit calculations using
nonlinear variables.
• These values can be used by kernels, BCs and material properties.
– Just couple to them as if they were a nonlinear variable.
• They will also come out in the output file. . . useful for viewing things you
don’t solve for (e.g. velocity).
• Auxiliary variables currently come in two flavors:
– Element (constant monomials)
– Nodal (linear Lagrange)
• When using element auxiliary variables:
– You are computing average values per element.
– You can couple to nonlinear variables and both element and nodal auxiliary
• When using nodal auxiliary variables:
– You are computing values at nodes.
– You can only couple to nonlinear variables and other nodal auxiliary variables.
• Auxiliary variables have “old” states just like nonlinear variables.
160 / 313
Aux Kernels
• Aux kernels should go under include/auxkernels and
• They are similar to regular kernels except that they override
computeValue() instead of computeQpResidual().
• They don’t have Jacobians.
• Note that there is no physical difference between a nodal auxiliary kernel
and an elemental.
• The difference is only in the input file.
161 / 313
(Some) Values Available to AuxKernels
u, grad u
– Value and gradient of variable this AuxKernel is operating on.
q point
– XYZ coordinates of the current q-point.
– Only valid for element AuxKernels!
– Current quadrature point.
– Used even for nodal AuxKernels! (Just for consistency)
current elem
– A pointer to the current element that is being operated on.
– Only valid for element AuxKernels!
current node
– A pointer to the current node that is being operated on.
– Only valid for nodal AuxKernels!
And more!
162 / 313
Go Look at Example 10 (page E75)
163 / 313
Example 10 Output
164 / 313
• Krylov methods need preconditioning to be efficient (or even effective!).
• Even though the Jacobian is never formed, JFNK methods still require
• MOOSE’s automatic (without user intervention) preconditioning is fairly
• Many options exist for implementing improved preconditioning in MOOSE.
166 / 313
Preconditioned JFNK
• Using right preconditioning, solve
R 0 (u i )M −1 (Mδu i+1 ) = −R(u i )
• M symbolically represents the preconditioning matrix or process
• Inside GMRES, we only apply the action of M −1 on a vector
• Right preconditioned matrix free version
R 0 (u i )M −1 v ≈
R(u i + M −1 v ) − R(u i )
167 / 313
Preconditioning Matrix vs Process
• On the previous slide M represented the “Preconditioning Matrix”.
• The action of M −1 on a vector represents the “Preconditioner” or
“Preconditioning Process”.
• In MOOSE the “matrix to build” and the “process to apply” with that matrix
are separated.
• There are four different ways to build preconditioning matrices:
– Default: Block Diagonal Preconditioning
– Single Matrix Preconditioner (SMP)
– Finite Difference Preconditioner (FDP)
– Physics Based Preconditioner (PBP)
• After selecting how to build a preconditioning matrix you can then use
solver options to select how to apply the Preconditioner.
168 / 313
Solve Type
• The default solve type for MOOSE is “Preconditioned JFNK”.
• An alternative solve type can be set through either the
[Executioner] or [Preconditioner/*] block.
• Valid options include:
– PJFNK (default)
– FD (Finite Difference)
169 / 313
PETSc Preconditioning Options
• For specifying the preconditioning process we use solver options directly
(i.e. PETSc options).
• Currently the options for preconditioning with PETSc are exposed to the
• This will change in the future. . . there will be more generic ways of
specifying preconditioning parameters.
• The best place to learn about all of the preconditioning options with PETSc
is the user manual.
• We use the command-line syntax, but provide places to enter it into the
input file.
170 / 313
PETSc Specific Options (for Executioner)
petsc options
-snes ksp ew
Variable linear solve tolerance – useful for transient solves
Show PETSc options during the solve
petsc options iname
-pc type
-sub pc type
-pc hypre type
-pc hypre boomeramg (cont.)
strong threshold
-ksp gmres restart
petsc options value
ilu, lu, hypre
0.0 - 1.0
Default for serial
Default for parallel with -sub pc type ilu
Additive Schwartz with -sub pc type ilu
Full LU, serial only!
PETSc Geometric AMG Preconditioner
Hypre, usually used with boomeramg
Can be used with bjacobi or asm
Algebraic multigrid
”Information Threshold” for AMG process
(Use 0.7 for 3D!)
Number of Krylov vectors to store
171 / 313
Default Preconditioning Matrix
• Consider the fully coupled system of equations:
−∇ · k (s, T )∇T = 0
−∇ · D(s, T )∇s = 0
• Fully coupled Jacobian approximation
R 0 (s, T ) =
(R T )T
(R s )T
(R T )s
(R T )T
(R s )s
(R s )s
• For our example:
(k(s, T )∇φj , ∇ψi )
≈ R 0 (s, T )
(D(s, T )∇φj , ∇ψi )
• This simple style of throwing away the off-diagonal blocks is the way
MOOSE will precondition when using the default solve type.
172 / 313
The Preconditioning Block
active = ’my_prec’
type = SMP
# SMP Options Go Here!
# Override PETSc Options Here!
type = PBP
# PBP Options Go Here!
# Override PETSc Options Here!
• The Preconditioning block allows you
to define which type of preconditioning
matrix to build and what process to apply.
• You can define multiple blocks with
different names, allowing you to quickly
switch out preconditioning options.
• Each sub-block takes a type parameter to
specify the type of preconditioning matrix.
• Within the sub-blocks you can also provide
other options specific to that type of
preconditioning matrix.
• You can also override PETSc options here.
• Only one block can be active at a time.
173 / 313
Single Matrix Preconditioning (SMP)
• The Single Matrix Preconditioner (SMP) builds one matrix for
• You enable SMP with:
type = SMP
• You specify which blocks of the matrix to use with:
= ’s’
off_diag_column = ’T’
• Which would produce an M like this:
(k (s, T )∇φj , ∇ψi )
M ≡  ∂D(s,T )
 ≈ R0
(D(s, T )∇φj , ∇ψi )
• In order for this to work you must provide a
computeQpOffDiagJacobian() function in your Kernels that computes
the required partial derivatives.
• To use all off diagonal blocks, you can use the following input file syntax:
full = true
174 / 313
Finite Difference Preconditioning (FDP)
• The Finite Difference Preconditioner (FDP) allows you to form a “Numerical
Jacobian” by doing direct finite differences of your residual statements.
• This is extremely slow and inefficient, but is a great debugging tool because
it allows you to form a nearly perfect preconditioner.
• You specify it by using:
type = FDP
• You can use the same options for specifying off-diagonal blocks as SMP.
• Since FDP allows you to build the perfect approximate Jacobian it can be
useful to use it directly to solve instead of using JFNK.
• The finite differencing is sensitive to the differencing parameter which can
be specified using:
petsc_options_iname = ’-mat_fd_coloring_err -mat_fd_type’
petsc_options_value = ’1e-6
• NOTE: FDP currently works in serial only! This might change in the future,
but FDP will always be meant for debugging purposes!
175 / 313
petsc_options_iname = ’-pc_type -pc_hypre_type -ksp_gmres_restart’
petsc_options_value = ’hypre
• Default Preconditioning Matrix, Preconditioned JFNK, monitor linear solver, variable
linear solver tolerance.
• Use Hypre with algebraic multigrid and store 101 Krylov vectors.
active = ’SMP_jfnk’
type = SMP
= ’forced’
off_diag_column = ’diffused’
petsc_options_iname = ’-pc_type’
petsc_options_value = ’lu’
• Single Matrix Preconditioner, Fill in the (forced, diffused) block, Preconditioned
JFNK, Full inverse with LU
176 / 313
Look at Example 11 (page E81)
177 / 313
Physics Based Preconditioning
• Physics based preconditioning is an advanced concept used to more
efficiently solve using JFNK.
• The idea is to create a preconditioning process that targets each physics
• In this way you can create a more effective preconditioner. . . while also
maintaining efficiency.
• In MOOSE there is a PhysicsBasedPreconditioner object.
• This object allows you to dial up a preconditioning matrix and the
operations to be done on the different blocks of that matrix on the fly from
the input file.
178 / 313
What the PBP Does
• The PBP works by partially inverting a preconditioning matrix (usually an
approximation of the true Jacobian) by partially inverting each block row in
a Block-Gauss-Seidel way.
R(u, v ) =
(R u )u
(R v )u
Mq = p
≈ R0
(R v )v
(R u )u q u
(R v )v q v
p v − (R v )u q u
179 / 313
Using the PBP
active = ’myPBP’
type = PBP
solve_order = ’u v’
preconditioner = ’ILU AMG’
= ’v’
off_diag_column = ’u’
• Set up a PBP object for a two variable
system (consisting of variables “u” and “v”).
• Use ILU for the “u” block and AMG for “v”.
• Use the lower diagonal (v,u) block.
• When using ‘type=PBP’, MOOSE will set
solve type = JFNK automatically.
180 / 313
Applying PBP
• Applying these ideas to a coupled thermo-mechanics problem:
181 / 313
Look at Example 12 (page E91)
182 / 313
• Function objects allow you to evaluate analytic expressions based on x, y, z
and time.
• You can create your own custom Function object in the general MOOSE
way of inheriting from Function and overriding value() and optionally
• Functions can be used in any MOOSE-based object by calling
getFunction("name") where “name” matches a name from the input
• In this way you can create generic BCs, ICs, Forcing Functions, Materials
and more where you can plug and play different Functions to change
• A number of these have already been created that you can use including:
– FunctionDirichletBC, FunctionNeumannBC, FunctionIC,
UserForcingFunction. . .
• Each of these objects takes a “function” parameter from the input file to
know what Function object to use.
• In addition to creating your own objects that inherit from Function there is
also a ParsedFunction object. This object will parse arbitrary
expressions directly from the input file to define its value and gradient like:
– value = x*x+sin(y*t)
184 / 313
Default Functions
• Whenever a Function object is requested through an InputParameter
object, a default can be provided.
• Constant values or parsed functions can be supplied as the default
// Adding a Function with a default constant
params.addParam<FunctionName>("pressure_grad", "0.5", "doc");
// Adding a Function with a default parsed function
params.addParam<FunctionName>("power_history", "t+100*sin(y)", "doc");
• A ParsedFunction or ConstantFunction object is automatically
constructed based on the default value if a function name is not supplied in
the input file.
185 / 313
Input File Syntax
• Functions are declared in the Function
active = ’bc_func’
type = ParsedFunction
value = ’sin(alpha*pi*x)’
vars = ’alpha’
vals = ’16’
active = ’all’
type = FunctionDirichletBC
variable = u
boundary = ’1 2’
function = bc_func
• ParsedFunction allows you to
provide a string specifying the function.
• You can use constants (like alpha),
and define their value. Common
expressions like sin() and pi are
built in.
• After you have declared your functions
you can use them in objects like
186 / 313
Look at Example 13 (page E97)
187 / 313
Postprocessors and Code
• A Postprocessor is an explicit calculation based on the values of your
simulation variables.
• They are computed when needed using the execute on option in the
input file.
timestep begin
• They can be restricted to specific blocks, sidesets, and nodesets in your
• The output from a Postprocessor is one scalar number.
• Think of Postprocessors as “Reductions” or “Aggregations”.
189 / 313
Types of Postprocessors
• Element
– Operate on each element.
– Can be restricted to subdomains by specifying one or more block ids.
– Inherit from ElementPostprocessor.
• Nodal
– Operate on each node.
– Can be restricted to nodesets by specifying one or more boundary ids.
– Inherit from NodalPostprocessor.
• Side
– Operate on boundaries.
– Requires specification of one or more boundary ids.
– Inherit from SidePostprocessor.
• General
– Does whatever it wants.
– Inherit from GeneralPostprocessor.
190 / 313
Postprocessor Anatomy
Postprocessor virtual functions for implementing your aggregation operation:
• void initialize()
– Clear or initialize your data structures before execution.
• void execute()
– Called on each geometric entity for the type of this Postprocessor.
• void threadJoin(const UserObject & uo)
– Aggregation across threads.
– Called to join the passed in Postprocessor with this Postprocessor.
– You have local access to the data structures in both Postprocessors.
• void finalize()
– Aggregation across MPI.
– One of the only places in MOOSE where you might need to use MPI!
– Several Aggregation routines are available in libMesh’s parallel.h file.
• Real getValue()
– Retrieve the final scalar value.
191 / 313
Helpful Aggregation routines
We provide several utility routines to perform common aggregation operations:
• MOOSE convenience functions:
gatherSum(scalar) – returns the sum of scalar across all processors.
gatherMin(scalar) – returns the min of scalar from all processors.
gatherMax(scalar) – returns the max of scalar from all processors.
gatherProxyValueMax(scalar, proxy) – returns proxy based on max
• LibMesh convenience functions (from parallel.h):
– communicator.max(...)
– communicator.sum(...)
– communicator.min(...)
– communicator.gather(...)
– communicator.send(...)
– communicator.receive(...)
– communicator.set union(...)
• LibMesh functions work with a wide variety of types (scalars, vectors, sets,
maps, . . . )
192 / 313
ThreadJoin (Advanced)
• You do not need to implement this function initially to run in parallel. Start
with finalize() and use MPI only.
• You generally need to cast the base class reference to the current type so
that you can access the data structures within.
• Finally, you can perform your custom aggregation operation.
PPSum::threadJoin(const UserObject & y)
// Cast UserObject into a PPSum object so that we can access member variables
const PPSum & pps = static_cast<const PPSum &>(y);
_total_value += pps._total_value;
193 / 313
• A few types of built in Postprocessors:
– ElementIntegral, ElementAverageValue
– SideIntegral, SideAverageValue
– ElementL2Error, ElementH1Error
– And others. . .
• In all of these cases you can inherit from these objects and extend them.
For instance, if you want the average flux on one side you can inherit from
SideAverageValue and override computeQpIntegral to compute the
flux at every quadrature point.
• For the Element and Side Postprocessors, you can use material
properties (and functions).
• By default, Postprocessors will output to a formatted table on the
screen, but they can also write to a CSV or Tecplot file.
• They are also written to Exodus format when using that as an output option.
194 / 313
Default Postprocessor Values
• It is possible to set default values for Postprocessors.
• This allows a MooseObject (e.g., Kernel) to operate without creating or
specifying a Postprocessor.
• Within the validParams function for your object, declare a
Postprocessor parameter with a default value.
params.addParam<PostprocessorName>("postprocessor", 1.2345, "My optional postprocessor documentation")
• When you use the getPostprocessorValue() interface, MOOSE
provides the user-defined value, or the default if no PostProcessor has
been specified.
const PostprocessorValue & value = getPostprocessorValue("postprocessor");
• Additionally, users may supply a real value in the input file in lieu of a
postprocessor name
195 / 313
Input File Syntax and Output
• Postprocessors are declared in the
Postprocessors block.
• The name of the sub-block (like side average
and integral) is the “name” of the
Postprocessor, and will be the name of the
column in the output.
• Element and Side Postprocessors generally
take a variable argument to work on, but can
also be coupled to other variables just like
Kernels, BCs, etc.
type = NumDOFs
type = ElementH1Error
variable = forced
function = bc_func
type = ElementL2Error
variable = forced
function = bc_func
Postprocessor Values:
| time
| dofs
| h1_error
| l2_error
0.000000e+00 |
9.000000e+00 |
2.224213e+01 |
9.341963e-01 |
1.000000e+00 |
9.000000e+00 |
2.224213e+01 |
9.341963e-01 |
2.000000e+00 |
2.500000e+01 |
6.351338e+00 |
1.941240e+00 |
3.000000e+00 |
8.100000e+01 |
1.983280e+01 |
1.232381e+00 |
4.000000e+00 |
2.890000e+02 |
7.790486e+00 |
2.693545e-01 |
5.000000e+00 |
1.089000e+03 |
3.995459e+00 |
7.130219e-02 |
6.000000e+00 |
4.225000e+03 |
2.010394e+00 |
1.808616e-02 |
7.000000e+00 |
1.664100e+04 |
1.006783e+00 |
4.538021e-03 |
196 / 313
Code Verification Using MMS
• Method of Manufactured Solutions (MMS) is a useful tool for code
verification (making sure that your mathematical model is being properly
• MMS works by assuming a solution, substituting it into the PDE, and
obtaining a “forcing term”.
• The modified PDE (with forcing term added) is then solved numerically; the
result can be compared to the assumed solution.
• By checking the norm of the error on successively finer grids you can verify
your code obtains the theoretical convergence rate (i.e. that you don’t have
any code bugs).
• For example:
Assumed solution:
Forcing function:
Need to solve:
−∇ · ∇u = 0
u = sin(απx)
f = α2 π 2 sin(απx)
−∇ · ∇u − f = 0
197 / 313
Error Analysis
• To compare two solutions (or a solution and an analytical solution) f1 and f2 ,
the following expressions are frequently used:
kf1 − f2 k2L2 (Ω) = (f1 − f2 )2 dΩ
kf1 − f2 kH1,semi (Ω) =
|∇ (f1 − f2 )|2 dΩ
• From finite element theory, we know the convergence rates of these
quantities on successively refined grids.
• They can be computed in a MOOSE-based application by utilizing the
ElementL2Error or ElementH1SemiError Postprocessors,
respectively, and specifying the analytical solution with Functions.
198 / 313
Look at Example 14 (page E103)
199 / 313
Example 14 Output
Postprocessor Values:
| time
| dofs
| integral
0.000000e+00 |
1.210000e+02 |
7.071068e-01 |
1.000000e+00 |
1.210000e+02 |
2.359249e+00 |
2.000000e+00 |
4.410000e+02 |
3.093980e-01 |
3.000000e+00 |
1.681000e+03 |
8.861951e-02 |
4.000000e+00 |
6.561000e+03 |
2.297902e-02 |
5.000000e+00 |
2.592100e+04 |
5.797875e-03 |
6.000000e+00 |
1.030410e+05 |
1.452813e-03 |
200 / 313
Parallel-Agnostic Random
Number Generation
Pseudo-Random Number Generation (PRNG)
• Most MOOSE objects include an interface for generating pseudo-random
numbers consistently during serial, parallel, and threaded runs.
• This consistency enables more robust development and debugging without
sacrificing PRNG quality.
• Users have control over the reset frequency of the PRNG.
• Helps avoid convergence issues due to excessive PRNG noise during
linear or non-linear iterations.
• The PRNG system avoids the repetition of “patterns” in subsequent
executions of an application.
202 / 313
Using Random Numbers
• Make a call to setRandomResetFrequency() in your object’s
// Note: EXEC_TIMESTEP == EXEC_TIMESTEP_BEGIN for the purpose of reset
• Obtain Random Numbers (Real or Long)
// anywhere inside your object (except the constructor)
unsigned long random_long = getRandomLong();
Real random_real = getRandomReal();
203 / 313
More Details
• Each MooseObject has its own “seed” value.
• The seed is used to generate different random sequences from run to run.
• The “reset frequency” specifies how often the random number generators
should be reset.
• If you reset on EXEC RESIDUAL, you will get the same random number
sequence each residual evaluation for a given timestep.
• You can also reset less often, e.g. Jacobian, timestep, or simulation
initialization only.
• Generators are advanced every time step unless you explicitly set the reset
frequency to EXEC INITIAL.
• A multi-level random seeding scheme is used to avoid patterning from
mesh entity to mesh entity, timestep to timestep, and run to run.
204 / 313
MooseApp and main()
MooseApp Base Class
• A MOOSE Application (MooseApp) is just another plugable system.
• Your application will contain a MooseApp derived class.
• Each MooseApp is responsible for holding on to a number of essential
objects such as the Factories where its objects are built, and the
Warehouses where its objects are stored.
• In this way, MooseApp objects can be combined (coupled) together to form
larger simulations. (See the MultiApp System)
• MooseApp objects also supply validParams() like any other MOOSE
– Parameters for MooseApps are extracted from the Command Line with special
functions on InputParameters.
– InputParameters::addRequiredCommandLineParam()
– InputParameters::addCommandLineParam()
206 / 313
Your AnimalApp.h/.C
• Your application will contain a MooseApp derived class which will contain a
coupled of key static functions:
– registerApps()
– registerObjects()
– associateSyntax() // optional
• This is the “go-to” place to see all of the applications and objects that this
application depends on.
207 / 313
Object Registration
• The Application object is responsible for calling the static function
registerObjects() where you have registered all of the objects created
in your application.
• Strong coupling to other applications is handling by calling
registerObjects() in those applications making those objects
available in your application.
• By default, your application will register all MOOSE and MOOSE module
objects, but can made to link to any other application.
• When creating a new application with Stork, your application object will be
completely setup and should not require any editing for normal use.
208 / 313
• This is your program entry point!
• By default it only does a couple of very specific things:
– Initializes MPI through an object Wrapper (MooseInit)
– Calls registerApps() which makes your application objects available for
construction in the AppFactory.
– Builds your application object
– Runs your application object
– Clean-up and exit
• See main.C in Example 1 (page E5)
• While it is possible to add additional code here, it’s not recommended.
209 / 313
Test Harness
• MOOSE provides an extendable Test Harness for executing your code with
different input files.
• Each kernel (or logical set of kernels) you write should have test cases that
verify the code’s correctness.
• The test system is very flexible. You can perform many different operations,
for example: testing for expected error conditions.
• Additionally, you can create your own “Tester” classes which extend the
Test Harness.
211 / 313
Tests setup
• Related tests should be grouped into an individual directory and have a
consistent naming convention.
• We recommend organizing tests in a hierarchy similar to your application
source (i.e. kernels, BCs, materials, etc).
• Tests are found dynamically by matching patterns (highlighted below)
[input mesh]
[input file]
[test specification file]
[gold standard folder - validated solution]
212 / 313
A quick look at the test specification file
• Same format as the standard MOOSE input file
= Exodiff
= my_kernel_test.i
exodiff = my_kernel_test_out.e
= RunException
= my_kernel_exception.i
expect_err = ’Bad stuff happened with variable \w+’
213 / 313
Testers provided in MOOSE
• RunApp: Runs a MOOSE-based application with specified options.
• Exodiff: Checks Exodus files for differences within specified tolerances.
• CSVDiff: Checks CSV files for differences within specified tolerances.
• RunException: Tests for various error conditions.
• CheckFiles: Checks for the existence of specific files after a completed run.
214 / 313
Adding Additional Testers (Advanced)
• Inherit from Tester and override:
– checkRunnable()
– prepare(): Method to run right before a test starts
– getCommand(): Command to run (in parallel with other tests)
– processResults(): Process the results to check whether the test has passed
– Drop the Tester object in “<Your App>/scripts/TestHarness/testers”
215 / 313
Options available to each Tester
Run: ./run tests --dump
• input: The name of the input file
• exodiff: The list of output filenames to compare
• abs zero: Absolute zero tolerance for exodiff
• rel err: Relative error tolerance for exodiff
• prereq: Name of the test that needs to complete before running this test
• min parallel: Minimum number of processors to use for a test (default: 1)
• max parallel: Maximum number of processors to use for a test
• ...
216 / 313
Running your tests
./run tests [options]
-j <n>
--not group=GROUP
-p <n>
run ‘n’ jobs at a time
run tests in debug mode (debug binary)
run just one set of tests
run regular tests and those marked ‘heavy’
write separate log file for each failed test
all the tests in a user defined group
opposite of --group option
quiet (don’t print output of FAILED tests
request to run each test with ‘n’ procs
217 / 313
Other Notes on Tests
• Individual tests should run relatively quickly (∼2 second rule)
• Outputs or other generated files should not be checked into the subversion
– Do not check in the solution that is created in the test directory when running
the test!
• The MOOSE developers rely on application tests when refactoring to verify
– Poor test coverage = Higher code failure rate
218 / 313
MOOSE Modules
MOOSE Modules
• MOOSE comes with a library of community-developed physics modules.
• The purpose of the modules is to encapsulate common kernels, boundary
conditions, etc. to prevent code duplication.
• Examples include: heat conduction, solid mechanics, Navier-Stokes, and
• No export controlled physics (i.e. neutronics) should be put into the
MOOSE modules.
• The modules are organized so that your application can link against only
those which it requires.
220 / 313
MOOSE Modules Anatomy
$ ls moose/modules
• All applications are set up to use the MOOSE modules.
• If you need assistance adding or removing unneeded modules from your
application, please contact us and we’ll be happy to help.
221 / 313
MOOSE Modules Anatomy
• The contents of each module are the same as any MOOSE application:
$ ls moose/modules/solid_mechanics
• Application codes specify the modules they want to use in their Makefiles
with the following syntax:
################################## MODULES ####################################
:= yes
222 / 313
MOOSE modules: Solid Mechanics Example
• Available in
modules/solid mechanics
• Stats:
– 127,650 elements, 25,227 nodes
• Features:
– Large displacement formulation
– Plasticity
– Creep
223 / 313
MOOSE modules: Flow Example
• Available in
modules/navier stokes
• Subsonic Test Case:
– Mach 0.5 over a circular arc
– Euler equations
– 8,232 elements, 9,675 nodes
224 / 313
MOOSE Internal SVN
Developer Audiences
• The MOOSE team currently supports several distinct developer audiences:
• Internal = Developer with access to INL servers.
• External = Developer without access to INL servers.
• SVN = Developer working with an SVN checkout of INL MOOSE
• GitHub = Developer working with a git checkout of MOOSE from GitHub.
226 / 313
Developer Audiences
• These training slides focus primarily on
– Internal SVN users, both on- and off-site.
– External GitHub users.
• Detailed instructions1 for Internal and External GitHub developers (people
who will commit to MOOSE) are also available.
227 / 313
Instructions, support, and tools for users of MOOSE.
• Getting Starting:
• Documentation:
• Wiki:
• Blog:
228 / 313
Off-site SVN Access
• Apply for an account
• Set up Port Forwarding
– Linux/OS X
• Set up a ∼/.ssh/config profile
– Windows (Really?)
• Configure forwarding in PuTTY or some other SSH tool
• Create an ssh connection to, and leave it open.
• Translate internal links as follows:
https://hpcsc/moose → https://localhost:4443/moose
https://hpcsc/svn/herd/trunk → https://localhost:4443/svn/herd/trunk
229 / 313
Sample SSH config file for off-site users
Host *
ControlMaster auto
ControlPath ˜/.ssh/master-%[email protected]%h:%p
# General Purpose HPC Machines
Host flogin1 flogin2 eos quark hpcsc hpcweb
User <username>
ProxyCommand ssh <username> netcat %h %p
# Forwarding
Host hpclogin
User <username>
LocalForward 8080 hpcweb:80
LocalForward 4443 hpcsc:443
230 / 313
Getting Started On Your Own Machine
• On the internal Trac Wiki, there are “Getting Started” links on the front page
to directions for getting your environment set up for use with MOOSE.
• In general the steps are:
1. Download and install redistributable package.
2. Check out MOOSE.
3. Build libmesh.
4. Build your application.
5. Run tests!
• We currently have redistributable packages for Linux (Ubuntu and others)
and Mac OSX.
• Under “Getting Started” there are also “advanced” directions for special
situations (like compiling MOOSE on a cluster).
• No matter what directions you follow, make sure to read every step
231 / 313
Basic Subversion workflow
• The INL internal MOOSE applications are currently kept in a Subversion
• Subversion (or SVN) allows multiple people to work on source code
• The
basic workflow is:
Check out source from server.
Make changes.
Add files.
Commit changes back to server.
• Create an SVN checkout by typing:
svn co https://hpcsc/svn/herd/trunk
232 / 313
• Build libMesh by running:
• After libMesh is compiled, compile MOOSE by typing:
make -j8
• The 8 after -j should be replaced with the number of processors in your
machine. This enables parallel compilation.
• To build a debug version of the code, type METHOD=dbg make -j8
• Another option is just to go into your application and do make -j8 this will
automatically recompile your application, MOOSE, and MOOSE modules if
233 / 313
Running Tests
• After building your application, it can be a good idea to make sure
everything is working by running the tests:
• If you would like to run the MOOSE test suite you can type:
cd ∼/projects/trunk/moose/test
make -j8
• Remember to add tests to your test suite whenever possible. This will help
you to know when something is broken, and will help the MOOSE
developers know when they’ve broken your application!
234 / 313
Basic Subversion Usage
At any time you can see what you have modified in the current directory by doing:
svn stat
This will generally print a lot of extra files with “?” next to them. These are usually just generated files like “.o” and “.d”. To get them out
of the way do:
svn stat -q
Some of those “?” files might be new files you need to tell subversion about:
svn add filename
To see the actual modifications you have made to a file you can do:
svn diff filename
When you are ready to commit your changes you first need to update your copy of the code:
Note that this can fail if someone else modified the same piece of code you did. You will get a conflict that you will have to resolve. Just
ask us the first time this happens.
The next step before committing is to rerun the tests to make sure you haven’t broken anything for your application:
svn update
Finally, when you are happy with the changes you have made and you’ve svn added all the new files, you can commit your changes
svn commit -m "Some descriptive message."
235 / 313
Internal Wiki
• The MOOSE Wiki is a one stop shop for
information on how to develop applications using
• To get to the wiki just point your browser to:
• Log in using your INL HPC username and
• The first thing you will see is the Wiki.
• Anyone can add or edit any page on the Wiki (in
fact it’s encouraged!)
• In the middle of the front page are links to
“Tickets” that are relevant to you (explained in a
• On the right side is a menu with a lot of links to
info about developing applications using
• The top menu allows you to navigate to different
sections of the site.
• The first time you login you will need to go to
“Preferences” and set your name and email
236 / 313
Trac Tickets
• Tickets are “bug reports” or feature requests for
your application.
• If you run into a bug or think of a feature you
would like, just click on “New Ticket” and fill out
the form.
• When a new ticket is submitted and assigned an
“Owner,” he or she will automatically receive
email regarding it.
• If you don’t know who the owner should be, just
leave it blank.
• To view tickets you can either use the links
provided on the front page of the Wiki or click on
“View Tickets” and select a report.
• When submitting bug reports, try to be as
thorough as possible:
– Attach relevant input files.
– Reference a specific test or example in the
• “Tickets” are “bug reports” for MOOSE must be
submitted via
237 / 313
Trac Build Status
• Any time a change is made to MOOSE, its
modules, or any application, our regression
test suite runs to ensure everything is still
• You can view the current status of the tests
by clicking on “Build Status” in the upper
– Yellow = In progress
– Green = All tests passed
– Red = Something (compilation, testing,
etc.) failed.
• You can click on individual builds to get
more information and diagnose failures.
238 / 313
MOOSE External GitHub
Working With a GitHub Clone
• Users (non-developers) of MOOSE should follow the instructions at After setting up your
environment, the steps are:
1. Clone MOOSE
mkdir projects
cd projects
git clone
git checkout master
2. Compile libMesh
cd moose
3. Compile and test MOOSE all in one step:
cd test
• If you plan to develop in MOOSE, alternate instructions2 are available.
240 / 313
Basic Git Usage
• To see a brief summary of all current (not yet committed) modifications:
git status
• If you’ve added files, git will list them as being “untracked”. Add each one
you’d like to commit:
git add filename
• To see changes you’ve made to an existing file, type:
git diff filename
• When you are ready to (locally) commit your changes, type:
git commit -a -m"An informative message about your work."
• To see a list of recent commits:
git log
241 / 313
GitHub Issues
• Issues are bug reports or
feature requests for MOOSE
• If you run into a bug or think of
a feature you would like, just
click on “New Issue” and fill
out the form.
• When submitting bug reports,
try to be as thorough as
– Attach relevant input
– Reference a specific test
or example in the
242 / 313
Build Status
• Any time a change is made to MOOSE or
its modules our regression test suite runs
to ensure everything is still working.
• The current build status is shown on
• Additional details are available on
– Yellow = In progress
– Green = All tests passed
– Red = Something (compilation, testing,
etc.) failed.
• The status of “Pull Requests” are also
243 / 313
Visualization Tools
• MOOSE can write results in several formats:
– ExodusII
– Tecplot
– Miscellaneous others. . .
• The INL has a network Tecplot license. For installation instructions, see:
• Paraview is a free visualization and data analysis program that reads
ExodusII files:
245 / 313
Paraview Interface
View a Variable
Parts List
246 / 313
Ensight Interface
247 / 313
Using Stork with an SVN checkout
• Stork is a template application for “delivering” new applications.
• To create a new internal application, run the following commands:
svn co https://hpcsc/svn/herd/trunk
cd trunk/stork
./ <new animal name>
• This will create a new barebones application that contains:
– The standard app directory layout.
– The standard main.C file.
– A basic Application Object where you can register new physics.
– A Makefile that will link against MOOSE and its modules.
249 / 313
Using Stork on GitHub
• Go to and click the Fork button.
• Rename your fork
– Click on your Repository, then the Settings button.
– Rename your repository.
• Clone your fork and run make new
cd ∼/projects
git clone<username>/<app_name>.git
cd <app_name>
• Commit and push
git commit -a -m"Starting my new application."
git push
250 / 313
The Actions System
Advanced Topic
The Actions System
• Responsible for performing work to set up a MOOSE problem or problems
• MOOSE has a large set of common tasks that are performed for every
• Supports complete dependency resolution
• Customizable and extendable
252 / 313
Actions System Model (tasks)
• The setup of a problem in MOOSE is very order sensitive.
• The required order for these steps has already been defined for all
MOOSE-based applications and can be viewed in Moose.C.
• Each step of the setup phase is labeled as a task.
• MOOSE looks for Actions that will satisfy the current task.
• Some of these steps are optional, but they still have to be acted on in the
correct order.
• The list of steps can be augmented by registering and injecting a new task
into the setup order:
– registerTask("task", is required);
– addTaskDependency("task", "depends on");
253 / 313
Actions System Model (Action Object)
• An Action is another MOOSE object type.
• When building a new Action, inherit from Action and override act().
• Typically you will set up other MOOSE objects with your Action:
– Set up and add a group of Kernels. . .
– Set up a group of Variables, each with their own Kernel. . .
– Inspect other Actions in the warehouse, and add objects appropriately. . .
• A single Action class can be registered with more than one task.
• A single Action instance can only satisfy one task, however the system
may create several instances of any one Action to satisfy multiple tasks.
254 / 313
Some built in MOOSE “tasks”
"setup mesh"
"add variable"
"add aux variable"
"add kernel"
"add bc"
"add postprocessor"
"setup executioner"
"setup mesh complete"
"init problem"
"check integrity"
255 / 313
The Parser (briefly)
• MOOSE comes with an input file parser that will automatically create
Actions for you based on the syntax it sees.
• Using the MOOSE Parser (or any parser) is not required. MOOSE
operates on Actions which can be built in any way the developer chooses.
• To use the Parser, Actions must first be associated with syntax blocks
(this works much like object registration).
• The
Encounters a new syntax block in the input file
Checks to see if there is an Action associated with that block
Gets the InputParameters for your object using the appropriate
validParams function
4. Parses and fills in the InputParameters object with options from the input
5. Builds and stores the appropriate Action in MOOSE’s ActionWarehouse.
256 / 313
Actions System Model
“Mesh/” SetupMesh setup_mesh 1 prepare_mesh 2 add_variable 3 init_problem 4 add_kernel 5 PrepareMesh “Kernels/diffusion/” “Variables/temp/” Parser AddKernelAc)on AddVariableAc)on Ac)on System 257 / 313
Look at Example 15 (page E107)
258 / 313
Advanced Topic
• TimeSteppers are lightweight objects used for computing suggested time
steps for transient executioners.
• Use by extending TimeStepper and overriding computeDT()
• Using a TimeStepper is easier than extending the Transient class if all
you want to do is provide a custom method for picking the time step.
• TimeSteppers have access to current and old values of time and dt as
well as access to the Problem and Executioner
260 / 313
Built-in TimeSteppers
• MOOSE has several built-in TimeSteppers
– ConstantDT
– SolutionTimeAdaptiveDT
– FunctionDT
– PostprocessorDT
– DT2
• Example 16 creates a custom TimeStepper that multiplies the current
time step size by a fixed ratio each time step until it reaches a
user-specified minimum value.
261 / 313
Look at Example 16 (page E115)
262 / 313
Dirac Kernels
Advanced Topic
Point Source
• Often in engineering applications you will want to apply a load or source
function at a single point in the domain.
• This happens when the load needs to be applied over a much smaller area
than the domain of interest.
– e.g. an injection well in a geothermal reservoir or a tiny defect in a mesoscale
• For MOOSE this is just another term in your PDE:
−∇ · ∇u − f = 0,
• where f is some forcing function that you want to apply at a point.
• Unfortunately
f = 0 since f only has a value at a single point.
• To deal with that we’re going to use a Dirac Delta Distribution...
264 / 313
Dirac Deltas To The Rescue
• A Dirac Delta Distribution (commonly referred to as a Dirac Delta Function
and denoted by δ) is a generalized
function that is zero except at one point
(usually zero) and for which −∞ δ = 1. (From Wikipedia).
• Dirac Deltas also have another unique property under integration when
multiplied by another function, r (x):
Z ∞
δ(x − x0 )r (x)dx = r (x0 )
• The delta function “picks out the value of r at the point x0 ”
• The idea is that instead of just using f we’re going to use f δ, with the delta
function non-zero at the point where f is applied.
• Now we can form the weak form of that piece of the PDE:
(−f δ(x − x0 ), ψi ) =
−f δ(x − x0 )ψi = −f ψi (x0 )
• That is: if the point at which δ is nonzero is within an element, we get a
contribution to each DOF with a shape function active on that element
• We need to evaluate the shape function at x0 and multiply the result by the
point load.
• This is what a DiracKernel achieves.
265 / 313
Dirac Kernels
• A DiracKernel provides a residual (and optionally a Jacobian) at a set of
points in the domain.
structure is very similar to kernels
• The
computeQpResidual / computeQpJacobian()
Material Properties
• The only difference is that DiracKernel must override addPoints() to
tell MOOSE the points at which DiracKernel is active.
• Inside of addPoints() there are two different ways to notify MOOSE of
the points:
– addPoint(Point p)
• Adds the physical point p that lies inside the domain of the problem.
– addPoint(Elem* e, Point p)
• Adds the physical point p that lies inside the element e.
• The second version is much more efficient if you know, a-priori, the element
in which the point is located.
266 / 313
(Some) Values Available to DiracKernels
u, grad u
– Value and gradient of variable this
DiracKernel is operating on.
grad phi
– Value (φ) and gradient (∇φ) of the trial
functions at the q-points.
test, grad test
– Value (ψ) and gradient ( ∇ψ) of the test
functions at the q-points.
q point
– XYZ coordinates of the current q-point.
i, j
– Current shape functions for test and trial
functions respectively.
– Current quadrature point.
current elem
– A pointer to the current element that is being
operated on.
current point
– The Point where the DiracKernel is currently
being asked to compute.
And more!
267 / 313
ExampleDirac.h / .C
// MOOSE Includes
#include "DiracKernel.h"
//Forward Declarations
class ExampleDirac;
InputParameters validParams<ExampleDirac>();
class ExampleDirac : public DiracKernel
ExampleDirac(const std::string & name,
InputParameters parameters);
virtual void addPoints();
virtual Real computeQpResidual();
Real _value;
std::vector<Real> _point_param;
Point _p;
#include "ExampleDirac.h"
InputParameters validParams<ExampleDirac>()
InputParameters params = validParams<DiracKernel>();
params.addRequiredParam<Real>("value", "");
params.addRequiredParam<std::vector<Real> >("point", "");
return params;
ExampleDirac::ExampleDirac(const std::string & name,
InputParameters parameters) :
DiracKernel(name, parameters),
_point_param(getParam<std::vector<Real> >("point"))
_p(0) = _point_param[0];
if(_point_param.size() > 1)
_p(1) = _point_param[1];
if(_point_param.size() > 2)
_p(2) = _point_param[2];
void ExampleDirac::addPoints()
addPoint( p);
addPoint(Point(4.9, 0.9, 0.9));
Real ExampleDirac::computeQpResidual()
return -_test[_i][_qp]*_value;
268 / 313
Look at Example 17 (page E121)
269 / 313
Example 17 Output
270 / 313
Scalar Kernels
Advanced Topic
Scalar Kernels
• Scalar Kernels:
– Operate on scalar variables (family = SCALAR).
– Are defined in the [ScalarKernels] section of your input file.
• Use
them for:
Solving ODEs (see example 18).
Formulations with Lagrange multipliers.
Other applications. . .
• Notes:
– Mesh-specific data such as qp and current elem are not available to
272 / 313
Scalar Kernels
• Problem being solved:
= ∇2 u + f
u = X (t)
u = Y (t)
in Ω = [−1, 1]
on Γleft
on Γright
• Where the boundary conditions are governed by the ODEs:
= 3X + 2Y
= 4X + Y
plus suitable initial conditions.
273 / 313
ImplicitODEx.h / .C
#include "ODEKernel.h"
class ImplicitODEx;
InputParameters validParams<ImplicitODEx>();
class ImplicitODEx : public ODEKernel
ImplicitODEx(const std::string & name,
InputParameters parameters);
virtual Real computeQpResidual();
virtual Real computeQpJacobian();
virtual Real computeQpOffDiagJacobian(unsigned int jvar);
unsigned int _y_var;
VariableValue & _y;
#include "ImplicitODEx.h"
InputParameters validParams<ImplicitODEx>()
InputParameters params = validParams<ODEKernel>();
params.addCoupledVar("y", "coupled variable Y");
return params;
ImplicitODEx::ImplicitODEx(const std::string & name,
InputParameters parameters) :
ODEKernel(name, parameters),
return -3. * _u[_i] - 2. * _y[_i];
return -3.;
ImplicitODEx::computeQpOffDiagJacobian(unsigned int jvar)
if (jvar == _y_var)
return -2.;
return 0.;
274 / 313
Look at Example 18 (page E127)
275 / 313
Example 18 Output
276 / 313
Geometric Search
Advanced Topic
Geometric Search
• Sometimes information needs to be exchanged between disconnected
pieces of mesh.
• Examples include:
– Mechanical Contact
– Gap Heat Conduction
– Radiation
– Constraints
– Mesh Tying
• The Geometric Search system allows an application to track evolving
geometric relationships.
• Currently, this entails two main capabilities: NearestNodeLocator and
• Both of the capabilities work in parallel and with both Parallel- and
278 / 313
• NearestNodeLocator provides the nearest
node on a “Master” boundary for each node
on a “Slave” boundary (and the other way
• The distance between the two nodes is also
Master Nodes
Slave Nodes
• It works by generating a “Neighborhood” of
nodes on the Master side that are close to
the Slave node.
• The size of the Neighborhood can be
controlled in the input file by setting the
patch size parameter in the Mesh section.
• To get a NearestNodeLocator #include
"NearestNodeLocator.h" and call
getNearestNodeLocator(master id,
slave id) to create the object.
• The functions distance() and
nearestNode() both take a node ID and
return either the distance to the nearest node
or a Node pointer for the nearest node
279 / 313
• A PenetrationLocator provides the
perpendicular distance from a
Slave node to a Master side and
the “contact point” on the Master
Master Nodes
Slave Nodes
• The distance returned is negative if
penetration hasn’t yet occurred
and positive if it has.
Penetration Distance
• To get a NearestNodeLocator
"PenetrationLocator.h" and
getPenetrationLocator(master id,
slave id) to create the object.
Contact Point
• The algorithm in
PenetrationLocator utilizes a
NearestNodeLocator so
patch size is still important.
280 / 313
Advanced Topic
• Dampers allow computation of the Newton damping (or scaling) parameter
Regular Newton
Jδu n+1 = −R (u n )
u n+1 = u n + δu n+1
Damped Newton
Jδu n+1 = −R (u n )
u n+1 = u n + αδu n+1
• Where α is a number between 0 and 1.
– Essentially taking some fraction of the step you just solved for.
• A Damper is created by inheriting from Damper and overriding
• computeQpDamping() computes a damping parameter at each
quadrature point throughout the mesh.
– The smallest damping parameter computed is then actually used.
• Dampers have access to variable values, gradients, material properties and
functions just like a kernel.
– In addition they have access to the Newton Increment.
282 / 313
Initial guess here
may not converge!!
Initial guess here will
likely converge.!
283 / 313
Look at Example 19 (page E139)
284 / 313
Example19 Output
Damping = 1.0
Damping = 0.9
Outputting Initial Condition
True Initial Nonlinear Residual: 10.4403
NL step 0, |residual|_2 = 1.044031e+01
NL step 1, |residual|_2 = 6.366756e-05
NL step 2, |residual|_2 = 3.128450e-10
0: 3.128450e-10
Outputting Initial Condition
True Initial Nonlinear Residual: 10.4403
NL step 0, |residual|_2 = 1.044031e+01
NL step 1, |residual|_2 = 1.044031e+00
NL step 2, |residual|_2 = 1.044031e-01
NL step 3, |residual|_2 = 1.044031e-02
NL step 4, |residual|_2 = 1.044031e-03
NL step 5, |residual|_2 = 1.044031e-04
NL step 6, |residual|_2 = 1.044031e-05
NL step 7, |residual|_2 = 1.044031e-06
NL step 8, |residual|_2 = 1.044031e-07
NL step 9, |residual|_2 = 1.044031e-08
0: 1.044031e-08
285 / 313
Discontinuous Galerkin
Advanced Topic
Discontinuous Galerkin
• Discontinuous Galerkin is a set of methods that rely on a discontinuous set
of shape functions across the domain.
• Essentially, the idea is to allow discontinuities in the value of the function
you are solving for along element boundaries.
• DG then relies on penalizing the jump in the integral of quantities along
element boundaries.
• MOOSE has full support for DG.
• You can use DG with MOOSE by utilizing a discontinuous set of shape
functions (like the MONOMIALS) and creating / specifying DGKernels to
run along with regular Kernels.
• DGKernels are responsible for residual and Jacobian contributions coming
from the integral of jump terms along inter element edges.
• DG is beyond the scope of this training class, if you want to utilize this
capability just ask!
287 / 313
Advanced Topic
• The UserObject system provides data and calculation results to other
MOOSE objects.
• All Postprocessors are UserObjects that compute a single scalar value.
• Therefore, a UserObject can often be thought of as a more generic
Postprocessor with more functionality.
• UserObjects define their own interface, which other MOOSE objects can
call to retrieve data.
• Just like Postprocessors, there are 4 types of UserObjects:
– ElementUserObject
– NodalUserObject
– SideUserObject
– GeneralUserObject
• The first three perform a calculation on the associated geometric entity, and
then provide an interface to the result.
• The GeneralUserObject can do “anything,” and then provide an
interface to the result.
• For example, a GeneralUserObject might read in a large data set, hold
it in memory, and provide an interface for Material classes to access the
289 / 313
UserObject Anatomy
All UserObjects must override the following functions:
1. virtual void initialize();
– Called just one time before beginning the UserObject calculation.
– Useful for resetting data structures.
2. virtual void execute();
– Called once on each geometric object (element, node or side) or just one time
per calculation for a GeneralUserObject.
– This is where you actually do your calculation, read data, etc.
3. virtual void threadJoin(const UserObject & y);
– During threaded execution this function is used to “join” together calculations
generated on different threads.
– In general you need to cast y to a const reference of your type of
UserObject, then extract data from y and add it to the data in “this” object.
– Note, this is not required for a GeneralUserObject because it is not
4. virtual void finalize();
– The very last function called after all calculations have been completed.
– In this function, the user must take all of the small calculations performed in
execute() and do some last operation to get the final values.
– Be careful to do parallel communication where necessary to ensure all
processors compute the same values.
290 / 313
UserObject Anatomy (Cont.)
• A UserObject defines its own interface by defining const accessor
• When another MOOSE object uses a UserObject, they do so by calling
these accessor functions.
• For example, if a UserObject is computing the average value of a variable
on every block in the mesh, it might provide a function like:
Real averageValue(SubdomainID block) const;
• Another MOOSE object using this UserObject would then call
averageValue() to get the result of the calculation.
• Take special note of the const at the end of the function declaration!
• This const means the function cannot modify any member variables of the
object, and is required for UserObject accessor functions.
291 / 313
Using UserObjects
Any MOOSE object can retrieve a UserObject in a manner similar to retrieving a Function.
Generally, it is a good idea to take the name of the UserObject to use from the input file:
InputParameters validParams<BlockAverageDiffusionMaterial>()
InputParameters params = validParams<Material>();
params.addRequiredParam<UserObjectName>("block_average_userobject", "Doc");
return params;
A UserObject comes through as a const reference of the UserObject type. So, in your class:
const BlockAverageValue & _block_average_value;
Set the reference in the initialization list of your object by calling the templated getUserObject() function:
BlockAverageDiffusionMaterial::BlockAverageDiffusionMaterial(const std::string & name,
InputParameters parameters) :
Material(name, parameters),
Use the reference by calling some of the interface functions defined by the UserObject:
_diffusivity[_qp] = 0.5 * _block_average_value.averageValue(_current_elem->subdomain_id());
292 / 313
Example 20 Overview
• The problem is time-dependent diffusion with Dirichlet boundary conditions
of 0 on the left and 1 on the right.
• The diffusion coefficient being calculated by the Material is dependent
on the average value of a variable on each block.
• This means that as the concentration diffuses, the diffusion coefficient is
getting larger, but the coefficient is different for each block (based on the
average value of the variable on that block).
• To achieve this we need 3 objects working together:
– BlockAverageValue: A UserObject that computes the average value of a
variable on each block of the domain and provides averageValue() for
retrieving the average value on a particular block.
– BlockAverageDiffusionMaterial: A Material that computes
diffusivity based on the average value of a variable as computed by a
BlockAverageValue UserObject.
– ExampleDiffusion: The same Kernel we’ve seen before that uses a
diffusivity material property.
293 / 313
Look at Example 20 (page E143)
294 / 313
Example 20 Output
After 4 time steps:
After 10 time steps:
295 / 313
Advanced Topic
• MOOSE was originally created to solve fully-coupled systems of PDEs.
• Not
all systems need to be / are fully coupled:
Multiscale systems are generally loosely coupled between scales.
Systems with both fast and slow physics can be decoupled in time.
Simulations involving input from external codes might be solved somewhat
• To MOOSE these situations look like loosely-coupled systems of
fully-coupled equations.
• A MultiApp allows you to simultaneously solve for individual physics
297 / 313
MultiApps (Cont.)
• Each “App” is considered to be a solve that
is independent.
Master Mul*App 1 • There is always a “master” App that is
doing the “main” solve.
Mul*App 2 • A “master” App can then have any number
Sub-­‐app 1-­‐1 Sub-­‐app 1-­‐2 Mul*App 3 Mul*App 4 Sub-­‐app 3-­‐1 Sub-­‐app 3-­‐2 Sub-­‐app 4-­‐1 Sub-­‐app 4-­‐2 Sub-­‐app 2-­‐1 Sub-­‐app 2-­‐2 Sub-­‐app 2-­‐3 of MultiApps.
• Each MultiApp can represent many
(hence Multi!) “sub-apps”.
• The sub-apps can be solving for completely
different physics from the main application.
• They can be other MOOSE applications, or
might represent external applications.
• A sub-app can, itself, have MultiApps...
leading to multi-level solves.
298 / 313
Input File Syntax
type = TransientMultiApp
app_type = SomeApp
execute_on = timestep
positions = ’0.0 0.0 0.0
0.5 0.5 0.0
0.6 0.6 0.0
0.7 0.7 0.0’
input_files = ’sub.i’
• MultiApps are declared in the MultiApps
• They require a type just like any other block.
• app type is required and is the name of the
MooseApp derived App that is going to be run.
Generally this is something like AnimalApp.
• A MultiApp can be executed at any point
during the master solve. You set that using
execute on to one of: initial, residual,
jacobian, timestep begin, or timestep.
• positions is a list of 3D coordinate pairs
describing the offset of the sub-application into
the physical space of the master application.
More on this in a moment.
• You can either provide one input file for all the
sub-apps... or provide one per position.
299 / 313
• The only currently-available MultiApp is TransientMultiApp, but that
will change.
• A TransientMultiApp requires that your “sub-apps” use an
Executioner derived from Transient.
• A TransientMultiApp will be taken into account during time step
selection inside the “master” Transient executioner.
• Currently, the minimum dt over the master and all sub-apps is used.
• That situation will change when we add the ability to do “sub-cycling.”
300 / 313
• The positions parameter allows you to
define a “coordinate offset” of the sub-app’s
coordinates into the master app’s domain.
Master Domain
• You must provide one set of (x, y, z)
Sub Domain
coordinates for each sub-app.
• The number of coordinate sets determines
the actual number of sub-applications.
• If you have a large number of positions you
can read them from a file using
positions file = filename.
• You can think of the (x, y, z) coordinates as
a vector that is being added to the
coordinates of your sub-app’s domain to put
that domain in a specific spot within the
master domain.
• If your sub-app’s domain starts at (0, 0, 0) it
is easy to think of moving that point around
using positions.
• For sub-apps on completely different scales,
positions is the point in the master domain
where that App is.
position = ‘5 2 0’
301 / 313
• The MultiApp system is designed for
efficient parallel execution of hierarchical
Master Mul*App 1 Sub-­‐app 1-­‐1 Mul*App 3 Sub-­‐app 3-­‐1 Sub-­‐app 3-­‐2 Sub-­‐app 1-­‐2 Mul*App 4 Sub-­‐app 4-­‐1 • The master application utilizes all
Mul*App 2 Sub-­‐app 4-­‐2 Sub-­‐app 2-­‐1 Sub-­‐app 2-­‐2 processors.
Sub-­‐app 2-­‐3 • Within each MultiApp, all of the
processors are split among the sub-apps.
• If there are more sub-apps than
processors, each processor will solve for
multiple sub-apps.
• All sub-apps of a given MultiApp are run
simultaneously in parallel.
• Multiple MultiApps will be executed one
after another.
302 / 313
Advanced Topic
• While a MultiApp allows you to execute many solves in parallel, it doesn’t
allow for data to flow between those solves.
• A Transfer allows you to move fields and data both to and from the
“master” and “sub” applications.
• There are three main kinds of Transfers:
– Field interpolation.
– UserObject interpolation (volumetric value evaluation).
– Value transfers (like Postprocessor values).
• Most Transfers put values into AuxVariable fields.
• The receiving application can then couple to these values in the normal
• Idea: each application should be able to solve on its own, and then, later,
values can be injected into the solve using a Transfer, thereby coupling
that application to the one the Transfer came from.
304 / 313
Field Interpolation
type = MultiAppMeshFunctionTransfer
direction = from_multiapp
multi_app = sub
source_variable = sub_u
variable = transferred_u
type = MultiAppMeshFunctionTransfer
direction = to_multiapp
multi_app = sub
source_variable = u
variable = from_master
• An “interpolation” Transfer should be
used when the domains have some
overlapping geometry.
• The source field is evaluated at the
destination points (generally nodes or
element centroids).
• The evaluations are then put into the
receiving AuxVariable field named
• All MultiAppTransfers take a
direction parameter to specify the flow
of information. Options are:
from multiapp or to multiapp.
305 / 313
UserObject Interpolation
type = MultiAppUserObjectTransfer
direction = from_multiapp
multi_app = sub_app
user_object = layered_average
variable = multi_layered_average
• Many UserObjects compute
spatially-varying data that isn’t associated
directly with a mesh.
• Any UserObject can override Real
spatialValue(Point &) to provide a
value given a point in space.
• A UserObjectTransfer can sample this
spatially-varying data from one App, and
put the values into an AuxVariable in
another App.
306 / 313
Single Value Transfers
type = MultiAppVariableValueSampleTransfer
direction = to_multiapp
multi_app = sub
execute_on = timestep
source_variable = u
variable = from_master
type = MultiAppPostprocessorInterpolationTransfer
direction = from_multiapp
multi_app = sub
postprocessor = average
variable = from_sub
• A single value transfer will allow
you to transfer scalar values
between applications.
• This is useful for Postprocessor
values and sampling a field at a
single point.
• When transferring to a MultiApp,
the value can either be put into a
Postprocessor value or can be
put into a constant AuxVariable
• When transferring from a
MultiApp to the master, the value
can be interpolated from all the
sub-apps into an auxiliary field.
307 / 313
Advanced Topic
• During development, you will reach points where your code is not running
• Sometimes simple print statements will inform you of what is going wrong.
• In cases where your program is actually “crashing” a “debugger” can help
pinpoint the problem.
• Many debuggers exist: GDB, Totalview, ddd, Intel Debugger, etc.
• We are going to focus on GDB because of its ubiquity and simplicity.
• A “Segmentation fault” or “Segfault” or “Signal 11” is a common error, and
denotes a memory bug (often array access out of range).
• In your terminal you will see a message like:
Segmentation fault: 11
• A segfault is a “good” error to have, because a debugger can easily
pinpoint the problem.
309 / 313
Example 21 (page E155)
• Example 21 is exactly like Example 8, except a common error has been
• In ExampleDiffusion.h, a MaterialProperty that should be
declared as a reference is not:
MaterialProperty<Real> _diffusivity;
• Not storing this as a reference will cause a copy of the
MaterialProperty to be made.
• That copy will never be resized, nor will values ever be inserted into it.
• Attempting to access that MaterialProperty results in a segfault:
Solving time step 1, time=0.1000000...
Segmentation fault: 11
• We can use a debugger to help us find the problem. . .
310 / 313
Debug Executable
• To use a debugger with a MOOSE-based application, you must do the
1. Compile your application in debug mode:
cd ∼/projects/moose/examples/ex21_debugging
METHOD=dbg make -j8
• You will now have a “debug version” of your application called
• Next, you need to run your application using GDB:
gdb --args ./ex21-dbg -i ex21.i
• --args tells GDB that any arguments after the executable should be
passed to the executable.
• This will start GDB, load your executable, and leave you at a GDB
command prompt.
311 / 313
Using GDB or LLDB
• At any prompt in GDB or LLDB, you can type h and hit enter to get help.
• We need to set a breakpoint at MPI Abort in order to catch any crashes:
b MPI_abort
• To run your application, type r and hit enter.
• After your application has crashed, type where (or bt) to see a “backtrace”:
#0 0x0101e2baff
#1 0x0100008d89
#2 0x0100007cf0
#3 0x01008ed71a
MPI_Abort ()
MooseArray<double>::operator[] (this=0x1028c6200, i=1) at MooseArray.h:256
ExampleDiffusion::computeQpResidual (this=0x1028c5a00) at ExampleDiffusion.C:44
Kernel::computeResidual (this=0x1028c5a00) at Kernel.C:133
• This backtrace shows that, in ExampleDiffusion::computeQpResidual at line
44 of the file ExampleDiffusion.C, we attempted to use operator[] to index
into something, and failed.
• If we look at this line, we see:
return _diffusivity[_qp]*Diffusion::computeQpResidual();
• There is only one thing we’re indexing into on that line: diffusivity.
• Therefore, we can look at how diffusivity was declared, realize that we forgot
an ampersand (&), and fix it!
312 / 313
313 / 313
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF