Syntax:
fix ID group-ID property/atom vec1 vec2 ... keyword value ...
mol = molecule IDs i_name = new integer vector referenced by name d_name = new floating-point vector referenced by name
ghost value = no or yes for whether ghost atom info in communicated
Examples:
fix 1 all property/atom mol fix 1 all property/atom i_myflag1 i_myflag2 fix 1 all property/atom d_sx d_sy d_sz
Description:
Create one or more additional per-atom vectors to store information about atoms and to use during a simulation. The specified group-ID is ignored by this fix.
The atom style used for a simulation defines a set of per-atom properties, as explained on the atom_style and read_data doc pages. The latter command allows these properties to be defined for each atom in the system when a data file is read. This fix will augment the set of properties with new custom ones.
This can be useful in at least two scenarios.
If the atom style (e.g. atomic or sphere) does not define molecule IDs, they can be added using the mol vector. This can be useful to carry along an additional flag with atoms, or to define "molecules" to use as rigid bodies with the fix rigid command. An alternative is to use an atom style that does define molecule IDs or a hybrid atom style that combines two styles to allow for molecule IDs, but that has 2 practical drawbacks. First it typically necessitates changing the format of the data file. And it may define additional properties that aren't needed such as bond lists (which has some overhead even if there are no bonds).
In the future, we may add additional per-atom properties like mol for molecule IDs that "turn-on" specific properties defined by some atom styles, so they can be used by atom styles that don't define them.
More generally, the i_name and d_name vectors allow one or more new custom per-atom properties to be defined. Each name must be unique and can use alphanumeric or underscore characters. These vectors can store whatever values you decide are useful in your simulation. As explained below there are several ways to initialize and access and output these values, both via input script commands and in new code that you add to LAMMPS.
This is effectively a simple way to add per-atom properties to a model without needing to write code for a new atom style that defines the properties. Note however that implementing a new atom style allows new atom properties to be more tightly and seamlessly integrated with the rest of the code.
The new atom properties encode values that migrate with atoms to new processors and are written to restart files. If you want the new properties to also be defined for ghost atoms, then use the border keyword with a value of yes. This will invoke extra communication when ghost atoms are created (at every re-neighboring) to insure the new properties are also defined for the ghost atoms.
IMPORTANT NOTE: The properties for ghost atoms are not updated every timestep, but only once every few steps when neighbor lists are re-built. Thus the border keyword is suitable for static properties, like molecule IDs, but not for dynamic properties that change every step. In that case, the code you add to LAMMPS to change the properties will also need to communicate their new values, an operation that can be invoked from within a pair style or fix or compute that you write.
This fix is one of a small number that can be defined in an input script before the simulation box is created or atoms are defined. This is so it can be used with the read_data command as described below.
Per-atom properties that are defined by the atom style are initialized when atoms are created, e.g. by the read_data or create_atoms commands. The per-atom properaties defined by this fix are not. So you need to initialize them explicitly. This can be done by the read_data command, using its fix keyword and passing it the fix-ID of this fix.
Thus these commands:
fix prop all property/atom mol d_flag read_data data.txt fix prop NULL Molecules
would allow a data file to have a section like this:
Molecules
1 4 1.5 2 4 3.0 3 10 1.0 4 10 1.0 5 10 1.0 ... N 763 4.5
where N is the number of atoms, and the first field on each line is the atom-ID, followed by a molecule-ID and a floating point value that will be stored in a new property called "flag". Note that the list of per-atom properties can be in any order.
Another way of initializing the new properties is via the set command. For example, if you wanted molecules defined for every set of 10 atoms, based on their atom-IDs, these commands could be used:
fix prop all property/atom mol variable cluster atom ((id-1)/10)+1 set id * mol v_cluster
The atom-style variable will create values for atoms with IDs 31,32,33,...40 that are 4.0,4.1,4.2,...,4.9. When the set commands assigns them to the molecule ID for each atom, they will be truncated to an integer value, so atoms 31-40 will all be assigned a molecule ID of 4.
Note that atomfile-style variables can also be used in place of atom-style variables, which means in this case that the molecule IDs could be read-in from a separate file and assinged by the set command. This allows you to initialize new per-atom properties in a completely general fashion.
For new atom properties specified as i_name or d_name, the compute property/atom command can access their values. This means that the values can be output via the dump custom command, accessed by fixes like fix ave/atom, accessed by other computes like compute reduce, or used in atom-style variables.
For example, these commands will output two new properties to a custom dump file:
fix prop all property/atom i_flag1 d_flag2 compute 1 all property/atom i_flag1 d_flag2 dump 1 all custom 100 tmp.dump id x y z c_11 c_12
If you wish to add new pair styles, fixes, or computes that use the per-atom properties defined by this fix, see Section modify of the manual which has some details on how the properties can be accessed from added classes.
Restart, fix_modify, output, run start/stop, minimize info:
This fix writes the per-atom values it stores to binary restart files, so that the values can be restored when a simulation is restarted. See the read_restart command for info on how to re-specify a fix in an input script that reads a restart file, so that the operation of the fix continues in an uninterrupted fashion.
None of the fix_modify options are relevant to this fix. No global or per-atom quantities are stored by this fix for access by various output commands. No parameter of this fix can be used with the start/stop keywords of the run command. This fix is not invoked during energy minimization.
Restrictions: none
Related commands:
read_data, set, compute property/atom
Default:
The default keyword values are ghost = no.