\(\renewcommand{\AA}{\text{Å}}\)

# fix reaxff/species command

Accelerator Variants: reaxff/species/kk

## Syntax

    fix ID group-ID reaxff/species Nevery Nrepeat Nfreq filename keyword value ...

- ID, group-ID are documented in fix command

- reaxff/species = style name of this command

- Nevery = sample bond-order every this many timesteps

- Nrepeat = # of bond-order samples used for calculating averages

- Nfreq = calculate average bond-order every this many timesteps

- filename = name of output file

- zero or more keyword/value pairs may be appended

- keyword = cutoff or element or position or delete or delete_rate_limit

      cutoff value = I J Cutoff
        I, J = atom types (see asterisk form below)
        Cutoff = Bond-order cutoff value for this pair of atom types
      element value = Element1, Element2, ...
      position value = posfreq filepos
        posfreq = write position files every this many timestep
        filepos = name of position output file
      delete value = filedel keyword value
        filedel = name of delete species output file
        keyword = specieslist or masslimit
          specieslist value = Nspecies Species1 Species2 ...
            Nspecies = number of species in list
          masslimit value = massmin massmax
            massmin = minimum molecular weight of species to delete
            massmax = maximum molecular weight of species to delete
      delete_rate_limit value = Nlimit Nsteps
            Nlimit = maximum number of deletions allowed to occur within interval
            Nsteps = the interval (number of timesteps) over which to count deletions
      delete_subgroup value = group-ID
            group-ID = name of a group

## Examples

    fix 1 all reaxff/species 10 10 100 species.out
    fix 1 all reaxff/species 1 2 20 species.out cutoff 1 1 0.40 cutoff 1 2*3 0.55
    fix 1 all reaxff/species 1 100 100 species.out element Au O H position 1000 AuOH.pos
    fix 1 all reaxff/species 1 100 100 species.out delete species.del masslimit 0 50

## Description

Write out the chemical species information computed by the ReaxFF potential specified by pair_style reaxff. Bond-order values (either averaged or instantaneous, depending on value of Nrepeat) are used to determine chemical bonds. Every Nfreq timesteps, chemical species information is written to filename as a two line output. The first line is a header containing labels. The second line consists of the following: timestep, total number of molecules, total number of distinct species, number of molecules of each species. In this context, “species” means a unique molecule. The chemical formula of each species is given in the first line.

Warning

In order to compute averaged data, it is required that there are no neighbor list rebuilds for at least Nrepeat*Nevery steps preceding each Nfreq step. For that reason, fix reaxff/species may change your neighbor list settings. Reneighboring will occur no more frequently than every Nrepeat*Nevery timesteps, and will occur less frequently if Nfreq is not a multiple of Nrepeat*Nevery. There will be a warning message showing the new settings. Having a Nfreq setting that is larger than what is required for correct computation of the ReaxFF force field interactions, in combination with certain Nrepeat and Nevery settings, can thus lead to incorrect results. For typical ReaxFF calculations, reneighboring only every 100 steps is already quite a low frequency.

If the filename ends with “.gz” or some other supported compression format suffix, the output file is written in compressed format. A compressed output file can be significantly smaller than the text version, but will also take longer to write.

Added in version 15Jun2023: Support for wildcards added

Optional keyword cutoff can be assigned to change the minimum bond-order values used in identifying chemical bonds between pairs of atoms. Bond-order cutoffs should be carefully chosen, as bond-order cutoffs that are too small may include too many bonds (which will result in an error), while cutoffs that are too large will result in fragmented molecules. The default cutoff of 0.3 usually gives good results. A wildcard asterisk can be used in place of or in conjunction with the I,J arguments to set the bond-order cutoff for multiple pairs of atom types. This takes the form “*” or “*n” or “n*” or “m*n”. If \(N\) is the number of atom types, then an asterisk with no numeric values means all types from 1 to \(N\). A leading asterisk means all types from 1 to n (inclusive). A trailing asterisk means all types from n to \(N\) (inclusive). A middle asterisk means all types from m to n (inclusive).

The optional keyword element can be used to specify the chemical symbol printed for each LAMMPS atom type. The number of symbols must match the number of LAMMPS atom types and each symbol must consist of 1 or 2 alphanumeric characters. By default, these symbols are the same as the chemical identity of each LAMMPS atom type, as specified by the ReaxFF pair_coeff command and the ReaxFF force field file.

The optional keyword position writes center-of-mass positions of each identified molecules to file filepos every posfreq timesteps. The first line contains information on timestep, total number of molecules, total number of distinct species, and box dimensions. The second line is a header containing labels. From the third line downward, each molecule writes a line of output containing the following information: molecule ID, number of atoms in this molecule, chemical formula, total charge, and center-of-mass xyz positions of this molecule. The xyz positions are in fractional coordinates relative to the box dimensions.

For the keyword position, the filepos is the name of the output file. It can contain the wildcard character “*”. If the “*” character appears in filepos, then one file per snapshot is written at posfreq and the “*” character is replaced with the timestep value. For example, AuO.pos.* becomes AuO.pos.0, AuO.pos.1000, etc.

Added in version 3Aug2022.

The optional keyword delete enables the periodic removal of molecules from the system (Gissinger). Criteria for deletion can be either a list of specific chemical formulae or a range of molecular weights. Molecules are deleted every Nfreq timesteps, and bond connectivity is determined using the Nevery and Nrepeat keywords. The filedel argument is the name of the output file that records the species that are removed from the system (see below for output file format options). The specieslist keyword permits specific chemical species to be deleted. The Nspecies argument specifies how many species are eligible for deletion and is followed by a list of chemical formulae, whose strings are compared to species identified by this fix. For example, “specieslist 2 CO CO2” deletes molecules that are identified as “CO” and “CO2” in the species output file. The masslimit keyword permits deletion of molecules with molecular weights between massmin and massmax. The specieslist and masslimit keywords cannot both be used in the same reaxff/species fix.

The delete_rate_limit keyword can enforce an upper limit on the overall rate of molecule deletion. The number of deletion occurrences is limited to Nlimit within an interval of Nsteps timesteps. Nlimit can be specified with an equal-style variable. When using the delete_rate_limit keyword, no deletions are permitted to occur within the first Nsteps timesteps of the first run (after reading either a data or restart file).

Added in version 10Dec2025.

The delete_subgroup keyword enforces a requirement that deleted molecules must have at least one atom in the group specified by the keyword’s group-ID argument. For example, this keyword can be used to delete an entire molecule when it is partially inside a region, as long as the molecule is fully contained with the overall fix group.

The delete keyword can output information about the deleted molecules in either the legacy format or in JSON format. The latter is activated when the filedel argument has a ‘.json’ extension. The legacy format lists how many of each species are deleted, while the JSON format provides the atom ID, atom type, and coordinates of deleted atoms within each molecule. The format for legacy output changes depending on the keyword used. When using the specieslist keyword and legacy format, the filedel file has the following format: the first line lists the chemical formulae eligible for deletion, and each additional line contains the timestep on which a molecule deletion occurs and the number of each species deleted on that timestep. When using the masslimit keyword and the legacy format, each line of the filedel file contains the timestep on which deletions occurs, followed by how many of each species are deleted (with quantities preceding chemical formulae). The JSON format is the same regardless of the keyword, and lists deleted molecules in the style of the JSON molecule file, where more discussion of JSON schema can be found. Here is an example of a JSON output file from a simulation during which one water molecule was deleted on the first timestep:

    {
        "application": "LAMMPS",
        "units": "real",
        "format": "dump",
        "style": "molecules",
        "revision": 1,
        "title": "fix reaxff/species: delete keyword",
        "timesteps": [
            {
                "timestep": 1,
                "molecules": [
                    {
                        "types": {
                            "format": ["atom-id", "type"],
                            "data": [
                                [1368, "H"],
                                [1366, "O"],
                                [1367, "H"]
                            ]
                        },
                        "coords": {
                            "format": ["atom-id", "x", "y", "z"],
                            "data": [
                                [1368, 26.787767440427466, 29.785528640296768, 25.85197353660144],
                                [1366, 26.641801222582824, 29.868106247702887, 24.91285138212243],
                                [1367, 25.69611192416744, 30.093425787807448, 24.914380215672846]
                            ]
                        }
                    }
                ]
            }
        ]
    }

The required first-level keys of the JSON format output are “application”, “format”, “style”, “revision”, and “timesteps”, and optional keys are “units” and “title”. The value of the “timesteps” key is an array of objects that contain data for each timestep on which a molecule was deleted, and the other first-level keys identify this JSON schema. The objects in “timesteps” contains two keys, “timestep” and “molecules”. The “molecules” key is an array of LAMMPS molecule JSON objects, one for each deleted molecule. The “format” keys within molecule JSON objects are only listed once per output file, for brevity. The “atom-id” values are atom IDs from the simulation, and the “type” values are atom types. In the above example, the types were reported as strings corresponding to elements using type labels.

The Nevery, Nrepeat, and Nfreq arguments specify on what timesteps the bond-order values are sampled to get the average bond order. The species analysis is performed using the average bond-order on timesteps that are a multiple of Nfreq. The average is over Nrepeat bond-order samples, computed in the preceding portion of the simulation every Nevery timesteps. Nfreq must be a multiple of Nevery and Nevery must be non-zero even if Nrepeat is 1. Also, the timesteps contributing to the average bond-order cannot overlap, i.e. Nrepeat*Nevery can not exceed Nfreq.

For example, if Nevery=2, Nrepeat=6, and Nfreq=100, then bond-order values on timesteps 90,92,94,96,98,100 will be used to compute the average bond-order for the species analysis output on timestep 100.

## Restart, fix_modify, output, run start/stop, minimize info

No information about this fix is written to binary restart files. None of the fix_modify options are relevant to this fix.

This fix computes both a global vector of length 2 and a per-atom vector, either of which can be accessed by various output commands. The values in the global vector are “intensive”.

The 2 values in the global vector are as follows:

> 1. total number of molecules

> 2. total number of distinct species

The per-atom vector stores the molecule ID for each atom as identified by the fix. If an atom is not in a molecule, its ID will be 0. For atoms in the same molecule, the molecule ID for all of them will be the same, and molecule IDs will range from 1 to the number of molecules.

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.

This fix supports dynamic groups only if the Nrepeat setting is 1, i.e. there is no averaging.

Styles with a gpu, intel, kk, omp, or opt suffix are functionally the same as the corresponding style without the suffix. They have been optimized to run faster, depending on your available hardware, as discussed on the Accelerator packages page. The accelerated styles take the same arguments and should produce the same results, except for round-off and precision issues.

These accelerated styles are part of the GPU, INTEL, KOKKOS, OPENMP, and OPT packages, respectively. They are only enabled if LAMMPS was built with those packages. See the Build package page for more info.

You can specify the accelerated styles explicitly in your input script by including their suffix, or you can use the -suffix command-line switch when you invoke LAMMPS, or you can use the suffix command in your input script.

See the Accelerator packages page for more instructions on how to use the accelerated styles effectively.

## Restrictions

The “fix reaxff/species” requires that pair_style reaxff is used. This fix is part of the REAXFF package. It is only enabled if LAMMPS was built with that package. See the Build package page for more info.

To write compressed species files, you must compile LAMMPS with the `-DLAMMPS_GZIP` option. See the Build settings doc page for details.

## Related commands

pair_style reaxff, fix reaxff/bonds

## Default

The default values for bond-order cutoffs are 0.3 for all I-J pairs. The default element symbols are taken from the ReaxFF pair_coeff command. Position files are not written by default.

(Gissinger) Jacob R. Gissinger, Scott R. Zavada, Joseph G. Smith, Josh Kemppainen, Ivan Gallegos, Gregory M. Odegard, Emilie J. Siochi, and Kristopher E. Wise, Carbon, 202, 336-347 (2023).