Force models

Get started:

This module offers different models to introduce a body force in the lattice Boltzmann scheme. If you don’t know which model to choose, use lbmpy.forcemodels.Guo.

Detailed information:

Force models add a term \(C_F\) to the collision equation:

\[f(\mathbf{x} + c_q \Delta t, t + \Delta t) - f(\mathbf{x},t) = \Omega(f, f^{(\mathrm{eq})}) + \underbrace{F_q}_{\mbox{forcing term}}\]

The form of this term depends on the concrete force model: the first moment of this forcing term is equal to the acceleration \(\mathbf{a}\) for all force models. Here \(\mathbf{F}\) is the D dimensional force vector, which defines the force for each spatial dircetion.

\[\sum_q \mathbf{c}_q \mathbf{F} = \mathbf{a}\]

The second order moment is different for the forcing models - if it is zero the model is suited for incompressible flows. For weakly compressible collision operators a force model with a corrected second order moment should be chosen.

\[ \begin{align}\begin{aligned}\sum_q c_{qi} c_{qj} f_q &= F_i u_j + F_j u_i &\qquad \mbox{for Guo, Luo models}\\\sum_q c_{qi} c_{qj} f_q &= 0 &\qquad \mbox{for Simple, Buick}\end{aligned}\end{align} \]

Models with zero second order moment have:

\[F_q = \frac{w_q}{c_s^2} c_{qi} \; a_i\]

Models with nonzero second moment have:

\[F_q = \frac{w_q}{c_s^2} c_{qi} \; a_i + \frac{w_q}{c_s^4} (c_{qi} c_{qj} - c_s^2 \delta_{ij} ) u_j \, a_i\]

For all force models the computation of the macroscopic velocity has to be adapted (shifted) by adding a term \(S_{macro}\) that we call “macroscopic velocity shift”

\[ \begin{align}\begin{aligned}\mathbf{u} &= \sum_q \mathbf{c}_q f_q + S_{\mathrm{macro}}\\S_{\mathrm{macro}} &= \frac{\Delta t}{2 \cdot \rho} \sum_q F_q\end{aligned}\end{align} \]

Some models also shift the velocity entering the equilibrium distribution.

Comparison

Force models can be distinguished by 2 options:

Option 1:

\(C_F = 1\) and equilibrium velocity is not shifted, or \(C_F=(1 - \frac{\omega}{2})\) and equilibrum is shifted.

Option 2:

second velocity moment is zero or \(F_i u_j + F_j u_i\)

Option2 \ Option1	no equilibrium shift	equilibrium shift
second moment zero	Simple	Buick
second moment nonzero	Luo	Guo

class AbstractForceModel(force)

Abstract base class for all force models. All force models have to implement the __call__, which should return a q dimensional vector added to the PDFs in the population space. If an MRT method is used, it is also possible to apply the force directly in the moment space. This is done by additionally providing the function moment_space_forcing. The MRT method will check if it is available and apply the force directly in the moment space. For MRT methods in the central moment space the central_moment_space_forcing function can be provided, which shifts the force vector to the central moment space. Applying the force in the collision space has the advantage of saving FLOPs. Furthermore, it is sometimes easier to apply the correct force vector in the collision space because often, the relaxation matrix has to be taken into account.

Parameters

force – force vector of size dim which contains the force for each spatial dimension.

macroscopic_velocity_shift(density)

macroscopic velocity shift by \(\frac{\Delta t}{2 \cdot \rho}\)

Parameters

density – Density symbol which is needed for the shift

macroscopic_momentum_density_shift(*_)

macroscopic momentum density shift by \(\frac{\Delta t}{2}\)

equilibrium_velocity_shift(density)

Some models also shift the velocity entering the equilibrium distribution. By default the shift is zero

Parameters

density – Density symbol which is needed for the shift

class Simple(force)

A simple force model which introduces the following additional force term in the collision process \(\frac{w_q}{c_s^2} \mathbf{c_{q}} \cdot \mathbf{F}\) (often: force = rho * acceleration where rho is the zeroth moment to be consistent with the above definition) Should only be used with constant forces! Shifts the macroscopic velocity by \(\frac{\mathbf{F}}{2}\), but does not change the equilibrium velocity.

class Luo(force)

Force model by Luo [Luo93].

Shifts the macroscopic velocity by \(\frac{\mathbf{F}}{2}\), but does not change the equilibrium velocity.

class Guo(force)

Force model by Guo [GZS02], generalized to MRT, which makes it equivalent to [Sch08], equation 4.67 Adapts the calculation of the macroscopic velocity as well as the equilibrium velocity (both shifted by \(\frac{\mathbf{F}}{2}\))!

equilibrium_velocity_shift(density)

Some models also shift the velocity entering the equilibrium distribution. By default the shift is zero

Parameters

density – Density symbol which is needed for the shift

class He(force)

Force model by He [HSD98] Adapts the calculation of the macroscopic velocity as well as the equilibrium velocity (both shifted by \(\frac{\mathbf{F}}{2}\))!

Force moments are derived from the continuous maxwellian equilibrium. From the moment integrals of the continuous force term

\[F (\mathbf{c}) = \frac{1}{\rho c_s^2} \mathbf{F} \cdot ( \mathbf{c} - \mathbf{u} ) f^{\mathrm{eq}} (\mathbf{c})\]

the following analytical expresson for the monomial raw moments of the force is found:

\[m_{\alpha\beta\gamma}^{F, \mathrm{He}} = \frac{1}{\rho c_s^2} \left( F_x m^{\mathrm{eq}}_{\alpha+1,\beta,\gamma} + F_y m^{\mathrm{eq}}_{\alpha,\beta+1,\gamma} + F_z m^{\mathrm{eq}}_{\alpha,\beta,\gamma+1} - m^{eq}_{\alpha\beta\gamma} ( \mathbf{F} \cdot \mathbf{u} ) \right)\]

equilibrium_velocity_shift(density)

Some models also shift the velocity entering the equilibrium distribution. By default the shift is zero

Parameters

density – Density symbol which is needed for the shift

class Schiller(force)

Force model by Schiller [Sch08], equation 4.67 Equivalent to the generalized Guo model.

class Buick(force)

This force model [BG00] has a force term with zero second moment. It is suited for incompressible lattice models. However it should be used with care because such a LB body form model is only consistent when applied to the solution of steady - state hydrodynamic problems. More information on an analysis of the Buick force model can be found in [SS11] and in [PS20]

equilibrium_velocity_shift(density)

Some models also shift the velocity entering the equilibrium distribution. By default the shift is zero

Parameters

density – Density symbol which is needed for the shift

class EDM(force)

Exact differencing force model as shown in [KrugerKK+17] in eq. 6.32

class ShanChen(force)

Shan and Chen force model. The implementation is done according to [PS20]. For reference compare table 1 which is the Shan and Chen model for an SRT collision operator. These terms are transfered to the moment space and then all representations for the different collision operators are derived from that.

equilibrium_velocity_shift(density)

Some models also shift the velocity entering the equilibrium distribution. By default the shift is zero

Parameters

density – Density symbol which is needed for the shift