From 3b9cbe4361fabd25dccf5fc43b294af80912ac01 Mon Sep 17 00:00:00 2001 From: Yaser Afshar Date: Tue, 16 Feb 2021 16:44:58 -0600 Subject: [PATCH] Update the kim command doc Update the document with the latest interface changes. Replace the discontinued models in the examples with the correct models. Test all provided examples and fix the mistakes in them. --- doc/src/kim_commands.rst | 1299 ++++++++++++++++++++------------------ 1 file changed, 694 insertions(+), 605 deletions(-) diff --git a/doc/src/kim_commands.rst b/doc/src/kim_commands.rst index e9afa48fd5..47b8d3e790 100644 --- a/doc/src/kim_commands.rst +++ b/doc/src/kim_commands.rst @@ -1,106 +1,136 @@ -.. index:: kim_init, kim_interactions, kim_query, kim_param, kim_property +.. index:: kim_commands -:ref:`kim_init` command -========================================= - -:ref:`kim_interactions` command -========================================================= - -:ref:`kim_query` command -=========================================== - -:ref:`kim_param` command -=========================================== - -:ref:`kim_property` command -================================================= +kim command +=========== Syntax """""" .. code-block:: LAMMPS - kim_init model user_units unitarg - kim_interactions typeargs - kim_query variable formatarg query_function queryargs - kim_param get param_name index_range variables formatarg - kim_param set param_name index_range values - kim_property create instance_id property_id - kim_property modify instance_id key key_name key_name_key key_name_value - kim_property remove instance_id key key_name - kim_property destroy instance_id - kim_property dump file + kim sub-command -.. _formatarg_options: - -* model = name of the KIM interatomic model (the KIM ID for models archived in OpenKIM) -* user_units = the LAMMPS :doc:`units ` style assumed in the LAMMPS input script -* unitarg = *unit_conversion_mode* (optional) -* typeargs = atom type to species mapping (one entry per atom type) or *fixed_types* for models with a preset fixed mapping -* variable(s) = single name or list of names of (string style) LAMMPS variable(s) where a query result or parameter get result is stored. Variables that do not exist will be created by the command. -* formatarg = *list, split, or explicit* (optional): - - .. parsed-literal:: - - *list* = returns a single string with a list of space separated values - (e.g. "1.0 2.0 3.0"), which is placed in a LAMMPS variable as - defined by the *variable* argument. [default for *kim_query*] - *split* = returns the values separately in new variables with names based - on the prefix specified in *variable* and a number appended to - indicate which element in the list of values is in the variable. - *explicit* = returns the values separately in one more more variable names - provided as arguments that precede *formatarg*\ . [default for *kim_param*] - -* query_function = name of the OpenKIM web API query function to be used -* queryargs = a series of *keyword=value* pairs that represent the web query; supported keywords depend on the query function -* param_name = name of a KIM portable model parameter -* index_range = KIM portable model parameter index range (an integer for a single element, or pair of integers separated by a colon for a range of elements) -* values = new value(s) to replace the current value(s) of a KIM portable model parameter -* instance_id = a positive integer identifying the KIM property instance -* property_id = identifier of a `KIM Property Definition `_, which can be (1) a property short name, (2) the full unique ID of the property (including the contributor and date), (3) a file name corresponding to a local property definition file -* key_name = one of the keys belonging to the specified KIM property definition -* key_name_key = a key belonging to a key-value pair (standardized in the `KIM Properties Framework `__) -* key_name_value = value to be associated with a key_name_key in a key-value pair -* file = name of a file to write the currently defined set of KIM property instances to +* sub-command = :ref:`init ` or :ref:`interactions ` or + :ref:`query ` or :ref:`param ` or :ref:`property ` Examples """""""" .. code-block:: LAMMPS - kim_init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal - kim_interactions Si - kim_init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 real - kim_init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 metal unit_conversion_mode - kim_interactions C H O - kim_init Sim_LAMMPS_IFF_PCFF_HeinzMishraLinEmami_2015Ver1v5_FccmetalsMineralsSolventsPolymers__SM_039297821658_000 real - kim_interactions fixed_types - kim_query a0 get_lattice_constant_cubic crystal=["fcc"] species=["Al"] units=["angstrom"] - kim_param get gamma 1 varGamma - kim_param set gamma 1 3.0 - kim_property create 1 atomic-mass - kim_property modify 1 key mass source-value 26.98154 - kim_property modify 1 key species source-value Al - kim_property remove 1 key species - kim_property destroy 1 - kim_property dump results.edn - + kim init ... + kim interactions ... + kim query ... + kim param ... + kim property ... .. _kim_description: Description """"""""""" -The set of *kim_commands* provide a high-level wrapper around the +*kim command* provides a set of high-level wrapper around the `Open Knowledgebase of Interatomic Models (OpenKIM) `_ repository of interatomic models (IMs) (potentials and force fields), -so that they can be used by LAMMPS scripts. These commands do not implement -any computations directly, but rather generate LAMMPS input commands based -on the information retrieved from the OpenKIM repository to initialize and -activate OpenKIM IMs and query their predictions for use in the LAMMPS script. -All LAMMPS input commands generated and executed by *kim_commands* are +so that they can be used by LAMMPS scripts. This command is followed by a +a set of sub-coammnds. The kim command does not implement any computations +directly, but rather generates LAMMPS input commands based on the information +retrieved from the OpenKIM repository to initialize and activate OpenKIM IMs +and query their predictions for use in the LAMMPS script. +All LAMMPS input commands generated and executed by *kim command* are echoed to the LAMMPS log file. +Full syntax +""""""""""" + +.. code-block:: LAMMPS + + kim init model user_units unitarg + kim interactions typeargs + kim query variable formatarg query_function queryargs + kim param get param_name index_range variables formatarg + kim param set param_name index_range values + kim property create instance_id property_id + kim property modify instance_id key key_name key_name_key key_name_value + kim property remove instance_id key key_name + kim property destroy instance_id + kim property dump file + +.. _formatarg_options: + +* model = name of the KIM interatomic model (the KIM ID for models archived in + OpenKIM) +* user_units = the LAMMPS :doc:`units ` style assumed in the LAMMPS + input script +* unitarg = *unit_conversion_mode* (optional) +* typeargs = atom type to species mapping (one entry per atom type) or + *fixed_types* for models with a preset fixed mapping +* variable(s) = single name or list of names of (string style) LAMMPS + variable(s) where a query result or parameter get result is stored. Variables + that do not exist will be created by the command +* formatarg = *list, split, index, or explicit* (optional): + + .. parsed-literal:: + + *list* = returns a single string with a list of space separated values + (e.g. "1.0 2.0 3.0"), which is placed in a LAMMPS variable as + defined by the *variable* argument. [default for *query* + sub-command] + *split* = returns the values separately in new variables with names based + on the prefix specified in *variable* and a number appended to + indicate which element in the list of values is in the variable + *index* = returns a variable style index that can be incremented via the + next command. This enables the construction of simple loops + *explicit* = returns the values separately in one more more variable names + provided as arguments that precede *formatarg*\ . [default for + *kim_param*] + +* query_function = name of the OpenKIM web API query function to be used +* queryargs = a series of *keyword=value* pairs that represent the web query; + supported keywords depend on the query function +* param_name = name of a KIM portable model parameter +* index_range = KIM portable model parameter index range (an integer for a + single element, or pair of integers separated by a colon for a range of + elements) +* values = new value(s) to replace the current value(s) of a KIM portable model + parameter +* instance_id = a positive integer identifying the KIM property instance +* property_id = identifier of a + `KIM Property Definition `_, which can be (1) + a property short name, (2) the full unique ID of the property (including the + contributor and date), (3) a file name corresponding to a local property + definition file +* key_name = one of the keys belonging to the specified KIM property definition +* key_name_key = a key belonging to a key-value pair (standardized in the + `KIM Properties Framework `__) +* key_name_value = value to be associated with a key_name_key in a key-value + pair +* file = name of a file to write the currently defined set of KIM property + instances to + +Full syntax examples +"""""""""""""""""""" + +.. code-block:: LAMMPS + + kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal + kim interactions Si + kim init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_001 real + kim init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_001 metal unit_conversion_mode + kim interactions C H O + kim init Sim_LAMMPS_IFF_PCFF_HeinzMishraLinEmami_2015Ver1v5_FccmetalsMineralsSolventsPolymers__SM_039297821658_000 real + kim interactions fixed_types + kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom] + kim query model index get_available_models species=[Al] potential_type=[eam] + kim param get gamma 1 varGamma + kim param set gamma 1 3.0 + kim property create 1 atomic-mass + kim property modify 1 key mass source-value 26.98154 + kim property modify 1 key species source-value Al + kim property remove 1 key species + kim property destroy 1 + kim property dump results.edn + Benefits of Using OpenKIM IMs ----------------------------- @@ -109,22 +139,49 @@ Employing OpenKIM IMs provides LAMMPS users with multiple benefits: Reliability ^^^^^^^^^^^ -* All content archived in OpenKIM is reviewed by the `KIM Editor `_ for quality. -* IMs in OpenKIM are archived with full provenance control. Each is associated with a maintainer responsible for the integrity of the content. All changes are tracked and recorded. -* IMs in OpenKIM are exhaustively tested using `KIM Tests `_ that compute a host of material properties, and `KIM Verification Checks `_ that provide the user with information on various aspects of the IM behavior and coding correctness. This information is displayed on the IM's page accessible through the `OpenKIM browse interface `_. +* All content archived in OpenKIM is reviewed by the + `KIM Editor `_ for quality. +* IMs in OpenKIM are archived with full provenance control. Each is associated + with a maintainer responsible for the integrity of the content. All changes + are tracked and recorded. +* IMs in OpenKIM are exhaustively tested using + `KIM Tests `_ that compute a + host of material properties, and + `KIM Verification Checks `_ + that provide the user with information on various aspects of the IM behavior + and coding correctness. This information is displayed on the IM's page + accessible through the + `OpenKIM browse interface `_. Reproducibility ^^^^^^^^^^^^^^^ -* Each IM in OpenKIM is issued a unique identifier (`KIM ID `_), which includes a version number (last three digits). Any changes that can result in different numerical values lead to a version increment in the KIM ID. This makes it possible to reproduce simulations since the specific version of a specific IM used can be retrieved using its KIM ID. -* OpenKIM is a member organization of `DataCite `_ and issues digital object identifiers (DOIs) to all IMs archived in OpenKIM. This makes it possible to cite the IM code used in a simulation in a publications to give credit to the developers and further facilitate reproducibility. +* Each IM in OpenKIM is issued a unique identifier + (`KIM ID `_), which includes a + version number (last three digits). Any changes that can result in different + numerical values lead to a version increment in the KIM ID. This makes it + possible to reproduce simulations since the specific version of a specific IM + used can be retrieved using its KIM ID. +* OpenKIM is a member organization of `DataCite `_ and + issues digital object identifiers (DOIs) to all IMs archived in OpenKIM. This + makes it possible to cite the IM code used in a simulation in a publications + to give credit to the developers and further facilitate reproducibility. Convenience ^^^^^^^^^^^ -* IMs in OpenKIM are distributed in binary form along with LAMMPS and can be used in a LAMMPS input script simply by providing their KIM ID in the *kim_init* command documented on this page. -* The *kim_query* web query tool provides the ability to use the predictions of IMs for supported material properties (computed via `KIM Tests `_) as part of a LAMMPS input script setup and analysis. -* Support is provided for unit conversion between the :doc:`unit style ` used in the LAMMPS input script and the units required by the OpenKIM IM. This makes it possible to use a single input script with IMs using different units without change and minimizes the likelihood of errors due to incompatible units. +* IMs in OpenKIM are distributed in binary form along with LAMMPS and can be + used in a LAMMPS input script simply by providing their KIM ID in the + *kim init* command documented on this page. +* The *kim_query* web query tool provides the ability to use the predictions of + IMs for supported material properties (computed via + `KIM Tests `_) as part of a + LAMMPS input script setup and analysis. +* Support is provided for unit conversion between the :doc:`unit style ` + used in the LAMMPS input script and the units required by the OpenKIM IM. + This makes it possible to use a single input script with IMs using different + units without change and minimizes the likelihood of errors due to + incompatible units. .. _IM_types: @@ -135,12 +192,23 @@ There are two types of IMs archived in OpenKIM: .. _PM_type: -1. The first type is called a *KIM Portable Model* (PM). A KIM PM is an independent computer implementation of an IM written in one of the languages supported by KIM (C, C++, Fortran) that conforms to the KIM Application Programming Interface (`KIM API `_) Portable Model Interface (PMI) standard. A KIM PM will work seamlessly with any simulation code that supports the KIM API/PMI standard (including LAMMPS; see `complete list of supported codes `_). -2. The second type is called a *KIM Simulator Model* (SM). A KIM SM is an IM that is implemented natively within a simulation code (\ *simulator*\ ) that supports the KIM API Simulator Model Interface (SMI); in this case LAMMPS. A separate SM package is archived in OpenKIM for each parameterization of the IM, which includes all of the necessary parameter files, LAMMPS commands, and metadata (supported species, units, etc.) needed to run the IM in LAMMPS. +1. The first type is called a *KIM Portable Model* (PM). A KIM PM is an + independent computer implementation of an IM written in one of the languages + supported by KIM (C, C++, Fortran) that conforms to the KIM Application + Programming Interface (`KIM API `_) Portable + Model Interface (PMI) standard. A KIM PM will work seamlessly with any + simulation code that supports the KIM API/PMI standard (including LAMMPS; see + `complete list of supported codes `_). +2. The second type is called a *KIM Simulator Model* (SM). A KIM SM is an IM + that is implemented natively within a simulation code (\ *simulator*\ ) that + supports the KIM API Simulator Model Interface (SMI); in this case LAMMPS. A + separate SM package is archived in OpenKIM for each parameterization of the + IM, which includes all of the necessary parameter files, LAMMPS commands, and + metadata (supported species, units, etc.) needed to run the IM in LAMMPS. -With these two IM types, OpenKIM can archive and test almost all IMs that -can be used by LAMMPS. (It is easy to contribute new IMs to OpenKIM, see -the `upload instructions `_.) +With these two IM types, OpenKIM can archive and test almost all IMs that can be +used by LAMMPS. (It is easy to contribute new IMs to OpenKIM, see the +`upload instructions `_.) OpenKIM IMs are uniquely identified by a `KIM ID `_. @@ -155,7 +223,7 @@ By convention SM prefixes begin with *Sim_* to readily identify them. .. parsed-literal:: SW_StillingerWeber_1985_Si__MO_405512056662_005 - Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 + Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_001 Each OpenKIM IM has a dedicated "Model Page" on `OpenKIM `_ providing all the information on the IM including a title, description, @@ -169,16 +237,17 @@ The URL for the Model Page is constructed from the https://openkim.org/id/extended_KIM_ID -For example, for the Stillinger--Weber potential -listed above the Model Page is located at: +For example, for the Stillinger--Weber potential listed above the Model Page is +located at: .. parsed-literal:: `https://openkim.org/id/SW_StillingerWeber_1985_Si__MO_405512056662_005 `_ -See the `current list of KIM PMs and SMs archived in OpenKIM `_. -This list is sorted by species and can be filtered to display only -IMs for certain species combinations. +See the +`current list of KIM PMs and SMs archived in OpenKIM `_. +This list is sorted by species and can be filtered to display only IMs for +certain species combinations. See `Obtaining KIM Models `_ to learn how to install a pre-built binary of the OpenKIM Repository of Models. @@ -190,91 +259,87 @@ learn how to install a pre-built binary of the OpenKIM Repository of Models. Using OpenKIM IMs with LAMMPS ----------------------------- -Two commands are employed when using OpenKIM IMs, one to select the -IM and perform necessary initialization (\ *kim_init*\ ), and the second +Two sub-commands are employed when using OpenKIM IMs, one to select the +IM and perform necessary initialization (\ *kim init*\ ), and the second to set up the IM for use by executing any necessary LAMMPS commands -(\ *kim_interactions*\ ). Both are required. +(\ *kim interactions*\ ). Both are required. See the *examples/kim* directory for example input scripts that use KIM PMs and KIM SMs. -.. _kim_init command: +.. _init: -OpenKIM IM Initialization (*kim_init*) +OpenKIM IM Initialization (*kim init*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *kim_init* mode command must be issued **before** -the simulation box is created (normally at the top of the file). -This command sets the OpenKIM IM that will be used and may issue -additional commands changing LAMMPS default settings that are required -for using the selected IM (such as :doc:`units ` or -:doc:`atom_style `). If needed, those settings can be overridden, -however, typically a script containing a *kim_init* command -would not include *units* and *atom_style* commands. +The *kim* command followed by *init* sub-command must be issued **before** +the simulation box is created (normally at the top of the file). This command +sets the OpenKIM IM that will be used and may issue additional commands changing +LAMMPS default settings that are required for using the selected IM (such as +:doc:`units ` or :doc:`atom_style `). If needed, those +settings can be overridden, however, typically a script containing a *kim init* +command would not include *units* and *atom_style* commands. -The required arguments of *kim_init* are the *model* name of the -IM to be used in the simulation (for an IM archived in OpenKIM this is -its `extended KIM ID `_, and -the *user_units*, which are the LAMMPS :doc:`units style ` used -in the input script. (Any dimensioned numerical values in the input -script and values read in from files are expected to be in the -*user_units* system.) +The required arguments of *kim init* are the *model* name of the IM to be used +in the simulation (for an IM archived in OpenKIM this is its +`extended KIM ID `_, and the +*user_units*, which are the LAMMPS :doc:`units style ` used in the input +script. (Any dimensioned numerical values in the input script and values read in +from files are expected to be in the *user_units* system.) -The selected IM can be either a :ref:`KIM PM or a KIM SM `. -For a KIM SM, the *kim_init* command verifies that the SM is designed -to work with LAMMPS (and not another simulation code). -In addition, the LAMMPS version used for defining -the SM and the LAMMPS version being currently run are -printed to help diagnose any incompatible changes to input script or -command syntax between the two LAMMPS versions. +The selected IM can be either a :ref:`KIM PM or a KIM SM `. For a KIM +SM, the *kim init* command verifies that the SM is designed to work with LAMMPS +(and not another simulation code). In addition, the LAMMPS version used for +defining the SM and the LAMMPS version being currently run are printed to help +diagnose any incompatible changes to input script or command syntax between the +two LAMMPS versions. -Based on the selected model *kim_init* may modify the -:doc:`atom_style `. -Some SMs have requirements for this setting. If this is the case, then -*atom_style* will be set to the required style. Otherwise, the value is left -unchanged (which in the absence of an *atom_style* command in the input script -is the :doc:`default atom_style value `). +Based on the selected model *kim init* may modify the +:doc:`atom_style `. Some SMs have requirements for this setting. +If this is the case, then *atom_style* will be set to the required style. +Otherwise, the value is left unchanged (which in the absence of an *atom_style* +command in the input script is the +:doc:`default atom_style value `). -Regarding units, the *kim_init* command behaves in different ways depending -on whether or not *unit conversion mode* is activated as indicated by the -optional *unitarg* argument. -If unit conversion mode is **not** active, then *user_units* must -either match the required units of the IM or the IM must be able -to adjust its units to match. (The latter is only possible with some KIM PMs; -SMs can never adjust their units.) If a match is possible, the LAMMPS -:doc:`units ` command is called to set the units to -*user_units*\ . If the match fails, the simulation is terminated with -an error. +Regarding units, the *kim init* behaves in different ways depending on whether +or not *unit conversion mode* is activated as indicated by the optional +*unitarg* argument. +If unit conversion mode is **not** active, then *user_units* must either match +the required units of the IM or the IM must be able to adjust its units to +match. (The latter is only possible with some KIM PMs; SMs can never adjust +their units.) If a match is possible, the LAMMPS :doc:`units ` command is +called to set the units to *user_units*\ . If the match fails, the simulation is +terminated with an error. -Here is an example of a LAMMPS script to compute the cohesive energy -of a face-centered cubic (fcc) lattice for the Ercolessi and Adams (1994) -potential for Al: +Here is an example of a LAMMPS script to compute the cohesive energy of a +face-centered cubic (fcc) lattice for the MEAM potential by Pascuet and +Fernandez (2015) for Al. .. code-block:: LAMMPS - kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal - boundary p p p - lattice fcc 4.032 - region simbox block 0 1 0 1 0 1 units lattice - create_box 1 simbox - create_atoms 1 box - mass 1 26.981539 - kim_interactions Al - run 0 - variable Ec equal (pe/count(all))/${_u_energy} - print "Cohesive Energy = ${EcJ} eV" + kim init Sim_LAMMPS_MEAM_PascuetFernandez_2015_Al__SM_811588957187_000 metal + boundary p p p + lattice fcc 4.049 + region simbox block 0 1 0 1 0 1 units lattice + create_box 1 simbox + create_atoms 1 box + mass 1 26.981539 + kim interactions Al + run 0 + variable Ec equal (pe/count(all)) + print "Cohesive Energy = ${Ec} eV" -The above script will end with an error in the *kim_init* line if the -IM is changed to another potential for Al that does not work with *metal* -units. To address this *kim_init* offers the *unit_conversion_mode* -as shown below. -If unit conversion mode *is* active, then *kim_init* calls the LAMMPS -:doc:`units ` command to set the units to the IM's required or -preferred units. Conversion factors between the IM's units and the *user_units* -are defined for all :doc:`physical quantities ` (mass, distance, etc.). +The above script will end with an error in the *kim init* line if the IM is +changed to another potential for Al that does not work with *metal* units. To +address this, *kim init* offers the *unit_conversion_mode* as shown below. + +If unit conversion mode *is* active, then *kim init* calls the LAMMPS +:doc:`units ` command to set the units to the IM's required or preferred +units. Conversion factors between the IM's units and the *user_units* are +defined for all :doc:`physical quantities ` (mass, distance, etc.). (Note that converting to or from the "lj" unit style is not supported.) -These factors are stored as :doc:`internal style variables ` with -the following standard names: +These factors are stored as :doc:`internal style variables ` with the +following standard names: .. parsed-literal:: @@ -297,127 +362,125 @@ If desired, the input script can be designed to work with these conversion factors so that the script will work without change with any OpenKIM IM. (This approach is used in the `OpenKIM Testing Framework `_.) -For example, the script given above for the cohesive energy of fcc Al -can be rewritten to work with any IM regardless of units. The following -script constructs an fcc lattice with a lattice parameter defined in -meters, computes the total energy, and prints the cohesive energy in -Joules regardless of the units of the IM. + +For example, the script given above for the cohesive energy of fcc Al can be +rewritten to work with any IM regardless of units. The following script +constructs an fcc lattice with a lattice parameter defined in meters, computes +the total energy, and prints the cohesive energy in Joules regardless of the +units of the IM. .. code-block:: LAMMPS - kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 si unit_conversion_mode - boundary p p p - lattice fcc 4.032e-10*${_u_distance} - region simbox block 0 1 0 1 0 1 units lattice - create_box 1 simbox - create_atoms 1 box - mass 1 4.480134e-26*${_u_mass} - kim_interactions Al - run 0 - variable Ec_in_J equal (pe/count(all))/${_u_energy} - print "Cohesive Energy = ${Ec_in_J} J" + kim init Sim_LAMMPS_MEAM_PascuetFernandez_2015_Al__SM_811588957187_000 si unit_conversion_mode + boundary p p p + lattice fcc $(4.049e-10*v__u_distance) + region simbox block 0 1 0 1 0 1 units lattice + create_box 1 simbox + create_atoms 1 box + mass 1 $(4.480134e-26*v__u_mass) + kim interactions Al + neighbor $(0.001e-10*v__u_distance) bin + run 0 + variable Ec_in_J equal (pe/count(all))/v__u_energy + print "Cohesive Energy = ${Ec_in_J} J" -Note the multiplication by ${_u_distance} and ${_u_mass} to convert -from SI units (specified in the *kim_init* command) to whatever units the -IM uses (metal in this case), and the division by ${_u_energy} -to convert from the IM's energy units to SI units (Joule). This script -will work correctly for any IM for Al (KIM PM or SM) selected by the -*kim_init* command. +Note the multiplication by `v__u_distance` and `v__u_mass` to convert from SI +units (specified in the *kim init* command) to whatever units the IM uses (metal +in this case), and the division by `v__u_energy` to convert from the IM's energy +units to SI units (Joule). This script will work correctly for any IM for Al +(KIM PM or SM) selected by the *kim init* command. Care must be taken to apply unit conversion to dimensional variables read in -from a file. For example, if a configuration of atoms is read in from a -dump file using the :doc:`read_dump ` command, the following can -be done to convert the box and all atomic positions to the correct units: +from a file. For example, if a configuration of atoms is read in from a dump +file using the :doc:`read_dump ` command, the following can be done +to convert the box and all atomic positions to the correct units: + .. code-block:: LAMMPS - variable xyfinal equal xy*${_u_distance} - variable xzfinal equal xz*${_u_distance} - variable yzfinal equal yz*${_u_distance} change_box all x scale ${_u_distance} & - y scale ${_u_distance} & - z scale ${_u_distance} & - xy final ${xyfinal} & - xz final ${xzfinal} & - yz final ${yzfinal} & - remap + y scale ${_u_distance} & + z scale ${_u_distance} & + xy final $(xy*v__u_distance) & + xz final $(xz*v__u_distance) & + yz final $(yz*v__u_distance) & + remap .. note:: - Unit conversion will only work if the conversion factors are placed in - all appropriate places in the input script. It is up to the user to do this + Unit conversion will only work if the conversion factors are placed in all + appropriate places in the input script. It is up to the user to do this correctly. -.. _kim_interactions command: +.. _interactions: -OpenKIM IM Execution (*kim_interactions*) +OpenKIM IM Execution (*kim interactions*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The second and final step in using an OpenKIM IM is to execute the -*kim_interactions* command. This command must be preceded by a *kim_init* +*kim interactions* command. This command must be preceded by a *kim init* command and a command that defines the number of atom types *N* (such as :doc:`create_box `). -The *kim_interactions* command has one argument *typeargs*\ . This argument +The *kim interactions* command has one argument *typeargs*\ . This argument contains either a list of *N* chemical species, which defines a mapping between -atom types in LAMMPS to the available species in the OpenKIM IM, or the -keyword *fixed_types* for models that have a preset fixed mapping (i.e. -the mapping between LAMMPS atom types and chemical species is defined by -the model and cannot be changed). In the latter case, the user must consult -the model documentation to see how many atom types there are and how they -map to the chemical species. +atom types in LAMMPS to the available species in the OpenKIM IM, or the keyword +*fixed_types* for models that have a preset fixed mapping (i.e. the mapping +between LAMMPS atom types and chemical species is defined by the model and +cannot be changed). In the latter case, the user must consult the model +documentation to see how many atom types there are and how they map to the +chemical species. -For example, consider an OpenKIM IM that supports Si and C species. -If the LAMMPS simulation has four atom types, where the first three are Si, -and the fourth is C, the following *kim_interactions* command would be used: +For example, consider an OpenKIM IM that supports Si and C species. If the +LAMMPS simulation has four atom types, where the first three are Si, and the +fourth is C, the following *kim interactions* command would be used: .. code-block:: LAMMPS - kim_interactions Si Si Si C + kim interactions Si Si Si C Alternatively, for a model with a fixed mapping the command would be: .. code-block:: LAMMPS - kim_interactions fixed_types + kim interactions fixed_types -The *kim_interactions* command performs all the necessary steps to set up -the OpenKIM IM selected in the *kim_init* command. The specific actions depend -on whether the IM is a KIM PM or a KIM SM. For a KIM PM, -a :doc:`pair_style kim ` command is executed followed by -the appropriate *pair_coeff* command. For example, for the -Ercolessi and Adams (1994) KIM PM for Al set by the following commands: +The *kim interactions* command performs all the necessary steps to set up the +OpenKIM IM selected in the *kim_init* command. The specific actions depend on +whether the IM is a KIM PM or a KIM SM. For a KIM PM, a +:doc:`pair_style kim ` command is executed followed by the appropriate +*pair_coeff* command. For example, for the Ercolessi and Adams (1994) KIM PM for +Al set by the following commands: .. code-block:: LAMMPS - kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal + kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal ... ... box specification lines skipped ... - kim_interactions Al + kim interactions Al -the *kim_interactions* command executes the following LAMMPS input commands: +the *kim interactions* command executes the following LAMMPS input commands: .. code-block:: LAMMPS pair_style kim EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 pair_coeff * * Al -For a KIM SM, the generated input commands may be more complex -and require that LAMMPS is built with the required packages included -for the type of potential being used. The set of commands to be executed -is defined in the SM specification file, which is part of the SM package. -For example, for the Strachan et al. (2003) ReaxFF SM -set by the following commands: +For a KIM SM, the generated input commands may be more complex and require that +LAMMPS is built with the required packages included for the type of potential +being used. The set of commands to be executed is defined in the SM +specification file, which is part of the SM package. For example, for the +Strachan et al. (2003) ReaxFF SM set by the following commands: .. code-block:: LAMMPS - kim_init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 real + kim init Sim_LAMMPS_ReaxFF_StrachanVanDuinChakraborty_2003_CHNO__SM_107643900657_000 real ... ... box specification lines skipped ... - kim_interactions C H N O + kim interactions C H N O -the *kim_interactions* command executes the following LAMMPS input commands: +the *kim interactions* command executes the following LAMMPS input commands: .. code-block:: LAMMPS @@ -427,325 +490,354 @@ the *kim_interactions* command executes the following LAMMPS input commands: .. note:: - The files *lmp_control*, *ffield.reax.rdx* and *param.qeq* - are specific to the Strachan et al. (2003) ReaxFF parameterization - and are archived as part of the SM package in OpenKIM. + The files *lmp_control*, *ffield.reax.rdx* and *param.qeq* are specific to + the Strachan et al. (2003) ReaxFF parameterization and are archived as part + of the SM package in OpenKIM. .. note:: - Parameters like cutoff radii and charge tolerances, - which have an effect on IM predictions, are also included in the - SM definition ensuring reproducibility. + Parameters like cutoff radii and charge tolerances, which have an effect on + IM predictions, are also included in the SM definition ensuring + reproducibility. .. note:: - When using *kim_init* and *kim_interactions* to select - and set up an OpenKIM IM, other LAMMPS commands - for the same functions (such as pair_style, pair_coeff, bond_style, - bond_coeff, fixes related to charge equilibration, etc.) should normally - not appear in the input script. + When using *kim init* and *kim interactions* to select and set up an OpenKIM + IM, other LAMMPS commands for the same functions (such as pair_style, + pair_coeff, bond_style, bond_coeff, fixes related to charge equilibration, + etc.) should normally not appear in the input script. -.. _kim_query command: +.. note:: -Using OpenKIM Web Queries in LAMMPS (*kim_query*) + Changing a periodic boundary to a non-periodic one, or in general using the + :doc:`change_box ` command after the interactions are set via + *kim interactions* or *pair_coeff* commands might affect some of the + settings. For example, SM models containing Coulombic terms in the + interactions require different settings if a periodic boundary changes to a + non-periodic one. In these cases, *kim interactions* must be called again + after the *change_box* command to provide the correct settings. + +.. _query: + +Using OpenKIM Web Queries in LAMMPS (*kim query*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The *kim_query* command performs a web query to retrieve the predictions -of an IM set by *kim_init* for material properties archived in +The *kim query* command performs a web query to retrieve the predictions of an +IM set by *kim init* for material properties archived in `OpenKIM `_. -.. note:: - - The *kim_query* command must be preceded by a *kim_init* command. - -The syntax for the *kim_query* command is as follows: - +The syntax for the *kim query* command is as follows: .. code-block:: LAMMPS - kim_query variable formatarg query_function queryargs + kim query variable formatarg query_function queryargs The result of the query is stored in one or more -:doc:`string style variables ` as determined by the -optional *formatarg* argument :ref:`documented above `. -For the "list" setting of *formatarg* (or if *formatarg* is not -specified), the result is returned as a space-separated list of -values in *variable*\ . -The *formatarg* keyword "split" separates the result values into -individual variables of the form *prefix_I*, where *prefix* is set to the -*kim_query* *variable* argument and *I* ranges from 1 to the number of -returned values. The number and order of the returned values is determined -by the type of query performed. (Note that the "explicit" setting of -*formatarg* is not supported by *kim_query*\ .) +:doc:`string style variables ` as determined by the optional +*formatarg* argument :ref:`documented above `. For the "list" +setting of *formatarg* (or if *formatarg* is not specified), the result is +returned as a space-separated list of values in *variable*\ . The *formatarg* +keyword "split" separates the result values into individual variables of the +form *prefix_I*, where *prefix* is set to the *kim query* *variable* argument +and *I* ranges from 1 to the number of returned values. The number and order of +the returned values is determined by the type of query performed. The +*formatarg* keyword "index" returns a :doc:`variable style index ` +that can be incremented via the :doc:`next ` command. This enables the +construction of simple loops over the returned values by the type of query +performed. (Note that the "explicit" setting of *formatarg* is not supported by +*kim query*\ .) .. note:: - *kim_query* only supports queries that return a single result or - an array of values. More complex queries that return a JSON structure - are not currently supported. An attempt to use *kim_query* in such - cases will generate an error. + *kim query* only supports queries that return a single result or an array of + values. More complex queries that return a JSON structure are not currently + supported. An attempt to use *kim query* in such cases will generate an + error. -The second required argument *query_function* is the name of the -query function to be called (e.g. *get_lattice_constant_cubic*\ ). -All following :doc:`arguments ` are parameters handed over to -the web query in the format *keyword=value*\ , where *value* is always -an array of one or more comma-separated items in brackets. -The list of supported keywords and the type and format of their values -depend on the query function used. The current list of query functions -is available on the OpenKIM webpage at +The second required argument *query_function* is the name of the query function +to be called (e.g. *get_lattice_constant_cubic*\ ). All following +:doc:`arguments ` are parameters handed over to the web query in +the format *keyword=value*\ , where *value* is always an array of one or more +comma-separated items in brackets. The list of supported keywords and the type +and format of their values depend on the query function used. The current list +of query functions is available on the OpenKIM webpage at `https://openkim.org/doc/usage/kim-query `_. .. note:: - All query functions require the *model* keyword, which identifies - the IM whose predictions are being queried. This keyword is automatically - generated by *kim_query* based on the IM set in *kim_init* and must not - be specified as an argument to *kim_query*\ . + All query functions, except *get_available_models* function, require the + *model* keyword, which identifies the IM whose predictions are being queried. + *kim query* automatically generates the *model* keyword based on the IM set + in by *kim init*, and it can be overwritten if specified as an argument to + the *kim query*\ . Where *Kim init* is not specified, the *model* keyword + must be provided as an argument to the *kim query*\ . .. note:: - Each *query_function* is associated with a default method (implemented - as a `KIM Test `_) - used to compute this property. In cases where there are multiple - methods in OpenKIM for computing a property, a *method* keyword can - be provided to select the method of choice. See the - `query documentation `_ - to see which methods are available for a given *query_function*\ . + Each *query_function* is associated with a default method (implemented as a + `KIM Test `_) used to compute + this property. In cases where there are multiple methods in OpenKIM for + computing a property, a *method* keyword can be provided to select the method + of choice. See the + `query documentation `_ to see which + methods are available for a given *query_function*\ . -*kim_query* Usage Examples and Further Clarifications +*kim query* Usage Examples and Further Clarifications ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -The data obtained by *kim_query* commands can be used as part of the setup -or analysis phases of LAMMPS simulations. Some examples are given below. +The data obtained by *kim query* commands can be used as part of the setup or +analysis phases of LAMMPS simulations. Some examples are given below. **Define an equilibrium fcc crystal** .. code-block:: LAMMPS - kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal - boundary p p p - kim_query a0 get_lattice_constant_cubic crystal=["fcc"] species=["Al"] units=["angstrom"] - lattice fcc ${a0} + kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal + boundary p p p + kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom] + lattice fcc ${a0} ... -The *kim_query* command retrieves from `OpenKIM `_ -the equilibrium lattice constant predicted by the Ercolessi and Adams (1994) -potential for the fcc structure and places it in -variable *a0*\ . This variable is then used on the next line to set up the -crystal. By using *kim_query*, the user is saved the trouble and possible -error of tracking this value down, or of having to perform an energy -minimization to find the equilibrium lattice constant. +.. code-block:: LAMMPS + + units metal + kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom] model=[EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005] + lattice fcc ${a0} + ... + +The *kim query* command retrieves from `OpenKIM `_ the +equilibrium lattice constant predicted by the Ercolessi and Adams (1994) +potential for the fcc structure and places it in variable *a0*\ . This variable +is then used on the next line to set up the crystal. By using *kim query*, the +user is saved the trouble and possible error of tracking this value down, or of +having to perform an energy minimization to find the equilibrium lattice +constant. .. note:: - In *unit_conversion_mode* the results obtained from a - *kim_query* would need to be converted to the appropriate units system. - For example, in the above script, the lattice command would need to be - changed to: "lattice fcc ${a0}*${_u_distance}". + In *unit_conversion_mode* the results obtained from a *kim query* would need + to be converted to the appropriate units system. For example, in the above + script, the lattice command would need to be changed to: + "lattice fcc $(v_a0*v__u_distance)". **Define an equilibrium hcp crystal** .. code-block:: LAMMPS - kim_init EAM_Dynamo_Mendelev_2007_Zr__MO_848899341753_000 metal - boundary p p p - kim_query latconst split get_lattice_constant_hexagonal crystal=["hcp"] species=["Zr"] units=["angstrom"] - variable a0 equal latconst_1 - variable c0 equal latconst_2 - variable c_to_a equal ${c0}/${a0} - lattice custom ${a0} a1 0.5 -0.866025 0 a2 0.5 0.866025 0 a3 0 0 ${c_to_a} & - basis 0.333333 0.666666 0.25 basis 0.666666 0.333333 0.75 + kim init EAM_Dynamo_MendelevAckland_2007v3_Zr__MO_004835508849_000 metal + boundary p p p + kim query latconst split get_lattice_constant_hexagonal crystal=[hcp] species=[Zr] units=[angstrom] + lattice custom ${latconst_1} a1 0.5 -0.866025 0 a2 0.5 0.866025 0 a3 0 0 $(latconst_2/latconst_1) & + basis 0.333333 0.666666 0.25 basis 0.666666 0.333333 0.75 ... -In this case the *kim_query* returns two arguments (since the hexagonal -close packed (hcp) structure has two independent lattice constants). -The *formatarg* keyword "split" places the two values into -the variables *latconst_1* and *latconst_2*\ . (These variables are -created if they do not already exist.) For convenience the variables -*a0* and *c0* are created in order to make the remainder of the -input script more readable. +In this case the *kim query* returns two arguments (since the hexagonal close +packed (hcp) structure has two independent lattice constants). The *formatarg* +keyword "split" places the two values into the variables *latconst_1* and +*latconst_2*\ . (These variables are created if they do not already exist.) **Define a crystal at finite temperature accounting for thermal expansion** .. code-block:: LAMMPS - kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal - boundary p p p - kim_query a0 get_lattice_constant_cubic crystal=["fcc"] species=["Al"] units=["angstrom"] - kim_query alpha get_linear_thermal_expansion_coefficient_cubic crystal=["fcc"] species=["Al"] units=["1/K"] temperature=[293.15] temperature_units=["K"] - variable DeltaT equal 300 - lattice fcc ${a0}*${alpha}*${DeltaT} + kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal + boundary p p p + kim query a0 get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom] + kim query alpha get_linear_thermal_expansion_coefficient_cubic crystal=[fcc] species=[Al] units=[1/K] temperature=[293.15] temperature_units=[K] + variable DeltaT equal 300 + lattice fcc $(v_a0*v_alpha*v_DeltaT) ... -As in the previous example, the equilibrium lattice constant is obtained -for the Ercolessi and Adams (1994) potential. However, in this case the -crystal is scaled to the appropriate lattice constant at room temperature -(293.15 K) by using the linear thermal expansion constant predicted by the -potential. +As in the previous example, the equilibrium lattice constant is obtained for the +Ercolessi and Adams (1994) potential. However, in this case the crystal is +scaled to the appropriate lattice constant at room temperature (293.15 K) by +using the linear thermal expansion constant predicted by the potential. .. note:: - When passing numerical values as arguments (as in the case - of the temperature in the above example) it is also possible to pass a - tolerance indicating how close to the value is considered a match. - If no tolerance is passed a default value is used. If multiple results - are returned (indicating that the tolerance is too large), *kim_query* - will return an error. See the - `query documentation `_ - to see which numerical arguments and tolerances are available for a - given *query_function*\ . + When passing numerical values as arguments (as in the case of the temperature + in the above example) it is also possible to pass a tolerance indicating how + close to the value is considered a match. If no tolerance is passed a default + value is used. If multiple results are returned (indicating that the + tolerance is too large), *kim query* will return an error. See the + `query documentation `_ to see which + numerical arguments and tolerances are available for a given + *query_function*\ . **Compute defect formation energy** .. code-block:: LAMMPS - kim_init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal + kim init EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 metal ... ... Build fcc crystal containing some defect and compute the total energy ... which is stored in the variable *Etot* ... - kim_query Ec get_cohesive_energy_cubic crystal=["fcc"] species=["Al"] units=["eV"] - variable Eform equal ${Etot} - count(all)*${Ec} + kim query Ec get_cohesive_energy_cubic crystal=[fcc] species=[Al] units=[eV] + variable Eform equal ${Etot} - count(all)*${Ec} ... -The defect formation energy *Eform* is computed by subtracting from *Etot* the -ideal fcc cohesive energy of the atoms in the system obtained from +The defect formation energy *Eform* is computed by subtracting the ideal fcc +cohesive energy of the atoms in the system from *Etot*\ . The ideal fcc +cohesive energy of the atoms is obtained from `OpenKIM `_ for the Ercolessi and Adams (1994) potential. +**Retrieve equilibrium fcc crystal of all EAM potentials that support a specific species** + +.. code-block:: LAMMPS + + kim query model index get_available_models species=[Al] potential_type=[eam] + label model_loop + kim query latconst get_lattice_constant_cubic crystal=[fcc] species=[Al] units=[angstrom] model=[${model}] + print "FCC lattice constant (${model} potential) = ${latconst}" + ... + ... do something with current value of latconst + ... + next model + jump SELF model_loop + +In this example, the *index* mode of *formatarg* is used. The first *kim query* +returns the list of all available EAM potentials that support the *Al* species +and archived in `OpenKIM `_. The result of the query +operation is stored in the LAMMPS variable *model* as an index *variable*\ . +This variable is used later to access the values one at a time within a loop as +shown in the example. The second *kim query* command retrieves from +`OpenKIM `_ the equilibrium lattice constant predicted by +each potential for the fcc structure and places it in variable *latconst*\ . + .. note:: - *kim_query* commands return results archived in - `OpenKIM `_. These results are obtained - using programs for computing material properties - (KIM Tests and KIM Test Drivers) that were contributed to OpenKIM. - In order to give credit to Test developers, the number of times results - from these programs are queried is tracked. No other information about - the nature of the query or its source is recorded. + *kim query* commands return results archived in + `OpenKIM `_. These results are obtained using programs + for computing material properties (KIM Tests and KIM Test Drivers) that were + contributed to OpenKIM. In order to give credit to Test developers, the + number of times results from these programs are queried is tracked. No other + information about the nature of the query or its source is recorded. -.. _kim_param command: -Accessing KIM Model Parameters from LAMMPS (*kim_param*) +.. _param: + +Accessing KIM Model Parameters from LAMMPS (*kim param*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -All IMs are functional forms containing a set of -parameters. The values of these parameters are typically -selected to best reproduce a training set of quantum mechanical -calculations or available experimental data. For example, a -Lennard-Jones potential intended to model argon might have the values of -its two parameters, epsilon and sigma, fit to the -dimer dissociation energy or thermodynamic properties at a critical point -of the phase diagram. +All IMs are functional forms containing a set of parameters. These parameters' +values are typically selected to best reproduce a training set of quantum +mechanical calculations or available experimental data. For example, a +Lennard-Jones potential intended to model argon might have the values of its two +parameters, epsilon, and sigma, fit to the dimer dissociation energy or +thermodynamic properties at a critical point of the phase diagram. -Normally a user employing an IM should not modify its parameters since, -as noted above, these are selected to reproduce material properties. -However, there are cases where accessing and modifying IM parameters -is desired, such as for assessing uncertainty, fitting an IM, -or working with an ensemble of IMs. As explained :ref:`above `, -IMs archived in OpenKIM are either Portable Models (PMs) or -Simulator Models (SMs). KIM PMs are complete independent implementations -of an IM, whereas KIM SMs are wrappers to an IM implemented within LAMMPS. -Two different mechanisms are provided for accessing IM parameters in these -two cases: +Normally a user employing an IM should not modify its parameters since, as noted +above, these are selected to reproduce material properties. However, there are +cases where accessing and modifying IM parameters is desired, such as for +assessing uncertainty, fitting an IM, or working with an ensemble of IMs. As +explained :ref:`above `, IMs archived in OpenKIM are either Portable +Models (PMs) or Simulator Models (SMs). KIM PMs are complete independent +implementations of an IM, whereas KIM SMs are wrappers to an IM implemented +within LAMMPS. Two different mechanisms are provided for accessing IM parameters +in these two cases: -* For a KIM PM, the *kim_param* command can be used to *get* and *set* the values of the PM's parameters as explained below. -* For a KIM SM, the user should consult the documentation page for the specific IM and follow instructions there for how to modify its parameters (if possible). +* For a KIM PM, the *kim param* command can be used to *get* and *set* the + values of the PM's parameters as explained below. +* For a KIM SM, the user should consult the documentation page for the specific + IM and follow instructions there for how to modify its parameters (if + possible). -The *kim_param get* and *kim_param set* commands provide an interface -to access and change the parameters of a KIM PM that "publishes" its -parameters and makes them publicly available (see the +The *kim param get* and *kim param set* commands provide an interface to access +and change the parameters of a KIM PM that "publishes" its parameters and makes +them publicly available (see the `KIM API documentation `_ for details). .. note:: - The *kim_param get/set* commands must be preceded by *kim_init*\ . - The *kim_param set* command must additionally be preceded by a - *kim_interactions* command (or alternatively by a *pair_style kim* - and *pair_coeff* commands). The *kim_param set* command may be used wherever a *pair_coeff* command may occur. + The *kim param get/set* commands must be preceded by *kim init*\ . + The *kim param set* command must additionally be preceded by a + *kim_interactions* command (or alternatively by a *pair_style kim* and + *pair_coeff* commands). The *kim param set* command may be used wherever a + *pair_coeff* command may occur. -The syntax for the *kim_param* command is as follows: +The syntax for the *kim param* command is as follows: .. code-block:: LAMMPS - kim_param get param_name index_range variable formatarg - kim_param set param_name index_range values + kim param get param_name index_range variable formatarg + kim param set param_name index_range values -Here, *param_name* is the name of a KIM PM parameter (which is published -by the PM and available for access). The specific string used to identify -a parameter is defined by the PM. For example, for the +Here, *param_name* is the name of a KIM PM parameter (which is published by the +PM and available for access). The specific string used to identify a parameter +is defined by the PM. For example, for the `Stillinger--Weber (SW) potential in OpenKIM `_, the parameter names are *A, B, p, q, sigma, gamma, cutoff, lambda, costheta0*\ . .. note:: The list of all the parameters that a PM exposes for access/mutation are - automatically written to the lammps log file when *kim_init* is called. + automatically written to the lammps log file when *kim init* is called. -Each published parameter of a KIM PM takes the form of an array of -numerical values. The array can contain one element for a single-valued -parameter, or a set of values. For example, the +Each published parameter of a KIM PM takes the form of an array of numerical +values. The array can contain one element for a single-valued parameter, or a +set of values. For example, the `multispecies SW potential for the Zn-Cd-Hg-S-Se-Te system `_ has the same parameter names as the `single-species SW potential `_, but each parameter array contains 21 entries that correspond to the parameter values used for each pairwise combination of the model's six supported species -(this model does not have parameters specific to individual ternary -combinations of its supported species). +(this model does not have parameters specific to individual ternary combinations +of its supported species). -The *index_range* argument may either be an integer referring to -a specific element within the array associated with the parameter -specified by *param_name*, or a pair of integers separated by a colon -that refer to a slice of this array. In both cases, one-based indexing is -used to refer to the entries of the array. +The *index_range* argument may either be an integer referring to a specific +element within the array associated with the parameter specified by +*param_name*, or a pair of integers separated by a colon that refer to a slice +of this array. In both cases, one-based indexing is used to refer to the +entries of the array. The result of a *get* operation for a specific *index_range* is stored in -one or more :doc:`LAMMPS string style variables ` as determined -by the optional *formatarg* argument :ref:`documented above. ` -If not specified, the default for *formatarg* is "explicit" for the -*kim_param* command. +one or more :doc:`LAMMPS string style variables ` as determined by the +optional *formatarg* argument :ref:`documented above. ` If +not specified, the default for *formatarg* is "explicit" for the *kim param* +command. -For the case where the result is an array with multiple values -(i.e. *index_range* contains a range), the optional "split" or "explicit" -*formatarg* keywords can be used to separate the results into multiple -variables; see the examples below. -Multiple parameters can be retrieved with a single call to *kim_param get* -by repeating the argument list following *get*\ . +For the case where the result is an array with multiple values (i.e. +*index_range* contains a range), the optional "split" or "explicit" *formatarg* +keywords can be used to separate the results into multiple variables; see the +examples below. Multiple parameters can be retrieved with a single call to +*kim param get* by repeating the argument list following *get*\ . -For a *set* operation, the *values* argument contains the new value(s) -for the element(s) of the parameter specified by *index_range*\ . For the case -where multiple values are being set, *values* contains a set of values -separated by spaces. Multiple parameters can be set with a single call to -*kim_param set* by repeating the argument list following *set*\ . +For a *set* operation, the *values* argument contains the new value(s) for the +element(s) of the parameter specified by *index_range*\ . For the case where +multiple values are being set, *values* contains a set of values separated by +spaces. Multiple parameters can be set with a single call to *kim param set* by +repeating the argument list following *set*\ . -*kim_param* Usage Examples and Further Clarifications +*kim param* Usage Examples and Further Clarifications ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Examples of getting and setting KIM PM parameters with further -clarifications are provided below. +Examples of getting and setting KIM PM parameters with further clarifications +are provided below. **Getting a scalar parameter** .. code-block:: LAMMPS - kim_init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal + kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal ... - kim_param get A 1 VARA + kim param get A 1 VARA -In this case, the value of the SW *A* parameter is retrieved and placed -in the LAMMPS variable *VARA*\ . The variable *VARA* can be used -in the remainder of the input script in the same manner as any other -LAMMPS variable. +In this case, the value of the SW *A* parameter is retrieved and placed in the +LAMMPS variable *VARA*\ . The variable *VARA* can be used in the remainder of +the input script in the same manner as any other LAMMPS variable. **Getting multiple scalar parameters with a single call** .. code-block:: LAMMPS - kim_init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal + kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal ... - kim_param get A 1 VARA B 1 VARB + kim param get A 1 VARA B 1 VARB -This retrieves the *A* and *B* parameters of the SW potential and stores -them in the LAMMPS variables *VARA* and *VARB*\ . +In this example, it is shown how to retrieve the *A* and *B* parameters of the +SW potential and store them in the LAMMPS variables *VARA* and *VARB*\ . **Getting a range of values from a parameter** @@ -754,9 +846,9 @@ determined by the *formatarg* argument. .. code-block:: LAMMPS - kim_init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal + kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal ... - kim_param get lambda 7:9 LAM_TeTe LAM_TeZn LAM_TeSe + kim param get lambda 7:9 LAM_TeTe LAM_TeZn LAM_TeSe In this case, *formatarg* is not specified and therefore the default "explicit" mode is used. (The behavior would be the same if the word @@ -766,166 +858,164 @@ lambda retrieved by the *get* operation are placed in the LAMMPS variables .. note:: - In the above example, elements 7--9 of the lambda parameter correspond - to Te-Te, Te-Zm and Te-Se interactions. This can be determined by visiting - the `model page for the specified potential `_ - and looking at its parameter file linked to at the bottom of the page - (file with .param ending) and consulting the README documentation - provided with the driver for the PM being used. A link to the driver - is provided at the top of the model page. + In the above example, elements 7--9 of the lambda parameter correspond to + Te-Te, Te-Zm and Te-Se interactions. This can be determined by visiting the + `model page for the specified potential `_ + and looking at its parameter file linked to at the bottom of the page (file + with .param ending) and consulting the README documentation provided with the + driver for the PM being used. A link to the driver is provided at the top of + the model page. .. code-block:: LAMMPS - kim_init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal + kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal ... - kim_param get lambda 15:17 LAMS list - variable LAM_VALUE index ${LAMS} - label loop_on_lambda + kim param get lambda 15:17 LAMS list + variable LAM_VALUE index ${LAMS} + label loop_on_lambda ... - ... do something with current value of lambda + ... do something with the current value of lambda ... - next LAM_VALUE - jump SELF loop_on_lambda + next LAM_VALUE + jump SELF loop_on_lambda -In this case, the "list" mode of *formatarg* is used. -The result of the *get* operation is stored in the LAMMPS variable -*LAMS* as a string containing the three retrieved values separated -by spaces, e.g "1.0 2.0 3.0". This can be used in LAMMPS with an -*index* variable to access the values one at a time within a loop -as shown in the example. At each iteration of the loop *LAM_VALUE* -contains the current value of lambda. +In this case, the "list" mode of *formatarg* is used. The result of the *get* +operation is stored in the LAMMPS variable *LAMS* as a string containing the +three retrieved values separated by spaces, e.g "1.0 2.0 3.0". This can be used +in LAMMPS with an *index* variable to access the values one at a time within a +loop as shown in the example. At each iteration of the loop *LAM_VALUE* contains +the current value of lambda. .. code-block:: LAMMPS - kim_init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal + kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal ... - kim_param get lambda 15:17 LAM split + kim param get lambda 15:17 LAM split -In this case, the "split" mode of *formatarg* is used. -The three values retrieved by the *get* operation are stored in -the three LAMMPS variables *LAM_15*, *LAM_16* and *LAM_17*\ . -The provided name "LAM" is used as prefix and the location in -the lambda array is appended to create the variable names. +In this case, the "split" mode of *formatarg* is used. The three values +retrieved by the *get* operation are stored in the three LAMMPS variables +*LAM_15*, *LAM_16* and *LAM_17*\ . The provided name "LAM" is used as prefix and +the location in the lambda array is appended to create the variable names. **Setting a scalar parameter** .. code-block:: LAMMPS - kim_init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal + kim init SW_StillingerWeber_1985_Si__MO_405512056662_005 metal ... - kim_interactions Si - kim_param set gamma 1 2.6 + kim interactions Si + kim param set gamma 1 2.6 Here, the SW potential's gamma parameter is set to 2.6. Note that the *get* -and *set* commands work together, so that a *get* following a *set* -operation will return the new value that was set. For example: +and *set* commands work together, so that a *get* following a *set* operation +will return the new value that was set. For example, .. code-block:: LAMMPS ... - kim_interactions Si - kim_param get gamma 1 ORIG_GAMMA - kim_param set gamma 1 2.6 - kim_param get gamma 1 NEW_GAMMA + kim interactions Si + kim param get gamma 1 ORIG_GAMMA + kim param set gamma 1 2.6 + kim param get gamma 1 NEW_GAMMA ... - print "original gamma = ${ORIG_GAMMA}, new gamma = ${NEW_GAMMA}" + print "original gamma = ${ORIG_GAMMA}, new gamma = ${NEW_GAMMA}" -Here, *ORIG_GAMMA* will contain the original gamma value for the SW -potential, while *NEW_GAMMA* will contain the value 2.6. +Here, *ORIG_GAMMA* will contain the original gamma value for the SW potential, +while *NEW_GAMMA* will contain the value 2.6. **Setting multiple scalar parameters with a single call** .. code-block:: LAMMPS - kim_init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal + kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal ... - kim_interactions Cd Te - variable VARG equal 2.6 - variable VARS equal 2.0951 - kim_param set gamma 1 ${VARG} sigma 3 ${VARS} + kim interactions Cd Te + variable VARG equal 2.6 + variable VARS equal 2.0951 + kim param set gamma 1 ${VARG} sigma 3 ${VARS} -In this case, the first element of the *gamma* parameter and -third element of the *sigma* parameter are set to 2.6 and 2.0951, -respectively. This example also shows how LAMMPS variables can -be used when setting parameters. +In this case, the first element of the *gamma* parameter and third element of +the *sigma* parameter are set to 2.6 and 2.0951, respectively. This example +also shows how LAMMPS variables can be used when setting parameters. **Setting a range of values of a parameter** .. code-block:: LAMMPS - kim_init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal + kim init SW_ZhouWardMartin_2013_CdTeZnSeHgS__MO_503261197030_002 metal ... - kim_interactions Cd Te Zn Se Hg S - kim_param set sigma 2:6 2.35214 2.23869 2.04516 2.43269 1.80415 + kim interactions Cd Te Zn Se Hg S + kim param set sigma 2:6 2.35214 2.23869 2.04516 2.43269 1.80415 -In this case, elements 2 through 6 of the parameter *sigma* -are set to the values 2.35214, 2.23869, 2.04516, 2.43269 and 1.80415 in -order. +In this case, elements 2 through 6 of the parameter *sigma* are set to the +values 2.35214, 2.23869, 2.04516, 2.43269 and 1.80415 in order. -.. _kim_property command: +.. _property: -Writing material properties computed in LAMMPS to standard KIM property instance format (*kim_property*) +Writing material properties computed in LAMMPS to standard KIM property instance format (*kim property*) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As explained :ref:`above`, -The OpenKIM system includes a collection of Tests (material property calculation codes), -Models (interatomic potentials), Predictions, and Reference Data (DFT or experiments). -Specifically, a KIM Test is a computation that when coupled with a KIM Model generates -the prediction of that model for a specific material property rigorously defined -by a KIM Property Definition (see the +As explained :ref:`above`, the OpenKIM system includes a +collection of Tests (material property calculation codes), Models (interatomic +potentials), Predictions, and Reference Data (DFT or experiments). Specifically, +a KIM Test is a computation that when coupled with a KIM Model generates the +prediction of that model for a specific material property rigorously defined by +a KIM Property Definition (see the `KIM Properties Framework `__ -for further details). A prediction of a material property for a given model is a specific -numerical realization of a property definition, referred to as a "Property -Instance." The objective of the *kim_property* command is to make it easy to -output material properties in a standardized, machine readable, format that can be easily -ingested by other programs. -Additionally, it aims to make it as easy as possible to convert a LAMMPS script that computes a -material property into a KIM Test that can then be uploaded to `openkim.org `_ +for further details). A prediction of a material property for a given model is a +specific numerical realization of a property definition, referred to as a +"Property Instance." The objective of the *kim property* command is to make it +easy to output material properties in a standardized, machine readable, format +that can be easily ingested by other programs. Additionally, it aims to make it +as easy as possible to convert a LAMMPS script that computes a material property +into a KIM Test that can then be uploaded to +`openkim.org `_ -A developer interested in creating a KIM Test using a LAMMPS script should -first determine whether a property definition that applies to their calculation +A developer interested in creating a KIM Test using a LAMMPS script should first +determine whether a property definition that applies to their calculation already exists in OpenKIM by searching the `properties page `_. If none exists, it is possible to use a locally defined property definition contained in a file until it can be uploaded to the official repository (see below). Once one or more applicable -property definitions have been identified, the *kim_property create*, -*kim_property modify*, *kim_property remove*, and *kim_property destroy*, +property definitions have been identified, the *kim property create*, +*kim property modify*, *kim property remove*, and *kim property destroy*, commands provide an interface to create, set, modify, remove, and destroy -instances of them within a LAMMPS script. Their general syntax is as follows: +instances of them within a LAMMPS script. Their general syntax is as follows, .. code-block:: LAMMPS - kim_property create instance_id property_id - kim_property modify instance_id key key_name key_name_key key_name_value - kim_property remove instance_id key key_name - kim_property destroy instance_id - kim_property dump file + kim property create instance_id property_id + kim property modify instance_id key key_name key_name_key key_name_value + kim property remove instance_id key key_name + kim property destroy instance_id + kim property dump file Here, *instance_id* is a positive integer used to uniquely identify each property instance; (note that the results file can contain multiple property -instances). A property_id is an identifier of a +instances). A *property_id* is an identifier of a `KIM Property Definition `_, which can be (1) a property short name, (2) the full unique ID of the property (including the contributor and date), (3) a file name corresponding to a local -property definition file. Examples of each of these cases are shown below: +property definition file. Examples of each of these cases are shown below, .. code-block:: LAMMPS - kim_property create 1 atomic-mass - kim_property create 2 cohesive-energy-relation-cubic-crystal + kim property create 1 atomic-mass + kim property create 2 cohesive-energy-relation-cubic-crystal .. code-block:: LAMMPS - kim_property create 1 tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass - kim_property create 2 tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal + kim property create 1 tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass + kim property create 2 tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal .. code-block:: LAMMPS - kim_property create 1 new-property.edn - kim_property create 2 /home/mary/marys-kim-properties/dissociation-energy.edn + kim property create 1 new-property.edn + kim property create 2 /home/mary/marys-kim-properties/dissociation-energy.edn -In the last example, "new-property.edn" and "/home/mary/marys-kim-properties/dissociation-energy.edn" are the -names of files that contain user-defined (local) property definitions. +In the last example, "new-property.edn" and +"/home/mary/marys-kim-properties/dissociation-energy.edn" are the names of files +that contain user-defined (local) property definitions. A KIM property instance takes the form of a "map," i.e. a set of key-value pairs akin to Perl's hash, Python's dictionary, or Java's Hashtable. It @@ -944,13 +1034,13 @@ as stipulated in the property definition. Each map assigned to a *key_name* must contain the *key_name_key* "source-value" and an associated *key_name_value* of the appropriate type (as defined in the relevant KIM Property Definition). For keys that are - defined as having physical units, the - "source-unit" *key_name_key* must also be given a string value recognized - by `GNU units `_. + defined as having physical units, the "source-unit" *key_name_key* must also + be given a string value recognized by + `GNU units `_. -Once a *kim_property create* command has been given to instantiate a property +Once a *kim property create* command has been given to instantiate a property instance, maps associated with the property's keys can be edited using the -*kim_property modify* command. In using this command, the special keyword +*kim property modify* command. In using this command, the special keyword "key" should be given, followed by the property key name and the key-value pair in the map associated with the key that is to be set. For example, the `atomic-mass `_ @@ -959,37 +1049,37 @@ An instance of this property could be created like so: .. code-block:: LAMMPS - kim_property create 1 atomic-mass - kim_property modify 1 key species source-value Al - kim_property modify 1 key mass source-value 26.98154 - kim_property modify 1 key mass source-unit amu + kim property create 1 atomic-mass + kim property modify 1 key species source-value Al + kim property modify 1 key mass source-value 26.98154 + kim property modify 1 key mass source-unit amu or, equivalently, .. code-block:: LAMMPS - kim_property create 1 atomic-mass - kim_property modify 1 key species source-value Al & + kim property create 1 atomic-mass + kim property modify 1 key species source-value Al & key mass source-value 26.98154 & source-unit amu -*kim_property* Usage Examples and Further Clarifications +*kim property* Usage Examples and Further Clarifications ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ **Create** .. code-block:: LAMMPS - kim_property create instance_id property_id + kim property create instance_id property_id -The *kim_property create* command takes as input a property instance ID and the +The *kim property create* command takes as input a property instance ID and the property definition name, and creates an initial empty property instance data structure. For example, .. code-block:: LAMMPS - kim_property create 1 atomic-mass - kim_property create 2 cohesive-energy-relation-cubic-crystal + kim property create 1 atomic-mass + kim property create 2 cohesive-energy-relation-cubic-crystal creates an empty property instance of the "atomic-mass" property definition with instance ID 1 and an empty instance of the @@ -1002,32 +1092,32 @@ path of a file containing a valid property definition. For example, .. code-block:: LAMMPS - kim_property create 1 new-property.edn + kim property create 1 new-property.edn where "new-property.edn" refers to a file name containing a new property definition that does not exist in OpenKIM. If the *property_id* given cannot be found in OpenKIM and no file of this name containing a valid property definition can be found, this command will produce -an error with an appropriate message. Calling *kim_property create* with the +an error with an appropriate message. Calling *kim property create* with the same instance ID multiple times will also produce an error. **Modify** .. code-block:: LAMMPS - kim_property modify instance_id key key_name key_name_key key_name_value + kim property modify instance_id key key_name key_name_key key_name_value -The *kim_property modify* command incrementally builds the property instance -by receiving property definition keys along with associated arguments. Each +The *kim property modify* command incrementally builds the property instance +by receiving property definition keys along with associated arguments. Each *key_name* is associated with a map containing one or more key-value pairs (in the form of *key_name_key*-*key_name_value* pairs). For example, .. code-block:: LAMMPS - kim_property modify 1 key species source-value Al - kim_property modify 1 key mass source-value 26.98154 - kim_property modify 1 key mass source-unit amu + kim property modify 1 key species source-value Al + kim property modify 1 key mass source-value 26.98154 + kim property modify 1 key mass source-unit amu where the special keyword "key" is followed by a *key_name* ("species" or "mass" in the above) and one or more key-value pairs. These key-value pairs @@ -1036,7 +1126,7 @@ command line is reached. Thus, the above could equivalently be written as .. code-block:: LAMMPS - kim_property modify 1 key species source-value Al & + kim property modify 1 key species source-value Al & key mass source-value 26.98154 & key mass source-unit amu @@ -1044,19 +1134,18 @@ As an example of modifying multiple key-value pairs belonging to the map of a single property key, the following command modifies the map of the "cohesive-potential-energy" property key to contain the key "source-unit" which is assigned a value of "eV" and the key "digits" which is assigned a value of -5: +5, .. code-block:: LAMMPS - kim_property modify 2 key cohesive-potential-energy source-unit eV digits 5 + kim property modify 2 key cohesive-potential-energy source-unit eV digits 5 .. note:: - The relevant data types of the values in the map are handled - automatically based on the specification of the key in the - KIM Property Definition. In the example above, - this means that the value "eV" will automatically be interpreted as a string - while the value 5 will be interpreted as an integer. + The relevant data types of the values in the map are handled automatically + based on the specification of the key in the KIM Property Definition. In + the example above, this means that the value "eV" will automatically be + interpreted as a string while the value 5 will be interpreted as an integer. The values contained in maps can either be scalars, as in all of the examples above, or arrays depending on which is stipulated in the corresponding Property @@ -1067,7 +1156,7 @@ dimensionality of the array. .. note:: - All array indexing used by *kim_property modify* is one-based, i.e. the + All array indexing used by *kim property modify* is one-based, i.e. the indices are enumerated 1, 2, 3, ... .. note:: @@ -1088,20 +1177,20 @@ of the "species" property key, we can do so by issuing: .. code-block:: LAMMPS - kim_property modify 2 key species source-value 1 Al - kim_property modify 2 key species source-value 2 Al - kim_property modify 2 key species source-value 3 Al - kim_property modify 2 key species source-value 4 Al + kim property modify 2 key species source-value 1 Al + kim property modify 2 key species source-value 2 Al + kim property modify 2 key species source-value 3 Al + kim property modify 2 key species source-value 4 Al .. note:: No declaration of the number of elements in this array was given; - *kim_property modify* will automatically handle memory management to allow + *kim property modify* will automatically handle memory management to allow an arbitrary number of elements to be added to the array. .. note:: - In the event that *kim_property modify* is used to set the value of an + In the event that *kim property modify* is used to set the value of an array index without having set the values of all lesser indices, they will be assigned default values based on the data type associated with the key in the map: @@ -1124,8 +1213,8 @@ of the "species" property key, we can do so by issuing: .. code-block:: LAMMPS - kim_property create 2 cohesive-energy-relation-cubic-crystal - kim_property modify 2 key species source-value 4 Al + kim property create 2 cohesive-energy-relation-cubic-crystal + kim property modify 2 key species source-value 4 Al will result in the "source-value" key in the map for the property key "species" being assigned the array ["", "", "", "Al"]. @@ -1137,12 +1226,12 @@ included). Thus, the snippet above could equivalently be written: .. code-block:: LAMMPS - kim_property modify 2 key species source-value 1:4 Al Al Al Al + kim property modify 2 key species source-value 1:4 Al Al Al Al Calling this command with a non-positive index, e.g. -``kim_property modify 2 key species source-value 0 Al``, or an incorrect +``kim property modify 2 key species source-value 0 Al``, or an incorrect number of input arguments, e.g. -``kim_property modify 2 key species source-value 1:4 Al Al``, will result in an +``kim property modify 2 key species source-value 1:4 Al Al``, will result in an error. As an example of modifying multidimensional arrays, consider the "basis-atoms" @@ -1165,36 +1254,36 @@ each row at a time using colon notation: .. code-block:: LAMMPS - kim_property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 - kim_property modify 2 key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 - kim_property modify 2 key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 - kim_property modify 2 key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5 + kim property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 + kim property modify 2 key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 + kim property modify 2 key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 + kim property modify 2 key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5 Where the first index given refers to a row and the second index refers to a column. We could, instead, choose to set each column at a time like so: .. code-block:: LAMMPS - kim_property modify 2 key basis-atom-coordinates source-value 1:4 1 0.0 0.5 0.5 0.0 & + kim property modify 2 key basis-atom-coordinates source-value 1:4 1 0.0 0.5 0.5 0.0 & key basis-atom-coordinates source-value 1:4 2 0.0 0.5 0.0 0.5 & key basis-atom-coordinates source-value 1:4 3 0.0 0.0 0.5 0.5 .. note:: - Multiple calls of *kim_property modify* made for the same instance ID + Multiple calls of *kim property modify* made for the same instance ID can be combined into a single invocation, meaning the following are both valid: .. code-block:: LAMMPS - kim_property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 & + kim property modify 2 key basis-atom-coordinates source-value 1 1:3 0.0 0.0 0.0 & key basis-atom-coordinates source-value 2 1:3 0.5 0.5 0.0 & key basis-atom-coordinates source-value 3 1:3 0.5 0.0 0.5 & key basis-atom-coordinates source-value 4 1:3 0.0 0.5 0.5 .. code-block:: LAMMPS - kim_property modify 2 key short-name source-value 1 fcc & + kim property modify 2 key short-name source-value 1 fcc & key species source-value 1:4 Al Al Al Al & key a source-value 1:5 3.9149 4.0000 4.032 4.0817 4.1602 & source-unit angstrom & @@ -1211,46 +1300,46 @@ column. We could, instead, choose to set each column at a time like so: .. code-block:: LAMMPS - kim_property modify 2 key basis-atom-coordinates 1 1:3 0.0 0.0 0.0 + kim property modify 2 key basis-atom-coordinates 1 1:3 0.0 0.0 0.0 is valid but .. code-block:: LAMMPS - kim_property modify 2 key basis-atom-coordinates 1:2 1:3 0.0 0.0 0.0 0.0 0.0 0.0 + kim property modify 2 key basis-atom-coordinates 1:2 1:3 0.0 0.0 0.0 0.0 0.0 0.0 is not. .. note:: - After one sets a value in a map with the *kim_property modify* command, + After one sets a value in a map with the *kim property modify* command, additional calls will overwrite the previous value. **Remove** .. code-block:: LAMMPS - kim_property remove instance_id key key_name + kim property remove instance_id key key_name -The *kim_property remove* command can be used to remove a property key from a +The *kim property remove* command can be used to remove a property key from a property instance. For example, .. code-block:: LAMMPS - kim_property remove 2 key basis-atom-coordinates + kim property remove 2 key basis-atom-coordinates **Destroy** .. code-block:: LAMMPS - kim_property destroy instance_id + kim property destroy instance_id -The *kim_property destroy* command deletes a previously created property +The *kim property destroy* command deletes a previously created property instance ID. For example, .. code-block:: LAMMPS - kim_property destroy 2 + kim property destroy 2 .. note:: @@ -1259,22 +1348,22 @@ instance ID. For example, **Dump** -The *kim_property dump* command can be used to write the content of all +The *kim property dump* command can be used to write the content of all currently defined property instances to a file: .. code-block:: LAMMPS - kim_property dump file + kim property dump file For example, .. code-block:: LAMMPS - kim_property dump results.edn + kim property dump results.edn .. note:: - Issuing the *kim_property dump* command clears all existing property + Issuing the *kim property dump* command clears all existing property instances from memory. Citation of OpenKIM IMs @@ -1283,32 +1372,32 @@ Citation of OpenKIM IMs When publishing results obtained using OpenKIM IMs researchers are requested to cite the OpenKIM project :ref:`(Tadmor) `, KIM API :ref:`(Elliott) `, and the specific IM codes used in the simulations, -in addition to the relevant scientific references for the IM. -The citation format for an IM is displayed on its page on -`OpenKIM `_ along with the corresponding BibTex file, -and is automatically added to the LAMMPS citation reminder. +in addition to the relevant scientific references for the IM. The citation +format for an IM is displayed on its page on +`OpenKIM `_ along with the corresponding BibTex file, and +is automatically added to the LAMMPS citation reminder. -Citing the IM software (KIM infrastructure and specific PM or SM codes) -used in the simulation gives credit to the researchers who developed them -and enables open source efforts like OpenKIM to function. +Citing the IM software (KIM infrastructure and specific PM or SM codes) used in +the simulation gives credit to the researchers who developed them and enables +open source efforts like OpenKIM to function. Restrictions """""""""""" -The set of *kim_commands* is part of the KIM package. It is only enabled if -LAMMPS is built with that package. A requirement for the KIM package, -is the KIM API library that must be downloaded from the -`OpenKIM website `_ and installed before -LAMMPS is compiled. When installing LAMMPS from binary, the kim-api package -is a dependency that is automatically downloaded and installed. The *kim_query* -command requires the *libcurl* library to be installed. The *kim_property* +The *kim* command is part of the KIM package. It is only enabled if LAMMPS is +built with that package. A requirement for the KIM package, is the KIM API +library that must be downloaded from the +`OpenKIM website `_ and installed before LAMMPS is +compiled. When installing LAMMPS from binary, the kim-api package is a +dependency that is automatically downloaded and installed. The *kim query* +command requires the *libcurl* library to be installed. The *kim property* command requires *Python* 3.6 or later and the *kim-property* python package to -be installed. See the KIM section of the :doc:`Packages details ` -for details. +be installed. See the KIM section of the +:doc:`Packages details ` for details. -Furthermore, when using *kim_commands* to run KIM SMs, any packages required -by the native potential being used or other commands or fixes that it invokes -must be installed. +Furthermore, when using *kim* command to run KIM SMs, any packages required by +the native potential being used or other commands or fixes that it invokes must +be installed. Related commands """"""""""""""""