Merge pull request #14 from lammps/master

if(BUILD_SHARED_LIBS) # for all pkg libs, mpi_stubs and linalg

  set(CMAKE_POSITION_INDEPENDENT_CODE ON)

endif()

option(DEVELOPER_MODE "Enable developer mode" OFF)

mark_as_advanced(DEVELOPER_MODE)

option(CMAKE_VERBOSE_MAKEFILE "Generate verbose Makefiles" OFF)

include(GNUInstallDirs)

set(LAMMPS_LINK_LIBS)

endif()

if(PKG_KIM)

  find_package(KIM QUIET)

  if(NOT KIM_FOUND)

    message(STATUS "KIM not found - we will build our own")

  option(DOWNLOAD_KIM "Download kim-api (instead of using the system's one)" OFF)

  if(DOWNLOAD_KIM)

    include(ExternalProject)

    ExternalProject_Add(kim_build

      URL https://github.com/openkim/kim-api/archive/v1.9.4.tar.gz

      URL_MD5 f4d35a1705eed46d64c7c0ab448ff3e0

      URL https://github.com/openkim/kim-api/archive/v1.9.5.tar.gz

      URL_MD5 9f66efc128da33039e30659f36fc6d00

      BUILD_IN_SOURCE 1

      CONFIGURE_COMMAND <SOURCE_DIR>/configure --prefix=<INSTALL_DIR>

      )

    set(KIM_INCLUDE_DIRS ${INSTALL_DIR}/include/kim-api-v1)

    set(KIM_LIBRARIES ${INSTALL_DIR}/lib/libkim-api-v1.so)

    list(APPEND LAMMPS_DEPS kim_build)

  else()

    find_package(KIM)

    if(NOT KIM_FOUND)

      message(FATAL_ERROR "KIM not found, help CMake to find it by setting KIM_LIBRARY and KIM_INCLUDE_DIR, or set DOWNLOAD_KIM=ON to download it")

    endif()

  endif()

  list(APPEND LAMMPS_LINK_LIBS ${KIM_LIBRARIES})

  include_directories(${KIM_INCLUDE_DIRS})

endif()

if(PKG_USER-INTEL)

    if(NOT DEVELOPER_MODE)

      if(NOT CMAKE_CXX_COMPILER_ID STREQUAL "Intel")

        message(FATAL_ERROR "USER-INTEL is only useful together with intel compiler")

      endif()

      if(CMAKE_CXX_COMPILER_VERSION VERSION_LESS 16)

        message(FATAL_ERROR "USER-INTEL is needed at least 2016 intel compiler, found ${CMAKE_CXX_COMPILER_VERSION}")

      endif()

    endif()

    option(INJECT_INTEL_FLAG "Inject OMG fast flags for USER-INTEL" ON)

    if(INJECT_INTEL_FLAG AND CMAKE_CXX_COMPILER_ID STREQUAL "Intel")

      if(CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.3 OR CMAKE_CXX_COMPILER_VERSION VERSION_EQUAL 17.4)

        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xCOMMON-AVX512")

      else()

        set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -xHost")

      endif()

      include(CheckCXXCompilerFlag)

      foreach(_FLAG -qopenmp -qno-offload -fno-alias -ansi-alias -restrict -DLMP_INTEL_USELRT -DLMP_USE_MKL_RNG -O2 "-fp-model fast=2" -no-prec-div -qoverride-limits -qopt-zmm-usage=high)

        check_cxx_compiler_flag("${__FLAG}" COMPILER_SUPPORTS${_FLAG})

        if(COMPILER_SUPPORTS${_FLAG})

          set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} ${_FLAG}")

        endif()

      endforeach()

    endif()

    set(USER-INTEL_SOURCES_DIR ${LAMMPS_SOURCE_DIR}/USER-INTEL)

    set(USER-INTEL_SOURCES ${USER-INTEL_SOURCES_DIR}/intel_preprocess.h

                           ${USER-INTEL_SOURCES_DIR}/intel_buffers.h

bond/react = style name of this fix command :l

zero or more common keyword/value pairs may be appended directly after 'bond/react' :l

these apply to all reaction specifications (below) :l

common_keyword = {stabilization}

  {stabilization} values = group-ID xmax

    group-ID = user-assigned ID of an internally-created dynamic group that excludes reacting atoms, and can be used by a subsequent time integration fix such as nvt, npt, or nve (cannot be 'all')

  {xmax} value = distance

    distance = xmax value that is used by an internally created "nve/limit"_fix_nve_limit.html integrator

react = mandatory argument indicating new reaction specification

  react-ID = user-assigned name for the reaction

  react-group-ID = only atoms in this group are available for the reaction

common_keyword = {stabilization} :l

  {stabilization} values = {no} or {yes} {group-ID} {xmax}

    {no} = no reaction site stabilization

    {yes} = perform reaction site stabilization

      {group-ID} = user-assigned ID for all non-reacting atoms (group created internally)

      {xmax} = xmax value that is used by an internally created "nve/limit"_fix_nve_limit.html integrator :pre

react = mandatory argument indicating new reaction specification :l

  react-ID = user-assigned name for the reaction :l

  react-group-ID = only atoms in this group are available for the reaction :l

  Nevery = attempt reaction every this many steps :l

  Rmin = bonding pair atoms must be separated by more than Rmin to initiate reaction (distance units) :l

  Rmax = bonding pair atoms must be separated by less than Rmax to initiate reaction (distance units) :l

molecule mol1 pre_reacted_topology.txt

molecule mol2 post_reacted_topology.txt

fix 5 all bond/react stabilization no react myrxn1 all 1 0 3.25 mol1 mol2 map_file.txt

fix 5 all bond/react stabilization no react myrxn1 all 1 0 3.25 mol1 mol2 map_file.txt :pre

molecule mol1 pre_reacted_rxn1.txt

molecule mol2 post_reacted_rxn1.txt

fix 5 all bond/react stabilization yes nvt_grp .03 &

  react myrxn1 all 1 0 3.25 mol1 mol2 map_file_rxn1.txt prob 0.50 12345 &

  react myrxn2 all 1 0 2.75 mol3 mol4 map_file_rxn2.txt prob 0.25 12345

fix 6 nvt_grp nvt temp 300 300 100 # system-wide thermostat must be defined after bond/react :pre

fix 6 nvt_grp nvt temp 300 300 100 # set thermostat after bond/react :pre

[Description:]

Initiate complex covalent bonding (topology) changes. These topology

changes will be referred to as "reactions" throughout this

changes will be referred to as 'reactions' throughout this

documentation. Topology changes are defined in pre- and post-reaction

molecule templates and can include creation and deletion of bonds,

angles, dihedrals, impropers, bond-types, angle-types, dihedral-types,

reaction has occurred 4) create a map that relates the

template-atom-IDs of each atom between pre- and post-reaction molecule

templates 5) fill a simulation box with molecules and run a simulation

with fix/bond react.

with fix bond/react.

Only one 'fix bond/react' command can be used at a time. Multiple

reactions can be simultaneously applied by specifying multiple 'react'

reactions can be simultaneously applied by specifying multiple {react}

arguments to a single 'fix bond/react' command. This syntax is

necessary because the 'common keywords' are applied to all reactions.

during the simulation.

The group-ID set using the {stabilization} keyword should be a

previously unused group-ID. The fix bond/react command creates a

"dynamic group"_group.html of this name that excludes reacting atoms.

This dynamic group-ID should then be used by a subsequent system-wide

time integrator, as shown in the second example above. It is currently

previously unused group-ID. It cannot be specified as 'all'. The fix

bond/react command creates a "dynamic group"_group.html of this name

that includes all non-reacting atoms. This dynamic group-ID should

then be used by a subsequent system-wide time integrator such as nvt,

npt, or nve, as shown in the second example above. It is currently

necessary to place the time integration command after the fix

bond/react command due to the internal dynamic grouping performed by

fix bond/react.

the system, i.e. you should generally not have a separate thermostat

which acts on the 'all' group.

The following comments pertain to each 'react' argument:

The following comments pertain to each {react} argument:

A check for possible new reaction sites is performed every Nevery

A check for possible new reaction sites is performed every {Nevery}

timesteps.

Two conditions must be met for a reaction to occur. First a bonding

A bonding atom pair will be identified if several conditions are met.

First, a pair of atoms within the specified react-group-ID of type

typei and typej must separated by a distance between Rmin and Rmax. It

is possible that multiple bonding atom pairs are identified: if the

bonding atoms in the pre-reacted template are not 1-2, 1-3, or 1-4

neighbors, the closest bonding atom partner is set as its bonding

partner; otherwise, the farthest potential partner is chosen. Then, if

both an atomi and atomj have each other as their nearest bonding

partners, these two atoms are identified as the bonding atom pair of

the reaction site. Once this unique bonding atom pair is identified

for each reaction, there could two or more reactions that involve a

given atom on the same timestep. If this is the case, only one such

reaction is permitted to occur. This reaction is chosen randomly from

all potential reactions. This capability allows e.g. for different

reaction pathways to proceed from identical reaction sites with

user-specified probabilities.

typei and typej must separated by a distance between {Rmin} and

{Rmax}. It is possible that multiple bonding atom pairs are

identified: if the bonding atoms in the pre-reacted template are not

1-2, 1-3, or 1-4 neighbors, the closest bonding atom partner is set as

its bonding partner; otherwise, the farthest potential partner is

chosen. Then, if both an atomi and atomj have each other as their

nearest bonding partners, these two atoms are identified as the

bonding atom pair of the reaction site. Once this unique bonding atom

pair is identified for each reaction, there could two or more

reactions that involve a given atom on the same timestep. If this is

the case, only one such reaction is permitted to occur. This reaction

is chosen randomly from all potential reactions. This capability

allows e.g. for different reaction pathways to proceed from identical

reaction sites with user-specified probabilities.

The pre-reacted molecule template is specified by a molecule command.

This molecule template file contains a sample reaction site and its

The map file is a text document with the following format:

Format of the map file

A map file has a header and a body. The header appears first. The

first line of the header is always skipped; it typically contains a

description of the file.  Lines can have a trailing comment starting

with '#' that is ignored. If the line is blank (only whitespace after

comment is deleted), it is skipped. If the line contains a header

keyword, the corresponding value(s) is read from the line. If it

doesn't contain a header keyword, the line begins the body of the

file.

The header contains one mandatory keyword and one optional keyword.

The mandatory keyword is 'equivalences' and the optional keyword is

'edgeIDs.' These specify the number of atoms in the pre- and

post-reacted templates and the number of edge atoms in pre-reacted

template, respectively.

The body contains two mandatory sections and one optional section. The

first section begins with the keyword 'BondingIDs' and lists the atom

IDs of the bonding atom pair in the pre-reacted molecule template. The

second mandatory section begins with the keyword 'Equivalences' and

lists a one-to-one correspondence between atom IDs of the pre- and

post-reacted templates. The optional section begins with the keyword

'EdgeIDs' and list the atom IDs of edge atoms in the pre-reacted

A map file has a header and a body. The header of map file the

contains one mandatory keyword and one optional keyword. The mandatory

keyword is 'equivalences' and the optional keyword is 'edgeIDs':

N {equivalences} = # of atoms N in the reaction molecule templates

N {edgeIDs} = # of edge atoms N in the pre-reacted molecule template :pre

The body of the map file contains two mandatory sections and one

optional section. The first mandatory section begins with the keyword

'BondingIDs' and lists the atom IDs of the bonding atom pair in the

pre-reacted molecule template. The second mandatory section begins

with the keyword 'Equivalences' and lists a one-to-one correspondence

between atom IDs of the pre- and post-reacted templates. The first

column is an atom ID of the pre-reacted molecule template, and the

second column is the corresponding atom ID of the post-reacted

molecule template. The optional section begins with the keyword

'EdgeIDs' and lists the atom IDs of edge atoms in the pre-reacted

molecule template.

Format of the header of the map file

These are the recognized header keywords. Header lines can come in any

order. The value(s) are read from the beginning of the line. Thus the

keyword 'equivalences' should be in a line like "25 equivalences."

equivalences = # of atoms in the pre- and post-reacted molecule

templates edgeIDs = # of edge atoms in the pre-reacted molecule template :pre

The edgeIDs keyword is optional.

Format of the body of the map file

These are the section keywords for the body of the file.

BondingIDs, EdgeIDs = list of atom IDs of bonding and edge atoms in

the pre-reacted molecule template

Equivalences = a two column list where the first column is an atom ID

of the pre-reacted molecule template, and the second column is the

corresponding atom ID of the post-reacted molecule template

The bondingIDs section will always contain two atom IDs, corresponding

to the bonding atom pairs of the pre-reacted map file. The

Equivalences section will contain as many rows as there are atoms in

the pre- and post-reacted molecule templates. The edgeIDs section is

optional, but would contain an atom ID for each edge atom in the

pre-reacted molecule template.

A sample map file is given below:

:line

# This is a map file :pre

# this is a map file :pre

2 edgeIDs

7 equivalences :pre

BondingIDs :pre

3 5 :pre

3

5 :pre

EdgeIDs :pre

1 7 :pre

1

7 :pre

Equivalences :pre

post-reacted molecule template. All force fields with fixed bonds,

angles, dihedrals or impropers are supported.

A few capabilities to note: 1) You may specify as many 'react'

A few capabilities to note: 1) You may specify as many {react}

arguments as desired. For example, you could break down a complicated

reaction mechanism into several reaction steps, each defined by its

own 'react' argument. 2) While typically a bond is formed or removed

own {react} argument. 2) While typically a bond is formed or removed

between the bonding atom pairs specified in the pre-reacted molecule

template, this is not required. 3) By reversing the order of the pre-

and post- reacted molecule templates in another 'react' argument, you

and post- reacted molecule templates in another {react} argument, you

can allow for the possibility of one or more reverse reactions.

The optional keywords deal with the probability of a given reaction

would thermostat the group of all atoms currently involved in a

reaction:

fix 1 bond_react_MASTER_group temp/rescale 1 300 300 10 1

fix 1 bond_react_MASTER_group temp/rescale 1 300 300 10 1 :pre

NOTE: This command must be added after the fix bond/react command, and

will apply to all reactions.

[Restart, fix_modify, output, run start/stop, minimize info:]

No information about this fix is written to "binary restart

files"_restart.html.  None of the "fix_modify"_fix_modify.html options

are relevant to this fix.

files"_restart.html, aside from internally-created per-atom

properties. None of the "fix_modify"_fix_modify.html options are

relevant to this fix.

This fix computes one statistic for each 'react' argument that it

This fix computes one statistic for each {react} argument that it

stores in a global vector, of length 'number of react arguments', that

can be accessed by various "output

commands"_Section_howto.html#howto_15. The vector values calculated by

:line

:link(Gissinger) [(Gissinger)] Gissinger, Jensen and Wise, Polymer,

128, 211 (2017).

:link(Gissinger)

[(Gissinger)] Gissinger, Jensen and Wise, Polymer, 128, 211 (2017).

[Restrictions:]

This pair style is part of the USER-MISC package. It is only enabled

if LAMMPS was built with that package.  See

the "Making LAMMPS"_Section_start.html#start_3 section for more info.

This pair style is part of the MANYBODY package. It is only enabled if

LAMMPS was built with that package.  See the "Making

LAMMPS"_Section_start.html#start_3 section for more info.

This pair style requires the "newton"_newton.html setting to be "on"

for pair interactions.

:line

:link(Gao)

[(Gao)] Gao and Weber, Nuclear Instruments and Methods in Physics Research B 191 (2012) 504.

[(Gao)] Gao and Weber, Nuclear Instruments and Methods in Physics

Research B 191 (2012) 504.

implemented as a stand-alone C code and is now integrated into LAMMPS

as a package.

The {reax/c/kk} style is a Kokkos version of the ReaxFF potential that is

derived from the {reax/c} style. The Kokkos version can run on GPUs and

can also use OpenMP multithreading. For more information about the Kokkos package,

see "Section 4"_Section_packages.html#kokkos and "Section 5.3.3"_accelerate_kokkos.html.

One important consideration when using the {reax/c/kk} style is the choice of either

half or full neighbor lists. This setting can be changed using the Kokkos "package"_package.html

command.

The {reax/c/kk} style is a Kokkos version of the ReaxFF potential that

is derived from the {reax/c} style. The Kokkos version can run on GPUs

and can also use OpenMP multithreading. For more information about the

Kokkos package, see "Section 4"_Section_packages.html#kokkos and

"Section 5.3.3"_accelerate_kokkos.html.  One important consideration

when using the {reax/c/kk} style is the choice of either half or full

neighbor lists. This setting can be changed using the Kokkos

"package"_package.html command.

The {reax/c} style differs from the "pair_style reax"_pair_reax.html

command in the lo-level implementation details.  The {reax} style is a

a contact request at the Materials Computation Center (MCC) website

"https://www.mri.psu.edu/materials-computation-center/connect-mcc"_https://www.mri.psu.edu/materials-computation-center/connect-mcc,

describing the material(s) you are interested in modeling with ReaxFF.

They can tell

you what is currently available or what it would take to create a

suitable ReaxFF parameterization.

They can tell you what is currently available or what it would take to

create a suitable ReaxFF parameterization.

The {cfile} setting can be specified as NULL, in which case default

settings are used. A control file can be specified which defines

interactions in the system.

See the "fix qeq/reax"_fix_qeq_reax.html command for details.

Using the optional keyword {lgvdw} with the value {yes} turns on

the low-gradient correction of the ReaxFF/C for long-range

London Dispersion, as described in the "(Liu)"_#Liu_2011 paper. Force field

Using the optional keyword {lgvdw} with the value {yes} turns on the

low-gradient correction of the ReaxFF/C for long-range London

Dispersion, as described in the "(Liu)"_#Liu_2011 paper. Force field

file {ffield.reax.lg} is designed for this correction, and is trained

for several energetic materials (see "Liu"). When using lg-correction,

recommended value for parameter {thb} is 0.01, which can be set in the

control file.  Note: Force field files are different for the original

or lg corrected pair styles, using wrong ffield file generates an error message.

or lg corrected pair styles, using wrong ffield file generates an

error message.

Using the optional keyword {enobonds} with the value {yes}, the energy

of atoms with no bonds (i.e. isolated atoms) is included in the total

potential energy and the per-atom energy of that atom.  If the value

{no} is specified then the energy of atoms with no bonds is set to zero.

The latter behavior is usual not desired, as it causes discontinuities

in the potential energy when the bonding of an atom drops to zero.

{no} is specified then the energy of atoms with no bonds is set to

zero.  The latter behavior is usual not desired, as it causes

discontinuities in the potential energy when the bonding of an atom

drops to zero.

Optional keywords {safezone} and {mincap} are used for allocating

reax/c arrays.  Increasing these values can avoid memory problems, such

as segmentation faults and bondchk failed errors, that could occur under

certain conditions. These keywords aren't used by the Kokkos version, which

instead uses a more robust memory allocation scheme that checks if the sizes of

the arrays have been exceeded and automatically allocates more memory.

reax/c arrays.  Increasing these values can avoid memory problems,

such as segmentation faults and bondchk failed errors, that could

occur under certain conditions. These keywords aren't used by the

Kokkos version, which instead uses a more robust memory allocation

scheme that checks if the sizes of the arrays have been exceeded and

automatically allocates more memory.

The thermo variable {evdwl} stores the sum of all the ReaxFF potential

energy contributions, with the exception of the Coulombic and charge

energy into sub-categories, which can be accessed via the "compute

pair"_compute_pair.html command as a vector of values of length 14.

The 14 values correspond to the following sub-categories (the variable

names in italics match those used in the original FORTRAN ReaxFF code):

names in italics match those used in the original FORTRAN ReaxFF

code):

{eb} = bond energy

{ea} = atom energy

[Default:]

The keyword defaults are checkqeq = yes, enobonds = yes, lgvdw = no, safezone = 1.2,

mincap = 50.

The keyword defaults are checkqeq = yes, enobonds = yes, lgvdw = no,

safezone = 1.2, mincap = 50.

:line

[Restrictions:]

This pair style is part of the MANYBODY package.  It is only enabled

if LAMMPS was built with that package.  See

the "Making LAMMPS"_Section_start.html#start_3 section for more info.

if LAMMPS was built with that package.  See the "Making

LAMMPS"_Section_start.html#start_3 section for more info.

This pair style requires the "newton"_newton.html setting to be "on"

for pair interactions.