ICODE-ADC/lammps
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

initial doc pages

Browse Source
This commit is contained in:
Steve Plimpton
2022-08-15 17:29:11 -06:00
parent ce4ca06035
commit e6e9e1b59c
4 changed files with 379 additions and 155 deletions
Download Patch File Download Diff File Expand all files Collapse all files

333
doc/src/Howto_output.rst
View File

@ -22,14 +22,17 @@ commands you specify.
As discussed below, LAMMPS gives you a variety of ways to determine
what quantities are computed and printed when the thermodynamics,
dump, or fix commands listed above perform output. Throughout this
discussion, note that users can also :doc:`add their own computes and fixes to LAMMPS <Modify>` which can then generate values that can then be
output with these commands.
discussion, note that users can also :doc:`add their own computes and
fixes to LAMMPS <Modify>` which can then generate values that can then
be output with these commands.
The following sub-sections discuss different LAMMPS command related
The following sub-sections discuss different LAMMPS commands related
to output and the kind of data they operate on and produce:
* :ref:`Global/per-atom/local data <global>`
* :ref:`Global/per-atom/local/per-grid data <global>`
* :ref:`Scalar/vector/array data <scalar>`
* :ref:`Per-grid data <grid>`
* :ref:`Disambiguation <disambiguation>`
* :ref:`Thermodynamic output <thermo>`
* :ref:`Dump file output <dump>`
* :ref:`Fixes that write output files <fixoutput>`
@ -42,27 +45,32 @@ to output and the kind of data they operate on and produce:
.. _global:
Global/per-atom/local data
--------------------------
Global/per-atom/local/per-grid data
-----------------------------------
Various output-related commands work with three different styles of
data: global, per-atom, or local. A global datum is one or more
system-wide values, e.g. the temperature of the system. A per-atom
datum is one or more values per atom, e.g. the kinetic energy of each
atom. Local datums are calculated by each processor based on the
atoms it owns, but there may be zero or more per atom, e.g. a list of
bond distances.
Various output-related commands work with four different styles of
data: global, per-atom, local, and per-grid. A global datum is one or
more system-wide values, e.g. the temperature of the system. A
per-atom datum is one or more values per atom, e.g. the kinetic energy
of each atom. Local datums are calculated by each processor based on
the atoms it owns, but there may be zero or more per atom, e.g. a list
of bond distances.
A per-grid datum is one or more values per grid point, for a grid
which overlays the simulation domain. Each processor owns the grid
points which fall within its sub-domain. Thus the grid points and the
data they store are distributed across processors.
.. _scalar:
Scalar/vector/array data
------------------------
Global, per-atom, and local datums can each come in three kinds: a
single scalar value, a vector of values, or a 2d array of values. The
doc page for a "compute" or "fix" or "variable" that generates data
will specify both the style and kind of data it produces, e.g. a
per-atom vector.
Global, per-atom, and local datums can come in three kinds: a single
scalar value, a vector of values, or a 2d array of values. The doc
page for a "compute" or "fix" or "variable" that generates data will
specify both the style and kind of data it produces, e.g. a per-atom
vector.
When a quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
@ -83,6 +91,39 @@ the dimension twice (array -> scalar). Thus a command that uses
scalar values as input can typically also process elements of a vector
or array.
.. _grid:
Per-grid data
------------------------
Per-grid data can come in two kinds: a vector of values (one per grid
point), or a 2d array of values (multiple values per grid point). The
doc page for a "compute" or "fix" that generates data will specify
both the style and kind of data it produces, e.g. a per-grid vector or
array.
Only computes and fixes produce and output per-grid data. Per-grid
variables have not (yet) been implemented. A compute or fix may
define one or more grids, e.g. of differing sizes. Each grid can
store one or more data fields.
Another command accesses grid data in the following syntax:
* c_ID:gname:dname
* c_ID:gname:dname[I]
* f_ID:gname:dname
* f_ID:gname:dname[I]
The prefix "c_" or "f_" refers to the ID of the compute or fix. Gname
is the name of the grid, which is assinged by the compute or fix.
Dname is the name of the data field, which is also assinged by the
compute or fix. If the data field is a per-grid vector (one value per
grid point), then no brackets are used to access the values. If the
data field is a per-grid array (multiple values per grid point), then
brackets are used to specify the column I of the array. I ranges from
1 to Ncol inclusive, where Ncol is the number of columns in the array
and is defined by the compute or fix.
.. _disambiguation:
Disambiguation
@ -90,15 +131,15 @@ Disambiguation
Some computes and fixes produce data in multiple styles, e.g. a global
scalar and a per-atom vector. Usually the context in which the input
script references the data determines which style is meant. Example: if
a compute provides both a global scalar and a per-atom vector, the
script references the data determines which style is meant. Example:
if a compute provides both a global scalar and a per-atom vector, the
former will be accessed by using ``c_ID`` in an equal-style variable,
while the latter will be accessed by using ``c_ID`` in an atom-style
variable. Note that atom-style variable formulas can also access global
scalars, but in this case it is not possible to do directly because of
the ambiguity. Instead, an equal-style variable can be defined which
accesses the global scalar, and that variable used in the atom-style
variable formula in place of ``c_ID``.
variable. Note that atom-style variable formulas can also access
global scalars, but in this case it is not possible to do this
directly because of the ambiguity. Instead, an equal-style variable
can be defined which accesses the global scalar, and that variable can
be used in the atom-style variable formula in place of ``c_ID``.
.. _thermo:
@ -141,9 +182,10 @@ There is also a :doc:`dump custom <dump>` format where the user
specifies what values are output with each atom. Pre-defined atom
attributes can be specified (id, x, fx, etc). Three additional kinds
of keywords can also be specified (c_ID, f_ID, v_name), where a
:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable <variable>`
provides the values to be output. In each case, the compute, fix, or
variable must generate per-atom values for input to the :doc:`dump custom <dump>` command.
:doc:`compute <compute>` or :doc:`fix <fix>` or :doc:`variable
<variable>` provides the values to be output. In each case, the
compute, fix, or variable must generate per-atom values for input to
the :doc:`dump custom <dump>` command.
There is also a :doc:`dump local <dump>` format where the user specifies
what local values to output. A pre-defined index keyword can be
@ -154,18 +196,23 @@ provides the values to be output. In each case, the compute or fix
must generate local values for input to the :doc:`dump local <dump>`
command.
There is also a :doc:`dump grid <dump>` format where the user
specifies what per-grid values to output (c_ID:gname:fname or
f_ID:gname:fname) from computes of fixes that generate per-grid data.
.. _fixoutput:
Fixes that write output files
-----------------------------
Several fixes take various quantities as input and can write output
files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`,
:doc:`fix ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
files: :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/chunk
<fix_ave_chunk>`, :doc:`fix ave/histo <fix_ave_histo>`, :doc:`fix
ave/correlate <fix_ave_correlate>`, and :doc:`fix print <fix_print>`.
The :doc:`fix ave/time <fix_ave_time>` command enables direct output to
a file and/or time-averaging of global scalars or vectors. The user
specifies one or more quantities as input. These can be global
The :doc:`fix ave/time <fix_ave_time>` command enables direct output
to a file and/or time-averaging of global scalars or vectors. The
user specifies one or more quantities as input. These can be global
:doc:`compute <compute>` values, global :doc:`fix <fix>` values, or
:doc:`variables <variable>` of any style except the atom style which
produces per-atom values. Since a variable can refer to keywords used
@ -184,8 +231,14 @@ atoms, e.g. individual molecules. The per-atom quantities can be atom
density (mass or number) or atom attributes such as position,
velocity, force. They can also be per-atom quantities calculated by a
:doc:`compute <compute>`, by a :doc:`fix <fix>`, or by an atom-style
:doc:`variable <variable>`. The chunk-averaged output of this fix can
also be used as input to other output commands.
:doc:`variable <variable>`. The chunk-averaged output of this fix is
global and can also be used as input to other output commands.
Note that the :doc:`fix ave/grid <fix_ave_grid>` command can also
average the same per-atom quantities within spatial bins, but it does
this for a distributed grid whose grid points are owned by different
processors. It outputs per-grid data, not global data, so is more
efficient for large numbers of averaging bins.
The :doc:`fix ave/histo <fix_ave_histo>` command enables direct output
to a file of histogrammed quantities, which can be global or per-atom
@ -202,38 +255,53 @@ written to the screen and log file or to a separate file, periodically
during a running simulation. The line can contain one or more
:doc:`variable <variable>` values for any style variable except the
vector or atom styles). As explained above, variables themselves can
contain references to global values generated by :doc:`thermodynamic keywords <thermo_style>`, :doc:`computes <compute>`,
:doc:`fixes <fix>`, or other :doc:`variables <variable>`, or to per-atom
values for a specific atom. Thus the :doc:`fix print <fix_print>`
command is a means to output a wide variety of quantities separate
from normal thermodynamic or dump file output.
contain references to global values generated by :doc:`thermodynamic
keywords <thermo_style>`, :doc:`computes <compute>`, :doc:`fixes
<fix>`, or other :doc:`variables <variable>`, or to per-atom values
for a specific atom. Thus the :doc:`fix print <fix_print>` command is
a means to output a wide variety of quantities separate from normal
thermodynamic or dump file output.
.. _computeoutput:
Computes that process output quantities
---------------------------------------
The :doc:`compute reduce <compute_reduce>` and :doc:`compute reduce/region <compute_reduce>` commands take one or more per-atom
or local vector quantities as inputs and "reduce" them (sum, min, max,
The :doc:`compute reduce <compute_reduce>` and :doc:`compute
reduce/region <compute_reduce>` commands take one or more per-atom or
local vector quantities as inputs and "reduce" them (sum, min, max,
ave) to scalar quantities. These are produced as output values which
can be used as input to other output commands.
The :doc:`compute slice <compute_slice>` command take one or more global
vector or array quantities as inputs and extracts a subset of their
values to create a new vector or array. These are produced as output
values which can be used as input to other output commands.
The :doc:`compute slice <compute_slice>` command take one or more
global vector or array quantities as inputs and extracts a subset of
their values to create a new vector or array. These are produced as
output values which can be used as input to other output commands.
The :doc:`compute property/atom <compute_property_atom>` command takes a
list of one or more pre-defined atom attributes (id, x, fx, etc) and
The :doc:`compute property/atom <compute_property_atom>` command takes
a list of one or more pre-defined atom attributes (id, x, fx, etc) and
stores the values in a per-atom vector or array. These are produced
as output values which can be used as input to other output commands.
The list of atom attributes is the same as for the :doc:`dump custom <dump>` command.
The list of atom attributes is the same as for the :doc:`dump custom
<dump>` command.
The :doc:`compute property/local <compute_property_local>` command takes
a list of one or more pre-defined local attributes (bond info, angle
info, etc) and stores the values in a local vector or array. These
are produced as output values which can be used as input to other
output commands.
The :doc:`compute property/local <compute_property_local>` command
takes a list of one or more pre-defined local attributes (bond info,
angle info, etc) and stores the values in a local vector or array.
These are produced as output values which can be used as input to
other output commands.
The :doc:`compute property/grid <compute_property_grid>` command takes
a list of one or more pre-defined per-grid attributes (id, grid point
coords, etc) and stores the values in a per-grid vector or array.
These are produced as output values which can be used as input to the
:doc:`dump grid <dump>` command.
The :doc:`compute property/chunk <compute_property_chunk>` command
takes a list of one or more pre-defined chunk attributes (id, count,
coords for spatial bins) and stores the values in a global vector or
array. These are produced as output values which can be used as input
to other output commands.
.. _fixprocoutput:
@ -247,18 +315,42 @@ a time.
The :doc:`fix ave/atom <fix_ave_atom>` command performs time-averaging
of per-atom vectors. The per-atom quantities can be atom attributes
such as position, velocity, force. They can also be per-atom
quantities calculated by a :doc:`compute <compute>`, by a
:doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`. The
quantities calculated by a :doc:`compute <compute>`, by a :doc:`fix
<fix>`, or by an atom-style :doc:`variable <variable>`. The
time-averaged per-atom output of this fix can be used as input to
other output commands.
The :doc:`fix store/state <fix_store_state>` command can archive one or
more per-atom attributes at a particular time, so that the old values
can be used in a future calculation or output. The list of atom
attributes is the same as for the :doc:`dump custom <dump>` command,
including per-atom quantities calculated by a :doc:`compute <compute>`,
by a :doc:`fix <fix>`, or by an atom-style :doc:`variable <variable>`.
The output of this fix can be used as input to other output commands.
The :doc:`fix store/state <fix_store_state>` command can archive one
or more per-atom attributes at a particular time, so that the old
values can be used in a future calculation or output. The list of
atom attributes is the same as for the :doc:`dump custom <dump>`
command, including per-atom quantities calculated by a :doc:`compute
<compute>`, by a :doc:`fix <fix>`, or by an atom-style :doc:`variable
<variable>`. The output of this fix can be used as input to other
output commands.
The :doc:`fix ave/grid <fix_ave_grid>` command performs time-averaging
of either per-atom or per-grid data.
For per-atom data it performs averaging for the atoms within each grid
cell, similar to the :doc:`fix ave/chunk <fix_ave_chunk>` command when
its chunks are defined as regular 2d or 3d bins. The per-atom
quantities can be atom density (mass or number) or atom attributes
such as position, velocity, force. They can also be per-atom
quantities calculated by a :doc:`compute <compute>`, by a :doc:`fix
<fix>`, or by an atom-style :doc:`variable <variable>`.
The chief difference between the :doc:`fix ave/grid <fix_ave_grid>`
and :doc:`fix ave/chunk <fix_ave_chunk>` commands when used in this
context is that the former uses a distributed grid, while the latter
uses a global grid. Distributed means that each processor owns the
subset of grid points within its subdomain. Global means that each
processor owns a copy of the entire grid. Distributed is thus more
efficient for large grids.
For per-grid data, the :doc:`fix ave/grid <fix_ave_grid>` command
takes inputs for grid data produced by other computes or fixes and
averages the values for each grid point over time.
.. _compute:
@ -266,24 +358,25 @@ Computes that generate values to output
---------------------------------------
Every :doc:`compute <compute>` in LAMMPS produces either global or
per-atom or local values. The values can be scalars or vectors or
arrays of data. These values can be output using the other commands
described in this section. The page for each compute command
per-atom or local or per-grid values. The values can be scalars or
vectors or arrays of data. These values can be output using the other
commands described in this section. The page for each compute command
describes what it produces. Computes that produce per-atom or local
values have the word "atom" or "local" in their style name. Computes
without the word "atom" or "local" produce global values.
or per-grid values have the word "atom" or "local" or "grid as the
last word in their style name. Computes without the word "atom" or
"local" or "grid" produce global values.
.. _fix:
Fixes that generate values to output
------------------------------------
Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom or
local values which can be accessed by other commands. The values can
be scalars or vectors or arrays of data. These values can be output
using the other commands described in this section. The page for
each fix command tells whether it produces any output quantities and
describes them.
Some :doc:`fixes <fix>` in LAMMPS produces either global or per-atom
or local or per-grid values which can be accessed by other commands.
The values can be scalars or vectors or arrays of data. These values
can be output using the other commands described in this section. The
page for each fix command tells whether it produces any output
quantities and describes them.
.. _variable:
@ -300,6 +393,8 @@ computes, fixes, and other variables. The values generated by
variables can be used as input to and thus output by the other
commands described in this section.
Per-grid variables have not (yet) been implemented.
.. _table:
Summary table of output options and data flow between commands
@ -319,44 +414,52 @@ Also note that, as described above, when a command takes a scalar as
input, that could be an element of a vector or array. Likewise a
vector input could be a column of an array.
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| Command | Input | Output |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`thermo_style custom <thermo_style>` | global scalars | screen, log file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`dump custom <dump>` | per-atom vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`dump local <dump>` | local vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix print <fix_print>` | global scalar from variable | screen, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`print <print>` | global scalar from variable | screen |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`computes <compute>` | N/A | global/per-atom/local scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fixes <fix>` | N/A | global/per-atom/local scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`variables <variable>` | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute reduce <compute_reduce>` | per-atom/local vectors | global scalar/vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute slice <compute_slice>` | global vectors/arrays | global vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute property/atom <compute_property_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`compute property/local <compute_property_local>` | local vectors | local vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix vector <fix_vector>` | global scalars | global vector |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/atom <fix_ave_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/time <fix_ave_time>` | global scalars/vectors | global scalar/vector/array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/chunk <fix_ave_chunk>` | per-atom vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/histo <fix_ave_histo>` | global/per-atom/local scalars and vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix ave/correlate <fix_ave_correlate>` | global scalars | global array, file |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
| :doc:`fix store/state <fix_store_state>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+-------------------------------------------+
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| Command | Input | Output |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`thermo_style custom <thermo_style>` | global scalars | screen, log file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`dump custom <dump>` | per-atom vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`dump local <dump>` | local vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`dump grid <dump>` | per-grid vectors | dump file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix print <fix_print>` | global scalar from variable | screen, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`print <print>` | global scalar from variable | screen |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`computes <compute>` | N/A | global/per-atom/local/per-grid scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fixes <fix>` | N/A | global/per-atom/local/per-grid scalar/vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`variables <variable>` | global scalars and vectors, per-atom vectors | global scalar and vector, per-atom vector |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute reduce <compute_reduce>` | per-atom/local vectors | global scalar/vector |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute slice <compute_slice>` | global vectors/arrays | global vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/atom <compute_property_atom>` | N/A | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/local <compute_property_local>` | N/A | local vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/grid <compute_property_grid>` | N/A | per-grid vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`compute property/chunk <compute_property_chunk>` | N/A | global vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix vector <fix_vector>` | global scalars | global vector |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/atom <fix_ave_atom>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/time <fix_ave_time>` | global scalars/vectors | global scalar/vector/array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/chunk <fix_ave_chunk>` | per-atom vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/grid <fix_ave_grid>` | per-atom vectors or per-grid vectors | per-grid vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/histo <fix_ave_histo>` | global/per-atom/local scalars and vectors | global array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix ave/correlate <fix_ave_correlate>` | global scalars | global array, file |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+
| :doc:`fix store/state <fix_store_state>` | per-atom vectors | per-atom vector/array |
+--------------------------------------------------------+----------------------------------------------+----------------------------------------------------+

65
doc/src/compute_property_chunk.rst
View File

@ -12,7 +12,8 @@ Syntax
* ID, group-ID are documented in :doc:`compute <compute>` command
* property/chunk = style name of this compute command
* input = one or more attributes
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command that defines the chunks
* input1,etc = one or more attributes
.. parsed-literal::
@ -26,8 +27,8 @@ Examples
.. code-block:: LAMMPS
compute 1 all property/chunk count
compute 1 all property/chunk ID coord1
compute 1 all property/chunk bin2d id count
compute 1 all property/chunk myChunks id coord1
Description
"""""""""""
@ -35,24 +36,28 @@ Description
Define a computation that stores the specified attributes of chunks of
atoms.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute chunk/atom <compute_chunk_atom>` command, which assigns each atom
to a single chunk (or no chunk). The ID for this command is specified
as chunkID. For example, a single chunk could be the atoms in a
molecule or atoms in a spatial bin. See the :doc:`compute chunk/atom <compute_chunk_atom>` and :doc:`Howto chunk <Howto_chunk>`
doc pages for details of how chunks can be defined and examples of how
they can be used to measure properties of a system.
In LAMMPS, chunks are collections of atoms defined by a :doc:`compute
chunk/atom <compute_chunk_atom>` command, which assigns each atom to a
single chunk (or no chunk). The ID for this command is specified as
chunkID. For example, a single chunk could be the atoms in a molecule
or atoms in a spatial bin. See the :doc:`compute chunk/atom
<compute_chunk_atom>` and :doc:`Howto chunk <Howto_chunk>` doc pages
for details of how chunks can be defined and examples of how they can
be used to measure properties of a system.
This compute calculates and stores the specified attributes of chunks
as global data so they can be accessed by other :doc:`output commands <Howto_output>` and used in conjunction with other
commands that generate per-chunk data, such as :doc:`compute com/chunk <compute_com_chunk>` or :doc:`compute msd/chunk <compute_msd_chunk>`.
as global data so they can be accessed by other :doc:`output commands
<Howto_output>` and used in conjunction with other commands that
generate per-chunk data, such as :doc:`compute com/chunk
<compute_com_chunk>` or :doc:`compute msd/chunk <compute_msd_chunk>`.
Note that only atoms in the specified group contribute to the
calculation of the *count* attribute. The :doc:`compute chunk/atom <compute_chunk_atom>` command defines its own group;
atoms will have a chunk ID = 0 if they are not in that group,
signifying they are not assigned to a chunk, and will thus also not
contribute to this calculation. You can specify the "all" group for
this command if you simply want to include atoms with non-zero chunk
IDs.
calculation of the *count* attribute. The :doc:`compute chunk/atom
<compute_chunk_atom>` command defines its own group; atoms will have a
chunk ID = 0 if they are not in that group, signifying they are not
assigned to a chunk, and will thus also not contribute to this
calculation. You can specify the "all" group for this command if you
simply want to include atoms with non-zero chunk IDs.
The *count* attribute is the number of atoms in the chunk.
@ -61,21 +66,23 @@ can only be used if the *compress* keyword was set to *yes* for the
:doc:`compute chunk/atom <compute_chunk_atom>` command referenced by
chunkID. This means that the original chunk IDs (e.g. molecule IDs)
will have been compressed to remove chunk IDs with no atoms assigned
to them. Thus a compressed chunk ID of 3 may correspond to an original
chunk ID (molecule ID in this case) of 415. The *id* attribute will
then be 415 for the third chunk.
to them. Thus a compressed chunk ID of 3 may correspond to an
original chunk ID (molecule ID in this case) of 415. The *id*
attribute will then be 415 for the third chunk.
The *coordN* attributes can only be used if a *binning* style was used
in the :doc:`compute chunk/atom <compute_chunk_atom>` command referenced
by chunkID. For *bin/1d*, *bin/2d*, and *bin/3d* styles the attribute
is the center point of the bin in the corresponding dimension. Style
*bin/1d* only defines a *coord1* attribute. Style *bin/2d* adds a
*coord2* attribute. Style *bin/3d* adds a *coord3* attribute.
in the :doc:`compute chunk/atom <compute_chunk_atom>` command
referenced by chunkID. For *bin/1d*, *bin/2d*, and *bin/3d* styles
the attribute is the center point of the bin in the corresponding
dimension. Style *bin/1d* only defines a *coord1* attribute. Style
*bin/2d* adds a *coord2* attribute. Style *bin/3d* adds a *coord3*
attribute.
Note that if the value of the *units* keyword used in the :doc:`compute chunk/atom command <compute_chunk_atom>` is *box* or *lattice*, the
*coordN* attributes will be in distance :doc:`units <units>`. If the
value of the *units* keyword is *reduced*, the *coordN* attributes
will be in unitless reduced units (0-1).
Note that if the value of the *units* keyword used in the
:doc:`compute chunk/atom command <compute_chunk_atom>` is *box* or
*lattice*, the *coordN* attributes will be in distance :doc:`units
<units>`. If the value of the *units* keyword is *reduced*, the
*coordN* attributes will be in unitless reduced units (0-1).
The simplest way to output the results of the compute property/chunk
calculation to a file is to use the :doc:`fix ave/time <fix_ave_time>`

110
doc/src/compute_property_grid.rst Normal file
View File

@ -0,0 +1,110 @@
.. index:: compute property/grid
compute property/grid command
=============================
Syntax
""""""
.. parsed-literal::
compute ID group-ID property/grid input1 input2 ...
* ID, group-ID are documented in :doc:`compute <compute>` command
* property/grid = style name of this compute command
* input1,etc = one or more attributes
.. parsed-literal::
attributes = id, ix, iy, iz, x, y, z, xs, ys, zs, xc, yc, zc, xsc, ysc, zsc
id = ID of grid point, x fastest, y next, z slowest
ix,iy,iz = grid indices in each dimension (1 to N inclusive)
x,y,z = coords of lower left corner of grid cell
xs,ys,zs = scaled coords of lower left corner of grid cell (0.0 to 1.0)
xc,yc,zc = coords of center point of grid cell
xsc,ysc,zsc = scaled coords of center point of grid cell (0.0 to 1.0)
Examples
""""""""
.. code-block:: LAMMPS
compute 1 all property/grid id ix iy iz
compute 1 all property/grid id xc yc zc
Description
"""""""""""
Define a computation that stores the specified attributes of a
distributed grid. In LAMMPS, distributed grids are regular 2d or 3d
grids which overlay a 2d or 3d simulation domain. Each processor owns
the grid points within its subdomain.
See the :doc:`Howto grid <Howto_grid>` doc page for details of how
distributed grids can be defined by various commands and examples of
how they can be used to measure properties of a system.
This compute stores the specified attributes of grids as per-grid data
so they can be accessed by other :doc:`output commands <Howto_output>`
such as :doc:`dump grid <dump>`.
The *id* attribute stores the grid ID for each grid point. For a
global grid of size Nx by Ny by Nz (in 3d simulations) the grid IDs
range from 1 to Nx*Ny*Nz. They are ordered with the X index of the 3d
grid varying fastest, then Y, then Z slowest. For 2d grids (in 2d
simulations), the grid IDs range from 1 to Nx*Ny, with X varying
fastest and Y slowest.
The *ix*, *iy*, *iz* attributes are the indices of a grid point in
each dimension. They range from 1 to Nx inclusive in the X dimension,
and similar for Y and Z.
The *x*, *y*, *z* attributes are the coordinates of the lower left
corner point of each grid cell.
The *xs*, *ys*, *zs* attributes are also coordinates of the lower left
corner point of each grid cell, except in scaled coordinates, where
the lower-left corner of the entire simulation box is (0,0,0) and he
upper right corner is (1,1,1).
Only in triclinic.
For 2d simulations, none of the attributes which refer to
the Z dimension can be used.
Output info
"""""""""""
This compute calculates a per-grid vector or array depending on the
number of input values. The length of the vector or number of rows
for each processor is the the number of grid points it owns.
This compute calculates a global vector or global array where the
number of rows = the number of chunks *Nchunk* as calculated by the
specified :doc:`compute chunk/atom <compute_chunk_atom>` command. If a
single input is specified, a global vector is produced. If two or
more inputs are specified, a global array is produced where the number
of columns = the number of inputs. The vector or array can be
accessed by any command that uses global values from a compute as
input. See the :doc:`Howto output <Howto_output>` page for an
overview of LAMMPS output options.
The vector or array values are "intensive". The values will be
unitless or in the units discussed above.
Restrictions
""""""""""""
none
Related commands
""""""""""""""""
:doc:`fix ave/grid <fix_ave_grid>`
Default
"""""""
none

26
doc/src/compute_property_local.rst
View File

@ -57,10 +57,11 @@ Description
"""""""""""
Define a computation that stores the specified attributes as local
data so it can be accessed by other :doc:`output commands <Howto_output>`. If the input attributes refer to bond
information, then the number of datums generated, aggregated across
all processors, equals the number of bonds in the system. Ditto for
pairs, angles, etc.
data so it can be accessed by other :doc:`output commands
<Howto_output>`. If the input attributes refer to bond information,
then the number of datums generated, aggregated across all processors,
equals the number of bonds in the system. Ditto for pairs, angles,
etc.
If multiple attributes are specified then they must all generate the
same amount of information, so that the resulting local array has the
@ -101,17 +102,20 @@ specified compute group. Likewise for angles, dihedrals, etc.
For bonds and angles, a bonds/angles that have been broken by setting
their bond/angle type to 0 will not be included. Bonds/angles that
have been turned off (see the :doc:`fix shake <fix_shake>` or
:doc:`delete_bonds <delete_bonds>` commands) by setting their bond/angle
type negative are written into the file. This is consistent with the
:doc:`compute bond/local <compute_bond_local>` and :doc:`compute angle/local <compute_angle_local>` commands
:doc:`delete_bonds <delete_bonds>` commands) by setting their
bond/angle type negative are written into the file. This is
consistent with the :doc:`compute bond/local <compute_bond_local>` and
:doc:`compute angle/local <compute_angle_local>` commands
Note that as atoms migrate from processor to processor, there will be
no consistent ordering of the entries within the local vector or array
from one timestep to the next. The only consistency that is
guaranteed is that the ordering on a particular timestep will be the
same for local vectors or arrays generated by other compute commands.
For example, output from the :doc:`compute bond/local <compute_bond_local>` command can be combined with bond
atom indices from this command and output by the :doc:`dump local <dump>` command in a consistent way.
For example, output from the :doc:`compute bond/local
<compute_bond_local>` command can be combined with bond atom indices
from this command and output by the :doc:`dump local <dump>` command
in a consistent way.
The *natom1* and *natom2*, or *patom1* and *patom2* attributes refer
to the atom IDs of the 2 atoms in each pairwise interaction computed
@ -149,8 +153,8 @@ the array is the number of bonds, angles, etc. If a single input is
specified, a local vector is produced. If two or more inputs are
specified, a local array is produced where the number of columns = the
number of inputs. The vector or array can be accessed by any command
that uses local values from a compute as input. See the :doc:`Howto output <Howto_output>` page for an overview of LAMMPS output
options.
that uses local values from a compute as input. See the :doc:`Howto
output <Howto_output>` page for an overview of LAMMPS output options.
The vector or array values will be integers that correspond to the
specified attribute.