diff --git a/ci/clean_numba_cache.py b/ci/clean_numba_cache.py new file mode 100644 index 000000000..4043131c8 --- /dev/null +++ b/ci/clean_numba_cache.py @@ -0,0 +1,115 @@ +"""Delete numba's on-disk cache for ``uxarray``. + +Numba stamps each ``cache=True`` index (``*.nbi``) with the ``(mtime, size)`` of the +source file that *defines* the function, and nothing else. A kernel that calls a jitted +function from another module has that callee's code linked into its own cached object, +so editing the callee leaves the caller's cache entry "valid" with the old body baked in. + +The test suite calls ``clear_if_shared_modules_changed`` at session start, which clears +the cache only when the jitted modules that others call into (``SHARED_MODULES``) differ +from the last run. Outside pytest (notebooks, scripts), run this by hand after editing +one of them:: + + python ci/clean_numba_cache.py [--dry-run] +""" + +import argparse +import hashlib +import os +from pathlib import Path + +PACKAGE_DIR = Path(__file__).resolve().parent.parent / "uxarray" +CACHE_SUFFIXES = {".nbi", ".nbc"} +# Jitted modules whose kernels are compiled into kernels of *other* modules. Add a module +# here when another module's jitted code starts calling into it; test_numba_flags.py's +# test_shared_modules_complete fails if one is missing. +SHARED_MODULES = [ + "utils/computing.py", + "utils/numba_math.py", + "grid/angles.py", + "grid/arcs.py", + "grid/area.py", + "grid/coordinates.py", + "grid/geometry.py", + "grid/intersections.py", + "grid/point_in_face.py", + "grid/utils.py", +] +# Digest of SHARED_MODULES as of the last clear; __pycache__ keeps it out of git. +STAMP = PACKAGE_DIR / "__pycache__" / "numba_shared_modules.sha256" +# Numba files caches in NUMBA_CACHE_DIR under a hash of each source directory, so they +# can't be told apart from other projects' entries; leave them alone rather than guess. +EXTERNAL_CACHE_WARNING = ( + "NUMBA_CACHE_DIR is set, so uxarray's numba cache lives there and was not cleared " + "(to avoid touching other projects' entries); clear it by hand." +) + + +def _cache_files(): + """Yield numba cache files stored next to the package's sources.""" + for path in PACKAGE_DIR.rglob("__pycache__/*"): + if path.suffix in CACHE_SUFFIXES: + yield path + + +def _shared_modules_digest(): + digest = hashlib.sha256() + for name in SHARED_MODULES: + path = PACKAGE_DIR / name + digest.update(name.encode()) + digest.update(path.read_bytes() if path.exists() else b"") + return digest.hexdigest() + + +def _write_stamp(digest): + STAMP.parent.mkdir(exist_ok=True) + STAMP.write_text(digest) + + +def clear(dry_run=False): + """Delete every cache file; return how many there were.""" + files = sorted(set(_cache_files())) + for path in files: + if dry_run: + print(path) + else: + path.unlink(missing_ok=True) + + if not dry_run: + _write_stamp(_shared_modules_digest()) + return len(files) + + +def clear_if_shared_modules_changed(): + """Clear the cache if SHARED_MODULES changed since the last clear (or there is no + record of one); return the number of files removed, or None if nothing changed. + """ + digest = _shared_modules_digest() + try: + if STAMP.read_text() == digest: + return None + except OSError: + pass + return clear() + + +def main(argv=None): + parser = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) + parser.add_argument( + "-n", + "--dry-run", + action="store_true", + help="list what would be removed without deleting anything", + ) + args = parser.parse_args(argv) + + removed = clear(dry_run=args.dry_run) + if os.environ.get("NUMBA_CACHE_DIR"): + print(f"WARNING: {EXTERNAL_CACHE_WARNING}") + verb = "would remove" if args.dry_run else "removed" + print(f"{verb} {removed} numba cache file(s)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/docs/contributing.rst b/docs/contributing.rst index cffde8e8f..db4af0e6b 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -360,6 +360,16 @@ following command:: $ pre-commit run --all-files +A note on numba's kernel cache: numba only checks a cached kernel against the file that +defines it, so a kernel that calls a jitted function from another file keeps running the old +code after that function is edited. ``pytest`` handles this for you: at startup it clears the +cache if any of the shared jitted modules (``SHARED_MODULES`` in +``ci/clean_numba_cache.py``) differs from the last run, and leaves a warm cache alone +otherwise. Outside pytest (a notebook or script), clear it by hand after editing one of +those modules:: + + $ python ci/clean_numba_cache.py + 3.5. Use Feature Branches ------------------------- diff --git a/test/conftest.py b/test/conftest.py index 50ee2831b..e558e34ff 100644 --- a/test/conftest.py +++ b/test/conftest.py @@ -1,10 +1,42 @@ """Pytest configuration and fixtures for uxarray tests.""" +import importlib.util +import os + import pytest import numpy as np from pathlib import Path +@pytest.hookimpl(tryfirst=True) +def pytest_sessionstart(session): + """Clear numba's cache if a module other kernels compile in has changed. + + Runs before collection imports uxarray, so no stale kernel is loaded first. See + ci/clean_numba_cache.py for why numba's own staleness check misses this. + """ + if hasattr(session.config, "workerinput"): # pytest-xdist worker; controller did it + return + script = Path(__file__).parent.parent / "ci" / "clean_numba_cache.py" + if not script.exists(): # running from an installed package without the repo + return + spec = importlib.util.spec_from_file_location("clean_numba_cache", script) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + + removed = module.clear_if_shared_modules_changed() + if removed is None: + return + reporter = session.config.pluginmanager.get_plugin("terminalreporter") + if reporter is None: + return + reporter.write_line( + f"uxarray: shared jitted modules changed; removed {removed} numba cache file(s)" + ) + if os.environ.get("NUMBA_CACHE_DIR"): + reporter.write_line(f"WARNING: {module.EXTERNAL_CACHE_WARNING}", yellow=True) + + @pytest.fixture def gridpath(): """Get the path to test grid/mesh file(s). diff --git a/test/grid/geometry/test_numba_flags.py b/test/grid/geometry/test_numba_flags.py new file mode 100644 index 000000000..45a182eca --- /dev/null +++ b/test/grid/geometry/test_numba_flags.py @@ -0,0 +1,181 @@ +"""Guard the numba flags that uxarray's compensated (EFT) kernels depend on. + +A kernel declared ``inline="always"`` is compiled with its *caller's* flags, not its own, +so every kernel it is inlined into, directly or transitively, needs the same flags. +Taking ``acc_sqrt_re`` (``uxarray.utils.computing``) as the example: + +- ``error_model="numpy"``: division follows IEEE 754, so ``acc_sqrt_re(0.0)`` returns + ``(0.0, nan)`` (the correction is 0/0) and the status layer's isfinite mask rejects it. + Under numba's default ``error_model="python"`` the same call raises ZeroDivisionError. + (A negative input gives ``(nan, nan)`` under either model; only division raises.) +- no ``fastmath``: compensated arithmetic relies on IEEE 754 forbidding reassociation. + ``fastmath`` lets LLVM simplify two_sum's ``e = (a - (s - bp)) + (b - bp)``, with + ``s = a + b``, to 0, discarding the rounding error the term exists to recover: + ``acc_sqrt_re(10.0)`` returns correction -1.9e-16 normally, 0.0 under fastmath. + +``test_numpy_error_model`` checks every uxarray kernel that inlines one of +``NUMPY_ERROR_MODEL_KERNELS``; ``test_no_fastmath`` checks every kernel that inlines +anything from ``uxarray.utils.computing``. ``test_shared_modules_complete`` checks that +the cache clearing in test/conftest.py watches every module whose kernels are compiled +into another module's. +""" + +import ast +import importlib +import importlib.util +import inspect +import pkgutil +import sys +import textwrap +from pathlib import Path + +import pytest +from numba.core.registry import CPUDispatcher + +import uxarray + +EFT_MODULE = "uxarray.utils.computing" +# The kernels whose own arithmetic relies on 1/0 -> inf and 0/0 -> nan. This is the +# list of *sources*: the tests scan every kernel in uxarray and flag any one these are +# inlined into that lacks error_model="numpy". It has to be maintained by hand, because +# a kernel's own flags can't tell us this: e.g. ``_try_gca_gca_intersection`` sets +# error_model="numpy" only because it inlines ``_accux_gca``, not because it needs it. +NUMPY_ERROR_MODEL_KERNELS = { + "uxarray.utils.computing.acc_sqrt_re", + "uxarray.grid.intersections._accux_gca", + "uxarray.grid.intersections._accux_constlat", +} + + +def _qualname(kernel): + return f"{kernel.py_func.__module__}.{kernel.py_func.__name__}" + + +def _callees(kernel): + """Yield the jitted functions called by name in ``kernel``'s body.""" + namespace = kernel.py_func.__globals__ + for node in ast.walk(ast.parse(textwrap.dedent(inspect.getsource(kernel.py_func)))): + if not isinstance(node, ast.Call): + continue + + func = node.func + # A direct function call (e.g., print()) + if isinstance(func, ast.Name): + target = namespace.get(func.id) + # An attribute method call (e.g. val.print()) + elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name): + target = getattr(namespace.get(func.value.id), func.attr, None) + else: + continue + + # Only consider Numba JIT func calls + if isinstance(target, CPUDispatcher): + yield target + + +def _get_inlined_funcs_in_call_tree(kernel): + """Names of ``kernel`` and every kernel inlined into it, all built with its flags.""" + names, stack = {_qualname(kernel)}, [kernel] + while stack: + for callee in _callees(stack.pop()): + name = _qualname(callee) + if callee.targetoptions.get("inline") == "always" and name not in names: + names.add(name) + stack.append(callee) + return names + + +@pytest.fixture(scope="module") +def kernels(): + """Map each module-level kernel in uxarray to ``(kernel, names compiled into it)``.""" + found = {} + for info in pkgutil.walk_packages(uxarray.__path__, "uxarray."): + try: + module = importlib.import_module(info.name) + except ImportError: # missing optional dependency: its kernels can't run either + continue + for obj in vars(module).values(): + if isinstance(obj, CPUDispatcher) and obj.py_func.__module__ == info.name: + found[_qualname(obj)] = (obj, _get_inlined_funcs_in_call_tree(obj)) + return found + + +def test_numpy_error_model(kernels): + """Every kernel that inlines a NUMPY_ERROR_MODEL_KERNELS entry sets error_model="numpy".""" + # If a source kernel is renamed, moved or fails to import, nothing would match it + # below and this test would pass without checking anything. + missing = NUMPY_ERROR_MODEL_KERNELS - kernels.keys() + assert not missing, f"NUMPY_ERROR_MODEL_KERNELS names unknown kernels: {missing}" + + offenders = sorted( + name + for name, (kernel, is_compiled) in kernels.items() + if is_compiled & NUMPY_ERROR_MODEL_KERNELS # inlines a kernel that needs it... + and kernel.targetoptions.get("error_model") != "numpy" # ...but doesn't set it + ) + assert not offenders, ( + f"Missing error_model='numpy' on {offenders}: they inline kernels that rely on " + f"1/0 -> inf and 0/0 -> nan, which raise ZeroDivisionError under the default model" + ) + + +def test_no_fastmath(kernels): + """No kernel that inlines EFT code from uxarray.utils.computing enables fastmath.""" + eft = { + name: kernel + for name, (kernel, compiled) in kernels.items() + if any(n.startswith(EFT_MODULE + ".") for n in compiled) + } + assert eft, f"No kernels found in {EFT_MODULE}; was it renamed?" # else vacuous + offenders = [ + name for name, kernel in eft.items() if kernel.targetoptions.get("fastmath") + ] + # Also scan the source, for kernels the import walk can't see: nested ones and the + # ``two_prod`` variant not selected on this machine. Only a literal ``False`` is known + # to be safe; anything else (``True``, a flag set, a variable) is flagged. + for module in {kernel.py_func.__module__ for kernel in eft.values()}: + tree = ast.parse(Path(sys.modules[module].__file__).read_text()) + offenders += [ + f"{module}:{node.lineno}" + for node in ast.walk(tree) + if isinstance(node, ast.keyword) + and node.arg == "fastmath" + and not (isinstance(node.value, ast.Constant) and node.value.value is False) + ] + assert not offenders, ( + f"fastmath enabled on {sorted(offenders)} (kernels, or module:line of a fastmath= " + f"that isn't a literal False): they inline EFT code from {EFT_MODULE}, whose " + f"error terms fastmath cancels to 0. Remove fastmath or set it to False." + ) + + +def test_shared_modules_complete(kernels): + """SHARED_MODULES lists every module whose kernels another module's kernels call.""" + script = Path(__file__).parents[3] / "ci" / "clean_numba_cache.py" + if not script.exists(): + pytest.skip("ci/clean_numba_cache.py is not available outside the repository") + spec = importlib.util.spec_from_file_location("clean_numba_cache", script) + cleaner = importlib.util.module_from_spec(spec) + spec.loader.exec_module(cleaner) + shared = { + "uxarray." + name.removesuffix(".py").replace("/", ".") + for name in cleaner.SHARED_MODULES + } + + # Any cross-module call counts, not only inline="always": numba links a cached + # callee's code into the caller's cached object either way. + called_from = {} + for kernel, _ in kernels.values(): + caller = kernel.py_func.__module__ + for callee in _callees(kernel): + if callee.py_func.__module__ != caller: + called_from.setdefault(callee.py_func.__module__, set()).add(caller) + assert called_from, "found no cross-module kernel calls; is _callees broken?" + + missing = {m: sorted(c) for m, c in sorted(called_from.items()) if m not in shared} + assert not missing, ( + f"Add these to SHARED_MODULES in ci/clean_numba_cache.py: {missing} " + f"(module -> its callers). Kernels in the callers compile in code from these " + f"modules, and numba won't notice when they change, so pytest must clear the " + f"cache whenever they do." + ) diff --git a/uxarray/grid/utils.py b/uxarray/grid/utils.py index 68cae8790..56e849319 100644 --- a/uxarray/grid/utils.py +++ b/uxarray/grid/utils.py @@ -559,7 +559,8 @@ def setter(self, value): # # NOTE: these are inlined into ``cache=True`` kernels in another module, and numba stamps its # cache against the defining file alone, so editing them does not invalidate a caller's cached -# object. Clear ``uxarray/grid/__pycache__/*.nbi *.nbc`` after changing anything here. +# object. pytest clears the cache when this file changes; outside pytest, run +# ``python ci/clean_numba_cache.py`` after changing anything here. @njit(cache=True) diff --git a/uxarray/utils/computing.py b/uxarray/utils/computing.py index aff800372..a5e14f3ac 100644 --- a/uxarray/utils/computing.py +++ b/uxarray/utils/computing.py @@ -8,6 +8,13 @@ hardware FMA when one is available (validated bit-exact at import time) and falls back to the Veltkamp split otherwise, so there is no hard FMA dependency. +.. warning:: + Every primitive here is inlined into ``cache=True`` kernels in other modules. Numba + stamps a cache entry against the file that *defines* the kernel only, + so after editing this file those callers keep running the old body from their cache, + with no warning. pytest clears the cache when this file changes; elsewhere, run + ``python ci/clean_numba_cache.py`` before testing changes here. + Python/Numba port of the AccuSphGeom C++ library (EFT tier only; the adaptive Shewchuk predicate and exact-arithmetic fallback tiers are not ported):