convert docs for fixes eos/cv, eos/table/rx, gcmc, grem, langevin/spin, lb/fluid

This commit is contained in:
Axel Kohlmeyer 2020-02-14 12:27:39 +01:00
parent 7b32b1e595
commit 74a2fd973b
No known key found for this signature in database
GPG Key ID: D9B44E93BF0C375A
32 changed files with 150 additions and 269 deletions

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.9 KiB

View File

@ -1,9 +0,0 @@
\documentstyle[12pt]{article}
\pagestyle{empty}
\begin{document}
$$
u_{i} = u^{mech}_{i} + u^{cond}_{i} = C_{V} \theta_{i}
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 17 KiB

View File

@ -1,9 +0,0 @@
\documentstyle[12pt]{article}
\pagestyle{empty}
\begin{document}
\begin{eqnarray*}
U_{i} = \displaystyle\sum_{j=1}^{m} c_{i,j}(u_{j} + \Delta H_{f,j}) + \frac{3k_{b}T}{2} + Nk_{b}T \\
\end{eqnarray*}
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 5.5 KiB

View File

@ -1,9 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
\begin{eqnarray*}
\mu &=&\mu^{id} + \mu^{ex}
\end{eqnarray*}
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 10 KiB

View File

@ -1,10 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
\begin{eqnarray*}
\mu^{id} &=& k T \ln{\rho \Lambda^3} \\
&=& k T \ln{\frac{\phi P \Lambda^3}{k T}}
\end{eqnarray*}
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 7.3 KiB

View File

@ -1,9 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
\begin{eqnarray*}
\Lambda &=& \sqrt{ \frac{h^2}{2 \pi m k T}}
\end{eqnarray*}
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.1 KiB

View File

@ -1,9 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
T_{eff} = \lambda + \eta (H - H_0)
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.5 KiB

View File

@ -1,14 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
\left(\partial_t + e_{i\alpha}\partial_{\alpha}\right)f_i = -\frac{1}{\tau}\left(f_i - f_i^{eq}\right) + W_i
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.3 KiB

View File

@ -1,14 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
{\bf F}_{j \alpha} = \gamma \left({\bf v}_n - {\bf u}_f \right) \zeta_{j\alpha}
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 4.7 KiB

View File

@ -1,14 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
\gamma = \frac{2m_um_v}{m_u+m_v}\left(\frac{1}{\Delta t_{collision}}\right)
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 9.1 KiB

View File

@ -1,16 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
\partial_t \rho + \partial_{\beta}\left(\rho u_{\beta}\right)= 0
$$
$$
\partial_t\left(\rho u_{\alpha}\right) + \partial_{\beta}\left(\rho u_{\alpha} u_{\beta}\right) = \partial_{\beta}\sigma_{\alpha \beta} + F_{\alpha} + \partial_{\beta}\left(\eta_{\alpha \beta \gamma \nu}\partial_{\gamma} u_{\nu}\right)
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 3.4 KiB

View File

@ -1,17 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
\rho = \displaystyle\sum\limits_{i} f_i
$$
$$
\rho u_{\alpha} = \displaystyle\sum\limits_{i} f_i e_{i\alpha}
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.5 KiB

View File

@ -1,14 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
\sigma_{\alpha \beta} = -P_{\alpha \beta} = -\rho a_0 \delta_{\alpha \beta}
$$
\end{document}

Binary file not shown.

Before

Width:  |  Height:  |  Size: 6.4 KiB

View File

@ -1,14 +0,0 @@
\documentclass[12pt]{article}
\begin{document}
$$
\eta_{\alpha \beta \gamma \nu} = \eta\left[\delta_{\alpha \gamma}\delta_{\beta \nu} + \delta_{\alpha \nu}\delta_{\beta \gamma} - \frac{2}{3}\delta_{\alpha \beta}\delta_{\gamma \nu}\right] + \Lambda \delta_{\alpha \beta}\delta_{\gamma \nu}
$$
\end{document}

View File

@ -27,17 +27,19 @@ Description
"""""""""""
Fix *eos/cv* applies a mesoparticle equation of state to relate the
particle internal energy (u\_i) to the particle internal temperature
(dpdTheta\_i). The *eos/cv* mesoparticle equation of state requires
particle internal energy (:math:`u_i`) to the particle internal temperature
(:math:`\theta_i`). The *eos/cv* mesoparticle equation of state requires
the constant-volume heat capacity, and is defined as follows:
.. image:: Eqs/fix_eos-cv.jpg
:align: center
.. math::
where Cv is the constant-volume heat capacity, u\_cond is the internal
conductive energy, and u\_mech is the internal mechanical energy. Note
that alternative definitions of the mesoparticle equation of state are
possible.
u_{i} = u^{mech}_{i} + u^{cond}_{i} = C_{V} \theta_{i}
where :math:`C_V` is the constant-volume heat capacity, :math:`u^{cond}`
is the internal conductive energy, and :math:`u^{mech}` is the internal
mechanical energy. Note that alternative definitions of the mesoparticle
equation of state are possible.
----------

View File

@ -40,30 +40,34 @@ Description
Fix *eos/table/rx* applies a tabulated mesoparticle equation
of state to relate the concentration-dependent particle internal
energy (u\_i) to the particle internal temperature (dpdTheta\_i).
energy (:math:`u_i`) to the particle internal temperature (:math:`\theta_i`).
The concentration-dependent particle internal energy (u\_i) is
The concentration-dependent particle internal energy (:math:`u_i`) is
computed according to the following relation:
.. image:: Eqs/fix_eos_table_rx.jpg
:align: center
.. math::
where *m* is the number of species, *c\_i,j* is the concentration of
species *j* in particle *i*\ , *u\_j* is the internal energy of species j,
*DeltaH\_f,j* is the heat of formation of species *j*\ , N is the number of
molecules represented by the coarse-grained particle, kb is the
Boltzmann constant, and T is the temperature of the system. Additionally,
it is possible to modify the concentration-dependent particle internal
U_{i} = \displaystyle\sum_{j=1}^{m} c_{i,j}(u_{j} + \Delta H_{f,j}) + \frac{3k_{b}T}{2} + Nk_{b}T \\
where *m* is the number of species, :math:`c_{i,j}` is the
concentration of species *j* in particle *i*\ , :math:`u_j` is the
internal energy of species j, :math:`\Delta H_{f,j} is the heat of
formation of species *j*\ , N is the number of molecules represented
by the coarse-grained particle, :math:`k_b` is the Boltzmann constant,
and *T* is the temperature of the system. Additionally, it is
possible to modify the concentration-dependent particle internal
energy relation by adding an energy correction, temperature-dependent
correction, and/or a molecule-dependent correction. An energy correction can
be specified as a constant (in energy units). A temperature correction can be
specified by multiplying a temperature correction coefficient by the
internal temperature. A molecular correction can be specified by
by multiplying a molecule correction coefficient by the average number of
product gas particles in the coarse-grain particle.
correction, and/or a molecule-dependent correction. An energy
correction can be specified as a constant (in energy units). A
temperature correction can be specified by multiplying a temperature
correction coefficient by the internal temperature. A molecular
correction can be specified by by multiplying a molecule correction
coefficient by the average number of product gas particles in the
coarse-grain particle.
Fix *eos/table/rx* creates interpolation tables of length *N* from *m*
internal energy values of each species *u\_j* listed in a file as a
internal energy values of each species :math:`u_j` listed in a file as a
function of internal temperature. During a simulation, these tables
are used to interpolate internal energy or temperature values as needed.
The interpolation is done with the *linear* style. For the *linear* style,
@ -72,20 +76,21 @@ which an internal energy is computed by linear interpolation. A secant
solver is used to determine the internal temperature from the internal energy.
The first filename specifies a file containing tabulated internal
temperature and *m* internal energy values for each species *u\_j*.
temperature and *m* internal energy values for each species :math:`u_j`.
The keyword specifies a section of the file. The format of this
file is described below.
The second filename specifies a file containing heat of formation
*DeltaH\_f,j* for each species.
:math:`\Delta H_{f,j}` for each species.
In cases where the coarse-grain particle represents a single molecular
species (i.e., no reactions occur and fix *rx* is not present in the input file),
fix *eos/table/rx* can be applied in a similar manner to fix *eos/table*
within a non-reactive DPD simulation. In this case, the heat of formation
filename is replaced with the heat of formation value for the single species.
Additionally, the energy correction and temperature correction coefficients may
also be specified as fix arguments.
species (i.e., no reactions occur and fix *rx* is not present in the
input file), fix *eos/table/rx* can be applied in a similar manner to
fix *eos/table* within a non-reactive DPD simulation. In this case,
the heat of formation filename is replaced with the heat of formation
value for the single species. Additionally, the energy correction and
temperature correction coefficients may also be specified as fix
arguments.
----------

View File

@ -248,8 +248,10 @@ two groups: the default group "all" and the fix group
The chemical potential is a user-specified input parameter defined
as:
.. image:: Eqs/fix_gcmc1.jpg
:align: center
.. math::
\mu = \mu^{id} + \mu^{ex}
The second term mu\_ex is the excess chemical potential due to
energetic interactions and is formally zero for the fictitious gas
@ -260,31 +262,35 @@ quite different. The first term mu\_id is the ideal gas contribution
to the chemical potential. mu\_id can be related to the density or
pressure of the fictitious gas reservoir by:
.. image:: Eqs/fix_gcmc2.jpg
:align: center
.. math::
where k is Boltzman's constant,
T is the user-specified temperature, rho is the number density,
P is the pressure, and phi is the fugacity coefficient.
The constant Lambda is required for dimensional consistency.
For all unit styles except *lj* it is defined as the thermal
de Broglie wavelength
\mu^{id} = & k T \ln{\rho \Lambda^3} \\
= & k T \ln{\frac{\phi P \Lambda^3}{k T}}
.. image:: Eqs/fix_gcmc3.jpg
:align: center
where h is Planck's constant, and m is the mass of the exchanged atom
or molecule. For unit style *lj*\ , Lambda is simply set to the
unity. Note that prior to March 2017, lambda for unit style *lj* was
calculated using the above formula with h set to the rather specific
where *k* is Boltzman's constant, *T* is the user-specified
temperature, :math:`\rho` is the number density, *P* is the pressure,
and :math:`\phi` is the fugacity coefficient. The constant
:math:`\Lambda` is required for dimensional consistency. For all unit
styles except *lj* it is defined as the thermal de Broglie wavelength
.. math::
\Lambda = \sqrt{ \frac{h^2}{2 \pi m k T}}
where *h* is Planck's constant, and *m* is the mass of the exchanged atom
or molecule. For unit style *lj*\ , :math:`\Lambda` is simply set to
unity. Note that prior to March 2017, :math:`\Lambda` for unit style *lj*
was calculated using the above formula with *h* set to the rather specific
value of 0.18292026. Chemical potential under the old definition can
be converted to an equivalent value under the new definition by
subtracting 3kTln(Lambda\_old).
subtracting :math:`3 k T \ln(\Lambda_{old})`.
As an alternative to specifying mu directly, the ideal gas reservoir
can be defined by its pressure P using the *pressure* keyword, in
can be defined by its pressure *P* using the *pressure* keyword, in
which case the user-specified chemical potential is ignored. The user
may also specify the fugacity coefficient phi using the
may also specify the fugacity coefficient :math:`\phi` using the
*fugacity\_coeff* keyword, which defaults to unity.
The *full\_energy* option means that the fix calculates the total
@ -322,7 +328,7 @@ this will ensure roughly the same behavior whether or not the
*full\_energy* option is used.
Inserted atoms and molecules are assigned random velocities based on
the specified temperature T. Because the relative velocity of all
the specified temperature *T*. Because the relative velocity of all
atoms in the molecule is zero, this may result in inserted molecules
that are systematically too cold. In addition, the intramolecular
potential energy of the inserted molecule may cause the kinetic energy

View File

@ -38,17 +38,19 @@ which uses non-Boltzmann ensembles to sample over first order phase
transitions. The is done by defining replicas with an enthalpy
dependent effective temperature
.. image:: Eqs/fix_grem.jpg
:align: center
.. math::
with *eta* negative and steep enough to only intersect the
T_{eff} = \lambda + \eta (H - H_0)
with :math:`\eta` negative and steep enough to only intersect the
characteristic microcanonical temperature (Ts) of the system once,
ensuring a unimodal enthalpy distribution in that replica. *Lambda* is
the intercept and effects the generalized ensemble similar to how
temperature effects a Boltzmann ensemble. *H0* is a reference
enthalpy, and is typically set as the lowest desired sampled enthalpy.
Further explanation can be found in our recent papers
:ref:`(Malolepsza) <Malolepsza>`.
ensuring a unimodal enthalpy distribution in that replica.
:math:`\lambda` is the intercept and effects the generalized ensemble
similar to how temperature effects a Boltzmann ensemble. :math:`H_0`
is a reference enthalpy, and is typically set as the lowest desired
sampled enthalpy. Further explanation can be found in our recent
papers :ref:`(Malolepsza) <Malolepsza>`.
This fix requires a Nose-Hoover thermostat fix reference passed to the
grem as *thermostat-ID*\ . Two distinct temperatures exist in this
@ -59,13 +61,13 @@ algorithms can be used.
The fix enforces a generalized ensemble in a single replica
only. Typically, this ideology is combined with replica exchange with
replicas differing by *lambda* only for simplicity, but this is not
replicas differing by :math:`\lambda` only for simplicity, but this is not
required. A multi-replica simulation can be run within the LAMMPS
environment using the :doc:`temper/grem <temper_grem>` command. This
utilizes LAMMPS partition mode and requires the number of available
processors be on the order of the number of desired replicas. A
100-replica simulation would require at least 100 processors (1 per
world at minimum). If a many replicas are needed on a small number of
world at minimum). If many replicas are needed on a small number of
processors, multi-replica runs can be run outside of LAMMPS. An
example of this can be found in examples/USER/misc/grem and has no
limit on the number of replicas per processor. However, this is very
@ -74,13 +76,13 @@ inefficient and error prone and should be avoided if possible.
In general, defining the generalized ensembles is unique for every
system. When starting a many-replica simulation without any knowledge
of the underlying microcanonical temperature, there are several tricks
we have utilized to optimize the process. Choosing a less-steep *eta*
yields broader distributions, requiring fewer replicas to map the
microcanonical temperature. While this likely struggles from the same
sampling problems gREM was built to avoid, it provides quick insight
to Ts. Initially using an evenly-spaced *lambda* distribution
identifies regions where small changes in enthalpy lead to large
temperature changes. Replicas are easily added where needed.
we have utilized to optimize the process. Choosing a less-steep
:math:`\eta` yields broader distributions, requiring fewer replicas to
map the microcanonical temperature. While this likely struggles from
the same sampling problems gREM was built to avoid, it provides quick
insight to Ts. Initially using an evenly-spaced :math:`\lambda`
distribution identifies regions where small changes in enthalpy lead
to large temperature changes. Replicas are easily added where needed.
----------

View File

@ -36,16 +36,19 @@ Brownian dynamics (BD).
A random torque and a transverse dissipation are applied to each spin i according to
the following stochastic differential equation:
.. image:: Eqs/fix_langevin_spin_sLLG.jpg
:align: center
.. math::
with lambda the transverse damping, and eta a random vector.
\frac{d \vec{s}_{i}}{dt} = \frac{1}{\left(1+\lambda^2 \right)} \left( \left(
\vec{\omega}_{i} +\vec{\eta} \right) \times \vec{s}_{i} + \lambda\, \vec{s}_{i}
\times\left( \vec{\omega}_{i} \times\vec{s}_{i} \right) \right)
with :math:`\lambda` the transverse damping, and :math:`\eta` a random vector.
This equation is referred to as the stochastic Landau-Lifshitz-Gilbert (sLLG)
equation.
The components of eta are drawn from a Gaussian probability law. Their amplitude
is defined as a proportion of the temperature of the external thermostat T (in K
in metal units).
The components of :math:`\eta` are drawn from a Gaussian probability
law. Their amplitude is defined as a proportion of the temperature of
the external thermostat T (in K in metal units).
More details about this implementation are reported in :ref:`(Tranchida) <Tranchida2>`.

View File

@ -69,33 +69,42 @@ dependent force to the fluid.
The lattice-Boltzmann algorithm solves for the fluid motion governed by
the Navier Stokes equations,
.. image:: Eqs/fix_lb_fluid_navierstokes.jpg
:align: center
.. math::
\partial_t \rho + \partial_{\beta}\left(\rho u_{\beta}\right)= & 0 \\
\partial_t\left(\rho u_{\alpha}\right) + \partial_{\beta}\left(\rho u_{\alpha} u_{\beta}\right) = & \partial_{\beta}\sigma_{\alpha \beta} + F_{\alpha} + \partial_{\beta}\left(\eta_{\alpha \beta \gamma \nu}\partial_{\gamma} u_{\nu}\right)
with,
.. image:: Eqs/fix_lb_fluid_viscosity.jpg
:align: center
.. math::
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
\eta_{\alpha \beta \gamma \nu} = \eta\left[\delta_{\alpha \gamma}\delta_{\beta \nu} + \delta_{\alpha \nu}\delta_{\beta \gamma} - \frac{2}{3}\delta_{\alpha \beta}\delta_{\gamma \nu}\right] + \Lambda \delta_{\alpha \beta}\delta_{\gamma \nu}
.. image:: Eqs/fix_lb_fluid_stress.jpg
:align: center
with a\_0 set to 1/3 (dx/dt)\^2 by default.
where :math:`\rho` is the fluid density, *u* is the local
fluid velocity, :math:`\sigma` is the stress tensor, *F* is a local external
force, and :math:`\eta` and :math:`\Lambda` are the shear and bulk viscosities
respectively. Here, we have implemented
.. math::
\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.
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,
.. image:: Eqs/fix_lb_fluid_boltzmann.jpg
:align: center
.. 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 tau is a
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
@ -108,8 +117,10 @@ finite difference LB integrator is used. If *LBtype* is set equal to
Physical variables are then defined in terms of moments of the distribution
functions,
.. image:: Eqs/fix_lb_fluid_properties.jpg
:align: center
.. math::
\rho = & \displaystyle\sum\limits_{i} f_i \\
\rho u_{\alpha} = \displaystyle\sum\limits_{i} f_i e_{i\alpha}
Full details of the lattice-Boltzmann algorithm used can be found in
:ref:`Mackay et al. <fluid-Mackay>`.
@ -119,12 +130,15 @@ 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:
.. image:: Eqs/fix_lb_fluid_fluidforce.jpg
:align: center
.. math::
where v\_n is the velocity of the MD particle, u\_f is the fluid
{\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 gamma is the force
coupling constant. Zeta is a weight assigned to the grid point,
coupling constant. :math:`\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
@ -135,20 +149,25 @@ 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
By default, the force coupling constant, :math:`\gamma`, is calculated
according to
.. image:: Eqs/fix_lb_fluid_gammadefault.jpg
:align: center
.. math::
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 :ref:`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.
\gamma = \frac{2m_um_v}{m_u+m_v}\left(\frac{1}{\Delta t_{collision}}\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_{collision}` is a collision time, chosen such that
:math:`\frac{\tau}{\Delta t_{collision}} = 1` (see :ref:`Mackay and
Denniston <Mackay2>` for full details). In order to calculate :math:`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
@ -364,8 +383,10 @@ Default
By default, the force coupling constant is set according to
.. image:: Eqs/fix_lb_fluid_gammadefault.jpg
:align: center
.. math::
\gamma = \frac{2m_um_v}{m_u+m_v}\left(\frac{1}{\Delta t_{collision}}\right)
and an area of dx\_lb\^2 per node, used to calculate the fluid mass at
the particle node location, is assumed.