Whether this expression contains any free variables, i.e. parameters to a @multiset_function.
+176 @abstractmethod +177 def has_free_variables(self) -> bool: +178 """Whether this expression contains any free variables, i.e. parameters to a @multiset_function.""" +
Whether this expression contains any free variables, i.e. parameters to a @multiset_function.
+185 @abstractmethod -186 def denominator(self) -> int: -187 """The total weight of all paths through this generator. -188 -189 Raises: -190 UnboundMultisetExpressionError if this is called on an expression with free variables. -191 """ +@@ -13216,8 +13261,8 @@180 @abstractmethod +181 def denominator(self) -> int: +182 """The total weight of all paths through this generator. +183 +184 Raises: +185 UnboundMultisetExpressionError if this is called on an expression with free variables. +186 """Raises:
235 def equals(self, other) -> bool: -236 """Whether this expression is logically equal to another object.""" -237 if not isinstance(other, MultisetExpression): -238 return False -239 return self._hash_key == other._hash_key +@@ -13278,9 +13323,9 @@230 def equals(self, other) -> bool: +231 """Whether this expression is logically equal to another object.""" +232 if not isinstance(other, MultisetExpression): +233 return False +234 return self._hash_key == other._hash_keyRaises:
254 def order_preference(self) -> tuple[Order | None, OrderReason]: -255 return merge_order_preferences(*(node.local_order_preference() -256 for node in self._iter_nodes())) +@@ -13298,40 +13343,40 @@249 def order_preference(self) -> tuple[Order | None, OrderReason]: +250 return merge_order_preferences(*(node.local_order_preference() +251 for node in self._iter_nodes()))Raises:
266 def sample(self) -> tuple[tuple, ...]: -267 """EXPERIMENTAL: A single random sample from this generator. -268 -269 This uses the standard `random` package and is not cryptographically -270 secure. -271 -272 Returns: -273 A sorted tuple of outcomes for each output of this generator. -274 """ -275 if not self.outcomes(): -276 raise ValueError('Cannot sample from an empty set of outcomes.') -277 -278 order, order_reason = self.order_preference() -279 -280 if order is not None and order > 0: -281 outcome = self.min_outcome() -282 generated = tuple(self._generate_min(outcome)) -283 else: -284 outcome = self.max_outcome() -285 generated = tuple(self._generate_max(outcome)) -286 -287 cumulative_weights = tuple( -288 itertools.accumulate(g.denominator() * w for g, _, w in generated)) -289 denominator = cumulative_weights[-1] -290 # We don't use random.choices since that is based on floats rather than ints. -291 r = random.randrange(denominator) -292 index = bisect.bisect_right(cumulative_weights, r) -293 popped_generator, counts, _ = generated[index] -294 head = tuple((outcome, ) * count for count in counts) -295 if popped_generator.outcomes(): -296 tail = popped_generator.sample() -297 return tuple(tuple(sorted(h + t)) for h, t, in zip(head, tail)) -298 else: -299 return head +@@ -13360,23 +13405,23 @@261 def sample(self) -> tuple[tuple, ...]: +262 """EXPERIMENTAL: A single random sample from this generator. +263 +264 This uses the standard `random` package and is not cryptographically +265 secure. +266 +267 Returns: +268 A sorted tuple of outcomes for each output of this generator. +269 """ +270 if not self.outcomes(): +271 raise ValueError('Cannot sample from an empty set of outcomes.') +272 +273 order, order_reason = self.order_preference() +274 +275 if order is not None and order > 0: +276 outcome = self.min_outcome() +277 generated = tuple(self._generate_min(outcome)) +278 else: +279 outcome = self.max_outcome() +280 generated = tuple(self._generate_max(outcome)) +281 +282 cumulative_weights = tuple( +283 itertools.accumulate(g.denominator() * w for g, _, w in generated)) +284 denominator = cumulative_weights[-1] +285 # We don't use random.choices since that is based on floats rather than ints. +286 r = random.randrange(denominator) +287 index = bisect.bisect_right(cumulative_weights, r) +288 popped_generator, counts, _ = generated[index] +289 head = tuple((outcome, ) * count for count in counts) +290 if popped_generator.outcomes(): +291 tail = popped_generator.sample() +292 return tuple(tuple(sorted(h + t)) for h, t, in zip(head, tail)) +293 else: +294 return headReturns:
320 def additive_union( -321 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' -322 ) -> 'MultisetExpression[T]': -323 """The combined elements from all of the multisets. -324 -325 Same as `a + b + c + ...`. -326 -327 Any resulting counts that would be negative are set to zero. -328 -329 Example: -330 ```python -331 [1, 2, 2, 3] + [1, 2, 4] -> [1, 1, 2, 2, 2, 3, 4] -332 ``` -333 """ -334 expressions = tuple( -335 implicit_convert_to_expression(arg) for arg in args) -336 return icepool.operator.MultisetAdditiveUnion(*expressions) +@@ -13407,31 +13452,31 @@315 def additive_union( +316 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' +317 ) -> 'MultisetExpression[T]': +318 """The combined elements from all of the multisets. +319 +320 Same as `a + b + c + ...`. +321 +322 Any resulting counts that would be negative are set to zero. +323 +324 Example: +325 ```python +326 [1, 2, 2, 3] + [1, 2, 4] -> [1, 1, 2, 2, 2, 3, 4] +327 ``` +328 """ +329 expressions = tuple( +330 implicit_convert_to_expression(arg) for arg in args) +331 return icepool.operator.MultisetAdditiveUnion(*expressions)Returns:
355 def difference( -356 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' -357 ) -> 'MultisetExpression[T]': -358 """The elements from the left multiset that are not in any of the others. -359 -360 Same as `a - b - c - ...`. -361 -362 Any resulting counts that would be negative are set to zero. +@@ -13470,29 +13515,29 @@350 def difference( +351 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' +352 ) -> 'MultisetExpression[T]': +353 """The elements from the left multiset that are not in any of the others. +354 +355 Same as `a - b - c - ...`. +356 +357 Any resulting counts that would be negative are set to zero. +358 +359 Example: +360 ```python +361 [1, 2, 2, 3] - [1, 2, 4] -> [2, 3] +362 ``` 363 -364 Example: -365 ```python -366 [1, 2, 2, 3] - [1, 2, 4] -> [2, 3] -367 ``` -368 -369 If no arguments are given, the result will be an empty multiset, i.e. -370 all zero counts. -371 -372 Note that, as a multiset operation, this will only cancel elements 1:1. -373 If you want to drop all elements in a set of outcomes regardless of -374 count, either use `drop_outcomes()` instead, or use a large number of -375 counts on the right side. -376 """ -377 expressions = tuple( -378 implicit_convert_to_expression(arg) for arg in args) -379 return icepool.operator.MultisetDifference(*expressions) +364 If no arguments are given, the result will be an empty multiset, i.e. +365 all zero counts. +366 +367 Note that, as a multiset operation, this will only cancel elements 1:1. +368 If you want to drop all elements in a set of outcomes regardless of +369 count, either use `drop_outcomes()` instead, or use a large number of +370 counts on the right side. +371 """ +372 expressions = tuple( +373 implicit_convert_to_expression(arg) for arg in args) +374 return icepool.operator.MultisetDifference(*expressions)Returns:
398 def intersection( -399 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' -400 ) -> 'MultisetExpression[T]': -401 """The elements that all the multisets have in common. -402 -403 Same as `a & b & c & ...`. -404 -405 Any resulting counts that would be negative are set to zero. +@@ -13529,23 +13574,23 @@393 def intersection( +394 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' +395 ) -> 'MultisetExpression[T]': +396 """The elements that all the multisets have in common. +397 +398 Same as `a & b & c & ...`. +399 +400 Any resulting counts that would be negative are set to zero. +401 +402 Example: +403 ```python +404 [1, 2, 2, 3] & [1, 2, 4] -> [1, 2] +405 ``` 406 -407 Example: -408 ```python -409 [1, 2, 2, 3] & [1, 2, 4] -> [1, 2] -410 ``` -411 -412 Note that, as a multiset operation, this will only intersect elements -413 1:1. -414 If you want to keep all elements in a set of outcomes regardless of -415 count, either use `keep_outcomes()` instead, or use a large number of -416 counts on the right side. -417 """ -418 expressions = tuple( -419 implicit_convert_to_expression(arg) for arg in args) -420 return icepool.operator.MultisetIntersection(*expressions) +407 Note that, as a multiset operation, this will only intersect elements +408 1:1. +409 If you want to keep all elements in a set of outcomes regardless of +410 count, either use `keep_outcomes()` instead, or use a large number of +411 counts on the right side. +412 """ +413 expressions = tuple( +414 implicit_convert_to_expression(arg) for arg in args) +415 return icepool.operator.MultisetIntersection(*expressions)Returns:
438 def union( -439 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' -440 ) -> 'MultisetExpression[T]': -441 """The most of each outcome that appear in any of the multisets. -442 -443 Same as `a | b | c | ...`. -444 -445 Any resulting counts that would be negative are set to zero. -446 -447 Example: -448 ```python -449 [1, 2, 2, 3] | [1, 2, 4] -> [1, 2, 2, 3, 4] -450 ``` -451 """ -452 expressions = tuple( -453 implicit_convert_to_expression(arg) for arg in args) -454 return icepool.operator.MultisetUnion(*expressions) +@@ -13576,25 +13621,25 @@433 def union( +434 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' +435 ) -> 'MultisetExpression[T]': +436 """The most of each outcome that appear in any of the multisets. +437 +438 Same as `a | b | c | ...`. +439 +440 Any resulting counts that would be negative are set to zero. +441 +442 Example: +443 ```python +444 [1, 2, 2, 3] | [1, 2, 4] -> [1, 2, 2, 3, 4] +445 ``` +446 """ +447 expressions = tuple( +448 implicit_convert_to_expression(arg) for arg in args) +449 return icepool.operator.MultisetUnion(*expressions)Returns:
474 def symmetric_difference( -475 self, -476 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -477 /) -> 'MultisetExpression[T]': -478 """The elements that appear in the left or right multiset but not both. -479 -480 Same as `a ^ b`. -481 -482 Specifically, this produces the absolute difference between counts. -483 If you don't want negative counts to be used from the inputs, you can -484 do `left.keep_counts('>=', 0) ^ right.keep_counts('>=', 0)`. -485 -486 Example: -487 ```python -488 [1, 2, 2, 3] ^ [1, 2, 4] -> [2, 3, 4] -489 ``` -490 """ -491 other = implicit_convert_to_expression(other) -492 return icepool.operator.MultisetSymmetricDifference(self, other) +@@ -13627,23 +13672,23 @@469 def symmetric_difference( +470 self, +471 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +472 /) -> 'MultisetExpression[T]': +473 """The elements that appear in the left or right multiset but not both. +474 +475 Same as `a ^ b`. +476 +477 Specifically, this produces the absolute difference between counts. +478 If you don't want negative counts to be used from the inputs, you can +479 do `left.keep_counts('>=', 0) ^ right.keep_counts('>=', 0)`. +480 +481 Example: +482 ```python +483 [1, 2, 2, 3] ^ [1, 2, 4] -> [2, 3, 4] +484 ``` +485 """ +486 other = implicit_convert_to_expression(other) +487 return icepool.operator.MultisetSymmetricDifference(self, other)Returns:
494 def keep_outcomes( -495 self, target: -496 'Callable[[T], bool] | Collection[T] | MultisetExpression[T]', -497 /) -> 'MultisetExpression[T]': -498 """Keeps the elements in the target set of outcomes, and drops the rest by setting their counts to zero. -499 -500 This is similar to `intersection()`, except the right side is considered -501 to have unlimited multiplicity. -502 -503 Args: -504 target: A callable returning `True` iff the outcome should be kept, -505 or an expression or collection of outcomes to keep. -506 """ -507 if isinstance(target, MultisetExpression): -508 return icepool.operator.MultisetFilterOutcomesBinary(self, target) -509 else: -510 return icepool.operator.MultisetFilterOutcomes(self, target=target) +@@ -13673,27 +13718,27 @@489 def keep_outcomes( +490 self, target: +491 'Callable[[T], bool] | Collection[T] | MultisetExpression[T]', +492 /) -> 'MultisetExpression[T]': +493 """Keeps the elements in the target set of outcomes, and drops the rest by setting their counts to zero. +494 +495 This is similar to `intersection()`, except the right side is considered +496 to have unlimited multiplicity. +497 +498 Args: +499 target: A callable returning `True` iff the outcome should be kept, +500 or an expression or collection of outcomes to keep. +501 """ +502 if isinstance(target, MultisetExpression): +503 return icepool.operator.MultisetFilterOutcomesBinary(self, target) +504 else: +505 return icepool.operator.MultisetFilterOutcomes(self, target=target)Arguments:
512 def drop_outcomes( -513 self, target: -514 'Callable[[T], bool] | Collection[T] | MultisetExpression[T]', -515 /) -> 'MultisetExpression[T]': -516 """Drops the elements in the target set of outcomes by setting their counts to zero, and keeps the rest. -517 -518 This is similar to `difference()`, except the right side is considered -519 to have unlimited multiplicity. -520 -521 Args: -522 target: A callable returning `True` iff the outcome should be -523 dropped, or an expression or collection of outcomes to drop. -524 """ -525 if isinstance(target, MultisetExpression): -526 return icepool.operator.MultisetFilterOutcomesBinary(self, -527 target, -528 invert=True) -529 else: -530 return icepool.operator.MultisetFilterOutcomes(self, -531 target=target, -532 invert=True) +@@ -13723,19 +13768,19 @@507 def drop_outcomes( +508 self, target: +509 'Callable[[T], bool] | Collection[T] | MultisetExpression[T]', +510 /) -> 'MultisetExpression[T]': +511 """Drops the elements in the target set of outcomes by setting their counts to zero, and keeps the rest. +512 +513 This is similar to `difference()`, except the right side is considered +514 to have unlimited multiplicity. +515 +516 Args: +517 target: A callable returning `True` iff the outcome should be +518 dropped, or an expression or collection of outcomes to drop. +519 """ +520 if isinstance(target, MultisetExpression): +521 return icepool.operator.MultisetFilterOutcomesBinary(self, +522 target, +523 invert=True) +524 else: +525 return icepool.operator.MultisetFilterOutcomes(self, +526 target=target, +527 invert=True)Arguments:
536 def map_counts(*args: -537 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -538 function: Callable[..., int]) -> 'MultisetExpression[T]': -539 """Maps the counts to new counts. -540 -541 Args: -542 function: A function that takes `outcome, *counts` and produces a -543 combined count. -544 """ -545 expressions = tuple( -546 implicit_convert_to_expression(arg) for arg in args) -547 return icepool.operator.MultisetMapCounts(*expressions, -548 function=function) +@@ -13762,17 +13807,17 @@531 def map_counts(*args: +532 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +533 function: Callable[..., int]) -> 'MultisetExpression[T]': +534 """Maps the counts to new counts. +535 +536 Args: +537 function: A function that takes `outcome, *counts` and produces a +538 combined count. +539 """ +540 expressions = tuple( +541 implicit_convert_to_expression(arg) for arg in args) +542 return icepool.operator.MultisetMapCounts(*expressions, +543 function=function)Arguments:
561 def multiply_counts(self, n: int, /) -> 'MultisetExpression[T]': -562 """Multiplies all counts by n. -563 -564 Same as `self * n`. -565 -566 Example: -567 ```python -568 Pool([1, 2, 2, 3]) * 2 -> [1, 1, 2, 2, 2, 2, 3, 3] -569 ``` -570 """ -571 return icepool.operator.MultisetMultiplyCounts(self, constant=n) +@@ -13801,17 +13846,17 @@556 def multiply_counts(self, n: int, /) -> 'MultisetExpression[T]': +557 """Multiplies all counts by n. +558 +559 Same as `self * n`. +560 +561 Example: +562 ```python +563 Pool([1, 2, 2, 3]) * 2 -> [1, 1, 2, 2, 2, 2, 3, 3] +564 ``` +565 """ +566 return icepool.operator.MultisetMultiplyCounts(self, constant=n)Arguments:
599 def divide_counts(self, n: int, /) -> 'MultisetExpression[T]': -600 """Divides all counts by n (rounding down). -601 -602 Same as `self // n`. -603 -604 Example: -605 ```python -606 Pool([1, 2, 2, 3]) // 2 -> [2] -607 ``` -608 """ -609 return icepool.operator.MultisetFloordivCounts(self, constant=n) +@@ -13840,17 +13885,17 @@594 def divide_counts(self, n: int, /) -> 'MultisetExpression[T]': +595 """Divides all counts by n (rounding down). +596 +597 Same as `self // n`. +598 +599 Example: +600 ```python +601 Pool([1, 2, 2, 3]) // 2 -> [2] +602 ``` +603 """ +604 return icepool.operator.MultisetFloordivCounts(self, constant=n)Arguments:
616 def modulo_counts(self, n: int, /) -> 'MultisetExpression[T]': -617 """Moduos all counts by n. -618 -619 Same as `self % n`. -620 -621 Example: -622 ```python -623 Pool([1, 2, 2, 3]) % 2 -> [1, 3] -624 ``` -625 """ -626 return self % n +@@ -13879,25 +13924,25 @@611 def modulo_counts(self, n: int, /) -> 'MultisetExpression[T]': +612 """Moduos all counts by n. +613 +614 Same as `self % n`. +615 +616 Example: +617 ```python +618 Pool([1, 2, 2, 3]) % 2 -> [1, 3] +619 ``` +620 """ +621 return self % nArguments:
638 def keep_counts(self, comparison: Literal['==', '!=', '<=', '<', '>=', -639 '>'], n: int, -640 /) -> 'MultisetExpression[T]': -641 """Keeps counts fitting the comparison, treating the rest as zero. -642 -643 For example, `expression.keep_counts('>=', 2)` would keep pairs, -644 triplets, etc. and drop singles. -645 -646 ```python -647 Pool([1, 2, 2, 3, 3, 3]).keep_counts('>=', 2) -> [2, 2, 3, 3, 3] -648 ``` -649 -650 Args: -651 comparison: The comparison to use. -652 n: The number to compare counts against. -653 """ -654 return icepool.operator.MultisetKeepCounts(self, -655 comparison=comparison, -656 constant=n) +@@ -13932,18 +13977,18 @@633 def keep_counts(self, comparison: Literal['==', '!=', '<=', '<', '>=', +634 '>'], n: int, +635 /) -> 'MultisetExpression[T]': +636 """Keeps counts fitting the comparison, treating the rest as zero. +637 +638 For example, `expression.keep_counts('>=', 2)` would keep pairs, +639 triplets, etc. and drop singles. +640 +641 ```python +642 Pool([1, 2, 2, 3, 3, 3]).keep_counts('>=', 2) -> [2, 2, 3, 3, 3] +643 ``` +644 +645 Args: +646 comparison: The comparison to use. +647 n: The number to compare counts against. +648 """ +649 return icepool.operator.MultisetKeepCounts(self, +650 comparison=comparison, +651 constant=n)Arguments:
658 def unique(self, n: int = 1, /) -> 'MultisetExpression[T]': -659 """Counts each outcome at most `n` times. -660 -661 For example, `generator.unique(2)` would count each outcome at most -662 twice. -663 -664 Example: -665 ```python -666 Pool([1, 2, 2, 3]).unique() -> [1, 2, 3] -667 ``` -668 """ -669 return icepool.operator.MultisetUnique(self, constant=n) +@@ -13973,34 +14018,34 @@653 def unique(self, n: int = 1, /) -> 'MultisetExpression[T]': +654 """Counts each outcome at most `n` times. +655 +656 For example, `generator.unique(2)` would count each outcome at most +657 twice. +658 +659 Example: +660 ```python +661 Pool([1, 2, 2, 3]).unique() -> [1, 2, 3] +662 ``` +663 """ +664 return icepool.operator.MultisetUnique(self, constant=n)Arguments:
684 def keep( -685 self, index: slice | Sequence[int | EllipsisType] | int -686 ) -> 'MultisetExpression[T] | icepool.Die[T] | icepool.MultisetEvaluator[T, T]': -687 """Selects elements after drawing and sorting. +@@ -14041,30 +14086,30 @@679 def keep( +680 self, index: slice | Sequence[int | EllipsisType] | int +681 ) -> 'MultisetExpression[T] | icepool.Die[T] | icepool.MultisetEvaluator[T, T]': +682 """Selects elements after drawing and sorting. +683 +684 This is less capable than the `KeepGenerator` version. +685 In particular, it does not know how many elements it is selecting from, +686 so it must be anchored at the starting end. The advantage is that it +687 can be applied to any expression. 688 -689 This is less capable than the `KeepGenerator` version. -690 In particular, it does not know how many elements it is selecting from, -691 so it must be anchored at the starting end. The advantage is that it -692 can be applied to any expression. -693 -694 The valid types of argument are: -695 -696 * A `slice`. If both start and stop are provided, they must both be -697 non-negative or both be negative. step is not supported. -698 * A sequence of `int` with `...` (`Ellipsis`) at exactly one end. -699 Each sorted element will be counted that many times, with the -700 `Ellipsis` treated as enough zeros (possibly "negative") to -701 fill the rest of the elements. -702 * An `int`, which evaluates by taking the element at the specified -703 index. In this case the result is a `Die` (if fully bound) or a -704 `MultisetEvaluator` (if there are free variables). -705 -706 Use the `[]` operator for the same effect as this method. -707 """ -708 if isinstance(index, int): -709 return icepool.evaluator.KeepEvaluator(index).evaluate(self) -710 else: -711 return icepool.operator.MultisetKeep(self, index=index) +689 The valid types of argument are: +690 +691 * A `slice`. If both start and stop are provided, they must both be +692 non-negative or both be negative. step is not supported. +693 * A sequence of `int` with `...` (`Ellipsis`) at exactly one end. +694 Each sorted element will be counted that many times, with the +695 `Ellipsis` treated as enough zeros (possibly "negative") to +696 fill the rest of the elements. +697 * An `int`, which evaluates by taking the element at the specified +698 index. In this case the result is a `Die` (if fully bound) or a +699 `MultisetEvaluator` (if there are free variables). +700 +701 Use the `[]` operator for the same effect as this method. +702 """ +703 if isinstance(index, int): +704 return icepool.evaluator.KeepEvaluator(index).evaluate(self) +705 else: +706 return icepool.operator.MultisetKeep(self, index=index)Arguments:
730 def lowest(self, -731 keep: int | None = None, -732 drop: int | None = None) -> 'MultisetExpression[T]': -733 """Keep some of the lowest elements from this multiset and drop the rest. -734 -735 In contrast to the die and free function versions, this does not -736 automatically sum the dice. Use `.sum()` afterwards if you want to sum. -737 Alternatively, you can perform some other evaluation. -738 -739 This requires the outcomes to be evaluated in ascending order. -740 -741 Args: -742 keep, drop: These arguments work together: -743 * If neither are provided, the single lowest element -744 will be kept. -745 * If only `keep` is provided, the `keep` lowest elements -746 will be kept. -747 * If only `drop` is provided, the `drop` lowest elements -748 will be dropped and the rest will be kept. -749 * If both are provided, `drop` lowest elements will be dropped, -750 then the next `keep` lowest elements will be kept. -751 """ -752 index = lowest_slice(keep, drop) -753 return self.keep(index) +@@ -14106,30 +14151,30 @@725 def lowest(self, +726 keep: int | None = None, +727 drop: int | None = None) -> 'MultisetExpression[T]': +728 """Keep some of the lowest elements from this multiset and drop the rest. +729 +730 In contrast to the die and free function versions, this does not +731 automatically sum the dice. Use `.sum()` afterwards if you want to sum. +732 Alternatively, you can perform some other evaluation. +733 +734 This requires the outcomes to be evaluated in ascending order. +735 +736 Args: +737 keep, drop: These arguments work together: +738 * If neither are provided, the single lowest element +739 will be kept. +740 * If only `keep` is provided, the `keep` lowest elements +741 will be kept. +742 * If only `drop` is provided, the `drop` lowest elements +743 will be dropped and the rest will be kept. +744 * If both are provided, `drop` lowest elements will be dropped, +745 then the next `keep` lowest elements will be kept. +746 """ +747 index = lowest_slice(keep, drop) +748 return self.keep(index)Arguments:
755 def highest(self, -756 keep: int | None = None, -757 drop: int | None = None) -> 'MultisetExpression[T]': -758 """Keep some of the highest elements from this multiset and drop the rest. -759 -760 In contrast to the die and free function versions, this does not -761 automatically sum the dice. Use `.sum()` afterwards if you want to sum. -762 Alternatively, you can perform some other evaluation. -763 -764 This requires the outcomes to be evaluated in descending order. -765 -766 Args: -767 keep, drop: These arguments work together: -768 * If neither are provided, the single highest element -769 will be kept. -770 * If only `keep` is provided, the `keep` highest elements -771 will be kept. -772 * If only `drop` is provided, the `drop` highest elements -773 will be dropped and the rest will be kept. -774 * If both are provided, `drop` highest elements will be dropped, -775 then the next `keep` highest elements will be kept. -776 """ -777 index = highest_slice(keep, drop) -778 return self.keep(index) +@@ -14171,79 +14216,79 @@750 def highest(self, +751 keep: int | None = None, +752 drop: int | None = None) -> 'MultisetExpression[T]': +753 """Keep some of the highest elements from this multiset and drop the rest. +754 +755 In contrast to the die and free function versions, this does not +756 automatically sum the dice. Use `.sum()` afterwards if you want to sum. +757 Alternatively, you can perform some other evaluation. +758 +759 This requires the outcomes to be evaluated in descending order. +760 +761 Args: +762 keep, drop: These arguments work together: +763 * If neither are provided, the single highest element +764 will be kept. +765 * If only `keep` is provided, the `keep` highest elements +766 will be kept. +767 * If only `drop` is provided, the `drop` highest elements +768 will be dropped and the rest will be kept. +769 * If both are provided, `drop` highest elements will be dropped, +770 then the next `keep` highest elements will be kept. +771 """ +772 index = highest_slice(keep, drop) +773 return self.keep(index)Arguments:
782 def sort_match(self, -783 comparison: Literal['==', '!=', '<=', '<', '>=', '>'], -784 other: 'MultisetExpression[T]', -785 /, -786 order: Order = Order.Descending) -> 'MultisetExpression[T]': -787 """EXPERIMENTAL: Matches elements of `self` with elements of `other` in sorted order, then keeps elements from `self` that fit `comparison` with their partner. +@@ -14310,66 +14355,66 @@777 def sort_match(self, +778 comparison: Literal['==', '!=', '<=', '<', '>=', '>'], +779 other: 'MultisetExpression[T]', +780 /, +781 order: Order = Order.Descending) -> 'MultisetExpression[T]': +782 """EXPERIMENTAL: Matches elements of `self` with elements of `other` in sorted order, then keeps elements from `self` that fit `comparison` with their partner. +783 +784 Extra elements: If `self` has more elements than `other`, whether the +785 extra elements are kept depends on the `order` and `comparison`: +786 * Descending: kept for `'>='`, `'>'` +787 * Ascending: kept for `'<='`, `'<'` 788 -789 Extra elements: If `self` has more elements than `other`, whether the -790 extra elements are kept depends on the `order` and `comparison`: -791 * Descending: kept for `'>='`, `'>'` -792 * Ascending: kept for `'<='`, `'<'` -793 -794 Example: An attacker rolls 3d6 versus a defender's 2d6 in the game of -795 *RISK*. Which pairs did the attacker win? -796 ```python -797 d6.pool(3).highest(2).sort_match('>', d6.pool(2)) -798 ``` -799 -800 Suppose the attacker rolled 6, 4, 3 and the defender 5, 5. -801 In this case the 4 would be blocked since the attacker lost that pair, -802 leaving the attacker's 6 and 3. If you don't want to keep the extra -803 element, you can use `highest`. -804 ```python -805 Pool([6, 4, 3]).sort_match('>', [5, 5]) -> [6, 3] -806 Pool([6, 4, 3]).highest(2).sort_match('>', [5, 5]) -> [6] -807 ``` -808 -809 Contrast `maximum_match()`, which first creates the maximum number of -810 pairs that fit the comparison, not necessarily in sorted order. -811 In the above example, `maximum_match()` would allow the defender to -812 assign their 5s to block both the 4 and the 3. -813 -814 Args: -815 comparison: The comparison to filter by. If you want to drop rather -816 than keep, use the complementary comparison: -817 * `'=='` vs. `'!='` -818 * `'<='` vs. `'>'` -819 * `'>='` vs. `'<'` -820 other: The other multiset to match elements with. -821 order: The order in which to sort before forming matches. -822 Default is descending. -823 """ -824 other = implicit_convert_to_expression(other) -825 -826 match comparison: -827 case '==': -828 lesser, tie, greater = 0, 1, 0 -829 case '!=': -830 lesser, tie, greater = 1, 0, 1 -831 case '<=': -832 lesser, tie, greater = 1, 1, 0 -833 case '<': -834 lesser, tie, greater = 1, 0, 0 -835 case '>=': -836 lesser, tie, greater = 0, 1, 1 -837 case '>': -838 lesser, tie, greater = 0, 0, 1 -839 case _: -840 raise ValueError(f'Invalid comparison {comparison}') -841 -842 if order > 0: -843 left_first = lesser -844 right_first = greater -845 else: -846 left_first = greater -847 right_first = lesser -848 -849 return icepool.operator.MultisetSortMatch(self, -850 other, -851 order=order, -852 tie=tie, -853 left_first=left_first, -854 right_first=right_first) +789 Example: An attacker rolls 3d6 versus a defender's 2d6 in the game of +790 *RISK*. Which pairs did the attacker win? +791 ```python +792 d6.pool(3).highest(2).sort_match('>', d6.pool(2)) +793 ``` +794 +795 Suppose the attacker rolled 6, 4, 3 and the defender 5, 5. +796 In this case the 4 would be blocked since the attacker lost that pair, +797 leaving the attacker's 6 and 3. If you don't want to keep the extra +798 element, you can use `highest`. +799 ```python +800 Pool([6, 4, 3]).sort_match('>', [5, 5]) -> [6, 3] +801 Pool([6, 4, 3]).highest(2).sort_match('>', [5, 5]) -> [6] +802 ``` +803 +804 Contrast `maximum_match()`, which first creates the maximum number of +805 pairs that fit the comparison, not necessarily in sorted order. +806 In the above example, `maximum_match()` would allow the defender to +807 assign their 5s to block both the 4 and the 3. +808 +809 Args: +810 comparison: The comparison to filter by. If you want to drop rather +811 than keep, use the complementary comparison: +812 * `'=='` vs. `'!='` +813 * `'<='` vs. `'>'` +814 * `'>='` vs. `'<'` +815 other: The other multiset to match elements with. +816 order: The order in which to sort before forming matches. +817 Default is descending. +818 """ +819 other = implicit_convert_to_expression(other) +820 +821 match comparison: +822 case '==': +823 lesser, tie, greater = 0, 1, 0 +824 case '!=': +825 lesser, tie, greater = 1, 0, 1 +826 case '<=': +827 lesser, tie, greater = 1, 1, 0 +828 case '<': +829 lesser, tie, greater = 1, 0, 0 +830 case '>=': +831 lesser, tie, greater = 0, 1, 1 +832 case '>': +833 lesser, tie, greater = 0, 0, 1 +834 case _: +835 raise ValueError(f'Invalid comparison {comparison}') +836 +837 if order > 0: +838 left_first = lesser +839 right_first = greater +840 else: +841 left_first = greater +842 right_first = lesser +843 +844 return icepool.operator.MultisetSortMatch(self, +845 other, +846 order=order, +847 tie=tie, +848 left_first=left_first, +849 right_first=right_first)Arguments:
856 def maximum_match_highest( -857 self, comparison: Literal['<=', -858 '<'], other: 'MultisetExpression[T]', /, -859 *, keep: Literal['matched', -860 'unmatched']) -> 'MultisetExpression[T]': -861 """EXPERIMENTAL: Match the highest elements from `self` with even higher (or equal) elements from `other`. -862 -863 This matches elements of `self` with elements of `other`, such that in -864 each pair the element from `self` fits the `comparision` with the -865 element from `other`. As many such pairs of elements will be matched as -866 possible, preferring the highest matchable elements of `self`. -867 Finally, either the matched or unmatched elements from `self` are kept. -868 -869 This requires that outcomes be evaluated in descending order. -870 -871 Example: An attacker rolls a pool of 4d6 and a defender rolls a pool of -872 3d6. Defender dice can be used to block attacker dice of equal or lesser -873 value, and the defender prefers to block the highest attacker dice -874 possible. Which attacker dice were not blocked? -875 ```python -876 d6.pool(4).maximum_match('<=', d6.pool(3), keep='unmatched').sum() -877 ``` -878 -879 Suppose the attacker rolls 6, 4, 3, 1 and the defender rolls 5, 5. -880 Then the result would be [6, 1]. -881 ```python -882 d6.pool([6, 4, 3, 1]).maximum_match('<=', [5, 5], keep='unmatched') -883 -> [6, 1] -884 ``` +@@ -14429,49 +14474,49 @@851 def maximum_match_highest( +852 self, comparison: Literal['<=', +853 '<'], other: 'MultisetExpression[T]', /, +854 *, keep: Literal['matched', +855 'unmatched']) -> 'MultisetExpression[T]': +856 """EXPERIMENTAL: Match the highest elements from `self` with even higher (or equal) elements from `other`. +857 +858 This matches elements of `self` with elements of `other`, such that in +859 each pair the element from `self` fits the `comparision` with the +860 element from `other`. As many such pairs of elements will be matched as +861 possible, preferring the highest matchable elements of `self`. +862 Finally, either the matched or unmatched elements from `self` are kept. +863 +864 This requires that outcomes be evaluated in descending order. +865 +866 Example: An attacker rolls a pool of 4d6 and a defender rolls a pool of +867 3d6. Defender dice can be used to block attacker dice of equal or lesser +868 value, and the defender prefers to block the highest attacker dice +869 possible. Which attacker dice were not blocked? +870 ```python +871 d6.pool(4).maximum_match('<=', d6.pool(3), keep='unmatched').sum() +872 ``` +873 +874 Suppose the attacker rolls 6, 4, 3, 1 and the defender rolls 5, 5. +875 Then the result would be [6, 1]. +876 ```python +877 d6.pool([6, 4, 3, 1]).maximum_match('<=', [5, 5], keep='unmatched') +878 -> [6, 1] +879 ``` +880 +881 Contrast `sort_match()`, which first creates pairs in +882 sorted order and then filters them by `comparison`. +883 In the above example, `sort_matched` would force the defender to match +884 against the 5 and the 4, which would only allow them to block the 4. 885 -886 Contrast `sort_match()`, which first creates pairs in -887 sorted order and then filters them by `comparison`. -888 In the above example, `sort_matched` would force the defender to match -889 against the 5 and the 4, which would only allow them to block the 4. -890 -891 Args: -892 comparison: Either `'<='` or `'<'`. -893 other: The other multiset to match elements with. -894 keep: Whether 'matched' or 'unmatched' elements are to be kept. -895 """ -896 if keep == 'matched': -897 keep_boolean = True -898 elif keep == 'unmatched': -899 keep_boolean = False -900 else: -901 raise ValueError(f"keep must be either 'matched' or 'unmatched'") -902 -903 other = implicit_convert_to_expression(other) -904 match comparison: -905 case '<=': -906 match_equal = True -907 case '<': -908 match_equal = False -909 case _: -910 raise ValueError(f'Invalid comparison {comparison}') -911 return icepool.operator.MultisetMaximumMatch(self, -912 other, -913 order=Order.Descending, -914 match_equal=match_equal, -915 keep=keep_boolean) +886 Args: +887 comparison: Either `'<='` or `'<'`. +888 other: The other multiset to match elements with. +889 keep: Whether 'matched' or 'unmatched' elements are to be kept. +890 """ +891 if keep == 'matched': +892 keep_boolean = True +893 elif keep == 'unmatched': +894 keep_boolean = False +895 else: +896 raise ValueError(f"keep must be either 'matched' or 'unmatched'") +897 +898 other = implicit_convert_to_expression(other) +899 match comparison: +900 case '<=': +901 match_equal = True +902 case '<': +903 match_equal = False +904 case _: +905 raise ValueError(f'Invalid comparison {comparison}') +906 return icepool.operator.MultisetMaximumMatch(self, +907 other, +908 order=Order.Descending, +909 match_equal=match_equal, +910 keep=keep_boolean)Arguments:
917 def maximum_match_lowest( -918 self, comparison: Literal['>=', -919 '>'], other: 'MultisetExpression[T]', /, -920 *, keep: Literal['matched', -921 'unmatched']) -> 'MultisetExpression[T]': -922 """EXPERIMENTAL: Match the lowest elements from `self` with even lower (or equal) elements from `other`. -923 -924 This matches elements of `self` with elements of `other`, such that in -925 each pair the element from `self` fits the `comparision` with the -926 element from `other`. As many such pairs of elements will be matched as -927 possible, preferring the lowest matchable elements of `self`. -928 Finally, either the matched or unmatched elements from `self` are kept. +@@ -14510,19 +14555,19 @@912 def maximum_match_lowest( +913 self, comparison: Literal['>=', +914 '>'], other: 'MultisetExpression[T]', /, +915 *, keep: Literal['matched', +916 'unmatched']) -> 'MultisetExpression[T]': +917 """EXPERIMENTAL: Match the lowest elements from `self` with even lower (or equal) elements from `other`. +918 +919 This matches elements of `self` with elements of `other`, such that in +920 each pair the element from `self` fits the `comparision` with the +921 element from `other`. As many such pairs of elements will be matched as +922 possible, preferring the lowest matchable elements of `self`. +923 Finally, either the matched or unmatched elements from `self` are kept. +924 +925 This requires that outcomes be evaluated in ascending order. +926 +927 Contrast `sort_match()`, which first creates pairs in +928 sorted order and then filters them by `comparison`. 929 -930 This requires that outcomes be evaluated in ascending order. -931 -932 Contrast `sort_match()`, which first creates pairs in -933 sorted order and then filters them by `comparison`. -934 -935 Args: -936 comparison: Either `'>='` or `'>'`. -937 other: The other multiset to match elements with. -938 keep: Whether 'matched' or 'unmatched' elements are to be kept. -939 """ -940 if keep == 'matched': -941 keep_boolean = True -942 elif keep == 'unmatched': -943 keep_boolean = False -944 else: -945 raise ValueError(f"keep must be either 'matched' or 'unmatched'") -946 -947 other = implicit_convert_to_expression(other) -948 match comparison: -949 case '>=': -950 match_equal = True -951 case '>': -952 match_equal = False -953 case _: -954 raise ValueError(f'Invalid comparison {comparison}') -955 return icepool.operator.MultisetMaximumMatch(self, -956 other, -957 order=Order.Ascending, -958 match_equal=match_equal, -959 keep=keep_boolean) +930 Args: +931 comparison: Either `'>='` or `'>'`. +932 other: The other multiset to match elements with. +933 keep: Whether 'matched' or 'unmatched' elements are to be kept. +934 """ +935 if keep == 'matched': +936 keep_boolean = True +937 elif keep == 'unmatched': +938 keep_boolean = False +939 else: +940 raise ValueError(f"keep must be either 'matched' or 'unmatched'") +941 +942 other = implicit_convert_to_expression(other) +943 match comparison: +944 case '>=': +945 match_equal = True +946 case '>': +947 match_equal = False +948 case _: +949 raise ValueError(f'Invalid comparison {comparison}') +950 return icepool.operator.MultisetMaximumMatch(self, +951 other, +952 order=Order.Ascending, +953 match_equal=match_equal, +954 keep=keep_boolean)Arguments:
963 def expand( -964 self, -965 order: Order = Order.Ascending -966 ) -> 'icepool.Die[tuple[T, ...]] | icepool.MultisetEvaluator[T, tuple[T, ...]]': -967 """Evaluation: All elements of the multiset in ascending order. -968 -969 This is expensive and not recommended unless there are few possibilities. -970 -971 Args: -972 order: Whether the elements are in ascending (default) or descending -973 order. -974 """ -975 return icepool.evaluator.ExpandEvaluator(order=order).evaluate(self) +@@ -14551,15 +14596,15 @@958 def expand( +959 self, +960 order: Order = Order.Ascending +961 ) -> 'icepool.Die[tuple[T, ...]] | icepool.MultisetEvaluator[T, tuple[T, ...]]': +962 """Evaluation: All elements of the multiset in ascending order. +963 +964 This is expensive and not recommended unless there are few possibilities. +965 +966 Args: +967 order: Whether the elements are in ascending (default) or descending +968 order. +969 """ +970 return icepool.evaluator.ExpandEvaluator(order=order).evaluate(self)Arguments:
977 def sum( -978 self, -979 map: Callable[[T], U] | Mapping[T, U] | None = None -980 ) -> 'icepool.Die[U] | icepool.MultisetEvaluator[T, U]': -981 """Evaluation: The sum of all elements.""" -982 if map is None: -983 return icepool.evaluator.sum_evaluator.evaluate(self) -984 else: -985 return icepool.evaluator.SumEvaluator(map).evaluate(self) +@@ -14579,18 +14624,18 @@972 def sum( +973 self, +974 map: Callable[[T], U] | Mapping[T, U] | None = None +975 ) -> 'icepool.Die[U] | icepool.MultisetEvaluator[T, U]': +976 """Evaluation: The sum of all elements.""" +977 if map is None: +978 return icepool.evaluator.sum_evaluator.evaluate(self) +979 else: +980 return icepool.evaluator.SumEvaluator(map).evaluate(self)Arguments:
987 def count(self) -> 'icepool.Die[int] | icepool.MultisetEvaluator[T, int]': -988 """Evaluation: The total number of elements in the multiset. +@@ -14618,9 +14663,9 @@982 def count(self) -> 'icepool.Die[int] | icepool.MultisetEvaluator[T, int]': +983 """Evaluation: The total number of elements in the multiset. +984 +985 This is usually not very interesting unless some other operation is +986 performed first. Examples: +987 +988 `generator.unique().count()` will count the number of unique outcomes. 989 -990 This is usually not very interesting unless some other operation is -991 performed first. Examples: -992 -993 `generator.unique().count()` will count the number of unique outcomes. -994 -995 `(generator & [4, 5, 6]).count()` will count up to one each of -996 4, 5, and 6. -997 """ -998 return icepool.evaluator.count_evaluator.evaluate(self) +990 `(generator & [4, 5, 6]).count()` will count up to one each of +991 4, 5, and 6. +992 """ +993 return icepool.evaluator.count_evaluator.evaluate(self)Arguments:
1000 def any(self) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': -1001 """Evaluation: Whether the multiset has at least one positive count. """ -1002 return icepool.evaluator.any_evaluator.evaluate(self) +@@ -14640,15 +14685,15 @@995 def any(self) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': +996 """Evaluation: Whether the multiset has at least one positive count. """ +997 return icepool.evaluator.any_evaluator.evaluate(self)Arguments:
1004 def highest_outcome_and_count( -1005 self -1006 ) -> 'icepool.Die[tuple[T, int]] | icepool.MultisetEvaluator[T, tuple[T, int]]': -1007 """Evaluation: The highest outcome with positive count, along with that count. -1008 -1009 If no outcomes have positive count, the min outcome will be returned with 0 count. -1010 """ -1011 return icepool.evaluator.highest_outcome_and_count_evaluator.evaluate( -1012 self) +@@ -14670,27 +14715,27 @@999 def highest_outcome_and_count( +1000 self +1001 ) -> 'icepool.Die[tuple[T, int]] | icepool.MultisetEvaluator[T, tuple[T, int]]': +1002 """Evaluation: The highest outcome with positive count, along with that count. +1003 +1004 If no outcomes have positive count, the min outcome will be returned with 0 count. +1005 """ +1006 return icepool.evaluator.highest_outcome_and_count_evaluator.evaluate( +1007 self)Arguments:
1014 def all_counts( -1015 self, -1016 filter: int | Literal['all'] = 1 -1017 ) -> 'icepool.Die[tuple[int, ...]] | icepool.MultisetEvaluator[T, tuple[int, ...]]': -1018 """Evaluation: Sorted tuple of all counts, i.e. the sizes of all matching sets. -1019 -1020 The sizes are in **descending** order. +@@ -14726,10 +14771,10 @@1009 def all_counts( +1010 self, +1011 filter: int | Literal['all'] = 1 +1012 ) -> 'icepool.Die[tuple[int, ...]] | icepool.MultisetEvaluator[T, tuple[int, ...]]': +1013 """Evaluation: Sorted tuple of all counts, i.e. the sizes of all matching sets. +1014 +1015 The sizes are in **descending** order. +1016 +1017 Args: +1018 filter: Any counts below this value will not be in the output. +1019 For example, `filter=2` will only produce pairs and better. +1020 If `None`, no filtering will be done. 1021 -1022 Args: -1023 filter: Any counts below this value will not be in the output. -1024 For example, `filter=2` will only produce pairs and better. -1025 If `None`, no filtering will be done. -1026 -1027 Why not just place `keep_counts_ge()` before this? -1028 `keep_counts_ge()` operates by setting counts to zero, so you -1029 would still need an argument to specify whether you want to -1030 output zero counts. So we might as well use the argument to do -1031 both. -1032 """ -1033 return icepool.evaluator.AllCountsEvaluator( -1034 filter=filter).evaluate(self) +1022 Why not just place `keep_counts_ge()` before this? +1023 `keep_counts_ge()` operates by setting counts to zero, so you +1024 would still need an argument to specify whether you want to +1025 output zero counts. So we might as well use the argument to do +1026 both. +1027 """ +1028 return icepool.evaluator.AllCountsEvaluator( +1029 filter=filter).evaluate(self)Arguments:
1036 def largest_count( -1037 self) -> 'icepool.Die[int] | icepool.MultisetEvaluator[T, int]': -1038 """Evaluation: The size of the largest matching set among the elements.""" -1039 return icepool.evaluator.largest_count_evaluator.evaluate(self) +@@ -14749,12 +14794,12 @@1031 def largest_count( +1032 self) -> 'icepool.Die[int] | icepool.MultisetEvaluator[T, int]': +1033 """Evaluation: The size of the largest matching set among the elements.""" +1034 return icepool.evaluator.largest_count_evaluator.evaluate(self)Arguments:
1041 def largest_count_and_outcome( -1042 self -1043 ) -> 'icepool.Die[tuple[int, T]] | icepool.MultisetEvaluator[T, tuple[int, T]]': -1044 """Evaluation: The largest matching set among the elements and the corresponding outcome.""" -1045 return icepool.evaluator.largest_count_and_outcome_evaluator.evaluate( -1046 self) +@@ -14774,28 +14819,28 @@1036 def largest_count_and_outcome( +1037 self +1038 ) -> 'icepool.Die[tuple[int, T]] | icepool.MultisetEvaluator[T, tuple[int, T]]': +1039 """Evaluation: The largest matching set among the elements and the corresponding outcome.""" +1040 return icepool.evaluator.largest_count_and_outcome_evaluator.evaluate( +1041 self)Arguments:
1054 def count_subset( -1055 self, -1056 divisor: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -1057 /, -1058 *, -1059 empty_divisor: int | None = None -1060 ) -> 'icepool.Die[int] | icepool.MultisetEvaluator[T, int]': -1061 """Evaluation: The number of times the divisor is contained in this multiset. -1062 -1063 Args: -1064 divisor: The multiset to divide by. -1065 empty_divisor: If the divisor is empty, the outcome will be this. -1066 If not set, `ZeroDivisionError` will be raised for an empty -1067 right side. -1068 -1069 Raises: -1070 ZeroDivisionError: If the divisor may be empty and -1071 empty_divisor_outcome is not set. -1072 """ -1073 divisor = implicit_convert_to_expression(divisor) -1074 return icepool.evaluator.CountSubsetEvaluator( -1075 empty_divisor=empty_divisor).evaluate(self, divisor) +@@ -14831,14 +14876,14 @@1049 def count_subset( +1050 self, +1051 divisor: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +1052 /, +1053 *, +1054 empty_divisor: int | None = None +1055 ) -> 'icepool.Die[int] | icepool.MultisetEvaluator[T, int]': +1056 """Evaluation: The number of times the divisor is contained in this multiset. +1057 +1058 Args: +1059 divisor: The multiset to divide by. +1060 empty_divisor: If the divisor is empty, the outcome will be this. +1061 If not set, `ZeroDivisionError` will be raised for an empty +1062 right side. +1063 +1064 Raises: +1065 ZeroDivisionError: If the divisor may be empty and +1066 empty_divisor_outcome is not set. +1067 """ +1068 divisor = implicit_convert_to_expression(divisor) +1069 return icepool.evaluator.CountSubsetEvaluator( +1070 empty_divisor=empty_divisor).evaluate(self, divisor)Raises:
1077 def largest_straight( -1078 self: 'MultisetExpression[int]' -1079 ) -> 'icepool.Die[int] | icepool.MultisetEvaluator[int, int]': -1080 """Evaluation: The size of the largest straight among the elements. -1081 -1082 Outcomes must be `int`s. -1083 """ -1084 return icepool.evaluator.largest_straight_evaluator.evaluate(self) +@@ -14860,15 +14905,15 @@1072 def largest_straight( +1073 self: 'MultisetExpression[int]' +1074 ) -> 'icepool.Die[int] | icepool.MultisetEvaluator[int, int]': +1075 """Evaluation: The size of the largest straight among the elements. +1076 +1077 Outcomes must be `int`s. +1078 """ +1079 return icepool.evaluator.largest_straight_evaluator.evaluate(self)Raises:
1086 def largest_straight_and_outcome( -1087 self: 'MultisetExpression[int]' -1088 ) -> 'icepool.Die[tuple[int, int]] | icepool.MultisetEvaluator[int, tuple[int, int]]': -1089 """Evaluation: The size of the largest straight among the elements and the highest outcome in that straight. -1090 -1091 Outcomes must be `int`s. -1092 """ -1093 return icepool.evaluator.largest_straight_and_outcome_evaluator.evaluate( -1094 self) +@@ -14890,18 +14935,18 @@1081 def largest_straight_and_outcome( +1082 self: 'MultisetExpression[int]' +1083 ) -> 'icepool.Die[tuple[int, int]] | icepool.MultisetEvaluator[int, tuple[int, int]]': +1084 """Evaluation: The size of the largest straight among the elements and the highest outcome in that straight. +1085 +1086 Outcomes must be `int`s. +1087 """ +1088 return icepool.evaluator.largest_straight_and_outcome_evaluator.evaluate( +1089 self)Raises:
1096 def all_straights( -1097 self: 'MultisetExpression[int]' -1098 ) -> 'icepool.Die[tuple[int, ...]] | icepool.MultisetEvaluator[int, tuple[int, ...]]': -1099 """Evaluation: The sizes of all straights. -1100 -1101 The sizes are in **descending** order. -1102 -1103 Each element can only contribute to one straight, though duplicate -1104 elements can produces straights that overlap in outcomes. In this case, -1105 elements are preferentially assigned to the longer straight. -1106 """ -1107 return icepool.evaluator.all_straights_evaluator.evaluate(self) +@@ -14927,18 +14972,18 @@1091 def all_straights( +1092 self: 'MultisetExpression[int]' +1093 ) -> 'icepool.Die[tuple[int, ...]] | icepool.MultisetEvaluator[int, tuple[int, ...]]': +1094 """Evaluation: The sizes of all straights. +1095 +1096 The sizes are in **descending** order. +1097 +1098 Each element can only contribute to one straight, though duplicate +1099 elements can produces straights that overlap in outcomes. In this case, +1100 elements are preferentially assigned to the longer straight. +1101 """ +1102 return icepool.evaluator.all_straights_evaluator.evaluate(self)Raises:
1109 def all_straights_reduce_counts( -1110 self: 'MultisetExpression[int]', -1111 reducer: Callable[[int, int], int] = operator.mul -1112 ) -> 'icepool.Die[tuple[tuple[int, int], ...]] | icepool.MultisetEvaluator[int, tuple[tuple[int, int], ...]]': -1113 """Experimental: All straights with a reduce operation on the counts. -1114 -1115 This can be used to evaluate e.g. cribbage-style straight counting. -1116 -1117 The result is a tuple of `(run_length, run_score)`s. -1118 """ -1119 return icepool.evaluator.AllStraightsReduceCountsEvaluator( -1120 reducer=reducer).evaluate(self) +@@ -14962,33 +15007,33 @@1104 def all_straights_reduce_counts( +1105 self: 'MultisetExpression[int]', +1106 reducer: Callable[[int, int], int] = operator.mul +1107 ) -> 'icepool.Die[tuple[tuple[int, int], ...]] | icepool.MultisetEvaluator[int, tuple[tuple[int, int], ...]]': +1108 """Experimental: All straights with a reduce operation on the counts. +1109 +1110 This can be used to evaluate e.g. cribbage-style straight counting. +1111 +1112 The result is a tuple of `(run_length, run_score)`s. +1113 """ +1114 return icepool.evaluator.AllStraightsReduceCountsEvaluator( +1115 reducer=reducer).evaluate(self)Raises:
1122 def argsort(self: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -1123 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -1124 order: Order = Order.Descending, -1125 limit: int | None = None): -1126 """Experimental: Returns the indexes of the originating multisets for each rank in their additive union. -1127 -1128 Example: -1129 ```python -1130 MultisetExpression.argsort([10, 9, 5], [9, 9]) -1131 ``` -1132 produces -1133 ```python -1134 ((0,), (0, 1, 1), (0,)) -1135 ``` -1136 -1137 Args: -1138 self, *args: The multiset expressions to be evaluated. -1139 order: Which order the ranks are to be emitted. Default is descending. -1140 limit: How many ranks to emit. Default will emit all ranks, which -1141 makes the length of each outcome equal to -1142 `additive_union(+self, +arg1, +arg2, ...).unique().count()` -1143 """ -1144 self = implicit_convert_to_expression(self) -1145 converted_args = [implicit_convert_to_expression(arg) for arg in args] -1146 return icepool.evaluator.ArgsortEvaluator(order=order, -1147 limit=limit).evaluate( -1148 self, *converted_args) +@@ -15032,23 +15077,23 @@1117 def argsort(self: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +1118 *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +1119 order: Order = Order.Descending, +1120 limit: int | None = None): +1121 """Experimental: Returns the indexes of the originating multisets for each rank in their additive union. +1122 +1123 Example: +1124 ```python +1125 MultisetExpression.argsort([10, 9, 5], [9, 9]) +1126 ``` +1127 produces +1128 ```python +1129 ((0,), (0, 1, 1), (0,)) +1130 ``` +1131 +1132 Args: +1133 self, *args: The multiset expressions to be evaluated. +1134 order: Which order the ranks are to be emitted. Default is descending. +1135 limit: How many ranks to emit. Default will emit all ranks, which +1136 makes the length of each outcome equal to +1137 `additive_union(+self, +arg1, +arg2, ...).unique().count()` +1138 """ +1139 self = implicit_convert_to_expression(self) +1140 converted_args = [implicit_convert_to_expression(arg) for arg in args] +1141 return icepool.evaluator.ArgsortEvaluator(order=order, +1142 limit=limit).evaluate( +1143 self, *converted_args)Arguments:
1191 def issubset( -1192 self, -1193 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -1194 /) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': -1195 """Evaluation: Whether this multiset is a subset of the other multiset. +@@ -15078,33 +15123,33 @@1186 def issubset( +1187 self, +1188 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +1189 /) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': +1190 """Evaluation: Whether this multiset is a subset of the other multiset. +1191 +1192 Specifically, if this multiset has a lesser or equal count for each +1193 outcome than the other multiset, this evaluates to `True`; +1194 if there is some outcome for which this multiset has a greater count +1195 than the other multiset, this evaluates to `False`. 1196 -1197 Specifically, if this multiset has a lesser or equal count for each -1198 outcome than the other multiset, this evaluates to `True`; -1199 if there is some outcome for which this multiset has a greater count -1200 than the other multiset, this evaluates to `False`. -1201 -1202 `issubset` is the same as `self <= other`. -1203 -1204 `self < other` evaluates a proper subset relation, which is the same -1205 except the result is `False` if the two multisets are exactly equal. -1206 """ -1207 return self._compare(other, icepool.evaluator.IsSubsetEvaluator) +1197 `issubset` is the same as `self <= other`. +1198 +1199 `self < other` evaluates a proper subset relation, which is the same +1200 except the result is `False` if the two multisets are exactly equal. +1201 """ +1202 return self._compare(other, icepool.evaluator.IsSubsetEvaluator)Arguments:
1226 def issuperset( -1227 self, -1228 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -1229 /) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': -1230 """Evaluation: Whether this multiset is a superset of the other multiset. -1231 -1232 Specifically, if this multiset has a greater or equal count for each -1233 outcome than the other multiset, this evaluates to `True`; -1234 if there is some outcome for which this multiset has a lesser count -1235 than the other multiset, this evaluates to `False`. -1236 -1237 A typical use of this evaluation is testing for the presence of a -1238 combo of cards in a hand, e.g. -1239 -1240 ```python -1241 deck.deal(5) >= ['a', 'a', 'b'] -1242 ``` +@@ -15145,16 +15190,16 @@1221 def issuperset( +1222 self, +1223 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +1224 /) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': +1225 """Evaluation: Whether this multiset is a superset of the other multiset. +1226 +1227 Specifically, if this multiset has a greater or equal count for each +1228 outcome than the other multiset, this evaluates to `True`; +1229 if there is some outcome for which this multiset has a lesser count +1230 than the other multiset, this evaluates to `False`. +1231 +1232 A typical use of this evaluation is testing for the presence of a +1233 combo of cards in a hand, e.g. +1234 +1235 ```python +1236 deck.deal(5) >= ['a', 'a', 'b'] +1237 ``` +1238 +1239 represents the chance that a deal of 5 cards contains at least two 'a's +1240 and one 'b'. +1241 +1242 `issuperset` is the same as `self >= other`. 1243 -1244 represents the chance that a deal of 5 cards contains at least two 'a's -1245 and one 'b'. -1246 -1247 `issuperset` is the same as `self >= other`. -1248 -1249 `self > other` evaluates a proper superset relation, which is the same -1250 except the result is `False` if the two multisets are exactly equal. -1251 """ -1252 return self._compare(other, icepool.evaluator.IsSupersetEvaluator) +1244 `self > other` evaluates a proper superset relation, which is the same +1245 except the result is `False` if the two multisets are exactly equal. +1246 """ +1247 return self._compare(other, icepool.evaluator.IsSupersetEvaluator)Arguments:
1288 def isdisjoint( -1289 self, -1290 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', -1291 /) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': -1292 """Evaluation: Whether this multiset is disjoint from the other multiset. -1293 -1294 Specifically, this evaluates to `False` if there is any outcome for -1295 which both multisets have positive count, and `True` if there is not. -1296 """ -1297 return self._compare(other, icepool.evaluator.IsDisjointSetEvaluator) +@@ -15329,323 +15374,326 @@1283 def isdisjoint( +1284 self, +1285 other: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]', +1286 /) -> 'icepool.Die[bool] | icepool.MultisetEvaluator[T, bool]': +1287 """Evaluation: Whether this multiset is disjoint from the other multiset. +1288 +1289 Specifically, this evaluates to `False` if there is any outcome for +1290 which both multisets have positive count, and `True` if there is not. +1291 """ +1292 return self._compare(other, icepool.evaluator.IsDisjointSetEvaluator)Arguments:
173 174 return range(outcomes[0], outcomes[-1] + 1) 175 -176 def extra_inputs(self) -> 'tuple[icepool.MultisetExpression, ...]': -177 """An optional sequence of extra inputs whose counts will be prepended to *counts.""" -178 return () -179 -180 def validate_arity(self, arity: int) -> None: -181 """An optional method to verify the total input arity. +176 def bound_inputs(self) -> 'tuple[icepool.MultisetExpression, ...]': +177 """An optional sequence of extra inputs whose counts will be prepended to *counts. +178 +179 (Prepending rather than appending is analogous to `functools.partial`.) +180 """ +181 return () 182 -183 This is called after any implicit conversion to expressions, but does -184 not include any `extra_inputs()`. +183 def validate_arity(self, arity: int) -> None: +184 """An optional method to verify the total input arity. 185 -186 Overriding `next_state` with a fixed number of counts will make this -187 check redundant. +186 This is called after any implicit conversion to expressions, but does +187 not include any `bound_inputs()`. 188 -189 Raises: -190 `ValueError` if the total input arity is not valid. -191 """ -192 -193 @cached_property -194 def _cache( -195 self -196 ) -> 'MutableMapping[tuple[Order, Alignment, tuple[MultisetExpression, ...], Hashable], Mapping[Any, int]]': -197 """Cached results. -198 -199 The key is `(order, extra_outcomes, inputs, state)`. -200 The value is another mapping `final_state: quantity` representing the -201 state distribution produced by `order, extra_outcomes, inputs` when -202 starting at state `state`. -203 """ -204 return {} -205 -206 @overload -207 def evaluate( -208 self, -209 *args: 'Mapping[T, int] | Sequence[T]') -> 'icepool.Die[U_co]': -210 ... -211 -212 @overload -213 def evaluate( -214 self, -215 *args: 'MultisetExpression[T]') -> 'MultisetEvaluator[T, U_co]': -216 ... -217 -218 @overload -219 def evaluate( -220 self, *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' -221 ) -> 'icepool.Die[U_co] | MultisetEvaluator[T, U_co]': -222 ... -223 -224 def evaluate( -225 self, *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' -226 ) -> 'icepool.Die[U_co] | MultisetEvaluator[T, U_co]': -227 """Evaluates input expression(s). -228 -229 You can call the `MultisetEvaluator` object directly for the same effect, -230 e.g. `sum_evaluator(input)` is an alias for `sum_evaluator.evaluate(input)`. +189 Overriding `next_state` with a fixed number of counts will make this +190 check redundant. +191 +192 Raises: +193 `ValueError` if the total input arity is not valid. +194 """ +195 +196 @cached_property +197 def _cache( +198 self +199 ) -> 'MutableMapping[tuple[Order, Alignment, tuple[MultisetExpression, ...], Hashable], Mapping[Any, int]]': +200 """Cached results. +201 +202 The key is `(order, extra_outcomes, inputs, state)`. +203 The value is another mapping `final_state: quantity` representing the +204 state distribution produced by `order, extra_outcomes, inputs` when +205 starting at state `state`. +206 """ +207 return {} +208 +209 @overload +210 def evaluate( +211 self, +212 *args: 'Mapping[T, int] | Sequence[T]') -> 'icepool.Die[U_co]': +213 ... +214 +215 @overload +216 def evaluate( +217 self, +218 *args: 'MultisetExpression[T]') -> 'MultisetEvaluator[T, U_co]': +219 ... +220 +221 @overload +222 def evaluate( +223 self, *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' +224 ) -> 'icepool.Die[U_co] | MultisetEvaluator[T, U_co]': +225 ... +226 +227 def evaluate( +228 self, *args: 'MultisetExpression[T] | Mapping[T, int] | Sequence[T]' +229 ) -> 'icepool.Die[U_co] | MultisetEvaluator[T, U_co]': +230 """Evaluates input expression(s). 231 -232 Most evaluators will expect a fixed number of input multisets. -233 The union of the outcomes of the input(s) must be totally orderable. +232 You can call the `MultisetEvaluator` object directly for the same effect, +233 e.g. `sum_evaluator(input)` is an alias for `sum_evaluator.evaluate(input)`. 234 -235 Args: -236 *args: Each may be one of the following: -237 * A `MultisetExpression`. -238 * A mappable mapping outcomes to the number of those outcomes. -239 * A sequence of outcomes. -240 -241 Returns: -242 A `Die` representing the distribution of the final outcome if no -243 arg contains a free variable. Otherwise, returns a new evaluator. -244 """ -245 from icepool.generator.alignment import Alignment -246 -247 # Convert arguments to expressions. -248 inputs = tuple( -249 icepool.implicit_convert_to_expression(arg) for arg in args) -250 -251 if any(input._free_arity() > 0 for input in inputs): -252 from icepool.evaluator.multiset_function import MultisetFunctionEvaluator -253 return MultisetFunctionEvaluator(*inputs, evaluator=self) -254 -255 self.validate_arity( -256 sum(expression.output_arity() for expression in inputs)) +235 Most evaluators will expect a fixed number of input multisets. +236 The union of the outcomes of the input(s) must be totally orderable. +237 +238 Args: +239 *args: Each may be one of the following: +240 * A `MultisetExpression`. +241 * A mappable mapping outcomes to the number of those outcomes. +242 * A sequence of outcomes. +243 +244 Returns: +245 A `Die` representing the distribution of the final outcome if no +246 arg contains a free variable. Otherwise, returns a new evaluator. +247 """ +248 from icepool.generator.alignment import Alignment +249 +250 # Convert arguments to expressions. +251 inputs = tuple( +252 icepool.implicit_convert_to_expression(arg) for arg in args) +253 +254 if any(input.has_free_variables() for input in inputs): +255 from icepool.evaluator.multiset_function import MultisetFunctionEvaluator +256 return MultisetFunctionEvaluator(*inputs, evaluator=self) 257 -258 inputs = self.extra_inputs() + inputs -259 -260 if not all(expression._is_resolvable() for expression in inputs): -261 return icepool.Die([]) +258 self.validate_arity( +259 sum(expression.output_arity() for expression in inputs)) +260 +261 inputs = self.bound_inputs() + inputs 262 -263 algorithm, order = self._select_algorithm(*inputs) -264 -265 outcomes = icepool.sorted_union(*(expression.outcomes() -266 for expression in inputs)) -267 extra_outcomes = Alignment(self.extra_outcomes(outcomes)) -268 -269 dist: MutableMapping[Any, int] = defaultdict(int) -270 iterators = MultisetEvaluator._initialize_inputs(inputs) -271 for p in itertools.product(*iterators): -272 sub_inputs, sub_weights = zip(*p) -273 prod_weight = math.prod(sub_weights) -274 sub_result = algorithm(order, extra_outcomes, sub_inputs) -275 for sub_state, sub_weight in sub_result.items(): -276 dist[sub_state] += sub_weight * prod_weight -277 -278 final_outcomes = [] -279 final_weights = [] -280 for state, weight in dist.items(): -281 outcome = self.final_outcome(state) -282 if outcome is None: -283 raise TypeError( -284 "None is not a valid final outcome.\n" -285 "This may have been a result of not supplying any input with an outcome." -286 ) -287 if outcome is not icepool.Reroll: -288 final_outcomes.append(outcome) -289 final_weights.append(weight) -290 -291 return icepool.Die(final_outcomes, final_weights) -292 -293 __call__ = evaluate -294 -295 def _select_algorithm( -296 self, *inputs: 'icepool.MultisetExpression[T]' -297 ) -> tuple[ -298 'Callable[[Order, Alignment[T], tuple[icepool.MultisetExpression[T], ...]], Mapping[Any, int]]', -299 Order]: -300 """Selects an algorithm and iteration order. -301 -302 Returns: -303 * The algorithm to use (`_eval_internal*`). -304 * The order in which `next_state()` sees outcomes. -305 1 for ascending and -1 for descending. -306 """ -307 eval_order = self.order() -308 -309 if not inputs: -310 # No inputs. -311 return self._eval_internal, eval_order -312 -313 input_order, input_order_reason = merge_order_preferences( -314 *(input.order_preference() for input in inputs)) +263 if not all(expression._is_resolvable() for expression in inputs): +264 return icepool.Die([]) +265 +266 algorithm, order = self._select_algorithm(*inputs) +267 +268 outcomes = icepool.sorted_union(*(expression.outcomes() +269 for expression in inputs)) +270 extra_outcomes = Alignment(self.extra_outcomes(outcomes)) +271 +272 dist: MutableMapping[Any, int] = defaultdict(int) +273 iterators = MultisetEvaluator._initialize_inputs(inputs) +274 for p in itertools.product(*iterators): +275 sub_inputs, sub_weights = zip(*p) +276 prod_weight = math.prod(sub_weights) +277 sub_result = algorithm(order, extra_outcomes, sub_inputs) +278 for sub_state, sub_weight in sub_result.items(): +279 dist[sub_state] += sub_weight * prod_weight +280 +281 final_outcomes = [] +282 final_weights = [] +283 for state, weight in dist.items(): +284 outcome = self.final_outcome(state) +285 if outcome is None: +286 raise TypeError( +287 "None is not a valid final outcome.\n" +288 "This may have been a result of not supplying any input with an outcome." +289 ) +290 if outcome is not icepool.Reroll: +291 final_outcomes.append(outcome) +292 final_weights.append(weight) +293 +294 return icepool.Die(final_outcomes, final_weights) +295 +296 __call__ = evaluate +297 +298 def _select_algorithm( +299 self, *inputs: 'icepool.MultisetExpression[T]' +300 ) -> tuple[ +301 'Callable[[Order, Alignment[T], tuple[icepool.MultisetExpression[T], ...]], Mapping[Any, int]]', +302 Order]: +303 """Selects an algorithm and iteration order. +304 +305 Returns: +306 * The algorithm to use (`_eval_internal*`). +307 * The order in which `next_state()` sees outcomes. +308 1 for ascending and -1 for descending. +309 """ +310 eval_order = self.order() +311 +312 if not inputs: +313 # No inputs. +314 return self._eval_internal, eval_order 315 -316 if input_order is None: -317 input_order = Order.Any -318 input_order_reason = OrderReason.NoPreference -319 -320 # No mandatory evaluation order, go with preferred algorithm. -321 # Note that this has order *opposite* the pop order. -322 if eval_order == Order.Any: -323 return self._eval_internal, Order(-input_order or Order.Ascending) -324 -325 # Mandatory evaluation order. -326 if input_order == Order.Any: -327 return self._eval_internal, eval_order -328 elif eval_order != input_order: -329 return self._eval_internal, eval_order -330 else: -331 return self._eval_internal_forward, eval_order -332 -333 def _eval_internal( -334 self, order: Order, extra_outcomes: 'Alignment[T]', -335 inputs: 'tuple[icepool.MultisetExpression[T], ...]' -336 ) -> Mapping[Any, int]: -337 """Internal algorithm for iterating in the more-preferred order. -338 -339 All intermediate return values are cached in the instance. -340 -341 Arguments: -342 order: The order in which to send outcomes to `next_state()`. -343 extra_outcomes: As `extra_outcomes()`. Elements will be popped off this -344 during recursion. -345 inputs: One or more `MultisetExpression`s to evaluate. Elements -346 will be popped off this during recursion. -347 -348 Returns: -349 A dict `{ state : weight }` describing the probability distribution -350 over states. -351 """ -352 cache_key = (order, extra_outcomes, inputs, None) -353 if cache_key in self._cache: -354 return self._cache[cache_key] -355 -356 result: MutableMapping[Any, int] = defaultdict(int) -357 -358 if all(not input.outcomes() -359 for input in inputs) and not extra_outcomes.outcomes(): -360 result = {None: 1} -361 else: -362 outcome, prev_extra_outcomes, iterators = MultisetEvaluator._pop_inputs( -363 Order(-order), extra_outcomes, inputs) -364 for p in itertools.product(*iterators): -365 prev_inputs, counts, weights = zip(*p) -366 counts = tuple(itertools.chain.from_iterable(counts)) -367 prod_weight = math.prod(weights) -368 prev = self._eval_internal(order, prev_extra_outcomes, -369 prev_inputs) -370 for prev_state, prev_weight in prev.items(): -371 state = self.next_state(prev_state, outcome, *counts) -372 if state is not icepool.Reroll: -373 result[state] += prev_weight * prod_weight -374 -375 self._cache[cache_key] = result -376 return result +316 input_order, input_order_reason = merge_order_preferences( +317 *(input.order_preference() for input in inputs)) +318 +319 if input_order is None: +320 input_order = Order.Any +321 input_order_reason = OrderReason.NoPreference +322 +323 # No mandatory evaluation order, go with preferred algorithm. +324 # Note that this has order *opposite* the pop order. +325 if eval_order == Order.Any: +326 return self._eval_internal, Order(-input_order or Order.Ascending) +327 +328 # Mandatory evaluation order. +329 if input_order == Order.Any: +330 return self._eval_internal, eval_order +331 elif eval_order != input_order: +332 return self._eval_internal, eval_order +333 else: +334 return self._eval_internal_forward, eval_order +335 +336 def _eval_internal( +337 self, order: Order, extra_outcomes: 'Alignment[T]', +338 inputs: 'tuple[icepool.MultisetExpression[T], ...]' +339 ) -> Mapping[Any, int]: +340 """Internal algorithm for iterating in the more-preferred order. +341 +342 All intermediate return values are cached in the instance. +343 +344 Arguments: +345 order: The order in which to send outcomes to `next_state()`. +346 extra_outcomes: As `extra_outcomes()`. Elements will be popped off this +347 during recursion. +348 inputs: One or more `MultisetExpression`s to evaluate. Elements +349 will be popped off this during recursion. +350 +351 Returns: +352 A dict `{ state : weight }` describing the probability distribution +353 over states. +354 """ +355 cache_key = (order, extra_outcomes, inputs, None) +356 if cache_key in self._cache: +357 return self._cache[cache_key] +358 +359 result: MutableMapping[Any, int] = defaultdict(int) +360 +361 if all(not input.outcomes() +362 for input in inputs) and not extra_outcomes.outcomes(): +363 result = {None: 1} +364 else: +365 outcome, prev_extra_outcomes, iterators = MultisetEvaluator._pop_inputs( +366 Order(-order), extra_outcomes, inputs) +367 for p in itertools.product(*iterators): +368 prev_inputs, counts, weights = zip(*p) +369 counts = tuple(itertools.chain.from_iterable(counts)) +370 prod_weight = math.prod(weights) +371 prev = self._eval_internal(order, prev_extra_outcomes, +372 prev_inputs) +373 for prev_state, prev_weight in prev.items(): +374 state = self.next_state(prev_state, outcome, *counts) +375 if state is not icepool.Reroll: +376 result[state] += prev_weight * prod_weight 377 -378 def _eval_internal_forward( -379 self, -380 order: Order, -381 extra_outcomes: 'Alignment[T]', -382 inputs: 'tuple[icepool.MultisetExpression[T], ...]', -383 state: Hashable = None) -> Mapping[Any, int]: -384 """Internal algorithm for iterating in the less-preferred order. -385 -386 All intermediate return values are cached in the instance. -387 -388 Arguments: -389 order: The order in which to send outcomes to `next_state()`. -390 extra_outcomes: As `extra_outcomes()`. Elements will be popped off this -391 during recursion. -392 inputs: One or more `MultisetExpression`s to evaluate. Elements -393 will be popped off this during recursion. -394 -395 Returns: -396 A dict `{ state : weight }` describing the probability distribution -397 over states. -398 """ -399 cache_key = (order, extra_outcomes, inputs, state) -400 if cache_key in self._cache: -401 return self._cache[cache_key] -402 -403 result: MutableMapping[Any, int] = defaultdict(int) -404 -405 if all(not input.outcomes() -406 for input in inputs) and not extra_outcomes.outcomes(): -407 result = {state: 1} -408 else: -409 outcome, next_extra_outcomes, iterators = MultisetEvaluator._pop_inputs( -410 order, extra_outcomes, inputs) -411 for p in itertools.product(*iterators): -412 next_inputs, counts, weights = zip(*p) -413 counts = tuple(itertools.chain.from_iterable(counts)) -414 prod_weight = math.prod(weights) -415 next_state = self.next_state(state, outcome, *counts) -416 if next_state is not icepool.Reroll: -417 final_dist = self._eval_internal_forward( -418 order, next_extra_outcomes, next_inputs, next_state) -419 for final_state, weight in final_dist.items(): -420 result[final_state] += weight * prod_weight -421 -422 self._cache[cache_key] = result -423 return result +378 self._cache[cache_key] = result +379 return result +380 +381 def _eval_internal_forward( +382 self, +383 order: Order, +384 extra_outcomes: 'Alignment[T]', +385 inputs: 'tuple[icepool.MultisetExpression[T], ...]', +386 state: Hashable = None) -> Mapping[Any, int]: +387 """Internal algorithm for iterating in the less-preferred order. +388 +389 All intermediate return values are cached in the instance. +390 +391 Arguments: +392 order: The order in which to send outcomes to `next_state()`. +393 extra_outcomes: As `extra_outcomes()`. Elements will be popped off this +394 during recursion. +395 inputs: One or more `MultisetExpression`s to evaluate. Elements +396 will be popped off this during recursion. +397 +398 Returns: +399 A dict `{ state : weight }` describing the probability distribution +400 over states. +401 """ +402 cache_key = (order, extra_outcomes, inputs, state) +403 if cache_key in self._cache: +404 return self._cache[cache_key] +405 +406 result: MutableMapping[Any, int] = defaultdict(int) +407 +408 if all(not input.outcomes() +409 for input in inputs) and not extra_outcomes.outcomes(): +410 result = {state: 1} +411 else: +412 outcome, next_extra_outcomes, iterators = MultisetEvaluator._pop_inputs( +413 order, extra_outcomes, inputs) +414 for p in itertools.product(*iterators): +415 next_inputs, counts, weights = zip(*p) +416 counts = tuple(itertools.chain.from_iterable(counts)) +417 prod_weight = math.prod(weights) +418 next_state = self.next_state(state, outcome, *counts) +419 if next_state is not icepool.Reroll: +420 final_dist = self._eval_internal_forward( +421 order, next_extra_outcomes, next_inputs, next_state) +422 for final_state, weight in final_dist.items(): +423 result[final_state] += weight * prod_weight 424 -425 @staticmethod -426 def _initialize_inputs( -427 inputs: 'tuple[icepool.MultisetExpression[T], ...]' -428 ) -> 'tuple[icepool.InitialMultisetGeneration, ...]': -429 return tuple(expression._generate_initial() for expression in inputs) -430 -431 @staticmethod -432 def _pop_inputs( -433 order: Order, extra_outcomes: 'Alignment[T]', -434 inputs: 'tuple[icepool.MultisetExpression[T], ...]' -435 ) -> 'tuple[T, Alignment[T], tuple[icepool.PopMultisetGeneration, ...]]': -436 """Pops a single outcome from the inputs. -437 -438 Args: -439 order: The order in which to pop. Descending order pops from the top -440 and ascending from the bottom. -441 extra_outcomes: Any extra outcomes to use. -442 inputs: The inputs to pop from. -443 -444 Returns: -445 * The popped outcome. -446 * The remaining extra outcomes. -447 * A tuple of iterators over the resulting inputs, counts, and weights. -448 """ -449 extra_outcomes_and_inputs = (extra_outcomes, ) + inputs -450 if order < 0: -451 outcome = max(input.max_outcome() -452 for input in extra_outcomes_and_inputs -453 if input.outcomes()) -454 -455 next_extra_outcomes, _, _ = next( -456 extra_outcomes._generate_max(outcome)) +425 self._cache[cache_key] = result +426 return result +427 +428 @staticmethod +429 def _initialize_inputs( +430 inputs: 'tuple[icepool.MultisetExpression[T], ...]' +431 ) -> 'tuple[icepool.InitialMultisetGeneration, ...]': +432 return tuple(expression._generate_initial() for expression in inputs) +433 +434 @staticmethod +435 def _pop_inputs( +436 order: Order, extra_outcomes: 'Alignment[T]', +437 inputs: 'tuple[icepool.MultisetExpression[T], ...]' +438 ) -> 'tuple[T, Alignment[T], tuple[icepool.PopMultisetGeneration, ...]]': +439 """Pops a single outcome from the inputs. +440 +441 Args: +442 order: The order in which to pop. Descending order pops from the top +443 and ascending from the bottom. +444 extra_outcomes: Any extra outcomes to use. +445 inputs: The inputs to pop from. +446 +447 Returns: +448 * The popped outcome. +449 * The remaining extra outcomes. +450 * A tuple of iterators over the resulting inputs, counts, and weights. +451 """ +452 extra_outcomes_and_inputs = (extra_outcomes, ) + inputs +453 if order < 0: +454 outcome = max(input.max_outcome() +455 for input in extra_outcomes_and_inputs +456 if input.outcomes()) 457 -458 return outcome, next_extra_outcomes, tuple( -459 input._generate_max(outcome) for input in inputs) -460 else: -461 outcome = min(input.min_outcome() -462 for input in extra_outcomes_and_inputs -463 if input.outcomes()) -464 -465 next_extra_outcomes, _, _ = next( -466 extra_outcomes._generate_min(outcome)) +458 next_extra_outcomes, _, _ = next( +459 extra_outcomes._generate_max(outcome)) +460 +461 return outcome, next_extra_outcomes, tuple( +462 input._generate_max(outcome) for input in inputs) +463 else: +464 outcome = min(input.min_outcome() +465 for input in extra_outcomes_and_inputs +466 if input.outcomes()) 467 -468 return outcome, next_extra_outcomes, tuple( -469 input._generate_min(outcome) for input in inputs) +468 next_extra_outcomes, _, _ = next( +469 extra_outcomes._generate_min(outcome)) 470 -471 def sample( -472 self, *inputs: -473 'icepool.MultisetExpression[T] | Mapping[T, int] | Sequence[T]'): -474 """EXPERIMENTAL: Samples one result from the input(s) and evaluates the result.""" -475 # Convert non-`Pool` arguments to `Pool`. -476 converted_inputs = tuple( -477 input if isinstance(input, icepool.MultisetExpression -478 ) else icepool.Pool(input) for input in inputs) -479 -480 result = self.evaluate(*itertools.chain.from_iterable( -481 input.sample() for input in converted_inputs)) +471 return outcome, next_extra_outcomes, tuple( +472 input._generate_min(outcome) for input in inputs) +473 +474 def sample( +475 self, *inputs: +476 'icepool.MultisetExpression[T] | Mapping[T, int] | Sequence[T]'): +477 """EXPERIMENTAL: Samples one result from the input(s) and evaluates the result.""" +478 # Convert non-`Pool` arguments to `Pool`. +479 converted_inputs = tuple( +480 input if isinstance(input, icepool.MultisetExpression +481 ) else icepool.Pool(input) for input in inputs) 482 -483 if not result.is_empty(): -484 return result.outcomes()[0] -485 else: -486 return result -487 -488 def __bool__(self) -> bool: -489 raise TypeError('MultisetEvaluator does not have a truth value.') +483 result = self.evaluate(*itertools.chain.from_iterable( +484 input.sample() for input in converted_inputs)) +485 +486 if not result.is_empty(): +487 return result.outcomes()[0] +488 else: +489 return result 490 -491 def __str__(self) -> str: -492 return type(self).__name__ +491 def __bool__(self) -> bool: +492 raise TypeError('MultisetEvaluator does not have a truth value.') +493 +494 def __str__(self) -> str: +495 return type(self).__name__
176 def extra_inputs(self) -> 'tuple[icepool.MultisetExpression, ...]': -177 """An optional sequence of extra inputs whose counts will be prepended to *counts.""" -178 return () + +176 def bound_inputs(self) -> 'tuple[icepool.MultisetExpression, ...]': +177 """An optional sequence of extra inputs whose counts will be prepended to *counts. +178 +179 (Prepending rather than appending is analogous to `functools.partial`.) +180 """ +181 return ()@@ -16035,25 +16088,25 @@An optional sequence of extra inputs whose counts will be prepended to *counts.
+ +(Prepending rather than appending is analogous to
functools.partial.)Raises: