==================================
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 <https://openkim.org/doc/schema/properties-framework/>`_, a *Property Definition* is a file in `EDN format <https://openkim.org/doc/schema/edn-format/>`_ that defines the fields required to fully characterize a material property.

An example Property Definition is provided with the example Test Driver |example_url| 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:
    * https://openkim.org/properties/show/2024-07-10/staff@noreply.openkim.org/bulk-modulus-isothermal-npt
    * https://openkim.org/properties/show/2024-07-10/staff@noreply.openkim.org/elastic-constants-isothermal-npt

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 <https://openkim.org/properties>`_. This will trigger a new release of the `kim-property <https://github.com/openkim/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 <https://openkim.org/doc/schema/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 :ref:`doc.example_test_driver`.
* Do not add pressure as a key for constant-pressure simulations, report it as a hydrostatic stress state in the ``cell-cauchy-stress`` key.

Example Property
================

.. literalinclude:: ../../examples/CrystalGenomeASEExample__TD_000000654321_000/local-props/energy-vs-volume-isotropic-crystal.edn
    :language: clojure