Elmer Models Manual

Peter Råback, Mika Malinen, Juha Ruokolainen,

Antti Pursula, Thomas Zwinger, Eds.

CSC – IT Center for Science

October 17, 2022

Elmer Models Manual

About this document

Elmer Models Manual is a part of the documentation of Elmer finite element software. It consists of inde-
pendent chapters describing different modules a.k.a. solvers which the main program (ElmerSolver) uses to
create a specific physical model, although some solvers take care of computational tasks which are not tied
up with the concept of physical model.
The structure of the manual reflects the modular architecture of the software which enables the addition
of new modules without making any changes to the main program. Each chapter typically has a separate
section for theory and keywords, and often some additional information is also given, for example about the
limitations of the model. The Elmer Models Manual is best used as a reference manual rather than a concise
introduction to the matter.
The present manual corresponds to Elmer software version 9.0. The latest documentation and program
versions of Elmer are available (or links are provided) at http://www.csc.fi/elmer.

Copyright information
The original copyright of this document belongs to CSC – IT Center for Science, Finland, 1995–2019. This
document is licensed under the Creative Commons Attribution-No Derivative Works 3.0 License. To view a
copy of this license, visit http://creativecommons.org/licenses/by-nd/3.0/.
Elmer program is free software; you can redistribute it and/or modify it under the terms of the GNU
General Public License as published by the Free Software Foundation; either version 2 of the License, or (at
your option) any later version. Elmer software is distributed in the hope that it will be useful, but without
any warranty. See the GNU General Public License for more details.
Elmer includes a number of libraries licensed also under free licensing schemes compatible with the
GPL license. For their details see the copyright notices in the source files.
All information and specifications given in this document have been carefully prepared by the best ef-
forts of CSC, and are believed to be true and accurate as of time writing. CSC assumes no responsibility or
liability on any errors or inaccuracies in Elmer software or documentation. CSC reserves the right to modify
Elmer software and documentation without notice.

2
Contents

Table of Contents 3

I Models of Fluid Mechanics and Transport Phenomena 7

1 Heat Equation 8

2 Navier-Stokes Equations 19

3 Advection-Diffusion Equation 29

4 Advection-Reaction Equation 35

5 Reynolds Equation for Thin Film Flow 39

II Models of Solid Mechanics 45

6 Linear Elasticity 46

7 Finite Elasticity 54

8 Shell Equations of Classical Elasticity 61

9 Plate Equations of Linear Elasticity 71

10 One-dimensional Equations for Elastic Beams 77

11 Adding pointwise springs and masses 81

III Models of Acoustics 83

12 The Helmholtz Model 84

13 The Linearized Navier–Stokes Equations in the Frequency Domain 88

14 Wave Equation 97

15 Large-amplitude Wave Motion in Air 100

IV Models of Electromagnetism 103

16 Electrostatics 104

3
CONTENTS 4

17 Static Current Conduction 108

18 Computation of Magnetic Fields in 3D 111

19 Circuits and Dynamics Solver 125

20 Vectorial Helmholtz for Electromagnetic Waves 130

21 Electromagnetic Waves 135

22 Computation of Magnetic Fields in 2D 138

23 Magnetic Induction Equation 142

24 Reduced Dimensional Electrostatics 146

25 Poisson-Boltzmann Equation 150

26 Loss Estimation Using the Fourier Series 154

27 Coil Current Solver 159

V Other Physical Models 164

28 Electrokinetics 165

29 Mixed Approximation of the Poisson equation 169

30 Block Preconditioning for the Steady State Navier–Stokes Equations 172

31 Rotational Form of the Incompressible Navier–Stokes Equations 178

VI Free Surfaces, Phase Change and Particle Dynamics 184

32 Level-Set Method 185

33 Kinematic Free Surface Equation with Limiters 191

34 Free Surface with Constant Flux 195

35 Particle Dynamics 198

36 Semi-Lagrangian Advection Using Particle Tracking 206

37 Ordinary differential equation in moving mesh 210

VII Mesh Adaptation, Transformation and Analysis 212

38 Mesh Adaptation Solver 213

39 Nonphysical Mesh Adaptation Solver 216

40 Rigid Mesh Transformation 218

41 Structured Mesh Mapper 221

CONTENTS 5

42 Free surface with streamlines 224

43 Statistics of finite element mesh 226

VIII Derived Fields and Quantities 227

44 Streamline Computation 228

45 Flux Computation 231

46 Vorticity Computation 234

47 Divergence Computation 236

48 Scalar Potential Resulting to a Given Flux 238

49 Artificial Compressibility for FSI 240

50 Fluidic Force 246

51 Electrostatic force 248

52 System Reduction for Displacement Solvers 250

53 Filtering Time-Series Data 255

54 Data to field solver 258

55 Projection to plane 260

56 Structured projection to plane 262

57 Internal Cost Function Optimization 264

IX Saving Data and Results 267

58 Saving Scalar Values to a File 268

59 Saving data along lines to a file 274

60 Saving material parameters and boundary conditions 277

61 Result output in different formats 279

62 Saving data on uniform Cartesian grid 283

63 Isosurface extraction for reduced output 286

64 Coupling Elmer with OpenFOAM via file IO 288

X Reading Data 291

65 Read fields from Gmsh results file 292

66 Reload Existing Simulation Results 293

CONTENTS 6

67 Runtime Control of the Input Data 295

68 Reading NetCDF data into FE mesh 296

XI Experimental or Obsolete Solvers 299

69 Lithium-Ion Battery Model 300

70 Richards equation for variably saturated porous flow 309

71 Outlet Boundary Condition for Arterial Flow Simulations 313

72 BEM Solver for Poisson Equation 317

73 BEM Solver for Helmholtz Equation 320

74 Magnetoquasistatic approximation for axial symmetry 323

75 Linear Constraints 327

76 Density Functional Theory 329

77 Parallel I/O using HDF5 library 333

Index 335
 Part I

Models of Fluid Mechanics and

Transport Phenomena

CSC – IT Center for Science

Model 1

Heat Equation

Module name: HeatSolve

Module subroutines: HeatSolver
Module authors: Juha Ruokolainen, Peter Råback, Matthias Zenker
Document authors: Juha Ruokolainen, Ville Savolainen, Peter Råback

1.1 Introduction
Heat equation results from the requirement of energy conservation. In addition the Fourier’s law is used to
model the heat conduction. The linearity of the equation may be ruined by temperature dependent thermal
conductivity, or by heat radiation.

1.2 Theory
1.2.1 Governing Equations
The incompressible heat equation is expressed as
 
∂T
ρcp + (~u · ∇)T − ∇ · (k∇T ) = τ : ε + ρh, (1.1)
∂t
where ρ is the density, cp the heat capacity at constant pressure, T the temperature, ~u the convection velocity,
k the heat conductivity and h is source of heat. The term τ : ε is the frictional viscous heating, which is
negligible in most cases. For Newtonian fluids, the viscous part of the stress tensor is

τ = 2µε, (1.2)

where ε the linearized strain rate tensor.

Eq.1.1 applies also for solids, setting ~u = 0. For solids, conduction may be anisotropic and the conduc-
tivity a tensor.
For compressible fluids, the heat equation is written as
 
∂T
ρcv + ~u · ∇T − ∇ · (k∇T ) = −p∇ · ~u + τ : ε + ρh, (1.3)
∂t
where cv is the heat capacity at constant volume. The density needs to be calculated from the equation of
state, e.g., perfect gas law. More information is given in the chapter describing the Navier-Stokes equation.
The Elmer heat equation module is capable of simulation heat transfer by conduction, convection, and
diffuse gray radiation. Also a phase change model is included. Couplings to other modules include, convec-
tion by fluid flow, frictional heating (modules providing flow fields), and resistive heating (modules providing
magnetic and/or electric fields).

CSC – IT Center for Science

1. Heat Equation 9

1.2.2 Arbitrary Lagrangian-Eulerian (ALE) coordinates

For problems involving a deforming mesh the transient heat equation must be solved using Arbitrary Lagrangian-
Eulerian (ALE) frame of reference. Assume that the mesh velocity is ~c. Then the convective term yields
ρcp ((~u − ~c)) · ∇)T (1.4)

1.2.3 Phase Change Model

Elmer has an internal fixed grid phase change model. Modelling phase change is done by modifying the
definition of heat capacity according to whether a point in space is in solid or liquid phase or in a ’mushy’
region. The choice of heat capacity within the intervals is explained in detail below.
This type of algorithm is only applicable, when the phase change occurs within finite temperature inter-
val. If the modelled material is such that the phase change occurs within very sharp temperature interval,
this method might not be appropriate.
For the solidification phase change model Elmer uses, we need enthalpy. The enthalpy is defined to be
Z T 
∂f
H(T ) = ρcp + ρL dλ, (1.5)
0 ∂λ
where f (T ) is the fraction of liquid material as a function of temperature, and L is the latent heat. The
enthalpy-temperature curve is used to compute an effective heat capacity, whereupon the equations become
identical to the heat equation. There are two ways of computing the effective heat capacity in Elmer:
∂H
cp,eff = , (1.6)
∂T
and  1/2
∇H · ∇H
cp,eff = . (1.7)
∇T · ∇T
The former method is used only if the local temperature gradient is very small, while the latter is the preferred
method. In transient simulations a third method is used, given by
∂H/∂t
cp,eff = . (1.8)
∂T /∂t
Note that for the current implementation of the heat equation heat capacity and enthalpy are additive. So
if heat capacity is present in the command file it should not be incorporated to enthalpy as an integral.

1.2.4 Additional Heat Sources

Frictional heating is calculated currently, for both incompressible and compressible fluids, by the heat source
hf = 2µε : ε. (1.9)
In case there are currents in the media the also the the resistive heating may need to be considered. The
Joule heating is then given by
1
hm = J~ · J. ~ (1.10)
σ
In the above equations, B~ and E ~ are the magnetic and electric fields, respectively. The current density J~ is
defined as
J~ = σ(E~ + ~u × B).
~ (1.11)
In modeling biological tissue perfused with blood acting as heat sink an additional heat source term of
the Pennes’ Bioheat equation is needed. The term is
hb = cb ρb w(Tb − T ) (1.12)
where cb is the specific heat capacity, ρb the density, and Tb the temperature of the blood. The perfusion rate
w is the volume of blood flowing through a unit volume of tissue per second. This additional source term
is modeled so that the part including T is treated implicitly for better convergence. Even though the model
was written for the biological application in mind the additional heat source may find also other uses.

CSC – IT Center for Science

1. Heat Equation 10

1.2.5 Boundary Conditions

For temperature one can apply boundary conditions and have either temperature or heat flux prescribed.
Dirichlet boundary condition (temperature is prescribed) reads as

T = Tb . (1.13)

The value of Tb can be constant or a function of time, position or other variables.

Heat flux depending on heat transfer coefficient α and external temperature Text may be written as
∂T
−k = α(T − Text ). (1.14)
∂n
Both variables α and Text can be constant or functions of time, position or other variables. If the heat transfer
coefficient α is equal to zero, it means that the heat flux on a boundary is identically zero. The Neumann
boundary condition −k∂T /∂n = 0 is also used in a symmetry axis in 2D, axisymmetric or cylindrical
problems.
Heat flux can consist of idealized radiation whereupon
∂T
−k = σε(T 4 − Text
4
). (1.15)
∂n
Above, σ is the Stefan-Boltzmann constant and ε the surface emissivity. The emissivity and the external
temperature can again be constant or functions of time, position, or other variables.
If the surface k is receiving radiation from other surfaces in the system, then the heat flux reads as
N
∂Tk 1 X
− kk = σεk (Tk4 − Gik εi Ti4 Ai ), (1.16)
∂nk Ak εk i=1

where the subscripts i and k refer to surfaces i and k, and the parameters Ai and Ak to the specific surface
areas. The factors Gik are Gebhardt factors, and N represents the total number of radiating surfaces present
in the system. Emissivities are assumed to be constant on each surface.
The heat equation is nonlinear when radiation is modelled. The nonlinear term in the boundary condition
(1.15) can be linearized as

T 4 − Text
4
≈ (T 3 + Text T 2 + Text
2 3
T + Text )(T − Text ), (1.17)

where T is the temperature from the previous iteration.

A "radiator" is a pointlike source radiating energy, giving raise to flux
∂T X
−k = Pi αi (1.18)
∂n i

where Pi is the power of the source and αi is vector of geometrical factors giving the portion of energy
incident on a given boundary element. The factors take into account the orientation of the boundary element
with respect to the sources and shadowing. Note that this type of source is not available in cylindrically
symmetric cases.
One may also give an additional heat flux term as
∂T
−k = q. (1.19)
∂n

1.3 Keywords
Constants
Stefan Boltzmann Real
The value of the Stefan-Boltzmann constant needed for thermal radiation.

CSC – IT Center for Science

1. Heat Equation 11

Simulation
The simulation section gives the case control data:
Simulation Type String
Heat equation may be either Transient or Steady State.
Coordinate System String
Defines the coordinate system to be used, one of: Cartesian 1D, Cartesian 2D, Cartesian
3D, Polar 2D, Polar 3D, Cylindric, Cylindric Symmetric and Axi
Symmetric.
Timestepping Method String
Possible values of this parameter are Newmark (an additional parameter Newmark Beta must
be given), BDF (BDF Order must be given). Also as a shortcut to Newmark-method with
values of Beta= 0.0, 0.5, 1.0 the keywords Explicit Euler, Crank-Nicolson, and
Implicit Euler may be given respectively. The recommended choice for the first order
time integration is the BDF method of order 2.
BDF Order Integer
Value may range from 1 to 5.
Newmark Beta Real
Value in range from 0.0 to 1.0. The value 0.0 equals to the explicit Euler integration method and
the value 1.0 equals to the implicit Euler method.
Solver solver id
The solver section defines equation solver control variables. Most of the possible keywords – related
to linear algebra, for example – are common for all the solvers and are explained elsewhere.
Equation String [Heat Equation]
The name of the equation. If it is Heat Equation then an old logic will define the following
keyword.
Procedure File "HeatSolve" "HeatSolver"
The name of the procedure for the heat equation. This must be given as stated here.
Variable String [Temperature]
This may be of any name for temperature as long at it is used consistently elsewhere. The default
name is Temperature.
Nonlinear System Convergence Tolerance Real
The criterion to terminate the nonlinear iteration after the relative change of the norm of the field
variable between two consecutive iterations is small enough

||Ti − Ti−1 || < ||Ti ||,

where  is the value given with this keyword.

Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations the solver is allowed to do.
Nonlinear System Newton After Iterations Integer
Change the nonlinear solver type to Newton iteration after a number of Picard iterations have
been performed. If a given convergence tolerance between two iterations is met before the it-
eration count is met, it will switch the iteration type instead. In the heat equation the Picard
iterations means that the radiation term is factorized to linear and third-power terms.
Nonlinear System Newton After Tolerance Real
Change the nonlinear solver type to Newton iteration, if the relative change of the norm of the
field variable meets a tolerance criterion:

||Ti − Ti−1 || < ||Ti ||,

where  is the value given with this keyword.

CSC – IT Center for Science

1. Heat Equation 12

Nonlinear System Relaxation Factor Real

Giving this keyword triggers the use of relaxation in the nonlinear equation solver. Using a
factor below unity is sometimes required to achieve convergence of the nonlinear system. A
factor above unity might speed up the convergence. Relaxed variable is defined as follows:
0
Ti = λTi + (1 − λ)Ti−1 ,

where λ is the factor given with this keyword. The default value for the relaxation factor is unity.
Steady State Convergence Tolerance Real
With this keyword a equation specific steady state or coupled system convergence tolerance is
given. All the active equation solvers must meet their own tolerances before the whole system is
deemed converged. The tolerance criterion is:

||Ti − Ti−1 || < ||Ti ||,

where  is the value given with this keyword.

Stabilize Logical
If this flag is set true the solver will use stabilized finite element method when solving the heat
equation with a convection term. If this flag is set to False RFB (Residual Free Bubble)
stabilization is used instead (unless the next flag Bubbles is set to False in a problem with
Cartesian coordinate system). If convection dominates stabilization must be used in order to
successfully solve the equation. The default value is False.
Bubbles Logical
There is also a residual-free-bubbles formulation of the stabilized finite-element method. It is
more accurate and does not include any ad hoc terms. However, it may be computationally more
expensive. The default value is True. If both Stabilize and Bubbles or set to False, no
stabilization is used. Note that in this case, the results might easily be nonsensical.
Smart Heater Control After Tolerance Real
The smart heater control should not be activated before the solution has somewhat settled. By
default the smart heater control is set on when the Newtonian linearization is switched on for the
temperature equation. Sometimes it may be useful to have more stringent condition for turning
on the smart heater control and then this keyword may be used to give the tolerance.
Apply Limiter Logical
The generic soft limiters may be applied for the heat equation equation. They could for example,
account for the effects of phase change under circumstances where it may be assumed that the
temperature does not go over the phase change temperature. With this flag active the minimum
and maximum limiters are accounted.

Radiating sources ("radiators") are activated using the following keywords (see also the "Boundary
Conditions" section). Also some of the view factor shadowing subdivision/accuracy keywords are
used when resolving the shadowing between the radiation sources and participating boundary surfaces.

Radiator Coordinates(n,3) Real

Activate n radiating sources by giving their coordinates in space.
Radiator Power i Real
Give power of each of the radiating sources introduced with "Radiator Coordinates" -keyword.
Compute Radiator Factors Logical
Force computation of the radiator factors even if the factors have been previously computed and
stored to still existing file. One might want to set this flag when changing the computational
mesh, for example. Note that you should be able to recompute radiator factors also manually
before start of the simulation simply by invoking the binary Radiators. False is the default,
unless the factors don’t exist.

CSC – IT Center for Science

1. Heat Equation 13

Update Radiator Factors Logical

The recomputation of the radiator factors is activated by setting the value of this flag to True.
Note that you should be able to recompute radiator factors also manually before start of the
simulation simply by invoking the binary Radiators. False is the default.

In some cases the geometry or the emissivities of the radiation boundaries change. This may require
the recomputation of the view factors and Gebhardt factors. For that purpose also dynamic computa-
tion of the factors is enabled and it is controlled by the keywords below. The radiation factors are also
automatically computed if no files for the factors are given although radiation boundaries exist.

Update View Factors Logical

The recomputation of the view factors is activated by setting the value of this flag to True. Note
that you should be able to recompute view factors also manually before start of the simulation
simply by invoking the binary ViewFactors. False is the default.
Update Gebhardt Factors Logical
If the emissivities depend on the solution the Gebhardt factors may need to be recomputed. This
is activated by setting giving this flag value True. False is the default. Gebhardt factors are
computed fully internally in ElmerSolver.
Minimum View Factor Real
This keyword determines the cut-off value under which the view factors are omitted. Neglecting
small values will not only save memory but also will make the matrix used for solving the
Gabhardt factors less dense. This consequently will enable more efficient sparse matrix strategies
in solving the Gebhardt factors. The value for this parameter might be of the order 10e-8.
Minimum Gebhardt Factor Real
The Gebhardt factors make part of matrix dense. By neglecting the smallest Gebhardt factors
the matrix structure for the heat equation may become significantly sparser and thus the solution
time may drop. The value for this parameter might also be of the order 10e-8.
Implicit Gebhardt Factor Fraction Real
In computing heat transfer problems with radiation in an implicit manner the matrix structure
becomes partially filled. This affects the performance of the linear equation solvers and also
increases the memory requirements. On the other hand explicit treatment of radiation slows
down the convergence significantly. This keyword allows that the largest Gebhardt factors are
treated in an implicit manner whereas the smallest are treated explicitly. The value should lie in
between zero (fully explicit) and one (fully implicit).
Matrix Topology Fixed Logical
If the Gebhardt factors change the matrix structure of the heat equation may also have to be
changed unless this flag is set to False. Then all factors that do not combine with the matrix
structure are omitted.
View Factors Geometry Tolerance Real
The view factors take a lot of time to compute. Therefore during the iteration a test is performed
to check whether the geometry has changed. If the relative maximum change in the coordinate
values is less than the value given by this parameter the view factors are not recomputed and the
old values are used.
View Factors Fixed After Iterations Integer
Sometimes the iteration changes the geometry of the radiation boundaries as an unwanted side-
effect. Then the geometry on the radiation boundary may be set fixed after some iterations. In
practice this is done by adding suitable Dirichlet conditions in the boundary conditions.
Gebhardt Factors Fixed After Iterations Integer
Sometimes the emissivity depends on temperature but recomputing it every time may be costly.
By this keyword the recomputation may be limited to the given number of visits to the heat
equation solver.

CSC – IT Center for Science

1. Heat Equation 14

View Factors Fixed Tolerance Real

This keywords defines the coupled system tolerance for the heat equation after which the recom-
putation of view factors is omitted. Typically this should be defined by a geometry tolerance but
if the temperature solver follows the changes in geometry this may be a good control as well.
Gebhardt Factors Fixed Tolerance Real
This keywords defines the coupled system tolerance for the heat equation after which the recom-
putation of Gebhardt factors is omitted. The temperature dependence of emissivity is typically
not so strong that small temperature changes would result to a need to recompute the Gebhardt
factors as well.
Gebhardt Factors Solver Full Logical
If the view factor matrix is relatively sparse it will make sense to use a sparse matrix equation
for solving the Gebhardt factors. This flag may be used if a full matrix should be desired.
Gebhardt Factors Solver Iterative Logical
If the Gebhardt factors are solved from a sparse matrix equation also the type of solver may
be selected. The default is direct umfpack solver. Sometimes the memory usage may be a
problem or the direct strategy simply not efficient enough. Then an iterative cgs solver may be
used instead.
radiation: Linear System Keyword
Sometimes the default routines for computing Gebhardt factors are not suitable. For that pur-
poses the user may specify any linear system strategy using namespace radiation: and the
standard linear system keywords. The solver instance is created on the fly and the keywords are
passed to it without the suffix.
radiation: Linear System Symmetric True
Makes the computation of Gebhardt factors symmetric. This can only be done if all emissivities
are less than one. When the system is symmetric, there are more economical linear solvers
available.
radiation: Linear System Positive Definite True
If the linear system is made symmetric, it is also positive definite. Also this may be used by
some linear solvers for better efficiency.
Viewfactor Symmetry x Logical
We may enforce view factors to be symmetric. The code for computing view factors creates
the full mesh internally but all other computations may then be done assuming symmetric ge-
ometry. Also keywords textttViewfactor Symmetry y and Viewfactor Symmetry z exist
correspondingly.
Viewfactor Divide Integer
For axisymmetric view factor computation gives the number of divisions for each element. The
default is 1.
Viewfactor Combine Elements Logical
There may be a significant amount of saved time if in the axisymmetric view factor computation
the elements that are aligned and share a common node are united. The shadowing loop will then
only be performed over these macroelements.
Viewfactor Number Of Rays Integer
In 2D and 3D cases the shadowing is resolved by casting rays between elements. This is the
number of rays sent between elements when computing view factors. It is also used for "radi-
ators" when resolving shadowing between boundary elements and the radiating sources. The
default is 1.
Viewfactor Area Tolerance Real
In 2D and 3D cases the shadowing is resolved by casting rays between elements. This setting
gives a size of the boundary patch, which is not to be divided into smaller pieces even if shad-
owing is undetermined for the patch (the number of hits is larger than zero or fewer than number
of rays). If the area tolerance is used stop the recursive division, the viewfactor is multiplied by

CSC – IT Center for Science

1. Heat Equation 15

hits/maxrays. This keyword is also used for "radiators" when resolving shadowing between
boundary elements and the radiating sources. The default is 1.
Viewfactor Factor Tolerance Real
In 2D and 3D cases the shadowing is resolved by casting rays between elements. This setting
gives the maximum of the computed facto which is accepted for a boundary patch even if shad-
owing is undetermined for the patch (the number of hits is larger than zero or fewer than number
of rays). shadowing between boundary elements and the radiating sources. The default is 1.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies.
Heat Equation Logical
If set to True, solve the heat equation.
Convection String
The type of convection to be used in the heat equation, one of: None, Computed, Constant.
Phase Change Model String
One of: None, Spatial 1, Spatial 2 and Temporal. Note that when solidification
is modelled, the enthalpy-temperature- and viscosity-temperature-curves must be defined in the
material section.

Body Forces bf id
The body force section may be used to give additional force terms for the equations. The following
keywords are recognized by the base solver:
Heat Source Real
A heat source h for the heat equation may be given with this keyword. Note that by default the
heating is given per unit mass, not unit volume.
Friction Heat Logical
Currently redundant keyword, the frictional heating hf is automatically added.
Joule Heat Logical
If set True, triggers use of the electromagnetic heating. This keywords accounts for the heating
of many different solvers; electrostatics, magnetostatics, and induction equation.
Smart Heater Control Logical
Sometimes the predescribed heat source does not lead to the desired temperature. Often the
temperature is controlled by a feedback and therefore a similar heater control in the simulation
may give more realistic results. This flag makes sets the smart heater control on for the given
body force.
Integral Heat Source Real
This keyword activates a normalization of the Heat Source so that the integral heating power
is the desired objective.
Temperature Lower Limit Real
The lower limit for temperature that is enforced iteratively when the soft limiters are applied.
Temperature Upper Limit Real
The upper limit for temperature that is enforced iteratively when the soft limiters are applied.
There are four optional keywords related to the Pennes’ Bioheat equation term that model the perfusion
process.

Perfusion Rate Real

The rate of the perfusion w. Activates the perfusion process.
Perfusion Reference Temperature Real
Temperature Tb of the perfusion fluid.

CSC – IT Center for Science

1. Heat Equation 16

Perfusion Density Real

Density ρb of the perfusion fluid.
Perfusion Heat Capacity Real
Heat capacity cb of the perfusion fluid.

Initial Condition ic id
The initial condition section may be used to set initial values for temperature.
Temperature Real
Material mat id
The material section is used to give the material parameter values. The following material parameters
may be effective when heat equation is solved.
Density Real
The value of density is given with this keyword. The value may be constant, or variable. For the
compressible flow, the density is computed internally, and this keyword has no effect.
Enthalpy Real
Note that, when using the solidification modelling, an enthalpy-temperature curve must be given.
The enthalpy is derived with respect to temperature to get the value of the effective heat capacity.
Viscosity Real
Viscosity is needed if viscous heating is taken into account. When using the solidification mod-
elling, a viscosity-temperature curve must be given. The viscosity must be set to high enough
value in the temperature range for solid material to effectively set the velocity to zero.
Heat Capacity Real
The value of heat capacity in constant pressure cp is given with this keyword. The value may
be constant, or variable. For the phase change model, this value is modified according to rules
given in the theory section.
Heat Conductivity Real
The value of heat conductivity k is given with this keyword. The value may be a constant or
variable.
Convection Velocity i Real
Convection velocity i= 1, 2, 3 for the constant convection model.
Compressiblity Model Real
This setting may be used to set the compressibilty model for the flow simulations. Choices are
Incompressible and Perfect Gas. If set to the latter there may be mechanical work
performed by the heating. Then also the settings Reference Pressure and Specific
Heat Ratio must also be given.
Reference Pressure Real
With this keyword a reference level of pressure may be given.
Specific Heat Ratio Real
The ratio of specific heats (in constant pressure versus in constant volume) may be given with this
keyword. The default value of this setting is 5/3, which is the appropriate value for monoatomic
ideal gas.
Emissivity Real
Emissivity of the radiating surface, required for radiation model is present. If the emissivity is
not found in the radiating boundary only then will it be looked at the material properties of the
parent elements. Often locating the emissivity here makes the case definition more simple.
Transmissivity Real
For the diffuse gray radiation model also transmissivity of the surface may be provided. It gives
the part of the energy that is lost as it passes through the wall. By default transmissivity is zero.

CSC – IT Center for Science

1. Heat Equation 17

Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types. In
heat equation we may set the temperature directly by Dirichlet boundary conditions or use different
flux conditions for the temperature. The natural boundary condition of heat equation is zero flux
condition.
Temperature Real
Heat Flux BC Logical
Must be set to True, if heat flux boundary condition is present.
Heat Flux Real
A user defined heat flux term.
Heat Transfer Coefficient Real
Defines the parameter α in the heat flux boundary condition of the type
∂T
−k = α(T − Text ).
∂n
External Temperature Real
Defines the variable for ambient temperature Text in the previous equation.
Radiation String
The type of radiation model for this boundary, one of: None, Idealized, Diffuse Gray.
Radiation Boundary Integer
If there are many closures with radiation boundary conditions that do not see each other the
view factors may be computed separately. This keyword is used to group the boundaries to
independent sets. The default is one.
Radiation Boundary Open Logical
The closures may be partially open. Then no normalization of the view factors is enforced. The
missing part of the radiation angle is assumed to be ideal radiation. Therefore if this option is
enforced also the parameter External Temperature must be given.
Radiation External Temperature Real
In case the external temperature related to the heat transfer coefficient is different than that related
to the radiation they cannot be given with the same keyword. For this purpose an alternative
keyword is provided for radiation problems. This is used instead if it is present.
Emissivity Real
Emissivity of the radiating surface, required for radiation model is present. If the emissivity is
not found here it will be searched at the parent elements.
Transmissivity Real
If the transmissivity is not found here it will be searched at the parent elements.
Radiator BC Logical
This boundary is getting radiated by "radiators". The surface normal is determined similarly to
diffuse gray radiation model (see "Radiation Target Body" -keyword). Default 1 "False".
Radiation Target Body Integer
This flag may be used to set the direction of the outward pointing normal. This is used when
computing view factors. If the value of emissivity is given in the Material section, then
the normal is assumed to point outwards from the material having the property. If the value
of emissivity is given in the Boundary Condition section, then the direction of normal is
ambiguous. This keyword may then be used to give the direction of the normal by specifying the
material to which the normal points to. Value -1 means that the normal is pointing outwards to
non-existing material (this is also the default). Hence, this keyword should be given on internal
ambiguous boundaries or on external boundaries where we are radiating into the domain.
Smart Heater BoundaryLogical If the smart heater is activated the point for monitoring the tempera-
ture is the point with maximum x-coordinate on the boundary where this keyword is set True.
Alternatively the logical variable Phase Change is looked for.

CSC – IT Center for Science

1. Heat Equation 18

Smart Heater TemperatureReal The desired temperature for the smart heater system is set by this
keyword. Alternatively the real variable Melting Point may be used.

CSC – IT Center for Science

Model 2

Navier-Stokes Equations

Module name: FlowSolve

Module subroutines: FlowSolver
Module authors: Juha Ruokolainen
Document authors: Juha Ruokolainen, Peter Råback

2.1 Introduction
In solid and liquid materials heat transfer and viscous fluid flow are governed by heat and Navier-Stokes
equations, which can be derived from the basic principles of conservation of mass, momentum and energy.
Fluid can be either Newtonian or non-Newtonian. In the latter case the consideration in Elmer is limited to
purely viscous behaviour with the power-law model.
In the following we present the governing equations of fluid flow, heat transfer and stresses in elastic
material applied in Elmer. Also the most usual boundary conditions applied in computations are described.

2.2 Theory
The momentum and continuity equations can be written as
 
∂~u
ρ + (~u · ∇)~u − ∇ · σ = ρf~, (2.1)
∂t

and
 
∂ρ
+ (~u · ∇)ρ + ρ(∇ · ~u) = 0, (2.2)
∂t

where σ is the stress tensor. For Newtonian fluids

2
σ = 2µε − µ(∇ · ~u)I − pI, (2.3)
3

where µ is the viscosity, p is the pressure, I the unit tensor and ε the linearized strain rate tensor, i.e.
 
1 ∂ui ∂uj
εij = + . (2.4)
2 ∂xj ∂xi

The density of an ideal gas depends on the pressure and temperature through the equation of state
p
ρ= , (2.5)
RT

CSC – IT Center for Science

2. Navier-Stokes Equations 20

where R is the gas constant:

γ−1
R= cp . (2.6)
γ
The specific heat ratio γ is defined as
cp
γ= , (2.7)
cv
where cp and cv are the heat capacities in constant pressure and volume, respectively. The value of γ depends
solely on the internal molecular properties of the gas.
An incompressible flow is characterized by the condition ρ=constant, from which it follows that

∇ · ~u = 0. (2.8)

Enforcing the constraint (2.8) in (2.1), (2.2) and (2.3), the equations reduce to the Navier-Stokes equations
 
∂~u
ρ + (~u · ∇)~u − ∇ · (2µε) + ∇p = ρf~, (2.9)
∂t
∇ · ~u = 0. (2.10)

Compressible flows are modelled by the equations (2.1)-(2.7). Then, it is possible to replace the state equa-
tion (2.5) by
1
ρ = 2 p, (2.11)
c
where c = c(p, T, . . . ) is the speed of sound. The equation (2.11) can be used with liquid materials as well.
Most commonly the term ρf~ represents a force due to gravity, in which case the vector f~ is the gravita-
tional acceleration. It can also represent, for instance, the Lorentz force when magnetohydrodynamic effects
are present.
For isothermal flows the equations (2.9) and (2.10) describe the system in full. For thermal flows also
the heat equation needs to be solved.
For thermal incompressible fluid flows we assume that the Boussinesq approximation is valid. This
means that the density of the fluid is constant except in the body force term where the density depends
linearly on temperature through the equation

ρ = ρ0 (1 − β(T − T0 )), (2.12)

where β is the volume expansion coefficient and the subscript 0 refers to a reference state. Assuming that
the gravitational acceleration ~g is the only external force, then the force ρ0~g (1 − β(T − T0 )) is caused in the
fluid by temperature variations. This phenomenon is called Grashof convection or natural convection.
One can choose between transient and steady state analysis. In transient analysis one has to set, besides
boundary conditions, also initial values for the unknown variables.

2.2.1 Boundary Conditions

For the Navier-Stokes equation one can apply boundary conditions for velocity components or the tangential
or normal stresses may be defined.
In 2D or axisymmetric cases the Dirichlet boundary condition for velocity component ui is simply

ui = ubi . (2.13)

A value ubi can be constant or a function of time, position or other variables. In cylindrical cases the Dirichlet
boundary condition for angular velocity uθ is

uθ = ω, (2.14)

where ω is the rotation rate.

CSC – IT Center for Science

2. Navier-Stokes Equations 21

In axisymmetric geometries one has to set ur = 0 and ∂uz /∂r = 0 on the symmetry axis.
If there is no flow across the surface, then

~u · ~n = 0 (2.15)

where ~n is the outward unit normal to the boundary.

Surface stresses can be divided into normal and tangential stresses. Normal stress is usually written in
the form
γ
σn = − pa (2.16)
R
where γ is the surface tension coefficient, R the mean curvature and pa the atmospheric (or external) pres-
sure. Tangential stress has the form
~στ = ∇s γ, (2.17)
where ∇s is the surface gradient operator.
The coefficient γ is a thermophysical property depending on the temperature. Temperature differences
on the surface influence the transport of momentum and heat near the surface. This phenomenon is called
Marangoni convection or thermocapillary convection. The temperature dependence of the surface tension
coefficient can be approximated by a linear relation:

γ = γ0 (1 − ϑ(T − T0 )), (2.18)

where ϑ is the temperature coefficient of the surface tension and the subscript 0 refers to a reference state.
If a Boussinesq hypothesis is made, i.e., the surface tension coefficient is constant except in (2.17) due to
(2.18), the boundary condition for tangential stress becomes

~στ = −ϑγ0 ∇s T. (2.19)

In equation (2.16) it holds then that γ = γ0 . The linear temperature dependence of the surface tension
coefficient is naturally only one way to present the dependence. In fact, the coefficient γ can be any user
defined function in Elmer. One may also give the force vector on a boundary directly as in

σ · ~n = ~g . (2.20)

2.2.2 Linearization
As is well known, the convective transport term of the Navier-Stokes equations and the heat equation is a
source of both physical and numerical instability. The numerical instability must be compensated somehow
in order to solve the equations on a computer. For this reason the so called stabilized finite element method
([2],[1]) is used in Elmer to discretize these equations.
The convection term of the Navier-Stokes equations is nonlinear and has to be linearized for computer
solution. There are two linearizations of the convection term in Elmer:
~ · ∇)~u
(~u · ∇)~u ≈ (U (2.21)

and
~ · ∇)~u + (~u · ∇)U
(~u · ∇)~u ≈ (U ~ − (U
~ · ∇)U,
~ (2.22)
where U~ is the velocity vector from the previous iteration. The first of the methods is called Picard iteration
or the method of the fixed point, while the latter is called Newton iteration. The convergence rate of the
Picard iteration is of first order, and the convergence might at times be very slow. The convergence rate of
the Newton method is of second order, but to successfully use this method, a good initial guess for velocity
and pressure fields is required. The solution to this problem is to first take a couple of Picard iterations, and
switch to Newton iteration after the convergence has begun.

CSC – IT Center for Science

2. Navier-Stokes Equations 22

2.2.3 Arbitrary Lagrangian-Eulerian (ALE) coordinates

For problems involving deformations the transient Navier-Stokes equation must be solved using Arbitrary
Lagrangian-Eulerian (ALE) frame of reference. Assume that the mesh velocity during the nonlinear iteration
is ~c. Then the convective term yields
~ − ~c) · ∇)~u.
((~u − ~c) · ∇) ~u ≈ ((U (2.23)

This results naturally to Picard iteration. For Newton iteration the additional two terms remains the same
since the mesh velocities in there cancel each other.

2.2.4 Non-Newtonian Material Models

There are several non-Newtonian material models. All are functions of the strainrate γ̇. The simple power
law model has a problematic behavior at low shear rates. The more complicated models provide a smooth
transition from low to high shearrates.
Power law (
η0 γ̇ n−1 if γ̇ > γ̇0 ,
η= (2.24)
η0 γ̇0n−1 if γ̇ ≤ γ̇0 .
where η∞ is constant, γ̇0 is the critical shear rate, and n is the viscosity exponent.
Carreau-Yasuda n−1
η = η∞ + ∆η (1 + (cγ̇)y ) y , (2.25)
where η∞ is the high shearrate viscosity γ̇ → ∞ provided that n < 1. For shearrates approaching zero the
viscosity is η0 = η∞ + ∆η. ∆η is thus the maximum viscosity difference between low and high shearrate.
This model recovers the plain Carreau model when the Yasuda exponent y = 2.
Cross
∆η
η = η∞ + , (2.26)
1 + cγ̇ n
where again η∞ is the high shearrate viscosity.
Powell-Eyring
asinh(cγ̇)
η = η∞ + ∆η . (2.27)
cγ̇
All the viscosity models can be made temperature dependent. The current choice is to multiply the
suggested viscosity with a factor exp(d(1/(To + T ) − 1/Tr )), where d is the exponential factor, To is
temperature offset (to allow using of Celcius), and Tr the reference temperature for which the factor becomes
one.

2.2.5 Flow in Porous Media

A simple porous media model is provided in the Navier-Stokes solver. It utilizes the Darcy’s law that states
that the flow resistance is proportional to the velocity and thus the modified momentum equation reads
 
∂~u
ρ + (~u · ∇)~u − ∇ · σ + r~u = ρf~, (2.28)
∂t

where r is the porous resistivity which may also be an orthotropic tensor. Usually the given parameter is
permeability which is the inverse of the resistivity as defined here. No other features of the porous media
flow is taken into consideration. Note that for large value of r only the bubble stabilization is found to work.

CSC – IT Center for Science

2. Navier-Stokes Equations 23

2.2.6 Rotating coordinates

~ The rotation
In rotating coordinate system around origin one may define the angular velocity vector, Ω.
introduces additional forces that may be evaluated from the following
d~uinertial d~urotating ~ × ~urotating + Ω
~ × (Ω
~ × ~x).
= + 2Ω (2.29)
dt dt
In numerical implementations the following Lagrange’s formula is used
~ × (Ω
Ω ~ × ~x) = (Ω
~ · ~x)Ω
~ − (Ω
~ · Ω)~
~ x. (2.30)

which results to the following form of the Navier-Stokes equation in rotating coordinates
 
∂~u ~ × ~u = ρ(Ω
~ · Ω)~
~ x − ρ(Ω ~ + ρf~,
~ · ~x)Ω
ρ + (~u · ∇)~u − ∇ · σ + 2ρΩ (2.31)
∂t
It should be noted that now also the boundary conditions need to be given in the rotational coordinate system.

2.2.7 Coupling to Electric Fields

In electrokinetics the fluid may have charges that are coupled to external electric fields. This results to an
external force that is of the form
f~e = −ρe ∇φ, (2.32)
where ρe is the charge density and φ is the external electric field. The charge density may also be a variable.
More specifically this force may be used to couple the Navier-Stokes equation to the Poisson-Boltzmann
equation describing the charge distribution in electric doubly layers. Also other types of forces that are
proportional to the gradient of the field may be considered.

2.2.8 Coupling to Magnetic Fields

If the fluid has free charges it may couple with an magnetic field. The magnetic field induced force term for
the flow momentum equations is defined as

f~m = J~ × B,
~ (2.33)
~ and E
Here B ~ are the magnetic and electric fields, respectively. The current density J~ is defined as

J~ = σ(E
~ + ~u × B).
~ (2.34)

2.3 Keywords
Constants
Gravity Size 4 Real [x y z abs]
The above statement gives a real vector whose length is four. In this case the first three compo-
nents give the direction vector of the gravity and the fourth component gives its intensity.
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere.

Equation String [Navier-Stokes]

The name of the equation. If it is Navier-Stokes then an old logic will define the following
keyword.
Procedure File "FlowSolve" "FlowSolver"
The name of the procedure for the Navier-Stokes equation. This should be given as stated here.

CSC – IT Center for Science

2. Navier-Stokes Equations 24

Variable String Flow Solution[Velocity:3 Pressure:1]

This is the default name of velocity field in 3D, for 2D replace modify the number of velocity
components. User could give this mainly if needing several flow fields within one simulation.
Flow Model String [Full][No convection][Stokes]
Flow model to be used. The default is to include both convection and time derivative terms in the
model. The "No convection" model switches off the convection terms, and the "Stokes" model
both the convection terms and the (explicit) time derivative terms.
Nonlinear System Convergence Tolerance Real
this keyword gives a criterion to terminate the nonlinear iteration after the relative change of the
norm of the field variable between two consecutive iterations is small enough

||ui − ui−1 || < ||ui ||,

where  is the value given with this keyword.

Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations the solver is allowed to do.
Nonlinear System Newton After Iterations Integer
Change the nonlinear solver type to Newton iteration after a number of Picard iterations have
been performed. If a given convergence tolerance between two iterations is met before the itera-
tion count is met, it will switch the iteration type instead.
Nonlinear System Newton After Tolerance Real
Change the nonlinear solver type to Newton iteration, if the relative change of the norm of the
field variable meets a tolerance criterion:

||ui − ui−1 || < ||ui ||,

where  is the value given with this keyword.

Nonlinear System Relaxation Factor Real
Giving this keyword triggers the use of relaxation in the nonlinear equation solver. Using a
factor below unity is sometimes required to achieve convergence of the nonlinear system. A
factor above unity might speed up the convergence. Relaxed variable is defined as follows:
0
ui = λui + (1 − λ)ui−1 ,

where λ is the factor given with this keyword. The default value for the relaxation factor is unity.
Steady State Convergence Tolerance Real
With this keyword a equation specific steady state or coupled system convergence tolerance is
given. All the active equation solvers must meet their own tolerances before the whole system is
deemed converged. The tolerance criterion is:

||ui − ui−1 || < ||ui ||,

where  is the value given with this keyword.

Stabilize Logical
If this flag is set true the solver will use stabilized finite element method when solving the Navier-
Stokes equations. Usually stabilization of the equations must be done in order to successfully
solve the equations. If solving for the compressible Navier-Stokes equations, a bubble function
formulation is used instead of the stabilized formulation regardless of the setting of this keyword.
Also for the incompressible Navier-Stokes equations, the bubbles may be selected by setting this
flag to False.
Div Discretization Logical
In the case of incompressible flow using the this form of discretization of the equation may lead
to more stable discretization when the Reynolds number increases.

CSC – IT Center for Science

2. Navier-Stokes Equations 25

Gradp Discretization Logical

Whit this form of discretization pressure Dirichlet boundary conditions can be used (and pressure
level must be fixed by such a condition). Also the mass flux is available as a natural boundary
condition.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
Navier-Stokes Logical
if set to True, solve the Navier-Stokes equations.
Magnetic Induction Logical
If set to True, solve the magnetic induction equation along with the Navier-Stokes equations.
Convection String [None, Computed, Constant]
The convection type to be used in the heat equation, one of: None, Computed, Constant.
The second choice is used for thermal flows.
Body Force bf id
The body force section may be used to give additional force terms for the equations.
Boussinesq Logical
If set true, sets the Boussinesq model on.
Flow BodyForce i Real
May be used to give additional body force for the flow momentum equations, i=1,2,3.
Lorentz Force Logical
If set true, triggers the magnetic field force for the flow momentum equations.
Potential Force Logical
If this is set true the force used for the electrostatic coupling is activated.
Potential Field Real
The field to which gradient the external force is proportional to. For example the electrostatic
field.
Potential Coefficient Real
The coefficient that multiplies the gradient term. For example, the charge density.
Angular Velocity Real
~ used for rotating coordinate systems. The size is always expected to be
The angular velocity Ω
three.
Initial Condition ic id
The initial condition section may be used to set initial values for the field variables. The following
variables are active:
Pressure Real
Velocity i Real
For each velocity component i= 1, 2, 3.
Kinetic Energy Real
For the k-ε turbulence model.
Kinetic Energy Dissipation Real

Material mat id
The material section is used to give the material parameter values. The following material parameters
may be set in Navier-Stokes equation.
Density Real The value of density is given with this keyword. The value may be constant, or
variable. For the of compressible flow, the density is computed internally, and this keyword has
no effect.

CSC – IT Center for Science

2. Navier-Stokes Equations 26

Viscosity Real
The relationship between stress and strain velocity. When using the solidification modelling, a
viscosity-temperature curve must be given. The viscosity must be set to high enough value in
the temperature range for solid material to effectively set the velocity to zero.
Reference Temperature Real
This is the reference temperature for the Boussinesq model of temperature dependence of density.
Heat Expansion Coefficient real
For the Boussinesq model the heat expansion coefficient must be given with this keyword. De-
fault is 0.0.
Applied Magnetic Field i Real
An applied magnetic field may be given with these keywords with i=1,2,3.
Compressibility Model String
This setting may be used to set the compressibility model for the flow simulations. Currently the
setting may be set to either Incompressible, Perfect Gas and ArtificialCompressible.
If perfect gas model is chosen the settings Reference Pressure and Specific Heat
Ratio must also be given. The artificial compressibility model may be used to boost conver-
gence in fluid-structure-interaction cases. The default value of this setting is Incompressible.
Reference Pressure Real
with this keyword a reference level of pressure may be given. This setting applies only if the
Compressibility Model is set to the value Perfect Gas.
Specific Heat Ratio Real
The ratio of specific heats (in constant pressure versus in constant volume) may be given with
this keyword. This setting applies only if the Compressibility Model is set to value
Perfect Gas. The default value of this setting is 5/3, which is the appropriate value for
monoatomic ideal gas.
For the k-ε turbulence model the model parameters may also be given in the material section using the
following keywords
KE SigmaK Real [1.0]
KE SigmaE Real [1.3]
KE C1 Real [1.44]
KE C2 Real [1.92]
KE Cmu Real [0.09]
Non-Newtonian material laws are also defined in material section. For the power law the constant
coefficient is given by the keyword Viscosity.
Viscosity Model String
The choices are power law, carreau, cross, powell eyring and thermal carreau.
If none is given the fluid is treated as Newtonian.
Viscosity Exponent Real
Parameter n in the models power law, Carreau, Cross
Viscosity Difference Real
Difference ∆η between high and low shearrate viscosities. Ablicable to Carreau, Cross and
Powell-Eyring models.
Viscosity Transition Real
Parameter c in the Carreau, Cross and Powell-Eyring models.
Critical Shear Rate Real [0.0]
Optional parameter γ̇0 in power law viscosity model.

CSC – IT Center for Science

2. Navier-Stokes Equations 27

Nominal Shear Rate Real [0.0]

Optional parameter in the power law viscosity model that gives the shearrate that returns the
plain Newtonian viscosity.
Yasuda Exponent Real
Optional parameter y in Carreau model. The default is 2. If activated the model is the more
generic Yasuda-Carreau model.
Viscosity Temp Offset Real
Parameter To in the thermal viscosity dependence. When using Celsius instead of Kelvin this
would be 273.15, for example.
Viscosity Temp Ref Real
Parameter Tr in the thermal viscosity dependence. This should be set so that unity factor is
obtained when Tr = To + T .
Viscosity Temp Exp Real
Exponential parameter d in the thermal viscosity dependence.
Porosity is defined by the material properties

Porous Media Logical

If this keyword is set True then the porous model will be active in the material.
Porous Resistance Real
This keyword may give a constant resistance or also an orthotropic resistance where the resis-
tance of each velocity component is given separately.

Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. The one related to Navier-
Stokes equation are

Velocity i Real
Dirichlet boundary condition for each velocity component i= 1, 2, 3.
Pressure Real
Absolute pressure.
Normal-Tangential Velocity Real
The Dirichlet conditions for the vector variables may be given in normal-tangential coordinate
system instead of the coordinate axis directed system using the keywords
Flow Force BC Logical
Set to true, if there is a force boundary condition for the Navier-Stokes equations.
Surface Tension Expansion Coefficient Real
Triggers a tangential stress boundary condition to be used. If the keyword Surface Tension
Expansion Coefficient is given, a linear dependence of the surface tension coefficient
on the temperature is assumed. Note that this boundary condition is the tangential derivative of
the surface tension coefficient
Surface Tension Coefficient Real
Triggers the same physical model as the previous one except no linearity is assumed. The value
is assumed to hold the dependence explicitly.
External Pressure Real
A pressure boundary condition directed normal to the surface.
Pressure i Real
A pressure force in the given direction i= 1, 2, 3.
Free Surface Logical
Specifies a free surface.

CSC – IT Center for Science

BIBLIOGRAPHY 28

Free Moving Logical

Specifies whether the regeneration of mesh is free to move the nodes of a given boundary when
remeshing after moving the free surface nodal points. The default is that the boundary nodes are
fixed.
The k-ε turbulence model also has its own set of boundary condition keywords (in addition to the
Dirichlet settings):
Wall Law Logical
The flag activates the (Reichardts) law of the wall for the boundary specified. the default is 9.0.
Boundary Layer Thickness Real
The distance from the boundary node of the meshed domain to the physical wall.

Bibliography
[1] L.P. Franca and S.L. Frey. Computer methods in Applied Mechanics and Engineering, 99:209–233,
1992.
[2] L.P. Franca, S.L. Frey, and T.J.R. Hughes. Computer methods in Applied Mechanics and Engineering,
95:253–276, 1992.

CSC – IT Center for Science

Model 3

Advection-Diffusion Equation

Module name: AdvectionDiffusion

Module subroutines: AdvectionDiffusionSolver
Module authors: Juha Ruokolainen, Ville Savolainen, Antti Pursula
Document authors: Ville Savolainen, Antti Pursula

3.1 Introduction
Advection-diffusion equation (sometimes called diffusion-convection equation) describes the transport of a
scalar quantity or a chemical species by convection and diffusion. The difference in the nomenclature usually
indicates that an advected quantity does not have an effect on the velocity field of the total fluid flow but
a convected quantity has. Advection-diffusion equation is derived from the principle of mass conservation
of each species in the fluid mixture. Advection-diffusion equation may have sources or sinks, and several
advection-diffusion equations may be coupled together via chemical reactions.
Fick’s law is used to model the diffusive flux. Diffusion may be anisotropic, which may be physically
reasonable at least in solids. If the velocity field is identically zero, the advection-diffusion equation reduces
to the diffusion equation, which is applicable in solids.
Heat equation is a special case of the advection-diffusion (or diffusion-convection) equation, and it is
described elsewhere in this manual.

3.2 Theory
3.2.1 Governing Equations
The advection-diffusion equation may, in general, be expressed in terms of relative or absolute mass or
molar concentrations. In Elmer, when the transported quantity is carried by an incompressible fluid (or it is
diffused in a solid), relative mass concentration ci = Ci /ρ for the species i is used (Ci is the absolute mass
concentration in units kg/m3 , and ρ the total density of the mixture). We have used the approximation valid
for dilute multispecies flows, i.e., 0 ≤ ci  1. The advection-diffusion equation is now written as
 
∂ci
ρ + (~v · ∇)ci = ρ∇ · (Di ∇ci ) + Si , (3.1)
∂t

where ~v is the advection velocity, Di the diffusion coefficient and Si is a source, sink or a reaction term. The
diffusion coefficient may be a tensor.
For a compressible fluid, the concentration should be expressed in absolute mass units, and the advection-
diffusion equation reads
∂Ci
+ (∇ · ~v )Ci + (~v · ∇)Ci = ∇ · (Di ∇Ci ) + Si . (3.2)
∂t

CSC – IT Center for Science

3. Advection-Diffusion Equation 30

For a situation, where the quantity is transported through a phase change boundary, it is convenient to
scale the absolute mass formulation by the respective solubilities of the different phases. Such a case is for
example the surface of a liquid, where the transported quantity is evaporated into a gaseous material. The
scaled concentration variable satisfies the equilibrium boundary condition on the phase change boundary
automatically, and thus the advection-diffusion equation can be solved for both materials simultaneously.
The scaling is following
Ci
xi = , (3.3)
Ci,max
where xi is the concentration of species i relative to its maximum solubility in the current material in absolute
mass units. The maximum solubility has to be a constant (temperature independent) for the absolute mass
formulation of the advection-diffusion equation to remain unchanged.
It is also possible to include temperature dependent diffusion (Soret diffusion). This introduces an addi-
tional term on the right had side of the equation:

∇ · (ρDi,T ∇T ), (3.4)

where Di,T is the thermal diffusion coefficient of species i. The coefficient Di,T has to be given in the units
m2 /Ks regardless of the units used for concentration.
The velocity of the advecting fluid, ~v , is typically calculated by the Navier-Stokes equation and read in
from a restart file. All quantities can also be functions of, e.g., temperature that is given or solved by the
heat equation. Several advection-diffusion equations for different species i may be coupled and solved for
the same velocity field.
Given volume species sources Si can be prescribed. They are given in absolute mass units, i.e., kg/m3 s.
If the equation is scaled to maximum solubility, the source term can be given in absolute mass units, or in
scaled units, Si,sc = Si /Ci,max , which is the default.

3.2.2 Boundary Conditions

For each species one can apply either a prescribed concentration or a mass flux as boundary conditions.
Dirichlet boundary condition reads as
ci = ci,b , (3.5)
or
Ci = Ci,b , (3.6)
depending on the units. If the concentration is scaled to maximum solubility, the Dirichlet boundary condi-
tions have to be given also in scaled values, xi = Ci,b /Ci,max . In all variations, the boundary value can be
constant or a function of time, position or other variables.
One may specify a mass flux ~i perpendicular to the boundary by
∂Ci
~i · ~n = −Di = g. (3.7)
∂n
In relative mass units, this may be written as
∂ci
~i · ~n = −ρDi = g. (3.8)
∂n
Thus the units in the flux boundary condition are always kg/m2 s except when the equation is scaled to
maximum solubility. In that case the default is to give flux condition in scaled units, gsc = g/Ci,max ,
although the physical units are also possible.
The mass flux may also be specified by a mass transfer coefficient β and an external concentration Cext
∂Ci
− Di = β(Ci − Ci,ext ). (3.9)
∂n
On the boundaries where no boundary condition is specified, the boundary condition g = 0 is applied.
This zero flux condition is also used at a symmetry axis in 2D, axisymmetric or cylindrical problems.

CSC – IT Center for Science

3. Advection-Diffusion Equation 31

The equilibrium boundary condition on phase change boundaries under certain conditions is that the
relative amounts of the transported quantity are equal on both sides of the boundary,
(1) (2)
Ci Ci
(1)
= (2)
, (3.10)
Ci,max Ci,max

where the superscripts (1) and (2) refer to different sides of the boundary. This boundary condition is
(j)
automatically satisfied if the equation is scaled with the maximum solubilities Ci,max .
However, the scaling causes a discontinuity into the mass flux of the species through the phase change
surface. The solver compensates this effect as long as such a boundary is flagged in the command file by the
user.

3.3 Keywords
Simulation
The simulation section gives the case control data:
Simulation Type String
Advection-diffusion equation may be either Transient or Steady State.
Coordinate System String
Defines the coordinate system to be used, one of: Cartesian 1D, Cartesian 2D, Cartesian
3D, Polar 2D, Polar 3D, Cylindric, Cylindric Symmetric and Axi
Symmetric.
Timestepping Method String
Possible values of this parameter are Newmark (an additional parameter Newmark Beta must
be given), BDF (BDF Order must be given). Also as a shortcut to Newmark-method with
values of Beta=0.0,0.5, 1.0 the keywords Explicit Euler, Crank-Nicolson,
and Implicit Euler may be given respectively. The recommended choice for the first order
time integration is the BDF method of order 2.
BDF Order Integer
Value may range from 1 to 5.
Newmark Beta Real
Value in range from 0.0 to 1.0. The value 0.0 equals to the explicit Euler integration method and
the value 1.0 equals to the implicit Euler method.

Solver solver id
The solver section defines equation solver control variables. Most of the possible keywords – related
to linear algebra, for example – are common for all the solvers and are explained elsewhere.
Equation String [Advection Diffusion Equation Varname]
The name of the equation, e.g., Advection Diffusion Equation Oxygen.
Variable String Varname
The name of the variable, e.g., Oxygen.
Procedure File "AdvectionDiffusion" "AdvectionDiffusionSolver"
The name of the file and subroutine.
Nonlinear System Convergence Tolerance Real
The criterion to terminate the nonlinear iteration after the relative change of the norm of the field
variable between two consecutive iterations k is small enough

||uk − uk−1 || < ||uk ||,

where  is the value given with this keyword, and u is either ci or Ci .

CSC – IT Center for Science

3. Advection-Diffusion Equation 32

Nonlinear System Max Iterations Integer

The maximum number of nonlinear iterations the solver is allowed to do.
Nonlinear System Relaxation Factor Real
Giving this keyword triggers the use of relaxation in the nonlinear equation solver. Using a
factor below unity is sometimes required to achieve convergence of the nonlinear system. A
factor above unity might speed up the convergence. Relaxed variable is defined as follows:
0
uk = λuk + (1 − λ)uk−1 ,

where λ is the factor given with this keyword. The default value for the relaxation factor is unity.
Steady State Convergence Tolerance Real
With this keyword a equation specific steady state or coupled system convergence tolerance is
given. All the active equation solvers must meet their own tolerances for their variable u before
the whole system is deemed converged. The tolerance criterion is:

||ui − ui−1 || < ||Ti ||,

where  is the value given with this keyword.

Stabilize Logical
If this flag is set true the solver will use stabilized finite element method when solving the
advection-diffusion equation with a convection term. If this flag is set to False, RFB (Residual
Free Bubble) stabilization is used instead (unless the next flag Bubbles is set to False in a
problem with Cartesian coordinate system). If convection dominates, some form of stabilization
must be used in order to succesfully solve the equation. The default value is False.
Bubbles Logical
There is also a residual-free-bubbles formulation of the stabilized finite-element method. It is
more accurate and does not include any ad hoc terms. However, it may be computationally more
expensive. The default value is True. If both Stabilize and Bubbles or set to False, no
stabilization is used. This choice may be enforced in a problem with Cartesian coordinates, but
the results might be nonsensical. Both Stabilize and Bubbles should not be set to True
simultaneously.
Equation eq id
The equation section is used to define a set of equations for a body or set of bodies.
Advection Diffusion Equation Varname Logical
If set to True, solve the advection-diffusion equation.
Convection String
The type of convection to be used in the advection-diffusion equation, one of: None, Computed,
Constant.
Concentration Units String
If set to Absolute Mass, absolute mass units are used for concentration. Recommended for
a compressible flow. Also possible to select Mass To Max Solubility which causes the
absolute mass formulation of the equation to be scaled by the maximum solubilities of each
material.
Body Forces bf id
The body force section may be used to give additional force terms for the equations. The following
keyword is recognized by the solver:
Varname Diffusion Source Real
An additional volume source for the advection-diffusion equation may be given with this key-
word. It may depend on coordinates, temperature and other variables, such as concentration of
other chemical species, and thus describe a source, a sink or a reaction term. Given in absolute
mass units or, in case of scaling, in the scaled units.

CSC – IT Center for Science

3. Advection-Diffusion Equation 33

Physical Units Logical True

With this keyword, the source term can be given in absolute mass units regardless of scaling.
Initial Condition ic id
The initial condition section may be used to set initial values for the concentration ci , Ci or xi .

Varname Real
Material mat id
The material section is used to give the material parameter values. The following material parameters
may be effective when advection-diffusion equation is solved.

Convection Velocity i Real

Convection velocity i= 1, 2, 3 for the constant convection model.
Density Real
The value of density of the transporting fluid is given with this keyword. The value may be
constant, or variable. For compressible flow, the density of the transporting fluid is computed
internally, and this keyword has no effect.
Compressibility Model String
This setting may be used to set the compressibility model for the flow simulations. Choices are
Incompressible and Perfect Gas. If set to the latter, the density is calculated from the
ideal gas law. Then also the settings Reference Pressure, Specific Heat Ratio
and Heat Capacity must be given.
Reference Pressure Real
With this keyword a reference level of pressure may be given.
Specific Heat Ratio Real
The ratio of specific heats (in constant pressure versus in constant volume) may be given with this
keyword. The default value of this setting is 5/3, which is the appropriate value for monoatomic
ideal gas.
Heat Capacity Real
For the compressible flow, specific heat in constant volume.
Varname Diffusivity Real
The diffusivity D given by, e.g., Oxygen Diffusivity. Can be a constant or variable. For
an anisotropic case, may also be a tensor Dij .
Varname Soret Diffusivity Real
The thermal diffusivity coefficient DT given by, e.g., Oxygen Soret Diffusivity. Can
be a constant or variable.
Varname Maximum Solubility Real
The maximum solubility of the species in absolute mass units. Has to be a constant value.

Boundary Condition bc id
In advection-diffusion equation we may set the concentration directly by Dirichlet boundary condi-
tions or use mass flux condition. The natural boundary condition is zero flux condition.
Varname Real
Mass Transfer Coefficient Real
External Concentration Real
These two keywords are used to define flux condition that depends on the external concentration
and a mass transfer coefficient. This condition is only applicable to absolute mass formulation
of the equation (see keywords for Equation block).
Varname Flux Real
A user defined mass flux term in absolute mass units or, in case of scaling, in the scaled units.

CSC – IT Center for Science

3. Advection-Diffusion Equation 34

Physical Units Logical True

With this keyword, the flux boundary condition can be given in absolute mass units regardless of
scaling. Note that this keyword does NOT affect the Dirichlet boundary condition nor the mass
transfer coefficient bc.
Varname Solubility Change Boundary Logical True
This keyword marks the boundary over which the maximum solubility changes. Has to be present
for the mass flux continuity to be preserved.
Normal Target Body Integer bd id
In a solubility change boundary, this keyword can be used to control on which side the mass flux
compensation is done. Basically, this can be done on either side but there can be some effect on
the accuracy or on the speed of the solution. Recommended is to give as normal target the body
with less dense mesh, or the direction of average species transport. If normal target body is not
specified, the material with smaller density is used.

CSC – IT Center for Science

Model 4

Advection-Reaction Equation

Module name: AdvectionReaction

Module subroutines: AdvectionReactionSolver
Module authors: Mikko Lyly, Juha Ruokolainen, Thomas Zwinger
Document authors: Thomas Zwinger

4.1 Introduction
Advection-reaction equation describes the transport of a passive scalar quantity, c, by a fluid. The advected
quantity is assumed not to have an effect on the velocity field. Besides a reaction rate, advection-reaction
equation may have sources or sinks. If no reaction rate and source are given, this equation may be used to
trace passive scalars through a given flow-field. If a constant source of unity value is given, the equation also
may be used to evaluate the time a passive tracer has remained in the flow field.

4.2 Theory
4.2.1 Governing Equations
The advective transport of a scalar c can be written as

∂c
+ ~v · ∇c + Γc = S, (4.1)
∂t
where ~v is the advection velocity, Γ is the reaction rate and S is a source/sink, depending on the sign.
Due to the absence of any diffusion, (4.1) has to be solved applying the Discontinuous Galerkin (DG)
method. Elmer implements the particular method as presented in [1]. In order to evaluated jumps across
partition boundaries in parallel computations, DG requires the utilization of halo-elements for domain de-
composition (see ElmerGrid manual for details).

4.2.2 Limiters
If the scalar has a lower, cmin ≤ c and/or an upper limit c ≤ cmax limit (where the limit can be also a
function of another variable), the variational form of (4.1) becomes a variational inequality. In order to
obtain a consistent solution a method using Dirichlet constraints within the domain is applied. The exact
procedure is the following:
1. construct the linear system: Ac = S, with the system matrix A and the solution vector c on the
left-hand side and the force vector S on the right hand side
2. set nodes as active if the constraint is violated

CSC – IT Center for Science

4. Advection-Reaction Equation 36

3. for active nodes the matrix and force vector are manipulated such that effectively a Dirichlet condition
c = cmax/min is applied
4. the manipulated system is solved: Ãc̃ = S̃
5. a residual is obtained from the un-manipulated system: R = Ac̃ − S

6. an active node is reset if the residual is R < 0 (for lower limit) and R > 0 (for upper limit)
The whole algorithm is iterated (within the non-linear iteration loop) until the limit given in Nonlinear
System Convergence Tolerance is reached. In the converged solution the residual represents the
needed accumulation/volume flux (on matrix level, hence not in physical units) needed in order to obtain the
limited solution. Consequently, the system not necessarily is volume conserving if the Dirichlet method is
applied.

4.2.3 Boundary Conditions

At boundaries, a Dirichlet boundary condition reads as

c = cb . (4.2)

By nature of the applied DG method, the condition above only applies at inflow boundaries, i.e., if

~v · ~nb < 0, (4.3)

where ~nb is the outwards facing surface normal of the boundary.

On the boundaries where no boundary condition is specified, the boundary condition c = 0 is applied
upon inflow.

4.3 Keywords
Simulation
The simulation section gives the case control data:
Simulation Type String
Advection-reaction equation may be either Transient or Steady State.
Coordinate System String
Defines the coordinate system to be used, one of: Cartesian 1D, Cartesian 2D, Cartesian
3D, Polar 2D, Polar 3D, Cylindric, Cylindric Symmetric and Axi
Symmetric.
Timestepping Method String
Possible values of this parameter are Newmark (an additional parameter Newmark Beta must
be given), BDF (BDF Order must be given). Also as a shortcut to Newmark-method with
values of Beta=0.0,0.5, 1.0 the keywords Explicit Euler, Crank-Nicolson,
and Implicit Euler may be given respectively. The recommended choice for the first order
time integration is the BDF method of order 2.
BDF Order Integer
Value may range from 1 to 5.
Newmark Beta Real
Value in range from 0.0 to 1.0. The value 0.0 equals to the explicit Euler integration method and
the value 1.0 equals to the implicit Euler method.
Solver solver id
The solver section defines equation solver control variables. Most of the possible keywords – related
to linear algebra, for example – are common for all the solvers and are explained elsewhere.

CSC – IT Center for Science

4. Advection-Reaction Equation 37

Equation String Advection-Diffusion

The name of the equation, it can be arbitrary but unique.
Discontinuous Galerkin Logical
needs to be set to True. This is currently also enforced internally.
Variable String Variable_name
The name of the variable, e.g., Tracer.
Procedure File "AdvectionReaction" "AdvectionReactionSolver"
The name of the file and subroutine.
Nonlinear System Convergence Tolerance Real
The criterion to terminate the nonlinear iteration after the relative change of the norm of the field
variable between two consecutive iterations k is small enough

||ck − ck−1 || < ||ck ||,

where  is the value given with this keyword.

Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations the solver is allowed to do.
Steady State Convergence Tolerance Real
With this keyword a equation specific steady state or coupled system convergence tolerance is
given. All the active equation solvers must meet their own tolerances for their variable c before
the whole system is deemed converged. The tolerance criterion is:

||ci − ci−1 || < ||ci ||,

where  is the value given with this keyword.

Limit Solution Logical
Assumes the variational inequality method to apply, if set to true.
Compute Nodal Average Logical
The user may choose to average the Discontinuous Galerkin field to nodes. This was historically
needed to be able to visualize the fields using ElmerPost but Paraview can also handle cell
fields. If this flag is set on then Varname_nodal is the name used for the resulting field.
Equation eq id
The equation section is used to define a set of equations for a body or set of bodies.
Convection String
The type of convection to be used in the advection-reaction equation, one of: None, Computed,
Constant.
Body Forces bf id
The body force section may be used to give additional force terms for the equations. The following
keyword is recognized by the solver:
Variable_name Source Real
defines the volumetric source for variable c

Initial Condition ic id
The initial condition section may be used to set initial values for the scalar c.
Variable_name Real
Material mat id
The material section is used to give the material parameter values. The following material parameters
may be effective when advection-diffusion equation is solved.

CSC – IT Center for Science

BIBLIOGRAPHY 38

Convection Velocity i Real

Convection velocity i= 1, 2, 3 for the constant convection model.
Variable_name Upper Limit Real
The upper limit, cmax , for variable Variable_name. Only used if keyword Limit Solution
for the solver is set to true
Variable_name Lower Limit Real
The upper limit, cmin , for variable Variable_name. Only used if keyword Limit Solution
for the solver is set to true
Variable_name Gamma Real
defines the reaction rate, Γ

Boundary Condition bc id
Variable_name Real sets the value for c at inflow boundaries

Bibliography
[1] F. Brezzi and E. Marini, .L. D.and Süli. Discontinuous Galerkin methods for first-order hyperbolic prob
lems. Math. Models Methods Appl. Sci., 14(12):1893–1903, 2004.

CSC – IT Center for Science

Model 5

Reynolds Equation for Thin Film Flow

Module name: ReynoldsSolver

Module subroutines: ReynoldsSolver, ReynoldsHeatingSolver
Module authors: Peter Råback
Document authors: Peter Råback

5.1 Introduction
The flow of fluids is in the continuum level usually described by the Navier-Stokes equations. For narrow
channels this approach is an overkill and usually not even necessary. Neglecting the inertial forces and
assuming fully developed laminar velocity profiles the flow equations may be reduced in dimension resulting
to the Reynolds equation.
The current implementation of the Reynolds equation is suitable for incompressible and weakly com-
pressible liquids as well as for isothermal and adiabatic ideal gases. The nonlinear terms for the compressible
fluids are accounted for. The fluid is assumed to be newtonian i.e. there is a direct connection between the
strain rate and stress. The equation may be solved either in steady state or in a transient mode.
There is an additional solver for postprocessing purposes that computes the local heat generation field
using the Galerkin method. It also computes the integrals over the force and heating fields over the whole
area.

5.2 Theory
The underlying assumption of the Reynolds equation is that the flow in the channel is fully developed and
has thus the Hagen-Poiseuille parabolic velocity profile. Accounting also for the movement of the planes
and leakage through perforation holes the pressure may be solved from the equation
 3 
ρh 1 ∂ρ
∇· ∇p − Y ρp = ∇ · (ρh~vt ) + h + ρvn , (5.1)
12η 2 ∂t

where ρ is the density, η is the viscosity, p is the pressure and h is the gap height, vt is the tangential velocity,
and vn is the velocity in direction of the surface normal [1, 5]. Holes may be homogenized using the flow
admittance Y which gives the ratio between pressure drop and mean flow velocity through the hole.
The exact form of the Reynolds equation depends on the material law for density, ρ(p). The absolute
value of density does not play any role and therefore we may study just the functional forms. For gases we
solve for the pressure variation from the reference pressure P0 rather than for the absolute pressure. The

CSC – IT Center for Science

5. Reynolds Equation for Thin Film Flow 40

different functional forms for some idealized material laws are the following:

ρ∝ (P0 + p) isothermal ideal gas

1/γ
ρ∝ (P0 + p) adiabatic ideal gas
ρ∝ 1 incompressible
p/β
ρ∝ e weakly compressible.

Here γ = Cp /CV is the specific heat ratio and β the bulk modulus. In discretization of the equations it is
also useful to derive the functional dependencies of the density derivatives in respect to pressure,

ρp ∝ 1 isothermal ideal gas

1/γ−1
ρp ∝ (1/γ)(P0 + p) adiabatic ideal gas
ρp ∝ 0 incompressible
ρp ∝ ρ/β weakly compressible.

In order to improve convergence of the iteration of the nonlinear system some terms including differen-
tials of density may be expressed implicitly using pressure. This way equation (5.1) may be written in the
following form:
 3 
ρh ∂p 1 1
∇· ∇p − Y ρp − ρp h − ρp h~vt · ∇p = ρ∇ · (h~vt ) + ρvn . (5.2)
12η ∂t 2 2
The surface velocity ~v may also be given in normal Cartesian coordinate system. Then the normal and
tangential components may easily be obtained from

vn = ~v · ~n
~vt = ~v − vn~n.

The normal velocity and gap height are naturally related by

∂h
vn = . (5.3)
∂t
In transient case the user should make sure that this relationship is honored.

5.2.1 Flow admittances of simple geometries

The flow admittance, Y , occurring in the Reynolds equation may sometimes be solved analytically for
simple hole geometries from the steady-state Stokes equation. Generally Y depends on the history but
here we assume that it is presents the steady-state situation of the flow [2, 5]. This means that inertial and
compressibility effects are not accounted for. For cylindrical holes the admittance then yields,
D2
Y = , (5.4)
32ηb
where D is the diameter of the holes and b is the length of the hole. In case of a narrow slot with width W
the admittance is given by
W2
Y = . (5.5)
12bη

5.2.2 Gas rarefaction effects

Generally the Reynolds equation could also be used to model nonnewtonian material laws. The current
implementation is limited to the special case of rarefied gases. The goodness of the continuum assumption
η depends on the Knudsen number, Kn , which is defined by
λ
Kn = , (5.6)
h

CSC – IT Center for Science

5. Reynolds Equation for Thin Film Flow 41

where λ is the mean free path of the molecules and h is the characteristic scale (here the gap height). In this
solver only the dependence with pressure is taken into account from the formula
1
λ= λ0 . (5.7)
1 + p/P0
When the Knudsen number is very small (Kn  1) the gas may be considered as a continuous medium.
When the Knudsen number is in the transition regime (Kn ≈ 1) we may take the gas rarefaction effect
into account by an effective viscosity. This accounts for the slip conditions of the flow in the channel by
decreasing the viscosity value. An approximation given by Veijola [4] is
η0
η= . (5.8)
1 + 9.638Kn1.159
It s relative accuracy is 5 % in the interval 0 < Kn < 880.

5.2.3 Boundary conditions for the Reynolds equation

The Reynolds equation may have different boundary conditions. The natural boundary condition that is
obtained by default is
∂p
= 0. (5.9)
∂n
This condition may be used at symmetry and closed boundaries.
If the aspect ratio of the resonator is large then the pressure variation at the open sides is small compared
to the values far from boundaries. Then may set Dirichlet boundary conditions (p = 0) for the pressure.
However, if the aspect ratio is relatively small the open side effects should be taken into account. The
pressure variation at the side is not exactly zero while also the open space has a flow resistance. The pressure
derivative at the boundary is approximated by
∂p p
= , (5.10)
∂n L
where L is the effective added length of the open sides [3]. If gas rarefaction is not accounted for then
L = 0.8488h, otherwise
L = 0.8488(1.0 + 2.676Kn0.659 )h. (5.11)

5.2.4 Postprocessing
When the equation has been solved the solution may be used to compute some data for postprocessing
purposes. The local volume flux in the lateral direction may be obtained from
h3
~q = − ∇p + h~vt . (5.12)
12η
The total force acting on the surface is
Z 
η 
F~ = p~n + ~vt dA, (5.13)
A h
where the first term is due to pressure driven flow and the second one due to sliding driven flow. Also the
heating effect may be computed. It consist of two parts: pressure driven flow and sliding flow. The local
form of this is
h3 η
h= |∇p|2 + |~vt |2 . (5.14)
12η h
Therefore the total heating power of the system is
Z
Q= q dA. (5.15)
A
It should be noted that if the velocity field ~v is constant then the integral quantities should fulfill the condition
Q = F~ · ~v .
Note that the above implementation does not take into account the leakage through perforation holes nor
the compressibility effects of the fluids.

CSC – IT Center for Science

5. Reynolds Equation for Thin Film Flow 42

5.3 Keywords
The module includes two different solvers. ReynoldsSolver solves the differential equation (5.2) while
ReynoldsHeatingSolver solves the equation (5.14) and computes the integrals. The second solver
only makes sense when the pressure field has already been computed with the first one. The second solver
uses the same material parameters as the first one.

Keywords for ReynoldsSolver

Solver solver id
Equation String ReynoldsSolver
A describing name for the solver. This can be changes as long as it is used consistently.
Procedure File "ReynoldsSolver" "ReynoldsSolver"
Name of the solver subroutine.
Variable String FilmPressure
The name of the variable may be freely chosen as far as it is used consistently also elsewhere.
Variable DOFs Integer 1
Degrees of freedom for the pressure. This should be 1 which is also the default value.
Procedure File "ReynoldsSolver" "ReynoldsSolver"
The name of the module and procedure. These are fixed.
Apply Limiter Logical
The generic soft limiters may be applied for the Reynolds equation in order to mimic the effects
of cavitation. With this flag active the minimum and maximum limiters are accounted.
Nonlinear System Convergence Tolerance Real
The transient equation is nonlinear if the relative displacement or pressure deviation is high.
The iteration is continued till the relative change in the norm falls under the value given by this
keyword.
Nonlinear System Max Iterations Integer
This parameter gives the maximum number of nonlinear iterations required in the solution. This
may be set higher than the typical number of iterations required as the iteration procedure should
rather be controlled by the convergence tolerance.
Material mat id
Gap Height Real
Height of the gap where the fluid is trapped. If the case is transient the user should herself make
sure that also this variable has the correct dependence on time.
Surface Velocity i Real
The velocity of the moving body may be given in either Cartesian coordinates, or in ones that are
already separated to normal and tangential directions. In the first case the velocity components
are given with this keyword with i=1,2,3.
Tangent Velocity i Real
For setting the tangential velocity (i.e. sliding velocity) use this keyword with i=1,2,3.
Normal Velocity Real
Normal velocity is the velocity in the direction of the surface normal. Typically a negative value
means contraction.
Viscosity Real
Viscosity of the gas.
Viscosity Model String
The choices are newtonian and rarefied. The first one is also the default.

CSC – IT Center for Science

5. Reynolds Equation for Thin Film Flow 43

Compressibility Model String

The choices are incompressible, weakly compressible, isothermal ideal gas,
and adiabatic ideal gas.
Reference Pressure Real
Reference pressure is required only for the ideal gas laws.
Specific Heat Ratio Real
This parameter is only required for adiabatic processes. For ideal monoatomic gases the ratio is
5/3. Only required for the adiabatic compressibility model.
Bulk Modulus Real
The parameter β in the weakly compressible material model.
Mean Free Path Real
If the viscosity model assumes rarefied gases the mean free path of the gas molecules in the
reference pressure must be given.
Flow Admittance Real
The steady-state flow admittance resulting from perforation, for example.
Body Force bf id
FilmPressure Lower Limit Real
The lower limit for the pressure that will be iteratively be enforced when the soft limiters are
active.
Boundary Condition bc id
FilmPressure Real
Sets the boundary conditions for the pressure. Usually the deviation from reference pressure is
zero at the boundaries.
Open Side Logical
The open end effect may be taken into account by setting this keyword True.

Keywords for ReynoldsPostprocess

This solver uses largely the same keywords that are already defined above. Only the Solver section has its
own keyword settings. This solvers should be active in the same bodies than the ReynoldsSolver.

Solver solver id
Equation String ReynoldsPostprocess
A describing name for the solver. This can be changes as long as it is used consistently.
Procedure File "ReynoldsSolver" "ReynoldsPostProcess"
Name of the solver subroutine.
Reynolds Pressure Variable Name String
The name of the field that is assumed to provide the pressure field. The default is FilmPressure.
Note that the Variable of this equation need not to be defined since it is automatically set when
any of the field computation is requested.
Calculate Force Logical
Calculate the forces resulting from the pressure distribution computed with the Reynolds equa-
tion. The name of the field is obtained by adding the suffix Force.
Calculate Flux Logical
Calculate the fluxes resulting from the pressure distribution computed with the Reynolds equa-
tion. The name of the field is obtained by adding the suffix Flux.
Calculate Heating Logical
Calculate the heating efficiency from the pressure distribution computed with the Reynolds equa-
tion. The name of the field is obtained by adding the suffix Heating.

CSC – IT Center for Science

BIBLIOGRAPHY 44

Calculate Force Dim Integer

By default the dimension of the force field is the mesh dimension plus one. Sometimes the pres-
sure lives on a 1D line of a 2D mesh. Then this keyword may be used to supress the dimension
of force to two.
Calculate Flux Dim Integer
As the previous keyword but for the flux.

Bibliography
[1] B.J. Hamrock, S.R. Schmid, and B.O. Jacobson. Fundamentals of fluid film lubrication. Marcel Dekker,
second edition, 2004.
[2] P. Rback, A. Pursula, V. Junttila, and T. Veijola. Hierarchial finite element simulation of perforated
plates with arbitrary hole geometries. In NANOTECH 2003, San Francisco, 23-27 February 2003,
volume 1, pages 194–197.
[3] T. Veijola. APLAC 7.60 Reference Manual, January 2002. Electromechanical Macro Models.
[4] T. Veijola, H. Kuisma, J. Lahdenper, and T. Ryhnen. Equivalent-circuit model of the squeezed gas
film in a silicon accelerometer. Sensors and Actuators A, pages 239–248, 1995.

[5] T. Veijola and P. Rback. A method for solving arbitrary mems perforation problems with rare gas
effects. In NANOTECH 2005, Anaheim, May 8-12, 2005, volume 3, pages 561–564.

CSC – IT Center for Science

 Part II

Models of Solid Mechanics

CSC – IT Center for Science

Model 6

Linear Elasticity

Module name: StressSolve

Module subroutines: StressSolver
Module authors: Juha Ruokolainen
Document authors: Juha Ruokolainen, Thomas Zwinger

6.1 Introduction
This module computes displacement field from the Navier equations. The Navier equations correspond to
linear theory of elastic deformation of solids. The material may be anisotropic and stresses may be computed
as a post processing step, if requested by the user. Thermal stresses may also be requested.

6.2 Theory
The dynamical equation for elastic deformation of solids may be written as

∂ 2 d~
ρ − ∇ · τ = f~, (6.1)
∂t2

where ρ is density, d~ is the displacement field, f~ given volume force, and τ the stress tensor. Stress tensor is
given by
τ ij = C ijkl εkl − β ij (T − T0 ), (6.2)
where ε is the strain and quantity C is the elastic modulus. The elastic modulus is a fourth order tensor,
which has at the most 21 (in 3D, 10 in 2D) independent components due to symmetries. In Elmer thermal
stresses may be considered by giving the heat expansion tensor β and reference temperature of the stress free
state T0 . The temperature field T may be solved by the heat equation solver or otherwise. The linearized
strains are given simply as:
1
ε = (∇d~ + (∇d) ~ T ). (6.3)
2

6.2.1 Material laws

For isotropic materials the elastic modulus tensor may be reduced to two independent values, either the Lame
parameters or Young’s modulus and Poisson’s ratio. The stress tensor given in terms of the Lame parameters
is:
~ − β(T − T0 )I,
τ = 2µε + λ∇ · dI (6.4)

CSC – IT Center for Science

6. Linear Elasticity 47

where µ and λ are the first and second Lame parameters respectively, β the heat expansion coefficient, and
I is the unit tensor. The Lame parameters in terms of Young’s modulus and Poisson’s ratio read
Yκ Y
λ= , µ= (6.5)
(1 + κ)(1 − 2κ) 2(1 + κ)

except for plane stress situations (τz = 0) where λ is defined as

Yκ
λ= . (6.6)
(1 − κ2 )

Quantities Y and κ are the Young’s modulus and Poisson’s ratio respectively.
For anisotropic materials, the stress-strain relations may be given in somewhat different form:

τV = EεV , (6.7)

where τV and εV are the stress and strain vectors respectively. The 6 × 6 matrix E (in 3D, 4 × 4 in 2D) is
the matrix of elastic coefficients. The stress and strain vectors are defined as
T
τV = (τx τy τz τxy τyz τxz ) (6.8)

and
T
εV = (εx εy εz 2εxy 2εyz 2εxz ) . (6.9)
In 2D the stress vector is
T
τV = (τx τy τz τxy ) (6.10)
and the strain vector
T
εV = (εx εy εz 2εxy ) . (6.11)
When plane stress computation is requested τz = 0, otherwise εz = 0. Cylindrically symmetric case is
identical to the 2D case, the components are given in the order of r, z, and φ. The matrix E is given as input
for the anisotropic material model of Elmer.

6.2.2 Viscoelastic Maxwell model

Assuming incompressibility, a viscoelastic Maxwell model is introduced [1] by evolving the viscoelastic
stress tensor, τve ,
∂τve ∂τ µ
= + (τve − ΠI) , (6.12)
∂t ∂t ν
with µ denoting the dynamic viscosity of the material as well as Π and I standing for the isotropic part of
the Cauchy stress tensor and the unit tensor, respectively. τ still denotes the elastic contribution of the stress
tensor, which in case of incompressibility is altered to

τ = ΠI + 2µ. (6.13)

If the viscoelastic model is used in the context of solid-Earth deformation, a restoring force (second term
below), called Gravitational Pre-stress Advection (GPA), has to be introduced to prevent a loaded Earth to
collapse [1]. The quasi-stationary momentum balance then reads
 
∇ · τ − ρg ∇ ~ez · d~ = 0, (6.14)
|{z}
=cGP A

where g is the acceleration by gravity and ~ez the vertical direction (aligned with gravity). cGP A = ρg is the
local coefficient for gravitational pre-stress advection, changing between different layers of the Earth.

CSC – IT Center for Science

6. Linear Elasticity 48

6.2.3 Modal, harmonic and stability analysis

In addition to steady state and time dependent equations, modal, harmonic and stability analysis may be
considered. In modal analysis the Fourier transform of the homogeneous form of the dynamical equation is
~ = ∇ · τ (φ),
ρω 2 φ ~ (6.15)

or Z Z
ω 2
ρφk ψk dΩ = ~ ij (ψ)
τij (φ) ~ dΩ, (6.16)
Ω Ω

where ω is the angular frequency and φ ~ is the corresponding vibration mode.

When modal analysis of pre-stressed solids are considered, we first perform a steady analysis to compute
stress tensor, here denoted by σij , and solve the variational equation
Z Z Z
~ ij (ψ)
~ dΩ + ∂φk ∂ψk
ω2 ρφk ψk dΩ = τij (φ) σij dΩ. (6.17)
Ω Ω Ω ∂xi ∂xj

The last term on the right-hand-side represents here the geometric stiffness due to external loads, thermal
stresses etc.
In stability analysis the buckling modes φ~ are obtained from
Z Z
∂φk ∂ψk ~ ij (ψ)
~ dΩ,
−λ σij dΩ = τij (φ) (6.18)
Ω ∂xi ∂xj Ω

where λ is the margin of safety with respect to bifurcation (the current load can be multiplied by factor λ
before stability is lost).
The equations may be interpreted as generalized eigenproblems and solved with standard techniques.

6.2.4 Rayleigh damping

Damping may be taken into consideration using viscous damping or Rayleigh damping, in which it is as-
sumed that the damping matrix C is proportional to the mass M and stiffness matrices K, or

C = αM + βK (6.19)

The identification of suitable damping coefficients α and β may be a difficult task.

6.2.5 Boundary conditions

For each boundary either a Dirichlet boundary condition

di = dbi (6.20)

or a force boundary condition

τ · ~n = ~g (6.21)
must be given. The default boundary condition is the natural boundary condition which implies that ~g = 0.
The user may give spring k or damping λ coefficients on the boundary. These enable the introduction of
the force term in the form
∂ d~
~g = k d~ + λ (6.22)
∂t
which may be solved implicitly maintaining the linear form of the equation.

CSC – IT Center for Science

6. Linear Elasticity 49

6.2.6 Model lumping

For linear structures it is possible to create a lumped model that gives the same dependence between force
and displacement as the original distributed model,

F = KD (6.23)

where F = (Fx Fy Fz Mx My Mz )T and D = (Dx Dy Dz φx φy φz )T . However, the lumped model is not

uniquely defined as it depends on the force or displacement distribution used in the model lumping. In the
current model lumping procedure the lumping is done with respect to a given boundary. The lumped force
and momentum are then integrals over this boundary,
Z
Fi = fi dA. (6.24)
A

Lumped displacements and angles are determined as the mean values over the boundary,
Z
1
Di = di dA. (6.25)
A A

Therefore the methodology works best if the boundary is quite rigid in itself.
There are two different model lumping algorithms. The first one uses pure lumped forces and lumped
moments to define the corresponding displacements and angles. In 3D this means six different permutations.
Each permutation gives one row of the inverse matrix K −1 . Pure lumped forces are obtained by constant
force distributions whereas pure moments are obtained by linearly varying loads vanishing at the center of
area. Pure moments are easily achieved only for relatively simple boundaries which may limit the usability
of the model lumping utility.
The second choice for model lumping is to set pure translations and rotations on the boundary and
compute the resulting forces on the boundary. This method is not limited by geometric constraints. Also
here six permutations are required to get the required data. In this method the resulting matrix equation is
often better behaving in comparison with the model lumping by pure forces which may be another reason to
favour this procedure.

6.3 Keywords
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere.

Equation String [StressSolver]

A describing name for the solver. This can be changed but it must be given,
Procedure File "StressSolve" "StressSolver"
Name of the solver subroutine.
Eigen Analysis Logical
Modal or stability analysis may be requested with this keyword.
Eigen System Values Integer
The number of the lowest eigen states must be given with this keyword, if modal or stability
analysis is in effect.
Harmonic Analysis Logical
Time-harmonic analysis where the solution becomes complex if damping is defined. The solu-
tion algorithm assumes that the diagonal entries in the matrix equation dominates.
Frequency Real
The frequency related to the harmonic analysis. If the simulation type is scanning this may a
scalar function, otherwise it is assumed to be a vector of the desired frequencies.

CSC – IT Center for Science

6. Linear Elasticity 50

Displace Mesh Logical

Should the mesh be deformed by the displacement field. The default is True except for eigen
and harmonic analysis.
Stability Analysis Logical
If set to true, then eigen analysis is stability analysis. Otherwise modal analysis is performed.
Geometric Stiffness Logical
If set to true, then geometric stiffness is taken into account in modal analysis.
Calculate Strains Logical
Computes the strain tensor of the solution.
Calculate Stresses Logical
If set to true the stress tensor will be computed. Also von Mises will be computed by default.
Calculate Principal Logical
Computes the principal stress components.
Calculate Pangle Logical
Calculate the principal stress angles.
Model Lumping Logical
If model lumping is desired this flag should be set to True.
Model Lumping Filename File
The results from model lumping are saved into an external file the name of which is given by
this keyword.
Fix Displacement Logical
This keyword defines whether the displacements or forces are set and thereby chooses the model
lumping algorithm.
Constant Bulk System Logical
For some type of analysis only the boundary conditions change from one subroutine call to
another. Then the original matrix may be maintained using this logical keyword. The purpose is
mainly to save time spent on matrix assembly.
Update Transient System Logical
Even if the matrix is defined constant it may change with time. The time may also be pseudo-time
and then for example the frequency could change with time thus making the harmonic system
different between each timestep. This keyword has effect only if the previous keyword is also
defined to be true.
Maxwell Material Logical
If set to true, viscoelastic material model is computed. In case of incompressibility of the material
the keyword Incompressible has to be activated. The user has to supply a value for the
viscosity in the Material section in this case.
Incompressible Logical
Enables computation of incompressible material in connection with the viscoelastic Maxwell
material. This demands to declare a pressure variable as an additional degree of freedom in the
solver. For a two-dimensional problem, that would read as Variable = String "t[d:2
p:1]", with d declaring the displacements and p the pressure (the isotropic part of Cauchy
stress tensor).

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
Stress Analysis Logical
if set to True, solve the Navier equations.
Plane Stress Logical
If set to True, compute the solution according to the plane stress situation τzz = 0. Applies
only in 2D.

CSC – IT Center for Science

6. Linear Elasticity 51

Body Force bf id
The body force section may be used to give additional force terms for the equations.
Stress Bodyforce 1 Real
Stress Bodyforce 2 Real
Stress Bodyforce 3 Real
The keywords may be used to give volume force.
Stress Bodyforce 1 im Real
Stress Bodyforce 2 im Real
Stress Bodyforce 3 im Real
The keywords may be used to give volume force for the imaginary part. May be applied only to
harmonic solution of the equation.
Stress Load Real
Keyword for defining stress load for the body.
Strain Load Real
Keyword for defining strain load for the body.
Gravitational Prestress Advection Logical
Switches the additional restoring term of pre-stress advection used in solid-Earth deformation
GPA Coeff Real
Sets the factor of the gravitational pre-stress advection, cGP A

Initial Condition ic id
The initial condition section may be used to set initial values for the field variables. The following
variables are active:
Displacement i Real
For each displacement component i= 1, 2, 3.

Material mat id
The material section is used to give the material parameter values. The following material parameters
may be set in Navier equations.
Density Real The value of density is given with this keyword. The value may be constant, or
variable.
Poisson Ratio Real
For isotropic materials Poisson’s ratio must be given with this keyword.
Youngs Modulus Real
The elastic modulus must be given with this keyword. The modulus may be given as a scalar for
the isotropic case or as 6 × 6 (3D) or 4 × 4 (2D and axisymmetric) matrix for the anisotropic
case. Although the matrices are symmetric, all entries must be given.
Rayleigh Damping Logical
Apply Rayleigh damping.
Rayleigh Damping Alpha Real
Rayleigh Damping Beta Real
The parameters of Rayleigh damping.
Pre Stress Real
One may give prestress as an input to the solver.
Pre Strain Real
One may give prestrain as an input to the solver.

CSC – IT Center for Science

6. Linear Elasticity 52

Heat Expansion Coefficient Real

If thermal stresses are to be computed this keyword may be used to give the value of the heat
expansion coefficient. May also be given as 3 × 3 tensor for 3D cases, and 2 × 2 tensor for 2D
cases.
Reference Temperature Real
If thermal stresses are to be computed this keyword may be used to give the value of the reference
temperature of the stress free state.
Rotate Elasticity Tensor Logical
For anisotropic materials the principal directions of anisotropy do not always correspond to the
coordinate axes. Setting this keyword to True enables the user to input Young’s modulus matrix
with respect to the principal directions of anisotropy. Otherwise Young’s modulus should be
given with respect to the coordinate axis directions.
Material Coordinates Unit Vector 1(3) Real [1 0 0]
Material Coordinates Unit Vector 2(3) Real [0 0.7071 0.7071]
Material Coordinates Unit Vector 3(3) Real [0 -0.7071 0.7071]
The above vectors define the principal directions of the anisotropic material. These are needed
only if Rotate Elasticity Tensor is set to True. The values given above define the
direction of anisotropy to differ from the coordinate axes by a rotation of 45 degrees about x-axis,
for example.
Mesh Velocity 1 Real
Mesh Velocity 2 Real
Mesh Velocity 3 Real
Keywords for giving the mesh velocity
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. The one related to Navier
equations are
Displacement i Real
Dirichlet boundary condition for each displacement component i= 1, 2, 3.
Normal-Tangential Displacement Logical
The Dirichlet conditions for the vector variables may be given in normal-tangential coordinate
system instead of the coordinate axis directed system. The first component will in this case be
the normal component and the components 2, 3 two orthogonal tangent directions.
Normal Force Real
A force normal to the boundary is given with this keyword.
Force i Real
A force in the given in coordinate directions i= 1, 2, 3.
Force i Im Real
An imaginary part of the force in the given in coordinate directions i= 1, 2, 3. Applies only to
harmonic simulation.
Normal Force Im Real
A imaginary part of the force normal to the boundary is given with this keyword. Applies only
to harmonic simulation.
Damping Real
Introduces a force proportional to velocity with the given coefficient. Also Damping i and
Damping ij may be given.
Spring Real
Introduces a force proportional to displacement with the given coefficient. Also Spring i and
Spring ij may be given.

CSC – IT Center for Science

BIBLIOGRAPHY 53

Stress Load Real

Keyword for defining stress load for the boundary.
Model Lumping Boundary Logical True
When using the model lumping utility the user must define which boundary is to be loaded in
order to determined the lumped model.

Bibliography
[1] T. Zwinger, GA. Nield, J. Ruokolainen, and M.A. King. A new open-source viscoelastic solid earth
deformation module implemented in Elmer (v8.4). Geoscientific Model Development, 13:1155–1164,
2020.

CSC – IT Center for Science

Model 7

Finite Elasticity

Module name: ElasticSolve

Module subroutines: ElasticSolver
Module authors: Mikko Lyly, Juha Ruokolainen, Mika Malinen
Document authors: Mika Malinen

7.1 Introduction
This chapter is concerned with the equations which describe finite deformations of elastic solids. As the
region of space occupied by the body at time t is not known in advance, it is not convenient to handle
the equations in the form that expresses the field equations on the deformed configuration. Therefore the
associated problem is formulated here by employing the reference configuration which equals to the region
occupied by the body before the deformation.

7.2 Field equations

Let Ω denote the reference configuration, so that the region of space occupied by the body at the time t is
given by
Ωt = x(Ω, t),
with x(·, t), for fixed t, a deformation of Ω. If we define the displacement u(p, t) of the material point p ∈ Ω
by
u(p, t) = x(p, t) − p,
the basic system of field equations describing finite deformations of the body Ω may then be written as
ρ0 ü − Div S = b0 ,
S = F Σ̄(C), (7.1)
T
F = I + ∇u, C = F F,
where ρ0 gives the density when the body is in the reference position, the tensor field S is referred to as the
first Piola-Kirchhoff stress, and b0 = b0 (p, t) defines a body force. The response function Σ̄(C) generally
characterizes the second Piola-Kirchhoff stress as a function of the right Cauchy-Green tensor C.
In the basic case it is assumed that either
λ
Σ̄(C) = [tr(C − I)]I + µ(C − I) (7.2)
2
or, when the neo-Hookean material is assumed,
λ
Σ̄(C) = [det C − 1]C −1 + µ(I − C −1 ), (7.3)
2

CSC – IT Center for Science

7. Finite Elasticity 55

with λ and µ the Lame material parameters. We note that a common way to express (7.2) uses the material
strain tensor
E = 1/2(C − I), (7.4)
so that the constitutive law (7.2) may be written as

Σ = λtr(E)I + 2µE.

To treat the incompressible neo-Hookean material associated with the limit case λ → ∞ (or equivalently
ν → 1/2, with ν the Poisson ratio), we introduce an auxiliary field p defined by
1
(1/λ)p = − [det C − 1] (7.5)
2
to replace (7.3) by
Σ̄(C, p) = −pC −1 + µ(I − C −1 ). (7.6)
To handle the case of a nearly incompressible material (the value of ν close to 0.5) computationally, the field
p is taken to be an additional unknown which is solved under the constraint (7.5). It is notable that in the limit
case of incompressible material p is unique only up to a constant if the displacement is prescribed over the
entire boundary of the body (a special care is then needed to ensure that the condition det C = det F 2 = 1
is respected by the boundary conditions).
The solver also offers some utilities to handle more general constitutive laws so that a user-defined
material model in the form of an Abaqus user subroutine (UMAT) may be included. In this case the con-
stitutive law has to be defined differently by employing the Cauchy stress σ whose material description
σ m (p, t) ≡ σ(x(p, t), t) is related to the first Piola-Kirchhoff stress by

S = (det F )σ m F −T . (7.7)

A user-defined subroutine should define a stress response function σ̄ to specify how the Cauchy stress de-
pends on a strain field Ê(F ) and an additional N -tuple of state variable fields denoted by q = (q1 , . . . , qN ).
One may then consider a generic constitutive law of the type

σ m (p, t) = σ̄(Ê(F )(p, t), q(p, t)). (7.8)

The user-defined subroutine should also define the derivative of the Cauchy stress at the current state with
respect to the strain variable for performing the nonlinear solution procedure. That is, in the differentiation
the stress response function is treated as the composition

F 7→ σ̄(·, q) ◦ Ê(F ), (7.9)

with q being taken as a parameter, so that the Fréchet differential of (7.9) is obtained by using the chain rule
as
U 7→ Dσ̄(Ê(F ), q)[DÊ(F )[U ]]. (7.10)
The user-defined subroutine must thus return a representation of Dσ̄(Ê(F ), q) so that the differential (7.10)
can be generated on the side where the user-defined subroutine is called. In this connection the strain field
Ê(F ) need not necessarily be the material strain (7.4), as the Hencky (logarithmic) strain or the standard
linearized strain can also be used. Including a user-defined material model requires some programming skills
and the best place to check for the current functionality is the solver code. A template subroutine for a user-
defined material model can also be found in the file UMATLib.F90 that is located in the same directory as
the code of the solver module.

7.3 Boundary conditions

Boundary conditions may be obtained by prescribing the displacement and surface traction on complemen-
tary parts Γ1 and Γ2 of the boundary ∂Ω, respectively. The displacement boundary condition is simply of
the form
u = û(p, t), (7.11)

CSC – IT Center for Science

7. Finite Elasticity 56

with û a prescribed vector field on Γ1 × [0, T ].

Handling surface traction is more involved. First, assume that the surface traction vector s on the de-
formed surface x(Γ2 , t) is normal to the tangent plane of the deformed boundary surface, so that

s(x, t) = g(x, t)m(x),

where m(x) is the unit normal on the deformed configuration, x ∈ x(Γ2 , t) for any t, and g(x, t) is a given
scalar function. This can be shown to be equivalent to specifying the values of Sn such that

Sn = ĝ(det F )F −T n on Γ2 × [0, T ], (7.12)

where n = n(p) is the normal vector to the boundary ∂Ω and ĝ = ĝ(p, t) = g(x(p, t), t). The constraint
(7.12) gives rise to a nonlinear force term which is handled in the computational solution iteratively by using
a lagged-value approximation.
The surface traction s may also be specified by giving its components with respect to the frame of
reference such that
s(x(p, t), t) = ŝ(p, t), (7.13)
with ŝ(p, t) a given vector. While the condition (7.13) specifies the actual force per unit area of the deformed
surface, it also possible to specify directly the pseudo-traction s0 = Sn which gives the actual force per
unit undeformed area. If the pseudo-traction is specified on Γ2 as

s0 (p, t) = ŝ0 (p, t), (7.14)

the total force exerted across Γ2 is then given by the surface integral
Z
ŝ0 dΓ.
Γ2

If the alternate (7.13) is used, the total force is obtained by

Z q
ŝ(det F ) n · (F −1 F −T )n dΓ
Γ2

where the additional scalar term in the integrand relates to the area change during the deformation.

7.4 Linearization: The basic constitutive laws

To handle the model computationally, the constitutive law S = Ŝ(F ) = F Σ(F ), with Σ(F ) = Σ̄(F T F ),
has to be linearized also. This can be done in terms of the derivative DŜ(F )[U ] by using the Newton
approximation
Ŝ(F k+1 ) ≈ Ŝ(F k ) + DŜ(F k )[F k+1 − F k ].
We then have

Ŝ(F k+1 ) ≈ Ŝ(F k ) + F k DΣ(F k )[F k+1 − F k ] + (F k+1 − F k )Σ(F k ).

In view of F k+1 − F k = ∇uk+1 − ∇uk , this leads to the linearization

Ŝ(F k+1 ) ≈ Ŝ(F k ) + F k DΣ(F k )[∇uk+1 − ∇uk ] + (∇uk+1 − ∇uk )Σ(F k )

= Ŝ(F k ) − F k DΣ(F k )[∇uk ] − ∇uk Σ(F k ) + F k DΣ(F k )[∇uk+1 ] + ∇uk+1 Σ(F k ).
(7.15)

In the case of (7.2) the derivative of the response function Σ is given by

λ
DΣ(F )[∇v] = tr(F T ∇v + ∇v T F )I + µ(F T ∇v + ∇v T F ),
2

CSC – IT Center for Science

7. Finite Elasticity 57

while
DΣ(F )[∇v] =λ(det F )2 tr(∇vF −1 )C(F )−1 +
λ
[µ − (det F − 1)(det F + 1)]C(F )−1 [F T ∇v + ∇v T F ]C(F )−1
2
for the neo-Hookean material obeying (7.3). In the computation of the associated tangential stiffness matrix,
which result from substituting the approximation (7.15) into the discrete version of the weak formulation of
(7.1), the following self-adjointness property

F k DΣ(F k )[∇uk+1 ] · ∇v + ∇uk+1 Σ(F k ) · ∇v = F k DΣ(F k )[∇v] · ∇uk+1 + ∇vΣ(F k ) · ∇uk+1

is also used.
When a nearly incompressible neo-Hookean material is considered, we need to linearize both the consti-
tutive law S = Ŝ(F , p) = F Σ(F , p), with Σ(F , p) = Σ̄(F T F , p), and the constraint

ϕ(F , p) = 0 (7.16)

where
ϕ(F , p) = εp + 1/2(det F )2 − 1/2 (7.17)
with
ε = 1/λ. (7.18)
The Newton updates related to solving (7.16) are given by

(det F k )2 tr[(F k+1 − F k )F −1

k ] + ε(pk+1 − pk ) = −ϕ(F k , pk ). (7.19)

To obtain the Newton linearization of the stress response function, we note in particular that the derivative
of the function G(F , p) = −pC(F )−1 is given by

DG(F , p)[(U , h)] = −hC(F )−1 + pC(F )−1 [F T U + U T F ]C(F )−1 .

It then follows that

DΣ(F , p)[(U , h)] = −hC(F )−1 + (p + µ)C(F )−1 [F T U + U T F ]C(F )−1 . (7.20)

7.5 Linearization: The case of a user-defined material model

Other constitutive laws can be defined by including a user-defined material model in the form of an Abaqus
user subroutine (UMAT). In contrast to the other constitutive laws, such subroutine is expected to return the
Cauchy stress corresponding to the current estimate of the strain increment with respect to the previous con-
verged solution (the solution before the time/load increment) as well as the derivative of the stress response
function for computing the differential (7.10).
It should be noted that, despite relying on the Cauchy stress, the weak formulation is still generated from
the equilibrium equations expressed in terms of the first Piola-Kirchhoff stress. The stress power calculations
are thus done in terms of an energetically conjugate pair of the first Piola-Kirchhoff stress and the rate of
change of the deformation gradient. To this end, in view of (7.7)–(7.9), we consider the mapping

F 7→ Ŝ(F ) = (det F ){σ̄(·, q) ◦ Ê(F )}F −T (7.21)

and use (7.10) to obtain the Fréchet differential

DŜ(F )[U ] = (det F ){Dσ̄(Ê(F ), q)[DÊ(F )[U ]]}F −T

(7.22)
+ (det F )tr(U F −1 )σ̄(Ê(F ), q)F −T − (det F )σ̄(Ê(F ), q)F −T U T F −T .

In the differentiation the state variables are thus treated as parameters. In the case of a user-defined material
model the equation (7.22) provides the key ingredient for linearization.

CSC – IT Center for Science

7. Finite Elasticity 58

7.6 Stress and strain computation

In addition to solving for the displacement, the solver can produce the strain and stress fields associated with
the solution. In this connection the strain tensor is defined by (7.4). In the stress computation the material
description of the usual Cauchy stress σ is produced. That is, we measure the surface force per unit area in
the deformed configuration and write σ m (p, t) = σ(x(p, t), t). We note that this stress is related to one of
the Piola-Kirchhoff stresses as

σ m = (det F )−1 SF T = (det F )−1 F Σ̄(C)F T . (7.23)

7.7 Keywords
Simulation
In specifying the keywords for the simulation section, note that all coordinate systems are not sup-
ported.
Coordinate System String
The coordinate system may be Cartesian 2D, Cartesian 3D or Axi Symmetric.
Material mat id
The following keywords relate to giving the material parameters for the finite elasticity solver.
Density Real
This keyword is used for defining the density field ρ0 corresponding to the reference configura-
tion.
Poisson Ratio Real
The values of the scalar Lame material parameters depend on the Poisson ratio as in the case of
the linear elasticity solver. The Poisson ratio is given by using this keyword.
Youngs Modulus Real
The values of the scalar Lame material parameters depend on Young’s modulus as in the case of
the linear elasticity solver. This keyword specifies the value of Young’s modulus.
UMAT Subroutine File
The value of this keyword consists of two string parameters. The first parameter specifies the
name of a compiled file containing the definition of a user-defined material model in the UMAT
form. The second parameter defines the name of the user-defined subroutine. If this keyword is
used, all material models must be defined in the UMAT form.
Number of Material Constants Integer
The value of this keyword defines the number of material constants that are passed to the UMAT
subroutine.
Material Constants Real
The values of the material constants passed to the UMAT subroutine.
Number of State Variables Integer
This keyword is used to declare the number of state variables.
Name String
This keyword may be used to define the name argument of the UMAT subroutine.
Equation eq id

Plane Stress Logical

If the coordinate system is chosen to be Cartesian 2D, this keyword may be used to activate
nonlinear plane stress analysis. In the case of plane stress the definition of the Lame parameter λ
is altered such that the plane stress components are directly obtained in terms of the plane strain
components. The strain E33 can then be expressed as E33 = −ν/(1 − ν)(E11 + E22 ).

CSC – IT Center for Science

7. Finite Elasticity 59

Solver solver id

Equation String [ElasticSolver]

A describing name for the solver. This can be changed but it must be given,
Procedure File "ElasticSolve" "ElasticSolver"
Name of the solver subroutine.
Neo-Hookean Material Logical
By default the constitutive law (7.2) is employed. Switching to the neo-Hookean material model
(7.3) can be performed by giving the value True for this keyword.
Mixed Formulation Logical
This keyword is used to handle incompressible or nearly incompressible material obeying the
neo-Hookean constitutive law. If the value True is given for this keyword, the field p is taken to
be an additional unknown which is solved under the constraint (7.5). In this case the solver
assumes that the mesh files correspond to the lowest-order finite elements (the lowest-order
pressure approximation together with the second-order displacement approximation is then con-
structed by default). In addition, the default names for the displacement variable u and pressure
variable p are then Disp and Pres, respectively.
Calculate Strains Logical
If the value True is given for this keyword, the strains are also computed. The strain components
are output into an ordered six-tuple as (Exx Eyy Ezz Exy Eyz Exz ). However, in the axially
symmetric simulation only four components are produced as (Exx Ezz Eyy Exy ), with the
convention x = r and z = θ.
Calculate Stresses Logical
If the value True is given for this keyword, the Cauchy stress (7.23) is also computed. The
stress components are output into an ordered six-tuple in the same way as the strain.
Calculate Principal Logical
If the strain or stress computation is activated, this keyword can be used to activate the computa-
tion of principal components.
Calculate PAngle Logical
This keyword can be used to activate the computation of the principal angles for the stress tensor.
If the value True is given for this keyword, then the computation of principal components is also
activated.
Initialize State Variables Logical
If the material model is defined in terms of a user-defined material model (UMAT), an extra call
of the UMAT subroutine can be done to obtain the state variables in the initial state (stress-free
initial condition is supposed).

Body Force bf id
This section may be used to define body forces.
Inertial Bodyforce j Real
This keyword may be used to give the component j of the body force b(x, t) in order to define
b0 = ρ0 (p)b(x(p, t), t). It is noted that in this case b(x, t) defines the body force per unit mass.
The density changes are then considered correctly , i.e. the condition ρ(x(p, t), t) det F (p, t) =
ρ0 (p) is respected.
Stress Bodyforce j Real
This keyword may be used to give the component j of the body force b(x, t) in order to define
b0 = (det F )b(x(p, t), t). It is noted that b(x, t) is now the body force per unit volume of
the deformed body, so this type of force is appropriate for specifying true volumetric forces,
whatever they might be.

CSC – IT Center for Science

7. Finite Elasticity 60

Boundary Condition bc id
The Dirichlet conditions (7.11) for the displacement variable of the solver can be given in the standard
manner. Other options for defining boundary conditions are explained in the following.
Normal Surface Traction Real
A surface force which is normal to the deformed boundary and gives force per unit area of the
deformed surface may be given with this keyword.
Surface Traction k Real
By default this keyword may be used to give the actual force per unit area of the deformed sur-
face. The value of this keyword then specifies the component k of ŝ in (7.13). If the keyword
command Pseudo-Traction = True is also given, then the values of this keyword com-
mand are used to determine the components of the pseudo-traction vector ŝ0 which gives the
actual force per unit undeformed area.
Pseudo-Traction Logical
If this keyword has the value True, then the surface force is defined via the pseudo-traction
condition; see the explanation of the keyword Surface Traction k below.
Spring Real
This keyword can be used to generate a reaction force which is aligned with the normal direction
of the undeformed configuration and which is proportional to the displacement in the normal
direction.
Spring i Real
This keyword is similar to the keyword Spring but here the spring coefficients are defined with
respect to the coordinate axes.
FSI BC Logical
If this keyword has the value True, then the Navier–Stokes flow solution is used to determine
the surface force generated by the flow.

CSC – IT Center for Science

Model 8

Shell Equations of Classical Elasticity

Module name: ShellSolver

Module subroutines: ShellSolver
Module authors: Mika Malinen
Document authors: Mika Malinen

8.1 Introduction
This chapter is concerned with the equations which describe deformations of thin elastic shells. Here a shell
refers to a curved three-dimensional body which can be described in terms of its mid-surface and thickness
(the extent of the shell in the direction of normal to the mid-surface). When the placement of the shell in its
reference configuration is described by using a system of normal coordinates (that is, two coordinate curves
on the mid-surface are perpendicular to the third coordinate curve), simplifications to solving 3-D elasticity
equations can be sought via the process of dimensional reduction, so that unknowns that depend only on the
two curvilinear coordinates associated with the shell mid-surface can be employed. Classical shell theory [3]
is dedicated to the study of such models by assuming that the exact parametrization of the shell mid-surface
is known in advance.
However, classical shell theory cannot often be applied in a straightforward manner in connection with
finite element modelling, since in practice the mapping giving the mid-surface is not usually available in an
explicit form. To offer generality, the shell solver described here is also able to create a computational surface
model by assuming that information about the surface position and the director vector (the unit normal to
the exact mid-surface) are given at the nodes of a background mesh. Elementwise approximations of the
mid-surface are then created such that the surface position and the normal to the approximate surface agree
with the data given at the nodes. It should be noted that the approximate mid-surface obtained in this way
generally gives a more accurate description of the surface position than what would be obtained by using
the standard strategy where straightforward Lagrange interpolation merely based on the nodal position data
is employed. Here the approximation of the director field is then derived via straightforward differentiation
of the mapping giving the approximate surface (it should be noted that this approximation is consistent with
the given data at the nodes). As an alternate to the internal surface reconstruction, a higher-order nodal mesh
can be used to derive the necessary geometric data without expecting director data.
In the first place each (physical) element S of the approximate mid-surface is originally parametrized in
terms of the rectangular Cartesian coordinates of points of a usual reference element (a square or an equilat-
eral triangle). However, the solver considered performs additional computation in order to find a convenient
elementwise reparametrization by lines of curvature coordinates, so that we may write S = ϕK (K) where
ϕK : K ⊂ R2 → E3 and the rectangular Cartesian coordinates y α of a point y in K correspond to lines
of curvature coordinates on S (for the basic concepts related to lines of curvature, see [2]). Then each point
on the surface can naturally be associated with an orthogonal system of basis vectors which offer a conve-
nient starting point for representing vector-valued fields over the surface. Since the basis is orthogonal, the
components of a vector field have intuitive physical significance and tensor calculations related to the shell

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 62

equations are greatly simplified in comparison with the case of general curvilinear coordinates.
It is mentioned that this solver can also be adapted to handle special cases where the exact parametrization
of the shell mid-surface by lines of curvature coordinates can be given globally. In this case, the approach of
classical shell theory is followed, so the mathematical formulation is done over a two-dimensional (planar)
reference domain.

8.2 Discrete shell model

The shell models we consider employ kinematic assumptions that enable the approximation of 3-D elasticity
equations without additional assumptions about the state of stress. The simplest assumption conforms with
using solid finite elements which have nodes located on the upper and lower surfaces of the shell, together
with auxiliary degrees of freedom to enable a normal strain field that depends linearly on the normal coor-
dinate. Conventional 2-D shell models can then be derived by imposing the condition of vanishing normal
stress, but use of a refined shell model can also be considered in this setting.

8.2.1 Preliminaries
We may now think of a physical surface element S = ϕK (K) to be associated with the physical solid
element ΩS ⊂ E3 which is the image of the set S × [−d/2, d/2] under a mapping of normal coordinates

(p, y 3 ) 7→ p + y 3 (a3 ◦ ϕ−1

K )(p), (8.1)

with d being the shell thickness and the surface function p 7→ (a3 ◦ ϕ−1 K )(p) giving the unit normal to
the mid-surface at a point p ∈ S in terms of the vector field a3 : K → R3 . Since the normal coordinates
(p, y 3 ) ∈ S × [−d/2, d/2] thus identify a point in the physical element ΩS , it is natural to approximate the
elementwise restriction of the displacement vector field of the shell

u : S × [−d/2, d/2] → R3 , (p, y 3 ) 7→ u(p, y 3 ), (8.2)

in a systematic manner such that

1
u(ϕK (y), y 3 ) ≡ û(y, y 3 ) ≡ v (0) (y) − y 3 v (1) (y) − (y 3 )2 v (2) (y), (8.3)
2
with the vector fields v (k) : K → R3 in two variables being taken as unknowns. The mathematical domain
of definition for three-dimensional shell variables will thus be the set ΩK = K × [−d/2, d/2] whose points
are mapped to the points of the physical space E3 as

(y, y 3 ) 7→ Θ(y, y 3 ) ≡ ϕK (y) + y 3 a3 (y). (8.4)

This representation of geometry follows by writing an alternate referential description of the normal coordi-
nates representation defined by (8.1).
Each physical point Θ(y, y 3 ) of the shell can be associated with three vectors

g k (y, y 3 ) = DΘ(y, y 3 )[êk ] = ∂k Θ(y, y 3 ), (8.5)

with êk being the orthonormal basis vectors associated with the mathematical domain of definition, to give
a covariant basis for the translation space R3 of E3 . Similarly, by restricting to the mid-surface, we define a
set of surface basis vectors ai : K → R3 , which give the covariant basis at p = ϕK (y), via

aα (y) = DϕK (y)[êα ] = ∂α ϕK (y), a3 (y) · aα (y) = 0. (8.6)

The covariant components of the metric surface tensor A (the first fundamental form) are now given by

Aαβ (y) = aα (y) · aβ (y). (8.7)

We also define Bαβ : K → R by

Bαβ (y) = a3 (y) · ∂α aβ (y) = −aα (y) · ∂β a3 (y). (8.8)

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 63

They give the covariant components of the second fundamental form B of the surface at p = ϕK (y). We
shall also need the contravariant basis vectors ai of the surface satisfying the orthogonality conditions

ai (y) · aj (y) = δij , (8.9)

with δij being the Kronecker’s symbol.

When lines of curvature coordinates are used, the two sets of basis vectors are related by

g 1 (y, y 3 ) = µ11 (y, y 3 )a1 (y), g 2 (y, y 3 ) = µ22 (y, y 3 )a2 (y), g 3 (y, y 3 ) = a3 (y) (8.10)

where µβα are the mixed components of a diagonal (shifter) tensor. We then have

µ11 (y, y 3 ) = 1 + y 3 /R1 (y), µ22 (y, y 3 ) = 1 + y 3 /R2 (y) (8.11)

with
1 B11 (y) 1 B22 (y)
=− = −B11 (y) and =− = −B22 (y) (8.12)
R1 (y) A11 (y) R2 (y) A22 (y)
being the principal curvatures. The sign convention is here chosen such that the principal radii of curvature
Rα > 0 if the normal vector is directed away from the centre of curvature.
Two different kinematic assumptions in the form (8.3) can be chosen. The most general version of
(8.3) leads to handling nine scalar fields as unknowns. The simplest kinematic assumption, which does not
necessitate introducing an additional assumption about the state of stress, however corresponds to the choice
where the part v (2) can be expressed simply as

v (2) (y) = [v (2) (y) · a3 (y)]a3 (y), (8.13)

i.e. only one scalar field describes the second-order part with respect to y 3 . The resulting kinematic assump-
tion thus involves seven scalar fields (for original contributions that use this restriction, see historical notes
in [3] and papers by Reissner and Naghdi mentioned there). The assumption that only one quadratic compo-
nent in y 3 is included is motivated by having the ability to expand all components of linearized strain tensor
up to the first-order terms in y 3 . In practice, especially in the context of linear theory, this choice allows the
derivation of a variational formulation which does not necessitate solving the part (8.13) as tightly coupled
with the other unknowns, i.e. its values can be found afterwards when v (k) , k = 0, 1, have first been solved.

8.2.2 The measure of strain

The measure of three-dimensional strain we employ is based on the Green-St Venant strain tensor field
E(û) : ΩK → Sym associated with the elementwise restriction û of the displacement field. Its components
measure the change of the metric tensor associated with the displacement field and are defined such that

2Ēij (û)(·) = g i (·) · ∂j û(·) + ∂i û(·) · g j (·) + [∂i û(·)] · [∂j û(·)]. (8.14)

In practice, we shall perform a change of basis in order to express the strain tensor field as

E(û)(y, y 3 ) = Eij (û)(y, y 3 )ai (y) ⊗ aj (y),

so that the components are then expressed with respect to the surface basis vectors depending only on the
two curvilinear coordinates of the mid-surface. Alternatively, the most basic representation of strain follows
by switching to a local orthonormal basis {e1 (y), e2 (y), e3 (y)} = {e1 (y), e2 (y), e3 (y)} obtained as

aα (y)
eα (y) = , e3 (y) = a3 (y), with Aα (y) = |aα (y)|, (8.15)
Aα (y)
and writing then
E(û)(y, y 3 ) = Êij (û)(y, y 3 )ei (y) ⊗ ej (y).
The components of these representations can be shown to obey the following transformation rules (here the
summation convention is adopted so that a repeated index simultaneously appearing as a subscript and as a

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 64

superscript in a term imply summation over all possible values, with a Greek index being however allowed
to have values in {1, 2})

Eαβ (û) (µ−1 )λα (µ−1 )νβ Ēλν (û) Eα3 (û) (µ−1 )να Ēν3 (û)
Êαβ (û) = = , Êα3 (û) = = ,
Aα Aβ Aα Aβ Aα Aα
Ê33 (û) = E33 (û) = Ē33 (û).

By letting U = (v1 , v2 , . . .) denote an n-tuple of 2-D scalar fields which determine û, we next expand the
components of the strain tensor in powers of the normal coordinate y 3 to obtain the first-order approximation

Eij (û(U))(y, y 3 ) = γij (U)(y) + ij (U)(y) − y 3 κij (U)(y) − y 3 χij (U)(y) (8.16)

where the 2-D fields γij (U) : K → R and κij (U) : K → R are linear with respect to U, while ij (U) :
K → R and χij (U) : K → R are nonlinear. If the shell undergoes only small deflections, linearization can
additionally be performed by omitting the nonlinear terms to write then

Eij (û(U)) = γij (U) − y 3 κij (U).

We note that the tangent plane components γαβ (U) and καβ (U) constitute the so-called membrane strain
and bending strain tensors, while γα3 (U) are the transverse shear strains.
When we simplify the notation by setting

v (0) ≡ v, v (1) ≡ β, v (2) ≡ ψ, (8.17)

the components of the linearized strain tensors have the following component-free representations (the
component-freeness should be understood with respect to the displacements)

2γαβ (U) = aα · ∂β v + ∂α v · aβ ,
2γα3 (U) = a3 · ∂α v − aα · β,
γ33 (U) = −β · a3 ,
καα (U) = aα · ∂α β − κα γαα , (8.18)
2κ12 (U) = a1 · ∂2 β + ∂1 β · a2 − κ2 a1 · ∂2 v − κ1 ∂1 v · a2 ,
2κα3 (U) = a3 · ∂α β − κα a3 · ∂α v + ψ · aα ,
κ33 (U) = ψ · a3 ,

with κ1 ≡ B11 and κ2 ≡ B22 . On the other hand, the nonlinear parts of the strain tensors can be expressed as

2αβ (U) = ∂α v · ∂β v,
2α3 (U) = −β · ∂α v,
33 (U) = 1/2β · β,
(8.19)
2χαβ (U) = ∂α v · ∂β β + ∂α β · ∂β v − (κ1 + κ2 )∂α v · ∂β v,
2χα3 (U) = −β · ∂α β + ψ · ∂α v + κα β · ∂α v,
χ33 (U) = −β · ψ.

It should be noted that under our kinematic assumptions the expression for the linearized normal strain
is precisely
γ33 (U) − y 3 κ33 (U) = −β3 − y 3 ψ3 , (8.20)
so we cannot generally proceed beyond linear terms in y 3 in the expansions of strains. This generally
motivates our choice to truncate the expressions for strains as done in (8.16). In addition, the terms of type
Bβα γαk (U) in the expressions for κij (U) are expected to have little impact on the strain energy of a thin
shell and could therefore be omitted to obtain simplified expressions.
It is notable that the derivatives of ψ do not occur in the expressions for strains when only the terms up to
the first order with respect to y 3 are taken into account. When weak solutions of shell equations are sought,

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 65

the components of ψ are thus seen to be exceptional in that less regularity can be supposed. In addition, in
the context of linear theory together with the restriction (8.13), ψ enters only through its normal component
ψ3 in the expression for κ33 (U). In this case, a variational formulation of the shell problem may be obtained
such that it does not necessitate solving ψ3 as tightly coupled with the other unknowns, i.e. its values can
be found afterwards when v (k) , k = 0, 1, have first been solved. In the context of nonlinear theory such
simplification cannot be attained in a fully consistent manner and using the nine-component shell model
may be a more natural choice. If the nine-component model is not employed and nonlinearities are taken
into account, the shell solver neglects the incomplete part ψ · ∂α v in the expression for χα3 (U), so that a
formulation in terms of v (k) , k = 0, 1, can be obtained.

8.2.3 The principle of virtual work

To simplify the statement of the principle of virtual work, we now shorten the expressions for the strain
components by omitting the splitting into the linear and nonlinear parts, so that

E(û(U)) = ε(U) − y 3 ρ(U) (8.21)

with
εij (U) ≡ γij (U) + ij (U),
(8.22)
ρij (U) ≡ κij (U) + χij (U).

Currently the shell solver can handle only a nonlinear extension of the standard constitutive law for an
isotropic material characterized by Young’s modulus E and Poisson’s ratio ν. That is, we assume that
νE E
Σ̂ij (·) = [Ê11 (û)(·) + Ê22 (û)(·) + Ê33 (û)(·)]δij + Êij (û)(·) (8.23)
(1 + ν)(1 − 2ν) 1+ν

where the scalar fields Σ̂ij : ΩK → R are the components of the second Piola-Kirchhoff stress with respect
to the orthonormal basis. This model is expected to be feasible when the stretches of the shell remain
relatively small, while rigid body deformations of arbitrary magnitude are possible.
The statement of the three-dimensional principle of virtual work can now be put into the form

DU(U)[V] = Q(U, V)

where DU(U)[V] gives the derivative of strain energy and Q(U, ·) is a linear functional determined by
loads. We note that the linear functional does not always depend on the solution U. In that case we could
simplify the statement of the principle of virtual work as

DU(U)[V] = L(V),

with L(·) being a linear functional independent of U. The strain energy is expressed elementwise as
Z p
UK (U) = W (E(û(U))(y, y 3 )) g(y, y 3 )dydy 3 , (8.24)
ΩK

with W : Sym → R giving the strain-energy density and g(y, y 3 ) denoting the determinant of three-
dimensional metric tensor. The contribution to the principle of virtual work can then be expressed as
Z p
R(E(û(U))(y, y 3 )) · DE(û(U))[V](y, y 3 ) g(y, y 3 ) dΩK = QK (U, V) (8.25)
ΩK

for all kinematically admissible V, with the second Piola-Kirchhoff stress field Σ(·) = R(E(û(U))(·))
being found as the derivative R(E) · H = DW (E)[H].
A truly two-dimensional variational formulation follows by using (8.21) in connection with (8.24) and
performing the integration over the thickness of the shell. In the integration, we have chosen to neglect terms

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 66

of O(d/Rα ) in order to simplify the final statement of the 2-D version of the principle of virtual work. When
the restriction (8.13) is employed, after some reduction the strain energy over K may be expressed as
Z n 2 o√
Ed X
UK (U) = ν[ε11 (U) + ε22 (U)]2 + (1 − ν) [εαβ (U)]2 a dK
2(1 − ν 2 )
K α,β=1

Ed(1 − ν)
Z n
ν o2 √
+ ε33 (U) + [ε11 (U) + ε22 (U)] a dK
2(1 + ν)(1 − 2ν) 1−ν
K
√
Z
Ed
+ [(ε13 (U))2 + (ε23 (U))2 ] a dK (8.26)
1+ν
K
2
Ed3 o√
Z n X
2 2
+ ν[ρ 11 (U) + ρ22 (U)] + (1 − ν) [ραβ (U)] a dK
24(1 − ν 2 )
K α,β=1

Ed3 √
Z
+ [(ρ13 (U))2 + (ρ23 (U))2 ] a dK
12(1 + ν)
K

with a being the determinant of the metric surface tensor.

8.2.4 Formulation in terms of the Cartesian components

The component-free expressions for strains (the component-freeness should be understood with respect to
the displacements) enable the approximation of shell equations directly in terms of the orthogonal Carte-
sian components of the vector fields (8.17). The variables of the shell solver are therefore the Cartesian
components with respect to the global frame.

8.2.5 Strain reduction operators vs. high-order approximations

Efficient and reliable finite element discretization of shell equations is a challenging task and unsettled
questions still remain. Shell problems can exhibit different types of asymptotic behaviour when the shell
thickness tends to zero [1]. A great challenge for a finite element designer is to work out a formulation which
works for all possible asymptotic scenarios. An ultimate challenge would be to accompany the method with
a mathematical error analysis covering the full versatility of shell problems.
For the above reasons applying standard finite elements is not an option unless basis functions of high
degree (the p-version of FEM) are used, as standard low-order methods are not suitable for approximating
fields with negligible membrane and transverse shear strains (such case corresponds a bending-dominated
asymptotic behaviour). This relates to a computational trouble known as finite element locking. To obtain
better low-order methods, the shell solver of Elmer employs strain reduction operators which are applied to
the membrane and transverse shear strains and designed, in the first place, to relax constraints that arise in the
case of bending-dominated problems. Currently the strain reduction operators have been worked out only
for the lowest-order approximation (a 3-node triangle or 4-node quadrilateral) under the restriction (8.13).
Approximation with hierarchic p-elements can also be applied, but also in this case the computational
surface model is based on the surface reconstruction derived from information about the surface position and
the director vector at the nodes of a background mesh. At the moment the internal surface reconstruction
is based on mapped polynomials of degree 3, so the accuracy is not expected to be optimal for all element
orders, since geometric errors eventually dominate the error. Numerical over-stiffness due to locking can
however be treated effectively by using finite elements of a sufficiently high order, so even a non-optimal
approximation combination might improve the solution if the dominating error is caused by locking. Note
that the high-order version does not apply any strain reduction operators to alleviate locking, so with this
approach increasing the polynomial order is the only way to handle locking. The p-approximation does not
necessitate using the restriction (8.13).

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 67

8.3 Specifying surface data

In order to improve the approximation of the shell mid-surface, the shell solver needs information about the
director vector. As alternatives the nodal director data can be read from a file, or it can be associated with
an ordinary Elmer variable ”Director” that has been solved before executing the shell solver. It should
be noted that parallel versions of file formats used in connection with reading from files do not exist yet, so
at the moment parallel computation is possible only when the director field is made available as the Elmer
variable ”Director”.
The nodal director data can be formatted into special data files in two ways. The first option is to write a
file mesh.director which lists the director at the nodes in a similar way as nodes are defined in the file
mesh.nodes. That is, the contents of the file mesh.director should be organized as
n1 dx dy dz
n2 dx dy dz
...
nn dx dy dz
The first integer is the identification number for the node followed by three real numbers which are the
components of the director with respect to the global coordinate frame. The file should be located in the
same place as the standard mesh files.
The second option is to provide a file mesh.elements.data which should define the nodal director
in elementwise manner and associate the name ’director’ with this data. Thus, if just the director data
is given, the contents of the file should be arranged as
element: element_id_1
director: dx_1 dy_1 dz_1 ... dx_n dy_n dz_n
end
element: ...
...
end
Here the nodewise ordering of the director data on lines starting with director: must correspond to
that of the mesh.elements file. Also this file should be located in the same place as the standard mesh
files. It is noted that a file mesh.elements.data is considered first in priority. Optionally, given a file
mesh.director, the solver can write the director data as elementwise property to a file whose format con-
forms with a file mesh.elements.data. The elementwise data contained in mesh.elements.data
may generally be discontinuous over adjacent finite elements.
One way to create the Elmer variable ”Director” is to utilize the solver NormalSolver that uses
the background mesh for the computation of the normal vector. This approach can compromise the accuracy
of the geometry model but allows parallel computation. For special cases where the dependency of the
director on the global coordinates is known, a slight modification of the NormalSolver module might be
enough for obtaining both an accurate approximation of the director and having the option to run the shell
solver in parallel.

8.4 Combined analysis with beam sections

If the mesh contains also one-dimensional elements, these lower-dimensional elements can be used to define
additional stiffeners by treating them as elastic beams. The combined model can be assembled in the case
of both linear and nonlinear analysis, but the deformation of beam sections is always computed according to
the linear theory as described in the Model 10 chapter of this manual.
The model parameters of the beam model are named as described in the Model 10 chapter and their
values are read from material sections, so elementwise organized data cannot yet be given. In particular one
of the principal directions of the beam cross section (the y3 -axis) can be given by specifying the value of the
keyword Director.
The shell model does not inherently recognize a moment around the shell director (normal) of the mid-
surface, while the beam formulation which is used employs the full resultant couple (moment) vector with

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 68

three components. To cope with this discrepancy, the beam stiffness matrix is manipulated before assembling
into the global stiffness matrix in such a way that the resultant couple vector cannot have a component with
respect to the director vector of the beam. The beam and shell directors are now defined independently, but
it is natural to construct the combined model so that the shell and beam directors agree in places where the
domains of the two models intersect.

8.5 Keywords
Simulation
Coordinate System String Cartesian 3D
The coordinate system should be selected to be three-dimensional, although basis functions for
computation correspond to 2-D finite elements.
Material mat id
The following keywords relate to specifying the shell thickness and material parameters.
Shell Thickness Real
The thickness d of the shell is specified with this keyword.
Poisson Ratio Real
Poisson’s ratio is given by using this keyword.
Youngs Modulus Real
This keyword specifies the value of Young’s modulus.
Density Real
This keyword is used for defining the density of the material.
Rayleigh Damping Alpha Real
This specifies a coefficient to activate mass-proportional damping.
Solver solver id
Equation String
A describing name for the solver.
Procedure File "ShellSolver" "ShellSolver"
The name of the solver subroutine.
Variable String Deflection[U:3 DNU:3]
The name of the solver variable can be chosen freely (but it is must be used consistently else-
where). The default variable is Deflection[U:3 DNU:3] which is thus suitable for the
model derived under the restriction (8.13). Then the first three components of the solver variable
define the mid-surface displacement field v (0) (the default variable name U), while the rest are
related to the vector v (1) (the default variable name DNU). The variables always correspond to
the orthogonal Cartesian components with respect to the global coordinate frame.
Variable DOFs Integer
The value of this can be either 6 or 9. The value 9 can be used only when p-elements are applied.
The value 6 is given by default.
Large Deflection Logical
By default the nonlinear equations are solved. With the value being False, the linearized strain
tensor is employed.
Eigen Analysis Logical
Eigenanalysis based on the linearized model can be done if this keyword is given the value True.
Displace Mesh Logical
If this keyword is given the value True, the mesh is mapped to represent the deformed config-
uration. The formulation of the total Lagrangian type is nevertheless used, so the shell problem
is posed over the undeformed configuration. In the case of eigenanalysis this keyword is not
supported.

CSC – IT Center for Science

8. Shell Equations of Classical Elasticity 69

Nonlinear System Convergence Tolerance Real

The ratio of the 2-norm of the nonlinear system residual to the 2-norm of the initial right-hand
side vector is always used as the stopping criterion for the nonlinear iteration. This keyword
specifies the stopping tolerance for the Newton iteration to solve the nonlinear system.
Linear System Convergence Tolerance Real
It should be noted that each linearized problem solved during the nonlinear iteration gives an
increment δUk+1 = Uk+1 −Uk to the previous iterate. Therefore, except for the case of solving
the linear shell model (Large Deflection = False), a rather mild stopping tolerance
may often be used for the linear systems without affecting the progress of the nonlinear iteration.
Mesh Reparametrization Logical
If the value True is given, the solver does not apply the internal surface reconstruction which
depends on given director data, but it expects a third-order nodal mesh of the physical mid-
surface. In this case, all geometric information is derived directly from the mesh, so no user-
supplied information about the shell director is needed. At the moment no numerical tricks are
then applied to handle numerical over-stiffness (locking), but the basic third-order approximation
may give reasonable results if the shell is not very thin.
Skip Surface Reconstruction Logical
If the value True is given, the solution of some special cases can be performed such that the
mathematical formulation is given over a two-dimensional (planar) reference domain which is
utilized to give a global parametrization of the mid-surface by lines of curvature coordinates. In
this case, the approximation should be done by using p-elements.
Strain Reduction Operator Integer
This keyword specifies the choice of strain reduction operators. If this keyword is not given, the
solver switches to a method which has been found to give the best results for benchmark cases
considered during the development.
Body Force bf id
Normal Pressure Real
The value of this keyword should give the sum of normal tractions applied to the upper and lower
faces of the shell at y 3 = ±d. If the shell model is nonlinear, this is the normal surface force per
unit area of the deformed surface. In this case the normal to the deformed mid-surface and the
area are computed by using the previous iterate.
Boundary Condition bc id
The Dirichlet conditions for the components of v (0) and v (1) can be given in the standard manner. In
addition, the resultant force vector N and the resultant couple vector M can be specified to give a
mechanical load on a curve c which lies on the mid-surface in its reference configuration and may be
represented as c = f (I), with I ⊂ R. This gives rise to a contribution
Z Z
N (f (s)) · v (f (s)) dc(f (s)) + M (f (s)) · v (1) (f (s)) dc(f (s))
(0)

I I

to the linear functional of the shell problem. Note that by default the components of all data vectors
are defined with respect to the global coordinate frame.
U i Real
If the default variable name is used, then, with i=1,2,3, Dirichlet BCs for the components of
the mid-surface displacement v (0) can be given.
DNU i Real
If the default variable name is used, then, with i=1,2,3, Dirichlet BCs for the components of
v (1) can be given.
Resultant Force i Real
This keyword may be used to give the components of the resultant force N measured per unit
length of a curve c on the mid-surface.

CSC – IT Center for Science

BIBLIOGRAPHY 70

Resultant Couple i Real

This keyword may be used to give the components of the resultant couple M measured per unit
length of a curve c on the mid-surface.
Dead Loads Logical
By default giving constant values for N or M creates “dead loads” whose orientation is fixed
with respect to the global frame. Giving the value False for this keyword alters the meaning
of the resultant force and couple loads such that their orientation follows the deformation of
lines of curvature, with the direction of the first component following the deformation of the
coordinate curve corresponding to the smallest curvature in the undeformed configuration. Then
Resultant Force 3 generally gives an edge-load in the direction of normal to the deformed
mid-surface.
Spring i Real
With i=1,2,3, this keyword may be used to create a resultant force which is proportional to the
displacement along the ith coordinate direction. With i=4,5,6, one may generate a resultant
couple which is proportional to the (i-3)th component of v (1) with respect to the global frame.
Mass i Real
This keyword, with i=1,2,...,6, may be used to assemble an additional mass or a moment
of inertia. The first three components are related to translational DOFs, while the remaining
components are related to the DOFs which determine v (1) ; cf. the indexing convention used in
connection with Spring i.

Bibliography
[1] D. Chapelle and K.J. Bathe. The Finite Element Analysis of Shells - Fundamentals. Springer, second
edition, 2011.
[2] P.G. Ciarlet. An Introduction to Differential Geometry with Applications to Elasticity. Springer, Dor-
drecht, the Netherlands, 2005.
[3] P.M. Naghdi. Foundations of elastic shell theory. In Progress in Solid Mechanics, Vol. 4 (I.N. Sneddon,
R. Hill, Eds) North-Holland, pages 1–90, 1963.

CSC – IT Center for Science

Model 9

Plate Equations of Linear Elasticity

Module name: Smitc

Module subroutines: SmitcSolver
Module authors: Mikko Lyly, Jani Paavilainen
Document authors: Mikko Lyly, Peter Råback

9.1 Introduction
The linear elastic plate elements of Elmer are based on the shear deformable model of Reissner and Mindlin.The
finite element discretization is performed using the so called stabilized MITC-plate elements, which are free
from numerical locking.

9.1.1 Reissner-Mindlin model

The displacement ~u = (ux , uy , uz ) of a Reissner-Mindlin plate (thin or moderately thick linearly elastic
body which in its undeformed reference configuration occupies the three dimensional region Ω × (− 2t , 2t ),
where Ω is the midsurface and t the thickness) is obtained from the kinematic equations

ux (x, y, z) = −θx (x, y) · z (9.1)

uy (x, y, z) = −θy (x, y) · z (9.2)
uz (x, y, z) = w(x, y) (9.3)

where θx and θy are components of the rotation vector θ = (θx , θy ) and w is the transverse deflection of the
mid-surface, see Figure 1.
The functions w and θ = (θx , θy ) are determined from the condition that they minimize the total potential
energy Z Z Z
1
κ : m dΩ + γ · q dΩ − pw dΩ (9.4)
2 Ω Ω Ω

where p is the transverse pressure load, κ = 12 (∇θ + ∇θT ) is the curvature of the mid-surface, γ = ∇w − θ
is the transverse shear strain, m = E : κ is the bending moment, and q = G · γ the transverse shear force
vector. The fourth order tensor E and second order tensor G define the bending and shear rigidities of the
cross section, respectively. For linearly elastic materials we have G · γ = Gtγ and
ν
E : κ = K[κ + (trκ)I] (9.5)
1−ν
where K = Et3 /[12(1 − ν 2 )] is the bending stiffness, E is Young’s modulus, G shear modulus, and ν
Poisson ratio. The design of the tensors E and G for orthotropic and perforated materials is discussed in
section 9.3.

CSC – IT Center for Science

9. Plate Equations of Linear Elasticity 72

The minimizer of the energy satisfies the equilibrium equations

∇·m+q =0 (9.6)
−∇ · q = p (9.7)

9.1.2 Surface tension

When surface tension is present, the following term is added to the energy:
Z
1
∇w · T · ∇w dΩ (9.8)
2 Ω

where T is a second order tensor representing the given normal force (usually T = T I, where T is constant).
The equilibrium equation (9.7) is then rewritten as

−∇ · (q + T · ∇w) = p (9.9)

9.1.3 Boundary conditions

The following boundary conditions can be applied in the Reissner-Mindlin plate model:
• Soft fixed edge: w = 0 and θ · n = 0

• Hard fixed edge: w = 0 and θ = 0

• Soft simply supported edge: w = 0
• Hard simply supported edge: w = 0 and θ · t = 0

• Free edge: m · n = 0 and (q + T · ∇w) · n = 0

The boundary conditions can of course be non-homogeneous as well. For fixed and simply supported edges
the prescribed values of w, θ, θ · n, and θ · t, are taken into account on matrix level after finite element
discretization. On the free part of the edge, the non-homogeneous case is treated by adding the following
terms in the energy: Z Z
qn w dΓ + mn · θ dΓ (9.10)
Γf ree Γf ree

where qn = q · n and mn = m · n are prescribed functions.

9.1.4 Kirchhoff plates

When the thickness of the plate is small (t << diam(Ω)), the Reissner-Mindlin model can be considered
as a penalty approximation of the classical plate model of Kirchhoff. The Kirchhoff model is obtained from
(9.1)-(9.9) by enforcing the constraint γ = 0. The governing equations are then reduced to

K∆∆w − T ∆w = p (9.11)

9.1.5 Transient and natural mode analysis

A transient plate model is obtained by adding the inertia term ρtẅ on the left hand-side of (9.7), (9.9), and
(9.11). Here ρ is the density of the material. The natural vibration frequencies and mode shapes are then
obtained by taking p = 0 and solving the Fourier transformed equations.

CSC – IT Center for Science

9. Plate Equations of Linear Elasticity 73

9.2 Finite element implementation

The direct minimization of (9.4) using the standard Galerkin finite element method fails due to the well
known numerical locking phenomena (the method is unable to deal with the Kirchhoff constraint γ = 0,
which becomes valid when t is small). In order to avoid locking, Elmer utilizes the so called SMITC
(Stabilization and Mixed Interpolation of Tensorial Components) elements, which are known to be optimally
convergent and work well under all conditions [4].
The linear element of the SMITC-family was first introduced by Brezzi, Fortin and Stenberg in [2]. The
method is defined by replacing the shear energy term in (9.4) by the following numerical modification:
Z
γ h · q h dΩ (9.12)
Ω

where γ h is called the reduced shear strain (sometimes also referred to as the assumed or substitute shear)
and q h = (t2 + αh2 )−1 G · γ h the reduced shear force. Here h is the mesh size (the diameter of the biggest
element) and α > 0 is a numerical stabilization parameter (typically α = 0.15).
The reduced shear γ h is defined elementwise such that
γ h|K = (aK − bK y, aK + cK x) (9.13)

for any element K. The parameters aK , bK , and cK , are determined from the conditions
Z
(γ − γ h ) · t ds = 0 (9.14)
E

for every edge E of K. Here t is the counterclockwise tangent to E.

It has been shown [3] that the linear SMITC-element is equivalent to the T3BL (Triangle, 3 nodes,
Linked Interpolation) element of Xu, Auricchio and Taylor [8, 1], the anisoparametrically interpolated MIN3
element of Tessler and Hughes [7], and the TRIA3 element of MacNeal [5]. We refer to [3] for a more
detailed discussion.

9.3 Elastic parameters for perforated plates

In microelectromechanical systems the plate structures are often perforated in order to reduce the squeezed-
film damping effect. This has also an effect on the elasticity equation. If there are so many holes that it is
not feasible to treat them individually their effect may be homogenized over the whole structure. In practice
this means that the original elastic parameters are replaced by effective parameters that take into account the
holes. This method was reported by Pedersen et al. [6] and implemented into the solver by Jani Paavilainen.
In the homogenization effective parameters for an orthotropic plate are defined so that the unperforated
model approximates the perforated plate. The basic idea is to set the analytical expressions of the deforma-
tion energies of the perforated and unperforated plates equal. This method is inherently limited to simple
geometries where analytical expressions may be found. So far, only square holes have been implemented in
the solver.
The unit cell of a perforated plate may be assumed to consist of one small square plate with side b − 2a,
and of four beams of length a as shown in Figure 9.1. Using approximate formulas an analytical formula for
the deformation energy of the perforated plate is obtained. This has to be equal to the deformation energy
of an unperforated orthotropic membrane. From this condition we get a set of equations from which the
effective parameters may be solved.
The elasticity tensor has three independent components, C11 = C22 , C12 = C21 , and C44 . The expres-
sions for these are [6],
E b(b − 2a) a(b − 2a)2
 
C11 = C22 = 2 + (9.15)
b 1 − ν2 b
νE(b − 2a)
C12 = C21 = (9.16)
b(1 − ν 2 )
 
E 12Ka(b − 2a)
C44 = 2
2b(b − 2a) + . (9.17)
4b (1 + ν) bh3

CSC – IT Center for Science

9. Plate Equations of Linear Elasticity 74

basic
element

2a
b

Figure 9.1: The basic element of the perforated plate consisting of five rectangular beams

where K is a constant1 , defined as

( 1 b−2a

3
K=
3 1 − 0.63 h (b − 2a) h, jos h > b − 2a (9.18)
1 h
3 1 − 0.63 b−2a (b − 2a)h3 , jos h < b − 2a.

The midplane tension of the perforated plate may be reduced to lateral stresses of the orthotropic plate
by a simple scaling, p
T = (1 − 4a2 /b2 ) T0 , (9.19)
where is the tension T0 of the perforated plate. Using this reduced tension and the modified material param-
eters of equations (9.15), (9.16) and (9.17) the orthotropic plate mimics the behavior of the perforated plate
when looking at macroscopic quantities. However, the model is not suitable for approximating maximum
stresses around the holes, for example.

9.4 Keywords
Solver solver id

Equation String SmitcSolver

Procedure File "Smitc" "SmitcSolver"
The procedure which includes the linear plate model.
Variable String Deflection
This may be of any name as far as it is used consistently also elsewhere.
Variable DOFs Integer 3
Degrees of freedom for the deflection. The first degree is the displacement and the two following
ones are its derivatives in the direction of the coordinate axis.
Eigen Analysis Logical
Also the eigenvalues and eigenmodes of the elasticity equation may be computed. This is done
automatically by calling a eigensolver after the original equation has been solved. The default is
False.
1 In article [6] there is an error in the definition of K. In the article there is an expression (b − 2a)/h3 , which would make K

discontinuous at h = b − 2a.

CSC – IT Center for Science

BIBLIOGRAPHY 75

Eigen System Values Integer

If the eigenvalues are computed this keyword gives the number of eigenmodes to be computed.
The lowest eigenvalues are always solved for.
Hole Correction Logical
If the plate is perforated the holes may be taken into account by a homogenized model. This is
activated with this keyword. The default is False.
Material mat id
Density Real
Density of the plate.
Poisson Ratio Real
Youngs Modulus Real
The elastic parameters are given with the keywords Youngs Modulus and Poisson ratio.
Thickness Real
Thickness of the plate.
Tension Real
The plate may be pre-stressed.
Hole Size Real
Hole Fraction Real
If Hole Correction is True the solver tries to find the size and relative fraction of the
holes. If these are present the hole is assumed to be a square hole.
Boundary Condition bc id
Deflection i Real
Dirichlet BC for the components of the deflection, i=1,2,3.
Body Force bf id
Pressure Real
Possibility for a body forces. For coupled systems there is a possibility to have up to three forces.
The two others are then marked with Pressure B and Pressure C.
Spring Real
The local spring which results to a local force when multiplied by the displacement.
Damping Real
The local damping which results to a local force when multiplied by the displacement velocity.
The spring and damping may also be defined as material parameters.

Bibliography
[1] F. Auricchio and R.L. Taylor. A triangular thick plate finite element with an exact thin limit. Finite
Element in Analysis and Design, 19:57–68, 1995.
[2] M. Fortin F. Brezzi and R. Stenberg. Error analysis of mixed-interpolated elements for reissner-mindlin
plates. Mathematical Models and Methods in Applied Sciences, 1:125–151, 1991.
[3] M. Lyly. On the connection between some linear triangular reissner-mindlin plate bending elements.
Numerische Mathematik, 85:77–107, 2000.
[4] M. Lyly and R. Stenberg. Stabilized mitc plate bending elements. In Advances in Finite Element
Techniques (M. Papadrakakis and B.H.V. Topping, eds.) Civil Comp Press., pages 11–16, 1994.
[5] R.H. MacNeal. Derivation of element stiffness matrices by assumed strain distribution. Nucl. Engrg.
Design, 70:3–12, 1982.

CSC – IT Center for Science

BIBLIOGRAPHY 76

[6] M. Pedersen, W. Olthuis, and P. Bergveld. On the mechanical behaviour of thin perforated plates and
their application in silicon condenser microphones. Sensors and Actuators, A 54:6.
[7] A. Tessler and T.J.R. Hughes. A three-node mindlin plate element with improved transverse shear.
Comp. Meths. Appl. Mech. Engrg., 50:71–101, 1985.

[8] Z. Xu. A thick-thin triangular plate element. Int. J. Num. Meths. Eng., 33:963–973, 1992.

CSC – IT Center for Science

Model 10

One-dimensional Equations for Elastic

Beams

Module name: BeamSolver3D

Module subroutines: TimoshenkoSolver
Module authors: Mika Malinen
Document authors: Mika Malinen

10.1 Introduction
The solver described in this section can be used to solve structural beam equations. The equilibrium equa-
tions are expressed in terms of stress resultants N and M that represent forces and moments experienced
by the cross section of a beam. If the cross section is considered to be an oriented surface with positive unit
normal e1 , the stress resultant N is defined by
Z
N = σe1 dA (10.1)
A

where σ is the stress tensor and A denotes the cross section of the beam. Generally N is resolved into
components with respect to an orthonormal basis {e1 , e2 , e3 } associated with a local frame which has its
origin at the intersection of the cross section and the axis of the beam. The coordinates of points with respect
to this frame are denoted by (y1 , y2 , y3 ) with the y1 -axis being aligned with the axis of the beam, while the
other two axes are assumed to coincide with the principal directions of the cross section. The stress resultant
M = M1 e1 + M2 e2 + M3 e3 has as its components the bending moments
Z Z
M2 = y3 (σe1 ) · e1 dA, M3 = − y2 (σe1 ) · e1 dA, (10.2)
A A

while M1 is a torsional moment. We note that in general accurate modelling of the torsion is not a simple
problem and here a rudimentary approximation will only be employed.

10.2 Governing equations

Let us assume that the axis of the beam is described by using the arc length parametrization s ∈ [0, L] 7→
r(s) ∈ E3 . The equilibrium equations are then given by

−N 0 (s) = F (s),
(10.3)
−M 0 (s) − t(s) × N (s) = G(s),

CSC – IT Center for Science

10. One-dimensional Equations for Elastic Beams 78

where F and G are the densities of applied forces and moments per unit length and t(s) ≡ e1 (s) is tangential
to the beam axis. It should be noted that F and G can be considered to include inertial body forces to obtain
equations for transient cases.
In the case of Timoshenko’s treatment of shear deformation, suitable generalized measures of strain may
be expressed as

ε(s) = u0 (s) − θ(s) × t(s),

(10.4)
κ(s) = θ 0 (s)

where u : [0, L] → R3 is the displacement of the beam axis and the components of θ : [0, L] → R3 are the
so-called rotations. It is noted that the underlying approximation of the displacement u3D for a generic point
r(s) + y2 e2 (s) + y3 e3 (s) of the cross sections is given componentwise by

u3D (s; y2 , y3 ) · e1 (s) = u1 (s) − y2 θ3 (s) + y3 θ2 (s),

u3D (s; y2 , y3 ) · e2 (s) = u2 (s) − y3 θ1 (s), (10.5)
u3D (s; y2 , y3 ) · e3 (s) = u3 (s) + y2 θ1 (s).

The constitutive relations are written as

N = Dε,
(10.6)
M = Eκ,

where
D = diag(EA, GAk2 , GAk3 ) (10.7)
and
E = diag(GJT , EI2 , EI3 ). (10.8)
Here E and G are Young’s modulus and the shear modulus, respectively, while JT and Ik give a torsional
constant and the second moments of area, respectively. The parameters kj are known as the shear correction
factors.

10.3 The weak formulation

A weak formulation of the beam problem stems from the identities

ZL ZL
0
− N · v ds = F · v ds,
0 0
(10.9)
ZL ZL ZL
− M 0 · ψ ds − t × N · ψ ds = G · ψ ds
0 0 0

that yield after integration by parts

ZL ZL
0
N · v ds = F · v ds + N (L) · v(L) − N (0) · v(0),
0 0
(10.10)
ZL ZL ZL
M · ψ 0 ds − t × N · ψ ds = G · ψ ds + M (L) · ψ(L) − M (0) · ψ(0).
0 0 0

In order to specify forces exerted upon the beam by the environment, we shall set

N 0 = −N (0) and N L = N (L). (10.11)

CSC – IT Center for Science

10. One-dimensional Equations for Elastic Beams 79

Similarly the bending moments applied to the beam are specified as

M 0 = −M (0) and M L = M (L). (10.12)

By using (10.4) and (10.6) and by including transient inertia terms, the equations (10.10) lead to the
standard abstraction of the problem: Find w ≡ (u(·, t), θ(·, t)) ∈ U such that

a(w, z) = l(z), ∀z ≡ (v, ψ) ∈ V (10.13)

with
ZL ZL ZL ZL
0 0
a(w, z) = mü · v ds + I m θ̈ · ψ ds + Eθ · ψ ds + D(u0 − θ × t) · (v 0 − ψ × t) ds (10.14)
0 0 0 0

and
ZL ZL
l(z) = F · v ds + G · ψ ds + N L · v(L) + N 0 · v(0) + M L · ψ(L) + M 0 · ψ(0). (10.15)
0 0

Here m is the mass per unit length and the diagonal I m gives the (mass) moments of inertia. In addition, U
and V denote the sets of kinematically admissible functions and test functions, respectively.

10.4 Keywords
Simulation
Coordinate System String Cartesian 3D
The coordinate system should be selected to be three-dimensional, as no specific orientation of
the beam axis is supposed.
Material mat id
The following keywords relate to specifying the material parameters and the cross section data.
Youngs Modulus Real
This keyword specifies the value of Young’s modulus E.
Shear Modulus Real
This keyword specifies the value of G.
Density Real
This keyword is used for defining the density of the material. The density is needed in transient
cases to include the effects of inertial forces.
Cross Section Area Real
This keyword specifies the area A of the cross section.
Principal Direction 2(3) Real
The three components given by using this keyword should define the direction of the local y2 -
axis, so that the vector e2 can be computed. This direction must be orthogonal to the beam axis
that is determined by the coordinates of the element nodes. If this keyword is not specified, the
default value e2 = (0, 0, −1) is used.
Torsional Constant Real
To get an approximation of the torsional effects, the value of the parameter JT can be given.
Second Moment of Area 2 Real
This keyword should give the value of the integral I2 ≡ A y32 dA.
R

Second Moment of Area 3 Real

This keyword should give the value of the integral I3 ≡ A y22 dA.
R

CSC – IT Center for Science

10. One-dimensional Equations for Elastic Beams 80

Solver solver id
Equation String
A describing name for the solver.
Procedure File "BeamSolver3D" "TimoshenkoSolver"
The name of the solver subroutine.
Variable String Deflection[U:3 Theta:3]
The name of the solver variable can be chosen freely (but it is must be used consistently else-
where).
Variable DOFs Integer 6
There is no need for using this keyword as the only possible value is 6 and it is given automat-
ically by the solver. The first three components of the solver variable define the displacement
u of the beam axis (the default variable name U), while the rest give the vector θ (the default
variable name Theta). In this connection the components of both the vectors are defined with
respect to the global coordinate frame.
Body Force bf id

Body Force k Real

The value of this keyword gives the kth component of the applied force F with respect to the
global coordinate frame.
Boundary Condition bc id
The Dirichlet conditions for the components of u and θ can be given in the standard manner. Note
that here the components of both vectors are defined with respect to the global coordinate frame.
U i Real
If the default variable name is used, then, with i=1,2,3, Dirichlet BCs for the components of
the displacement u can be given.
Theta i Real
If the default variable name is used, then, with i=1,2,3, Dirichlet BCs for the components of
the rotation θ can be given.

CSC – IT Center for Science

Model 11

Adding pointwise springs and masses

Module name: SpringAssembly

Module subroutines: SpringAssembler
Module authors: Mika Malinen
Document authors: Mika Malinen

11.1 Introduction
The utility described in this section can be used to add nodewise specified springs and masses to structural
models. This utility is generic and should be applicable to several structural models including equations
of linear and nonlinear elasticity, shells, plates and beams. It should be noted that some models may be
defined to have pointwise springs or masses without using this utility, provided the set of boundary elements
includes point elements and the model itself can handle springs or masses. The utility considered here does
not however depend on the content of the mesh file defining boundary elements, since the places of the
springs and masses are now supposed to be specified in terms of the indices of the mesh nodes.

11.2 Guiding assembly procedure

The module subroutine considered can be called as an additional assembly procedure to change the stiffness
and mass matrices of the target model which is modified to have the springs or masses. To achieve this, in the
solver input file the solver section associated with the primary model must contain the keyword command
Assembly Solvers (for the documentation of this generic utility command see also ElmerSolver Man-
ual). The value of this keyword gives the integer identifier of the solver section which is utilized to perform
the additional assembly procedure.
To describe what is needed, let us suppose that the primary solver which should utilize the spring defini-
tions is associated with the variable name "Displacement". If one then adds Xth solver section into the
solver input file as
Solver X
Equation = "Assemble Springs"
Exec Solver = Never
Procedure = "SpringAssembly" "SpringAssembler"
Displacement Variable Name = "Displacement"
End
and adds into the solver section of the primary solver a line
Assembly Solvers(1) = X
then it should be possible to use boundary condition sections to add spring specifications as

CSC – IT Center for Science

11. Adding pointwise springs and masses 82

Boundary Condition Y
Target Nodes(...) = ...
Spring 1 = ...
Spring 2 = ...
Spring 3 = ...
...
End
An additional mass (and moment of inertia when applicable) may be added in a similar way by using a
keyword Mass i, with i being an integer string.

11.3 Keywords
Solver id
Displacement Variable Name String
The value of this keyword must be the variable name of the solver which is modified to have
additional springs or masses. The default value is "Displacement".
Boundary Condition bc id

Spring i Real
This keyword may be used to create a reaction which is proportional to the value of the ith
global DOF (degree of freedom) of the finite element used to discretize the primary model.
Mass i Real
With this keyword, the mass matrix of the model can be modified by assembling an additional
diagonal mass matrix. The integer string i of the keyword refers to ith global DOF (degree of
freedom) of the element. In the basic 3D simulation the values for all i∈ {1, 2, 3} should be
the same by physical reasons as they originate from the same scalar property. With i > 3 an
additional moment of inertia may be given for models for which it is meaningful (for example a
shell model).

CSC – IT Center for Science

 Part III

Models of Acoustics

CSC – IT Center for Science

Model 12

The Helmholtz Model

Module name: HelmholtzSolve

Module subroutines: HelmholtzSolver
Module authors: Juha Ruokolainen, Mikko Lyly, Mika Malinen, Peter Råback
Document authors: Juha Ruokolainen, Peter Råback

12.1 Introduction
This module solves the Helmholtz equation, which is the Fourier transform of the wave equation. In addition
to the basic equation the solver may take into consideration variable density, background convections field,
simple damping and special boundary conditions with other time-harmonic solvers.

12.2 Theory
For example, sound propagation in air is fairly well described by the wave equation:

1 ∂2p
− ∇2 p = 0. (12.1)
c2 ∂t2
When linear the equation may be written in frequency space as

k 2 P + ∇2 P = 0, (12.2)

where k = ω/c. This is the Helmholtz equation. The instantaneous pressure may be computed from the
given field P :
p(t) = <(P eiωt ) = <(P ) cos(ωt) − =(P ) sin(ωt), (12.3)
√
where i = −1 is the imaginary unity.
In Elmer the equation has an added term which is proportional to first time derivative of the field, where-
upon the equation becomes
(k 2 − ikD)P + ∇2 P = 0, (12.4)
where D is the damping factor.

12.2.1 Boundary Conditions

The usual boundary condition for the Helmholtz equation is to give the flux on the boundary:

∇P · ~n = g, (12.5)

CSC – IT Center for Science

12. The Helmholtz Model 85

also Dirichlet boundary conditions may be set. The Sommerfeldt or far field boundary condition is as follows
iω
∇P · ~n + P = 0, (12.6)
Z
where the complex-valued quantity Z may be defined by the user. It is noted that incoming and outgoing
waves may be approximated by setting Z = ±c, respectively.
A special kind of flux condition is one with a given harmonic velocity field that is obtained from a
harmonic solution of a flow or structure equation. When the velocity field ~v is given then the flux is obtained
from
g = iωρ~v · ~n (12.7)
where ρ is the fluid density. If harmonic displacement is given instead a further term iω appears in the
equation.

12.3 Keywords
Simulation
This section gives values to parameters concerning the simulation as whole.
Frequency Real
Give simulation frequency in units of 1/s. Alternatively use the Angular Frequency key-
word.
Angular Frequency Real
Give simulation frequency in units of 1/rad. Alternatively use the Frequency keyword.
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere. Note also that for the Helmholtz equation ILUT
preconditioning works well.

Equation String [Helmholtz]

The name of the equation.
Procedure File ["HelmholtzSolve" "HelmholtzSolver"]
This keyword is used to give the Elmer solver the place where to search for the Helmholtz
equation solver.
Variable String [Pressure]
Give a name to the field variable.
Variable DOFs Integer [2]
This keyword must be present, and must be set to the value 2.
Bubbles Logical
If set to True this keyword activates the bubble stabilization.
Use Density Logical
Historically the solver was able to solve only cases with constant density when it may be elimi-
nated. If the density is however not constant this flag must be set True.
Velocity Variable Name String
If there is a Flow Interface then the name of the harmonic velocity variable may be speci-
fied. The default is Flow. Note that normal real valued velocity field is not suitable.
Displacement Variable Name String
If there is a Structure Interface then the name of the harmonic displacement variable
may be specified. The default is Displacement. Note that normal real valued displacement
field is not suitable, its complex valued eigenmode however is.
Displacement Variable Eigenmode Integer
If eigenmode is used for the interface this keyword is used to specify the number of the mode.

CSC – IT Center for Science

12. The Helmholtz Model 86

Displacement Variable Frequency Logical

If eigenmode is used for the interface this keyword may be used to choose the frequency to be
the frequency of the computed eigenmode.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
Helmholtz Logical
If set to True, solve the Helmholtz equation, the name of the variable must match the Equation
setting in the Solver section. Alternatively use the Active Solvers keyword.
Initial Condition ic id
The initial condition section may be used to set initial values for the field variables. The following
variables are active:

Pressure i Real
For each the real and imaginary parts of the solved field i= 1, 2.
Material mat id
The material section is used to give the material parameter values. The following material parameters
may be set in Helmholtz equation.

Sound Speed Real

This keyword is used to give the value of the speed of sound.
Sound Damping Real
This keyword is used to give the value of the damping factor D in equation 12.4.
Density Real
If sound density is varying the density must be specified and its use must be enforced by the Use
Density keyword.
Convection Velocity i Real
If the pressure field is convected by a background velocity field (as in the Doppler effect) then
this keyword is used to give the velocity field.

Body Force bf id
Pressure Source i Real
The pressure sources of the real (i = 1) and complex (i = 2) parts. The use of this is rather
seldom.

Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. The one related to
Helmholtz equations are
Pressure i Real
Dirichlet boundary condition for real and imaginary parts of the variable. Here the values i= 1, 2
correspond to the real and imaginary parts of the unknown field.
Wave Flux 1,2 Real
Real and imaginary parts of the boundary flux. Here the values i= 1, 2 correspond to the real
and imaginary parts of the boundary flux.
Wave Impedance 1,2 Real
This keyword may be used to define the real and imaginary parts of the quantity Z in (12.6).
Here the values i= 1, 2 correspond to the real and imaginary parts of Z.
Plane Wave BC Logical
Automatically sets the boundary conditions assuming outgoing plane waves if set True.

CSC – IT Center for Science

12. The Helmholtz Model 87

Flow Interface Logical

Use harmonic velocity field to set the flux.
Structure Interface Logical
Use harmonic displacement field to set the flux.

CSC – IT Center for Science

Model 13

The Linearized Navier–Stokes

Equations in the Frequency Domain

Module name: Acoustics

Module subroutines: AcousticsSolver
Module authors: Mika Malinen
Document authors: Mika Malinen

13.1 Introduction
The basic acoustic equations such as the Helmholtz equation, which is frequently taken as the starting point
in acoustic analyses, are based on the assumption of lossless flow, i.e. the effects of viscosity and heat
conduction are neglected. These effects are significant, however, in thin zones near a solid boundary. In this
chapter, a system of acoustic field equations taking into account the effects of viscosity and heat conduction
is described. Consideration is confined to the time-harmonic solution of these equations.

13.2 Mathematical model

The acoustic field equations may be derived using the general principles of continuum mechanics and supple-
menting these equations by suitable constitutive equations applicable for the fluid flow. Here the linearized
versions of such equations are used to derive an approximate system of field equations appropriate to the
small-amplitude acoustics problem.
In the following the velocity, density, pressure and temperature fields associated with the flow are denoted
by ~v , ρ, p and T , respectively. The notations ρ0 , p0 and T0 are used for the values of the density, pressure
and temperature at the equilibrium state.

13.2.1 The field equations

Consider the acoustic equations based on the linearized equation of motion, the constitutive equation relating
the stress to the motion for a Newtonian fluid, the kinematic relation, the linearized continuity equation and

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 89

the linearized energy equation

∂~v
ρ0 = ∇ · σ + ρ0~b,
∂t
σ = −pI + λ(∇ · ~v )I + 2µD(~v ),
1
D(~v ) = (∇~v + ∇~v T ), (13.1)
2
∂ρ
= −ρ0 ∇ · ~v ,
∂t
du
ρ0 = κ∆T − p0 ∇ · ~v + ρ0 h.
dt
Here σ is the stress tensor, ~b is the body force (per unit mass), λ and µ are parameters characterizing the
viscosity of the fluid, u is the specific internal energy, κ is the heat conductivity and h is the internal supply
of heat.
We supplement the system (13.1) by suitable equations of state assuming that the properties of the
medium are expressible as functions of two state variables, say the temperature and density. We denote
the specific entropy (entropy per unit mass) and its equilibrium value by s and s0 and assume that the rela-
tion
du = T0 ds + (p0 /ρ20 )dρ (13.2)
is valid. In addition, we approximate the equations which give the changes of pressure and specific entropy
in terms of the changes of the state variables by
(γ − 1)ρ0 CV (γ − 1)CV
p − p0 = (T − T0 ) + (ρ − ρ0 ) (13.3)
T0 β T0 β 2
and
CV CV (γ − 1)
s − s0 = (T − T0 ) − (ρ − ρ0 ), (13.4)
T0 T0 ρ0 β
where CV is the specific heat at constant volume (per unit mass), γ is the ratio of the specific heats at constant
pressure and constant volume and β is the coefficient of thermal expansion defined by
1  ∂ρ 
β=− . (13.5)
ρ ∂T p
Confining consideration to the time-harmonic case, the solutions of the primary unknowns are assumed
to be of the form
~v (x, t) = ~v (x) exp(iωt),
ρ(x, t) = ρ0 + ρ(x) exp(iωt), (13.6)
T (x, t) = T0 + T (x) exp(iωt),
where ω is the angular frequency. By the substitution of (13.6), the system of field equations based on
(13.1)–(13.4) may be reduced to a system where the only unknown fields are the amplitudes ~v (x) and T (x)
of the disturbances of the velocity and temperature fields. The reduced system may be written as
(γ − 1)CV ρ0 i(γ − 1)CV ρ0
iωρ0~v + ∇T − (λ + µ − )∇(∇ · ~v ) − µ∆~v = ρ0~b,
βT0 ωT0 β 2
(13.7)
(γ − 1)CV ρ0
−κ∆T + iωρ0 CV T + ∇ · ~v = ρ0 h.
β
It is noted that after the solution of the velocity and temperature the amplitudes p(x) and ρ(x) of the distur-
bances of the pressure and density fields can readily be obtained from the relations
(γ − 1)CV ρ0 i
p= (T + ∇ · ~v ),
βT0 ωβ
(13.8)
iρ0
ρ= ∇ · ~v .
ω

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 90

For numerical approximation the system (13.7) is rewritten as a mixed problem; to motivate this, see [2].
The mixed formulation is written as
~v − i∇τ − i∇φ + i∇(∇ · ~v ) + i∆~v = −(i/ω)~b,
i 1 1 ih
− ∆τ − τ+ φ= ,
(γ − 1)δ γ−1 1 + iγk 2 η βT0 ω 2 (13.9)
γk 2
i∇ · ~v − φ = 0,
1 + iγk 2 η
where φ is an auxiliary unknown, τ is the scaled temperature defined by
ωβ
τ= T (13.10)
γk 2
and
ω µ CV µ λ
k= = δ= η= (13.11)
c ρ0 ω κ µ
with c the adiabatic sound speed defined by the relation

T0 β 2 c2 = γ(γ − 1)CV . (13.12)

It should be noted that although the solver of the acoustic equations is based on the formulation (13.9), the
solver overwrites the approximations of τ and φ by the unscaled temperature and the pressure, which may
be expressed as
1
p = ρ0 ω(τ + φ). (13.13)
1 + iγk 2 η
It is assumed that β = 1/T0 . This value is obtained by evaluating the coefficient of thermal expansion
for the equilibrium values of the state variables in the case of an ideal gas.

13.2.2 Boundary conditions

Suitable boundary conditions must be adjoined to the field equations (13.1). In a usual manner, one may
specify any component of the velocity vector on the boundary. Alternatively, if the component of the velocity
vector is not specified at a point on the boundary, the corresponding component of the surface force vector
may be prescribed. Similarly, as a boundary condition for the energy equation one may specify either the
disturbance of the temperature or zero heat flux (the default boundary condition) on the boundary.
Specifying two impedances on the boundary provides an alternative way of prescribing boundary con-
ditions in the normal direction to the boundary. Firstly, one may specify the specific acoustic impedance Z
which is defined to be the ratio of the normal component of the surface force vector (which equals to the
pressure in the case of a nonviscous Newtonian fluid with no bulk viscosity) to the normal component of the
velocity vector at a point on the boundary, i.e. one may specify
~n · σ~n
Z= ,
~v · ~n
where ~n is the outward unit normal vector to the boundary. Secondly, one may prescribe the ratio of the heat
flux to the disturbance of the temperature at a point on the boundary by specifying
∇T (x) · ~n
ZT = .
T (x)
For example, outgoing waves may be approximated by setting Z = −ρ0 c and ZT = −iω/c on the outflow
boundary.
Slip boundary conditions may also be used. The velocity slip boundary condition relating the tangential
component of the surface force vector to the tangential velocity jump at a point on the boundary is written in
the form
cσ 2(γ − 1)CV (T0 + Tw ) 1/2
σ~n · ~t = − ( ) ρ0 (~v · ~t − ~vw · ~t),
2 − cσ π

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 91

where ~t is a tangent vector to the boundary, cσ is the momentum accommodation coefficient and Tw and
~vw are the reference wall temperature and velocity. Here the reference wall temperature is defined to be the
deviation of the wall temperature from the equilibrium temperature T0 . The similar boundary condition for
the heat flux is given by

cT (γ + 1) 2(γ − 1)CV (T0 + Tw ) 1/2

κ∇T · ~n = − ( ) ρ0 CV (T − Tw ),
2(2 − cT ) π

where cT is the energy accommodation coefficient.

13.3 The use of block preconditioning

The finite element approximation of the system (13.9) leads usually to large linear systems which have to
be solved using preconditioned iterative methods. The general preconditioners available in Elmer may not
always work satisfactorily well when the size of the system becomes larger and larger. To facilitate the
solution of large problems, a problem-specific strategy for solving the linear systems that arise from the
discretization of (13.9) has been developed. We describe the essential features of this solution method in this
section; for a full description see [1].
The solution strategy discussed here is based on using nested GCR iterations in combination with a
special block-preconditioner. Given the linear system

KU = F

the standard GCR method generates a sequence of improving approximations such that each iterate U (k)
minimizes ||F − KU (k) || over the so-called Krylov subspace. The standard algorithm can be modified
easily so that the update direction can be chosen flexibly. Obviously, an optimal update direction would be
given by the current error e(k) = U − U (k) . To find an approximation to the error one may apply an iterative
method to
Ke(k) = r(k) ,
where r(k) = F − KU (k) is the residual. The preconditioned GCR algorithm which employs this idea to
find the update direction can be described as follows:
Form an initial guess U (0)
r(0) = F − KU (0)
k=0
while (Stopping criterion is not met)
Solve Ks(k+1) = r(k) iteratively using at most m iteration steps
v (k+1) = Ks(k+1)
do j = 1, k
v (k+1) = v (k+1) − < v (j) , v (k+1) > v (j)
s(k+1) = s(k+1) − < v (j) , v (k+1) > s(j)
end do
v (k+1) = v (k+1) /kv (k+1) k
s(k+1) = s(k+1) /kv (k+1) k
U (k+1) = U (k) + < v (k+1) , r(k) > s(k+1)
r(k+1) = r(k) − < v (k+1) , r(k) > v (k+1)
k =k+1
end while

Here the inner product and norm are defined by < v, r >= v · r and kvk =< v, v >1/2 . The GCR iteration
steps used to update the approximation of U are referred to as outer iterations, while the iteration steps of
the preconditioning iterative method used for solving the new search direction s(k+1) are referred to as inner
iterations.

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 92

Here the GCR algorithm is also used as the inner iterative method. In connection with the inner iterations
a special block-preconditioner is used. The preconditioning is done by solving approximately the block-
triangular system of the form
A B∗ B∗ 0
    
sv rv
 0 C D 0    sτ  =  rτ  ,
   

 0 E (13.14)
G H   sφ   rφ 
0 0 0 M ψ rφ
where sv , sτ and sφ are update directions for the errors of v, τ and φ. In addition, ψ is an auxiliary unknown
which has been introduced so as to handle the boundary conditions of the preconditioner is a consistent way.
In practice, an approximate solution of (13.14) is constructed by applying iterative methods to the systems
of the type
M ψ = rφ , (13.15)
    
C D sτ rτ
= (13.16)
E G sφ r̂φ
and
Asv = r̂v , (13.17)
where r̂φ and r̂v are modified right-hand sides the computation of which requires the evaluation of certain
matrix-vector products. The special solver discussed hence requires that iterations are performed on three
levels.
One of the key ideas in the nested application of the GCR algorithm is that the outer iteration can be
made rapidly convergent. Consequently the optimality of the outer iteration need not be sacrificed by using
such techniques as restarting or truncation. A few inner iterations are usually enough to produce a useful
reduction in the outer iteration residual. Therefore the maximum number of iterations the inner iterative
method may take need not be large. We have found that limiting the number of inner iterations by taking
m = 5 (this is the default value) or m = 10 leads often to an efficient method. In addition to specifying
the maximum number of inner iterations, the user can control the residual reduction in the outer iteration
process by specifying the error tolerance δinner so that the inner GCR iteration is stopped if
kr(k) − K ŝ(k+1) k < δinner kr(k) k, (13.18)
(k+1) (k+1)
where ŝ is the approximation to s . The default value of δinner is 0.1.
Ideally a mild stopping criterion should be used in the solution of the linear systems of the type (13.15)–
(13.17) which arise in the block-preconditioning of the inner iteration. The iterative solution of (13.15) being
a cheap operation, the overall cost of the block-preconditioning is essentially determined by the solution of
the systems of the type (13.16) and (13.17). These systems are solved using the preconditioned BiCGStab(l)
method. In this connection the Jacobi and incomplete LU factorization preconditioners can be applied.

13.4 Utilities
The dissipative acoustics solver may be used in resolving the acoustic impedance of a system. The value of
the impedance defined by R
p dS
zi = R Si (13.19)
Si
~v · (−~n) dS
may automatically be calculated for a given boundary Si . Here this impedance will be referred to as the
specific acoustic impedance of the surface (Si ).
The acoustic impedance is divided into two parts, a part in phase with velocity and a part out of phase
with velocity. The value of the impedance zi is meaningful only when the velocity on the input boundary is
considered. It is though possible to calculate the response over an other boundary Sj and to compare it to
the input velocity, i.e. one may compute
R
Sj
p dS
zij = R . (13.20)
Si
~v · (−~n) dS
This impedance is here called the cross specific acoustic impedance.

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 93

13.5 Keywords
The following keywords are particularly related to the acoustics solver.

Simulation
Angular Frequency Real
This keyword is used to declare the angular frequency. Alternatively one may define the fre-
quency by using the Frequency keyword.
Frequency Real
This keyword is used to declare the frequency. Alternatively one may define the angular fre-
quency by using the Angular Frequency keyword.
Simulation Type String
The value of this keyword should be either Steady State or Scanning. The value Scanning
may be used to obtain results for several frequencies by using a single sif-file.
Coordinate System String
The coordinate system must be set to be one of the following options: Cartesian 2D, Cartesian
3D or Axi Symmetric.
Solver solver-id
The following keywords may be used in the solver section that contains solver parameters for the
acoustics solver.

Equation String
This keyword can be used to give a name for the discrete acoustic equations
Procedure File Acoustics AcousticsSolver
This keyword is used to give the Elmer solver the place where to search for the acoustics solver.
Variable String Flow
The name Flow is used for the solution of the acoustics equations consisting of the amplitudes
of the disturbances of the velocity, temperature and pressure from the equilibrium state (note that
the disturbance of the density is not computed explicitly). The acoustics solver uses a convention
that if dim is the coordinate system dimension then the components 1, ..., 2 × dim of Flow give
the real and imaginary parts of velocities (Flow.1 and Flow.2 are the real and imaginary
parts of the first velocity component, etc.). The temperature and pressure solutions come after
the velocity solution.
Variable Dofs Integer
The value of this keyword should equal to 2 × (dim + 2) where dim is the coordinate system
dimension.
Element String
The use of standard finite elements in the approximation of the acoustic equations is likely to
lead to an unstable method. The finite element formulation can be stabilised by using additional
bubble finite element functions in the approximation of velocities. If this keyword is given the
value p:1 b:n, with n an integer, then n additional bubble functions contained in the p-element
library are used in the approximation of each velocity component.
Bubbles in Global System Logical
This keyword should be given the value False, so that the additional bubble basis functions
needed for the stability are eliminated via the static condensation.
Utilize Previous Solution Logical
If a single sif-file is used to compute the solutions for several frequencies, then the previous
solution can be used as an initial guess for the next iterative solution. This can be done by giving
the value True for this keyword.

Material material-id

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 94

Specific Heat Real

This keyword is used to define the specific heat (per unit mass) at constant volume.
Specific Heat Ratio Real
This keyword is used to define the ratio of the specific heats at constant pressure and constant
volume.
Equilibrium Density Real
This keyword is used to declare the density at the equilibrium state.
Equilibrium Temperature Real
This keyword is used to declare the absolute temperature at the equilibrium state.
Heat Conductivity Real
This keyword is used to define the value of the heat conductivity.
Viscosity Real
This keyword is used to define the value of the viscosity µ.
Bulk Viscosity Real
The material parameter λ is determined by giving the bulk viscosity κ0 defined by κ0 = λ+2/3µ.
If the value of this keyword is not given, the Stokes condition is assumed, i.e. the value of λ is
determined by the condition κ0 = 0.
Re Heat Source Real
This keyword is used to define the real part of the heat source (per unit mass).
Im Heat Source Real
This keyword is used to define the imaginary part of the heat source (per unit mass).
Re Body Force i Real
This keyword is used to define the real part of the i’s component of the body force vector (per
unit mass).
Im Body Force i Real
This keyword is used to define the imaginary part of the i’s component of the body force vector
(per unit mass).
Boundary Condition bc-id
Re Velocity i Real
This keyword is used to prescribe the real part of the i’s component of the velocity vector.
Im Velocity i Real
This keyword is used to prescribe the imaginary part of the i’s component of the velocity vector.
Re Temperature Real
This keyword is used to prescribe the real part of the amplitude of the disturbance of temperature.
Im Temperature Real
This keyword is used to prescribe the imaginary part of the amplitude of the disturbance of
temperature.
Re Surface Traction i Real
This keyword is used to define the real part of the i’s component of the surface force vector.
Im Surface Traction i Real
This keyword is used to define the imaginary part of the i’s component of the surface force vector.
Re Specific Acoustic Impedance Real
This keyword is used to define the real part of the ratio of the normal component of the surface
force vector to the normal component of the velocity vector at a point on the boundary.
Im Specific Acoustic Impedance Real
This keyword is used to define the imaginary part of the ratio of the normal component of the
surface force vector to the normal component of the velocity vector at a point on the boundary.

CSC – IT Center for Science

13. The Linearized Navier–Stokes Equations in the Frequency Domain 95

Re Specific Thermal Impedance Real

This keyword is used to define the real part of the ratio of the normal derivative of temperature
to the disturbance of the temperature at a point on the boundary.
Im Specific Thermal Impedance Real
This keyword is used to define the imaginary part of the ratio of the normal derivative of temper-
ature to the disturbance of the temperature at a point on the boundary.
Slip Boundary Logical
The value of this keyword should be set to be True if slip boundary conditions were given.
Momentum Accommodation Coefficient Real
This keyword is used to define the momentum accommodation coefficient cσ .
Energy Accommodation Coefficient Real
This keyword is used to define the energy accommodation coefficient cT .
Re Reference Wall Velocity i Real
This keyword is used to prescribe the real part of the i’s component of the reference wall velocity.
Im Reference Wall Velocity i Real
This keyword is used to prescribe the imaginary part of the i’s component of the reference wall
velocity.
Reference Wall Temperature Real
This keyword is used to define the reference wall temperature.
Calculate Acoustic Impedance Logical
This keyword is used to define the boundary for which the specific acoustic impedance zi is
calculated.
Impedance Target Boundary Logical
When calculating the cross impedance zij , this keyword defines the boundary Sj . The input
velocity boundary (Si ) is defined using the Calculate Acoustic Impedance keyword.

The following keywords are related to the use of block preconditioning and may be given in the Solver
section.

Solver solver-id
Block Preconditioning Logical
The value of this keyword should be set to be True to enable the use of block preconditioning.
Max Outer Iterations Integer
The value of this keyword defines the maximum number of outer iterations.
Max Inner GCR Iterations Integer
This keyword is used to define the value of the parameter m, i.e. the maximum number of inner
iterations. The default value is 5.
Ratio of Convergence Tolerances Real
This keyword is used to define the stopping criterion for the outer iteration. The outer iteration
is stopped when

kF − KU (k) k∞ < (εr × ε)(kKk∞ kU (k) k∞ + kF k∞ ).

Here εr is defined using this keyword and ε is the value of the Linear System Convergence
Tolerance keyword. Having εr  1 is desirable.
Residual Reduction Ratio Real
This keyword is used to define the value of the parameter δinner in the stopping criterion (13.18).
The default value is 0.1.

CSC – IT Center for Science

BIBLIOGRAPHY 96

Linear System Convergence Tolerance Real

In connection with the block-preconditioning the keyword Linear System Convergence
Tolerance defines the stopping criterion used in connection with the iterative solution of
(13.16) and (13.17). In this connection the stopping criterion of the type

kr̂v(k) − As(k) (k)

v k < εkr̂v k

is used. Here ε is the value of this keyword. It is noted that the solution accuracy of (13.15) need
not be specified by the user.
Velocity Convergence Tolerance Real
The systems (13.16) and (13.17) may solved with different degrees of accuracy. Instead of using
the Linear System Convergence Tolerance keyword one may specify the solution
accuracy for (13.17) by using this keyword.
Schur Complement Convergence Tolerance Real
The systems (13.16) and (13.17) may solved with different degrees of accuracy. Instead of using
the Linear System Convergence Tolerance keyword one may specify the solution
accuracy for (13.16) by using this keyword.
Linear System Max Iterations Integer
In connection with the block-preconditioning the Linear System Max Iterations key-
word is used for defining the maximum number of iteration steps which can be taken in the
iterative solution of (13.15)–(13.17).
Velocity Assembly Logical
The coefficient matrix A in (13.17) corresponds to the (1,1) block of the coefficient matrix K.
As the elements of A can be extracted from K, the assembly of A can be avoided if a diagonal
preconditioning is used in the iterative solution of (13.17). If an incomplete factorization pre-
conditioner is used, the matrix A is assembled explicitly. In this case the value True must be
given for this keyword.
ILU Order for Schur Complement Integer
The value of this keyword defines the fill level for the incomplete LU factorization preconditioner
that is applied in the iterative solution of the linear systems of the type (13.16).
ILU Order for Velocities Integer
The value of this keyword defines the fill level for the incomplete LU factorization preconditioner
that is applied in the iterative solution of the linear systems of the type (13.17). If this keyword
is not given, then a diagonal preconditioning is used. This keyword has an effect only when the
Velocity Assembly keyword is given the value True.

Bibliography
[1] M. Malinen. Boundary conditions in the schur complement preconditioning of dissipative acoustic
equations. SIAM J. Sci. Comput., 29:1567–1592, 2007.

[2] M. Malinen, M. Lyly, P. Råback, A. Kärkkäinen, and L. Kärkkäinen. A finite element method for the
modeling of thermo-viscous effects in acoustics. In P. Neittaanmäki et. al., editor, Proceedings of the
4th European Congress on Computational Methods in Applied Sciences and Engineering, 2004.

CSC – IT Center for Science

Model 14

Wave Equation

Module name: WaveSolver

Module subroutines: WaveSolver
Module authors: Juha Ruokolainen, Peter Råback, Mika Malinen
Document authors: Mika Malinen

14.1 Introduction
This module can be used to solve a generalized version of the wave equation in time domain. It provides an
alternative to the Helmholtz equation which follows from the wave equation by transforming to the frequency
domain.

14.2 Theory
This solver can be used to handle the following generalized version of the wave equation:

1 ∂2p η ∂p α ∂p
− + ∆p + 2 ∆( ) − 2 = f, (14.1)
c2 ∂t2 c ∂t c ∂t
with c and f being the sound speed and a source function, respectively. In addition, η and α are model
parameters, which can also be set to be zero to obtain the standard wave equation.
In the case of sound waves the equation (14.1) can be obtained from the equation of motion and the
continuity equation by linearization. By assuming an isentropic fluid and irrotational flow, we then come to
considering the velocity-pressure system

∂v
ρ0 − η̂∇(∇ · v) + α̂v − ∇P = ρ0 b,
∂t
(14.2)
1 ∂P
+ ∇ · v = 0,
ρ0 c2 ∂t
where ρ0 is the density of the fluid at the equilibrium state, η̂ is a parameter related to the fluid viscosity
and α̂ is a reaction parameter. If we use the continuity equation to eliminate the divergence term from the
equation of motion and set η = η̂/ρ0 , α = α̂/ρ0 and p = P/ρ0 , the velocity-pressure system can also be
expressed as

∂v η ∂p
+ 2 ∇( ) + αv − ∇p = b,
∂t c ∂t (14.3)
1 ∂p
+ ∇ · v = 0.
c2 ∂t

CSC – IT Center for Science

14. Wave Equation 98

The elimination of the velocity from the time-differentiated continuity equation

1 ∂2p ∂v
− −∇·( )=0 (14.4)
c2 ∂t2 ∂t
then yields (14.1), with f ≡ ∇ · b.
Boundary conditions. Basically boundary conditions of three types can be given. In addition to a basic
Dirichlet constraint, one can specify the Neumann constraint

η ∂p
− ∇p · n − ∇( ) · n = g. (14.5)
c2 ∂t
In the absence of body forces and reaction terms (b = 0 and α = 0), the value of g is related to the normal
component of the acceleration via
∂v
g=− · n.
∂t
The final option is to set
η ∂p 1 ∂p
− ∇p · n − 2 ∇( ) · n = (14.6)
c ∂t c ∂t
in order to approximate outgoing waves, especially when η is small.

14.3 Keywords
Solver solver id
The following keywords are especially related to the wave equation solver.
Equation String
This keyword can be used to give a name for the equation handled by the solver.
Procedure File "WaveSolver" "WaveSolver"
This specifies the name of the solver subroutine.
Variable String "Excess Pressure"
The name of the solver variable can be chosen freely.
Variable DOFs Integer
The value of this keyword must be 1.
Time Derivative Order Integer
There is no need for using this keyword as the only possible value is 2 and it is given automati-
cally by the solver.
Initial Condition ic-id
The initial condition section may be used to set initial values for the field variable. The form of the
commands depends on the name given for the solver variable.
Material mat id
The material section is used to give the values of the material parameters.
Sound Speed Real
This keyword is used to give the value of the sound speed c.
Sound Damping Real
This keyword is used to give the value of the parameter η.
Sound Reaction Damping Real
This keyword is used to give the value of the parameter α.

Body Force bf id
Although volumetric sources may be rare, there is an option to specify such a source.

CSC – IT Center for Science

14. Wave Equation 99

Sound Source Real

This keyword can be used to specify the source function f ≡ ∇ · b.
Boundary Condition bc id
Special keywords are used to specify Neumann and outflow constraints, while a Dirichlet constraint
can be given in a standard manner.

Excess Pressure Real

The form of the command to specify a Dirichlet constraint naturally depends on the name given
for the solver variable.
Source Acceleration Real
This keyword can be used to specify the source function g.
Outflow Boundary Logical
This keyword can be used to activate the use of the constraint (14.6). An alternate keyword for
the same purpose is Plane Wave BC.

CSC – IT Center for Science

Model 15

Large-amplitude Wave Motion in Air

Module names: CompressibleNS

Module subroutines: CompressibleNS
Module authors: Mika Malinen
Document authors: Mika Malinen

15.1 Introduction
This module contains a monolithic solver for the compressible Navier–Stokes equations subject to the ideal
gas law. It can be used to model the fully nonlinear wave propagation in the time domain.

15.2 Mathematical model

The acoustic wave motion in a fluid is generally characterized by the compressional Navier–Stokes equa-
tions. If the medium obeys the ideal gas law, so that the fluid pressure p satisfies

p = RρT, (15.1)

the Navier–Stokes system may be reduced to consist of the equation of motion

∂~v
ρ[ + (~v · ∇)~v ] − µ∆~v − (µ + λ)∇(∇ · ~v ) + Rρ∇T + RT ∇ρ = ~b, (15.2)
∂t
the energy equation
∂T
ρCV ( + ~v · ∇T ) − K∆T + RρT ∇ · ~v = 0, (15.3)
∂t
and the continuity equation
∂ρ
+ ~v · ∇ρ + ρ∇ · ~v = 0. (15.4)
∂t
Here ~v , ρ and T are the fluid velocity, density and temperature, respectively, and the material properties are
expressed in terms of the viscosity parameters µ and λ, the heat conductivity K and the specific heat CV ,
with R = (γ − 1)CV .
If ρ0 and T0 are the equilibrium values of density and temperature, we may then write

ρ = ρ0 + δ, T = T0 + τ, (15.5)

so that δ and τ give the disturbances in ρ and T . To solve the coupled system consisting of (15.2)–(15.4) the
fully implicit time integration is employed. At each time level a nonlinear iteration is thus applied. Given

CSC – IT Center for Science

15. Large-amplitude Wave Motion in Air 101

nonlinear iterates ~vk , τk and δk , new approximations are generated via

(ρ0 + δk )[(~vt )k+1 + (~vk · ∇)~vk+1 ] − µ∆~vk+1 − (µ + λ)∇(∇ · ~vk+1 )

+ R(ρ0 + δk )∇τk+1 + R(T0 + τk )∇δk+1 = ~b,
(15.6)
(ρ0 + δk )CV [(τt )k+1 + ~vk · ∇τk+1 ) − K∆τk+1 + R(ρ0 + δk )(T0 + τk )∇ · ~vk+1 = 0,
(ρt )k+1 + ~vk · ∇δk+1 + (ρ0 + δk )∇ · ~vk+1 = 0,

with the time derivatives approximated using suitable finite difference schemes. It is recommended that the
BDF(2) method is used for the time discretization. It is also noted that the pressure is not approximated
directly, so it has to be computed separately using (15.1) and (15.5).
It should be noted that the solver is tailored to the case of the lowest-order continuous temperature and
density approximation. To obtain stable finite element solutions the velocity discretization must be enhanced
by using elementwise bubble functions or by rising the polynomial order of the velocity approximation.
Therefore a special element type definition in the solver input file should be given.

15.3 Keywords
The keywords that are related especially to this solver are described in the following.

Simulation
Coordinate System String
The coordinate system must be set to be one of the following options: Cartesian 2D,
Cartesian 3D or Axi Symmetric.
Solver solver id

Equation String
A name to the equation may be given by using this keyword.
Procedure File "CompressibleNS" "CompressibleNS"
This keyword is used to give the Elmer solver the place where to search for the compressible
Navier–Stokes solver.
Variable String
A name to the solver variable should be given by using this keyword.
Variable DOFs Integer
The value of this keyword should equal to dim + 2 where dim is the coordinate system dimen-
sion. The field variables are organized in such a way that the first dim components correspond
to the velocity solution and the temperature and density fluctuations come after the velocity.
Element String
The user has to specify what strategy is used for enhancing the velocity approximation by giving
the element type definition. If the command Element = ”p:2” is given, then the velocity is
approximated using the shape functions of the second order elements. The element type defini-
tion Element = ”p:1 b:1” can be given to enhance the velocity approximation with one
bubble function.

Material mat id
Equilibrium Density Real
The equilibrium density ρ0 should be specified by using this keyword.
Equilibrium Temperature Real
The equilibrium temperature T0 should be specified by using this keyword.
Specific Heat Real
The value of this keyword specifies CV .

CSC – IT Center for Science

15. Large-amplitude Wave Motion in Air 102

Specific Heat Ratio Real

The value of this keyword specifies γ.
Heat Conductivity Real
The heat conductivity K should be defined by using this keyword.
Viscosity Real
The viscosity parameter µ should be defined by using this keyword.
Bulk Viscosity Real
The viscosity parameter λ is taken to be λ = κ − 2/3µ, with κ the value of this keyword.
Body Force bc id

Body Force i Real

This keyword defines the i’s component of the body force.

CSC – IT Center for Science

 Part IV

Models of Electromagnetism

CSC – IT Center for Science

Model 16

Electrostatics

Module name: StatElecSolve

Module subroutines: StatElecSolver
Module authors: Leila Puska, Antti Pursula, Peter Råback
Document authors: Peter Råback, Antti Pursula

16.1 Introduction
The macroscopic electromagnetic theory is governed by Maxwell’s equations. In Elmer it is possible to
solve the electrostatic potential in linear dielectric material and in conducting medium. The dielectric case
is described in this Chapter. For static currents, refer to Chapter 17. Based on the potential, various field
variables as well as physical parameters, such as capacitance, can be calculated.

16.2 Theory
Maxwell’s equations are here written as
~
∇·D = ρ (16.1)
~
∇·B = 0 (16.2)
~
∂B
~
∇×E = − (16.3)
∂t
∂D~
~
∇×H = J~ + (16.4)
∂t
~ = µH
For linear materials the fields and fluxes are simply related, B ~ and D ~ = εE, ~ where the permittivity
ε = ε0 εr is defined through the permittivity of vacuum ε0 and the relative permittivity of the material εr .
In a stationary case the electric field may be expressed with a help of an electric scalar potential φ,
~ = −∇φ.
E (16.5)

Assuming linear material law and using the equation (16.1) gives

− ∇ · ε∇φ = ρ. (16.6)

This is the electrostatic equation for non-conducting media.

The energy density of the field is
1~ ~ 1
e= E · D = ε(∇φ)2 . (16.7)
2 2

CSC – IT Center for Science

16. Electrostatics 105

Thus the total energy of the field may be computed from

Z
1
E= ε(∇φ)2 dΩ. (16.8)
2 Ω

If there is only one potential difference Φ present then the capacitance C may be computed from
2E
C= . (16.9)
Φ2

16.2.1 Boundary Conditions

For electric potential either Dirichlet or Neumann boundary condition can be used. The Dirichlet boundary
condition gives the value of the potential on specified boundaries. The Neumann boundary condition is used
to give a flux condition on specified boundaries

− ε∇φ · ~n = g. (16.10)

The flux may be defined e.g. by the surface charge density: g = σ.

In case there is a object in infinite space it is of course not possible to extent the volume over it. Instead
a spherically symmetric approximation may be used. It results to a flux given by

~r · ~n
g = εφ . (16.11)
r2
This may be implemented as an additional term to the matrix so that the linear nature of the problem is
maintained.
Conductors are often covered by thin oxidation layers which may contain static charges. The effect of
these charges can be taken into account by Robin type of boundary condition which combines the fixed
potential value on the conductor and the flux condition due to the static charges
εh 1 εh
g=− φ + ρh + Φ0 on the boundary, (16.12)
h 2 h
where εh and h are the permittivity and the thickness of the oxidation layer respectively, ρ is the static charge
density of the layer, and Φ0 is the fixed potential on the conductor.
Note that this formulation is valid only for thin layers. For a larger layer a separate body should be added
and a source defined for that.

16.2.2 Capacitance matrix

There is a possibility to compute the capacitance matrix. The algorithm takes use of the original matrix A
before the initial conditions are set. Now the point charges are given by

q = Aφ. (16.13)

The induced charges on a body may be computed by summing up the point charges.
If there are n different bodies the boundary conditions are permuted n times so that body i gets a potential
unity while others are set to zero potential,
X
Cij = q. (16.14)
Γj

The symmetry of the matrix is ensured afterwards by setting

1
C= (C + C T ). (16.15)
2

CSC – IT Center for Science

16. Electrostatics 106

16.3 Notes on output control

The user can control which derived quantities (from the list of electric field, electric flux, electric energy,
surface charge density and capacitance matrix) are calculated.
There are also available two choices of visualization types for the derived quantities. The node values
can be calculated by taking the average of the derived values on neighbouring elements (constant weights).
This results often in visually good images. The other possible choice is to weight the average with the size of
the elements, which is more accurate and should be used when some other variable depends on these derived
values. The latter choice is also the default.

16.4 Keywords
Constants
Permittivity Of Vacuum Real [8.8542e-12]
Solver solver id
Equation String Stat Elec Solver
Variable String Potential
This may be of any name as far as it is used consistently also elsewhere.
Variable DOFs Integer 1
Degrees of freedom for the potential.
Procedure File "StatElecSolve" "StatElecSolver"

Following are listed four keywords with default values for output control.
Calculate Electric Field Logical [True]
Calculate Electric Flux Logical [True]
Calculate Electric Energy Logical [False]
Calculate Surface Charge Logical [False]
Calculate Capacitance Matrix Logical [False]
Capacitance Bodies Integer
In case of a capacitance matrix computation the number of bodies at different potential must be
given (not accounting the ground).
Capacitance Matrix Filename String
The name of the file where capacitance matrix is being saved. The default is cmatrix.dat.
Constant Weights Logical [True]
Used to turn constant weighting on for the results.
Potential Difference Real
Used to give the potential difference for which the capacitance is calculated, when capacitance
matrix calculation is not performed. This keyword gives thus the voltage between the electrodes
of a simple capacitor. The voltage has to be consistent with the potentials defined in boundary
conditions.

Material mat id
Relative Permittivity Real
Body Force bodyforce id
Charge Density Real

CSC – IT Center for Science

16. Electrostatics 107

Boundary Condition bc id
Potential Real
If the name of the primary variable is potential then this sets the Dirichlet boundary condition.
Electric Flux Real
Neumann boundary condition in terms of g.
Surface Charge Density Real
Another way to define flux condition. Identical to the previous keyword.
Electric Infinity BC Logical
The spherical approximation for the open boundaries extending to infinity.

The following five keywords are used if a thin oxidation layer is modeled. Note that these are only
active if the Electric Flux BC keyword is set to True.
Layer Thickness Real
Defines the thickness of the oxidation layer. This is presumed to extend on the outside the
boundary.
Layer Relative Permittivity Real
The relative permittivity of the oxidation layer.
Layer Charge Density Real
The volume charge density in the oxidation layer.
Electrode Potential Real
The potential on the conductor behind the oxidation layer.
Capacitance Body Integer i
These should number from i=1 up to Capacitance Bodies. The ground may be given
directly with zero potential or with value 0 for this keyword. This definition is only needed in
the computation of the capacitance matrix where the potential is permuted in a very specific way.

CSC – IT Center for Science

Model 17

Static Current Conduction

Module name: StatCurrentSolve

Module subroutines: StatCurrentSolver
Module authors: Leila Puska, Antti Pursula, Peter Råback
Document authors: Antti Pursula

17.1 Note
There is a vectorized and multithreaded version of the solver with almost the same functionality (some more,
some less) as module StatCurrentSolveVec.

17.2 Introduction
The macroscopic electromagnetic theory is governed by Maxwell’s equations. This module solves the elec-
trostatic potential in a conducting medium allowing volume currents and electric power loss (the Joule heat-
ing) to be derived.

17.3 Theory
In the electro-quasistatic approximation Maxwell’s equations are written as
~
∇·D = ρ (17.1)
~
∇×E ' 0 (17.2)
~
∂D
~
∇×H = J~ + (17.3)
∂t
so that the electric field may be expressed in terms of an electric scalar potential φ as
~ = −∇φ.
E (17.4)

In addition, the continuity equation for electric charges is easily obtained from (17.1) and (17.3):

∂ρ
+ ∇ · J~ = 0. (17.5)
∂t
Ohm’s law for conducting material gives the relationship between the current density and the electric
field,
J~ = σ E~ (17.6)

CSC – IT Center for Science

17. Static Current Conduction 109

where σ is the electric conductivity. Starting from the continuity equation (17.5) and using the equa-
tions (17.6) and (17.4), we get
− ∇ · σ∇φ = ρt . (17.7)
This Poisson equation is used to solve the electric potential. The source term is often zero, but in some cases
it might be necessary. The vectorized and multithreaded version of the solver can also be used to handle a
generalized equation
∂E~
− ∇ · J~ − ∇ · (ε ) = 0, (17.8)
∂t
where ε is the permittivity. This version is a consequence of (17.3).
The volume current density in a conductor is now calculated by

J~ = −σ∇φ, (17.9)

and the density of electric power loss, which is turned into heat, by

h = ∇φ · σ∇φ. (17.10)

The latter is often called the Joule heating. The total heating power is found by integrating the above equation
over the conducting volume.
The user may also compute the nodal heating which is just the integral of the heating sampled at nodes.

17.3.1 Boundary Conditions

For the electric potential either a Dirichlet or Neumann boundary condition can be used. The Dirichlet
boundary condition gives the value of the potential on specified boundaries. The Neumann boundary condi-
tion is used to give a current Jb on specified boundaries

Jb = σ∇φ · ~n. (17.11)

17.3.2 Power and current control

Sometimes the desired power or current of the system is known a priori. An additional control may then
be applied to guide the system. When the electric potential has been computed, the heating power may be
estimated from Z
P = ∇φ · σ∇φ dΩ. (17.12)
Ω
If there is a potential difference U in the system, the effective resistance may also be computed from R =
U 2 /P and the effective current from I = P/U .
The control is achieved by multiplying the potential and all derived fields by a suitable coefficient. For
power control the coefficient is p
CP = P0 /P , (17.13)
where P0 is the desired power. For current control the coefficient is

CI = I0 /I, (17.14)

where I0 is the desired total current.

17.4 Note on output control

The user can control which of the derived quantities (i.e., the volume current and the Joule heating) are
calculated and additionally specify if the electric conductivity is also output. The latter is useful when the
conductivity depends for example on temperature. This feature is available only for cases with isotropic
(scalar) conductivities.

CSC – IT Center for Science

17. Static Current Conduction 110

Two ways to visualize the derived quantities are available. The node values can be calculated by taking
the average of the derived values over a collection of neighbouring elements (constant weights). This often
results in visually good images. The other possibility is to weight the average with the size of the elements,
which is more accurate and should be used when some other variable depends on these derived values. The
latter choice is also the default.

17.5 Keywords
Solver solver id
Equation String Stat Current Solver
Variable String Potential
This may be any name as far as it is also used consistently elsewhere.
Variable DOFs Integer 1
Degrees of freedom for the potential.
Procedure File "StatCurrentSolve" "StatCurrentSolver"

The following two keywords control the calculation of derived fields.

Calculate Volume Current Logical [True]
Calculate Joule Heating Logical [True]
Constant Weights Logical [True]
Used to turn constant weighting on for the results.
Calculate Nodal Heating Logical [True]
Calculate nodal heating that may be used to couple the heat equation optimally when using
conforming finite element meshes.
Power Control Real
Apply power control with the desired heating power being P0 .
Current Control Real
Apply current control with the desired current being I0 .
Material mat id
Electric Conductivity Real
Body Force bodyforce id
Current Source Real
This enables a scalar-valued source, not used often though.
Joule Heat Logical
If this flag is active the Heat equation will automatically compute the quantity ∇φ · σ∇φ as heat
source. Then it is assumed that φ is named Potential. If there is no heat equation this flag
has no effect.
Boundary Condition bc id
Potential Real
Dirichlet BC for the potential.
Current Density BC Logical
Must be set to True if Neumann BC is used.
Current Density Real
Neumann boundary condition for the current.

CSC – IT Center for Science

Model 18

Computation of Magnetic Fields in 3D

Module name: MagnetoDynamics

Module subroutines: WhitneyAVSolver,WhitneyAVHarmonicSolver,MagnetoDynamicsCalcFields
Module authors: Juha Ruokolainen, Mika Malinen, Eelis Takala
Document authors: Mika Malinen, Juha Ruokolainen, Juhani Kataja, Eelis Takala, Peter Råback

18.1 Introduction
This module may be used to solve a version of the Maxwell equations in the A-V form. The approximation
of the associated vector potential variable A is here done by using vector-valued (edge) finite element basis
functions, while the classic Lagrange interpolation is applied to compute the scalar potential V . The use
of edge finite elements limits the applicability of this solver to 3D problems. In addition to performing the
computations in the time domain, the analogous version of the equations may also be solved in the frequency
domain. Several ways to handle stationary equations are also included. Furthermore, an additional solver
may be called to produce nodal and elementwise approximations of derived fields after the two potentials
have been obtained.
The equations over moving media are treated in the case of rigid motion. This implies that the associated
velocity field is divergence-free and the velocity gradient is both constant and skew.

18.2 The transient equations

If a charge q moves in a region in which there are both electric and magnetic fields, the electromagnetic force
on the charge moving with velocity v is experimentally observed to be given by the Lorentz force
F = q(E + v × B). (18.1)
Alternatively, the force exerted on a volume element dΩ is therefore given by
dF = (ρE + ρv × B)dΩ (18.2)
where ρ is the charge density, per unit volume. By assuming a short relaxation time of the charge’s motion
as compared with the characteristic time scale of the motion of the body, we may incorporate the notion of
such electromagnetic field in Ohm’s law by writing it as
F
J = σ( ) ≡ σE 0 , (18.3)
q
where J is the current density and σ is the electrical conductivity. An alternative would be to define the
electromagnetic field E 0 as the ratio of the volume force density to the charge density, but both the definitions
lead to the conclusion that in order to explain the Lorentz force we must have
E 0 = E + v × B. (18.4)

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 112

We note that since our definition of the electromagnetic field depends on the notions of force and charge
which are assumed to be invariant quantities (under a change of observer), the electromagnetic field also has
an invariant nature. It is tacit here that if the separation of the known electromagnetic field into its electric
and magnetic components was sought via (18.4), the result would depend on the observer. However, we
shall not need such separation since solving for E 0 is enough to find the current density.
Otherwise the content of electromagnetic equations on a region Ω is here cast into a magnetic version of
Maxwell’s equations

∂B
curl E = − , (18.5)
∂t
1
curl( B) − J = g, (18.6)
µ
div B = 0, (18.7)
div J = 0, (18.8)

where µ is the permeability and g is a divergence-free source satisfying (for ways to ensure this condition
beforehand, see the description of the Helmholtz projection in the context of stationary equations below)

div g = 0. (18.9)

Writing this system in terms of the electromagnetic field defined by (18.4) via eliminating E and using
Ohm’s law (18.3) yields

∂B
− curl(v × B) + curl E 0 = 0, (18.10)
∂t
1
curl( B) − σE 0 = g, (18.11)
µ
div B = 0, (18.12)
div(σE 0 ) = 0. (18.13)

The content of this system is adequate for finding the instantaneous spatial solutions B(x, t) and E 0 (x, t) at
time t simultaneously over both static and moving parts of the model. Here the point x is thus specified by
its coordinates with respect to a single, fixed Cartesian coordinate frame.
If an Elmer model contains moving bodies, the spatial discretization is typically done over an instanta-
neous configuration whose representation is obtained via a rigid motion of the previous mesh into the current
configuration. In this case the time stepping machinery of Elmer by default produces an approximation to
the material time derivative of a spatial field (the material point is held fixed in the differentiation) when the
field is a scalar or vector field. It agrees with the usual definition of the substantial (or total) time derivative
of the spatial field. However, when the field is a one-form and is approximated by using edge finite elements
(here the case of the vector potential), a more subtle approach is needed to show that the computational
procedure leads to an approximation of the Lie derivative [1].
Since the computational procedure does not make it straightforward to evaluate the standard partial
derivatives with respect to time, the need of rewriting the equations in forms which employ other time
derivatives arises as a natural endeavour. To this end, we shall consider the upper convected time derivative

DB ∂B
= + (v · ∇)B − (B · ∇)v + (div v)B, (18.14)
Dt ∂t
which agrees with the Lie derivative Lv B of the vector B with respect to v when the motion is rigid so that

div v = 0. (18.15)

It can be expressed in terms of the substantial time derivative

DB ∂B
≡ + (v · ∇)B (18.16)
Dt ∂t

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 113

as
DB DB
= − (B · ∇)v + (div v)B. (18.17)
Dt Dt
By using vector identities, the definition (18.14) can also be rewritten as
DB ∂B
= − curl(v × B) + v(div B). (18.18)
Dt ∂t
This immediately implies that, under Gauss’s law for the magnetic field (18.12), the content of the Faraday
law (18.10) can be expressed as
DB
+ curl E 0 = 0. (18.19)
Dt
Although we consider (18.19) to be a convenient way to express the Faraday law for our purposes, we do
not want to assert whether this useful mathematical reduction happens by chance or whether it should be
considered to reflect some theoretical underpinning.
If we think of A as a one-form, the formula for the Lie derivative of A with respect to v should be
written as (see, for example, [1])
∂A
Lv A = + (v · ∇)A + (∇v)T A. (18.20)
∂t
In the case of rigid motion, however, the velocity gradient is skew so that

(∇v)T = −∇v. (18.21)

Hence the vector representations for the Lie differentiation of vectors and one-forms become the same.
When the edge finite element basis functions defined on the reference element give the pull-back of
the basis functions on the physical element by the element mapping (the standard construction followed by
Elmer), evaluating the rate of change of the associated degrees of freedom gives coefficients to approximate
the finite element interpolant of the Lie derivative. That is, if ϕk (·) are linear functionals which define the
degrees of freedom of a one-form, it follows that
. 1
ϕk (Lv A) = [ϕk (A(·, τ + δt)) − ϕk (A(·, τ ))] (18.22)
δt
where τ is a fixed value of time and δt is a time increment. Thus writing the equations such that the Lie
derivatives are employed is seen to be very natural.
In practice the solution is sought in terms of potentials. In the first place we set

B = curl A. (18.23)

It should be noted that this implies some ambiguity, since the resulting set of equations does not have a
unique solution without imposing additional constraints on A(x, t). Otherwise, if A satisfies the equations,
any field Aφ having the decomposition Aφ = A + ∇φ may also be made to be a solution. The uniqueness
of A could be assured for example by seeking A(·, t) ∈ H(curl, Ω) ∩ H(div, Ω) that satisfies additionally

div A = 0

on Ω and
A·n=0
on the boundary ∂Ω.
In the case of the vector potential description (18.23) the Faraday law in the form (18.10) yields
∂A
curl( − v × curl A + E 0 ) = 0,
∂t
so we may automate the satisfaction of the Faraday law by seeking the solution in the form
∂A
− v × curl A + E 0 = −∇ψ, (18.24)
∂t

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 114

with ψ being an unknown scalar potential. Switching to the substantial time derivative then gives
DA
− (v · ∇)A − v × curl A + E 0 = −∇ψ. (18.25)
Dt
Straightforward calculation shows that this is equivalent to
DA
− (∇A)T v + E 0 = −∇ψ (18.26)
Dt
and, by using the vector identity

(∇A)T v = ∇(v · A) − (∇v)T A, (18.27)

we further obtain
DA
+ (∇v)T A + E 0 = −∇(ψ − v · A). (18.28)
Dt
By setting
ψ = V + v · A, (18.29)
the content of (18.28) can finally be expressed as

Lv A + E 0 = −∇V. (18.30)

The equation (18.30) offers the possibility of eliminating the field E 0 from the set of primary unknowns
while the additional constraint (18.13) serves the determination of V . It should be noted that the scalar
potential ψ is related to the field E via
∂A
+ E = −∇ψ.
∂t
The relation (18.29) can be used to recover ψ after A and V have been solved.
To derive a weak version of the equations, let v be an appropriate test function for V , so that we have v ∈
H 1 (Ω). Multiplying (18.13) with v, integrating by parts and using (18.30) bring us to the weak formulation
Z Z Z
σ(Lv A) · ∇v dΩ + σ∇V · ∇v dΩ = − (σE 0 ) · n v dS. (18.31)
Ω Ω ∂Ω

The determination of the scalar potential V is thus joined with the possibility of specifying either V or the
normal component of the current density σE 0 on the boundary. If the normal component of the current
density is specified on the entire boundary ∂Ω as

− (σE 0 ) · n = jn , (18.32)

the boundary data must satisfy the compatibility condition

Z
jn dS = 0.
∂Ω

On the other hand, by using (18.23) and (18.30), we may rewrite (18.11) as
1
σ(Lv A) + σ∇V + curl( curl A) = g (18.33)
µ
to obtain the weak version
Z Z Z
1
σ(Lv A) · η dΩ + σ∇V · η dΩ + curl A · curl η dΩ
µ
Ω Ω Ω
Z Z (18.34)
1
+ ( curl A) · (η × n) dS = g · η dΩ,
µ
∂Ω Ω

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 115

with η an appropriate test function corresponding to A. The weak formulations obtained from (18.34) and
(18.31) generally form the basis for the A-V formulation of the problem.
It should be noted that here we have avoided seeking a unique solution in the space

A(·, t) ∈ H(curl, Ω) ∩ H(div, Ω)

as only the requirement A(·, t) ∈ H(curl, Ω) appears to be necessary in this derivation. The Elmer im-
plementation relies on this minimal regularity assumption so that a finite element approximation Ah (·, t)
is sought from an edge finite element space X h ⊂ H(curl, Ω). This simplification however leads to the
inconvenience that the uniqueness of the vector potential solution cannot be ensured. Thus, given a solution
(A, V ), we can generate another solution (Aφ , Vφ ) ≡ (A + ∇φ, V − Lv φ), although the associated fields
B and E 0 remain invariant.

The steady state solution of the evolutionary equations. Sometimes the steady state solution of the evo-
lutionary model may be of an interest. For example the steady state solution of a case where a homogeneous
disk is spun with a constant angular velocity in a region in which there is a steady magnetic field without
circumferential variation can be described over a fixed domain. Then (18.24) yields

E 0 − v × curl A = −∇ψ. (18.35)

In this special case the scalar potential variable of the solver is taken to be ψ.
In this connection, we note that when a body makes a rigid rotation about the line through the origin o
spanned by the angular velocity ω, the velocity field is described by the formula

v(x, t) = v(o, t) + ω(t) × (x − o). (18.36)

We also note that the term (∇v)T A occurring in the expression for the Lie Derivative has the following
representation in terms of ω
(∇v)T A = −(∇v)A = −ω × A. (18.37)

A Poynting’s theorem for electromagnetic energy. The magnetic energy density is defined by
1
Wm = B · H. (18.38)
2
Let us define a Poynting vector S 0 corresponding to our definition of the electromagnetic field E 0 by

S 0 = E 0 × H, (18.39)

with B = µH. In view of (18.19) and (18.11), we then obtain

div S 0 = curl E 0 · H − E 0 · curl H

DB (18.40)
=− · H − E 0 · (σE 0 + g).
Dt
On the other hand, the Lie derivative of the magnetic energy density (note that for scalar-valued functions
the expressions of the Lie derivative and the total derivative are equivalent) is given by

D 1 DB
( B · H) = · H. (18.41)
Dt 2 Dt
We hence come to the conservation principle of the magnetic energy expressed as
DWm
+ div S 0 = −E 0 · (σE 0 + g). (18.42)
Dt
The right-hand side of (18.42) describes the power per unit volume of the heating effect of the electric current
which is called the Joule effect.

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 116

Since the displacement current has been neglected in the magnetic version of the equations considered,
the above conservation principle does not contain an electric energy density term. Elmer however calculates
the total electromagnetic energy density as
Wm + We
with
1 0
We = εE · E 0 . (18.43)
2
Here ε is the permittivity.

Solution in the frequency domain. The equations in the A-V form may also be solved in the frequency
domain. In this case the ansatz A(x, t) = A(x) exp(iωt) and V (x, t) = V (x) exp(iωt) is made to obtain
the analogous set of equations for determining the complex-valued amplitudes A(x) and V (x). In addition,
we employ (18.24) with ψ = V .

18.3 The stationary equations and the Helmholtz projection of a source

In the stationary case the electric field E 0 is simply the gradient of a scalar potential. The weak formulation
based on (18.34) and (18.31) then simplifies to
Z Z Z Z
1 1
σ∇V · η dΩ + curl A · curl η dΩ + ( curl A) · (η × n) dS = g · η dΩ (18.44)
µ µ
Ω Ω ∂Ω Ω

and Z Z
σ∇V · ∇v dΩ = − (σE 0 ) · n v dS. (18.45)
Ω ∂Ω

As the solution of V and A can then be done sequentially by first solving for V , the basic scenario for
applying the solver to stationary cases is that only the field A is solved by employing the weak formulation
Z Z Z
1 1
curl A · curl η dΩ + ( curl A) · (η × n) dS = g S · η dΩ (18.46)
µ µ
Ω ∂Ω Ω

where g S denotes the static source.

It should be noted that the source should generally be divergence-free. The divergence-freeness of g S
may be assured by setting g S = P(g U ) where g U is the user-supplied source term and the Helmholtz
projection P(g U ) = g U − ∇Q, with Q ∈ M ⊂ H 1 (Ω), is defined via the requirement
Z
∇ · (g U − ∇Q)q dΩ = 0 (18.47)
Ω

for any admissible variation q of Q. Integration by parts is used to obtain the version
Z Z Z
∇Q · ∇q dΩ = g U · ∇q dΩ − P(g U ) · nq dS. (18.48)
Ω Ω ∂Ω

If g U has already been obtained from a scalar field V s as

g U = −σ∇V s , (18.49)

to obtain a close resemblance of g U and P(g U ) (especially, P(g U ) = g U when g U is already divergence-
free) it is natural to set
P(g U ) · n = g U · n (18.50)
on the boundary where the current density was prescribed. On the remaining part of the boundary where the
Dirichlet constraint was specified for V s the homogeneous Dirichlet constraint for the field Q may be used.

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 117

However, by default a different strategy is applied by setting Q = 0 on parts where |g U · n| =

6 0. Then the
boundary integral in (18.48) vanishes. The Helmholtz projection of the source may also be performed when
the evolutionary version of the equations is handled.
Other types of source vectors may also be considered as the user may generally specify the source in the
form
g = P(g U ) + curl M s − σ∇V s (18.51)
or, if the Helmholtz projection is not applied,

g = g U + curl M s − σ∇V s . (18.52)

Here M s is referred to as the magnetization. It arises from using a constitutive law of the form

H = µ−1 B − M s . (18.53)

The last terms in (18.51) and (18.52) enable the direct generation of the source electric current density in
terms of the source potential V s without first computing g U from (18.49).
To conclude, we note that it is also possible to solve the stationary equations such that both A and V are
handled as unknowns and solved simultaneously by employing the variational equations
Z Z Z Z
1 1
σ∇V · η dΩ + curl A · curl η dΩ + ( curl A) · (η × n) dS = P(g U ) · η dΩ (18.54)
µ µ
Ω Ω ∂Ω Ω

and Z Z
σ∇V · ∇v dΩ = − (σE 0 ) · n v dS. (18.55)
Ω ∂Ω

18.4 The boundary conditions

We see from the weak versions (18.34) and (18.31) that, if the Dirichlet type constraints

A × n = a × n and V = v̂ (18.56)

are not given, we may specify the tangential components of the magnetic field H = (1/µ)B and the normal
component of current density J = σE 0 . These may be defined via giving h to define
1
curl A = n × h × n (18.57)
µ
and
− (σE 0 ) · n = jn . (18.58)
We note that giving a Dirichlet constraint is a useful way to guarantee the uniqueness of the scalar potential
V which would otherwise be determined only up to a constant.
A Robin-like generalization of (18.57) leads to the boundary condition
1
curl A = α(A × n) + n × h × n, (18.59)
µ
with α being a given parameter. We however note that the case α 6= 0 may lack in having a physical
interpretation. On the other hand, a generalized version of (18.58) is written as

− (σE 0 ) · n = jn − βV, (18.60)

which in the stationary case reduces to the Robin boundary condition

σ∇V · n + βV = jn . (18.61)

In addition, a procedural technique may be applied to specify a Dirichlet constraint for A when the normal
component of the magnetic flux density B is given on the boundary.

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 118

The surface impedance condition for time-harmonic cases. In the case of time-harmonic analysis it is
possible to generate tangential surface currents via giving a boundary condition

E × n = ZS (H × n) × n (18.62)

where ZS is referred to as the surface impedance and defined as

1+i
ZS = . (18.63)
σδ
Here δ denotes the skin depth p
δ= 2/(σµω). (18.64)

18.5 A consistently regularized formulation for magnetostatics

The possibility to seek a unique vector potential solution to the magnetostatic equations is included here as
a special case via using the scalar variable to impose the divergence-free constraint on A in a weak manner.
This strategy employs the weak formulation
Z Z Z
1
curl A · curl η dΩ − ∇φ · η dΩ = P(g U ) · η dΩ,
µ
Ω Ω Ω
Z (18.65)
(−A + k∇φ) · ∇q dΩ = 0
Ω

with φ ∈ H 1 (Ω)/P0 (Ω) (the definition of the space H 1 (Ω)/P0 (Ω) reflects the fact that φ can be determined
up to a freely chosen constant only) and k being a regularization/stabilization parameter. The choice k = 1
is seen to be natural. Then, if ΠA ≡ A − ∇φ denotes the Helmholtz projection of A, the content of this
formulation can also be cast into the form
Z Z Z
1
curl A · curl η dΩ − (A − ΠA) · (η − Πη) dΩ = P(g U ) · η dΩ,
µ
Ω Ω Ω
Z (18.66)
− ΠA · ∇q dΩ = 0.
Ω

This formulation reflects how the scheme works; the second term in the left-hand side of the first equation in
(18.66) acts as a penalization term to get into the right set of divergence-free solutions. That is, A−ΠA = 0
is enforced by having this term. It is noted that with k = 0 the method reduces to the standard Lagrange
multiplier formulation to impose the Coulomb gauge.

18.6 Keywords
Keywords for WhitneyAVSolver
Here we list the keywords that are relevant to solving the evolutionary and stationary versions of the equa-
tions by calling the solver subroutine WhitneyAVSolver and that may also be common to the other
solvers. Such common keywords relate to specifying material parameters, body forces, and boundary con-
ditions.
Constants
Permeability of Vacuum Real
This constant has the default value 4π · 10−7 .
Material mat id
The following material parameters may be used by all the solvers in the module.

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 119

Electric Conductivity Real

This keyword is used to specify the electric conductivity σ. If the material is anisotropic, the
electric conductivity may also be defined to be a tensor function by giving its components with
respect to the global coordinate lines.
Relative Permeability Real
If this keyword is used, the permeability µ can be specified in terms of the permeability of
vacuum. To obtain the permeability, the value of this keyword is then internally multiplied with
the permeability of vacuum. Instead of using this keyword, the keywords Permeability or
Reluctivity may be used.
Permeability Real
This keyword may be used to specify directly the permeability µ.
Reluctivity Real
The value of this keyword specifies the reluctivity ν. The permeability is then taken to be µ =
1/ν. The reluctivity can also be taken to be an array-valued parameter in order to model magnetic
anisotropy.

Solver solver id
Equation String WhitneySolver
A describing name for the discrete model handled by this solver may be given by using this
keyword. The name can be changed as long as it is used consistently.
Procedure File "MagnetoDynamics" "WhitneyAVSolver"
This declaration specifies the name of the solver subroutine.
Variable String AV
The name of the variable may be freely chosen provided it is used consistently also elsewhere.
The associated number of degrees of freedom should always be one.
Element
The default initialization routine should give a suitable element type definition automatically, so
that the value of this keyword need not necessarily be given by the user.
Use Piola Transform Logical
Several types of edge finite elements can be used for spatial discretization. This keyword must
be given the value True when the basis functions for the edge element interpolation are selected
to be members of the optimal edge element family or when second-order approximation is used.
The elements of the optimal family provide optimal accuracy even when the physical elements
are not obtained as affine images of the reference elements. The simpler basis functions which
are used otherwise may not provide such accuracy for non-affine element shapes. For the docu-
mentation of the edge element basis functions see the appendices of the ElmerSolver Manual.
Quadratic Approximation Logical
This keyword can be used to activate the approximation with the edge finite elements of second
degree; see also the keyword Use Piola Transform.
Static Conductivity Logical
If the stationary equations are solved such that both A and V are handled as unknowns, this
keyword can be given the value True so that the solver can create an automated value for the
Element keyword.
Fix Input Current Density Logical
To ensure the divergence-freeness of the source term via performing the projection (18.47), the
value True should be given for this keyword.
Automated Source Projection BCs Logical
If the projection (18.47) is applied to the user-specified source g U , the solver has originally
constrained the field Q automatically such that Q is chosen to satisfy the zero Dirichlet condition
on parts where |g U · n| =6 0. This feature can be disabled by giving the value False for this
keyword in order to specify, for example, the homogeneous Dirichlet constraint for Q (known as

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 120

the field Jfix) on boundaries where the scalar potential V or V s is constrained by a Dirichlet
constraint.
Use Lagrange Gauge Logical
This keyword must be True in order to switch to the regularized formulation (18.65) which has
a unique vector potential solution.
Lagrange Gauge Penalization Coefficient Real
This keyword defines the stabilization parameter k in (18.65).
Use Tree Gauge Logical
Due to the chosen discretization, the vector potential is not sufficiently constrained to guarantee
the uniqueness. Despite this, the iterative solvers are expected to be able to generate a consistent
solution among many. However, to enable the solution with direct solvers this keyword is by
default given the value True so that a special technique is applied to additionally constrain the
discrete vector potential variable (in the case of iterative solvers the default value is False).
This option is not supported when Use Piola Transform = True is given.
Linear System Refactorize Logical
It is noted that if the refactorization of the system matrix is controlled with this keyword, the
matrix factorization is anyhow recomputed automatically if the time step size differs from the
previous one.
Linear System Preconditioning String
Here the value None may give better performance than the standard ILU preconditioners since
the null space of the system matrix may be non-trivial, leading to a singularity problem in con-
nection with handling the LU decomposition.
Linear System Iterative Method String
The iterative solvers BiCGStab or BiCGStab(L) may work well.
Body Force bf id
In the body force section the user may give various volumetric sources contained in the vector g as
defined in either (18.51) or (18.52). The velocity field related to a rigid motion may also be defined
for cases where this information is explicitly needed to write the equations.

Current Density i Real

This keyword is used to specify the components of the source g U .
Magnetization i Real
This keyword is used to specify the components of the magnetization Mis , with i = 1, 2, 3.
Electric Potential Real
This keyword specifies the source electric potential V s .
Angular Velocity i Real
When the velocity is explicitly needed, this keyword may be given to define the components of
the angular velocity ω. This is then used to obtain the representation for the velocity term in the
equation (18.35).
Lorentz Velocity i Real
This keyword may be used to define the velocity v(x, t) when the steady state solution of the
evolutionary model is sought. Alternatively, if the velocity is specified by the formula (18.36)
and the angular velocity ω is given, a constant value may be given in order to specify the uniform
part v(o, t) of the velocity.

Boundary Condition bc id

As explained, two versions of Dirichlet conditions are possible in connection with the A-V formu-
lation. The first option relates to giving the value of the scalar potential, while the other version is
used for prescribing the tangential components of the vector potential field. Assuming that the solver
variable is AV, we may thus use the following keywords to specify the Dirichlet conditions:

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 121

AV Real
This keyword is used to specify the Dirichlet condition for the scalar potential V , which is
approximated by using the standard Lagrange interpolation.
AV {e} j Real
This keyword is used to the give the vector a in (18.56) in order to prescribe the degrees of
freedom corresponding to the edge element interpolation of the vector potential. The value
of this keyword defines the component aj , j ∈ {1, 2, 3}, with respect to the global Cartesian
coordinate system.
Jfix Real
This keyword is used to specify the Dirichlet condition for the scalar potential field Q, which is
defined via (18.47).

The following keywords may be used in order to handle the flux-related boundary conditions:

Magnetic Field Strength i Real

This keyword can be used to define the components hi of the vector h so that the boundary
conditions (18.57) and (18.59) may be imposed. It should be noted that on an interface between a
permanent magnet with a given magnetization M s1 and a material without magnetization (M s2 =
0) the boundary condition m × (ν1 B 1 − ν2 B 2 ) = m × M s1 is imposed by default, with m
being the normal vector associated with the common interface.
Electric Current Density Real
This keyword can be used to define the electric current density jn in the boundary conditions
(18.58) and (18.60).
Current Density Real
If the Helmholtz projection of the source is applied, this keyword may be used to specify the
left-hand side in (18.50) as g U · n = −jn , with jn the value of this keyword.
Magnetic Transfer Coefficient Real
The value of this keyword gives the parameter α in the boundary condition (18.59).
Electric Transfer Coefficient Real
The value of this keyword gives the parameter β in the boundary condition (18.60).

Finally, the following keywords relate to a procedural technique to determine a tangential constraint
for the vector potential A when the normal component of the magnetic flux density B is specified on
the boundary.

Magnetic Flux Density i Real

This keyword is used to specify the components of the magnetic flux density B with respect to
the global Cartesian coordinate axes.
Magnetic Flux Density {n} Real
This keyword may be used to specify directly the normal component Bn of the magnetic flux
density.

Keywords for WhitneyAVHarmonicSolver

In the following the additional keywords related to solving the harmonic version are listed. Typically these
are used for giving optional values which specify the imaginary parts of the parameter values. The corre-
sponding real parts are then given by using the keyword commands already described above.

Solver solver id
Equation String WhitneyHarmonicSolver
This gives a describing name for the discrete model handled here. The name can be changed as
long as it is used consistently.

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 122

Procedure File "MagnetoDynamics" "WhitneyAVHarmonicSolver"

The name of the solver subroutine is declared.
Variable String P[Pot re:1 Pot im:1]
The name of the variable may be freely chosen provided it is used consistently also elsewhere.
The associated number of degrees of freedom is always two. Here the real and imaginary parts
are named so that they are easily recognized.
Angular Frequency Real
The angular frequency ω = 2πf in the harmonic ansatz is specified.
Material mat id

Reluctivity Im Real
The reluctivity ν = 1/µ may be specified to be a complex-valued quantity with the imaginary
part given by using this keyword. An array value may also be given in order to model magnetic
anisotropy.
Electric Conductivity Im Real
The value of this keyword may be used to specify the imaginary part of the conductivity param-
eter. If the material is anisotropic, the electric conductivity may also be defined to be a tensor
function by giving its components with respect to the global coordinate lines.
Body Force bf id
The following keywords are used to specify the imaginary parts of the volume sources:

Current Density Im i Real

Magnetization Im i Real
Boundary Condition bc id
The following keywords relate to specifying imaginary parts in conjunction with defining boundary
conditions:

Magnetic Field Strength Im i Real

Electric Current Density Im Real
Magnetic Transfer Coefficient Im Real
Electric Transfer Coefficient Im Real
Magnetic Flux Density Im i Real
Magnetic Flux Density Im {n} Real

To give the boundary condition (18.62) the following keywords may be used:
Layer Electric Conductivity Real
This keyword defines the electric conductivity of the surface material.
Layer Relative Permeability Real
The permeability µ of the surface conductor is specified in terms of the value of this keyword
and the permeability of vacuum.

Keywords for MagnetoDynamicsCalcFields

An additional solver may finally be called to compute derived fields.

Solver solver id
The fields to be computed are chosen in the solver section. The field Magnetic Flux Density
is computed always, others if requested. The size of a vector field is 3, while a tensor field has the size
6. For the harmonic solution the sizes are doubled as the imaginary components are also present.

CSC – IT Center for Science

18. Computation of Magnetic Fields in 3D 123

Equation String CalcFields

A describing name for the solver is given. This can be changed as long as it is used consistently.
Procedure File "MagnetoDynamics" "MagnetoDynamicsCalcFields"
The name of the solver subroutine is given.
Potential Variable String
This keyword is used to specify the name of the underlying potential variable, for example AV.
For edge elements the Use Piola Transform and Quadratic Approximation flags
are inherited from the solver owning this variable.
Angular Frequency Real
The angular frequency must be declared in this connection also as this is needed by some post-
processed fields.
Calculate Magnetic Field Strength Logical
If True is given, a vector field Magnetic Field Strength is computed.
Calculate Electric Field Logical
If True is given, a vector field Electric Field is computed.
Calculate Current Density Logical
If True is given, a vector field Current Density is computed.
Impose Body Force Current Logical
If True is given, the body force current density given by the keyword Current Density i
is added to above.
Calculate Nodal Forces Logical
This keyword can be used to activate the computation of nodal forces to enable further mechan-
ical analysis. The nodal forces are calculated by computing an opposite parameter derivative of
the magnetic energy, with the placement of the body being described in terms of a one-parameter
family of deformations x(x, ) = x + λk u. Here u is a unit vector along the global coordinate
axis and λk is the Lagrange basis function associated with a mesh node xk . The components of
the nodal forces are then obtained as
Z Z ZB
fk · u = − H · (B · ∇λk )u dΩ + [H · B − H · dB] div(λk u) dΩ.
Ω Ω

Calculate Maxwell Stress Logical

If True is given, a tensor field Maxwell Stress is computed. This computation assumes
that the reluctivity (and the permeability) is a real-valued parameter.
Calculate Harmonic Loss Logical
If True is given, scalar fields Harmonic Loss Linear and Harmonic Loss Quadratic
are computed. See Chapter 26 for more details.
Calculate Joule Heating Logical
If True is given, a scalar field Joule Heating is computed.
Calculate Nodal Heating Logical
If True is given, a scalar field Nodal Joule Heating is computed. In SI system the re-
sulting unit is Watt. The nodal heating is easy to directly link as a nodal heat source to the heat
equation assuming conforming meshes for the both equations.
Calculate Nodal Fields Logical
If this is set False, do not compute nodal fields at all. The default is True.
Calculate Elemental Fields Logical
If this is set False, do not compute elemental fields at all. The default is True. Elemental
fields are nice in that they can present discontinuities in meshes.

CSC – IT Center for Science

BIBLIOGRAPHY 124

If the harmonic loss will be computed, then the following material parameters should be provided. Note
that these are not parameters needed by the primary solver since the loss estimation is just a post-processing
feature. See Chapter 26 for more details.

Material material id
Harmonic Loss Linear Coefficient Real
This keyword is used to define the material parameter C in (26.6) for the losses that are linear
with frequency. Note that the coefficient may be a function of frequency itself.
Harmonic Loss Quadratic Coefficient Real
As the previous keyword except define the material parameter C for the quadratic loss terms.

Component component id

Calculate Magnetic Force Logical

The lumped magnetic force affecting the master bodies of the current component will be calcu-
lated if this is set true. If elemental fields are available, then airgap forces are also lumped.
Calculate Magnetic Torque Logical
The total torque associated with the master bodies of the current component will be calculated
if this is set true. If elemental fields are available, then also torque arising from airgap forces is
included.
Master Bodies Integer
This defines the integer identifiers of bodies which constitute a component.
Master Boundaries Integer
The identifiers of boundary condition sections may also be used to constitute a component.
Torque Origin(3) Real
This keyword is used to define a point in space which torque axis meets.
Torque Axis(3) Real
This keyword is used to define the axis with respect to which torque is calculated.

In addition to the field computation, two scalar quantities are always computed by the solver and saved in
the list of the Simulation section values: Eddy current power and Magnetic Field Energy.
The first one is only relevant for time-dependent and harmonic cases.

Bibliography
[1] Jerrold E. Marsden and Thomas J.R. Hughes. Mathematical Foundations of Elasticity. Dover Publica-
tions, Inc., New York, 1994.

CSC – IT Center for Science

Model 19

Circuits and Dynamics Solver

Module name: CircuitsAndDynamics

Module subroutines: CircuitsAndDynamics, CircuitsAndDynamicsHarmonic, CircuitsOutput
Module authors: Eelis Takala, Juha Ruokolainen
Document authors: Eelis Takala

19.1 Introduction
It may become necessary to connect a magnetoquasistatic model to circuit equations when modelling elec-
trical devices that are circuit-driven. Even if such model could in theory be handled without introducing
circuits, it can considerably simplify the model setup. In Elmer the circuit equations are added into the
system matrix of a magnetodynamics solver and thus they are solved in a strongly coupled manner together
with the finite element equations. One should note that adding the circuit equations may hinder the parallel
performance of the solver. In case this is a critical concern to the user, one should pay attention to tuning
the model [9] (for example by using the so-called reduced support that can bring great benefits [8]). Here
the module for adding the circuit equations to the system matrix of the magnetoquasistatic solvers is pre-
sented. Note that this solver may (and needs to) be used together with the modules MagnetoDynamics
or MagnetoDynamics2D.
When the CircuitsAndDynamics module is used in a published academic work, please refer to [9]. When
reduced support is used in order to achieve better parallel scalability, one may refer to [8].

19.2 Theory
In Elmer the magnetodynamic problems are currently solved by using the so-called a-v formulation. This
can be done in 2D or 3D and with all simulation types (i.e., steady, harmonic, or transient). The a-v
formulation [7, p. 124] may be presented as follows: find a ∈ We1 and v ∈ We0 such that
(ν∇ × a, ∇ × a0 )Ω + (σ∂t a, a0 )Ωc + (σ∇v, a0 )Ωc − (j 0 , a0 )Ω + hn × h, a0 iΓh = 0 ∀a0 ∈ We,0
1
(19.1)
and
(σ∂t a, ∇v 0 )Ωc + (σ∇v, ∇v 0 )Ωc + hn · j, v 0 iΓc = 0 ∀v 0 ∈ We,0
0
, (19.2)
−1
where ν = µ is the reluctivity, a is the magnetic vector potential, v is the electric scalar potential, j 0 is
the source current density, n is the normal vector to the boundary Γh , and a0 and v 0 are test functions. The
domain Ω is the considered body, Ωc ⊂ Ω consists of a conductive material, and Γh and Γc are boundaries
where the magnetic field and the current density field are imposed, respectively. The edge finite element
discretization [7, p. 93] generates approximations of the magnetic vector potential a and electric scalar po-
tential v functions in discrete versions of We1 and We0 . This formulation thus requires a system matrix with
two types of unknowns for expressing the magnetic vector potential and the electric potential. For more infor-
mation about the formulation in Elmer see the modules MagnetoDynamics or MagnetoDynamics2D.

CSC – IT Center for Science

19. Circuits and Dynamics Solver 126

19.2.1 Component and Circuit network equations

The circuit equations are described as a general equation

Aẋ + Bx = f (19.3)

where x is the circuit variable vector, A and B are the coefficient matrices and f is the force vector. In Elmer
this equation can be described in the solver input file (SIF) in MATC language.
Circuit equations can be divided into two categories: 1) the component equations that determine the
behaviour of a component, and 2) the circuit network equations that determine the relationship between the
components (the Kirchhoff I and II laws).
The component equations are further divided into two subcategories: 1) the circuit element equations
that can be used to define ideal components (for example Ohm’s law), and 2) FE component equations that
are coupled to the finite element equations (related to the finite elements which belong to the corresponding
components). During the development of the CircuitsAndDynamics module a new section of keywords,
called "Component", was added. Within this section the user may control the component equation by spec-
ifying which bodies belong to the component and what formulation should be used with it, together with
specific component formulation input data (for example the number of turns).
The circuit network equations are further divided into two categories as well: 1) the Kirchhoff I law
that is the current conservation law (every node in the network graph must conserve the current), and 2) the
Kirchhoff II law that is the conservation of energy (the potential difference over every loop in the network
graph must be zero).
In Elmer the circuit equations are technically divided into two categories: 1) the automatically written
equations, and 2) the manually written equations. This is due to the fact that it is convenient to write the
FE component equations automatically once the formulation and its specific data are known while the rest
of the equations can be manually written without any difficulties. Note that the ideal components could be
automated as well (for example a resistor model); however such components do not exist at the moment and
the user needs to write those equations manually.
In the following sections three supported component formulations (massive, stranded, and foil winding)
are presented. The type of the formulation can be chosen in SIF via "Coil Type" keyword in the "Component"
section.

19.2.2 Massive coil

In some cases where the winding consists of only few turns the so-called massive inductor model [2] may
be used. Then the a-v formulation takes the following form: for all massive inductor indices jm (multiple
instances may exist in one computation)
X
(ν∇ × a, ∇ × a0 )Ω + (σ∂t a, a0 )Ωm + Vjm (σ∇v0i , a0 )Ωm = 0 (19.4)
i∈Γjm

and
(σ∂t a, ∇si )Ωm + Vjm (σ∇v0i , ∇si )Ωm = Ijm , (19.5)
where Ωm is the massive inductor domain, Γjm lists nodes on the electrode boundaries, Vjm is the voltage
and Ijm is the total current through the electrodes.
The source electric potential v0i can be precomputed with an electrokinetic formulation (the Poisson
equation) by setting it 1 at the positive electrode boundary and 0 at the negative boundary. If the electroki-
netic solver is not executed, then the reduced support is used.

19.2.3 Stranded coil

In the case of a coil with a small diameter wire that is densely packed, a stranded model could be used. The
main line of models takes the form [3]: for all stranded inductor index numbers js

(ν∇ × a, ∇ × a0 )Ω + Ijs (j s,js , a0 )Ωs = 0 (19.6)

CSC – IT Center for Science

19. Circuits and Dynamics Solver 127

and
(∂t a, j s,js )Ωs + Ijs (σ −1 j s,js , j s,js )Ωs = Vjs , (19.7)
where Ijs is the total current in the coil and Vjs is the voltage in the coil. This is the preferred method for
defining the component equation for the so-called classical stranded inductor model [7, p. 286], but the
resistance of the coil can also be given explicitly [6, 5]. The classical model yields
Z
∂t a · w dΩs + RIjs = Vjs , (19.8)
Ωs

where w is the wire density vector and R is the resistance of the coil.

19.2.4 Foil winding model

In the case of a foil winding with a small layer thickness that is densely packed, a foil winding model could
be used. It takes the following form [4, 1]: for all foil winding index numbers jf
X
(ν∇ × a, ∇ × a0 )Ω + (σ∂t a, a0 )Ωf + (σVjf (α)∇v0i , a0 )Ωf = 0 (19.9)
i∈Γjf

and Z
Njf
(σ∂t a, V 0 (α)∇si )Ωf + (σVjf (α)∇v0i , V 0 (α)∇v 0 )Ωf = Ij V 0 (α) dα, (19.10)
Ljf f Ωα,jf

where Ωf is the foil winding domain, Γjf lists the nodes on the electrode boundaries, Vjf is the voltage and
Ijf is the total current through the electrodes.

19.3 Keywords
The circuits and dynamics solver adds the circuit equations to the system matrix of the WhitneySolver or the
MagnetoDynamics2D solver. Keywords are needed to both of these solvers.

19.3.1 CircuitsAndDynamics solver

Solver solver id
Equation String Circuits
Procedure File "CircuitsAndDynamics" "CircuitsAndDynamics"
The procedure which includes the addition of circuit equations to the linear system of Magneto-
Dynamics and MagnetoDynamics2D solvers.
No Matrix Logical True
This solver does not have it’s own matrix. It only operates on the matrices of the magnetody-
namics solvers.

Component component id
Master Bodies Integer body ids
Body ids of the bodies which constitute a circuit component.
Coil Type String type
If the circuit component is defined as a coil, it can be treated as a "stranded", "massive" or "foil
winding".
Resistance Real resistance
If the coil type is defined as stranded, then the resistance of the coil can explicitly be defined with
this keyword. In case this keyword is not given the resistance is computed by using the electric
conductivity of the associated body materials.

CSC – IT Center for Science

19. Circuits and Dynamics Solver 128

Electrode Area Real area

If the coil type is stranded and resistance is not explicitly given, then this keyword may be
given to specify the area of the coil terminal. This is then used to compute the Resistance
parameter of the coil. Note that if neither Resistance nor Electrode Area are given,
then the area of the terminal is automatically computed. However, at the moment this feature is
not yet working in 3D.
Body Force 1
Source Name Real value
The circuit definitions may be used to give a freely chosen name to a source associated with a
circuit component. For example, if the name "Source Name" is used, this command can then
be used to specify the source (function).

19.3.2 CircuitsAndDynamics output

This solver saves the results of all the variables that belong to the CircuitsAndDynamics solver, namely the
currents and voltages of components (also those variables that are defined by the user). These can then be
saved into a text file by using the SaveData solver.
Simulation
Max Output Level Integer Level
This determines what is shown on the standard output. Level 3 shows some information about
what is happening during the execution, Level 8 shows component variable results and Level 10
shows all the Circuit Variable results. All these variables are stored even if they are not shown in
the standard output. The stored variables can be saved with the SaveData routine.
Solver solver id

Equation String Circuits Output

Procedure File "CircuitsAndDynamics" "CircuitsOutput"
The procedure which outputs the results of the added circuits (currents, voltages, resistances,
etc.).

19.3.3 Additional Keywords to the MagnetoDynamics or MagnetoDynamics2D solver

Solver solver id
Equation String WhitneySolver
Procedure File "MagnetoDynamics" "WhitneyAVSolver"
This is the WhitneySolver to whose system matrix the circuit equations are added. This proce-
dure could be MagnetoDynamics2D as well.
Export Lagrange Multiplier Logical True
The magnetodynamics solvers need this when circuit equations are added.

19.3.4 Circuit Definitions

The circuit definitions are written in MATC.

$ nof_circuits = 1
$ nof_variables = 6
$ Circuits = nof_circuits

$ !----- Circuit 1 ----

$ ! Define variable count and initialize circuit matrices

CSC – IT Center for Science

BIBLIOGRAPHY 129

$ C.1.variables = nof_variables
$ C.1.A = zeros(nof_variables, nof_variables)
$ C.1.B = zeros(nof_variables, nof_variables)
$ C.1.Mre = zeros(nof_variables, nof_variables)
$ C.1.Mim = zeros(nof_variables, nof_variables)
$ C.1.perm = zeros(nof_variables)

$ ! Define variables
$ C.1.name.1 = "var1"
$ C.1.name.2 = "var2"

$ ! Define component variables

$ C.1.name.3 = "i_component(1)"
$ C.1.name.4 = "v_component(1)"
$ C.1.name.5 = "i_component(2)"
$ C.1.name.6 = "v_component(2)"
! The number in the parenthesis refers to
! the component id that is defined in sif.

$ ! Define Sources:
$ C.1.B(0,0) = 1
$ C.1.source.1 = "Source Name"

Bibliography
[1] Patrick Dular and Christophe Geuzaine. Spatially dependent global quantities associated with 2-d and 3-
d magnetic vector potential formulations for foil winding modeling. IEEE trans. magn., 38(2):633–636,
March 2002.
[2] Patrick Dular, F. Henrotte, and W. Legros. A general and natural method to define circuit relations
associated with magnetic vector potential formulations. IEEE trans. magn., 35(3):1630–1633, May
1999.
[3] Patrick Dular, Nelson Sadowski, J.P.A. Bastos, and Willy Legros. Dual complete procedures to
take stranded inductors into account in magnetic vector potential formulations. IEEE trans. magn.,
36(4):1600–1605, July 2000.
[4] H. D. Gersem and K. Hameyer. A finite element model for foil winding simulation. IEEE trans. magn.,
37(5):3427–3432, September 2001.
[5] C. Golovanov, Y. Marechal, and G. Meunier. 3d edge element based formulation coupled to electric
circuits. IEEE trans. magn., 34(5):3162–3165, September 1998.
[6] P. J. Leonard and D. Rodger. Voltage forced coils for 3d finite element method electromagnetic model.
IEEE trans. magn., 24(5):2579–2581, September 1988.
[7] Gerard Meunier, editor. The Finite Element Method for Electromagnetic Modeling. iSTE and Wiley,
2008.
[8] Eelis Takala, Evren Yurtesen, Jan Westerholm, Juha Ruokolainen, and Tommi Peussa. Using reduced
support to enhance parallel strong scalability in 3d finite element magnetic vector potential formulations
with circuit equations. Electromagnetics, 36(6):400–408, August 2016.
[9] Eelis Takala, Evren Yurtesen, Jan Westerholm, Juha Ruokolainen, and Peter Råback. Parallel simula-
tions of inductive components with elmer finite element software in cluster environments. Electromag-
netics, 36(3):167–185, April 2016.

CSC – IT Center for Science

Model 20

Vectorial Helmholtz for Electromagnetic

Waves

Module name: VectorHelmholtz

Module subroutines: VectorHelmholtzSolver,VectorHelmholtzCalcFields
Module authors: Juhani Kataja, Juha Ruokolainen and Mika Malinen
Document authors: Juhani Kataja and Roman Szewczyk

20.1 Introduction
This module is aimed to solve the time-harmonic Maxwell equations in high-frequency regime so that the
curl-curl equation is valid.

20.2 Theory
The time-harmonic Maxwell equations (time factor e−iωt , ω = 2πf ) are given by

µ−1 curl E = iωH, (20.1)

curl H = −iωεE + J , (20.2)

where complex scalars µ = µ0 µr and ε = ε0 εr are the permeability and permittivity parameters of the
model, while E, H and J are electric field, magnetic field strength and impressed current distribution,
respectively. The quantities µ0 , ε0 are the permeability and permittivity of vacuum, and µr and εr are the
relative permeability and permittivity.
The elimination of H from the equations (20.1) and (20.2) gives

curl µ−1 curl E − ω 2 εE = iωJ (20.3)

over a computational domain Ω. The Dirichlet and Robin boundary conditions for (20.3) are

E × n =f × n on ΓE , (20.4)
n × curl E − αn × (n × E) = n × g × n on ΓZ , (20.5)

where the subsets ΓE and ΓZ cover the boundary ∂Ω of Ω, i.e., ∂Ω = ΓE ∪ ΓZ . Note that the Neumann
boundary condition is achieved by setting α = 0.

CSC – IT Center for Science

20. Vectorial Helmholtz for Electromagnetic Waves 131

The variational form of (20.3) is as follows:

Find E ∈ Hf,E (curl, Ω) such that

Z Z
(µ−1 curl E · curl v − ω 2 εE · v)dΩ − α µ−1 (E × n) · (v × n)dS
Ω ΓZ
Z Z
−1
=− µ (g × n) · (v × n)dS + iωJ · vdΩ ∀v ∈ H0,E (curl, Ω). (20.6)
ΓZ Ω

20.2.1 Boundary condition models

Leontovich impedance boundary. The Robin boundary condition (20.5) can be utilized to implement
impedance boundary approximation of well conducting medium by choosing

α = −iωµZp−1 and g = 0, (20.7)

where Zp is the surface impedance. Here Zp can be given, e.g., as

r
µc ω
Zp = (1 − i) , (20.8)
2σc
where σc and µc are the bulk conductivity and permeability of the wall [1].

First-order absorbing boundary condition. Now let the computational domain Ω be BR \ D, where
BR ⊂ R3 is an open ball of radius R and D ⊂ BR . Furthermore, suppose that ΓE ∪ ΓZ covers only ∂D,
while the first-order absorbing boundary condition on ∂BR is given by [2]
√
n × curl E = iω ε0 µ0 n × (n × E). (20.9)

This can be recovered with a Robin boundary on ∂BR , with

√
α = iω ε0 µ0 and g = 0. (20.10)

Port feed. Suppose a guided wave E p propagates along the positive z-axis with propagation constant β.
Furthermore, suppose that E p is the only propagating mode at the chosen frequency. The port feed model
can be implemented with the Robin boundary condition by choosing

α = iβ and g = 2iβn × E p × n. (20.11)

Surface potential. The differential of a scalar potential φ defined on a boundary can be used to generate
g as
g = (∂α φ)aα (20.12)
where aα give the dual basis of coordinate basis vectors aα on the surface, so that
Z Z
−1
µ (g × n) · (v × n)dS = µ−1 ((∂α φ)aα × n) · (v × n)dS.
ΓZ ΓZ

20.3 Keywords
Constants
The keywords of this section are used to change the values of natural constants.
Permittivity of Vacuum Real
The permittivity of vacuum ε0 , defaulting to 8.854187817 · 10−12 C
Vm .
Permeability of Vacuum Real
The permeability of vacuum µ0 , defaulting to 4π · 10−7 Vs
Am .

CSC – IT Center for Science

20. Vectorial Helmholtz for Electromagnetic Waves 132

Material material id
The material parameters εr and µ−1
r are defined in this section.

Relative Permittivity Real

The real part of relative permittivity εr .
Relative Permittivity im Real
The imaginary part of relative permittivity εr .
Relative Reluctivity Real
The real part of µ−1
r .
Relative Reluctivity im Real
The imaginary part of µ−1
r .

Keywords for VectorHelmholtzSolver

Solver solver id
The solver section defines equation solver control variables. Most of the possible keywords – related
to linear algebra (starting with Linear System), for example – are common for all the solvers and
are explained elsewhere.
Equation String
A string identifying the solver. This can be changed but it must be given. Example:
VectorHelmholtzSolver
Procedure File "VectorHelmholtz" "VectorHelmholtzSolver"
The name of the solver subroutine.
Variable String
The identifier for the field variable to be solved. Real and imaginary parts must be provided, cf.
the default value E[E re:1 E im:1].
Angular Frequency Real
The angular frequency ω.
Use Piola Transform Logical
Utilize modern Piola transformed edge finite elements. This increases the number of DOFs on
meshes containing quadrilateral element faces. If the mesh contains elements that are not affine
images of the reference element, then this option should be enabled.
Linear System Preconditioning Damp Coefficient Real
If present, the preconditioner is constructed from a damped system matrix A + κ(S − M + B),
where A is the original total system matrix, S is the stiffness matrix containing the curl terms, M
is the scaled mass matrix, B is the matrix arising from boundary integrals and κ is the damping
coefficient.
Linear System Preconditioning Damp Coefficient im Real
The imaginary part of the damping coefficient κ.
Lossless cavity models usually benefit from shifted preconditioning. Utilizing BiCGStab(l) with the
ILU(0) or Vanka preconditioner and choosing damping coefficient κ = i is likely to result in a con-
vergent iteration.
Body Force bf id
The impressed current J is specified in the Body Force section.
Current Density i Real
The i:th component of the real part of the current density J .
Current Density im i Real
The i:th component of the imaginary part of the current density J .
Boundary Condition bc id

CSC – IT Center for Science

20. Vectorial Helmholtz for Electromagnetic Waves 133

E re {e} i Real
The real part of the component data fi to evaluate DOFs corresponding to the edge basis func-
tions.
E im {e} i Real
The imaginary part of the component data fi to evaluate DOFs corresponding to the edge basis
functions.
Electric Robin Coefficient Real
Real part of α.
Electric Robin Coefficient im Real
Imaginary part of α.
Magnetic Boundary Load i Real
The i:th component of the real part of g × n.
Magnetic Boundary Load i im Real
The i:th component of the imaginary part of g × n.
TEM Potential Real
This can be used to define the real part of the scalar potential φ to calculate g.
TEM Potential im Real
This can be used to define the imaginary part of the scalar potential φ to calculate g.

Keywords for VectorHelmholtzCalcFields

Solver solver id
Unique id for the solver.
Equation String
A string identifying the solver.
Procedure File "VectorHelmholtz" "VectorHelmholtzCalcFields"
The name of the postprocessing subroutine.
Angular Frequency Real
The angular frequency ω.
Calculate Elemental Fields Logical
Calculate elementwise constant approximations of the fields. Useful for discontinuous material
parameters.
Calculate Magnetic Flux Density Logical
Output the magnetic flux density B = −i/ω curl E.
Calculate Magnetic Field Strength Logical
Output the magnetic field strength H = µ−1 B.
Calculate Electric field Logical
Output the electric field E.
Calculate Poynting Vector Logical
Output the Poynting vector 21 E × H ∗ .
Calculate Div of Poynting Vector Logical
Output the divergence of Poynting vector
1 1 1
∇ · E × H ∗ = iω (µH · H ∗ + E · (εE)∗ ) − E · J ∗
2 2 2
and also generate the result variable Electric Work corresponding to the term 1/2E · J ∗
above.
Calculate Energy Functional Logical
Evaluate the left-hand side of (20.6) with the discrete field solution.

CSC – IT Center for Science

BIBLIOGRAPHY 134

Bibliography
[1] J.D. Jackson. Classical Electrodynamics. John Wiley & Sons, third edition, 1999.
[2] A.F. Peterson. Absorbing boundary conditions for the vector wave equation. Microwave and Optical
Technology Letters, 1(2):62–64, 1988.

CSC – IT Center for Science

Model 21

Electromagnetic Waves

Module name: EMWaveSolver

Module subroutines: EMWaveSolver, EMWaveCalcFields
◦
Module authors: Juhani Kataja, Peter Raback, Juha Ruokolainen and Mika Malinen
Document authors: Mika Malinen

21.1 Introduction
The module described here is aimed at solving the time-dependent electromagnetic wave equation derived
from Maxwell’s equations. Here the unknown field is approximated by using vector-valued (edge) finite
elements.

21.2 Theory
By assuming time-independent material parameters, the electromagnetic wave equation may be written as
∂2E ∂E ∂J E
curl µ−1 curl E + ε +σ =− (21.1)
∂t2 ∂t ∂t
where µ = µ0 µr and ε = ε0 εr are the permeability and permittivity, E is the electric field and J E is an
impressed current density. The quantities µ0 and ε0 are the permeability and permittivity of vacuum, and µr
and εr are the relative permeability and relative permittivity; respectively.
The Dirichlet and Robin-like boundary conditions for (21.1) are
E × n = f × n on ΓE , (21.2)
∂E
n × curl E + αn × (n × ) = g on ΓZ , (21.3)
∂t
where ΓE and ΓZ give a partitioning of the boundary ∂Ω of the computational domain Ω such that ∂Ω =
ΓE ∪ ΓZ . Note that the Neumann boundary condition is achieved by setting α = 0. An absorbing boundary
condition can be created by choosing
√
α = ε0 µ0 . (21.4)
To obtain the variational formulation of (21.1) integration by parts is carried out. After using (21.3) we
then come to the weak form
∂2E
Z Z
∂E ∂E
(µ−1 curl E · curl v + ε 2 · v + σ · v)dΩ + α µ−1 ( × n) · (v × n)dS
Ω ∂t ∂t ΓZ ∂t
Z Z
=− µ−1 g · vdS − J˙E · vdΩ (21.5)
ΓZ Ω

which can be used to obtain the fully discrete equations.

CSC – IT Center for Science

21. Electromagnetic Waves 136

21.3 Keywords
Constants
The keywords of this section are used to change the values of natural constants.
Permittivity of Vacuum Real
The permittivity of vacuum ε0 , defaulting to 8.854187817 · 10−12 ( Vm
C
).
Permeability of Vacuum Real
The permeability of vacuum µ0 , defaulting to 4π · 10−7 ( Am
Vs
).
Material material id
The material parameters εr , µr and σ are defined in this section.
Relative Permittivity Real
This defines the value of the relative permittivity εr .
Relative Permeability Real
This defines the value of µr .
Electric Conductivity Real
This defines the value of σ.

Keywords for EMWaveSolver

Solver solver id

Equation String
This gives a name for referring to this solver definition.
Procedure File "EMWaveSolver" "EMWaveSolver"
This is used to identify the solver subroutine.
Variable String
The name for the field variable to be solved. If this is not given, the solver defaults this to E.
Use Piola Transform Logical
Utilize modern Piola-transformed edge finite elements. This increases the number of DOFs on
meshes containing hexahedral and pyramidal elements. If the mesh contains elements that are
not affine images of the reference element, then this option should be enabled.
Quadratic Approximation Logical
This keyword can be used to switch to using vector-valued finite elements of second order.
Body Force bf id
The time derivative of the impressed current density J E can be specified in the Body Force section.
Current Density Rate i Real
The i:th component of the time derivative field J˙E .
Boundary Condition bc id
E {e} i Real
In the case of the default variable name this command defines a vector so that its tangential trace
f × n is approximated by E h × n, with E h the finite element interpolating function. The
value of this keyword defines the components of the vector with respect to the global Cartesian
coordinate system.
Electric Damping Coefficient Real
This specifies the value of the parameter α.
Magnetic Boundary Load i Real
The value of this keyword specifies the i:th component of g.

CSC – IT Center for Science

21. Electromagnetic Waves 137

Keywords for EMWaveCalcFields

A separate solver section can be written so as to create a postprocessed field Elfield which corresponds
to the computed solution and which can be used for visualization.
Solver solver id

Equation String
This gives a name for referring to this solver definition.
Procedure File "EMWaveSolver" "EMWaveCalcFields"
This is used to identify the name of the postprocessing subroutine.
Calculate Elemental Fields Logical
Calculate an elementwise fit for the primary solution. This is useful especially in cases where
material parameters have discontinuities.

CSC – IT Center for Science

Model 22

Computation of Magnetic Fields in 2D

Module name: MagnetoDynamics2D

Module subroutines: MagnetoDynamics2D, MagnetoDynamics2DHarmonic, BSolver
Module authors: Juha Ruokolainen, Eelis Takala, Mika Malinen, Peter Råback
Document authors: Peter Råback, Mika Malinen

22.1 Introduction
This module may be used to solve a version of the Maxwell equations in 2D special cases (including axially
symmetric problems) when the unknown is the z-component (or φ-component) of the vector potential. In
contrast to the 3D version of the magnetodynamics solver described earlier, the standard Lagrange interpola-
tion is here applied. In addition to performing the computations in the time domain, the analogous version of
the equations may also be solved in the frequency domain. Furthermore, an additional solver may be called
to produce derived fields (for example the magnetic flux density) from the computed vector potential. Also
Joule losses may be computed for harmonic fields.

22.2 Theory
When the current density acts in a direction orthogonal to the plane considered, the scalar potential need
not be considered as an unknown in the A-V formulation of Maxwell’s equations. In the case of Cartesian
coordinates the system is then fully described by the vector potential A ≡ A3 (x1 , x2 )e3 as

∂A3 1
σ e3 + curl( curl A3 e3 ) − σ(v × curl A3 e3 ) = J3 e3 + curl M (22.1)
∂t µ
where J3 e3 is the electric current density and the magnetization current is expressed in terms of a planar
magnetization vector M = M1 e1 + M2 e2 . In addition, v is an optional velocity field describing a motion
of a body. It should be noted that if the motion is modelled via performing a rigid motion of the previous
mesh into the current configuration, the effect of motion may be incorporated in the total time derivative and
v need not be specified explicitly; cf. the discussion in connection with the 3D equations.
When cylindrical coordinates (r, φ, z) are employed, the curl of the vector potential A ≡ Aφ (r, z)eφ
has components (−∂z Aφ , 0, ∂r Aφ + Aφ /r) with respect to the orthonormal basis {er , eφ , ez }. The field
equation is then given by

∂Aφ 1
σ eφ + curl( curl Aφ eφ ) − σ(v × curl A3 e3 ) = Jφ eφ + curl M , (22.2)
∂t µ
with the magnetization vector being M = Mr er + Mz ez .

CSC – IT Center for Science

22. Computation of Magnetic Fields in 2D 139

∂
The harmonic version of the equation is obtained by replacing the operator ∂t by multiplication with iω
and solving the vector potential as a complex-valued field. In the case of a harmonic problem described in
terms of Cartesian coordinates the Joule heat generation in stationary conductors may be computed from
1 2
h= σω |A3 |2 .
2
As the electric conductivity σ may be discontinuous over material boundaries, it is attractive to compute a
field without it and carry out the multiplication within the heat solver where the source term is needed.

22.2.1 Boundary Conditions

The Dirichlet boundary condition for A3 is simply

A3 = Ab3 . (22.3)

Since we now have

curl A3 e3 × n = (∇A3 · n)e3 ,
natural boundary conditions of the type
1 ∂A3
=g (22.4)
µ ∂n
may be used as an alternative. It may be difficult to extend the Dirichlet conditions far enough. Then a
spherically symmetric far-field approximation may be used. This gives a boundary condition of Robin kind
which corresponds to the choice
1 r·n
g = A3 (22.5)
µ |r|2
in (22.4). If no boundary conditions are specified, the natural boundary condition with g = 0 prevails.

22.3 Keywords
Keywords for MagnetoDynamics2D
Here we list the keywords that are relevant when utilizing the module MagnetoDynamics2D and that
may also be common to the other solvers. Such common keywords relate to specifying material parameters,
body forces, and boundary conditions.

Constants
Permeability of Vacuum Real
This constant has the default value 4π · 10−7 in SI units. In different unit system change this
accordingly.

Material mat id
The following material parameters may be used by all the solvers in the module.

Electric Conductivity Real

This keyword is used to specify the electric conductivity σ.
Relative Permeability Real
If this keyword is used, the permeability µ can be specified in terms of the permeability of
vacuum. To obtain the permeability, the value of this keyword is then internally multiplied with
the permeability of vacuum. Instead of using this keyword, the keywords Permeability or
Reluctivity may be used.
Permeability Real
This keyword may be used to specify directly the permeability µ.

CSC – IT Center for Science

22. Computation of Magnetic Fields in 2D 140

Reluctivity Real
The value of this keyword specifies the reluctivity ν. The permeability is then taken to be µ =
1/ν.
Magnetization i Real
The components of the magnetization vector, i = 1, 2.
H-B Curve Cubic Real
The H-B curve must be given as a cubic spline. This enables that the derivative of the curve is
computed analytically from the spline coefficients.

Solver solver id
Equation String MgDyn2D
This keyword gives a describing name for the discrete model handled by this solver. The name
can be changed as long as it is used consistently.
Procedure File "MagnetoDynamics2D" "MagnetoDynamics2D"
This declaration specifies the name of the solver subroutine.
Variable String Potential
The name of the variable may be freely chosen provided it is used consistently also elsewhere.
The associated number of degrees of freedom should always be one.
Nonlinear System Max Iterations Integer
If the material laws are nonlinear, the equation may need some iterations before reaching the
solution. This keyword gives the maximum number of iterations. The default is one. If a
nonlinear H-B curve is given, then Newton’s linearization is applied after the first iteration.
Nonlinear System Convergence Tolerance Real
This keyword gives the convergence tolerance for the nonlinear iteration.
Body Force bf id
In the body force section the user may give various volume sources.

Current Density Real

This keyword is used to specify the current density in the z/φ-direction.
Lorentz Velocity i Real
This keyword may be used to define the optional velocity v.

Boundary Condition bc id
Potential Real
If the variable is given the name Potential, this keyword can be used to specify the Dirichlet
condition for the vector potential.
Infinity BC Logical
Sets far-field conditions for the vector potential assuming spherical symmetry at distance.
Mortar BC Integer
This enforces continuity in the case of rotating boundary conditions by the mortar finite element
method.

Keywords for MagnetodDynamics2DHarmonic

Here only the additional keywords related to the harmonic solver are listed. For other keywords see the
definitions above.
Material mat id
Electric Conductivity im Real
The imaginary part of the electric conductivity.

CSC – IT Center for Science

22. Computation of Magnetic Fields in 2D 141

Magnetization i Im Real
The imaginary components of the magnetization vector, i = 1, 2.
Solver solver id
Equation String MgDyn2DHarmonic
A name for the solver.
Procedure File "MagnetoDynamics2D" "MagnetoDynamics2DHarmonic"
This declaration specifies the name of the solver subroutine.
Variable String Potential[Potential Re:1 Potential Im:1]
The name of the variable may be freely chosen provided it is used consistently also elsewhere.
The associated number of degrees of freedom should always be two.
Body Force bf id
Current Density Im Real
This keyword is used to specify the imaginary part of the current density.

Keywords for BSolver

An additional solver may finally be called to compute derived fields. Note: The subroutine BSolver
described here is obsolete. It is recommended that the subroutine MagnetoDynamicsCalcFields
within the module MagnetoDynamics is used for postprocessing.
Solver solver id
The postprocessing solver currently only solves for the magnetic field density. The size of the re-
quested vector field is 2 when the target variable is real-valued and 4 if it is complex-valued. The user
does not need to specify the output fields.

Equation String BSolver

A describing name for the solver is given. This can be changed as long as it is used consistently.
Procedure File "MagnetoDynamics2D" "BSolver"
The name of the solver subroutine is given.
Target Variable String
This keyword is used to specify the name of the underlying potential variable; the default is
Potential.
Discontinuous Galerkin Logical
The derived fields are discontinuous if the material properties has jumps. Therefore the visual-
izations are more appealing if the fields are allowed to be discontinuous. Setting this flag True
activates discontinuous Galerkin (DG) computation of the fields. Note that these fields are com-
patible only with certain postprocessing practices. One possible way is to use vtu output and
ask elemental fields for saving, such as Vector Field Elemental 1.
Average Within Materials Logical
If DG formulation for the fields is asked, this enforces averaging of the fields within materials.
Calculate Joule Heating Logical [True]
The automatic computation of the Joule heating may be turned on by this keyword. The default
is False. The keyword is only applicable for the harmonic case. The computation results to
two additional variables. Joule Heating gives the absolute heating and Joule Field the
field that gives the heating when multiplied by the electric conductivity. This may be needed if
the electric conductivity is discontinuous making also the heating power discontinuous.
Desired Heating Power Real
A constant that gives the desired total heating power in Watts. If the keyword is active, then the
Joule Heating and Joule Field are multiplied by the ratio of the desired and computed
heating powers.

CSC – IT Center for Science

Model 23

Magnetic Induction Equation

Module name: MagneticSolve

Module subroutines: MagneticSolver
Module authors: Juha Ruokolainen
Document authors: Ville Savolainen, Antti Pursula

23.1 Introduction
The magnetic induction equation describes interaction of a conducting liquid or gas with applied and induced
magnetic fields in the low-frequency domain. The induction equation for the magnetic flux density is always
coupled to the Navier-Stokes equation for the movement of the fluid. The magnetic field, in turn, causes the
Lorentz force in the Navier-Stokes equation. The fluid is typically hot, and the Navier-Stokes equation is
often coupled also to the heat equation.
The induction equation solver can also be used in a body without a moving fluid, i.e., when ~v = 0 and the
Navier-Stokes equation is not solved. In this case, the problem belongs to the field of magneto-quasistatics.

23.2 Theory
The magnetic induction equation may be derived from Maxwell’s equations, with the displacement current
in Ampère’s law neglected, and the Ohm’s law for conducting fluids, ~ = σ(E ~ +~v × B).
~ This approximation
for the behavior of electromagnetic fields in conducting, moving fluids is called magnetohydrodynamics.
The magnetic induction equation is given by
~
∂B 1
+ ~ − ∇ × (~v × B)
∇×∇×B ~ = 0, (23.1)
∂t σµ
where σ is the electric conductivity and µ the magnetic permeability of the material. These must be
specified by using the keywords Electric Conductivity and Magnetic Permeability in the
Material section.
The force term induced by the magnetic field for the flow momentum equations is given by

f~m = ~ × B,
~ (23.2)

and the Joule heating in the heat equation by

1 2
hm = |~| , (23.3)
σ
~ These body forces are specified
where ~ is the current density, calculated from the Ampère’s law ~ = ∇ × H.
by the keywords Lorentz Force and Joule Heat.

CSC – IT Center for Science

23. Magnetic Induction Equation 143

The magnetic field can also be divided into external, or applied, and induced field, B ~ =B ~e + B
~ i . The
external magnetic field B ~ is created by permanent magnets or currents outside the fluid. The external field
e

may be given to the induction equation solver either from a restart file, e.g., as calculated by the magnetostatic
solver, or defined via the sif file’s keywords Applied Magnetic Field 1, 2 and 3. If the restart file
is used, the components of B ~ e are read from the variables named magnetic flux density 1, 2 and
3. If both methods are used, the two applied fields are summed together. It is assumed that the sources of the
external field are outside the flow region, i.e., ∇ × B~ e = 0, and that the time derivative of the external field
can be ignored. The time derivative ∂ B ~ /∂t can, however, be specified directly by the keywords Magnetic
e

Bodyforce 1, 2 and 3. The induction equation solver gives the components of the induced magnetic field
B~ i.
Both transient and steady-state solvers for the magnetohydrodynamical system (induction, Navier-Stokes
and heat equations) are available. The magnetostatic and time-harmonic solvers for the external magnetic
field are described elsewhere in the Models Manual. In some cases it is also possible that the velocity is a
priori known, for example when studying induction in a rotating body. Then a user defined velocity can be
used instead of computing the velocity from Navier-Stokes equations.
Currently the induction equation can be solved in a cylindrically symmetric or a general three-dimensional
formulation.

23.2.1 Boundary Conditions

For the induction equation one can apply either Dirichlet or natural boundary conditions. In both cases, one
must check that the computational domain is extended far enough to avoid numerical errors. For this reason,
it is possible to solve the magneto-quasistatics problem in an adjacent body.
The Dirichlet boundary condition for a component of the induced magnetic field Bi (we have dropped
now the superscript i that marked the induced field) is
Bi = Bib . (23.4)
Bib can be a constant or a function of time, position or other variables. The keywords for the Dirichlet
boundary conditions are Magnetic Field 1, 2 and 3.
In the cylindrically symmetric case, the Dirichlet boundary condition for the azimuthal component Bφ
is in the same units as for the other two components, i.e., in T, and not for a contravariant component. On
the symmetry axis one has to set Br = 0 and Bφ = 0, and ∂Bz /∂r = 0 is applied implicitly.
If no Dirichlet condition is specified, natural boundary condition is applied.

23.3 Keywords
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere.
Equation String [Magnetic Induction]
The name of the equation. It is also possible to use this solver as external procedure. Then the
name of the equation must not be the above (use e.g. Magnetic Field Solver). Also the
following four keywords have to be added with the values give here.
Procedure File "MagneticSolve" "MagneticSolver"
Variable String Magnetic Field
Variable DOFs Integer 3
Exported Variable 1 = -dofs 3 electric current
The above four keywords are to be given only when using the solver as an external procedure.
Nonlinear System Convergence Tolerance Real
This keyword gives a criterion to terminate the nonlinear iteration after the relative change of the
norm of the field variable between two consecutive iterations k is small enough
~k − B
||B ~ k−1 || < ||B
~ k ||,

CSC – IT Center for Science

23. Magnetic Induction Equation 144

where  is the value given with this keyword.

Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations the solver is allowed to do. If neither the material
parameters nor the boundary conditions are functions of the solution, the problem is linear, and
this should be set to 1.
Nonlinear System Relaxation Factor Real
Giving this keyword triggers the use of relaxation in the nonlinear equation solver. Using a
factor below unity is sometimes required to achieve convergence of the nonlinear system. A
factor above unity might speed up the convergence. Relaxed variable is defined as follows:

~ 0 = λB
B ~ k + (1 − λ)B
~ k−1 ,

where λ is the factor given with this keyword. The default value for the relaxation factor is unity.
Steady State Convergence Tolerance Real
With this keyword a equation specific steady state or coupled system convergence tolerance is
given. All the active equation solvers must meet their own tolerances for their variable u, before
the whole system is deemed converged. The tolerance criterion is:

||ui − ui−1 || < ||ui ||,

where  is the value given with this keyword.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:

Magnetic Induction Logical

If set to True, solve the magnetic induction equation.
User Defined Velocity Logical
Controls whether the velocity is given by the user or computed by another solver. Default value
is False, which means that velocity solution of Navier-Stokes equations is used.
Navier-Stokes Logical
If set to True, solve also the Navier-Stokes equations. For magnetohydrodynamics, this is done,
except when the computational region for the magnetic field is extended beyond the fluid.
Heat Equation Logical
If set to True, solve also the heat equation.

Body Force bf id
The body force section may be used to give additional force terms for the equations.
Lorentz Force Logical
If set true, triggers the magnetic field force for the flow momentum equations.
Joule Heat Logical
If set true, the Joule heating is added in the heat equation.
Magnetic Bodyforce i Real
This keyword can be used to specify explicitly the time dependence of the external field, i.e., the
term −∂ B~ e /∂t. This is especially useful for time-harmonic fields, where the time derivative can
be calculated and expressed easily.

Initial Condition ic id
The initial condition section may be used to set initial values for the field variables. The following
variables are active:
Magnetic Field i Real
For each magnetic flux density component i= 1, 2, 3.

CSC – IT Center for Science

23. Magnetic Induction Equation 145

Material mat id
The material section is used to give the material parameter values. The following material parameters
may be set for the induction equation. They can be a constant or a function of a given variable.
Magnetic Permeability Real
The magnetic permeability is set with this keyword. For most fluids, the vacuum value for µ0
can be used, and the keyword set to 1.25664e-6.
Electric Conductivity Real
The value of the electric conductivity is set with the keyword. For example, for polythermal
flows the conductivity could be a function of the temperature.
Applied Magnetic Field i Real
This keyword can be used to specify the external field, or a part of it, and its contribution to the
~ e ). The field may be a function of, e.g., time or position.
term ∇ × (~v × B
MHD Velocity i Real
The user defined velocity can be given with these keywords with i=1,2,3.
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. The ones related to
induction equation are
Magnetic Field i Real
Dirichlet boundary condition for each magnetic flux density component i= 1, 2, 3.

CSC – IT Center for Science

Model 24

Reduced Dimensional Electrostatics

Module name: StatElecBoundary

Module subroutines: StatElecBoundaryForce, StatElecBoundaryEnergy,
StatElecBoundaryCharge, StatElecBoundarySpring
Module authors: Peter Råback
Document authors: Peter Råback

24.1 Introduction
In some applications the geometry is such that the 3D electrostatics may quite accurately be reduced to a 1D
problem. This is the case for nearly aligned planes. If the angle between the planes is ϕ (in radians) the error
of this approximation is roughly 2ϕ2 /3. Therefore we may use an analytical solution that results directly
from the distance of the planes that are in different potential. The ideal model may be further developed by
taking into account perforated structures and dielectric layers.

24.2 Theory
~ may
It is assumed here that the electric field is stationary in the time-scale under study. The electric field E
be expressed with an electric scalar potential φ,
~ = ∇φ.
E (24.1)

If there are no free charges, the scalar potential may be solved from

− ∇ · ε∇φ = 0. (24.2)

When one dimension is much smaller than the other two we may assume that the field is one-dimensional.
Then the electric field resulting from potential difference Φ = ∆φ is

~ = E~n = Φ ~n,
E (24.3)
d
where ~n is the unit normal and d(~r) is the height of the aperture. The energy density per unit area is now,

1 2 εΦ2
e= εE d = . (24.4)
2 2d
which corresponds to a induced charge density on the surface
εΦ
q= . (24.5)
d

CSC – IT Center for Science

24. Reduced Dimensional Electrostatics 147

The force is obtained from the derivative of the energy,

∂e εΦ2
f= =− 2, (24.6)
∂d 2d
and the spring constant from the derivative of the force,

∂f εΦ2
k= = 3 , (24.7)
∂d d
The forces and spring constants are always aligned in the direction of the surface normal since any other
direction is incompatible with the original assumptions.

24.2.1 Electrostatics of perforated structures

If there are holes or other imperfections in the structure they may be homogenized over the whole area. By
computing the electric energy and force in the presence and absence of holes we get correction factors

eholes = αeideal (24.8)

and
fholes = βfideal (24.9)
The correction terms may be precalculated for a given geometry. However, if the relative change in the
aperture is large the correction terms should be modeled in some manner. we would also like to have similar
expressions for the spring constant
kholes = γkideal . (24.10)
If we assume that eholes is proportional to 1/d then the following relations may easily be derived.

β = α − α0 d (24.11)

and
1
γ = α − α0 d + α00 d2 , (24.12)
2
where the derivation is done respect to d.
Now we are only left with the problem of finding a nice functional approximation for α. The holes in
the membrane may be expressed using three dimensionless variables d˜ = d/r, b̃ = b/r and R̃ = R/r. Here
r is the hole radius, b the hole depth, d the aperture and R the distance between holes. When R̃ >> 1 and
b >> 1 the correction depends only on d. ˜
Numerical computations suggest that the correction α(d) ˜ should approach unity as the distance d˜ ap-
proaches unity. On the other hand, it should approach 1 − q for small values of d. Here q is the area fraction
of the holes.
Numerical calculations suggest that a second order rational polynomial gives quite an accurate fit to the
computed results,
1
α(d) = 1 − q . (24.13)
1 + a1 d + a2 d2
Fully analytical formulas are now more tedious but the values for β and γ are easily calculated using the
derivatives
a1 + 2a2 d
α(d)0 = q , (24.14)
(1 + a1 d + a2 d2 )2
and
a2 − 2a21 − 3a1 a2 d − 3a22 d2
α(d)00 = 2q . (24.15)
(1 + a1 d + a2 d2 )3
Least squares fitting to the numerical computations suggest that for cylindrical hole a1 = 4.2523, a2 =
0.4133, for a rectangular slot a1 = 2.3198, a2 = 0.2284 and for a square hole a1 = 3.8434, a2 = 0.3148.
When fitting the model the suggested constant term diverged up to 4 % from unity but the value one was
enforced anyway because it has the nice limiting value properties.

CSC – IT Center for Science

24. Reduced Dimensional Electrostatics 148

24.2.2 Dielectric layer

If the conductor is covered with a dielectric layer we need to modify the equations. We assume that the
aperture consists of two materials with permittivities ε1 and ε2 and thicknesses d1 and d2 . Because the flux
must be the same this means that the fields are
Φ
E1 = (24.16)
d1 + ε1 d2 /ε2

and
Φ
E2 = . (24.17)
ε2 d1 /ε1 + d2
Defining dx = d1 + ε1 d2 /ε2 these become
Φ
E1 = (24.18)
dx
and
ε1 Φ
E2 = . (24.19)
ε2 dx
The total energy density is then

1 d1 1 ε21 2 d2 ε 1 Φ2
e= ε 1 Φ2 2 + Φ 2 = . (24.20)
2 dx 2 ε2 dx 2dx

We assume that the resonator moves so that d1 changes and d2 remains constant. Then the force density is

∂e ∂e ∂dx ε1 Φ2
f= = =− 2 . (24.21)
∂d1 ∂dx ∂d1 2dx

And similarly the spring constant density

∂f ε1 Φ2
k= = 3 . (24.22)
∂d1 dx

These expressions may be used inside the integral instead of the constant field values to account for the
dielectric layer. It may be noted that the equations are exactly the same as for the case without the layer
except that the aperture d is replaced with the efficient aperture dx = d1 + ε1 d2 /ε2 .

24.3 Implementation issues

This module is not a solver in itself. It only provides boundary conditions for real models. Natural models
to combine with these boundary conditions are models describing deformation in solid structures. For plates
the conditions are applied to the leading dimension while for generic 3D solids the conditions are applied
to the boundaries. Therefore the same subroutines may be applied to either boundary or to material section.
There is actually just one subroutine and the value it returns is defined by the name of the routine used to
call it.
These routines here were historically developed for MEMS modeling in a different setting and were
much later added to the open source publication as a lighter version.

24.4 Keywords
Constants
Permittivity Of Vacuum Real [8.8542d-12]
The default is given in SI units. In other units the constant should be changed appropriately.
Boundary Condition bd id

CSC – IT Center for Science

24. Reduced Dimensional Electrostatics 149

Procedure "StatElecBoundary" "StatElecBoundaryForce"

Function that returns the nodal force density.
Procedure "StatElecBoundary" "StatElecBoundaryCharge"
Function that returns the nodal charge density.
Procedure "StatElecBoundary" "StatElecBoundaryEnergy"
Function that returns the nodal energy density.
Procedure "StatElecBoundary" "StatElecBoundarySpring"
Function that returns the nodal spring density.
Gap Height Real
Distance on which the 1D electrostatic model is applied for. May depend on displacement, for
example, via MATC functions.
Potential Difference Real
Potential difference between the plates.
Relative Permittivity Real
Relative permittivity of the material between the plates.
Layer Thickness Real
There may be a non-conducting layer on top of the plate. If this keyword is not defined no layer
is assumed.
Layer Permittivity Real
Relative permittivity of the layer.
Hole Type String [slot / round / square]
The 1D electrostatics can account also for perforated structures if the depth of the hole is large
compared to the width of the hole. The different hole geometries are an infinite slot, a round hole
and a square hole.
Hole Size Real
The size of the hole is for a round hole the radius, for a square half the side and for a slot half of
the width.
Hole Fraction Real
The fraction of the holes on the surface.
Hole Depth Real
The depth of the holes i.e. also the thickness of the perforated plate.

CSC – IT Center for Science

Model 25

Poisson-Boltzmann Equation

Module name: PoissonBoltzmannSolve

Module subroutines: PoissonBoltzmannSolve
Module authors: Peter Råback
Document authors: Peter Råback

25.1 Introduction
The macroscopic electromagnetic theory is governed by Maxwell’s equations. In steady state the electric
field may usually be solved from a simple Poisson equation. However, if there are free charges in the domain
that are affected by the electric field the equation is no longer valid. Also the contribution of the free charges
need to be taken into consideration. If the electrostatic force is the only force affecting the distribution of
the electric charges then the potential in the steady-state is given by the Poisson-Boltzmann equation [1].
This equation may find its use in microfluidics and electrochemical applications. Note that if the charge
distribution is affected by the flow distribution of the carrier fluid this equation is no longer valid.

25.2 Theory
The electrostatic equation for the electric potential φ yields,

− ∇ · ε∇φ = ρ, (25.1)

where ε is the permittivity of the medium and ρ is the charge density. Assuming that there is a fixed charge
density and both positive or negative moving ions the charge may be written as

ρ = ρ0 + e(z − n− + z + n+ ) (25.2)

where ρ0 is interior charge distribution of fixed positions of all solute charges, and e is the unit charge of a
electron, and z is the charge number of the positive or negative ions, and n is the corresponding ion density.
The electrochemical potential µ of the ions is defined by µ = ezφ + kB T ln n, where the first term is the
electrostatic contribution and the second term comes from the entropy of the ions at the weak solution limit.
In equilibrium µi is constant over the whole domain and thus the ion density obeys a Boltzmann distribution,

n = n0 e−ezφ/kB T (25.3)

where kB is the Boltzmann constant. Inserting this to the Poisson equation we obtain the Poisson-Boltzmann
equation that determines the potential field self-consistently,
− +
− ∇ · ε∇φ = ρ0 + ez − n−
0e
−ez φ/kB T
+ ez + n+
0e
−ez φ/kB T
. (25.4)

CSC – IT Center for Science

25. Poisson-Boltzmann Equation 151

A special case of the equation is obtained if the charge numbers and the concentrations are equal, z =
−z − = z + and n0 = n− +
0 = n0 . Then the equation simplifies to

− ∇ · ε∇φ = ρ0 − 2ezn0 sinh(ezφ/kB T ). (25.5)

The Poisson-Boltzmann equation is obviously nonlinear. We will show the iterative procedure only for this
case, the generic case is dealt similarly.

25.2.1 Iteration scheme

Defining α = 2ezn0 and β = ez/kB T the Poisson-Boltzmann equation for a symmetric electrolyte may be
written as
− ∇ · ε∇φ = ρ0 − α sinh(βφ). (25.6)
The straight-forward iterative procedure treats only the left-hand-side of the equation in an implicit manner,
− ∇ · ε∇φ(n+1) = ρ0 − α sinh(βφ(n) ). (25.7)
The convergence of this scheme is, however, quite poor for many cases of practical interest. An improved
strategy should linearize also the right-hand-side.
Making a Taylor’s expansion we may approximate
sinh(βφ(n+1) ) ≈ sinh(βφ(n) ) + β cosh(βφ(n) )(φ(n+1) − φ(n) ) (25.8)
which results to the Newton iteration scheme
h i
−∇ · ε∇ + αβ cosh(βφ(n) ) φ(n+1)
= ρ0 − α sinh(βφ(n) ) + αβ cosh(βφ(n) )φ(n) . (25.9)
This scheme has good convergence properties and is usually the method of choice.

25.2.2 Boundary conditions

For electric potential either Dirichlet or Neumann boundary condition can be used. The Dirichlet boundary
condition gives the value of the potential on specified boundaries. The Neumann boundary condition is used
to give a flux condition on specified boundaries
σ = ε∇φ · ~n, (25.10)
where σ is the surface charge density.

25.2.3 Derived quanties

When the potential has been solved the electric field may be obtained as a postprocessing step from
~ = −∇φ.
E (25.11)
Charge density may be obtained as the right-hand-side of the Poisson equation,
− +
ρ = ρ0 + ez − n−
0e
−ez φ/kB T
+ ez + n+
0e
−ez φ/kB T
. (25.12)
which in symmetric case yields,
ρ = ρ0 − 2ezn0 sinh(ezφ/kB T ). (25.13)
The energy density of the field ay be computed from
1~ ~ 1
e= E · D = ε(∇φ)2 . (25.14)
2 2
However, in a more generic treatment also the contribution of the concentration should be included in the
expression of the energy.

CSC – IT Center for Science

25. Poisson-Boltzmann Equation 152

25.3 Notes on output control

The user can control which derived quantities (i.e. electric field and electric energy) are calculated.
There are also available two choices of visualization types for the derived quantities. The node values
can be calculated by taking the average of the derived values on neighboring elements (constant weights).
This results often in visually good images. The other possible choice is to weight the average with the size of
the elements, which is more accurate and should be used when some other variable depends on these derived
values. The latter choice is also the default.

25.4 Keywords
Constants

Permittivity Of Vacuum Real [8.8542e-12 C2 /Nm2 ]

Boltzmann Constant Real [1.3807e-23 J/K]
Unit Charge Real [1.602e-19 C]
Equation equation id

Calculate Electric Energy Logical [False]

Controls whether the electric energy density is written in results files (default False).
Solver solver id
Equation String Poisson Boltzmann Solver
Variable String Potential
This may be of any name as far as it is used consistently also elsewhere.
Variable DOFs Integer 1
Degrees of freedom for the potential.
Procedure File PoissonBoltzmannSolve PoissonBoltzmannSolve
Following are listed three keywords with default values for output control.
Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations.
Nonlinear System Convergence Tolerance Real
The relative error after which the iteration is terminated.
Nonlinear System Newton After Iterations Integer
The number of iterations after which Newton iteration is turned on. The default is zero which
should usually be optimal.
Nonlinear System Newton After Tolerance Real
Optional parameter which gives the tolerance in error after which Newton iteration is turned on.
Calculate Electric Field Logical [True]
Calculate Electric Flux Logical [True]
Constant Weights Logical [True]
Used to turn constant weighting on for the results.
Material mat id

Relative Permittivity Real

The total permittivity is the product of the relative permittivity and the permittivity of vacuum.
Reference Temperature Real
This keyword is used to give the temperature occurring in the Boltzmann factor.

CSC – IT Center for Science

BIBLIOGRAPHY 153

Charge Number Integer

For symmetric cases the charge number. For unsymmetric cases one may give separately Positive
Charge Number and Negative Charge Number.
Ion Density Integer
For symmetric cases the original density of ions. For unsymmetric cases one may give separately
Positive Ion Density and Negative Ion Density.
An alternative set of parameters are also possible which are particularly suitable for testing purposes.
These are limited to the symmetric case where the potential normalized with the Zeta potential is
solved. Then the permittivities should be set to unity and only two variables are needed to define the
case.

Poisson Boltzmann Beta Real

This keyword gives the ratio of parameter β to the the Zeta potential.
Poisson Boltzmann Alpha Real
This keyword gives the parameter α

Body Force bodyforce id

Charge Density Real
The fixed charge distribution that is not affected by the electric field.
Boundary Condition bc id

Potential Real
Electric Flux BC Logical
Must be set to True if flux BC is used.
Surface Charge Real
Gives the surface charge for the Neumann boundary condition.

Bibliography
[1] D. Andelman. Handbook of Biological Physics, chapter 12. Electrostatic Properties of Membranes: The
Poisson-Boltzmann Theory. Elsevier Science, 1995.

CSC – IT Center for Science

Model 26

Loss Estimation Using the Fourier

Series

Module names: FourierLoss

Module subroutines: FourierLossSolver
◦
Module authors: Peter Raback, Mika Malinen
◦
Document authors: Mika Malinen, Peter Raback

26.1 Introduction
The primary motivation for this solver is the estimation of electromagnetic losses by using the Steinmetz
equation approach. It could have other uses as well. The main idea is to make a Fourier transformation on-
the-fly and compute losses that are proportional to the frequency always when full cycle has been completed.
Given an evolutionary finite element field
N
X
~ h (x, t) =
A ~j (x),
αj (t)ψ (26.1)
j=1

the solver enables to replace the evolution of the scalar degrees of freedom αj (t) for t ∈ [t0 , t0 + T ] by the
Fourier series approximation
K
X K
X
αj (t) ≈ a0j + akj cos[kω(t − t0 )] + bkj sin[kω(t − t0 )], (26.2)
k=1 k=1

where the angular frequency ω may be defined in terms of a period T as ω = 2π/T . The coefficients akj and
bkj are given by

ZT
1
a0j = αj (t0 + t0 )dt0 ,
T
0
ZT
1
akj = αj (t0 + t0 ) cos(2πkt0 /T )dt0 , (26.3)
T
0
ZT
1
bkj = αj (t0 + t0 ) sin(2πkt0 /T )dt0 .
T
0

CSC – IT Center for Science

26. Loss Estimation Using the Fourier Series 155

In practice the time stepping algorithm gives the values of αj (t) at only a discrete set of time values and
linear interpolation is applied to generate αj (t) at the other points.
The use of (26.2) in (26.1) now yields
K
X K
X
~ h (x, t) ≈ ~a0 (x) +
A ~ak (x) cos[kω(t − t0 )] + ~bk (x) sin[kω(t − t0 )] (26.4)
k=1 k=1

where the fields ~ak (x) and ~bk (x) have the finite element expansions
N
X N
X
~ak (x) = ~j (x)
akj ψ and ~bk (x) = ~j (x).
bkj ψ
j=1 j=1

~ =∇×A
If the field of interest is B ~ h , we have similarly

K
X K
X
~
B(x, t) ≈ ∇ × ~a0 (x) + ∇ × ~ak (x) cos[kω(t − t0 )] + ∇ × ~bk (x) sin[kω(t − t0 )]. (26.5)
k=1 k=1

If the problem setup is given in 3D case it is assumed that the solution is obtained using edge element
basis. In the special case of 2D target field and the target variable is expected to be a scalar field Ah (x, t)
and B~ is then generated as
B~ = ∂Ah ~ex − ∂Ah ~ey .
∂y ∂x

26.2 Loss estimation

~ h is taken to be the vector potential solution corresponding
In a typical application we have in mind the field A
to the AV formulation of electromagnetic equations. Then the field B ~ = ∇×A ~ h gives the magnetic flux
density which, in view of (26.5), may be approximated in the form
K
X
~
B(x, t) ≈ B0 (x) + Bk (x) cos[kω(t − t0 ) − φk ],
k=1

with φk a phase angle.

The loss power associated with each simple-harmonic component may then be estimated over a body Ω
by using the Steinmetz equation approach as
Z
Pk = Cfkα Bkβ dΩ (26.6)
Ω

where C, α and β are given data and fk = kω/(2π). The total loss P is then obtained as
K
X
P = Pk . (26.7)
k=1

The field variable Ph associated with this solver is the total loss power distribution per unit volume which is
obtained from the weak formulation
Z K
Z X
Ph vh dΩ = Cfkα Bkβ vh dΩ (26.8)
Ω Ω k=1

where vh denotes a suitable test function. The current implementation enables several terms with constant
exponents α and β. The coefficient C, on the other hand varies among materials and may be a function of
frequency.

CSC – IT Center for Science

26. Loss Estimation Using the Fourier Series 156

26.3 Keywords
Solver solver id
Procedure File "FourierLoss" "FourierLossSolver"
This keyword is used to give the Elmer solver the place where to search for the routine producing
the loss estimate.
Equation String [FourierLoss]
A name to the computational version of the loss equation may be given by using this keyword.
The name has no effect but it should be unique.
Target Variable String
The value of this keyword gives the name of the field for which the Fourier series expansion is
produced. It is usually assumed that the field is magnetic vector potential. It may be either nodal
(with 1 component in 2D and 3 components in 3D) or a curl-conforming vector field.
Target Variable AV Logical
The user may enforce the target variable to be one resulting from the AV-solver which uses the
edge degrees of freedom to express the vector potential. If the flag is not given, the existence of
the AV solver is deduced from the size of the permutation vector. Because the detection may be
erroneous, for example when a DG field is used, this may also be given value False to enforce
use of a nodal field.
Target Variable Direct Logical
By default it is assumed that the target variable is the magnetic vector potential and the curl
operator is applied. However, with this flag it is possible to give either scalar field |B| or vector
~ directly. The handicap of this is that the field is not continuous. However, this may be
field B
particularly useful for testing purposes.
Variable String
The primary variable is the loss component for the linear frequency dependence. The default
name is Fourier Loss if all components are summed together and Fourier Loss i if
each component is treated separately.
Separate Loss Components Logical
By setting this flag to True the user may save the different loss components in Steinmetz model
as separate fields for postprocessing. Otherwise they will be merged to one single field.
Inexact Integration Logical
The integration may be performed most accurately by integrating the product of the linear ap-
proximation of the time-dependence and the sines and cosines analytically. Currently this exact
integration is used. However, the user may replace it with inexact version even though this is not
recommended.
Simpsons Rule Logical
If using inexact integration, the default method is the trapezoidal integration. Instead the user
may request the Simpson’s rule for better accuracy. If exact integration is used, this keyword has
no effect.
Discontinuous Galerkin Logical
Instead of the standard Galerkin formulation the user may also choose to compute the post-
processed fields using discontinuous Galerkin (DG) approximation. This enables discontinuities
between elements. However, the cost is often quite large since the matrix structures related to DG
are very large compared to the standard Galerkin method. The lumped quantities are computed
on-the-fly so for them there is no difference.
Average Within Materials Logical
This only applies when the DG method is used to compute the loss fields. When this flag is
turned on the fields within same material are weakly enforced to be continuous. This results to
much smoother fields while still maintaining the discontinuity over material interfaces.

CSC – IT Center for Science

26. Loss Estimation Using the Fourier Series 157

Calculate Elemental Fields Logical

The user may request elemental fields to be computed. These are natural since they allow dis-
continuous fields to be visualized. This features uses the same degrees of freedom as the DG
approximation but does not include interactions between elements.
Calculate Nodal Losses Logical
This may be used to calculate the losses directly in terms of power (i.e. Watts in SI units) lost
in each node. For conforming meshes this provides the easiest coupling with heat equation and
these losses become directly the r.h.s. source terms for the heat equation. Nodal losses are always
lumped to one field even though the distributed fields would be separated.
Fourier Series Components Integer
This keyword is used to define the parameter K in (26.2), i.e. how many Fourier series compo-
nents are generated.
Fourier Series Output Logical
If the value True is given, then the Fourier component fields ~ak and ~bk are output into the result
file. Note that for edge elements this does not currently work as they cannot be directly written
to a file but they should be mapped into a space that is able to be visualized.
Angular Frequency Real
This keyword is used to give the angular frequency ω. Alternatively, the simulation section may
be used for the same purpose.
Frequency Real
Instead of giving the angular frequency, the user may specify the frequency f = ω/(2π) by
using this keyword.
Fourier Start Time Real
This keyword can be used to define the start time t0 for performing the integration.
Fourier Start Timestep Integer
This keyword can be used to define the start time t0 such that t0 = tn , with n the timestep index
given by using this keyword.
Fourier Start Cycles Integer
This keyword can be used to define the start time t0 such that t0 = nT , with n the value of this
keyword.
Fourier Integrate Cycles Integer
By default the Fourier coefficient computation is restarted after integration over one complete
period T . If this keyword is used, then the restarting occurs after integration over n periods,
with n the value of this keyword. The reason for this could be that the results include some
randomness that we would like to filter out by integrating over several cycles.
Harmonic Loss Frequency Exponent(K) Real
The value of this keyword gives the parameters αk in a vector format. The number of compo-
nents, K, should be the same as the number terms in Steinmetz loss model. Alternatively the
user may give this componentwise, i.e. Harmonic Loss Frequency Exponent 1, etc.
Harmonic Loss Field Exponent(K) Real
The value of this keyword gives the parameters βk in a vector format. The number of compo-
nents, K, should be the same as the number terms in Steinmetz loss model. Alternatively the
user may give this componentwise, i.e. Harmonic Loss Field Exponent 1, etc.
Fourier Loss Filename File
Name for the file in which the losses will be saved. Losses will be saved so that each body for
which there are any losses is written to a separate line. If the name is not given, nothing will be
saved.
Material material id
Harmonic Loss Coefficient i Real
This keyword is used to define the material parameter C in (26.6) for each simple-harmonic term

CSC – IT Center for Science

26. Loss Estimation Using the Fourier Series 158

i. The highest existing value i determines the number of terms in the loss model. Note that the
coefficient may only be a function of frequency itself.

CSC – IT Center for Science

Model 27

Coil Current Solver

Module name: CoilSolver

Module subroutines: CoilSolverr
Module authors: Peter Råback
Document authors: Peter Råback

27.1 Introduction
Assume that we have been given a geometry of a coil. Now the coil consists of individual wires and there-
fore the direction of the current is basically well defined. Unfortunately it is often difficult to provide the
directional information of the wires. In simple cases (such as ideal cylinder) the user may give the current in
the coil using analytical functions. In general case this is however, not possible.
This solver tries to provide numerical means for setting the coil current. The idea is that the computed
current density (or potential) may then be used in further simulations of magnetic fields.
Now the natural way to create the currents is to solve a static current conduction equation. Unfortunately
for closed loops it is difficult to define the boundary conditions. Rather than trying to make some special
mesh this solver provides a unique strategy to create the currents in two pieces using Dirichlet conditions for
some nodes in the bulk.

27.2 Theory
Our starting point for defining currents in the coil is to use an equation for the static current conduction,

− ∇ · σ∇φ = 0. (27.1)

where φ is the electric potential, and σ is the electric conductivity. For this equation we may either set
Dirichlet boundary conditions
φ = φ0 (27.2)
or Neumann boundary conditions
∂φ
−σ = jn . (27.3)
∂n
If we solver the equation with the standard Galerkin method in FEM the volume current density may then
be calculated using the same finite element spaces from
~j = −σ∇φ. (27.4)

CSC – IT Center for Science

27. Coil Current Solver 160

Normalization of potential and current

Typically we know the total current over the cross section
Z
J = jn dΓ. (27.5)

If the current density over the boundary area A is constant this gives the current density, jn = J0 /A. Often
it is more ideal to define Dirichlet conditions and normalize the potential afterwords to give the desired total
current,
J0
φ := φ (27.6)
J
and similarly for the current,
~j := J0 ~j. (27.7)
J
If we know that the cross section of the coil is constant and thereby also the current density is constant
j0 we may normalize the current density also locally taking only the direction from the initial current,

~
~j := j0 j . (27.8)
|~j|

Now this normalization should not be done light-heartedly since after this the solution might not be divergence-
free any more. When the magnitude of the solution is known a priori we could use also other means of
obtaining the direction field.

Modified conductivity field

Now in the previous we assumed that conduction is isotropic and homogeneous. Unfortunately this means
that for coils the current won’t follow the wires as it tends to take the shortest path more easily. On the other
hand we don’t know the anisotropic conductivity since if we knew it we would also know the direction of
the current and there would be nothing to compute. Therefore we look at some ways to iteratively determine
the solution from the already computed field.
One idea is to introduce an additional field variable, say c, such that

−∇ · cσ∇φ = 0. (27.9)
c|σ∇φ| = j0 . (27.10)

This may be iteratively solved by solving φ from the 1st equation and c from the 2nd equation. Unfortunately
numerical tests showed that the resulting field for c that is prone to numerical oscillations. Therefore we add
some regularization to the 2nd equation by adding some diffusion

− ∇ · D∇c + |σ∇φ|c = j0 . (27.11)

where D is the numerical diffusion. Unfortunately the equation does not necessarily have any solution. In
fact real tests showed that increasing value of D will make the solution smoother but at the same time it will
be more difficult to find a solution that would fulfil both equations. Still the current density may be closer to
the real current density than in the homogeneous case. Just a small number of iterations will get the most of
the benefits of the scaled conductivity field.
We may also look at the conductivity in an anisotropic form. One idea is to use the knowledge that in the
true coil the conductivity is only in the direction of the gradient. We may therefore look at the conductivity
in the form
∇φ
σ = σ0 (27.12)
|∇φ|
Now without the multiplier c this would not lead to an improvement because then the direction does not have
an effect as the flux is always in the direction of the gradient only. However, the combined effect of these
two could improve the accuracy of the direction of the current density.

CSC – IT Center for Science

27. Coil Current Solver 161

There can be also partially geometric means for setting the direction of the conductivity field. Basically
the distance from the coil surface, s, defines a field the gradient of which defines a direction with zero
conductivity. So we take a isotropic conductivity as a starting point and eliminate the conductivity in the
direction of the normal i.e.
1
σ = σ0 √ [I − abs(∇s)] (27.13)
3
Unfortunately this formulation has some difficulties at the center of the coil where the the distance function
is poorly defined.
For structured and extruded meshes one could also use the directions of the element edges to directly set
the direction of the current. Starting from a rough information for the current direction the edges aligned
with the current could be detected and thereafter the current direction could be refined accurately with the
geometry. This method has not been implemented.

Case of closed coils

The closed coils are dealt with in two parts. The idea is to use rough fiction boundary conditions for the
bulk nodes. Setting potentials to 0 and φ0 on a narrow gap around the fictitious interface we can generate
a current to the coil. Now this current is "good" only in the other side of the coil where the effects of the
poorly defined boundary conditions have settled. The distance from the fictitious interface should be at least
around three times the diameter of the coil cross section. Therefore the approach is better suited for "lean"
coils. We apply the same procedure to opposite sides of the coil and normalize the coil current to be the
same. The final current is an union of the two cases so that we always take the more accurate of the two
computed currents fields.
Now the currents should ideally be continuous. However, the potential derived in this way can never
be continuous since at some stage the potential should have a jump over the coil. Still, if the coil potential
is used only element-wise so that it is always operated by a gradient we may use a special subroutine that
returns always the more accurate set of nodal potentials for each element. After taking the gradient of the
potentials the solution should be continuous.

Using the coil solver

The solver can be used to compute currents or potentials to be used by other solvers. The standard case could
equally well be computed by the StatCurrentSolver but this solver includes some ways to make the
current distribution more accurate to the case of coils. Unfortunately all these techniques are based on
heuristics and they will most likely offer better current distributions that the standard approach.
If one tries to normalize the current density to a predefined constant value the user should be sure that
the cross section of the coil is constant. Otherwise the user introduces a current source or drain that may be
difficult to treat in the later steps of the simulation.
When using in conjunction with the MagnetoDynamics module it is advisable to perform the fixing
of the current to be divergence free using the internal Jfix solver. Otherwise the solution might not exist
for the equation.
Currently it assumed that there is just one coil, and for the closed coil it is assumed that the coil axis is in
the direction of the z-axis. These limitations are not inherent to the method and could be resolved by small
coding effort.

27.3 Keywords
The solver includes some internal definitions which eliminates some keywords. For example, the variable
related to the solver is internally created and also the boundary conditions related to it are set internally so
the user does not need to know of it.

Solver solver id
Equation String CoilSolver

CSC – IT Center for Science

27. Coil Current Solver 162

Procedure File "CoilSolver" "CoilSolver"

Name of the solver module and solver.
Coil Closed Logical
Is the coil closed. If it is then the potential will be computed in two parts. Note that for many
coils it is currently assumed that all the coils are either open or closed. Closed coils will in effect
create a secondary potential field and an auxiliary field PotSelect used to toggle between the
two potentials.
Coil Conductivity Fix Logical
Fix the coil conductivity so that the current density would be more even.
Cfix diffusion D
iffusion coefficient for regularization of c field.
Coil Anisotropic Logical
Make the conductivity be aligned with the gradient of the potential.
Calculate Coil Current Logical [True]
Calculate the current flowing in the coil(s). The effect of the enforced currents in the coil may
be given as a source term either as current, or as a enforced potential.
Use Wall Distance Logical
Use wall distance to introduce anisotropy into the coil conductivity. If wall distance is used then
it is assumed that a field Wall Distance exists.
Save Coil Set Logical
Optionally save the CoilSet field.
Save Coil Index Logical
Optionally save the CoilIndex field. This makes sense only if there are more than one coil.
Then the index gives the number of the coil.
Normalize Coil Current Logical
After the current has been computed normalize it to the desired magnitude if this flag is given.
Nonlinear System Max Iterations Integer
For the inhomogeneous cases give the number of iterations. The default is 2 for the scaled
conductivity, and 3 for the scaled anisotropic conductivity.
The following keywords define one single coil. They may be located in the Solver section if there is
just one single coil. If there are many coils they should be located in different Component sections.

Desired Coil Current Real

The desired coil current J0 in the coil. The default is 1.
Desired Current Density Real
The desired coil current density j0 in the coil. The default is 1.
Coil Cross Section Real
Cross section (area) of the coil that may be used to related total current and current density.
Coil Center(3) Real
Center of the coil in (x, y, z) Cartesian coordinates. If coil center is not given then the volumetric
mid point is assumed to be the center.
Coil Normal(3) Real
The user may give the coil axis around which the coil circulates around. If not given the coil
axis is found as the axis that gives the maximum inertial momentum for the coil. The tangent
directions are deduced from the coil normal.
Coil Bandwidth Real
A parameter related to the width of the fictitious interface used to set the potentials in an auto-
mated way. This is relative to the total width. Default is 20% of the width of the coil.

CSC – IT Center for Science

27. Coil Current Solver 163

Narrow Interface Logical

This flag enforces the use of narrow strategy for the setting of Dirichlet conditions and computa-
tion of the resulting nodal charges. It is a better strategy than the wider coil bandwidth strategy
particularly for thick coils. Makes the above keyword obsolete.
Boundary Condition bc id

Potential Real
Dirichlet BC for the potential.
Current Density BC Logical
Must be set to True if Neumann BC is used.
Coil Start Logical
Defines a boundary where coil starts. Not needed if coil is closed.
Coil End Logical
Defines a boundary where coil ends. Not needed if coil is closed.

The user can use the united potential also for closed coils by using a special subroutine. The calling conven-
tion would then be, for example, in the MagnetoDynamics module in the Body Force section
Electric Potential = Variable time
Real Procedure "CoilSolver" "CoilPotential"
Here time is just a dummy variable. Similarly for coil potential normalized on-the-fly within each element,
Electric Potential = Variable time
Real Procedure "CoilSolver" "CoilPotentialNormalized"

CSC – IT Center for Science

 Part V

Other Physical Models

CSC – IT Center for Science

Model 28

Electrokinetics

Module name: Electrokinetics

Module subroutines: helmholtz_smoluchowski1, helmholtz_smoluchowski2,
helmholtz_smoluchowski3, helmholtz_smoluchowski
Module author: Thomas Zwinger
Document author: Thomas Zwinger

28.1 Introduction
If dealing with electrolytic fluids constrained to small volumes, surface forces caused by electric surface
charges in combination with externally applied electrostatic fields are sufficient strong to affect the fluid
volume. If these effects are utilized to attenuate the fluid volume, we talk of Electrokinetics. The term
Electroosmotic Flow (EOF) is used in connection with the attenuation of a net charge inside a originally
neutral electrolyte caused by separation induced by a surface charge of a wall.

28.2 Theory
Chemical reactions between the contents of a liquid and the wall material may lead to a net charge of the
containment at the wall-liquid interface. If the liquid is an electrolyte (i.e., it contains free ions), ions of
opposite charge align along the wall creating the Stern layer. Adjacent to the Stern layer, a charge separation
- called the diffuse layer of the initially neutral electrolyte takes place. Due to the two layer structure the
whole are area of charge separation in the vicinity of a wall is called the Electric Double layer (EDL).

28.2.1 Electroosmotic slip velocity

Considering a symmetric electrolyte – i.e., the bulk ion density of ions with opposite valence numbers ±z
−
are equal n+
0 = n0 = n0 – at a certain temperature, T , the typical width-scale of the EDL is given by the
Debye length [1]
 1/2
f 0 kb T0
λD = . (28.1)
2 n0 z 2 e20
Here e0 stands for the unit charge and kb denotes the Boltzmann constant. The relative permittivity of the
electrolyte and the permittivity of vacuum are given by f and 0 , respectively.
The potential, Φ and the volume charge density, ρe , within the EDL are tightly coupled to each other by
the Poisson-Boltzmann equation (25.4) (see chapter 25). In order to exactly resolve the dynamics close to the
walls, (25.4) should be solved and the resulting specific electric force then be considered in the equation of
motion. Nevertheless, provided the typical length scales of the flow perpendicular to the containment walls,
H, strongly exceed those of the EDL – in other words, we obtain very small values for the non-dimensional
group L = λD /H  1 – the dynamics of the electrolyte inside the EDL does not have to be resolved at

CSC – IT Center for Science

28. Electrokinetics 166

all. In this case simple considerations of a force balance between shear stress and electric force lead to a slip
condition for the fluid [2]. At the boundary, the tangential velocity is set to the Helmholtz-Smoluchowski
velocity
E~ tang. f 0 ζ
~utang. = ~uH−S = , (28.2)
µf
with µf standing for the local fluid viscosity. The zeta potential, ζ – a property depending on the electric
properties of the wall material as well as the electrolyte – usually is determined experimentally. From a
physical point of view it can be interpreted as the value of the solution obtained by (25.4) at the Stern layer.
The tangential component, E ~ tang. , of the external electric field, E,
~ is evaluated from the outward pointing
surface normal ~n, applying the following relation
 
~ tang. = E
E ~− E ~ · ~n ~n (28.3)

Alternatively, the resulting slip velocity may be related to the tangential field using the Electroosmotic Mo-
bility, µEOF
~uH−S = µEO E ~ tang. . (28.4)
A combination of (28.2) and (28.4) leads to the following identity

f 0 ζ
µEO = . (28.5)
µf

28.3 Limitations
• The Helmholtz-Smoluchowski velocity should not be applied if the non-dimensional group L defined
in 28.2.1 is of unity order or larger. Then the potential- and charge density distribution as well as the
dynamics of the electrolyte inside the EDL has to be resolved.
• In a strict sense, the Helmholtz-Smoluchowski theory applies only to configurations where the normal-
component of the external field, E ~ · ~n, is small. If dealing with electric insulating wall materials – as
it is usually the case in microfluidic applications – this condition is implicitly complied with.
• The assumption of a Newtonian fluid underlies the derivation of the Helmholtz-Smoluchowski veloc-
ity.
• The function helmholtz_smoluchowski can only be applied on boundaries of two-dimensional
domains, where the tangential direction is uniquely defined.

28.4 Keywords
Keywords for helmholtz_smoluchowski
Constants
Permittivity Of Vacuum Real [8.8542e-12 C2 /Nm2 ]
permittivity of vacuum, only needed if Helmholtz-Smoluchowski velocity is defined using ex-
pression (28.2)
Equation equation id
Electric Field String [computed, constant]
the option for how to evaluate the electric field should be set to one of these values.
If set to computed, the function will search for Electric Field {1,2,3} in the list
of solver variables. If set to constant, the function will search for Electric Field
{1,2,3} in the section Material material id, where material id is the id-number
associated with the material parameter list of the electrolyte

CSC – IT Center for Science

BIBLIOGRAPHY 167

Material material id
If the Helmholtz-Smoluchowski velocity is defined using expression (28.2), then the following key-
words have to be provided in this section
Viscosity Real
viscosity of the electrolyte
Density Real
volumetric density of the electrolyte
Relative Permittivity Real
relative permittivity of the electrolyte

Boundary Condition bc id
In two-dimensional configurations the Helmholtz-Smoluchowski velocity directly can be assigned to
the tangential component of the velocity field
Normal Tangential Velocity Logical True
Velocity 2 = Variable Dummyargument
Real Procedure "Electrokinetics" "helmholtz_smoluchowski"
Sets tangential EO slip velocity
The argument Dummyargument can be any existing variable, since it is not used to evaluate the
velocity.
In three-dimensional configurations (and as an alternative also in two-dimensional), the velocity has
to be defined for each component
Normal Tangential Velocity Logical False
Velocity 1 = Variable Dummyargument
Real Procedure "Electrokinetics" "helmholtz_smoluchowski1"
Velocity 2 = Variable Dummyargument
Real Procedure "Electrokinetics" "helmholtz_smoluchowski2"
Velocity 3 = Variable Dummyargument
Real Procedure "Electrokinetics" "helmholtz_smoluchowski3"
The argument Dummyargument can be any existing variable, since it is not used to evaluate the
velocity.
If the Helmholtz-Smoluchowski velocity is defined using expression (28.2), then the zeta potential, ζ,
for the specific boundary region has to be defined
Zeta Potential Real
Sets the zeta-potential for this boundary

Alternatively, the user can declare the EO-mobility, as explained in (28.5)

EO Mobility Real
Sets EO mobility for this boundary

Bibliography
[1] G.E. Karniadakis and A. Beskok. Micro flows : fundamentals and simulation. Springer-Verlag, New
York, Berlin, Heidelberg, 2001.
[2] R.-J. Yang, L.-M. Fu, and Y.-C. Lin. Electroosmotic Flow in Microchannels. J. Colloid and Interface
Science, 239:98–105, November 2001.

CSC – IT Center for Science

BIBLIOGRAPHY 168

electrolyte E
y

ζ
neutral
bulk

diffuse
layer

Stern layer
φ
σe
wall

Figure 28.1: Structure of the EDL. The value of the induced potential, Φ at the Stern layer usually is referred
to as the zeta-potential, ζ

CSC – IT Center for Science

Model 29

Mixed Approximation of the Poisson

equation

Module name: ModelMixedPoisson

Module subroutines: MixedPoisson
Module authors: Mika Malinen
Document authors: Mika Malinen

29.1 Introduction
In some cases obtaining an accurate approximation of the flux connected with the solution of the Poisson
equation may be of a particular interest. To this end, the flux may be introduced as an additional independent
variable which is solved simultaneously with the associated scalar variable. Such approximations where two
finite elements spaces are employed at the same time are generally known as mixed methods.
The mixed problem considered here also provides a basic example of the application of divergence-
conforming finite elements. They are also known as face finite elements and offer a natural choice when just
the continuity of the normal component of the solution can be assumed. It should be noted that the selection
of face finite elements is not complete yet, so discretizations over simplicial (i.e., triangular or tetrahedral),
quadrilateral and hexahedral meshes are only supported currently.

29.2 Governing equations and the weak formulation

Let us consider rewriting the Poisson problem

− div(a∇u) = f on Ω,
u=g on Γ1 , (29.1)
a∇u · n = q on Γ2
as
q − a∇u = 0 on Ω,
− div q = f on Ω,
(29.2)
u=g on Γ1 ,
q·n=q on Γ2 .

Here a is a material parameter and the physical interpretations of the fields u and q depend on a case. For
example, u may be the temperature or a potential variable, while q may represent the heat flux, electric field,
current density, etc.

CSC – IT Center for Science

29. Mixed Approximation of the Poisson equation 170

If U ≡ L2 (Ω) denotes the set of square-integrable scalar functions over the d dimensional body Ω, we
are thus led to seeking the weak solution of the flux in the space of divergence-conforming functions defined
by
Q = {v ∈ L2 (Ω)d | div v ∈ L2 (Ω) and v · n = q on Γ2 }.
By defining µ ≡ 1/a, multiplication with test functions and integration by parts lead us to seeking (q, u) ∈
Q × U such that
Z Z Z
µq · v dΩ + u div v dΩ = g(v · n) dS,
Ω Ω Γ1
Z Z (29.3)
div q w dΩ = − f w dΩ,
Ω Ω

for any (v, w) ∈ Q0 × U , with the test space of fluxes being defined by

Q0 = {v ∈ L2 (Ω)d | div v ∈ L2 (Ω) and v · n = 0 on Γ2 }.

As a generalization, the scalar parameter µ can be replaced by a tensor of order 2. In addition the total time
derivative may be added to the model. The weak formulation (29.3) is then replaced by
Z Z Z
µq · v dΩ + u div v dΩ = g(v · n) dS,
Ω Ω Γ1
Z Z Z (29.4)
∂p
div q w dΩ − ( + a · q)w dΩ = − f w dΩ,
∂t
Ω Ω Ω

where µ is a second-order tensor and a is the convection velocity treated as a model parameter.
It is worth noting that the standard Neumann boundary condition is now built in the construction of the
solution space, i.e., it is specified as an essential boundary condition in the mixed formulation. On the other
hand the standard Dirichlet condition is handled as a natural condition. The boundary conditions of the
standard and mixed formulation have thus opposite roles to another.
Finite element approximations to the solution of (29.3) are constructed in the standard manner by ex-
pressing the weak formulation in terms of finite element versions of the solution and test spaces. For the
available face finite elements a natural finite dimensional version of U is based on functions which are con-
stants elementwise. For additional details on the construction of divergence-conforming finite elements see
also the Appendix “Face and edge elements” of the ElmerSolver Manual.

29.3 Keywords
Material mat id

Material Parameter Real

This keyword specifies the value of a.
Material Tensor(3,3) Real
This keyword defines the tensor µ in the generalized model (29.4).
Convection Velocity i Real
The components of the convection velocity a may be given by using these keywords.
Solver solver id
Equation String
A describing name for the solver.
Procedure File "ModelMixedPoisson" "MixedPoisson"
The name of the solver subroutine.

CSC – IT Center for Science

29. Mixed Approximation of the Poisson equation 171

Variable
The name of the solver variable can be chosen freely (but it is must be used consistently else-
where).
Variable DOFs Integer
The value of this keyword should be 1.
Second Kind Basis Logical
This keyword specifies whether the Brezzi-Douglas-Marini space or the Nédélec face elements
of the second kind are used in two or three dimensions, respectively.
Element String
A special element definition is needed to obtain a suitable set of degrees of freedom. The solver
should be able to create an automated value for this keyword provided the value of the key-
word "Coordinate System" specifies the dimension of coordinate system basis. That is,
one should use the value "Cartesian 2D" or "Cartesian 3D" to specify the coordinate
system.
Body Force bf id

Source Field Real

The value of this keyword gives f .
Boundary Condition bc id

Scalar Field Real

This keyword is used to define the data g.
Q {f} j Real
If the solver variable has been given the name Q, this keyword defines a vector ĝ so that its
normal trace ĝ · n is approximated by q h · n, with q h the finite element solution. The value
of this keyword defines the components ĝj , j ∈ {1, 2, 3}, with respect to the global Cartesian
coordinate system.

CSC – IT Center for Science

Model 30

Block Preconditioning for the Steady

State Navier–Stokes Equations

Module name: ParStokes, PressurePrecond, VelocityPrecond

Module subroutines: StokesSolver, PressurePrecond, VelocityPrecond
Module authors: Mika Malinen, Jonas Thies, Juha Ruokolainen
Document authors: Mika Malinen

30.1 Introduction
The discretization of the incompressible Navier–Stokes equations usually leads to large linear systems which
cannot be solved efficiently with the standard iterative methods. Special preconditioning strategies should
therefore be employed to obtain rapid convergence of iterations. In this section we describe a special solver
for the steady state Navier–Stokes equations which has utility when the Reynolds number is moderate. The
development of the solver was originally motivated by needs to solve the full Stokes equations in connection
with glaciological simulations. Therefore, the possibility to utilize parallel computation has been in mind
from the very beginning (the module name comes from Parallel Stokes solver).
The speciality of the solver is that it contains an in-built two-level iteration scheme to handle the linear
systems arising from the linearization and discretization. Inner iterations can be associated with precon-
ditioning and they provide search directions for the outer iterative method (GCR) applied to the primitive
problem. The preconditioning strategy is here based on the idea of block preconditioning via utilizing the
natural block structure of the discrete system. In practice simpler auxiliary problems need to be solved in
order to find the update directions for the velocity and pressure unknowns in a decoupled manner. In this way
the door is opened to utilizing other efficient methods, such as multigrid methods for the discrete Poisson
problems, in connection with the solution of the more complicated problem.
The alternate flow solver contained in the ParStokes module basically mimics the standard Navier–
Stokes (NS) solver of Elmer. However, it does not provide all features available in the standard NS solver.

30.2 The model

The equations to be solved are written as

ρ0 (u · ∇)u − div[2µ(D)D(u)] + ∇p = ρ0 g,
(30.1)
− div u = 0
or
− div[2µ(D)D(u)] + ∇p = ρ0 g,
(30.2)
− div u = 0

CSC – IT Center for Science

30. Block Preconditioning for the Steady State Navier–Stokes Equations 173

when the effect of convection is neglected to obtain the Stokes equations. Here D(u) is the symmetric
part of the velocity gradient, the constant ρ0 is the fluid density and µ is the fluid viscosity. For example,
in the case of Glen’s flow law we have µ(D) = 1/2A−k [I2 (D)](k−1)/2 , with A and k parameters and
I2 (D) = 1/2(D · D).
Common boundary conditions may be expressed as
u = û on ΓD ,
2µ(D)D(u)n − pn = ŝ on ΓN , (30.3)
u·n=0 and n × [2µ(D)D(u)n] × n = −βn × u × n on ΓS .
Here û is the specified velocity, ŝ is the specified traction, and also the friction coefficient β > 0 is given as
initial data.

30.3 Linearization
Either Newton’s method or the strategy of Picard type can be used to linearize the effect of viscosity. The
possible convection term is always linearized with the Picard method.

30.4 Discretization aspects

The solver is tailored to the case of the lowest-order continuous pressure approximation. Equal-order approx-
imations of (u, p) are unstable, but the solver offers the following two strategies to obtain stable methods:
• P2 -P1 /Q2 -Q1 approximation. The polynomial order of the velocity approximation can be taken to be
of the second order. This option requires that the finite element mesh contains second-order elements
based on the Lagrange interpolation.
• A hierarchic version of bubble-stabilized methods. The lowest-order velocity approximation may also
be enhanced relative to the pressure by using elementwise bubble functions. The richness of velocity
approximation depends on how many bubble basis functions are constructed. For example, the set of
basis functions for the linear triangular and tetrahedral elements can be augmented with one interior
bubble function by giving the element type definition Element = "p:1 b:1" in the Equation
section. Analogous rectangular and brick elements may also be constructed, but our experience is
that more than one bubble function may be necessary to obtain stability, making this strategy less
attractive. It is recommended that the definition Element = "p:1 b:4" is generally used in three
dimensional cases. The Q2 -Q1 and P2 -P1 approximation methods may require less computational
work, especially for three-dimensional problems where the burden of numerical integration in the
assembly phase is increased significantly.
It is noted that other instabilities generally arise when the flow is convection-dominated. The computa-
tional methods of the solver have not been designed to handle this scenario, i.e. the Reynolds number for the
flow should be moderate.

30.5 Block preconditioning

The linearization and discretization of the flow model considered leads to solving linear systems of the form
Ak B T
    
U F
= , (30.4)
B 0 P 0
where Ak is the coefficient matrix for the velocity unknowns at the nonlinear iteration step k + 1 and B is
the divergence matrix. If the linear system (30.4) is abbreviated as Kx = b, the outer iterative method based
on the generalized conjugate residual method (GCR) can be used to generate iterates x(k) that minimize the
residual 2-norm
||b − Kx(k) ||2

CSC – IT Center for Science

30. Block Preconditioning for the Steady State Navier–Stokes Equations 174

over the search direction space

Xk = x(0) + span{s(1) , s(2) , . . . , s(k) }

where x(0) is the initial guess. In this setting, the preconditioner is considered to be an operator P which,
given the previous iterate, produces the new search direction s(k+1) .
Here the search directions are found as approximate solutions of systems

Ps(k+1) = b − Kx(k) . (30.5)

The preconditioner matrix is selected to be of the form

T BT
 
P= (30.6)
0 Q

where T approximates A and Q = µ−1 M , with M the pressure mass matrix. By default the choice T = A is
used. An alternate is to select T to be the block diagonal approximation of A or the scaled vector-Laplacian
matrix, which is the discrete version of the operator −µ div ∇ subject to suitable boundary conditions.
To apply the preconditioner via performing approximate solves of (30.5), the user must define methods
for solving subproblems of the type
(k) (k)
QδP (k+1) = RP and T δV (k+1) = RA − B T δP (k+1)

or, in practice, their preconditioned versions

(k)
(QP−1
Q )δ P̂
(k+1)
= RP (30.7)

and
(k)
(T P−1
T )δ V̂
(k+1)
= RA − B T δV (k+1) . (30.8)
The efficiency of the block-preconditioned solver depends heavily on how these auxiliary problems are
solved (the solves associated with the coefficient matrix T are the most critical). A crucial aspect of the
methodology is that these subsidiary problems can be considerably easier to solve than the original fully
coupled system. They may also be solved inexactly without impairing the performance of the preconditioner.
In addition, it is noted that performing highly accurate solutions of the linearized systems (30.4) is not needed
in the beginning of the nonlinear iteration when the iterates are not accurate. The solver provides an option
to employ adaptive stopping criteria so that the solution accuracy for (30.4) is adapted automatically based
on the size of the current nonlinear error.

30.6 Defining additional solvers for subsidiary problems

If the block preconditioner is applied, the solver input file must contain two additional solver sections to
enable the assembly of the subsidiary problems with the coefficient matrices T and Q. In this connection
special equation names (given as the value of Equation keyword) have to be used. If the value of the
parameter d defines the space dimension, these solver sections should be written as

Solver 1
Equation = "Velocity Preconditioning"
Procedure = "VelocityPrecond" "VelocityPrecond"
Variable = "V"
Variable DOFs = $d
! Potential commands to adjust the solution of velocity
! preconditioning problems:
...
End

CSC – IT Center for Science

30. Block Preconditioning for the Steady State Navier–Stokes Equations 175

Solver 2
Equation = "Pressure Preconditioning"
Procedure = "PressurePrecond" "PressurePrecond"
Variable = "P"
Variable DOFs = 1
! Potential commands to adjust the solution of pressure
! preconditioning problems:
...
End

The first solver section is needed for creating the velocity preconditioning system (30.8), while the second
solver section corresponds to the pressure preconditioning system (30.7). Each of these sections may also
contain additional keyword commands to change the default linear solver and its parameters. The default
variable names V and P can be changed freely.
If a boundary condition u = û of Dirichlet type is specified, the variable of the velocity preconditioning
equation δV (the Elmer variable V above) must also be constrained similarly by using the homogeneous
Dirichlet condition. Usually there is no need to specify boundary conditions for the pressure preconditioning
variable.

30.7 Examples
The solver described here has for example been applied to simulate flows of ice sheets. To obtain an example
in this field, see the ISMIP HOM A test case
.../elmerfem/fem/tests/ParStokes_ISMIP_HOM_A010/

in the source code repository.

30.8 Keywords
Material material-id
Density Real
This keyword is used to define the density ρ0 .
Viscosity Model String
This keyword can be used to select a more advanced viscosity model such as Glen’s law. For
available options see the documentation of the standard Navier–Stokes solver.
Viscosity Real
This keyword is used to define directly the viscosity µ.
Constant-Viscosity Start Logical
In some cases it may be useful to start the nonlinear iteration with a constant viscosity although
the intention is eventually to use another model. Starting with a constant viscosity can be avoided
by giving the value False for this keyword.

Solver solver-id
Equation String
This keyword declares the name of the equation.
Procedure File ”ParStokes” ”StokesSolver”
The name of the file and procedure.
Variable String
This keyword is used to declare the name of the solution.

CSC – IT Center for Science

30. Block Preconditioning for the Steady State Navier–Stokes Equations 176

Variable DOFs Integer

The value of this keyword defines the number of unknown scalar fields and must hence equal to
d + 1 where d is the spatial dimensionality of the computational domain. The unknown scalar
fields are always numbered in such a way that the highest running number is associated with the
pressure solution.
Convective Logical
If the value True is given, the convection term will be included so that the steady state version
of the incompressible Navier–Stokes equations is solved.
Nonlinear System Convergence Tolerance Real
This keyword defines the stopping criterion for the nonlinear iteration. The nonlinear iteration is
terminated when the maximum number of nonlinear iterations is reached or when
kb − K(x)xk2 /kbk2 < εN ,
where εN is the value of this keyword.
Nonlinear System Max Iterations Integer
This keyword defines the maximum number of nonlinear iterations.
Nonlinear System Newton After Iterations Integer
If n is the value of this keyword, n Picard updates are performed before switching to Newton’s
method.
Nonlinear System Newton After Tolerance Real
If the norm of the nonlinear residual is smaller than the value of this keyword, then the nonlinear
iteration method is switched to Newton’s method.
P2-P1 Approximation Logical
This keyword can be used to select the P2 -P1 /Q2 -Q1 approximation method. The finite element
mesh must then contain second-order finite elements based on the Lagrange interpolation.
Element String
If bubble functions are used as the stabilization strategy, then an element definition must be given
to specify the number of bubble functions. The recommended choice is "p:1 b:4" for three
dimensional simulations.
Block Preconditioning Logical
If the block preconditioner is used, the value of this keyword must be True.
Block Diagonal A Logical
This can be used to select the preconditioner matrix T to be the block diagonal approximation of
the A-block.
Use Velocity Laplacian Logical
This can be used to select T to be the scaled vector-Laplacian matrix. Then the keyword Block
Diagonal A must also set to be True.
Linear System Convergence Tolerance Real
When the block preconditioning is used, the value of this keyword defines the stopping criterion
for the outer GCR method applied to (30.4). The iteration is terminated when
kb − Kx(j) k2 /kbk2 < εL ,
where εL is the value of this keyword.
Linear System Adaptive Tolerance Logical
The usage of adaptive stopping criteria can be activated with this keyword.
Linear System Relative Tolerance Real
If the adaptive stopping criteria are employed, this keyword controls the solution accuracy for
the linear systems (30.4) during the nonlinear iteration. The stopping tolerance εL for (30.4) is
(k) (k)
chosen to be εL = ηR · ηN , with ηR the value of this keyword and ηN the previous nonlin-
ear error. If the value obtained in this way is smaller than the value of the keyword Linear
System Convergence Tolerance, then this has no effect.

CSC – IT Center for Science

30. Block Preconditioning for the Steady State Navier–Stokes Equations 177

Linear System Base Tolerance Real

The stopping tolerance for solving (30.4) can never be larger that the value of this keyword.
Linear System Max Iterations Integer
When the block preconditioner is used, this keyword is used to define the maximum number of
the outer GCR iterations applied to (30.4).
Linear System GCR Restart Integer
The outer GCR iteration can be restarted after m iterations to avoid the increasing cost of the
orthogonalization procedure. The value of this keyword specifies the parameter m. The default
value is m = 50. Giving a larger value can be beneficial if convergence problems relating to the
outer iteration are met.

Body Force bf-id

Flow BodyForce i Real
This keyword is used to define the i’s component of the body force vector g.

Boundary Condition bc-id

Surface Traction i Real

This keyword can be used to specify the components of the traction vector ŝ. An alternate for
the phrase Surface Traction is Pressure.
Normal Surface Traction Real
This keyword can be used to specify a surface traction in the form ŝ = p̂n where p̂ is the value
of this keyword. An alternate for the phrase Normal Surface Traction is External
Pressure.
Slip Coefficient i Real
This defines the friction coefficient such that the friction force is proportional to the velocity in
the direction i.

CSC – IT Center for Science

Model 31

Rotational Form of the Incompressible

Navier–Stokes Equations

Module name: Stokes

Module subroutines: StokesSolver
Module authors: Mika Malinen
Document authors: Mika Malinen

31.1 Introduction
The basic incompressible flow solver of Elmer uses the standard formulation of the Navier–Stokes equations.
This section describes an alternative solver based on the rotational form of the Navier–Stokes system. In
addition, some iterative methods that utilize splitting strategies in the solution of the associated discrete
problems are represented.

31.2 Field equations

Using the vector identity
1
(~u · ∇)~u = (∇ × ~u) × ~u + ∇(~u · ~u), (31.1)
2
the Navier–Stokes system for incompressible Newtonian fluid may be written as
 
∂~u
ρ + (∇ × ~u) × ~u − 2µ∇ · ε(~u) + ∇P = ~b,
∂t (31.2)
∇ · ~u = 0,

where ε is the stretching tensor (2.4) and

1
P = p + ρ~u · ~u (31.3)
2
is the total (Bernoulli) pressure. The stress σ, which may be of interest especially near boundaries, can now
be expressed as
1
σ = (−P + ρ~u · ~u)I + 2µε(~u). (31.4)
2
The system (31.2) provides an alternative starting point for finding discrete solutions. Thus, instead
of approximating the conventional primitive variables (~u, p), we here look for discrete solutions of (~u, P ).
It should be noted that if the convection term is not taken into account the system (31.2) reduces to the
(generalized) Stokes equations. The pressure variable then reduces to the standard pressure, i.e. P = p.

CSC – IT Center for Science

31. Rotational Form of the Incompressible Navier–Stokes Equations 179

31.3 Boundary conditions

Either the normal velocity ~u ·~n, with ~n the outward unit normal vector, or the normal surface force σ~n ·~n can
be prescribed on the boundary. The tangential boundary conditions can be handled systemically in a similar
manner. Thus, if ~t is a tangent vector to the boundary, one may prescribe either the tangential velocity ~u · ~t
or the tangential surface force σ~n · ~t.
A rather common way to define an outflow boundary condition for the Navier–Stokes equations is to
impose the normal surface force condition
σ~n · ~n = 0, (31.5)
which ensures the uniqueness of the pressure solution. This condition arises when the homogeneous natural
boundary condition (do-nothing boundary condition) is imposed in the standard formulation of the Navier–
Stokes equations. It should be noted, however, that the homogeneous natural boundary condition associated
with the variational formulation of (31.2) can be written as
1
−P ~n + 2µε~n = σ~n − ρ(~u · ~u)~n = ~0.
2
Thus, a distinction must here be made between the surface force boundary condition and the natural boundary
condition. In the case of the rotational form, imposing the homogeneous natural boundary condition in the
normal direction yields
1
σ~n · ~n = ρ~u · ~u,
2
which, except for the special case of irrotational steady flow of a non-viscous fluid, may be an artificial
boundary condition. Nevertheless, the tangential natural boundary condition associated with the rotational
form is equivalent to the condition of vanishing tangential surface force, i.e. σ~n · ~t = 0.

31.4 Linearization
The linearization of the equation of motion in (31.2) can be done by utilizing the Newton iteration. This
iteration strategy is based on approximating the rotational convection term as

(∇ × ~u) × ~u ≈ (∇ × ~u) × ~a + (∇ × ~a) × ~u − (∇ × ~a) × ~a

where ~a is the previous velocity iterate. In this connection, the nonlinear boundary condition corresponding
to the outflow condition (31.5) is linearized as
1
−P + ρ(2~a · ~u − ~a · ~a) + 2µε(~u)~n · ~n = 0.
2
An alternative linearization strategy is to apply Picard’s method. Here this method corresponds to lin-
earizing the convection term and the outflow boundary condition as

(∇ × ~u) × ~u ≈ (∇ × ~u) × ~a

and
1
−P + ρ~a · ~u + 2µε(~u)~n · ~n = 0.
2
The convergence of the Newton method can be considerably faster than that of Picard’s method. Our
experience is that this can be the case, especially, when the steady solutions are sought for moderately large
Reynolds numbers. However, a difficulty with the Newton method is that the iteration may not be convergent
for arbitrary initial guesses. This trouble can often be avoided by performing some Picard updates before
switching to Newton’s method. In the case of time-accurate simulations this is usually unnecessary since
suitably accurate initial guesses are often available from the previous time levels.

CSC – IT Center for Science

31. Rotational Form of the Incompressible Navier–Stokes Equations 180

31.5 Discretization aspects

The solver is tailored to the case of the lowest-order continuous pressure approximation, but it does not
provide any in-built technique to stabilize discrete solutions based on inherently unstable equal-order ap-
proximations of (~u, P ). The solver offers two strategies which can be used to obtain stable methods. First,
one can use elements where the velocity approximation is augmented by using elementwise bubble func-
tions. Second, one can utilize hierarchic versions of the second-order elements to rise the polynomial order
of the velocity approximation. Both the strategies can be put into effect by utilizing the shape functions for
p-elements. Some stable approximation methods are summarized as follows.

• A hierarchic version of P2 -P1 approximation for triangular and tetrahedral elements. If the ba-
sic mesh consists of linear elements (element type 303 or 504), giving the element type definition
Element = "p:2" in the Equation section switches to the P2 -P1 approximation where the ve-
locity approximation is enhanced by using hierarchic basis functions associated with the mid-edge
nodes.
• A hierarchic version of Q2 -Q1 approximation for rectangular and brick elements. Analogously to
the previous case, if the basic mesh consists of bilinear or trilinear elements (element type 404 or
808), giving the element type definition Element = "p:2" in the Equation section switches to
the Q2 -Q1 approximation where the velocity approximation is enhanced by using hierarchic basis
functions.
• A hierarchic version of bubble-stabilized methods. The velocity approximation may also be enhanced
relative to the pressure by using elementwise bubble functions. The richness of velocity approximation
depends on how many bubble basis functions are constructed. For example, the set of basis functions
for the linear triangular and tetrahedral elements can be augmented with one interior bubble function
by giving the element type definition Element = "p:1 b:1" in the Equation section. Analogous
rectangular and brick elements may also be constructed, but our experience is that more than one
bubble function may be necessary to obtain stability, making this strategy less attractive. The Q2 -
Q1 and P2 -P1 approximation methods may generally require less computational work, especially for
three-dimensional problems where the number of interior bubble functions can be large (notice that in
the case of the time-dependent equations the interior degrees of freedom are not eliminated by using
the method of static condensation).

It is noted that other instabilities may arise when the flow is convection-dominated. A potentially useful
aspect of using the rotational formulation is that, as compared with the standard convection form, instabilities
relating to dominating convection may be more benign.

31.6 Utilizing splitting strategies by preconditioning

Discrete Navier–Stokes problems lead usually to large linear systems which are customarily solved with
iterative algorithms, in combination with preconditioning. The general preconditioning strategy used in
Elmer is based on the computation of incomplete factorizations. The performance of these preconditioners
is case-dependent and may not always be satisfactory.
More efficient solution algorithms for a particular problem can often be developed by exploiting the
block structure of the linear system. In the following such a solution strategy will be described. Since
the application of the preconditioner considered is based on solving certain simpler problems, the door is
opened to utilizing other efficient methods, such as multigrid methods for the discrete Poisson problems, in
connection with the solution of this more complicated problem.
The linearization and discretization of (31.2) leads to solving linear systems of the form

A BT
    
U F
= , (31.6)
B 0 Π 0

where A is the coefficient matrix for the velocity unknowns and B is the divergence matrix. The solution
strategy we consider is based on applying a preconditioned Krylov subspace method to (31.6). Given a

CSC – IT Center for Science

31. Rotational Form of the Incompressible Navier–Stokes Equations 181

previous iterate (Uk , Πk ), the preconditioning is performed via solving approximately systems of the form

F − AUk − B T Πk
    
A 0 0 Uk+1 − Uk
 B M 0   ψk+1  =  −BUk . (31.7)
B H S Πk+1 − Πk −BUk

Here M is the pressure mass matrix, while H and S are approximations of (scaled) Laplacian operators. In
practice the approximate solution of this block triangular system is generated by applying linear solvers to
systems with the coefficient matrices A, M and S. A crucial aspect of the methodology is that these sub-
sidiary problems can be considerably easier to solve than the original fully coupled system. They may also
be solved inexactly without impairing the performance of the preconditioner. Moreover, to our experience
the performance of the preconditioner is insensitive to discretization parameters and depends only mildly on
the Reynolds number, especially in the case of the evolutionary equations. The method is also suitable for
finding the steady solutions via using large time step sizes.
The outer iterative method applied to the primary system (31.6) is based on GCR, while the user can
specify linear solvers which are used to solve the subsidiary problems related to the preconditioning. It
should be noted that boundary conditions associated with the preconditioning operators are built-in, so the
user need not specify these constraints.

31.7 Restrictions
Currently, only homogeneous surface force conditions can be imposed on the boundary. If Q2 -Q1 or P2 -P 1
approximation is used, the boundary conditions are set by employing the linear interpolation of boundary
data. As a result, optimal accuracy may not be realised. If the preconditioning is done via solving (31.7), the
time discretization must be done using BDF(1) and viscosity should be constant.
If decoupled solution strategies are employed, parallel computations are possible only with the version
that does not involve performing the outer Krylov iteration update.

31.8 Keywords
Material material-id
Density Real
This keyword is used to define the density ρ.
Viscosity Real
This keyword is used to define the viscosity µ.

Solver solver-id
Equation String
This keyword declares the name of the equation.
Procedure File ”Stokes” ”StokesSolver”
The name of the file and procedure.
Variable String
This keyword is used to declare the name of the solution.
Variable DOFs Integer
The value of this keyword defines the number of unknown scalar fields and must hence equal to
d + 1 where d is the spatial dimensionality of the computational domain. The unknown scalar
fields are always numbered in such a way that the highest running number is associated with the
pressure solution.
Convective Logical
If the value ”False” is given, the convection term will be neglected so that the generalized
Stokes equations are solved.

CSC – IT Center for Science

31. Rotational Form of the Incompressible Navier–Stokes Equations 182

Nonlinear Iteration Method String

This keyword defines the nonlinear iteration method. The default is the Newton method, and
Picard’s method can be chosen by giving the value ”Picard”.
Nonlinear System Convergence Tolerance Real
This keyword defines the stopping criterion for the nonlinear iteration. The nonlinear iteration is
terminated when the maximum number of nonlinear iterations is reached or when
F − A(Uk )Uk − B T Πk
   
F
< T OL ,
−BUk 0

where T OL is the value of this keyword.

Nonlinear System Max Iterations Integer
This keyword defines the maximum number of nonlinear iterations.
Nonlinear System Newton After Iterations Integer
If n is the value of this keyword, n Picard updates are performed before switching to Newton’s
method.
Nonlinear System Newton After Tolerance Real
If the norm of the nonlinear residual is smaller than the value of this keyword, then the nonlinear
iteration method is switched to Newton’s method.
Nonlinear System Relaxation Factor Real
If this keyword is used, then the new nonlinear iterate is taken to be

(1 − λ)(Uk , Πk ) + λ(Uk−1 , Πk−1 ),

where λ is the value of this keyword.

Block Preconditioning Logical
If the block preconditioning via (31.7) is used, the value of this keyword must be ”True”.
Linear System Convergence Tolerance Real
When the block preconditioning is used, the value of this keyword defines the stopping criterion
for the outer GCR method applied to (31.6).
Linear System Max Iterations Integer
When the block preconditioning is used, this keyword is used to define the maximum number
of the outer GCR iterations applied to (31.6). It should be noted that the GCR iteration requires
that all previous iterates are saved. Especially in the case of time-accurate simulations the con-
vergence of the preconditioned GCR method is expected to be rapid so that saving all the iterates
is not expected be expensive. If the block preconditioning is used, the solver allocates computer
memory based on the value of this keyword, so giving an exaggerated value should be avoided.

Body Force bf-id

Body Force i Real
This keyword is used to define the i’s component of the body force vector ~b.

Boundary Condition bc-id

Outflow boundary Logical
If the value ”True” is given, then the normal outflow boundary condition (31.5) will be used.
Note that this does not define the tangential boundary conditions which have to be specified
separately.

If the preconditioning is done via solving (31.7), three additional solver sections need to be written to define
linear solvers for subsidiary problems with the coefficient matrices A, M and S. In this connection special
equation names (given as values of Equation keyword) have to be used. These solver sections should be
written as follows.

CSC – IT Center for Science

31. Rotational Form of the Incompressible Navier–Stokes Equations 183

Solver 1
Equation = "Velocity Preconditioning"
Procedure = "VelocityPrecond" "VelocityPrecond"
Exec Solver = "before simulation"
Variable Output = False
Variable DOFs = $ d
Variable = "VelocityCorrection"
...
End

Solver 2
Equation = "Divergence Projection"
Procedure = "DivProjection" "DivProjection"
Exec Solver = "before simulation"
Variable Output = False
Variable DOFs = 1
Variable = "DivField"
...
End

Solver 3
Equation = "Pressure Preconditioning"
Procedure = "PressurePrecond" "PressurePrecond"
Exec Solver = "before simulation"
Variable Output = False
Variable DOFs = 1
Variable = "PressureCorrection"
...
End

The first solver section defines a linear solver for the preconditioning system with the velocity matrix A,
while the second solver section defines a solver for the system involving the pressure mass matrix M . Finally,
the third section is related to the system with the coefficient matrix S arising from the discretization of the
Laplacian operator. Each of these sections should also contain the standard keyword commands that actually
define the linear solver. Some examples of such definitions can be found in the tests subdirectory of the fem
module.

CSC – IT Center for Science

 Part VI

Free Surfaces, Phase Change and

Particle Dynamics

CSC – IT Center for Science

Model 32

Level-Set Method

Module name: LevelSet

Module subroutines: LevelSetSolver, LevelSetDistance, LevelSetIntegrate, LevelSetCurvature, LevelSet-
Timestep
Module authors: Peter Råback, Juha Ruokolainen
Document authors: Peter Råback

32.1 Introduction
There are a number of problems involving free surfaces in continuum mechanics. There are two main strate-
gies to solve them using the finite element method: Lagrangian and Eulerian approach. In the Lagrangian
approach the free surface is solved exactly so that it is also an interface between the individual elements. This
requires that the computational mesh is distorted in a way that this is possible. However, often the changes
in geometry may be too drastic or even the whole topology may change and the Lagrangian approach is no
longer feasible. The Eulerian approach describes the interface in a fixed mesh using some additional variable
to describe the position of the interface. One possible Eulerian technique is the level-set method (LSM).
In the level-set method the free surface is given as a zero level-set of a higher dimensional variable. E.g.
for 2D surfaces the level-set function is defined in 3D space. The level-set function is usually defined to
be a signed distance so that inside the domain it obtains a positive value and outside a negative value. The
changes in the value of the level-set function mean also that the interface changes the position.
This module includes several different subroutines that may be used when applying the level-set method.
Currently there is no reinitialization strategy for 3D problems. Also some other procedures are not fully
optimized for the best performance. Therefore the current implementation is best applied to quite simple 2D
problems.

32.2 Theory
The interface is defined by a marker function φ so that at the interface φ = 0, inside the fluid of interest
φ > 0 and elsewhere φ < 0. The interface is update by solving the equation

∂φ
+ ~u · ∇φ = a (32.1)
∂t
where ~u is the convection field and a is the normal flux on the interface. It is quite challenging to solve
the differential equation above without diffusion effects playing a significant role. It is advisable to use 2nd
order time-discretization schemes and short timesteps. More precisely, the Courant number C = |~u|dt/h
should be below unity.
It is desirable that the absolute value of function equals the shortest distance to the zero level-set. How-
ever, as the level-set function is advected this property may be gradually lost. Therefore a process called

CSC – IT Center for Science

32. Level-Set Method 186

reinitialization may be evoked. In 2D the reinitialization may easily be done by geometric procedure. First
the zero level-set is formed by going through all the elements and finding the line segments that make the
zero level-set. Then the minimum distance of all the nodes is computed by a brute-force search. Assuming
there are N nodes and M line segments, the search algorithm is N ×M which is quite acceptable complexity
for small cases but may become computationally costly in large cases.
The line segments may be assumed to go with the flow and thereby they form an on-the-fly Lagrangian
mesh. Therefore it is also possible to advect the line segments when the velocity field is given since for
any node ~r = ~r + ~u dt. After the advection the shortest distance is computed. In the case of no advection
the sign of the distance is inherited from the original level-set function. However, when the level-set is also
convected the sign must be deduced from the geometric information as well. In the current implementation
each line segment is given a flag telling on which side of the element the fluid of interest is located. This
directional information is then used in giving the correct sign for the distance.
The volume of the fluid of interest in the level-set method may be computed over an integral that obtains
a value one inside the fluid and value zero outside the fluid. The Heaviside function H(φ) has this desired
property. However, as the interface does not follow the element division the numerical integration would
result into spurious fluctuations depending on the position of the interface within the elements. To obtain a
smooth behavior the Heaviside function must be regularized.

0,
 x < −α
Hα (x) = f (α/x) |x| ≤ α (32.2)

1, x > α,


where the following has been implemented

1  π 
f (t) = 1 + sin t (32.3)
2 2
while one could also use
3
1
f (t) = t − t3 /3 + . (32.4)
4 2
Here α is the interface bandwidth which equals typically the size of a few elements. Now the volume (area
in 2D) is obtained by the integral Z
V = Hα (φ) dΩ. (32.5)
Ω
After the same regularization the area (length in 2D) may be obtained from the integral
Z
A= δα (φ)|∇φ| dΩ (32.6)
Ω

where the delta function is (

0, |x| > α
δα (x) = 1 x

(32.7)
2α cos aπ , |x| ≤ α.
The information obtained by the above integrals may be used to improve the volume conservation of the
level-set advection. If the initial volume V0 is known the level-set function may be given a small correction
by
V0 − V
dφ = . (32.8)
A
This correction has no physical basis but it may be argued that a consistently small update of the level-set
function has a minor effect in overall results. It is more important that the volume is conserved since the
history information of the shape of a bubble is gradually lost while the errors in volume are never forgotten.
However, if the fluid of interest is divided into several parts this kind of overall correction does not have any
justification since it could ruin the volume balance between the different domains.
The problems in accuracy may be partially resolved by using an optimal timestepping strategy. This
may be achieved by looking at the velocity field around the active boundary. The normal velocity may be
obtained by un = ~u · ∇φ̃. Registering the maximum velocity at band the timestep may be limited so that

CSC – IT Center for Science

32. Level-Set Method 187

the Courant number is bound. If ds is the maximum allowed change in the position of the zero level-set the
corresponding time-step is dt = ds/ max |un |.
In the Eulerian approach to the free surface problems the surface tension force must be smeared out to a
volume force within a narrow band from the interface. The transformation is achieved by using a regularized
delta function, Z Z
σκ dΓ = σκδ(φ)∇φ dΩ, (32.9)
Γ Ω
where σ is the surface tension coefficient and κ the curvature of the interface given by

∇φ
κ=∇· . (32.10)
|∇φ|

In the finite element approach the force cannot be estimated directly since it involves three derivatives of the
level-set function. Therefore we must solve an additional equation for the curvature κ,

κ − cκ ∇2 κ = ∇ · ∇φ̃. (32.11)

Here cκ is an ad hoc diffusion coefficient that may be used to smooth the resulting curvature field. Otherwise
the sharp corners may result to very large peak values of the curvature. The weak formulation of the above
equation introduces surface fluxes which are evaluated from the normal derivatives of the level-set function.
Once the level-set function and the corresponding curvature have been computed the surface tension may be
applied as a volume force in the flow equations.

32.3 Keywords
LevelSetSolver
This subroutine uses the finite element method to solve the equation (32.1). The implementation is valid in
2D, 3D and axisymmetric problems.

Solver solver id

Equation String "Level Set Solver"

Procedure File "LevelSet" "LevelSetSolver"
The subroutine for advecting the level-set function.
Variable String "Surface"
The name of the level-set function. This may be chosen freely as long as it is used consistently
elsewhere.
Stabilize Logical
Either stabilization or bubbles are used to solve the convection problem. This flag enforces the
stabilization on.
Material mat id

LevelSet Velocity i Real

The velocity field that advects the level-set function. In 2D i=1,2 and in 3D i=1,2,3. This
may be a constant field or also something computed with the Navier-Stokes solver.
Body Force bodyforce id

LevelSet Flux Real

The flux (i.e. the normal velocity) of the level-set function.

CSC – IT Center for Science

32. Level-Set Method 188

LevelSetDistance
This solver uses the geometric information to compute the signed distance and, if desired, to advect the
zero level-set at the same time. This solver does not solve an equation and hence it does not need to have a
variable of its own. The solver is limited to 2D and axisymmetric cases.

Solver solver id
Equation String "Level Set Distance"
Procedure File "LevelSet" "LevelSetDistance"
The subroutine for renormalizing (and advecting) the level-set function.
LevelSet Variable String "Surface"
This keyword should refer to the name of the level-set variable that is used to advect the field.
The default is Surface.
Exported Variable 1 String "Surface"
In case the level-set variable does not exist it must be introduced. This may be the case if this
subroutine is also used for advecting the level-set function.
LevelSet Convect Logical
Whether to also convect the level-set function. Default is False.
Extract Interval Integer
When this function is used to extract the zero level-set function the user may choose the interval
how often this is done. The default is one. Just extracting the level-set may be useful if one just
wants to save the zero level-set without activating reinitialization.
Reinitialize Interval Integer
When this function is used to reinitialize the level-set function the user may choose the interval
how often this is done. The default is one but often this results to excessive smoothening of the
level-set field. If reinitialization is asked the zero level-set will also be automatically extracted.
Reinitialize Passive Logical
If this keyword is set True the reinitialization is not applied to the level-set field. The field is
only used to extract the zero level-set and compute the corresponding signed distance but this
information is not used to change the original field.
Narrow Band Real
In case that also the convecting is done by this solver there is the possibility to introduce a
narrow band which gives the distance at within the level-set function is recomputed. Default
is ∞. Typically this should be larger that the level-set bandwidth α used to evaluate surface
integrals.
Filename File
The zero level-set may also be saved. It consists of a number of line segments that are defined
elementwise. The results from the file may be used for visualization, for example, in MatLab. If
no filename is given the zero level-set is not saved.
File Append Logical
If the above is given this flag enforces the results to be appended on the same file rather than
writing over the old results.

Material mat id
LevelSet Velocity 1 Real
LevelSet Velocity 2 Real
If also convection is accounted in this solver the convection field is given by the above expres-
sions. Currently it is not possible to give the desired surface flux as it is not uniquely defined for
the line segments having different normals even at the same point.

CSC – IT Center for Science

32. Level-Set Method 189

LevelSetIntegrate
This subroutine computes the integrals (32.5) and (32.6). In addition of computing volume and surface
integrals this subroutine may also be used to set the absolute level of the level-set function so that volume is
conserved using equation (32.8). The implementation is valid in 2D, 3D and axisymmetric problems.

Solver solver id
Equation String Level Set Integrate
Procedure File "LevelSet" "LevelSetIntegrate"
The subroutine for computing the integrals.
LevelSet Variable String "Surface"
This keyword gives the name of the level-set function used for computing the integrals. The
default is Surface.
LevelSet Bandwidth Real
When computing the values over the domain the interface is treated a with smooth functions.
How smooth the functions are depends on the value of this keyword. Typically the bandwidth
should be such that the interface is extended over a few elements.
Conserve Volume Logical
The volume in the level-set formulation is not conserved by construction. To that end the level
of the level-set function may be tuned so that conservation is enforced. The default is False.
Conserve Volume Relaxation Real
If conservation is enforced it may be done only partially as there are inaccuracies in the evalua-
tion of the volume integrals. The default is one.
Initial Volume Real
If conservation is enforced the target volume is given by this keyword. Otherwise the volume
from the first timestep is used as the target value.

LevelSetCurvature
This solver computes the value of the curvature give the level-set function using equation (32.11).

Solver solver id
Equation String Level Set Curvature
Procedure File "LevelSet" "LevelSetCurvature"
The subroutine for computing the curvature.
Variable String "Curvature"
The name of the curvature variable.
LevelSet Variable String "Surface"
This keyword gives the name of the level-set function used for computing the integrals. The
default is Surface.
Curvature Diffusion Real
Artificial diffusion may be used to control the singularities of the curvature field around sharp
corners. The default is zero.
Curvature Coefficient Real
A constant that is used to multiply the curvature field before the solver is exited. This may be
used for example to change the sign of the curvature if the material of interest is on the outside
and not an the inside.
LevelSet Bandwidth Real
The delta function for the volume force may be applied to the curvature field also within this
solver directly. This has the disadvantage that the evaluation is done at nodal points rather than

CSC – IT Center for Science

32. Level-Set Method 190

at the integration points. However, if the flow solver used may not be modified this may be the
best alternative. If this keyword does not exist, no delta function is used to filter the curvature
field.
Boundary Condition bc id

Levelset Curvature BC Logical

The weak formulation of the curvature computation results to boundary integrals that should be
set at all surfaces where the curvature is computed.

LevelSetTimestep
The solution of the level-set function is accurate only if the timestep is limited so that the local Courant
number along the zero level-set is in the order of one or smaller. A tailored function for setting the timestep
is given in this module. This solver assumes that the level-set variable is named Surface and that this
variable is related to some solver. The velocity needed for setting the timestep should be given by the
keywords LevelSet Velocity i, where i=1,2,3.

Simulation
The function call and the needed parameters reside in the Simulation block of the command file.

Timestep Function
Real Procedure "LevelSet" "LevelSetTimestep"

LevelSet Courant Number Real

This keyword gives the desired Courant number of for the level-set solvers. The default for the
desired Courant number is one.
LevelSet Timestep Directional Logical
If the timestep limit is active this option may be used to account only the normal direction of the
interface velocity rather that the absolute direction. Default is False.

Other solvers
Basically the user may give user defined material parameters where the values are computed as a function of
the level-set function. Unfortunately this approach generally uses nodal points for the smearing whereas it
is optimal to use the Gaussian integration points for doing this. There is one exception to this model that has
been implemented for the MaterialModels module, namely the viscosity may be computed at Gaussian
integration points.

Material mat id
Viscosity Model String levelset
This uses the level-set methodology to smear out the viscosity between inside and outside values.
Viscosity Real
The value of the viscosity outside the domain (negative level-set function values).
Viscosity Difference Real
The difference between the inside and outside viscosity values.
Levelset bandwidth Real
The bandwidth at which the viscosity is smeared out between the extreme values.

CSC – IT Center for Science

Model 33

Kinematic Free Surface Equation with

Limiters

Module name: FreeSurfaceSolver

Module subroutines: FreeSurfaceSolver
Module authors: Thomas Zwinger, Peter Råback, Juha Ruokolainen, Mikko Lyly
Document authors: Thomas Zwinger

33.1 Introduction
Flows with a free surface are to be found in geophysical as well as technical applications. On large scale
flows the free surface usually is governed by a kinematic boundary condition given as a partial differential
equation. This equation then is solved on the specific boundary in combination with the (Navier)-Stokes
equation and the mesh update solver.

33.2 Theory
The implicit equation describing the free surface is given by

F (~x, t) = z − h(x, y, t), (33.1)

with the explicit position of the free surface h(x, y, t). Mass conservation implies that, with respect to the
velocity of the surface, ~um , F has to define a substantial surface, i.e.,

∂F
+ ~um ∇F = 0. (33.2)
∂t
The net volume flux through the free surface then is given by the projection of the difference between the
fluid velocity at the free surface, ~u and the velocity of the free surface with respect to the surface normal

a⊥ = (~um − ~u) · ~n. (33.3)

In Geophysical context (e.g., Glaciology), a⊥ often is referred to as the net accumulation. With the surface
unit normal defined as
∇F
~n = , (33.4)
k∇F k
this leads to
∂F
+ ~u∇F = −k∇F ka⊥ . (33.5)
∂t

CSC – IT Center for Science

33. Kinematic Free Surface Equation with Limiters 192

Using the definition in (33.1), (33.5) can be rewritten in its explicit form
"  2  2 #1/2
∂h ∂h ∂h ∂h ∂h
+u +v −w = 1+ + a⊥ , (33.6)
∂t ∂x ∂y ∂x ∂y

with the components of fluid velocity vector at the free surface given as ~u = (u, v, w)T . The variational
formulation of (33.6) reads as
 
Z   Z  "  2  2 #1/2
∂h ∂h ∂h ∂h ∂h 
+u +v ϕ dV = w+ 1+ + a⊥ ϕ dV, (33.7)
∂t ∂x ∂y  ∂x ∂y 
Ω Ω

where the occurrence of h in the right hand side is inserted from the previous time-step/non-linear iteration,
hence linearizing the equation. In case of a horizontally moving mesh, the contribution in form of an arbitrary
Lagrangian-Eulerian (ALE) formulation has to be included (by default is is omitted). With the horizontal
mesh velocity components, umesh and vmesh , the ALE version of equation (33.6) then reads
"  2  2 #1/2
∂h ∂h ∂h ∂h ∂h
+ (u − umesh ) + (v − vmesh ) −w = 1+ + a⊥ , (33.8)
∂t ∂x ∂y ∂x ∂y

33.2.1 Limiters
In certain cases the free surface is constrained by an upper hmax (x, y, t) and/or a lower hmin (x, y, t) limit.
For instance, the free surface of a fluid contained in a vessel cannot penetrate the vessel’s walls. This adds
the constraint
hmin ≤ h ≤ hmax (33.9)
to (33.7) converting the variational formulation into a variational inequality. In order to obtain a with (33.9)
consistent solution a method using Dirichlet constraints within the domain is applied. The exact procedure
is the following:
1. construct the linear system: Ah = f , with the system matrix A and the solution vector h on the
left-hand side and the force vector f on the right hand side
2. set nodes as active if (33.9) is violated
3. for active nodes the matrix and force vector are manipulated such that effectively a Dirichlet condition
h = hmax/min is applied
4. the manipulated system is solved: Ãh̃ = f˜
5. a residual is obtained from the un-manipulated system: R = Ah̃ − f
6. an active node is reset if the residual is R < 0 (for lower limit) and R > 0 (for upper limit)
The whole algorithm is iterated (within the non-linear iteration loop) until the limit given in Nonlinear
System Convergence Tolerance is reached. In the converged solution the residual represents the
needed accumulation/volume flux (on matrix level, hence not in physical units) needed in order to obtain the
limited solution. Consequently, the system not necessarily is volume conserving if the Dirichlet method is
applied. As the solver in principle works with second order elements, the limitation procedure only converges
with only the between elements shared nodes being subject to the algorithm described in this section. This
is done automatically by the code.

33.3 Constraints
The code only works in Cartesian coordinates and – by the nature of the differential equation – effectively
converges only in a transient simulation. Although, technically, it also can be run in steady state simulations.

CSC – IT Center for Science

33. Kinematic Free Surface Equation with Limiters 193

33.4 Keywords
Solver solver id
Equation String "Free Surface Limited"
Variable String Varname
The change in the free surface coordinate. This may be of any name as far as it is used consis-
tently also elsewhere, as Varname is used as a preceding keyword for the exported variable of
the residual, as well as for the accumulation
Variable DOFs Integer 1
Degrees of freedom for the free surface coordinate.
Procedure File "FreeSurfaceSolver" "FreeSurfaceSolver"
The following four keywords are used for output control.
Velocity Implicitness Real
Determines the level of implicitness in the velocity field. Values shall be in the interval cv ∈
[0, 1]. The velocity is interpolated between the current and the previous time level such that
u = (1 − cv ) un−1 + cv un . Thus, unity corresponds to complete implicitness (default).
Maximum Displacement Real
This limits the maximal local displacement in a time-step. If exceeded, relaxation automatically
is applied in order to limit the displacement.
Apply Dirichlet Logical
Takes the variational inequality method (here referred to as Dirichlet method) into use. The user
should be aware that if the method is applied (value True) this implies setting the Nonlinear
Max Iterations to a value large enough for the method to converge. The default value is
False.
ALE Formulation Logical
If set to True, the mesh horizontal mesh velocity is taken into account in the convection term.
The default value is False.
Relaxation Factor Real
The changes in the free surface may be relaxed. The default is no relaxation or value 1.0
Stabilization Method String
Sets stabilization method. Either Stabilized or Bubbles can be set.
Nonlinear System Convergence Tolerance Real
This keyword gives a criterion to terminate the nonlinear iteration after the maximum change in
the free surface coordinate is small enough

max ||dR/(R − R0 )|| < 

where  is the value given with this keyword.

Exported Variable 1 String
The residual, which is the essential property in solving the variational inequality has to be given
as an exported variable. The name is fixed by the variable name Varname given in the Solver
section plus Residual. For instance, if the variable is named FreeSurf, the exported vari-
able is expected to be FreeSurf Residual.
Exported Variable 1 DOFs Integer
As the free surface is a scalar, the value has to be set to 1.
Use Linear Elements Logical
If set to true, forces usage of linear element types despite the order of the mesh. Mind, that in
case of limited elements, by default linear elements are used. The default value is False.
Equation eq id

CSC – IT Center for Science

33. Kinematic Free Surface Equation with Limiters 194

Convection String
The type of convection to be used: None (default), Computed, Constant. In the last case,
the keyword Convection Velocity is expected to be found in the Material section.
Body Force bf id

Varname Accumulation Real

sets the value for the normal accumulation/volume flux, a⊥ for the variable name varname. If
this keyword is set, the following keyword Varname Accumulation Flux is ignored (as
those are excluding)
Varname Accumulation Flux i Real
sets the accumulation flux in Cartesian components (i = 1,2,3 in 3-dimensional problem). The
resulting vertical flux then is evaluated using the surface normal.
Initial Condition ic id
Varname Real
Initiation of the free surface variable (sets initial shape of surface)

Boundary Condition bc id
Body ID Integer
usually, the solver is run on a lower dimensional boundary of the model. Then a separate body-
id has to be defined and all component of the solver (Equation, Body Force, Equation,
Initial Condition and Material) defined accordingly.
Varname Real
Dirichlet condition of the free surface variable (makes really sense only on dimension - 2 bound-
aries, e.g. lines in case of a three dimensional run)
Mesh Update i Real
usually, the free surface evolution should have a feedback on the domain’s geometry. This usually
is achieved by running the MeshUpdate Solver and linking the variable of the free surface with
the corresponding component of the Mesh Update (i=1,2,3). For instance, in a 3-dimensional
case with the variable name FreeSurf this could read as: Mesh Update 3 = Equals
FreeSurf

CSC – IT Center for Science

Model 34

Free Surface with Constant Flux

Module name: FreeSurfaceReduced

Module subroutines: FreeSurfaceReduced
Module authors: Peter Råback
Document authors: Peter Råback

34.1 Introduction
The determination of free surface is often an essential part of solving a fluid dynamics problem. Usually the
surface is found by solving a free surface equation resulting from force balance, or by finding the free surface
from zero flux condition. In some extreme cases both of these methods were found to fail and therefore an
alternative approach was taken. The method can only be applied to stationary 2D or axisymmetric flows
where the total flux is conserved. This is the case, for example, in many coating and drawing processes.

34.2 Theory
The determination of the free surface takes use of the conservation of mass. If the flow is stationary the mass
flux through all planes cutting the flow must be same. In the following we concentrate on the axisymmetric
case which has more applications than the 2D case.
In the axisymmetric case the mass flux is obtained from
Z R
f (R, z) = (~u · ~n) rds. (34.1)
R0

The free surface is set by finding a surface profile R(z) such that the integral is constant for all nodes on the
surface, or
f (R, zj ) = f (R1 , z1 ) ∀j ∈ [1, M ]. (34.2)
Note that the factor 2π has been consistently omitted since it has no bearing to the shape of the free surface.
The subroutine uses simple heuristics to determine the direction of the flow on the free surface. The first
upwind node z1 on the free surface is assumed to be fixed and the corresponding flux is f1 . The new radius
is set approximately by assuming that the added or removed flow has the same velocity as the velocity on
the surface. Then the corrected radius is found from

un R(m) dRm = f (R(m) , z) − f (R1 , z1 ) (34.3)

or
f (R(m) , z) − f (R1 , z1 )
R(m+1) = R(m) + . (34.4)
un R(m)

CSC – IT Center for Science

34. Free Surface with Constant Flux 196

After the new profile is being found the element nodes are moved to the new positions. The nodes that are
not on the surface may be mapped in many different ways. The straight-forward strategy is to use linear 1D
mapping. Also more generic 2D mapping may be used.
The free surface and the fluid flow must be consistent and therefore the system must be solved iteratively.
When convergence of the coupled system has been obtained the suggested dR vanishes and the free surface
solver does not affect the solution.
Sometimes the free surface solver overshoots and therefore it may be necessary to use relaxation to
suppress the large changes of the solution.
Note that the free surface solver is simple based on mass conservation. No forces are applied on the free
surface. If surface tension needs to be taken into account it may be done while solving the Navier-Stoke
equation.

34.3 Applicable cases and limitations

The method has some limitations which are inherent of the method:
• Limited to steady-state simulations.
• Limited to 2D and axisymmetric cases.

• If there is back-flow within the free surface flow the correctness of the solution is not guaranteed.
Some limitations result from the current implementation:
• The free surface must be oriented so that the flow is on its negative side.
• There may be several free surfaces of this type but they must be directed the same way.

• The line integral from R0 to R may cause some difficulties in unstructured meshes. Therefore struc-
tured meshes are favored.
• At the moment density is assumed to be constant and therefore only incompressible fluids may be
considered.

34.4 Keywords
Solver solver id
Equation String "Free Surface Reduced"
Variable String dx
The change in the free surface coordinate. This may be of any name as far as it is used consis-
tently also elsewhere.
Variable DOFs Integer 1
Degrees of freedom for the free surface coordinate.
Procedure File "FreeSurfaceReduced" "FreeSurfaceReduced"
The following four keywords are used for output control.
Perform Mapping Logical
If this keyword is True the coordinate mapping is done locally by using linear 1D mapping.
This is also the default. Also 2D mapping is possible by using a separate mesh update solver.
Then the keyword should be set to False.
Nonlinear System Relaxation Factor Real
The changes in the free surface may be relaxed. The default is no relaxation or value 1.0

CSC – IT Center for Science

34. Free Surface with Constant Flux 197

Nonlinear System Convergence Tolerance Real

This keyword gives a criterion to terminate the nonlinear iteration after the maximum change in
the free surface coordinate is small enough

max ||dR/(R − R0 )|| < 

where  is the value given with this keyword.

Boundary Condition bc id
Free Surface Reduced Logical
Must be set to True for the free surface when the solver is used. The boundary must be simply
continuous.
Free Surface Number Integer
If more than one free surface of the reduced type is present simultaneously they must somehow
be separated. This keyword is for that purpose. The surfaces should be ordered from 1 to the
number or free surfaces. Value 1 is also the default if the surface is active. Note that free surfaces
with different numbers should be aligned the same way and should not touch each other.
Free Surface Bottom Logical
If this flag is free it sets the lower boundaries of integration when solving for the free surface.
Note that this surface should not touch any of the free surfaces. A free surface is automatically a
lower boundary for another free surface.

If mapping is not performed within the solver also boundary conditions for the mapping are required.
Surface tension may be taken into account while solving the Navier-Stokes equation. The proper
keywords for activating the surface tension are explained in the manual of the Navier-Stokes solver.

CSC – IT Center for Science

Model 35

Particle Dynamics

Mdule name: ParticleDynamics

Module subroutines: ParticleDynamics
Module authors: Peter Råback, Juha Ruokolainen
Document authors: Peter Råback

35.1 Introduction
Note: this is an initial version of the dynamic particle tracker. For real applications it probably requires some
additional effort.
The ability to follow single or statistical particles within a finite element can be used in a variety of appli-
cations. A common application is to follow particles along streamlines for the purpose of flow visualization.
Accounting for electrostatic forces opens the field to microfluidics and accounting for the gravitational force
enables applications in sedimentation, for example. If also particle-particle interaction is accounted for also
granular flow phenomena may be studied.
This module depends on the many library routines related to particle transport in Elmer. In this module
it is assumed that there may be particle-particle interactions. This choice fixes the time-stepping strategies
of the different particles together, at least without heroic timestepping schemes. In other words, the same
timestep size is applied to the whole particle set.
The particles are located in the finite element mesh using a marching routine where intersections with
element boundaries are checked for. The nearest boundary on the way is crossed until there is no boundary
to cross. Then the right element has been reached. The algorithm is fast when the stepsize with respect to
elementsize is smaller or of the same order. Therefore for the initialization the octree-based search may be
more economical and also more robust regarding geometric shapes.
The particle-particle interaction is based on the knowledge of nearest neighbours. Currently the neigh-
bours are determined using the closeness to the nodes if the parent element. This means that the interaction
distance needs to be smaller than h/2 where h is the mesh parameter. Further, it means that the mesh must
be rather uniform.
As the name implies, this module assumes the particles to be dynamic i.e. they have an acceleration.
However, the user may also use the module neglecting the inertial forces and requiring a force balance
between the drag force and external forces.

35.2 Theory
Forces acting on the particle
Assume that we have a particle in position ~r. The corresponding velocity is
d~r
~v = (35.1)
dt

CSC – IT Center for Science

35. Particle Dynamics 199

Newton’s second law yields

d~v
m = Σf (~r, ~v , . . .) (35.2)
dt
where a number of different forces may be considered.
The gravity force acting on the particle is

f~ = m~g , (35.3)

where ~g is the acceleration due to gravity. The electrostatic force is simply proportional to the electric field

f~e = q E
~ = q∇φ (35.4)

where q is the electric charge.

The viscous fluids cause also a force that acts on the particle

f~S = −b(~v − ~v0 ) (35.5)

where ~v0 is the velocity of the fluid. If the change is estimated to be d~r then the estimate may be improved
by the gradient of velocity, i.e. ∇~v0 · d~r. For Stokes flow the proportionality coefficient scales with viscosity,
for example for spheres b = 6πηd where η is the fluid viscosity and d the radius of the sphere.

Collision model
Two particles may collide with one-another. Assume that the initial particle positions are ~r1 and ~r2 . Velocity
vectors are ~v1 and ~v2 and lets define δ~r = ~r1 − ~r2 and δ~v = ~v1 − ~v2 . Now the condition for a collision is

|δ~r + δ~v dt| = R1 + R2 . (35.6)

This leads to condition for the timestep

√
−b − b2 − ac
dt = (35.7)
a
where b = δ~r · δ~v , a = δ~v · δ~v , and c = δ~r · δ~r − (R1 + R2 )2 . Collision happens if 0 < dt < Dt.
The collision only affects the normal component. The normal vector is aligned with δ~r0 = δ~r + dt δ~v
i.e. ~nr = ~r0 /|~r0 |. Now the normal velocity components are vi,n = ~vi · ~nr . After the collision the normal
velocity component is
0 cM2 (v2,n − v1,n ) + M1 v1,n + M2 v2,n
v1,n = (35.8)
M1 + M2
0
and likewise for v2,n . Here the parameter c is called bounciness and it varies between zero, for fully inelastic
collision, to one, for fully elastic collisions. The new velocity is now

~vi0 = ~vi + (vi,n

0
− vi,n )~nr (35.9)

and the new position,

~ri0 = ~ri + ~vi dt + ~vi0 dt0 (35.10)
where dt0 = Dt − dt.
Collisions with the wall are governed with the same equations assuming that mass of the wall is infinite.
The change in the velocity and coordinate position may be mutated to a change in velocity and force.
This way the collision model is better additive with the other type of models present in the system.

CSC – IT Center for Science

35. Particle Dynamics 200

Contact model
In general the contact between particles depends on their relative position, relative velocity, and relative
angular velocity. Generally the contacts should include some damping (negative feedback from velocity)
since otherwise the system is prone to flow up. In molecular dynamics, for example, also interaction with
more than two particles should be considered. The current treatment is quite limited and we here assume
that the contact results just to a spring force in the form
f~k = k max(R1 + R2 − |d~r|, 0)~nr , (35.11)
where k is the spring coefficient.
A similar particle contact model may be present with the wall but possibly with different value for the
spring coefficient.

Periodic boundary conditions

It is relatively straight-forward to implement periodic boundary conditions for rectangular and hexahedral
type of geometries. And for different geometries the periodic conditions seems more unlikely.

Time evolution
For particles with mass the basic update sequence of velocity and position is
dt
~vi+1 = ~v + Σf (35.12)
m
~ri+1 = ~r + dt~vi+1 (35.13)
while for massless particles it is assumed that the particle drag is in balance with the other forces given
explicitly
1
~vi+1 = Σf (35.14)
b
~ri+1 = ~r + dt~vi+1 (35.15)
The timestep dt may be given explicitly, or it may be defined from the characteristic velocity V . If the
change in distance dS is given then
dS
dt = , (35.16)
V
and when the Courant number C is given
h
dt = C , (35.17)
V
where V is either the maximum absolute velocity, or the mean absolute velocity.
Also other timestepping schemes could be used but that’s something for later.

35.2.1 Postprocessing
The possibility to use each particle as an integration point in data fitting problem makes it possible to couple
the particles back to a continuous field. The following kinds of information could be abstracted from the
particles, for example.
Kinetic energy of particles
1
Ek = mv 2 . (35.18)
2
Potential energy associated to gravity field
Eg = m~g · ~r. (35.19)
Potential energy associated to electrostatic field The corresponding potential energy is
Ee = qφ. (35.20)
Etc. In practice sufficient amount of data may not be present at every node if the data is used only after
appropriate smoothing.

CSC – IT Center for Science

35. Particle Dynamics 201

35.3 Keywords
Solver solver id
Equation String [ParticleDynamics]
The name of the equation.
Procedure File "ParticleDynamics" "ParticleDynamics"
The name of the procedure.

Keywords related to the allocation and initialization of the particles.

Number of Particles Integer
Number of particles to be sent. The number may be given by this keyword as an absolute number.
Often a relative number, particularly in parallel computation, may be favorable.
Particle Node Fraction Real
The relative fraction of particles to nodes. The nodes may also be masked ones.
Particle Element Fraction Real
The relative fraction of particles to elements. The elements may also be masked ones.
Coordinate Initialization Method String
Initialization method for the coordinates. The options include nodal ordered, elemental
ordered, sphere random, box random, box random cubic with their own initial-
ization strategy.
Initial Coordinate Size n, dim; Real
The default initialization methods for coordinates.
Initialization Condition Variable String
If this is given then the particles are initialized only where this has a nonzero permutation vector.
Initialization Mask Variable String
If this is given then the particles are initialized only in elements or nodes where the variable has
a positive value.
Min Initial Coordinate i Real
Max Initial Coordinate i Real
For box initialization methods set the bounding box for doing initialization.
Particle Cell Radius Real
If the initialization method is box random cubic then the particle is always put to a unit cell
located in the given bounding box.
Particle Cell Fraction Real
If the initialization method is box random cubic then this keyword gives the fraction of
filled cells in the initial configuration.
Initial Sphere Radius Real
If the initialization method is sphere random then this set the radius of the sphere.
Initial Sphere Center Size 3; Real
Sets the size of the initial sphere center.
Velocity Initialization Method String
There are many ways to initialize the velocities of the particles: thermal random, even
random, constant random.
Initial Velocity Size n, dim; Real
The particle velocities may be also initialized only by this keyword, or this may be used to give
a bulk component to the otherwise random velocity field.
Initial Velocity Amplitude Real
In many velocity initialization methods an initial velocity amplitude is needed.

CSC – IT Center for Science

35. Particle Dynamics 202

Initial Velocity Time Real

When initializing the velocity also the initial coordinates may be affected by determining a offset
for the time used to advance the particles. This could be used, for example, to distribute the
particles from an initial point using the random velocity field.
Initial Coordinate Search Logical
After the initialization is done do an initial octree-based search for the initial coordinate posi-
tions. This is applicable only to serial problems.
Reinitialize Particles Logical
Reinitialize the particles in the start of each time when the subroutine is called. This would make
sense in some kind of scanning mode. The default is False.
Particle Release Number Integer
If not all particles are sent at the same time. This is the absolute number of particles sent at the
start of the subroutine call.
Particle Release Fraction Real
If not all particles are sent at the same time. This is the fraction of particles sent at the start of
the subroutine call.
Delete Wall Particles Logical
Currently a hack which is used to remove particles sitting on the wall which otherwise seem to
get stuck.

Keywords related to the timestepping strategy.

Timestep Size Real
The internal timestep size.
Max Timestep Size Real
The lower limit of the internal timestep size.
Min Timestep Size Real
The upper limit of the internal timestep size.
Timestep Distance Real
The distance that is travelled within one timestep based on the characteristic velocity.
Timestep Courant Number Real
The desired Courant number resulting from the timestep based on the characteristic velocity.
Note that currently just one element is used to compute the parameter h. A global definition of
the Courant number would result to a significant increase in the computational cost.
Max Characteristic Speed Logical
When computing characteristic velocity use the max norm.
Max Timestep Intervals Integer
Maximum number of internal timesteps.
Max Cumulative Time Real
Maximum cumulative time within one call.
Simulation Timestep Sizes Logical
Alternatively, one may use the timesteps as defined by the Timestep Sizes of the Simulation
section.

Keywords related to the actual physical interaction models chosen within the particles and with particles
and walls.
Particle Particle Collision Logical
Is there some collisions between particles.
Particle Particle Contact Logical
Is there contact between particles resulting to additional forces.

CSC – IT Center for Science

35. Particle Dynamics 203

Box Particle Periodic Logical

Is the system periodic.
Box Periodic Directions Integer
If not all directions require the periodic model this may be used to define the active directions.
Box Particle Collision Logical
Is there collisions between particles and 2D or 3D box. This provided for a cheaper treatment of
BCs than the generic way.
Box Particle Contact Logical
Is there contact between particles and walls resulting to additional force.
Box Contact Directions Integer
If not all directions require the contact model this may be used to define the active directions.
Velocity Variable Name String
Name of the variable if velocity drag is present.
Velocity Gradient Correction Logical
When using the drag model evaluate the drag forces using correction from the velocity gradient.
Potential Variable Name String
Name of the variable if electrostatic potential is present.
Velocity Condition Variable Name String
Name of the field which determines the fixed velocity conditions of the particles.
Coordinate Condition Variable Name String
Name of the field which determines the fixed coordinate conditions of the particles.

Keywords related to the physical properties of the particle and to the joint physical properties of the
particle-particle and particle-wall contacts.
Particle Mass Real
There are a number of particle properties needed in different interaction models and particle mass
is one of them. In principle these could be altered to be variables but currently they are assumed
to be the same for all particles.
Particle Radius Real
The particle raidus used in particle-particle interaction, and in evaluating the density of the par-
ticle.
Particle Gravity Logical
Should gravity be accounted for. If yes, use the gravity defined in the
Particle Lift Logical
The background fluid has a density that results to a lift (buoyancy) that may be accounted for.
Should gravity be accounted for. If yes, use the gravity defined in the Constants section.
Particle Damping Real
Particle damping proportional to velocity only.
Particle Drag Coefficient Real
Particle drag coefficient in fluid field.
Particle Bounciness Real
Defines, when particles collide is the collision totally elastic or totally inelastic. Corresponding
extreme values are 1 and 0. This relates only to collision models.
Particle Spring Real
Spring constant in the force model between particles. This relates only to contact models.
Particle Charge Real
The electric charge of the particle.

CSC – IT Center for Science

35. Particle Dynamics 204

Particle Decay Distance Real

The decay of the particle effect.
Wall Particle Radius Real
In interaction with the walls different properties are given as the interaction with the wall is quite
different regarding, for example, the contact shape.
Wall Particle Spring Real
Spring constant in interaction with wall.
Wall Particle Bounciness Real
Elasticity of collision with interaction with the wall.

Keywords related to the generation of fields from the particle data.

Particle To Field Logical
Is there any coupling from particles to field needed? This leads to the need of finite element
machinery. The opposite is always assumed to be true i.e. the particles are always assumed to be
located in the FE mesh.
Reinitialize Field Logical
When revisiting the solver should the particle field be initialized at the start.
Particle To Field Mode Integer
If a field is generated from the particles, what actually should be computed.
Particle Decay Time Real
This is an optional parameter that represents the characteristic time that is used to forget history
data from the particle to field representation.
Particle Decay Distance Real
This is an optional parameter that represents the characteristic distance that is used to forget
history data from the particle to field representation.

Keywords related to saving and echoing information. No effect to the actual computations.
Output Interval Integer
The internal output interval of the solver. If not given the particle data will be saved within the
solver. The alternative is to save particle data with an external solver.
Output Format String
Output format which may be either table or vtu.
Table Format Logical
Vtu Format Logical
Alternative way of giving the output format. Has the nice property that several formats may be
given at the same time.
Filename Prefix String
The prefix of the filename used for saving. Depending on the chosen format an appropriate suffix
is attached to the prefix.
Filename Particle Numbering Logical
If possible in the format, use particle indexes for the numbering of files.
Filename Timestep Numbering Logical
If possible in the format, use timestep indexes for the numbering of the files. This is the default
in vtu format.
Particle Info Logical
Optionally print out on the screen information on the number of particles and time steps taken.
Statistical Info Logical
Optionally print out on the screen some statistical information on the coordinate positions and
velocities. May be useful for debugging purposes, for example.

CSC – IT Center for Science

35. Particle Dynamics 205

Scalar Field i String

The scalar fields of the particles to be saved in vtu format. Currently options include distance
and dt.
Vector Field i String
The vector fields of the particles to be saved in vtu format. Currently options include velocity
and force.
Particle Save Fraction Real
If there is a huge number of particles it may be sufficient to use only a subset of them for
visualization. This keyword gives the fraction.
Boundary Condition bc id

Wall Particle Collision Logical

This activates the collision model between particles and generic boundaries.
Particle Accumulation Logical
An optional flag that activates the possible destruction of the particles at the boundary in case
conditions for accumulation are met.
Particle Accumulation Max Speed Real
If this critical speed is given, then accumulate only those particles with smaller velocity.
Particle Accumulation Max Shear Real
If this critical shear rate is given, then accumulate only those particles with a smaller shear rate.
Particle Trace Logical
If this flag is set active then use the accumulated particles to compute a trace to a finite element
field.
Moving Wall Logical
The movement of the wall may be accounted for in the wall-particle collision model.

CSC – IT Center for Science

Model 36

Semi-Lagrangian Advection Using

Particle Tracking

Module name: ParticleAdvector

Module subroutines: ParticleAdvector
Module authors: Peter Råback, Juha Ruokolainen
Document authors: Peter Råback

36.1 Introduction
This solver utilizes the particle tracker features of Elmer to advect scalar fields diffusion-free on the mesh.
For each node of the field one particle is sent backwards in time and the field value is restored from the
location where the particle is found.
For more details on the particle tracking look at the other modules utilizing the same features in a more
generic way.

36.2 Theory
In particle advection we assume that the fields are transported diffusion-free carried by a velocity field ~v .
The particle are initialized at the nodes of the mesh. Thereafter each particle is followed −δt in time i.e. the
following integral is evaluated
Z −δt
~r = ~r0 + ~v dt. (36.1)
0
Currently the integral may be evaluated using first order explicit scheme or a second order Runge-Kutta
scheme. In the first order scheme a quadratic correction term is available making the scheme effectively
comparable with the Runge-Kutta scheme. There the following approximation is used
1
< ~v >= ~v0 + (∇~v0 ) · ~v0 dt. (36.2)
2
When the particles have been transported the field may be evaluated from
f (~r0 , t) = f (~r, t − δt) (36.3)
The treatment of boundaries results to some additional complication. It is assumed that if the particles
vanishes in the upstream boundary then the boundary values of f are used.
The particles may have some properties along the path integral. For this purpose the user may evaluate
evolution over time, Z
It = c(t) dt (36.4)

CSC – IT Center for Science

36. Semi-Lagrangian Advection Using Particle Tracking 207

and over distance, Z

Is = c(t) ds (36.5)

36.3 Parallel operation

The parallel operation of the particle advector routine is much more complicated than the serial. The particles
are followed in the partitioned mesh and if they pass the partition interface they are passed to the next
partition. Finally the values must be sent back to the originating partition in order to collect the results.
The 2nd order Runge-Kutta method will probably have problems in parallel so the user should rather
choose the quadratic correction method which offers similar accuracy.

36.4 Keywords
Solver solver id

Equation String [ParticleAdvector]

The name of the equation.
Procedure File "ParticleAdvector" "ParticleAdvector"
The name of the procedure.
Advect Elemental Logical
Should we advect the particles on center of elements instead of nodes. This is often more robust
as the velocity field is well defined within elements.
Advect DG Logical
Initilize particles at corners of DG elements with reduced size. This may also be more robust but
also significantly more costly.
Advect IP Logical
Initilize particles at integration points. May yield optimal accuracy with high computational cost.
Coordinate Initialization Method String
This is automatically enforced to nodal ordered.
Particle Node Fraction Real
This is automatically enforced to one in order to have one particle for each node.
Initialization Mask Variable String
If this is given then the particles are initialized only in nodes where the variable has a positive
value.
Reinitialize Particles Logical
Reinitialize particles after each time visiting the solver. This could be desired operation in tran-
sient simulation if we just want to advect for one timestep.
Velocity Initialization Method String
This is enforced to nodal velocity which means that the first velocity is taken from the
nodal point.
Velocity Variable Name String
Name of the velocity field in vector form. Default is flow solution.
Time Order Integer
This is defaulted to zero which means that the velocity field is used directly for the particle
velocity.
Timestep Size Real
There are several keywords related to the timestepping strategy. All of them are available also
here. The negative sign is added internally. Here just the most typical ones are given. This
keyword gives the internal timestep size.

CSC – IT Center for Science

36. Semi-Lagrangian Advection Using Particle Tracking 208

Simulation Timestep Sizes Logical

Alternatively, one may use the timesteps as defined by the Timestep Sizes of the
Max Timestep Intervals Integer
Maximum number of internal timesteps.
Max Integration Time Real
This keyword may be used to retire particles after following them long enough in time. This
may help to save some time if there are regions with almost zero velocities or closed circulation
loops.
Particle Accurate At Face Logical
When hitting the well this keyword enforces the more accurate integration method which returns
the correct point of exit. This is then used in the advection as the point of evaluation. When
using accurate particle detection the algorithms might not always be as robust.
Runge Kutta Logical
Use the 2nd order Runge-Kutta method for integration.
Velocity Gradient Correction Logical
This is an alternative way of increasing the accuracy of the integral. Here the gradient of the
velocity field is evaluated at the point of the particle to account for the curvature of the flow.
Source Gradient Correction Logical
This is a way to increase accuracy of the path integrals by evaluating the integrands c(t) and c(s)
using gradient correction over the step.
Variable i String
Names of the variables to be advected (i=1,2,3,. . . ). Any proper field variable of Elmer may be
advected. The field may exist in advance, if not it will be created There is also a group of in-
ternal variables with fixed name: particle status, particle number, particle
distance, particle coordinate, particle coordinate_abs, particle
velocity, particle velocity_abs, particle time, particle time integral,
and particle distance integral These are related to the particle tracking machin-
ery.
Result Variable i String
The default name of the advected variable is obtained by adding the prefix Adv to the field name.
Alternatively, the user may give the name of the result variable by this keyword.
Operator i String
Possible operator that may be applied to the variable. The choices are derivative (with re-
spect to time), difference, and cumulative. By default no additional operator is applied.
Norm Variable Index Integer
The solver may compute the change in one specific field value in order to provide information
for consistency check, or convergence monitoring. This keyword sets the index related to the
Variable i list. Default is zero i.e. no norm is computed.
Particle Info Logical
Show the particle information at the end of the solver execution.
Body Force bf id
Particle Distance Integral Source T
he integrands c(s) related to the distance path integral. Existence of this keyword will activate
also the path integral variable named Particle Distance Integral.
Particle Time Integral Source T
he integrands c(t) related to the time path integral. Existence of this keyword will activate also
the path integral variable named Particle Time Integral.
Particle Fixed Condition Real
We may want to freeze the particles on the body depending on the physics. This is done if this
condition has a positive value.

CSC – IT Center for Science

36. Semi-Lagrangian Advection Using Particle Tracking 209

Boundary Condition bc id
Particle Wall T
his will mark the wall which the particle cannot go though and by default stops at.
Particle Fixed Condition Real
We may want to freeze the particles on the boundary depending on the physics. This is done if
this condition has a positive value.

CSC – IT Center for Science

Model 37

Ordinary differential equation in

moving mesh

Module name: StructureFlowLine

Module subroutines: StructureFlowLine
Module authors: Peter Råback
Document authors: Peter Råback

37.1 Introduction
The purpose of this solver is to allow accurate solution of ordinary differential equations in moving mesh.
The approach is limited meshes that could be extruded being drawn to the direction of the extrusion. The
idea is that then in moving coordinates we have a direct correspondence between mesh parameter h, draw
velocity v and timestep dt, by dt = h/v.
All the equation could basically also be solved in an eulerien mesh where the velocity is presented as
convection term in the transport equation. The problem with this kind of approach is that such convec-
tion terms require some kind of stabilization schemes. In extreme cases when diffusion tends to zero such
equations easily become hard to solve. The current approach cannot consider diffusion. Only convection,
reaction and diffusion terms are possible.

37.2 Keywords
Solver solver id
Equation String MarchingOde
The name of the equation.
Procedure File "MarchingODESolver" "MarchingODESolver"
The name of the procedure.
Variable String
Name of the variable used for the marching.
Nonlinear System Max Iterations Integer
If the system is nonlinear we may solve it for each node until convergence or number of iterations
has been reached.
Nonlinear System Convergence Tolerance Real
Convergence tolerance if several iterations are used..
Draw Velocity Real
Speed of the drawing process in the direction of the extrusion.

CSC – IT Center for Science

37. Ordinary differential equation in moving mesh 211

Parabolic Model Logical

Really solve for u2 rather than u. This treatment may then be used to eliminate the nonlinear
nature of the problem.
Apply BCs Only Logical
We might want to apply the marching routine only at the surface.
Active Coordinate Integer
The drawing direction i.e. 1, 2 or 3. This is a keyword passed on to routines detecting extruded
structures, as are some of the following ones too.
Dot Product Tolerance Real
When determining the structure of the mesh in the active direction this tolerance is used to decide
that an element edge is aligned with the direction of the action.
Material bc id
Varname: Source Real
Source term for the field to be marched.
Varname: Reaction Coefficient Real
Reaction term for the field to be marched.
Varname: Time Derivative Coefficient Real
Time derivative term. If not given it is assumed to be unity.

CSC – IT Center for Science

 Part VII

Mesh Adaptation, Transformation and

Analysis

CSC – IT Center for Science

Model 38

Mesh Adaptation Solver

Module name: MeshSolve

Module subroutines: MeshSolver
Module authors: Juha Ruokolainen
Document authors: Juha Ruokolainen

38.1 Introduction
Moving boundaries are often encountered in different types of computations, e.g. in Fluid-Structure Inter-
action (FSI) problems. Moving boundaries pose the problem of mesh adaptation to the boundaries. With
this solver, instead of generating the whole mesh afresh when a boundary is moved, the current mesh nodes
are moved so that the mesh hopefully remains ’good’. This type of solution only applies to cases where
the changes in geometry are relatively small. It is, however, often cheaper in terms of CPU time to use this
module in contrast to regenerating the whole mesh.
For time dependent simulations the mesh deformation velocity is also computed. The name of this
variable is Mesh Velocity.

38.2 Theory
The equation for elastic deformation of the mesh, given displacement of the boundaries, may be written as

− ∇ · τ = 0, (38.1)

where the stress tensor τ can be expressed in terms of Lame parameters as

~ + λ∇ · dI.
τ = 2µε(d) ~ (38.2)

Here d~ is the mesh displacement field, µ and λ are the first and second Lame parameters, respectively, and I
is the unit tensor. The linearized strains are given as

~ = 1 ~ ~ T ).
ε(d) (∇d + (∇d) (38.3)
2
The Lame parameters in terms of Young’s modulus Y and the Poisson ratio κ read
Yκ Y
µ= , λ= . (38.4)
(1 − κ)(1 − 2κ) 2(1 + κ)

Note that in this context the values of the material parameters are fictional, and may be chosen to help
convergence or quality of the resulting mesh.

CSC – IT Center for Science

38. Mesh Adaptation Solver 214

38.2.1 Boundary Conditions

For each boundary a Dirichlet boundary condition

di = dbi (38.5)

may be given. Usually the displacement is given a priori or computed by, for example, the elasticity solvers.

38.3 Keywords
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere.
Equation String [Mesh Update]
The name of the equation. If different from the default name Mesh Update, then the following
two keywords must be defined as well.
Procedure File "MeshSolve" "MeshSolver"
Name of the solver subroutine.
Variable String
Name of the variable.
Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
Mesh Update Logical
If set to True, solve the mesh adaptation equations.
Material mat id
The material section is used to give the material parameter values. The following material parameters
may be set for the Navier equations.
Poisson Ratio Real
For isotropic materials the Poisson ratio must be given with this keyword.
Youngs Modulus Real
The elastic modulus must be given with this keyword.
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. Those related to the
Navier equations are
Mesh Update i Real
Dirichlet boundary condition for each displacement component i= 1, 2, 3. The boundary dis-
placement may be computed with some other solver. The computed displacement field may then
be used in the setting in the following way:
Mesh Update i Equals Displacement i
Including such lines with i=1,2,3 in the boundary condition setting will give the position of
the updated mesh on the boundary directly in terms of the solution of the displacement solver.

38.4 Examples
38.4.1 A Simple FSI computation using MeshSolver
In this simple computation Navier-Stokes equations are solved in the domain shown in the two pictures
below. On the left there is an inflow boundary, and on the right an outflow boundary. In the block inside the

CSC – IT Center for Science

38. Mesh Adaptation Solver 215

flow domain (the mesh is not shown for the block), the elasticity equations are solved. The block is fixed at
the bottom, and is otherwise deformed by the fluid pressure and flow fields. The whole system is iterated as
follows:
• Solve fluid flow,

• Solve deformation of the block,

• Solve the fluid domain mesh with MeshSolver according to the displacements of the block,
until convergence is obtained.

Figure 38.1: The original computational mesh (up), and the mesh of the converged solution (down) of a FSI
computation.

CSC – IT Center for Science

Model 39

Nonphysical Mesh Adaptation Solver

Module name: NonphysicalMeshSolve

Module subroutines: MeshSolver
Module authors: Juha Ruokolainen, Peter Råback
Document authors: Juha Ruokolainen, Peter Råback

39.1 Introduction
This solver is a variation of the MeshSolver for cases where the true mesh velocity is not of concern and
more liberties can be used in the mesh adaptation. Also it may be used as the mesh adaptation solver in
conjunction with MeshSolver. For example, in shape optimization of fluid-structure interaction problems
two mesh adaptation solvers may be needed simultaneously.

39.2 Theory
For the equation to be solved look at the theory section of the MeshSolver. In addition to that, also weak
ways of giving boundary conditions is implemented, namely

τ · ~n = kd + f + c(d − d0 ) (39.1)

where k is a spring coefficient, f is a given force, and d0 is the target configuration. When c goes to infinity,
this condition approaches the Dirichlet conditions.

39.3 Keywords
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere.
Procedure File "NonphysicalMeshSolve" "MeshSolver"
Name of the solver subroutine.
Variable String [-dofs 3 Mesh Deform]
The name of the displacement field. It should be different from Mesh Update in order to avoid
conflicts in its interpretation. Here we use the name Mesh Deform. The dimension should be
the same as that of the mesh.
Cumulative Displacements Logical
If the same solver is called multiple times, then this flag controls whether the displacements are
added each time to the initial or previous mesh shape. The default is False.

CSC – IT Center for Science

39. Nonphysical Mesh Adaptation Solver 217

Moving Mesh Logical

This keyword relates to a mesh that is being moved by an outside solver such as the MeshSolver.
The default is True.
Target Field String
The name of the field d0 that is used as a target when setting the boundary conditions in a weak
manner.
Nodal Penalty Factor Real
A coefficient that is used to set the displacements to those given by the target field in a soft
manner. This is constant for each node which results to problems in mesh consistency.
Material mat id
The material section is used to give the material parameter values. The following material parameters
may be set for the Navier equations.
Poisson Ratio Real
For isotropic materials the Poisson ratio must be given with this keyword.
Youngs Modulus Real
The elastic modulus must be given with this keyword.
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. Those related to the
Navier equations are

Mesh Deform i Real

Dirichlet boundary condition for each displacement component i= 1, 2, 3.
Mesh Coefficient i Real
The spring coefficient related to the given coordinate direction, i= 1, 2, 3.
Mesh Force i Real
The right-hand-side of the mesh deformation equation, i= 1, 2, 3.
Mesh Normal Force Real
The right-hand-side of the mesh deformation equation in the normal direction.
Mesh Penalty Factor Real
When using the soft way of setting boundary conditions, this value gives the weight function c.

CSC – IT Center for Science

Model 40

Rigid Mesh Transformation

Module name: RigidMeshMapper

Module subroutines: RigidMeshMapper
Module authors: Peter Råback
Document authors: Peter Råback

40.1 Introduction
Sometimes there is a need to transform meshes without generating a new mesh. The most simple case is
that of a rigid motion where some bodies move according to prescribed rotations and translations. Typically
this could be a preprocessing step in a parametric study of some problem. Then this solver may be used to
perform the mesh transformation.
In addition to applying rigid transformations to bodies followed by a stretching, this solver includes also
a relaxation parameter which may be used to define which fraction of the node coordinates is taken from the
suggested coordinates, and which part from the original coordinates.
It should be noted that the usage of this solver is rather limited. It cannot handle cases where bodies
move with respect to one another if there is a mesh between the bodies. Then the MeshUpdate solver
should be used instead.

40.2 Theory
Given original coordinate ~x0 the solver applied first a rotation, then a translation, and finally a scaling
operator such that the suggested new coordinates yield

~x1 = S(R(~x0 − ~o) + ~t) + ~o, (40.1)

where ~t is the vector of translation, ~o is the origin, S the scaling matrix, and R is the rotation matrix. Rotation
may currently be performed only around one main axis.
Often it is desirable that the rigid transformations are performed only for some objects and while some
stay fixed. Between them the transformation degree should vary smoothly. To this aim the solver may be
used to compute a degree of transformation field from the Poisson equation

− ∇ · (1 + c|∇Φ|)∇Φ = s (40.2)

where c is an optional coefficient which may be used to increase the mesh rigidity around singularities. A
suitable boundary condition is Φ = 0 for fixed objects and Φ = 1 for moving objects.
Usually the rigid mesh mapper does not have a source term. However, for different testing purposes there
is also the possibility to give a source term s which may be used to distort the mesh in a continuous way.
Upon request the deformation may then be normalized to unity.

CSC – IT Center for Science

40. Rigid Mesh Transformation 219

When the rigid mesh mapping is applied together with the relaxation, the end result is

d~x = Φ (~x1 − ~x0 ) . (40.3)

40.3 Keywords
Solver solver id
Equation String [RigidMeshMapper]
The name of the equation.
Procedure File "RigidMeshMapper" "RigidMeshMapper"
The name of the procedure.
Variable String
Optionally the solver may be used to compute a relaxation field whose values are on the interval
[0, 1]. The final displacement is then obtained as a product of the field and the suggested rigid
body motion. The name is arbitrary since it is not referenced elsewhere.
Mesh Rotation Axis Order(dim) Integer
The user may specify the order in which the mesh is rotated around the axes with this keyword.
By default first rotation is around x-axis, then around y, and finally around z. Different order
will give a different end result.
Translate Before Rotate Logical
If this keyword is given value True, then the translation is carried out before rotations. The
default is vice versa.
Cumulative Displacements Logical
The displacement resulting from this solver may be either absolute or cumulative. For example,
for rotating problems if the mode is cumulative only the incremental angle is given. If the
cumulative mode is not enforced, then the full angle from the start of the simulation should be
given. The default is False.
Calculate Mesh Velocity Logical
If this keyword is enforced, then the solver will compute the mesh velocity resulting from rigid
body deformation in a transient case. The name of the resulting vector field will be Mesh
Velocity.
Mesh Relax Normalize Found
Normalize the mesh relaxation field such that the maximum value is one.
Body Force bf id
The mesh transformations are defined in this section.

Mesh Translate Real [tx ty tz ]

The translational vector which may also be given individually for each component, i = 1, 2, 3.
Mesh Rotate Real [αx αy αz ]
The rotation around main coordinate directions. This may also be given individually for each
component, i = 1, 2, 3. When given for each component, they may also be variables of time, for
example.
Mesh Scale Real [sx sy sz ]
The scaling around of main directions. This may also be given individually for each component,
i = 1, 2, 3.
Mesh Origin Real [ox oy oz ]
The origin used in rotation and scaling.
Mesh Matrix(dim,dim) Real
Give the mesh transformation matrix. This overrides all other rigid mesh mapping keywords.

CSC – IT Center for Science

40. Rigid Mesh Transformation 220

Mesh Displace i Real

An alternative for giving the mesh deformation in rigid body motion. Give separately for each
component, i = 1, 2, 3. This is a local field that may vary between the nodes while the rigid
body motion may only depend on global variables such as time.
Mesh Relax Real
The relaxation factor determining which amount of the coordinate transformation is taken into
account. This is a local field which may depend on coordinate values whereas the other above
keywords must be constant for each body force.
Mesh Relax Source Real
An optional source term for the mesh relaxation field.

Boundary Condition bc id
The boundary conditions that define the moving and fixed walls.
Moving Boundary Logical
Gets relaxation field multiplied by one.
Fixed Boundary Logical
Gets relaxation field multiplied by zero.

CSC – IT Center for Science

Model 41

Structured Mesh Mapper

Module name: StructuredMeshMapper

Module subroutines: StructuredMeshMapper
Module authors: Peter Råback and Thomas Zwinger
Document authors: Peter Råback and Thomas Zwinger

41.1 Introduction
For structured meshes some operations may be done much more effectively than for generic meshes. One
such operation is the mapping of mesh so that it is fitted for given top and bottom surfaces. For example,
the mesh for the computational glaciology could be deduced from a uniform initial mesh when its top and
bottom surfaces would be known in terms of some given fields.

41.2 Theory
The algorithm used for the mapping has two sweeps. Assume that we would like to perform mapping in
direction ~ez . At the first sweep over all elements we would deduce pairwise information over nodes on which
nodes are in up and down directions from each other. Then using this directional information recursively
one can easily deduce which nodes are the top and bottom representatives of any node in the mesh. With
this information any node between the top and bottom surface may be mapped as the linear combination of
the top and bottom displacements. In the end the top surface of the mesh is mapped to the given top position
and the bottom surface of the mesh to the given bottom position, correspondingly.

41.3 Keywords
Solver solver id
Equation String [StructuredMeshMapper]
The name of the equation.
Procedure File "StructuredMeshMapper" "StructuredMeshMapper"
The name of the procedure.
Active Coordinate Integer
The direction in which the structured mapping is performed i.e. 1, 2 or 3.
Displacement Mode Logical
The values may be either used either directly as absolute coordinate values, or as displacement
adding them to the original coordinate values. With this keyword the latter may be chosen.

CSC – IT Center for Science

41. Structured Mesh Mapper 222

Dot Product Tolerance Real

When determining the structure of the mesh in the active direction this tolerance is used to decide
that an element edge is aligned with the direction of the action.
Top Surface Level Real
If the value is constant, then this keyword may be used to give the top surface position.
Top Surface Variable Name String
The top surface may be given by some auxiliary variable computed by some other solver, for
example.
Bottom Surface Level Real
If the value is constant, then this keyword may be used to give the bottom surface position.
Bottom Surface Variable Name String
The bottom surface may be given by some auxiliary variable computed by some other solver, for
example.
Mid Surface Real
Sometimes there is a middle layer that needs to be mapped as well. Then this keyword may be
used. The mapping is then done linearly in two parts.
Correct Surface Logical
If this keyword is set to True, a minimum height (see next keyword) is applied to the extrusion.
Minimum Height Real
Sets the constant minimum extrusion height.
Mesh Height Map Real
Assuming that the mesh has height blow the minimum height how should the relative height
to that (<1) be mapped. Allows for smoother geometry deformations avoiding large areas of
constant thickness.
Correct Surface Mask String
This optionally defines a name for a variable where the information on whether a point is part of
a column that has been corrected to the minimum height. It is -1 if it has been corrected and +1
else.
Mesh Velocity Variable String
This keyword is used to give the variable in which mesh velocity will be computed to. The mesh
velocity will be really 1D only so this variable should be a scalar. If the user wants to compute a
vector then the correct component of that should be given as the parameter.
Mesh Update Variable String
This keyword is used to give the variable in which mesh coordinate will be computed to. The
new coordinate will be really 1D only so this variable should be a scalar. If the user wants to
compute a vector then the correct component of that should be given as the parameter.
Displacement Mode Logical
The coordinates resulting from this solver may be either absolute or cumulative. If displacement
mode is not enforced then the coordinates will be treated as absolute values. The default is
False.
Mesh Velocity First Zero Logical
If this keyword is set True then the 1st time this routine is visited the mesh velocity is enforced
to zero. May be attractive if the initial geometry is not really the initial state.
Always Detect Structure Logical
Redetect structure always when visiting solver. Does not really make sense except if the mesh
has changed.
Recompute Stabilization Logical
Mesh deformation may affect the stabilization. This flag activated the stabilization parameters
(that may be used by FlowSolve or HeatSolve, for example). Using this flag enforces that the
parameters are recomputed.

CSC – IT Center for Science

41. Structured Mesh Mapper 223

Mapped Mesh Name File

We may want to save the mapped mesh. This keyword gives the output directory.
Boundary Condition bc id
Top Surface Real
The top surface position may also be given with a boundary condition.
Bottom Surface Real
The bottom surface position may also be given with a boundary condition.
Mid Surface Real
Optionally one may give a mid surface that should be between the top and bottom surfaces. This
is the only method for giving the mid surface since it also specifies the active nodes whereas for
top and bottom they are defined even without the boundary condition.

CSC – IT Center for Science

Model 42

Free surface with streamlines

Module name: StructureFlowLine

Module subroutines: StructureFlowLine
Module authors: Peter Råback
Document authors: Peter Råback

42.1 Introduction
There are many different kinds of free surface problems. It is difficult to create a generic algorithm that
would be optimal for all problems. Therefore specific cases may need specific solvers. This solver is
intended for steady-state drawing and pulling problems where the mesh is structured in the direction of the
forced flow. Then it is possible to follow the streamlines of the flow and map element edges with the flow.
When converged the streamlines will then coincide with the element edges providing an optimal solution for
the problem.
The solver can be used by itself as a free surface solver, or together with a mesh adaptation solver so that
the current solver only gives the suggested displacement at the boundaries.

42.2 Theory
Assume that we want to map the coordinates ~ri so that they coincide with the streamlines. Then

|dri,k |
~ri+1 = ~ri + ~va (42.1)
|va,k |

where k is the active coordinate direction of the pulling or drawing process. The average velocity may be
computed from
1
~va = (~vi + ~v (~ri + 1)) (42.2)
2
or from  
1
~va = ~v (~ri + ~ri+1 ) . (42.3)
2
When ~ri+1 is updated the information may be used to derive on improved estimate of ~va . This requires
as an operation that the velocity must be evaluated within an arbitrary position. For this purpose an octree
structure for the elements is used to speedup the search. Typically even one corrector step will improve the
results significantly.

CSC – IT Center for Science

42. Free surface with streamlines 225

42.3 Keywords
Solver solver id
Equation String [StructuredFlowLine]
The name of the equation.
Procedure File "StructuredFlowLine" "StructuredFlowLine"
The name of the procedure.
Velocity Variable Name String
Name of the variable used to define the streamlines.
Active Coordinate Integer
The drawing direction i.e. 1, 2 or 3.
Dot Product Tolerance Real
When determining the structure of the mesh in the active direction this tolerance is used to decide
that an element edge is aligned with the direction of the action.
Displacement Mode Logical
The values may be either used either directly, or saved to a field. If this flag is set True the
coordinate values will be changed directly. The default is False.
Hard Displacement Name String
The name of the field for the suggested displacement. These values may be used in a soft way in
mesh deformations in order to avoid singularities that often appear at corners.
True Flow Line Iterations Logical
When computing the drawing shapes the first iterations lead to larger displacements and set
higher demands to the numerical methods. Close to convergence the velocity may be more
accurately defined at the existing flow line. This flag determines the number of the more costly
iterations. The default is zero.
Averaging Order Integer
Order of iterations in evaluating the new position. Default is one.
Averaging Method Integer
Whether to use velocity at the average point (1), or average of the velocity (2).
Nonlinear System Relaxation Factor Real
Relaxation may be used to relax already the suggested displacement field.
Boundary Condition bc id
Flow Line Logical
By defining this keyword the solver is applied only to the those boundary nodes where the flag
is active. This reduces the computational time required.

Body Force bf id
Flow Line Logical
By defining this keyword the solver is applied only to the those bulk nodes nodes where the flag
is active.

CSC – IT Center for Science

Model 43

Statistics of finite element mesh

Module name: ElementStats

Module subroutines: ElementStats
Module authors: Peter Råback
Document authors: Peter Råback

43.1 Introduction
This module is used to calculate provide information on the mesh. The quality of the mesh will have a great
effect on the solution. This solver may help the user to determine whether the mesh is suitable for the need.
Currently three different operations are performed:
• element size
This is the metric determinant given by the ElementInfo.

• element skew
This is the skewness (in degrees) of the mesh, if applicable. Only quadrilaterals, pyramids, wedges
and hexahedrons may be skewed.
• element ratio
This refers to the ratio between maximum and minimum edge lengths of an element.

The operations are performed separately for bulk and boundary elements.
It is available currently only in serial.

43.2 Keywords
Solver solver id
Equation String ElementStats
Procedure File "ElementStats" "ElementStats"
Create Histogram Logical
When analyzing the mesh the results may be shown also as a histogram with an even distribu-
tion between min and max values. This flag activates the classification of the statistics into a
histogram.
Histogram Intervals Integer
The number of intervals in the histogram when classifying the element properties.

CSC – IT Center for Science

 Part VIII

Derived Fields and Quantities

CSC – IT Center for Science

Model 44

Streamline Computation

Module name: StreamSolver

Module subroutines: StreamSolver
Module authors: Mika Juntunen, Peter Råback
Document authors: Mika Juntunen, Peter Råback

44.1 Introduction
Streamline is a line in flow whose tangent is parallel to velocity field ~u of the flow in every point ~x. It should
be noted that the path of material is generally not the same as streamlines. There is also third set of closely
related lines, namely streak lines. On certain streak lines lie all those flow elements that at some earlier
instant passed through a certain point in domain. Of course, the streak lines are generally different than
streamlines but when the flow is steady all three set of lines coincide.
Streamlines are mainly used in providing a picture of the flow field. Drawing streamlines so that neigh-
bouring streamlines differ by the same amount, gives a picture where direction and magnitude change of
flow are clearly prescribed.

44.2 Theory
We are restricted here to the incompressible, steady flow in 2D geometry. The geometry may be 3D, but it
must effectively be 2D as in axis symmetric geometry.
In 2D Cartesian geometry stream function ψ is defined
∂ψ ∂ψ
u = , v = − . (44.1)
∂y ∂x
Here the geometry is (x, y) and the corresponding flow is ~u = (u, v). Let Ω be the domain of the flow and
~v a test function for the flow. Definition (44.1) leads to finite element approximation
Z Z
∇ψ · ~v dΩ = ~u⊥ · ~v dΩ (44.2)
Ω Ω
In axis symmetric geometry the mass conservation calculated in a different way. This leads to following
definition for stream function.
1 ∂ψ 1 ∂ψ
u = , v = − (44.3)
r ∂r r ∂z
where the cylindrical coordinates are (z, r, φ), velocity components are (u, v, w) and axis of symmetry is z
i.e. r = 0. This function is sometimes called the Stokes stream function and it is not as informative as the
stream function in Cartesian case. Of course the finite element approximation is a bit different.
Z Z
∇ψ · ~v dΩ = ~u⊥ · ~v r dΩ (44.4)
Ω Ω

CSC – IT Center for Science

44. Streamline Computation 229

Here the φ component of the flow is excluded.

From definitions (44.1) and (44.3) it is apparent that stream function is constant along the streamlines.
So drawing the contours of stream function gives the streamlines.
Sometimes setting the Dirichlet node does results to local distortion of the streamline function. To
circumvent this there is an alternative way to fix the level of the streamline. There a implicit penalty cψ is
added to the equation which effectively defines a finite level for the streamfunction. Small values of c are
to be favored in order not to distort the streamline field. Using this penalty method the magnitude of the
streamline may be quite large but after scaling the values should be rather independent on the value of c.

44.3 Limitations
Some limitations of the current implementation:

• The flow field is assumed to be incompressible.

• There is no dependency on time. Solver can be used in transient cases, but it only produces the
streamlines of the current flow field as if it was steady.
• Only 2D Cartesian and axis symmetric coordinate systems are implemented.

• Solver gets the velocity field from user defined variable. In Cartesian case it assumes that first degree
of freedom is the x-component and the second is the y-component of the velocity. In axis symmetric
case it assumes that the first degree of freedom is the r-component and the second is the z-component
of the velocity field.
• User can define the node whose value is first set to zero. This shouldn’t have affect on results if the
normal stream function is used in Cartesian coordinates and Stokes stream function in axis symmetric
coordinates. However, if used stream function is forced to something else, the position of the first node
usually has a large effect on results. This is because the mass conservation is calculated differently.

44.4 Keywords
Simulation

Coordinate System String

The coordinate system should be set to be one of the following options: Cartesian 2D or Axi
Symmetric.
Solver solver-id
All the keywords beginning Linear System can be used. They are explained elsewhere.

Equation String
The name you want to give to the solver, for example StreamSolver.
Procedure File "StreamSolver" "StreamSolver"
The name of the file and subroutine.
Variable String
The name you want to call the solution, for example StreamFunction.
Variable DOFs Integer 1
The degree of freedom of the variable. Stream function is scalar so this must be set to 1.
Stream Function Velocity Variable String
The name of the velocity field variable. FlowSolvers solution is called Flow Solution and
this is also the default value.

CSC – IT Center for Science

44. Streamline Computation 230

Stream Function First Node Integer

Number of the node that is set to zero. If given, non-positive values are set to 1 and too large
values are set to largest possible i.e. ’the last node’. If not given, then other means are assumed
to be used for setting the level.
Stream Function Penalty Real
When the level of the streamline is defined by a penalty formulation then this keyword is used to
define the penalty factor c. Default is zero.
Stream Function Shifting Logical
Shift the smallest value to zero. Default is True.
Stream Function Scaling Logical
Scale largest absolute value to 1. Default is False.
Stokes Stream Function Logical
This keyword forces the stream function type regardless of the coordinate system. If the coordi-
nate system is axis symmetric, then the default is True, else the default is False.

44.5 Example
This example computes the streamlines from a 2D incompressible flow field assuming the default name for
flow field
Solver 4
Exec Solver = after all
Equation = "streamlines"
Procedure = "StreamSolver" "StreamSolver"
Variable = String Stream

Linear System Solver = "Iterative"

Linear System Iterative Method = "cg"
Linear System Preconditioning = ILU0
Linear System Residual Output = 10
Linear System Max Iterations = Integer 500
Linear System Convergence Tolerance = 1.0e-10
Linear System Abort Not Converged = False
End

CSC – IT Center for Science

Model 45

Flux Computation

Module name: FluxSolver

Module subroutines: FluxSolver
Module authors: Juha Ruokolainen, Peter Råback
Document authors: Peter Råback

45.1 Introduction
This module is used to calculate the fluxes resulting usually from Poisson kind of equations. These include,
for example, the heat equation, the electrostatic equation, and the pressure equation for Darcy’s flow. There
are also flux computation subroutines that are built in the solvers but this provides a generic approach that
should be easy to combine with most solvers.

45.2 Theory
Given a potential φ it is often interesting to know its gradient or the resulting flux. The gradient may be
computed from ∇φ. The flux resulting from a potential field is assumed to be proportional to the gradi-
ent. The proportionality coefficient c may be conductivity, permeability, diffusivity, etc., depending on the
application field. It may be a scalar or a tensor of second kind. The flux may now be expressed as

~q = −c∇φ. (45.1)

For the heat equation the potential would thus be the temperature and the conductivity would be the heat
conductivity.
The magnitude of a flux (or gradient) may be defined as

|q| = |~q · ~q| = |c∇φ · c∇φ| (45.2)

The computation of magnitude may be done before or after the numerical discretization giving slightly
different results.

45.3 Implementation issues

The flux may be computed in many ways. Often for visualization purposes it suffices to take some nodal
average of the element-wise computed fluxes. The most consistent method for flux computation is, however,
using the finite element method to solve the equation (45.1). The Galerkin method creates a diagonally
dominated matrix equation that may be solved easily with iterative methods even with cheap preconditioners.
The flux computation may be done component-wise so that each component qi , where i = 1 . . . dim,
is solved separately. This saves a significant amount of memory even though it slightly complicates the

CSC – IT Center for Science

45. Flux Computation 232

implementation. In the solver it is also possible to choose just one component as could be sometimes
desirable.
The main limitation of the current version is that it does not take into account any boundary conditions.
Therefore, if there is an internal boundary over which the flux is not continuous, the calculated value does
not make sense.

45.4 Keywords
Solver solver id
Equation String Flux Solver
Procedure File "FluxSolver" "FluxSolver"
Discontinuous Galerkin Logical
For discontinuous fields the standard Galerkin approximation enforces continuity which may be
unphysical. As a remedy for this, the user can enforce Discontinuous Galerkin (DG) formulation.
Then the result may be discontinuous, and may even be visualized as such if the postprocessing
format supports it.
Average Within Materials Logical
This keyword enforces continuity within the same material in the DG discretization using the
penalty terms of the DG formulation.
Calculate Flux Logical
This flag controls the computation of fluxes. The default is False.
Calculate Flux Abs Logical
In conjunction with flux computation this flag may be used to compute the absolute value of the
flux vector. It requires that the previous flag is active.
Calculate Flux Magnitude Logical
This flag can be used to compute the magnitude of the vector field. Basically it is the same in
continuous level as the previous but this requires less memory and solves the matrix equation
only once. The downside is that even negative values may be introduced.
Calculate Grad Logical
This flag turns on gradient computation. The default is False.
Calculate Grad Abs Logical
In conjunction with gradient computation this flag may be used to compute the absolute value of
the gradient. It requires that the previous flag is active.
Calculate Grad Magnitude Logical
This flag can be used to compute the magnitude of the gradient field. Basically it is the same
in continuous level as the previous but this requires less memory and solves the matrix equation
only once. The downside is that even negative values may be introduced.
Enforce Positive Magnitude Logical
If this is active, then the negative values of the computed magnitude fields are a posteriori set to
zero.
Target Variable String "Temperature"
This gives the name of the potential variable used to compute the gradient. By default the variable
is Temperature.
Flux Coefficient String "Heat Conductivity"
This gives the name of the proportionality coefficient to compute the flux. By default the coeffi-
cient is Heat Conductivity.
The resulting linear system is easily solved even without preconditioning. Fox example, the following
linear system control may be applied.

CSC – IT Center for Science

45. Flux Computation 233

Linear System Solver "Iterative"

Linear System Iterative Method "BiCGStab"
Linear System Preconditioning None
Linear System Max Iterations 500
Linear System Convergence Tolerance 1.0e-10

45.5 Example
This example computes the diffusive heat flux in the whole domain after the whole solution has been per-
formed.
Solver 3
Exec Solver = after all
Equation = "flux compute"
Procedure = "FluxSolver" "FluxSolver"
Calculate Flux = Logical True
Flux Variable = String Temperature
Flux Coefficient = String "Heat Conductivity"

Linear System Solver = "Iterative"

Linear System Iterative Method = "cg"
Linear System Preconditioning = ILU0
Linear System Residual Output = 10
Linear System Max Iterations = Integer 500
Linear System Convergence Tolerance = 1.0e-10
End

CSC – IT Center for Science

Model 46

Vorticity Computation

Module name: VorticitySolver

Module subroutines: VorticitySolver
Module authors: Peter Råback
Document authors: Peter Råback

46.1 Introduction
This module is used to calculate the vorticity of vector fields. Vorticity may be of interest mainly in the post-
processing of flow fields or electromagnetic fields. The default name for the vorticity is Curl varname.

46.2 Theory
The vorticity w
~ of a vector field ~v is obtained simply as the curl of the field,

~ = ∇ × ~v .
w (46.1)

Component-wise the equations for the vorticity read

∂vz ∂vy
wx = − (46.2)
∂y ∂z
∂vx ∂vz
wy = − (46.3)
∂z ∂x
∂vy ∂vx
wz = − . (46.4)
∂x ∂y
Thus, all three components exist in 3D, while in 2D and axisymmetric cases only the z-component is present
The most consistent method for computing the vorticity in conjunction with the finite elements is to
solve the equations (46.4) using the Galerkin method. The resulting matrix is diagonally dominated and
the linear system may be solved easily with iterative methods even with poor preconditioners. In 3D the
vorticity computation may be done component-wise so that each component wi , where i = 1, 2, 3, is solved
separately. This saves some memory and may also save in the overall time consumption.

46.3 Keywords
Solver solver id
Equation String Vorticity Solver
Procedure File "VorticitySolver" "VorticitySolver"

CSC – IT Center for Science

46. Vorticity Computation 235

Target Variable String "Velocity"

This gives the name of the vector variable used to compute the vorticity. By default the variable
is Velocity.
Constant Bulk Matrix Logical
This keyword may be used to activate the saving of the stiffness matrix if the same solver is
called repeatedly. The stiffness matrix depends only on geometric information and is hence the
same if the geometry is unaltered.
The solver is easily solved even without preconditioning. Fox example, the following linear system
control may be applied.

Linear System Solver "Iterative"

Linear System Iterative Method "cg"
Linear System Preconditioning None
Linear System Max Iterations 500
Linear System Convergence Tolerance 1.0e-10

46.4 Example
This example computes the vorticity field after each timestep. Some resources are saved by reusing the same
bulk matrix.
Solver 5
Exec Solver = after timestep
Equation = "vorticity"
Procedure = "VorticitySolver" "VorticitySolver"
Constant Bulk Matrix = True

Linear System Solver = "Iterative"

Linear System Iterative Method = "cg"
Linear System Preconditioning = ILU0
Linear System Residual Output = 10
Linear System Max Iterations = Integer 500
Linear System Convergence Tolerance = 1.0e-10
Linear System Abort Not Converged = False
End

CSC – IT Center for Science

Model 47

Divergence Computation

Module name: DivergenceSolver

Module subroutines: DivergenceSolver
Module authors: Peter Råback
Document authors: Peter Råback

47.1 Introduction
This module is used to calculate the divergence of vector fields. Divergence may be of interest mainly in the
postprocessing to check how well incompressibility constraints are honored.

47.2 Theory
The divergence d of a vector field ~v is obtained simply from

d = ∇ · ~v . (47.1)

The most consist ant method for computing the divergence in conjunction with the finite elements is to
solve the equation (47.1) using the Galerkin method. The resulting matrix is diagonally dominated and may
be computed easily with iterative methods even with poor preconditioners.

47.3 Keywords
Solver solver id

Equation String Divergence Solver

Procedure File "DivergenceSolver" "DivergenceSolver"
Target Variable String "Velocity"
This gives the name of the vector variable used to compute the divergence. By default the variable
is Velocity.
Constant Bulk Matrix Logical
This keyword may be used to activate the saving of the stiffness matrix if the same solver is
called repeatedly. The stiffness matrix depends only on geometric information and is hence the
same if the geometry is unaltered.
The following keywords are not usually needed as they are set by the initialization procedure of the
solver.

CSC – IT Center for Science

47. Divergence Computation 237

Variable String
By default the variable is obtained from the divergence variable by adding a prefix Div to the
field name. Naturally the name of the resulting field may also be given as desired.
The solver is easily solved even without preconditioning. Fox example, the following linear system
control may be applied.

Linear System Solver "Iterative"

Linear System Iterative Method "cg"
Linear System Preconditioning None
Linear System Max Iterations 500
Linear System Convergence Tolerance 1.0e-10

CSC – IT Center for Science

Model 48

Scalar Potential Resulting to a Given

Flux

Module name: ScalarPotentialSolver

Module subroutines: ScalarPotentialSolver
Module authors: Peter Råback
Document authors: Peter Råback

48.1 Introduction
This module is an auxiliary solver that may be used to compute the scalar potential that results to a given
flux. The flux is assumed to be a vector field resulting from some computation. This solver is the dual of the
FluxSolver. Computing first the flux of a given potential and thereafter resolving for the potential that
creates the flux should give approximately the original potential.

48.2 Theory
The flux resulting from a potential field is assumed to be proportional to the gradient of the field, φ. The
proportionality factor is here called conductivity, c. The flux may therefore be expressed as

q = −c∇φ. (48.1)

For heat equation the potential would be the temperature and the conductivity would be the heat conductivity.
This solver handles the equation in the reverse form, i.e. given the flux the potential is solved. The weak
formulation is created by choosing the test functions to be the gradients of the shape functions. This results
to the standard discretization of the Poisson equation.
The potential is not defined uniquely unless the level is fixed at least at one point. Therefore the user
should set a Dirichlet condition at least at one node.

48.3 Keywords
Solver solver id
Equation String ScalarPotentialSolver
Procedure File "ScalarPotentialSolver" "ScalarPotentialSolver"
Variable String "Scalar Potential"
The desired name of the resulting scalar field.

CSC – IT Center for Science

48. Scalar Potential Resulting to a Given Flux 239

Flux Variable String

This gives the name of the flux variable used to compute the source term. Note that this must be
the name of a vector field such as Velocity.
Flux Coefficient String
This gives the name of the coefficient used in the computation of the flux. For example, in
thermal analysis it would be Heat Conductivity. If a non-existing material parameter is
given, the coefficient will be assumed to be the unity, i.e. c = 1.
The equation is a Poisson type of equation and defaults for it are set to be cg+ILU0. If these do not
suffice, other linear system options should be defined.

Boundary Condition bc id
Scalar Potential Real
The defined field variable must be set to be a constant at least at one point.
Target Nodes Integer
The user may also define a target node on-the-fly at which the condition is set.

CSC – IT Center for Science

Model 49

Artificial Compressibility for FSI

Module name: ArtificialCompressibility

Module subroutines: CompressibilityScale
Module authors: Peter Råback
Document authors: Peter Råback

49.1 Introduction
When fluid-structure interaction (FSI) problems are solved with a loosely coupled iteration strategy there is
a risk of applying unphysical boundary conditions that lead to severe convergence problems. The reason for
this is that initially the fluid domain is unaware of the constraint of the structural domain, and vice versa. If
the iteration converges this discrepancy will be settled, but sometimes the initial phase is so ill posed that
convergence is practically impossible to obtain [4, 3].
The problem may be approached by applying the method of artificial compressibility to the fluid-
structure interaction. Previously artificial compressibility has mainly been used as a trick to eliminate the
pressure from the Navier-Stokes equations or to improve the convergence of the solution procedure [2, 6, 1].
Here the compressibility is defined so that it makes the fluid imitate the elastic response of the structure.
The method is best suited for cases where there is a direct correspondence between the pressure and the
volume. Inertial forces and traction forces should be of lesser importance. The method might, for example,
boost up the modeling of human arteries.

49.2 Theory
49.2.1 Fluid-structure interaction
The theoretical model with some results is thoroughly presented in
We look at the time-dependent fluid-structure interaction of elastic structures and incompressible fluid.
The equations of momentum in the structural domain is
∂ 2 ~u
ρ = ∇ · τ + f~ in Ωs , (49.1)
∂t2
where ρ is the density, ~u is the displacement, f~ the applied body force and τ = τ (~u) the stress tensor that
for elastic materials may be locally linearized with ~u. For the fluid fluid domain the equation is
 
∂~v
ρ + ~v · ∇~v = ∇ · σ + f~ in Ωf , (49.2)
∂t
where ~v the fluid velocity and σ the stress tensor. For Newtonian incompressible fluids the stress is
σ = 2µε(~v ) − pI, (49.3)

CSC – IT Center for Science

49. Artificial Compressibility for FSI 241

where µ is the viscosity, ε(~v ) the strain rate tensor and p the pressure. In addition the fluid has to follow the
equation of continuity that for incompressible fluid simplifies to

∇ · ~v = 0 in Ωf . (49.4)

For later use we, however, recall the general form of the continuity equation,

∂ρ
+ ∇ · (ρ~v ) = 0 in Ωf . (49.5)
∂t
The fluid-structure interface, Γf s , must meet two different boundary conditions. At the interface the fluid
and structure velocity should be the same,

~v (~r, t) = ~u˙ (~r, t), ~r ∈ Γf s . (49.6)

On the other hand, the surface force acting on the structure, ~gs , should be opposite to the force acting on the
fluid, ~gf , thus
~gs (~r, t) = −~gf (~r, t), ~r ∈ Γf s . (49.7)
A widely used iteration scheme in FSI is the following: First, assume a constant geometry and solve the
Navier-Stokes equation for the fluid domain with fixed boundary conditions for the velocity. Then calculate
the surface forces acting on the structure. Using these forces solve the structural problem. Using the resulting
displacement velocities as fixed boundary conditions resolve the fluid domain. Continue the procedure until
the solution has converged.
The above described iteration usually works quite well. However, in some cases the boundary condi-
tions (49.6) and (49.7) lead to problems. The elasticity solver is not aware of the divergence free constraint
of the velocity field. Therefore the suggested displacement velocities used as boundary conditions may well
be such that there is no solution for the continuity equation. A proper coupling method makes the solution
possible even if the velocity boundary conditions aren’t exactly correct. Further, if the Navier-Stokes equa-
tion is solved without taking into account the elasticity of the walls, the forces in equation (49.7) will be
exaggerated. The pathological case is one where all the boundaries have fixed velocities. Then even an in-
finitely small net flux leads to infinite pressure values. A proper coupling method should therefore also give
realistic pressure values even with inaccurate boundary conditions. The method of artificial compressibility
meets both these requirements.

49.2.2 Artificial compressibility

When a surface load is applied to an elastic container it results to a change in the volume. In many cases of
practical interest the change in volume is mainly due to a pressure variation from the equilibrium pressure
that leads to zero displacements. If the structural domain is described by linear equations the change in
volume dV has a direct dependence on the change in the pressure, dP , or

dV
= c dP. (49.8)
V
This assumption limits the use of the model in highly nonlinear cases.
The change in the volume should be the same as the net volume flux into the domain. As this cannot be
guaranteed during the iteration, some other way to enable the material conservation must be used. A natural
choice is to let the density of the fluid vary so that is has the same pressure response as the elastic walls,

dρ
= c dP, (49.9)
ρ
where c is the artificial compressibility. This is interpreted locally and inserted to the continuity equa-
tion (49.5) while neglecting the space derivative of the density, thus

dp
c + ∇ · ~v = 0, (49.10)
dt

CSC – IT Center for Science

49. Artificial Compressibility for FSI 242

where dp is the local pressure change. Here the time derivative of pressure must be understood as an iteration
trick. A more precise expression is
c  (m) 
p − p(m−1) + ∇ · ~v (m) = 0, (49.11)
∆t
where m is the current iteration step related to fluid-structure coupling. When the iteration converges p(m) →
p(m−1) and therefore the modified equation is consistent with the original one. The weak form of the
equation for finite element method (FEM) may easily be written,
Z Z
(m) 1  
(∇ · ~v )ϕp dΩ + c p(m) − p(m−1) ϕp dΩ = 0, (49.12)
Ωf ∆t Ωf

where ϕp is the test function.

The artificial compressibility may be calculated analytically in simple geometries. For example, for a
thin cylinder with thickness h and radius R the compressibility is c = 2R/Eh [5], where E is the Young’s
modulus, and correspondingly for a sphere c = 3R/Eh.
In most practical cases the elastic response of the structure cannot be calculated analytically. Then the
compressibility may also be computed from equation (49.8) by applying a pressure change dP to the system,

1 dV
c= . (49.13)
V dP
The change in volume may be calculated by comparing it to initial volume, thus
V − V0 1
c= . (49.14)
V0 dP
For small deformations ds = ~u · ~n, where ~n is the surface normal. Therefore we may use an alternative
form convenient for numerical computations,
R R
Γf s
(~u · ~n) dA Γf s dA
c= R R . (49.15)
Ωf
dV Γf s
dp dA

This way c has a constant value over the domain.

49.2.3 Scaling artificial compressibility

If the artificial compressibility distribution is a priori defined we may use the above equations to scale the
compressibility appropriately. For example, the compressibility could be given only within a limited distance
from the elastic wall. and the functional behavior of c(~r) would be user defined. Computing compressibility
becomes then just a matter of scaling,
R R
Γf s
(~u · ~n) dA Γf s dA
c(~r) = c0 (~r) R R . (49.16)
Ωf 0
c (~r)dV Γf s dp dA
| {z }
scaling factor

A suitable test load for computing compressibility is the current pressure load on the structure. However,
for the first step the compressibility must be predefined. It is safer to over-estimate it since that leads to too
small a pressure increase. Too large a pressure increase might ruin the solution of the elasticity solver and
by that also the computational mesh used by the flow solver would be corrupted. Therefore some sort of
exaggeration factor exceeding unity might be used to ensure convergence.

CSC – IT Center for Science

49. Artificial Compressibility for FSI 243

49.2.4 Elementwise artificial compressibility

If the displacement field is extended smoothly throughout the whole geometry it may be possible to define
the artificial compressibility separately for each element or node. This is particularly useful for geometries
where the elastic response changes significantly. The equation is now similar to (49.14),
V e − V0e 1
c= , (49.17)
V0e dP

where the superscript e refers to the volume of an element. This may also be solved using finite element
strategies to get nodal values for c.

49.3 Keywords
Keywords of FlowSolve
Material mat id
In the material section the compressibility model and the initial artificial compressibility field is given.

Compressibility Model String [Artificial Compressible]

Set the material model of the fluid.
Artificial Compressibility Real
The initial value of artificial compressibility. This may also be a distributed function that is then
scaled by the solver.

Keywords of solver CompressibilityScale

If the artificial compressibility is tuned so that it best imitates the elastic response, a additional solver must
be used to rescale the above mentioned compressibility. The solver computes the total compressibility and
the force acting on the surface. The compressibility is integrated over all volumes that are solved with the
Navier-Stokes equation.

Solver solver id
Equation String CompressibilityScale
The name of the solver.
Procedure File "ArtificialCompressibility"
"CompressibilityScale"
The subroutine in the dynamically linked file.
Steady State Convergence Tolerance Real
How much the relative value of the compressibility may change between iterations, abs(ci −
ci−1 )/ci < ε.
Nonlinear System Relaxation Factor Real
Relaxation scheme c0i = λci + (1 − λ)ci−1 for the compressibility. By dafault is λ = 1.
Boundary Condition bc id
Force BC Logical
The elastic response is calculated over the surface(s) which has this definition as True.

Keywords of solver CompressibilitySolver

When the compressibility is solved elementwise using this solver there has to usually be a isobaric steady-
state test phase where the compressibility is defined. For this solver all the normal Linear System
keywords also apply.

CSC – IT Center for Science

BIBLIOGRAPHY 244

Solver solver id
Equation String CompressibilitySolver
Procedure File "ArtificialCompressibility"
"CompressibilitySolver"
Variable String ac
The name of the artificial compressibility field variable.
Displacement Variable Name String "Mesh Update"
The name of the displacement field variable that is used to compute the the volume change.
Displaced Shape Logical True
Flag that defines whether the current shape is the displaced or original shape.
Reference Pressure Real
The value of pressure used for the test loading.
The computed field should then be given as the value in the material section.

Material mat id
Artificial Compressibility Equals ac
The initial value of artificial compressibility given by the solver.

49.3.1 Examples
The examples show a 2D square and a 3D cube being gradually filled. The fluid comes in from one wall and
the opposing elastic wall makes room for the fluid so that the continuity equation is satisfied. Here the value
of artificial compressibility is scaled every timestep to account for the nonlinear elasticity.

Figure 49.1: Snapshots of an elastic square being gradually filled by incompressible fluid.

Bibliography
[1] F. D. Carter and A. J. Baker. Accuracy and stability of a finite element pseudo-compressibility cfd
algorithm for incompressible thermal flows. Num. Heat Transfer, Part B, 20:1–23, 1991.

CSC – IT Center for Science

BIBLIOGRAPHY 245

Figure 49.2: Snapshots of an elastic cube being gradually filled by incompressible fluid.

[2] A. J. Chorin. A numerical method for solving incompressible viscous flow problems. J. Comput. Phys.,
135:118–125, 1997.
[3] L. Formaggia, J. F. Gerbeau, F. Nobile, and A. Quarteroni. Numerical treatment of defective boundary
conditions for the navier-stokes equations. EPFL-DMA Analyse et Analyse Numerique, 20, 2000.

[4] E. Järvinen, M. Lyly, J. Ruokolainen, and P. Råback. Three dimensional fluid-structure interaction
modeling of blood flow in elastic arteries. In Eccomas Computational Fluid Dynamics Conference,
September 2001.
[5] Kris Riemslagh, Jan Vierendeels, and Erik Dick. An efficient coupling procedure for flexible wall fluid-
sructure interaction. In Eccomas Congress on Comp. Meth. in Appl. Sci. and Eng, September 2000.

[6] S. E. Rogers, D. Kwak, and U. Kaul. On the accuracy of the pseudocompressibility method in solving
the incompressible navier-stokes equations. Appl. Math. Modelling, 11:35–44, 1987.

CSC – IT Center for Science

Model 50

Fluidic Force

Module name: FluidicForce

Module subroutines: ForceCompute
Module authors: Juha Ruokolainen, Antti Pursula
Document authors: Antti Pursula

50.1 Introduction
This module is used to calculate the force that a fluid flow induces on a surface. The fluidic force can
be divided into two main components: force due to pressure and viscous drag force. The fluid can be
compressible or incompressible and also non-Newtonian with the same limitations that there are in the Elmer
Navier-Stokes Equation solver. The force calculation is based on a flow solution (velocity components and
pressure) which has to be present when calling the procedure. Also the torque with respect to a given point
can be requested.

50.2 Theory
The force due to fluid is calculated as a product of the stress tensor and normal vector integrated over the
surface Z
F~ = σ · ~n dS. (50.1)
S
The stress tensor is
2
σ = 2µε − µ(∇ · ~u)I − pI, (50.2)
3

where µ is the viscosity, ~u is the velocity, p is the pressure, I the unit tensor and ε the linearized strain rate
tensor, i.e.
 
1 ∂ui ∂uj
εij = + . (50.3)
2 ∂xj ∂xi

The torque about a point ~a is given by

~τ = (~r − ~a) × F~ (~r), (50.4)
where ~r is the position vector.

CSC – IT Center for Science

50. Fluidic Force 247

50.3 Additional output

There is also a feature for saving the tangential component of the surface force i.e. the shear stress elemen-
twise on the boundaries. The shear stress output is written on disk in a file which contains three columns:
1) the value of the shear stress, 2 and 3) the corresponding x and y coordinates. The shear stress is saved
on all boundaries where fluidic force computation is requested. This feature is implemented only for 1D-
boundaries of 2D-geometries.

50.4 Keywords
Solver solver id
Equation String Fluidic Force
Procedure File "FluidicForce" "ForceCompute"
Calculate Viscous Force Logical [True]
Setting this flag to false disables the viscous drag force, and only the surface integral of pressure
is calculated.
Sum Forces Logical [False]
By default the solver calculates the fluidic force by boundaries. Setting this flag to True applies
summing of each individual boundary force in to a resultant force which is the only force vector
in output.
Shear Stress Output Logical [False]
Setting this flag to True activates writing shear stress values on disk.
Shear Stress Output File String [shearstress.dat]
Defines the name of the shear stress file.
Velocity Field Name String
The name of the velocity field variable. This keyword may be necessary if some other flow
solver than the built-in Navier-Stokes solver of Elmer is used. Normally this keyword should be
omitted.
Material mat id
Viscosity Real
Boundary Condition bc id

Calculate Fluidic Force Logical [True]

The fluidic force is calculated for the surfaces where this flag is set to true.
Moment About(dim) Real
Coordinates for the point on which the torque is returned.

CSC – IT Center for Science

Model 51

Electrostatic force

Module name: ElectricForce

Module subroutines: StatElecForce
Module authors: Antti Pursula
Document authors: Antti Pursula

51.1 Introduction
This solver calculates the electrostatic force acting on a surface. The calculation is based on an electrostatic
potential which can be solved by the electrostatic solver (see Model 16 of this Manual).

51.2 Theory
The force is calculated by integrating the electrostatic Maxwell stress tensor [1] over the specified surface.
Using the stress tensor T the total force on the surface S can be expressed as
Z
F~ = ~
T · dS. (51.1)
S

The components of the Maxwell stress tensor for linear medium are
1 ~ ~
Tij = −Di Ej + δij D · E, (51.2)
2
~ and electric displacement field D
where electric field E ~ are obtained from the electric potential Φ

~ = −∇Φ,
E (51.3)

and
~ = −ε0 εr ∇Φ,
D (51.4)
where ε0 is the permittivity of vacuum and εr is the relative permittivity of the material, which can be a
tensor.

51.3 Keywords
Constants
Permittivity Of Vacuum Real [8.8542e-12]
Solver solver id

CSC – IT Center for Science

BIBLIOGRAPHY 249

Equation String Electric Force

The name of the equation. Not necessary.
Procedure File "ElectricForce" "StatElecForce"
Exec Solver String After Timestep
Often it is not necessary to calculate force until solution is converged.

Material mat id
Relative Permittivity Real
Boundary Condition bc id

Calculate Electric Force Logical True

This keyword marks the boundaries where force is calculated.

Bibliography
[1] J. Vanderlinde. Classical electromagnetic theory. John Wiley & Sons, 1993.

CSC – IT Center for Science

Model 52

System Reduction for Displacement

Solvers

Module name: RigidBodyReduction

Module subroutines: RigidBody
Module authors: Antti Pursula
Document authors: Antti Pursula

52.1 Introduction
This module is used to reduce and simplify the computation of a displacement solver when the problem
includes rigid blocks. In such a case, it is often difficult for iterative solvers to find a solution for the full
system, and direct solvers become obsolete when the system is large enough. The convergence and also the
speed of the solution can be substantially improved when the degrees of freedom corresponding to the nodes
belonging in the rigid blocks are reduced onto the 6 DOFs (3 in 2D) of the corresponding rigid body. In the
module, the reduction is achieved via a projection matrix.
Additionally, the routine automatically eliminates the degrees of freedom corresponding to the Dirichlet
boundary conditions. It is also possible to request the elastic regions to be extended into the rigid blocks.
There is also possibility to reorder the reduced matrix elements to decrease its bandwidth.

52.2 Theory
The module starts with normally constructed matrix equation for the unknown displacements x, Ax = b.
Let us assume that the nodes are ordered in such a way that the first n elements of the vectors correspond to
the elastic parts of the structure and the remaining m elements correspond to the rigid parts of the structure.
The goal is to reduce the (n + m) × (n + m) matrix A to a (n + αk) × (n + αk) matrix B, where k is 3
for 2D and 6 for 3D problems and α is the number of rigid blocks present. Reductions are made also for the
vectors so that finally the matrix equation reads Bu = f .
The relation between the unknowns is
x = P u, (52.1)
where the projection matrix P ties the nodes in the rigid bodies to the same displacements in coordinate
directions and the same rotations about the coordinate axis. The rotations are defined with a coordinate
system whose origin is at the center of each rigid body. For the right hand sides we can write
f = Qb, (52.2)
where the matrix Q sums the forces and torques present at the nodes in rigid bodies for a resultant force and
torque of the center point of the corresponding rigid body. In both mappings, the rotations are linearized so
the module is valid only for cases where the rotations are small.

CSC – IT Center for Science

52. System Reduction for Displacement Solvers 251

Using these definitions, we have

Ax = AP u = b (52.3)
and
Bu = f = Qb. (52.4)
Combining the equations gives Bu = QAP u and thus

B = QAP. (52.5)

With a suitable order of the rotations one can write

Q = P T ≡ C, (52.6)

and
B = CAC T . (52.7)
The matrix C has a identity matrix block of size n × n which keeps the elastic nodes intact, and a projection
block of size αk × m.
The reduced order solution u is transformed back to the original nodes by the same mapping

x = C T u. (52.8)

52.3 Applicable cases and limitations

The module works for

• Linear steady-state problems

• Linear transient problems
• Eigen analysis
• Quadratic eigenproblems

There are following limitations:

• Rigid blocks should not have common nodes (there should be elastic nodes in between rigid blocks)
• If a Dirichlet bc is given on a node of a rigid block then the entire rigid block is assumed to be fixed
in all directions

52.4 Keywords
Body body id
Rigid Body Logical
Value True defines the rigid body.
Solver solver id
The module does not need a separate solver but a call in the stress analysis, or the elasticity solver in
the linear mode.
Equation String Stress Analysis
Variable String Displacement
Variable DOFs Integer
It is important to give the DOFs right, either 2 or 3 depending on the dimension.

CSC – IT Center for Science

52. System Reduction for Displacement Solvers 252

Before Linsolve File "RigidBodyReduction" "RigidBody"

The model order reduction is performed after the matrix has been assembled but before the
matrix equation has been solver. The matrix equation is modified to a smaller equation and the
new equation is solved within the subroutine.
Eigen Analysis Logical
It is possible to use the model order reduction with modal analysis, as well as with static and
transient cases.
Eigen System Values Integer
The number of eigen values to be computed.
Eigen System Damped Logical
Eigen System Use Identity Logical [True]
The reduction is possible also with quadratic (damped) eigenproblems.
Optimize Matrix Structure Logical
If true, the matrix structure is optimized. This feature is recommended since the reduced ma-
trix has often very scattered structure. The optimization is performed with the Cutholl-McKee
algorithm.
Reverse Ordering Logical
This flag can be used to reverse the matrix ordering if the matrix structure is optimized, resulting
in reverse Cuthill-McKee ordering.
Extend Elastic Region Logical
If true, the elastic regions of the geometry are extended into the rigid block. This feature allows
taking into account the bending in the joints between elastic and rigid parts.
Extend Elastic Layers Integer
Defines the number of element layers that the elastic regions are extended.
Output Node Types Logical
Writes in the ElmerPost output file a variable describing the status of each node in the geometry.
The variable has value 0 for elastic nodes, -1 for rigid blocks that are fixed due to a Dirichlet
boundary condition, and a positive integer for separate rigid blocks. The variable may be used
to check that the reduction is performed on the right blocks, and to check how many layers the
elastic regions should be extended, for example.
Additional Info Logical
If true, additional information is written about the performed tasks during the simulation.

52.5 Examples

CSC – IT Center for Science

52. System Reduction for Displacement Solvers 253

Cpu times for matrix reduction (circles)

100

90

80

70
Cpu time in seconds

60

50

40

30

20

10

0
0 0.5 1 1.5 2 2.5 3
Number of degrees of freedom 5
x 10

Figure 52.1: The cpu time required for the matrix reduction operations depends linearly on the degrees of
freedom in the system.

CSC – IT Center for Science

52. System Reduction for Displacement Solvers 254

52.6 Interpolate, Filter, and Find Data

CSC – IT Center for Science

Model 53

Filtering Time-Series Data

Module name: FilterTimeSeries

Module subroutines: FilterTimeSeries
Module authors: Peter Råback
Document authors: Peter Råback
Document updated: 13.2.2008

53.1 Introduction
The module includes auxiliary utilities for filtering time-series data. Supported filters include various aver-
aging possibilities and Fourier series, for example. The solver does not introduce any new physics. However,
it may be useful in analyzing time-dependent data to be used in conjunction with time-harmonic models, or
in studying phenomena with different timescales (turbulence).

53.2 Theory
Mean of a function
The solver is built so that an estimate for the filtered data may be obtained at all times i.e. the normalizing
is done after each timestep. As an example let’s consider taking a simple mean over a period of time. The
starting point is the time averaged mean,
Z T
1
< f >T = f (t) dt. (53.1)
T 0

Its discrete counterpart assuming piecewise constant integration is

n
1 X
< f >n = fi dti , (53.2)
Tn i
P
where Tn = dti . Now this may be presented inductively as

Tn−1 < f >n−1 +fn dtn

< f >n = (53.3)
Tn−1 + dtn
Tn = Tn−1 + dtn . (53.4)

CSC – IT Center for Science

53. Filtering Time-Series Data 256

Weighted mean
It’s also possible to take a weighted mean with a user defined function g(t) depending on time only. Then
similarly,
Tn−1 < f g >n−1 +fn gn dtn
< f g >n = . (53.5)
Tn−1 + dtn

Fourier series
Using the weighted mean as starting point its possible to present the solution in terms of sine and cosine
series. In order to obtain normalized Fourier series components the function g is internally replaced by sine
and cosine functions defined as 2 sin(2πkwt) and 2 cos(2πkwt), where k is the degree of the term, and w is
the user defined frequency. After each full cycle the inner product then includes the Fourier coefficients and
the transient solution may hence be approximated by
ms
X mc
X
f≈ sk sin(2πkwt) + ck cos(2πkwt), (53.6)
k=1 k=1

where ms and mc are maximum degrees defined by the user.

Continuous average
Sometimes it may be useful that the new solution is given a relatively higher weight than the old solution.
This is achieved by relaxing the weight (elapsed time) related to the old solution by

Tn−1 := Tn−1 exp(−dtn /τ ), (53.7)

where τ is the time scale when decay to fraction 1/e is desired. If the decay time is short compared to the
overall simulation time this provides a continuous mean that represents only the recent results. The fraction
of the last timestep in solution will always be dt/τ .

Computing variances
It is not possible to compute the variance directly with one sweep as computing the variance from the
functional values requires the knowledge of the mean. However, computing the mean of the square of the
solution enables that the variance is computed a posteriori since the following holds for any field variable,

σ 2 =< (f − < f >)2 >=< f 2 > − < f >2 . (53.8)

53.3 Keywords
Solver solver id
Procedure File "FilterTimeSeries" "FilterTimeSeries"
Variable i String
The names of the variables to be filtered. There can in principle be up to 99 variables. Note that
the keywords with the same i form a set which define one filtering. If the Variable is not
redefined the previously defined variable with a lower i is used.
Operator i String
Normally the variable is treated as its plain value. There are however different options for using
the field value in a modified manner. These include length (L2 norm), abs, and square.
Start Time i Real
The start time for performing the integration. Note that for Fourier series this is used to reset the
zero time i.e. t := t − t0 .

CSC – IT Center for Science

53. Filtering Time-Series Data 257

Stop Time i Real

The stop time for performing the integration.
Start Timestep i Integer
Sometimes its unpractical to compute the start time. For example, the start of the simulation
could include a starting strategy with a number of timesteps. Then the number of timesteps
that starts the averaging may be given by this keyword. Note that this keyword also activates
timestep-insensitive averaging.
Stop Timestep i Integer
The timestep number that ends the averaging.
Start Cycle i Real
Alternative way to give the start time for sine and cosine series. The start time is the inverse of
this.
Stop Cycle i Real
Alternative way to give the stop time for sine and cosine series.
Start Real Time Real
Start after given real wall-clock-time, rather than physical simulation time.
Start Real Time Fraction Real
Relative way of given start time when the Real Time Max keyword in Simulation block
is given.
Reset Interval i Real
The time interval at which the computation of a mean is reinitialized.
Decay Time i Real
The decay time τ in computing continuous means.
Decay Timestep i Real
The number of timestep needed to perform averaging. If the timestep given is N then the decay of
the previous timesteps is done with exp(−1/N ). Note that this keyword also activates timestep-
insensitive averaging.
Time Filter i Real
The function g(t) that may be used in computing the mean.
Sine Series i Integer
The number of terms in the sine series. Note that its possible to make a Fourier series only if the
target variable is a scalar. Its also possible to have only one sine or cosine series at a time.
Cosine Series i Integer
The number of terms in the cosine series.
Frequency i Integer
If using cosine or sine series the frequency must be given.

CSC – IT Center for Science

Model 54

Data to field solver

Mdule name: DataToFieldSolver

Module subroutines: DataToFieldSolver
Module authors: Peter Råback
Document authors: Peter Råback

54.1 Introduction
This subroutine may be used fit data to a continuous field. In principle just a simple identity equation with
some diffusion for regularization is solved. The origin of the data could be from a particle trace of a Monte-
Carlo simulation, measurement data read from an external file, etc.

54.2 Theory
Galerkin method minimizes the L2 norm of the solution and is therefore a good choice also for problems
where a regular field must be fitted into data. Imagine a case where we have an initial field fˆ and want to a
field f on it. Then we need to solve an equation f = fˆ with the Galerkin method. Now if the initial data
is noisy the fitting should include some regularization. The natural way to introduce regularization in this
context is to add artificial diffusion such that we are really solving for

− ∇ · D∇f + f = fˆ (54.1)

which is a linear diffusion-reaction equation. The weak formulation for this is

Z Z Z Z
∂f
D∇f · ∇ψ dΩ − D dΓ f dΩ = fˆ dΩ (54.2)
∂n
Now the data could be given already in the integral form i.e. as
Z
F̂ = fˆ dΩ. (54.3)

Also the user may know the weight w that was accumulated when the data was generated.
The data may not always be accurate or even given. Therefore using the given data in all fields might not
be a good idea. We may introduce a masking field, say p ∈ [0, 1], that picks the values that are considered
as accurate. On the other hand diffusion, might not be needed for those points.
Adding these generalizations we obtain the following form
Z Z Z Z
∂f
(1 − p)D∇f · ∇ψ dΩ − D(1 − p) ψ dΓ + p w f ψ dΩ = p fˆψ dΩ + p F̂ . (54.4)
∂n
This formulation enables the use of various techniques for data fitting.

CSC – IT Center for Science

54. Data to field solver 259

54.3 Keywords
Below are the dedicated keywords for the solver. In addition generic keywords such as many of those related
to Linear System solution methods may be used.

Solver solver id
Equation String [DataToFieldSolver]
The name of the equation.
Procedure File "DataToFieldSolver" "DataToFieldSolver"
The name of the procedure.
Variable String [FieldName]
The name of the resulting field.
Target Variable String
Name of the scalar field to be used as input data. This is either fˆ or F̂
Diffusion Coefficient Real
The value of the diffusion constant used in the regularization.
Normalize by Nodal Weight Logical
Normalize the particle properties with nodal weight i.e. the standard mass matrix. This would
be a good choice if the right-hand-side is a result of an integral i.e. F̂ .
Normalize by Given Weight Logical
Normalize the particle properties i.e. divide the trace with the corresponding weight. Basically
this corresponds to the integral over w. Here an integral data set is assumed such that it is
consistent with the given weight.
Weight Variable String
If there is a weight associated to the data the name of it should be given with this function.
Set Constant Weight Sum Logical
If the weights are provided by the user and this flag is set True then the given weights are
normalized so that their sum is always the same as the sum of nodal weights. The idea is that
the solution will be independent on the given level of the weight, and only depend on the relative
sizes.
Mask Variable T
he data points may selectively chosen to be considered. If a mask variable is given it may have
both lower and upper boundaries. Only if the mask variable is between these bounds will the
data be considered. Effectively p = 1 in the interval, and p = 0 outside the interval.
Max Mask Value Real
Maximum value for the mask interval. Default is +HUGE.
Min Mask Value Real
Minimum value for the mask interval. Default is -HUGE, except if the maximum interval is not
given either. Then the default is 0.
Mask Diffusion Logical
If the mask is true, should diffusion be neglected. Default is False.
Boundary Condition bc id
FieldName Real
The user may set Dirichlet conditions for the field to be fitted if they are known.
FieldName Continue Logical
Enforce boundary conditions with constant slope. The default boundary condition is otherwise
the natural boundary condition with zero gradient.

CSC – IT Center for Science

Model 55

Projection to plane

Module name: ProjectToPlane

Module subroutines: ProjectToPlane,ParallelProjectToPlane
Module authors: Juha Ruokolainen and Peter Råback
Document authors: Peter Råback

55.1 Introduction
Sometimes the solution of a complex problem calls for a dimensional reduction of some field variables. A
possible scenario for using the solver is in extracting some useful information from DNS or LES type of
flow simulations. This module offers the subroutines needed in such a cases.
There are currently a serial and a parallel version of the subroutine which are both located in this module.
The reason for the fork is that the parallel version uses techniques that are not optimal in the serial problem.
Therefore the user should herself choose the correct version. Optimally these two approaches should of
course be fused.

55.2 Theory
In principle the dimensional reduction is performed taking on average of a 2D (or axisymmetric) nodal point
~r2D when it travels through the 3D mesh.
Z
1
f2D (~r2D ) = f (~r3D ) dS. (55.1)
S
In practice this is implemented with the following steps
1. Create a list of faces for the 3D mesh
2. Loop though each nodal point in the 2D mesh
(a) Loop through each face in the 3D mesh
i. Check if there is an intersection between the integration line and face
ii. If intersection found memorize the point of intersection
(b) Order the intersection points in the integration direction
(c) Take a weighted average over the ordered list, (fi , ri )
The algorithm is accurate for linear elements. For higher order elements it is suboptimal in accuracy. Also
in axisymmetric mapping the elements should be small enough so that the curvature of the line segment is
not significant. Near the origin there may be few hits and then the averaging is done by just taking a small
number of values around the center axis.

CSC – IT Center for Science

55. Projection to plane 261

55.3 Keywords
Solver solver id
Equation ProjectToPlane
The arbitrary name of the equation.
Procedure File "ProjectToPlane" "ProjectToPlane"
or
Procedure File "ProjectToPlane" "ParallelProjectToPlane"
Convert From Equation Name String
The solver needs a 3D mesh which is associated determined by the association to the solver given
by this keyword.
Convert From Variable String
The variable to be converted.
Volume Permutation Integer
The algorithm is build so that integration direction is the second coordinate (y). This is typically
valid for axisymmetric cases, for example. If the integration should be performed with respect
to some other direction the volume coordinates may be permuted by this keyword.
Plane Permutation Integer
Permutation of the plane coordinates.
Rotate Plane Logical
Should rotation be performed.
Max Relative Radius Real
For the axisymmetric projection the outer radius may be difficult since the 3D mesh typically
may have faces that do not quite extend to the surface. This is a result of finite sized linear
elements. To ease this problem the user may give the maximum relative radius that is used when
trying to find the point of intersection.
Minimum Hits At Radius Integer
The number of hits needed for a accepted integration. The default is one.
Integration Points At Radius Integer
If no minimum number of hits is achieved then a few points around the axis are used to determine
the value. The default is two.

CSC – IT Center for Science

Model 56

Structured projection to plane

Module name: StructureProjectToPlane

Module subroutines: StructureProjectToPlane
Module authors: Peter Råback
Document authors: Peter Råback

56.1 Introduction
For structured meshes some operations may be done much more effectively than for generic meshes. One
such operation is mapping some values within the mesh to the reduced dimensional surface of the mesh.
In practice this could mean, for example, mapping the values at the bottom of mesh to the top of mesh to
determine the difference in value. Or to map some isosurface values to the top of the mesh.

56.2 Theory
The algorithm used for the mapping has two sweeps. Assume that we would like to perform mapping
in direction ~ez . At the first sweep over all elements we would deduce pairwise information over nodes
on which nodes are in up and down directions from each other. Then using this directional information
recursively one can easily deduce which nodes are the top and bottom representatives of any node in the
mesh. With this information mapping information to top or bottom nodes, or to the whole mesh becomes
extremely cheap.

56.3 Keywords
Solver solver id
Equation String [StructuredProjectToPlane]
The name of the equation.
Procedure File "StructuredProjectToPlane" "StructuredProjectToPlane"
The name of the procedure.
Velocity Variable Name String
Name of the variable used to define the streamlines.
Active Coordinate Integer
The direction in which the structured mapping is performed i.e. 1, 2 or 3.
Project To Bottom Logical
Instead of projecting to the top of the active direction, project to the bottom.

CSC – IT Center for Science

56. Structured projection to plane 263

Projection Mask Variable String

By default the projection is performed assuming that the whole mesh is active. This keyword
may be used to choose the variable that chooses the active set of nodes user in the projections.
Dot Product Tolerance Real
When determining the structure of the mesh in the active direction this tolerance is used to decide
that an element edge is aligned with the direction of the action.
Project to Everewhere Logical
By default the operators height, depth, thickness, distance and index are mapped
to the whole mesh. The other operators are mapped to the top only, if not else specified. This
keyword will always map all operators to the whole mesh.
Variable i String
When applying the different projections, the variable to apply the projection to. The resultant
field will obtain as the name the name of the operator followed by the initial variable name.
Operator i String
The operator to apply to the variable or just the geometry. The choices are
• sum: sum over all nodes on the structured line
• int: integral over the structured line using trapezoidal rule
• min: minimum value over the line
• max: maximum value over the line
• bottom: field value at the bottom layer
• top: field value at the top layer
• middle: field value at the middle layer
• thickness: thickness of the object i.e. the length of the line
• depth: depth i.e. distance from the top surface
• height: height i.e. distance from the bottom surface
• distance: minimum distance to either top or bottom surface
• index: number of the layer from the bottom
• layer below top: field value at layer below the top
• layer above bottom: field value at layer above bottom
• isosurface: field value at the given value of the isosurface variable
Layer Index i Integer
The number of structured layers from the top or bottom layer when appropriate. The index i
refers to the corresponding variable and operator.
Isosurface Variable i String
The variable used to determine the isosurface position.
Isosurface Value i Real
The value for the isosurface position.
Target Variable i String
By default the target variable is created using the name of the variable and operator. However,
the user may also give the target variable using this keyword. Then it should be allocated before.
Target Variable i At Bottom Logical
Create a target variable that is not at top but at bottom instead.
Target Variable i At Middle Logical
Create a target variable that is not at top but at middle instead.
Target Variable i Everywhere Logical
Create a target variable that is not at top but everywhere.

CSC – IT Center for Science

Model 57

Internal Cost Function Optimization

Module name: FindOptimum

Module subroutines: FindOptimum
Module authors: Peter Råback
Document authors: Peter Råback

57.1 Introduction
This solver is an auxiliary solver for optimization problems. As input it requires a cost function computed
with the previous parameter values, and as output it gives the new parameters for which the cost function will
be computed for. Typically the cost function depends on the solution of one or several differential equations.
Based on this solution a measure of goodness for the solution is computed.
The routine is still in its development phase but is provided as a skeleton that may be further developed.

57.2 Theory
The optimization routines must be slightly modified from their standard form since the solver is not in a
ruling position in respect to the simulation. Therefore its difficult to plug in existing optimization packages
to this solver.
Currently the solver includes some very basic optimization routines. Of these the Simplex algorithm
(Nelder-Mead) and the differential GA (Genetic algorithm) are the only ones that may be used for a number
of design variables.
For just one design variables there is the choice of simple scanning, bisection search and the secant
method. Secant method finds roots making it better suited for problems where the target is known i.e. design
problems.

57.3 Keywords
Simulation
Simulation Type String ”scanning”
The natural mode used for optimization problems is scanning. If the problem is really time-
dependent the current internal solution is not probably the optimal solution.
Timestep Intervals Integer
The maximum number of optimization rounds is in the case of scanning defined by the timestep
intervals.

Solver solver id

CSC – IT Center for Science

57. Internal Cost Function Optimization 265

Equation String FindOptimum

A describing name for the solver.
Variable String OptPar
The name of the variable may be freely chosen as far as it is used consistently also elsewhere.
Variable DOFs Integer n
Degrees of freedom for the pressure. Here n should be equal to the number of parameters.
Variable Global Logical True
Indicates the variable is a global one i.e. not a field variable. For global variables the number of
unknowns is the same as number of dofs.
Procedure File "FindOptimum" "FindOptimum"
The name of the module and procedure. These are fixed.
Optimization Method String
Choices are currently random, scanning, genetic, bisect, secant and simplex.
Cost Function Name String
The name of the cost function that is a real stored in the Simulation list structure.
Optimal Restart Logical
Use the previous best set of parameters for the 1st round of cost function computation.
Optimal Finish Logical
Use the best set of parameters for the last round of cost function computation. This may be useful
as the last step is often also saved.
Best File File [best.dat]
The file were the best set of parameters is always saved.
Guess File File [best.dat]
The file were the best set of parameters is read in case of optimal restart.
Fixed Parameter i Logical
Is the i:th parameter fixed. Applies for some optimization routines.
Min Parameter i Real
Minimum value for i:th parameter. Applies for some optimization routines.
Max Parameter i Real
Maxium value for i:th parameter. Applies for some optimization routines.
Initial Parameter i Real
Initial value for i:th parameter if not given by the Optimal restart
Internal history Logical
Save the internal values within the solver.
History File File
The name of the file where the history data is saved.
Cost Function Target Real
If the given cost function is C use C − C0 instead.
Cost Function Absolute Logical
If the given cost function is C use |C| instead.
Cost Function Maximize Logical
If the given cost function is C use −C instead.
The following keywords apply to the GA algorithm
Population Size Integer [5n]
Population Coefficient Real [0.7]
Population Crossover Real [0.1]

CSC – IT Center for Science

57. Internal Cost Function Optimization 266

The following keywords apply to the simplex algorithm

Simplex Relative Length Scale Real [0.01]
The relative length scale that determines the size of the 1st simplex.
Simplex Restart Interval Integer
The restart interval after which the simulation is restarted if the convergence is poor.
Simplex Restart Convergence Ratio Real
A critical value which is used to define a poor convergence ratio.
The following keywords apply to the secant method

Step Size Real

The step size of the first computations.
Max Step Size M
aximum allowed step size.
Relaxation Factor R
elaxation used in the secant method.

This shows just a couple of examples how the design parameters could be used in the simulation. The
variables may be referred in a similar manner as other global variables such as time or timestep size.

Body Force 1
Heat Source = Equals OptPar 1
End

Boundary Condition 1
Heat Flux = Equals OptPar 2
End

CSC – IT Center for Science

 Part IX

Saving Data and Results

CSC – IT Center for Science

Model 58

Saving Scalar Values to a File

Module name: SaveData

Module subroutines: SaveScalars
Subroutine authors: Peter Råback
Document authors: Peter Råback
Document updated: January 8th 2008

58.1 Introduction
This subroutine may be used to compute derived quantities and saving scalar values to external file. The
results are easily then utilized by MatLab, Excel or any other program that can read ASCII data. In addition
to the number values also an additional file with the suffix .name is saved. It tells what variables are at each
column.

58.2 Theory
The equations and algorithms needed for the computation of scalar values are relatively simple. Here some
of them are introduced.
When saving statistical information there are two possibilities. We may use normal number statistics
where each node is given an equal weight. Then, for example the mean becomes,
Pn
fi
< f >= i=1 . (58.1)
n
The other possibility is to treat the variable as a continuous function and compute the statistical values as
averages over the domain. Now the mean is
R
f dΩ
< f >= R . (58.2)
dΩ
In addition to the mean we may compute the mean deviation, < |f − < f > | >.and the variance δf =
p
< f 2 > − < f >2 .
It is possible to compute energy type of lumped quantities by integrating over the domain. The energy
of the field f resulting from a diffusion equation is
Z
1
Edif f = ∇f · c∇f dΩ, (58.3)
2 Ω
where c may a tensor or a scalar. Kinetic energy related to convection is of type
Z
1
Econ = c~v · ~v dΩ, (58.4)
2 Ω

CSC – IT Center for Science

58. Saving Scalar Values to a File 269

and potential type of energy Z

Epot = cf dΩ. (58.5)
Ω
Sometimes it may be interesting to compute the fluxes through surfaces. The values may be used in
evaluating the accuracy of the results – what goes in should in steady state also come out. There are two
different fluxes that may be computed. For convective field the flux is of type
Z
Fcon = cf~v · ~n dΓ. (58.6)
Γ

Currently the code automatically detects the dimension of the given variable. If it is scalar f then ~v is
assumed to be the velocity computed by Navier-Stokes equation. If the given variable is vector then it is
used as the velocity field and f is not present. Here ~n is the surface normal.
Diffusive fluxes may be computed from
Z
Fdif f = c∇f · ~n dΓ, (58.7)
Γ

where c may also be a tensor.

58.3 Implementation issues

There are many solvers that internally compute lumped quantities. By convention these are added to the list
structure of the Simulation section in the following style
CALL ListAddConstReal( Model % Simulation,’res: capacitance’,Capacitance)
By default the solver looks through quantities starting with prefix res: and saves them to an external file.
Also the user may create new quantities to be saved in similar manner.

58.4 Keywords
Solver solver id
Procedure File "SaveData" "SaveScalars"
Filename String
Name of the file where results are to be saved. If no filename is given then the results will only
be echoed on output.
Output Directory String
Name of the directory where results are to be saved, relative to the case directory. By default the
results are saved in the case directory.
Scalars Prefix String
Save constants starting with this prefix. The default is res:.
Variable i String
The names of the variables to be saved. There can be up to 99 variables. In addition to field
variables there are some special variables. The scalar variables. e.g. Time, are saved as is.
There are also variables CPU Time and CPU Memory that may be used to save execution
details.
Target Variable i String
This is an optional keyword that for each entry computed by the subroutine may give an alter-
native name that is placed as a proper variable in the model. This variable may then be used
similarly to time in functional expressions. Note that if the operator creates several output val-
ues the numbering of this is not the same as that of Variables. So check the output file for
correct entries when in doubt.

CSC – IT Center for Science

58. Saving Scalar Values to a File 270

Mask Name i String

If the operator is such that it can use masks then this keyword may be used to override the default
mask name Save Scalars.
Save Points(n) Integer
Save the specified degrees of freedom in the n nodes specified.
Save Coordinates(n,DIM) Real
Save the degrees of freedom in the nodes nearest to the given n coordinates.
Exact Coordinates Logical
When this keyword is true the coordinates will be looked in an exact manner. Then the degrees
of freedom are linear combinations of the node values of the element that the point belongs to.
Moving Mesh Logical
If this parameter is True the saved points will be defined every time the subroutine is visited.
The default is False.
File Append Logical
If the results from consecutive rounds should be appended to the file this flag should be set to
True. The default is False.
Filename Numbering Logical
If set to true a running index is added to the filename so that the next free filename is used to
save the results.
Partition Numbering Logical
Optionally add the number of partitions to the filename. This makes the benchmarking more
convenient since each case may use the same command file without conflicts.
Show Norm Index Integer
The user may choose to output one value of the results as the norm of the solver in a similar
output syntax as ComputeChange shows its norms. This is of course not a real norm but may
be used in monitoring desired convergence measures in ElmerGUI, for example. By default no
norm is shown.
Echo Values Logical
When this is turned on the scalar values will also be echoed to the screen. This is the default
action also when the filename is not given and hence nothing is saved to file.
Cost Function Index T
he user may also choose to save a desired value in the list structure with the name Cost
Function. This may be utilized by the FindOptimum solver in optimization problems.
Parallel Reduce Logical
By default the output is written independently for each partition in parallel runs. Enabling this,
however, the information is reduced to just one file. The reduction is done using MPI_ALLREDUCE:
MPI_MAX, MPI_MIN, MPI_SUM. The default is MPI_SUM. Parallel operator is controlled
with keyword Parallel Operator. These are not sufficient for all operators. By default
the value of the 1st partition is written.
Save Eigenvalues Logical
Save the eigenvalues found in any of the variables.
Save Eigenfrequencies Logical
Save the frequencies computed from the eigenvalues found in any of the variables.
Operator i String
There are different operators that may be performed on all the given variables. These include
statistical operators working on the set of numbers, max, min, max abs, min abs,
mean, rms, variance and deviation. Note that these operate directly on the result
vector and do not employ the mesh in anyway.
Different scalar quantities are obtained also by domain integral operators over the mesh. Opera-
tor int gives the integral over a variable, int mean the mean value, int rms the root mean

CSC – IT Center for Science

58. Saving Scalar Values to a File 271

square, and int variance the variance of the variable. The volume used by a given variable
is obtained by operator volume. If a name for the coefficient, is given for the operator, the
integral is taken over the coefficient. One can for example obtain the weight from a integral over
Density. Three different energy type of energy quantities may be computed by diffusive
energy, convective energy, potential energy, volume.
By default the statistical and integral operators are performed over the whole mesh. However,
the user may apply the operator only to some parts of the mesh that are related to the logical
entities of the sif file. Currently these entities are body, body force, and material. If the
user wants to select some of these parts then the standard operator should be preceded by the
name of the section. For example, there could be operators body max or body force int.
There are also a number of similar operators that only operate on the boundary. These are invoked
by boundary sum, boundary dofs, boundary mean, boundary max, boundary
min, boundary max abs, boundary min abs, area, boundary int, and boundary
int mean. Also boundary integrals are possible using operators diffusive flux, convective
flux, boundary int, boundary int mean and area. These require that in the bound-
ary conditions the active boundaries are defined. Also here there may be an optional coefficient.
Some operators do not work on the solution itself but use other info related to that. Operator
dofs simply returns the length of the variable under study. Operator norm returns the last com-
puted norm of the field variable, and operators nonlinear change and steady state
change return the last computed convergence measures at the nonlinear and steady state levels.
Operator nonlin iter returns the number of nonlinear iterations, while operators nonlin
converged and coupled converged which tell whether or not the simulation has con-
verged. Note that these operators most operate on the primary variable for which the matrix
equation is solved for.
Operator bounding box returns the minimum and maximum coordinate value of each coor-
dinate i.e. six values in 3D mesh.
Finally for parallel runs the operator partitions may be useful in creating parallel scaling
results in automated manner.
There is no upper bound to the number of operators or variables. If the variable is a vector the
statistics is performed on its length.
Coefficient i String
Even though only limited number of operators are given almost any energy or flux kind of quan-
tity may be computed since the coefficient c may be defined by the user. The idea is that the
same data that is already used as a material parameter can be simple referred to by its name. The
coefficient may be, Heat Conductivity, Permittivity, Density, for example. Usu-
ally the coefficient is the same that was used in computing the field variable under integration.
For the diffusive energy and diffusive flux the coefficient may even be a matrix.
This parameter is optional and the default is one.
Parallel Operator i String
Sometimes the default parallel reduction method is not the desired one. Therefore the user may
define the parallel reduction method by this keyword. The alternatives are min, max and sum.
Polyline Coordinates(n,DIM) Real
This keyword may be used to create line segments that are defined by points x1 , y1 , x2 , and y2 .
For each line different kinds of fluxes through the elements may be computed. This makes it
possible, for example, to check the mass flux even though no boundary has a priori been defined.
Save component results Logical
Save results arising from component sections.
Boundary Condition bc id
Save Scalars Logical
The flag activates the computation of boundary-related information. The results are treated inde-
pendently for each boundary. The keyword replaces the previously used Flux Integrate.
Also if Mask Name is given this arbitrary string may be used instead.

CSC – IT Center for Science

58. Saving Scalar Values to a File 272

If the user only wants a basic functionality of SaveScalars it is possible to let the system create
automatically an instance simply by:
Simulation
Scalars File File
Name of the file where the results are saved.
scalars: Keyword Type
Any keyword with the suffix scalars: is passed to the solver instance without the suffix.
By default the solver is executed after saving. With the namespace it is possible to include all keywords
(with the keyword type given) also in the simulation section. At some point the Simulation section will
get crowded making it justified to create a separate solver instance.

58.5 Examples
In the following examples it is assumed that the SaveScalars solver gets the first free index.

Range of solution
The following example shows how to deduce after each converged timestep the minimum and maximum
values of temperature to an external file.
Solver 2
Exec Solver = After Timestep
Equation = SaveScalars
Procedure = "SaveData" "SaveScalars"
Filename = "temprange.dat"

Variable 1 = Temperature
Operator 1 = min
Operator 2 = max
Operator 3 = int mean
End

Force resulting from flow solution

The following example shows how to compute the force resulting from the Navier-Stokes equation on the
boundary 3. It is assumed that for the flow solver is set Calculate Loads = True and that the name
of the solution vector is Flow Solution. Then the force acting on the boundary is obtained by summing
up the nodal forces on the boundary.

Solver 2
Exec Solver = After Timestep
Equation = SaveScalars
Procedure = "SaveData" "SaveScalars"
Filename = "forces.dat"

Variable 1 = Flow Solution Loads 1

Operator 1 = boundary sum
Variable 2 = Flow Solution Loads 2
Operator 2 = boundary sum
End

Boundary Condition 3

CSC – IT Center for Science

58. Saving Scalar Values to a File 273

Name = no_slip
...
Save Scalars = Logical True
End

Benchmark information
The following example shows how benchmark information from the computation of some potential equation
is gathered to one file. Different runs will append the results to the same file and in parallel runs the degrees
of freedom, number of partitions and consumed cpu time will be automatically gathered.

Solver 3
Exec Solver = After all
Equation = SaveScalars
Procedure = "SaveData" "SaveScalars"
Filename = timing.dat
File Append = Logical True
Variable 1 = Potential
Operator 1 = dofs
Operator 2 = partitions
Operator 3 = cpu time
Parallel Reduce = Logical True
End

CSC – IT Center for Science

Model 59

Saving data along lines to a file

Module name: SaveData

Module subroutines: SaveLine
Subroutine authors: Peter Råback, Ville Savolainen
Document authors: Peter Råback
Document updated: 10.6.2022

59.1 Introduction
The subroutine saves lines that pass through higher dimensional computational meshes. The data is saved
in simple matrix format thereby allowing the easy postprocessing of data by MatLab, Excel or any other
program that can read ASCII data. In addition to the number values also an additional file with the suffix
.name is saved. It tells what variables are at each column.

59.2 Theory
One mildly theoretical problem in saving data comes from the fact that the data should be saved in lines
that were not a priori defined. If there are relatively few points the dummy algorithm where each element
is checked for including the node may be used. For the lines, however, this algorithm might become quite
expensive as there may be many points that constitute the line and faster choices are needed.
Therefore we only look for intersections of element faces and the lines. Each element face is divided
into triangles. The triangle has points ~e1 , ~e2 and ~e3 . The line is drawn between points ~r1 and ~r2 . Therefore
the line goes through the point only if

~r1 + a(~r2 − ~r1 ) = ~e1 + b(~e2 − ~e1 ) + c(~e3 − ~e1 ) (59.1)

has a solution for which 0 ≤ a, b, c ≤ 1. This results to a matrix equation

    
r2x − r1x e1x − e2x e1x − e3x a e1x − r1x
r2y − r1y e1y − e2y e1y − e3y   b  = e1y − r1y  (59.2)
r2z − r1z e1z − e2z e1z − e3z c e1z − r1z

which may be easily solved with standard methods linear algebra. Because the face element is a triangle
there is an additional condition that b + c ≤ 1.

59.3 Keywords
Solver solver id

CSC – IT Center for Science

59. Saving data along lines to a file 275

Procedure File "SaveData" "SaveLine"

Filename String
Name of the file where results are to be saved, the default is sides.dat.
Output Directory String
Name of the directory where results are to be saved, relative to the case directory. By default the
results are saved in the case directory.
File Append Logical
If the results from consecutive rounds should be appended to the file this flag should be set to
True. The default is False.
Save Axis Logical
Save all the principal axis. Also keywords Save Axis i exist, where i=1,2,3 defines the axis.
Polyline Coordinates(n,DIM) Real
Save the line consisting of line segments defined by two points (n = 2). There can be more than
one set of points (n = 2, 4, 6, . . .) but as a line segment is defined by two points there must be
an even number of points.
Polyline Divisions(n/2,DIM) Integer
The user may give the number of divisions for each polyline. This allows also the proper saving
of discontinuous data. The size of this vector should be such that it is compatible with the number
of lines.
Save Isocurves Logical
Saves isocurves defined on 2D meshes.
Isosurface Variable i String
The variable which isocurve to save, i = 1, 2, . . .. This must be a scalar variable.
Isosurface Value i Real
A constant value that defines the value of the isosurface variable at the isocurve to be saved. Note
that for the same variable there may be several values, each with a different keyword.
Variable i String
By default SaveLine saves all the active variables. However, it is possible to save only a
specified list of variables given by this keyword where tt i=1,2,3,. . . This may be particularly
useful if one wants to save a table of linear dependence, for example Temperature along x-
direction, to be used as a boundary condition in consecutive Elmer runs with a different mesh.
Save Flux Logical
Saves a flux resulting from a gradient of a field by the model h = −κ∂T /∂n. This may only be
applied to existing boundaries, not lines defined by points.
Flux Variable String
The name of the field variable (default T is Temperature).
Flux Coefficient String
The diffusion constant (by default κ is Heat Conductivity)
Save Mask String
a By default SaveLine saves only the values that are on boundary marked with Save Line flag.
If the user wants several instances of the SaveLine subroutine, for saving different boundaries to
different files, the mask name may be defined by this keyword. The correspondingly one should
use the same flag in the Boundary Condition and Body section.
Optimize Node Ordering Logical
When saving data on pre-existing boundaries, should we try to optimize the order so that a
continuous line is created. This uses connectivity information that is optimal only when saving
1D data defined on lines. This is defaulted to True only for serial simulations.
Break Line Loop Logical
This is a keyword related to finding optimal node ordering. For loops the connectivity-based

CSC – IT Center for Science

59. Saving data along lines to a file 276

node ordering does not work properly. However, if we cut the loop at one point, the resulting
connectivity enables us to create a continuous loop. So use this only when you know that your
line creates a full loop.
Parallel Reduce Logical
By default the output is written independently for each partition in parallel runs. By enabling
this, however, the information is reduced to just one file when using predefined lines. The data
is communicated to the partition that owns most data to start with and it does the writing to the
file.
Boundary Condition bc id

Save Line Logical

The flag activates the saving of the boundary condition as a line. The subroutine tries to save
the finite-element lines as a chain of points to enable nice preprocessing with MatLab or similar
tools. The flux may only be saved on lines defined by boundary conditions.

59.4 Examples
In the following examples it is assumed that the 1st solver is the primary solver and the SaveLine solver
gets index two.
The following example shows how to save a line that extends from point (0,0,0) to point (1,2,3) in 3D
mesh after the whole simulation has ended using 100 divisions for both line segments.
Solver 2
Exec Solver = After Simulation
Equation = SaveLine
Procedure = "SaveData" "SaveLine"
Filename = "line.dat"
Polyline Coordinates(2,3) = 0.0 0.0 0.0 1.0 2.0 3.0
Polyline Divisions(2) = 100 100
End

CSC – IT Center for Science

Model 60

Saving material parameters and

boundary conditions

Module name: SaveData

Module subroutines: SaveMaterials, SaveBoundaryValues
Module authors: Thomas Zwinger
Document authors: Thomas Zwinger, Peter Råback
Document updated: 4.4.2011

60.1 Introduction
These subroutines creates fields from material parameter entries or boundary conditions that normally cannot
accessed as a field, as they are expressions that are evaluated when needed. The SaveMaterials may be
used to create additional field variables from the material parameters. A similar procedure SaveBoundaryValues
stores parameters defined on boundaries as variables for the whole mesh. This can be of help if a boundary
condition that is not directly accessible from the variables (like a normal component of a vector field) should
be evaluated in the post-processing step.

60.2 Keywords
Keywords of subroutine SaveMaterials
Solver solver id
Procedure File "SaveData" "SaveMaterials"
Parameter i String
The user may choose a number of parameters (i=1,. . . ,99) which will be save as variables. This
may be particularly handy if one wants to visualize how the parameters depend on the position
over the domain. Values in bodies with the assigned material list not containing the keyword of
the parameter are set to zero by default.

Keywords of subroutine SaveBoundaryValues

Solver solver id

Procedure File "SaveData" "SaveBoundaryValues"

Variable String -nooutput dummyvar
a dummy variable for the solver that does not show up

CSC – IT Center for Science

60. Saving material parameters and boundary conditions 278

Variable DOFs Integer 1

Parameter i String
The user may choose a number of parameters (i=1,. . . ,99) which will be save as variables. These
parameters will then be stored as variables with the values assigned as they were found on the
specific boundary. Bulk values and values on boundaries with the parameter not being defined
are set to zero by default.
Body Force Parameters Integer
The user may also save parameters given in body force section by giving the number of these
parameters by this keyword. Note that the body force parameters must be first in the list followed
by the material parameters. The default is zero.

CSC – IT Center for Science

Model 61

Result output in different formats

Module name: ResultOutputSolve

Module subroutines: ResultOutputSolver
Module authors: Peter Råback, Erik Edelmann, Mikko Lyly
Document authors: Peter Råback

61.1 Introduction
This subroutine is intended for saving data in other than the native format of Elmer – ElmerPost. The reason
for using another postprocessing tool might be that some feature is missing in ElmerPost, or that the user is
more acquainted with some other visualization software. Currently supported formats include GiD, Gmsh,
VTK legacy, XML coded VTK file bearing the suffix VTU and Open DX.
The recommended 3rd party visualization tool of Elmer results is Paraview and the corresponding format
for it is the Vtu format. The old VTK format is not recommended.

61.2 Keywords
Solver solver id
Equation String "ResultOutput"
The name of the equation. This is actually not much needed since there are no degrees of freedom
associated with this solver.
Procedure File "ResultOutputSolve" "ResultOutputSolver"
The name of the file and subroutine.
Output File Name File
Specifies the name of the output file.
Output Format String
This keyword the output format of choice. The choices are gid, gsmh, vtk, vtu, and dx.
Gid Format Logical
Gmsh Format Logical
Vtk Format Logical
Vtu Format Logical
Dx Format Logical
The user may also use the above logical keywords to set which of the formats is saved. This
has more flexibility in that there may be several formats that are saved simultaneously where the
Output Format keyword may only be used to activate one solution type.

CSC – IT Center for Science

61. Result output in different formats 280

Binary Output Logical

For Vtu format (no other format) the data may also be written in binary format which is signifi-
cantly more compact than the ASCII format. Default is True.
Ascii Output Logical
As the default format for Vtu is binary this keyword is more natural for enforcing ascii format.
The default is False.
Single Precision Logical
The floating numbers in Vtu format may be saved either in single (32 bits) or double (64 bits)
precision. The single precision saves some disk space. Default is False.
Eigen Analysis Logical
For GiD and Gmsh output format activates the eigenmode writing, and in Vtu format makes the
numbering of the files follow the eigenmodes. Vtu format will still save the eigenmodes without
this keyword but this will be done in the same file just altering the name of the field.
Number Of EigenModes Integer
Maximum number of modes, when supported. Default is that all eigenmodes are saved.
Active EigenModes Integer
List of active eigenmodes to be saved. Supported only in the Vtu format. By default modes are
saved in order (1,2,. . .).
The following keywords related only to the GiD, Vtu and Gsmh formats. In the other formats all
available degrees of freedom are saved. Also in Vtu format all dofs are saved if none of the list is
given.
Scalar Field i String
The scalar fields to be saved, for example Pressure. Note that the fields must be numbered
continuously starting from one.
Vector Field i String
The vector fields to be saved, for example Velocity
Tensor Field i String
The tensor fields to be saved. The rank of tensor fields should be 3 in 2D and 6 in 3D.
Sometimes when the variables need to be explicitly listed it may be difficult to know what the actual
available variables are. For this purpose there is the following keyword.
Show Variables Logical
Show all the different variables on output as a list. Default is False.
In the Vtu output format the user may use several various masking operations to choose the elements
to be saved. These cannot be used with other formats. Also the user may choose whether to save
elemental or nodal fields, if applicable.
Save Geometry Ids Logical
Save the index of geometric entities i.e. of the bodies and boundaries. The body index will be
saved as such whereas the boundary index will get a offset of 100 (or always 10 times larger if
not larger than largest body index).
Default Body Id Integer
This may be used to modify the default geometry id for the bodies when saving the geometry ids
in VTU format.
Default BC Id Integer
This may be used to modify the default geometry id for the boundary conditions when saving
the geometry ids in VTU format.
BC Id Offset Integer
This may be used to modify the offset from the default one when saving the geometry ids in
VTU format.

CSC – IT Center for Science

61. Result output in different formats 281

Save Elemental Fields Logical

There may be some elemental fields present, for example if they have been computed with the
Discontinuous Galerkin method. Then the elementwise nodal information is averaged to ele-
mental field. Elemental fields can present discontinuities better than the nodal fields, whereas
the nodal fields can represent smooth fields better.
Save Nodal Fields Logical
Save the computed nodal fields. Most fields are nodal only.
Lagrange Element Degree Integer
This keyword enables the visualization of results which have been obtained by applying hierar-
chic higher-order finite elements (the p-version of FEM). The value of this keyword defines the
polynomial degree of Lagrange interpolation elements which is used in the visualization. In prin-
ciple, it is reasonable to choose the value to be the same as the polynomial order of the p-solution
(defined by a command "Element = p:..." in a solver section), but the two values can be
chosen independently. At the moment this option works for the values up to 8 for quadrilaterals,
triangles and hexahedra, while tetrahedra and prisms allow values up to 4. Pyramids however
allow at most the second-order visualization.
Save Linear Elements Logical
For higher-order nodal (Lagrange) elements the user has the option to save the data still using
linear basis. This effectively saves only values at the corner nodes of each element. Often the
derived data from quadratic elements is just of linear accuracy and therefore there is no real
benefit in treating the actual quadratic data.
Discontinuous Galerkin Logical
When dealing with elemental fields there is the option to save the field as discontinuous such that
each instance of a node is recreated. This may make the resulting files huge but may still be the
desired option when dealing with discontinuous fields.
Discontinuous Bodies Logical
When dealing with elemental fields one can also create a minimal discontinuous set of nodes
such that the discontinuous information is averaged within shared nodes body-wise. Often the
discontinuity is present only over different bodies so this strategy maintains the essential discon-
tinuous while having only a minor effect on the file size.
Vtu Part Collection Logical
Save each part into a different file and include a file with .pvd suffix that acts as a container for
these individual parts. The parts may be recognized by their entity name.
Vtu Time Collection Logical
Save a time collection file with a .pvd suffix that includes the timestamps for each file in a
transient simulation.
Skip Halo Elements Logical
If halo element are used in the parallel computation this flag can be used to suppress the saving
of these elements. They are basically redundant so this flag could well be set to true for typical
use.
Save Halo Elements Only Logical
If halo elements are used then this flag can be used to save only the halo elements. This would
probably have mainly uses in debugging or demonstrating the halo elements.
Save Bulk Only Logical
Save the bulk elements only.
Save Boundaries Only Logical
Save the boundary elements only. This could be useful if one is interested of the results only at
the boundaries. This flag would also often save considerable amount of disk space.
Mask Variable String
The user may give a variable for masking. If this flag is given then only the elements where the
permutation vector associated with this variable is positive for all nodes are saved.

CSC – IT Center for Science

61. Result output in different formats 282

Mask Name String

The user may give a logical name of the mask. This mask will then be checked for in body force
and boundary condition lists and the active elements are determined on-the-fly.
Mask Condition String
The user may give a real valued condition for the mask. This mask condition will be check in
body for and boundary condition lists and the results will be saved only where the value of the
mask condition is positive. This could easily be used to save results only within a sphere, for
example.
Body body id

Geometry Id Integer
May be used to remap the default body index to a new value for VTU output.
Boundary Condition bc id
Geometry Id Integer
May be used to remap the default boundary condition index to a new value for VTU output.

If the user only wants a basic functionality of VtuOutputSolver it is possible to let the system create
automatically an instance of the solver simply by adding a Post File with suffix .vtu to the Simulation
section.
Simulation
Post File File [filename.vtu]
Name of the file where the unstructured XML based VTK results are to be saved.
vtu: Keyword Type
Any keyword with the suffix vtu: is passed to the solver instance without the suffix.
By default the solver is executed after saving. With the help of the namespace it is possible to include
any keyword (with the keyword type given) also in the Simulation section. At some point the section
will get crowded making it justified to create a separate solver instance.

61.3 Example
This example saves the results of a computation in binary unstructured VTK XML format following the
Output Intervals definition in the Simulation section. The variables to be saved are hand-selected.
Solver 3
Exec Solver = after saving
Equation = "result output"
Procedure = "ResultOutputSolve" "ResultOutputSolver"
Output File Name = "case"

Vtu Format = Logical True

Binary Output = Logical True ! binary format is the default
Single Precision = Logical True ! double precision is the default

! In the Vtu format all fields are saved if the user does not list them explicitly.
Scalar Field 1 = String Temperature
Scalar Field 2 = String Pressure
Vector Field 1 = String Velocity
End

CSC – IT Center for Science

Model 62

Saving data on uniform Cartesian grid

Module name: SaveGridData

Module subroutines: SaveGridData
Module authors: Peter Råback
Document authors: Peter Råback

62.1 Introduction
This subroutine is intended for saving data in a uniform grid. One possible use of the feature is to combine a
boundary representation and a glyph representation (velocity vectors) in the same visualization. This routine
would then save the data for the glyphs. The routine may also be used so that the resolution in two other
directions is set to a high value which will then effectively create uniform line plots.
The algorithm goes through all the elements and checks whether the element could include some of the
uniform grid nodes. If so then these are tested for. The algorithm should scale linearly with mesh size.
Optionally one may check for duplicates to eliminate the same nodes being repeatedly saved. Currently no
particular order is guaranteed for the nodes.
The routine works currently only in VTU, VTI and ASCII table formats, but other format may be possible
in the future.

62.2 Keywords
Solver solver id
Equation String "SaveGridData"
The name of the equation. This is actually not much needed since there are no degrees of freedom
associated with this solver.
Procedure File "SaveGridData" "SaveGridData"
The name of the file and subroutine.
Filename Prefix File
Specifies the name of the output file. A appropriate suffix is added to the given name.
Output Format String
This keyword the output format of choice. The choices are vtu, vti and table.
Vtu Format Logical
Vti Format Logical
Table Format Logical
The user may also use the above logical keywords to set which of the formats is saved. This
has more flexibility in that there may be several formats that are saved simultaneously where the
Output Format keyword may only be used to activate one solution type.

CSC – IT Center for Science

62. Saving data on uniform Cartesian grid 284

Fileindex Offset Integer

By default the files are numbered starting from one. However, for some restarted simulations the
offset may be defined to be something else. The default is zero.
Check for Duplicates Logical
This flag activates the checking of duplicates. This is usually advisable but may for peculiar
geometries require a large logical table and is therefore not defaulted to be true.
Grid dx Real
The grid size in direction x (i.e. Coordinate 1). Similarly we have Grid dy and Grid
dz, if applicable. If the density in directions y or z is not defined, it is assumed to be the same
as for x.
Grid nx Integer
The number of cells in direction x. This is only required if the previous keyword is not given.
Then the resolution is defined by the size of the bounding box. Similarly we have Grid ny and
Grid nz,
Grid Origin i Real
The mesh is by default located so that there is a node at (0, 0, 0). If the origin should not reside
here then this keyword may be used to transform the origin (i = 1, 2, 3).
Min Coordinate i Real
The bounding box may be limited by this keyword (i = 1, 2, 3). If not given the minimum values
of the mesh are used.
Max Coordinate i Real
The bounding box may be limited by this keyword (i = 1, 2, 3). If not given the maximum
values of the mesh are used.
Scalar Field i String
The scalar fields to be saved, for example Pressure. Note that the fields must be numbered
continuously starting from one. If no fields are given then an attempt is made to save all the
relevant fields.
Vector Field i String
The vector fields to be saved, for example Velocity
Mask Name String [MyMask]
The user may provide a mask that is used to determine the active elements. If the elements are
lower dimensional then it is assumed that the last coordinate is eliminated from the gridded data.
So if the full mesh is 3D and a mask is given for a boundary only then the data is saved on x-y
plane.
Filename Timestep Numbering Logical
Use this keyword in transient case to number the files by the timesteps. Applies only to the table
format.
Filename Particle Numbering Logical
Use this keyword in transient case to number the files by particles indexes. Applies only to the
table format.
Boundary Condition bc id

MyMask Logical True

The mask define in the solver section may be set True in the BC or Body Force section.

62.3 Example
The following example saves the results in the VTK XML image data format at the end of simulation. A
mesh parameter h = 0.1 is used for every direction and the lower left corner is taken as the base of the finite
uniform mesh.

CSC – IT Center for Science

62. Saving data on uniform Cartesian grid 285

Solver 5
Exec Solver = after all
Equation = SaveGrid
Procedure = "SaveGridData" "SaveGridData"

Grid dx = Real 0.1

Grid Origin At Corner = Logical True
Check For Duplicates = Logical True
Binary Output = Logical True
Single Precision = Logical True
Filename Prefix = String glyphs
Vti Format = Logical True
End

CSC – IT Center for Science

Model 63

Isosurface extraction for reduced output

Module name: Isosurface

Module subroutines: IsosurfaceSolver
Module authors: Juha Ruokolainen, Peter Råback
Document authors: Peter Råback

63.1 Introduction
This subroutine extract isosurfaces from 3D meshes or isolines from 2D meshes. The intended use of the
routine is in heavy simulations where the standard output could result to an I/O bottle-neck. If the desired
isosurface is known in advance then this can be used to reduce the amount of data to be written. The solver
does not itself write the data. It is expected that there is some external strategy for writing the data. It could,
for example, be the ResultOutputSolver for VTK XML output.

63.2 Keywords
Solver solver id
Equation String "Isosurface"
The name of the equation. This is actually not much needed since there are no degrees of freedom
associated with this solver.
Procedure File "Isosurface" "IsosurfaceSolver"
The name of the file and subroutine.
Output Directory File
Specifies the name of the output directory. Output file name will be determined in the normal
manner.
Isosurface Variable String
The name of the variable for which the isosurface is determined. This must be a scalar variable.
Isosurface Values Real
The isosurface values used to extract the surfaces. If this is a vector then a number of isosurfaces
will be defined.
Isosurface Values Real
The isosurface value used to extract the surfaces. For constant values this is the scalar variant
of the previous keyword. However, this may also have a functional dependency on some scalar
variable, such as time, for example.
Variable i String
Name of the variable to be outputted on the isosurface (or isoline), i=1, 2, 3, . . .

CSC – IT Center for Science

63. Isosurface extraction for reduced output 287

63.3 Example
This solver extracts the 1D isolines from 2D temperature field and stores them to a mesh called isosurf at
the three given isosurface values. If the original mesh would be 3D then the resulting isosurface mesh would
be 2D. Note that if saving of results is desired then this solver should be performed prior to the saving of
results.
Solver 8
Exec Solver = after all
Equation = "isoline"
Procedure = "Isosurface" "IsosurfaceSolver"
IsoSurface Variable = Temperature
IsoSurface Values(3) = 0.25 0.5 0.75

Output Directory = isoline

Variable 1 = Temperature
Variable 2 = stream
Variable 3 = vorticity
End

CSC – IT Center for Science

Model 64

Coupling Elmer with OpenFOAM via

file IO

Module name: Elmer2OpenFoamIO,OpenFOAM2ElmerIO

Module subroutines: Elmer2OpenFoamIO,OpenFOAM2ElmerFit
Module authors: Peter Råback
Document authors: Peter Råback

64.1 Introduction
These solver modules provides the possibility to transfer field values from Elmer into OpenFOAM and
back. The data transfer is done via file IO and has therefore some limitations regarding speed of operation.
However, the approach also has some flexibility since it does not set any additional constraints to how Elmer
and OpenFOAM have been compiled.
The solvers assume a working Elmer case and OpenFOAM case directory. The solvers assume that the
OpenFOAM directory 0 includes the cell centers computed with writeCellCenters in file C. For a
multiblock case the mesh directory will include subdirectories and then the cell centers should be available
at least in one subdirectory. Note that the Elmer field will only be mapped if the cell center file C is provided.
The Elmer2OpenFoamIO solver first reads the cell centers, then creates a temporal mesh structure from
them, and interpolates the desired field using the standard interpolation routines within Elmer. The interpo-
lation uses octree search tree and therefore it should be rather fast – in serial. The interpolated field is written
into the same directory where cell centers C were found. The format is a one that can be used to initialize
object from class volScalarField.
The coupling from OpenFOAM to Elmer is performed with the OpenFOAM2ElmerFit routine. It again
read the cells centers from files C. The solution with a given name is not fetched from directory 0 but rather
from the time step given by the user. The resulting values are not interpolated using the basis function since
there is no OpenFOAM mesh available at Elmer. Rather a procedure similar to DataToFieldSolver
is used. There diffusivity may be given as a regularization parameter. A good choice may be the physical
diffusivity related to the solver. I.e. if you’re reading in temperatures they may be regularized by heat
conductivity.
In case the performance of the routines is not satisfactory or one needs parallel operation then the MPI
coupler EOF library mainly written by Juris Vencels could be a better choice for the problem.

64.2 Keywords for module Elmer2OpenFoamIO

Solver solver id

CSC – IT Center for Science

64. Coupling Elmer with OpenFOAM via file IO 289

Equation String [Elmer2OpenFoamIO]

The name of the equation.
Procedure File "Elmer2OpenFoamIO" "Elmer2OpenFoamWrite"
The name of the procedure for writing Elmer fields to be read by OpenFOAM.
Filename File
Full name of the target file (with the suffix).
Target Variable String
Name of the Elmer field to be mapped for OpenFOAM. Currently only one field is supported.
OpenFoam Directory File
Name of the OpenFOAM directory that includes the whole OpenFOAM case tree.
OpenFoam File File
Name of the OpenFOAM file that will include the exported field from Elmer interpolated to the
cell centers.
OpenFoam Mesh i File
If the OpenFOAM mesh directory cannot be retrieved automatically for some reason the user
may define the OpenFOAM meshes to be treated. This could be the case in Windows where the
system commands might not be available.

64.3 Keywords for module OpenFoam2ElmerIO

Solver solver id
Equation String [OpenFoam2ElmerIO]
The name of the equation.
Procedure File "OpenFoam2ElmerIO" "OpenFoam2ElmerFit"
The name of the procedure for importing fields from OpenFOAM to Elmer.
OpenFoam Directory File
Name of the OpenFOAM directory that includes the whole OpenFOAM case tree.
OpenFoam Mesh i File
If the OpenFOAM mesh directory cannot be retrieved automatically for some reason the user
may define the OpenFOAM meshes to be treated. This could be the case in Windows where the
system commands might not be available.
OpenFoam Field String
Name of the OpenFOAM field to be read from the directory tree. Currently only one scalar field
is supported. Typical files are T (temparature) and p (pressure).
OpenFoam Timestep Integer
Name timestep number to define the subdirectory where the field is read from. Zero refers to the
initial state.
Fit Coefficient Real
This constant gives the factor that is used to weight the data when performing the fitting. This
has a relevance only with respect to the diffusivity used for regularization. Default value is one.
Diffusion Coefficient Real
This constant gives the diffusivity used for regularization.
Diffusivity Name String
The user may give an existing material parameter for the diffusivity. Then this is the name which
is searched in Material section.
Passive OpenFOAM Coordinate Integer 3
In case the initial file is 3D and we want to interpolate the results into a 2D mesh we may
give the passive coordinate index that will be used in dimensional reduction. If not given, 3D
interpolation will be assumed.

CSC – IT Center for Science

64. Coupling Elmer with OpenFOAM via file IO 290

64.4 Example
This example is used to map the field joule heating from Elmer to the OpenFOAM initialization file
fieldSolidHS.dat to be used in temperature distribution computations.

Solver 2
Equation = ElmerToOpenFOAM
Procedure = "Elmer2OpenFoamIO" "Elmer2OpenFoamWrite"

! The variable to be mapped

Target Variable = joule heating

! The OpenFOAM project directory containing the mesh etc.

OpenFOAM Directory = FILE "ofdir"

! The file to write the OpenFOAM sources to.

OpenFOAM File = File "fieldSolidHS.dat"
End

CSC – IT Center for Science

 Part X

Reading Data

CSC – IT Center for Science

Model 65

Read fields from Gmsh results file

Module name: GmshOutputReader

Module subroutines: GmshOutputReader
Module authors: Peter Råback
Document authors: Peter Råback

65.1 Introduction
This subroutine can read results provided in simple Gmsh ASCII output format and use the results to initial-
ize Elmer fields. Gmsh format is handy as it is relatively simple and has supporting software that can deal
with it. Also the Gmsh result format includes both the mesh geometry, topology and results. Hence it can be
used to read old results and interpolate them into a new mesh
This solver is not intended to replace the fully fledged restart format of Elmer. However, this tool may be
nice if we need to interpolate results in a workflow in a flexible manner. Note that the ResultOutputSolver
includes also a Gmsh writer and may therefore be used in conjunction with this module in workflows coupled
via saving and reading files.

65.2 Keywords
Solver solver id
Equation String "GmshReader"
The name of the equation. This is actually not much needed since there are no degrees of freedom
associated with this solver.
Procedure File "GmshOutputReader" "GmshOutputReader"
The name of the file and subroutine.
Filename File
Filename to read the results from. This file should currently be in Gmsh 2.2. format ASCII file.
Align Coordinate Logical
When reading the mesh into ElmerSolver should we align the mesh with some coordinate direc-
tion. The possible values are 1, 2, 3 to align in maximum coordinate direction. If negative value
is used then the mesh will be aligned with the minimum coordinates.
Mask Name String
If we want to interpolate results only on part of the mesh we may use a mask. Only where the
mask is present interpolation will be performed. The possible sections where the mask should
exist are Body Force and Boundary Condition.

CSC – IT Center for Science

Model 66

Reload Existing Simulation Results

Module name: ReloadData

Module subroutines: ReloadSolution
Module authors: Antti Pursula
Document authors: Antti Pursula

66.1 Introduction
This subroutine is intended for repeated loading of existing results during simulation. An example of a
typical application is to use previously computed fluid flow as a convection field for the transfer of a passive
scalar variable. The module is implemented as a dummy solver which is defined in the command file just as
the ’normal’ solvers.
This module offers extended features compared to the Restart File option in the Simulation
section. The module reads a new solution step from the solution file on each timestep, whereas the restart
file option reads only the initial state for a simulation.
The module reads in all the available variables from the solution file. The solution file should be in the
mesh directory. If the simulation takes more than a single steady state iteration per time step it is advisable
to use Exec Solver = Before Timestep for this module.

66.2 Keywords
Solver solver id

Equation String "Reload Data"

The name of the equation. This is actually not much needed since there are no degrees of freedom
associated with this solver.
Procedure File "ReloadData" "ReloadSolution"
The name of the file and subroutine.
Reload Solution File String "flow-data.dat"
The name of the old solution data file, eg. flow-data.dat
Reload Starting Position Integer
The index of the timestep where to start reading. If the keyword is not given the reading is started
from the first step in the file, or from the beginning of the reload range, if specified.
Reload Range Minimum Integer
Reload Range Maximum Integer
The beginning and the end of the reading range. The timesteps on the range are read in cyclically
if the current simulation has more timesteps than what there are on the range.

CSC – IT Center for Science

66. Reload Existing Simulation Results 294

Reload Reading Intervals Integer

Defines the interval for reading in old results, defaults to 1. An integer i larger than 1 defines that
results are read in only on every ith timestep. However, consecutive steps are read in regardless
of the value of i.
Continuous Reading Logical True
When set to True the reload solution file is kept open also between the timesteps. However,
when reading is not started at the first solution step, or when the old solution is read in cyclically,
it is advisable to switch this feature off. Defining False will slow down reading especially from
large ASCII files.

CSC – IT Center for Science

Model 67

Runtime Control of the Input Data

Module name: ReloadInput

Module subroutines: ReloadInput
Module authors: Juha Ruokolainen
Document authors: Peter Råback

67.1 Introduction
This subroutine is intended for cases where the user wants to have run-time control over the solution. The
control is obtained by reloading the command file (.sif-file) during the solution. This is done with an addi-
tional solver that is called similarly as any other solver during the solution process.
The most likely usage of the solver is in cases where the user realizes during the solution process that
the some parameters were not optimally chosen. For example, the convergence criteria may have been set
too tight for optimal performance. Then the user may set looser criteria by editing the command file during
the computation. Once the new value is read the solver will apply the new criteria thereafter.

67.2 Limitations
The solver should not be used for things that need allocation. For example, the number of solvers or bound-
aries may not change. Also the computational mesh must remain the same.

67.3 Keywords
Solver solver id

Equation String "Reload"

The name of the equation. This is actually not much needed since there are no degrees of freedom
associated with this solver.
Procedure File "ReloadInput" "ReloadInput"
The name of the file and subroutine.

CSC – IT Center for Science

Model 68

Reading NetCDF data into FE mesh

Module name: GridDataReader

Module subroutines: GridDataReader
Module authors: Peter Råback, Vili Forsell
Document authors: Peter Råback

68.1 Introduction
This solver provides the possibility to read in data in uniform grid into Elmer mesh. The supported format
includes currently only NetCDF.
Currently following features are supported:
• Bilinear (in 2D) or trilinear (in 3D) interpolation
• Possibility to have a multiplicator and offset in the target field
• Linear interpolation in time
• Multiple possibilities to define the time instant or index
The module requires the netcdf library. Because of this, it has been isolated from the main build system.
The source code for XdmfWriter can be found from the source tree in misc/netcdf2 and it should be
compiled by the user as follows:
elmerf90 -I$HDF5/include -L$HDF5/lib -o GridDataReader.so GridDataReader.f90 -lnetcdff -lnetcdf

The environment variable $NETCDF defines the installation directory for the NetCDF-library.

68.2 Theory
In structured data the finding of grid cell where a certain node belongs to is trivial. Assume that the grid is
defined by coordinates ai and bi so that any coordinate xi is presented by

xi = ai ni + bi (68.1)

where ni ∈ [1, Ni ] and i ∈ [1, DIM]. Now the finite element node with coordinate x̂i may be interpolated
using the cell with indexes mi = ceiling((x̂i − bi )/ai ) and mi + 1 using linear interpolation with weighing
factor qi = mi − (x̂i − bi )/ai .
fˆ = qi fmi + (1 − qi )fmi +1 . (68.2)
This generalizes into multiple dimensions using recursion. For example, in 2D the bilinear interpolation
reads
fˆ(x1 , x2 ) = q1 q2 f11 + (1 − q1 )q2 f21 + q1 (1 − q2 )f12 + (1 − q1 )(1 − q2 )f22 . (68.3)

CSC – IT Center for Science

68. Reading NetCDF data into FE mesh 297

The current implementation provides bilinear and trilinear interpolation in space, and linear interpolation in
time.
The algorithmic complexity of the reader and interpolation routine is linear in time. However, the current
implementation assumes that each partition do their own interpolation routines which means that there may
be a large number of files open in parallel runs introducing potential bottle-necks.

68.3 Keywords
Solver solver id
Equation String [GridDataReader]
The name of the equation.
Procedure File "GridDataReader" "GridDataReader"
The name of the procedure.
Filename File
Full aame of the target file (with the suffix).
X Name String
Name of the 1st coordinate.
Y Name String
Name of the 2nd coordinate.
Z Name String
Name of the 3rd coordinate.
Time Name String
Name of the time coordinate.
X Epsilon A
ccuracy of the 1st coordinate assumed in interpolation. Default is machine epsilon.
Y Epsilon A
ccuracy of the 2nd coordinate assumed in interpolation. Default is X Epsilon.
Z Epsilon A
ccuracy of the 3rd coordinate assumed in interpolation. Default is X Epsilon.
Time Epsilon A
ccuracy of time assumed in interpolation. Default is machine epsilon.
Time Point Real
Value of time used in this calling. If this is not found the Elmer time will be used.
Time Offset Real
Offset used to add to the Elmer time.
Time Multiplier Real
Coefficient used to multiply the Elmer time.
Is Time Index Real
If this flag is turned on then the time instance given with the previous keywords will be under-
stood as being the index of time in the NetCDF file (starting from 1) rather than actual time.
Is Time Counter Logical
If this flag is turned on, the time index of the NetCDF file will be increased by one each time the
routine is called. This makes it ideal for looping over each timestep.
Coordinate Transformation String
Optional coordinate transformation that is applied on the Elmer coordinate prior to finding its
value on the grid.
Enable Scaling Logical
If this flag is turned on the bounding box of Elmer mesh will be made compatible with that of
the grid.

CSC – IT Center for Science

68. Reading NetCDF data into FE mesh 298

Variable i String
Variable of the NetCDF file. There is no upper limit to the number of variables.
Target Variable i String
Optional name for the target variable. If this is not given then the Variable i value will be
used for the FE variable as well. If the target variable is not present it will be created the first
time it is needed. Also, if different variables that follow each other have the same target variable
these will be summed up. With the multiplication and offset features this makes it possible to
derive new variables as a linear combination of any fields given in the NetCDF file.
Interpolation Offset Real
A constant that will be added to the value of the interpolated field. If there are many fields with
different offsets use Interpolation Offset i instead.
Interpolation Multiplier Real
A constant that will be used to multiply the interpolated field. The default value is one. If there
are many fields with different offsets use Interpolation Multiplier i instead.

CSC – IT Center for Science

 Part XI

Experimental or Obsolete Solvers

CSC – IT Center for Science

Model 69

Lithium-Ion Battery Model

Module name: BatterySolver

Module subroutines: SolidPhaseCons, ElectrolyteCons, SolidPhasePot, ElectrolytePot, BatteryPost
Module authors: Peter Raback, Timo Uimonen
Document authors: Timo Uimonen, Joel Songok, Peter Raback
Document edited: March 2nd 2020

69.1 Introduction
This module can be used to solve a set of conservation equations that govern lithium-ion battery cycling
behaviour. The macroscopic model follows multiphase porous electrode and concentrated solutions theories
that describe the transfer of mass and charge between solid electrodes and liquid electrolyte [2] [3].
The current implementation provides perhaps a starting point for continued work. There is still some
challenges in the robustness of the solver. It has been verified against literature but the number of coupled
system iterations needed seems often excessive.
If you’re interested in continuing the work, please contact the authors for more details. In the partial
differential equations we have followed closely the references while the numerical solution is very different,
probably both in good and bad.

69.2 Theory
For the equations we mainly follow the Master’s Thesis of A. Borakhadikar [1]. For other relevant references
see, for example, [3].
The model for the battery includes two coupled equations for both electrostatic potential and concentra-
tion. These are closed by chemical kinetics described by the Butler-Volmer equation. The special feature
of the equations is that the solid phase concentration is to be solved within each solid phase particle. The
multiscale nature is captured by solving the 1D diffusion equation in spherical coordinates in each node of
the distributed system. The other equations follow pretty much standard procedures.
Conservation of species in solid phase is written as
 
∂cs Ds ∂ ∂cs
− 2 r2 = 0, (69.1)
∂t r ∂r ∂r

where cs (~x, r, t) is the concentration, Ds is solid phase Li diffusion coefficient. At the boundary of each
sphere the flux condition is given by

∂cs 1
Ds r=r0
=− JLi , (69.2)
∂r as F

CSC – IT Center for Science

69. Lithium-Ion Battery Model 301

where as = 3εs /Rs is the active interfacial surface area, F is Faraday constant and Rs is the radius of the
solid particle. JLi is the lithium ion flux between the solid and electrolyte phases. The coupling to other
fields takes place only at the surface where we define C(~x, t) = cs (~x, r0 , t).
Conservation of species in electrolyte phase leads to a diffusion equation

∂ 1 − t+
(εe Ce ) − ∇ · Deef f ∇Ce = JLi , (69.3)
∂t F
where t+ is transference number of lithium ions and Deef f is effective electrolyte phase Li+ diffusion coeffi-
cient. The effective diffusivity depends on the electrode porosity which is described by Bruggeman relation
Deef f = De εpe where εe is electrolyte phase volume fraction. At the current collectors, no-flux boundary
conditions are imposed,
∂Ce ∂Ce
= = 0. (69.4)
∂x x=0 ∂x x=L
Conservation of charge in solid phase defines the solid phase potential,

− ∇ · σ ef f ∇ϕs = −JLi , (69.5)

where the σ ef f refers to effective conductivity of an electrode. It is defined as σ ef f = σεs where εs is active
particle volume fraction. The boundary condition for solid phase potential at the current collectors reads as

ef f ∂ϕs ef f ∂ϕs I
− σ− x=0
= σ+ x=L
= , (69.6)
∂x ∂x A
where I(t) is applied current and A is the plate area of an electrode. The boundary conditions at the
electrode-electrolyte interface are defined as follows,

∂ϕs ∂ϕs
x=LN eg
= x=LN eg +LSep
= 0. (69.7)
∂x ∂x
Conservation of charge in electrolyte phase defines the potential in the electrolyte phase,

− ∇ · κef f ∇ϕe − ∇ · κef f

d ∇(log Ce ) = JLi , (69.8)

where κef f is the effective ionic conductivity, which is calculated by using Bruggeman’s relation κef f =
κεpe . The electrolyte phase ionic conductivity κ can respectively be defined as

Ce 1.4
κ = 15.8e−4 Ce exp(0.85( ) ). (69.9)
1000
The second term of the equation gives rise to numerical challenges since it may be difficult to evaluate
accurately. Here κef
d
f
is effective diffusional conductivity which is evaluated as

2RT κef f
κef
d
f
= (t+ − 1), (69.10)
F
where R is gas constant and T is ambient temperature. At the current collectors, the boundary conditions
are defined as
∂ϕe ∂ϕe
= = 0. (69.11)
∂x x=0 ∂x x=L
The system of equation is closed by Butler-Volmer kinetic equation
    
αa F αc F
JLi = as i0 exp η − exp η . (69.12)
RT RT

In the equation, i0 is the exchange current density given by

i0 = k0 Ceαa (Cs,max − Cs )αa Csαc , (69.13)

CSC – IT Center for Science

69. Lithium-Ion Battery Model 302

where k0 is kinetic rate constant, Cs,max is the maximum solid phase concentration of an electrode while
the αa and αc are anodic and cathodic charge coefficients. Overpotential η may be written as

η = ϕs − ϕe − U, (69.14)

where empirical expressions are used for the equilibrium potential U . The equilibrium potential is a material
property and for the particular material used in this module, the potential for negative electrode it given by
1 1 3
Un (x) =8.0029 + 5.0647 x − 12.578 x 2 − 8.6322e-4 + 2.1765e-5 x 2
x
− 0.46016 exp(15(0.06 − x)) − 0.55364 exp(−2.4326(x − 0.92)) (69.15)

and for positive, correspondingly, by

Up (x) =85.681 x6 − 357.7 x5 + 613.89 x4 − 555.65 x3 + 281.06 x2

− 76.648 x − 0.30987 exp(5.657 x1.15 ) + 13.1983, (69.16)

where x = Cs /Cs,max .

69.2.1 Postprocessing
Once the conservation equations have been solved, the solution can be transformed into more readable
format. The cell voltage of the battery can be expressed as
Rf
Vcell = φs (t, L) − φs (t, 0) − I(t), (69.17)
A
where φs (t, L) and φs (t, 0) are solid phase potentials at cathode and anode current collectors, Rf is resis-
tance of current collectors and A is electrode plate area.
The battery state of charge can be estimated in variety of ways. In this module, the SOC is evaluated by
default as
C
( Cs,surf
s,max
) − x0%
SOC(t) = , (69.18)
x100% − x0%
where x0% and x100% are stoichiometric coefficients at 0% and 100% state of charge. Alternatively, the state
of charge can also be calculated by Coulomb counting which goes as follows
Z t
1
SOC(t) = SOC(0) − I(t)dt, (69.19)
Qrated 0
where Qrated is rated cell capacity. The cell capacity during cycling is given by
Z t
Qcell = I(t)dt. (69.20)
0

69.3 Keywords
The module includes five different solvers. Usually order of solvers is arbitrary. However, here a specific
order is given that has been found to be most successful.

Solver 1
Poisson equation for the solid phase potential, ϕs . The equation is solved in both anode and cathode.
Equation String SolidPhasePot
The name of the equation.
Procedure File "BatterySolver" "SolidPhasePot"
The name of the solver file and subroutine.

CSC – IT Center for Science

69. Lithium-Ion Battery Model 303

Variable String [Phis]

This is the default name for ϕs assumed by other solvers.
Linearize Flux Logical [True]
Linearize the flux JLi with respect to ϕs . This is needed since the equation does not otherwise
set the potential levels. This keyword may be applied for any of the potential and concentration
solvers.
Skip Butler Volmer Logical [False]
The strategy when Butler-Volmer equation is computed affects the convergence. It may some-
times be advantageous to skip the re-computation. This keyword may also be applied for any of
the solvers.
Fixed Overpotential Logical [False]
The strategy when the overpotential in Butler-Volmer equation is computed affects the con-
vergence. It may sometimes be advantageous to skip the re-computation overpotential. This
keyword may also be applied for any of the solvers.
Use Time Average Flux Logical [False]
Whether to use instantaneous flux JLi or average the flux over the timestep. When activated it is
applied in all the solvers.
Use Mean Flux Logical [False]
Whether to use instantaneous flux or average flux over iterations. Cannot be used together with
time-averaged flux.
Use Time Average Diffusion Logical [False]
Whether to use instantaneous diffusion or average diffusion over the timestep. When activated it
is applied in all the solvers.
The following keywords are related to the library functionality but are nevertheless explained briefly
also here. For more details look at the ElmerSolver manual.
Linear System Solver String [Direct]
The type of linear solver used can be specified here.
Linear System Direct Method String [banded]
The type of direct linear system solver can be specified here. Banded is chosen by default.
Linear System Scaling False
For 1D equation the direct banded solver without any scaling is the fastest strategy. For 2D and
3D geometries, other strategies should be used.
Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations the solver is allowed to do.
Nonlinear System Relaxation Factor Real
Giving this keyword triggers the use of relaxation in the nonlinear equation solver. The factor
might speed up the convergence.
Nonlinear System Convergence Tolerance Real
A set value which specifies criterion for relative change between iterations in the nonlinear solver.
Nonlinear System Convergence Measure Real
There is a interplay between nonlinear and steady state convergence criteria. Usually speed is
optimized by iterating mainly at the steady state level. However, here we need to iterate also on
the nonlinear level to achieve convergence.
Steady State Convergence Tolerance Real
This relates to the overall convergence of the system.
Solver 2
Poisson equation for the electrolyte potential, ϕe . This is solved in the whole domain.
Equation String ElectrolytePot
The name of the equation.

CSC – IT Center for Science

69. Lithium-Ion Battery Model 304

Procedure File "BatterySolver" "ElectrolytePot"

The name of the solver file and subroutine.
Variable String [Phie]
This is the default name for ϕe assumed by other solvers.
Linearize Flux Logical True
Linearize the flux JLi with respect to ϕe .
Quadratic Electrolyte Diffusion Logical [False]
This enables to toggle between the two different formulations for electrolyte diffusion. The
quadratic form requires higher order elements whereas the standard weak formulation is also
applicable to linear elements.
Ignore Electrolyte Diffusion Logical [False]
This enables to toggle off the effects of Li+ diffusion in the electrolyte during computation.
Use Time Average Diffusion Logical [False]
Whether to use instantaneous diffusion or average diffusion over the timestep.
Fixed Overpotential Logical [False]
The strategy when the overpotential in Butler-Volmer equation is computed affects the con-
vergence. It may sometimes be advantageous to skip the re-computation overpotential. This
keyword may also be applied for any of the solvers.
Calculate Ce sensitivity Logical [False]
If set to True, the solver calculates Ce sensitivity for solver 2.
Correct Source Disbalance Logical
This keyword toggles an option to correct the flux imbalance in the ϕe solver.
Solver 3
Diffusion equation for the solid phase concentration, Cs . This is always 1D equation utilizing an
internal 1D mesh as a submodel in every node.

Equation String SolidPhaseCons

The name of the equation.
Procedure File "BatterySolver" "SolidPhaseCons"
The name of the solver file and subroutine.
Variable String [Cs onedim]
This is the default name for Cs an 1D stride assumed by other solvers.
Solid Phase Relaxation Factor Real
The value of relaxation factor used by solid phase solver.
Maximum Global Change Speed Real
Sets the value of the largest allowed change in solid phase concentration in one iteration.
Number of Passive Visits Integer
Specifies the number of solid phase iterations for only electrostatic solver.
Linearize Flux Logical True
Linearize the flux JLi with respect to Cs .
Fixed Overpotential Logical [False]
The strategy when the overpotential in Butler-Volmer equation is computed affects the con-
vergence. It may sometimes be advantageous to skip the re-computation overpotential. This
keyword may also be applied for any of the solvers.
Check Material Balance Logical
A toggle to check for flux imbalance in 1D solution.
Save Solid Phase Average Logical True
Toggle to save average flux between solid and electrolyte phase.

CSC – IT Center for Science

69. Lithium-Ion Battery Model 305

Save Solid Phase Diff Logical True

Toggle to save the difference in flux between solid and electrolyte phase.
Visualize Node Index Integer
A toggle to visualize a given node with 1D solution.

The following keywords are used by 1D submeshes located in the nodes of the main mesh.
1D Mesh Create Logical [True]
Creates 1D submesh if set to True.
1D Element Order Integer
The order of elements in 1D submesh can be specified here.
1D Number Of Elements Integer
The number of elements in 1D submesh can be specified here.
1D Mesh Ratio Real
Here the ratio of 1st and last element in the 1D submesh can be specified.
1D Mesh Length Real
This keywords is used to specify the length of the 1D submesh.
1D Active Direction Integer
Specifies the direction of the 1D submesh. This is set to 1 by default.
1D Body Id Integer
This keyword is used to set the body id.

Solver 4
Diffusion equation for the electrolyte concentration, Ce . It is solved in the whole domain.
Equation String ElectrolyteCons
The name of the equation.
Procedure File "BatterySolver" "ElectrolyteCons"
The name of the solver file and subroutine.
Variable String [Ce]
This is the default name for Ce assumed by other solvers.
Linearize Flux Logical [False]
Linearize the flux JLi with respect to ce .
Number of Passive Visits Integer
Specifies the number of solid phase iterations for only electrostatic solver.
Use Solid Phase Relaxation Logical [True]
If set to True, the solver inherits relaxation factor from solid phase concentration solver.
Fixed Overpotential Logical [True]
The strategy when the overpotential in Butler-Volmer equation is computed affects the con-
vergence. It may sometimes be advantageous to skip the re-computation overpotential. This
keyword may also be applied for any of the solvers.
Skip Butler Volmer Logical [True]
The strategy when Butler-Volmer equation is computed affects the convergence. It may some-
times be advantageous to skip the re-computation.
Use Effective Diffusion Logical [False]
It can sometimes be advantageous to use non-effective diffusion where the electrolyte volume
fraction is not taken into account. This is due to numerical difficulties risen from the second term
in solver 2.
Calculate Cs sensitivity Logical [False]
If set to True, the solver calculates Cs sensitivity for solver 4.

CSC – IT Center for Science

69. Lithium-Ion Battery Model 306

Use Time Average Diffusion Logical [False]

Whether to use instantaneous diffusion or average diffusion over the timestep.
Correct Butler Volmer Fluxes Logical
Sometimes there might exist an imbalance of fluxes between the electrodes. This toggle is used
to add a correction coefficient to adjust the imbalance.

Solver 5
Solver for performing postprocessing information after convergence is obtained.
Equation String BatteryPost
The name of the postprocessing equation.
Procedure File "BatterySolver" "BatteryPost"
The name of the solver file and subroutine.
Study Jli Balance Logical
This keyword is used to toggle on an option to save error values in the Cs solution to study JL i
balance.
Soc Model String
State of charge model to be used. The Default model evaluates SOC in terms of the solid phase
concentration while taking the stoichiometric coefficients into account. Selecting Simplified,
on the other hand, makes the model to ignore them. Alternatively, selecting Coulomb evaluates
SOC using Coulomb counting method.
SOC on surface Logical
If set to True, the solver uses the surface values for SOC instead of true average.
Initial SOC Real
The initial SOC can be specified here if the simulation starts in conditions other than fully
charged or discharged.
Cutoff Voltage Real
This keyword is used to set a lower-limit for the cell voltage at which the battery cell is considered
fully discharged.
Stoichiometric Limit Real
This keyword is used to set a lower-limit for solid phase concentration after which a warning is
issued.
Applied Current Real
This keyword is used to define the value of applied current that is only used in postprocessing.
Here, negative sign refers to charge current and vice versa.
Cell Capacity Real
This keyword is used to define value of rated capacity of the battery cell, which is used in
evaluation of state of charge by Coulomb counting method.
Use Average Cell Voltage Logical
We may either use extremum potential to compute the cell voltage or take average over anode
and cathode. The first one is the default.
Calculate Charges Logical
Toggle to calculate addition information about the charges and potentials of anode, cathode and
electrolyte.

Constants

Gas Constant Real

The universal gas constant R. In SI units the value is 8.314 J/K mol.
Faraday Constant Real
Specific charge in mole, F . In SI units the value is 96485.3 C/mol.

CSC – IT Center for Science

69. Lithium-Ion Battery Model 307

Transference Number Real

This keyword is used to define the Li+ transference number, t+ .
Electrode Plate Area Real
This keyword is used to define the electrode plate area, A.
Ambient Temperature Real
This keyword is used to define the ambient temperature, T .
Current Collector Resistance Real
This keyword is used to define the contact resistance of a current collector, Rf .

Material mat id
Materials parameters for anode and cathode.
Anode Logical
If material is anode set True, otherwise False.
Cathode Logical
If material is cathode set True, otherwise False (default).
Particle Radius Real
This keyword is used to define the radius of the solid phase particles, Rs .
Active Particle Volume Fraction Real
This keyword is used to define the volume fraction of particles in an electrode, εs .
Maximum solid phase concentration Real
This keyword is used to define the value of maximum lithium concentration in an electrode,
Cs,max .
Kinetic Constant Real
This keyword is used to define the value of kinetic rate constant, k0 .
Anodic charge transfer coefficient Real
This keyword is used to define the anodic charge transfer coefficient, αa .
Cathodic charge transfer coefficient Real
This keyword is used to define the cathodic charge transfer coefficient, αc .
Solid Phase Diffusion Coefficient Real
The value of lithium diffusivity in solid phase, Ds .
Solid Phase Electrical Conductivity Real
This keyword is used to define the electrical conductivity of an electrode in solid phase, σ.
Stoichiometry at Full Charge Real
Stoichiometry when the battery cell is considered fully charged, x100% .
Stoichiometry at Nill Charge Real
Stoichiometry when the battery cell is considered fully discharged, x0% .
Material parameters for electrolyte.

Electrolyte Volume Fraction Real

This keyword is used to define the volume fraction of electrolyte, εe .
Electrolyte Diffusion Coefficient Real
The value of Li+ diffusivity in electrolyte phase, De .

Initial Condition ic id
Initial conditions are used to set the state of the battery at start of the simulation. We may initialize
Cs , Ce , ϕs , ϕe and JLi .

Cs Real
Ce Real

CSC – IT Center for Science

BIBLIOGRAPHY 308

Phis Real
Phie Real
Jli Real

Boundary Condition bc id
Current Density Real
Neumann boundary condition for the current density. During discharge, current density has a
positive sign at anode current collector and negative sign at cathode current collector.

Bibliography
[1] Ashwin S. Borakhadikar. One dimensional computer modeling of a lithium-ion battery. Master’s thesis,
Wright State University, 2017.
[2] M Doyle, T F Fuller, and J Newman. Modeling of galvanostatic charge and discharge of the
lithium/polymer/insertion cell. Journal of the Electrochemical Society; (United States), 140:6, 6 1993.
[3] K. A. Smith, C. D. Rahn, and C.-Y. Wang. Control oriented 1D electrochemical model of lithium ion
battery. Energy Conversion and Management, 48:2565–2578, 2007.

CSC – IT Center for Science

Model 70

Richards equation for variably

saturated porous flow

Module name: RichardsSolver

Module subroutines: RichardsSolver, RichardsFlux
Module authors: Peter Råback
Document authors: Serge-Étienne Parent and Peter Råback

70.1 Introduction
Richards equation is a non-linear partial differential equation that represents the movement of fluids through
porous media.
The current implementation of the Richards equation uses normal Lagrange elements and therefore the
conservation of flux cannot be guaranteed. Dense meshes are required if the variations in the permeability
are high.
This version should not yet be considered a production version. However, it provides a suitable starting
case for more serious testing and further development.

70.2 Theory
The transient, incompressible, variably saturated, isotropic flow of water in non-swelling porous media is
expressed by the combination of Darcy’s law and the continuity equation, i.e. Richards equation. The
modern form of Darcy’s law can be written as

~q = −kw ∇H (70.1)

where ~q is the unit flux, or Darcy velocity (L/T), kw is the fluid hydraulic conductivity of water (L/T), and H
is the total head (L). Since the velocity component of total head can be treated as negligible in porous media,
and air pressure can be considered as constant, total head can be expressed as H = p + z where p is pressure
(F/L2 ) (note that p = −ψ = ua − uw ), ψ is matric suction (F/L2 ), uw is the water pressure in pores (F/L2 ),
ua is the air pressure in pores (F/L2 ), z is elevation from a datum (depth coordinate of the geometry).
The continuity equation is expressed as
∂θ
= −∇ · ~q + Sw , (70.2)
∂t
where θ is the volumetric water content (L/L), t is time (T), Sw is a source/sink term (L/T). Richards equation
may now be written as,
∂θ
= −∇ · (kw ∇H) + Sw , (70.3)
∂t

CSC – IT Center for Science

70. Richards equation for variably saturated porous flow 310

since θ = f (ψ) and kw = f (ψ) the latter equation can be expressed using a pressure form,

∂θ ∂ψ
= −∇ · (kw ∇H) + Sw , (70.4)
∂ψ ∂t
Or, developing total head,
∂θ ∂ψ
= −∇ · (kw ∇(−ψ + z)) + Sw , (70.5)
∂ψ ∂t
The volumetric water content and the hydraulic conductivity are non-linear functions related to pres-
sure head. Both are commonly expressed by van Genuchten (1980)’s equations. Volumetric water content
function yields (
−θr
θs + (1+αθns vG mvG , if ψ > 0
θ(ψ) = vG ) (70.6)
θs , if ψ < 0.
And the hydraulic conductivity function is
nvG mvG n m 2
(
kw,sat (1−(αvG ψ) (1+αnvG(1+(αvG ψ) vG ) vG )
−mvG /2 , if ψ > 0
kw (ψ) = vG ) (70.7)
kw,sat , if ψ < 0.

where θ is the volumetric water content (L/L), θr is the residual volumetric water content (L/L), θs is the sat-
urated volumetric water content, equal to the porosity (L/L), αvG , nvG , mvG are fitting parameters without
any units.

70.3 Implementation issues

The current implementation is carried out for the total head, H. This results to a weak form where the fluxes
occur naturally. The total head is intuitive since it gives directly the ground water level. Since the time
derivative of the elevation is zero, we may use the following equation to solve the total head,

∂H
θψ + ∇ · (kw ∇H) = Sw . (70.8)
∂t
From the total head the matrix suction will be automatically computed, ψ = z − H. This makes it possible
to have material laws that depend on it.
For transient problems the first term requires special attention. In the current version the sensitivity of θ
to ψ is computed from
(
θ(ψ(ti ))−θ(ψ(ti−1 ))
ψ(ti )−ψ(ti−1 ) if |ψ(ti ) − ψ(ti−1 )| > 
θψ = θ(ψ(ti ))−θ(ψ(ti )−)
(70.9)
 otherwise.

This way the effective sensitivity is smeared over the whole timestep, dt = ti − ti−1 .
The values of the material parameters in the Richards equation vary a great deal depending on the sat-
uration level and type of medium. Therefore it is important to evaluate the water content and hydraulic
conductivity at the Gaussian integration points using the relevant formulas, rather than computing them at
nodal points and thereafter evaluating the values at the Gaussian integration points using a weighted sum
over the nodal values.

70.4 Keywords
The module includes two different solvers. RichardsSolver solves the primary differential equation
while RichardsFlux solves the resulting flux from the computed solution. The second solver only makes
sense when the pressure field has already been computed with the first one. The second solver uses the same
material parameters as the first one.

CSC – IT Center for Science

70. Richards equation for variably saturated porous flow 311

Keywords for RichardsSolver

Solver solver id
Equation String RichardsSolver
A describing name for the solver. This can be changes as long as it is used consistently.
Procedure File "RichardsSolver" "RichardsSolver"
Name of the solver subroutine.
Variable String TotalHead
The name of the variable may be freely chosen as far as it is used consistently also elsewhere.
Variable DOFs Integer 1
Degrees of freedom for the pressure. This should be 1 which is also the default value.
Saturated Initial Guess Logical
Use saturated material parameters when computing the first equation for the total head.
Active Coordinate Integer
The coordinate corresponding to the dephth z in the Richards equation. By default the last
coordinate is the active one.
Calculate Matrix Suction Logical
Whether to compute the matrix suction from the total head.
Bubbles Logical
Use stabilization by residual free bubbles.
Nonlinear System Convergence Tolerance Real
The Richards equation is always nonlinear and hence keywords related to the nonlinear system
control are needed. The iteration of the nonlinear system is continued till the relative change in
the norm falls under the value given by this keyword.
Nonlinear System Max Iterations Integer
This parameter gives the maximum number of nonlinear iterations required in the solution. This
may be set higher than the typical number of iterations required as the iteration procedure should
rather be controlled by the convergence tolerance.
Nonlinear System Relaxation Factor Real
Keyword related to the relaxation of the nonlinear system.
Material mat id
Porositity Model String
Currently the choices are van Genuchten and Default. The latter does not estimate the
functional forms on gaussian points and hence may have inferior accuracy. Also, currently the
computation of water content derivative is not supported for it limiting its usability to steady
state problems.
Saturated Hydraulic Conductivity Real
Saturated Water Content Real
Residual Water Content Real
van Genuchten Alpha Real
van Genuchten N Real
van Genuchten M Real
The parameters above are the material parameters of the van Genuchten material law that are
used to compute the hydraulic conductivity and water content.
Hydraulic Conductivity Real
Water Content Real
In case the porosity model is constant then the hydraulic conductivity and water content are
given with this keyword.

CSC – IT Center for Science

70. Richards equation for variably saturated porous flow 312

Body Force bf id
Richards Source Real
The source term, Sw , of the equation.
Boundary Condition bc id

Richards Flux Real

The given flux at the boundary.

Keywords for RichardsPostprocess

This solver uses largely the same keywords that are already defined above. Only the Solver section has its
own keyword settings. This solvers should be active in the same bodies than the RichardsSolver.

Solver solver id
Equation String RichardsPostprocess
A describing name for the solver. This can be changes as long as it is used consistently.
Procedure File "RichardsSolver" "RichardsPostprocess"
Name of the solver subroutine.
Target Variable String
The name of the total head field solved by the Richards equation. The default name is Total
head.

CSC – IT Center for Science

Model 71

Outlet Boundary Condition for Arterial

Flow Simulations

Module name: ArteryOutlet

Module subroutines: OutletCompute, OutletInit, OutletPres, OutletdX, OutletdY
Module authors: Esko Järvinen, Mikko Lyly, Peter Råback
Document authors: Esko Järvinen

71.1 Introduction
Arterial elasticity is a fundamental determinant of blood flow dynamics in arteries, such as the aorta and
its daughter vessel, that face the largest displacements and which takes care of the cushioning of the stroke
volume. Simulation of such a phenomenon requires simultaneous solving of the equations governing both
the fluid flow and wall elasticity. To be able to perform accurate fluid-structure interaction (FSI) simulations,
only a segment of the circulatory system can be studied at a time. For these artificially truncated segments,
which are naturally unbounded domains and in interaction with the rest of the circulation domain, one should
construct in the numerical models boundary conditions which do not exhibit any unphysical behaviour,
which operates transparently, and are also capable to transport a sufficient amount of information over the
boundary.
A natural boundary condition at the outlet of a numerical FSI flow model of an artery is not a proper
choice because it does not exhibit enough correct physiological behavior of the flow, and from the point of
view of numerical approximation, it causes non-physiological reflections of the wave at the boundary. If
measured data of both the pressure (or velocity) and the wall displacement at the outlet boundary are not
available, the only way to get the outlet boundary of a higher order, 2D or 3D model sufficiently specified is
to combine the model with some lower order model, such as a 1D or lumped model.
In order to get the outlet of the arterial FSI model to behave transparently in such cases when only
forward travelling waves are considered, a simple characteristic equation of the of the one dimensional FSI
model can be combined with the higher order model.

71.2 Theory
The conservation equations for a flow in an elastic artery in one dimension may be expressed as

∂A ∂Q
 ∂t + ∂x = 0

(71.1)
2
∂Q ∂ Q A ∂p
+ ∂x ( A )+ = 0,


∂t ρ ∂x

CSC – IT Center for Science

71. Outlet Boundary Condition for Arterial Flow Simulations 314

where Q is the volume flow, A the cross section area of the artery, p is the pressure and x is the axial
coordinate [3]. In order to get the system (71.1) close, an equation relating the area A to the pressure
p = p(A) is derived applying the theory of thin shell structures. Assuming a cylindrical shell, and neglecting
the rotation on the shell cut plane, and the movements of the structure in the axial and circumferential
directions, as well as applying the Kirchhoff-Love assumption, the energy balance equations is reduced to

E h3 Eh 1
dR (4) + dR = p, (71.2)
12(1 − ν 2 ) (1 − ν 2 ) Rm 2
where Rm is the radius to the midplane of the wall, E, ν and dR are the Young modulus, the Poisson
ratio and the radial displacement of wall, respectively. Assuming that the first term on the left side in the
equation (71.2) is much smaller than the second term, we can give the pressure-area relation in the form
√
√ p πhE
p = pext + β( A − A0 ), β= . (71.3)
(1 − ν 2 )A0
The pressure is scaled to be equal to external pressure pext with corresponding reference artery cross
sections area A0 .
The equations (71.1) and (71.3) form a closed system for the simulations of flow in an elastic tubes. The
equations may be written in conservative form which is strictly hyperbolic with two distinctqreal eigenvalues
p √
λ1,2 = ū ± c, where ū = Q/A is the average axial velocity, c = (A/ρf )(∂p/∂A) = β A/(2ρf ) is
the speed of sound, and ρf is the density of blood. The system can be further decomposed into a set of the
equations for the characteristic variables Wi , which are the components of the vector W = T −1 U ( ∂W ∂U =
T −1 ) , U = [A, Q]T [2]. These equations are
∂Wi ∂Wi
+ λi = 0, (71.4)
∂t ∂x
and the characteristic variables are
s
Q 2 √
W1,2 = ±2 + β A.
A ρf
When considering a pulse propagation in a straight, infinitely long homogeneous conduit, without any
bifurcations or other objects which might cause reflections of the pulse, i.e. any backward travelling waves
does not exists, the computations can be done using only the first of equations in (71.4), i.e.

∂W1 (U ) ∂W1 (U )
+ λ1 (U ) = 0.
∂t ∂x
This equation is solved in this Elmer outlet bondary condition for arterial flow simulations solver. The
connection of the one dimensional model to the test models at the their outlets is done applying the following
coupling [1]

 dR− = dR+


σ − = p+
W1 = g1 (A− , Q− , p− ),


where dR and σ are radial displacement of the artery wall and fluid traction, respectively. The superscript
’–’ denotes the values in the higher order models, and superscript ’+’ to the values in the 1D model.

71.3 Keywords
Keywords of FlowSolve
Initial Condition ic id
For making the initial guess for the characteristic variable W1

CSC – IT Center for Science

71. Outlet Boundary Condition for Arterial Flow Simulations 315

Wnodal Variable Coordinate

Real Procedure "ArteryOutlet" "OutletInit"

Material mat id
Material properties for the one dimensional section.
Density Real
Density of blood
Artery Wall Youngs Modulus Real
Young’s modulus of the artery
Artery Radius Real
Radius of the artery to the midplane of the artery wall
Artery Wall Thickness Real
Wall thickness of the artery
Artery Poisson Ratio Real
Poisson ratio of the artery
Solver solver id
Keywords for the one dimensional solver. Note that all the keywords related to linear solver (starting
with Linear System) may be used in this solver as well. They are defined elsewhere.
Equation String [Artery Outlet Solver]

Variable [Wnodal]
The variable which is solved
Variable DOFs [1]

Procedure File "ArteryOutlet" "OutletCompute"

The name of the file and the subroutine
Equation eq id
The equation section is used to define a set of equations for a body or set of bodies
Artery Outlet Solver Logical [True]
If set True, the solver is used. The name of the solver must match with the name in the Solver
section
Boundary Condition boundary id
The pressure of the given coordinate direction i at the artery outlet of the higher order model is set to
correspond the value given by the 1D model.
Pressure i Variable Time
Real Procedure "ArteryOutlet" "OutletPres"

The diameter of the artery in the appropriate direction at the outlet of the higher order model is set to
correspond the value given by the outlet boundary condition solver. The subroutines OutletdX and
OutletdY are located in the module ArteryOutlet
Displacement i Variable Time
Real Procedure "./ArteryOutlet" "OutletdX"

This is the inlet boundary of the one dimensional section which is coupled with both, the fluid and the
solid outlet boundary of the higher order model
Fluid Coupling With Boundary Integer
Structure Coupling With Boundary Integer

CSC – IT Center for Science

BIBLIOGRAPHY 316

Figure 71.1: An example of the model results: pressure pulse propagation in a 2D axisymmetric model
combined with an 1D model.

Bibliography
[1] L. Formaggia, J.F. Gerbeau, F. Nobile, and A. Quarteroni. Numerical treatment of defective boundary
conditions for the navier-stokes equations. SIAM J. Numer. Anal, 40:376–401, 2002.

[2] E. Godlewski and P.-A. Raviart. Numerical Approximation of Hyperbolic Systems of Concervation Laws.
Springer, 1996.
[3] T. J. R. Hughes and J. Lubliner. On the one-dimensional theory of blood flow in the large vessels.
Mathematical Biosciences, 19:161–170, 1973.

CSC – IT Center for Science

Model 72

BEM Solver for Poisson Equation

Module name: PoissonBEM

Module subroutines: PoissonBEMSolver
Module authors: Juha Ruokolainen
Document authors: Juha Ruokolainen

72.1 Introduction
This module solves the Laplace equation by boundary element method (BEM), where the differential equa-
tion is transformed to integral equation along the boundaries. On the boundaries either potential or normal
flux may be defined. A source term may be included (Poisson equation), but the source term remains a
volume integral.
This is an old module which has limited use since the BEM matrix is assembled in full. This means
that the memory consumption and speed of solution grow rather unfavorably with problem size. Efficient
BEM solvers never create the full matrix but use iterative multilevel methods instead, such as the multi-
pole expansion. Also, the solver only works in serial so parallel computing is not available to resolve the
bottleneck.

72.2 Theory
The Poisson equation is mathematically described as

− ∆Φ − f = 0, in Ω, (72.1)

where f is the given source.

In BEM we transform this equation to integral equation over boundaries. We start by multiplying the
equation by a weight function and integrating over the volume, and integrating by parts
Z Z Z
∂Φ
− ∆Φw dΩ = ∇Φ · ∇w dΩ − w dΓ. (72.2)
Ω Ω Γ ∂n

Similarly we may write an equation reversing the roles of Φ and w

Z Z Z
∂w
− ∆wΦ dΩ = ∇w · ∇Φ dΩ − Φ dΓ. (72.3)
Ω Ω Γ ∂n

Subtracting the two equations we have

Z Z Z Z
∂Φ ∂w
− ∆Φw dΩ = − ∆wΦ dΩ − w dΓ + Φ dΓ (72.4)
Ω Ω Γ ∂n Γ ∂n

CSC – IT Center for Science

72. BEM Solver for Poisson Equation 318

Next we choose the weight w as follows:

− ∆w = δr (r0 ), (72.5)

so that Z
− ∆wΦ dΩ = Φ(r), (72.6)
Ω
The weight w chosen this way is the Green’s function for the Laplace operator, i.e.

log(r − r0 ) 1
w(r, r0 ) = in 2d , w(r, r0 ) = in 3d . (72.7)
2π 4π(r − r0 )
Finally we add the source term, and we have the equation
Z Z Z
∂Φ ∂w
Φ(r) − w dΓ + Φ dΓ − f w dΩ = 0. (72.8)
Γ ∂n Γ ∂n Ω

Only the source term is now integrated over the volume. This equation may now be discretized by standard
methods.

72.2.1 Boundary Conditions

Boundary conditions may be set for either potential

Φ = ΦΓ on Γ, (72.9)

or normal flux
∂Φ
− = g on Γ. (72.10)
∂n

72.3 Keywords
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere. Note also that the BEM discretization results to a full
linear system in contrast to FEM discretizations and the ILU preconditioning settings are not available.

Equation String [PoissonBEM]

The name of the equation.
Procedure File ["PoissonBEM" "PoissonBEMSolver"]
This keyword is used to give the Elmer solver the place where to search for the equation solver.
Variable String [Potential]
Give a name to the field variable.
Variable DOFs Integer [1]
This keyword must be present, and must be set to the value 1.
Exported Variable 1 String Flux
If this keyword is given, the output will include the normal flux at boundaries, the name must be
exactly as given.
Exported Variable 1 DOFs Integer [1]
This keyword must be present if Flux values are to be computed, and must be set to the value 1.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
PoissonBEM Logical
if set to True, solve the Poisson equation, the name of this parameter must match the Equation
setting in the Solver section.

CSC – IT Center for Science

72. BEM Solver for Poisson Equation 319

If the mesh has any volume elements with a body id that corresponds to a body where to the Poisson
equation is activated, the value of the potential is computed for these elements as a postprocessing
step. Note that the computation of potential is not a trivial task, so large number of volume elements
may result to long execution time.
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. The one related to Poisson
(BEM) equation are
Body Id Integer
Give body identification number for this boundary, used to reference body definitions in .sif
file. This parameter must be set so that the ElmerSolver knows at which boundaries to solve the
corresponding equation.
Potential Real
Known potential value at boundary.
Flux Real
Known normal flux at boundary.
Normal Target Body Integer
The direction of boundary normals are important for the success of the computation. They
should point consistently outward from the boundaries. This is accomplished either if the mesh
generator automatically orients the boundary elements consistently, or including in the mesh
the parent (volume) elements of the boundaries and using this keyword. The value -1 of this
parameter points to the side where there are no volume elements. If the parameter gets the value
of the body id of the volume elements, the normal will point to that direction.
Body Force bf id
The source term for the Poisson equation may be given here. The volume integral is computed on a
body with a volume mesh and the PoissonBEM equation set to true.

Source Real
The source term for the Poisson equation.

CSC – IT Center for Science

Model 73

BEM Solver for Helmholtz Equation

Module name: HelmholtzBEM

Module subroutines: HelmholtzBEMSolver
Module authors: Juha Ruokolainen
Document authors: Juha Ruokolainen

73.1 Introduction
This module solves the Helmholtz equation by boundary element method (BEM), where the differential
equation is transformed to integral equation along the boundaries. On the boundaries either pressure or
normal flux may be defined.
This is an old module which has limited use since the BEM matrix is assembled in full. This means
that the memory consumption and speed of solution grow rather unfavorably with problem size. Efficient
BEM solvers never create the full matrix but use iterative multilevel methods instead, such as the multi-
pole expansion. Also, the solver only works in serial so parallel computing is not available to resolve the
bottleneck.

73.2 Theory
The Helmholtz equation is mathematically described as

(k 2 + ∆)Φ = 0, in Ω. (73.1)

In BEM we transform this equation to integral equation over boundaries. We start by multiplying the
equation by a weight function and integrating over the volume, and integrating by parts
Z Z Z Z
2 2 ∂Φ
(k + ∆Φ)w dΩ = k wΦdΩ − ∇Φ · ∇w dΩ + w dΓ. (73.2)
Ω Ω Ω Γ ∂n

Similarly we may write an equation reversing the roles of Φ and w

Z Z Z Z
∂w
(k 2 + ∆)wΦ dΩ = k 2 wΦdΩ − ∇w · ∇Φ dΩ + Φ dΓ. (73.3)
Ω Ω Ω Γ ∂n

Subtracting the two equations we have

Z Z Z Z
2 2 ∂Φ ∂w
(k + ∆)Φw dΩ = (k + ∆)wΦ dΩ − w dΓ + Φ dΓ (73.4)
Ω Ω Γ ∂n Γ ∂n

Next we choose the weight w as follows:

(k 2 + ∆)w = δr (r0 ), (73.5)

CSC – IT Center for Science

73. BEM Solver for Helmholtz Equation 321

so that Z
(k 2 + ∆)wΦ dΩ = Φ(r), (73.6)
Ω
The weight w chosen this way is the Green’s function for the Helmholtz operator, i.e.
1 1 0
w(r, r0 ) =
H0 (k(r − r0 )) in 2d , w(r, r0 ) = exp−ik(r−r ) in 3d , (73.7)
i4 4π
where H0 is the Hankel function.
Finally we have the equation
Z Z
∂Φ ∂w
Φ(r) − w dΓ + Φ dΓ = 0. (73.8)
Γ ∂n Γ ∂n

73.2.1 Boundary Conditions

Boundary conditions may be set for either pressure

Φ = ΦΓ on Γ, (73.9)

or normal flux
∂Φ
− = g on Γ. (73.10)
∂n

73.3 Keywords
Simulation
Angular Frequency Real
Give the value of the angular frequency for the simulation.
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere. Note also that the BEM discretization results to a full
linear system in contrast to FEM discretizations and the ILU preconditioning settings are not available.

Equation String [HelmholtzBEM]

The name of the equation.
Procedure File ["HelmholtzBEM" "HelmholtzBEMSolver"]
This keyword is used to give the Elmer solver the place where to search for the equation solver.
Variable String [Pressure]
Give a name to the field variable.
Variable DOFs Integer [2]
This keyword must be present, and must be set to the value 2.
Exported Variable 1 String Flux
If this keyword is given, the output will include the normal flux at boundaries, the name must be
exactly as given.
Exported Variable 1 DOFs Integer [2]
This keyword must be present if Flux values are to be computed, and must be set to the value 2.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
HelmholtzBEM Logical
if set to True, solve the Helmholtz equation, the name of this parameter must match the
Equation setting in the Solver section.

CSC – IT Center for Science

73. BEM Solver for Helmholtz Equation 322

If the mesh has any volume elements with a body id that corresponds to a body where to the Helmholtz
equation is activated, the value of the pressure is computed for these elements as a postprocessing step.
Note that the computation of potential is not a trivial task, so large number of volume elements may
result to long execution time.
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types.
Dirichlet boundary conditions may be set for all the primary field variables. The one related to
Helmholtz (BEM) equation are
Body Id Integer
Give body identification number for this boundary, used to reference body definitions in .sif
file. This parameter must be set so that the ElmerSolver knows at which boundaries to solve the
corresponding equation.
Pressure 1 Real
Known real part of pressure at boundary.
Pressure 2 Real
Known imaginary part of pressure at boundary.
Flux 1 Real
Known real part of normal flux at boundary.
Flux 2 Real
Known real part of normal flux at boundary.
Normal Target Body Integer
The direction of boundary normals are important for the success of the computation. They
should point consistently outward from the boundaries. This is accomplished either if the mesh
generator automatically orients the boundary elements consistently, or including in the mesh
the parent (volume) elements of the boundaries and using this keyword. The value -1 of this
parameter points to the side where there are no volume elements. If the parameter gets the value
of the body id of the volume elements, the normal will point to that direction.

CSC – IT Center for Science

Model 74

Magnetoquasistatic approximation for

axial symmetry

Module name: StatMagSolve

Module subroutines: StatMagSolver
Module authors: Juha Ruokolainen, Ville Savolainen, Jussi Heikonen, Peter Råback, Antti Pursula
Document authors: Ville Savolainen, Peter Råback, Antti Pursula, Mika Malinen

74.1 Introduction
Note: This solver is obsolete!
Maxwell’s equations may generally be expressed by employing a scalar potential and a vector potential.
The magnetic flux density is then the curl of the vector potential. In some cases the effect of the scalar
potential vanishes and the system is fully described by the vector potential. These cases include magne-
tostatics problems where time-independent magnetic fields may be created by electromagnets with given
current distributions or permanent ferromagnets. The solver considered here allows the first option, with
non-homogeneous and non-linear magnetic materials.
The scalar potential may also be ignored in two-dimensional magnetoquasistatic cases when the current
density acts in a direction orthogonal to the plane considered. Then eddy current effects relating to a sinu-
soidal evolution of the current density may also be considered at low frequencies. If there are no conductors
in the system, this approximation reduces to the equations of magnetostatics.
This solver was historically developed for the axially symmetric cases and it should only be used in
those. For handling problems in orthogonal Cartesian coordinates, see the modules MagnetoDynamics
and MagnetoDynamics2D for 3-D and 2-D versions, respectively.

74.2 Theory
When there are no hard ferromagnets, a magnetostatics problem may be expressed using the magnetic vector
~ that gives the magnetic flux density as B
potential A ~ = ∇ × A.
~ It is obtained directly using the Ampère’s
law, so that  
1 ~
∇× ∇ × A = ~. (74.1)
µ
Here µ is the magnetic permeability of the material. The equation may be non-linear through the magnetic
permeability curve of a ferromagnetic material. The solver discussed is intended for handling the axially
symmetric version of (74.1).
The axially symmetric version of (74.1) may also employed to handle magnetoquasistatic problems
where the effect of the displacement current is ignored. If there are conductors in the system, the current

CSC – IT Center for Science

74. Magnetoquasistatic approximation for axial symmetry 324

~ + ~0 where σ is the electric conductivity and the electric field E

density is then written as ~ = σ E ~ is given
by
~
~ = − ∂A .
E
∂t
In the time-harmonic case the source current density ~0 is considered to be ~0 (x, t) = ~0 (x)eiωt , where
ω = 2πf is the angular frequency. Using a trial A(x,~ t) = A ~ 0 (x)eiωt , we then obtain an equation for the
amplitude:  
1 ~ 0 + iωσ A ~ 0 = ~0 .
∇× ∇×A
µ
In the axially symmetric case, the magnetic flux density B ~ has only r- and z-components, while the
~
current density ~ and the vector potential A have only φ-components, so that the equation to be solved is
 
1
∇× ∇ × Aφ~eφ + iωσAφ~eφ = jφ~eφ . (74.2)
µ
The vector potential satisfies now automatically the Coulomb gauge. After the solution the heat generation
in the conductors may be computed from
1 2 ~ 2
h= σω |A0 | .
2
In contrast to the stationary case where Aφ is real and the equation has only one unknown, in the har-
monic case the equation has two unknowns — the in-phase and the out-of-phase component of the vector po-
tential. The magnetic flux density may generally be calculated from the vector potential as a post-processing
step. Both the vector potential and the magnetic flux density components are then provided. The vari-
able names in the result file are magnetic vector potential and magnetic flux density
i, with i=1 and i=2.

74.2.1 Boundary Conditions

For the magnetostatics equation one can apply either Dirichlet or homogeneous natural boundary conditions.
In both cases, one must check that the computational domain is extended far enough to avoid numerical
errors.
The Dirichlet boundary condition for Aφ is

Aφ = Abφ . (74.3)

In practice, when the Dirichlet condition is used, one usually takes Abφ = 0. If a Dirichlet condition is not
specified, the homogeneous natural boundary condition is used.

74.3 Keywords
Simulation
Frequency Real
Frequency f if harmonic simulation is used.
Angular Frequency Real
Angular frequency ω = 2πf if harmonic simulation is used, alternative to the previous one.
Constants
Permeability of Vacuum Real [4π10−7 ]
Solver solver id
Note that all the keywords related to linear solver (starting with Linear System) may be used in
this solver as well. They are defined elsewhere.

CSC – IT Center for Science

74. Magnetoquasistatic approximation for axial symmetry 325

Equation String [Static Magnetic Field]

The name of the equation.
Variable String [Aphi]
The name of the variable.
Variable Dofs Integer
Number of dofs in the field, this should be one for the steady-state case and two for time-
harmonic analysis.
Procedure File ["StatMagSolve" "StatMagSolver"]
The name of the file and subroutine.
Harmonic Simulation Logical
Assume time-harmonic simulation.
Calculate Magnetic Flux Logical [True]
By this flag the computation of the magnetic flux is activated. The default is False.
Calculate Magnetic Flux Abs Logical [True]
Sometimes it is useful to have the absolute magnetic flux available for nonlinear material laws.
Then this flag can be turned on. The default is False.
Calculate Joule Heating Logical [True]
In large computations the automatic computation of the Joule heating may be turned off by this
keyword. The default is False. The keyword is only applicable for the harmonic case. The
computation results to two additional variables. Joule Heating gives the absolute heating
and Joule Field the field that gives the heating when multiplied by the electric conductivity.
This may be needed if the electric conductivity is discontinuous making also the heating power
discontinuous.
Desired Heating Power Real
A constant that gives the desired total heating power in Watts. If the keyword is active, then the
Joule Heating and Joule Field are multiplied by the ratio of the desired and computed
heating powers.
Nonlinear System Convergence Tolerance Real
This keyword gives a criterion to terminate the nonlinear iteration after the relative change of the
norm of the field variable between two consecutive iterations k is small enough

||Akφ − Ak−1 k
φ || < ||Aφ ||,

where  is the value given with this keyword.

Nonlinear System Max Iterations Integer
The maximum number of nonlinear iterations the solver is allowed to do. If neither the material
parameters nor the boundary conditions are functions of the solution, the problem is linear and
this should be set to be 1.
Nonlinear System Relaxation Factor Real
Giving this keyword triggers the use of relaxation in the nonlinear equation solver. Using a
factor below unity is sometimes required to achieve convergence of the nonlinear system. A
factor above unity might speed up the convergence. Relaxed variable is defined as follows:
0
Aφ = λAkφ + (1 − λ)Ak−1
φ ,

where λ is the factor given with this keyword. The default value for the relaxation factor is unity.

Equation eq id
The equation section is used to define a set of equations for a body or set of bodies:
Static Magnetic Field Logical
If set to True, solve the magnetostatics equation.

CSC – IT Center for Science

74. Magnetoquasistatic approximation for axial symmetry 326

Body Force bf id
The body force section may be used to give additional force terms for the equations.
Current Density Real
Specifies the azimuthal component of the current density. It may be a positive or negative con-
stant, or a function of a given variable.
Current Phase Angle Real
Specifies the phase angle of the current density in degrees. The default phase angle is zero.
Applies only to the time-harmonic case.
Joule Heat Logical
If this flag is active, the heat equation will automatically include the computed Joule heating as
a heat source. Then it is assumed that Joule heating field φ is named Joule field. If there is
no heat equation, this flag has no effect.
Initial Condition ic id
The initial condition section may be used to set initial values for the field variables. The following
variable is active:

Aphi Real
The azimuthal component of the magnetic vector potential.
Material mat id
The material section is used to give the material parameter values. Material parameter available for
the magnetostatics equation are.

Relative Permeability Real

~ =
The relative magnetic permeability µ is set with this keyword, defining the material relation B
~
µr µ0 H. By default the relative magnetic permeability is one, but it may also be set otherwise or
~ The value of the
be a function of a given variable, typically given by the relation µr = µr (|B|).
~ is available by the variable named Absolute Magnetic Flux.
magnetic flux density |B|
Electric Conductivity Real
~ Only isotropic case is possible. The
The electric conductivity defines the relation ~ = σ E.
parameter is needed only in the time-harmonic case.
Boundary Condition bc id
The boundary condition section holds the parameter values for various boundary condition types. A
Dirichlet boundary condition may be set for the vector potential. The one related to the the axially
symmetric magnetostatics problem is
Aphi Real
The azimuthal component of the magnetic vector potential.

CSC – IT Center for Science

Model 75

Linear Constraints

Module name: included in solver (SolverUtils)

Module subroutines: SolveWithLinearRestriction
Module authors: Mika Juntunen
Document authors: Mika Juntunen

75.1 Introduction
This subroutine allows user to solve problems with linear constraints. Here constraints are forced with
Lagrange multipliers. This method, however, does not always lead to a well-posed problem. Conditions
that ensure a (unique) solution are excluded here, but the conditions are found in many books (check for
example [1]).

75.2 Theory
The problem at hand is
min xT Ax − xT f (75.1)
x

Let’s assume that we can solve this. Now we also want that the solution solves the system Bx = g. This
gives constraints to our solution. The rank of B should be less or equal to the rank of A. Loosely speaking,
the number of rows in B should be less or equal to the number of rows in A. The method of Lagrange
multipliers fixes these two equations together and gives a new functional to minimize.

min xT Ax − xT f + λT (Bx − g) (75.2)

x

If A is symmetric, then simple variational approach leads to solving x out of system

A BT
    
x f
= (75.3)
B 0 λ g

Symmetry of A is not always needed, but then more powerful methods have to be used to get to the above
system.

75.3 Limitations
• General usage of the subroutine
This subroutine can not be used by just adding keywords to solver input file. You must somehow
create the constraint matrix and then call for SolveWithLinearRestriction in your own subroutine or
function. The reader is encouraged to check for details in ElmerTutorials.

CSC – IT Center for Science

BIBLIOGRAPHY 328

• EMatrix-field
The EMatrix-field of the solved system matrix is used passing constraint matrix to SolveWithLinear-
Restriction. This will be a problem if some other function or subroutine tries to use the EMatrix-field.
EMatrix-field of the constraint-matrix is internally used by SolveWithLinearRestriction and should
therefore be left alone.

• Exported Multipliers
The length of the vector that holds the multipliers is limited to be a multiply of the number of nodes
in mesh. This means that the vector usually has extra entries. These entries are set to zero. This leads
to problems in extracting the correct values from the result file. Also post processing with ElmerPost
is at least tricky.

• Parallel solving is not yet implemented.

75.4 Keywords
Solver solver-id
Export Lagrange Multiplier Logical
If the multiplier has some physical meaning, you can save it to result file and to post file. This
feature has certain drawbacks, check subsection Limitations. Default is False.
Lagrange Multiplier Name String
The name you want to call the exported multipliers. This keyword has no meaning if the previous
keyword is set to False. Default name is LagrangeMultiplier.

Bibliography
[1] V. Girault and P.A. Raviart. Finite element methods for Navier-Stokes equations. Springer-Verlag, New
York, Berlin, Heidelberg, 1986.

CSC – IT Center for Science

Model 76

Density Functional Theory

Module name: DFTSolver

Module subroutines: Poisson, WaveFunctionSolver, ChargeDensitySolver, xc
Module authors: Olli Mali, trad (xc)
Document authors: Olli Mali

76.1 Introduction
This is an instructional text for using Elmer solvers I created for DFT calculations during the year 2006 while
preparing my Master’s Thesis [7]. These Solvers are rather experimental and I would not recommend their
use for highly complicated problems. Nevertheless they provide nice backbone for creating own DFT-solvers
with finite element method.

76.2 Theory
In DFT, Kohn-Sham equations [1, 2] play central role. They are set of highly nonlinear equations which
define uniquely the exact ground state charge density. From charge density the total energy of the system in
ground state can be calculated, which is unfortunately not implemented in present code.
The Kohn-Sham equations have a form
 
− 12 ∆ + VEXT (r) + VC [ρ(r)] + VXC [ρ(r)] ψk (r) = εk ψk (r)
PN (76.1)
2
ρ(r) = k=1 |ψk (r)| ,
where KS-orbitals ψk (r) are normalized, ψk (r)2 dr = 1, for eack k = 1, 2, . . . , N . VEXT is the exter-
R

nal potential caused by the nuclei, VC is the non-interacting Coulomb potential and VXC is the exchange
correlation potential that includes all the complicated many body effects, at least approximates. Nice expla-
nation from the widely used Local Density Approximation can be found from [3]. Nonlinearity occurs in
eigenvalue problem, where the operator depends on the solution of the eigen problem.

Self-Consistent iteration
The equations (76.1) are solved with self-consistent iteration (fixed point iteration). In this iteration Coulomb
and external potentials are solved from Poisson equation. The iteration steps are as follows:
1. Begin with previous or initial guess for charge density ρj
2. Solve new electric potential from Poisson equation,
M
X
− ∆V j+1 (r) = 1 j
4π ρ (r) − Zi δ(r − r i ) , (76.2)
i=1

CSC – IT Center for Science

76. Density Functional Theory 330

where δ refers to Dirac’s delta distribution (point load).

3. Solve eigenvalue problem,
 
− 12 ∆ + V j+1 (r) + VXC
j+1
(r) ψk (r) = εk ψk (r) , (76.3)

j+1 j+1
where VXC is calculated via some function W from point values of charge density ρj . VXC (r) =
j
W (ρ (r))).
4. Sum new charge density,
N
X
ρj+1 (r) = wk ψk (r)2 , (76.4)
k=1

where the weight coefficients wk depend on the numbers of electrons in orbitals. Extensive overview
of calculation of molecular orbitals can be found from [4, 5].

The point load at the nuclei location requires, that exactly at each nuclei there has to be a node in the
mesh. For the functionality of the solvers no other requirements exists for the mesh or domain.
Unfortunately convergence of this iteration procedure is not guaranteed. For simple atoms (Z = 1,2,3,4)
code converges within any tolerance limits but for more complicated molecules or atoms usually not. Sensi-
ble tolerances were found to between 10−6 or 10−4 .

Boundary Conditions
In theory the zero level of the potential can be set arbitrarily and often in practice one uses condition V (r) →
0, when |r| → ∞. Of course in real calculations the domain Ω is finite and we set, V (r) = 0 if r ∈ ∂Ω. One
also assumes Ω to be large enough, so that charge density vanishes on the boundary, ρ(r) = 0 if r ∈ ∂Ω, so
we set ψk (r) = 0 if r ∈ ∂Ω.
In Kohn-Sham -equations in order to obtain positive definite coefficient matrix on the left hand side of
eigenvalue problem (76.1), one sets V (r) → C, when |r| → ∞. The constant C has to be large enough, so
the eigenvalues are shifted positive. But too large value slows the convergence of the eigenvalue solver.

76.3 Keywords
From the structure of the self-consistent iteration it was natural to divide the solution procedure for three
solvers, Poisson solver, eigensolver and charge density summation. For each solver some keywords to
control the solution procedure were added.

Poisson Solver
Poisson Solver demands knowledge about the locations of the nuclei and their atomic numbers. There has to
be nodes in the mesh at the nuclei locations, or else error will occur. Following example demonstrates how
nuclei of the water molecule with two atoms of atomic numbers Z = 1 (Hydrogen) and single with Z = 8
(Oxygen) are set to the coordinates (0.0, 0.0, 0.0) (Oxygen) and (−1.43, 1.11, 0.0) and (1.43, 1.11, 0.0)
(Hydrogens). The rows beginning with ! are comments.

!
! NOFnuclei is the number of nuclei in the structure.
!

NOFnuclei = Integer 3

!
! NucleiTable is an array of the form

CSC – IT Center for Science

76. Density Functional Theory 331

! NucleiTable( NOFnuclei, 4 ) where each row

! includes the information of one nucleus.
! The colums are from left to right :
!
! atomic number, x-coordinate, y-coordinate and z-coordinate.
!

NucleiTable(3,4) = Real 8.0 0.0 0.0 0.0 \

1.0 -1.43 1.11 0.0 \
1.0 1.43 1.11 0.0

The self-consistent iteration requires heavy (under) relaxation to avoid divergence. Relaxation means
linear mixing of present solution with previous one(s). It is possible to use Guaranteed Reduction Pulay -
method [6, 7] where the mixing constants are calculated every time as a solution of a minimization problem,
it’s sensible to begin GR Pulay after some steps of linear mixing.
In following example the exponential relaxation scheme is changed to GR Pulay after 5 steps or if the
mixing parameter exceeds value 0.5 . Use of constant mixing parameter instead of increasing one can be
easily done by commenting out the first four uncommented lines and removing the comment sign ! from
following two lines.

!
! Select the relaxation method used, possibilities are
! constant mixing parameter a(k) = A or varying parameter
! with scheme a(k) = C + 1- A * Exp( B * k )
!

Relaxation Method = String "Exponential mixing"

Relaxation Parameter A = Real 1.0
Relaxation Parameter B = Real 0.05
Relaxation Parameter C = Real 0.005

! Relaxation Method = String "Constant mixing"

! Relaxation Parameter A = Real 0.01

Start GRPulay after iterations = Integer 5

Start GRPulay if relaxation factor is more than = Real 0.5

Eigenproblem Solver
Eigenproblem solver demands knowledge about the type of exchange correlation approximation used. Namely
the expression of W in third self-consistent iteration step. In module xc.f90 there are several different for-
mulae for LDA approximations. Some of them include spin directions and are to be used with different
solver composition where KS-orbitals for up- and down-spins are calculated separately.

!
! Choose the type of the XC Potential, possible choises are:
! "None"
! "Perdew-Zunger"
! "Von Barth-Hedin"
! "Gunnarsson-Lundqvist"
! "Perdew-Wang"

CSC – IT Center for Science

BIBLIOGRAPHY 332

XC Potential type = String "Perdew-Zunger"

Charge Density Solver

Charge density solver demands knowledge about the number of KS-orbitals to be summed and the weights
of each orbital. These are the N and wk ’s in fourth self-consistent iteration step. In following example one
sets N = 5 and wk = 2, for all k = 1, . . . , 5.

! Define the number of eigenmodes included on the

! calculation of charge density. Set weights for the
! eigen states. By default they are all 1.

Number of Eigenmodes Included = Integer 5

Weights of Eigen States(5,1) = Real 2.0 2.0 2.0 2.0 2.0

Weights of the Eigen States table has to be size (N, 1). Naturally N has to be equal or less
for the number of eigenstates to be solved in eigenvalue solver.

Bibliography
[1] P. Hohenberg, W Kohn Inhomogeneous Electron Gas Physical Review, Volume 136, Number 3B, 9
November 1964
[2] W. Kohn, L. J. Sham, Self-Consistent Equations Including Exchange and Correlation Effects Physical
Review, Volume 140, Number 4A, 15 November 1965

[3] M. P. Das, Density Functional Theory: Many-Body Effects Without Tears Proceedings of the Miniwork-
shop on "Methods of Electronic Structure Calculations", ICTP, Trieste, Italy 10 August - 4 September
1992
[4] Peter Atkins, Ronald Frieman, Molecular Quantum Mechanics Oxford University Press Inc., Fourth
edition 2005

[5] Andrew R. Leach, Molecular Modelling, Pearson Education Limited, Second edition 2001
[6] D. R. Bowler, M. J. Gillan, An efficient and robust technique for achieving self consistency in electronic
structure calculations Chemical Physics Letters 325 sivut 473-476 (2000)
[7] O. Mali, Kohn-Sham -yhtälöiden ratkaiseminen elementtimenetelmällä,
Diplomityö, 19. syyskuuta 2006

CSC – IT Center for Science

Model 77

Parallel I/O using HDF5 library

Module name: XdmfWriter

Module subroutines: XdmfWriter
Module authors: Mikko Lyly
Document authors: Mikko Lyly

77.1 Introduction
This subroutine is intended for saving parallel results in Xdmf/HDF5 format. The advantages of the Xdmf/HDF5-
format over the native parallel ep-format are the following:
• All results are stored in only two files (results.xmf and results.h5)
• The results are stored in a binary format with reduced storage requirements
• The results can be visualized on the fly during the solution
The result files written by XdmfWriter can be opened and visualized e.g. with Paraview.
At the moment, the module is available for the parallel version of Elmer only. Because of this, it has
been isolated from the main build system. The source code for XdmfWriter can be found from the source
tree in misc/xdmf and it should be compiled by the user as follows:
elmerf90 -I$HDF5/include -L$HDF5/lib -o XdmfWriter XdmfWriter.f90 -lhdf5_fortran -lhdf5

The environment variable $HDF5 defines the installation directory for the HDF5-library.

77.2 Keywords
Solver solver id
Equation String "Xdmf"
The name of the equation.
Procedure File "XdmfWriter" "XdmfWriter"
The name of the file and subroutine.
Base File Name String
Specifies the base file name of the output files. The default is results.
Single Precision Logical
This keyword specifies the output precision (4 byte single precision floating point numbers vs. 8
byte double precision floating point numbers). The default is false.
The following keywords define the scalar and vector fields to be saved:

CSC – IT Center for Science

77. Parallel I/O using HDF5 library 334

Scalar Field i String

The scalar fields to be saved, for example Pressure.
Vector Field i String
The vector fields to be saved, for example Velocity.

The number i must be in the range 1...1000.

77.3 Example
The following SIF-block saves results in Xdmf/HDF5-format for the Navier-Stokes equations:
Solver 1
Equation = String "Xdmf"
Procedure = File "XdmfWriter" "XdmfWriter"
Base File Name = String "MyResults"
Single Precision = Logical True
Scalar Field 1 = String "Pressure"
Vector Field 1 = String "Velocity"
End

CSC – IT Center for Science

Index

1D Active Direction, 305 Ascii Output, 280

1D Body Id, 305 Assembly Solvers, 81
1D Element Order, 305 Automated Source Projection BCs, 119
1D Mesh Create, 305 AV, 121
1D Mesh Length, 305 AV {e} j, 121
1D Mesh Ratio, 305 Average Within Materials, 141, 156, 232
1D Number Of Elements, 305 Averaging Method, 225
Averaging Order, 225
accumulation, 191
Active Coordinate, 211, 221, 225, 262, 311 Base File Name, 333
Active EigenModes, 280 BatteryPost, 300
Active Particle Volume Fraction, 307 BatterySolver, 300
Additional Info, 252 BC Id Offset, 280
Advect DG, 207 BDF Order, 11, 31, 36
Advect Elemental, 207 BeamSolver3D, 77
Advect IP, 207 Before Linsolve, 252
Advection Diffusion Equation Varname, 32 BEM, 317, 320
AdvectionDiffusionSolver, 29 Best File, 265
AdvectionReactionSolver, 35 Binary Output, 280
ALE, 9, 22 bisection, 264
ALE Formulation, 193 Block Diagonal A, 176
Align Coordinate, 292 Block Preconditioning, 95, 176, 182
Always Detect Structure, 222 Body, 251, 282
Ambient Temperature, 307 Body Force, 25, 43, 51, 59, 69, 75, 80, 86, 98, 102,
Angular Frequency, 85, 93, 122, 123, 132, 133, 157, 106, 110, 120, 122, 128, 132, 136, 140,
321, 324 141, 144, 153, 171, 177, 182, 187, 194,
Angular Velocity, 25 208, 219, 225, 312, 319, 326
Angular Velocity i, 120 Body Force i, 102, 182
Anode, 307 Body Force k, 80
Anodic charge transfer coefficient, 307 Body Force Parameters, 278
Aphi, 326 Body Forces, 15, 32, 37
Applied Current, 306 Body ID, 194
Applied Magnetic Field i, 26, 145 Body Id, 319, 322
Apply BCs Only, 211 Boltzmann Constant, 152
Apply Dirichlet, 193 Boltzmann distribution, 150
Apply Limiter, 12, 42 Bottom Surface, 223
Arbitrary Lagrangian-Eulerian, 9, 22 Bottom Surface Level, 222
Artery Outlet Solver, 315 Bottom Surface Variable Name, 222
Artery Poisson Ratio, 315 Boundary Condition, 17, 27, 33, 38, 43, 52, 60, 69,
Artery Radius, 315 75, 80, 82, 86, 94, 99, 107, 110, 120, 122,
Artery Wall Thickness, 315 132, 136, 140, 145, 148, 153, 163, 167,
Artery Wall Youngs Modulus, 315 171, 177, 182, 190, 194, 197, 205, 209,
ArteryOutlet, 313 214, 217, 220, 223, 225, 239, 243, 247,
Artificial Compressibility, 243, 244 249, 259, 271, 276, 282, 284, 308, 312,
artificial compressibility, 240 315, 319, 322, 326
ArtificialCompressibility, 240 boundary element method, 317, 320

CSC – IT Center for Science

INDEX 336

boundary integral, 271 Calculate Nodal Heating, 110, 123

Boundary Layer Thickness, 28 Calculate Nodal Losses, 157
Boussinesq, 25 Calculate PAngle, 59
Boussinesq approximation, 21 Calculate Pangle, 50
Box Contact Directions, 203 Calculate Poynting Vector, 133
Box Particle Collision, 203 Calculate Principal, 50, 59
Box Particle Contact, 203 Calculate Strains, 50, 59
Box Particle Periodic, 203 Calculate Stresses, 50, 59
Box Periodic Directions, 203 Calculate Surface Charge, 106
Break Line Loop, 275 Calculate Viscous Force, 247
BSolver, 138 Calculate Volume Current, 110
Bubbles, 12, 32, 85, 311 Capacitance Bodies, 106
Bubbles in Global System, 93 Capacitance Body, 107
Bulk Modulus, 43 capacitance matrix, 105
Bulk Viscosity, 94, 102 Capacitance Matrix Filename, 106
Cathode, 307
Calculate Acoustic Impedance, 95 Cathodic charge transfer coefficient, 307
Calculate Capacitance Matrix, 106 Ce, 307
Calculate Ce sensitivity, 304 Cell Capacity, 306
Calculate Charges, 306 Cfix diffusion, 162
Calculate Coil Current, 162 Charge Density, 106, 153
Calculate Cs sensitivity, 305 Charge Number, 153
Calculate Current Density, 123 ChargeDensitySolver, 329
Calculate Div of Poynting Vector, 133 Check for Duplicates, 284
Calculate Electric Energy, 106, 152 Check Material Balance, 304
Calculate Electric Field, 106, 123, 152 CircuitsAndDynamics, 125
Calculate Electric field, 133 CircuitsAndDynamicsHarmonic, 125
Calculate Electric Flux, 106, 152 CircuitsOutput, 125
Calculate Electric Force, 249 coating, 195
Calculate Elemental Fields, 123, 133, 137, 157 Coefficient i, 271
Calculate Energy Functional, 133 Coil Anisotropic, 162
Calculate Fluidic Force, 247 Coil Bandwidth, 162
Calculate Flux, 43, 232 Coil Center(3), 162
Calculate Flux Abs, 232 Coil Closed, 162
Calculate Flux Dim, 44 Coil Conductivity Fix, 162
Calculate Flux Magnitude, 232 Coil Cross Section, 162
Calculate Force, 43 Coil End, 163
Calculate Force Dim, 44 Coil Normal(3), 162
Calculate Grad, 232 Coil Start, 163
Calculate Grad Abs, 232 Coil Type, 127
Calculate Grad Magnitude, 232 CoilSolver, 159
Calculate Harmonic Loss, 123 CoilSolverr, 159
Calculate Heating, 43 Component, 124, 127
Calculate Joule Heating, 110, 123, 141, 325 Compressibility Model, 26, 33, 43, 243
Calculate Magnetic Field Strength, 123, 133 CompressibilityScale, 240
Calculate Magnetic Flux, 325 CompressibleNS, 100
Calculate Magnetic Flux Abs, 325 Compressiblity Model, 16
Calculate Magnetic Flux Density, 133 Compute Nodal Average, 37
Calculate Magnetic Force, 124 Compute Radiator Factors, 12
Calculate Magnetic Torque, 124 Concentration Units, 32
Calculate Matrix Suction, 311 Conserve Volume, 189
Calculate Maxwell Stress, 123 Conserve Volume Relaxation, 189
Calculate Mesh Velocity, 219 Constant Bulk Matrix, 235, 236
Calculate Nodal Fields, 123 Constant Bulk System, 50
Calculate Nodal Forces, 123

CSC – IT Center for Science

INDEX 337

Constant Weights, 106, 110, 152 Default BC Id, 280

Constant-Viscosity Start, 175 Default Body Id, 280
Constants, 10, 23, 106, 118, 131, 136, 139, 148, 152, Deflection i, 75
166, 248, 306, 324 Delete Wall Particles, 202
continuity equation, 241 delta function, 186
Continuous Reading, 294 Density, 16, 25, 33, 51, 58, 68, 75, 79, 86, 167, 175,
Convection, 15, 25, 32, 37, 194 181, 315
Convection Velocity i, 16, 33, 38, 86, 170 Desired Coil Current, 162
Convective, 176, 181 Desired Current Density, 162
Convert From Equation Name, 261 Desired Heating Power, 141, 325
Convert From Variable, 261 DFTSolver, 329
Coordinate Condition Variable Name, 203 dielectric layer, 148
Coordinate Initialization Method, 201, 207 Diffusion Coefficient, 259, 289
Coordinate System, 11, 31, 36, 58, 68, 79, 93, 101, Diffusivity Name, 289
229 Dirichlet boundary condition, 10, 20, 30, 36, 139,
Coordinate Transformation, 297 143, 324
Correct Butler Volmer Fluxes, 306 Discontinuous Bodies, 281
Correct Source Disbalance, 304 Discontinuous Galerkin, 35, 37, 141, 156, 232, 281
Correct Surface, 222 Displace Mesh, 50, 68
Correct Surface Mask, 222 Displaced Shape, 244
Cosine Series i, 257 Displacement i, 51, 52, 315
Cost Function Absolute, 265 Displacement Mode, 221, 222, 225
Cost Function Index, 270 Displacement Variable Eigenmode, 85
Cost Function Maximize, 265 Displacement Variable Frequency, 86
Cost Function Name, 265 Displacement Variable Name, 82, 85, 244
Cost Function Target, 265 Div Discretization, 24
Create Histogram, 226 DivergenceSolver, 236
Critical Shear Rate, 26 DNU i, 69
Cross Section Area, 79 domain integral, 270
Cs, 307 Dot Product Tolerance, 211, 222, 225, 263
Cumulative Displacements, 216, 219 Draw Velocity, 210
Current Collector Resistance, 307 drawing, 195
Current Control, 110 Dx Format, 279
Current Density, 110, 121, 140, 308, 326
current density, 108 E {e} i, 136
Current Density i, 132 E im {e} i, 133
Current Density BC, 110, 163 E re {e} i, 133
Current Density i, 120 Echo Values, 270
Current Density Im, 141 effective parameters, 73
Current Density im i, 132 Eigen Analysis, 49, 68, 74, 252, 280
Current Density Im i, 122 Eigen System Damped, 252
Current Density Rate i, 136 Eigen System Use Identity, 252
Current Phase Angle, 326 Eigen System Values, 49, 75, 252
Current Source, 110 ElasticSolve, 54
curvature, 187 ElasticSolver, 54
Curvature Coefficient, 189 Electric Conductivity, 110, 119, 136, 139, 145, 326
Curvature Diffusion, 189 Electric Conductivity Im, 122
Cutoff Voltage, 306 Electric Conductivity im, 140
Electric Current Density, 121
Damping, 52, 75 Electric Current Density Im, 122
Darcy’s law, 22 Electric Damping Coefficient, 136
DataToFieldSolver, 258, 288 Electric Field , 166
Dead Loads, 70 Electric Flux, 107
Decay Time i, 257 Electric Flux BC, 153
Decay Timestep i, 257 Electric Infinity BC, 107

CSC – IT Center for Science

INDEX 338

Electric Potential, 120 Faraday Constant, 306

Electric Robin Coefficient, 133 FieldName, 259
Electric Robin Coefficient im, 133 FieldName Continue, 259
Electric Transfer Coefficient, 121 File Append, 188, 270, 275
Electric Transfer Coefficient Im, 122 Fileindex Offset, 284
ElectricForce, 248 Filename, 188, 269, 275, 289, 292, 297
Electrode Area, 128 Filename Numbering, 270
Electrode Plate Area, 307 Filename Particle Numbering, 204, 284
Electrode Potential, 107 Filename Prefix, 204, 283
Electrokinetics, 165 Filename Timestep Numbering, 204, 284
electrokinetics, 23 FilmPressure, 43
Electrolyte Diffusion Coefficient, 307 FilmPressure Lower Limit, 43
Electrolyte Volume Fraction, 307 filtering, 255
ElectrolyteCons, 300 FilterTimeSeries, 255
ElectrolytePot, 300 FindOptimum, 264
Element, 93, 101, 119, 171, 176 Fit Coefficient, 289
ElementStats, 226 Fix Displacement, 50
Elmer2OpenFoamIO, 288 Fix Input Current Density, 119
Emissivity, 16, 17 Fixed Boundary, 220
EMWaveCalcFields, 135 Fixed Overpotential, 303–305
EMWaveSolver, 135 Fixed Parameter i, 265
Enable Scaling, 297 Flow Admittance, 43
Energy Accommodation Coefficient, 95 Flow BodyForce i, 25, 177
energy conservation, 8 Flow Force BC, 27
energy method, 73 Flow Interface, 87
Enforce Positive Magnitude, 232 Flow Line, 225
Enthalpy, 16 Flow Model, 24
EO Mobility, 167 FlowSolve, 19
Equation, 11, 15, 23, 25, 31, 32, 37, 42, 43, 49, 50, FlowSolver, 19
58, 59, 68, 74, 80, 85, 86, 93, 98, 101, 106, Fluid Coupling With Boundary, 315
110, 119, 121, 123, 127, 128, 132, 133, fluid-structure interaction, 240
136, 137, 140, 141, 143, 144, 152, 156, FluidicForce, 246
161, 166, 170, 175, 181, 187–189, 193, Flux, 319
196, 201, 207, 210, 214, 219, 221, 225, Flux 1, 322
226, 229, 232, 234, 236, 238, 243, 244, Flux 2, 322
247, 249, 251, 259, 261, 262, 265, 279, Flux Coefficient, 232, 239, 275
283, 286, 288, 289, 292, 293, 295, 297, Flux Variable, 239, 275
302–306, 311, 312, 315, 318, 321, 325, FluxSolver, 231
333 Force BC, 243
Equilibrium Density, 94, 101 Force i, 52
Equilibrium Temperature, 94, 101 Force i Im, 52
Eulerian, 185 Fourier Integrate Cycles, 157
Exact Coordinates, 270 Fourier Loss Filename, 157
Excess Pressure, 99 Fourier series, 255
Exec Solver, 249 Fourier Series Components, 157
Export Lagrange Multiplier, 128, 328 Fourier Series Output, 157
Exported Variable 1, 143, 188, 193, 318, 321 Fourier Start Cycles, 157
Exported Variable 1 DOFs, 193, 318, 321 Fourier Start Time, 157
Extend Elastic Layers, 252 Fourier Start Timestep, 157
Extend Elastic Region, 252 FourierLossSolver, 154
External Concentration, 33 Free Moving, 28
External Pressure, 27 Free Surface, 27
External Temperature, 17 free surface, 185
Extract Interval, 188 Free Surface Bottom, 197

CSC – IT Center for Science

INDEX 339

Free Surface Number, 197 Heaviside function, 186

Free Surface Reduced, 197 Helmholtz, 86
FreeSurfaceReduced, 195 HelmholtzBEM, 321
FreeSurfaceSolver, 191 HelmholtzBEMSolver, 320
Frequency, 49, 85, 93, 157, 324 HelmholtzSolver, 84
Frequency i, 257 Histogram Intervals, 226
Friction Heat, 15 History File, 265
FSI BC, 60 Hole Correction, 75
Hole Depth, 149
Gap Height, 42, 149 Hole Fraction, 75, 149
Gas Constant, 306 Hole Size, 75, 149
Gebhardt factors, 10, 13 Hole Type, 149
Gebhardt Factors Fixed After Iterations, 13 Hydraulic Conductivity, 311
Gebhardt Factors Fixed Tolerance, 14
Gebhardt Factors Solver Full, 14 Ignore Electrolyte Diffusion, 304
Gebhardt Factors Solver Iterative, 14 ILU Order for Schur Complement, 96
Genetic algorithm, 264 ILU Order for Velocities, 96
Geometric Stiffness, 50 Im Body Force i, 94
Geometry Id, 282 Im Heat Source, 94
GiD, 279 Im Reference Wall Velocity i, 95
Gid Format, 279 Im Specific Acoustic Impedance, 94
Gmsh, 279 Im Specific Thermal Impedance, 95
Gmsh Format, 279 Im Surface Traction i, 94
GmshOutputReader, 292 Im Temperature, 94
GPA Coeff, 51 Im Velocity i, 94
Gradp Discretization, 25 Impedance Target Boundary, 95
Grashof convection, 20 Implicit Gebhardt Factor Fraction, 13
Gravitational Prestress Advection, 51 Impose Body Force Current, 123
Gravity, 23 Incompressible, 50
Green’s function, 321 induction equation, 142
Grid dx, 284 Inertial Bodyforce j, 59
Grid nx, 284 Inexact Integration, 156
Grid Origin i, 284 Infinity BC, 140
GridDataReader, 296 inflow boundaries, 36
Guess File, 265 Initial Condition, 16, 25, 33, 37, 51, 86, 98, 144, 194,
307, 314, 326
H-B Curve, 140 Initial Coordinate, 201
Hard Displacement Name, 225 Initial Coordinate Search, 202
Harmonic Analysis, 49 Initial Parameter i, 265
Harmonic Loss Coefficient i, 157 Initial SOC, 306
Harmonic Loss Field Exponent(K), 157 Initial Sphere Center, 201
Harmonic Loss Frequency Exponent(K), 157 Initial Sphere Radius, 201
Harmonic Loss Linear Coefficient, 124 Initial Velocity, 201
Harmonic Loss Quadratic Coefficient, 124 Initial Velocity Amplitude, 201
Harmonic Simulation, 325 Initial Velocity Time, 202
Heat Capacity, 16, 33 Initial Volume, 189
Heat Conductivity, 16, 94, 102 Initialization Condition Variable, 201
Heat Equation, 15, 144 Initialization Mask Variable, 201, 207
Heat Expansion Coefficient, 26, 52 Initialize State Variables, 59
Heat Flux, 17 integral equation, 317, 320
Heat Flux BC, 17 Integral Heat Source, 15
Heat Source, 15 Integration Points At Radius, 261
Heat Transfer Coefficient, 17 Internal history, 265
HeatSolve, 8 Interpolation Multiplier, 298
HeatSolver, 8 Interpolation Offset, 298

CSC – IT Center for Science

INDEX 340

Ion Density, 153 Limit Solution, 37

Is Time Counter, 297 Linear Constraints, 327
Is Time Index, 297 Linear System Adaptive Tolerance, 176
Isosurface, 286 Linear System Base Tolerance, 177
Isosurface Value i, 263, 275 Linear System Convergence Tolerance, 69, 96, 176,
Isosurface Values, 286 182, 233, 235, 237
Isosurface Variable, 286 Linear System Direct Method, 303
Isosurface Variable i, 263, 275 Linear System GCR Restart, 177
Linear System Iterative Method, 120, 233, 235, 237
Jfix, 121 Linear System Max Iterations, 96, 177, 182, 233,
Jli, 308 235, 237
Joule Heat, 15, 110, 144, 326 Linear System Preconditioning, 120, 233, 235, 237
Joule heating, 9, 109 Linear System Preconditioning Damp Coefficient, 132
Linear System Preconditioning Damp Coefficient im,
KE C1, 26 132
KE C2, 26 Linear System Refactorize, 120
KE Cmu, 26 Linear System Relative Tolerance, 176
KE SigmaE, 26 Linear System Scaling, 303
KE SigmaK, 26 Linear System Solver, 233, 235, 237, 303
Kinetic Constant, 307 Linearize Flux, 303–305
Kinetic Energy, 25 Lorentz Force, 25, 144
Kinetic Energy Dissipation, 25 Lorentz force, 20
Knudsen number, 40 Lorentz Velocity i, 120, 140
Lagrange Element Degree, 281 Magnetic Bodyforce i, 144
Lagrange Gauge Penalization Coefficient, 120 Magnetic Boundary Load i, 133
Lagrange Multiplier Name, 328 Magnetic Boundary Load i im, 133
Lagrange multipliers, 327 Magnetic Boundary Load i, 136
Lagrangian, 185 Magnetic Field i, 144, 145
Large Deflection, 68 Magnetic Field Strength i, 121
Layer Charge Density, 107 Magnetic Field Strength Im i, 122
Layer Electric Conductivity, 122 Magnetic Flux Density {n}, 121
Layer Index i, 263 Magnetic Flux Density i, 121
Layer Permittivity, 149 Magnetic Flux Density Im {n}, 122
Layer Relative Permeability, 122 Magnetic Flux Density Im i, 122
Layer Relative Permittivity, 107 Magnetic Induction, 25, 144
Layer Thickness, 107, 149 Magnetic Permeability, 145
level-set method, 185 Magnetic Transfer Coefficient, 121
LevelSet, 185 Magnetic Transfer Coefficient Im, 122
LevelSet Bandwidth, 189 MagneticSolve, 142
Levelset bandwidth, 190 MagneticSolver, 142
LevelSet Convect, 188 Magnetization i, 120, 140
LevelSet Courant Number, 190 Magnetization i Im, 141
Levelset Curvature BC, 190 Magnetization Im i, 122
LevelSet Flux, 187 MagnetoDynamics, 111
LevelSet Timestep Directional, 190 MagnetoDynamics2D, 138
LevelSet Variable, 188, 189 MagnetoDynamics2DHarmonic, 138
LevelSet Velocity 1, 188 MagnetoDynamicsCalcFields, 111
LevelSet Velocity 2, 188 magnetohydrodynamics, 142
LevelSet Velocity i, 187 magnetostatics, 323
LevelSetCurvature, 185 Mapped Mesh Name, 223
LevelSetDistance, 185 Mask Condition, 282
LevelSetIntegrate, 185 Mask Diffusion, 259
LevelSetSolver, 185 Mask Name, 282, 284, 292
LevelSetTimestep, 185 Mask Name i, 270

CSC – IT Center for Science

INDEX 341

Mask Variable, 259, 281 Mesh Scale, 219

mass conservation, 195 Mesh Translate, 219
Mass i, 70, 82 Mesh Update, 214
Mass Transfer Coefficient, 33 Mesh Update i, 194, 214
Master Bodies, 124, 127 Mesh Update Variable, 222
Master Boundaries, 124 Mesh Velocity 1, 52
Material, 16, 25, 33, 37, 42, 51, 58, 68, 75, 79, 86, Mesh Velocity 2, 52
93, 98, 101, 106, 110, 118, 122, 124, 132, Mesh Velocity 3, 52
136, 139, 140, 145, 152, 157, 167, 170, Mesh Velocity First Zero, 222
175, 181, 187, 188, 190, 211, 214, 217, Mesh Velocity Variable, 222
243, 244, 247, 249, 307, 311, 315, 326 MeshSolver, 213, 216
Material Constants, 58 MHD Velocity i, 145
Material Coordinates Unit Vector 1(3), 52 Mid Surface, 222, 223
Material Coordinates Unit Vector 2(3), 52 Min Coordinate i, 284
Material Coordinates Unit Vector 3(3), 52 Min Initial Coordinate i, 201
Material Parameter, 170 Min Mask Value, 259
Material Tensor(3,3), 170 Min Parameter i, 265
Matrix Topology Fixed, 13 Min Timestep Size, 202
Max Characteristic Speed, 202 Minimum Gebhardt Factor, 13
Max Coordinate i, 284 Minimum Height, 222
Max Cumulative Time, 202 Minimum Hits At Radius, 261
Max Initial Coordinate i, 201 Minimum View Factor, 13
Max Inner GCR Iterations, 95 Mixed Formulation, 59
Max Integration Time, 208 MixedPoisson, 169
Max Mask Value, 259 Model Lumping, 50
Max Outer Iterations, 95 Model Lumping Boundary, 53
Max Output Level, 128 Model Lumping Filename, 50
Max Parameter i, 265 ModelMixedPoisson, 169
Max Relative Radius, 261 Moment About(dim), 247
Max Step Size, 266 Momentum Accommodation Coefficient, 95
Max Timestep Intervals, 202, 208 Mortar BC, 140
Max Timestep Size, 202 Moving Boundary, 220
Maximum Displacement, 193 Moving Mesh, 217, 270
Maximum Global Change Speed, 304 Moving Wall, 205
Maximum solid phase concentration, 307 MyMask, 284
Maxwell Material, 50
Maxwell stress tensor, 248 Name, 58
Maxwell’s equations, 104 Narrow Band, 188
Mean Free Path, 43 Narrow Interface, 163
Mesh Coefficient i, 217 natural convection, 20
Mesh Deform i, 217 Navier-Stokes, 25, 144
Mesh Displace i, 220 Navier-Stokes equation, 19
Mesh Force i, 217 Nelder-Mead, 264
Mesh Height Map, 222 Neo-Hookean Material, 59
Mesh Matrix(dim,dim), 219 Neumann boundary condition, 10
Mesh Normal Force, 217 Newmark Beta, 11, 31, 36
Mesh Origin, 219 Newton iteration, 21
Mesh Penalty Factor, 217 Newtonian, 19
Mesh Relax, 220 No Matrix, 127
Mesh Relax Normalize, 219 Nodal Penalty Factor, 217
Mesh Relax Source, 220 Nominal Shear Rate, 27
Mesh Reparametrization, 69 non-Newtonian, 19
Mesh Rotate, 219 Nonlinear Iteration Method, 182
Mesh Rotation Axis Order(dim), 219 Nonlinear System Convergence Measure, 303

CSC – IT Center for Science

INDEX 342

Nonlinear System Convergence Tolerance, 11, 24, Output Interval, 204

31, 37, 42, 69, 140, 143, 152, 176, 182, Output Node Types, 252
193, 197, 210, 303, 311, 325
Nonlinear System Max Iterations, 11, 24, 32, 37, 42, P2-P1 Approximation, 176
140, 144, 152, 162, 176, 182, 210, 303, Parabolic Model, 211
311, 325 Parallel Operator i, 271
Nonlinear System Newton After Iterations, 11, 24, Parallel Reduce, 270, 276
152, 176, 182 ParallelProjectToPlane, 260
Nonlinear System Newton After Tolerance, 11, 24, Parameter i, 277, 278
152, 176, 182 Particle Accumulation, 205
Nonlinear System Relaxation Factor, 12, 24, 32, 144, Particle Accumulation Max Shear, 205
182, 196, 225, 243, 303, 311, 325 Particle Accumulation Max Speed, 205
Norm Variable Index, 208 Particle Accurate At Face, 208
Normal Force, 52 Particle Bounciness, 203
Normal Force Im, 52 Particle Cell Fraction, 201
Normal Pressure, 69 Particle Cell Radius, 201
Normal Surface Traction, 60, 177 Particle Charge, 203
Normal Tangential Velocity, 167 Particle Damping, 203
Normal Target Body, 34, 319, 322 Particle Decay Distance, 204
Normal Velocity, 42 Particle Decay Time, 204
Normal-Tangential Displacement, 52 Particle Distance Integral Source, 208
Normal-Tangential Velocity, 27 Particle Drag Coefficient, 203
Normalize by Given Weight, 259 Particle Element Fraction, 201
Normalize by Nodal Weight, 259 Particle Fixed Condition, 208, 209
Normalize Coil Current, 162 Particle Gravity, 203
Number Of EigenModes, 280 Particle Info, 204, 208
Number of Material Constants, 58 Particle Lift, 203
Number of Particles, 201 Particle Mass, 203
Number of Passive Visits, 304, 305 Particle Node Fraction, 201, 207
Number of State Variables, 58 Particle Particle Collision, 202
Particle Particle Contact, 202
Ohm’s law, 108 Particle Radius, 203, 307
Open DX, 279 Particle Release Fraction, 202
Open Side, 43 Particle Release Number, 202
OpenFoam Directory, 289 Particle Save Fraction, 205
OpenFoam Field, 289 Particle Spring, 203
OpenFoam File, 289 Particle Time Integral Source, 208
OpenFoam Mesh i, 289 Particle To Field, 204
OpenFoam Timestep, 289 Particle To Field Mode, 204
OpenFOAM2ElmerFit, 288 Particle Trace, 205
OpenFOAM2ElmerIO, 288 Particle Wall, 209
Operator i, 208, 256, 263, 270 ParticleAdvector, 206
Optimal Finish, 265 ParticleDynamics, 198
Optimal Restart, 265 Partition Numbering, 270
Optimization, 264 Passive OpenFOAM Coordinate, 289
Optimization Method, 265 perforated plate, 73
Optimize Matrix Structure, 252 Perform Mapping, 196
Optimize Node Ordering, 275 Perfusion Density, 16
orthotropic, 73 Perfusion Heat Capacity, 16
Outflow Boundary, 99 Perfusion Rate, 15
Outflow boundary, 182 Perfusion Reference Temperature, 15
OutletCompute, 313 Permeability, 119, 139
Output Directory, 269, 275, 286 Permeability of Vacuum, 118, 131, 136, 139, 324
Output File Name, 279 Permittivity Of Vacuum, 106, 148, 152, 166, 248
Output Format, 204, 279, 283 Permittivity of Vacuum, 131, 136

CSC – IT Center for Science

INDEX 343

Phase Change Model, 15 Projection Mask Variable, 263

Phie, 308 projection matrix, 250
Phis, 308 ProjectToPlane, 260
Physical Units, 33, 34 Pseudo-Traction, 60
Picard iteration, 21
Plane Permutation, 261 Q {f} j, 171
Plane Stress, 50, 58 Quadratic Approximation, 119, 136
Plane Wave BC, 86 Quadratic Electrolyte Diffusion, 304
Poisson, 329
Poisson Boltzmann Alpha, 153 Radiation, 17
Poisson Boltzmann Beta, 153 Radiation Boundary, 17
Poisson Ratio, 51, 58, 68, 75, 214, 217 Radiation Boundary Open, 17
Poisson-Boltzmann equation, 23, 150 Radiation External Temperature, 17
PoissonBEM, 318 Radiation Target Body, 17
PoissonBEMSolver, 317 radiation: Linear System Keyword, 14
PoissonBoltzmannSolve, 150 radiation: Linear System Positive Definite, 14
Polyline Coordinates(n,DIM), 271, 275 radiation: Linear System Symmetric, 14
Polyline Divisions(n/2,DIM), 275 Radiator BC, 17
Population Coefficient, 265 Radiator Coordinates(n,3), 12
Population Crossover, 265 Radiator Power i, 12
Population Size, 265 Ratio of Convergence Tolerances, 95
Porositity Model, 311 Rayleigh Damping, 51
Porous Media, 27 Rayleigh Damping Alpha, 51, 68
porous media, 22 Rayleigh Damping Beta, 51
Porous Resistance, 27 Re Body Force i, 94
Post File, 282 Re Heat Source, 94
Potential, 107, 110, 140, 153, 163, 319 Re Reference Wall Velocity i, 95
Potential Coefficient, 25 Re Specific Acoustic Impedance, 94
Potential Difference, 106, 149 Re Specific Thermal Impedance, 95
Potential Field, 25 Re Surface Traction i, 94
Potential Force, 25 Re Temperature, 94
Potential Variable, 123 Re Velocity i, 94
Potential Variable Name, 203 reaction rate, 35
Power Control, 110 Recompute Stabilization, 222
Pre Strain, 51 reduced order model, 250
Pre Stress, 51 Reference Pressure, 16, 26, 33, 43, 244
Pressure, 25, 27, 75 Reference Temperature, 26, 52, 152
Pressure 1, 322 Reference Wall Temperature, 95
Pressure 2, 322 reinitialization, 185
Pressure i, 27, 86, 315 Reinitialize Field, 204
Pressure Source i, 86 Reinitialize Interval, 188
Principal Direction 2(3), 79 Reinitialize Particles, 202, 207
Procedure, 11, 23, 31, 37, 42, 43, 49, 59, 68, 74, 80, Reinitialize Passive, 188
85, 93, 98, 101, 106, 110, 119, 122, 123, Relative Permeability, 119, 136, 139, 326
127, 128, 132, 133, 136, 137, 140, 141, Relative Permittivity, 106, 132, 136, 149, 152, 167,
143, 149, 152, 156, 162, 170, 175, 181, 249
187–189, 193, 196, 201, 207, 210, 214, Relative Permittivity im, 132
216, 219, 221, 225, 226, 229, 232, 234, Relative Reluctivity, 132
236, 238, 243, 244, 247, 249, 256, 259, Relative Reluctivity im, 132
261, 262, 265, 269, 275, 277, 279, 283, Relaxation Factor, 193, 266
286, 289, 292, 293, 295, 297, 302, 304– Reload Range Maximum, 293
306, 311, 312, 315, 318, 321, 325, 333 Reload Range Minimum, 293
Project To Bottom, 262 Reload Reading Intervals, 294
Project to Everewhere, 263 Reload Solution File, 293
Reload Starting Position, 293

CSC – IT Center for Science

INDEX 344

ReloadData, 293 Save Solid Phase Average, 304

ReloadInput, 295 Save Solid Phase Diff, 305
ReloadSolution, 293 SaveBoundaryValues, 277
Reluctivity, 119, 140 SaveData, 268, 274, 277
Reluctivity Im, 122 SaveGridData, 283
Reset Interval i, 257 SaveLine, 274
Residual Reduction Ratio, 95 SaveMaterials, 277
Residual Water Content, 311 SaveScalars, 268
Resistance, 127 Scalar Field, 171
Restart File, 293 Scalar Field i, 205, 280, 284, 334
Result Variable i, 208 Scalar Potential, 239
Resultant Couple i, 70 ScalarPotentialSolver, 238
Resultant Force i, 69 Scalars File, 272
ResultOutputSolve, 279 Scalars Prefix, 269
Reverse Ordering, 252 scalars: Keyword, 272
Reynolds equation, 39 Schur Complement Convergence Tolerance, 96
Reynolds Pressure Variable Name, 43 secant method, 264
ReynoldsHeatingSolver, 39 Second Kind Basis, 171
ReynoldsSolver, 39 Second Moment of Area 2, 79
Richards equation, 309 Second Moment of Area 3, 79
Richards Flux, 312 Separate Loss Components, 156
Richards Source, 312 Set Constant Weight Sum, 259
RichardsFlux, 309 Shear Modulus, 79
RichardsSolver, 309 Shear Stress Output, 247
Rigid Body, 251 Shear Stress Output File, 247
RigidBodyReduction, 250 Shell Thickness, 68
RigidMeshMapper, 218 ShellSolver, 61
Rotate Elasticity Tensor, 52 Show Norm Index, 270
Rotate Plane, 261 Show Variables, 280
run-time control, 295 signed distance, 185
Runge Kutta, 208 Simplex Relative Length Scale, 266
Simplex Restart Convergence Ratio, 266
Saturated Hydraulic Conductivity, 311 Simplex Restart Interval, 266
Saturated Initial Guess, 311 Simpsons Rule, 156
Saturated Water Content, 311 Simulation, 11, 31, 36, 58, 68, 79, 85, 93, 101, 128,
Save Axis, 275 190, 229, 264, 272, 282, 321, 324
Save Boundaries Only, 281 Simulation Timestep Sizes, 202, 208
Save Bulk Only, 281 Simulation Type, 11, 31, 36, 93, 264
Save Coil Index, 162 Sine Series i, 257
Save Coil Set, 162 Single Precision, 280, 333
Save component results, 271 Skip Butler Volmer, 303, 305
Save Coordinates(n,DIM), 270 Skip Halo Elements, 281
Save Eigenfrequencies, 270 Skip Surface Reconstruction, 69
Save Eigenvalues, 270 Slip Boundary, 95
Save Elemental Fields, 281 Slip Coefficient i, 177
Save Flux, 275 Smart Heater Control, 15
Save Geometry Ids, 280 Smart Heater Control After Tolerance, 12
Save Halo Elements Only, 281 SmitcSolver, 71
Save Isocurves, 275 Soc Model, 306
Save Line, 276 SOC on surface, 306
Save Linear Elements, 281 Solid Phase Diffusion Coefficient, 307
Save Mask, 275 Solid Phase Electrical Conductivity, 307
Save Nodal Fields, 281 Solid Phase Relaxation Factor, 304
Save Points(n), 270 SolidPhaseCons, 300
Save Scalars, 271

CSC – IT Center for Science

INDEX 345

SolidPhasePot, 300 Steinmetz loss model, 154

Solver, 11, 23, 31, 36, 42, 43, 49, 59, 68, 74, 80, 82, Step Size, 266
85, 93, 95, 98, 101, 106, 110, 119, 121, Stoichiometric Limit, 306
122, 127, 128, 132, 133, 136, 137, 140, Stoichiometry at Full Charge, 307
141, 143, 152, 156, 161, 170, 175, 181, Stoichiometry at Nill Charge, 307
187–189, 193, 196, 201, 207, 210, 214, Stokes Stream Function, 230
216, 219, 221, 225, 226, 229, 232, 234, Stokes stream function, 228
236, 238, 243, 244, 247, 248, 251, 256, Stop Cycle i, 257
259, 261, 262, 264, 269, 274, 277, 279, Stop Time i, 257
283, 286, 288, 289, 292, 293, 295, 297, Stop Timestep i, 257
302–306, 311, 312, 315, 318, 321, 324, Strain Load, 51
328, 333 Strain Reduction Operator, 69
SolveWithLinearRestriction, 327 Stream Function First Node, 230
Sound Damping, 86, 98 Stream Function Penalty, 230
Sound Reaction Damping, 98 Stream Function Scaling, 230
Sound Source, 99 Stream Function Shifting, 230
Sound Speed, 86, 98 Stream Function Velocity Variable, 229
Source, 319 Streamline, 228
Source Acceleration, 99 StreamSolver, 228
Source Field, 171 Stress Analysis, 50
Source Gradient Correction, 208 Stress Bodyforce 1, 51
Source Name, 128 Stress Bodyforce 1 im, 51
Specific Heat, 94, 101 Stress Bodyforce 2, 51
Specific Heat Ratio, 16, 26, 33, 43, 94, 102 Stress Bodyforce 2 im, 51
Spring, 52, 60, 75 Stress Bodyforce 3, 51
Spring i, 52, 60, 70, 82 Stress Bodyforce 3 im, 51
SpringAssembler, 81 Stress Bodyforce j, 59
SpringAssembly, 81 Stress Load, 51, 53
Stability Analysis, 50 StressSolve, 46
Stabilization Method, 193 StressSolver, 46
Stabilize, 12, 24, 32, 187 Structure Coupling With Boundary, 315
Start Cycle i, 257 Structure Interface, 87
Start Real Time, 257 StructuredMeshMapper, 221
Start Real Time Fraction, 257 StructureFlowLine, 210, 224
Start Time i, 256 StructureProjectToPlane, 262
Start Timestep i, 257 Study Jli Balance, 306
StatCurrentSolve, 108 substantial surface, 191
StatCurrentSolver, 108 Sum Forces, 247
StatElecBoundary, 146 Surface Charge, 153
StatElecBoundaryCharge, 146 Surface Charge Density, 107
StatElecBoundaryEnergy, 146 surface tension, 187
StatElecBoundaryForce, 146 Surface Tension Coefficient, 27
StatElecBoundarySpring, 146 Surface Tension Expansion Coefficient, 27
StatElecForce, 248 Surface Traction i, 177
StatElecSolve, 104 Surface Traction k, 60
StatElecSolver, 104 Surface Velocity i, 42
Static Conductivity, 119
Static Magnetic Field, 325 Table Format, 204, 283
Statistical Info, 204 Tangent Velocity i, 42
StatMagSolver, 323 Target Field, 217
Steady State Convergence Tolerance, 12, 24, 32, 37, Target Nodes, 239
144, 243, 303 Target Variable, 141, 156, 232, 235, 236, 259, 289,
Stefan Boltzmann, 10 312
Stefan-Boltzmann constant, 10 Target Variable AV, 156
Target Variable Direct, 156

CSC – IT Center for Science

INDEX 346

Target Variable i, 263, 269, 298 Use Tree Gauge, 120

Target Variable i At Bottom, 263 Use Velocity Laplacian, 176
Target Variable i At Middle, 263 Use Wall Distance, 162
Target Variable i Everywhere, 263 User Defined Velocity, 144
TEM Potential, 133 Utilize Previous Solution, 93
TEM Potential im, 133
Temperature, 16, 17 van Genuchten Alpha, 311
Temperature Lower Limit, 15 van Genuchten M, 311
Temperature Upper Limit, 15 van Genuchten N, 311
Tension, 75 Variable, 11, 24, 31, 37, 42, 68, 74, 80, 85, 93, 98,
Tensor Field i, 280 101, 106, 110, 119, 122, 132, 136, 140,
Theta i, 80 141, 143, 152, 156, 171, 175, 181, 187,
Thickness, 75 189, 193, 196, 210, 214, 216, 219, 229,
Time Derivative Order, 98 237, 238, 244, 251, 259, 265, 277, 303–
Time Epsilon, 297 305, 311, 315, 318, 321, 325
Time Filter i, 257 Variable DOFs, 42, 68, 74, 80, 85, 98, 101, 106, 110,
Time Multiplier, 297 143, 152, 171, 176, 181, 193, 196, 229,
Time Name, 297 251, 265, 278, 311, 315, 318, 321
Time Offset, 297 Variable Dofs, 93, 325
Time Order, 207 Variable Global, 265
Time Point, 297 Variable i, 208, 256, 263, 269, 275, 286, 298
Timestep Courant Number, 202 Variable_name, 37, 38
Timestep Distance, 202 Variable_name Gamma, 38
Timestep Intervals, 264 Variable_name Lower Limit, 38
Timestep Size, 202, 207 Variable_name Source, 37
Timestepping Method, 11, 31, 36 Variable_name Upper Limit, 38
TimoshenkoSolver, 77 variational inequality, 192
Top Surface, 223 Varname, 33, 194
Top Surface Level, 222 Varname Accumulation, 194
Top Surface Variable Name, 222 Varname Accumulation Flux i, 194
Torque Axis(3), 124 Varname Diffusion Source, 32
Torque Origin(3), 124 Varname Diffusivity, 33
Torsional Constant, 79 Varname Flux, 33
Transference Number, 307 Varname Maximum Solubility, 33
Translate Before Rotate, 219 Varname Solubility Change Boundary, 34
Transmissivity, 16, 17 Varname Soret Diffusivity, 33
True Flow Line Iterations, 225 Varname: Reaction Coefficient, 211
Varname: Source, 211
U i, 69, 80 Varname: Time Derivative Coefficient, 211
UMAT Subroutine, 58 Vector Field i, 205, 280, 284, 334
Unit Charge, 152 VectorHelmholtz, 130
Update Gebhardt Factors, 13 VectorHelmholtzCalcFields, 130
Update Radiator Factors, 13 VectorHelmholtzSolver, 130
Update Transient System, 50 Velocity 1, 167
Update View Factors, 13 Velocity 2, 167
Use Average Cell Voltage, 306 Velocity 3, 167
Use Density, 85 Velocity Assembly, 96
Use Effective Diffusion, 305 Velocity Condition Variable Name, 203
Use Lagrange Gauge, 120 Velocity Convergence Tolerance, 96
Use Linear Elements, 193 Velocity Field Name, 247
Use Mean Flux, 303 Velocity Gradient Correction, 203, 208
Use Piola Transform, 119, 132, 136 Velocity i, 25, 27
Use Solid Phase Relaxation, 305 Velocity Implicitness, 193
Use Time Average Diffusion, 303, 304, 306 Velocity Initialization Method, 201, 207
Use Time Average Flux, 303 Velocity Variable Name, 85, 203, 207, 225, 262

CSC – IT Center for Science

INDEX 347

view factors, 13 Z Epsilon, 297

View Factors Fixed After Iterations, 13 Z Name, 297
View Factors Fixed Tolerance, 14 Zeta Potential, 167
View Factors Geometry Tolerance, 13
Viewfactor Area Tolerance, 14
Viewfactor Combine Elements, 14
Viewfactor Divide, 14
Viewfactor Factor Tolerance, 15
Viewfactor Number Of Rays, 14
Viewfactor Symmetry x, 14
Viscosity, 16, 26, 42, 94, 102, 167, 175, 181, 190,
247
Viscosity Difference, 26, 190
Viscosity Exponent, 26
Viscosity Model, 26, 42, 175, 190
Viscosity Temp Exp, 27
Viscosity Temp Offset, 27
Viscosity Temp Ref, 27
Viscosity Transition, 26
Visualize Node Index, 305
Volume Permutation, 261
VorticitySolver, 234
VTI, 283
Vti Format, 283
VTK, 279
Vtk Format, 279
VTU, 279, 283
Vtu Format, 204, 279, 283
Vtu Part Collection, 281
Vtu Time Collection, 281
vtu: Keyword, 282

Wall Law, 28
Wall Particle Bounciness, 204
Wall Particle Collision, 205
Wall Particle Radius, 204
Wall Particle Spring, 204
Water Content, 311
Wave Flux 1,2, 86
Wave Impedance 1,2, 86
WaveFunctionSolver, 329
WaveSolver, 97
Weight Variable, 259
WhitneyAVHarmonicSolver, 111
WhitneyAVSolver, 111
Wnodal, 315

X Epsilon, 297
X Name, 297
XdmfWriter, 333

Y Epsilon, 297
Y Name, 297
Yasuda Exponent, 27
Youngs Modulus, 51, 58, 68, 75, 79, 214, 217

CSC – IT Center for Science