Add wall_flow documentation

doc/src/Bibliography.rst

@@ -877,6 +877,9 @@ Bibliography
 **(PLUMED)**
    G.A. Tribello, M. Bonomi, D. Branduardi, C. Camilloni and G. Bussi, Comp. Phys. Comm 185, 604 (2014)
 
+**(Pavlov)**
+D Pavlov, V Galigerov, D Kolotinskii, V Nikolskiy, V Stegailov, International Journal of High Performance Computing Applications, 38, 34-49 (2024).
+
 **(Paquay)**
    Paquay and Kusters, Biophys. J., 110, 6, (2016). preprint available at `arXiv:1411.3019 <https://arxiv.org/abs/1411.3019/>`_.
 

doc/src/Commands_fix.rst

@@ -262,6 +262,7 @@ OPT.
    * :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>`
    * :doc:`wall/colloid <fix_wall>`
    * :doc:`wall/ees <fix_wall_ees>`
+   * :doc:`wall/flow (k) <fix_wall_flow>`
    * :doc:`wall/gran (k) <fix_wall_gran>`
    * :doc:`wall/gran/region <fix_wall_gran_region>`
    * :doc:`wall/harmonic <fix_wall>`

doc/src/fix.rst

@@ -427,6 +427,7 @@ accelerated styles exist.
 * :doc:`wall/body/polyhedron <fix_wall_body_polyhedron>` - time integration for body particles of style :doc:`rounded/polyhedron <Howto_body>`
 * :doc:`wall/colloid <fix_wall>` - Lennard-Jones wall interacting with finite-size particles
 * :doc:`wall/ees <fix_wall_ees>` - wall for ellipsoidal particles
+* :doc:`wall/flow <fix_wall_flow>` - flow boundary conditions
 * :doc:`wall/gran <fix_wall_gran>` - frictional wall(s) for granular simulations
 * :doc:`wall/gran/region <fix_wall_gran_region>` - :doc:`fix wall/region <fix_wall_region>` equivalent for use with granular particles
 * :doc:`wall/harmonic <fix_wall>` - harmonic spring wall

doc/src/fix_wall_flow.rst

@@ -0,0 +1,123 @@
+.. index:: fix wall/flow
+.. index:: fix wall/flow/kk
+
+fix wall/flow command
+=====================
+
+Accelerator Variants: *wall/flow/kk*
+
+Syntax
+""""""
+
+.. code-block:: LAMMPS
+
+   fix ID group-ID wall/flow ax vf T seed N coords...
+
+* ID, group-ID are documented in :doc:`fix <fix>` command
+* wall/flow = style name of this fix command
+* ax = flow axis (*x*, *y*, or *z* character)
+* vf = *ax* component of generated flow velocity
+* T = flow temperature (temperature units)
+* seed = random seed for stochasticity (positive integer)
+* N = number of walls (positive integer)
+* coords = set of N wall coordinates (box units) along *ax* axis arranged in ascending order. Note that an additional implicit wall is introduced at the boundary of the simulation domain, so the resulting system always has N+1 walls.
+
+Examples
+""""""""
+
+.. code-block:: LAMMPS
+
+   fix 1 g_flow wall/flow x ${VFLOW} ${TEMP} 123 ${nwall} ${w1} ${w2} ${w3} ${w4}
+   fix 2 all wall/flow 0.4 0.2 3 1 400
+
+Description
+"""""""""""
+
+This fix implements flow boundary conditions (FBC) introduced in :ref:`(Pavlov) <fbc-Pavlov1>` and :ref:`(Pavlov) <fbc-Pavlov2>`.
+The goal is to generate a stationary flow with a shifted Maxwell velocity distribution:
+
+.. math::
+
+   f_z(v_z) \propto \exp{\left(-\frac{m (v_z-v_{\text{flow}})^2}{2 k T}\right)}
+
+This is achieved by reassigning the velocity of each particle that passes a wall.
+Such reassigning represents an emission of a new particle into the system with
+simultaneous removal of a particle with the same position.
+The parallel velocity components parallel to the wall are re-assigned according
+to the Maxwell velocity distribution. The perpendicular component is assigned
+according to the following velocity distribution:
+
+.. math::
+
+   f_{\text{z generated}}(v_z) \propto v_z f_z(v_z)
+
+It can be shown that in an ideal-gas scenario this makes the velocity
+distribution of particles between walls exactly as desired.
+
+Since in most cases simulated systems are not ideal gas,
+the need for multiple walls might arise, as a single wall may not be
+sufficient for maintaining a stationary flow without congestions
+manifesting as areas with increased density located upstream from static obstacles.
+
+For the same reason, the actual temperature and velocity of the generated
+flow may differ from ones requested. The degree of such discrepancy is determined
+by how different from the ideal gas the simulated system is. Therefore, a calibration procedure is required for each system as described in :ref:`(Pavlov) <fbc-Pavlov2>`.
+
+The interactions between particles on different sides of a wall are not disabled or neglected and the
+particle positions aren't affected by the velocity reassignment.
+This removes the need to modify the force field to work correctly in cases when a particle is close
+to a wall (for example, if particle positions were uniformly redistributed across the surface of the wall,
+two particles could end up too close to each other, potentially causing the simulation to explode).
+However due to this compromise, some collective phenomena such as areas with increased/decreased density
+or collective movements are not fully removed when particles cross a wall.
+This unwanted consequence can also be potentially mitigated by using more than one wall.
+
+
+----------
+
+Note that when high flow velocity is reached, a lost atoms error may
+occur (see :doc:`error messages <Errors_messages>`).
+If this message appears when using this fix, you can, for example, reduce the frequency of the
+neighbor list rebuild via :doc:`neigh_modify <neigh_modify>` command.
+
+Restart, fix_modify, output, run start/stop, minimize info
+"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+
+No information about this fix is written to :doc:`binary restart files <restart>`.
+
+None of the :doc:`fix_modify <fix_modify>` options are relevant to
+this fix.
+
+No global or per-atom quantities are stored by this fix for access by
+various :doc:`output commands <Howto_output>`.
+
+No parameter of this fix can be used with the *start/stop* keywords of
+the :doc:`run <run>` command.
+
+This fix is not invoked during :doc:`energy minimization <minimize>`.
+
+Restrictions
+""""""""""""
+
+Flow boundary conditions should not be used with rigid bodies such as those
+defined by a "fix rigid" command.
+
+Related commands
+""""""""""""""""
+
+:doc:`fix wall/reflect <fix_wall>` command
+
+Default
+"""""""
+
+none
+
+----------
+
+.. _fbc-Pavlov1:
+
+**(Pavlov)** Pavlov, Kolotinskii, Stegailov, “GPU-Based Molecular Dynamics of Turbulent Liquid Flows with OpenMM”, In: Proceedings of PPAM-2022, LNCS (Springer), vol. 13826, pp. 346–358 (2023)
+
+.. _fbc-Pavlov2:
+
+**(Pavlov)** Pavlov, Galigerov, Kolotinskii, Nikolskiy, Stegailov, "GPU-based Molecular Dynamics of Fluid Flows: Reaching for Turbulence”, Int. J. High Perf. Comp. Appl., (2024)