labelarray 0.1.0__tar.gz → 0.1.1__tar.gz

{labelarray-0.1.0 → labelarray-0.1.1}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.1.1 — 2026-10-26
+
+- Grouped float32 sums and means over many small groups are much faster:
+  200,000 values in 96,846 groups (voxels holding one to a few points) now
+  take 6 ms instead of 111. The exact mean of a few float32 values often
+  lies exactly halfway between two float32 values, where the error bound
+  cannot decide the rounding; about one group in ten went to an exact
+  path computed in Python fractions. Groups whose values span a narrow
+  range of exponents now have their exact sums computed as 64-bit integers
+  and rounded with NumPy (integer division kept to 27 or 28 bits with the
+  last bit set when anything is left over, then one rounding to float32),
+  so the Python path is left for groups spanning a wide range. Results are
+  unchanged, bit for bit: the tests compare them with exact rational
+  arithmetic, and the new code gave the same bits as 0.1.0 on two million
+  results.
+
 ## 0.1.0 — 2026-10-25
 
 The first release on its own. labelarray was developed as the array layer

{labelarray-0.1.0/src/labelarray.egg-info → labelarray-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labelarray
-Version: 0.1.0
+Version: 0.1.1
 Summary: Labelled N-D arrays in pure NumPy, with exact label semantics and reproducible reductions
 Author: Rigoberto Leyva Salmeron
 License-Expression: MIT
@@ -46,7 +46,7 @@ It is deliberately small. What it offers that other array libraries do not:
 3. **Collections.** Arrays sharing axes, with one label array per axis,
    joined and aligned under those rules.
 
-**Status:** version `0.1.0`, the first release on its own; the API may still
+**Status:** version `0.1.1`; the API may still
 change before 1.0. What changed in each release is in
 [CHANGELOG.md](CHANGELOG.md).
 

{labelarray-0.1.0 → labelarray-0.1.1}/README.md

@@ -18,7 +18,7 @@ It is deliberately small. What it offers that other array libraries do not:
 3. **Collections.** Arrays sharing axes, with one label array per axis,
    joined and aligned under those rules.
 
-**Status:** version `0.1.0`, the first release on its own; the API may still
+**Status:** version `0.1.1`; the API may still
 change before 1.0. What changed in each release is in
 [CHANGELOG.md](CHANGELOG.md).
 

labelarray-0.1.1/src/labelarray/__version__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

{labelarray-0.1.0 → labelarray-0.1.1}/src/labelarray/sums.py

@@ -214,7 +214,14 @@ def _certify(total, magnitude, terms, counts, op, compensated):
 
 
 def _exact(values, rows, chosen, groups, op, na_rm) -> np.ndarray:
-    """Correctly rounded results for groups *chosen*, from exact sums of their values."""
+    """Correctly rounded results for groups *chosen*, from exact sums of their values.
+
+    Most such groups are small and hold values of nearby magnitudes (their
+    exact mean lies on a float32 tie, where the bound cannot decide): their
+    exact sums fit in 64-bit integers and are rounded with NumPy
+    (``_rounded``). Groups spanning a wider range of exponents are summed and
+    rounded in Python integers and fractions.
+    """
     if rows is None:
         part, codes, count = values, np.zeros(len(values), dtype=np.intp), 1
     else:
@@ -223,27 +230,35 @@ def _exact(values, rows, chosen, groups, op, na_rm) -> np.ndarray:
         codes = remap[rows]
         keep = codes >= 0
         part, codes, count = values[keep], codes[keep], len(chosen)
-    totals, present, special = _exact_sums(part, codes, count, na_rm)
-    out = np.empty(count, dtype=np.float32)
-    for k in range(count):
-        if special[k] is not None:
-            out[k] = special[k]
-        elif op == "sum":
-            out[k] = _round32(totals[k])
-        else:
-            out[k] = _round32(totals[k] / present[k]) if present[k] else np.float32(np.nan)
+    buckets, low, present, nan, plus, minus = _exact_sums(part, codes, count)
+    out = np.full(count, np.nan, dtype=np.float32)
+    undefined = (nan & (not na_rm)) | (plus & minus)
+    infinite = (plus | minus) & ~undefined
+    out[infinite] = np.where(plus[infinite], np.float32(np.inf), np.float32(-np.inf))
+    regular = ~(undefined | infinite)
     if op == "mean":
-        out[(present == 0) & np.array([s is None for s in special])] = np.nan
+        regular &= present > 0  # a mean of no values stays NaN
+    divisor = present if op == "mean" else np.ones(count, dtype=np.int64)
+    whole, fits = _whole(buckets)
+    fast = regular & fits & (divisor < 2**35)  # so the integer quotient below stays within int64
+    if fast.any():
+        out[fast] = _rounded(whole[fast], low - 150, divisor[fast])
+    for k in np.flatnonzero(regular & ~fits):
+        row = buckets[k]
+        total = sum(int(row[j]) << int(j) for j in np.flatnonzero(row)) * Fraction(2) ** (low - 150)
+        out[k] = _round32(total / int(divisor[k]))
     return out
 
 
-def _exact_sums(values, codes, count, na_rm):
-    """Exact sums as Fractions, values present, and NaN or infinity where they decide the result.
+def _exact_sums(values, codes, count):
+    """Exact sums as integer buckets per group and exponent, the lowest exponent, values present, and specials.
 
     A float32 is M * 2**(e - 150) with M a signed integer below 2**24 and e
     from 1 to 254. Integers M with the same e add exactly in float64 for
     fewer than 2**29 values, so they are summed per group and exponent with
-    ``np.bincount``, and the few totals per group combined in Python integers.
+    ``np.bincount``: group k's exact sum is the sum over j of
+    ``buckets[k, j] * 2**(low + j - 150)``. Also, per group, the values
+    present (not NaN), and whether a NaN, +inf, or -inf is among them.
     """
     bits = values.view(np.uint32)
     exponent = ((bits >> 23) & 0xFF).astype(np.intp)
@@ -257,30 +272,70 @@ def _exact_sums(values, codes, count, na_rm):
     has_nan = np.bincount(codes, weights=nan, minlength=count) > 0
     plus = np.bincount(codes, weights=values == np.inf, minlength=count) > 0
     minus = np.bincount(codes, weights=values == -np.inf, minlength=count) > 0
-    totals = [Fraction(0)] * count
+    low, width = 1, 1
     if finite.any():
         low, high = int(exponent[finite].min()), int(exponent[finite].max())
         width = high - low + 1
+    buckets = np.zeros(count * width, dtype=np.int64)
+    if finite.any():
         key = codes[finite] * width + (exponent[finite] - low)
         weights = mantissa[finite].astype(np.float64)
-        buckets = np.zeros(count * width, dtype=np.int64)
         chunk = 1 << 28  # each bucket sum stays below 2**52, so float64 holds it exactly
         for start in range(0, len(key), chunk):
             buckets += np.bincount(key[start:start + chunk], weights=weights[start:start + chunk],
                                    minlength=count * width).astype(np.int64)
-        buckets = buckets.reshape(count, width)
-        scale = Fraction(2) ** (low - 150)
-        for k in range(count):
-            row = buckets[k]
-            whole = sum(int(row[j]) << int(j) for j in np.flatnonzero(row))  # Python integers: shifts beyond 63
-            totals[k] = whole * scale
-    special = [None] * count
-    for k in range(count):
-        if (has_nan[k] and not na_rm) or (plus[k] and minus[k]):
-            special[k] = np.float32(np.nan)
-        elif plus[k] or minus[k]:
-            special[k] = np.float32(np.inf if plus[k] else -np.inf)
-    return totals, present, special
+    return buckets.reshape(count, width), low, present, has_nan, plus, minus
+
+
+def _whole(buckets: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Each group's exact sum as one integer (the buckets shifted into place), and where it is below 2**52.
+
+    Where it is, the shifted buckets and their sum stay within int64 and the
+    sum is exact in float64 too; other groups need Python integers.
+    """
+    shifts = np.arange(buckets.shape[1])
+    bound = (np.abs(buckets).astype(np.float64) * np.ldexp(1.0, shifts)).sum(axis=1)  # exact terms; rounding is small
+    fits = bound < 2.0**52
+    whole = np.zeros(len(buckets), dtype=np.int64)
+    if fits.any():
+        # Shifts of zero buckets beyond 62 bits are clamped; a nonzero bucket that far up does not fit.
+        whole[fits] = np.left_shift(buckets[fits], np.minimum(shifts, 62)).sum(axis=1)
+    return whole, fits
+
+
+def _rounded(whole: np.ndarray, scale: int, divisor: np.ndarray) -> np.ndarray:
+    """``whole * 2**scale / divisor`` correctly rounded to float32, ties to even, for |whole| below 2**52.
+
+    The quotient is taken in integers to 27 or 28 significant bits, with its
+    last bit set when anything was left over ("round to odd"); with at least
+    two bits more than float32 keeps, the one rounding from float64 to
+    float32 then rounds as the exact quotient would, subnormals included.
+    """
+    sign = np.where(whole < 0, -1.0, 1.0)
+    size = np.abs(whole)
+    divisor = divisor.astype(np.int64)
+    zero = size == 0
+    size = np.where(zero, 1, size)  # placeholders; zero sums are +0.0, as NumPy gives them
+    size_bits = np.frexp(size.astype(np.float64))[1].astype(np.int64)  # bit lengths, exact below 2**53
+    divisor_bits = np.frexp(divisor.astype(np.float64))[1].astype(np.int64)
+    up = 27 + divisor_bits - size_bits  # shift so the quotient has 27 or 28 bits
+    quotient = np.empty(len(size), dtype=np.int64)
+    rest = np.empty(len(size), dtype=bool)
+    left = up >= 0
+    if left.any():  # size << up has 27 or 28 more bits than the divisor: below 2**63 for divisors below 2**35
+        numerator = np.left_shift(size[left], up[left])
+        quotient[left], remainder = np.divmod(numerator, divisor[left])
+        rest[left] = remainder != 0
+    right = ~left
+    if right.any():
+        whole_part, remainder = np.divmod(size[right], divisor[right])
+        down = -up[right]
+        quotient[right] = np.right_shift(whole_part, down)
+        rest[right] = (remainder != 0) | ((whole_part & ((np.int64(1) << down) - 1)) != 0)
+    quotient |= rest.astype(np.int64)
+    result = np.ldexp(sign * quotient.astype(np.float64), scale - up).astype(np.float32)
+    result[zero] = np.float32(0.0)
+    return result
 
 
 def _round32(value: Fraction) -> np.float32:

{labelarray-0.1.0 → labelarray-0.1.1/src/labelarray.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: labelarray
-Version: 0.1.0
+Version: 0.1.1
 Summary: Labelled N-D arrays in pure NumPy, with exact label semantics and reproducible reductions
 Author: Rigoberto Leyva Salmeron
 License-Expression: MIT
@@ -46,7 +46,7 @@ It is deliberately small. What it offers that other array libraries do not:
 3. **Collections.** Arrays sharing axes, with one label array per axis,
    joined and aligned under those rules.
 
-**Status:** version `0.1.0`, the first release on its own; the API may still
+**Status:** version `0.1.1`; the API may still
 change before 1.0. What changed in each release is in
 [CHANGELOG.md](CHANGELOG.md).
 

{labelarray-0.1.0 → labelarray-0.1.1}/tests/test_sums.py

@@ -61,9 +61,14 @@ def expected(values: np.ndarray, op: str, na_rm: bool) -> np.float32:
 
 
 def same_bits(a, b) -> bool:
-    a, b = np.asarray(a, F32), np.asarray(b, F32)
+    return not differing(a, b).size
+
+
+def differing(a, b) -> np.ndarray:
+    """Where *a* and *b* differ in their bits, NaN counting as equal to NaN."""
+    a, b = np.atleast_1d(np.asarray(a, F32)), np.atleast_1d(np.asarray(b, F32))
     both_nan = np.isnan(a) & np.isnan(b)
-    return bool(np.all(both_nan | (a.view(np.uint32) == b.view(np.uint32))))
+    return np.flatnonzero(~(both_nan | (a.view(np.uint32) == b.view(np.uint32))))
 
 
 def corpus():
@@ -233,3 +238,84 @@ def test_compiled_kernels_run_only_from_a_size_where_they_pay(monkeypatch):
     sums.reduce(many, "sum", (0,))
     sums.reduce(many[0, :sums.COMPILED_FROM], "mean", (0,), codes=rng.integers(0, 5, sums.COMPILED_FROM), groups=5)
     assert calls == ["in_order", "grouped_estimate"]
+
+
+# ── Many tiny groups, where exact means and sums often lie on float32 ties ──
+
+
+def tiny_groups(seed, count=3000, spread=(0.0, 2.4)):
+    """Groups of 1 to 4 float32 values, many of whose exact sums and means are float32 ties."""
+    rng = np.random.default_rng(seed)
+    sizes = rng.integers(1, 5, count)
+    keys = np.repeat(np.arange(count), sizes)
+    values = rng.uniform(0, 255, len(keys)) * 10.0 ** rng.uniform(*spread, len(keys)) * rng.choice([-1, 1], len(keys))
+    values = values.astype(F32)
+    order = rng.permutation(len(values))
+    return values[order], keys[order]
+
+
+def _reduced(values, keys, count, op, na_rm=False, min_count=None):
+    return sums.reduce(values[:, None], op, (0,), codes=keys, groups=count, na_rm=na_rm, min_count=min_count)[:, 0]
+
+
+@pytest.mark.parametrize("seed", range(6))
+@pytest.mark.parametrize("op", ["sum", "mean"])
+def test_tiny_groups_on_ties_are_correctly_rounded(seed, op):
+    values, keys = tiny_groups(seed)
+    count = int(keys.max()) + 1
+    got = _reduced(values, keys, count, op)
+    groups = [values[keys == k] for k in range(count)]
+    want = np.array([expected(g, op, False) for g in groups], F32)
+    wrong = differing(got, want)
+    assert not wrong.size, [(k, groups[k], got[k], want[k]) for k in wrong[:5]]
+
+
+@pytest.mark.parametrize("na_rm", [False, True])
+def test_tiny_groups_with_subnormals_zeros_and_missing_values(na_rm):
+    rng = np.random.default_rng(7)
+    groups = []
+    for _ in range(2000):
+        size = int(rng.integers(1, 5))
+        kind = rng.integers(0, 6)
+        if kind == 0:
+            group = rng.integers(-2**23, 2**23, size) * 2.0**-149  # subnormals, and ties between them
+        elif kind == 1:
+            group = rng.choice([0.0, -0.0], size)
+        elif kind == 2:
+            group = np.where(rng.random(size) < 0.4, np.nan, rng.uniform(0, 255, size))
+        elif kind == 3:
+            group = rng.uniform(1, 2, size) * rng.choice([1, 2**-126, 2**100], size)  # narrow and wide spreads
+        elif kind == 4:
+            group = rng.choice([np.inf, -np.inf, 1.0], size)
+        else:
+            group = rng.uniform(0, 255, size)
+        groups.append(np.asarray(group, F32))
+    values = np.concatenate(groups)
+    keys = np.repeat(np.arange(len(groups)), [len(g) for g in groups])
+    for op in ("sum", "mean"):
+        got = _reduced(values, keys, len(groups), op, na_rm=na_rm)
+        want = np.array([expected(g, op, na_rm) for g in groups], F32)
+        wrong = differing(got, want)
+        assert not wrong.size, [(op, k, groups[k], got[k], want[k]) for k in wrong[:5]]
+
+
+def test_narrow_groups_are_decided_without_fractions(monkeypatch):
+    values, keys = tiny_groups(11, count=5000)
+    count = int(keys.max()) + 1
+    monkeypatch.setattr(sums, "_round32", lambda value: pytest.fail("a narrow group was decided with fractions"))
+    for op in ("sum", "mean"):
+        _reduced(values, keys, count, op)
+
+
+def test_groups_spanning_wide_exponents_still_add_exactly(monkeypatch):
+    big = 2.0**100
+    groups = [[big, 1.0, -big], [1e30, 3.0, -1e30, 1.0], [2.0**-140, 2.0**120, -(2.0**120)]]
+    values = np.concatenate([np.asarray(g, F32) for g in groups])
+    keys = np.repeat(np.arange(len(groups)), [len(g) for g in groups])
+    calls = []
+    original = sums._round32
+    monkeypatch.setattr(sums, "_round32", lambda value: calls.append(value) or original(value))
+    for op in ("sum", "mean"):
+        got = _reduced(values, keys, len(groups), op)
+        assert same_bits(got, np.array([expected(np.asarray(g, F32), op, False) for g in groups], F32))
+    assert calls  # these need the exact path in Python integers

labelarray-0.1.0/src/labelarray/__version__.py

@@ -1 +0,0 @@
-__version__ = "0.1.0"