esets-lib 0.1.0__tar.gz → 0.3.2__tar.gz

{esets_lib-0.1.0 → esets_lib-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: esets-lib
-Version: 0.1.0
+Version: 0.3.2
 Summary: Lazy, index-addressable enumerated sets, including a full combinatorics family (permutations, combinations, arrangements, subsets, partitions, derangements, and Cartesian products)
 Project-URL: Homepage, https://github.com/ffavela/esets
 Project-URL: Repository, https://github.com/ffavela/esets
@@ -50,6 +50,34 @@ still:
 >>>
 ```
 
+## The docs, if you want to skip ahead
+
+This README is a long, informal walkthrough. If you'd rather get to
+the substance directly:
+
+* [COMBINATORICS.md](https://github.com/ffavela/esets/blob/main/COMBINATORICS.md)
+  -- the combinatorics family: permutations, combinations,
+  arrangements, subsets, integer partitions, set partitions,
+  derangements, and Cartesian products, all addressable by index with
+  no enumeration involved.
+* [POKER.md](https://github.com/ffavela/esets/blob/main/POKER.md) --
+  several of those put to work together on one running example, a
+  deck of cards.
+* [COMBINATORIALDB.md](https://github.com/ffavela/esets/blob/main/COMBINATORIALDB.md)
+  -- a second worked example, a shop database: comparing a raw
+  purchase log against a `set`-based, an arrangement-indexed, and a
+  combination-indexed representation, for both correctness and size.
+* [INCLUSIONEXCLUSION.md](https://github.com/ffavela/esets/blob/main/INCLUSIONEXCLUSION.md)
+  -- the library's own counting recursion benchmarked against
+  inclusion-exclusion, with the real performance fixes that
+  benchmarking turned up.
+* [FLOAT64S.md](https://github.com/ffavela/esets/blob/main/FLOAT64S.md)
+  -- an eset that enumerates all 64-bit floats.
+* [TEXTENCODE.md](https://github.com/ffavela/esets/blob/main/TEXTENCODE.md)
+  -- character and word alphabets built from a small text file, encoded
+  with `Arranger` and with `Combinator`+`Permutator` by hand, as a
+  first step toward larger-text, whole-language "compression."
+
 ## What is it? (An informal introduction)
 
 **esets** stands for enumerated sets. They can handle arbitrarily

{esets_lib-0.1.0 → esets_lib-0.3.2}/README.md

@@ -26,6 +26,34 @@ still:
 >>>
 ```
 
+## The docs, if you want to skip ahead
+
+This README is a long, informal walkthrough. If you'd rather get to
+the substance directly:
+
+* [COMBINATORICS.md](https://github.com/ffavela/esets/blob/main/COMBINATORICS.md)
+  -- the combinatorics family: permutations, combinations,
+  arrangements, subsets, integer partitions, set partitions,
+  derangements, and Cartesian products, all addressable by index with
+  no enumeration involved.
+* [POKER.md](https://github.com/ffavela/esets/blob/main/POKER.md) --
+  several of those put to work together on one running example, a
+  deck of cards.
+* [COMBINATORIALDB.md](https://github.com/ffavela/esets/blob/main/COMBINATORIALDB.md)
+  -- a second worked example, a shop database: comparing a raw
+  purchase log against a `set`-based, an arrangement-indexed, and a
+  combination-indexed representation, for both correctness and size.
+* [INCLUSIONEXCLUSION.md](https://github.com/ffavela/esets/blob/main/INCLUSIONEXCLUSION.md)
+  -- the library's own counting recursion benchmarked against
+  inclusion-exclusion, with the real performance fixes that
+  benchmarking turned up.
+* [FLOAT64S.md](https://github.com/ffavela/esets/blob/main/FLOAT64S.md)
+  -- an eset that enumerates all 64-bit floats.
+* [TEXTENCODE.md](https://github.com/ffavela/esets/blob/main/TEXTENCODE.md)
+  -- character and word alphabets built from a small text file, encoded
+  with `Arranger` and with `Combinator`+`Permutator` by hand, as a
+  first step toward larger-text, whole-language "compression."
+
 ## What is it? (An informal introduction)
 
 **esets** stands for enumerated sets. They can handle arbitrarily

{esets_lib-0.1.0 → esets_lib-0.3.2}/esets/besets.py

@@ -17,10 +17,7 @@ class BEvens(BEset):
 
 
 class BWholesSHA256s(BEset):
-    """A blind eset of SHA256s of the Whole numbers. It uses ascii
-    encoding since only decimal numbers are expected.
-
-    """
+    """A blind eset of SHA256s of the Whole numbers. It uses ascii encoding since only decimal numbers are expected."""
 
     def direct_function(self, i):
         return hashlib.sha256(str(i).encode('ascii')).hexdigest()

{esets_lib-0.1.0 → esets_lib-0.3.2}/esets/cesets.py

@@ -109,7 +109,9 @@ class Distinct_Permutator(Distinct_PermutatorABCMixin):
         """Delegating to eset_obj like EMixinABC, but also carrying
         self.elements along when slicing."""
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -289,9 +291,11 @@ class Permutator(PermutatorABCMixin):
         """Delegating to eset_obj like EMixinABC, but also carrying
         self.elements/self.classes along when slicing."""
         if isinstance(key, slice):
-            return type(self)(
+            result = type(self)(
                 xtra_params=(self.eset_obj[key], self.elements, self.classes)
             )
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -422,7 +426,9 @@ class Distinct_Combinator(Distinct_CombinatorABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.elements, self.k))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.elements, self.k))
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -592,9 +598,11 @@ class Combinator(CombinatorABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(
+            result = type(self)(
                 xtra_params=(self.eset_obj[key], self.elements, self.k, self.classes)
             )
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -768,7 +776,9 @@ class Distinct_Arranger(Distinct_ArrangerABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.elements, self.r))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.elements, self.r))
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -798,6 +808,29 @@ class Natural_Multiset_Arranger(Eset):
     arrangement #0 agree with Natural_Arranger's ordering when every
     capacity is 1, and with Natural_Multiset_Permutator's ordering
     when r equals the full multiset size.
+
+    That position-by-position shape is also why ranking's recursion
+    depth is O(classes * r) in the worst case, not O(classes) --
+    each of the r positions can try up to `classes` candidates before
+    landing on the right one. A prototype class-by-class ranking
+    (decide how many of the smallest remaining class, and which of
+    the still-open positions they occupy, via plain get_combination/
+    get_combination_number over positions, then recurse into the next
+    class for the remaining positions) was benchmarked and verified
+    as a correct bijection: it cuts depth to O(classes) and wins big
+    on many-classes/tight-capacity shapes (~470x faster before the
+    memo fix below existed, still much shallower after), but costs
+    more wall-clock time than the position-by-position approach on
+    few-classes/large-r shapes (get_combination_number's own O(r)
+    candidate search per class-step isn't free), and it ranks
+    arrangements in a different order than this class does today, so
+    switching isn't behavior-preserving the way the memo fix is.
+    Shipping it for real would mean dispatching between the two by
+    shape -- the same treatment multiset_combination_count already
+    gives inclusion-exclusion -- plus its own benchmark file, not a
+    blanket replacement. Not attempted here; left as a known, deferred
+    option for whoever next needs ranking to survive a much larger
+    number of classes than it currently does.
     """
 
     def __init__(self, *args, **kwargs):
@@ -929,9 +962,11 @@ class Arranger(ArrangerABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(
+            result = type(self)(
                 xtra_params=(self.eset_obj[key], self.elements, self.r, self.classes)
             )
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -1047,7 +1082,9 @@ class Distinct_Powerset(Distinct_PowersetABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -1188,9 +1225,11 @@ class Powerset(PowersetABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(
+            result = type(self)(
                 xtra_params=(self.eset_obj[key], self.elements, self.classes)
             )
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -1349,7 +1388,9 @@ class Set_Partitioner(Set_PartitionerABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -1508,7 +1549,9 @@ class Distinct_Derangement(Distinct_DerangementABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.elements))
+            result.sliced = True
+            return result
         return super().__getitem__(key)
 
 
@@ -1633,5 +1676,7 @@ class Cartesian_Product(Cartesian_ProductABCMixin):
 
     def __getitem__(self, key):
         if isinstance(key, slice):
-            return type(self)(xtra_params=(self.eset_obj[key], self.sources))
+            result = type(self)(xtra_params=(self.eset_obj[key], self.sources))
+            result.sliced = True
+            return result
         return super().__getitem__(key)

{esets_lib-0.1.0 → esets_lib-0.3.2}/esets/ecombinatorics.py

@@ -153,8 +153,54 @@ def get_combination_number(combination: tuple[int], n: int) -> int | None:
     return rank(list(range(n)), list(combination))
 
 
-def multiset_combination_count(multiplicities: tuple[int, ...], k: int) -> int:
-    memo: dict[tuple[tuple[int, ...], int], int] = {}
+# Below this many remaining classes, inclusion-exclusion's 2**len(rem)
+# subsets are cheap regardless of capacity size -- and above this many
+# remaining classes, that same sum stops being cheap. Below this
+# capacity, the branching recursion's own cost (tied to capacity, not
+# class count) is already small enough that switching buys nothing.
+# Both are load-bearing together, not independently: inclusion-exclusion
+# has its own weak spot (a target near half of a subproblem's own total
+# capacity prunes poorly, regardless of how large that capacity is), so
+# this only dispatches when there are few *enough* classes left that even
+# that weak spot stays cheap -- checked up to 15 classes at capacity 100,
+# worst case (target at exactly half), before shipping this threshold.
+_INCLUSION_EXCLUSION_CLASS_THRESHOLD = 15
+_INCLUSION_EXCLUSION_CAPACITY_THRESHOLD = 15
+
+
+def _inclusion_exclusion_combination_count(
+    rem: tuple[int, ...], remaining_k: int
+) -> int:
+    m = len(rem)
+    total_answer = 0
+
+    def rec(i: int, excess: int, sign: int) -> None:
+        nonlocal total_answer
+        if excess > remaining_k:
+            return
+        if i == m:
+            total_answer += sign * comb(m - 1 + remaining_k - excess, m - 1)
+            return
+        rec(i + 1, excess, sign)
+        rec(i + 1, excess + rem[i] + 1, -sign)
+
+    rec(0, 0, 1)
+    return total_answer
+
+
+def multiset_combination_count(
+    multiplicities: tuple[int, ...],
+    k: int,
+    _memo: dict[tuple[tuple[int, ...], int], int] | None = None,
+) -> int:
+    # get_multiset_combination/get_multiset_combination_number call this
+    # once per candidate tried at every class, and get_multiset_subset/
+    # get_multiset_subset_number call it once per size -- both pass their
+    # own long-lived _memo through every call instead of letting each one
+    # start over from empty, since overlapping subproblems (same
+    # sorted-suffix, same remaining_k) come up constantly across those
+    # calls.
+    memo: dict[tuple[tuple[int, ...], int], int] = {} if _memo is None else _memo
 
     def count(rem: tuple[int, ...], remaining_k: int) -> int:
         key = (rem, remaining_k)
@@ -164,24 +210,63 @@ def multiset_combination_count(multiplicities: tuple[int, ...], k: int) -> int:
             result = 1
         elif not rem:
             result = 0
-        elif remaining_k <= min(rem):
-            # Capacities can't bind: plain stars-and-bars (mset's C1 shortcut).
-            result = comb(len(rem) + remaining_k - 1, remaining_k)
         else:
-            result = sum(
-                count(rem[1:], remaining_k - t)
-                for t in range(min(rem[0], remaining_k) + 1)
-            )
+            total = sum(rem)
+            if remaining_k > total:
+                # Even every remaining class at full capacity can't reach
+                # remaining_k: no need to branch to find that out.
+                result = 0
+            elif remaining_k <= min(rem):
+                # Capacities can't bind: plain stars-and-bars (mset's C1 shortcut).
+                result = comb(len(rem) + remaining_k - 1, remaining_k)
+            elif total - remaining_k <= min(rem):
+                # Gaps can't bind: x_i <-> c_i - x_i is a bijection between
+                # assignments summing to remaining_k and ones summing to
+                # total - remaining_k (unused capacity), so the same
+                # "can't bind" shortcut applies to that leftover instead.
+                # Only fires when the leftover slack could fit inside a
+                # single remaining class's own capacity -- when even the
+                # smallest remaining capacity is less than the slack, this
+                # doesn't trigger and the recursion still has to walk down
+                # to the original shortcut above, one class at a time.
+                gap = total - remaining_k
+                result = comb(len(rem) + gap - 1, gap)
+            elif (
+                len(rem) <= _INCLUSION_EXCLUSION_CLASS_THRESHOLD
+                and min(rem) >= _INCLUSION_EXCLUSION_CAPACITY_THRESHOLD
+            ):
+                # Few classes, each with plenty of room: this is exactly
+                # where this recursion's own branching factor (tied to
+                # capacity size, not class count) stops being competitive
+                # with inclusion-exclusion's 2**len(rem), which doesn't
+                # care how large the capacities are at all.
+                result = _inclusion_exclusion_combination_count(rem, remaining_k)
+            else:
+                # t (how many go to this class) can't be so small that the
+                # rest of the classes, even maxed out, can't cover what's
+                # left -- that's a hopeless branch just as much as t being
+                # too large is, so bound the loop on both ends instead of
+                # generating and then discarding those calls.
+                tail_capacity = total - rem[0]
+                lo = max(0, remaining_k - tail_capacity)
+                hi = min(rem[0], remaining_k)
+                result = sum(count(rem[1:], remaining_k - t) for t in range(lo, hi + 1))
         memo[key] = result
         return result
 
-    return count(multiplicities, k)
+    # The count is invariant under reordering the classes (it depends only
+    # on the multiset of capacities, not their positions), but the
+    # recursion's cost isn't: ascending order lets the "capacities can't
+    # bind" shortcut above trigger as soon as only large-capacity classes
+    # are left, instead of branching on them first.
+    return count(tuple(sorted(multiplicities)), k)
 
 
 def get_multiset_combination(
     val: int, multiplicities: tuple[int, ...], k: int
 ) -> tuple[int] | None:
-    total = multiset_combination_count(multiplicities, k)
+    memo: dict[tuple[tuple[int, ...], int], int] = {}
+    total = multiset_combination_count(multiplicities, k, memo)
     if val >= total or val < 0:
         return None
 
@@ -211,7 +296,7 @@ def get_multiset_combination(
         retlist: list[int],
         t: int,
     ) -> list[int]:
-        block = multiset_combination_count(classes[1:], remaining_k - t)
+        block = multiset_combination_count(classes[1:], remaining_k - t, memo)
         if resval < block:
             return place(
                 resval,
@@ -237,6 +322,8 @@ def get_multiset_combination_number(
     ):
         return None
 
+    memo: dict[tuple[tuple[int, ...], int], int] = {}
+
     def rank(
         classes: tuple[int, ...], remaining_k: int, class_id: int, seq: list[int]
     ) -> int:
@@ -257,7 +344,7 @@ def get_multiset_combination_number(
         t: int,
         actual: int,
     ) -> int:
-        block = multiset_combination_count(classes[1:], remaining_k - t)
+        block = multiset_combination_count(classes[1:], remaining_k - t, memo)
         if t == actual:
             return rank(classes[1:], remaining_k - t, class_id + 1, seq[t:])
         return block + locate(classes, remaining_k, class_id, seq, t - 1, actual)
@@ -365,8 +452,18 @@ def get_arrangement_number(arrangement: tuple[int], n: int) -> int | None:
     return get_number(list(arrangement), r)
 
 
-def multiset_arrangement_count(multiplicities: tuple[int, ...], r: int) -> int:
-    memo: dict[tuple[tuple[int, ...], int], int] = {}
+def multiset_arrangement_count(
+    multiplicities: tuple[int, ...],
+    r: int,
+    _memo: dict[tuple[tuple[int, ...], int], int] | None = None,
+) -> int:
+    # get_multiset_arrangement/get_multiset_arrangement_number call this
+    # once per candidate tried at every position, so they pass their own
+    # long-lived _memo through every call instead of letting each call
+    # start over from an empty one -- the two share overlapping
+    # subproblems (same sorted-suffix, same remaining_r) constantly, and
+    # without a shared memo those get recomputed from scratch every time.
+    memo: dict[tuple[tuple[int, ...], int], int] = {} if _memo is None else _memo
 
     def g(rem: tuple[int, ...], remaining_r: int) -> int:
         key = (rem, remaining_r)
@@ -377,23 +474,40 @@ def multiset_arrangement_count(multiplicities: tuple[int, ...], r: int) -> int:
         elif not rem:
             result = 0
         else:
-            # Choose x occurrences of the current class, choose which x of
-            # the remaining_r open slots they take (comb), and recurse on
-            # the rest with the later classes.
-            result = sum(
-                comb(remaining_r, x) * g(rem[1:], remaining_r - x)
-                for x in range(min(rem[0], remaining_r) + 1)
-            )
+            total = sum(rem)
+            if remaining_r > total:
+                # Even every remaining class at full capacity can't reach
+                # remaining_r: no need to branch to find that out.
+                result = 0
+            elif remaining_r <= min(rem):
+                # Capacities can't bind: every one of the remaining_r ordered
+                # slots can freely pick any of the len(rem) remaining classes.
+                result = len(rem) ** remaining_r
+            else:
+                # x (how many go to this class) can't be so small that the
+                # rest of the classes, even maxed out, can't cover what's
+                # left -- bound the loop on both ends instead of generating
+                # and then discarding those calls.
+                tail_capacity = total - rem[0]
+                lo = max(0, remaining_r - tail_capacity)
+                hi = min(rem[0], remaining_r)
+                result = sum(
+                    comb(remaining_r, x) * g(rem[1:], remaining_r - x)
+                    for x in range(lo, hi + 1)
+                )
         memo[key] = result
         return result
 
-    return g(multiplicities, r)
+    # See multiset_combination_count: the count doesn't depend on class
+    # order, but ascending order lets the shortcut above trigger sooner.
+    return g(tuple(sorted(multiplicities)), r)
 
 
 def get_multiset_arrangement(
     val: int, multiplicities: tuple[int, ...], r: int
 ) -> tuple[int] | None:
-    total = multiset_arrangement_count(multiplicities, r)
+    memo: dict[tuple[tuple[int, ...], int], int] = {}
+    total = multiset_arrangement_count(multiplicities, r, memo)
     if val >= total or val < 0:
         return None
 
@@ -419,7 +533,7 @@ def get_multiset_arrangement(
         new_mult = list(remaining_mult)
         new_mult[label] -= 1
         rest_mult = tuple(new_mult)
-        block = multiset_arrangement_count(rest_mult, remaining_r - 1)
+        block = multiset_arrangement_count(rest_mult, remaining_r - 1, memo)
         if resval < block:
             return place(resval, rest_mult, remaining_r - 1, retlist + [label])
         return try_candidate(
@@ -440,6 +554,8 @@ def get_multiset_arrangement_number(
     ):
         return None
 
+    memo: dict[tuple[tuple[int, ...], int], int] = {}
+
     def rank(remaining_mult: tuple[int, ...], remaining_r: int, seq: list[int]) -> int:
         if not seq:
             return 0
@@ -456,7 +572,7 @@ def get_multiset_arrangement_number(
         new_mult = list(remaining_mult)
         new_mult[label] -= 1
         rest_mult = tuple(new_mult)
-        block = multiset_arrangement_count(rest_mult, remaining_r - 1)
+        block = multiset_arrangement_count(rest_mult, remaining_r - 1, memo)
         if label == seq[0]:
             return rank(rest_mult, remaining_r - 1, seq[1:])
         return block + locate(remaining_mult, remaining_r, seq, candidates[1:])
@@ -503,8 +619,10 @@ def get_multiset_subset(val: int, multiplicities: tuple[int, ...]) -> tuple[int]
     if val >= total or val < 0:
         return None
 
+    memo: dict[tuple[tuple[int, ...], int], int] = {}
+
     def try_size(resval: int, k: int) -> tuple[int]:
-        block = multiset_combination_count(multiplicities, k)
+        block = multiset_combination_count(multiplicities, k, memo)
         if resval < block:
             return get_multiset_combination(resval, multiplicities, k)
         return try_size(resval - block, k + 1)
@@ -519,10 +637,14 @@ def get_multiset_subset_number(
     if combo_rank is None:
         return None
 
+    memo: dict[tuple[tuple[int, ...], int], int] = {}
+
     def offset(size: int) -> int:
         if size == 0:
             return 0
-        return multiset_combination_count(multiplicities, size - 1) + offset(size - 1)
+        return multiset_combination_count(multiplicities, size - 1, memo) + offset(
+            size - 1
+        )
 
     return offset(len(subset)) + combo_rank
 

{esets_lib-0.1.0 → esets_lib-0.3.2}/esets/eset.py

@@ -470,7 +470,9 @@ class EABCMixinFactory(abc.ABC):
                 def __getitem__(self, key):
                     """Delegating __getitem__ to the eset_obj"""
                     if isinstance(key, slice):
-                        return type(self)(xtra_params=(self.eset_obj[key],))
+                        result = type(self)(xtra_params=(self.eset_obj[key],))
+                        result.sliced = True
+                        return result
                     elif isinstance(key, int):
                         mix_val = self.get_mix_val(self.eset_obj[key])
                         return mix_val

{esets_lib-0.1.0 → esets_lib-0.3.2}/esets/numeric.py

@@ -386,7 +386,9 @@ class Float64s(Eset):
 
         """
         if isinstance(key, slice):
-            return Float64s(xtra_params=(self.f64tpls[key],))
+            result = Float64s(xtra_params=(self.f64tpls[key],))
+            result.sliced = True
+            return result
         elif isinstance(key, int):
             return tpl2float(self.f64tpls[key])
         raise ValueError('Need a slice or an integer')

{esets_lib-0.1.0 → esets_lib-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "esets-lib"
-version = "0.1.0"
+version = "0.3.2"
 description = "Lazy, index-addressable enumerated sets, including a full combinatorics family (permutations, combinations, arrangements, subsets, partitions, derangements, and Cartesian products)"
 readme = "README.md"
 license = "BSD-3-Clause"