Test Driver Creation Tutorial

This is a tutorial for creating OpenKIM Test Drivers in the Crystal Genome framework for arbitrary crystals. It follows the example Test Driver hosted at https://github.com/openkim-hackathons/CrystalGenomeASEExample__TD_000000654321_000. You are encouraged to use it as a template when writing your own Test Driver. For example, if you are working in the KIM Developer Platform, you can clone the example Test Driver with the following shell commands:

cd ~/test-drivers
git clone https://github.com/openkim-hackathons/CrystalGenomeASEExample__TD_000000654321_000

Note

If you are working in the KIM Developer Platform and intend to test the integration of your Test Driver into the OpenKIM pipeline, the location and directory name of the Test Driver is important. This means that when you should follow the above instructions exactly to clone into the correct location, and when you create your own Test Driver, you should place it in /home/openkim/test-drivers/<Extended KIM ID Prefix>__TD_DDDDDDDDDDDDD_VVV. <Extended KIM ID Prefix> is a short alphanumeric description of your test driver, DDDDDDDDDDDD is an arbitrary unique 12-digit integer code (it is conventional for in-development codes to start with 000000), and VVV is the version starting with 000. For more info see https://openkim.org/doc/schema/kim-ids/.

Steps for Creating a Crystal Genome Test Driver

• Creating a Crystal Genome Property
  • Tips
  • Example Property
• Main Computational Code
  • Example test_driver.py written with ASE
  • Functionality not covered in the above example
• Testing and Debugging Your Crystal Genome Test Driver
  • Example Script for Running a Crystal Genome Test Driver
  • Curated Set of Test Cases
• Metadata and KIM Processing Pipeline Integration
  • test_generator.json
  • Generating and Running Tests
  • test_template/kimspec.edn.genie
  • Other files
• kimvv Python package integration
  • Forking the kimvv repo
  • Setting up the packaging files
  • Issuing a release and adding it to your fork of kimvv
  • Checking that your fork passes the tests

Submitting Your Test Driver

When your Test Driver is complete (meaning you have completed the 5 tasks outlined above), take the following final steps to get your Test Driver submitted to OpenKIM.org and running in the Pipeline:

• If you have not done so already, request a member of the OpenKIM team to permanently add your Property Definition to the collection of KIM Property Definitions.

• Request a member of the OpenKIM team to add you to the openkim-dev-tests Github organization, and transfer ownership of your repo there.

• Create an OpenKIM account at https://openkim.org/new-account.

• Submit a tar.gz of your Test Driver at https://openkim.org/contribute/test-driver/. Create this archive by issuing a release on Github with the tag v000. The .gitattributes file provided with the example Test Driver already has the correct settings to only export the needed files. Follow the instructions in the form to fill out the information about your Test Driver. Before you submit, you will be provided a .txz archive named InProgress.... Repeat the kimvv integration test one last time with this archive, then you are ready to submit!