diff --git a/doc/src/fix_efield_lepton.rst b/doc/src/fix_efield_lepton.rst index 607a2ec8c5..5deec4a15e 100644 --- a/doc/src/fix_efield_lepton.rst +++ b/doc/src/fix_efield_lepton.rst @@ -1,143 +1,143 @@ -.. index:: fix efield/lepton - -fix efield/lepton command -========================= - -Syntax -"""""" - -.. code-block:: LAMMPS - - fix ID group-ID efield/lepton V ... - -* ID, group-ID are documented in the :doc:`fix ` command -* style = *efield/lepton* -* V = electric potential (electric field * distance units) -* V must be a Lepton expression (see below) -* zero or more keyword/value pairs may be appended to args -* keyword = *region* or *step* - - .. parsed-literal:: - - *region* value = region-ID - region-ID = ID of region atoms must be in to have effect - *step* value = h - h = step size for numerical differentiation (distance units) - -Examples -"""""""" - -.. code-block:: LAMMPS - - fix ex all efield/lepton "-E*x; E=1" - fix dexx all efield/lepton "-0.5*x^2" step 1 - fix yukawa all efield/lepton "A*exp(-B*r)/r; r=abs(sqrt(x^2+y^2+z^2)); A=1; B=1" step 1e-6 - fix infp all efield/lepton "-abs(x)" step 1 - - variable th equal 2*PI*ramp(0,1) - fix erot all efield/lepton "-(x*cos(v_th)+y*sin(v_th))" - -Description -""""""""""" - -.. versionadded:: TBD - -Add an electric potential :math:`V` that applies to a group of charged atoms a force :math:`\vec{F} = q \vec{E}`, -and to dipoles a force :math:`\vec{F} = (\vec{p} \cdot \nabla) \vec{E}` and torque :math:`\vec{T} = \vec{p} \times \vec{E}`, -where :math:`\vec{E} = - \nabla V`. The fix also evaluates the electrostatic energy (:math:`U_{q} = q V` and :math:`U_{p} = - \vec{p} \cdot \vec{E}`) -due to this potential when the :doc:`fix_modify energy yes ` command is specified (see below). - -.. note:: - - This command should be used instead of :doc:`fix efield ` if you want to impose a non-uniform electric field on a system with dipoles - since the latter does not include the dipole force term. If you only have charges or if the electric field gradient is negligible, - :doc:`fix efield ` should be used since it is faster. - -The `Lepton library `_, that the *efield/lepton* fix style interfaces with, evaluates -the expression string at run time to compute the energy, forces, and torques. It creates an analytical representation -of :math:`V` and :math:`\vec{E}`, while the gradient force is computed using a central difference scheme - -.. math:: - - \vec{F} = \frac{|\vec{p}|}{2h} \left[ \vec{E}(\vec{x} + h \hat{p}) - \vec{E}(\vec{x} - h \hat{p}) \right] . - -The Lepton expression must be either enclosed in quotes or must not contain any whitespace so that LAMMPS -recognizes it as a single keyword. More on valid Lepton expressions below. The final Lepton expression must -be a function of only :math:`x, y, z`, which refer to the current *unwrapped* coordinates of the atoms to ensure continuity. -Special care must be taken when using this fix with periodic boundary conditions or box-changing commands. - ----------- - -.. include:: lepton_expression.rst - ----------- - -If the *region* keyword is used, the atom must also be in the specified -geometric :doc:`region ` in order to be affected by the potential. - -The *step* keyword is required when :doc:`atom_style dipole ` is used and the electric field is non-uniform. - ----------- - -Restart, fix_modify, output, run start/stop, minimize info -""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - -No information about this fix is written to :doc:`binary restart files -`. - -The :doc:`fix_modify ` *energy* option is supported by this -fix to add the potential energy defined above to the global potential energy -of the system as part of :doc:`thermodynamic output `. -The default setting for this fix is :doc:`fix_modify energy no `. - -The :doc:`fix_modify ` *virial* option is supported by this -fix to add the contribution due to the added ***forces*** on charges and dipoles -to both the global pressure and per-atom stress of the system via the -:doc:`compute pressure ` and :doc:`compute stress/atom -` commands. The former can be accessed by -:doc:`thermodynamic output `. The default setting for -this fix is :doc:`fix_modify virial no `. - -The :doc:`fix_modify ` *respa* option is supported by this -fix. This allows to set at which level of the :doc:`r-RESPA ` -integrator the fix adding its forces. Default is the outermost level. - -This fix computes a global scalar and a global 3-vector of forces, -which can be accessed by various :doc:`output commands `. -The scalar is the potential energy discussed above. -The vector is the total force added to the group of atoms. -The scalar and vector values calculated by this fix are "extensive". - -This fix cannot be used with the *start/stop* keywords of -the :doc:`run ` command. - -The forces due to this fix are imposed during an energy minimization, -invoked by the :doc:`minimize ` command. You should not -specify force components with a variable that has time-dependence for -use with a minimizer, since the minimizer increments the timestep as -the iteration count during the minimization. - -.. note:: - - If you want the electric potential energy to be included in the - total potential energy of the system (the quantity being minimized), - you MUST enable the :doc:`fix_modify ` *energy* option for this fix. - ----------- - -Restrictions -"""""""""""" - -Fix style *efield/lepton* is part of the LEPTON package. It is only enabled if LAMMPS was built with that package. -See the :doc:`Build package ` page for more info. - - -Related commands -"""""""""""""""" - -:doc:`fix efield ` - -Default -""""""" - -none +.. index:: fix efield/lepton + +fix efield/lepton command +========================= + +Syntax +"""""" + +.. code-block:: LAMMPS + + fix ID group-ID efield/lepton V ... + +* ID, group-ID are documented in the :doc:`fix ` command +* style = *efield/lepton* +* V = electric potential (electric field * distance units) +* V must be a Lepton expression (see below) +* zero or more keyword/value pairs may be appended to args +* keyword = *region* or *step* + + .. parsed-literal:: + + *region* value = region-ID + region-ID = ID of region atoms must be in to have effect + *step* value = h + h = step size for numerical differentiation (distance units) + +Examples +"""""""" + +.. code-block:: LAMMPS + + fix ex all efield/lepton "-E*x; E=1" + fix dexx all efield/lepton "-0.5*x^2" step 1 + fix yukawa all efield/lepton "A*exp(-B*r)/r; r=abs(sqrt(x^2+y^2+z^2)); A=1; B=1" step 1e-6 + fix infp all efield/lepton "-abs(x)" step 1 + + variable th equal 2*PI*ramp(0,1) + fix erot all efield/lepton "-(x*cos(v_th)+y*sin(v_th))" + +Description +""""""""""" + +.. versionadded:: TBD + +Add an electric potential :math:`V` that applies to a group of charged atoms a force :math:`\vec{F} = q \vec{E}`, +and to dipoles a force :math:`\vec{F} = (\vec{p} \cdot \nabla) \vec{E}` and torque :math:`\vec{T} = \vec{p} \times \vec{E}`, +where :math:`\vec{E} = - \nabla V`. The fix also evaluates the electrostatic energy (:math:`U_{q} = q V` and :math:`U_{p} = - \vec{p} \cdot \vec{E}`) +due to this potential when the :doc:`fix_modify energy yes ` command is specified (see below). + +.. note:: + + This command should be used instead of :doc:`fix efield ` if you want to impose a non-uniform electric field on a system with dipoles + since the latter does not include the dipole force term. If you only have charges or if the electric field gradient is negligible, + :doc:`fix efield ` should be used since it is faster. + +The `Lepton library `_, that the *efield/lepton* fix style interfaces with, evaluates +the expression string at run time to compute the energy, forces, and torques. It creates an analytical representation +of :math:`V` and :math:`\vec{E}`, while the gradient force is computed using a central difference scheme + +.. math:: + + \vec{F} = \frac{|\vec{p}|}{2h} \left[ \vec{E}(\vec{x} + h \hat{p}) - \vec{E}(\vec{x} - h \hat{p}) \right] . + +The Lepton expression must be either enclosed in quotes or must not contain any whitespace so that LAMMPS +recognizes it as a single keyword. More on valid Lepton expressions below. The final Lepton expression must +be a function of only :math:`x, y, z`, which refer to the current *unwrapped* coordinates of the atoms to ensure continuity. +Special care must be taken when using this fix with periodic boundary conditions or box-changing commands. + +---------- + +.. include:: lepton_expression.rst + +---------- + +If the *region* keyword is used, the atom must also be in the specified +geometric :doc:`region ` in order to be affected by the potential. + +The *step* keyword is required when :doc:`atom_style dipole ` is used and the electric field is non-uniform. + +---------- + +Restart, fix_modify, output, run start/stop, minimize info +""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" + +No information about this fix is written to :doc:`binary restart files +`. + +The :doc:`fix_modify ` *energy* option is supported by this +fix to add the potential energy defined above to the global potential energy +of the system as part of :doc:`thermodynamic output `. +The default setting for this fix is :doc:`fix_modify energy no `. + +The :doc:`fix_modify ` *virial* option is supported by this +fix to add the contribution due to the added ***forces*** on charges and dipoles +to both the global pressure and per-atom stress of the system via the +:doc:`compute pressure ` and :doc:`compute stress/atom +` commands. The former can be accessed by +:doc:`thermodynamic output `. The default setting for +this fix is :doc:`fix_modify virial no `. + +The :doc:`fix_modify ` *respa* option is supported by this +fix. This allows to set at which level of the :doc:`r-RESPA ` +integrator the fix adding its forces. Default is the outermost level. + +This fix computes a global scalar and a global 3-vector of forces, +which can be accessed by various :doc:`output commands `. +The scalar is the potential energy discussed above. +The vector is the total force added to the group of atoms. +The scalar and vector values calculated by this fix are "extensive". + +This fix cannot be used with the *start/stop* keywords of +the :doc:`run ` command. + +The forces due to this fix are imposed during an energy minimization, +invoked by the :doc:`minimize ` command. You should not +specify force components with a variable that has time-dependence for +use with a minimizer, since the minimizer increments the timestep as +the iteration count during the minimization. + +.. note:: + + If you want the electric potential energy to be included in the + total potential energy of the system (the quantity being minimized), + you MUST enable the :doc:`fix_modify ` *energy* option for this fix. + +---------- + +Restrictions +"""""""""""" + +Fix style *efield/lepton* is part of the LEPTON package. It is only enabled if LAMMPS was built with that package. +See the :doc:`Build package ` page for more info. + + +Related commands +"""""""""""""""" + +:doc:`fix efield ` + +Default +""""""" + +none diff --git a/examples/LEPTON/in.efield-lepton b/examples/LEPTON/in.efield-lepton index 00ba8fa112..176eb3ca63 100644 --- a/examples/LEPTON/in.efield-lepton +++ b/examples/LEPTON/in.efield-lepton @@ -1,50 +1,50 @@ -# Point dipoles in a 3d box with an external potential (ignoring dipolar interactions) - -units lj -atom_style hybrid sphere dipole -dimension 3 -boundary s s s -region box block -2 2 -2 2 -2 2 - -create_box 1 box -create_atoms 1 random 100 12345 NULL - -# need both mass settings due to hybrid atom style -mass 1 1.0 -set group all mass 1.0 -set group all diameter 0.1 - -set group all dipole/random 98934 0.01 -pair_style none -comm_modify cutoff 3.0 - -velocity all create 0.0 87287 mom yes rot yes - -fix 1 all nve/sphere update dipole - -############################################################################################################### -## Yukawa potential -#fix 2 all efield/lepton "A*exp(-B*r)/r; r=abs(sqrt(x^2+y^2+z^2)); A = 0.1; B = 5" step 1e-8 - -## Gradually increasing uniform field -#variable E equal ramp(0,1) -#fix 2 all efield/lepton "-v_E*(x+y+z)" - -## Linear gradient field -fix 2 all efield/lepton "-1/6*x^3" step 1e-6 - -fix_modify 2 energy yes - -############################################################################################################### - -timestep 1e-3 - -compute erot all erotate/sphere -variable etotal equal "ke + c_erot + pe" # thermo etotal doesn't include erot -thermo_style custom step temp ke c_erot pe v_etotal -thermo 500 -thermo_modify norm no - -#dump 1 all custom 500 dump.dipole id x y z diameter mux muy muz fx fy fz tqx tqy tqz - -run 10000 +# Point dipoles in a 3d box with an external potential (ignoring dipolar interactions) + +units lj +atom_style hybrid sphere dipole +dimension 3 +boundary s s s +region box block -2 2 -2 2 -2 2 + +create_box 1 box +create_atoms 1 random 100 12345 NULL + +# need both mass settings due to hybrid atom style +mass 1 1.0 +set group all mass 1.0 +set group all diameter 0.1 + +set group all dipole/random 98934 0.01 +pair_style none +comm_modify cutoff 3.0 + +velocity all create 0.0 87287 mom yes rot yes + +fix 1 all nve/sphere update dipole + +############################################################################################################### +## Yukawa potential +#fix 2 all efield/lepton "A*exp(-B*r)/r; r=abs(sqrt(x^2+y^2+z^2)); A = 0.1; B = 5" step 1e-8 + +## Gradually increasing uniform field +#variable E equal ramp(0,1) +#fix 2 all efield/lepton "-v_E*(x+y+z)" + +## Linear gradient field +fix 2 all efield/lepton "-1/6*x^3" step 1e-6 + +fix_modify 2 energy yes + +############################################################################################################### + +timestep 1e-3 + +compute erot all erotate/sphere +variable etotal equal "ke + c_erot + pe" # thermo etotal doesn't include erot +thermo_style custom step temp ke c_erot pe v_etotal +thermo 500 +thermo_modify norm no + +#dump 1 all custom 500 dump.dipole id x y z diameter mux muy muz fx fy fz tqx tqy tqz + +run 10000