everything you always wanted to know about 1oomph-lib but ......everything you always wanted to know...

Everything you always wanted to know aboutoomph-lib but were afraid to ask

Matthias Heil, Andrew L. Hazel

Jonathan Boyle, Andy Gait, Richard Muddle, Cedric Ody, Floraine Cordier, ...

School of Mathematics, University of Manchester

http://www.oomph-lib.org

Matthias Heil, Andrew L. Hazel Everything you always wanted to know about oomph-lib but were afraid to ask

OverviewI Background

I Theory

I Implementation

I Application

I How to get started

I Why did we write it?I What is it?

I Theory

I Implementation

I Application

I TheoryI The mathematical framework

I Implementation

I Application

I ImplementationI What is object-orientation and why is it good for you?

I Application

I ApplicationI An example: Cedric Ody’s micro-fluidics problem.

I How to get startedI Documentation and webpages.

Background

Background: What we [used to] do...E.g.: Biologically-motivated, fluid-structure interaction problems

Steady flow in a collapsible tube. Surface-tension-driven airway collapse

I Code development is typically driven by the demands of aspecific physical/physiological problem ⇒ custom-made codeswith little systematic code reuse.

I No common codebase ⇒ lots of wasted timere-writing/adapting (and debugging!) code.

I Develop an object-oriented library (C++) to solve general,multi-physics problems: oomph-lib.

Background: What we [used to] do...E.g.: Biologically-motivated, fluid-structure interaction problems

Steady flow in a collapsible tube. Surface-tension-driven airway collapse

I Code development is typically driven by the demands of aspecific physical/physiological problem ⇒ custom-made codeswith little systematic code reuse.

I No common codebase ⇒ lots of wasted timere-writing/adapting (and debugging!) code.

I Develop an object-oriented library (C++) to solve general,multi-physics problems: oomph-lib.

Background: [Multi-physics] challengesI Interaction between field equations in the same domain.

I Interaction between field equations in different domains.

I “Non-standard” problems.

I Examples: Thermo-elasticity, thermal convection,reaction-diffusion, ...

I Source terms/coefficients in one system of PDEs depend onthe solution of another system of PDEs and vice versa.

I Interaction between field equations in different domains.I Examples: Fluid-structure interaction, free-surface

Navier-Stokes, ....I Deformation of an elastic structure affects the geometry of the

fluid domain; fluid flow affects the deformation of the elasticstructure.

I Interaction between field equations in different domains.I Examples: Fluid-structure interaction, free-surface

Navier-Stokes, ....I Deformation of an elastic structure affects the geometry of the

fluid domain; fluid flow affects the deformation of the elasticstructure.

I “Non-standard” problems.I Examples: Coupling asymptotic approximations to the

“full” equationsI Outflow boundary conditions for Navier-Stokes, based on

long-wave approximation for flow downstream.

Want to provide a framework that faciliates the formulation of suchproblems within a modern scientific computing environment, offering

I spatial and temporal adaptivity

I capability to deal with free-boundary problems

I parallelisation

I sophisticated solvers

while allowing maximum code-reuse.

oomph-lib

oomph-lib: What is it?oomph-lib is:

I an object-oriented, open-source finite-element library for thesimulation of multi-physics problems.

oomph-lib is not:

I a GUI-based, mouse-driven ”package”.

I You must write your own C++ driver codes to specify yourproblem, using oomph-lib’s high-level objects.

oomph-lib is not:

oomph-lib provides the infrastructure for the problem formulationand solution.

oomph-lib is not:

oomph-lib provides the infrastructure for the problem formulationand solution.

The library contains a large number of elements, meshes, timestep-pers, solvers, etc. which can be combined to solve “any” problem.

General Approach/Design PhilosophyI Robustness

I Generality

I Simple top-level “user” interfaces

I Efficiency

I “Robust algorithms are better than fast-but-flaky ones”I Extensive optional self-tests (via PARANOID flags)I Installation based on GNU autotools

I Generality

I Efficiency

General Approach/Design PhilosophyI RobustnessI Generality

I Easy to formulate “exotic” problemsI Easy to combine single-physics capabilities in multi-physics

problems

I Efficiency

I Generality

I Simple top-level “user” interfacesint main()

{// Create problem

MyReallyHardProblem problem;

// Solve

problem.newton solve();

// Post process

problem.doc solution();

}I Efficiency

I Generality

I Simple top-level “user” interfacesI Efficiency

I “Raw speed” is less important than robustness. However, thisis not an excuse for inefficiency!

I Generality

I Simple top-level “user” interfacesI Efficiency

I =⇒ Spatial and temporal adaptivity are essential and must beimplemented in “user-friendly” fashion:int main()

{[...]

// Solve the problem, allowing for up to

// 4 rounds of spatial adaptation

unsigned max adapt=4;

problem.newton solve(max adapt);

Theory

Theory: The overall framework

I Spatial/[implicit] temporal discretisation of “any” problemleads to a system of (non)linear algebraic equations.

I All problems are treated “monolithically” and are assumed tobe nonlinear.

I Use Newton’s method as default solver.

unew = uold + δu, where J · δu = −R

and J is the Jacobian matrix Jij ≡∂Ri

∂uj.

I Solves linear problems in one step.I Quadratic convergence for non-linear problems.I =⇒ Robust if used together with continuation or timestepping.

∂uj.

Theory: The overall frameworkI Finite-element-type framework, based on element-by-element

assembly of the discretised problem’s residual vector R andJacobian matrix J

Theory: The overall frameworkI Finite-element-type framework, based on element-by-element

assembly of the discretised problem’s residual vector R andJacobian matrix J

Theory: The overall framework“Solving the problem” requires:

1. “Assembly” of the Jacobian matrix and residual vector

2. Solution of the linear system(s)

3. Error estimation/problem adaptation.

Theory: The overall framework1. “Assembly” of the Jacobian matrix and residual vector

I This is oomph-lib’s main task.I Fully parallelised (MPI).

2. Solution of the linear system(s)

2. Solution of the linear system(s)I oomph-lib provides LinearSolver objects – wrappers to

state-of-the-art linear system solvers (HSL frontal solvers;SuperLU serial and parallel sparse matrix solvers; Hypre andTrilinos iterative solvers, both with “black-box”preconditioning strategies).

I oomph-lib has its own IterativeLinearSolvers andproblem-specific Preconditioner classes, e.g. for FSIproblems (Jonathan Boyle, Richard Muddle).

3. Error estimation/problem adaptation.I Z2 error estimator available for a wide range of equations.I Fully automatic mesh adaptation, based on generalised

QuadTree and OcTree procedures (parallelisation in progress[Andy Gait]).

Implementation

Implementation and object-orientationObservation:

I Huge code (≈ 280,000 lines of C++ code; this is notunusual).

I Multiple authors, simultaneously working on the same code.

I Multiple authors, simultaneously working on the same code.(if not, the project dies with each graduating PhD studentand has to be re-invented with/by the next one...)

=⇒ The challenge:

1. Code complexity: How does one manage code of this size (i.e.“keep its structure in one’s head”).

2. Code maintenance: How can you work on (improve!) one partof the code without affecting everybody else?

=⇒ The challenge:

Implementation and object-orientation=⇒ The challenge:

The solution: Object-orientation

I Encapsulation: Combine data into small logical units(objects) and allow the “user” to interact with these (only!)via clearly defined interfaces.

I Inheritance: Construct more complex objects by adding newfunctionality to already existing simpler ones, leading to ahierarchical data structure.

The solution: Object-orientation

I Encapsulation: Combine data into small logical units(objects) and allow the “user” to interact with these (only!)via clearly defined interfaces.

I Inheritance: Construct more complex objects by adding newfunctionality to already existing simpler ones, leading to ahierarchical data structure.

Object-orientation: Astraightforward example

An example of oomph-lib’s object-oriented data structureI The ultimate purpose of most scientific computations is to

compute a large set of (double precision) numbers.

I How do we “package” these up in a sensible way?

I Data as an example of straightforward inheritance.

An example of oomph-lib’s object-oriented data structure

DataDataDataI Has Value (double precision number)

I Has associated (global) equation numbers

I Has associated “History values”

DataDataDataI Has Values (double precision numbers)

Some member functions:

Data::nvalue()Data::value(j)Data::eqn number(j)Data::pin(j)

Important:

I “User” interacts with objects only through the member functions.

I Internal implementation is irrelevant (and deliberately hidden!).

NodeNodeNodeI Is Data.

I Has a Position

↑↑↑

I Has a Position

↑↑↑

I Has a Position

Node::dim()Node::x(i)

↑↑↑DataDataData

I Has Values (double precision numbers)

SolidNodeSolidNodeSolidNodeI Is Node.

I Position represented by Data.

↑↑↑

I Has a Position

↑↑↑

I Has a Position

SolidNode::x(i)SolidNode::pin position(i)

↑↑↑NodeNodeNode

I Is Data.

I Has a Position

An example of oomph-lib’s object-oriented data structureImportant features:

I Hierarchical data structure.

I Implementation is hidden.

I Derived classes “inherit” existing functionality.

I Derived classes can “overload” existing functionality.

oomph-lib’s overall datastructure

oomph-lib’s overall data structure

Object-orientation: A moresophisticated example

Virtual inheritance for (Finite)ElementsI (Virtual) base classes establish the required common

functionality and implement generic tasks.

I Specific implementations are delayed to derived classes whichoften use templating for dimension-independent formulation ofentire families of objects (elements).

Example:

I Every “element” must be able to compute its contribution tothe global residual vector and Jacobian matrix.

I Define the interfaces in the base class GeneralisedElement:

GeneralisedElement::get residual(...)GeneralisedElement::get jacobian(...)

...but delay their implementation to a specific derived element.

I Geometry is isolated from equations.I “Drop” new geometric elements into the overall framework,

“recycling” existing equations.I “Drop” your own equations into the overall framework,

“recycling” hundreds of (wo)man hours already invested intothe development and validation (!) of geometric elements,mesh generation, problem assembly, solution, etc.

Example:

Virtual inheritance for (Finite)Elements

I Geometry is isolated from equations.

I “Drop” new geometric elements into the overall framework,“recycling” existing equations.

I “Drop” your own equations into the overall framework,“recycling” hundreds of (wo)man hours already invested intothe development and validation (!) of geometric elements,mesh generation, problem assembly, solution, etc.

I Geometry is isolated from equations.

I “Drop” new geometric elements into the overall framework,“recycling” existing equations.

“recycling” existing equations.

Equation classesI Some existing equation classes

I PoissonEquations<DIM>I UnsteadyHeatEquations<DIM>I LinearWaveEquations<DIM>I AdvectionDiffusionEquations<DIM>I NavierStokesEquations<DIM>I AxisymmetricNavierStokesEquationsI PVDEquations<DIM> (general displacement-based solid

mechanics; based on principle of virtual displacements)I KirchhoffLoveBeamEquationsI KirchhoffLoveShellEquationsI ...

I Clear instructions and numerous “worked examples” explainhow to formulate new equations.

I All equations classes can be combined to multi-physicselements, e.g. “Navier-Stokes + Advection Diffusion” =“Boussinesq”, etc.

Applications: An exampleproblem

An example: The Young-Laplace equationCedric Ody’s (micro-fluidics) problem:

I Liquid plug propagating through a micro-fluidics network:What happens at the junction?

Rupture

Splitting

Blockage

I What is the largest pressure that a static meniscus at theend of an arbitrarily shaped parent tube can withstand?

An example: The Young-Laplace equation

I What is the largest pressure that a static meniscus at theend of an arbitrarily shaped parent tube can withstand?

I Governing equation

∆p = κ = const.

(∆p on the capillary scale, κ mean curvature).

I Approach: Prescribe ∆p (and thus κ) and compute shape ofmeniscus.

An example: The Young-Laplace equationI Governing equation

∆p = κ = const.

I Example: Rectangular channels

∆p = κ = const.

I Challenges:

∆p = κ = const.

I Challenges:

∆p = κ = const.

I Challenges:

∆p = κ = const.

I Challenges:

∆p = κ = const.

I Challenges:

H(κ) is generally not single-valued .

Example: 90o contact angle at “side wall” =⇒ “Barrel-shaped”solution.

∆p = κ = const.

I Challenges:

∆p = κ = const.

I Challenges:

Stage I: Poisson

I For small deflections from “flat” state

∆p = κ ≈ −∇2h(x , y) = const.

I =⇒ Solve∇2h(x , y) = −κ

for given constant κ (i.e. imposed pressure drop).

I =⇒ A Poisson problem; trivial with existing oomph-libfunctionality.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage I: Poisson

∆p = κ ≈ −∇2h(x , y) = const.

Stage II: Cartesian Young-Laplace

I For finite deflections from “flat” state

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

I Highly nonlinear but (algorithmically) trivial modification toPoisson problem. Easy to implement in oomph-lib via new“equation class”.

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

∆p = κ = −∇ · ∇h√1 + |∇h|2

= const.

I =⇒ Solve

∇ · ∇h√1 + |∇h|2

= −κ

Stage III: Spine-based Young-Laplace

I For non-one-to-one solutions: Use intrinsic representation ofmeniscus

R(ζ1, ζ2)

I Shape governed by variational principle

I Surface parametrisation by “Method of Spines”:

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

I Can’t do H(∆p) because of limit point. Treat ∆p as an unknownand prescribe height via an additional equation:

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

[ctrl ]2 ) · ez = Hctrl

I Implement as GeneralisedElement.

R(ζ1, ζ2)

∫dA =

∫∆pN · δR dA +

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA︸︷︷︸

Variationin

surfaceenergy

∫∆pN · δR dA︸︷︷︸

Virtualwork

done bypressure

∮Tn · δR dS︸︷︷︸Virtualwork

done atmoving

contact line

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

IMatthias Heil, Andrew L. Hazel Everything you always wanted to know about oomph-lib but were afraid to ask

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

R(ζ1, ζ2)

∫dA =

∮Tn · δR dS .

R(ζ1, ζ2) = B(ζ1, ζ2) + h(ζ1, ζ2) S(ζ1, ζ2)

R(ζ1 = ζ[ctrl ]1 , ζ2 = ζ

Meniscus in T-junction

I Note (automatic) mesh adaptation.

Mesh generation

Mesh generationStrategy:

I Start with coarse mesh and refine it automatically

Example: Poisson equation in a fish-shaped domain

∇2u = 1 in Dfish

subject to

u = 0 on ∂Dfish

∇2u = 1 in Dfish

subject to

u = 0 on ∂Dfish

∇2u = 1 in Dfish

subject to

u = 0 on ∂Dfish

for (unsigned i=0;i<max adapt;i++)

{problem.newton solve();

problem.adapt();

}Matthias Heil, Andrew L. Hazel Everything you always wanted to know about oomph-lib but were afraid to ask

∇2u = 1 in Dfish

subject to

u = 0 on ∂Dfish

problem.adapt();

∇2u = 1 in Dfish

subject to

u = 0 on ∂Dfish

problem.adapt();

∇2u = 1 in Dfish

subject to

u = 0 on ∂Dfish

problem.adapt();

Adaptive mesh refinement: Implementation

I Generic implementation of non-uniform refinement in two andthree dimensions

I High-level functions are part of RefineableMesh objects.

I Generalised QuadTree and OcTree data structures used forneighbour finding & determination of weights for hangingnode constraints.

I Z2 (flux recovery) is default error estimator.

3D Navier-Stokes: Developing flow in a pipe

• Inlet flow: 1− r20

becomes parabolic

Poiseuille profile

1− r2

• Re = 200

becomes parabolic

Poiseuille profile

1− r2

• Re = 200

becomes parabolic

Poiseuille profile

1− r2

• Re = 200

becomes parabolic

Poiseuille profile

1− r2

• Re = 200

becomes parabolic

Poiseuille profile

1− r2

• Re = 200

Note how the mesh refinement picks up the curvilinear boundary!

Interfaces to third-party mesh generatorsI For most of “our own” problems, hand-coded meshes are easy

to write.

I For very complex geometries this is not feasible.I oomph-lib provides interfaces to (open-source) third-party

mesh generators:I J.R. Shewchuk’s TriangleI Hang Si’s TetGenI Barry Joe’s Geompack++

I Interfaces to other (commercial) mesh generators could easilybe developed.

to write.

I For very complex geometries this is not feasible.

I oomph-lib provides interfaces to (open-source) third-partymesh generators:

I J.R. Shewchuk’s TriangleI Hang Si’s TetGenI Barry Joe’s Geompack++

to write.

Third-party mesh generators: Triangle + xfigI During a rainy Sunday afternoon we developed an interface

between xfig and Triangle:

1. Draw domain boundaries in xfig and save as hole.fig, say.

2. Run conversion script ./fig2poly hole.fig to convert intoinput file for Triangle.

3. Run Triangle.

4. Read Triangle mesh file from oomph-lib to create mesh:

5. Solve problem with oomph-lib:

3. Run Triangle.

I Also works for more complicated geometries:

I Finite-Reynolds-number flow past the oomph-lib logo.

Third-party mesh generators: TetgenI Tetgen mesh for a cube containing another cube

I Flow field induced by rising inner cube:

Post-processing

Visualisation of results...and now for the embarrasing bit:

I By default oomph-lib outputs data in tecplot format.

I Tecplot is a (fantastic) plotting package.

I Tecplot is a (fantastic) commerical plotting package.

However,

I oomph-lib’s default output is in ascii format and is easy tounderstand.

I Data can be displayed in gnuplot.

I Data can be converted to other (open source) plottingpackages: Angelo Simone (TU Delft) has developed aconversion script to paraview.

I Output can be customised!

However,

How to get started

I Have a look around the oomph-lib webpage:

http://www.oomph-lib.org

Navigating around http://www.oomph-lib.org

Acknowledgements/Current WorkSome current/recent projects:

I Jonathan Boyle: Self-excited oscillations in 3D collapsible tube flow; FSI.

I Alberto Lozar: 3D Bubble propagation in rectangular tubes

I Phil Haines: Self-similar vs. Navier-Stokes solutions in Jeffrey Hamel flow

I Richard Muddle: Block preconditioning, biharmonic equations

I Andy Gait: Parallel mesh adaptation

I Angelo Simone: Biofilms

I Rich Hewitt: Simulation of Long’s vortex

I Natasha Willoughby: Homogenisation

I Chris Glasman: Maxwell’s equations

Ongoing work ([nearly] complete but not yet documented)

I Eigenvalue problems

I Continuation and bifurcation tracking

I Hartree-Fock

everything you always wanted to know about 1oomph-lib but ......everything you always wanted to know...

Documents