LBflow: An extensible lattice Boltzmann framework for the simulation of ...

This article appeared in a journal published by Elsevier. The attached copy is furnished to the author for internal non-commercial research and education use, including for instruction at the authors institution and sharing with colleagues. Other uses, including reproduction and distribution, or selling or licensing copies, or posting to personal, institutional or third party websites are prohibited. In most cases authors are permitted to post their version of the article (e.g. in Word or Tex form) to their personal website or institutional repository. Authors requiring further information regarding Elsevier’s archiving and manuscript policies are encouraged to visit: http://www.elsevier.com/copyright

Author's personal copy ARTICLE IN PRESS Computers & Geosciences 36 (2010) 115–122

Contents lists available at ScienceDirect

Computers & Geosciences journal homepage: www.elsevier.com/locate/cageo

LBflow: An extensible lattice Boltzmann framework for the simulation of geophysical flows. Part I: theory and implementation$ E.W. Llewellin Department of Earth Sciences, Durham University, DH1 3LE, UK

a r t i c l e in fo

abstract

Article history: Received 24 October 2006 Received in revised form 20 July 2009 Accepted 18 August 2009

This article presents LBflow, a flexible, extensible implementation of the lattice Boltzmann method. The code has been developed with geophysical applications in mind, and is designed to be usable by those with no specialist computational fluid dynamics expertise. LBflow provides a ‘virtual laboratory’ which can be used, rapidly and easily, to obtain accurate flow data for the geometrically complex, threedimensional flows that abound in geophysical systems. Parameters can be ‘steered’ by the user at runtime to allow efficient and intuitive exploration of parameter space. LBflow is written in object-oriented C++ and adopts a modular approach. Lattice Boltzmann algorithms for distinct classes of material are encoded in separate modules, which implement a standard interface, and which are linked to LBflow dynamically at runtime. This allows users with programming skill and expertise in the lattice Boltzmann method to create and share new LBflow modules, extending functionality. A companion application, LBview, provides a graphical user interface to LBflow and renders a user-configurable visualization of the output. LBflow’s output can be piped directly to LBview allowing realtime visualization of steered flow. LBview also facilitates analysis of the data generated by LBflow. This article presents an overview of the theory of the lattice Boltzmann method and describes the design and operation of LBflow. The companion paper, ‘Part II’, describes the practical usage of LBflow and presents detailed validation of its accuracy for a variety of flows. & 2009 Elsevier Ltd. All rights reserved.

Keywords: Lattice Boltzmann method Geophysical fluid dynamics Flow simulation Flow visualization Computational steering

1. Introduction Over the last 20 years, a new class of computational fluid dynamic models has emerged, based upon the lattice Boltzmann equations (McNamara and Zanetti, 1988; Higuera and Jimenez, 1989; Higuera et al., 1989; Benzi et al., 1992; see Succi, 2001, for an overview). Intense research effort has been expended on the development of lattice Boltzmann algorithms with the result that a large inventory of model types is now available to the modeller. Algorithms exist for the simulation of single phase Newtonian and non-Newtonian fluids, for two-phase liquid–gas and liquid–solid mixtures and for many more-esoteric materials. Depending on the algorithm, creeping, inertial or turbulent flows may be simulated. Succi (2001) and Yu et al. (2003) provide accessible overviews. In general, the lattice Boltzmann method (introduced in Section 2) is easier to implement than conventional computational fluid dynamic techniques, is highly amenable to parallelization and can deal with arbitrarily complex flow geometries without significant penalty. These attributes, combined with the flexibility of the lattice Boltzmann method, make it suitable for the

investigation of a wide range of geophysical flow problems. The method is particularly well-suited to problems involving flow through complex geometries (e.g. permeating groundwater flow, melt segregation) and flows in which multiphase interactions are of interest (e.g. particle laden flows, bubble suspensions). Sophisticated lattice Boltzmann research-code implementations are available (e.g. PELABS: Dupuis and Chopard, 2000; and OpenLB1), however, since these are typically organized as libraries, their use requires programming expertise and time investment to learn the application programming interface. Commercial codes are also available. Section 3 of this article introduces LBflow, an extensible lattice Boltzmann implementation designed with geophysical applications in mind. LBflow comprises a core executable, which controls simulation flow and lattice operations, and a suite of ‘physics modules’ which provide implementations of various lattice Boltzmann algorithms for different materials. The simulation parameters and required outputs are specified by the user via a plain-text simulation file, which is parsed by the core executable. This allows sophisticated numerical experiments to be conducted

$

Code available from server at http://www.dur.ac.uk/ed.llewellin/lbflow/ E-mail address: [email protected]

0098-3004/$ - see front matter & 2009 Elsevier Ltd. All rights reserved. doi:10.1016/j.cageo.2009.08.004

1

http://www.openlb.org/

Author's personal copy ARTICLE IN PRESS 116

E.W. Llewellin / Computers & Geosciences 36 (2010) 115–122

by those without programming experience. LBflow and its modules are written using object-oriented C++ . Physics modules are called dynamically at runtime by the core executable and implement a specified interface, allowing users with programming experience to create further modules, adding functionality. Philosophically, LBflow is designed to be used as a ‘virtual laboratory’ in which complex natural flows can be simulated and analysed by those without specialist computational fluid dynamics training. Several features of LBflow exemplify this approach: output from LBflow can be visualized and analysed through a companion application, LBview, which has an intuitive graphical user interface; certain key parameters can be ‘steered’ by the user during execution and the results can be piped dynamically through LBview, allowing interactive exploration of parameter space; LBflow is ‘dimensional’, i.e. parameters are specified, and results are presented, in SI units. This article is Part I of a two-part series. Part II (Llewellin, 2009) describes the practical usage of LBflow and presents detailed validation of the code against analytical solutions and experimental data for a range of three-dimensional flows. In both parts, in line with LBflow’s experimental philosophy, considerable attention is paid to the quantification of errors and to practicalities, such as obtaining a pragmatic balance between accuracy, resolution and system resources.

2. The lattice Boltzmann method Historically, the lattice Boltzmann method developed heuristically from attempts to improve the performance of the lattice gas cellular automaton (McNamara and Zanetti, 1988; Higuera and Jimenez, 1989). Subsequent analysis has put the lattice Boltzmann method on a sound theoretical footing by showing that, providing that certain conditions are met, the lattice Boltzmann equations are formally equivalent to the Navier–Stokes equations, discretized in time and space (He and Luo, 1997; Chen and Doolen, 1998). The literature contains several excellent and rigorous theoretical treatments of the lattice Boltzmann method (see earlier references) which this section does not aim to duplicate. Rather, the relevant equations are presented and their physical meaning is discussed, echoing the method’s heuristic origins. According to the kinetic theory of gases, a control volume of gas, with spatial dimensions larger than the molecular mean free path and smaller than the hydrodynamic lengthscale of the fluid, contains a large number of molecules moving in all directions and at all velocities and exchanging momentum through collisions with one another. The probability that a molecule within this volume, centred on position r, at time t, has velocity v, is described by the velocity distribution function f (r; v; t). Collisions between the molecules act rapidly to bring the velocity distribution function to an equilibrium described by the Maxwell–Boltzmann distribution: " # 2 r (v u) ; (1) exp f eq ¼ 3=2 2RT (2pRT) where r is the gas density, R the universal gas constant, T the absolute temperature of the gas and u is the bulk velocity of the gas packet (u ¼ 0 for a gas at rest). For each orthogonal component a of velocity, the Maxwell–Boltzmann distribution is a normal distribution about ua . Note that the bulk velocity of the gas must be much smaller than the root mean square velocity of the molecules. Fig. 1a and b show, schematically, the Maxwell– Boltzmann distribution of velocities for a point in a twodimensional flow around a cylinder; note that Fig. 1b shows the distribution in velocity space.

Fig. 1. Diagrammatic representation of velocity distribution function for a small packet of flowing fluid. (a) Two-dimensional flow around a cylinder; (b) velocity distribution, in velocity space, for packet of fluid with mean velocity u; (c) same distribution discretized onto a two-dimensional, nine-velocity lattice.

The lattice Boltzmann method discretizes space into a regular lattice of nodes with spacing Dx. The lattice must have a high degree of symmetry and, typically, lower-dimension projections of a four-dimensional face-centred hypercubic lattice are used. All of the fluid molecules within a volume Dx3 centred on a node are treated as if they exist at the node. Each node, therefore, is analogous to the control volume discussed above, and has a velocity distribution associated with it. Since time is also discretized, into timesteps of duration Dt, velocity space is also discrete. It is important to note that there are two distinct sets of units that are used in the numerical implementation of the lattice Boltzmann method: physical units and simulation units (denoted by the symbol ‘ ^ ’ above a quantity). For simplicity the simulation units are usually chosen as Dx^ ¼ 1 and Dt^ ¼ 1. Distances in the simulation are, therefore, represented in units of lattice-spacings and times in units of timesteps. The mapping between simulation and physical units, and vice versa, is discussed later in this section. In a three-dimensional lattice, each node has 26 immediate neighbours. If we impose the constraint that information may only propagate from a node to its nearest neighbours in a single timestep, this gives 27 ‘allowed’ velocities (including a ‘rest velocity’ for stationary molecules). The velocities are denoted e^ i (i ¼ 0; . . . ; n); where n is the number of allowed velocities. On a lattice, the continuous velocity distribution f (r; v; t) can be discretized into components fi , which can be thought of as the fraction of the total mass of fluid at a node that is moving with each of the allowed velocities. Fig. 1c shows the discretization of the continuous Maxwell–Boltzmann distribution of velocities for a two-dimensional model, with nine allowed velocities. Although each node in a three-dimensional lattice has 26 nearest neighbours, the most commonly used three-dimensional lattice Boltzmann models have only 15 or 19 allowed velocities. Fig. 2 shows the allowed velocities for a so-called D3 Q 15 lattice (three-dimensional, 15 velocity), which is used by LBflow. The 15 velocities are: e^ 0 ¼ ½0; 0; 0 e^ 1 ¼ ½1; 0; 0 e^ 2 ¼ ½1; 0; 0 e^ 3 ¼ ½0; 1; 0 e^ 4 ¼ ½0; 1; 0

e^ 5 ¼ ½0; 0; 1 e^ 6 ¼ ½0; 0; 1 e^ 7 ¼ ½1; 1; 1

e^ 10 ¼ ½1; 1; 1 e^ 11 ¼ ½1; 1; 1 e^ 12 ¼ ½1; 1; 1

e^ 8 ¼ ½1; 1; 1 e^ 9 ¼ ½1; 1; 1

e^ 13 ¼ ½1; 1; 1 e^ 14 ¼ ½1; 1; 1:

(2)

Author's personal copy ARTICLE IN PRESS E.W. Llewellin / Computers & Geosciences 36 (2010) 115–122

Post-propagation, the incoming distribution fi is adjusted towards the equilibrium distribution fieq . Physically, this process is analogous to the redistribution of momentum that occurs when molecules collide with one another and which gives rise to viscosity. The degree of this adjustment is controlled by the dimensionless relaxation parameter t. After collision, time is ^ the new fractions fi are propagated to the incremented by Dt, neighbour node in the direction of velocity e^ i and the procedure repeats. Both the propagation and collision steps are encapsulated in the lattice Boltzmann equation:

9 11 5 7

2 3

13 0

4

14 1

8 z

^ f eq (r^ ; t) ^ f (r^ ; t) i ^ t^ þ Dt) ^ ¼ fi (r^ ; t) ^ i : fi (r^ þ e^ i Dt; |fflfflfflfflfflfflfflfflfflfflfflfflfflfflffl{zfflfflfflfflfflfflfflfflfflfflfflfflfflfflffl} |fflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflffl{zfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflfflffl} t

6

x

propagation

12

y

117

10

Fig. 2. D3 Q 15 lattice. Model has one rest direction (0), six orthogonal directions (1 6) and eight diagonal directions (7 14).

The lattice velocities e^ i are expressed in simulation units, hence, a velocity of ½1; 0; 0 moves one lattice-spacing in the x-direction each timestep. 2.1. The lattice Boltzmann algorithm At each node, at the beginning of each timestep, each fraction of mass fi propagates to the neighbour node in the direction of velocity e^ i (or remains at the current node for f0 ). Postpropagation, therefore, each node has a new set of fi which have arrived from the neighbour nodes. The new total density at each node is given by the sum of the fractional masses arriving at the node: X ^ ¼ ^ r^ (r^ ; t) fi (r^ ; t); (3) i

where the mass is expressed in simulation units. The lattice is typically initialized such that the density at each node r^ ¼ 1. The average fluid velocity at a node u^ is found by first multiplying the mass fraction fi by the velocity e^ i for each velocity and summing, to give the momentum per unit volume, then dividing by the density at the node (Eq. (3)): P ^ ^ ^ ^ ¼ i fi e i (r ; t) ; ^ r^ ; t) (4) u( ^ r^ (r^ ; t) ^ Dt^ ¼ 1: for example, given that Dx= 1 u^ x ¼ P (f1 þ f7 þ f10 þ f12 þf13 f2 f8 f9 f11 f14 ): i fi

(7)

collision

The collision operator (r.h.s. of Eq. (7)) is only valid when the difference between the incoming distribution and the equilibrium distribution is small. This version of the lattice Boltzmann equation, with a single relaxation parameter, is called the LBGK model and is the most commonly used lattice Boltzmann model. Other schemes are discussed briefly in Section 2.4. One of the major, generic advantages of the lattice Boltzmann method is that operations at each node are local. This means that, at each timestep, operations on the state of each node only require information held at that node (this information may have propagated there from an immediate neighbour at the beginning of the timestep). This locality of operations eliminates the need for time-consuming iterative convergence at each timestep, which is characteristic of implicit methods for the solution of differential equations used in many conventional computational fluid dynamic techniques.

2.2. Boundaries and driving flow One of the great advantages of the lattice Boltzmann method over conventional computational fluid dynamic techniques is its simple handling of boundary conditions. Fig. 3 illustrates the most common method for implementing fluid–solid boundaries. Lattice nodes that are within a solid do not have a fluid distribution associated with them. Fluid nodes that have at least one nearest neighbour that is a solid node are designated as boundary nodes and require special treatment. During the propagation step, boundary nodes do not receive an incoming mass component from solid nodes. Conversely, the mass component propagating from a boundary node to a solid node would be lost since solid nodes do not have a fluid distribution. The solution is to reverse

(5)

For a calculated fluid density and average velocity, there will be a corresponding equilibrium velocity distribution with the same density and average velocity (mass and momentum are conserved). On a lattice, this is given by a discrete version of Eq. (1): " # ^ u^ ^ 2 e^ i :u^ u: (e^ i :u) eq ; (6) fi ¼ r^ wi 1þ 2 2 þ 4 2c^ s 2c^ s c^ s where wi are ‘weights’ associated with each velocity, typically, for a D3 Q 15 lattice: w0 ¼ 29 (rest weight), w1;...;6 ¼ 19 (orthogonal 1 weights) pffiffiffi and w7;...;14 ¼ 72 (diagonal weights). The quantity ^ is referred to as the lattice pseudo^ Dt) c^ s ¼ c^ = 3 (where c^ ¼ Dx= sound-speed. This value of c^ s is valid for a D3 Q 15 lattice with the given value of w0 but may differ for other geometries. The derivation of the discretized equilibrium velocity distribution equation (6) from the continuous equation (1) assumes constant ^ temperature and low Mach-number flow (juj5 c^ s ).

Fig. 3. Fluid–solid boundary handling. Solid is shown in dark grey, bounded by a solid black line. Lattice nodes within solid are shown as solid black squares; nodes within fluid with at least one solid neighbour (boundary nodes) are shown as greyfilled squares. Mass components propagating from a boundary node towards a solid node are reflected and returned to node of origin within same propagation step, equivalent to siting fluid–solid boundary half way between nodes (dashed line). ‘Staircased’ solid represented within simulation is shown in light grey, bounded by dashed line.



the outgoing mass component and send it back to the boundary node from which it originated. This so-called ‘half-way bounce back’ boundary condition amounts to siting the fluid–solid interface half way between the boundary and solid nodes and perpendicular to the vector joining the nodes (Succi, 2001). The practical impact of the resulting ‘staircase’ boundary is considered in Part II. There are many ways of driving the flow in a lattice Boltzmann simulation (Succi, 2001, provides an overview). One of the simplest and most flexible methods is to impose a constant and uniform body force G on the fluid at every point, physically analogous to a gravitational force acting on the fluid. This is achieved by adding an extra term gi to each of the mass components fi prior to propagation. The term gi is formulated in such a way that the total mass is conserved but the momentum is adjusted to account for the force acting on the mass at the node for the duration of the timestep: ^ ¼ gi (r^ ; t)

wi Dt^ ^ G:e^ i : 2 c^ s

(8)

This term is added to the r.h.s. of Eq. (7). Care should be taken to ensure that gi 5fi so that the condition that the difference between incoming and equilibrium distributions is small is not violated. Note that the body force approach is not appropriate if moving boundaries are desired, or if specific inlet/outlet velocities or pressures are required, in which case readers are directed to chapter 6 of Succi (2001) and the references therein. 2.3. Dimensional considerations Geophysical flow problems involve physical units of length, time and mass which are distinct from the simulation units used internally by the lattice Boltzmann algorithm. For a simulation to be of practical use, we require a mapping between ^ 0 -t (time) and ^ 0 -x (length), tT simulation and physical units: xL ^ 0 -m (mass). The mapping allows us to convert, for example, mM velocities from lattice spacings per timestep in the simulation to metres per second in the modelled system. The length mapping L0 is imposed by the user’s choice of resolution of the simulation. For example, if we model flow along a square-sided pipe with side 1 mm and choose our simulation lattice resolution such that there are 20 nodes across the pipe, the lattice spacing Dx ¼ 5 105 m. Since Dx^ 1, L0 ¼ Dx=Dx^ ¼ 5 105 m. The mass mapping M0 is obtained from the density of the fluid. Suppose that, in the current example, we are simulating the flow of water which, at 20 3 C, has a density r ¼ 998:29 kg m3. The simulation is initialized with a density r^ ¼ 1 at all nodes. Since ^ r ¼ M0 L3 hence, density has dimensions ½M½L3 , 0 r, 10 kg. M0 ¼ 1:25 10 The time mapping T0 is determined from the user’s choice of fluid kinematic viscosity (n ¼ 1:004 106 m2 s1 for water at 20 3 C). In the LBGK model, the viscosity is related to the relaxation parameter and the lattice pseudo-sound-speed: 1 2

n^ ¼ t c^ 2s Dt^

(9)

and has dimensions: ½L2 ½T1 . Note that the definition of the lattice viscosity implies that the relaxation parameter t 4 0:5. From the dimensions of viscosity, we can see that n ¼ n^ L20 =T0 , hence, we can obtain T0 . With a relaxation parameter t ¼ 1, n^ ¼ 16, hence, in the current example, T0 ¼ 4:15 104 s.

in physical units. It is, however, important that the user understands the relationship between the mappings because they place practical restrictions on the flows that can be accurately simulated. In the calculation above, the physical timestep Dt is determined by the choice of resolution and relaxation parameter t. For problems involving time dependent flow, it is necessary that the timestep is much smaller than the timescale over which the flow evolves. Suppose that the pipe in the current example had a side of 1 m, rather than 1 mm. It is unlikely to be practical to maintain the resolution Dx ¼ 5 105 m due to memory limitations so a new resolution of Dx ¼ 0:05 m might be chosen. If all other parameters were kept the same, the new physical timestep, given by Eq. (9), would be T0 ¼ 415 s. Clearly this would be unsuitable for simulating unsteady flow. Theoretically, this problem can be overcome by varying the relaxation parameter, in this case by making (t 0:5) very small. However, very small values of t lead to very slow convergence of the simulation resulting in unfeasibly long simulation runs. Conversely, the accuracy of the simulation decreases markedly for large values of t, effectively restricting the relaxation parameter to the range 0:5 o t t 3. These practical considerations are discussed in detail in Part II. Care should also be taken to ensure that the low Machnumber assumption of the LBGK method is not violated (Section 2.1). This condition arises because the weak compressibility of the LBGK method leads to density gradients in the simulated domain which are not present for strictly incompressible flow. These gradients are O(Ma2 ) (Martinez et al., 1994) hence the error due to non-zero Mach number is O(Ma3 ) (Sterling and Chen, 1996) where Ma ¼ ju^ max j=c^ s . To keep this error to less than 1%, the maximum flow velocity should be ju^ max j t c^ s =5. The maximum expected flow velocity for a simulation should be estimated in physical units, giving the condition jumax j t Dx=10Dt. Since Dx=Dt ¼ L0 =T0 , this condition can be expressed in terms of the lattice spacing and the timestep. From Eq. (9) and the discussion which follows it, we can see that timestep is derived from the input parameters L0 , n and t, hence we can derive the low Mach-number condition in terms of input parameters. Assuming t ¼ 1, the condition for the minimum resolution required to ensure low Ma is: L0 t

3n : 5jumax j

(10)

This condition and consideration of memory resources restricts the range of Reynolds number that can be achieved. The Reynolds number is given by Re ¼ uL=n where u and L are the flow’s characteristic velocity and lengthscale, respectively. If we assume u ¼ jumax j and the characteristic lengthscale is resolved by n nodes (i.e. L ¼ nL0 ), then, from Eq. (10), we obtain: Re t

3n 5

(11)

to ensure low Mach-number flow. High Reynolds number simulations, therefore, require high resolutions and are computationally expensive, particularly for flows in which L is small compared with the size of the simulation domain. Various lattice-Boltzmann algorithms have been published which sacrifice some of the simplicity of the algorithm presented in Section 2.1 to allow moderate and high Mach-number flow to be simulated (e.g. Sun and Hsu, 2003 and references therein). 2.4. Modelling real materials

2.3.1. Practical limitations LBflow handles dimensional mapping internally. The user inputs parameters in physical units and LBflow outputs results

The lattice Boltzmann LBGK model developed above is, strictly, only valid for a weakly compressible ideal gas (Succi, 2001). The


‘ideal gas’ condition is a consequence of the single relaxation time of the LBGK model, which implies that mass, momentum and heat transfer all take place at the same rate. The ‘weakly compressible’ condition results from the slow speed of sound on the lattice. In practice, however, the LBGK model is found to be accurate for all Newtonian fluids, including incompressible liquids, at low Machnumber. The LBGK model is encapsulated in the LBflow module ‘lbgk’ which is tested and validated extensively in Part II. Lattice Boltzmann algorithms have been developed for a broad range of materials and classes of flow, and many are discussed in Succi (2001) and Sukop and Thorne (2006). Schemes that offer enhanced stability, at the cost of some simplicity, have been presented, including multiple relaxation time models (Lallemand and Luo, 2000; d’Humie res et al., 2002) and entropic lattice Boltzmann models (Ansumali et al., 2003). Methods for modelling turbulent flow (Chen et al., 2003) and compressible flow (Yu and Zhao, 2000; Sun and Hsu, 2003) have also been developed. The approach taken to modelling more complex material properties varies. Common approaches include adjusting the equilibrium distribution equation to introduce non-ideal behaviour (e.g. Swift et al., 1995; Luo, 1998) and propagating multiple species simultaneously on the same lattice (e.g. Shan and Chen, 1993; Kang et al., 2002). Other methods iteratively couple a lattice Boltzmann model for fluid flow with some other model which describes the behaviour of another phase, for example a latticespring model for a surrounding elastic shell (Buxton et al., 2005) or a discrete element model for suspended particles (Cook et al., 2004). The modular design of LBflow allows users to code modules which encapsulate the various lattice Boltzmann models that have been developed. It should be possible to create modules for most lattice Boltzmann models which preserve locality of operations (see end of Section 2.1). LBflow also supports iterative coupling to other models. The design and operation of LBflow are discussed in detail in the following section.

119

As discussed in Section 2.1, the operations that determine material behaviour, such as calculation of the equilibrium distribution function, are local in most lattice Boltzmann models. This means that the ‘physics’ of the material can be specified at the node level. LBflow ‘physics modules’ are shared object files (or dynamically linked libraries) which specify a subclass derived from the Node class, which defines a standard interface. Each module contains methods which encapsulate the physical behaviour of a particular type of node. The modules specified in the user’s simulation file are linked to LBflow dynamically at runtime. The key advantage of this approach is that expert users can develop new modules for LBflow, encapsulating different material behaviour, and share these easily with other users. Furthermore, a module does not have to specify a lattice Boltzmann node type but could, for example, specify an algorithm for adjusting the geometry of the simulated domain, or couple the lattice Boltzmann simulation to an elastic deformation model. LBflow is, therefore, highly extensible. For robustness and efficiency, LBflow makes use of the C++ Standard Template Library. Node instances are organized into user-specified groups via the STL map class, ensuring rapid iteration over nodes. This mechanism also allows differential treatment of groups of nodes, even of the same subclass, if required by the user. (This might be used, for example, to specify boundaries moving with different velocities in different parts of the simulated domain.) At the beginning of the simulation, LBflow creates a lookup table, mapping each node to its nearest neighbours, greatly increasing the speed of the propagation step. Due to the locality of calculations and the regularity of the lattice, the lattice Boltzmann method is amenable to efficient parallelization—typically speed-up is almost linear with the number of processors used. Adaptation of LBflow for parallel processing architectures is a development priority.

3.2. Running a simulation 3.

LBflow

This section introduces LBflow, describing its features and design philosophy, how to set up and run a simulation and the output format of the resulting data. Visualization and data analysis using the sister programme, LBview, are also discussed. This section is not intended as an exhaustive user manual and the design and implementation of new LBflow modules is not covered. 3.1. Implementation LBflow is designed to be user-friendly, efficient, flexible, extensible and portable. There is, inevitably, some degree of compromise between these goals, and a pragmatic balance has been sought. For example, in the interests of flexibility, extensibility and portability, LBflow does not have a graphical user interface, rather, a simulation is specified via a human-readable text file which is supplied to LBflow as a command line argument (Section 3.2). (Note, however, that the companion programme, LBview, supports GUI-driven operation of LBflow.) LBflow is written in ANSI C++ using an object-oriented approach and employing the Standard Template Library in the interests of clarity, modularity and reusability of the code. LBflow comprises three core classes, Simulation, Lattice and Node, and several ancillary classes. The Simulation class and its collaborators are responsible for parsing the user’s simulation file and controlling programme execution, the Lattice class deals with lattice operations and the Node class handles local operations at lattice nodes.

Simulations are specified in a plain text file that is parsed by LBflow. The following example simulation file specifies the flow of water along a square-sided pipe, following the example in Section 2.3. Note that indentation and carriage returns are for clarity only; the parser ignores multiple whitespace characters. The simulation is specified within a simulationf. . .g block. This block must begin with a lattice ( . . . )f. . .g block (line 2) which specifies the type of lattice to be used (in this case a D3 Q 15 lattice), the node dimensions of the lattice in the x-, y- and z-directions and the lattice spacing Dx. The modules f. . .g block (lines 3–10) comprises a sequence of calls to specific modules. Each call begins with the path to the module, which is then dynamically linked to the main LBflow executable. Execution control passes to the module which is responsible for parsing the relevant part of the simulation file. For example, line 4 specifies the path to the lbgk module which then parses the node-type specific information, including the placement of the nodes, in the remainder of line 4 and in line 5. The parsing of node-type specific information is carried out by the modules themselves, rather than by the core executable, because node-types will differ in the information they require from the simulation file. Modules may take a label which allows them to be referred to in the output ( . . . ) f. . .g block, described later. In addition, lbgk takes the fluid viscosity and density in physical units (in this case the values for water at 20 3 C). A driving body force can also be specified for lbgk, as a pressure gradient vector P which is given as Pgrad( Px Py Pz ). In this example, a fixed pressure gradient of 1 Pa m1 driving flow in the positive x-direction is given (negative sign arises because



1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16

simulationf lattice(D3Q15)fdimensions(40 22 22) dx(5e 5)g modulesf =pathto=lbgk(label(water) viscosity(1:004e 6) density(998:29) Pgrad(1 0 0))f uninitializedfwhere(everywhere)g g =pathto=null()f uninitializedfwhere(walls(0 0 1 1 1 1))g g g event(halt)fwhen(i 4 10000 % 1 OR s 1e 8 % 50)g output(results)fwriteto(=pathto=rfile) when(end) label(water) variables(u)g output(domain)fwriteto() when(i ¼ %1000) variables(V)g output(domain)fwriteto(=pathto=dfile) when(end) variables(V)g output(simulation)fwriteto(=pathto=sfile) when(end)g g

pressure drops in the direction of flow). It is also possible to specify that the value should be read from a file: e.g. Pgrad(0 0 steer(=pathto=Pfile:str)) reads the z-component of P from a file. The value is read from the file at the beginning of every timestep and can be changed by the user during runtime. This mechanism allows certain parameters to be ‘steered’ whilst the simulation is running. The final line of the call to lbgk, line 5, specifies where in the lattice the nodes should be placed. In this case, all nodes in the lattice are initialized as type lbgk. The second module call, in line 5, is to ‘null’, which specifies ‘empty’ nodes. LBflow treats an empty node, which requires no computer memory, as a solid. This minimizes the memory required for a simulation, particulary if the domain has a large volume fraction of solid. By default, all nodes are empty before the first module is called. The null module requires no information other than a location. In this case the location of the nodes is specified via the command walls(0 0 1 1 1 1), which, with these arguments, places an empty node in every lattice position x, y, z for which y ¼ 1; ly or z ¼ 1; lz. This creates a square-sided pipe with open ends in the x-direction. By default, boundaries in LBflow are periodic so the pipe is, effectively, infinitely long in the xdirection. Node types are placed within the lattice in the order in which they are specified, hence, the nulls overwrite the lbgks at the specified walls. Each call to a module results in a new group of nodes (Section 3.1). Geophysical flow problems often have complex geometries and LBflow provides various mechanisms for specifying the location of different node types. Geometry may be specified through a triangulated surface representation of a volume (using the GTS library2) or, most flexibly, though a binary or ascii file containing a binary representation of the placement of nodes within the lattice. Line 11 specifies the termination criteria for the simulation. In this example, the simulation will terminate when either the number of timesteps exceeds 10,000, or when the average speed across the entire lattice is varying by less than a factor of 108 over 50 timesteps. This latter condition is used to test when the simulation has settled (this is discussed in more detail in Part II). Various other criteria can be specified. Output of simulation data is controlled by the output ( . . . ) f. . .g block and can take several different formats. Line 12 specifies that the average value of the x-component of velocity for nodes with label ‘water’ (all nodes of type lbgk in this

2

http://gts.sourceforge.net

example) should be written to a file at the end of the simulation. Line 13 outputs the velocity vector for every node in the domain to stdout every 1000 timesteps. This is used when piping the output to the companion visualization programme, LBview, discussed later in Section 3.3.1. Line 14 outputs a domain to file at the end of the simulation. The final output ( . . . ) f. . .g block in line 15 tells LBflow to output a simulation file at the end of the current simulation. This simulation file takes the same format as the example input simulation file given, but also records the state of each node at the time the file is written. This ‘checkpoint’ can be used later to restart the simulation from that point. If simulation files are written regularly during a long simulation, they provide protection from loss of data in case of a computer crash. The simulation file can also be edited by the user, allowing multiple flow scenarios to be tested from the same starting point.

3.3. Output, visualization and analysis LBflow is designed to be used as a numerical laboratory for the investigation of practical geophysical flow problems, hence, it is expected that users will want to extract quantitative results from the simulation. Depending on the nature of the flow problem, the required result may be, for example, the average flow rate through the system, the pressure at a specific point in the flow, or the full three-dimensional velocity map throughout the simulated domain. Through the output ( . . . ) f. . .g command (Section 3.2), LBflow allows the user to extract many different types of data from the simulation. The most complete dataset is accessed through the output (simulation) f. . .g command, which creates a text file containing all of the information held in the simulation, including each of the components fi of the velocity distribution at every node in the lattice. From this file, the user can extract whatever data are required. The file is, however, large and typically contains far more information than is required by the user. The output(domain) f. . .g command creates a text file containing only the data specified by the user, over the whole lattice, or a subset of the lattice. For nodes of type lbgk, the following data can be accessed: ux , uy , uz , u, juj, r and local pressure. The following is part of the domain file created by the command in line 14 of the example simulation file presented in Section 3.2 (note that ‘ ==’ indicates that the rest of that line is a comment) Within the domain( . . . )f. . .g block, the first sub-block specifies the type of lattice, its dimensions, lattice spacing, and the position of its centre in physical units. The second sub-block specifies the


1 2 3 4 5 6 7 8 9

121

domain(structured)f latticeD3Q15fdimensions(40 22 22) dx(5e 05) centre(0 0 0)g mappingf5e 05 0:000415007 1:24786e 10g V ‘‘ velocity vector’’ (1 1 0) o 34 DOUBLE f == : : : 1:46739965538628e 05 8:31170908607243e 11 8:31171099426824e 11 == : : : gg

Fig. 4. Screenshot of a visualization of flow along a square-sided pipe using LBview; LBflow simulation to produce these data is specified in example simulation file presented in Section 3.2. Visualization is highly user-configurable and may include, for example, velocity vectors (for clarity, shown only in one quadrant of domain), velocity streamlines (not shown) and arbitrary two-dimensional surfaces coloured according to scalar or vector fields.

mapping between simulation and physical units: mapping fL0 T0 M0 g (see Section 2.3). After the mappingf. . .g block, there follows one or more data blocks: one for each variable specified in the variables( . . . ) tag within the output(domain)f. . .g block in the simulation file. In this example, the only variable supplied is ‘V’, which indicates that the velocity vector should be written for every point in the lattice. Line 4 opens the block which contains the velocity data. This line indicates the nature of the content as follows: the variable symbol V; a short description of the data ‘velocity vector’; the dimensionality of the data, here (1 1 0) indicates that the data have dimensions ½L1 ½T1 ½M0 , i.e. m s1 ; the number of data tokens per node 3 (three components of velocity vector); the type of data DOUBLE (double precision float). The data follow, starting with the value of the variable at the node with position vector ½1; 1; 1 then iterating through the lattice with the x-position incrementing fastest. The ‘-’ symbol indicates that the variable is undefined for that node, in this case because the node is solid. The data are presented in simulation units, but can be converted into physical units easily via the mapping specified in line 3 and the dimensionality specified in line 4.

3.3.1. LBview Visualization and analysis of data produced by LBflow are facilitated by the companion application LBview. LBview is written in Java, for portability, and provides a graphical user interface (GUI), through which the user can visually explore the data. Fig. 4 shows a screenshot of a visualization, using LBview, of

the domain file created by the command in line 14 of the example simulation file presented in Section 3.2. The importance of three-dimensional visualization of flow should not be underestimated, particularly when transient or spatially complex flow phenomena are present. The visualization, achieved via the Visualization ToolKit library,3 is highly userconfigurable. Velocity vectors and streamlines can be plotted in three dimensions, pressure and density scalars can be plotted on arbitrary two-dimensional surfaces and the surface of solid objects can be reconstructed. A powerful feature of LBview is that it is capable of displaying data piped directly from LBflow during a simulation. The visualization updates automatically as new data are produced allowing the user to observe transient flow phenomena directly. This is particularly valuable when the user is steering flow parameters (Section 3.2). The user can observe, in real time, changes to the flow that result from adjustment of steered variables. This can be used, for example, to observe the development of vortices behind a solid object as the driving pressure gradient is increased. This approach is most rewarding when the simulation size and computing power are such that the time between successive outputs of data is short, allowing changes in the flow to be rendered smoothly. LBview provides a configurable GUI for steering simulation parameters. This, combined with dynamic visualization of piped LBflow simulation output, allows the user to explore parameter space rapidly and interactively. This can assist the user in

3

http://www.vtk.org



identifying interesting regions of parameter space much more rapidly than is possible with a conventional ‘batch job’ approach. LBview also provides an ‘analysis’ GUI which implements a trilinear interpolation algorithm, allowing the user to extract scalar and vector data (pressure, velocity, etc.) from any point in the lattice. Through the GUI, the user can easily extract interpolated datasets for unstructured sets of points in the lattice, along arbitrarily oriented lines and surfaces and for subset threedimensional blocks. The interpolation routine accounts for the fact that boundaries between solid and fluid nodes are located halfway between nodes. The data can be written to tab-delimited plain-text files for further analysis. 3.4. Code availability LBflow and LBview are available by request from the author. Details are available at http://www.dur.ac.uk/ed.llewellin/lbflow/.

Acknowledgements I am grateful to Prof. Julia Yeomans, Dr. Alex Dupuis and Chris Pooley for helpful discussions regarding the practical implementation of the lattice Boltzmann algorithm, and to Dr. Jon Blower for guidance with C++ and Java programming. Three anonymous reviewers are thanked for their insightful comments that resulted in significant improvements to this article. EWL is supported by NERC Research Fellowships NER/I/S/2002/00685 and NE/ D009758/2. References Ansumali, S., Karlin, I.V., Ottinger, H.C., 2003. Minimal entropic kinetic models for hydrodynamics. Europhysics Letters 63, 798–804. Benzi, R., Succi, S., Vergassola, M., 1992. The lattice Boltzmann-equation—theory and applications. Physics Reports 222, 145–197. Buxton, G.A., Verberg, R., Jasnow, D., Balazs, A.C., 2005. Newtonian fluid meets an elastic solid: coupling lattice Boltzmann and lattice-spring models. Physical Review E 71 Article No: 056707.

Chen, S., Doolen, G.D., 1998. Lattice Boltzmann method for fluid flows. Annual Review of Fluid Mechanics 30, 329–364. Chen, H., Kandasamy, S., Orszag, S., Shock, R., Succi, S., Yakhot, V., 2003. Extended Boltzmann kinetic equation for turbulent flows. Science 301, 633–636. Cook, B.K., Noble, D.R., Williams, J.R., 2004. A direct simulation method for particle–fluid systems. Engineering Computations 21, 151–168. d’Humie res, D., Ginzburg, I., Krafczyk, M., Lallemand, P., Luo, L-S, 2002. Multiplerelaxation-time lattice Boltzmann models in three dimensions. Philosophical Transactions of the Royal Society of London A 360, 437–451. Dupuis, A., Chopard, B., 2000. An object oriented approach to lattice gas modeling. Future Generation Computer Systems 16, 523–532. He, X., Luo, L-S, 1997. Theory of the lattice Boltzmann method: from the Boltzmann equation to the lattice Boltzmann equation. Physical Review E 55, 6811–6817. Higuera, F., Jimenez, J., 1989. Boltzmann approach to lattice gas simulations. Europhysics Letters 9, 663–668. Higuera, F.J., Succi, S., Benzi, R., 1989. Lattice gas-dynamics with enhanced collisions. Europhysics Letters 9, 345–349. Kang, Q., Zhang, D., Chen, S., He, X., 2002. Lattice Boltzmann simulation of chemical dissolution in porous media. Physical Review E 65 Article No: 036318. Lallemand, P., Luo, L-S, 2000. Theory of the lattice Boltzmann method: dispersion, dissipation, isotropy, Galilean invariance, and stability. Physical Review E 64, 6546–6562. Llewellin, E.W., 2009. LBflow: an extensible lattice Boltzmann framework for the simulation of geophysical flows. Part II: usage and validation. Computers and Geosciences, in press, doi:10.1016/j.cageo.2009.08.003. Luo, L-S, 1998. Unified theory of the lattice Boltzmann models for nonideal gases. Physical Review Letters 81, 1618–1621. Martinez, D.O., Matthaeus, W.H., Chen, S., Montgomery, D.C., 1994. Comparison of spectral method and lattice Boltzmann simulations of two-dimensional hydrodynamics. Physics of Fluids A 6, 1285–1298. McNamara, G., Zanetti, G., 1988. Use of the Boltzmann equation to simulate lattice gas automata. Physical Review Letters 61, 2332–2335. Shan, X., Chen, H., 1993. Lattice Boltzmann model for simulating flows with multiple phases and components. Physical Review E 47, 1815–1819. Succi, S., 2001. The Lattice Boltzmann Equation for Fluid Dynamics and Beyond. Oxford University Press, Oxford ISBN: 0198503989, 288pp. Sukop, M.C., Thorne, D.T., 2006. Lattice Boltzmann Modelling: An Introduction for Geoscientists and Engineers. Springer, Berlin ISBN: 3540279814, 172pp. Sterling, J., Chen, S., 1996. Stability analysis of lattice Boltzmann methods. Journal of Computational Physics 123, 196–206. Sun, C.H., Hsu, A.T., 2003. Three-dimensional lattice Boltzmann model for compressible flows. Physical Review E 68 Art. No.: 016303. Swift, M.R., Osborn, W.R., Yeomans, J.M., 1995. Lattice Boltzmann simulations of nonideal fluids. Physical Review Letters 75, 830–833. Yu, D., Mei, R., Luo, L.-S., Shyy, W., 2003. Viscous flow computations with the method of lattice Boltzmann equation. Progress in Aerospace Sciences 39 329–367. Yu, H.D., Zhao, K.H., 2000. Lattice Boltzmann method for compressible flows with high Mach numbers. Physical Review E 61, 3867–3870.