kim-tools 0.2.3__tar.gz → 0.2.5__tar.gz

{kim_tools-0.2.3/kim_tools.egg-info → kim_tools-0.2.5}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: kim-tools
-Version: 0.2.3
+Version: 0.2.5
 Summary: Base classes and helper routines for writing KIM Tests
-Author-email: ilia Nikiforov <nikif002@umn.edu>, Ellad Tadmor <tadmor@umn.edu>, Claire Waters <bwaters@umn.edu>, "Daniel S. Karls" <karl0100umn@gmail.com>, Matt Bierbaum <matt.bierbaum@gmail.com>, Eric Fuemmeler <efuemmel@umn.edu>
+Author-email: ilia Nikiforov <nikif002@umn.edu>, Ellad Tadmor <tadmor@umn.edu>, Claire Waters <bwaters@umn.edu>, "Daniel S. Karls" <karl0100umn@gmail.com>, Matt Bierbaum <matt.bierbaum@gmail.com>, Eric Fuemmeler <efuemmel@umn.edu>, Philipp Hoellmer <ph2484@nyu.edu>, Guanming Zhang <gz2241@nyu.edu>
 Maintainer-email: ilia Nikiforov <nikif002@umn.edu>
 Project-URL: Homepage, https://kim-tools.readthedocs.io
 Project-URL: Issues, https://github.com/openkim/kim-tools/issues
@@ -24,9 +24,16 @@ Requires-Dist: sympy>=1.13.2
 Requires-Dist: numpy>=1.13.1
 Requires-Dist: scipy>=1.3.0
 Requires-Dist: jinja2>=2.7.2
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
 Dynamic: license-file
 
 # kim-tools
 
+![testing](https://github.com/openkim/kim-tools/actions/workflows/testing.yml/badge.svg)
+[![docs](https://app.readthedocs.org/projects/kim-tools/badge/?version=latest)](https://kim-tools.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/kim-tools.svg)](https://pypi.org/project/kim-tools/)
+
 KIMTestDriver and SingleCrystalTestDriver classes for creating OpenKIM Test Drivers, and helper routines for writing
 KIM Tests and Verification Checks. Documentation at https://kim-tools.readthedocs.io.

kim_tools-0.2.5/README.md

@@ -0,0 +1,8 @@
+# kim-tools
+
+![testing](https://github.com/openkim/kim-tools/actions/workflows/testing.yml/badge.svg)
+[![docs](https://app.readthedocs.org/projects/kim-tools/badge/?version=latest)](https://kim-tools.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/kim-tools.svg)](https://pypi.org/project/kim-tools/)
+
+KIMTestDriver and SingleCrystalTestDriver classes for creating OpenKIM Test Drivers, and helper routines for writing
+KIM Tests and Verification Checks. Documentation at https://kim-tools.readthedocs.io.

{kim_tools-0.2.3 → kim_tools-0.2.5}/kim_tools/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 from .aflow_util import *
 from .aflow_util import __all__ as aflow_all

{kim_tools-0.2.3 → kim_tools-0.2.5}/kim_tools/aflow_util/core.py

@@ -12,7 +12,7 @@ from math import acos, cos, degrees, radians, sin, sqrt
 from os import PathLike
 from random import random
 from tempfile import NamedTemporaryFile
-from typing import Any, Dict, List, Optional, Tuple, Union
+from typing import Any, Callable, Dict, List, Optional, Tuple, Union
 
 import ase
 import numpy as np
@@ -63,6 +63,8 @@ __all__ = [
     "AFLOW",
 ]
 
+AFLOW_EXECUTABLE = "aflow"
+
 
 class IncorrectSpaceGroupException(Exception):
     """
@@ -113,7 +115,7 @@ class EquivalentAtomSet:
 
 
 def write_tmp_poscar_from_atoms_and_run_function(
-    atoms: Atoms, function: callable, *args, **kwargs
+    atoms: Atoms, function: Callable, *args, **kwargs
 ) -> Any:
     """
     Write the Atoms file to a NamedTemporaryFile and run 'function' on it.
@@ -141,7 +143,7 @@ def check_number_of_atoms(
     has the correct number of atoms according to prototype_label
 
     Raises:
-    IncorrectNumAtomsException
+        IncorrectNumAtomsException
     """
     prototype_label_list = prototype_label.split("_")
     pearson = prototype_label_list[1]
@@ -267,8 +269,9 @@ def get_equivalent_atom_sets_from_prototype_and_atom_map(
     `atoms`, and `prototype_label` is the detected prototype label
 
     Args:
-        sort_atoms: If `atom_map` was obtained by sorting `atoms` before writing it to
-        POSCAR, set this to True
+        sort_atoms:
+            If `atom_map` was obtained by sorting `atoms` before writing it to
+            POSCAR, set this to True
     """
 
     if sort_atoms:
@@ -741,7 +744,10 @@ class AFLOW:
         """
 
     def __init__(
-        self, aflow_executable: str = "aflow", aflow_work_dir: str = "", np: int = 4
+        self,
+        aflow_executable: str = AFLOW_EXECUTABLE,
+        aflow_work_dir: str = "",
+        np: int = 4,
     ):
         """
         Args:
@@ -752,7 +758,7 @@ class AFLOW:
         self.aflow_executable = aflow_executable
 
         try:
-            subprocess.check_output(["aflow", "--proto=A_cF4_225_a"])
+            subprocess.check_output([aflow_executable, "--proto=A_cF4_225_a"])
         except Exception:
             raise self.AFLOWNotFoundException(
                 "Failed to run an AFLOW test command. It is likely "
@@ -1209,9 +1215,10 @@ class AFLOW:
             sort_atoms2: Whether to sort atoms2 before comparing.
 
         Returns:
-            Tuple of arrays in the order:
-            basis transformation, rotation, origin shift, atom_map
-            atom_map[index_in_structure_1] = index_in_structure_2
+            * basis transformation
+            * rotation
+            * origin shift
+            * atom_map (atom_map[index_in_structure_1] = index_in_structure_2)
 
         Raises:
             AFLOW.FailedToMatchException: if AFLOW fails to match the crystals
@@ -1494,9 +1501,11 @@ class AFLOW:
                 nl_len = nl.size
                 cov_mult += 1
             # set the maximum error to 1% of NN distance to follow AFLOW convention
-            max_resid = nl.min() * 0.01
+            # rescale by cube root of cell volume to get rough conversion from
+            # cartesian to fractional
+            max_resid = nl.min() * 0.01 * atoms.get_volume() ** (-1 / 3)
             logger.info(
-                "Automatically set max residual for solving position "
+                "Automatically set max fractional residual for solving position "
                 f"equations to {max_resid}"
             )
 

{kim_tools-0.2.3 → kim_tools-0.2.5}/kim_tools/symmetry_util/core.py

@@ -7,13 +7,17 @@ import logging
 import os
 from itertools import product
 from math import ceil
-from typing import Dict, List, Union
+from typing import Dict, List, Optional, Tuple, Union
 
+import matplotlib.pyplot as plt
 import numpy as np
+import numpy.typing as npt
 from ase import Atoms
 from ase.cell import Cell
-from ase.geometry import get_duplicate_atoms
-from numpy.typing import ArrayLike
+from ase.geometry import get_distances, get_duplicate_atoms
+from matplotlib.backends.backend_pdf import PdfPages
+from scipy.stats import kstest
+from sklearn.decomposition import PCA
 from sympy import Matrix, cos, matrix2numpy, sin, sqrt, symbols
 
 logger = logging.getLogger(__name__)
@@ -85,6 +89,12 @@ class IncorrectNumAtomsException(Exception):
     """
 
 
+class PeriodExtensionException(Exception):
+    """
+    Raised when a period-extending phase transition is detected.
+    """
+
+
 def _check_space_group(sgnum: Union[int, str]):
     try:
         assert 1 <= int(sgnum) <= 230
@@ -96,8 +106,8 @@ def _check_space_group(sgnum: Union[int, str]):
 
 
 def cartesian_to_fractional_itc_rotation_from_ase_cell(
-    cart_rot: ArrayLike, cell: ArrayLike
-) -> ArrayLike:
+    cart_rot: npt.ArrayLike, cell: npt.ArrayLike
+) -> npt.ArrayLike:
     """
     Convert Cartesian to fractional rotation. Read the arguments and returns carefully,
     as there is some unfortunate mixing of row and columns because of the different
@@ -132,8 +142,8 @@ def cartesian_to_fractional_itc_rotation_from_ase_cell(
 
 
 def fractional_to_cartesian_itc_rotation_from_ase_cell(
-    frac_rot: ArrayLike, cell: ArrayLike
-) -> ArrayLike:
+    frac_rot: npt.ArrayLike, cell: npt.ArrayLike
+) -> npt.ArrayLike:
     """
     Convert fractional to Cartesian rotation. Read the arguments and returns carefully,
     as there is some unfortunate mixing of row and columns because of the different
@@ -168,9 +178,9 @@ def fractional_to_cartesian_itc_rotation_from_ase_cell(
 
 
 def cartesian_rotation_is_in_point_group(
-    cart_rot: ArrayLike,
+    cart_rot: npt.ArrayLike,
     sgnum: Union[int, str],
-    cell: ArrayLike,
+    cell: npt.ArrayLike,
     rtol: float = 1e-2,
     atol: float = 1e-2,
 ) -> bool:
@@ -215,7 +225,7 @@ def cartesian_rotation_is_in_point_group(
     return False
 
 
-def get_cell_from_poscar(poscar: os.PathLike) -> ArrayLike:
+def get_cell_from_poscar(poscar: os.PathLike) -> npt.ArrayLike:
     """
     Extract the unit cell from a POSCAR file, including the specified scaling
     """
@@ -437,7 +447,7 @@ def get_symbolic_cell_from_formal_bravais_lattice(
 
 def get_change_of_basis_matrix_to_conventional_cell_from_formal_bravais_lattice(
     formal_bravais_lattice: str,
-) -> ArrayLike:
+) -> npt.ArrayLike:
     """
     Get a change of basis matrix **P** as defined in ITA 1.5.1.2, with "old basis"
     being the primitive cell of the provided Bravais lattice, and the "new basis" being
@@ -498,7 +508,7 @@ def get_change_of_basis_matrix_to_conventional_cell_from_formal_bravais_lattice(
     return np.round(change_of_basis_matrix)
 
 
-def change_of_basis_atoms(atoms: Atoms, change_of_basis: ArrayLike) -> Atoms:
+def change_of_basis_atoms(atoms: Atoms, change_of_basis: npt.ArrayLike) -> Atoms:
     """
     Perform an arbitrary basis change on an ``Atoms`` object, duplicating or cropping
     atoms as needed. A basic check is made that the determinant of ``change_of_basis``
@@ -506,7 +516,7 @@ def change_of_basis_atoms(atoms: Atoms, change_of_basis: ArrayLike) -> Atoms:
     that ``change_of_basis`` is appropriate for the particuar crystal described by
     ``atoms``, which is up to the user.
 
-    NOTE: This requires ASE >= 3.25 to delete atoms that are close across PBCs
+    TODO: Incorporate :func:`kstest_reduced_distances` into this function
 
     Args:
         atoms:
@@ -600,3 +610,176 @@ def get_primitive_genpos_ops(sgnum: Union[int, str]) -> List[Dict]:
     _check_space_group(sgnum)
     with open(os.path.join(DATA_DIR, "primitive_GENPOS_ops.json")) as f:
         return np.asarray(json.load(f)[str(sgnum)])
+
+
+def reduce_and_avg(
+    atoms: Atoms, repeat: Tuple[int, int, int]
+) -> Tuple[Atoms, npt.NDArray]:
+    """
+    TODO: Upgrade :func:`change_of_basis_atoms` to provide the distances
+    array, obviating this function
+
+    Function to reduce all atoms to the original unit cell position.
+
+    Args:
+        atoms:
+            The supercell to reduce
+        repeat:
+            The number of repeats of each unit cell vector in the
+            provided supercell
+
+    Returns:
+        * The reduced unit cell
+        * An array of displacement vectors. First dimension: index of reference atom
+          in reduced cell. Second dimension: index of atom in provided supercell.
+          Third dimension: x, y, z
+    """
+    new_atoms = atoms.copy()
+
+    cell = new_atoms.get_cell()
+
+    # Divide each unit vector by its number of repeats.
+    # See
+    # https://stackoverflow.com/questions/19602187/numpy-divide-each-row-by-a-vector-element.
+    cell = cell / np.array(repeat)[:, None]
+
+    # Decrease size of cell in the atoms object.
+    new_atoms.set_cell(cell)
+    new_atoms.set_pbc((True, True, True))
+
+    # Set averaging factor
+    M = np.prod(repeat)
+
+    # Wrap back the repeated atoms on top of
+    # the reference atoms in the original unit cell.
+    positions = new_atoms.get_positions(wrap=True)
+
+    number_atoms = len(new_atoms)
+    original_number_atoms = number_atoms // M
+    assert number_atoms == original_number_atoms * M
+    avg_positions_in_prim_cell = np.zeros((original_number_atoms, 3))
+    positions_in_prim_cell = np.zeros((number_atoms, 3))
+
+    # Start from end of the atoms
+    # because we will remove all atoms except the reference ones.
+    for i in reversed(range(number_atoms)):
+        if i >= original_number_atoms:
+            # Get the distance to the reference atom in the original unit cell with the
+            # minimum image convention.
+            distance = new_atoms.get_distance(
+                i % original_number_atoms, i, mic=True, vector=True
+            )
+            # Get the position that has the closest distance to
+            # the reference atom in the original unit cell.
+            position_i = positions[i % original_number_atoms] + distance
+            # Remove atom from atoms object.
+            new_atoms.pop()
+        else:
+            # Atom was part of the original unit cell.
+            position_i = positions[i]
+        # Average
+        avg_positions_in_prim_cell[i % original_number_atoms] += position_i / M
+        positions_in_prim_cell[i] = position_i
+
+    new_atoms.set_positions(avg_positions_in_prim_cell)
+
+    # Calculate the distances.
+    distances = np.empty((original_number_atoms, M, 3))
+    for i in range(number_atoms):
+        dr, _ = get_distances(
+            positions_in_prim_cell[i],
+            avg_positions_in_prim_cell[i % original_number_atoms],
+            cell=new_atoms.get_cell(),
+            pbc=True,
+        )
+        # dr is a distance matrix, here we only have one distance
+        assert dr.shape == (1, 1, 3)
+        distances[i % original_number_atoms, i // original_number_atoms] = dr[0][0]
+
+    return new_atoms, distances
+
+
+def kstest_reduced_distances(
+    reduced_distances: npt.NDArray,
+    significance_level: float = 0.05,
+    plot_filename: Optional[str] = None,
+    number_bins: Optional[int] = None,
+) -> None:
+    """
+    TODO: Incorporate this into :func:`change_of_basis_atoms`
+
+    Function to test whether the reduced atom positions are normally distributed
+    around their average.
+
+    Args:
+        reduced_distances:
+            Distance array provided by :func:`reduce_and_avg`
+        significance_level:
+            Significance level for Kolmogorov-Smirnov
+        plot_filename:
+        number_bins:
+            Number of bins for plot
+
+    Raises:
+        PeriodExtensionException:
+            If a non-normal distribution is detected
+    """
+    assert len(reduced_distances.shape) == 3
+    assert reduced_distances.shape[2] == 3
+
+    if plot_filename is not None:
+        if number_bins is None:
+            raise ValueError(
+                "number_bins must be specified if plot_filename is specified"
+            )
+        if not plot_filename.endswith(".pdf"):
+            raise ValueError(f"{plot_filename} is not a PDF file")
+        with PdfPages(plot_filename) as pdf:
+            for i in range(reduced_distances.shape[0]):
+                fig, axs = plt.subplots(1, 3, figsize=(10.0, 4.0))
+                for j in range(reduced_distances.shape[2]):
+                    axs[j].hist(reduced_distances[i, :, j], bins=number_bins)
+                    axs[j].set_xlabel(f"$x_{j}$")
+                axs[0].set_ylabel("Counts")
+                fig.suptitle(f"Atom {i}")
+                pdf.savefig()
+    else:
+        if number_bins is not None:
+            raise ValueError(
+                "number_bins must not be specified if plot_filename is not specified"
+            )
+
+    p_values = np.empty((reduced_distances.shape[0], reduced_distances.shape[2]))
+    for i in range(reduced_distances.shape[0]):
+        atom_distances = reduced_distances[i]
+
+        # Perform PCA on the xyz distribution.
+        pca = PCA(n_components=atom_distances.shape[1])
+        pca_components = pca.fit_transform(atom_distances)
+        assert (
+            pca_components.shape == atom_distances.shape == reduced_distances.shape[1:]
+        )
+
+        # Test each component with a KS test.
+        for j in range(pca_components.shape[1]):
+            component = pca_components[:, j]
+            component_mean = np.mean(component)
+            assert abs(component_mean) < 1.0e-7
+            component_std = np.std(component)
+            # Normalize component
+            normalized_component = (component - component_mean) / component_std
+            assert abs(np.mean(normalized_component)) < 1.0e-7
+            assert abs(np.std(normalized_component) - 1.0) < 1.0e-7
+            res = kstest(normalized_component, "norm")
+            p_values[i, j] = res.pvalue
+
+    if np.any(p_values <= significance_level):
+        raise PeriodExtensionException(
+            "Detected non-normal distribution of reduced atom positions around their "
+            f"average (smallest p value {np.min(p_values)})."
+        )
+    else:
+        print(
+            "Detected normal distribution or reduced atom positions around their "
+            f"average (smallest p value {np.min(p_values)})."
+        )

{kim_tools-0.2.3 → kim_tools-0.2.5}/kim_tools/test_driver/core.py

@@ -65,6 +65,7 @@ from ..aflow_util import (
     get_space_group_number_from_prototype,
     prototype_labels_are_equivalent,
 )
+from ..aflow_util.core import AFLOW_EXECUTABLE
 from ..kimunits import convert_list, convert_units
 from ..symmetry_util import (
     cartesian_rotation_is_in_point_group,
@@ -464,7 +465,7 @@ class KIMTestDriver(ABC):
     to be useful to for most KIM tests
 
     Attributes:
-        __kim_model_name (str, optional):
+        __kim_model_name (Optional[str]):
             KIM model name, absent if a non-KIM ASE calculator was provided
         __calc (:obj:`~ase.calculators.calculator.Calculator`):
             ASE calculator
@@ -563,7 +564,8 @@ class KIMTestDriver(ABC):
     ) -> None:
         """
         Add a key to the most recent property instance added with
-        :func:`~kim_tools.KIMTestDriver._add_property_instance`. If the value is an
+        :func:`~kim_tools.test_driver.core.KIMTestDriver._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.
@@ -721,15 +723,16 @@ def _add_common_crystal_genome_keys_to_current_property_instance(
     prototype_label: str,
     stoichiometric_species: List[str],
     a: float,
+    a_unit: str,
     parameter_values: Optional[List[float]] = None,
     library_prototype_label: Optional[Union[List[str], str]] = None,
     short_name: Optional[Union[List[str], str]] = None,
     cell_cauchy_stress: Optional[List[float]] = None,
+    cell_cauchy_stress_unit: Optional[str] = None,
     temperature: Optional[float] = None,
+    temperature_unit: Optional[str] = "K",
     crystal_genome_source_structure_id: Optional[List[List[str]]] = None,
-    a_unit: str = "angstrom",
-    cell_cauchy_stress_unit: str = "eV/angstrom^3",
-    temperature_unit: str = "K",
+    aflow_executable: str = AFLOW_EXECUTABLE,
 ) -> str:
     """
     Write common Crystal Genome keys to the last element of ``property_instances``. See
@@ -741,6 +744,8 @@ def _add_common_crystal_genome_keys_to_current_property_instance(
         property_instances:
             An EDN-serialized list of dictionaries representing KIM Property Instances.
             The key will be added to the last dictionary in the list
+        aflow_executable:
+            Path to the AFLOW executable
 
     Returns:
         Updated EDN-serialized list of property instances
@@ -756,7 +761,7 @@ def _add_common_crystal_genome_keys_to_current_property_instance(
     )
 
     # get parameter names
-    aflow = AFLOW()
+    aflow = AFLOW(aflow_executable=aflow_executable)
     aflow_parameter_names = aflow.get_param_names_from_prototype(prototype_label)
     if parameter_values is None:
         if len(aflow_parameter_names) > 1:
@@ -795,6 +800,8 @@ def _add_common_crystal_genome_keys_to_current_property_instance(
                 "Please specify the Cauchy stress as a 6-dimensional vector in Voigt "
                 "order [xx, yy, zz, yz, xz, xy]"
             )
+        if cell_cauchy_stress_unit is None:
+            raise KIMTestDriver("Please provide a `cell_cauchy_stress_unit`")
         property_instances = _add_key_to_current_property_instance(
             property_instances,
             "cell-cauchy-stress",
@@ -803,6 +810,8 @@ def _add_common_crystal_genome_keys_to_current_property_instance(
         )
 
     if temperature is not None:
+        if temperature_unit is None:
+            raise KIMTestDriver("Please provide a `temperature_unit`")
         property_instances = _add_key_to_current_property_instance(
             property_instances, "temperature", temperature, temperature_unit
         )
@@ -822,17 +831,18 @@ def _add_property_instance_and_common_crystal_genome_keys(
     prototype_label: str,
     stoichiometric_species: List[str],
     a: float,
+    a_unit: str,
     parameter_values: Optional[List[float]] = None,
     library_prototype_label: Optional[Union[List[str], str]] = None,
     short_name: Optional[Union[List[str], str]] = None,
     cell_cauchy_stress: Optional[List[float]] = None,
+    cell_cauchy_stress_unit: Optional[str] = None,
     temperature: Optional[float] = None,
+    temperature_unit: Optional[str] = "K",
     crystal_genome_source_structure_id: Optional[List[List[str]]] = None,
-    a_unit: str = "angstrom",
-    cell_cauchy_stress_unit: str = "eV/angstrom^3",
-    temperature_unit: str = "K",
     disclaimer: Optional[str] = None,
     property_instances: Optional[str] = None,
+    aflow_executable: str = AFLOW_EXECUTABLE,
 ) -> str:
     """
     Initialize a new property instance to ``property_instances`` (an empty
@@ -853,6 +863,8 @@ def _add_property_instance_and_common_crystal_genome_keys(
             "This relaxation did not reach the desired tolerance."
         property_instances:
             A pre-existing EDN-serialized list of KIM Property instances to add to
+        aflow_executable:
+            Path to the AFLOW executable
 
     Returns:
             Updated EDN-serialized list of property instances
@@ -861,24 +873,29 @@ def _add_property_instance_and_common_crystal_genome_keys(
         property_name, disclaimer, property_instances
     )
     return _add_common_crystal_genome_keys_to_current_property_instance(
-        property_instances,
-        prototype_label,
-        stoichiometric_species,
-        a,
-        parameter_values,
-        library_prototype_label,
-        short_name,
-        cell_cauchy_stress,
-        temperature,
-        crystal_genome_source_structure_id,
-        a_unit,
-        cell_cauchy_stress_unit,
-        temperature_unit,
+        property_instances=property_instances,
+        prototype_label=prototype_label,
+        stoichiometric_species=stoichiometric_species,
+        a=a,
+        a_unit=a_unit,
+        parameter_values=parameter_values,
+        library_prototype_label=library_prototype_label,
+        short_name=short_name,
+        temperature=temperature,
+        temperature_unit=temperature_unit,
+        crystal_genome_source_structure_id=crystal_genome_source_structure_id,
+        cell_cauchy_stress_unit=cell_cauchy_stress_unit,
+        cell_cauchy_stress=cell_cauchy_stress,
+        aflow_executable=aflow_executable,
     )
 
 
 def get_crystal_structure_from_atoms(
-    atoms: Atoms, get_short_name: bool = True, prim: bool = True, aflow_np: int = 4
+    atoms: Atoms,
+    get_short_name: bool = True,
+    prim: bool = True,
+    aflow_np: int = 4,
+    aflow_executable: str = AFLOW_EXECUTABLE,
 ) -> Dict:
     """
     By performing a symmetry analysis on an :class:`~ase.Atoms` object, generate a
@@ -896,6 +913,8 @@ def get_crystal_structure_from_atoms(
             whether to compare against AFLOW prototype library to obtain short-name
         prim: whether to primitivize the atoms object first
         aflow_np: Number of processors to use with AFLOW executable
+        aflow_executable:
+            Path to the AFLOW executable
 
     Returns:
         A dictionary that has the following Property Keys (possibly optionally) defined.
@@ -912,7 +931,7 @@ def get_crystal_structure_from_atoms(
         - "short-name"
 
     """
-    aflow = AFLOW(np=aflow_np)
+    aflow = AFLOW(aflow_executable=aflow_executable, np=aflow_np)
 
     proto_des = aflow.get_prototype_designation_from_atoms(atoms, prim=prim)
     library_prototype_label, short_name = (
@@ -933,16 +952,21 @@ def get_crystal_structure_from_atoms(
         prototype_label=proto_des["aflow_prototype_label"],
         stoichiometric_species=sorted(list(set(atoms.get_chemical_symbols()))),
         a=a,
+        a_unit="angstrom",
         parameter_values=parameter_values,
         library_prototype_label=library_prototype_label,
         short_name=short_name,
+        aflow_executable=aflow_executable,
     )
 
     return kim_edn.loads(property_instances)[0]
 
 
 def get_poscar_from_crystal_structure(
-    crystal_structure: Dict, output_file: Optional[str] = None, flat: bool = False
+    crystal_structure: Dict,
+    output_file: Optional[str] = None,
+    flat: bool = False,
+    aflow_executable: str = AFLOW_EXECUTABLE,
 ) -> Optional[str]:
     """
     Write a POSCAR coordinate file (or output it as a multiline string) from the AFLOW
@@ -968,13 +992,15 @@ def get_poscar_from_crystal_structure(
             Name of the output file. If not provided, the output is returned as a string
         flat:
             whether the input dictionary is flattened
+        aflow_executable:
+            path to AFLOW executable
     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``
+        AFLOW.ChangedSymmetryException:
+            if the symmetry of the atoms object is different from ``prototype_label``
     """
     if flat:
         prototype_label = crystal_structure["prototype-label.source-value"]
@@ -993,7 +1019,7 @@ def get_poscar_from_crystal_structure(
             "source-value"
         ]
 
-    aflow = AFLOW()
+    aflow = AFLOW(aflow_executable=aflow_executable)
     aflow_parameter_names = aflow.get_param_names_from_prototype(prototype_label)
 
     # Atoms objects are always in angstrom
@@ -1035,7 +1061,9 @@ def get_poscar_from_crystal_structure(
 
 
 def get_atoms_from_crystal_structure(
-    crystal_structure: Dict, flat: bool = False
+    crystal_structure: Dict,
+    flat: bool = False,
+    aflow_executable: str = AFLOW_EXECUTABLE,
 ) -> Atoms:
     """
     Generate an :class:`~ase.Atoms` object from the AFLOW Prototype Designation obtained
@@ -1059,6 +1087,8 @@ def get_atoms_from_crystal_structure(
             Dictionary containing the required keys in KIM Property Instance format
         flat:
             whether the dictionary is flattened
+        aflow_executable:
+            path to AFLOW executable
 
     Returns:
         Primitive unit cell of the crystal as defined in the
@@ -1070,7 +1100,9 @@ def get_atoms_from_crystal_structure(
             if the symmetry of the atoms object is different from ``prototype_label``
     """
     try:
-        poscar_string = get_poscar_from_crystal_structure(crystal_structure, flat=flat)
+        poscar_string = get_poscar_from_crystal_structure(
+            crystal_structure, flat=flat, aflow_executable=aflow_executable
+        )
     except AFLOW.ChangedSymmetryException as e:
         # re-raise, just indicating that this function knows about this exception
         raise e
@@ -1094,8 +1126,23 @@ class SingleCrystalTestDriver(KIMTestDriver):
             <https://openkim.org/properties/show/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
     """
 
+    def __init__(
+        self, model: Union[str, Calculator], aflow_executable: str = AFLOW_EXECUTABLE
+    ) -> None:
+        """
+        Args:
+            model:
+                ASE calculator or KIM model name to use
+            aflow_executable:
+                Path to AFLOW executable
+        """
+        self.aflow_executable = aflow_executable
+        super().__init__(model)
+
     def _setup(
         self,
         material: Union[Atoms, Dict],
@@ -1156,11 +1203,14 @@ class SingleCrystalTestDriver(KIMTestDriver):
                 simply provides recordkeeping of it. It is up to derived classes to
                 implement actually setting the temperature of the system.
         """
+
         if cell_cauchy_stress_eV_angstrom3 is None:
             cell_cauchy_stress_eV_angstrom3 = [0, 0, 0, 0, 0, 0]
 
         if isinstance(material, Atoms):
-            crystal_structure = get_crystal_structure_from_atoms(material)
+            crystal_structure = get_crystal_structure_from_atoms(
+                atoms=material, aflow_executable=self.aflow_executable
+            )
             msg = (
                 "Rebuilding atoms object in a standard setting defined by "
                 "doi.org/10.1016/j.commatsci.2017.01.017. See log file or computed "
@@ -1243,7 +1293,7 @@ class SingleCrystalTestDriver(KIMTestDriver):
         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 :class:`~ase.Atoms` object originally obtained from
-        :func:`~kim_tools.SingleCrystalTestDriver._get_atoms()`.
+        :func:`~kim_tools.test_driver.core.SingleCrystalTestDriver._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
@@ -1279,9 +1329,9 @@ class SingleCrystalTestDriver(KIMTestDriver):
                 If a more definitive error indicating a phase transformation is
                 encountered
         """
-
+        aflow = AFLOW(aflow_executable=self.aflow_executable)
         try:
-            aflow_parameter_values = AFLOW().solve_for_params_of_known_prototype(
+            aflow_parameter_values = aflow.solve_for_params_of_known_prototype(
                 atoms=atoms,
                 prototype_label=self.__nominal_crystal_structure_npt["prototype-label"][
                     "source-value"
@@ -1324,10 +1374,9 @@ class SingleCrystalTestDriver(KIMTestDriver):
             Whether or not the symmetry is unchanged
 
         """
+        aflow = AFLOW(aflow_executable=self.aflow_executable)
         return prototype_labels_are_equivalent(
-            AFLOW().get_prototype_designation_from_atoms(atoms)[
-                "aflow_prototype_label"
-            ],
+            aflow.get_prototype_designation_from_atoms(atoms)["aflow_prototype_label"],
             self.__nominal_crystal_structure_npt["prototype-label"]["source-value"],
         )
 
@@ -1343,7 +1392,8 @@ class SingleCrystalTestDriver(KIMTestDriver):
 
         Args:
             change_of_basis:
-                Passed to :meth:`kim_tools.SingleCrystalTestDriver._get_atoms`
+                Passed to
+                :meth:`kim_tools.test_driver.core.SingleCrystalTestDriver._get_atoms`
             filename:
                 File to save to. Will be automatically moved and renamed,
                 e.g. 'instance.poscar' -> 'output/instance-1.poscar'
@@ -1362,8 +1412,10 @@ class SingleCrystalTestDriver(KIMTestDriver):
     def _add_property_instance_and_common_crystal_genome_keys(
         self,
         property_name: str,
-        write_stress: bool = False,
-        write_temp: bool = False,
+        write_stress: Union[bool, List[float]] = False,
+        write_temp: Union[bool, float] = False,
+        stress_unit: Optional[str] = None,
+        temp_unit: str = "K",
         disclaimer: Optional[str] = None,
     ) -> None:
         """
@@ -1378,9 +1430,20 @@ class SingleCrystalTestDriver(KIMTestDriver):
                 "tag:staff@noreply.openkim.org,2023-02-21:property/binding-energy-crystal"
                 or "binding-energy-crystal"
             write_stress:
-                Write the "cell-cauchy-stress" key
+                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:
-                Write the "temperature" key
+                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:
+                Unit of stress. Required if a stress tensor is specified in
+                `write_stress`.
+            temp_unit:
+                Unit of temperature. Defaults to K.
             disclaimer:
                 An optional disclaimer commenting on the applicability of this result,
                 e.g. "This relaxation did not reach the desired tolerance."
@@ -1407,20 +1470,37 @@ class SingleCrystalTestDriver(KIMTestDriver):
 
         short_name = _get_optional_source_value(crystal_structure, "short-name")
 
-        # stress and temperature are always there (default 0), but we don't always write
-        if write_stress:
+        if write_stress is False:
+            cell_cauchy_stress = None
+            cell_cauchy_stress_unit = None
+        elif write_stress is True:
+            if stress_unit is not None:
+                raise KIMTestDriverError(
+                    "Setting write_stress=True indicates that you wish to use the "
+                    "nominal stress and stress unit stored in this object. Do not "
+                    "specify a stress_unit in this case"
+                )
             cell_cauchy_stress = crystal_structure["cell-cauchy-stress"]["source-value"]
+            cell_cauchy_stress_unit = crystal_structure["cell-cauchy-stress"][
+                "source-unit"
+            ]
         else:
-            cell_cauchy_stress = None
-
-        cell_cauchy_stress_unit = crystal_structure["cell-cauchy-stress"]["source-unit"]
+            if len(write_stress) != 6:
+                raise KIMTestDriverError(
+                    "`write_stress` must be a boolean or an array of length 6"
+                )
+            cell_cauchy_stress = write_stress
+            cell_cauchy_stress_unit = stress_unit
 
-        if write_temp:
+        if write_temp is False:
+            temperature = None
+            temperature_unit = None
+        elif write_temp is True:
             temperature = crystal_structure["temperature"]["source-value"]
+            temperature_unit = crystal_structure["temperature"]["source-unit"]
         else:
-            temperature = None
-
-        temperature_unit = crystal_structure["temperature"]["source-unit"]
+            temperature = write_temp
+            temperature_unit = temp_unit
 
         crystal_genome_source_structure_id = _get_optional_source_value(
             crystal_structure, "crystal-genome-source-structure-id"
@@ -1432,17 +1512,18 @@ class SingleCrystalTestDriver(KIMTestDriver):
                 prototype_label=prototype_label,
                 stoichiometric_species=stoichiometric_species,
                 a=a,
+                a_unit=a_unit,
                 parameter_values=parameter_values,
                 library_prototype_label=library_prototype_label,
                 short_name=short_name,
                 cell_cauchy_stress=cell_cauchy_stress,
-                temperature=temperature,
-                crystal_genome_source_structure_id=crystal_genome_source_structure_id,
-                a_unit=a_unit,
                 cell_cauchy_stress_unit=cell_cauchy_stress_unit,
+                temperature=temperature,
                 temperature_unit=temperature_unit,
+                crystal_genome_source_structure_id=crystal_genome_source_structure_id,
                 disclaimer=disclaimer,
                 property_instances=super()._get_serialized_property_instances(),
+                aflow_executable=self.aflow_executable,
             )
         )
 
@@ -1460,8 +1541,9 @@ class SingleCrystalTestDriver(KIMTestDriver):
         Get the nominal temperature
 
         Args:
-            unit: The requested unit for the output. Must be understood by the GNU
-            ``units`` utility
+            unit:
+                The requested unit for the output. Must be understood by the GNU
+                ``units`` utility
         """
         source_value = self.__nominal_crystal_structure_npt["temperature"][
             "source-value"
@@ -1478,8 +1560,9 @@ class SingleCrystalTestDriver(KIMTestDriver):
         Get the nominal stress
 
         Args:
-            unit: The requested unit for the output. Must be understood by the GNU
-            ``units`` utility
+            unit:
+                The requested unit for the output. Must be understood by the GNU
+                ``units`` utility
         """
         source_value = self.__nominal_crystal_structure_npt["cell-cauchy-stress"][
             "source-value"
@@ -1578,6 +1661,7 @@ class SingleCrystalTestDriver(KIMTestDriver):
             aflow_np=aflow_np,
             rot_rtol=rot_rtol,
             rot_atol=rot_atol,
+            aflow_executable=self.aflow_executable,
         )
         logger.info(
             f"Deduplicated {len(self.property_instances)} Property Instances "
@@ -1639,7 +1723,8 @@ class SingleCrystalTestDriver(KIMTestDriver):
                 corresponding to the "old basis" and the returned ``Atoms`` object being
                 in the "new basis".
 
-                See the docstring for :func:`kim_tools.change_of_basis_atoms` for
+                See the docstring for
+                :func:`kim_tools.symmetry_util.core.change_of_basis_atoms` for
                 more information on how to define the change of basis.
 
         Returns:
@@ -1647,7 +1732,9 @@ class SingleCrystalTestDriver(KIMTestDriver):
             Lengths are always in angstrom
         """
         crystal_structure = self.__nominal_crystal_structure_npt
-        atoms_prim = get_atoms_from_crystal_structure(crystal_structure)
+        atoms_prim = get_atoms_from_crystal_structure(
+            crystal_structure, aflow_executable=self.aflow_executable
+        )
         if isinstance(change_of_basis, str):
             if change_of_basis.lower() == "primitive":
                 change_of_basis_matrix = None
@@ -1702,7 +1789,8 @@ def query_crystal_structures(
             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
-            :func:`kim_tools.read_shortnames` and inspect the values of the returned
+            :func:`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
@@ -1785,6 +1873,7 @@ def detect_unique_crystal_structures(
     aflow_np: int = 4,
     rot_rtol: float = 0.01,
     rot_atol: float = 0.01,
+    aflow_executable=AFLOW_EXECUTABLE,
 ) -> Dict:
     """
     Detect which of the provided crystal structures is unique
@@ -1813,6 +1902,8 @@ def detect_unique_crystal_structures(
             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
     Returns:
         Dictionary with keys corresponding to indices of unique structures and values
         being lists of indices of their duplicates
@@ -1820,7 +1911,7 @@ def detect_unique_crystal_structures(
     if len(crystal_structures) == 0:
         return []
 
-    aflow = AFLOW(np=aflow_np)
+    aflow = AFLOW(aflow_executable=aflow_executable, np=aflow_np)
 
     with TemporaryDirectory() as tmpdirname:
         # I don't know if crystal_structurs is a list or a dict with integer keys
@@ -1832,7 +1923,9 @@ def detect_unique_crystal_structures(
             structure = crystal_structures[i]
             try:
                 get_poscar_from_crystal_structure(
-                    structure, os.path.join(tmpdirname, str(i))
+                    structure,
+                    os.path.join(tmpdirname, str(i)),
+                    aflow_executable=aflow_executable,
                 )
             except AFLOW.ChangedSymmetryException:
                 logger.info(
@@ -1888,6 +1981,7 @@ def detect_unique_crystal_structures(
                         aflow_np=aflow_np,
                         rot_rtol=rot_rtol,
                         rot_atol=rot_atol,
+                        aflow_executable=aflow_executable,
                     )
                 )
 
@@ -1901,6 +1995,7 @@ def get_deduplicated_property_instances(
     aflow_np: int = 4,
     rot_rtol: float = 0.01,
     rot_atol: float = 0.01,
+    aflow_executable: str = AFLOW_EXECUTABLE,
 ) -> List[Dict]:
     """
     Given a list of dictionaries constituting KIM Property instances,
@@ -1935,6 +2030,8 @@ def get_deduplicated_property_instances(
             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
 
     Returns:
         The deduplicated property instances
@@ -1969,6 +2066,7 @@ def get_deduplicated_property_instances(
             aflow_np=aflow_np,
             rot_rtol=rot_rtol,
             rot_atol=rot_atol,
+            aflow_executable=aflow_executable,
         )
 
         # Put together the list of unique instances for the current

{kim_tools-0.2.3 → kim_tools-0.2.5/kim_tools.egg-info}/PKG-INFO

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: kim-tools
-Version: 0.2.3
+Version: 0.2.5
 Summary: Base classes and helper routines for writing KIM Tests
-Author-email: ilia Nikiforov <nikif002@umn.edu>, Ellad Tadmor <tadmor@umn.edu>, Claire Waters <bwaters@umn.edu>, "Daniel S. Karls" <karl0100umn@gmail.com>, Matt Bierbaum <matt.bierbaum@gmail.com>, Eric Fuemmeler <efuemmel@umn.edu>
+Author-email: ilia Nikiforov <nikif002@umn.edu>, Ellad Tadmor <tadmor@umn.edu>, Claire Waters <bwaters@umn.edu>, "Daniel S. Karls" <karl0100umn@gmail.com>, Matt Bierbaum <matt.bierbaum@gmail.com>, Eric Fuemmeler <efuemmel@umn.edu>, Philipp Hoellmer <ph2484@nyu.edu>, Guanming Zhang <gz2241@nyu.edu>
 Maintainer-email: ilia Nikiforov <nikif002@umn.edu>
 Project-URL: Homepage, https://kim-tools.readthedocs.io
 Project-URL: Issues, https://github.com/openkim/kim-tools/issues
@@ -24,9 +24,16 @@ Requires-Dist: sympy>=1.13.2
 Requires-Dist: numpy>=1.13.1
 Requires-Dist: scipy>=1.3.0
 Requires-Dist: jinja2>=2.7.2
+Requires-Dist: matplotlib
+Requires-Dist: scipy
+Requires-Dist: scikit-learn
 Dynamic: license-file
 
 # kim-tools
 
+![testing](https://github.com/openkim/kim-tools/actions/workflows/testing.yml/badge.svg)
+[![docs](https://app.readthedocs.org/projects/kim-tools/badge/?version=latest)](https://kim-tools.readthedocs.io/en/latest/)
+[![PyPI](https://img.shields.io/pypi/v/kim-tools.svg)](https://pypi.org/project/kim-tools/)
+
 KIMTestDriver and SingleCrystalTestDriver classes for creating OpenKIM Test Drivers, and helper routines for writing
 KIM Tests and Verification Checks. Documentation at https://kim-tools.readthedocs.io.

{kim_tools-0.2.3 → kim_tools-0.2.5}/kim_tools.egg-info/requires.txt

@@ -7,3 +7,6 @@ sympy>=1.13.2
 numpy>=1.13.1
 scipy>=1.3.0
 jinja2>=2.7.2
+matplotlib
+scipy
+scikit-learn

{kim_tools-0.2.3 → kim_tools-0.2.5}/pyproject.toml

@@ -14,7 +14,10 @@ dependencies = [
     "sympy >= 1.13.2",
     "numpy >= 1.13.1",
     "scipy >= 1.3.0",
-    "jinja2 >= 2.7.2"
+    "jinja2 >= 2.7.2",
+    "matplotlib",
+    "scipy",
+    "scikit-learn"
     ]
 authors = [
     { name = "ilia Nikiforov", email = "nikif002@umn.edu" },
@@ -22,7 +25,9 @@ authors = [
     { name = "Claire Waters", email = "bwaters@umn.edu" },
     { name = "Daniel S. Karls", email = "karl0100umn@gmail.com" },
     { name = "Matt Bierbaum", email = "matt.bierbaum@gmail.com" },
-    { name = "Eric Fuemmeler", email = "efuemmel@umn.edu"}
+    { name = "Eric Fuemmeler", email = "efuemmel@umn.edu" },
+    { name = "Philipp Hoellmer", email = "ph2484@nyu.edu" },
+    { name = "Guanming Zhang", email = "gz2241@nyu.edu" }
 ]
 maintainers = [
     { name = "ilia Nikiforov", email = "nikif002@umn.edu" },

{kim_tools-0.2.3 → kim_tools-0.2.5}/tests/test_aflow_util.py

@@ -32,6 +32,7 @@ logging.basicConfig(filename="kim-tools.log", level=logging.INFO, force=True)
 
 TEST_CASES = [572, 365, 1729, 1194, 1473, 166, 1205, 1357, 915, 212, 641, 22]
 MATERIALS_FILE = "test_structures.json"
+QUERY_DUMP = "output/query_result.json"
 
 
 def shuffle_atoms(atoms: Atoms) -> Atoms:
@@ -205,6 +206,9 @@ def get_test_crystal_structures(
             indices_to_test = [0]
         test_crystal_structures += [query_result[i] for i in indices_to_test]
 
+    with open(QUERY_DUMP, "w") as f:
+        json.dump(test_crystal_structures, f)
+
     return test_crystal_structures
 
 
@@ -441,4 +445,6 @@ def test_solve_for_params_of_known_prototype(input_crystal_structures):
 
 
 if __name__ == "__main__":
-    pass
+    test_solve_for_params_of_known_prototype(
+        get_test_crystal_structures(test_cases=None)
+    )

{kim_tools-0.2.3 → kim_tools-0.2.5}/tests/test_symmetry_util.py

@@ -3,6 +3,7 @@
 import numpy as np
 from ase.build import bulk
 from ase.calculators.kim.kim import KIM
+from ase.io import read
 
 from kim_tools import (
     CENTERING_DIVISORS,
@@ -12,6 +13,11 @@ from kim_tools import (
     get_formal_bravais_lattice_from_space_group,
     get_space_group_number_from_prototype,
 )
+from kim_tools.symmetry_util.core import (
+    PeriodExtensionException,
+    kstest_reduced_distances,
+    reduce_and_avg,
+)
 
 
 def test_change_of_basis_atoms(
@@ -51,5 +57,22 @@ def test_change_of_basis_atoms(
     assert np.isclose(conventional_energy, conventional_rebuilt_energy)
 
 
+def test_test_reduced_distances():
+    data_file_has_period_extension = {
+        "structures/FeP_period_extended_phase_transition.data": True,
+        "structures/FeP_stable.data": False,
+    }
+    repeat = [11, 11, 11]
+    for data_file in data_file_has_period_extension:
+        has_period_extension = data_file_has_period_extension[data_file]
+        atoms = read(data_file, format="lammps-data")
+        _, reduced_distances = reduce_and_avg(atoms, repeat)
+        try:
+            kstest_reduced_distances(reduced_distances)
+            assert not has_period_extension
+        except PeriodExtensionException:
+            assert has_period_extension
+
+
 if __name__ == "__main__":
     test_change_of_basis_atoms()

kim_tools-0.2.3/README.md

@@ -1,4 +0,0 @@
-# kim-tools
-
-KIMTestDriver and SingleCrystalTestDriver classes for creating OpenKIM Test Drivers, and helper routines for writing
-KIM Tests and Verification Checks. Documentation at https://kim-tools.readthedocs.io.