.. index:: compute chunk/spread/atom

compute chunk/spread/atom command
=================================

Syntax
""""""

.. parsed-literal::

   compute ID group-ID chunk/spread/atom chunkID input1 input2 ...

* ID, group-ID are documented in :doc:`compute <compute>` command
* chunk/spread/atom = style name of this compute command
* chunkID = ID of :doc:`compute chunk/atom <compute_chunk_atom>` command
* one or more inputs can be listed
* input = c_ID, c_ID[N], f_ID, f_ID[N]

  .. parsed-literal::

       c_ID = global vector calculated by a compute with ID
       c_ID[I] = Ith column of global array calculated by a compute with ID, I can include wildcard (see below)
       f_ID = global vector calculated by a fix with ID
       f_ID[I] = Ith column of global array calculated by a fix with ID, I can include wildcard (see below)

Examples
""""""""

.. code-block:: LAMMPS

   compute 1 all chunk/spread/atom mychunk c_com[*] c_gyration

Description
"""""""""""

Define a calculation that "spreads" one or more per-chunk values to
each atom in the chunk.  This can be useful in several scenarios:

* For creating a :doc:`dump file <dump>` where each atom lists info about
  the chunk it is in, e.g. for post-processing purposes.
* To access chunk value in :doc:`atom-style variables <variable>` that
  need info about the chunk each atom is in.
* To use the :doc:`fix ave/chunk <fix_ave_chunk>` command to spatially
  average per-chunk values calculated by a per-chunk compute.

Examples are given below.

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.

For inputs that are computes, they must be a compute that calculates
per-chunk values.  These are computes whose style names end in
"/chunk".

For inputs that are fixes, they should be a fix that calculates
per-chunk values.  For example, :doc:`fix ave/chunk <fix_ave_chunk>` or
:doc:`fix ave/time <fix_ave_time>` (assuming it is time-averaging
per-chunk data).

For each atom, this compute accesses its chunk ID from the specified
*chunkID* compute, then accesses the per-chunk value in each input.
Those values are copied to this compute to become the output for that
atom.

The values generated by this compute will be 0.0 for atoms not in the
specified compute group *group-ID*\ .  They will also be 0.0 if the atom
is not in a chunk, as assigned by the *chunkID* compute.  They will
also be 0.0 if the current chunk ID for the atom is out-of-bounds with
respect to the number of chunks stored by a particular input compute
or fix.

.. note::

   LAMMPS does not check that a compute or fix which calculates
   per-chunk values uses the same definition of chunks as this compute.
   It's up to you to be consistent.  Likewise, for a fix input, LAMMPS
   does not check that it is per-chunk data.  It only checks that the fix
   produces a global vector or array.

----------

Each listed input is operated on independently.

If a bracketed index I is used, it can be specified using a wildcard
asterisk with the index to effectively specify multiple values.  This
takes the form "\*" or "\*n" or "n\*" or "m\*n".  If N = the number of
columns in the array, then an asterisk with no numeric values means
all indices from 1 to N.  A leading asterisk means all indices from 1
to n (inclusive).  A trailing asterisk means all indices from n to N
(inclusive).  A middle asterisk means all indices from m to n
(inclusive).

Using a wildcard is the same as if the individual columns of the array
had been listed one by one.  E.g. these 2 compute chunk/spread/atom
commands are equivalent, since the :doc:`compute com/chunk <compute_com_chunk>` command creates a per-atom array
with 3 columns:

.. code-block:: LAMMPS

   compute com all com/chunk mychunk
   compute 10 all chunk/spread/atom mychunk c_com[*]
   compute 10 all chunk/spread/atom mychunk c_com[1] c_com[2] c_com[3]

----------

Here is an example of writing a dump file the with the center-of-mass
(COM) for the chunk each atom is in.  The commands below can be added
to the bench/in.chain script.

.. code-block:: LAMMPS

   compute         cmol all chunk/atom molecule
   compute         com all com/chunk cmol
   compute         comchunk all chunk/spread/atom cmol c_com[*]
   dump            1 all custom 50 tmp.dump id mol type x y z c_comchunk[*]
   dump_modify     1 sort id

The same per-chunk data for each atom could be used to define per-atom
forces for the :doc:`fix addforce <fix_addforce>` command.  In this
example the forces act to pull atoms of an extended polymer chain
towards its COM in an attractive manner.

.. code-block:: LAMMPS

   compute         prop all property/atom xu yu zu
   variable        k equal 0.1
   variable        fx atom v_k*(c_comchunk[1]-c_prop[1])
   variable        fy atom v_k*(c_comchunk[2]-c_prop[2])
   variable        fz atom v_k*(c_comchunk[3]-c_prop[3])
   fix             3 all addforce v_fx v_fy v_fz

Note that :doc:`compute property/atom <compute_property_atom>` is used
to generate unwrapped coordinates for use in the per-atom force
calculation, so that the effect of periodic boundaries is accounted
for properly.

Over time this applied force could shrink each polymer chain's radius
of gyration in a polymer mixture simulation.  Here is output from the
bench/in.chain script.  Thermo output is shown for 1000 steps, where
the last column is the average radius of gyration over all 320 chains
in the 32000 atom system:

.. parsed-literal::

   compute         gyr all gyration/chunk cmol
   variable        ave equal ave(c_gyr)
   thermo_style    custom step etotal press v_ave

          0    22.394765    4.6721833     5.128278
        100    22.445002    4.8166709    5.0348372
        200    22.500128    4.8790392    4.9364875
        300    22.534686    4.9183766    4.8590693
        400    22.557196    4.9492211    4.7937849
        500    22.571017    4.9161853    4.7412008
        600    22.573944    5.0229708    4.6931243
        700    22.581804    5.0541301    4.6440647
        800    22.584683    4.9691734    4.6000016
        900     22.59128    5.0247538    4.5611513
       1000    22.586832      4.94697    4.5238362

----------

Here is an example for using one set of chunks, defined for molecules,
to compute the dipole moment vector for each chunk.  E.g. for water
molecules. Then spreading those values to each atom in each chunk.
Then defining a second set of chunks based on spatial bins.  And
finally, using the :doc:`fix ave/chunk <fix_ave_chunk>` command to
calculate an average dipole moment vector per spatial bin.

.. code-block:: LAMMPS

   compute       cmol all chunk/atom molecule
   compute       dipole all dipole/chunk cmol
   compute       spread all chunk/spread/atom cmol c_dipole[1] c_dipole[2] c_dipole[3]
   compute       cspatial all chunk/atom bin/1d z lower 0.1 units reduced
   fix           ave all ave/chunk 100 10 1000 cspatial c_spread[*]

Note that the :doc:`fix ave/chunk <fix_ave_chunk>` command requires
per-atom values as input.  That is why the compute chunk/spread/atom
command is used to assign per-chunk values to each atom in the chunk.
If a molecule straddles bin boundaries, each of its atoms contributes
in a weighted manner to the average dipole moment of the spatial bin
it is in.

----------

**Output info:**

This compute calculates a per-atom vector or array, which can be
accessed by any command that uses per-atom values from a compute as
input.  See the :doc:`Howto output <Howto_output>` doc page for an
overview of LAMMPS output options.

The output is a per-atom vector if a single input value is specified,
otherwise a per-atom array is output.  The number of columns in the
array is the number of inputs provided.  The per-atom values for the
vector or each column of the array will be in whatever
:doc:`units <units>` the corresponding input value is in.

The vector or array values are "intensive".

Restrictions
""""""""""""
 none

Related commands
""""""""""""""""

:doc:`compute chunk/atom <compute_chunk_atom>`, :doc:`fix ave/chunk <fix_ave_chunk>`, :doc:`compute reduce/chunk <compute_reduce_chunk>`

**Default:** none
