espressopp.integrator.LatticeBoltzmann

Overview

espressopp.integrator.LatticeBoltzmann

Details

The LatticeBoltzmann (LB) class controls fluid hydrodynamics and allows for hybrid LB/MD simulations. It is implemented as espressopp.integrator.Extension in ESPResSo++.

class espressopp.integrator.LatticeBoltzmann(system, nodeGrid, a = 1., tau = 1., numDims = 3, numVels = 19)
Parameters:
  • system (shared_ptr) – system object
  • nodeGrid (Int3D) – arrangement of CPUs in space
  • a (real) – lattice spacing (in lattice units).
  • tau (real) – time discretization (in lattice units)
  • numDims (int) – dimensionality of the LB model
  • numVels (int) – number of velocity vectors in the LB model
Returns:

lb object

The LB-fluid in ESPResSo++ is aiming at simulations of complex soft matter systems. They consist of MD particles (colloids, composite nanoparticles or polymer chains) that are solved in the LB-fluid preserving hydrodynamic interactions.

The default lattice model is D3Q19 (numDims = 3, numVels = 19) and both lattice spacing a and timestep tau are set to 1. If some other lattice model is needed feel free to modify the code: adding 3D ones is straightforward, for 2D cases one has to make more thouroughs changes.

The parameters of the LB-fluid are expected in Lennard-Jones (LJ) units. This strategy helps users with MD-background think of LB-fluid in term of LJ liquid. One only has to specify its properties such as liquid density, \(\rho\), temperature, \(T\), and viscosity, \(\eta\).

Note

Standard LJ fluid can be characterized by \(\rho \sim 1 [\sigma^{-3}]\), \(T \sim 1 [\epsilon]\), and \(\eta \sim 5 [\epsilon \tau / \sigma^3]\)

Example

>>> L = 20
>>>
>>> # create cubic box
>>> box = (L, L, L)
>>> # The rc+skin= lattice_size
>>> rc = 0.9
>>> skin= 0.1 
>>>
>>> # initialize empty default system with the created cubic box.
>>> system, integrator = espressopp.standard_system.Default(box)
>>>
>>> # nodeGrid is determined based on the number of CPUs used for simulation among others
>>> nodeGrid=espressopp.tools.decomp.nodeGrid(espressopp.MPI.COMM_WORLD.size,box,rc,skin)
>>>
>>> # initialize lb object. The dimensions of the lattice are obtained from the
>>> # system's box dimensions employing lattice spacing 1.
>>> lb = espressopp.integrator.LatticeBoltzmann(system, nodeGrid)

Methods

getLBMom(node, moment)

Get hydrodynamic moment from a specific node

Parameters:
  • node (Int3D) – node index
  • moment (int) – hydrodynamic moment to get

Use 0 to get density \(\rho\) and 1-3 for mass flux components \(j_x\), \(j_y\) and \(j_z\), correspondingly.

setLBMom(node, moment, value)

Set hydrodynamic moment for a specific node

Parameters:
  • node (Int3D) – node index
  • moment (int) – hydrodynamic moment to set
  • value (real) – value to set
saveLBConf()

Dumps LB configuration with separate files for coupling forces, LB-fluid moments and populations (the last one is a bit overkill). The dump files are written for every CPU separately and are put in the dump folder

keepLBDump()

Sets a flag to keep previously dumped LB configuration. Normally the previous dump is deleted after a new one is made.

Example

>>> # set bulk viscosity
>>> for k in range (10):
>>>     integrator.run(50000)
>>>
>>>     # output LB configuration
>>>     lb.keepLBDump()         # flag to keep previously saved LB state
>>>     lb.saveLBConf()         # saves current state of the LB fluid

Properties

Int3D nodeGrid

Array of CPUs in space

Example

>>> # it is advised to set nodeGrid by internal ESPResSo++ function
>>> # based on the number of CPUs
>>> nodeGrid=espressopp.tools.decomp.nodeGrid(espressopp.MPI.COMM_WORLD.size,box,rc,skin)
real a = 1.

Lattice spacing (lattice units)

real tau = 1.

Lattice time step (lattice units)

int numDims = 3

Number of dimensions of the LB model (D3Q19)

int numVels = 19

Number of velocity vectors of the LB model (D3Q19)

real visc_b

Bulk viscosity (LJ units), affects gamma_b.

Example

>>> # set bulk viscosity
>>> lb.visc_b = 5.
real visc_s

Shear viscosity (LJ units), affects gamma_s.

Example

>>> # set shear viscosity
>>> lb.visc_s = 5.
real gamma_b = 0.

Bulk gamma (for experienced LB users)

real gamma_s = 0.

Shear gamma (for experienced LB users)

real gamma_odd = 0.

Odd gamma (for experienced LB users)

real gamma_even = 0.

Even gamma (for experienced LB users)

real lbTemp = 0.

Temperature of the LB fluid (LJ units)

Example

>>> L = 20
>>> T = 1.
>>> N = 200
>>>
>>> # create cubic box
>>> box = (L, L, L)
>>> rc=0.9
>>> skin=0.1
>>> 
>>> # initialize Lennard Jones system with the created cubic box and given temperature.
>>> system, integrator = espressopp.standard_system.LennardJones(N, box, temperature=T)
>>>
>>> # nodeGrid is determined based on the number of CPUs used for simulation
>>> nodeGrid=espressopp.tools.decomp.nodeGrid(espressopp.MPI.COMM_WORLD.size,box,rc,skin)
>>>
>>> # initialize lb object. The dimensions of the lattice are obtained from the
>>> # system's box dimensions employing lattice spacing 1.
>>> lb = espressopp.integrator.LatticeBoltzmann(system, nodeGrid)
>>>
>>> # set LB temperature to T
>>> lb.lbTemp = T
real fricCoeff=5.

Friction coefficient of the coupling (LJ units)

Example

>>> # set friction coefficient of the coupling
>>> lb.fricCoeff = 20.
int nSteps = 1

Timescale contrast (ratio) between LB and MD

Example

>>> # set time step contrast between LB and MD
>>> lb.nSteps = 10
int profStep = 10000

Frequency of time profiling

Example

>>> # set profiling frequency
>>> lb.profStep = 5000
Int3D getMyNi

Number of real and halo nodes for the CPU