kim-tools 0.2.0b0__py3-none-any.whl

kim_tools/vc/__init__.py

@@ -0,0 +1,4 @@
+from .core import *
+from .core import __all__ as vc_all
+
+__all__ = vc_all

kim_tools/vc/core.py

@@ -0,0 +1,397 @@
+################################################################################
+#
+#  CDDL HEADER START
+#
+#  The contents of this file are subject to the terms of the Common Development
+#  and Distribution License Version 1.0 (the "License").
+#
+#  You can obtain a copy of the license at
+#  http:# www.opensource.org/licenses/CDDL-1.0.  See the License for the
+#  specific language governing permissions and limitations under the License.
+#
+#  When distributing Covered Code, include this CDDL HEADER in each file and
+#  include the License file in a prominent location with the name LICENSE.CDDL.
+#  If applicable, add the following below this CDDL HEADER, with the fields
+#  enclosed by brackets "[]" replaced with your own identifying information:
+#
+#  Portions Copyright (c) [yyyy] [name of copyright owner]. All rights reserved.
+#
+#  CDDL HEADER END
+#
+#  Copyright (c) 2017-2019, Regents of the University of Minnesota.
+#  All rights reserved.
+#
+#  Contributor(s):
+#     Ellad B. Tadmor
+#
+################################################################################
+"""
+Helper routines for KIM Verification Checks
+
+"""
+
+import math
+import os
+import sys
+import textwrap
+import time
+
+import jinja2
+import numpy as np
+from ase import Atoms
+
+__all__ = [
+    "KIMVCError",
+    "VerificationCheck",
+    "setup_and_run_vc",
+    "vc_stripall",
+    "vc_letter_grade_machine_precision",
+]
+
+
+################################################################################
+class KIMVCError(Exception):
+    def __init__(self, msg):
+        # Call the base class constructor with the parameters it needs
+        super(KIMVCError, self).__init__(msg)
+        self.msg = msg
+
+    def __str__(self):
+        return self.msg
+
+
+################################################################################
+def vc_stripall(string):
+    """
+    In "string", remove leading and trailing newlines, replace internal newlines
+    with spaces, and remove carriage returns.
+
+    Primary purpose is to process docstring at top of VC code and convert to
+    vc_description.
+    """
+    return string.strip().replace("\n", " ").replace("\r", "")
+
+
+################################################################################
+def vc_letter_grade_machine_precision(error, Amax=7.5, Bmax=10.0, Cmax=12.5, Dmax=15.0):
+    """
+    This function assigns a letter grade in the range A-D and F for fail
+    based on the obtained 'error' as compared with the machine precision
+    of the computation.
+    """
+    if not Amax < Bmax < Cmax < Dmax:
+        raise KIMVCError("ERROR: This condition not satisfied: Amax<Bmax<Cmax<Dmax")
+    eps = np.finfo(float).eps
+    if abs(error) < eps:
+        letter_grade = "A"
+    else:
+        score = math.log10(abs(error) / eps)
+        if score <= Amax:
+            letter_grade = "A"
+        elif score <= Bmax:
+            letter_grade = "B"
+        elif score <= Cmax:
+            letter_grade = "C"
+        elif score <= Dmax:
+            letter_grade = "D"
+        else:
+            letter_grade = "F"
+    # Return with assigned letter grade
+    comment = (
+        "The letter grade {0:} was assigned because the normalized error in the "
+        "computation was {1:.5e} compared with a machine precision of {2:.5e}. The "
+        "letter grade was based on 'score=log10(error/eps)', with ranges "
+        "A=[0, {3:.1f}], B=({3:.1f}, {4:.1f}], C=({4:.1f}, {5:.1f}], D=({5:.1f}, "
+        "{6:.1f}), F>{6:.1f}.  'A' is the best grade, and 'F' indicates failure."
+    ).format(letter_grade, error, eps, Amax, Bmax, Cmax, Dmax)
+    return letter_grade, comment
+
+
+################################################################################
+def setup_and_run_vc(
+    do_vc,
+    model,
+    vc_name,
+    vc_author,
+    vc_description,
+    vc_category,
+    vc_grade_basis,
+    vc_files,
+    vc_debug,
+):
+    """
+    Construct VerificationCheck object containing all info related to VC,
+    and perform the VC by calling the user supplied `do_vc` function.  The VC
+    report and property instance re generated.  If `vc_debug` is True, errors
+    generate exceptions will full traceback, otherwise exceptions are trapped
+    and an error message is reported.
+    """
+
+    # Define VC object and do verification check
+    vc = VerificationCheck(
+        vc_name,
+        vc_author,
+        vc_description,
+        vc_category,
+        vc_grade_basis,
+        vc_files,
+        vc_debug,
+    )
+    try:
+        with vc:
+            # Perform verification check and get grade
+            try:
+                vc_grade, vc_comment = do_vc(model, vc)
+                vc.rwrite("Grade: {}".format(vc_grade))
+                vc.rwrite("")
+                vc.rwrite("Comment: " + vc_comment)
+                vc.rwrite("")
+            except BaseException as e:
+                vc_grade = "N/A"
+                vc_comment = "Unable to perform verification check due to an error."
+                if vc_debug:
+                    raise
+                else:
+                    vc.rwrite(
+                        "\nERROR: Unable to perform verification check.\n\n Message = "
+                        + str(e)
+                    )
+            finally:
+                # Pack results in a dictionary and write VC property instance
+                results = {
+                    "vc_name": vc_name,
+                    "vc_description": vc_description,
+                    "vc_category": vc_category,
+                    "vc_grade_basis": vc_grade_basis,
+                    "vc_grade": vc_grade,
+                    "vc_comment": vc_comment,
+                    "vc_files": vc_files,
+                }
+                vc.write_results(results)
+    except Exception as e:
+        if vc_debug:
+            raise
+        else:
+            sys.stderr.write(
+                "\nERROR: Unable to initalize verification check.\n\n Message = "
+                + str(e)
+            )
+
+
+################################################################################
+class VerificationCheck(object):
+    """
+    Features routines related to outputting VC information and results.
+    """
+
+    ############################################################################
+    def rwrite(self, string):
+        """
+        Write 'string' with appended newline to report and echo to stdout
+        """
+        if not self.report_ready:
+            raise KIMVCError(
+                "ERROR: Trying to write out string to "
+                "report file that is not ready.\n\n"
+                '       string =  "{}"\n'.format(string)
+            )
+
+        self.report.write(string + "\n")
+        sys.stdout.write(string + "\n")
+
+    ############################################################################
+    def __init__(
+        self,
+        vc_name,
+        vc_author,
+        vc_description,
+        vc_category,
+        vc_grade_basis,
+        vc_files,
+        vc_debug,
+    ):
+        """
+        Initialize a VC object.
+        """
+        # Initialize object variables
+        self.output_ready = False  # Output directory not setup
+        self.report_ready = False  # Report file not open for writing
+        self.vc_name = vc_name
+        self.vc_description = vc_description
+        self.vc_author = vc_author
+        self.vc_category = vc_category
+        self.vc_grade_basis = vc_grade_basis
+        self.vc_files = vc_files
+        self.vc_debug = vc_debug
+
+    ############################################################################
+    def __enter__(self):
+        """
+        Beginning with block:
+        Send message to stdout, open report file, print header,
+        and return report file object.
+        """
+        # Send message to stdout that VC calculation is starting
+        print()
+        print(
+            "=== Verification check {} start ({}) ==="
+            "".format(self.vc_name, time.strftime("%Y-%m-%d %H:%M:%S"))
+        )
+        # Create directory 'output' if it does not already exist:
+        try:
+            if not os.path.exists("output"):
+                os.makedirs("output")
+            self.output_ready = True
+        except (OSError, IOError):
+            raise KIMVCError("ERROR: Unable to create directory 'output'.\n")
+        # Open report file and write header
+        try:
+            self.report = open(
+                os.path.abspath(os.path.join("output", "report.txt")),
+                "w",
+                encoding="utf-8",
+            )
+            self.report_ready = True
+        except (OSError, IOError):
+            raise KIMVCError(
+                "ERROR: Unable to open verification check report file for writing.\n"
+            )
+        # Output header to report file
+        padside = 5
+        c = "!"
+        content_line = "VERIFICATION CHECK: " + self.vc_name
+        content_width = len(content_line)
+        content_line += " " * (content_width - len(content_line))
+        width = 2 * padside + 4 + content_width
+        self.rwrite(c * width)
+        self.rwrite(c * width)
+        self.rwrite(c * padside + " " * (content_width + 4) + c * padside)
+        self.rwrite(c * padside + "  " + content_line + "  " + c * padside)
+        self.rwrite(c * padside + " " * (content_width + 4) + c * padside)
+        self.rwrite(c * width)
+        self.rwrite(c * width)
+        self.rwrite("")
+        prefix = "Description: "
+        preferredWidth = 80
+        wrapper = textwrap.TextWrapper(
+            initial_indent=prefix,
+            width=preferredWidth,
+            subsequent_indent=" " * len(prefix),
+        )
+        self.rwrite(wrapper.fill(self.vc_description))
+        self.rwrite("")
+        self.rwrite("Author: {}".format(self.vc_author))
+
+    ############################################################################
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """
+        Leaving with block:
+        Finishing VC calculation.  Send message to stdout, and close report file.
+        """
+        # Send message to stdout that VC calculation is starting
+        print()
+        print(
+            "=== Verification check {} end ({}) ==="
+            "".format(self.vc_name, time.strftime("%Y-%m-%d %H:%M:%S"))
+        )
+        # Close report file
+        self.report.close()
+
+    ############################################################################
+    def write_results(self, results):
+        """
+        Use jinja2 to Process the template file 'results.edn.tpl' (expected
+        in the current working directory) to replace the keys in 'results'.
+        Place the new 'results.edn' file in a directory called 'output',
+        creating it if it does not already exist.
+        """
+        if not self.report_ready:
+            raise KIMVCError(
+                "ERROR: Trying to write out results.edn "
+                "but directory 'output' is not ready.\n"
+            )
+
+        # Turn lists into strings with double quotes to to be compatible with
+        # EDN format
+        for key in results:
+            if isinstance(results[key], list):
+                results[key] = str(results[key]).replace("'", '"')
+
+        template_environment = jinja2.Environment(
+            loader=jinja2.FileSystemLoader("/"),
+            block_start_string="@[",
+            block_end_string="]@",
+            variable_start_string="@<",
+            variable_end_string=">@",
+            comment_start_string="@#",
+            comment_end_string="#@",
+            undefined=jinja2.StrictUndefined,
+        )
+        # Template the EDN output
+        with open(
+            os.path.abspath(os.path.join("output", "results.edn")),
+            "w",
+            encoding="utf-8",
+        ) as f:
+            template = template_environment.get_template(
+                os.path.abspath("results.edn.tpl")
+            )
+            f.write(template.render(**results))
+
+    ############################################################################
+    def write_aux_ase_atoms(self, aux_file, atoms, format):
+        """
+        Write the configuration in the ASE 'atoms' object to an auxiliary
+        file 'aux_file' in the output directory in the specified 'format'.
+        For supported formats, see https://wiki.fysik.dtu.dk/ase/ase/io/io.html
+        """
+        if not self.report_ready:
+            raise KIMVCError(
+                "ERROR: Trying to write out ASE Atoms "
+                "aux file but directory 'output' is not ready.\n"
+            )
+
+        Atoms.write(atoms, os.path.join("output", aux_file), format=format)
+
+    ############################################################################
+    def write_aux_x_y(self, aux_file, x, y):
+        """
+        Write a file containing the lists x and y:
+        x[0] y[0]
+        x[1] y[1]
+        ...
+        If the lists are not the same length, the shorter sets the size.
+        """
+        if not self.report_ready:
+            raise KIMVCError(
+                "ERROR: Trying to write out x-y data "
+                "aux file but directory 'output' is not ready.\n"
+            )
+
+        with open(
+            os.path.abspath(os.path.join("output", aux_file)), "w", encoding="utf-8"
+        ) as f:
+            for i in range(0, min(len(x), len(y))):
+                f.write("{0: 11.8e} {1: 11.8e}\n".format(x[i], y[i]))
+
+    ############################################################################
+    def write_aux_string(self, aux_file, string):
+        """
+        Write a file containing the contents in 'string'
+        """
+        if not self.report_ready:
+            raise KIMVCError(
+                "ERROR: Trying to write out string to "
+                "aux file but directory 'output' is not ready.\n"
+            )
+
+        with open(
+            os.path.abspath(os.path.join("output", aux_file)), "w", encoding="utf-8"
+        ) as f:
+            f.write("{}\n".format(string))
+
+
+################################################################################
+# If called directly, do nothing
+if __name__ == "__main__":
+    pass

kim_tools-0.2.0b0.dist-info/METADATA

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: kim-tools
+Version: 0.2.0b0
+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>
+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
+Keywords: kim-tools,kim_tools,openkim,crystal genome
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: Common Development and Distribution License 1.0 (CDDL-1.0)
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE.CDDL
+Requires-Dist: ase>=3.23
+Requires-Dist: kim-property>=2.6.8
+Requires-Dist: kim-edn>=1.4.1
+Requires-Dist: spglib>=2.1.0
+Requires-Dist: kim-query>=3.0.0
+Requires-Dist: sympy>=1.13.2
+Requires-Dist: numpy>=1.13.1
+Requires-Dist: scipy>=1.3.0
+Requires-Dist: jinja2>=2.7.2
+Dynamic: license-file
+
+# 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.0b0.dist-info/RECORD

@@ -0,0 +1,24 @@
+kim_tools/__init__.py,sha256=_IDKtgO7O3TeqoIhOaAUUqV2IEv5Suk3PPsYokbtI7Q,435
+kim_tools/kimunits.py,sha256=kR5VMTurQnbPOHcWF1XN-mjY9FXRAdWI8hA-RZHhrek,5036
+kim_tools/aflow_util/__init__.py,sha256=lJnQ8fZCma80QVRQeKvY4MQ87oCWu-9KATV3dKJfpDc,80
+kim_tools/aflow_util/core.py,sha256=Xqjh2Xwf4-e-98FMJ8RfRXsTdx2NeWeZXwrPP0xkvwM,71847
+kim_tools/aflow_util/data/README_PROTO.TXT,sha256=bTpcd8GHOkpcQn6YUZzqKhiTytwSDpkgu4boeoogT38,447851
+kim_tools/ase/__init__.py,sha256=1i6ko5tNr0VZC3T7hoEzq4fnSU0DdxNpxXcSaWMcJWc,76
+kim_tools/ase/core.py,sha256=d6eOu_HSxVr-ae0TSEbY4HKdePxhNu3yv8NN9VDl-BA,30256
+kim_tools/symmetry_util/__init__.py,sha256=uu-ZSUDUTe2P81rkAS3tXverx31s_uZ3wL4SD_dn5aI,86
+kim_tools/symmetry_util/core.py,sha256=eQV6gBVlLzGz3LvbRhD1H64uOooyRWTFxU346jSUbE4,20083
+kim_tools/symmetry_util/data/possible_primitive_shifts.json,sha256=4OVNgn3NnykgGlYiAcecERmVWiIZFrmP2LZI3ml_Sh0,25010
+kim_tools/symmetry_util/data/primitive_GENPOS_ops.json,sha256=FDu4H4PosOpK9yKwOPy3SxbH7xLMOmZfKZ4ItKPMjoQ,224498
+kim_tools/symmetry_util/data/space_groups_for_each_bravais_lattice.json,sha256=wSNu6d5pH72lJ6Zj5MZ64qzwS_6Fn5WOs0ts7E9uPC4,2507
+kim_tools/symmetry_util/data/wyck_pos_xform_under_normalizer.json,sha256=6g1YuYhnZwCq4n9Y0r4D7FfmI9cb5m_n5REk7FUlukQ,61980
+kim_tools/symmetry_util/data/wyckoff_multiplicities.json,sha256=qG2RPBd_-ejDIfz-E4ZhkHyRpIboxRy7oiXkdDf5Eg8,32270
+kim_tools/symmetry_util/data/wyckoff_sets.json,sha256=f5ZpHKDHo6_JWki1b7KUGoYLlhU-44Qikw_-PtbLssw,9248
+kim_tools/test_driver/__init__.py,sha256=KOiceeZNqkfrgZ66CiRiUdniceDrCmmDXQkOw0wXaCQ,92
+kim_tools/test_driver/core.py,sha256=YFLwqV6bBAxRzoinAB3cH86z90fQqENwhMcjyzrJxPM,78225
+kim_tools/vc/__init__.py,sha256=zXjhxXCKVMLBMXXWYG3if7VOpBnsFrn_RjVpnohDm5c,74
+kim_tools/vc/core.py,sha256=BIjzEExnQAL2S90a_npptRm3ACqAo4fZBtvTDBMWMdw,13963
+kim_tools-0.2.0b0.dist-info/licenses/LICENSE.CDDL,sha256=I2luEED_SHjuZ01B4rYG-AF_135amL24JpHvZ1Jhqe8,16373
+kim_tools-0.2.0b0.dist-info/METADATA,sha256=feOdrstYpWjnu0VzAeNU0_zTWgsSM7yBZfs0RkD7fbA,1462
+kim_tools-0.2.0b0.dist-info/WHEEL,sha256=ck4Vq1_RXyvS4Jt6SI0Vz6fyVs4GWg7AINwpsaGEgPE,91
+kim_tools-0.2.0b0.dist-info/top_level.txt,sha256=w_YCpJ5ERigj9te74ln7k64tqj1VumOzM_s9dsalIWY,10
+kim_tools-0.2.0b0.dist-info/RECORD,,

kim_tools-0.2.0b0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+