Open FOAM
Open FOAM
Open FOAM
In this article the principles of the field operation and manipulation ~FOAM! C11 class library for
continuum mechanics are outlined. Our intention is to make it as easy as possible to develop
reliable and efficient computational continuum-mechanics codes: this is achieved by making the
top-level syntax of the code as close as possible to conventional mathematical notation for tensors
and partial differential equations. Object-orientation techniques enable the creation of data types
that closely mimic those of continuum mechanics, and the operator overloading possible in C11
allows normal mathematical symbols to be used for the basic operations. As an example, the
implementation of various types of turbulence modeling in a FOAM computational-fluid-dynamics
code is discussed, and calculations performed on a standard test case, that of flow around a square
prism, are presented. To demonstrate the flexibility of the FOAM library, codes for solving
structures and magnetohydrodynamics are also presented with appropriate test case results given.
1998 American Institute of Physics. @S0894-1866~98!01906-3#
INTRODUCTION
where
Computational continuum mechanics ~CCM! is the simulation of continua using computers. Fluid dynamics is a significant branch of continuum mechanics and covers a variety of cases, including compressible, incompressible,
multiphase, and free-surface flows, as well as flows involving further physics such as chemical reactions, species
transport, phase changes, and electromagnetic effects. All
these flows can be described by systems of linked partial
differential equations of the form
]r Q
1~ r U ^ Q! 2r DQ5S p Q1S q ,
]t
~1!
]U
1
1~ U ^ U! 22 n D52 p,
]t
r
a!
620
~2!
D5 21 ~ U1UT ! .
~3!
~4!
621
to a mesh class fvMesh ~see below!, these classes contain boundary information, previous time steps necessary
for the temporal discretization, and dimension set information. All seven base SI dimensions are stored, and all algebraic expressions implemented above this level are dimensionally checked at execution. It is therefore impossible to
execute a dimensionally incorrect expression in FOAM.
This has no significant runtime penalty whatsoever: typical
fields have 104 105 tensors in them, and dimension checking is done once per field operation.
Currently two types of tensor-derivative classes are
implemented in FOAM: finiteVolumeCalculus or fvc, which
performs an explicit evaluation from predetermined data
and
returns
a
geometric
tensor
field,
and
finiteVolumeMethod or fvm, which returns a matrix representation of the operation, which can be solved to advance
the dependent variable~s! by a time step. fvm will be described in more detail in Sec. I B. The fvc class has no
private data and merely implements static member functions that map from one tensor field to another. Use of a
static class in this manner mimics the concept of a
namespace which has recently been introduced into C11,
and by implementing the operations in this manner, a clear
distinction is drawn between the data and the operations on
the data. The member functions of this class implement the
finite-volume equivalent of various differential operators,
for example, the expression
vorticity 5 0.5*fvc::curl(U);
scheme to use ~in this case Euler implicit!. Several temporal differencing schemes are available, with a default corresponding to the scheme that gets the most use, in this
case, backward differencing. Other selection methods are
possible, but this one is the simplest.
B. Implementation of partial-differential-equation classes
The fvc methods correspond directly to tensor differential
operators, since they map tensor fields to tensor fields.
CCM requires the solution of partial differential equations,
which is accomplished by converting them into systems of
difference equations by linearizing them and applying discretization procedures. The resulting matrices are inverted
using a suitable matrix solver.
The differential operators , , and 3 lead to
sparse matrices, which for unstructured meshes have a
complex structure requiring indirect addressing and appropriate solvers. FOAM currently uses the conjugate-gradient
method,19 with incomplete Cholensky preconditioning
~ICCG!,20 to solve symmetric matrices. For asymmetric
matrices the Bi-CGSTAB method21 is used. The matrix inversion is implemented using face addressing throughout,15
a method in which elements of the matrix are indexed according to which cell face they are associated with. Both
transient and steady-state solutions of the equation systems
are obtained by time-marching, with the time step being
selected to guarantee diagonal dominance of the matrices,
as required by the solvers.
In order that standard mathematical notation can be
used to create matrix representations of a differential equation, classes of equation object called fvMatrixScalar,
fvMatrixVector, etc., are defined to handle addressing issues,
storage allocation, solver choice, and the solution. These
classes store the matrices that represent the equations. The
standard mathematical operators 1 and 2 are overloaded
to add and subtract matrix objects. In addition, all the tensorial derivatives ] / ] t, , 3, etc., are implemented as
member functions of a class finiteVolumeMethod ~abbreviated to fvm!, which construct appropriate matrices using the
finite-volume discretization. Numerical considerations are
relevant in deciding the exact form of many of the member
functions. For instance, in the FVM, divergence terms are
represented by surface integrals over the control volumes
d V i . Thus the divergence function call is div(phi,Q), where
phi is the flux, a field whose values are recorded on the cell
faces, and Q is the quantity being transported by the flux,
and is a field whose values are on the cell centers. For this
reason, this operation cannot be represented as a function
call of the form div(phi*Q). Again, the Laplacian operator is
implemented as a single separate call rather than as calls to
div and grad, since its numerical representation is different.
Various forms of source term are also implemented. A
source term can be explicit, in which case it is a special
kind of equation object with entries only in the source vector y, or it can be made implicit, with entries in the matrix
M. In Eq. ~1! these are the terms S q and S p Q, respectively.
Construction of an explicit source term is provided for by
further overloading 1 ~and 2! to provide operations such
as fvm1volScalarField. Construction of an implicit source
is arranged by providing a function Sp(a,Q), thus specifying the dependent variable Q to be solved for.
Thus it is possible to build up the matrix system appropriate to any equation by summing the individual terms
in the equation. As an example, consider the mass conservation equation ]r / ] t1( f )50, where f 5 r U. The matrix system can be assembled by writing
fvMatrixScalar rhoEq
(
fvm::ddt(rho) 1 fvc::div(phi)
);
to advance the value of r by one timestep. Where necessary, the solution tolerance can be explicitly specified. For
completeness, the operation 55 is defined to represent
mathematical equality between two sides of an equation.
This operator is here entirely for stylistic reasons, since the
code automatically rearranges the equation ~all implicit
terms go into the matrix, and all explicit terms contribute to
the source vector!. In order for this to be possible, the operator chosen must have the lowest priority, which is why
55 was used; this also emphasizes that this represents
equality of the equation, not assignment.
C. Mesh topology and boundary conditions
Geometric information is contributed to the geometric
fields by the class fvMesh, which consists of a list of vertices, a list of internal cells, and a list of boundary patches
~which in turn are lists of cell faces!. The vertices specify
the mesh geometry, whereas the topology of any cellbe it
one dimension ~1D! ~a line!, two dimensions ~2D! ~a face!,
or three dimensions ~3D! ~a cell!is specified as an ordered list of the indices together with a shape primitive
describing the relationship between the ordering in the list
and the vertices in the shape. These primitive shapes are
defined at run time, and so the range of primitive shapes
can be extended with ease, although the 3D set tetrahedron
~four vertices!, pyramid ~five vertices!, prism ~six vertices!,
and hexahedron ~eight vertices! cover most eventualities.
In addition, each n-dimensional primitive shape knows
about its decomposition into (n21)-dimensional shapes,
which are used in the creation of addressing lists as, for
example, cell-to-cell connectivity.
Boundary conditions are regarded as an integral part
of the field rather than as an added extra. fvMesh incorporates a set of patches that define the exterior boundary ] D
of the domain. Every patch carries a boundary condition,
which is dealt with by every fvm operator in an appropriate
manner. Different classes of patch treat calculated, fixed
value, fixed gradient, zero gradient, symmetry, cyclic, and
other boundary conditions, all of which are derived from a
base class patchField. All boundary conditions have to provide the same types of information, that is, that they have
the same interface but different implementations. This is
therefore a good example of polymorphism within the
code. From these basic elements, boundaries suitable for
inlets, outlets, walls, etc., can be devised for each specific
situation. An additional patchField, processor is also available. Parallelization of FOAM is via domain decomposiCOMPUTERS IN PHYSICS, VOL. 12, NO. 6, NOV/DEC 1998
623
D. An example: icoFoam
As an example, the following is the main part of a code,
icoFoam, which solves the incompressible NavierStokes
Eqs. ~2!. The predictorcorrector PISO method,22,23 in
which the pressure and velocity fields are decoupled and
solved iteratively, is as follows.
~1! An initial guess for the pressure field is made ~in fact,
the pressure solution from the previous time step is
used! and the momentum equation is solved to a predefined tolerance to give an approximate velocity field.
~2! The pressure Poisson equation is then formulated with
the divergence of the partial velocity flux as a source
term and solved to give a new estimate of the pressure
field. A new set of conservative fluxes is obtained from
the pressure equation.
~3! The corrected pressure field is used in an explicit correction to the velocity field.
Steps ~2! and ~3! can be iterated as many times as are
necessary to reach a converged solution. Usually two PISO
correctors are sufficient for each time step, although this is
dependent on the time step selected, which in turn depends
on the temporal accuracy required.
for(runTime11; !runTime.end( ); runTime11)
$
Info ! Time 5 ! runTime.curTime( ) nl ! endl;
fvMatrixVector Ueqn
(
fvm::ddt(U)
1fvm::div(phi, U)
2fvm::laplacian(nu, U)
);
solve(Ueqn 55 2 fvc::grad(p));
// --- PISO loop
for (int corr 5 0; corr,nCorr; corr11)
$
phi 5 Interpolate(Ueqn.H( )/Ueqn.A( )) & mesh.areas( );
fvMatrixScalar peqn
(
fvm::laplacian (1.0/Ueqn.A( ), p) 55 fvc::div(phi)
624
);
peqn.setReference(0, 0.0);
peqn.solve( );
phi 2 5 peqn.flux( );
U 5 (Ueqn.H( ) 2 fvc::grad(p))/Ueqn.A( );
U.correctBoundaryConditions( );
%
%
]U
1
1~ U ^ U! 1R22 n D52 p
]t
r
~5!
where R5U8 ^ U8 is the Reynolds stress tensor. R is commonly modeled as a turbulent viscosity n t times U, and n t
evaluated from a hierarchy of equations derived from nth
order moments of the NavierStokes equation ~NSE!.
These are also commonly referred to as algebraic stress
models. As an alternative, dynamic equations for R can be
formulated; these contain terms including triple correlations
of the fluctuating velocity, which must be modeled. Such
models, known as Reynolds Stress ~RS! models, involve
much more effort in their solution, since, although R is a
symmetric tensor, it still has six independent components to
be solved for, and the equation set is even stiffer than that
for the standard k2 e model. A completely different approach is that of large-eddy simulation ~LES!, in which the
division is by scale via a filtering operation that can be
conveniently represented as a convolution between the dependent field variable and a filter function with particular
properties. The filtered form of the NS equations is
U50,
1
]U
1~ U ^ U! 1B22 n D52 p ,
]t
r
~6!
~7!
P k 52 n t u U u 2 ,
~8!
]e
nt
e
e2
1~ U e ! 2
e 5C 1 e P k 2C 2 e ,
]t
se
k
k
where P k is the production rate of k and s k , s k , C 1 e , and
C 2 e are model coefficients. Below is an example of how
this can be implemented in FOAM.
// Turbulent kinetic energy production
volScalarField Pk 5 2*nut*magSqr(fvc::grad(U));
// Turbulent kinetic energy equation
solve
(
fvm::ddt(k)
1 fvm::div(phi, k)
2 fvm::laplacian(nu/sigmaK, k)
55
Pk
2 fvm::Sp(epsilon/k, k)
);
// Dissipation equation
solve
(
fvm::ddt(epsilon)
1 fvm::div(phi, epsilon)
2 fvm::laplacian(nu/sigmalEps, epsilon)
55
C1*Pk*epsilon/k
2 fvm::Sp(C2*epsilon/k, Epsilon)
);
where turbulence is the RAS-model object. The contribution of the turbulence model to the flow is via the member
function nuEff(), which returns n 1 n t , where n is the laminar viscosity. As an example, the standard k2 e model24
requires the solution of the following equations for turbulent kinetic energy k and dissipation rate e:
]k
nt
1~ U k ! 2
k5 P k 2 e ,
]t
sk
Figure 1. Virtual class hierarchy for LES SGS models. The solid lines
represent the inheritance hierarchy.
B. LES modeling
The range of possible LES models is, if anything, even
larger than the range of RAS models, and a comparison is
made between a large number of different models in Ref.
17. Once again, the models can be incorporated directly
into the momentum equation, or a virtual class hierarchy
may be constructed in order to make the models run time
selectable. Unlike the flat hierarchy used for the RAS models, in this case a three-level system is used ~Fig. 1!. The
various LES models can be grouped into sets that share
common characteristics, and it is natural to construct the
class hierarchy to match, using derivation to represent the
COMPUTERS IN PHYSICS, VOL. 12, NO. 6, NOV/DEC 1998
625
~9!
1
3
I tr ~ P!# . ~10!
~11!
These models do not include the effects of dissipation correctly and are usually combined with an eddy-viscosity
type model to give a mixed model.32
The FOAM LES models class hierarchy is based on
the model relationships described; see Fig. 1. At the base is
a virtual base class isoLESmodel. Derived from this are
intermediate classes isoGenEddyVisc, isoGenSGSStress,
and isoGenScaleSimilarity, which implement Eqs. ~9!, ~10!,
and ~11!, respectively. Finally details of the models are
implemented in the highest-level classes. For example, the
classes derived from isoGenEddyVisc calculate the value
of n k used in Eq. ~9!, while those derived from
isoGenSGSStress implement the modeling of Eq. ~10!.
isoMixedSmagorinsky is a mixture of a scale-similarity and
an eddy-viscosity model, and so multiple inheritance is
used to represent this relationship.
626
LES are three-dimensional, and thus a semiartificial freeslip condition, Uex 50 and (Uek )ek 50, k5y, z, is applied on the planes xI e3 50 and 4h. For the top and bottom
boundaries, x/h567h, slip conditions are applied while
no-slip conditions are used for the boundary condition on
the prism. The computational domain is discretized using a
250,000-cell grid.
Results are shown in Fig. 3 from LES using the
Smagorinsky27 and one-equation eddy-viscosity29 models,
from RS using the LaunderGibson Reynolds stress
model,35 and the standard and RNG36 k2 e models. The
function of the comparison is to illustrate the flexibility of
FOAM for model implementation rather than to analyze the
merits of the various models; a detailed analysis of the
models will be described elsewhere. Hence, only a representative set of results is presented, these being the timeaveraged velocities U ~streamwise, that is, along the x axis!
and V ~in the y direction!. There is a significant and unexplained discrepancy between the Lyn and Durao data for
the U component on the center line, with the Lyn data
627
] 2D
5@ m ~ D1DT ! 1lI tr~ D!# ,
]t2
~12!
Note the split into implicit fvm and explicit fvc parts. This
particular rearrangement guarantees diagonal dominance of
the matrix and good convergence behavior. Iteration over
the equation is required every time step for transient calculation in order to converge over the explicit contribution.
For steady-state calculation, the inner iteration is unnecessary.
Figure 5 shows the computational domain for the calculation of the stress field in a 2-D square plate with a
circular hole in it. The plate is being stretched in one direction by uniform traction of 104 Pa. This is a relatively
small load, and so the problem can be considered isothermal, linear, elastic, and steady-state. Since the plate is twodimensional, the assumption of plane stress is made. The
hole is central to the plate, and so only one quarter of the
domain need be simulated, symmetry boundaries being applied on the left and bottom. The mesh for this calculation
contained 15,000 cells. The top boundary, together with the
hole, are given zero-traction boundary conditions, while the
right boundary has fixed traction of 104 Pa. The results are
shown in Fig. 6 in the form of contours of s xx , s xy , and
s y y . Apart from a small region in the plates center, the
agreement is close. The error is in the region where several
628
3H5J1
]D
,
]t
B50,
3E52
]B
,
]t
~14!
J50,
]U
1
B2
1~ U ^ U! 2n U52 p1
]t
r
2m
1
~15!
1
~ B ^ B! .
rm
~16!
Also,
3H5J5 s ~ E1U3B! ,
~17!
Figure 7. Variation of stress with angle around the hole. Curves are
calculated from the analytical solution, while the symbols represent profiles extracted from the boundary field of the FOAM computation. Q
5 90 is the x direction (the direction of applied strain).
1
]B
1~ U ^ B2B ^ U! 2
B50.
]t
sm
~18!
629
Figure 9. Comparison between computed profiles (symbols) and analytical profiles (solid lines) for MHD flow in a channel at Hartmann numbers M
5 1, 5, and 20. Shown on the left is the normalized velocity as a function of distance across the duct, and on the right is the nondimensionalized magnetic
field component parallel to the flow.
U cosh~ y 0 / d ! 2cosh~ y/ d !
,
5
cosh~ y 0 / d ! 21
v0
B
v 0 m Asnr
52
~19!
d5
1
B0
rn
,
s
In essence, FOAM is a high-level language, a CCM metalanguage, that closely parallels the mathematical description of continuum mechanics. As well as simplifying the
implementation of new models, this makes checking the
modeling more straightforward. This aspect is enhanced by
the inclusion of features such as automatic dimension
checking of operations. In addition to this, use of OOP
methodology has enabled the dissociation of different levels of the code, thus minimizing unwanted interaction, and
permitting research into the numerics ~differencing
schemes and matrix-inversion techniques! to be largely divorced from that of modeling.
A number of key properties of OOP that have enabled
the development of FOAM are the following.
~1! The use of data encapsulation and data hiding enables
lower-level details of the code, such as the implementation of the basic tensorial classes, to be hidden from
view at the higher levels. This enables a user to deal
only with aspects of the code relevant to the level of
coding that they are involved in; for example, a new
SGS model can be implemented without the need to
access ~or even know about! the details of how the
components of a tensor are being stored. Since a tensor
is not simply a group of components but is a mathematical object in its own right, this is also aesthetically pleasing.
~2! Operator overloading allows the syntax of the CCM
metalanguage to closely resemble that of conventional
mathematics. This enhances legibility at high levels in
the code. Although this approach increases the number
of copying operations somewhat and involves more
temporary storage than would be the case for a more
traditional code, this has not been found to be a critical
cost, and is more than compensated for by the ease of
use of the resulting code.
~3! Function overriding and the use of virtual class hierarchies enable new low-level algorithms to be included in
a manner that can be entirely transparent at higher levels. For example, constructing and implementing new
4.
5.
6.
7.
8.
9.
10.
11.
12.
13.
14.
15.
16.
17.
18.
19.
20.
21.
22.
23.
24.
25.
26.
27.
28.
29.
30.
31.
32.
33.
34.
35.
36.
37.
38.
tional Fluid Dynamics: The Finite Volume Method ~Longman Scientific and Technical, 1995!.
B. W. R. Forde, R. O. Foschi, and S. F. Stiemer, Comput. Struct. 34,
355 ~1990!.
B. Stroustrup, Proceedings of the 1st European Software Festival,
1991.
B. Stroustrup, The C11 Programming Language, 3rd ed. ~Addison
Wesley, Reading, MA, 1997!.
B. Stroustrup, OOPS Messenger, 1995, an addendum to the OOPSLA
95 Proceedings.
J. R. Cary, S. G. Shasharina, J. C. Cummings, J. V. W. Reynders, and
P. J. Hinker, Comput. Phys. Commun. ~submitted!; available at http://
jove.colorado.edu/ cary/CompCPP F90SciOOP.html.
Y. Dubois-Pe`lerin and Th. Zimmermann, Comput. Methods Appl.
Mech. Eng. 108, 165 ~1993!.
J-L. Liu, I.-J. Lin, M.-Z. Shih, R.-C. Chen, and M.-C. Hseih, Appl.
Numer. Math. 21, 439 ~1996!.
Th. Zimmermann, Y. Dubois-Pe`lerin, and P. Bomme, Comput. Methods Appl. Mech. Eng. 98, 291 ~1992!.
L. Machiels and M. O. Deville, ACM Trans. Math. Softw. 23, 32
~1997!.
Th. Zimmermann and D. Eyheramendy, Comput. Methods Appl.
Mech. Eng. 132, 259 ~1996!.
D. Eyheramendy and Th. Zimmermann, Comput. Methods Appl.
Mech. Eng. 132, 277 ~1996!.
H. Jasak, Ph.D. thesis, Imperial College, 1996.
O. Ubbink, Ph.D. thesis, Imperial College, 1997.
C. Fureby, G. Tabor, H. Weller, and A. D. Gosman, Phys. Fluids 9,
1416 ~1997!.
S. Meyer, Effective C11 ~AddisonWesley, Reading, MA, 1992!.
M. R. Hestens and E. L. Steifel, J. Res. 29, 409 ~1952!.
D. A. H. Jacobs, Technical report, Central Electricity Research Laboratories, 1980.
H. A. van der Vorst, SIAM J. Comput. 13, 631 ~1992!.
R. I. Issa, J. Comput. Phys. 62, 40 ~1986!.
R. I. Issa, A. D. Gosman, and A. P. Watkins, J. Comput. Phys. 62, 66
~1986!.
B. E. Launder and D. B. Spalding, Comput. Methods Appl. Mech.
Eng. 3, 269 ~1974!.
V. C. Patel, W. Rodi, and G. Scheuerer, AIAA J. 23, 1308 ~1985!.
B. E. Launder, G. J. Reece, and W. Rodi, Progress in the development of a Reynolds-stress Turbulence Closure, J. Fluid Mech. 68,
537 ~1975!.
J. Smagorinsky, Mon. Weather Rev. 91, 99 ~1963!.
U. Schumann, J. Comput. Phys. 18, 376 ~1975!.
A. Yoshizawa, Phys. Fluids A 29, 2152 ~1986!.
J. W. Deardorff, Trans. ASME, Ser. I: J. Fluids Eng. 156, 55 ~1973!.
J. Bardina, J. H. Ferziger, and W. C. Reynolds, Technical Report No.
TF-19, Stanford University, 1983.
G. Erlebacher, M. Y. Hussaini, C. G. Speziale, and T. A. Zang, J.
Fluid Mech. 238, 155 ~1992!.
D. Lyn, S. Einav, W. Rodi, and J. Park, Technical report, Karlsruhe
University, 1994.
D. F. G. Durao, M. V. Heitor, and J. C. F. Pereira, Exp. Fluids 6, 298
~1988!.
M. M. Gibson and B. E. Launder, J. Fluid Mech. 86, 491 ~1978!.
V. Yakhot, S. A. Orszag, S. Thangam, T. B. Gatski, and C. G. Speziale, Phys. Fluids A 4, 1510 ~1992!.
I. Demirdzic and S. Muzaferija, Int. J. Numer. Methods Eng. 37, 3751
~1994!.
I. Demirdzic and S. Muzaferija, Comput. Methods Appl. Mech. Eng.
125, 235 ~1995!.
631