Installation

kimvv and all requirements are available in the KIM Developer Platform (KDP) container available here: https://github.com/openkim/developer-platform

kimvv is installable with pip install kimvv, but it requires some non-Python rquirements to be installed first. These prerequisites are decribed in installation info for kim-tools, the backend for kimvv, here: https://kim-tools.readthedocs.io/en/stable/#doc-standalone-installation.

How to cite:

If you use the results from this package in a publication, please cite the Test Driver(s) you used. A BibTeX printout is available via the get_kimcite class method of each class, e.g. print(kimvv.EquilibriumCrystalStructure.get_kimcite()). An additional paper to cite is coming soon.

Basic usage example:

Computing elastic constants for FCC argon using an example KIM potential

from kimvv import ElasticConstantsCrystal
from ase.build import bulk
from json import dumps

# The Test Driver must be instantiated with an ASE Calculator object
# or a string indicating a KIM model name
elast = ElasticConstantsCrystal('LennardJones_Ar')

# To perform the computation, call the Test Driver object. The first argument
# to most Test Drivers is the crystal structure to perform the computation on.
# To see an explanation of the calculation and a description of the
# additonal arguments, use .printdoc()
elast.printdoc()

# For the sake of speed, let's compute the elastic constants with the
# "stress-condensed" method, instead of the default robust computation loop.
# The crystal structure can be specified as an Atoms object. Any dependencies
# (e.g. relaxing the crystal structure with EquilibriumCrystalStructure) are
# automatically run.
atoms = bulk("Ar", "fcc", 5.0)
results = elast(atoms, method="stress-condensed")

# Each Test Driver computes a list of one or more dictionaries, each defining
# a material property in the format specified by the KIM Properties Framework.
# The name of the property is in the "property-id" key. See
# https://openkim.org/properties for the definition of each property.
print(dumps(results, indent=2))

Usage example 2

Computing heat capacity and thermal expansion coefficients of gold using an example KIM potential using a small system size running 3 LAMMPS processes using 2 CPUs each

from kimvv import HeatCapacityThermalExpansionCrystalNPT
from ase.build import bulk
atoms = bulk("Au")
td = HeatCapacityThermalExpansionCrystalNPT("Sim_LAMMPS_LJcut_AkersonElliott_Alchemy_PbAu")
result = td(atoms, temperature_K=300, target_size=1000, lammps_command="mpirun -np 2 --bind-to numa lmp", max_workers=3)

Usage example 3

Getting the anisotropic pressure-volume curve of HCP Ag using a non-KIM ASE Calculator

from kimvv import CrystalStructureAndEnergyVsPressure
from ase.build import bulk
from ase.calculators.emt import EMT

# The Test Driver must be instantiated with an ASE Calculator object
# or a string indicating a KIM model name
scan = CrystalStructureAndEnergyVsPressure(EMT())

# To perform the computation, call the Test Driver object. The first argument
# to most Test Drivers is the crystal structure to perform the compuation on.
# To see the additonal arguments, use .printdoc() to print the docstring
scan.printdoc()

# The default volume range of 0.25-4.0 will take a long time to scan. Let's
# do a much smaller range
results = scan(
    bulk("Ag", "hcp", 2.92), min_fractional_volume=0.98, max_fractional_volume=1.02
)

Usage example 4

This example is functionally identical to the previous example, except the crystal is specified by passing a dictionary specifying the symmetry-reduced description of the crystal

from kimvv import CrystalStructureAndEnergyVsPressure
from ase.calculators.emt import EMT

scan = CrystalStructureAndEnergyVsPressure(EMT())

# Specify the material using a symmetry-reduced dictionary.
# Internally, all kimvv Test Drivers use this representation,
# so this allows more direct control, as an Atoms object will
# be converted to this regardless. This allows you to specify
# the crystal in a specific orientation that will be maintained
# Notionally, this should be an instance of the
# `crystal-structure-npt` OpenKIM Property, but the exact schema
# is not enforced. As long as the following fields are present,
# it will work: "prototype-label.source-value",
# "stoichiometric-species.source-value", "a.source-value",
# and, if the crystal has any free parameters,
# "parameter-values.source-value".
# For an exact definition of these fields, see
# https://openkim.org/properties/show/crystal-structure-npt
# For more info about the AFLOW Prototype Designation,
# see section B here: https://arxiv.org/pdf/2401.06875
material = {
    "prototype-label": {"source-value": "A_hP2_194_c"},
    "stoichiometric-species": {"source-value": ["Ag"]},
    "a": {
        "source-value": 2.933,
        "source-unit": "angstrom",
    },
    "parameter-names": {"source-value": ["c/a"]},
    "parameter-values": {"source-value": [1.6373338]},
}


results = scan(material, min_fractional_volume=0.98, max_fractional_volume=1.02)
scan.write_property_instances_to_file("scan_output/results.edn")

Usage example 5

Querying for all DFT-relaxed structures for a given combination of elements in OpenKIM and relaxing them with your potential

from kimvv import EquilibriumCrystalStructure
from kim_tools import (
  query_crystal_structures,
  get_deduplicated_property_instances
)
from json import dumps
from ase.calculators.lj import LennardJones

# Query for all relaxed Argon reference data in OpenKIM
# You can narrow the query further by specifying more information
# about the crystal, see
# https://kim-tools.readthedocs.io/en/stable/kim_tools.test_driver.html#kim_tools.test_driver.core.query_crystal_structures
raw_structs = query_crystal_structures(stoichiometric_species=["Ar"])

# Deduplicate them
unique_structs = get_deduplicated_property_instances(raw_structs, allow_rotation=True)

# Instantiate the Driver with your model
relax = EquilibriumCrystalStructure(LennardJones(sigma=3.4,epsilon=0.0104,rc=8.15))

# Run the Driver with each structure. As this is run, the driver internally accumulates
# Property Instances
for struct in unique_structs:
  relax(struct)

# In addition to returning the Property Instances for the current run, Test Drivers
# accumulate all computed Property Instances. They can be accessed like this:
print(dumps(relax.property_instances, indent=2))