numguard-ci 1.0.0__py3-none-any.whl

numguard/__init__.py

@@ -0,0 +1,70 @@
+"""numguard - numerical edge-case testing for array code.
+
+Generate the inputs that numerical code gets wrong (zeros, empty arrays, NaN,
+infinities, huge and subnormal magnitudes, signed zero, cancellation-prone
+data, float16 precision, ...) and check a function against them::
+
+    import numpy as np
+    import numguard
+
+    def logsumexp(x):
+        return np.log(np.sum(np.exp(x)))
+
+    report = numguard.check(logsumexp, reference=scipy.special.logsumexp,
+                            properties=["translation_equivariant"])
+    print(report.summary())
+"""
+
+from __future__ import annotations
+
+from . import properties
+from .api import Spec, check, check_spec, get_spec, guard
+from .cases import (
+    ANY,
+    DEFAULT_DTYPES,
+    FLOAT_DTYPES,
+    KINDS,
+    Array,
+    ArraySpec,
+    Case,
+    Domain,
+    generate_cases,
+    integers,
+    interval,
+)
+from .checks import compare
+from .properties import Property
+from .reference import highprec, longdouble, mp_scalar, ulp_distance
+from .report import CheckResult, NumGuardError, Report
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "ANY",
+    "Array",
+    "ArraySpec",
+    "Case",
+    "CheckResult",
+    "DEFAULT_DTYPES",
+    "Domain",
+    "FLOAT_DTYPES",
+    "KINDS",
+    "NumGuardError",
+    "Property",
+    "Report",
+    "Spec",
+    "__version__",
+    "check",
+    "check_spec",
+    "compare",
+    "generate_cases",
+    "get_spec",
+    "guard",
+    "highprec",
+    "integers",
+    "interval",
+    "longdouble",
+    "mp_scalar",
+    "properties",
+    "ulp_distance",
+]

numguard/__main__.py

@@ -0,0 +1,6 @@
+"""Allow ``python -m numguard``."""
+
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    main()

numguard/_corpus/__init__.py

@@ -0,0 +1 @@
+"""Bundled numguard bug corpus (task folders; installed as ``numguard._corpus``)."""

numguard/_corpus/cosine_similarity/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/cosine_similarity/buggy.py

@@ -0,0 +1,7 @@
+"""dot / (||a|| ||b||)."""
+
+import numpy as np
+
+
+def cosine_similarity(a, b):
+    return np.dot(a, b) / (np.linalg.norm(a) * np.linalg.norm(b))

numguard/_corpus/cosine_similarity/reference.py

@@ -0,0 +1,27 @@
+"""Scaled cosine similarity with an explicit zero-vector convention."""
+
+import numpy as np
+
+
+def cosine_similarity(a, b):
+    a = np.asarray(a)
+    b = np.asarray(b)
+    dt = np.result_type(a, b)
+    if np.isnan(a).any() or np.isnan(b).any():
+        return dt.type(np.nan)
+    sa = np.max(np.abs(a), initial=0.0)
+    sb = np.max(np.abs(b), initial=0.0)
+    if sa == 0 or sb == 0:
+        return dt.type(0.0)
+    acc = np.float64 if dt.itemsize < 8 else dt.type
+    ua = a.astype(acc) / acc(sa)
+    ub = b.astype(acc) / acc(sb)
+    if not (np.all(np.isfinite(ua)) and np.all(np.isfinite(ub))):
+        # infinite components: only their directions matter
+        ua = np.where(np.isinf(a), np.sign(a), 0).astype(acc)
+        ub = np.where(np.isinf(b), np.sign(b), 0).astype(acc)
+    na, nb = np.linalg.norm(ua), np.linalg.norm(ub)
+    if na == 0 or nb == 0:
+        return dt.type(0.0)
+    c = np.dot(ua / na, ub / nb)
+    return dt.type(np.clip(c, -1.0, 1.0))

numguard/_corpus/cosine_similarity/spec.py

@@ -0,0 +1,21 @@
+"""numguard spec for cosine_similarity."""
+
+import numpy as np
+
+FUNCTION = "cosine_similarity"
+
+
+def options(reference):
+    return dict(
+        inputs={"a": "any", "b": "any"},
+        dtypes=["float16", "float32", "float64"],
+        reference=reference,
+        properties=["symmetric", "scale_invariant", "permutation_invariant"],
+        bounds=(-1.0, 1.0),
+        # infinite components have no meaningful cosine; only require no crash
+        ignore=["reference:inf_input"],
+    )
+
+
+def happy_path(fn):
+    assert np.isclose(fn(np.array([1.0, 0.0]), np.array([1.0, 1.0])), np.sqrt(0.5))

numguard/_corpus/cosine_similarity/task.md

@@ -0,0 +1,17 @@
+# Task: cosine similarity
+
+Implement `cosine_similarity(a, b)` in `solution.py`.
+
+```python
+def cosine_similarity(a: np.ndarray, b: np.ndarray) -> np.floating:
+    """Cosine of the angle between two 1-D float vectors of equal length."""
+```
+
+Requirements:
+
+* result in `[-1, 1]`, same dtype as the inputs;
+* if either vector is all zeros (or empty) the similarity is defined as `0.0`
+  (this is the convention of the retrieval system that consumes it) - never NaN;
+* must not overflow or underflow for vectors with very large or very small
+  components (embeddings stored in float16/float32 can have either);
+* NaN in either input gives NaN.

numguard/_corpus/hypot/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/hypot/buggy.py

@@ -0,0 +1,7 @@
+"""Pythagoras, directly."""
+
+import numpy as np
+
+
+def hypot(x, y):
+    return np.sqrt(x * x + y * y)

numguard/_corpus/hypot/reference.py

@@ -0,0 +1,18 @@
+"""Scaled hypot."""
+
+import numpy as np
+
+
+def hypot(x, y):
+    x = np.abs(np.asarray(x))
+    y = np.abs(np.asarray(y))
+    dt = np.result_type(x, y)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        big = np.maximum(x, y)
+        small = np.minimum(x, y)
+        safe = np.where((big > 0) & np.isfinite(big), big, 1).astype(dt)
+        r = small / safe
+        out = big * np.sqrt(1 + r * r)
+        out = np.where(big == 0, 0, out)
+        out = np.where(np.isinf(x) | np.isinf(y), np.inf, out)
+    return out.astype(dt)

numguard/_corpus/hypot/spec.py

@@ -0,0 +1,21 @@
+"""numguard spec for hypot."""
+
+import numpy as np
+
+FUNCTION = "hypot"
+
+
+def options(reference):
+    from numguard import longdouble
+
+    return dict(
+        inputs={"x": "any", "y": "any"},
+        dtypes=["float32", "float64"],
+        reference=longdouble(np.hypot),
+        properties=["symmetric", "scale_equivariant:1", "even", "permutation_equivariant"],
+        nan="ignore",  # hypot(inf, nan) == inf by IEEE 754; the reference covers NaN
+    )
+
+
+def happy_path(fn):
+    assert np.allclose(fn(np.array([3.0, 5.0]), np.array([4.0, 12.0])), [5.0, 13.0])

numguard/_corpus/hypot/task.md

@@ -0,0 +1,15 @@
+# Task: hypot
+
+Implement `hypot(x, y)` in `solution.py` **without calling `np.hypot`**.
+
+```python
+def hypot(x: np.ndarray, y: np.ndarray) -> np.ndarray:
+    """Elementwise sqrt(x**2 + y**2) for same-shape float arrays; same dtype."""
+```
+
+Requirements:
+
+* no intermediate overflow or underflow: `hypot(3e200, 4e200) == 5e200` and
+  `hypot(3e-200, 4e-200) == 5e-200`;
+* `hypot(inf, nan)` is `inf` (IEEE 754); otherwise NaN propagates;
+* symmetric in its arguments and independent of their signs.

numguard/_corpus/log1p/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/log1p/buggy.py

@@ -0,0 +1,7 @@
+"""Direct formula."""
+
+import numpy as np
+
+
+def log1p(x):
+    return np.log(1 + x)

numguard/_corpus/log1p/reference.py

@@ -0,0 +1,15 @@
+"""log1p via the classic correction trick (Goldberg / HP-15C), no np.log1p."""
+
+import numpy as np
+
+
+def log1p(x):
+    x = np.asarray(x)
+    with np.errstate(divide="ignore", invalid="ignore"):
+        u = x.dtype.type(1) + x
+        d = u - x.dtype.type(1)
+        # where 1 + x rounds to 1, log(1 + x) ~= x (exact to working precision);
+        # otherwise log(u) * x / (u - 1) cancels the rounding error made in u
+        out = np.where(d == 0, x, np.log(u) * (x / np.where(d == 0, 1, d)))
+        out = np.where(np.isinf(u), u, out)
+    return out.astype(x.dtype)

numguard/_corpus/log1p/spec.py

@@ -0,0 +1,30 @@
+"""numguard spec for log1p."""
+
+import numpy as np
+
+from numguard import highprec
+
+FUNCTION = "log1p"
+DOMAIN = "(-1, inf)"
+
+
+def _mp_log1p(x):
+    import mpmath  # only called when mpmath is installed
+
+    return mpmath.log1p(x)
+
+
+def options(reference):
+    return dict(
+        inputs=DOMAIN,
+        dtypes=["float32", "float64"],
+        # an independent high-precision oracle (mpmath if installed, else
+        # np.log1p evaluated in long double) rather than the bundled reference
+        reference=highprec(numpy_fn=np.log1p, mp_fn=_mp_log1p),
+        monotonic="increasing",
+    )
+
+
+def happy_path(fn):
+    x = np.array([0.5, 1.0, 3.0])
+    assert np.allclose(fn(x), np.log(1 + x))

numguard/_corpus/log1p/task.md

@@ -0,0 +1,15 @@
+# Task: log(1 + x)
+
+Implement `log1p(x)` in `solution.py` **without calling `np.log1p`** (the
+point of the exercise is the algorithm; imagine a backend that lacks it).
+
+```python
+def log1p(x: np.ndarray) -> np.ndarray:
+    """Elementwise log(1 + x) for x > -1; same shape and dtype as x."""
+```
+
+Requirements:
+
+* full relative accuracy for tiny `|x|` (e.g. `log1p(1e-10) == 9.9999999995e-11`);
+* `log1p(-0.0)` is `-0.0`, `log1p(inf)` is `inf`, NaN propagates;
+* elementwise: works for any shape, including empty arrays.

numguard/_corpus/logsumexp/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/logsumexp/buggy.py

@@ -0,0 +1,7 @@
+"""Direct translation of the formula."""
+
+import numpy as np
+
+
+def logsumexp(x):
+    return np.log(np.sum(np.exp(x)))

numguard/_corpus/logsumexp/reference.py

@@ -0,0 +1,16 @@
+"""Max-shifted logsumexp."""
+
+import numpy as np
+
+
+def logsumexp(x):
+    x = np.asarray(x)
+    if x.size == 0:
+        return x.dtype.type(-np.inf)
+    m = np.max(x)
+    if np.isnan(m):
+        return m
+    if not np.isfinite(m):
+        # +inf dominates; if every element is -inf the result is -inf
+        return m
+    return (m + np.log(np.sum(np.exp(x - m)))).astype(x.dtype)

numguard/_corpus/logsumexp/spec.py

@@ -0,0 +1,20 @@
+"""numguard spec for logsumexp."""
+
+import numpy as np
+
+FUNCTION = "logsumexp"
+
+
+def options(reference):
+    return dict(
+        inputs="any",
+        dtypes=["float32", "float64"],
+        reference=reference,
+        properties=["translation_equivariant"],
+        nan="propagate",
+    )
+
+
+def happy_path(fn):
+    x = np.array([1.0, 2.0, 3.0])
+    assert np.isclose(fn(x), np.log(np.exp(1) + np.exp(2) + np.exp(3)))

numguard/_corpus/logsumexp/task.md

@@ -0,0 +1,15 @@
+# Task: logsumexp
+
+Implement `logsumexp(x)` in `solution.py`.
+
+```python
+def logsumexp(x: np.ndarray) -> np.floating:
+    """Return log(sum(exp(x))) over all elements of the 1-D float array `x`."""
+```
+
+Requirements:
+
+* return a scalar of the same floating dtype as `x` (float32 in, float32 out);
+* the result must be accurate for any finite input, including very large or
+  very negative values (e.g. `[1000.0, 1000.0]` -> `1000.6931...`);
+* `logsumexp([])` is `-inf`; NaN in the input gives NaN; `+inf` gives `+inf`.

numguard/_corpus/loo_mean/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/loo_mean/buggy.py

@@ -0,0 +1,9 @@
+"""Closed form, straight from the definition."""
+
+import numpy as np
+
+
+def loo_mean(x):
+    x = np.asarray(x)
+    n = x.size
+    return ((np.sum(x) - x) / (n - 1)).astype(x.dtype)

numguard/_corpus/loo_mean/reference.py

@@ -0,0 +1,22 @@
+"""Leave-one-out means from prefix and suffix sums: no subtraction of x[i]."""
+
+import numpy as np
+
+
+def loo_mean(x):
+    x = np.asarray(x)
+    n = x.size
+    if n == 1:
+        raise ValueError("leave-one-out mean needs at least 2 values")
+    if n == 0:
+        return x.copy()
+    # sum of the others = (sum of elements before i) + (sum of elements after i).
+    # Subtracting x[i] from the full sum instead would cancel catastrophically
+    # when x[i] dominates the total (e.g. [1e16, 1.0, 2.0]). Accumulate in the
+    # widest available float type (long double where the platform has one).
+    acc = np.longdouble if np.finfo(np.longdouble).bits > 64 else np.float64
+    xl = x.astype(acc)
+    zero = np.zeros(1, dtype=acc)
+    prefix = np.concatenate([zero, np.cumsum(xl)[:-1]])
+    suffix = np.concatenate([np.cumsum(xl[::-1])[::-1][1:], zero])
+    return ((prefix + suffix) / (n - 1)).astype(x.dtype)

numguard/_corpus/loo_mean/spec.py

@@ -0,0 +1,25 @@
+"""numguard spec for loo_mean."""
+
+import numpy as np
+
+FUNCTION = "loo_mean"
+
+
+def options(reference):
+    return dict(
+        inputs="any",
+        dtypes=["float32", "float64"],
+        reference=reference,
+        properties=["translation_equivariant", "scale_equivariant:1", "permutation_equivariant"],
+        # with NaN/inf in x, whether the *other* leave-one-out means should
+        # stay finite is a design choice; do not grade it
+        ignore=["reference:nonfinite_input"],
+        extra_cases={
+            "dominant_value": [1e16, 1.0, 2.0],
+            "pair": [3.0, -7.0],
+        },
+    )
+
+
+def happy_path(fn):
+    assert np.allclose(fn(np.array([1.0, 2.0, 3.0, 6.0])), [11 / 3, 10 / 3, 3.0, 2.0])

numguard/_corpus/loo_mean/task.md

@@ -0,0 +1,18 @@
+# Task: leave-one-out means
+
+Implement `loo_mean(x)` in `solution.py`.
+
+```python
+def loo_mean(x: np.ndarray) -> np.ndarray:
+    """out[i] = mean of x with element i removed; same shape and dtype as x."""
+```
+
+Requirements (this is a building block for jackknife estimates and
+leave-one-out influence diagnostics):
+
+* O(n): use the closed form `(sum(x) - x[i]) / (n - 1)` or equivalent;
+* accurate when the data contain values of very different magnitude
+  (e.g. `[1e16, 1.0, 2.0]` -> `[1.5, 5e15 + 1, 5e15 + 0.5]`) and when the data
+  have a large common offset;
+* `len(x) == 1` (no remaining elements) must raise `ValueError`;
+  `len(x) == 2` returns the swapped pair.

numguard/_corpus/mean_float16/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/mean_float16/buggy.py

@@ -0,0 +1,9 @@
+"""Sum then divide, in the input dtype."""
+
+import numpy as np
+
+
+def mean(x):
+    x = np.asarray(x)
+    total = np.sum(x, dtype=x.dtype)
+    return (total / x.dtype.type(x.size)).astype(x.dtype)

numguard/_corpus/mean_float16/reference.py

@@ -0,0 +1,14 @@
+"""Mean with a wide accumulator and overflow-safe scaling."""
+
+import numpy as np
+
+
+def mean(x):
+    x = np.asarray(x)
+    if x.size == 0:
+        raise ValueError("mean of an empty array is undefined")
+    acc = np.float64 if x.dtype.itemsize <= 8 else x.dtype
+    xa = x.astype(acc)
+    # divide first so that a sum of values near float64 max cannot overflow
+    m = np.sum(xa / x.size)
+    return np.asarray(m).astype(x.dtype)[()]

numguard/_corpus/mean_float16/spec.py

@@ -0,0 +1,20 @@
+"""numguard spec for mean (float16 focus)."""
+
+import numpy as np
+
+FUNCTION = "mean"
+
+
+def options(reference):
+    return dict(
+        inputs="any",
+        dtypes=["float16", "float32", "float64"],
+        reference=reference,
+        properties=["permutation_invariant", "translation_equivariant", "scale_equivariant:1"],
+        may_raise=["empty"],
+        large_n=100_000,
+    )
+
+
+def happy_path(fn):
+    assert np.isclose(fn(np.array([1.0, 2.0, 3.0], dtype=np.float16)), 2.0)

numguard/_corpus/mean_float16/task.md

@@ -0,0 +1,15 @@
+# Task: mean of a half-precision array
+
+Implement `mean(x)` in `solution.py`.
+
+```python
+def mean(x: np.ndarray) -> np.floating:
+    """Arithmetic mean of a non-empty 1-D float array; returns a scalar of x's dtype."""
+```
+
+Requirements:
+
+* the result has the same dtype as `x` (float16 in, float16 out);
+* must be accurate for long float16 arrays (e.g. 100,000 values between 1 and 2,
+  sensor data, activations) and for values close to the dtype's maximum;
+* NaN in the input gives NaN.

numguard/_corpus/normalize/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/normalize/buggy.py

@@ -0,0 +1,7 @@
+"""x / ||x||."""
+
+import numpy as np
+
+
+def normalize(x):
+    return x / np.sqrt(np.sum(x * x, axis=-1, keepdims=True))

numguard/_corpus/normalize/reference.py

@@ -0,0 +1,17 @@
+"""Row-wise, scaled L2 normalization with a zero-row guard."""
+
+import numpy as np
+
+
+def normalize(x):
+    x = np.asarray(x)
+    if x.shape[-1] == 0:
+        return x.copy()
+    scale = np.max(np.abs(x), axis=-1, keepdims=True)
+    safe = np.where((scale > 0) & np.isfinite(scale), scale, 1).astype(x.dtype)
+    acc = np.float64 if x.dtype.itemsize < 8 else x.dtype
+    y = x.astype(acc) / safe.astype(acc)
+    norm = np.sqrt(np.sum(y * y, axis=-1, keepdims=True))
+    # zero rows stay zero; a NaN anywhere in a row makes the whole row NaN
+    out = np.where(norm == 0, y, y / np.where(norm == 0, 1, norm))
+    return out.astype(x.dtype)

numguard/_corpus/normalize/spec.py

@@ -0,0 +1,20 @@
+"""numguard spec for normalize."""
+
+import numpy as np
+
+FUNCTION = "normalize"
+
+
+def options(reference):
+    return dict(
+        inputs="any",
+        dtypes=["float16", "float32", "float64"],
+        reference=reference,
+        properties=["scale_invariant", "permutation_equivariant", "odd"],
+        batched=True,
+        bounds=(-1.0, 1.0),
+    )
+
+
+def happy_path(fn):
+    assert np.allclose(fn(np.array([3.0, 4.0])), [0.6, 0.8])

numguard/_corpus/normalize/task.md

@@ -0,0 +1,15 @@
+# Task: L2 normalization
+
+Implement `normalize(x)` in `solution.py`.
+
+```python
+def normalize(x: np.ndarray) -> np.ndarray:
+    """Scale each row (last axis) of x to unit L2 norm; same shape and dtype."""
+```
+
+Requirements:
+
+* rows that are entirely zero are returned unchanged (all zeros) - never NaN;
+* works for rows with very large or very small components without overflow or
+  underflow (the result of a non-zero row always has norm 1);
+* rows are independent: batching along leading axes must not change results.

numguard/_corpus/quantize_dynamic/__init__.py

@@ -0,0 +1 @@
+"""Corpus task folder (data; graded by numguard.corpus)."""

numguard/_corpus/quantize_dynamic/buggy.py

@@ -0,0 +1,13 @@
+"""Naive dynamic quantization: the textbook formula, no guard for a zero range."""
+
+import numpy as np
+
+
+def quantize_dynamic(x):
+    x = np.asarray(x, dtype=np.float32)
+    x_min = np.minimum(x.min(), np.float32(0))
+    x_max = np.maximum(x.max(), np.float32(0))
+    scale = np.float32((x_max - x_min) / np.float32(255))
+    zero_point = np.uint8(np.clip(np.rint(-x_min / scale), 0, 255))
+    y = np.clip(np.rint(x / scale) + zero_point, 0, 255).astype(np.uint8)
+    return y, scale, zero_point

numguard/_corpus/quantize_dynamic/reference.py

@@ -0,0 +1,18 @@
+"""Dynamic quantization that never produces a zero (or overflowing) scale."""
+
+import numpy as np
+
+
+def quantize_dynamic(x):
+    x = np.asarray(x, dtype=np.float32)
+    x_min = np.minimum(x.min(), np.float32(0))
+    x_max = np.maximum(x.max(), np.float32(0))
+    # divide before subtracting so that the range cannot overflow float32
+    scale = np.float32(x_max / np.float32(255) - x_min / np.float32(255))
+    if not scale > 0:
+        # all-zero input (or a range that underflows): any positive scale
+        # represents the data exactly; 1.0 keeps downstream divisions finite
+        scale = np.float32(1.0)
+    zero_point = np.uint8(np.clip(np.rint(-x_min / scale), 0, 255))
+    y = np.clip(np.rint(x / scale) + np.float32(zero_point), 0, 255).astype(np.uint8)
+    return y, scale, zero_point