.. index:: compute

compute command
===============

Syntax
""""""

.. parsed-literal::

   compute ID group-ID style args

* ID = user-assigned name for the computation
* group-ID = ID of the group of atoms to perform the computation on
* style = one of a list of possible style names (see below)
* args = arguments used by a particular style

Examples
""""""""

.. code-block:: LAMMPS

   compute 1 all temp
   compute newtemp flow temp/partial 1 1 0
   compute 3 all ke/atom

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>` doc 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 one of three styles of quantities: global,
per-atom, or local.  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.  Computes that produce per-atom quantities have the
word "atom" in their style, e.g. *ke/atom*\ .  Computes that produce
local quantities have the word "local" in their style,
e.g. *bond/local*\ .  Styles with neither "atom" or "local" in their
style produce global quantities.

Note that a single compute can produce either global or per-atom or
local quantities, but not both global and per-atom.  It can produce
local quantities in tandem with global or per-atom quantities.  The
compute doc page will explain.

Global, per-atom, and local quantities each 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.

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:

+-------------+--------------------------------------------+
| c_ID        | entire scalar, vector, or array            |
+-------------+--------------------------------------------+
| c_ID[I]     | one element of vector, one column of array |
+-------------+--------------------------------------------+
| c_ID[I][J]  | one element of array                       |
+-------------+--------------------------------------------+

In other words, using one bracket reduces the dimension of the
quantity once (vector -> scalar, array -> vector).  Using two brackets
reduces the dimension twice (array -> scalar).  Thus a command that
uses scalar compute values as input can also process elements of a
vector or array.

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.

----------

In LAMMPS, the values generated by a compute can be used in several
ways:

* The results of computes that calculate a global temperature or
  pressure can be used by fixes that do thermostatting or barostatting
  or when atom velocities are created.
* Global values can be output via the :doc:`thermo_style custom <thermo_style>` or :doc:`fix ave/time <fix_ave_time>` command.
  Or the values can be referenced in a :doc:`variable equal <variable>` or
  :doc:`variable atom <variable>` command.
* Per-atom values can be output via the :doc:`dump custom <dump>` command.
  Or they can be time-averaged via the :doc:`fix ave/atom <fix_ave_atom>`
  command or reduced by the :doc:`compute reduce <compute_reduce>`
  command.  Or the per-atom values can be referenced in an :doc:`atom-style variable <variable>`.
* Local values can be reduced by the :doc:`compute reduce <compute_reduce>` command, or histogrammed by the :doc:`fix ave/histo <fix_ave_histo>` command, or output by the :doc:`dump local <dump>` command.

The results of computes that calculate global quantities can be either
"intensive" or "extensive" values.  Intensive means the value is
independent of the number of atoms in the simulation,
e.g. temperature.  Extensive means the value scales with the number of
atoms in the simulation, e.g. total rotational kinetic energy.
:doc:`Thermodynamic output <thermo_style>` will normalize extensive
values by the number of atoms in the system, depending on the
"thermo_modify norm" setting.  It will not normalize intensive values.
If a compute value is accessed in another way, e.g. by a
:doc:`variable <variable>`, you may want to know whether it is an
intensive or extensive value.  See the doc page for individual
computes for further info.

----------

LAMMPS creates its own computes internally for thermodynamic output.
Three computes are always created, named "thermo_temp",
"thermo_press", and "thermo_pe", as if these commands had been invoked
in the input script:

.. code-block:: LAMMPS

   compute thermo_temp all temp
   compute thermo_press all pressure thermo_temp
   compute thermo_pe all pe

Additional computes for other quantities are created if the thermo
style requires it.  See the documentation for the
:doc:`thermo_style <thermo_style>` command.

Fixes that calculate temperature or pressure, i.e. for thermostatting
or barostatting, may also create computes.  These are discussed in the
documentation for specific :doc:`fix <fix>` commands.

In all these cases, the default computes LAMMPS creates can be
replaced by computes defined by the user in the input script, as
described by the :doc:`thermo_modify <thermo_modify>` and :doc:`fix modify <fix_modify>` commands.

Properties of either a default or user-defined compute can be modified
via the :doc:`compute_modify <compute_modify>` command.

Computes can be deleted with the :doc:`uncompute <uncompute>` command.

Code for new computes can be added to LAMMPS; see the
:doc:`Modify <Modify>` doc page for details.  The results of their
calculations accessed in the various ways described above.

----------

Each compute style has its own doc page which describes its arguments
and what it does.  Here is an alphabetic list of compute styles
available in LAMMPS.  They are also listed in more compact form on the
:doc:`Commands compute <Commands_compute>` doc page.

There are also additional accelerated compute styles included in the
LAMMPS distribution for faster performance on CPUs, GPUs, and KNLs.
The individual style names on the :doc:`Commands compute <Commands_compute>` doc page are followed by one or more of
(g,i,k,o,t) to indicate which accelerated styles exist.

* :doc:`ackland/atom <compute_ackland_atom>` - determines the local lattice structure based on the Ackland formulation
* :doc:`adf <compute_adf>` - angular distribution function of triples of atoms
* :doc:`aggregate/atom <compute_cluster_atom>` - aggregate ID for each atom
* :doc:`angle <compute_angle>` - energy of each angle sub-style
* :doc:`angle/local <compute_angle_local>` - theta and energy of each angle
* :doc:`angmom/chunk <compute_angmom_chunk>` - angular momentum for each chunk
* :doc:`basal/atom <compute_basal_atom>` - calculates the hexagonal close-packed "c" lattice vector of each atom
* :doc:`body/local <compute_body_local>` - attributes of body sub-particles
* :doc:`bond <compute_bond>` - energy of each bond sub-style
* :doc:`bond/local <compute_bond_local>` - distance and energy of each bond
* :doc:`centro/atom <compute_centro_atom>` - centro-symmetry parameter for each atom
* :doc:`centroid/stress/atom <compute_stress_atom>` - centroid based stress tensor for each atom
* :doc:`chunk/atom <compute_chunk_atom>` - assign chunk IDs to each atom
* :doc:`chunk/spread/atom <compute_chunk_spread_atom>` - spreads chunk values to each atom in chunk
* :doc:`cluster/atom <compute_cluster_atom>` - cluster ID for each atom
* :doc:`cna/atom <compute_cna_atom>` - common neighbor analysis (CNA) for each atom
* :doc:`cnp/atom <compute_cnp_atom>` - common neighborhood parameter (CNP) for each atom
* :doc:`com <compute_com>` - center-of-mass of group of atoms
* :doc:`com/chunk <compute_com_chunk>` - center-of-mass for each chunk
* :doc:`contact/atom <compute_contact_atom>` - contact count for each spherical particle
* :doc:`coord/atom <compute_coord_atom>` - coordination number for each atom
* :doc:`damage/atom <compute_damage_atom>` - Peridynamic damage for each atom
* :doc:`dihedral <compute_dihedral>` - energy of each dihedral sub-style
* :doc:`dihedral/local <compute_dihedral_local>` - angle of each dihedral
* :doc:`dilatation/atom <compute_dilatation_atom>` - Peridynamic dilatation for each atom
* :doc:`dipole/chunk <compute_dipole_chunk>` - dipole vector and total dipole for each chunk
* :doc:`displace/atom <compute_displace_atom>` - displacement of each atom
* :doc:`dpd <compute_dpd>` -
* :doc:`dpd/atom <compute_dpd_atom>` -
* :doc:`edpd/temp/atom <compute_edpd_temp_atom>` - per-atom temperature for each eDPD particle in a group
* :doc:`entropy/atom <compute_entropy_atom>` - pair entropy fingerprint of each atom
* :doc:`erotate/asphere <compute_erotate_asphere>` - rotational energy of aspherical particles
* :doc:`erotate/rigid <compute_erotate_rigid>` - rotational energy of rigid bodies
* :doc:`erotate/sphere <compute_erotate_sphere>` - rotational energy of spherical particles
* :doc:`erotate/sphere/atom <compute_erotate_sphere_atom>` - rotational energy for each spherical particle
* :doc:`event/displace <compute_event_displace>` - detect event on atom displacement
* :doc:`fep <compute_fep>` -
* :doc:`force/tally <compute_tally>` -
* :doc:`fragment/atom <compute_cluster_atom>` - fragment ID for each atom
* :doc:`global/atom <compute_global_atom>` -
* :doc:`group/group <compute_group_group>` - energy/force between two groups of atoms
* :doc:`gyration <compute_gyration>` - radius of gyration of group of atoms
* :doc:`gyration/chunk <compute_gyration_chunk>` - radius of gyration for each chunk
* :doc:`gyration/shape <compute_gyration_shape>` - shape parameters from gyration tensor
* :doc:`gyration/shape/chunk <compute_gyration_shape_chunk>` - shape parameters from gyration tensor for each chunk
* :doc:`heat/flux <compute_heat_flux>` - heat flux through a group of atoms
* :doc:`heat/flux/tally <compute_tally>` -
* :doc:`hexorder/atom <compute_hexorder_atom>` - bond orientational order parameter q6
* :doc:`hma <compute_hma>` - harmonically mapped averaging for atomic crystals
* :doc:`improper <compute_improper>` - energy of each improper sub-style
* :doc:`improper/local <compute_improper_local>` - angle of each improper
* :doc:`inertia/chunk <compute_inertia_chunk>` - inertia tensor for each chunk
* :doc:`ke <compute_ke>` - translational kinetic energy
* :doc:`ke/atom <compute_ke_atom>` - kinetic energy for each atom
* :doc:`ke/atom/eff <compute_ke_atom_eff>` - per-atom translational and radial kinetic energy in the electron force field model
* :doc:`ke/eff <compute_ke_eff>` - kinetic energy of a group of nuclei and electrons in the electron force field model
* :doc:`ke/rigid <compute_ke_rigid>` - translational kinetic energy of rigid bodies
* :doc:`momentum <compute_momentum>` - translational momentum
* :doc:`msd <compute_msd>` - mean-squared displacement of group of atoms
* :doc:`msd/chunk <compute_msd_chunk>` - mean-squared displacement for each chunk
* :doc:`msd/nongauss <compute_msd_nongauss>` - MSD and non-Gaussian parameter of group of atoms
* :doc:`omega/chunk <compute_omega_chunk>` - angular velocity for each chunk
* :doc:`orientorder/atom <compute_orientorder_atom>` - Steinhardt bond orientational order parameters Ql
* :doc:`pair <compute_pair>` - values computed by a pair style
* :doc:`pair/local <compute_pair_local>` - distance/energy/force of each pairwise interaction
* :doc:`pe <compute_pe>` - potential energy
* :doc:`pe/atom <compute_pe_atom>` - potential energy for each atom
* :doc:`mesont <compute_mesont>` - Nanotube bending,stretching, and intertube energies
* :doc:`pe/mol/tally <compute_tally>` -
* :doc:`pe/tally <compute_tally>` -
* :doc:`plasticity/atom <compute_plasticity_atom>` - Peridynamic plasticity for each atom
* :doc:`pressure <compute_pressure>` - total pressure and pressure tensor
* :doc:`pressure/cylinder <compute_pressure_cylinder>` - pressure tensor in cylindrical coordinates
* :doc:`pressure/uef <compute_pressure_uef>` - pressure tensor in the reference frame of an applied flow field
* :doc:`property/atom <compute_property_atom>` - convert atom attributes to per-atom vectors/arrays
* :doc:`property/chunk <compute_property_chunk>` - extract various per-chunk attributes
* :doc:`property/local <compute_property_local>` - convert local attributes to localvectors/arrays
* :doc:`ptm/atom <compute_ptm_atom>` - determines the local lattice structure based on the Polyhedral Template Matching method
* :doc:`rdf <compute_rdf>` - radial distribution function g(r) histogram of group of atoms
* :doc:`reduce <compute_reduce>` - combine per-atom quantities into a single global value
* :doc:`reduce/chunk <compute_reduce_chunk>` - reduce per-atom quantities within each chunk
* :doc:`reduce/region <compute_reduce>` - same as compute reduce, within a region
* :doc:`rigid/local <compute_rigid_local>` - extract rigid body attributes
* :doc:`saed <compute_saed>` - electron diffraction intensity on a mesh of reciprocal lattice nodes
* :doc:`slice <compute_slice>` - extract values from global vector or array
* :doc:`smd/contact/radius <compute_smd_contact_radius>` -
* :doc:`smd/damage <compute_smd_damage>` - damage status of SPH particles in Smooth Mach Dynamics
* :doc:`smd/hourglass/error <compute_smd_hourglass_error>` -
* :doc:`smd/internal/energy <compute_smd_internal_energy>` - per-particle enthalpy in Smooth Mach Dynamics
* :doc:`smd/plastic/strain <compute_smd_plastic_strain>` - equivalent plastic strain per particle in Smooth Mach Dynamics
* :doc:`smd/plastic/strain/rate <compute_smd_plastic_strain_rate>` - time rate of the equivalent plastic strain in Smooth Mach Dynamics
* :doc:`smd/rho <compute_smd_rho>` - per-particle mass density in Smooth Mach Dynamics
* :doc:`smd/tlsph/defgrad <compute_smd_tlsph_defgrad>` - deformation gradient in Smooth Mach Dynamics
* :doc:`smd/tlsph/dt <compute_smd_tlsph_dt>` - CFL-stable time increment per particle in Smooth Mach Dynamics
* :doc:`smd/tlsph/num/neighs <compute_smd_tlsph_num_neighs>` -
* :doc:`smd/tlsph/shape <compute_smd_tlsph_shape>` -
* :doc:`smd/tlsph/strain <compute_smd_tlsph_strain>` -
* :doc:`smd/tlsph/strain/rate <compute_smd_tlsph_strain_rate>` -
* :doc:`smd/tlsph/stress <compute_smd_tlsph_stress>` - per-particle Cauchy stress tensor for SPH particles
* :doc:`smd/triangle/vertices <compute_smd_triangle_vertices>` -
* :doc:`smd/ulsph/num/neighs <compute_smd_ulsph_num_neighs>` -
* :doc:`smd/ulsph/strain <compute_smd_ulsph_strain>` -
* :doc:`smd/ulsph/strain/rate <compute_smd_ulsph_strain_rate>` -
* :doc:`smd/ulsph/stress <compute_smd_ulsph_stress>` - per-particle Cauchy stress tensor and von Mises equivalent stress in Smooth Mach Dynamics
* :doc:`smd/vol <compute_smd_vol>` - per-particle volumes and their sum in Smooth Mach Dynamics
* :doc:`snap <compute_sna_atom>` - bispectrum components and related quantities for a group of atoms
* :doc:`sna/atom <compute_sna_atom>` - bispectrum components for each atom
* :doc:`snad/atom <compute_sna_atom>` - derivative of bispectrum components for each atom
* :doc:`snav/atom <compute_sna_atom>` - virial contribution from bispectrum components for each atom
* :doc:`sph/e/atom <compute_sph_e_atom>` - per-atom internal energy of Smooth-Particle Hydrodynamics atoms
* :doc:`sph/rho/atom <compute_sph_rho_atom>` - per-atom density of Smooth-Particle Hydrodynamics atoms
* :doc:`sph/t/atom <compute_sph_t_atom>` - per-atom internal temperature of Smooth-Particle Hydrodynamics atoms
* :doc:`spin <compute_spin>` - magnetic quantities for a system of atoms having spins
* :doc:`stress/atom <compute_stress_atom>` - stress tensor for each atom
* :doc:`stress/mop <compute_stress_mop>` - normal components of the local stress tensor using the method of planes
* :doc:`stress/mop/profile <compute_stress_mop>` - profile of the normal components of the local stress tensor using the method of planes
* :doc:`stress/tally <compute_tally>` -
* :doc:`tdpd/cc/atom <compute_tdpd_cc_atom>` - per-atom chemical concentration of a specified species for each tDPD particle
* :doc:`temp <compute_temp>` - temperature of group of atoms
* :doc:`temp/asphere <compute_temp_asphere>` - temperature of aspherical particles
* :doc:`temp/body <compute_temp_body>` - temperature of body particles
* :doc:`temp/chunk <compute_temp_chunk>` - temperature of each chunk
* :doc:`temp/com <compute_temp_com>` - temperature after subtracting center-of-mass velocity
* :doc:`temp/cs <compute_temp_cs>` - temperature based on the center-of-mass velocity of atom pairs that are bonded to each other
* :doc:`temp/deform <compute_temp_deform>` - temperature excluding box deformation velocity
* :doc:`temp/deform/eff <compute_temp_deform_eff>` - temperature excluding box deformation velocity in the electron force field model
* :doc:`temp/drude <compute_temp_drude>` - temperature of Core-Drude pairs
* :doc:`temp/eff <compute_temp_eff>` - temperature of a group of nuclei and electrons in the electron force field model
* :doc:`temp/partial <compute_temp_partial>` - temperature excluding one or more dimensions of velocity
* :doc:`temp/profile <compute_temp_profile>` - temperature excluding a binned velocity profile
* :doc:`temp/ramp <compute_temp_ramp>` - temperature excluding ramped velocity component
* :doc:`temp/region <compute_temp_region>` - temperature of a region of atoms
* :doc:`temp/region/eff <compute_temp_region_eff>` - temperature of a region of nuclei and electrons in the electron force field model
* :doc:`temp/rotate <compute_temp_rotate>` - temperature of a group of atoms after subtracting out their center-of-mass and angular velocities
* :doc:`temp/sphere <compute_temp_sphere>` - temperature of spherical particles
* :doc:`temp/uef <compute_temp_uef>` - kinetic energy tensor in the reference frame of an applied flow field
* :doc:`ti <compute_ti>` - thermodynamic integration free energy values
* :doc:`torque/chunk <compute_torque_chunk>` - torque applied on each chunk
* :doc:`vacf <compute_vacf>` - velocity auto-correlation function of group of atoms
* :doc:`vcm/chunk <compute_vcm_chunk>` - velocity of center-of-mass for each chunk
* :doc:`viscosity/cos <compute_viscosity_cos>` - velocity profile under cosine-shaped acceleration
* :doc:`voronoi/atom <compute_voronoi_atom>` - Voronoi volume and neighbors for each atom
* :doc:`xrd <compute_xrd>` - x-ray diffraction intensity on a mesh of reciprocal lattice nodes

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

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

:doc:`uncompute <uncompute>`, :doc:`compute_modify <compute_modify>`, :doc:`fix ave/atom <fix_ave_atom>`, :doc:`fix ave/time <fix_ave_time>`, :doc:`fix ave/histo <fix_ave_histo>`

**Default:** none
