Topics

#combinatorics #dice #dice-probabilities #jupyterlite #order-statistics #probability #python #python3 #rpg

Language breakdown

No language data available.

▸ Files click to expand

README

Icepool

Python dice probability package.

GitHub repository.

PyPi page.

Try coding in your browser using Icecup, a simple frontend for scripting and graphing similar to AnyDice, SnakeEyes, and Troll. You can find a series of tutorials here.

Features

Pure Python implementation using only the Standard Library. Run it almost anywhere Python runs: program locally, share Jupyter notebooks, or build your own client-side web apps using Pyodide.
Dice support all standard operators (+, -, <, >, etc.) as well as an extensive library of functions (rerolling, exploding, etc.)

Efficient dice pool algorithm can solve keep-highest, finding sets and/or straights, RISK*-like mechanics, and more in milliseconds, even for large pools.

Exact fractional probabilities using Python ints.
Some support for decks (aka sampling without replacement).

Installing

pip install icepool

The source is pure Python, so including a direct copy in your project can work as well.

Contact

Feel free to open a discussion or issue on GitHub. You can also find me on Reddit or Twitter.

API documentation

pdoc on GitHub.

JupyterLite notebooks

See this JupyterLite distribution for a collection of interactive, editable examples. These include mechanics from published games, StackExchange, Reddit, and academic papers.

JupyterLite REPL.

As a backup, you can open the notebooks in Google Colab.

Tutorial notebooks

In particular, here is a series of tutorial notebooks.

StackExchange answers

Call-on traits in Burning Wheel*: Success-counting dice pools with explosions and rerolls. Vampire the Masquerade V*

Roll multiple ability score arrays and pick the one with the highest total. What is the distribution of each ranked score?

Year Zero Engine* Neon City Overdrive* Broken Compass / Household / Outgunned*

Probability that 0/4 players is dealt Blackjack

Here is a full search of answers in which I mention Icepool.

Web applications

These are all client-side, powered by Pyodide. Perhaps you will find inspiration for your own application.

Icecup, a simple frontend for scripting and graphing.

Alex Recarey's Face 2 Face Calculator for Infinity the Game* -- including the ability to be installed on Android and iOS and run without an internet connection.

Legends of the Wulin* calculator.

Year Zero Engine calculator.

Paper on algorithm

Presented at Artificial Intelligence and Interactive Digital Entertainment (AIIDE) 2022.

In the official proceedings.

Preprint in this repository.

BibTeX:

@inproceedings{liu2022icepool,
    title={Icepool: Efficient Computation of Dice Pool Probabilities},
    author={Albert Julius Liu},
    booktitle={Eighteenth AAAI Conference on Artificial Intelligence and Interactive Digital Entertainment},
    volume={18},
    number={1},
    pages={258-265},
    year={2022},
    month={Oct.},
    eventdate={2022-10-24/2022-10-28},
    venue={Pomona, California},
    url={https://ojs.aaai.org/index.php/AIIDE/article/view/21971},
    doi={10.1609/aiide.v18i1.21971}
}

Versioning

Frankly, I haven't made backwards compatibility a top priority. If you need specific behavior, I recommend version pinning. Typing is especially unstable.

Similar projects

In roughly chronological order:

Troll by Torben Ægidius Mogensen

http://hjemmesider.diku.dk/~torbenm/Troll/

The oldest general-purpose dice probability calculator I know of. It has an accompanying peer-reviewed paper.

AnyDice by Jasper Flick

https://anydice.com/

Probably the most popular dice probability calculator in existence, and with good reason---its accessibility and shareability remains unparalleled. I still use it often for prototyping and as a second opinion.

SnakeEyes by Noé Falzon

https://snake-eyes.io/

SnakeEyes demonstrated the viability of browser-based, client-side dice calculation, as well as introducing me to Chart.js.

dice_roll.py by Ilmari Karonen

https://gist.github.com/vyznev/8f5e62c91ce4d8ca7841974c87271e2f

This demonstrated the trick of iterating "vertically" over the outcomes of dice in a dice pool, rather than "horizontally" through the dice---one of the insights into creating a much faster dice pool algorithm.