# Tutorial: the open-source library Palabos in your daily work

Jonas Latt EPFL, Lausanne, Switzerland

Rome, DSFD 2010

www.lbmethod.org/palabos

Palabos: a library for developing LB models, and for running LB simulations

Two development interface
C++: The native interface; powerful and general, but not always easiest to use. Palabos: A scripting interface which combines the power of Palabos with a look-and-feel similar to Matlab.

Distinguishing features
Combines high-performance and interactivity. Offers a convenient platform to develop new models.

www.lbmethod.org/palabos

Example: ﬂow through a porous media
Let’s develop a simple application which contains
Creation of the geometry of a porous media. Execution of the simulation. Visualization of the result. Validation of the numerical model.

www.lbmethod.org/palabos

www.org/palabos.lbmethod. you need to download the Palabos library at www.Comment The Palabos application presented here is written in the Python language and was typed interactively during the DSFD 2010 tutorial. To run it yourself.org/palabos .lbmethod.py. and access the ﬁle examples/porous.

velocityNorm()) lattice[10:30.:.nz)): pout. rand_int(nobst.200): lattice.display(’Sphere at position’.org/palabos .cy. [1.:.:.nz/2]. 50..collideAndStream() imShow(lattice[:.velocityNorm()) pout.velocityComponent(0).imagesc( [ lattice.lbmethod.:].:.:.collideAndStream() imShow(lattice[:.0.10].definePressureBC(lattice[nx−1.6 lattice = Block3D(nx. cz) media += (x−cx)**2 + (y−cy)**2 + (z−cz)**2 < r**2 pout.collideAndStream() imShow(lattice[:.strainRateFromStress().setBoundaryDensity(1.isoSurface(media.defineDynamics(BGK(omega=1. 50 tau = 0.nz. rand_int(nobst.02) boundary.velocityNorm()) lattice.symmetricTensorNorm()[:.20] ] ) www.:.display( lattice[media==0][nx/2.:.10.10].setBoundaryDensity(1.ny.]) boundary.]) lattice.meshGrid() media = (x−10)**2 + (y−10)**2 + (z−10)**2 < 10**2 pout.. [0.nz/2].:]) lattice[nx−1.regularized().:.strainRate().defineDynamics(BounceBack(1.)) dir(lattice) help(lattice.:].cz in zip(rand_int(nobst.20]. lattice.10:30. nz = 100. BGK(omega=1/tau)) pout.y.:]. cx.100): lattice.10:30].symmetricTensorNorm()[:.10.]) nobst = 30 r = 8 for cx./tau)) x.ny).20].)) for i in range(1. [1.isoSurface(media>0.0.average() ) pout.initializeAtEquilibrium(1.:]) lattice[0.definePressureBC(lattice[0.defineDynamics(BounceBack(1.nx).z = lattice.The code #!/usr/bin/python from palabos import * nx.) lattice[media>0]. ny.collideAndStream() for i in range(1. D3Q19.display( lattice[10.1.100): lattice.velocity().regularized().defineDynamics) for i in range(1. cy.:.getPopulations() ) lattice[10.:.

ny.Step-by-step: Create the lattice Input nx.nz.6 lattice = Block3D(nx. D3Q19.ny. 50 tau = 0.org/palabos . BGK(omega=1/tau)) www. nz = 100. 50.lbmethod.

.02777778 0.02777778 0.05555556 0.10].05555556 0.02777778 0.0.lbmethod.0. [0.initializeAtEquilibrium(1.02777778 ] www.05555556 0..02777778 0.02777778 0.10.display( lattice[10.10.getPopulations() ) lattice[10.05555556 0.02777778 0.02777778 0.02777778 0.1.02777778 0.10].02777778 0.33333333 0.02777778 0.org/palabos .]) Output [ 0.Step-by-step: Access a single cell Input pout.05555556 0.05555556 0.

Theory: Collision rules Each lattice node can have different collision rule Additionally to providing the algorithm for collision. A lattice cell in Palabos looks as follows: www. . rescaling the populations.org/palabos . etc. This way of treating algorithms like data is typical for object-oriented programming. .lbmethod. this operation speciﬁes information for computing macroscopic variables.

lbmethod.:.nz/2].velocityNorm()) Output www.100): lattice.collideAndStream() imShow(lattice[:.Step-by-step: Run and visualize the simulation Input for i in range(1.org/palabos .

defineDynamics(BounceBack(1.org/palabos .10:30.:.100): lattice.)) for i in range(1.Step-by-step: Instantiate bounce-back nodes Input lattice[10:30.lbmethod.collideAndStream() imShow(lattice[:.velocityNorm()) Output www.10:30].nz/2].

/tau)) x.]) Output www.z = lattice.Step-by-step: Create a sherical obstacle Input lattice. [1.y.lbmethod.org/palabos .isoSurface(media.meshGrid() media = (x-10)**2 + (y-10)**2 + (z-10)**2 < 10**2 pout.defineDynamics(BGK(omega=1.

Step-by-step: Create 30 sherical obstacles Input nobst = 30 r = 8 for cx.display(’Sphere at position’. cx. rand_int(nobst. cz) media += (x-cx)**2 + (y-cy)**2 + (z-cz)**2 < r**2 pout. [1.cy.org/palabos .nx).lbmethod.]) Output Sphere Sphere Sphere Sphere Sphere Sphere Sphere . rand_int(nobst. at at at at at at at position position position position position position position 4 1 21 86 24 0 60 40 35 38 32 16 28 26 15 67 42 3 45 7 22 www.ny). cy.isoSurface(media>0.nz)): pout..cz in zip(rand_int(nobst..

cz) media += (x-cx)**2 + (y-cy)**2 + (z-cz)**2 < r**2 pout. rand_int(nobst.cz in zip(rand_int(nobst. rand_int(nobst.display(’Sphere at position’.isoSurface(media>0.Step-by-step: Create 30 sherical obstacles Input nobst = 30 r = 8 for cx.lbmethod.org/palabos .ny). cx.nx).nz)): pout. cy.cy.]) Output www. [1.

or . Evaluation of ﬁnite-difference schemes.Theory: Limited-range interactions They are used whenever an operation. involves communication between different blocks. Examples Non-local boundary conditions. . Coupling between components in a multi-component ﬂuid. www. . . . . for example for computing velocity gradients. .lbmethod. is non-local. They are executed either automatically if they are part of the physical scheme.org/palabos . or manually if they are part of a data evaluation process. .

lbmethod.:.:].Step-by-step: Instantiate boundary conditions for a pressure-driven ﬂow Input boundary.:]) lattice[0.setBoundaryDensity(1.definePressureBC(lattice[nx-1.regularized().02) boundary.) lattice[media>0].)) www.defineDynamics(BounceBack(1.:.:].org/palabos .definePressureBC(lattice[0.:.:]) lattice[nx-1.:.setBoundaryDensity(1.regularized().

20].:.org/palabos .lbmethod.velocityNorm()) Output www.Step-by-step: Run the simulation Input for i in range(1.200): lattice.collideAndStream() imShow(lattice[:.

2. 1. Iterate once over all lattice cells 1.Theory: The Palabos collision-streaming cycle lattice.lbmethod. Execute all automatic limited-range interaction operations Each operation has its own domain of activity (e.1 Execute an in-place collision on the cell.org/palabos .2 Execute a streaming towards all neighbor nodes which are in post-collision state (no temporary memory).g.collideAndStream() The algorithm 1. the boundary condition applies only to boundaries.) www.

org/palabos .00511083245972 www.average() ) Output 0.lbmethod. velocityComponent(0).Step-by-step: Compute the ﬂow through a surface Input pout.:].display( lattice[media==0][nx/2.:.

Theory: Two ways of computing the strain rate tensor in iso-thermal ﬂuids Local approach: get the stress tensor from particle populations q−1 X i=0 Π= ci ci fi S=− 1 ω Π 2 ρc2 s In Palabos.org/palabos .lbmethod. this is deﬁned as a limited-range operation www. this is deﬁned through the local collision rule Non-local approach: compute velocity gradients ” 1“ ∇u + (∇u)T 2 S= In Palabos.

lbmethod.20] ] ) Output www.imagesc( [ lattice. symmetricTensorNorm()[:.strainRate().:.20]. symmetricTensorNorm()[:.:].Step-by-step: Compare stress and strain-rate Input pout.:.strainRateFromStress().display( lattice[media==0][nx/2.velocity().org/palabos .:.average() ) pout. lattice. velocityComponent(0).

You do not need to be aware of parallelism while developing these ingredients.org/palabos .lbmethod. www.The programmers interface for Palabos users Developing with Palabos means to implement either collision rules or limited-range interactions.

lbmethod.The Palabos development interface www.org/palabos .

org/palabos .lbmethod.5 17.1 31.2 9 1 2 4 8 Number of cores 16 32 www.Performance on a small parallel machine: Intel 8×quad-core with MPI 400 × 400 × 400 domain. D3Q19 Million site updates per second 195 114 60.

D3Q19 Million site updates per second 8056 4685 2725 1467 790 430 228 256 512 1024 2048 4096 8192 16384 Number of cores www.lbmethod.Performance on a large parallel machine: Blue Gene/P 16’000 cores 1000 × 1000 × 1000 domain.org/palabos .

Sparse-memory implementations. Grid reﬁnement.lbmethod.The convenient block interface hides a complicated data structure The internal implementation offers: Parallelism. www.org/palabos .

. is internally subdivided to remove unused regions www.lbmethod. . .The idea of sparse-memory implementations: A given domain. .org/palabos . .

A 3D example www.lbmethod.org/palabos .

org/palabos .lbmethod.The idea of grid reﬁnement Example: let’s use grid reﬁnement with the 2D lid-driven cavity www.

lbmethod.org/palabos .The idea of grid reﬁnement All levels of grid reﬁnement are represented on separate layers (blocks of distinct size) And all layers are put together in a common data structure www.

org/palabos . www. .If you have questions.lbmethod. .