icepool

20@cache
21def d(sides: int, /) -> 'icepool.Die[int]':
22    """A standard die, uniformly distributed from `1` to `sides` inclusive.
23
24    Don't confuse this with `icepool.Die()`:
25
26    * `icepool.Die([6])`: A `Die` that always rolls the integer 6.
27    * `icepool.d(6)`: A d6.
28
29    You can also import individual standard dice from the `icepool` module, e.g.
30    `from icepool import d6`.
31    """
32    if not isinstance(sides, int):
33        raise TypeError('sides must be an int.')
34    elif sides < 1:
35        raise ValueError('sides must be at least 1.')
36    return icepool.Die(range(1, sides + 1))

39@cache
40def z(sides: int, /) -> 'icepool.Die[int]':
41    """A die uniformly distributed from `0` to `sides - 1` inclusive.
42    
43    Equal to d(sides) - 1.
44    """
45    if not isinstance(sides, int):
46        raise TypeError('sides must be an int.')
47    elif sides < 1:
48        raise ValueError('sides must be at least 1.')
49    return icepool.Die(range(0, sides))

 75def coin(n: int | float | Fraction,
 76         d: int = 1,
 77         /,
 78         *,
 79         max_denominator: int | None = None) -> 'icepool.Die[bool]':
 80    """A `Die` that rolls `True` with probability `n / d`, and `False` otherwise.
 81
 82    If `n <= 0` or `n >= d` the result will have only one outcome.
 83
 84    Args:
 85        n: An int numerator, or a non-integer probability.
 86        d: An int denominator. Should not be provided if the first argument is
 87            not an int.
 88    """
 89    if not isinstance(n, int):
 90        if d != 1:
 91            raise ValueError(
 92                'If a non-int numerator is provided, a denominator must not be provided.'
 93            )
 94        fraction = Fraction(n)
 95        if max_denominator is not None:
 96            fraction = fraction.limit_denominator(max_denominator)
 97        n = fraction.numerator
 98        d = fraction.denominator
 99    data = {}
100    if n < d:
101        data[False] = min(d - n, d)
102    if n > 0:
103        data[True] = min(n, d)
104
105    return icepool.Die(data)

108def stochastic_round(x,
109                     /,
110                     *,
111                     max_denominator: int | None = None) -> 'icepool.Die[int]':
112    """Randomly rounds a value up or down to the nearest integer according to the two distances.
113        
114    Specificially, rounds `x` up with probability `x - floor(x)` and down
115    otherwise, producing a `Die` with up to two outcomes.
116
117    Args:
118        max_denominator: If provided, each rounding will be performed
119            using `fractions.Fraction.limit_denominator(max_denominator)`.
120            Otherwise, the rounding will be performed without
121            `limit_denominator`.
122    """
123    integer_part = math.floor(x)
124    fractional_part = x - integer_part
125    return integer_part + coin(fractional_part,
126                               max_denominator=max_denominator)

129def one_hot(sides: int, /) -> 'icepool.Die[tuple[bool, ...]]':
130    """A `Die` with `Vector` outcomes with one element set to `True` uniformly at random and the rest `False`.
131
132    This is an easy (if somewhat expensive) way of representing how many dice
133    in a pool rolled each number. For example, the outcomes of `10 @ one_hot(6)`
134    are the `(ones, twos, threes, fours, fives, sixes)` rolled in 10d6.
135    """
136    data = []
137    for i in range(sides):
138        outcome = [False] * sides
139        outcome[i] = True
140        data.append(icepool.Vector(outcome))
141    return icepool.Die(data)

70class Outcome(Hashable, Protocol[T_contra]):
71    """Protocol to attempt to verify that outcome types are hashable and sortable.
72
73    Far from foolproof, e.g. it cannot enforce total ordering.
74    """
75
76    def __lt__(self, other: T_contra) -> bool:
77        ...

  45class Die(Population[T_co]):
  46    """Sampling with replacement. Quantities represent weights.
  47
  48    Dice are immutable. Methods do not modify the `Die` in-place;
  49    rather they return a `Die` representing the result.
  50
  51    It's also possible to have "empty" dice with no outcomes at all,
  52    though these have little use other than being sentinel values.
  53    """
  54
  55    _data: Counts[T_co]
  56
  57    @property
  58    def _new_type(self) -> type:
  59        return Die
  60
  61    def __new__(
  62        cls,
  63        outcomes: Sequence | Mapping[Any, int],
  64        times: Sequence[int] | int = 1,
  65        *,
  66        again_count: int | None = None,
  67        again_depth: int | None = None,
  68        again_end: 'Outcome | Die | icepool.RerollType | None' = None
  69    ) -> 'Die[T_co]':
  70        """Constructor for a `Die`.
  71
  72        Don't confuse this with `d()`:
  73
  74        * `Die([6])`: A `Die` that always rolls the `int` 6.
  75        * `d(6)`: A d6.
  76
  77        Also, don't confuse this with `Pool()`:
  78
  79        * `Die([1, 2, 3, 4, 5, 6])`: A d6.
  80        * `Pool([1, 2, 3, 4, 5, 6])`: A `Pool` of six dice that always rolls one
  81            of each number.
  82
  83        Here are some different ways of constructing a d6:
  84
  85        * Just import it: `from icepool import d6`
  86        * Use the `d()` function: `icepool.d(6)`
  87        * Use a d6 that you already have: `Die(d6)` or `Die([d6])`
  88        * Mix a d3 and a d3+3: `Die([d3, d3+3])`
  89        * Use a dict: `Die({1:1, 2:1, 3:1, 4:1, 5:1, 6:1})`
  90        * Give the faces as a sequence: `Die([1, 2, 3, 4, 5, 6])`
  91
  92        All quantities must be non-negative. Outcomes with zero quantity will be
  93        omitted.
  94
  95        Several methods and functions foward **kwargs to this constructor.
  96        However, these only affect the construction of the returned or yielded
  97        dice. Any other implicit conversions of arguments or operands to dice
  98        will be done with the default keyword arguments.
  99
 100        EXPERIMENTAL: Use `icepool.Again` to roll the dice again, usually with
 101        some modification. See the `Again` documentation for details.
 102
 103        Denominator: For a flat set of outcomes, the denominator is just the
 104        sum of the corresponding quantities. If the outcomes themselves have
 105        secondary denominators, then the overall denominator will be minimized
 106        while preserving the relative weighting of the primary outcomes.
 107
 108        Args:
 109            outcomes: The faces of the `Die`. This can be one of the following:
 110                * A `Sequence` of outcomes. Duplicates will contribute
 111                    quantity for each appearance.
 112                * A `Mapping` from outcomes to quantities.
 113
 114                Individual outcomes can each be one of the following:
 115
 116                * An outcome, which must be hashable and totally orderable.
 117                    * For convenience, `tuple`s containing `Population`s will be
 118                        `tupleize`d into a `Population` of `tuple`s.
 119                        This does not apply to subclasses of `tuple`s such as `namedtuple`
 120                        or other classes such as `Vector`.
 121                * A `Die`, which will be flattened into the result.
 122                    The quantity assigned to a `Die` is shared among its
 123                    outcomes. The total denominator will be scaled up if
 124                    necessary.
 125                * `icepool.Reroll`, which will drop itself from consideration.
 126                * EXPERIMENTAL: `icepool.Again`. See the documentation for
 127                    `Again` for details.
 128            times: Multiplies the quantity of each element of `outcomes`.
 129                `times` can either be a sequence of the same length as
 130                `outcomes` or a single `int` to apply to all elements of
 131                `outcomes`.
 132            again_count, again_depth, again_end: These affect how `Again`
 133                expressions are handled. See the `Again` documentation for
 134                details.
 135        Raises:
 136            ValueError: `None` is not a valid outcome for a `Die`.
 137        """
 138        outcomes, times = icepool.creation_args.itemize(outcomes, times)
 139
 140        # Check for Again.
 141        if icepool.population.again.contains_again(outcomes):
 142            if again_count is not None:
 143                if again_depth is not None:
 144                    raise ValueError(
 145                        'At most one of again_count and again_depth may be used.'
 146                    )
 147                if again_end is not None:
 148                    raise ValueError(
 149                        'again_end cannot be used with again_count.')
 150                return icepool.population.again.evaluate_agains_using_count(
 151                    outcomes, times, again_count)
 152            else:
 153                if again_depth is None:
 154                    again_depth = 1
 155                return icepool.population.again.evaluate_agains_using_depth(
 156                    outcomes, times, again_depth, again_end)
 157
 158        # Agains have been replaced by this point.
 159        outcomes = cast(Sequence[T_co | Die[T_co] | icepool.RerollType],
 160                        outcomes)
 161
 162        if len(outcomes) == 1 and times[0] == 1 and isinstance(
 163                outcomes[0], Die):
 164            return outcomes[0]
 165
 166        counts: Counts[T_co] = icepool.creation_args.expand_args_for_die(
 167            outcomes, times)
 168
 169        return Die._new_raw(counts)
 170
 171    @classmethod
 172    def _new_raw(cls, data: Counts[T_co]) -> 'Die[T_co]':
 173        """Creates a new `Die` using already-processed arguments.
 174
 175        Args:
 176            data: At this point, this is a Counts.
 177        """
 178        self = super(Population, cls).__new__(cls)
 179        self._data = data
 180        return self
 181
 182    # Defined separately from the superclass to help typing.
 183    def unary_operator(self: 'icepool.Die[T_co]', op: Callable[..., U], *args,
 184                       **kwargs) -> 'icepool.Die[U]':
 185        """Performs the unary operation on the outcomes.
 186
 187        This is used for the standard unary operators
 188        `-, +, abs, ~, round, trunc, floor, ceil`
 189        as well as the additional methods
 190        `zero, bool`.
 191
 192        This is NOT used for the `[]` operator; when used directly, this is
 193        interpreted as a `Mapping` operation and returns the count corresponding
 194        to a given outcome. See `marginals()` for applying the `[]` operator to
 195        outcomes.
 196
 197        Returns:
 198            A `Die` representing the result.
 199
 200        Raises:
 201            ValueError: If tuples are of mismatched length.
 202        """
 203        return self._unary_operator(op, *args, **kwargs)
 204
 205    def binary_operator(self, other: 'Die', op: Callable[..., U], *args,
 206                        **kwargs) -> 'Die[U]':
 207        """Performs the operation on pairs of outcomes.
 208
 209        By the time this is called, the other operand has already been
 210        converted to a `Die`.
 211
 212        If one side of a binary operator is a tuple and the other is not, the
 213        binary operator is applied to each element of the tuple with the
 214        non-tuple side. For example, the following are equivalent:
 215
 216        ```python
 217        cartesian_product(d6, d8) * 2
 218        cartesian_product(d6 * 2, d8 * 2)
 219        ```
 220
 221        This is used for the standard binary operators
 222        `+, -, *, /, //, %, **, <<, >>, &, |, ^`
 223        and the standard binary comparators
 224        `<, <=, >=, >, ==, !=, cmp`.
 225
 226        `==` and `!=` additionally set the truth value of the `Die` according to
 227        whether the dice themselves are the same or not.
 228
 229        The `@` operator does NOT use this method directly.
 230        It rolls the left `Die`, which must have integer outcomes,
 231        then rolls the right `Die` that many times and sums the outcomes.
 232
 233        Returns:
 234            A `Die` representing the result.
 235
 236        Raises:
 237            ValueError: If tuples are of mismatched length within one of the
 238                dice or between the dice.
 239        """
 240        data: MutableMapping[Any, int] = defaultdict(int)
 241        for (outcome_self,
 242             quantity_self), (outcome_other,
 243                              quantity_other) in itertools.product(
 244                                  self.items(), other.items()):
 245            new_outcome = op(outcome_self, outcome_other, *args, **kwargs)
 246            data[new_outcome] += quantity_self * quantity_other
 247        return self._new_type(data)
 248
 249    # Basic access.
 250
 251    def keys(self) -> CountsKeysView[T_co]:
 252        return self._data.keys()
 253
 254    def values(self) -> CountsValuesView:
 255        return self._data.values()
 256
 257    def items(self) -> CountsItemsView[T_co]:
 258        return self._data.items()
 259
 260    def __getitem__(self, outcome, /) -> int:
 261        return self._data[outcome]
 262
 263    def __iter__(self) -> Iterator[T_co]:
 264        return iter(self.keys())
 265
 266    def __len__(self) -> int:
 267        """The number of outcomes. """
 268        return len(self._data)
 269
 270    def __contains__(self, outcome) -> bool:
 271        return outcome in self._data
 272
 273    # Quantity management.
 274
 275    def simplify(self) -> 'Die[T_co]':
 276        """Divides all quantities by their greatest common denominator. """
 277        return icepool.Die(self._data.simplify())
 278
 279    # Rerolls and other outcome management.
 280
 281    def _select_outcomes(self, which: Callable[..., bool] | Collection[T_co],
 282                         star: bool | None) -> Set[T_co]:
 283        """Returns a set of outcomes of self that fit the given condition."""
 284        if callable(which):
 285            if star is None:
 286                star = guess_star(which)
 287            if star:
 288                # Need TypeVarTuple to check this.
 289                return {
 290                    outcome
 291                    for outcome in self.outcomes()
 292                    if which(*outcome)  # type: ignore
 293                }
 294            else:
 295                return {
 296                    outcome
 297                    for outcome in self.outcomes() if which(outcome)
 298                }
 299        else:
 300            # Collection.
 301            return set(outcome for outcome in self.outcomes()
 302                       if outcome in which)
 303
 304    def reroll(self,
 305               which: Callable[..., bool] | Collection[T_co] | None = None,
 306               /,
 307               *,
 308               star: bool | None = None,
 309               depth: int | Literal['inf']) -> 'Die[T_co]':
 310        """Rerolls the given outcomes.
 311
 312        Args:
 313            which: Selects which outcomes to reroll. Options:
 314                * A collection of outcomes to reroll.
 315                * A callable that takes an outcome and returns `True` if it
 316                    should be rerolled.
 317                * If not provided, the min outcome will be rerolled.
 318            star: Whether outcomes should be unpacked into separate arguments
 319                before sending them to a callable `which`.
 320                If not provided, this will be guessed based on the function
 321                signature.
 322            depth: The maximum number of times to reroll.
 323                If `None`, rerolls an unlimited number of times.
 324
 325        Returns:
 326            A `Die` representing the reroll.
 327            If the reroll would never terminate, the result has no outcomes.
 328        """
 329
 330        if which is None:
 331            outcome_set = {self.min_outcome()}
 332        else:
 333            outcome_set = self._select_outcomes(which, star)
 334
 335        if depth == 'inf' or depth is None:
 336            if depth is None:
 337                warnings.warn(
 338                    "depth=None is deprecated; use depth='inf' instead.",
 339                    category=DeprecationWarning,
 340                    stacklevel=1)
 341            data = {
 342                outcome: quantity
 343                for outcome, quantity in self.items()
 344                if outcome not in outcome_set
 345            }
 346        elif depth < 0:
 347            raise ValueError('reroll depth cannot be negative.')
 348        else:
 349            total_reroll_quantity = sum(quantity
 350                                        for outcome, quantity in self.items()
 351                                        if outcome in outcome_set)
 352            total_stop_quantity = self.denominator() - total_reroll_quantity
 353            rerollable_factor = total_reroll_quantity**depth
 354            stop_factor = (self.denominator()**(depth + 1) - rerollable_factor
 355                           * total_reroll_quantity) // total_stop_quantity
 356            data = {
 357                outcome: (rerollable_factor *
 358                          quantity if outcome in outcome_set else stop_factor *
 359                          quantity)
 360                for outcome, quantity in self.items()
 361            }
 362        return icepool.Die(data)
 363
 364    def filter(self,
 365               which: Callable[..., bool] | Collection[T_co],
 366               /,
 367               *,
 368               star: bool | None = None,
 369               depth: int | Literal['inf']) -> 'Die[T_co]':
 370        """Rerolls until getting one of the given outcomes.
 371
 372        Essentially the complement of `reroll()`.
 373
 374        Args:
 375            which: Selects which outcomes to reroll until. Options:
 376                * A callable that takes an outcome and returns `True` if it
 377                    should be accepted.
 378                * A collection of outcomes to reroll until.
 379            star: Whether outcomes should be unpacked into separate arguments
 380                before sending them to a callable `which`.
 381                If not provided, this will be guessed based on the function
 382                signature.
 383            depth: The maximum number of times to reroll.
 384                If `None`, rerolls an unlimited number of times.
 385
 386        Returns:
 387            A `Die` representing the reroll.
 388            If the reroll would never terminate, the result has no outcomes.
 389        """
 390
 391        if callable(which):
 392            if star is None:
 393                star = guess_star(which)
 394            if star:
 395
 396                not_outcomes = {
 397                    outcome
 398                    for outcome in self.outcomes()
 399                    if not which(*outcome)  # type: ignore
 400                }
 401            else:
 402                not_outcomes = {
 403                    outcome
 404                    for outcome in self.outcomes() if not which(outcome)
 405                }
 406        else:
 407            not_outcomes = {
 408                not_outcome
 409                for not_outcome in self.outcomes() if not_outcome not in which
 410            }
 411        return self.reroll(not_outcomes, depth=depth)
 412
 413    def split(self,
 414              which: Callable[..., bool] | Collection[T_co] | None = None,
 415              /,
 416              *,
 417              star: bool | None = None):
 418        """Splits this die into one containing selected items and another containing the rest.
 419
 420        The total denominator is preserved.
 421        
 422        Equivalent to `self.filter(), self.reroll()`.
 423
 424        Args:
 425            which: Selects which outcomes to reroll until. Options:
 426                * A callable that takes an outcome and returns `True` if it
 427                    should be accepted.
 428                * A collection of outcomes to reroll until.
 429            star: Whether outcomes should be unpacked into separate arguments
 430                before sending them to a callable `which`.
 431                If not provided, this will be guessed based on the function
 432                signature.
 433        """
 434        if which is None:
 435            outcome_set = {self.min_outcome()}
 436        else:
 437            outcome_set = self._select_outcomes(which, star)
 438
 439        selected = {}
 440        not_selected = {}
 441        for outcome, count in self.items():
 442            if outcome in outcome_set:
 443                selected[outcome] = count
 444            else:
 445                not_selected[outcome] = count
 446
 447        return Die(selected), Die(not_selected)
 448
 449    def truncate(self, min_outcome=None, max_outcome=None) -> 'Die[T_co]':
 450        """Truncates the outcomes of this `Die` to the given range.
 451
 452        The endpoints are included in the result if applicable.
 453        If one of the arguments is not provided, that side will not be truncated.
 454
 455        This effectively rerolls outcomes outside the given range.
 456        If instead you want to replace those outcomes with the nearest endpoint,
 457        use `clip()`.
 458
 459        Not to be confused with `trunc(die)`, which performs integer truncation
 460        on each outcome.
 461        """
 462        if min_outcome is not None:
 463            start = bisect.bisect_left(self.outcomes(), min_outcome)
 464        else:
 465            start = None
 466        if max_outcome is not None:
 467            stop = bisect.bisect_right(self.outcomes(), max_outcome)
 468        else:
 469            stop = None
 470        data = {k: v for k, v in self.items()[start:stop]}
 471        return icepool.Die(data)
 472
 473    def clip(self, min_outcome=None, max_outcome=None) -> 'Die[T_co]':
 474        """Clips the outcomes of this `Die` to the given values.
 475
 476        The endpoints are included in the result if applicable.
 477        If one of the arguments is not provided, that side will not be clipped.
 478
 479        This is not the same as rerolling outcomes beyond this range;
 480        the outcome is simply adjusted to fit within the range.
 481        This will typically cause some quantity to bunch up at the endpoint(s).
 482        If you want to reroll outcomes beyond this range, use `truncate()`.
 483        """
 484        data: MutableMapping[Any, int] = defaultdict(int)
 485        for outcome, quantity in self.items():
 486            if min_outcome is not None and outcome <= min_outcome:
 487                data[min_outcome] += quantity
 488            elif max_outcome is not None and outcome >= max_outcome:
 489                data[max_outcome] += quantity
 490            else:
 491                data[outcome] += quantity
 492        return icepool.Die(data)
 493
 494    @cached_property
 495    def _popped_min(self) -> tuple['Die[T_co]', int]:
 496        die = Die._new_raw(self._data.remove_min())
 497        return die, self.quantities()[0]
 498
 499    def _pop_min(self) -> tuple['Die[T_co]', int]:
 500        """A `Die` with the min outcome removed, and the quantity of the removed outcome.
 501
 502        Raises:
 503            IndexError: If this `Die` has no outcome to pop.
 504        """
 505        return self._popped_min
 506
 507    @cached_property
 508    def _popped_max(self) -> tuple['Die[T_co]', int]:
 509        die = Die._new_raw(self._data.remove_max())
 510        return die, self.quantities()[-1]
 511
 512    def _pop_max(self) -> tuple['Die[T_co]', int]:
 513        """A `Die` with the max outcome removed, and the quantity of the removed outcome.
 514
 515        Raises:
 516            IndexError: If this `Die` has no outcome to pop.
 517        """
 518        return self._popped_max
 519
 520    # Processes.
 521
 522    def map(
 523        self,
 524        repl:
 525        'Callable[..., U | Die[U] | icepool.RerollType | icepool.AgainExpression] | Mapping[T_co, U | Die[U] | icepool.RerollType | icepool.AgainExpression]',
 526        /,
 527        *extra_args,
 528        star: bool | None = None,
 529        repeat: int | Literal['inf'] = 1,
 530        time_limit: int | Literal['inf'] | None = None,
 531        again_count: int | None = None,
 532        again_depth: int | None = None,
 533        again_end: 'U | Die[U] | icepool.RerollType | None' = None
 534    ) -> 'Die[U]':
 535        """Maps outcomes of the `Die` to other outcomes.
 536
 537        This is also useful for representing processes.
 538
 539        As `icepool.map(repl, self, ...)`.
 540        """
 541        return icepool.map(repl,
 542                           self,
 543                           *extra_args,
 544                           star=star,
 545                           repeat=repeat,
 546                           time_limit=time_limit,
 547                           again_count=again_count,
 548                           again_depth=again_depth,
 549                           again_end=again_end)
 550
 551    def map_and_time(
 552            self,
 553            repl:
 554        'Callable[..., T_co | Die[T_co] | icepool.RerollType] | Mapping[T_co, T_co | Die[T_co] | icepool.RerollType]',
 555            /,
 556            *extra_args,
 557            star: bool | None = None,
 558            time_limit: int) -> 'Die[tuple[T_co, int]]':
 559        """Repeatedly map outcomes of the state to other outcomes, while also
 560        counting timesteps.
 561
 562        This is useful for representing processes.
 563
 564        As `map_and_time(repl, self, ...)`.
 565        """
 566        return icepool.map_and_time(repl,
 567                                    self,
 568                                    *extra_args,
 569                                    star=star,
 570                                    time_limit=time_limit)
 571
 572    def time_to_sum(self: 'Die[int]',
 573                    target: int,
 574                    /,
 575                    max_time: int,
 576                    dnf: 'int|icepool.RerollType|None' = None) -> 'Die[int]':
 577        """The number of rolls until the cumulative sum is greater or equal to the target.
 578        
 579        Args:
 580            target: The number to stop at once reached.
 581            max_time: The maximum number of rolls to run.
 582                If the sum is not reached, the outcome is determined by `dnf`.
 583            dnf: What time to assign in cases where the target was not reached
 584                in `max_time`. If not provided, this is set to `max_time`.
 585                `dnf=icepool.Reroll` will remove this case from the result,
 586                effectively rerolling it.
 587        """
 588        if target <= 0:
 589            return Die([0])
 590
 591        if dnf is None:
 592            dnf = max_time
 593
 594        def step(total, roll):
 595            return min(total + roll, target)
 596
 597        result: 'Die[tuple[int, int]]' = Die([0]).map_and_time(
 598            step, self, time_limit=max_time)
 599
 600        def get_time(total, time):
 601            if total < target:
 602                return dnf
 603            else:
 604                return time
 605
 606        return result.map(get_time)
 607
 608    @cached_property
 609    def _mean_time_to_sum_cache(self) -> list[Fraction]:
 610        return [Fraction(0)]
 611
 612    def mean_time_to_sum(self: 'Die[int]', target: int, /) -> Fraction:
 613        """The mean number of rolls until the cumulative sum is greater or equal to the target.
 614
 615        Args:
 616            target: The target sum.
 617
 618        Raises:
 619            ValueError: If `self` has negative outcomes.
 620            ZeroDivisionError: If `self.mean() == 0`.
 621        """
 622        target = max(target, 0)
 623
 624        if target < len(self._mean_time_to_sum_cache):
 625            return self._mean_time_to_sum_cache[target]
 626
 627        if self.min_outcome() < 0:
 628            raise ValueError(
 629                'mean_time_to_sum does not handle negative outcomes.')
 630        time_per_effect = Fraction(self.denominator(),
 631                                   self.denominator() - self.quantity(0))
 632
 633        for i in range(len(self._mean_time_to_sum_cache), target + 1):
 634            result = time_per_effect + self.reroll([
 635                0
 636            ], depth='inf').map(lambda x: self.mean_time_to_sum(i - x)).mean()
 637            self._mean_time_to_sum_cache.append(result)
 638
 639        return result
 640
 641    def explode(self,
 642                which: Collection[T_co] | Callable[..., bool] | None = None,
 643                /,
 644                *,
 645                star: bool | None = None,
 646                depth: int = 9,
 647                end=None) -> 'Die[T_co]':
 648        """Causes outcomes to be rolled again and added to the total.
 649
 650        Args:
 651            which: Which outcomes to explode. Options:
 652                * A single outcome to explode.
 653                * An collection of outcomes to explode.
 654                * A callable that takes an outcome and returns `True` if it
 655                    should be exploded.
 656                * If not supplied, the max outcome will explode.
 657            star: Whether outcomes should be unpacked into separate arguments
 658                before sending them to a callable `which`.
 659                If not provided, this will be guessed based on the function
 660                signature.
 661            depth: The maximum number of additional dice to roll, not counting
 662                the initial roll.
 663                If not supplied, a default value will be used.
 664            end: Once `depth` is reached, further explosions will be treated
 665                as this value. By default, a zero value will be used.
 666                `icepool.Reroll` will make one extra final roll, rerolling until
 667                a non-exploding outcome is reached.
 668        """
 669
 670        if which is None:
 671            outcome_set = {self.max_outcome()}
 672        else:
 673            outcome_set = self._select_outcomes(which, star)
 674
 675        if depth < 0:
 676            raise ValueError('depth cannot be negative.')
 677        elif depth == 0:
 678            return self
 679
 680        def map_final(outcome):
 681            if outcome in outcome_set:
 682                return outcome + icepool.Again
 683            else:
 684                return outcome
 685
 686        return self.map(map_final, again_depth=depth, again_end=end)
 687
 688    def if_else(
 689        self,
 690        outcome_if_true: U | 'Die[U]',
 691        outcome_if_false: U | 'Die[U]',
 692        *,
 693        again_count: int | None = None,
 694        again_depth: int | None = None,
 695        again_end: 'U | Die[U] | icepool.RerollType | None' = None
 696    ) -> 'Die[U]':
 697        """Ternary conditional operator.
 698
 699        This replaces truthy outcomes with the first argument and falsy outcomes
 700        with the second argument.
 701
 702        Args:
 703            again_count, again_depth, again_end: Forwarded to the final die constructor.
 704        """
 705        return self.map(lambda x: bool(x)).map(
 706            {
 707                True: outcome_if_true,
 708                False: outcome_if_false
 709            },
 710            again_count=again_count,
 711            again_depth=again_depth,
 712            again_end=again_end)
 713
 714    def is_in(self, target: Container[T_co], /) -> 'Die[bool]':
 715        """A die that returns True iff the roll of the die is contained in the target."""
 716        return self.map(lambda x: x in target)
 717
 718    def count(self, rolls: int, target: Container[T_co], /) -> 'Die[int]':
 719        """Roll this dice a number of times and count how many are in the target."""
 720        return rolls @ self.is_in(target)
 721
 722    # Pools and sums.
 723
 724    @cached_property
 725    def _sum_cache(self) -> MutableMapping[int, 'Die']:
 726        return {}
 727
 728    def _sum_all(self, rolls: int, /) -> 'Die':
 729        """Roll this `Die` `rolls` times and sum the results.
 730
 731        The sum is computed one at a time, with each additional item on the 
 732        right, similar to `functools.reduce()`.
 733
 734        If `rolls` is negative, roll the `Die` `abs(rolls)` times and negate
 735        the result.
 736
 737        If you instead want to replace tuple (or other sequence) outcomes with
 738        their sum, use `die.map(sum)`.
 739        """
 740        if rolls in self._sum_cache:
 741            return self._sum_cache[rolls]
 742
 743        if rolls < 0:
 744            result = -self._sum_all(-rolls)
 745        elif rolls == 0:
 746            result = self.zero().simplify()
 747        elif rolls == 1:
 748            result = self
 749        else:
 750            # In addition to working similar to reduce(), this seems to perform
 751            # better than binary split.
 752            result = self._sum_all(rolls - 1) + self
 753
 754        self._sum_cache[rolls] = result
 755        return result
 756
 757    def __matmul__(self: 'Die[int]', other) -> 'Die':
 758        """Roll the left `Die`, then roll the right `Die` that many times and sum the outcomes.
 759        
 760        The sum is computed one at a time, with each additional item on the 
 761        right, similar to `functools.reduce()`.
 762        """
 763        if isinstance(other, icepool.AgainExpression):
 764            return NotImplemented
 765        other = implicit_convert_to_die(other)
 766
 767        data: MutableMapping[int, Any] = defaultdict(int)
 768
 769        max_abs_die_count = max(abs(self.min_outcome()),
 770                                abs(self.max_outcome()))
 771        for die_count, die_count_quantity in self.items():
 772            factor = other.denominator()**(max_abs_die_count - abs(die_count))
 773            subresult = other._sum_all(die_count)
 774            for outcome, subresult_quantity in subresult.items():
 775                data[
 776                    outcome] += subresult_quantity * die_count_quantity * factor
 777
 778        return icepool.Die(data)
 779
 780    def __rmatmul__(self, other: 'int | Die[int]') -> 'Die':
 781        """Roll the left `Die`, then roll the right `Die` that many times and sum the outcomes.
 782        
 783        The sum is computed one at a time, with each additional item on the 
 784        right, similar to `functools.reduce()`.
 785        """
 786        if isinstance(other, icepool.AgainExpression):
 787            return NotImplemented
 788        other = implicit_convert_to_die(other)
 789        return other.__matmul__(self)
 790
 791    def sequence(self, rolls: int) -> 'icepool.Die[tuple[T_co, ...]]':
 792        """Possible sequences produced by rolling this die a number of times.
 793        
 794        This is extremely expensive computationally. If possible, use `reduce()`
 795        instead; if you don't care about order, `Die.pool()` is better.
 796        """
 797        return icepool.cartesian_product(*(self for _ in range(rolls)),
 798                                         outcome_type=tuple)  # type: ignore
 799
 800    def pool(self, rolls: int | Sequence[int] = 1, /) -> 'icepool.Pool[T_co]':
 801        """Creates a `Pool` from this `Die`.
 802
 803        You might subscript the pool immediately afterwards, e.g.
 804        `d6.pool(5)[-1, ..., 1]` takes the difference between the highest and
 805        lowest of 5d6.
 806
 807        Args:
 808            rolls: The number of copies of this `Die` to put in the pool.
 809                Or, a sequence of one `int` per die acting as
 810                `keep_tuple`. Note that `...` cannot be used in the
 811                argument to this method, as the argument determines the size of
 812                the pool.
 813        """
 814        if isinstance(rolls, int):
 815            return icepool.Pool({self: rolls})
 816        else:
 817            pool_size = len(rolls)
 818            # Haven't dealt with narrowing return type.
 819            return icepool.Pool({self: pool_size})[rolls]  # type: ignore
 820
 821    @overload
 822    def keep(self, rolls: Sequence[int], /) -> 'Die':
 823        """Selects elements after drawing and sorting and sums them.
 824
 825        Args:
 826            rolls: A sequence of `int` specifying how many times to count each
 827                element in ascending order.
 828        """
 829
 830    @overload
 831    def keep(self, rolls: int,
 832             index: slice | Sequence[int | EllipsisType] | int, /):
 833        """Selects elements after drawing and sorting and sums them.
 834
 835        Args:
 836            rolls: The number of dice to roll.
 837            index: One of the following:
 838            * An `int`. This will count only the roll at the specified index.
 839                In this case, the result is a `Die` rather than a generator.
 840            * A `slice`. The selected dice are counted once each.
 841            * A sequence of one `int` for each `Die`.
 842                Each roll is counted that many times, which could be multiple or
 843                negative times.
 844
 845                Up to one `...` (`Ellipsis`) may be used.
 846                `...` will be replaced with a number of zero
 847                counts depending on the `rolls`.
 848                This number may be "negative" if more `int`s are provided than
 849                `rolls`. Specifically:
 850
 851                * If `index` is shorter than `rolls`, `...`
 852                    acts as enough zero counts to make up the difference.
 853                    E.g. `(1, ..., 1)` on five dice would act as
 854                    `(1, 0, 0, 0, 1)`.
 855                * If `index` has length equal to `rolls`, `...` has no effect.
 856                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
 857                * If `index` is longer than `rolls` and `...` is on one side,
 858                    elements will be dropped from `index` on the side with `...`.
 859                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
 860                * If `index` is longer than `rolls` and `...`
 861                    is in the middle, the counts will be as the sum of two
 862                    one-sided `...`.
 863                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
 864                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
 865        """
 866
 867    def keep(self,
 868             rolls: int | Sequence[int],
 869             index: slice | Sequence[int | EllipsisType] | int | None = None,
 870             /) -> 'Die':
 871        """Selects elements after drawing and sorting and sums them.
 872
 873        Args:
 874            rolls: The number of dice to roll.
 875            index: One of the following:
 876            * An `int`. This will count only the roll at the specified index.
 877            In this case, the result is a `Die` rather than a generator.
 878            * A `slice`. The selected dice are counted once each.
 879            * A sequence of `int`s with length equal to `rolls`.
 880                Each roll is counted that many times, which could be multiple or
 881                negative times.
 882
 883                Up to one `...` (`Ellipsis`) may be used. If no `...` is used,
 884                the `rolls` argument may be omitted.
 885
 886                `...` will be replaced with a number of zero counts in order
 887                to make up any missing elements compared to `rolls`.
 888                This number may be "negative" if more `int`s are provided than
 889                `rolls`. Specifically:
 890
 891                * If `index` is shorter than `rolls`, `...`
 892                    acts as enough zero counts to make up the difference.
 893                    E.g. `(1, ..., 1)` on five dice would act as
 894                    `(1, 0, 0, 0, 1)`.
 895                * If `index` has length equal to `rolls`, `...` has no effect.
 896                    E.g. `(1, ..., 1)` on two dice would act as `(1, 1)`.
 897                * If `index` is longer than `rolls` and `...` is on one side,
 898                    elements will be dropped from `index` on the side with `...`.
 899                    E.g. `(..., 1, 2, 3)` on two dice would act as `(2, 3)`.
 900                * If `index` is longer than `rolls` and `...`
 901                    is in the middle, the counts will be as the sum of two
 902                    one-sided `...`.
 903                    E.g. `(-1, ..., 1)` acts like `(-1, ...)` plus `(..., 1)`.
 904                    If `rolls` was 1 this would have the -1 and 1 cancel each other out.
 905        """
 906        if isinstance(rolls, int):
 907            if index is None:
 908                raise ValueError(
 909                    'If the number of rolls is an integer, an index argument must be provided.'
 910                )
 911            if isinstance(index, int):
 912                return self.pool(rolls).keep(index)
 913            else:
 914                return self.pool(rolls).keep(index).sum()  # type: ignore
 915        else:
 916            if index is not None:
 917                raise ValueError('Only one index sequence can be given.')
 918            return self.pool(len(rolls)).keep(rolls).sum()  # type: ignore
 919
 920    def lowest(self,
 921               rolls: int,
 922               /,
 923               keep: int | None = None,
 924               drop: int | None = None) -> 'Die':
 925        """Roll several of this `Die` and return the lowest result, or the sum of some of the lowest.
 926
 927        The outcomes should support addition and multiplication if `keep != 1`.
 928
 929        Args:
 930            rolls: The number of dice to roll. All dice will have the same
 931                outcomes as `self`.
 932            keep, drop: These arguments work together:
 933                * If neither are provided, the single lowest die will be taken.
 934                * If only `keep` is provided, the `keep` lowest dice will be summed.
 935                * If only `drop` is provided, the `drop` lowest dice will be dropped
 936                    and the rest will be summed.
 937                * If both are provided, `drop` lowest dice will be dropped, then
 938                    the next `keep` lowest dice will be summed.
 939
 940        Returns:
 941            A `Die` representing the probability distribution of the sum.
 942        """
 943        index = lowest_slice(keep, drop)
 944        canonical = canonical_slice(index, rolls)
 945        if canonical.start == 0 and canonical.stop == 1:
 946            return self._lowest_single(rolls)
 947        # Expression evaluators are difficult to type.
 948        return self.pool(rolls)[index].sum()  # type: ignore
 949
 950    def _lowest_single(self, rolls: int, /) -> 'Die':
 951        """Roll this die several times and keep the lowest."""
 952        if rolls == 0:
 953            return self.zero().simplify()
 954        return icepool.from_cumulative(
 955            self.outcomes(), [x**rolls for x in self.quantities('>=')],
 956            reverse=True)
 957
 958    def highest(self,
 959                rolls: int,
 960                /,
 961                keep: int | None = None,
 962                drop: int | None = None) -> 'Die[T_co]':
 963        """Roll several of this `Die` and return the highest result, or the sum of some of the highest.
 964
 965        The outcomes should support addition and multiplication if `keep != 1`.
 966
 967        Args:
 968            rolls: The number of dice to roll.
 969            keep, drop: These arguments work together:
 970                * If neither are provided, the single highest die will be taken.
 971                * If only `keep` is provided, the `keep` highest dice will be summed.
 972                * If only `drop` is provided, the `drop` highest dice will be dropped
 973                    and the rest will be summed.
 974                * If both are provided, `drop` highest dice will be dropped, then
 975                    the next `keep` highest dice will be summed.
 976
 977        Returns:
 978            A `Die` representing the probability distribution of the sum.
 979        """
 980        index = highest_slice(keep, drop)
 981        canonical = canonical_slice(index, rolls)
 982        if canonical.start == rolls - 1 and canonical.stop == rolls:
 983            return self._highest_single(rolls)
 984        # Expression evaluators are difficult to type.
 985        return self.pool(rolls)[index].sum()  # type: ignore
 986
 987    def _highest_single(self, rolls: int, /) -> 'Die[T_co]':
 988        """Roll this die several times and keep the highest."""
 989        if rolls == 0:
 990            return self.zero().simplify()
 991        return icepool.from_cumulative(
 992            self.outcomes(), [x**rolls for x in self.quantities('<=')])
 993
 994    def middle(
 995            self,
 996            rolls: int,
 997            /,
 998            keep: int = 1,
 999            *,
1000            tie: Literal['error', 'high', 'low'] = 'error') -> 'icepool.Die':
1001        """Roll several of this `Die` and sum the sorted results in the middle.
1002
1003        The outcomes should support addition and multiplication if `keep != 1`.
1004
1005        Args:
1006            rolls: The number of dice to roll.
1007            keep: The number of outcomes to sum. If this is greater than the
1008                current keep_size, all are kept.
1009            tie: What to do if `keep` is odd but the current keep_size
1010                is even, or vice versa.
1011                * 'error' (default): Raises `IndexError`.
1012                * 'high': The higher outcome is taken.
1013                * 'low': The lower outcome is taken.
1014        """
1015        # Expression evaluators are difficult to type.
1016        return self.pool(rolls).middle(keep, tie=tie).sum()  # type: ignore
1017
1018    def map_to_pool(
1019        self,
1020        repl:
1021        'Callable[..., Sequence[icepool.Die[U] | U] | Mapping[icepool.Die[U], int] | Mapping[U, int] | icepool.RerollType] | None' = None,
1022        /,
1023        *extra_args: 'Outcome | icepool.Die | icepool.MultisetExpression',
1024        star: bool | None = None,
1025        denominator: int | None = None
1026    ) -> 'icepool.MultisetGenerator[U, tuple[int]]':
1027        """EXPERIMENTAL: Maps outcomes of this `Die` to `Pools`, creating a `MultisetGenerator`.
1028
1029        As `icepool.map_to_pool(repl, self, ...)`.
1030
1031        If no argument is provided, the outcomes will be used to construct a
1032        mixture of pools directly, similar to the inverse of `pool.expand()`.
1033        Note that this is not particularly efficient since it does not make much
1034        use of dynamic programming.
1035
1036        Args:
1037            repl: One of the following:
1038                * A callable that takes in one outcome per element of args and
1039                    produces a `Pool` (or something convertible to such).
1040                * A mapping from old outcomes to `Pool` 
1041                    (or something convertible to such).
1042                    In this case args must have exactly one element.
1043                The new outcomes may be dice rather than just single outcomes.
1044                The special value `icepool.Reroll` will reroll that old outcome.
1045            star: If `True`, the first of the args will be unpacked before 
1046                giving them to `repl`.
1047                If not provided, it will be guessed based on the signature of 
1048                `repl` and the number of arguments.
1049            denominator: If provided, the denominator of the result will be this
1050                value. Otherwise it will be the minimum to correctly weight the
1051                pools.
1052
1053        Returns:
1054            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1055            that this is not technically a `Pool`, though it supports most of 
1056            the same operations.
1057
1058        Raises:
1059            ValueError: If `denominator` cannot be made consistent with the 
1060                resulting mixture of pools.
1061        """
1062        if repl is None:
1063            repl = lambda x: x
1064        return icepool.map_to_pool(repl,
1065                                   self,
1066                                   *extra_args,
1067                                   star=star,
1068                                   denominator=denominator)
1069
1070    def explode_to_pool(
1071            self,
1072            rolls: int,
1073            which: Collection[T_co] | Callable[..., bool] | None = None,
1074            /,
1075            *,
1076            star: bool | None = None,
1077            depth: int = 9) -> 'icepool.MultisetGenerator[T_co, tuple[int]]':
1078        """EXPERIMENTAL: Causes outcomes to be rolled again, keeping that outcome as an individual die in a pool.
1079        
1080        Args:
1081            rolls: The number of initial dice.
1082            which: Which outcomes to explode. Options:
1083                * A single outcome to explode.
1084                * An collection of outcomes to explode.
1085                * A callable that takes an outcome and returns `True` if it
1086                    should be exploded.
1087                * If not supplied, the max outcome will explode.
1088            star: Whether outcomes should be unpacked into separate arguments
1089                before sending them to a callable `which`.
1090                If not provided, this will be guessed based on the function
1091                signature.
1092            depth: The maximum depth of explosions for an individual dice.
1093
1094        Returns:
1095            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1096            that this is not technically a `Pool`, though it supports most of 
1097            the same operations.
1098        """
1099        if depth == 0:
1100            return self.pool(rolls)
1101        if which is None:
1102            explode_set = {self.max_outcome()}
1103        else:
1104            explode_set = self._select_outcomes(which, star)
1105        if not explode_set:
1106            return self.pool(rolls)
1107        explode, not_explode = self.split(explode_set)
1108
1109        single_data: 'MutableMapping[icepool.Vector[int], int]' = defaultdict(
1110            int)
1111        for i in range(depth + 1):
1112            weight = explode.denominator()**i * self.denominator()**(
1113                depth - i) * not_explode.denominator()
1114            single_data[icepool.Vector((i, 1))] += weight
1115        single_data[icepool.Vector(
1116            (depth + 1, 0))] += explode.denominator()**(depth + 1)
1117
1118        single_count_die: 'Die[icepool.Vector[int]]' = Die(single_data)
1119        count_die = rolls @ single_count_die
1120
1121        return count_die.map_to_pool(
1122            lambda x, nx: [explode] * x + [not_explode] * nx)
1123
1124    def reroll_to_pool(
1125        self,
1126        rolls: int,
1127        which: Callable[..., bool] | Collection[T_co],
1128        /,
1129        max_rerolls: int,
1130        *,
1131        star: bool | None = None,
1132        mode: Literal['random', 'lowest', 'highest', 'drop'] = 'random'
1133    ) -> 'icepool.MultisetGenerator[T_co, tuple[int]]':
1134        """EXPERIMENTAL: Applies a limited number of rerolls shared across a pool.
1135
1136        Each die can only be rerolled once (effectively `depth=1`), and no more
1137        than `max_rerolls` dice may be rerolled.
1138        
1139        Args:
1140            rolls: How many dice in the pool.
1141            which: Selects which outcomes are eligible to be rerolled. Options:
1142                * A collection of outcomes to reroll.
1143                * A callable that takes an outcome and returns `True` if it
1144                    could be rerolled.
1145            max_rerolls: The maximum number of dice to reroll. 
1146                Note that each die can only be rerolled once, so if the number 
1147                of eligible dice is less than this, the excess rerolls have no
1148                effect.
1149            star: Whether outcomes should be unpacked into separate arguments
1150                before sending them to a callable `which`.
1151                If not provided, this will be guessed based on the function
1152                signature.
1153            mode: How dice are selected for rerolling if there are more eligible
1154                dice than `max_rerolls`. Options:
1155                * `'random'` (default): Eligible dice will be chosen uniformly
1156                    at random.
1157                * `'lowest'`: The lowest eligible dice will be rerolled.
1158                * `'highest'`: The highest eligible dice will be rerolled.
1159                * `'drop'`: All dice that ended up on an outcome selected by 
1160                    `which` will be dropped. This includes both dice that rolled
1161                    into `which` initially and were not rerolled, and dice that
1162                    were rerolled but rolled into `which` again. This can be
1163                    considerably more efficient than the other modes.
1164
1165        Returns:
1166            A `MultisetGenerator` representing the mixture of `Pool`s. Note  
1167            that this is not technically a `Pool`, though it supports most of 
1168            the same operations.
1169        """
1170        rerollable_set = self._select_outcomes(which, star)
1171        if not rerollable_set:
1172            return self.pool(rolls)
1173
1174        rerollable_die, not_rerollable_die = self.split(rerollable_set)
1175        single_is_rerollable = icepool.coin(rerollable_die.denominator(),
1176                                            self.denominator())
1177        rerollable = rolls @ single_is_rerollable
1178
1179        def split(initial_rerollable: int) -> Die[tuple[int, int, int]]:
1180            """Computes the composition of the pool.
1181
1182            Returns:
1183                initial_rerollable: The number of dice that initially fell into
1184                    the rerollable set.
1185                rerolled_to_rerollable: The number of dice that were rerolled,
1186                    but fell into the rerollable set again.
1187                not_rerollable: The number of dice that ended up outside the
1188                    rerollable set, including both initial and rerolled dice.
1189                not_rerolled: The number of dice that were eligible for
1190                    rerolling but were not rerolled.
1191            """
1192            initial_not_rerollable = rolls - initial_rerollable
1193            rerolled = min(initial_rerollable, max_rerolls)
1194            not_rerolled = initial_rerollable - rerolled
1195
1196            def second_split(rerolled_to_rerollable):
1197                """Splits the rerolled dice into those that fell into the rerollable and not-rerollable sets."""
1198                rerolled_to_not_rerollable = rerolled - rerolled_to_rerollable
1199                return icepool.tupleize(
1200                    initial_rerollable, rerolled_to_rerollable,
1201                    initial_not_rerollable + rerolled_to_not_rerollable,
1202                    not_rerolled)
1203
1204            return icepool.map(second_split,
1205                               rerolled @ single_is_rerollable,
1206                               star=False)
1207
1208        pool_composition = rerollable.map(split, star=False)
1209
1210        def make_pool(initial_rerollable, rerolled_to_rerollable,
1211                      not_rerollable, not_rerolled):
1212            common = rerollable_die.pool(
1213                rerolled_to_rerollable) + not_rerollable_die.pool(
1214                    not_rerollable)
1215            match mode:
1216                case 'random':
1217                    return common + rerollable_die.pool(not_rerolled)
1218                case 'lowest':
1219                    return common + rerollable_die.pool(
1220                        initial_rerollable).highest(not_rerolled)
1221                case 'highest':
1222                    return common + rerollable_die.pool(
1223                        initial_rerollable).lowest(not_rerolled)
1224                case 'drop':
1225                    return not_rerollable_die.pool(not_rerollable)
1226                case _:
1227                    raise ValueError(
1228                        f"Invalid reroll_priority '{mode}'. Allowed values are 'random', 'lowest', 'highest', 'drop'."
1229                    )
1230
1231        denominator = self.denominator()**(rolls + min(rolls, max_rerolls))
1232
1233        return pool_composition.map_to_pool(make_pool,
1234                                            star=True,
1235                                            denominator=denominator)
1236
1237    # Unary operators.
1238
1239    def __neg__(self) -> 'Die[T_co]':
1240        return self.unary_operator(operator.neg)
1241
1242    def __pos__(self) -> 'Die[T_co]':
1243        return self.unary_operator(operator.pos)
1244
1245    def __invert__(self) -> 'Die[T_co]':
1246        return self.unary_operator(operator.invert)
1247
1248    def abs(self) -> 'Die[T_co]':
1249        return self.unary_operator(operator.abs)
1250
1251    __abs__ = abs
1252
1253    def round(self, ndigits: int | None = None) -> 'Die':
1254        return self.unary_operator(round, ndigits)
1255
1256    __round__ = round
1257
1258    def stochastic_round(self,
1259                         *,
1260                         max_denominator: int | None = None) -> 'Die[int]':
1261        """Randomly rounds outcomes up or down to the nearest integer according to the two distances.
1262        
1263        Specificially, rounds `x` up with probability `x - floor(x)` and down
1264        otherwise.
1265
1266        Args:
1267            max_denominator: If provided, each rounding will be performed
1268                using `fractions.Fraction.limit_denominator(max_denominator)`.
1269                Otherwise, the rounding will be performed without
1270                `limit_denominator`.
1271        """
1272        return self.map(lambda x: icepool.stochastic_round(
1273            x, max_denominator=max_denominator))
1274
1275    def trunc(self) -> 'Die':
1276        return self.unary_operator(math.trunc)
1277
1278    __trunc__ = trunc
1279
1280    def floor(self) -> 'Die':
1281        return self.unary_operator(math.floor)
1282
1283    __floor__ = floor
1284
1285    def ceil(self) -> 'Die':
1286        return self.unary_operator(math.ceil)
1287
1288    __ceil__ = ceil
1289
1290    # Binary operators.
1291
1292    def __add__(self, other) -> 'Die':
1293        if isinstance(other, icepool.AgainExpression):
1294            return NotImplemented
1295        other = implicit_convert_to_die(other)
1296        return self.binary_operator(other, operator.add)
1297
1298    def __radd__(self, other) -> 'Die':
1299        if isinstance(other, icepool.AgainExpression):
1300            return NotImplemented
1301        other = implicit_convert_to_die(other)
1302        return other.binary_operator(self, operator.add)
1303
1304    def __sub__(self, other) -> 'Die':
1305        if isinstance(other, icepool.AgainExpression):
1306            return NotImplemented
1307        other = implicit_convert_to_die(other)
1308        return self.binary_operator(other, operator.sub)
1309
1310    def __rsub__(self, other) -> 'Die':
1311        if isinstance(other, icepool.AgainExpression):
1312            return NotImplemented
1313        other = implicit_convert_to_die(other)
1314        return other.binary_operator(self, operator.sub)
1315
1316    def __mul__(self, other) -> 'Die':
1317        if isinstance(other, icepool.AgainExpression):
1318            return NotImplemented
1319        other = implicit_convert_to_die(other)
1320        return self.binary_operator(other, operator.mul)
1321
1322    def __rmul__(self, other) -> 'Die':
1323        if isinstance(other, icepool.AgainExpression):
1324            return NotImplemented
1325        other = implicit_convert_to_die(other)
1326        return other.binary_operator(self, operator.mul)
1327
1328    def __truediv__(self, other) -> 'Die':
1329        if isinstance(other, icepool.AgainExpression):
1330            return NotImplemented
1331        other = implicit_convert_to_die(other)
1332        return self.binary_operator(other, operator.truediv)
1333
1334    def __rtruediv__(self, other) -> 'Die':
1335        if isinstance(other, icepool.AgainExpression):
1336            return NotImplemented
1337        other = implicit_convert_to_die(other)
1338        return other.binary_operator(self, operator.truediv)
1339
1340    def __floordiv__(self, other) -> 'Die':
1341        if isinstance(other, icepool.AgainExpression):
1342            return NotImplemented
1343        other = implicit_convert_to_die(other)
1344        return self.binary_operator(other, operator.floordiv)
1345
1346    def __rfloordiv__(self, other) -> 'Die':
1347        if isinstance(other, icepool.AgainExpression):
1348            return NotImplemented
1349        other = implicit_convert_to_die(other)
1350        return other.binary_operator(self, operator.floordiv)
1351
1352    def __pow__(self, other) -> 'Die':
1353        if isinstance(other, icepool.AgainExpression):
1354            return NotImplemented
1355        other = implicit_convert_to_die(other)
1356        return self.binary_operator(other, operator.pow)
1357
1358    def __rpow__(self, other) -> 'Die':
1359        if isinstance(other, icepool.AgainExpression):
1360            return NotImplemented
1361        other = implicit_convert_to_die(other)
1362        return other.binary_operator(self, operator.pow)
1363
1364    def __mod__(self, other) -> 'Die':
1365        if isinstance(other, icepool.AgainExpression):
1366            return NotImplemented
1367        other = implicit_convert_to_die(other)
1368        return self.binary_operator(other, operator.mod)
1369
1370    def __rmod__(self, other) -> 'Die':
1371        if isinstance(other, icepool.AgainExpression):
1372            return NotImplemented
1373        other = implicit_convert_to_die(other)
1374        return other.binary_operator(self, operator.mod)
1375
1376    def __lshift__(self, other) -> 'Die':
1377        if isinstance(other, icepool.AgainExpression):
1378            return NotImplemented
1379        other = implicit_convert_to_die(other)
1380        return self.binary_operator(other, operator.lshift)
1381
1382    def __rlshift__(self, other) -> 'Die':
1383        if isinstance(other, icepool.AgainExpression):
1384            return NotImplemented
1385        other = implicit_convert_to_die(other)
1386        return other.binary_operator(self, operator.lshift)
1387
1388    def __rshift__(self, other) -> 'Die':
1389        if isinstance(other, icepool.AgainExpression):
1390            return NotImplemented
1391        other = implicit_convert_to_die(other)
1392        return self.binary_operator(other, operator.rshift)
1393
1394    def __rrshift__(self, other) -> 'Die':
1395        if isinstance(other, icepool.AgainExpression):
1396            return NotImplemented
1397        other = implicit_convert_to_die(other)
1398        return other.binary_operator(self, operator.rshift)
1399
1400    def __and__(self, other) -> 'Die':
1401        if isinstance(other, icepool.AgainExpression):
1402            return NotImplemented
1403        other = implicit_convert_to_die(other)
1404        return self.binary_operator(other, operator.and_)
1405
1406    def __rand__(self, other) -> 'Die':
1407        if isinstance(other, icepool.AgainExpression):
1408            return NotImplemented
1409        other = implicit_convert_to_die(other)
1410        return other.binary_operator(self, operator.and_)
1411
1412    def __or__(self, other) -> 'Die':
1413        if isinstance(other, icepool.AgainExpression):
1414            return NotImplemented
1415        other = implicit_convert_to_die(other)
1416        return self.binary_operator(other, operator.or_)
1417
1418    def __ror__(self, other) -> 'Die':
1419        if isinstance(other, icepool.AgainExpression):
1420            return NotImplemented
1421        other = implicit_convert_to_die(other)
1422        return other.binary_operator(self, operator.or_)
1423
1424    def __xor__(self, other) -> 'Die':
1425        if isinstance(other, icepool.AgainExpression):
1426            return NotImplemented
1427        other = implicit_convert_to_die(other)
1428        return self.binary_operator(other, operator.xor)
1429
1430    def __rxor__(self, other) -> 'Die':
1431        if isinstance(other, icepool.AgainExpression):
1432            return NotImplemented
1433        other = implicit_convert_to_die(other)
1434        return other.binary_operator(self, operator.xor)
1435
1436    # Comparators.
1437
1438    def __lt__(self, other) -> 'Die[bool]':
1439        if isinstance(other, icepool.AgainExpression):
1440            return NotImplemented
1441        other = implicit_convert_to_die(other)
1442        return self.binary_operator(other, operator.lt)
1443
1444    def __le__(self, other) -> 'Die[bool]':
1445        if isinstance(other, icepool.AgainExpression):
1446            return NotImplemented
1447        other = implicit_convert_to_die(other)
1448        return self.binary_operator(other, operator.le)
1449
1450    def __ge__(self, other) -> 'Die[bool]':
1451        if isinstance(other, icepool.AgainExpression):
1452            return NotImplemented
1453        other = implicit_convert_to_die(other)
1454        return self.binary_operator(other, operator.ge)
1455
1456    def __gt__(self, other) -> 'Die[bool]':
1457        if isinstance(other, icepool.AgainExpression):
1458            return NotImplemented
1459        other = implicit_convert_to_die(other)
1460        return self.binary_operator(other, operator.gt)
1461
1462    # Equality operators. These produce a `DieWithTruth`.
1463
1464    # The result has a truth value, but is not a bool.
1465    def __eq__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1466        if isinstance(other, icepool.AgainExpression):
1467            return NotImplemented
1468        other_die: Die = implicit_convert_to_die(other)
1469
1470        def data_callback() -> Counts[bool]:
1471            return self.binary_operator(other_die, operator.eq)._data
1472
1473        def truth_value_callback() -> bool:
1474            return self.equals(other)
1475
1476        return icepool.DieWithTruth(data_callback, truth_value_callback)
1477
1478    # The result has a truth value, but is not a bool.
1479    def __ne__(self, other) -> 'icepool.DieWithTruth[bool]':  # type: ignore
1480        if isinstance(other, icepool.AgainExpression):
1481            return NotImplemented
1482        other_die: Die = implicit_convert_to_die(other)
1483
1484        def data_callback() -> Counts[bool]:
1485            return self.binary_operator(other_die, operator.ne)._data
1486
1487        def truth_value_callback() -> bool:
1488            return not self.equals(other)
1489
1490        return icepool.DieWithTruth(data_callback, truth_value_callback)
1491
1492    def cmp(self, other) -> 'Die[int]':
1493        """A `Die` with outcomes 1, -1, and 0.
1494
1495        The quantities are equal to the positive outcome of `self > other`,
1496        `self < other`, and the remainder respectively.
1497        """
1498        other = implicit_convert_to_die(other)
1499
1500        data = {}
1501
1502        lt = self < other
1503        if True in lt:
1504            data[-1] = lt[True]
1505        eq = self == other
1506        if True in eq:
1507            data[0] = eq[True]
1508        gt = self > other
1509        if True in gt:
1510            data[1] = gt[True]
1511
1512        return Die(data)
1513
1514    @staticmethod
1515    def _sign(x) -> int:
1516        z = Die._zero(x)
1517        if x > z:
1518            return 1
1519        elif x < z:
1520            return -1
1521        else:
1522            return 0
1523
1524    def sign(self) -> 'Die[int]':
1525        """Outcomes become 1 if greater than `zero()`, -1 if less than `zero()`, and 0 otherwise.
1526
1527        Note that for `float`s, +0.0, -0.0, and nan all become 0.
1528        """
1529        return self.unary_operator(Die._sign)
1530
1531    # Equality and hashing.
1532
1533    def __bool__(self) -> bool:
1534        raise TypeError(
1535            'A `Die` only has a truth value if it is the result of == or !=.\n'
1536            'This could result from trying to use a die in an if-statement,\n'
1537            'in which case you should use `die.if_else()` instead.\n'
1538            'Or it could result from trying to use a `Die` inside a tuple or vector outcome,\n'
1539            'in which case you should use `tupleize()` or `vectorize().')
1540
1541    @cached_property
1542    def _hash_key(self) -> tuple:
1543        """A tuple that uniquely (as `equals()`) identifies this die.
1544
1545        Apart from being hashable and totally orderable, this is not guaranteed
1546        to be in any particular format or have any other properties.
1547        """
1548        return tuple(self.items())
1549
1550    @cached_property
1551    def _hash(self) -> int:
1552        return hash(self._hash_key)
1553
1554    def __hash__(self) -> int:
1555        return self._hash
1556
1557    def equals(self, other, *, simplify: bool = False) -> bool:
1558        """`True` iff both dice have the same outcomes and quantities.
1559
1560        This is `False` if `other` is not a `Die`, even if it would convert
1561        to an equal `Die`.
1562
1563        Truth value does NOT matter.
1564
1565        If one `Die` has a zero-quantity outcome and the other `Die` does not
1566        contain that outcome, they are treated as unequal by this function.
1567
1568        The `==` and `!=` operators have a dual purpose; they return a `Die`
1569        with a truth value determined by this method.
1570        Only dice returned by these methods have a truth value. The data of
1571        these dice is lazily evaluated since the caller may only be interested
1572        in the `Die` value or the truth value.
1573
1574        Args:
1575            simplify: If `True`, the dice will be simplified before comparing.
1576                Otherwise, e.g. a 2:2 coin is not `equals()` to a 1:1 coin.
1577        """
1578        if not isinstance(other, Die):
1579            return False
1580
1581        if simplify:
1582            return self.simplify()._hash_key == other.simplify()._hash_key
1583        else:
1584            return self._hash_key == other._hash_key
1585
1586    # Strings.
1587
1588    def __repr__(self) -> str:
1589        inner = ', '.join(f'{repr(outcome)}: {weight}'
1590                          for outcome, weight in self.items())
1591        return type(self).__qualname__ + '({' + inner + '})'