icepool

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

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

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

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

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

44class Outcome(Hashable, Protocol[T_contra]):
45    """Protocol to attempt to verify that outcome types are hashable and sortable.
46
47    Far from foolproof, e.g. it cannot enforce total ordering.
48    """
49
50    def __lt__(self, other: T_contra) -> bool:
51        ...

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