diff --git a/doc/src/compute_local_composition_atom.rst b/doc/src/compute_local_composition_atom.rst index 270783d749..2b8fb7f080 100644 --- a/doc/src/compute_local_composition_atom.rst +++ b/doc/src/compute_local_composition_atom.rst @@ -32,85 +32,91 @@ Examples compute 1 all local_composition/atom cutoff 9.0 comm_modify cutoff 9.0 -.. - ****** UNDER CONSTRUCTION ****** - Description - """"""""""" - .. versionadded:: 24May2023 +Description +""""""""""" - Define a computation that calculates the local composition for each atom based on its neighbors inside a spherical - cutoff. If an atom has :math:`M` neighbors, then its local mass density is - calculated as the sum of its mass and its :math:`M` neighbor masses, divided - by the volume of the cutoff sphere (or circle in 2d). The local - temperature of the atom is calculated as the temperature of the - collection of :math:`M+1` atoms, after subtracting the center-of-mass velocity - of the :math:`M+1` atoms from each of the :math:`M+1` atom's velocities. This - is effectively the thermal velocity of the neighborhood of the central - atom, similar to :doc:`compute temp/com `. +.. versionadded:: 24May2023 - The optional keyword *cutoff* defines the distance cutoff used when - searching for neighbors. The default value is the cutoff specified by - the pair style. If no pair style is defined, then a cutoff must be - defined using this keyword. If the specified cutoff is larger than - that of the pair_style plus neighbor skin (or no pair style is - defined), the *comm_modify cutoff* option must also be set to match - that of the *cutoff* keyword. +Define a computation that calculates the local composition of atom types for a +central atom based on its neighbors inside a spherical cutoff. For a simulation with +:math:`N` atom types and an atom with :math:`M` neighbors within the cutoff, the +fraction of each atom type is counted and divided by the total number of atoms in the +sphere, including the central atom (:math:`M+1`). The sum of all fractions will +always add to one. - The neighbor list needed to compute this quantity is constructed each - time the calculation is performed (i.e. each time a snapshot of atoms - is dumped). Thus it can be inefficient to compute/dump this quantity - too frequently. +.. note:: - .. note:: + This compute uses the number of atom types, not chemical species, assigned in + :doc:`pair_coeff ` command. If an interatomic potential has two + species (i.e., Cu and Ni) assigned to four different atom types in + :doc:`pair_coeff ` (i.e., 'Cu Cu Ni Ni'), the local composition will + output four fractional values. In those cases, the user may desire an extra + calculation step to consolidate per-type fractions into per-species fractions. + This calculation can be conducted within LAMMPS using another compute such as + :doc:`compute reduce `, an atom-style :doc:`variable`, or as a + post-processing step. - If you have a bonded system, then the settings of - :doc:`special_bonds ` command can remove pairwise - interactions between atoms in the same bond, angle, or dihedral. - This is the default setting for the :doc:`special_bonds - ` command, and means those pairwise interactions do - not appear in the neighbor list. Because this compute uses the - neighbor list, it also means those pairs will not be included in - the order parameter. This difficulty can be circumvented by - writing a dump file, and using the :doc:`rerun ` command to - compute the order parameter for snapshots in the dump file. The - rerun script can use a :doc:`special_bonds ` command - that includes all pairs in the neighbor list. +---------- - ---------- +The optional keyword *cutoff* defines the distance cutoff used when +searching for neighbors. The default value is the cutoff specified by +the pair style. If no pair style is defined, then a cutoff must be +defined using this keyword. If the specified cutoff is larger than +that of the pair_style plus neighbor skin (or no pair style is +defined), the *comm_modify cutoff* option must also be set to match +that of the *cutoff* keyword. + +The neighbor list needed to compute this quantity is constructed each +time the calculation is performed (i.e. each time a snapshot of atoms +is dumped). Thus it can be inefficient to compute/dump this quantity +too frequently. + +.. note:: + + If you have a bonded system, then the settings of + :doc:`special_bonds ` command can remove pairwise + interactions between atoms in the same bond, angle, or dihedral. + This is the default setting for the :doc:`special_bonds + ` command, and means those pairwise interactions do + not appear in the neighbor list. Because this compute uses the + neighbor list, it also means those pairs will not be included in + the order parameter. This difficulty can be circumvented by + writing a dump file, and using the :doc:`rerun ` command to + compute the order parameter for snapshots in the dump file. The + rerun script can use a :doc:`special_bonds ` command + that includes all pairs in the neighbor list. + +---------- - .. include:: accel_styles.rst +.. include:: accel_styles.rst - ---------- +---------- - Output info - """"""""""" +Output info +""""""""""" - This compute calculates a per-atom array with two columns: mass - density in density :doc:`units ` and temperature in temperature - :doc:`units `. +This compute calculates a per-atom array with :math:`1 + N` columns, where :math:`N` is the number of atom types. The first column is a count of the number of atoms used to calcuate composition (including the central atom), and each subsequent column indicates the fraction of that atom type detected within the cutoff range. - These values can be accessed by any command that uses per-atom values - from a compute as input. See the :doc:`Howto output ` - doc page for an overview of LAMMPS output options. +These values can be accessed by any command that uses per-atom values +from a compute as input. See the :doc:`Howto output ` +doc page for an overview of LAMMPS output options. - Restrictions - """""""""""" +Restrictions +"""""""""""" - This compute is part of the EXTRA-COMPUTE package. It is only enabled - if LAMMPS was built with that package. See the :doc:`Build package - ` page for more info. +This compute is part of the EXTRA-COMPUTE package. It is only enabled +if LAMMPS was built with that package. See the :doc:`Build package +` page for more info. - Related commands - """""""""""""""" +Related commands +"""""""""""""""" - :doc:`comm_modify ` +:doc:`comm_modify ` - Default - """"""" +Default +""""""" - The option defaults are *cutoff* = pair style cutoff. - -.. \ No newline at end of file +The option defaults are *cutoff* = pair style cutoff.