Merge branch 'master' of https://github.com/lammps/lammps into kk_qeq_nevery

   * :doc:`region <region>`

   * :doc:`replicate <replicate>`

   * :doc:`rerun <rerun>`

   * :doc:`reset_ids <reset_ids>`

   * :doc:`reset_atom_ids <reset_atom_ids>`

   * :doc:`reset_mol_ids <reset_mol_ids>`

   * :doc:`reset_timestep <reset_timestep>`

   * :doc:`restart <restart>`

   * :doc:`run <run>`

There are four basic kinds of LAMMPS output:

* :doc:`Thermodynamic output <thermo_style>`, which is a list

  of quantities printed every few timesteps to the screen and logfile.

* :doc:`Thermodynamic output <thermo_style>`, which is a list of

  quantities printed every few timesteps to the screen and logfile.

* :doc:`Dump files <dump>`, which contain snapshots of atoms and various

  per-atom values and are written at a specified frequency.

* Certain fixes can output user-specified quantities to files: :doc:`fix ave/time <fix_ave_time>` for time averaging, :doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and :doc:`fix print <fix_print>` for single-line output of

  :doc:`variables <variable>`.  Fix print can also output to the

  screen.

* Certain fixes can output user-specified quantities to files:

  :doc:`fix ave/time <fix_ave_time>` for time averaging,

  :doc:`fix ave/chunk <fix_ave_chunk>` for spatial or other averaging, and

  :doc:`fix print <fix_print>` for single-line output of

  :doc:`variables <variable>`.  Fix print can also output to the screen.

* :doc:`Restart files <restart>`.

A simulation prints one set of thermodynamic output and (optionally)

.. _global:

Global/per-atom/local data

---------------------------------------

--------------------------

Various output-related commands work with three different styles of

data: global, per-atom, or local.  A global datum is one or more

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

scalar values as input can typically also process elements of a vector

or array.

.. _disambiguation:

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

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

.. _thermo:

Thermodynamic output

---------------------------------

--------------------

The frequency and format of thermodynamic output is set by the

:doc:`thermo <thermo>`, :doc:`thermo_style <thermo_style>`, and

.. _dump:

Dump file output

---------------------------

----------------

Dump file output is specified by the :doc:`dump <dump>` and

:doc:`dump_modify <dump_modify>` commands.  There are several

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

.. _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,

.. _fixprocoutput:

Fixes that process output quantities

--------------------------------------------------------

------------------------------------

The :doc:`fix vector <fix_vector>` command can create global vectors as

output from global scalars as input, accumulating them one element at

.. _compute:

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

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

.. _variable:

Variables that generate values to output

-------------------------------------------------------

----------------------------------------

:doc:`Variables <variable>` defined in an input script can store one or

more strings.  But equal-style, vector-style, and atom-style or

.. _table:

Summary table of output options and data flow between commands

--------------------------------------------------------------------------

--------------------------------------------------------------

This table summarizes the various commands that can be used for

generating output from LAMMPS.  Each command produces output data of

   region

   replicate

   rerun

   reset_ids

   reset_atom_ids

   reset_mol_ids

   reset_timestep

   restart

   run

**Output info:**

This compute calculates a per-atom vector, 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

This compute calculates a per-atom vector (the chunk ID), which can

be accessed by any command that uses per-atom values from a compute

as input.  It also calculates a global scalar (the number of chunks),

which can be similarly accessed everywhere outside of a per-atom context.

See the :doc:`Howto output <Howto_output>` doc page for an overview of

LAMMPS output options.

The per-atom vector values are unitless chunk IDs, ranging from 1 to

*Nchunk* (inclusive) for atoms assigned to chunks, and 0 for atoms not

belonging to a chunk.

belonging to a chunk.  The scalar contains the value of *Nchunk*.

Restrictions

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

.. parsed-literal::

   compute ID group-ID cluster/atom cutoff

   compute ID group-ID fragment/atom

   compute ID group-ID fragment/atom keyword value ...

   compute ID group-ID aggregate/atom cutoff

* ID, group-ID are documented in :doc:`compute <compute>` command

* *cluster/atom* or *fragment/atom* or *aggregate/atom* = style name of this compute command

* cutoff = distance within which to label atoms as part of same cluster (distance units)

* zero or more keyword/value pairs may be appended to *fragment/atom*

* keyword = *single*

    .. parsed-literal::

       *single* value = *yes* or *no* to treat single atoms (no bonds) as fragments

Examples

""""""""

   compute 1 all cluster/atom 3.5

   compute 1 all fragment/atom

   compute 1 all fragment/atom single no

   compute 1 all aggregate/atom 3.5

Description

"""""""""""

Define a computation that assigns each atom a cluster, fragment,

or aggregate ID.

Define a computation that assigns each atom a cluster, fragment, or

aggregate ID.  Only atoms in the compute group are clustered and

assigned cluster IDs. Atoms not in the compute group are assigned an

ID = 0.

A cluster is defined as a set of atoms, each of which is within the

cutoff distance from one or more other atoms in the cluster.  If an

atom has no neighbors within the cutoff distance, then it is a 1-atom

cluster.

A fragment is similarly defined as a set of atoms, each of

which has an explicit bond (i.e. defined via a :doc:`data file <read_data>`,

the :doc:`create_bonds <create_bonds>` command, or through fixes like

:doc:`fix bond/create <fix_bond_create>`, :doc:`fix bond/swap <fix_bond_swap>`,

or :doc:`fix bond/break <fix_bond_break>`).  The cluster ID or fragment ID

of every atom in the cluster will be set to the smallest atom ID of any atom

in the cluster or fragment, respectively.

A fragment is similarly defined as a set of atoms, each of which has a

bond to another atom in the fragment.  Bonds can be defined initially

via the :doc:`data file <read_data>` or :doc:`create_bonds

<create_bonds>` commands, or dynamically by fixes which create or

break bonds like :doc:`fix bond/react <fix_bond_react>`, :doc:`fix

bond/create <fix_bond_create>`, :doc:`fix bond/swap <fix_bond_swap>`,

or :doc:`fix bond/break <fix_bond_break>`.  The cluster ID or fragment

ID of every atom in the cluster will be set to the smallest atom ID of

any atom in the cluster or fragment, respectively.

For the *fragment/atom* style, the *single* keyword determines whether

single atoms (not bonded to another atom) are treated as one-atom

fragments or not, based on the *yes* or *no* setting.  If the setting

is *no* (the default), their fragment IDs are set to 0.

An aggregate is defined by combining the rules for clusters and

fragments, i.e. a set of atoms, where each of it is within the cutoff

the same cluster. This measure can be used to track molecular assemblies

like micelles.

Only atoms in the compute group are clustered and assigned cluster

IDs. Atoms not in the compute group are assigned a cluster ID = 0.

For fragments, only bonds where **both** atoms of the bond are included

in the compute group are assigned to fragments, so that only fragments

are detected where **all** atoms are in the compute group. Thus atoms

may be included in the compute group, yes still have a fragment ID of 0.

For computes *cluster/atom* and *aggregate/atom* 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 or to have

multiple compute/dump commands, each of a *cluster/atom* or

*aggregate/atom* style.

For computes *cluster/atom* and *aggregate/atom* a neighbor list

needed to compute cluster IDs is constructed each time the compute is

invoked.  Thus it can be inefficient to compute/dump this quantity too

frequently or to have multiple *cluster/atom* or *aggregate/atom*

style computes.

.. note::

   :doc:`special_bonds <special_bonds>` command that includes all pairs in

   the neighbor list.

.. note::

   For the compute fragment/atom style, each fragment is identified

   using the current bond topology.  This will not account for bonds

   broken by the :doc:`bond_style quartic <bond_quartic>` command

   because it does not perform a full update of the bond topology data

   structures within LAMMPS.

**Output info:**

This compute calculates a per-atom vector, which can be accessed by

:doc:`compute coord/atom <compute_coord_atom>`

**Default:** none

**Default:**

The default for fragment/atom is single no.