Package: kim-property
KIM-PROPERTY utility moduleThe objective is to make it as easy as possible to convert a script (for
example aLAMMPSscript) that computes aKIM propertyto a KIM Test.This utility module has 5 modes:1-CreateTake as input the property instance ID and property definition name and
create initial property instance data structure. It checks and indicates
whether the property definition exists inOpenKIM.2-DestroyDelete a previously created property instance ID.3-ModifyIncrementally build the property instance by receiving keys with
associated arguments. It can "append" and add to a key's existing array
argument.4-RemoveRemove a key.5-DumpTake as input the generated instance and a filename, validate each
instance against the property definition and either issues an error or
writes the instance out to file in edn format. Final validation should
make sure all keys/arguments are legal and all required keys are
provided.CreateCreating property instances::>>>kim_property_create(1,'cohesive-energy-relation-cubic-crystal')'[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1}]'>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>kim_property_create(2,'atomic-mass',property_inst)'[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1} {"property-id" "tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass" "instance-id" 2}]'>>>property_inst=kim_property_create(2,'atomic-mass',property_inst)>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1}{"property-id""tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass""instance-id"2}]A property instance is stored in a subset of the KIM-EDN format as described inKIM Property Instances.
Each property instance must contain theproperty-idandinstance-id.kim-propertyutility module can create a new property instance, using a KIM
property ID. A KIM 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:>>>kim_property_create(1,'atomic-mass')>>>kim_property_create(2,'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')>>>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.DestroyDestroying property instances::>>>property_inst_obj='[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1}]'>>>kim_property_destroy(property_inst_obj,1)'[]'>>>property_inst_obj='[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1} {"property-id" "tag:brunnels@noreply.openkim.org,2016-05-11:property/atomic-mass" "instance-id" 2}]'>>>kim_property_destroy(property_inst_obj,2)'[{"property-id" "tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal" "instance-id" 1}]'ModifyModifying (setting) property instances.Once akim_property_createhas been given to instantiate a property
instance, maps associated with the property's keys can be edited using the
kim_property_modify.
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, thecohesive-energy-relation-cubic-crystalproperty definition
consists of property keys named "short-name", "species", ...
An instance of this property could be created like so::>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"short-name"{"source-value"["fcc"]}"species"{"source-value"["Al""Al""Al""Al"]}"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"5}}]For cases where there are multiple keys or a key receives an array of values
computed one at a time, thekim_property_modifycan be called multiple
times and append values to a given key.>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"short-name"{"source-value"["fcc"]}"species"{"source-value"["Al""Al""Al""Al"]}"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"5}}]>>>property_inst=kim_property_modify(property_inst,1,"key","basis-atom-coordinates","source-value","2","1:2","0.5","0.5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"short-name"{"source-value"["fcc"]}"species"{"source-value"["Al""Al""Al""Al"]}"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"5}"basis-atom-coordinates"{"source-value"[[0.00.00.0][0.50.50.0]]}}]>>>property_inst=kim_property_modify(property_inst,1,"key","basis-atom-coordinates","source-value","3","1:3","0.5","0.0","0.5","key","basis-atom-coordinates","source-value","4","2:3","0.5","0.5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"short-name"{"source-value"["fcc"]}"species"{"source-value"["Al""Al""Al""Al"]}"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"5}"basis-atom-coordinates"{"source-value"[[0.00.00.0][0.50.50.0][0.50.00.5][0.00.50.5]]}}]>>>property_inst=kim_property_modify(property_inst,1,"key","cohesive-potential-energy","source-value","1:5","3.324","3.3576","3.3600","3.3550","3.3260","source-std-uncert-value","1:5","0.002","0.0001","0.00001","0.0012","0.00015","source-unit","eV","digits","5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"short-name"{"source-value"["fcc"]}"species"{"source-value"["Al""Al""Al""Al"]}"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"5}"basis-atom-coordinates"{"source-value"[[0.00.00.0][0.50.50.0][0.50.00.5][0.00.50.5]]}"cohesive-potential-energy"{"source-value"[3.3243.35763.363.3553.326]"source-std-uncert-value"[0.0020.00011e-050.00120.00015]"source-unit""eV""digits"5}}]Note:Variables which are introduced with a specified extent of either an empty
vector[]or[1], are scalars.Calling akim_property_modifywill update the scalars and vector values
which are already set.For example:>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"key","space-group","source-value","Immm")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"space-group"{"source-value""Immm"}}]Calling thekim_property_modifyagain set the scalar variable with a new
value.>>>property_inst=kim_property_modify(property_inst,1,"key","space-group","source-value","P6_3/mmc")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"space-group"{"source-value""P6_3/mmc"}}]Note:If the source-value key is a scalar, the values of the uncertainty and digits
keys must be scalars. Thus, calling thekim_property_modifywith a non-scalar
key where the source-value key is a scalar fails.Note:If the source-value key's value is an array (EDN vector), the values of the
uncertainty and digits keys must be either arrays of the same extent, or
scalars in which case they are taken to apply equally to all values in the
source-value array. The keys associated with uncertainty and precision conform
to theISO Guide to the Expression of Uncertainty in Measurementand theThermoML standard notation.The keys associated with uncertainty and precision of theKIM Property Instancesare:source-std-uncert-valuesource-expand-uncert-valuecoverage-factorsource-asym-std-uncert-negsource-asym-std-uncert-possource-asym-expand-uncert-negsource-asym-expand-uncert-posuncert-lev-of-confiddigitsIn below example, thea-key source-value key's value is an array, which means
the value of thedigits-key must be either an array of the same extent, or a
scalar.The value of thedigits-key is a scalar:>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"key","a","source-value","1:5","3.9149","4.0000","4.032","4.0817","4.1602","source-unit","angstrom","digits","5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"5}}]The value of thedigits-key is an array of the same extent:>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"key","a","source-value","1:5","3.9149","4.0000","4.032","4.0817","4.1602","source-unit","angstrom","digits","1:5","5","5","5","5","5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"a"{"source-value"[3.91494.04.0324.08174.1602]"source-unit""angstrom""digits"[55555]}}]RemoveRemoving (a) key(s) from a property instance::>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5","key","basis-atom-coordinates","source-value","2","1:2","0.5","0.5","key","basis-atom-coordinates","source-value","3","1:3","0.5","0.0","0.5","key","basis-atom-coordinates","source-value","4","2:3","0.5","0.5","key","cohesive-potential-energy","source-value","1:5","3.324","3.3576","3.3600","3.3550","3.3260","source-std-uncert-value","1:5","0.002","0.0001","0.00001","0.0012","0.00015","source-unit","eV","digits","5")>>>property_inst=kim_property_remove(property_inst,1,"key","a","source-unit")>>>property_inst=kim_property_remove(property_inst,1,"key","cohesive-potential-energy","key","basis-atom-coordinates")>>>property_inst_obj=kim_edn.loads(property_inst)>>>print(kim_edn.dumps(property_inst_obj,indent=4))[{"property-id""tag:staff@noreply.openkim.org,2014-04-15:property/cohesive-energy-relation-cubic-crystal""instance-id"1"short-name"{"source-value"["fcc"]}"species"{"source-value"["Al""Al""Al""Al"]}"a"{"source-value"[3.91494.04.0324.08174.1602]"digits"5}}]DumpFirst, it validates the generated instances against the property definition.
Then serializes it to aKIM-EDNformatted stream and dumps it to afp(a.write()-supporting file-like
object or a name string to open a file).The validation makes sure all keys/arguments are legal and all required keys
are provided.>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5","key","basis-atom-coordinates","source-value","2","1:2","0.5","0.5","key","basis-atom-coordinates","source-value","3","1:3","0.5","0.0","0.5","key","basis-atom-coordinates","source-value","4","2:3","0.5","0.5","key","cohesive-potential-energy","source-value","1:5","3.324","3.3576","3.3600","3.3550","3.3260","source-std-uncert-value","1:5","0.002","0.0001","0.00001","0.0012","0.00015","source-unit","eV","digits","5")>>>kim_property_dump(property_inst,"results.edn")or>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5","key","basis-atom-coordinates","source-value","2","1:2","0.5","0.5","key","basis-atom-coordinates","source-value","3","1:3","0.5","0.0","0.5","key","basis-atom-coordinates","source-value","4","2:3","0.5","0.5","key","cohesive-potential-energy","source-value","1:5","3.324","3.3576","3.3600","3.3550","3.3260","source-std-uncert-value","1:5","0.002","0.0001","0.00001","0.0012","0.00015","source-unit","eV","digits","5")>>>property_inst_obj=kim_edn.loads(property_inst)>>>kim_property_dump(property_inst_obj,"results.edn")or>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5","key","basis-atom-coordinates","source-value","2","1:2","0.5","0.5","key","basis-atom-coordinates","source-value","3","1:3","0.5","0.0","0.5","key","basis-atom-coordinates","source-value","4","2:3","0.5","0.5","key","cohesive-potential-energy","source-value","1:5","3.324","3.3576","3.3600","3.3550","3.3260","source-std-uncert-value","1:5","0.002","0.0001","0.00001","0.0012","0.00015","source-unit","eV","digits","5")>>>withopen("results.edn",'w')asfp:kim_property_dump(property_inst,fp)An example with two property instances,>>>property_inst=kim_property_create(1,'cohesive-energy-relation-cubic-crystal')>>>property_inst=kim_property_modify(property_inst,1,"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","digits","5","key","basis-atom-coordinates","source-value","2","1:2","0.5","0.5","key","basis-atom-coordinates","source-value","3","1:3","0.5","0.0","0.5","key","basis-atom-coordinates","source-value","4","2:3","0.5","0.5","key","cohesive-potential-energy","source-value","1:5","3.324","3.3576","3.3600","3.3550","3.3260","source-std-uncert-value","1:5","0.002","0.0001","0.00001","0.0012","0.00015","source-unit","eV","digits","5")>>>property_inst=kim_property_create(2,'atomic-mass',property_inst)>>>property_inst=kim_property_modify(property_inst,2,"key","mass","source-value","1.434e-19","source-unit","si","key","species","source-value","Al")>>>kim_property_dump(property_inst,"results.edn")Installing kim-propertyRequirementsYou need Python 3.6 or later to runkim-property. You can have multiple
Python versions (2.x and 3.x) installed on the same system without problems.To install Python 3 for different Linux flavors, macOS and Windows, packages
are available athttps://www.python.org/getit/Using pippipis the most popular tool for installing Python packages, and the one
included with modern versions of Python.kim-propertycan be installed withpip:pipinstallkim-propertyNote:Depending on your Python installation, you may need to usepip3instead ofpip.pip3installkim-propertyDepending on your configuration, you may have to runpiplike this:python3-mpipinstallkim-propertyUsing pip (GIT Support)pipcurrently supports cloning overgitpipinstallgit+https://github.com/openkim/kim-property.gitFor more information and examples, see thepip installreference.Using condacondais the package management tool for Anaconda Python installations.Installingkim-propertyfrom theconda-forgechannel can be achieved by
addingconda-forgeto your channels with:condaconfig--addchannelsconda-forgeOnce theconda-forgechannel has been enabled,kim-propertycan be
installed with:condainstallkim-propertyIt is possible to list all of the versions ofkim-propertyavailable on
your platform with:condasearchkim-property--channelconda-forgeCopyrightCopyright (c) 2020-2023, Regents of the University of Minnesota.All Rights ReservedContributingContributors:Yaser Afshar