fully integrate fix widom into manual. fix some style issues and reindent

   * :doc:`wall/region <fix_wall_region>`

   * :doc:`wall/region/ees <fix_wall_ees>`

   * :doc:`wall/srd <fix_wall_srd>`

   * :doc:`widom <fix_widom>`

* :doc:`wall/region <fix_wall_region>` - use region surface as wall

* :doc:`wall/region/ees <fix_wall_ees>` - use region surface as wall for ellipsoidal particles

* :doc:`wall/srd <fix_wall_srd>` - slip/no-slip wall for SRD particles

* :doc:`widom <fix_widom>` - Widom insertions of atoms or molecules

Restrictions

""""""""""""

Description

"""""""""""

This fix performs Widom insertions of

atoms or molecules at the given temperature as discussed

in :ref:`(Frenkel) <Frenkel>`. Specific uses include computation of Henry constants 

of small molecules in microporous materials or amorphous systems.

This fix performs Widom insertions of atoms or molecules at the given

temperature as discussed in :ref:`(Frenkel) <Frenkel>`. Specific uses

include computation of Henry constants of small molecules in microporous

materials or amorphous systems.

Every N timesteps the fix attempts M number of Widom insertions of atoms or molecules.

Every N timesteps the fix attempts M number of Widom insertions of atoms

or molecules.

If the *mol* keyword is used, only molecule insertions are performed.

Conversely, if the *mol* keyword is not used, only atom insertions are performed.

Conversely, if the *mol* keyword is not used, only atom insertions are

performed.

This command may optionally use the *region* keyword to define an

insertion volume.  The specified region must have been

previously defined with a :doc:`region <region>` command.  It must be

defined with side = *in*\ .  Insertion attempts occur only within the

specified region. For non-rectangular regions, random trial points are

generated within the rectangular bounding box until a point is found

that lies inside the region. If no valid point is generated after 1000

trials, no insertion is performed. If an attempted insertion places the atom or molecule

center-of-mass outside the specified region, a new attempted insertion is

generated. This process is repeated until the atom or molecule

center-of-mass is inside the specified region.

insertion volume.  The specified region must have been previously

defined with a :doc:`region <region>` command.  It must be defined with

side = *in*\ .  Insertion attempts occur only within the specified

region. For non-rectangular regions, random trial points are generated

within the rectangular bounding box until a point is found that lies

inside the region. If no valid point is generated after 1000 trials, no

insertion is performed. If an attempted insertion places the atom or

molecule center-of-mass outside the specified region, a new attempted

insertion is generated. This process is repeated until the atom or

molecule center-of-mass is inside the specified region.

Note that neighbor lists are re-built every timestep that this fix is

invoked, so you should not set N to be too small. See 

the :doc:`neighbor <neighbor>` command for details.

invoked, so you should not set N to be too small. See the :doc:`neighbor

<neighbor>` command for details.

When an atom or molecule is to be inserted, its coordinates are chosen

at a random position within the current simulation cell or regionRelative coordinates for atoms in a

molecule are taken from the template molecule provided by the

user. The center of mass of the molecule is placed at the insertion

point. The orientation of the molecule is chosen at random by rotating

about this point.

at a random position within the current simulation cell or

regionRelative coordinates for atoms in a molecule are taken from the

template molecule provided by the user. The center of mass of the

molecule is placed at the insertion point. The orientation of the

molecule is chosen at random by rotating about this point.

Individual atoms are inserted, unless the *mol* keyword is used.  It

specifies a *template-ID* previously defined using the

:doc:`molecule <molecule>` command, which reads a file that defines the

molecule.  The coordinates, atom types, charges, etc., as well as any

bonding and special neighbor information for the molecule can

be specified in the molecule file.  See the :doc:`molecule <molecule>`

command for details.  The only settings required to be in this file

are the coordinates and types of atoms in the molecule.

specifies a *template-ID* previously defined using the :doc:`molecule

<molecule>` command, which reads a file that defines the molecule.  The

coordinates, atom types, charges, etc., as well as any bonding and

special neighbor information for the molecule can be specified in the

molecule file.  See the :doc:`molecule <molecule>` command for details.

The only settings required to be in this file are the coordinates and

types of atoms in the molecule.

If you wish to insert molecules via the *mol* keyword, that will have

their bonds or angles constrained via SHAKE, use the *shake* keyword,

specifying as its value the ID of a separate :doc:`fix shake <fix_shake>` command which also appears in your input script.

specifying as its value the ID of a separate :doc:`fix shake

<fix_shake>` command which also appears in your input script.

Note that fix widom does not use configurational bias MC or any other

kind of sampling of intramolecular degrees of freedom.  Inserted

same intramolecular configuration, which was specified in the molecule

command input.

For atoms, inserted particles have the specified atom type. 

For molecules, they use the same atom types as in the template molecule supplied

by the user.

For atoms, inserted particles have the specified atom type.  For

molecules, they use the same atom types as in the template molecule

supplied by the user.

The excess chemical potential mu_ex is defined as:

   \mu_{ex} = -kT \ln(<\exp(-(U_{N+1}-U_{N})/{kT})>)

where *k* is Boltzman's constant, *T* is the user-specified temperature, U_N and U_{N+1}

is the potential energy of the system with N and N+1 particles.

where *k* is Boltzman's constant, *T* is the user-specified temperature,

U_N and U_{N+1} is the potential energy of the system with N and N+1

particles.

The *full_energy* option means that the fix calculates the total

potential energy of the entire simulated system, instead of just

the energy of the part that is changed. By default, this option is off,

in which case only

partial energies are computed to determine the energy difference

due to the proposed change.

potential energy of the entire simulated system, instead of just the

energy of the part that is changed. By default, this option is off, in

which case only partial energies are computed to determine the energy

difference due to the proposed change.

The *full_energy* option is needed for systems with complicated

potential energy calculations, including the following:

When the *mol* keyword is used, the *full_energy* option also includes

the intramolecular energy of inserted and deleted molecules, whereas

this energy is not included when *full_energy* is not used. If this

is not desired, the *intra_energy* keyword can be used to define an

amount of energy that is subtracted from the final energy when a

molecule is inserted, and subtracted from the initial energy when a molecule

is deleted. For molecules that have a non-zero intramolecular energy,

this will ensure roughly the same behavior whether or not the

*full_energy* option is used.

this energy is not included when *full_energy* is not used. If this is

not desired, the *intra_energy* keyword can be used to define an amount

of energy that is subtracted from the final energy when a molecule is

inserted, and subtracted from the initial energy when a molecule is

deleted. For molecules that have a non-zero intramolecular energy, this

will ensure roughly the same behavior whether or not the *full_energy*

option is used.

Some fixes have an associated potential energy. Examples of such fixes

include: :doc:`efield <fix_efield>`, :doc:`gravity <fix_gravity>`,

:doc:`addforce <fix_addforce>`,

:doc:`restrain <fix_restrain>`,

 and :doc:`wall fixes <fix_wall>`.

For that energy to be included in the total potential energy of the

system (the quantity used when performing Widom insertions),

you MUST enable

the :doc:`fix_modify <fix_modify>` *energy* option for that fix.  The

doc pages for individual :doc:`fix <fix>` commands specify if this

should be done.

:doc:`addforce <fix_addforce>`, :doc:`restrain <fix_restrain>`, and

:doc:`wall fixes <fix_wall>`.  For that energy to be included in the

total potential energy of the system (the quantity used when performing

Widom insertions), you MUST enable the :doc:`fix_modify <fix_modify>`

*energy* option for that fix.  The doc pages for individual :doc:`fix

<fix>` commands specify if this should be done.

Use the *charge* option to insert atoms with a user-specified point

charge. Note that doing so will cause the system to become

non-neutral.  LAMMPS issues a warning when using long-range

electrostatics (kspace) with non-neutral systems. See the :doc:`compute group/group <compute_group_group>` documentation for more details

about simulating non-neutral systems with kspace on.

charge. Note that doing so will cause the system to become non-neutral.

LAMMPS issues a warning when using long-range electrostatics (kspace)

with non-neutral systems. See the :doc:`compute group/group

<compute_group_group>` documentation for more details about simulating

non-neutral systems with kspace on.

**Restart, fix_modify, output, run start/stop, minimize info:**

This fix writes the state of the fix to :doc:`binary restart files <restart>`.  This includes information about the random

number generator seed, the next timestep for Widom insertions etc.  See

the :doc:`read_restart <read_restart>` command for info on how to

re-specify a fix in an input script that reads a restart file, so that

the operation of the fix continues in an uninterrupted fashion.

This fix writes the state of the fix to :doc:`binary restart files

<restart>`.  This includes information about the random number generator

seed, the next timestep for Widom insertions etc.  See the

:doc:`read_restart <read_restart>` command for info on how to re-specify

a fix in an input script that reads a restart file, so that the

operation of the fix continues in an uninterrupted fashion.

.. note::

   For this to work correctly, the timestep must **not** be changed

   after reading the restart with :doc:`reset_timestep <reset_timestep>`.

   The fix will try to detect it and stop with an error.

   after reading the restart with :doc:`reset_timestep

   <reset_timestep>`.  The fix will try to detect it and stop with an

   error.

None of the :doc:`fix_modify <fix_modify>` options are relevant to this

fix.

This fix computes a global vector of length 3, which can be accessed

by various :doc:`output commands <Howto_output>`.  The vector values are

This fix computes a global vector of length 3, which can be accessed by

various :doc:`output commands <Howto_output>`.  The vector values are

the following global cumulative quantities:

* 1 = average excess chemical potential on each timestep

The vector values calculated by this fix are "extensive".

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>`.

the :doc:`run <run>` command.  This fix is not invoked during

:doc:`energy minimization <minimize>`.

Restrictions

""""""""""""

doc page for more info.

Do not set "neigh_modify once yes" or else this fix will never be

called.  Reneighboring is required.

called.  Reneighboring is **required**.

Can be run in parallel, but aspects of the GCMC part will not scale

well in parallel. Only usable for 3D simulations.

Can be run in parallel, but aspects of the GCMC part will not scale well

in parallel. Only usable for 3D simulations.

Related commands

Default

"""""""

The option defaults are mol = no, intra_energy = 0.0 and full_energy = no,

except for the situations where full_energy is required, as

listed above.

The option defaults are mol = no, intra_energy = 0.0 and full_energy =

no, except for the situations where full_energy is required, as listed

above.

----------