Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
115 changes: 115 additions & 0 deletions ci/clean_numba_cache.py
Original file line number Diff line number Diff line change
@@ -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"<missing>")
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())
10 changes: 10 additions & 0 deletions docs/contributing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
-------------------------

Expand Down
32 changes: 32 additions & 0 deletions test/conftest.py
Original file line number Diff line number Diff line change
@@ -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).
Expand Down
181 changes: 181 additions & 0 deletions test/grid/geometry/test_numba_flags.py
Original file line number Diff line number Diff line change
@@ -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 = {
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
"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):
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
target = namespace.get(func.id)
# An attribute method call (e.g. val.print())
elif isinstance(func, ast.Attribute) and isinstance(func.value, ast.Name):
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
target = getattr(namespace.get(func.value.id), func.attr, None)
else:
continue

# Only consider Numba JIT func calls
if isinstance(target, CPUDispatcher):
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
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):
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
"""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
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
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):
Comment thread
jayeshkrishna marked this conversation as resolved.
Resolved
"""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."
)
3 changes: 2 additions & 1 deletion uxarray/grid/utils.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 7 additions & 0 deletions uxarray/utils/computing.py
Original file line number Diff line number Diff line change
Expand Up @@ -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):

Expand Down
Loading