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

update compute and fix doc pages for new generality

Browse Source
This commit is contained in:
Steve Plimpton
2023-08-21 09:39:00 -06:00
parent 6e1529ddff
commit c6233547a5
2 changed files with 113 additions and 90 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
doc/src/compute.rst
View File

@ -27,58 +27,62 @@ Examples
Description
"""""""""""
Define a computation that will be performed on a group of atoms.
Quantities calculated by a compute are instantaneous values, meaning
they are calculated from information about atoms on the current
timestep or iteration, though a compute may internally store some
information about a previous state of the system. Defining a compute
does not perform a computation. Instead computes are invoked by other
LAMMPS commands as needed (e.g., to calculate a temperature needed for
a thermostat fix or to generate thermodynamic or dump file output).
See the :doc:`Howto output <Howto_output>` page for a summary of
various LAMMPS output options, many of which involve computes.
Define a diagnostic computation that will be performed on a group of
atoms. Quantities calculated by a compute are instantaneous values,
meaning they are calculated from information about atoms on the
current timestep or iteration, though internally a compute may store
some information about a previous state of the system. Defining a
compute does not perform the computation. Instead computes are
invoked by other LAMMPS commands as needed (e.g., to calculate a
temperature needed for a thermostat fix or to generate thermodynamic
or dump file output). See the :doc:`Howto output <Howto_output>` page
for a summary of various LAMMPS output options, many of which involve
computes.
The ID of a compute can only contain alphanumeric characters and
underscores.
----------
Computes calculate and store any of four styles of quantities: global,
per-atom, local, or per-grid. A global quantity is one or more
system-wide values, e.g. the temperature of the system. A per-atom
quantity is one or more values per atom, e.g. the kinetic energy of
each atom. Per-atom values are set to 0.0 for atoms not in the
specified compute group. Local quantities 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. Per-grid quantities are
calculated on a regular 2d or 3d grid which overlays a 2d or 3d
simulation domain. The grid points and the data they store are
distributed across processors; each processor owns the grid points
which fall within its subdomain.
Computes calculate and store any of four *styles* of quantities:
global, per-atom, local, or per-grid.
Computes that produce per-atom quantities have the word "atom" at the
end of their style, e.g. *ke/atom*\ . Computes that produce local
quantities have the word "local" at the end of their style,
e.g. *bond/local*\ . Computes that produce per-grid quantities have
the word "grid" at the end of their style, e.g. *property/grid*\ .
Styles with neither "atom" or "local" or "grid" at the end of their
style name produce global quantities.
A global quantity is one or more system-wide values, e.g. the
temperature of the system. A per-atom quantity is one or more values
per atom, e.g. the kinetic energy of each atom. Per-atom values are
set to 0.0 for atoms not in the specified compute group. Local
quantities 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. Per-grid quantities are calculated on a regular 2d or 3d
grid which overlays a 2d or 3d simulation domain. The grid points and
the data they store are distributed across processors; each processor
owns the grid points which fall within its subdomain.
Note that a single compute typically produces either global or
per-atom or local or per-grid values. It does not compute both global
and per-atom values. It can produce local values or per-grid values
in tandem with global or per-atom quantities. The compute doc page
will explain the details.
As a general rule of thumb, computes that produce per-atom quantities
have the word "atom" at the end of their style, e.g. *ke/atom*\ .
Computes that produce local quantities have the word "local" at the
end of their style, e.g. *bond/local*\ . Computes that produce
per-grid quantities have the word "grid" at the end of their style,
e.g. *property/grid*\ . And styles with neither "atom" or "local" or
"grid" at the end of their style name produce global quantities.
Global, per-atom, local, and per-grid quantities come in three kinds:
a single scalar value, a vector of values, or a 2d array of values.
The doc page for each compute describes the style and kind of values
it produces, e.g. a per-atom vector. Some computes produce more than
one kind of a single style, e.g. a global scalar and a global vector.
Global, per-atom, local, and per-grid quantities can also be of three
*kinds*: a single scalar value (global only), a vector of values, or a
2d array of values. For per-atom, local, and per-grid quantities, a
"vector" means a single value for each atom, each local entity
(e.g. bond), or grid cell. Likewise an "array", means multiple values
for each atom, each local entity, or each grid cell.
When a compute quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
notation, where ID is the ID of the compute:
Note that a single compute can produce any combination of global,
per-atom, local, or per-grid values. Likewise it can prouduce any
combination of scalar, vector, or array output for each style. The
exception is that for per-atom, local, and per-grid output, either a
vector or array can be produced, but not both. The doc page for each
compute explains the values it produces.
When a compute output is accessed by another input script command it
is referenced via the following bracket notation, where ID is the ID
of the compute:
+-------------+--------------------------------------------+
| c_ID | entire scalar, vector, or array |
@ -89,17 +93,23 @@ notation, where ID is the ID of the compute:
+-------------+--------------------------------------------+
In other words, using one bracket reduces the dimension of the
quantity once (vector :math:`\to` scalar, array :math:`\to` vector). Using two
brackets reduces the dimension twice (array :math:`\to` scalar). Thus a
command that uses scalar compute values as input can also process elements of a
vector or array.
quantity once (vector :math:`\to` scalar, array :math:`\to` vector).
Using two brackets reduces the dimension twice (array :math:`\to`
scalar). Thus, for example, a command that uses global scalar compute
values as input can also process elements of a vector or array.
Depending on the command, this can either be done directly using the
syntax in the table, or by first defining a :doc:`variable <variable>`
of the appropriate style to store the quantity, then using the
variable as an input to the command.
Note that commands and :doc:`variables <variable>` which use compute
quantities typically do not allow for all kinds (e.g., a command may
require a vector of values, not a scalar). This means there is no
ambiguity about referring to a compute quantity as c_ID even if it
produces, for example, both a scalar and vector. The doc pages for
various commands explain the details.
Note that commands and :doc:`variables <variable>` which take compute
outputs as input typically do not allow for all styles and kinds of
data (e.g., a command may require global but not per-atom values, or
it may require a vector of values, not a scalar). This means there is
typically no ambiguity about referring to a compute output as c_ID
even if it produces, for example, both a scalar and vector. The doc
pages for various commands explain the details, including how any
ambiguities are resolved.
----------

89
doc/src/fix.rst
View File

@ -77,35 +77,44 @@ for individual fixes for info on which ones can be restarted.
----------
Some fixes calculate one or more of four styles of quantities: global,
per-atom, local, or per-grid, which can be used by other commands or
output as described below. A global quantity is one or more
system-wide values, e.g. the energy of a wall interacting with
particles. A per-atom quantity is one or more values per atom,
e.g. the displacement vector for each atom since time 0. Per-atom
values are set to 0.0 for atoms not in the specified fix group. Local
quantities are calculated by each processor based on the atoms it
owns, but there may be zero or more per atoms. Per-grid quantities
are calculated on a regular 2d or 3d grid which overlays a 2d or 3d
simulation domain. The grid points and the data they store are
distributed across processors; each processor owns the grid points
which fall within its subdomain.
Some fixes calculate and store any of four *styles* of quantities:
global, per-atom, local, or per-grid.
Note that a single fix typically produces either global or per-atom or
local or per-grid values (or none at all). It does not produce both
global and per-atom. It can produce local or per-grid values in
tandem with global or per-atom values. The fix doc page will explain
the details.
A global quantity is one or more system-wide values, e.g. the energy
of a wall interacting with particles. A per-atom quantity is one or
more values per atom, e.g. the original coordinates of each atom at
time 0. Per-atom values are set to 0.0 for atoms not in the specified
fix group. Local quantities are calculated by each processor based on
the atoms it owns, but there may be zero or more per atom, e.g. values
for each bond. Per-grid quantities are calculated on a regular 2d or
3d grid which overlays a 2d or 3d simulation domain. The grid points
and the data they store are distributed across processors; each
processor owns the grid points which fall within its subdomain.
Global, per-atom, local, and per-grid quantities come in three kinds:
a single scalar value, a vector of values, or a 2d array of values.
The doc page for each fix describes the style and kind of values it
produces, e.g. a per-atom vector. Some fixes produce more than one
kind of a single style, e.g. a global scalar and a global vector.
As a general rule of thumb, fixes that produce per-atom quantities
have the word "atom" at the end of their style, e.g. *ave/atom*\ .
Fixes that produce local quantities have the word "local" at the end
of their style, e.g. *store/local*\ . Fixes that produce per-grid
quantities have the word "grid" at the end of their style,
e.g. *ave/grid*\ .
When a fix quantity is accessed, as in many of the output commands
discussed below, it can be referenced via the following bracket
notation, where ID is the ID of the fix:
Global, per-atom, local, and per-grid quantities can also be of three
*kinds*: a single scalar value (global only), a vector of values, or a
2d array of values. For per-atom, local, and per-grid quantities, a
"vector" means a single value for each atom, each local entity
(e.g. bond), or grid cell. Likewise an "array", means multiple values
for each atom, each local entity, or each grid cell.
Note that a single fix can produce any combination of global,
per-atom, local, or per-grid values. Likewise it can prouduce any
combination of scalar, vector, or array output for each style. The
exception is that for per-atom, local, and per-grid output, either a
vector or array can be produced, but not both. The doc page for each
fix explains the values it produces, if any.
When a fix output is accessed by another input script command it is
referenced via the following bracket notation, where ID is the ID of
the fix:
+-------------+--------------------------------------------+
| f_ID | entire scalar, vector, or array |
@ -116,19 +125,23 @@ notation, where ID is the ID of the fix:
+-------------+--------------------------------------------+
In other words, using one bracket reduces the dimension of the
quantity once (vector :math:`\to` scalar, array :math:`\to` vector). Using two
brackets reduces the dimension twice (array :math:`\to` scalar). Thus, a
command that uses scalar fix values as input can also process elements of a
vector or array.
quantity once (vector :math:`\to` scalar, array :math:`\to` vector).
Using two brackets reduces the dimension twice (array :math:`\to`
scalar). Thus, for example, a command that uses global scalar fix
values as input can also process elements of a vector or array.
Depending on the command, this can either be done directly using the
syntax in the table, or by first defining a :doc:`variable <variable>`
of the appropriate style to store the quantity, then using the
variable as an input to the command.
Note that commands and :doc:`variables <variable>` that use fix
quantities typically do not allow for all kinds (e.g., a command may
require a vector of values, not a scalar), and even if they do, the context
in which they are called can be used to resolve which output is being
requested. This means there is no
ambiguity about referring to a fix quantity as f_ID even if it
produces, for example, both a scalar and vector. The doc pages for
various commands explain the details.
Note that commands and :doc:`variables <variable>` which take fix
outputs as input typically do not allow for all styles and kinds of
data (e.g., a command may require global but not per-atom values, or
it may require a vector of values, not a scalar). This means there is
typically no ambiguity about referring to a fix output as c_ID even if
it produces, for example, both a scalar and vector. The doc pages for
various commands explain the details, including how any ambiguities
are resolved.
----------