diff --git a/doc/src/fix_mdi_qm.rst b/doc/src/fix_mdi_qm.rst index 8ecb6ed488..a00f6e2edc 100644 --- a/doc/src/fix_mdi_qm.rst +++ b/doc/src/fix_mdi_qm.rst @@ -13,7 +13,7 @@ Syntax * ID, group-ID are documented in :doc:`fix ` command * mdi/qm = style name of this fix command * zero or more keyword/value pairs may be appended -* keyword = *virial* or *add* or *every* or *connect* +* keyword = *virial* or *add* or *every* or *connect* or *elements* .. parsed-literal:: @@ -28,6 +28,8 @@ Syntax *connect* args = *yes* or *no* yes = perform a one-time connection to the MDI engine code no = do not perform the connection operation + *elements* args = N_1 N_2 ... N_ntypes + N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types Examples """""""" @@ -36,7 +38,7 @@ Examples fix 1 all mdi/qm fix 1 all mdi/qm virial yes - fix 1 all mdi/qm add no every 100 + fix 1 all mdi/qm add no every 100 elements 13 29 Description """"""""""" @@ -118,6 +120,19 @@ series of system configurations. In this use case *connect no* is used along with the :doc:`mdi connect and exit ` command to one-time initiate/terminate the connection outside the loop. +The *elements* keyword allows specification of what element each +LAMMPS atom type corresponds to. This is specified by the atomic +number of the element, e.g. 13 for Al. An atomic number must be +specified for each of the ntypes LAMMPS atom types. Ntypes is +typically specified via the create_box command or in the data file +read by the read_data command. If this keyword is not specified, then +this fix will send the LAMMPS atom type for each atom to the MDI +engine. If both the LAMMPS driver and the MDI engine are initialized +so that atom type values are consistent in both codes, then the +*elements* keyword is not needed. Otherwise the keyword can be used +to insure the two codes are consistent in their definition of atomic +species. + ---------- The following 3 example use cases are illustrated in the examples/mdi diff --git a/doc/src/mdi.rst b/doc/src/mdi.rst index 0d647bbd4e..2591b3ea16 100644 --- a/doc/src/mdi.rst +++ b/doc/src/mdi.rst @@ -14,14 +14,18 @@ Syntax .. parsed-literal:: - *engine* args = none - *plugin* args = name keyword value keyword value + *engine* args = zero or more keyword arg pairs + keywords = *elements* + *elements* args = N_1 N_2 ... N_ntypes + N_1,N_2,...N_ntypes = atomic number for each of ntypes LAMMPS atom types + *plugin* args = name keyword value keyword value ... name = name of plugin library, e.g. lammps means a liblammps.so library will be loaded + keyword/value pairs in any order, some are required, some are optional keywords = *mdi* or *infile* or *extra* or *command* - *mdi* value = args passed to MDI for driver to operate with plugins - *infile* value = filename the engine will read at start-up + *mdi* value = args passed to MDI for driver to operate with plugins (required) + *infile* value = filename the engine will read at start-up (optional) *extra* value = aditional command-line args to pass to engine library when loaded - *command* value = a LAMMPS input script command to execute + *command* value = a LAMMPS input script command to execute (required) *connect* args = none *exit* args = none @@ -31,6 +35,7 @@ Examples .. code-block:: LAMMPS mdi engine + mdi engine elements 13 29 mdi plugin lammps mdi "-role ENGINE -name lammps -method LINK" & infile in.aimd.engine extra "-log log.aimd.engine.plugin" & command "run 5" @@ -109,6 +114,8 @@ commands, which are described further below. - Send/request charge on each atom (N values) * - >COORDS or ELEMENTS + - Send elements (atomic numbers) for each atom (N values) * - FORCES or TOLERANCE - Send 4 tolerance parameters for next MD minimization via OPTG command * - >TYPES or VELOCITIES or COORDS command), then LAMMPS will do a more expensive operation to migrate atoms to new processors as needed and - re-neighbor. If the >NATOMS or >TYPES commands have been sent - (since the previous >COORDS command), then LAMMPS assumes the - system is new and re-initializes an entirely new simulation. + re-neighbor. If the >NATOMS or >TYPES or >ELEMENTS commands have + been sent (since the previous >COORDS command), then LAMMPS assumes + the system is new and re-initializes an entirely new simulation. + +.. note:: + + The >TYPES or >ELEMENTS commands are how the MDI driver tells the + LAMMPS engine which LAMMPS atom type to assign to each atom. If + both the MDI driver and the LAMMPS engine are initialized so that + atom type values are consistent in both codes, then the >TYPES + command can be used. If not, the optional *elements* keyword can + be used to specify what element each LAMMPS atom type corresponds + to. This is specified by the atomic number of the element, e.g. 13 + for Al. An atomic number must be specified for each of the ntypes + LAMMPS atom types. Ntypes is typically specified via the + create_box command or in the data file read by the read_data + command. In this has been done, the MDI driver can send an + >ELEMENTS command to the LAMMPS driver with the atomic number of + each atom. The MD and OPTG commands perform an entire MD simulation or energy minimization (to convergence) with no communication from the driver