From e1411847dd1a08e34f45235485d53960648712bf Mon Sep 17 00:00:00 2001 From: rzaman64 Date: Fri, 10 Oct 2025 01:01:38 -0400 Subject: [PATCH 1/7] Add initial fix_lb_multicomponent documentation --- doc/src/fix-lb-multicomponent.rst | 124 ++++++++++++++++++++++++++++++ 1 file changed, 124 insertions(+) create mode 100644 doc/src/fix-lb-multicomponent.rst diff --git a/doc/src/fix-lb-multicomponent.rst b/doc/src/fix-lb-multicomponent.rst new file mode 100644 index 00000000000..dfed0f79abf --- /dev/null +++ b/doc/src/fix-lb-multicomponent.rst @@ -0,0 +1,124 @@ +.. _fix_lb_multicomponent: + +# fix lb/multicompon ent command + +## Syntax +:: + +.. parsed-literal:: + + fix ID group-ID lb/multicomponent keyword values +* ID, group-ID are documented in :doc:`fix ` command +* lb/multicomponent = style name of this fix command +* keyword = `init` followed by initialization style and parameters +* additional parameters are specified internally in the fix + +`fix ID group-ID lb/multicomponent keyword values ...` + +## Examples +:: +`fix 1 all lb/multicomponent init mixture` +`fix 2 fluid lb/multicomponent init droplet radius 10.0` + +## Description + +.. versionadded:: 2024 + +`fix lb/multicomponent` implements a **ternary lattice Boltzmann model (LBM)** for simulating multicomponent fluid mixtures in three dimensions. This fix is an extension of the single-component `fix lb/fluid`, designed to capture more complex interfacial and phase behaviors such as droplets, emulsions, and films involving **three interacting fluid components.** + +The algorithm evolves three coupled distribution functions over a D3Q19 lattice +and models thermodynamic interactions via chemical potentials and free-energy +gradients. The model is suitable for studying **phase separation, interface +dynamics, droplet stability, and multiphase coexistence. + +The implementation follows the work described in: + +- Arumugam Kumar et al., "Implementation of a Ternary Lattice Boltzmann Model in LAMMPS," _J. Comput. Phys._ (2024). + +## Model Overview (IN PROGRESS) +The fix advances ternary order parameters :math:`\rho`, :math:`\phi`, :math:`\psi` +according to the lattice Boltzmann equation on a D3Q19 velocity lattice: + +**(IN WORKS)** +(insert update rule that makes the whole ternary lattice Boltzmann model work) +- ex). how each fluid component’s probability distribution changes from one timestep to the next, balancing free streaming, relaxation toward equilibrium, and forces due to interactions +- +where :math:`k=1,2,3` corresponds to the three components, :math:`\tau_k` are +relaxation times, and :math:`S_i^k` encodes the thermodynamic forcing derived +from chemical potentials. + +The conserved order parameters are recovered as: + +.. math:: + + ``` + \rho &= C_1 + C_2 + C_3 = 1 \\ + \phi &= C_1 - C_2 \\ + \psi &= C_3 + ``` + +with :math:`C_1, C_2, C_3` denoting component concentrations. +## Keywords + +The `init` keyword specifies the initial configuration of the ternary system, and specifies the initial configuration of the ternary system. Based on the initial configuration, respective initialization parameters must also be provided (which are marked in `<>`). The supported initialization methods include: + +- `init mixture` — uniform random mixture of components 1, 2, 3. + +- `init droplet radius ` — a spherical droplet of radius R units of one component immersed in a immiscible bath of another component. The location of the droplet is at the center of the box. + +- `init liquid_lens radius ` — two adjacent droplets + +- `init double_emulsion radius ` — Double Emulsion with Janus template i.e., two droplets sharing an interface, immersed in a solvent. The double emulsion droplets are composed of component 1 and component 2, with each sphere having radius R. The solvent is composed purely of component 3. The location of the droplet is at the center of the box. + +- `init film thickness ` — Film of thickness "th" with components 1 and 2 with volume fraction C1_film, C2_film occupying the box center (along z direction). The rest of the box are occupied by component 3. + +- `init mixed_droplet radius ` — a spherical droplet of radius R units comprised of the two components 1 and 2, with volume fraction of C1 and C2,  immersed in  component 3. The location of the droplet is located at the center of the box. + +## Parameters + +This fix accepts several internal parameters specified in the source code: + +- `tau_r`, `tau_p`, `tau_s` — relaxation times for each component + +- `gamma_p`, `gamma_s` — parameters controlling the mobility of the phase variables phi, psi + +- `kappa_i` — parameters controlling the surface tension + +- `C1`, `C2`, `C3` — component concentrations or volume fraction (as density of the system is fixed to be 1) + +Future versions may allow passing these directly via input script. + +## Output + +This fix can output spatial fields such as: + +- Density fields for ternary phase variables (**rho, phi, psi**). These phase variables can be reverted back to `C1`, `C2`, `C3` by through some algebraic operation. + +- Pressure field + +- Velocity along x, y, z directions + +The fix supports output in `.xdmf` and `.raw` format which can then be post-processed and visualized using Paraview. + +## Restrictions + +- This fix requires MPI and cannot be compiled with MPI_STUBS. + +- Uses D3Q19 velocity vector space - can simulation 3D/pseudo 2D geometry + +- Currently does **not support coupling to molecular dynamics particles** + +## Related commands + +- `fix lb/fluid` + +## Default +None. +## Contact +Ternary model implementation: + +- Ulf D. Schiller [uschiller@mailaps.org](mailto:uschiller@mailaps.org) +- Fang Wang [fwang8@clemson.edu](mailto:fwang8@clemson.edu) +- Gokul Raman Arumugam Kumar akgokulraman@gmail.com + +.. NOTE:: Inline LaTeX-style equations for chemical potentials and free energy may be added in a future version for theoretical clarity. \ No newline at end of file From 2e0e6a39e00a18b1cee941a2f47f497d17a76d9f Mon Sep 17 00:00:00 2001 From: rzaman64 Date: Fri, 17 Oct 2025 00:44:34 -0400 Subject: [PATCH 2/7] Add documentation for fix_lb_multicomponent --- doc/src/fix-lb-multicomponent.rst | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/doc/src/fix-lb-multicomponent.rst b/doc/src/fix-lb-multicomponent.rst index dfed0f79abf..6241c81d5ac 100644 --- a/doc/src/fix-lb-multicomponent.rst +++ b/doc/src/fix-lb-multicomponent.rst @@ -62,17 +62,17 @@ with :math:`C_1, C_2, C_3` denoting component concentrations. The `init` keyword specifies the initial configuration of the ternary system, and specifies the initial configuration of the ternary system. Based on the initial configuration, respective initialization parameters must also be provided (which are marked in `<>`). The supported initialization methods include: -- `init mixture` — uniform random mixture of components 1, 2, 3. +- `init mixture` — uniform random mixture of components 1, 2, 3. x - `init droplet radius ` — a spherical droplet of radius R units of one component immersed in a immiscible bath of another component. The location of the droplet is at the center of the box. -- `init liquid_lens radius ` — two adjacent droplets +- `init liquid_lens radius ` — - `init double_emulsion radius ` — Double Emulsion with Janus template i.e., two droplets sharing an interface, immersed in a solvent. The double emulsion droplets are composed of component 1 and component 2, with each sphere having radius R. The solvent is composed purely of component 3. The location of the droplet is at the center of the box. - `init film thickness ` — Film of thickness "th" with components 1 and 2 with volume fraction C1_film, C2_film occupying the box center (along z direction). The rest of the box are occupied by component 3. -- `init mixed_droplet radius ` — a spherical droplet of radius R units comprised of the two components 1 and 2, with volume fraction of C1 and C2,  immersed in  component 3. The location of the droplet is located at the center of the box. +- `init mixed_droplet radius ` — a spherical droplet of radius R units comprised of the two components 1 and 2, with volume fraction of C1 and C2,  immersed in  component 3. The location of the droplet is located at the center of the box. x ## Parameters @@ -83,8 +83,6 @@ This fix accepts several internal parameters specified in the source code: - `gamma_p`, `gamma_s` — parameters controlling the mobility of the phase variables phi, psi - `kappa_i` — parameters controlling the surface tension - -- `C1`, `C2`, `C3` — component concentrations or volume fraction (as density of the system is fixed to be 1) Future versions may allow passing these directly via input script. @@ -113,7 +111,23 @@ The fix supports output in `.xdmf` and `.raw` format which can then be post-proc - `fix lb/fluid` ## Default -None. +The default values for optional parameters are: + +* seed = 12345 +* alpha = 1.0 +* C1 = 0.333333 +* C2 = 0.333333 +* C3 = 0.333334 +* kappa1 = 0.01 +* kappa2 = 0.01 +* kappa3 = 0.01 +* tau_r = 1.0 +* tau_p = 1.0 +* tau_s = 0.666667 +* gamma_p = 1.0 +* gamma_s = 1.0 +* init = mixture + ## Contact Ternary model implementation: From 92181581b8fd9bb66dca535e59e63c873cd63570 Mon Sep 17 00:00:00 2001 From: rzaman64 Date: Fri, 17 Oct 2025 01:19:59 -0400 Subject: [PATCH 3/7] Reformatted to RST, added Boundary conditions. --- doc/src/fix-lb-multicomponent.rst | 255 +++++++++++++++++++++--------- 1 file changed, 181 insertions(+), 74 deletions(-) diff --git a/doc/src/fix-lb-multicomponent.rst b/doc/src/fix-lb-multicomponent.rst index 6241c81d5ac..639beb8a001 100644 --- a/doc/src/fix-lb-multicomponent.rst +++ b/doc/src/fix-lb-multicomponent.rst @@ -1,53 +1,89 @@ -.. _fix_lb_multicomponent: +.. index:: fix lb/multicomponent -# fix lb/multicompon ent command +fix lb/multicomponent command +============================== -## Syntax -:: +Syntax +"""""" .. parsed-literal:: - fix ID group-ID lb/multicomponent keyword values * ID, group-ID are documented in :doc:`fix ` command * lb/multicomponent = style name of this fix command -* keyword = `init` followed by initialization style and parameters -* additional parameters are specified internally in the fix +* nevery = update the lattice-Boltzmann fluid every this many timesteps (should normally be 1) +* viscosity = the fluid viscosity (units of mass/(time\*length)) +* density = the initial fluid density +* D3Q19 = velocity lattice model (required) +* dx = keyword for lattice spacing +* dx_value = the lattice-Boltzmann grid spacing +* zero or more keyword/value pairs may be appended +* keyword = *tau_r* or *tau_p* or *tau_s* or *kappa1* or *kappa2* or *kappa3* or *alpha* or *gamma_p* or *gamma_s* or *C1* or *C2* or *C3* or *dumpxdmf* or *seed* or *init* + + .. parsed-literal:: + + *tau_r* value = relaxation time for momentum transport (related to viscosity) + *tau_p* value = relaxation time for order parameter φ transport + *tau_s* value = relaxation time for order parameter ψ transport + *kappa1* value = surface tension parameter between components C1 and C2 + *kappa2* value = surface tension parameter between components C1 and C3 + *kappa3* value = surface tension parameter for component C3 + *alpha* value = gradient energy coefficient + *gamma_p* value = mobility coefficient for order parameter φ + *gamma_s* value = mobility coefficient for order parameter ψ + *C1* value = bulk concentration of component 1 + *C2* value = bulk concentration of component 2 + *C3* value = bulk concentration of component 3 (note: C1 + C2 + C3 = 1) + *dumpxdmf* values = N filename timeI + N = output fluid fields every N timesteps + filename = base name for output files (.xdmf and .raw extensions added automatically) + timeI = 1 (use simulation time to index xdmf file), 0 (use output frame number) + *seed* value = random number generator seed (positive integer) + *init* values = initialization_method [method_parameters] + initialization_method = *mixture* or *droplet* or *liquid_lens* or *double_emulsion* or *film* or *mixed_droplet* + *mixture* = homogeneous mixture with random fluctuations + *droplet* radius = binary droplet (C1 and C2) of given radius in C3 solvent + *liquid_lens* radius = lens of C3 with given radius between C1 and C2 layers + *double_emulsion* radius = Janus droplet (C1 and C2 hemispheres) of given radius in C3 solvent + *film* thickness C1_film C2_film = ternary film with specified thickness and composition + *mixed_droplet* radius C1_drop C2_drop = ternary droplet with specified radius and composition in bulk + + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix 1 all lb/multicomponent 1 0.166667 1.0 D3Q19 dx 1.0 init mixture + fix 2 fluid lb/multicomponent 1 0.166667 1.0 D3Q19 dx 1.0 init droplet 10.0 + fix 3 all lb/multicomponent 1 0.166667 1.0 D3Q19 dx 1.0 C1 0.333333 C2 0.333333 C3 0.333334 kappa1 0.01 kappa2 0.02 kappa3 0.05 init mixture dumpxdmf 1000 output 0 + +Description +""""""""""" -`fix ID group-ID lb/multicomponent keyword values ...` +.. versionadded:: 2024 -## Examples -:: -`fix 1 all lb/multicomponent init mixture` -`fix 2 fluid lb/multicomponent init droplet radius 10.0` +The **fix lb/multicomponent** command implements a ternary lattice Boltzmann model (LBM) for simulating multicomponent fluid mixtures in three dimensions. This fix is an extension of the single-component :doc:`fix lb/fluid `, designed to capture more complex interfacial and phase behaviors such as droplets, emulsions, and films involving three interacting fluid components. -## Description +The algorithm evolves three coupled distribution functions over a D3Q19 lattice and models thermodynamic interactions via chemical potentials and free-energy gradients. The model is suitable for studying phase separation, interface dynamics, droplet stability, and multiphase coexistence. -.. versionadded:: 2024 +The implementation follows the work described in Arumugam Kumar et al., "Implementation of a Ternary Lattice Boltzmann Model in LAMMPS," Comput. Phys. Commun. 294, 108898 (2024). + +---------- -`fix lb/multicomponent` implements a **ternary lattice Boltzmann model (LBM)** for simulating multicomponent fluid mixtures in three dimensions. This fix is an extension of the single-component `fix lb/fluid`, designed to capture more complex interfacial and phase behaviors such as droplets, emulsions, and films involving **three interacting fluid components.** +**Model Overview** -The algorithm evolves three coupled distribution functions over a D3Q19 lattice -and models thermodynamic interactions via chemical potentials and free-energy -gradients. The model is suitable for studying **phase separation, interface -dynamics, droplet stability, and multiphase coexistence. +The ternary fluid composition is specified by three concentration fields C₁, C₂, and C₃, which are related to conserved order parameters: -The implementation follows the work described in: +.. math:: -- Arumugam Kumar et al., "Implementation of a Ternary Lattice Boltzmann Model in LAMMPS," _J. Comput. Phys._ (2024). + \rho &= C_1 + C_2 + C_3 \\ + \phi &= C_1 - C_2 \\ + \psi &= C_3 -## Model Overview (IN PROGRESS) -The fix advances ternary order parameters :math:`\rho`, :math:`\phi`, :math:`\psi` -according to the lattice Boltzmann equation on a D3Q19 velocity lattice: +where ρ is the total density (approximately constant for incompressible flow), and φ and ψ are order parameters that distinguish the three components. -**(IN WORKS)** -(insert update rule that makes the whole ternary lattice Boltzmann model work) -- ex). how each fluid component’s probability distribution changes from one timestep to the next, balancing free streaming, relaxation toward equilibrium, and forces due to interactions -- -where :math:`k=1,2,3` corresponds to the three components, :math:`\tau_k` are -relaxation times, and :math:`S_i^k` encodes the thermodynamic forcing derived -from chemical potentials. +The time evolution is described by three sets of distribution functions (f, g, h) that evolve according to the Bhatnagar-Gross-Krook (BGK) lattice Boltzmann equation: -The conserved order parameters are recovered as: .. math:: @@ -60,57 +96,117 @@ The conserved order parameters are recovered as: with :math:`C_1, C_2, C_3` denoting component concentrations. ## Keywords -The `init` keyword specifies the initial configuration of the ternary system, and specifies the initial configuration of the ternary system. Based on the initial configuration, respective initialization parameters must also be provided (which are marked in `<>`). The supported initialization methods include: +---------- -- `init mixture` — uniform random mixture of components 1, 2, 3. x - -- `init droplet radius ` — a spherical droplet of radius R units of one component immersed in a immiscible bath of another component. The location of the droplet is at the center of the box. - -- `init liquid_lens radius ` — - -- `init double_emulsion radius ` — Double Emulsion with Janus template i.e., two droplets sharing an interface, immersed in a solvent. The double emulsion droplets are composed of component 1 and component 2, with each sphere having radius R. The solvent is composed purely of component 3. The location of the droplet is at the center of the box. - -- `init film thickness ` — Film of thickness "th" with components 1 and 2 with volume fraction C1_film, C2_film occupying the box center (along z direction). The rest of the box are occupied by component 3. - -- `init mixed_droplet radius ` — a spherical droplet of radius R units comprised of the two components 1 and 2, with volume fraction of C1 and C2,  immersed in  component 3. The location of the droplet is located at the center of the box. x +**Initialization Methods** -## Parameters +The *init* keyword specifies how the ternary fluid is initialized: -This fix accepts several internal parameters specified in the source code: +* **mixture**: Creates a homogeneous mixture with bulk concentrations C1, C2, C3 plus small random fluctuations (±0.01) to seed phase separation. This is the default initialization if no *init* keyword is specified. -- `tau_r`, `tau_p`, `tau_s` — relaxation times for each component - -- `gamma_p`, `gamma_s` — parameters controlling the mobility of the phase variables phi, psi - -- `kappa_i` — parameters controlling the surface tension +* **droplet** *radius*: Creates a binary droplet composed of equal parts C1 and C2 (C3 = 0) with specified radius (in lattice units) centered in the simulation box, surrounded by pure C3. + +* **liquid_lens** *radius*: Creates a lens-shaped droplet of pure C3 with specified radius positioned at the interface between horizontal layers of pure C1 (top half) and pure C2 (bottom half). + +* **double_emulsion** *radius*: Creates a Janus-type double emulsion with a droplet of specified radius split into two hemispheres: left hemisphere of pure C1 and right hemisphere of pure C2, surrounded by pure C3 solvent. + +* **film** *thickness* *C1_film* *C2_film*: Creates a horizontal film of specified thickness (as a fraction of the box height) centered in the simulation box with composition C1_film, C2_film, C3_film = 1 - C1_film - C2_film, surrounded by bulk mixture. Small random fluctuations (±0.01) are added to seed phase separation. + +* **mixed_droplet** *radius* *C1_drop* *C2_drop*: Creates a ternary droplet with specified radius and composition (C1_drop, C2_drop, C3_drop = 1 - C1_drop - C2_drop) surrounded by pure C3 solvent. Small random fluctuations (±0.01) are added within the droplet. + +.. math:: -Future versions may allow passing these directly via input script. + \text{subNbx} = \frac{N_x}{P_x} + 2h_x \\ + \text{subNby} = \frac{N_y}{P_y} + 2h_y \\ + \text{subNbz} = \frac{N_z}{P_z} + 2h_z -## Output +where hₓ = hᵧ = hᵤ = 2 is the halo extent required for gradient and Laplacian calculations. -This fix can output spatial fields such as: +**Parameters** -- Density fields for ternary phase variables (**rho, phi, psi**). These phase variables can be reverted back to `C1`, `C2`, `C3` by through some algebraic operation. - -- Pressure field - -- Velocity along x, y, z directions +This fix accepts several internal parameters that control the thermodynamic and transport properties: -The fix supports output in `.xdmf` and `.raw` format which can then be post-processed and visualized using Paraview. +* **tau_r**, **tau_p**, **tau_s**: Relaxation times for momentum transport and order parameter transport. These control the viscosity and diffusivity of the fluid components. -## Restrictions +* **gamma_p**, **gamma_s**: Mobility coefficients controlling the rate of change of the phase variables φ and ψ. -- This fix requires MPI and cannot be compiled with MPI_STUBS. - -- Uses D3Q19 velocity vector space - can simulation 3D/pseudo 2D geometry - -- Currently does **not support coupling to molecular dynamics particles** +* **kappa1**, **kappa2**, **kappa3**: Surface tension parameters that determine the interfacial tensions between the three components. The surface tension between components m and n is given by: -## Related commands + .. math:: -- `fix lb/fluid` + \gamma_{mn} = \frac{\sqrt{(\kappa_m + \kappa_n)(\lambda_m + \lambda_n)}}{6} + +* **alpha**: Gradient energy coefficient. + +* **C1**, **C2**, **C3**: Bulk concentrations of the three components (must sum to 1.0). + +Future versions may allow passing these parameters directly via the input script. + +---------- + +**Output** + +The *dumpxdmf* keyword enables output of the fluid fields to files that can be visualized using Paraview or other XDMF-compatible visualization software. The output includes: + +* Density field ρ (converted to physical units) +* Order parameters φ and ψ (converted to physical units) +* Pressure field p (converted to physical units) +* Velocity field **u** (converted to physical units) + +Two files are created: + +* A text .xdmf file containing metadata and grid structure +* A binary .raw file containing the actual field data + +The concentration fields can be recovered from the output using: + +.. math:: + + C_1 = \frac{\rho + \phi}{2}, \quad C_2 = \frac{\rho - \phi}{2}, \quad C_3 = \psi + +---------- + +**Boundary Conditions** + +The ternary lattice-Boltzmann implementation currently supports periodic boundary conditions in all three directions. The boundary conditions are specified through the main LAMMPS :doc:`boundary ` command and must be set to periodic (p p p) for proper operation. + +*Periodic Boundaries* + +With periodic boundary conditions, the fluid domain wraps around in all directions. The distribution functions that stream out of one side of the simulation box re-enter from the opposite side. This is handled automatically through the MPI communication scheme, which includes a halo region of 2 lattice layers on each side of the local processor subdomain. + +The halo communication ensures that: + +* Gradient calculations (∇ρ, ∇φ, ∇ψ) required for the chemical potentials can be performed correctly near subdomain boundaries +* Laplacian calculations (∇²ρ, ∇²φ, ∇²ψ) have access to necessary neighbor information +* Streaming of distribution functions across processor boundaries is handled correctly + +---------- + +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. + +* This fix can only be used with an orthogonal simulation domain. +* Only the D3Q19 velocity lattice is currently supported. +* The boundary conditions must be periodic (p p p) in all three directions. +* Shrink-wrapped boundary conditions are not permitted. +* This fix requires MPI and cannot be compiled with MPI_STUBS. +* Currently does **not support coupling to molecular dynamics particles**. Particle-fluid interactions available in :doc:`lb/viscous ` are not yet implemented for the multicomponent case. + +Related commands +"""""""""""""""" + +:doc:`fix lb/fluid ` +:doc:`fix lb/viscous ` +:doc:`compute lb/fluid ` +:doc:`compute lb/multicomponent ` +:doc:`compute lb/viscous ` +:doc:`pair lb/multicomponent ` + +Default +""""""" -## Default The default values for optional parameters are: * seed = 12345 @@ -128,11 +224,22 @@ The default values for optional parameters are: * gamma_s = 1.0 * init = mixture -## Contact +---------- + +**Contact** + Ternary model implementation: -- Ulf D. Schiller [uschiller@mailaps.org](mailto:uschiller@mailaps.org) -- Fang Wang [fwang8@clemson.edu](mailto:fwang8@clemson.edu) -- Gokul Raman Arumugam Kumar akgokulraman@gmail.com +* Ulf D. Schiller (uschiller@mailaps.org) +* Fang Wang (fwang8@clemson.edu) +* Gokul Raman Arumugam Kumar (akgokulraman@gmail.com) + +---------- + +.. _ArumugamKumar2024: + +**(Arumugam Kumar)** Arumugam Kumar, G.R., Andrews, J.P., Schiller, U.D., Implementation of a ternary lattice Boltzmann model in LAMMPS, Computer Physics Communications 294, 108898 (2024). + +.. _Semprebon2016: -.. NOTE:: Inline LaTeX-style equations for chemical potentials and free energy may be added in a future version for theoretical clarity. \ No newline at end of file +**(Semprebon)** Semprebon, C., Krüger, T., Kusumaatmaja, H., Ternary free-energy lattice Boltzmann model with tunable surface tensions and contact angles, Phys. Rev. E 93, 033305 (2016). \ No newline at end of file From e470b47a5b8423003e313a2277c9ed5e8d076050 Mon Sep 17 00:00:00 2001 From: rzaman64 Date: Fri, 17 Oct 2025 11:52:03 -0400 Subject: [PATCH 4/7] Add documentation for fix_lb_multicomponent --- doc/src/fix_lb_multicomponent.rst | 245 ++++++++++++++++++++++++++++++ 1 file changed, 245 insertions(+) create mode 100644 doc/src/fix_lb_multicomponent.rst diff --git a/doc/src/fix_lb_multicomponent.rst b/doc/src/fix_lb_multicomponent.rst new file mode 100644 index 00000000000..639beb8a001 --- /dev/null +++ b/doc/src/fix_lb_multicomponent.rst @@ -0,0 +1,245 @@ +.. index:: fix lb/multicomponent + +fix lb/multicomponent command +============================== + +Syntax +"""""" + +.. parsed-literal:: + +* ID, group-ID are documented in :doc:`fix ` command +* lb/multicomponent = style name of this fix command +* nevery = update the lattice-Boltzmann fluid every this many timesteps (should normally be 1) +* viscosity = the fluid viscosity (units of mass/(time\*length)) +* density = the initial fluid density +* D3Q19 = velocity lattice model (required) +* dx = keyword for lattice spacing +* dx_value = the lattice-Boltzmann grid spacing +* zero or more keyword/value pairs may be appended +* keyword = *tau_r* or *tau_p* or *tau_s* or *kappa1* or *kappa2* or *kappa3* or *alpha* or *gamma_p* or *gamma_s* or *C1* or *C2* or *C3* or *dumpxdmf* or *seed* or *init* + + .. parsed-literal:: + + *tau_r* value = relaxation time for momentum transport (related to viscosity) + *tau_p* value = relaxation time for order parameter φ transport + *tau_s* value = relaxation time for order parameter ψ transport + *kappa1* value = surface tension parameter between components C1 and C2 + *kappa2* value = surface tension parameter between components C1 and C3 + *kappa3* value = surface tension parameter for component C3 + *alpha* value = gradient energy coefficient + *gamma_p* value = mobility coefficient for order parameter φ + *gamma_s* value = mobility coefficient for order parameter ψ + *C1* value = bulk concentration of component 1 + *C2* value = bulk concentration of component 2 + *C3* value = bulk concentration of component 3 (note: C1 + C2 + C3 = 1) + *dumpxdmf* values = N filename timeI + N = output fluid fields every N timesteps + filename = base name for output files (.xdmf and .raw extensions added automatically) + timeI = 1 (use simulation time to index xdmf file), 0 (use output frame number) + *seed* value = random number generator seed (positive integer) + *init* values = initialization_method [method_parameters] + initialization_method = *mixture* or *droplet* or *liquid_lens* or *double_emulsion* or *film* or *mixed_droplet* + *mixture* = homogeneous mixture with random fluctuations + *droplet* radius = binary droplet (C1 and C2) of given radius in C3 solvent + *liquid_lens* radius = lens of C3 with given radius between C1 and C2 layers + *double_emulsion* radius = Janus droplet (C1 and C2 hemispheres) of given radius in C3 solvent + *film* thickness C1_film C2_film = ternary film with specified thickness and composition + *mixed_droplet* radius C1_drop C2_drop = ternary droplet with specified radius and composition in bulk + + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix 1 all lb/multicomponent 1 0.166667 1.0 D3Q19 dx 1.0 init mixture + fix 2 fluid lb/multicomponent 1 0.166667 1.0 D3Q19 dx 1.0 init droplet 10.0 + fix 3 all lb/multicomponent 1 0.166667 1.0 D3Q19 dx 1.0 C1 0.333333 C2 0.333333 C3 0.333334 kappa1 0.01 kappa2 0.02 kappa3 0.05 init mixture dumpxdmf 1000 output 0 + +Description +""""""""""" + +.. versionadded:: 2024 + +The **fix lb/multicomponent** command implements a ternary lattice Boltzmann model (LBM) for simulating multicomponent fluid mixtures in three dimensions. This fix is an extension of the single-component :doc:`fix lb/fluid `, designed to capture more complex interfacial and phase behaviors such as droplets, emulsions, and films involving three interacting fluid components. + +The algorithm evolves three coupled distribution functions over a D3Q19 lattice and models thermodynamic interactions via chemical potentials and free-energy gradients. The model is suitable for studying phase separation, interface dynamics, droplet stability, and multiphase coexistence. + +The implementation follows the work described in Arumugam Kumar et al., "Implementation of a Ternary Lattice Boltzmann Model in LAMMPS," Comput. Phys. Commun. 294, 108898 (2024). + +---------- + +**Model Overview** + +The ternary fluid composition is specified by three concentration fields C₁, C₂, and C₃, which are related to conserved order parameters: + +.. math:: + + \rho &= C_1 + C_2 + C_3 \\ + \phi &= C_1 - C_2 \\ + \psi &= C_3 + +where ρ is the total density (approximately constant for incompressible flow), and φ and ψ are order parameters that distinguish the three components. + +The time evolution is described by three sets of distribution functions (f, g, h) that evolve according to the Bhatnagar-Gross-Krook (BGK) lattice Boltzmann equation: + + +.. math:: + + ``` + \rho &= C_1 + C_2 + C_3 = 1 \\ + \phi &= C_1 - C_2 \\ + \psi &= C_3 + ``` + +with :math:`C_1, C_2, C_3` denoting component concentrations. +## Keywords + +---------- + +**Initialization Methods** + +The *init* keyword specifies how the ternary fluid is initialized: + +* **mixture**: Creates a homogeneous mixture with bulk concentrations C1, C2, C3 plus small random fluctuations (±0.01) to seed phase separation. This is the default initialization if no *init* keyword is specified. + +* **droplet** *radius*: Creates a binary droplet composed of equal parts C1 and C2 (C3 = 0) with specified radius (in lattice units) centered in the simulation box, surrounded by pure C3. + +* **liquid_lens** *radius*: Creates a lens-shaped droplet of pure C3 with specified radius positioned at the interface between horizontal layers of pure C1 (top half) and pure C2 (bottom half). + +* **double_emulsion** *radius*: Creates a Janus-type double emulsion with a droplet of specified radius split into two hemispheres: left hemisphere of pure C1 and right hemisphere of pure C2, surrounded by pure C3 solvent. + +* **film** *thickness* *C1_film* *C2_film*: Creates a horizontal film of specified thickness (as a fraction of the box height) centered in the simulation box with composition C1_film, C2_film, C3_film = 1 - C1_film - C2_film, surrounded by bulk mixture. Small random fluctuations (±0.01) are added to seed phase separation. + +* **mixed_droplet** *radius* *C1_drop* *C2_drop*: Creates a ternary droplet with specified radius and composition (C1_drop, C2_drop, C3_drop = 1 - C1_drop - C2_drop) surrounded by pure C3 solvent. Small random fluctuations (±0.01) are added within the droplet. + +.. math:: + + \text{subNbx} = \frac{N_x}{P_x} + 2h_x \\ + \text{subNby} = \frac{N_y}{P_y} + 2h_y \\ + \text{subNbz} = \frac{N_z}{P_z} + 2h_z + +where hₓ = hᵧ = hᵤ = 2 is the halo extent required for gradient and Laplacian calculations. + +**Parameters** + +This fix accepts several internal parameters that control the thermodynamic and transport properties: + +* **tau_r**, **tau_p**, **tau_s**: Relaxation times for momentum transport and order parameter transport. These control the viscosity and diffusivity of the fluid components. + +* **gamma_p**, **gamma_s**: Mobility coefficients controlling the rate of change of the phase variables φ and ψ. + +* **kappa1**, **kappa2**, **kappa3**: Surface tension parameters that determine the interfacial tensions between the three components. The surface tension between components m and n is given by: + + .. math:: + + \gamma_{mn} = \frac{\sqrt{(\kappa_m + \kappa_n)(\lambda_m + \lambda_n)}}{6} + +* **alpha**: Gradient energy coefficient. + +* **C1**, **C2**, **C3**: Bulk concentrations of the three components (must sum to 1.0). + +Future versions may allow passing these parameters directly via the input script. + +---------- + +**Output** + +The *dumpxdmf* keyword enables output of the fluid fields to files that can be visualized using Paraview or other XDMF-compatible visualization software. The output includes: + +* Density field ρ (converted to physical units) +* Order parameters φ and ψ (converted to physical units) +* Pressure field p (converted to physical units) +* Velocity field **u** (converted to physical units) + +Two files are created: + +* A text .xdmf file containing metadata and grid structure +* A binary .raw file containing the actual field data + +The concentration fields can be recovered from the output using: + +.. math:: + + C_1 = \frac{\rho + \phi}{2}, \quad C_2 = \frac{\rho - \phi}{2}, \quad C_3 = \psi + +---------- + +**Boundary Conditions** + +The ternary lattice-Boltzmann implementation currently supports periodic boundary conditions in all three directions. The boundary conditions are specified through the main LAMMPS :doc:`boundary ` command and must be set to periodic (p p p) for proper operation. + +*Periodic Boundaries* + +With periodic boundary conditions, the fluid domain wraps around in all directions. The distribution functions that stream out of one side of the simulation box re-enter from the opposite side. This is handled automatically through the MPI communication scheme, which includes a halo region of 2 lattice layers on each side of the local processor subdomain. + +The halo communication ensures that: + +* Gradient calculations (∇ρ, ∇φ, ∇ψ) required for the chemical potentials can be performed correctly near subdomain boundaries +* Laplacian calculations (∇²ρ, ∇²φ, ∇²ψ) have access to necessary neighbor information +* Streaming of distribution functions across processor boundaries is handled correctly + +---------- + +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. + +* This fix can only be used with an orthogonal simulation domain. +* Only the D3Q19 velocity lattice is currently supported. +* The boundary conditions must be periodic (p p p) in all three directions. +* Shrink-wrapped boundary conditions are not permitted. +* This fix requires MPI and cannot be compiled with MPI_STUBS. +* Currently does **not support coupling to molecular dynamics particles**. Particle-fluid interactions available in :doc:`lb/viscous ` are not yet implemented for the multicomponent case. + +Related commands +"""""""""""""""" + +:doc:`fix lb/fluid ` +:doc:`fix lb/viscous ` +:doc:`compute lb/fluid ` +:doc:`compute lb/multicomponent ` +:doc:`compute lb/viscous ` +:doc:`pair lb/multicomponent ` + +Default +""""""" + +The default values for optional parameters are: + +* seed = 12345 +* alpha = 1.0 +* C1 = 0.333333 +* C2 = 0.333333 +* C3 = 0.333334 +* kappa1 = 0.01 +* kappa2 = 0.01 +* kappa3 = 0.01 +* tau_r = 1.0 +* tau_p = 1.0 +* tau_s = 0.666667 +* gamma_p = 1.0 +* gamma_s = 1.0 +* init = mixture + +---------- + +**Contact** + +Ternary model implementation: + +* Ulf D. Schiller (uschiller@mailaps.org) +* Fang Wang (fwang8@clemson.edu) +* Gokul Raman Arumugam Kumar (akgokulraman@gmail.com) + +---------- + +.. _ArumugamKumar2024: + +**(Arumugam Kumar)** Arumugam Kumar, G.R., Andrews, J.P., Schiller, U.D., Implementation of a ternary lattice Boltzmann model in LAMMPS, Computer Physics Communications 294, 108898 (2024). + +.. _Semprebon2016: + +**(Semprebon)** Semprebon, C., Krüger, T., Kusumaatmaja, H., Ternary free-energy lattice Boltzmann model with tunable surface tensions and contact angles, Phys. Rev. E 93, 033305 (2016). \ No newline at end of file From 614d07b70280747788a52cd43ac9671af029aa55 Mon Sep 17 00:00:00 2001 From: rzaman64 <132156415+rzaman64@users.noreply.github.com> Date: Wed, 3 Dec 2025 00:53:04 -0500 Subject: [PATCH 5/7] Apply suggestions from code review Commiting post pull request to improve clarity and technical accuracy of the documentation Co-authored-by: Gokul Raman <53153074+akgokulraman@users.noreply.github.com> --- doc/src/fix_lb_multicomponent.rst | 45 +++++++++++++++---------------- 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/doc/src/fix_lb_multicomponent.rst b/doc/src/fix_lb_multicomponent.rst index 639beb8a001..01d75ddb02e 100644 --- a/doc/src/fix_lb_multicomponent.rst +++ b/doc/src/fix_lb_multicomponent.rst @@ -12,8 +12,8 @@ Syntax * lb/multicomponent = style name of this fix command * nevery = update the lattice-Boltzmann fluid every this many timesteps (should normally be 1) * viscosity = the fluid viscosity (units of mass/(time\*length)) -* density = the initial fluid density -* D3Q19 = velocity lattice model (required) +* density = the fluid density +* D3Q19 = the only velocity vector set used in this fix (mandatory to mention) * dx = keyword for lattice spacing * dx_value = the lattice-Boltzmann grid spacing * zero or more keyword/value pairs may be appended @@ -21,27 +21,26 @@ Syntax .. parsed-literal:: - *tau_r* value = relaxation time for momentum transport (related to viscosity) - *tau_p* value = relaxation time for order parameter φ transport - *tau_s* value = relaxation time for order parameter ψ transport - *kappa1* value = surface tension parameter between components C1 and C2 - *kappa2* value = surface tension parameter between components C1 and C3 - *kappa3* value = surface tension parameter for component C3 - *alpha* value = gradient energy coefficient - *gamma_p* value = mobility coefficient for order parameter φ - *gamma_s* value = mobility coefficient for order parameter ψ - *C1* value = bulk concentration of component 1 - *C2* value = bulk concentration of component 2 - *C3* value = bulk concentration of component 3 (note: C1 + C2 + C3 = 1) - *dumpxdmf* values = N filename timeI + *tau_r* value = relaxation time constant for the population distribution *f* - related to viscosity + *tau_p* value = relaxation time constant for the population distribution *g* - related to the mobility coefficient of the order parameter $\phi$ + *tau_s* value = relaxation time constant for the population distribution *k* - related to the mobility coefficient of the order parameter $\psi$ + *kappa1* value = energy gradient parameter for fluid 1 - used in surface tension calculation between fluid 1 and other fluids + *kappa2* value = energy gradient parameter for fluid 2 - used in surface tension calculation between fluid 2 and other fluids + *kappa3* value = energy gradient parameter for fluid 3 - used in surface tension calculation between fluid 3 and other fluids + *alpha* value = parameter related to the interface width measurement + *gamma_p* value = mobility coefficient for order parameter $\phi$ + *gamma_s* value = mobility coefficient for order parameter $\psi$ + *C1* value = bulk concentration of fluid component 1 + *C2* value = bulk concentration of fluid component 2 + *C3* value = bulk concentration of fluid component 3 (note: C1 + C2 + C3 = 1) + *dumpxdmf* values = N filename N = output fluid fields every N timesteps filename = base name for output files (.xdmf and .raw extensions added automatically) - timeI = 1 (use simulation time to index xdmf file), 0 (use output frame number) - *seed* value = random number generator seed (positive integer) + *seed* value = random number generator seed (positive integer) - useful to initialize certain models like ternary mixture, ternary film, and ternary droplet *init* values = initialization_method [method_parameters] initialization_method = *mixture* or *droplet* or *liquid_lens* or *double_emulsion* or *film* or *mixed_droplet* - *mixture* = homogeneous mixture with random fluctuations - *droplet* radius = binary droplet (C1 and C2) of given radius in C3 solvent + *mixture* = well-mixed fluid mixture + *droplet* radius = droplet in a solvent model - droplet of fluid component 1 of given radius surrounded by fluid component 2 - droplet center is located at the center of the box *liquid_lens* radius = lens of C3 with given radius between C1 and C2 layers *double_emulsion* radius = Janus droplet (C1 and C2 hemispheres) of given radius in C3 solvent *film* thickness C1_film C2_film = ternary film with specified thickness and composition @@ -62,9 +61,9 @@ Description .. versionadded:: 2024 -The **fix lb/multicomponent** command implements a ternary lattice Boltzmann model (LBM) for simulating multicomponent fluid mixtures in three dimensions. This fix is an extension of the single-component :doc:`fix lb/fluid `, designed to capture more complex interfacial and phase behaviors such as droplets, emulsions, and films involving three interacting fluid components. +The **fix lb/multicomponent** command implements a ternary lattice Boltzmann model (LBM) for simulating three-dimensional multicomponent fluid systems. This fix is an extension of the single-component :doc:`fix lb/fluid `, designed to capture complex interfacial and phase behaviors of three immiscible fluid components for various fluid models like ternary mixture, droplets, and films. -The algorithm evolves three coupled distribution functions over a D3Q19 lattice and models thermodynamic interactions via chemical potentials and free-energy gradients. The model is suitable for studying phase separation, interface dynamics, droplet stability, and multiphase coexistence. +The algorithm evolves three distribution functions over a D3Q19 lattice and models thermodynamic interactions using the Landau-Ginzburg free-energy. This model is suitable for studying multi-component fluid interactions in the aspect of phase separation and interface dynamics. The implementation follows the work described in Arumugam Kumar et al., "Implementation of a Ternary Lattice Boltzmann Model in LAMMPS," Comput. Phys. Commun. 294, 108898 (2024). @@ -72,7 +71,7 @@ The implementation follows the work described in Arumugam Kumar et al., "Impleme **Model Overview** -The ternary fluid composition is specified by three concentration fields C₁, C₂, and C₃, which are related to conserved order parameters: +The ternary fluid composition is specified by three concentration fields $C_1$, $C_2$, and $C_3$, which are related to conserved order parameters: .. math:: @@ -80,7 +79,7 @@ The ternary fluid composition is specified by three concentration fields C₁, C \phi &= C_1 - C_2 \\ \psi &= C_3 -where ρ is the total density (approximately constant for incompressible flow), and φ and ψ are order parameters that distinguish the three components. +where $\rho$ is the total density (approximately constant for incompressible flow), $\phi$ and \psi$ are order parameters that distinguish the three components. The time evolution is described by three sets of distribution functions (f, g, h) that evolve according to the Bhatnagar-Gross-Krook (BGK) lattice Boltzmann equation: From 96a916a18e4351758dc76653465b653b49094264 Mon Sep 17 00:00:00 2001 From: rzaman64 <132156415+rzaman64@users.noreply.github.com> Date: Mon, 15 Dec 2025 16:09:56 -0500 Subject: [PATCH 6/7] Update doc/src/fix_lb_multicomponent.rst Co-authored-by: Gokul Raman <53153074+akgokulraman@users.noreply.github.com> --- doc/src/fix_lb_multicomponent.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/fix_lb_multicomponent.rst b/doc/src/fix_lb_multicomponent.rst index 01d75ddb02e..cecfc646933 100644 --- a/doc/src/fix_lb_multicomponent.rst +++ b/doc/src/fix_lb_multicomponent.rst @@ -107,7 +107,7 @@ The *init* keyword specifies how the ternary fluid is initialized: * **liquid_lens** *radius*: Creates a lens-shaped droplet of pure C3 with specified radius positioned at the interface between horizontal layers of pure C1 (top half) and pure C2 (bottom half). -* **double_emulsion** *radius*: Creates a Janus-type double emulsion with a droplet of specified radius split into two hemispheres: left hemisphere of pure C1 and right hemisphere of pure C2, surrounded by pure C3 solvent. +* **double_emulsion** *radius*: Creates a Janus-type double emulsion with a droplet of specified radius split into two hemispheres: left hemisphere of component 1 and right hemisphere of component 2, centered in the simulation box and surrounded by component 3 in bulk. * **film** *thickness* *C1_film* *C2_film*: Creates a horizontal film of specified thickness (as a fraction of the box height) centered in the simulation box with composition C1_film, C2_film, C3_film = 1 - C1_film - C2_film, surrounded by bulk mixture. Small random fluctuations (±0.01) are added to seed phase separation. From 87d48ce5f5335176111448c9a4825acdfdaed28e Mon Sep 17 00:00:00 2001 From: rzaman64 <132156415+rzaman64@users.noreply.github.com> Date: Mon, 15 Dec 2025 16:11:52 -0500 Subject: [PATCH 7/7] Update doc/src/fix_lb_multicomponent.rst Co-authored-by: Gokul Raman <53153074+akgokulraman@users.noreply.github.com> --- doc/src/fix_lb_multicomponent.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/fix_lb_multicomponent.rst b/doc/src/fix_lb_multicomponent.rst index cecfc646933..9cbaafb33e5 100644 --- a/doc/src/fix_lb_multicomponent.rst +++ b/doc/src/fix_lb_multicomponent.rst @@ -109,7 +109,7 @@ The *init* keyword specifies how the ternary fluid is initialized: * **double_emulsion** *radius*: Creates a Janus-type double emulsion with a droplet of specified radius split into two hemispheres: left hemisphere of component 1 and right hemisphere of component 2, centered in the simulation box and surrounded by component 3 in bulk. -* **film** *thickness* *C1_film* *C2_film*: Creates a horizontal film of specified thickness (as a fraction of the box height) centered in the simulation box with composition C1_film, C2_film, C3_film = 1 - C1_film - C2_film, surrounded by bulk mixture. Small random fluctuations (±0.01) are added to seed phase separation. +* **film** *thickness* *C1_film* *C2_film*: Creates a horizontal film of specified thickness (as a fraction of the box height) centered in the simulation box with composition C1_film, C2_film, C3_film (C1_film + C2_film + C3_film = 1), surrounded by a bulk mixture of C1, C2, C3 (C1+C2+C3 = 1). * **mixed_droplet** *radius* *C1_drop* *C2_drop*: Creates a ternary droplet with specified radius and composition (C1_drop, C2_drop, C3_drop = 1 - C1_drop - C2_drop) surrounded by pure C3 solvent. Small random fluctuations (±0.01) are added within the droplet.