From 7e2bb9a065368199834f65fb18c1ea180a8a4866 Mon Sep 17 00:00:00 2001 From: Axel Kohlmeyer Date: Sat, 12 Mar 2022 08:43:17 -0500 Subject: [PATCH] reformat and spellcheck the documentation --- doc/src/fix_lb_fluid.rst | 240 +++++++++++++------- doc/utils/sphinx-config/false_positives.txt | 4 + 2 files changed, 161 insertions(+), 83 deletions(-) diff --git a/doc/src/fix_lb_fluid.rst b/doc/src/fix_lb_fluid.rst index 0b473b2847..e2ca5f0fc7 100644 --- a/doc/src/fix_lb_fluid.rst +++ b/doc/src/fix_lb_fluid.rst @@ -63,9 +63,12 @@ Examples Description """"""""""" -Implement a lattice-Boltzmann fluid on a uniform mesh covering the LAMMPS -simulation domain. Note that this fix was updated in 2021 and is not backward compatible with the previous version. If you need the previous version, please download an older version of LAMMPS. The MD particles described by *group-ID* apply a velocity -dependent force to the fluid. +Implement a lattice-Boltzmann fluid on a uniform mesh covering the +LAMMPS simulation domain. Note that this fix was updated in 2021 and is +not backward compatible with the previous version. If you need the +previous version, please download an older version of LAMMPS. 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, @@ -90,23 +93,24 @@ respectively. Here, we have implemented \sigma_{\alpha \beta} = -P_{\alpha \beta} = -\rho a_0 \delta_{\alpha \beta} -with :math:`a_0` set to :math:`\frac{1}{3} \frac{dx}{dt}^2` by default. You should not normally need to change this default. +with :math:`a_0` set to :math:`\frac{1}{3} \frac{dx}{dt}^2` by default. +You should not normally need to change this 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, +distribution functions which evolve according to a velocity discretized +version of the Boltzmann equation, .. math:: \left(\partial_t + e_{i\alpha}\partial_{\alpha}\right)f_i = -\frac{1}{\tau}\left(f_i - f_i^{eq}\right) + W_i where the first term on the right hand side represents a single time -relaxation towards the equilibrium distribution function, and :math:`\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. Physical variables are then defined in terms of moments of the distribution -functions, +relaxation towards the equilibrium distribution function, and +:math:`\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. Physical variables are then +defined in terms of moments of the distribution functions, .. math:: @@ -126,10 +130,12 @@ calculated as: {\bf F}_{j \alpha} = \gamma \left({\bf v}_n - {\bf u}_f \right) \zeta_{j\alpha} where :math:`\mathbf{v}_n` is the velocity of the MD particle, -:math:`\mathbf{u}_f` is the fluid -velocity interpolated to the particle location, and :math:`\gamma` is the force -coupling constant. This force, as with most forces in LAMMPS, and hence the velocities, are calculated at the half-time step. :math:`\zeta` is a weight assigned to the grid point, -obtained by distributing the particle to the nearest lattice sites. +:math:`\mathbf{u}_f` is the fluid velocity interpolated to the particle +location, and :math:`\gamma` is the force coupling constant. This +force, as with most forces in LAMMPS, and hence the velocities, are +calculated at the half-time step. :math:`\zeta` is a weight assigned to +the grid point, obtained by distributing the particle to the nearest +lattice sites. The force coupling constant, :math:`\gamma`, is calculated according to @@ -139,43 +145,49 @@ according to \gamma = \frac{2m_um_v}{m_u+m_v}\left(\frac{1}{\Delta t}\right) Here, :math:`m_v` is the mass of the MD particle, :math:`m_u` is a -representative fluid mass at the particle location, and :math:`\Delta -t` is the time step. The fluid mass :math:`m_u` that the MD particle interacts with is calcuated internally. -This coupling is chosen to constrain the particle and associated fluid velocity to match at the end of the time step. As with other constraints, such as :doc:`shake `, this constraint can remove degrees of freedom from the simulation which are accounted for internally in the algorithm. +representative fluid mass at the particle location, and :math:`\Delta t` +is the time step. The fluid mass :math:`m_u` that the MD particle +interacts with is calculated internally. This coupling is chosen to +constrain the particle and associated fluid velocity to match at the end +of the time step. As with other constraints, such as :doc:`shake +`, this constraint can remove degrees of freedom from the +simulation which are accounted for internally in the algorithm. .. 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. There is only - one option to include this hydrodynamic force on the particles, and - that is through the use of the :doc:`lb/viscous ` 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. If the :doc:`lb/viscous ` - fix is NOT used to add the hydrodynamic force to the total force acting on the particles, this + While this fix applies the force of the particles on the fluid, it + does not apply the force of the fluid to the particles. There is + only one option to include this hydrodynamic force on the particles, + and that is through the use of the :doc:`lb/viscous ` + 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. If the + :doc:`lb/viscous ` 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). In this case, - setting *scaleGamma* to -1 for the corresponding particle type will explicity take this - limit (of infinite particle mass) in computing the force coupling for the fluid force. + particle and the fluid do not act to change the particle's velocity). + In this case, setting *scaleGamma* to -1 for the corresponding + particle type will explicitly take this limit (of infinite particle + mass) in computing the force coupling for the fluid force. ---------- Physical parameters describing the fluid are specified through -*viscosity* and *density*. 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. +*viscosity* and *density*. 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. The *dx* keyword allows the user to specify a value for the LB grid -spacing and the *dm* keyword allows the user to specify the LB mass unit. -Inside the fix, parameters are scaled by the lattice-Boltzmann +spacing and the *dm* keyword allows the user to specify the LB mass +unit. Inside the fix, parameters are scaled by the lattice-Boltzmann timestep, :math:`dt_{LB}`, grid spacing, :math:`dx_{LB}`, and mass unit, :math:`dm_{LB}`. :math:`dt_{LB}` is set equal to -:math:`\mathrm{nevery}\cdot dt_{MD}`, where :math:`dt_{MD}` is the MD timestep. -By default, -:math:`dm_{LB}` is set equal to 1.0, and :math:`dx_{LB}` is chosen so that -:math:`\frac{\tau}{dt} = \frac{3\eta dt}{\rho dx^2}` is approximately equal to 1. +:math:`\mathrm{nevery}\cdot dt_{MD}`, where :math:`dt_{MD}` is the MD +timestep. By default, :math:`dm_{LB}` is set equal to 1.0, and +:math:`dx_{LB}` is chosen so that :math:`\frac{\tau}{dt} = \frac{3\eta +dt}{\rho dx^2}` is approximately equal to 1. .. note:: @@ -192,16 +204,23 @@ If the *noise* keyword is used, followed by a positive temperature value, and a positive integer random number seed, the thermal LB algorithm of :ref:`Adhikari et al. ` is used. -If the keyword *stencil* is used, the value sets the number of interpolation points -used in each direction. For this, the user has the choice between a trilinear stencil (*stencil* 2), which -provides a support of 8 lattice sites, or the 3-point immersed boundary method -stencil (*stencil* 3), which provides a support of 27 lattice sites, or the 4-point Keys' interpolation stencil (stencil 4), which provides a support of 64 lattice sites. The trilinear stencil is the default as it is better suited for simulation of objects close to walls or other objects, due to its smaller support. The 3-point stencil provides smoother motion of the lattice and is suitable for particles not likely to be to close to walls or other objects. +If the keyword *stencil* is used, the value sets the number of +interpolation points used in each direction. For this, the user has the +choice between a trilinear stencil (*stencil* 2), which provides a +support of 8 lattice sites, or the 3-point immersed boundary method +stencil (*stencil* 3), which provides a support of 27 lattice sites, or +the 4-point Keys' interpolation stencil (stencil 4), which provides a +support of 64 lattice sites. The trilinear stencil is the default as it +is better suited for simulation of objects close to walls or other +objects, due to its smaller support. The 3-point stencil provides +smoother motion of the lattice and is suitable for particles not likely +to be to close to walls or other objects. -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. +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. .. note:: @@ -219,8 +238,14 @@ 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 *pressurebcx* keyword is used, a pressure jump (implemented by a step jump in density) -is imposed at the (periodic) x-boundary. The value set specifies what would be the resulting equilibrium average pressure gradient in the x-direction if the system had a constant cross-section (i.e. resistance to flow). It is converted to a pressure jump by multiplication by the system size in the x-direction. As this value should normally be quite small, it is also assumed to be scaled by 1000. +If the *pressurebcx* keyword is used, a pressure jump (implemented by a +step jump in density) is imposed at the (periodic) x-boundary. The +value set specifies what would be the resulting equilibrium average +pressure gradient in the x-direction if the system had a constant +cross-section (i.e. resistance to flow). It is converted to a pressure +jump by multiplication by the system size in the x-direction. As this +value should normally be quite small, it is also assumed to be scaled +by 1000. If the *bodyforce* keyword is used, a constant body force is added to the fluid, defined by it's x, y and z components. @@ -229,24 +254,50 @@ 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 *dumpxdmf* keyword is used, followed by a positive integer, N, and a file name, the fluid densities and velocities at each lattice site are output to an xdmf file every N timesteps. This is a binary file format that can be read by visualization packages such as `Paraview `_ . The xdmf file format contains a time index for each frame dump and the value timeI = 1 uses simulation time while 0 uses the output frame number to index xdmf file. The later can be useful if the :doc:`dump vtk ` command is used to output the particle positions at the same timesteps and you want to visualize both the fluid and particle data together in `Paraview `_ . +If the *dumpxdmf* keyword is used, followed by a positive integer, N, +and a file name, the fluid densities and velocities at each lattice site +are output to an xdmf file every N timesteps. This is a binary file +format that can be read by visualization packages such as `Paraview +`_ . The xdmf file format contains a time +index for each frame dump and the value timeI = 1 uses simulation time +while 0 uses the output frame number to index xdmf file. The later can +be useful if the :doc:`dump vtk ` command is used to output +the particle positions at the same timesteps and you want to visualize +both the fluid and particle data together in `Paraview +`_ . -The *scaleGamma* keyword allows the user to -scale the :math:`\gamma` value by a factor, gammaFactor, -for a given atom type. Setting *scaleGamma* to -1 for the corresponding particle type -will explicity take the limit of infinite particle mass in computing the force coupling for the fluid force (see note above). +The *scaleGamma* keyword allows the user to scale the :math:`\gamma` +value by a factor, gammaFactor, for a given atom type. Setting +*scaleGamma* to -1 for the corresponding particle type will explicitly +take the limit of infinite particle mass in computing the force coupling +for the fluid force (see note above). -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 -:math:`\frac{1}{3}\left(\frac{dx_{LB}}{dt_{LB}}\right)^2`. -Setting :math:`a0 > (\frac{dx_{LB}}{dt_{LB}})^2` is not allowed, -as this may lead to instabilities. As the speed of sound should usually be -much larger than any fluid velocity of interest, its value does not normally have -a significant impact on the results. As such, it is usually best to use the default -for this option. +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 +:math:`\frac{1}{3}\left(\frac{dx_{LB}}{dt_{LB}}\right)^2`. Setting +:math:`a0 > (\frac{dx_{LB}}{dt_{LB}})^2` is not allowed, as this may +lead to instabilities. As the speed of sound should usually be much +larger than any fluid velocity of interest, its value does not normally +have a significant impact on the results. As such, it is usually best +to use the default for this option. -The *npits* keyword (followed by integer arguments: npits, h_p, l_p, l_pp, l_e) sets the fluid domain to the pits geometry. These arguments should only be used if you actually want something more complex than a rectangular/cubic geometry. The npits value sets the number of pits regions (arranged along x). The remaining arguments are sizes measured in multiples of dx_lb: h_p is the z-height of the pit regions, l_p is the x-length of the pit regions, l_pp is the length of the region between consecutive pits (referred to as a "slit" region), and l_e is the x-length of the slit regions at each end of the channel. The pit geometry must fill the system in the x-direction but can be longer, in which case it is truncated (which enables asymmetric entrance/exit end sections). The additional *wp* keyword allows the width (in y-direction) of the pit to be specified (the default is full width) and the *sw* keyword indicates that there should be sidewalls in the y-direction (default is periodic in y-direction). These parameters are illustrated below:: +The *npits* keyword (followed by integer arguments: npits, h_p, l_p, +l_pp, l_e) sets the fluid domain to the pits geometry. These arguments +should only be used if you actually want something more complex than a +rectangular/cubic geometry. The npits value sets the number of pits +regions (arranged along x). The remaining arguments are sizes measured +in multiples of dx_lb: h_p is the z-height of the pit regions, l_p is +the x-length of the pit regions, l_pp is the length of the region +between consecutive pits (referred to as a "slit" region), and l_e is +the x-length of the slit regions at each end of the channel. The pit +geometry must fill the system in the x-direction but can be longer, in +which case it is truncated (which enables asymmetric entrance/exit end +sections). The additional *wp* keyword allows the width (in +y-direction) of the pit to be specified (the default is full width) and +the *sw* keyword indicates that there should be sidewalls in the +y-direction (default is periodic in y-direction). These parameters are +illustrated below:: Sideview (in xz plane) of pit geometry: ______________________________________________________________________ @@ -275,13 +326,12 @@ The *npits* keyword (followed by integer arguments: npits, h_p, l_p, l_pp, l_e) |__________| v - ---------- -For further details, as well as descriptions and results of several -test runs, see :ref:`Denniston et al. `. Please include a citation to -this paper if the lb_fluid fix is used in work contributing to -published research. +For further details, as well as descriptions and results of several test +runs, see :ref:`Denniston et al. `. Please include a +citation to this paper if the lb_fluid fix is used in work contributing +to published research. ---------- @@ -296,31 +346,55 @@ is written to the main LAMMPS :doc:`binary restart files `. None of the :doc:`fix_modify ` options are relevant to this fix. -The fix computes a global scalar which can be accessed by various :doc:`output commands `. The scalar is the current temperature of the group of particles described by *group-ID* along with the fluid constrained to move with them. The temperature is computed via the kinetic energy of the group and fluid constrained to move with them and the total number of degrees of freedom (calculated internally). If the particles are not integrated independently (such as via :doc:`fix NVE `) but have additional constraints imposed on them (such as via integration using :doc:`fix rigid `) the degrees of freedom removed from these additional constraints will not be properly accounted for. In this case, the user can specify the total degrees of freedom independently using the *dof* keyword. +The fix computes a global scalar which can be accessed by various +:doc:`output commands `. The scalar is the current +temperature of the group of particles described by *group-ID* along with +the fluid constrained to move with them. The temperature is computed via +the kinetic energy of the group and fluid constrained to move with them +and the total number of degrees of freedom (calculated internally). If +the particles are not integrated independently (such as via :doc:`fix +NVE `) but have additional constraints imposed on them (such as +via integration using :doc:`fix rigid `) the degrees of +freedom removed from these additional constraints will not be properly +accounted for. In this case, the user can specify the total degrees of +freedom independently using the *dof* keyword. -The fix also computes a global array of values which can be accessed by various :doc:`output commands `. There are 5 entries in the array. The first entry is the temperature of the fluid, the second entry is the total mass of the fluid plus particles, the third through fifth entries give the x, y, and z total momentum of the fluid plus particles. +The fix also computes a global array of values which can be accessed by +various :doc:`output commands `. There are 5 entries in +the array. The first entry is the temperature of the fluid, the second +entry is the total mass of the fluid plus particles, the third through +fifth entries give the x, y, and z total momentum of the fluid plus +particles. -No parameter of this fix can be used with the *start/stop* keywords of the -:doc:`run ` command. This fix is not invoked during :doc:`energy minimization `. +No parameter of this fix can be used with the *start/stop* keywords of +the :doc:`run ` command. This fix is not invoked during +:doc:`energy minimization `. Restrictions """""""""""" This fix is part of the LATBOLTZ package. It is only enabled if LAMMPS -was built with that package. See the :doc:`Build package ` page for more info. +was built with that package. See the :doc:`Build package +` page for more info. This fix can only be used with an orthogonal simulation domain. -The boundary conditions for the fluid are specified independently to the particles. However, these should normally be specified consistently via the main LAMMPS :doc:`boundary ` command (p p p, p p f, and p f f are the only consistent possibilities). -Shrink-wrapped boundary conditions are not permitted with this fix. +The boundary conditions for the fluid are specified independently to the +particles. However, these should normally be specified consistently via +the main LAMMPS :doc:`boundary ` command (p p p, p p f, and p +f f are the only consistent possibilities). Shrink-wrapped boundary +conditions are not permitted with this fix. -This fix must be used before any of :doc:`fix lb/viscous ` and :doc:`fix lb/momentum ` 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 +This fix must be used before any of :doc:`fix lb/viscous +` and :doc:`fix lb/momentum ` 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 :doc:`lb/viscous ` fix. -This fix needs to be used in conjuntion with a standard LAMMPS integrator such as :doc:`fix NVE ` or :doc:`fix rigid `. +This fix needs to be used in conjunction with a standard LAMMPS +integrator such as :doc:`fix NVE ` or :doc:`fix rigid +`. Related commands """""""""""""""" diff --git a/doc/utils/sphinx-config/false_positives.txt b/doc/utils/sphinx-config/false_positives.txt index e033b9088f..ac4dceed65 100644 --- a/doc/utils/sphinx-config/false_positives.txt +++ b/doc/utils/sphinx-config/false_positives.txt @@ -42,6 +42,7 @@ advect advection advects affine +Afrasiabian Afshar agilio Agilio @@ -2291,6 +2292,7 @@ Nmin Nmols nn nnodes +npits nO Nocedal nocite @@ -3319,6 +3321,7 @@ THz Tigran Tij Tildesley +timeI timespan timestamp timestamps @@ -3658,6 +3661,7 @@ xcm Xcm Xcode xCORE +xdmf Xeon xflag xhi