forked from lijiext/lammps
372 lines
17 KiB
Plaintext
Executable File
372 lines
17 KiB
Plaintext
Executable File
"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c
|
|
|
|
:link(lws,http://lammps.sandia.gov)
|
|
:link(ld,Manual.html)
|
|
:link(lc,Section_commands.html#comm)
|
|
|
|
:line
|
|
|
|
fix lb/fluid command :h3
|
|
|
|
[Syntax:]
|
|
|
|
fix ID group-ID lb/fluid nevery LBtype viscosity density keyword values ... :pre
|
|
|
|
ID, group-ID are documented in "fix"_fix.html command :ulb,l
|
|
lb/fluid = style name of this fix command :l
|
|
nevery = update the lattice-Boltzmann fluid every this many timesteps :l
|
|
LBtype = 1 to use the standard finite difference LB integrator,
|
|
2 to use the LB integrator of "Ollila et al."_#Ollila :l
|
|
viscosity = the fluid viscosity (units of mass/(time*length)). :l
|
|
density = the fluid density. :l
|
|
|
|
zero or more keyword/value pairs may be appended :l
|
|
keyword = {setArea} or {setGamma} or {scaleGamma} or {dx} or {dm} or {a0} or {noise} or {calcforce} or {trilinear} or {D3Q19} or {read_restart} or {write_restart} or {zwall_velocity} or {bodyforce} or {printfluid} :l
|
|
{setArea} values = type node_area
|
|
type = atom type (1-N)
|
|
node_area = portion of the surface area of the composite object associated with the particular atom type (used when the force coupling constant is set by default).
|
|
{setGamma} values = gamma
|
|
gamma = user set value for the force coupling constant.
|
|
{scaleGamma} values = type gammaFactor
|
|
type = atom type (1-N)
|
|
gammaFactor = factor to scale the {setGamma} gamma value by, for the specified atom type.
|
|
{dx} values = dx_LB = the lattice spacing.
|
|
{dm} values = dm_LB = the lattice-Boltzmann mass unit.
|
|
{a0} values = a_0_real = the square of the speed of sound in the fluid.
|
|
{noise} values = Temperature seed
|
|
Temperature = fluid temperature.
|
|
seed = random number generator seed (positive integer)
|
|
{calcforce} values = N forcegroup-ID
|
|
N = output the force and torque every N timesteps
|
|
forcegroup-ID = ID of the particle group to calculate the force and torque of
|
|
{trilinear} values = none (used to switch from the default Peskin interpolation stencil to the trilinear stencil).
|
|
{D3Q19} values = none (used to switch from the default D3Q15, 15 velocity lattice, to the D3Q19, 19 velocity lattice).
|
|
{read_restart} values = restart file = name of the restart file to use to restart a fluid run.
|
|
{write_restart} values = N = write a restart file every N MD timesteps.
|
|
{zwall_velocity} values = velocity_bottom velocity_top = velocities along the y-direction of the bottom and top walls (located at z=zmin and z=zmax).
|
|
{bodyforce} values = bodyforcex bodyforcey bodyforcez = the x,y and z components of a constant body force added to the fluid.
|
|
{printfluid} values = N = print the fluid density and velocity at each grid point every N timesteps. :pre
|
|
:ule
|
|
|
|
[Examples:]
|
|
|
|
fix 1 all lb/fluid 1 2 1.0 1.0 setGamma 13.0 dx 4.0 dm 10.0 calcforce sphere1
|
|
fix 1 all lb/fluid 1 1 1.0 0.0009982071 setArea 1 1.144592082 dx 2.0 dm 0.3 trilinear noise 300.0 8979873 :pre
|
|
|
|
[Description:]
|
|
|
|
Implement a lattice-Boltzmann fluid on a uniform mesh covering the LAMMPS
|
|
simulation domain. The MD particles described by {group-ID} apply a velocity
|
|
dependent force to the fluid.
|
|
|
|
The lattice-Boltzmann algorithm solves for the fluid motion governed by
|
|
the Navier Stokes equations,
|
|
|
|
:c,image(Eqs/fix_lb_fluid_navierstokes.jpg)
|
|
|
|
with,
|
|
|
|
:c,image(Eqs/fix_lb_fluid_viscosity.jpg)
|
|
|
|
where rho is the fluid density, u is the local fluid velocity, sigma
|
|
is the stress tensor, F is a local external force, and eta and Lambda
|
|
are the shear and bulk viscosities respectively. Here, we have
|
|
implemented
|
|
|
|
:c,image(Eqs/fix_lb_fluid_stress.jpg),
|
|
|
|
with a_0 set to 1/3 (dx/dt)^2 by default.
|
|
|
|
The algorithm involves tracking the time evolution of a set of partial
|
|
distribution functions which evolve according to a velocity
|
|
discretized version of the Boltzmann equation,
|
|
|
|
:c,image(Eqs/fix_lb_fluid_boltzmann.jpg)
|
|
|
|
where the first term on the right hand side represents a single time
|
|
relaxation towards the equilibrium distribution function, and tau is a
|
|
parameter physically related to the viscosity. On a technical note,
|
|
we have implemented a 15 velocity model (D3Q15) as default; however,
|
|
the user can switch to a 19 velocity model (D3Q19) through the use of
|
|
the {D3Q19} keyword. This fix provides the user with the choice of
|
|
two algorithms to solve this equation, through the specification of
|
|
the keyword {LBtype}. If {LBtype} is set equal to 1, the standard
|
|
finite difference LB integrator is used. If {LBtype} is set equal to
|
|
2, the algorithm of "Ollila et al."_#Ollila is used.
|
|
|
|
Physical variables are then defined in terms of moments of the distribution
|
|
functions,
|
|
|
|
:c,image(Eqs/fix_lb_fluid_properties.jpg)
|
|
|
|
Full details of the lattice-Boltzmann algorithm used can be found in
|
|
"Mackay et al."_#Mackay.
|
|
|
|
The fluid is coupled to the MD particles described by {group-ID}
|
|
through a velocity dependent force. The contribution to the fluid
|
|
force on a given lattice mesh site j due to MD particle alpha is
|
|
calculated as:
|
|
|
|
:c,image(Eqs/fix_lb_fluid_fluidforce.jpg)
|
|
|
|
where v_n is the velocity of the MD particle, u_f is the fluid
|
|
velocity interpolated to the particle location, and gamma is the force
|
|
coupling constant. Zeta is a weight assigned to the grid point,
|
|
obtained by distributing the particle to the nearest lattice sites.
|
|
For this, the user has the choice between a trilinear stencil, which
|
|
provides a support of 8 lattice sites, or the immersed boundary method
|
|
Peskin stencil, which provides a support of 64 lattice sites. While
|
|
the Peskin stencil is seen to provide more stable results, the
|
|
trilinear stencil may be better suited for simulation of objects close
|
|
to walls, due to its smaller support. Therefore, by default, the
|
|
Peskin stencil is used; however the user may switch to the trilinear
|
|
stencil by specifying the keyword, {trilinear}.
|
|
|
|
By default, the force coupling constant, gamma, is calculated according to
|
|
|
|
:c,image(Eqs/fix_lb_fluid_gammadefault.jpg).
|
|
|
|
Here, m_v is the mass of the MD particle, m_u is a representative
|
|
fluid mass at the particle location, and dt_collision is a collision
|
|
time, chosen such that tau/dt_collision = 1 (see "Mackay and
|
|
Denniston"_#Mackay2 for full details). In order to calculate m_u, the
|
|
fluid density is interpolated to the MD particle location, and
|
|
multiplied by a volume, node_area*dx_lb, where node_area represents
|
|
the portion of the surface area of the composite object associated
|
|
with a given MD particle. By default, node_area is set equal to
|
|
dx_lb*dx_lb; however specific values for given atom types can be set
|
|
using the {setArea} keyword.
|
|
|
|
The user also has the option of specifying their own value for the
|
|
force coupling constant, for all the MD particles associated with the
|
|
fix, through the use of the {setGamma} keyword. This may be useful
|
|
when modelling porous particles. See "Mackay et al."_#Mackay for a
|
|
detailed description of the method by which the user can choose an
|
|
appropriate gamma value.
|
|
|
|
IMPORTANT NOTE: while this fix applies the force of the particles on
|
|
the fluid, it does not apply the force of the fluid to the particles.
|
|
When the force coupling constant is set using the default method,
|
|
there is only one option to include this hydrodynamic force on the
|
|
particles, and that is through the use of the
|
|
"lb/viscous"_fix_lb_viscous.html fix. This fix adds the hydrodynamic
|
|
force to the total force acting on the particles, after which any of
|
|
the built-in LAMMPS integrators can be used to integrate the particle
|
|
motion. However, if the user specifies their own value for the force
|
|
coupling constant, as mentioned in "Mackay et al."_#Mackay, the
|
|
built-in LAMMPS integrators may prove to be unstable. Therefore, we
|
|
have included our own integrators "fix
|
|
lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, and "fix
|
|
lb/pc"_fix_lb_pc.html, to solve for the particle motion in these
|
|
cases. These integrators should not be used with the
|
|
"lb/viscous"_fix_lb_viscous.html fix, as they add hydrodynamic forces
|
|
to the particles directly. In addition, they can not be used if the
|
|
force coupling constant has been set the default way.
|
|
|
|
IMPORTANT NOTE: if the force coupling constant is set using the
|
|
default method, and the "lb/viscous"_fix_lb_viscous.html fix is NOT
|
|
used to add the hydrodynamic force to the total force acting on the
|
|
particles, this physically corresponds to a situation in which an
|
|
infinitely massive particle is moving through the fluid (since
|
|
collisions between the particle and the fluid do not act to change the
|
|
particle's velocity). Therefore, the user should set the mass of the
|
|
particle to be significantly larger than the mass of the fluid at the
|
|
particle location, in order to approximate an infinitely massive
|
|
particle (see the dragforce test run for an example).
|
|
|
|
:line
|
|
|
|
Inside the fix, parameters are scaled by the lattice-Boltzmann
|
|
timestep, dt, grid spacing, dx, and mass unit, dm. dt is set equal to
|
|
(nevery*dt_MD), where dt_MD is the MD timestep. By default, dm is set
|
|
equal to 1.0, and dx is chosen so that tau/(dt) =
|
|
(3*eta*dt)/(rho*dx^2) is approximately equal to 1. However, the user
|
|
has the option of specifying their own values for dm, and dx, by using
|
|
the optional keywords {dm}, and {dx} respectively.
|
|
|
|
IMPORTANT NOTE: Care must be taken when choosing both a value for dx,
|
|
and a simulation domain size. This fix uses the same subdivision of
|
|
the simulation domain among processors as the main LAMMPS program. In
|
|
order to uniformly cover the simulation domain with lattice sites, the
|
|
lengths of the individual LAMMPS subdomains must all be evenly
|
|
divisible by dx. If the simulation domain size is cubic, with equal
|
|
lengths in all dimensions, and the default value for dx is used, this
|
|
will automatically be satisfied.
|
|
|
|
Physical parameters describing the fluid are specified through
|
|
{viscosity}, {density}, and {a0}. If the force coupling constant is
|
|
set the default way, the surface area associated with the MD particles
|
|
is specified using the {setArea} keyword. If the user chooses to
|
|
specify a value for the force coupling constant, this is set using the
|
|
{setGamma} keyword. These parameters should all be given in terms of
|
|
the mass, distance, and time units chosen for the main LAMMPS run, as
|
|
they are scaled by the LB timestep, lattice spacing, and mass unit,
|
|
inside the fix.
|
|
|
|
:line
|
|
|
|
The {setArea} keyword allows the user to associate a surface area with
|
|
a given atom type. For example if a spherical composite object of
|
|
radius R is represented as a spherical shell of N evenly distributed
|
|
MD particles, all of the same type, the surface area per particle
|
|
associated with that atom type should be set equal to 4*pi*R^2/N.
|
|
This keyword should only be used if the force coupling constant,
|
|
gamma, is set the default way.
|
|
|
|
The {setGamma} keyword allows the user to specify their own value for
|
|
the force coupling constant, gamma, instead of using the default
|
|
value.
|
|
|
|
The {scaleGamma} keyword should be used in conjunction with the
|
|
{setGamma} keyword, when the user wishes to specify different gamma
|
|
values for different atom types. This keyword allows the user to
|
|
scale the {setGamma} gamma value by a factor, gammaFactor, for a given
|
|
atom type.
|
|
|
|
The {dx} keyword allows the user to specify a value for the LB grid
|
|
spacing.
|
|
|
|
The {dm} keyword allows the user to specify the LB mass unit.
|
|
|
|
If the {a0} keyword is used, the value specified is used for the
|
|
square of the speed of sound in the fluid. If this keyword is not
|
|
present, the speed of sound squared is set equal to (1/3)*(dx/dt)^2.
|
|
Setting a0 > (dx/dt)^2 is not allowed, as this may lead to
|
|
instabilities.
|
|
|
|
If the {noise} keyword is used, followed by a a positive temperature
|
|
value, and a positive integer random number seed, a thermal
|
|
lattice-Boltzmann algorithm is used. If {LBtype} is set equal to 1
|
|
(i.e. the standard LB integrator is chosen), the thermal LB algorithm
|
|
of "Adhikari et al."_#Adhikari is used; however if {LBtype} is set
|
|
equal to 2 both the LB integrator, and thermal LB algorithm described
|
|
in "Ollila et al."_#Ollila are used.
|
|
|
|
If the {calcforce} keyword is used, both the fluid force and torque
|
|
acting on the specified particle group are printed to the screen every
|
|
N timesteps.
|
|
|
|
If the keyword {trilinear} is used, the trilinear stencil is used to
|
|
interpolate the particle nodes onto the fluid mesh. By default, the
|
|
immersed boundary method, Peskin stencil is used. Both of these
|
|
interpolation methods are described in "Mackay et al."_#Mackay.
|
|
|
|
If the keyword {D3Q19} is used, the 19 velocity (D3Q19) lattice is
|
|
used by the lattice-Boltzmann algorithm. By default, the 15 velocity
|
|
(D3Q15) lattice is used.
|
|
|
|
If the keyword {write_restart} is used, followed by a positive
|
|
integer, N, a binary restart file is printed every N LB timesteps.
|
|
This restart file only contains information about the fluid.
|
|
Therefore, a LAMMPS restart file should also be written in order to
|
|
print out full details of the simulation.
|
|
|
|
IMPORTANT NOTE: When a large number of lattice grid points are used,
|
|
the restart files may become quite large.
|
|
|
|
In order to restart the fluid portion of the simulation, the keyword
|
|
{read_restart} is specified, followed by the name of the binary
|
|
lb_fluid restart file to be used.
|
|
|
|
If the {zwall_velocity} keyword is used y-velocities are assigned to
|
|
the lower and upper walls. This keyword requires the presence of
|
|
walls in the z-direction. This is set by assigning fixed boundary
|
|
conditions in the z-direction. If fixed boundary conditions are
|
|
present in the z-direction, and this keyword is not used, the walls
|
|
are assumed to be stationary.
|
|
|
|
If the {bodyforce} keyword is used, a constant body force is added to
|
|
the fluid, defined by it's x, y and z components.
|
|
|
|
If the {printfluid} keyword is used, followed by a positive integer, N,
|
|
the fluid densities and velocities at each lattice site are printed to the
|
|
screen every N timesteps.
|
|
|
|
:line
|
|
|
|
For further details, as well as descriptions and results of several
|
|
test runs, see "Mackay et al."_#Mackay. Please include a citation to
|
|
this paper if the lb_fluid fix is used in work contributing to
|
|
published research.
|
|
|
|
:line
|
|
|
|
[Restart, fix_modify, output, run start/stop, minimize info:]
|
|
|
|
Due to the large size of the fluid data, this fix writes it's own
|
|
binary restart files, if requested, independent of the main LAMMPS
|
|
"binary restart files"_restart.html; no information about {lb_fluid}
|
|
is written to the main LAMMPS "binary restart files"_restart.html.
|
|
|
|
None of the "fix_modify"_fix_modify.html options are relevant to this
|
|
fix. No global or per-atom quantities are stored by this fix for
|
|
access by various "output commands"_Section_howto.html#4_15. No
|
|
parameter of this fix can be used with the {start/stop} keywords of
|
|
the "run"_run.html command. This fix is not invoked during "energy
|
|
minimization"_minimize.html.
|
|
|
|
[Restrictions:]
|
|
|
|
This fix is part of the USER-LB package. It is only enabled if LAMMPS
|
|
was built with that package. See the "Making
|
|
LAMMPS"_Section_start.html#start_3 section for more info.
|
|
|
|
This fix can only be used with an orthogonal simulation domain.
|
|
|
|
Walls have only been implemented in the z-direction. Therefore, the
|
|
boundary conditions, as specified via the main LAMMPS boundary command
|
|
must be periodic for x and y, and either fixed or periodic for z.
|
|
Shrink-wrapped boundary conditions are not permitted with this fix.
|
|
|
|
This fix must be used before any of "fix
|
|
lb/viscous"_fix_lb_viscous.html, "fix
|
|
lb/momentum"_fix_lb_momentum.html, "fix
|
|
lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, and/ or "fix
|
|
lb/pc"_fix_lb_pc.html , as the fluid needs to be initialized before
|
|
any of these routines try to access its properties. In addition, in
|
|
order for the hydrodynamic forces to be added to the particles, this
|
|
fix must be used in conjunction with the
|
|
"lb/viscous"_fix_lb_viscous.html fix if the force coupling constant is
|
|
set by default, or either the "lb/viscous"_fix_lb_viscous.html fix or
|
|
one of the "lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html or
|
|
"lb/pc"_fix_lb_pc.html integrators, if the user chooses to specifiy
|
|
their own value for the force coupling constant.
|
|
|
|
[Related commands:]
|
|
|
|
"fix lb/viscous"_fix_lb_viscous.html, "fix
|
|
lb/momentum"_fix_lb_momentum.html, "fix
|
|
lb/rigid/pc/sphere"_fix_lb_rigid_pc_sphere.html, "fix
|
|
lb/pc"_fix_lb_pc.html
|
|
|
|
[Default:]
|
|
|
|
By default, the force coupling constant is set according to
|
|
|
|
:c,image(Eqs/fix_lb_fluid_gammadefault.jpg)
|
|
|
|
and an area of dx_lb^2 per node, used to calculate the fluid mass at
|
|
the particle node location, is assumed.
|
|
|
|
dx is chosen such that tau/(delta t_LB) =
|
|
(3 eta dt_LB)/(rho dx_lb^2) is approximately equal to 1.
|
|
dm is set equal to 1.0.
|
|
a0 is set equal to (1/3)*(dx_lb/dt_lb)^2.
|
|
The Peskin stencil is used as the default interpolation method.
|
|
The D3Q15 lattice is used for the lattice-Boltzmann algorithm.
|
|
If walls are present, they are assumed to be stationary.
|
|
|
|
:line
|
|
|
|
:link(Ollila)
|
|
[(Ollila et al.)] Ollila, S.T.T., Denniston, C., Karttunen, M., and Ala-Nissila, T., Fluctuating lattice-Boltzmann model for complex fluids, J. Chem. Phys. 134 (2011) 064902.
|
|
|
|
:link(Mackay)
|
|
[(Mackay et al.)] Mackay, F. E., Ollila, S.T.T., and Denniston, C., Hydrodynamic Forces Implemented into LAMMPS through a lattice-Boltzmann fluid, Computer Physics Communications 184 (2013) 2021-2031.
|
|
|
|
:link(Mackay2)
|
|
[(Mackay and Denniston)] Mackay, F. E., and Denniston, C., Coupling MD particles to a lattice-Boltzmann fluid through the use of conservative forces, J. Comput. Phys. 237 (2013) 289-298.
|
|
|
|
:link(Adhikari)
|
|
[(Adhikari et al.)] Adhikari, R., Stratford, K., Cates, M. E., and Wagner, A. J., Fluctuating lattice Boltzmann, Europhys. Lett. 71 (2005) 473-479.
|