Merge pull request #1089 from lammps/spread

"bond/local"_compute_bond_local.html,

"centro/atom"_compute_centro_atom.html,

"chunk/atom"_compute_chunk_atom.html,

"chunk/spread/atom"_compute_chunk_spread_atom.html,

"cluster/atom"_compute_cluster_atom.html,

"cna/atom"_compute_cna_atom.html,

"cnp/atom"_compute_cnp_atom.html,

"property/local"_compute_property_local.html,

"rdf"_compute_rdf.html,

"reduce"_compute_reduce.html,

"reduce/chunk"_compute_reduce_chunk.html,

"reduce/region"_compute_reduce.html,

"rigid/local"_compute_rigid_local.html,

"saed"_compute_saed.html,

"fix ave/chunk"_fix_ave_chunk.html

any of the "compute */chunk"_compute.html commands :ul

Here, each of the 3 kinds of chunk-related commands is briefly

Here, each of the 4 kinds of chunk-related commands is briefly

overviewed.  Then some examples are given of how to compute different

properties with chunk commands.

Compute */chunk commands: :h4

Currently the following computes operate on chunks of atoms to produce

per-chunk values.

The following computes operate on chunks of atoms to produce per-chunk

values.  Any compute whose style name ends in "/chunk" is in this

category:

"compute com/chunk"_compute_com_chunk.html

"compute gyration/chunk"_compute_gyration_chunk.html

atoms and then dividing by summed mass.

All of these computes produce a global vector or global array as

output, wih one or more values per chunk.  They can be used

in various ways:

output, wih one or more values per chunk.  The output can be used in

various ways:

As input to the "fix ave/time"_fix_ave_time.html command, which can

write the values to a file and optionally time average them. :ulb,l

molecule diffusion rates. :l

As input to special functions of "equal-style

variables"_variable.html, like sum() and max().  E.g. to find the

largest cluster or fastest diffusing molecule. :l

:ule

variables"_variable.html, like sum() and max() and ave().  E.g. to

find the largest cluster or fastest diffusing molecule or average

radius-of-gyration of a set of molecules (chunks). :l,ule

Other chunk commands: :h4

"compute chunk/spread/atom"_compute_chunk_spread_atom.html

"compute reduce/chunk"_compute_reduce_chunk.html :ul

The "compute chunk/spread/atom"_compute_chunk_spread_atom.html command

spreads per-chunk values to each atom in the chunk, producing per-atom

values as its output.  This can be useful for outputting per-chunk

values to a per-atom "dump file"_dump.html.  Or for using an atom's

associated chunk value in an "atom-style variable"_variable.html.

The "compute reduce/chunk"_compute_reduce_chunk.html command reduces a

peratom value across the atoms in each chunk to produce a value per

chunk.  When used with the "compute

chunk/spread/atom"_compute_chunk_spread_atom.html command it can

create peratom values that induce a new set of chunks with a second

"compute chunk/atom"_compute_chunk_atom.html command.

Example calculations with chunks :h4

compute cc1 all chunk/atom c_cluster compress yes

compute size all property/chunk cc1 count

fix 1 all ave/histo 100 1 100 0 20 20 c_size mode vector ave running beyond ignore file tmp.histo :pre

(6) An example of using a per-chunk value to apply per-atom forces to

compress individual polymer chains (molecules) in a mixture, is

explained on the "compute

chunk/spread/atom"_compute_chunk_spread_atom.html command doc page.

(7) An example of using one set of per-chunk values for molecule

chunks, to create a 2nd set of micelle-scale chunks (clustered

molecules, due to hydrophobicity), is explained on the "compute

chunk/reduce"_compute_reduce_chunk.html command doc page.

"bond/local"_compute_bond_local.html - distance and energy of each bond

"centro/atom"_compute_centro_atom.html - centro-symmetry parameter for each atom

"chunk/atom"_compute_chunk_atom.html - assign chunk IDs to each atom

"chunk/spread/atom"_compute_chunk_spread_atom.html - spreads chunk values to each atom in chunk

"cluster/atom"_compute_cluster_atom.html - cluster ID for each atom

"cna/atom"_compute_cna_atom.html - common neighbor analysis (CNA) for each atom

"com"_compute_com.html - center-of-mass of group of atoms

"property/chunk"_compute_property_chunk.html - extract various per-chunk attributes

"rdf"_compute_rdf.html - radial distribution function g(r) histogram of group of atoms

"reduce"_compute_reduce.html - combine per-atom quantities into a single global value

"reduce/chunk"_compute_reduce_chunk.html - reduce per-atom quantities within each chunk

"reduce/region"_compute_reduce.html - same as compute reduce, within a region

"rigid/local"_compute_rigid_local.html - extract rigid body attributes

"slice"_compute_slice.html - extract values from global vector or array

ID, group-ID are documented in "compute"_compute.html command :ulb,l

chunk/atom = style name of this compute command :l

style = {bin/1d} or {bin/2d} or {bin/3d} or {bin/sphere} or {type} or {molecule} or {compute/fix/variable}

style = {bin/1d} or {bin/2d} or {bin/3d} or {bin/sphere} or {type} or {molecule} or c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name

  {bin/1d} args = dim origin delta

    dim = {x} or {y} or {z}

    origin = {lower} or {center} or {upper} or coordinate value (distance units)

    ncbin = # of concentric circle bins between rmin and rmax

  {type} args = none

  {molecule} args = none

  {compute/fix/variable} = c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name with no args

  c_ID, c_ID\[I\], f_ID, f_ID\[I\], v_name args = none

    c_ID = per-atom vector calculated by a compute with ID

    c_ID\[I\] = Ith column of per-atom array calculated by a compute with ID

    f_ID = per-atom vector calculated by a fix with ID

compute 1 all chunk/atom bin/2d z lower 1.0 y 0.0 2.5

compute 1 all chunk/atom molecule region sphere nchunk once ids once compress yes

compute 1 all chunk/atom bin/sphere 5 5 5 2.0 5.0 5 discard yes

compute 1 all chunk/atom bin/cylinder z lower 2 10 10 2.0 5.0 3 discard yes :pre

compute 1 all chunk/atom bin/cylinder z lower 2 10 10 2.0 5.0 3 discard yes

compute 1 all chunk/atom c_cluster :pre

[Description:]

applied to the new {Nchunk} value, exactly as described in the

preceding paragraph.  Note that in this case, all atoms will end up

with chunk IDs <= {Nc}, but their original values (e.g. molecule ID or

compute/fix/variable value) may have been > {Nc}, because of the

compression operation.

compute/fix/variable) may have been > {Nc}, because of the compression

operation.

If {compress yes} is set, and the {compress} keyword comes after the

{limit} keyword, then the {limit} value of {Nc} is applied first to

"LAMMPS WWW Site"_lws - "LAMMPS Documentation"_ld - "LAMMPS Commands"_lc :c

:link(lws,http://lammps.sandia.gov)

:link(ld,Manual.html)

:link(lc,Commands_all.html)

:line

compute chunk/spread/atom command :h3

[Syntax:]

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

ID, group-ID are documented in "compute"_compute.html command :ulb,l

chunk/spread/atom = style name of this compute command :l

chunkID = ID of "compute chunk/atom"_compute_chunk_atom.html command :l

one or more inputs can be listed :l

input = c_ID, c_ID\[N\], f_ID, f_ID\[N\] :l

  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) :pre

:ule

[Examples:]

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

[Description:]

Define a calculation that "spreads" one or more per-chunk values to

each atom in the chunk.  This can be useful for creating a "dump

file"_dump.html where each atom lists info about the chunk it is in,

e.g. for post-processing purposes.  It can also be used in "atom-style

variables"_variable.html that need info about the chunk each atom is

in.  Examples are given below.

In LAMMPS, chunks are collections of atoms defined by a "compute

chunk/atom"_compute_chunk_atom.html 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 "compute

chunk/atom"_compute_chunk_atom.html and "Howto chunk"_Howto_chunk.html

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 a fix that calculates

per-chunk values.  For example, "fix ave/chunk"_fix_ave_chunk.html or

"fix ave/time"_fix_ave_time.html (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.

:line

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 "compute

com/chunk"_compute_com_chunk.html command creates a per-atom array

with 3 columns:

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\] :pre

:line

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.

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 :pre

The same per-chunk data for each atom could be used to define per-atom

forces for the "fix addforce"_fix_addforce.html command.  In this

example the forces act to pull atoms of an extended polymer chain

towards its COM in an attractive manner.

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 :pre

Note that "compute property/atom"_compute_property_atom.html 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:

compute         gyr all gyration/chunk cmol

variable        ave equal ave(c_gyr)

thermo_style    custom step etotal press v_ave :pre

       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 :pre

:line

[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 "Howto output"_Howto_output.html 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

"units"_units.html the corresponding input value is in.

The vector or array values are "intensive".

[Restrictions:] none

[Related commands:]

"compute chunk/atom"_compute_chunk_atom.html, "fix

ave/chunk"_fix_ave_chunk.html, "compute

reduce/chunk"_compute_reduce_chunk.html

[Default:] none