kim_tools.test_driver package

Submodules

kim_tools.test_driver.core module

Helper classes for KIM Test Drivers

kim_tools.test_driver.core._glob_with_exceptions(pattern, exceptions, recursive=False)

Return a list of paths that match the glob "pattern" but not the glob "exceptions"

Return type:

List[PathLike]

kim_tools.test_driver.core.get_supported_lammps_atom_style(model)

Get the supported LAMMPS atom_style of a KIM model

Return type:

str

kim_tools.test_driver.core._get_optional_source_value(property_instance, key)

Function for getting an optional key's source-value, or None if the key doesn't exist, from a Property Instance that is a Dict

Return type:

Any

kim_tools.test_driver.core._update_optional_key_in_property_dict(property_instance, key, value, unit=None)

In a Property Instance that's a Dict, update a key or erase it if None is provided

Return type:

None

kim_tools.test_driver.core.minimize_wrapper(atoms, fmax=1e-05, steps=200, variable_cell=True, logfile='kim-tools.log', algorithm=<class 'ase.optimize.lbfgs.LBFGSLineSearch'>, cell_filter=<class 'ase.filters.FrechetCellFilter'>, fix_symmetry=False, opt_kwargs={}, flt_kwargs={})

Use LBFGSLineSearch (default) to Minimize cell energy with respect to cell shape and internal atom positions.

LBFGSLineSearch convergence behavior is as follows:

  • The solver returns True if it is able to converge within the optimizer iteration limits (which can be changed by the steps argument passed to run), otherwise it returns False.

  • The solver raises an exception in situations where the line search cannot improve the solution, typically due to an incompatibility between the potential's values for energy, forces, and/or stress.

This routine attempts to minimizes the energy until the force and stress reduce below specified tolerances given a provided limit on the number of allowed steps. The code returns when convergence is achieved or no further progress can be made, either due to reaching the iteration step limit, or a stalled minimization due to line search failures.

Parameters:

  • atoms (Atoms) -- Atomic configuration to be minimized.

  • fmax (float) -- Force convergence tolerance (the magnitude of the force on each atom must be less than this for convergence)

  • steps (int) -- Maximum number of iterations for the minimization

  • variable_cell (bool) -- True to allow relaxation with respect to cell shape

  • logfile (Union[str, IO, None]) -- Log file. '-' means STDOUT

  • algorithm (type[Optimizer]) -- ASE optimizer algorithm

  • CellFilter -- Filter to use if variable_cell is requested

  • fix_symmetry (Union[bool, FixSymmetry]) -- Whether to fix the crystallographic symmetry. Can provide a FixSymmetry class here instead of detecting it on the fly

  • opt_kwargs (Dict) -- Dictionary of kwargs to pass to optimizer

  • flt_kwargs (Dict) -- Dictionary of kwargs to pass to filter (e.g. "scalar_pressure")

Return type:

bool

Returns:

Whether the minimization succeeded

kim_tools.test_driver.core._add_property_instance(property_name, disclaimer=None, property_instances=None)

Initialize a new property instance in the serialized property_instances. This wraps the kim_property.kim_property_create() function, with the simplification of setting "instance-id" automatically, as well as automatically searching for a definition file if property_name is not found.

NOTE: Is there any need to allow Test Driver authors to specify an instance-id?

Parameters:
Return type:

str

Returns:

Updated EDN-serialized list of property instances

kim_tools.test_driver.core._add_key_to_current_property_instance(property_instances, name, value, unit=None, uncertainty_info=None)

Write a key to the last element of property_instances. This wraps kim_property.kim_property_modify() with a simplified (and more restricted) interface.

Note: if the value is an array, this function will assume you want to write to the beginning of the array in every dimension.

This function is intended to write entire keys in one go, and should not be used for modifying existing keys.

WARNING! It is the developer's responsibility to make sure the array shape matches the extent specified in the property definition. This method uses fills the values of array keys as slices through the last dimension. If those slices are incomplete, kim_property automatically initializes the other elements in that slice to zero. For example, consider writing coordinates to a key with extent [":", 3]. The correct way to write a single atom would be to provide [[x, y, z]]. If you accidentally provide [[x], [y], [z]], it will fill the field with the coordinates [[x, 0, 0], [y, 0, 0], [z, 0, 0]]. This will not raise an error, only exceeding the allowed dimesnsions of the key will do so.

Parameters:

  • property_instances (str) -- An EDN-serialized list of dictionaries representing KIM Property Instances. The key will be added to the last dictionary in the list

  • name (str) -- Name of the key, e.g. "cell-cauchy-stress"

  • value (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[bool | int | float | complex | str | bytes]]) -- The value of the key. The function will attempt to convert it to a NumPy array, then use the dimensions of the resulting array. Scalars, lists, tuples, and arrays should work. Data type of the elements should be str, float, or int

  • unit (Optional[str]) -- The units

  • uncertainty_info (Optional[dict]) -- dictionary containing any uncertainty keys you wish to include. See https://openkim.org/doc/schema/properties-framework/ for the possible uncertainty key names. These must be the same dimension as value, or they may be scalars regardless of the shape of value.

Return type:

str

Returns:

Updated EDN-serialized list of property instances

exception kim_tools.test_driver.core.KIMTestDriverError(msg)

Bases: Exception

class kim_tools.test_driver.core.KIMTestDriver(model, suppr_sm_lmp_log=False, files_to_ignore_in_output=['output/pipeline.*'])

Bases: ABC

A base class for creating KIM Test Drivers. It has attributes that are likely to be useful to for most KIM tests

__kim_model_name

KIM model name, absent if a non-KIM ASE calculator was provided

Type:

Optional[str]

__calc

ASE calculator

Type:

Calculator

__output_property_instances

Property instances, possibly accumulated over multiple invocations of the Test Driver

Type:

str

__files_to_keep_in_output

List of files that were written by this class explicitly, that we won't touch when cleaning and backing up the output directory. Specified relative to 'output' directory.

Type:

List[PathLike]

__files_to_ignore_in_output

List of globs of files to ignore when handling the output directory. By default, this is set to the constant PIPELINE_EXCEPTIONS, which contains files that need to be left untouched for the OpenKIM pipeline. Top-level dotfiles are always ignored.

Type:

List[PathLike]

__token

Token that is written to TOKENPATH upon first evaluation. This is used to check that multiple Test Drivers are not being called concurrently, causing potential conflicts in the output directory

Type:

Optional[bytes]

__times_called

Count of number of times the instance has been __call__'ed, for numbering aux file archives

Type:

Optional[int]

Parameters:

  • model (Union[str, Calculator]) -- ASE calculator or KIM model name to use

  • suppr_sm_lmp_log (bool) -- Suppress writing a lammps.log

  • files_to_ignore_in_output (List[PathLike]) -- List of globs of files to ignore when handling the output directory. Top-level dotfiles are always ignored.

exception NonKIMModelError

Bases: Exception

Raised when a KIM model name is requested but is absent. This is important to handle to inform users that they are trying to run a Test Driver that requires a KIM model (e.g. a LAMMPS TD) with a non-KIM Calculator

exception MissingModelError

Bases: Exception

Raised when a model is requested but neither a self._calc nor self.kim_model_name are defined

_setup(material, **kwargs)

Empty method, for optional overrides

Return type:

None

_init_output_dir()

Initialize the output directory

Return type:

None

_archive_aux_files()

Archive aux files after a run

Return type:

None

abstract _calculate(**kwargs)

Abstract calculate method

Return type:

None

_add_property_instance(property_name, disclaimer=None)

Initialize a new property instance. NOTE: Is there any need to allow Test Driver authors to specify an instance-id?

Parameters:
Return type:

None

_add_key_to_current_property_instance(name, value, unit=None, uncertainty_info=None)

Add a key to the most recent property instance added with _add_property_instance(). If the value is an array, this function will assume you want to write to the beginning of the array in every dimension. This function is intended to write entire keys in one go, and should not be used for modifying existing keys.

WARNING! It is the developer's responsibility to make sure the array shape matches the extent specified in the property definition. This method uses kim_property.kim_property_modify, and fills the values of array keys as slices through the last dimension. If those slices are incomplete, kim_property automatically initializes the other elements in that slice to zero. For example, consider writing coordinates to a key with extent [":", 3]. The correct way to write a single atom would be to provide [[x, y, z]]. If you accidentally provide [[x], [y], [z]], it will fill the field with the coordinates [[x, 0, 0], [y, 0, 0], [z, 0, 0]]. This will not raise an error, only exceeding the allowed dimesnsions of the key will do so.

Parameters:

  • name (str) -- Name of the key, e.g. "cell-cauchy-stress"

  • value (Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[bool | int | float | complex | str | bytes]]) -- The value of the key. The function will attempt to convert it to a NumPy array, then use the dimensions of the resulting array. Scalars, lists, tuples, and arrays should work. Data type of the elements should be str, float, int, or bool

  • unit (Optional[str]) -- The units

  • uncertainty_info (Optional[dict]) -- dictionary containing any uncertainty keys you wish to include. See https://openkim.org/doc/schema/properties-framework/ for the possible uncertainty key names. These must be the same dimension as value, or they may be scalars regardless of the shape of value.

Return type:

None

_add_file_to_current_property_instance(name, filename, add_instance_id=True)

add a "file" type key-value pair to the current property instance.

Parameters:

  • name (str) -- Name of the key, e.g. "restart-file"

  • filename (PathLike) -- The path to the filename. If it is not in "$CWD/output/", the file will be moved there

  • add_instance_id (bool) -- By default, a numerical index will be added before the file extension or at the end of a file with no extension. This is to ensure files do not get overwritten when the _calculate method is called repeatedly.

Raises:

KIMTestDriverError -- If the provided filename does not exist

Return type:

None

_get_supported_lammps_atom_style()

Return the atom_style that should be used when writing LAMMPS data files. This atom_style will be compatible with the KIM model this object was instantiated with.

Return type:

str

property kim_model_name: str

Get the KIM model name

Raises:

KIMTestDriver.NonKIMModelError -- If the Test Driver is being run with a non-KIM calculator

property property_instances: Dict

Get all property instances accumulated over all calls to the Test Driver so far

property _calc: Calculator | None

Get the ASE calculator. Reinstantiate it if it's a KIM SM

property model: str | Calculator

Return the KIM model name, if present, otherwise return the ASE calculator. Useful for, for example, calling a Test Driver from another (e.g. _resolve_dependencies)

_get_serialized_property_instances()

Get the property instances computed so far in serialized EDN format

Return type:

str

_set_serialized_property_instances(property_instances)

Set the property instances from a serialized EDN string

Return type:

None

write_property_instances_to_file(filename='output/results.edn')

Write internal property instances (possibly accumulated over several calls to the Test Driver) to a file at the requested path.

Parameters:

filename -- path to write the file

Return type:

None

get_isolated_energy_per_atom(symbol)

Construct a non-periodic cell containing a single atom and compute its energy.

Args
symbol:

The chemical species

Return type:

float

Returns:

The isolated energy of a single atom

_abc_impl = <_abc._abc_data object>
kim_tools.test_driver.core._add_common_crystal_genome_keys_to_current_property_instance(property_instances, prototype_label, stoichiometric_species, a, a_unit, parameter_values=None, library_prototype_label=None, short_name=None, cell_cauchy_stress=None, cell_cauchy_stress_unit=None, temperature=None, temperature_unit='K', crystal_genome_source_structure_id=None, aflow_executable='aflow', omit_keys=None)

Write common Crystal Genome keys to the last element of property_instances. See https://openkim.org/properties/show/crystal-structure-npt for definition of the input keys. Note that the "parameter-names" key is inferred from the prototype_label input and is not an input to this function.

Parameters:

  • property_instances (str) -- An EDN-serialized list of dictionaries representing KIM Property Instances. The key will be added to the last dictionary in the list

  • aflow_executable (str) -- Path to the AFLOW executable

  • omit_keys (Optional[List[str]]) -- Which keys to omit writing

Return type:

str

Returns:

Updated EDN-serialized list of property instances

kim_tools.test_driver.core._add_property_instance_and_common_crystal_genome_keys(property_name, prototype_label, stoichiometric_species, a, a_unit, parameter_values=None, library_prototype_label=None, short_name=None, cell_cauchy_stress=None, cell_cauchy_stress_unit=None, temperature=None, temperature_unit='K', crystal_genome_source_structure_id=None, disclaimer=None, property_instances=None, aflow_executable='aflow', omit_keys=None)

Initialize a new property instance to property_instances (an empty property_instances will be initialized if not provided). It will automatically get the an "instance-id" equal to the length of property_instances after it is added. Then, write the common Crystal Genome keys to it. See https://openkim.org/properties/show/crystal-structure-npt for definition of the input keys. Note that the "parameter-names" key is inferred from the prototype_label input and is not an input to this function.

Parameters:
Return type:

str

Returns:

Updated EDN-serialized list of property instances

kim_tools.test_driver.core.get_crystal_structure_from_atoms(atoms, get_short_name=True, prim=True, aflow_np=4, aflow_executable='aflow')

By performing a symmetry analysis on an Atoms object, generate a dictionary that is a subset of the crystal-structure-npt property. See https://openkim.org/doc/schema/properties-framework/ for more information about KIM properties and how values and units are defined. The dictionary returned by this function does not necessarily constitute a complete KIM Property Instance, but the key-value pairs are in valid KIM Property format and can be inserted as-is into any single crystal Crystal Genome property.

Parameters:

  • atoms (Atoms) -- Configuration to analyze. It is assumed that the length unit is angstrom

  • get_short_name (bool) -- whether to compare against AFLOW prototype library to obtain short-name

  • prim (bool) -- whether to primitivize the atoms object first

  • aflow_np (int) -- Number of processors to use with AFLOW executable

  • aflow_executable (str) -- Path to the AFLOW executable

Return type:

Dict

Returns:

A dictionary that has the following Property Keys (possibly optionally) defined. See the crystal-structure-npt Property Definition for their meaning:

  • "stoichiometric-species"

  • "prototype-label"

  • "a"

  • "parameter-names" (inferred from "prototype-label")

  • "parameter-values"

  • "short-name"

kim_tools.test_driver.core.get_poscar_from_crystal_structure(crystal_structure, output_file=None, flat=False, addtl_args='--webpage ', aflow_executable='aflow')

Write a POSCAR coordinate file (or output it as a multiline string) from the AFLOW Prototype Designation obtained from a KIM Property Instance. The following keys from https://openkim.org/properties/show/2023-02-21/staff@noreply.openkim.org/crystal-structure-npt are used:

  • "stoichiometric-species"

  • "prototype-label"

  • "a"

  • "parameter-values" (if "prototype-label" defines a crystal with free parameters besides "a")

Note that although the keys are required to follow the schema of a KIM Property Instance (https://openkim.org/doc/schema/properties-framework/), there is no requirement or check that the input dictionary is an instance of any specific KIM Property, only that the keys required to build a crystal are present.

Parameters:

  • crystal_structure (Dict) -- Dictionary containing the required keys in KIM Property Instance format

  • output_file (Optional[str]) -- Name of the output file. If not provided, the output is returned as a string

  • flat (bool) -- whether the input dictionary is flattened

  • addtl_args (str) -- additional arguments to --proto

  • aflow_executable (str) -- path to AFLOW executable

Return type:

Optional[str]

Returns:

If output_file is not provided, a string in POSCAR format containg the primitive unit cell of the crystal as defined in http://doi.org/10.1016/j.commatsci.2017.01.017. Lengths are always in angstrom.

Raises:

AFLOW.ChangedSymmetryException -- if the symmetry of the atoms object is different from prototype_label

kim_tools.test_driver.core.get_atoms_from_crystal_structure(crystal_structure, flat=False, aflow_executable='aflow')

Generate an Atoms object from the AFLOW Prototype Designation obtained from a KIM Property Instance. The following keys from https://openkim.org/properties/show/2023-02-21/staff@noreply.openkim.org/crystal-structure-npt are used:

  • "stoichiometric-species"

  • "prototype-label"

  • "a"

  • "parameter-values" (if "prototype-label" defines a crystal with free parameters besides "a")

Note that although the keys are required to follow the schema of a KIM Property Instance (https://openkim.org/doc/schema/properties-framework/), There is no requirement or check that the input dictionary is an instance of any specific KIM Property, only that the keys required to build a crystal are present.

Parameters:

  • crystal_structure (Dict) -- Dictionary containing the required keys in KIM Property Instance format

  • flat (bool) -- whether the dictionary is flattened

  • aflow_executable (str) -- path to AFLOW executable

Return type:

Atoms

Returns:

Primitive unit cell of the crystal as defined in the AFLOW prototype standard. Lengths are always in angstrom

Raises:

AFLOW.ChangedSymmetryException -- if the symmetry of the atoms object is different from prototype_label

class kim_tools.test_driver.core.SingleCrystalTestDriver(model, suppr_sm_lmp_log=False, aflow_executable='aflow')

Bases: KIMTestDriver

A KIM test that computes property(s) of a single nominal crystal structure

__nominal_crystal_structure_npt[Dict]

An instance of the crystal-structure-npt property representing the nominal crystal structure and conditions of the current call to the Test Driver.

aflow_executable[str]

Path to the AFLOW executable

Parameters:

  • model (Union[str, Calculator]) -- ASE calculator or KIM model name to use

  • suppr_sm_lmp_log (bool) -- Suppress writing a lammps.log

  • aflow_executable (str) -- Path to AFLOW executable

_setup(material, pressure_eV_angstrom3=None, cell_cauchy_stress_eV_angstrom3=None, temperature_K=0, **kwargs)

TODO: Consider allowing arbitrary units for temp and stress?

Parameters:

  • material (Union[Atoms, Dict]) --

    An Atoms object or a KIM Property Instance specifying the nominal crystal structure that this run of the test will use. Pass one of the two following types of objects:

    Atoms object:

    Atoms object to use as the initial configuration. Note that a symmetry analysis will be performed on it and a primitive cell will be generated according to the conventions in http://doi.org/10.1016/j.commatsci.2017.01.017. This primitive cell may be rotated and translated relative to the configuration you provided.

    Property instance:

    Dictionary containing information about the nominal input crystal structure in KIM Property Instance format (e.g. from a query to the OpenKIM.org database) The following keys from https://openkim.org/properties/show/2023-02-21/staff@noreply.openkim.org/crystal-structure-npt are used:

    • "stoichiometric-species"

    • "prototype-label"

    • "a"

    • "parameter-values" (if "prototype-label" defines a crystal with free parameters besides "a")

    • "short-name" (if present)

    • "crystal-genome-source-structure-id" (if present)

    Note that although the keys are required to follow the schema of a KIM Property Instance (https://openkim.org/doc/schema/properties-framework/), There is no requirement or check that the input dictionary is an instance of any specific KIM Property, only that the keys required to build a crystal are present.

  • temperature_K (float) -- The temperature in Kelvin. This is a nominal variable, and this class simply provides recordkeeping of it. It is up to derived classes to implement actually setting the temperature of the system.

  • pressure_eV_angstrom3 (Optional[float]) -- Hydrostatic pressure in eV/angstrom^3 (ASE units). This is an alternative way of specifying the imposed stress, it will set the normal stresses to -pressure_eV_angstrom3, and shear stresses to zero. If this is specified, cell_cauchy_stress_eV_angstrom3 must not be specified.

  • cell_cauchy_stress_eV_angstrom3 (Optional[List[float]]) -- Cauchy stress on the cell in eV/angstrom^3 (ASE units) in [xx, yy, zz, yz, xz, xy] format. The base SingleCrystalTestDriver provides recordkeeping of this variable, and derived classes must implement actually imposing this stress on the system if the simulation they perform is stress-dependent. If this is specified, pressure_eV_angstrom3 must not be specified.

Return type:

None

_update_nominal_parameter_values(atoms, max_resid=None, cell_rtol=0.01, rot_rtol=0.01, rot_atol=0.01, match_library_proto=True)

Update the nominal parameter values of the nominal crystal structure from the provided Atoms object. It is assumed that the crystallographic symmetry (space group + occupied Wyckoff positions) have not changed from the initially provided structure.

The provided Atoms object MUST be a primitive cell of the crystal as defined in http://doi.org/10.1016/j.commatsci.2017.01.017. The Atoms object may be rotated, translated, and permuted, but the identity of the lattice vectors must be unchanged w.r.t. the crystallographic prototype. In other words, there must exist a permutation and translation of the fractional coordinates that enables them to match the equations defined by the prototype label.

In practical terms, this means that this function is designed to take as input a relaxed or time-averaged from MD (and folded back into the original primitive cell) copy of the Atoms object originally obtained from _get_atoms().

If finding the parameter fails, this function will raise an exception. This probably indicates a phase transition to a different symmetry, which is a normal occasional occurrence if the original structure is not stable under the interatomic potential and prescribed conditions. These exceptions should not be handled and that run of the Test Driver should be allowed to fail.

Parameters:

  • atoms (Atoms) -- Structure to analyze to get the new parameter values

  • max_resid (Optional[float]) -- Maximum residual allowed when attempting to match the fractional positions of the atoms to the crystallographic equations. If not provided, this is automatically set to 0.01*(minimum NN distance)

  • cell_rtol (float) -- Relative tolerance on cell lengths and angles. Justification for default value: AFLOW uses 0.01*(minimum NN distance) as default tolerance.

  • rot_rtol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance)

  • rot_atol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance)

  • match_library_proto (bool) -- Whether to match to library prototypes

Raises:

  • AFLOW.FailedToMatchException -- If the solution failed due to a failure to match two crystals that should be identical at some point in the solution process. This usually indicates a phase transformation

  • AFLOW.ChangedSymmetryException -- If a more definitive error indicating a phase transformation is encountered

Return type:

None

_verify_unchanged_symmetry(atoms)

Without changing the nominal state of the system, check if the provided Atoms object has the same symmetry as the nominal crystal structure associated with the current state of the Test Driver. This is defined as having the same prototype label, except for possible changes in Wyckoff letters as permitted by the space group normalizer.

Parameters:

  • atoms (Atoms) -- The structure to compare to the current nominal structure of the Test

  • Driver

Return type:

bool

Returns:

Whether or not the symmetry is unchanged

__add_poscar_to_curr_prop_inst(change_of_basis, filename, key_name)

Add a POSCAR file constructed from self.__nominal_crystal_structure_npt to the current property instance.

Parameters:
Return type:

None

_add_property_instance_and_common_crystal_genome_keys(property_name, write_stress=False, write_temp=False, stress_unit=None, temp_unit='K', disclaimer=None, omit_keys=None)

Initialize a new property instance to self.property_instances. It will automatically get the an "instance-id" equal to the length of self.property_instances after it is added. Then, write the common Crystal Genome keys to it from the attributes of this class.

Parameters:

  • property_name (str) -- The property name, e.g. "tag:staff@noreply.openkim.org,2023-02-21:property/binding-energy-crystal" or "binding-energy-crystal"

  • write_stress (Union[bool, List[float]]) -- What (if any) to write to the "cell-cauchy-stress" key. If True, write the nominal stress the Test Driver was initialized with. If a list of floats is given, write that value (it must be a length 6 list representing a stress tensor in Voigt order xx,yy,zz,yz,xz,xy). If a list is specified, you must also specify stress_unit.

  • write_temp (Union[bool, float]) -- What (if any) to write to the "temperature" key. If True, write the nominal temperature the Test Driver was initialized with. If float is given, write that value.

  • stress_unit (Optional[str]) -- Unit of stress. Required if a stress tensor is specified in write_stress.

  • temp_unit (str) -- Unit of temperature. Defaults to K.

  • disclaimer (Optional[str]) -- An optional disclaimer commenting on the applicability of this result, e.g. "This relaxation did not reach the desired tolerance."

  • omit_keys (Optional[List[str]]) -- Which keys to omit writing

Return type:

None

_get_temperature(unit='K')

Get the nominal temperature

Parameters:

unit (str) -- The requested unit for the output. Must be understood by the GNU units utility

Return type:

float

_get_cell_cauchy_stress(unit='eV/angstrom^3')

Get the nominal stress in [xx,yy,zz,yz,xz,xy] format

Parameters:

unit (str) -- The requested unit for the output. Must be understood by the GNU units utility

Return type:

List[float]

_get_pressure(unit='eV/angstrom^3', enforce_hydrostatic=True)

Get the nominal pressure (negative 1/3 trace of the cauchy stress)

Parameters:

  • unit (str) -- The requested unit for the output. Must be understood by the GNU units utility

  • enforce_hydrostatic (bool) -- If true, then calling this function when the nominal stress is non-hydrostatic will raise an error

Raises:

KIMTestDriverError -- When enforce_hydrostatic=True and the nominal stress isn't hydrostatic

Return type:

float

_get_mass_density(unit='amu/angstrom^3')

Get the mass density of the current nominal state of the system, according to the masses defined in ase.data.atomic_masses

Parameters:

unit (str) -- The requested units

Return type:

float

Returns:

The mass density of the crystal

_get_nominal_crystal_structure_npt()

Get the dictionary returning the current nominal state of the system.

Return type:

Dict

Returns:

An instance of the crystal-structure-npt OpenKIM property containing a symmetry-reduced description of the nominal crystal structure.

deduplicate_property_instances(allow_rotation=False, aflow_np=4, rot_rtol=0.01, rot_atol=0.01)

In the internally stored property instances, deduplicate any repeated crystal structures for each property id and merge their "crystal-genome-source-structure-id" keys.

WARNING: Only the crystal structures are checked. If you for some reason have a property that can reasonably report different non-structural values for the same atomic configuration, this will delete the extras!

Parameters:

  • allow_rotation (bool) -- Whether or not structures that are rotated by a rotation that is not in the crystal's point group are considered identical

  • aflow_np (int) -- Number of processors to use to run the AFLOW executable

  • rot_rtol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance). Used only if allow_rotation is False

  • rot_atol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance). Used only if allow_rotation is False

Return type:

None

_set_serialized_property_instances(property_instances)

An override to prevent SingleCrystalTestDriver derived classes from setting property instances directly

Return type:

None

_get_atoms(change_of_basis='primitive')

Get the atomic configuration representing the nominal crystal, with a calculator already attached.

Parameters:

change_of_basis (Union[str, _Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, bytes, _NestedSequence[bool | int | float | complex | str | bytes]]) --

Specify the desired unit cell. The default, "primitive", gives the cell as defined in the AFLOW prototype standard. "conventional" gives the conventional cell defined therein.

Alternatively, provide an arbitrary change of basis matrix P as defined in ITA 1.5.1.2, with the above-defined primitive cell corresponding to the "old basis" and the returned Atoms object being in the "new basis".

See the docstring for kim_tools.symmetry_util.core.change_of_basis_atoms() for more information on how to define the change of basis.

Return type:

Atoms

Returns:

Unit cell of the crystal. Lengths are always in angstrom

get_nominal_prototype_label()
Return type:

str

get_nominal_space_group_number()
Return type:

int

get_nominal_stoichiometric_species()
Return type:

List[str]

get_nominal_stoichiometry()
Return type:

List[int]

get_nominal_a()
Return type:

float

get_nominal_parameter_names()
Return type:

List[str]

get_nominal_parameter_values()
Return type:

List[float]

get_nominal_short_name()
Return type:

List[str]

get_nominal_library_prototype_label()
Return type:

str

get_atom_indices_for_each_wyckoff_orb()

Get a list of dictionaries containing the atom indices of each Wyckoff orbit.

Return type:

List[Dict]

Returns:

The information is in this format -- [{"letter":"a", "indices":[0,1]}, ... ]

get_input_rotation()
Return type:

Union[_Buffer, _SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[bool | int | float | complex | str | bytes], None]

Returns:

If the Test Driver was called with an Atoms object, the nominal crystal structure may be rotated w.r.t. the input. This returns the Cartesian rotation to transform the Atoms input to the internal nominal crystal structure. I.e., if you want to get computed tensor properties in the same orientation as your input, you should rotate the reported tensors by the transpose of this rotation.

_abc_impl = <_abc._abc_data object>
kim_tools.test_driver.core.query_crystal_structures(stoichiometric_species, prototype_label=None, short_name=None, cell_cauchy_stress_eV_angstrom3=None, temperature_K=0, kim_model_name=None)

Query for all equilibrium parameter sets for this species combination and, optionally, crystal structure specified by prototype_label and/or short_name in the KIM database. This is a utility function for running the test outside of the OpenKIM pipeline. In the OpenKIM pipeline, this information is delivered to the test driver through the runner script.

Parameters:

  • stoichiometric_species (List[str]) -- List of unique species in the crystal. Required part of the Crystal Genome designation.

  • short_name (Optional[str]) -- short name of the crystal, e.g. "Hexagonal Close Packed". This will be searched as a case-insensitive regex, so partial matches will be returned. The list of possible shortnames is taken by postprocessing README_PROTO.TXT from the AFLOW software and packaged with kim-tools for reproducibility. To see the exact list of possible short names, call kim_tools.aflow_util.core.read_shortnames() and inspect the values of the returned dictionary. Note that a given short name corresponds to an exact set of parameters (with some tolerance), except the overall scale of the crystal. For example, "Hexagonal Close Packed" will return only structures with a c/a close to 1.63 (actually close packed), not any structure with the same symmetry as HCP as is sometimes colloquially understood. TODO: consider adding the same expanded logic we have on the website that searches for any crystal with the symmetry corresponding to a given shortname, i.e. invalidating the last caveat given above.

  • prototype_label (Optional[str]) -- AFLOW prototype label for the crystal.

  • cell_cauchy_stress_eV_angstrom3 (Optional[List[float]]) -- Cauchy stress on the cell in eV/angstrom^3 (ASE units) in [xx,yy,zz,yz,xz,xy] format

  • temperature_K (float) -- The temperature in Kelvin

  • kim_model_name (Optional[str]) -- KIM model name. If not provided, RD will be queried instead

Return type:

List[Dict]

Returns:

List of kim property instances matching the query in the OpenKIM.org database

kim_tools.test_driver.core.detect_unique_crystal_structures(crystal_structures, allow_rotation=False, aflow_np=4, rot_rtol=0.01, rot_atol=0.01, aflow_executable='aflow')

Detect which of the provided crystal structures is unique

Parameters:

  • crystal_structures (Union[List[Dict], Dict]) -- A list of dictionaries in KIM Property format, each containing the Crystal Genome keys required to build a structure, namely: "stoichiometric-species", "prototype-label", "a", and, if the prototype has free parameters, "parameter-values". These dictionaries are not required to be complete KIM Property Instances, e.g. the keys "property-id", "instance-id" and "meta" can be absent. Alternatively, this can be a dictionary of dictionaries with integers as keys, for the recursive call.

  • allow_rotation (bool) -- Whether or not structures that are rotated by a rotation that is not in the crystal's point group are considered identical

  • aflow_np (int) -- Number of processors to use to run the AFLOW executable

  • rot_rtol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance). Used only if allow_rotation is False

  • rot_atol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance). Used only if allow_rotation is False

  • aflow_executable -- Path to AFLOW executable

Return type:

Dict

Returns:

Dictionary with keys corresponding to indices of unique structures and values being lists of indices of their duplicates

kim_tools.test_driver.core._compare_noncrystallographic_fields(prop_inst_1, prop_inst_2)

Check if two property instances are the same, ignoring the XtalG crystallographic fields which will be checked separately.

Return type:

bool

kim_tools.test_driver.core.get_deduplicated_property_instances(property_instances, allow_rotation=False, aflow_np=4, rot_rtol=0.01, rot_atol=0.01, aflow_executable='aflow')

Given a list of dictionaries constituting XtalG Property instances, remove any duplicates and merge their "crystal-genome-source-structure-id" keys.

Parameters:

  • property_instances (List[Dict]) -- The list of KIM Property Instances to deduplicate

  • allow_rotation (bool) -- Whether or not structures that are rotated by a rotation that is not in the crystal's point group are considered identical

  • aflow_np (int) -- Number of processors to use to run the AFLOW executable

  • rot_rtol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance). Used only if allow_rotation is False

  • rot_atol (float) -- Parameter to pass to numpy.allclose() for compariong fractional rotations. Default value chosen to be commensurate with AFLOW default distance tolerance of 0.01*(NN distance). Used only if allow_rotation is False

  • aflow_executable (str) -- Path to aflow executable

Return type:

List[Dict]

Returns:

The deduplicated property instances

kim_tools.test_driver.core.crystal_input_from_test_generator_line(test_generator_line, kim_model_name)

Produce a list of dictionaries of kwargs for a Crystal Genome Test Driver invocation from a line in its test_generator.json

Return type:

List[Dict]

Module contents