Simple Python tools for exploring dice outcomes and other discrete probabilities
Project description
Copyright and other protections apply.
Please see the accompanying LICENSE
file for rights and restrictions governing use of this software.
All rights not expressly waived or licensed are reserved.
If that file is missing or appears to be modified from its original, then please contact the author before viewing or using this software in any capacity.
Now you’re playing with…
dyce
– simple Python tools for exploring dice outcomes and other discrete probabilities
dyce
is a pure-Python library for computing discrete probability distributions.
It is designed to be immediately and broadly useful with minimal additional investment beyond basic knowledge of Python.
While not as compact as a dedicated grammar, dyce
’s Python-based primitives are quite sufficient, and often more expressive.
Those familiar with various game notations should be able to adapt quickly.
That being said, if you’re looking at something on which to build your own grammar, dyce
can serve you well.
Check out the dyce.r
sub-package and the rolling tutorial.
dyce
should be able to replicate or replace most other dice probability modeling tools.
It strives to be fully documented and relies heavily on examples to develop understanding.
If you find it lacking in any way, please consider contributing an issue to start a discussion.
dyce
is licensed under the MIT License.
See the accompanying LICENSE
file for details.
Non-experimental features should be considered stable (but an unquenchable thirst to increase performance remains).
See the release notes for a summary of version-to-version changes.
Source code is available on GitHub.
Customers
- This could be you! 👋
Do you have a project that uses dyce
?
Let me know, and I’ll promote it here!
And don’t forget to do your part in perpetuating gratuitous badge-ification!
<!-- Markdown -->
As of version 1.1, HighRollin is
[![dyce-powered](https://raw.githubusercontent.com/posita/dyce/v0.3.1/docs/dyce-powered.svg)][dyce-powered]!
[dyce-powered]: https://posita.github.io/dyce/ "dyce-powered!"
..
reStructuredText - see https://docutils.sourceforge.io/docs/ref/rst/directives.html#image
As of version 1.1, HighRollin is |dyce-powered|!
.. |dyce-powered| image:: https://raw.githubusercontent.com/posita/dyce/v0.3.1/docs/dyce-powered.svg
:align: top
:target: https://posita.github.io/dyce/
:alt: dyce-powered
<!-- HTML -->
As of version 1.1, HighRollin is <a href="https://posita.github.io/dyce/"><img
src="https://raw.githubusercontent.com/posita/dyce/v0.3.1/docs/dyce-powered.svg"
alt="dyce-powered"
style="vertical-align: middle;"></a>!
A taste
dyce
provides several core primitives.
H
objects represent histograms for modeling discrete outcomes, like individual dice.
P
objects represent pools (ordered sequences) of histograms.
R
objects (covered elsewhere) represent nodes in arbitrary roller trees useful for translating from proprietary grammars and generating weighted random rolls that “show their work” without the overhead of enumeration.
All support a variety of operations.
>>> from dyce import H
>>> d6 = H(6) # a standard six-sided die
>>> 2@d6 * 3 - 4 # 2d6 × 3 - 4
H({2: 1, 5: 2, 8: 3, 11: 4, 14: 5, 17: 6, 20: 5, 23: 4, 26: 3, 29: 2, 32: 1})
>>> d6.lt(d6) # how often a first six-sided die shows a face less than a second
H({False: 21, True: 15})
>>> abs(d6 - d6) # subtract the least of two six-sided dice from the greatest
H({0: 6, 1: 10, 2: 8, 3: 6, 4: 4, 5: 2})
>>> from dyce import P
>>> p_2d6 = 2@P(d6) # a pool of two six-sided dice
>>> p_2d6.h() # pools can be collapsed into histograms
H({2: 1, 3: 2, 4: 3, 5: 4, 6: 5, 7: 6, 8: 5, 9: 4, 10: 3, 11: 2, 12: 1})
>>> p_2d6 == 2@d6 # pools and histograms are comparable
True
By providing an optional argument to the P.h
method, one can “take” individual dice from pools, ordered least to greatest.
(The H.format
method provides rudimentary visualization for convenience.)
>>> p_2d6.h(0) # take the lowest die of 2d6
H({1: 11, 2: 9, 3: 7, 4: 5, 5: 3, 6: 1})
>>> print(p_2d6.h(0).format(width=65))
avg | 2.53
std | 1.40
var | 1.97
1 | 30.56% |###############
2 | 25.00% |############
3 | 19.44% |#########
4 | 13.89% |######
5 | 8.33% |####
6 | 2.78% |#
>>> p_2d6.h(-1) # take the highest die of 2d6
H({1: 1, 2: 3, 3: 5, 4: 7, 5: 9, 6: 11})
>>> print(p_2d6.h(-1).format(width=65))
avg | 4.47
std | 1.40
var | 1.97
1 | 2.78% |#
2 | 8.33% |####
3 | 13.89% |######
4 | 19.44% |#########
5 | 25.00% |############
6 | 30.56% |###############
H
objects provide a distribution
method and a distribution_xy
method to ease integration with plotting packages like matplotlib
.
>>> import matplotlib # doctest: +SKIP
>>> outcomes, probabilities = p_2d6.h(0).distribution_xy()
>>> matplotlib.pyplot.bar(
... [v - 0.125 for v in outcomes],
... probabilities,
... alpha=0.75,
... width=0.5,
... label="Lowest",
... ) # doctest: +SKIP
>>> outcomes, probabilities = p_2d6.h(-1).distribution_xy()
>>> matplotlib.pyplot.bar(
... [v + 0.125 for v in outcomes],
... probabilities,
... alpha=0.75,
... width=0.5,
... label="Highest",
... ) # doctest: +SKIP
>>> matplotlib.pyplot.legend() # doctest: +SKIP
>>> matplotlib.pyplot.title(r"Taking the lowest or highest die of 2d6") # doctest: +SKIP
>>> matplotlib.pyplot.show() # doctest: +SKIP
H
objects and P
objects can generate random rolls.
>>> d6 = H(6)
>>> d6.roll() # doctest: +SKIP
4
>>> d10 = H(10) - 1
>>> p_6d10 = 6@P(d10)
>>> p_6d10.roll() # doctest: +SKIP
(0, 1, 2, 3, 5, 7)
See the tutorials on counting and rolling, as well as the API guide for much more thorough treatments, including detailed examples.
Design philosophy
dyce
is fairly low-level by design, prioritizing ergonomics and composability.
It explicitly avoids stochastic simulation, but instead determines outcomes through enumeration and discrete computation.
That’s a highfalutin way of saying it doesn’t guess.
It knows, even if knowing is harder.
Which, if we’re honest with ourselves, it often is.
Or, at least, it should be.
!!! quote
“It’s frightening to think that you might not know something, but more frightening to think that, by and large, the world is run by people who have faith that they know exactly what is going on.”
—Amos Tversky
Because dyce
exposes Python primitives rather than defining a dedicated grammar and interpreter, one can more easily integrate it with other tools.[^1]
It can be installed and run anywhere[^2], and modified as desired.
On its own, dyce
is completely adequate for casual tinkering.
However, it really shines when used in larger contexts such as with Matplotlib or Jupyter.
[^1]:
You won’t find any lexers, parsers, or tokenizers in ``dyce``’s core, other than straight-up Python.
That being said, you can always “roll” your own (see what we did there?) and lean on ``dyce`` underneath to perform computations.
It doesn’t mind.
It actually [kind of *likes* it](https://posita.github.io/dyce/0.3/rollin/).
[^2]:
Okay, maybe not _literally_ anywhere, but [you’d be surprised](https://jokejet.com/guys-i-need-a-network-specialist-with-some-python-experience-its-urgent/).
Void where prohibited.
[Certain restrictions](#requirements) apply.
[Do not taunt Happy Fun Ball](https://youtu.be/GmqeZl8OI2M).
In an intentional departure from RFC 1925, § 2.2, dyce
includes some conveniences, such as minor computation optimizations (e.g., the H.lowest_terms
method, various other shorthands, etc.) and formatting conveniences (e.g., the H.distribution
, H.distribution_xy
, and H.format
methods).
Comparison to alternatives
The following is a best-effort[^3] summary of the differences between various available tools in this space. Consider exploring the applications and translations for added color.
[^3]:
I have attempted to ensure the above is reasonably accurate, but please consider [contributing an issue](https://posita.github.io/dyce/0.3/contrib/) if you observe discrepancies.
dyce Bogosian et al. |
dice_roll.py Karonen |
python-dice Robson et al. |
AnyDice Flick |
d20 Curse LLC |
DnDice “LordSembor” |
dice Clemens et al. |
dice-notation Garrido |
dyce Eyk |
|
---|---|---|---|---|---|---|---|---|---|
Latest release | 2021 | N/A | 2021 | Unknown | 2021 | 2016 | 2021 | 2021 | 2009 |
Actively maintained and documented | ✅ | ⚠️[^4] | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ |
Suitable as a dependency in other projects | ✅ | ⚠️[^5] | ✅ | ❌ | ✅ | ⚠️[^5] | ✅ | ❌ | ❌ |
Discrete outcome enumeration | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ | ❌ | ❌ | ❌ |
Arbitrary expressions | ✅ | ⚠️[^6] | ✅ | ✅ | ✅ | ⚠️[^7] | ❌ | ❌ | ❌ |
Arbitrary dice definitions | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
Integrates with other tools | ✅ | ✅ | ⚠️[^8] | ❌ | ⚠️[^8] | ✅ | ⚠️[^8] | ⚠️[^8] | ⚠️[^8] |
Open source (can inspect) | ✅ | ✅ | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ | ✅ |
Permissive licensing (can use and extend) | ✅ | ✅ | ✅ | N/A | ✅ | ✅ | ✅ | ✅ | ✅ |
[^4]:
Actively maintained, but sparsely documented.
The author has [expressed a desire](https://rpg.stackexchange.com/a/166663/71245) to release a more polished version.
[^5]:
Source can be downloaded and incorporated directly, but there is no packaging, versioning, or dependency tracking.
[^6]:
Callers must perform their own arithmetic and characterize results in terms of a lightweight die primitive, which may be less accessible to the novice.
That being said, the library is remarkably powerful, given its size.
[^7]:
Limited arithmetic operations are available.
The library also provides game-specific functions.
[^8]:
Results only.
Input is limited to specialized grammar.
License
dyce
is licensed under the MIT License.
See the included LICENSE
file for details.
Source code is available on GitHub.
Installation
Installation can be performed via PyPI.
% pip install dycelib
...
Alternately, you can download the source and run setup.py
.
% git clone https://github.com/posita/dyce.git
...
% cd dyce
% python setup.py install
...
Requirements
dyce
requires a relatively modern version of Python:
It has the following runtime dependencies:
typing-extensions
(with Python versions <3.8)
dyce
will opportunistically use the following, if available at runtime:
graphviz
for visualizing rollers and rollsmatplotlib
for visualizing histograms and pools
See the hacking quick-start for additional development and testing dependencies.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.