Creating a Crystal Genome Property
The first step is to create an OpenKIM Property Definition to describe the material property your Test Driver will calculate.
Under the KIM Properties Framework, a Property Definition is a file in EDN format that defines the fields required to fully characterize a material property.
An example Property Definition is provided with the example Test Driver https://github.com/openkim-hackathons/CrystalGenomeASEExample__TD_000000654321_000 at local-props/energy-vs-volume-isotropic-crystal.edn and is shown at the bottom of this page. All properties in the Crystal Genome framework share a set of keys for describing the crystal using the AFLOW Prototype Label, as well as other metadata. See the comments in the example Property Definition to see which sections you should change and which you should retain.
We strive to make all Crystal Genome properties as universally applicable to arbitrary crystals as possible. You should think carefully about what is needed for a minimal, yet complete, description of your material property when applied to a generic crystal with arbitrary symmetry. To demonstrate this point, consider that the example property here is NOT suitable for general crystals. This is because isotropic expansion and contraction is an arbitrary displacement boundary condition for any non-cubic crystal not corresponding to any specific loading. For cubic crystals it is a meaningful property, as it always corresponds to hydrostatic stress -- see the non-Crystal Genome version of the property here: https://openkim.org/properties/show/2014-04-15/staff@noreply.openkim.org/cohesive-energy-relation-cubic-crystal. You are encouraged to work with the OpenKIM team to develop your property definition (contact us individually or at https://openkim.org/contact/).
- Here are some examples of existing Crystal Genome properties:
It is possible that your Test Driver will write multiple material properties. In this case, create a separate property definition file for each. For example, the bulk modulus and elastic constants shown above are separate properties.
Once your property is finalized, you will need to request a member of the OpenKIM team to permanently add it to the collection of KIM Property Definitions. This will trigger a new release of the kim-property
package containing your new definition, making it automatically usable by your Test Driver if kim-property is up to date.
If you prefer to keep your property as a local file during development, kim-tools will automatically look for property definitions in the local-props and local_props subdirectories of the current working directory. If you wish to put them somewhere else,
you can point the environment variable KIM_PROPERTY_PATH to their location. kim-tools will expand any globs, including recursive **. If you are using new or existing properties after they have been added to OpenKIM, you should not use local definition files.
Tips
Property definitions should not include computational details. This should be included in the README and metadata of your Test Driver. The definition should strictly be a description of a physical material property and should apply to as many possible ways of calculating or measusing the property as possible.
Do not specify exact units (e.g. "J/kg") in the property definition. You may specify dimensionality (e.g. "energy per unit mass").
The KIM Properties Framework allows for flexible (optional) reporting of uncertainty information for every key, so you do not need to add uncertainties as separate keys. See how to do so at the end of the Example test_driver.py written with ASE.
Do not add pressure as a key for constant-pressure simulations, report it as a hydrostatic stress state in the
cell-cauchy-stresskey.
Example Property
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; START OF SECTION YOU SHOULD CHANGE
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
{
"property-id" "tag:staff@noreply.openkim.org,2024-03-11:property/energy-vs-volume-isotropic-crystal"
"property-title" "Energy vs. volume of an arbitrary crystal under isotropic expansion and compression"
"property-description" "Energy vs. volume curve for an arbitrary crystal under isotropic deformation. This is an example property definition for you to use as a template. It contains example keys that you should replace with one or more keys necessary to describe your material property, as well as the common keys for all Crystal Genome properties that you should uncomment or leave. See the comments below. See https://openkim.org/doc/schema/properties-framework/ to see the schema for a property definition, and https://openkim.org/doc/schema/edn-format/ for the edn format more generally."
"binding-potential-energy-per-atom" {
"type" "float"
"has-unit" true
"extent" [":"]
"required" true
"description" "Binding potential energy per atom of the crystal defined as follows: \\Delta \\bar{V}_{atom} = ( V(A_{N_A}B_{N_B}...) - [N_A V_{isolated}(A) + N_B V_{isolated}(B) + ...] )/(N_A + N_B ...), where \\Delta \\bar{V}_{atom} is the binding energy per atom, V(A_{N_A}B_{N_B}...) is the energy of (any) unit cell, V_{isolated}(X) is the energy of an isolated particle of species X, and N_X is the number of atoms of species X in the (same) unit cell."
}
"binding-potential-energy-per-formula" {
"type" "float"
"has-unit" true
"extent" [":"]
"required" true
"description" "This variable has the same definition as 'binding-potential-energy-per-atom' except that the energy is normalized per chemical formula instead of per atom, i.e. \\Delta \\bar{V}_{formula} = \\Delta \\bar{V}_{atom} N_{formula}, where N_{formula} is the number of atoms in the reduced stoichiometric formula, i.e. the sum of indices in the first section of the prototype-label."
}
"volume-per-atom" {
"type" "float"
"has-unit" true
"extent" [":"]
"required" true
"description" "The volume of the unit cell divided by the number of atoms in the unit cell."
}
"volume-per-formula" {
"type" "float"
"has-unit" true
"extent" [":"]
"required" true
"description" "The volume of the unit cell divided by the number of atoms in the unit cell, multiplied by the number of atoms in the reduced stoichiometric formula, i.e. the sum of indices in the first section of the prototype-label."
}
"cat-picture" {
"type" "file"
"has-unit" false
"extent" []
"required" true
"description" "This is a picture of a cat. It will be used to demonstrate how to manage auxiliary files and add them to properties."
}
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; END OF SECTION YOU SHOULD CHANGE (besides possibly uncommenting the block below)
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; If your material property can be meaningfully characterized at finite temperature and stress, uncomment the below section. You should do this even if the Test Driver you are writing only works at 0K and 0 Bar, for when future Test Drivers are written that work at finite T and pressure.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; "temperature" {
; "type" "float"
; "has-unit" true
; "extent" []
; "required" true
; "description" "Temperature of the crystal."
; }
; "cell-cauchy-stress" {
; "type" "float"
; "has-unit" true
; "extent" [6]
; "required" true
; "description" "The [xx,yy,zz,yz,xz,xy] components of the prescribed symmetric Cauchy stress tensor. The numerical value of the stress tensor of a test result or reference data may be different due to tolerance, and can be checked by inspecting the output files of the test or the reference data description. The components should be expressed in the same coordinate system as the structure specified by prototype-label and parameter-values, with the orientation of lattice vectors defined in M. J. Mehl et al., Comput. Mater. Sci. 136, S1 (2017)."
; }
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; END OF NPT SECTION, BELOW IS THE DESCRIPTION OF THE CRYSTAL THAT SHOULD PROBABLY BE IN EVERY
; CRYSTAL GENOME PROPERTY DEFINITION
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
"prototype-label" {
"type" "string"
"has-unit" false
"extent" []
"required" true
"description" "Prototype label (not including an enumeration suffix) as defined by the AFLOW standard (e.g. 'A_tI4_141_a') for the structure. It is expected that the alphabetically lowest of all equivalent labels is chosen."
}
"stoichiometric-species" {
"type" "string"
"has-unit" false
"extent" [":"]
"required" true
"description" "Element symbols corresponding to the atom types in the stoichiometric formula which appears at the start of the prototype label (e.g. ['Mo','S'] for the AB2 stoichiometric formula, means that the 'A' atom is 'Mo' and the 'B' atom is 'S' for the MoS_2 structure)."
}
"a" {
"type" "float"
"has-unit" true
"extent" []
"required" true
"description" "The average 'a' lattice constant of the crystal structure as defined by the AFLOW standard. Relative values of other lattice parameters (if present) are given in the 'parameter-values' key."
}
"parameter-names" {
"type" "string"
"has-unit" false
"extent" [":"]
"required" false
"description" "Names of the parameters other than 'a', if present, corresponding to this AFLOW prototype. These can include lattice parameters from the set {'b/a','c/a','alpha','beta','gamma'} (for the conventional crystal structure defined by lattice parameters a, b, and c and angles alpha, beta, gamma), and coordinates of Wyckoff positions that have a degree of variability labeled as 'x*', 'y*' and 'z*' where the asterisk represents an integer as defined by the AFLOW standard."
}
"parameter-values" {
"type" "float"
"has-unit" false
"extent" [":"]
"required" false
"description" "Values for the parameters listed in 'parameter-names' corresponding to the average positions of the atoms. Note that all parameters are dimensionless."
}
"library-prototype-label" {
"type" "string"
"has-unit" false
"extent" []
"required" false
"description" "The AFLOW library prototype, if any, matching the structure. Prototypes in the AFLOW library are associated with common short names used by the materials community. The library prototype includes an integer enumeration suffix defined by the AFLOW standard when there are multiple parameter values associated with the structure (e.g. 'A_tI4_141_a-001' for 'betaSn'). Because these prototype labels are named according to their original material's conventional chemical formula, they may differ from the 'prototype-label' key, which is expected to be standardized to have the alphabetically lowest possible of all equivalent labels."
}
"short-name" {
"type" "string"
"has-unit" false
"extent" [":"]
"required" false
"description" "Commonly used name associated with the 'library-prototype-label' key according to the AFLOW prototype library (e.g. 'Face-Centered Cubic' or 'Molybdenite')."
}
"coordinates-file" {
"type" "file"
"has-unit" false
"extent" []
"required" false
"description" "A file containing the atomic configuration including information such as the species, x,y,z coordinates of each particle, and periodicity data. This configuration is the primitive unit cell of the crystal according to the cell choice defined in M. J. Mehl et al., Comput. Mater. Sci. 136, S1 (2017)."
}
"coordinates-file-conventional" {
"type" "file"
"has-unit" false
"extent" []
"required" false
"description" "A file containing the atomic configuration including information such as the species, x,y,z coordinates of each particle, and periodicity data. This configuration is the conventional unit cell of the crystal according to the cell choice defined in M. J. Mehl et al., Comput. Mater. Sci. 136, S1 (2017)."
}
"crystal-genome-source-structure-id" {
"type" "string"
"has-unit" false
"extent" [":",":"]
"required" false
"description" "The identifiers (ID) of the Crystal Genome (CG) structures for which the property (test result and instance) containing this key was computed. Each element is the KIM ID of an OpenKIM Reference Data item that served as the initial configuration before it was relaxed or equilibrated with an interatomic model. Each row corresponds to a structure in the test, i.e. a test computing a property of a single crystal will only have one row, while something like a transformation between two pre-determined crystals would have two rows, and so on. Within each row, there may be multiple columns in the case when multiple initial structures converged to a single final structure during this test or one of its upstream dependencies. Because KIM Property values must be regular arrays, rows will be padded with empty strings to match the longest row."
}
}