Metadata and KIM Processing Pipeline Integration 

The penultimate step in creating your Test Driver is to set up the auxiliary files needed for the KIM Processing Pipeline to use it. As with the rest of this documentation, this page follows the example test driver from https://github.com/openkim-hackathons/CrystalGenomeASEExample__TD_000000654321_000. Most of the files are pre-configured to work as-is for most Test Drivers, and only a few changes are needed.

To test that everything is correctly configured, you will need to use the KIM Developer Platform and place your Driver in the correct path.

Todo

In the future, we will automate the manual processes described here.

First, let's go over the files you will need to change.

`test_generator.json`

This is the file that specifies the inputs to your Test Driver. Each line is a JSON dictionary. Each line corresponds to a separate KIM Test.

{"stoichiometric_species": ["Ca", "O", "Si"], "prototype_label": "AB3C_aP30_2_3i_9i_3i", "version": "000"}
{"stoichiometric_species": ["C"], "prototype_label": "A_mC16_12_4i", "version": "000"}
{"stoichiometric_species": ["U"], "prototype_label": "A_oC4_63_c", "version": "000"}
{"stoichiometric_species": ["Mo", "Ni"], "prototype_label": "AB4_tI10_87_a_h", "version": "000"}
{"stoichiometric_species": ["O", "Ti"], "prototype_label": "A2B_tP6_136_f_a", "version": "000"}
{"stoichiometric_species": ["Al", "Pd"], "prototype_label": "AB_hR26_148_a2f_b2f", "version": "000"}
{"stoichiometric_species": ["O", "Si"], "prototype_label": "A2B_hP9_154_c_a", "version": "000"}
{"stoichiometric_species": ["Fe", "P"], "prototype_label": "A2B_hP9_189_fg_ad", "version": "000"}
{"stoichiometric_species": ["As", "Ga"], "prototype_label": "AB_cP16_205_c_c", "version": "000"}
{"stoichiometric_species": ["Ce", "O"], "prototype_label": "AB2_cF12_225_a_c", "pressure_eV_angstrom3": 0.0, "version": "000"}
{"stoichiometric_species": ["Al"], "prototype_label": "A_cF4_225_a", "temperature_K": 0.0, "cell_cauchy_stress_eV_angstrom3": [0.0, 0.0, 0.0, 0.0, 0.0, 0.0], "crystal_genome_test_args": {"max_volume_scale": 0.1}, "version": "000"}

As you can see, it specifies the crystal structure and optionally allows you to pass any additional arguments you defined in your _calculate() method as a sub-dictionary under crystal_genome_test_args, as well as the pre-defined arguments all XtalG Test Drivers take (temperature and stress/pressure). If needed, edit this sub-dictionary to reflect the inputs your Test Driver uses. You can omit any arguments you wish to set to their default value, and if your _calculate() takes no additional arguments, you can omit crystal_genome_test_args entirely. If your Test Driver does not use temperature and/or stress, you may omit these keys as well (the example Test Driver does not use them, but they are left for demonstration).

If you wish to create Tests for different inputs (e.g. multiple temperatures), you must create a separate line for each one. For example, if we wanted to create Tests using the example Test Driver that set max_volume_scale=0.1 and different Tests that set max_volume_scale=0.2, both for all structures, we would double the number of lines in test_generator.json.

There is a file called test_generator_full.json that contains all structures currently on OpenKIM.org. Before submitting, you should expand your test_generator.json to include all of these structures.

Todo

Currently the temperature and stress inputs only set the internal values of those variables in the SingleCrystalTestDriver class, and do not affect querying. The structure queried for is always the zero temperature, zero pressure structure

Generating and Running Tests 

There is one more file that you will need to change from the example Test Driver, but it will be easier to contextualize if we first demonstrate how Tests are generated and run in the KIM Developer Platform using the example Test Driver.

To generate tests from the example Test Driver you've placed in ~/test-drivers/CrystalGenomeASEExample__TD_000000654321_000 of your KDP, run the following command.

kimgenie tests --add-random-kimnums --test-driver CrystalGenomeASEExample__TD_000000654321_000

Note

The --add-random-kimnums option has added a kimnum key to each line in test_generator.json. Do not use this option after these keys have been added.

Let's install a model for aluminum and run it with the created test for FCC aluminum. The random kimnum generated for your test will vary, but the pipeline-run-pair command accepts wildcards:

kimitems install -D EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005
pipeline-run-pair CrystalGenomeASEExample_A_cF4_225_a_Al_0_1__TE_* EAM_Dynamo_ErcolessiAdams_1994_Al__MO_123629422045_005 -v

You should see the output of the test, and there should be a new directory in ~/test-results/ with the results.edn file containing the resulting KIM Property Instance, as well as several other files documenting the run.

For more info regarding the utilities available in the KIM Developer Platform, see https://openkim.org/doc/evaluation/kim-developer-platform/, consult the README.txt in the home directory of the KDP, or run any of them with the -h option.

`test_template/kimspec.edn.genie`

If you look in your ~/tests/ directory, you will see that a subdirectory has been created for each Test. Within it is a file named kimspec.edn, which is a metadata file required to be provided with every piece of KIM content. The kimgenie utility generates these from the test_template/kimspec.edn.genie file in the Test Driver directory using Jinja2 templating. A Jinja2 tutorial is available here: https://ttl255.com/jinja2-tutorial-part-1-introduction-and-variable-substitution/. Below is the file in from the example Test Driver. Compare with one of the rendered kimspec.edn files in ~/tests/ to see how the templating works.

{
  "title" "Energy vs. volume scan under fractional isometric expansion/contraction of +-{{(crystal_genome_test_args|default({})).max_volume_scale|default(0.01)}} for {{stoichiometric_species|join('')}} in AFLOW crystal prototype {{prototype_label}} v{{version}}"
  "description" "Performs an energy vs. volume scan under isometric expansion/contraction of +-{{(crystal_genome_test_args|default({})).max_volume_scale|default(0.01)}} for {{stoichiometric_species|join("")}} in AFLOW crystal prototype {{prototype_label}}. Energies and volumes are reported normalized both per-atom and per-formula."
  "extended-id" "{{TEST_DRIVER_NAME.split('_')[:-4]|join('_')}}_{{prototype_label}}_{{stoichiometric_species|join('')}}_{{(crystal_genome_test_args|default({})).max_volume_scale|default(0.01)|replace('.','_')}}__TE_{{kimnum}}_{{version}}"
  "test-driver" "{{TEST_DRIVER_NAME}}"
  "species" ["{{stoichiometric_species|join('" "')}}"]
  "contributor-id" "4ad03136-ed7f-4316-b586-1e94ccceb311"
  "maintainer-id" "4ad03136-ed7f-4316-b586-1e94ccceb311"
  "executables" ["runner"]
  "domain" "openkim.org"
  "matching-models" ["standard-models"]
  "disclaimer" "Computer generated"
  "kim-api-version" "2.3"
  "publication-year" "2024"
}{# FILENAME = kimspec.edn #}

An example of a kimspec.edn.genie for a molecular dynamics Test Driver templating temperature and pressure: https://github.com/openkim-hackathons/NPTCrystalStructure/blob/main/test_template/kimspec.edn.genie

Here are the keys you will need to edit. You can leave the templating involving TEST_DRIVER_NAME, prototype_label, stoichiometric_species and kimnum as-is, but you will need to change descriptive prose, as well as render the arguments specific to your Test Driver (if any). Note, for example, how the max_volume_scale argument is templated in the fields below. At the very least, you will have to remove the logic involving max_volume_scale (assuming your Test Driver doesn't incidentally have the same argument). See https://openkim.org/doc/schema/kimspec/ for a detailed definition of each field.

title and description: change these to be relevant to your Test Driver and descriptive of the individual Tests, including rendering any non-default physical arguments using Jinja.

extended-id: See https://openkim.org/doc/schema/kim-ids/ for recommendations. The extended-id should also specify any non-default physical arguments. Note how a replace operation is used on crystal_genome_test_args.max_volume_scale, as . is not an allowed character. You may have to get creative with templating if your non-default arguments are arrays.

In most cases, this should be all you need to change. Use kimgenie to generate some Tests and check that kimspec.edn looks correct.

Other files 

These are the other required files in a Test Driver. In most cases, you can copy them from the example Test Driver as-is.

kimspec.edn: This is the metadata for the Test Driver itself. You may leave this in the minimal form provided in the example Test Driver, or you can fill in some of the fields following https://openkim.org/doc/schema/kimspec/. Any missing fields will be populated by the Web form when you submit your Driver.

Makefile: Unless your Test Driver requires compilation, leave this dummy Makefile untouched.

runner: This is the executable that invokes the TestDriver class when running in the KIM Pipeline. Its executable bit should be set.

test_template/runner: This is a wrapper executable in each Test that invokes the Test Driver's runner. Its executable bit should be set. You should never have to change this file.

test_template/pipeline.stdin.tpl.genie: This is the Jinja2 template file for passing inputs to the runner.

test_template/dependencies.edn.genie: This Jinja2 template file specifies the Tests that the generated Tests are dependent on.

test_template/LICENSE: By default, this is LGPL2. Change it if you want a different license. You will be able to choose the license for your Test Driver during submission

test_template/Makefile: Always leave this as-is.

Metadata and KIM Processing Pipeline Integration

test_generator.json

Generating and Running Tests

test_template/kimspec.edn.genie

Other files