Package: dycelib
Copyright and other protections apply.
Please see the accompanyingLICENSEfile 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 finite discrete probabilities💥Now 100%Bear-ified™!👌🏾🐻(Detailsbelow.)dyceis a pure-Python library for modeling arbitrarily complex dice mechanics.
It strives forcompact expressionandefficient computation, especially for the most common cases.
Its primary applications:Computing finite discrete probability distributions for:Game designers who want to understand or experiment with various dice mechanics and interactions;Players (including game masters) who may be curious about in-game probabilities; andTool authors who serve those game designers or players.Generating transparent, weighted random rolls for:Software developers who want to enable flexible dice mechanic resolution in their gaming environments such as chat servers or virtual tabletops (VTTs).Beyond those audiences, it may be useful to anyone interested in exploring finite discrete probabilities but not in developing all the low-level math bits from scratch.dyceis 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 variousgame notationsshould be able to adapt quickly.
If you’re looking at something on which to build your own grammar or interface,dycecan serve you well.dyceshould be able to replicate or replace most other dice probability modeling tools.
It strives to befully documentedand relies heavily on examples to develop understanding.dyceis licensed under theMIT License.
See the accompanyingLICENSEfile for details.
Non-experimental features should be considered stable (but an unquenchable thirst to increase performance remains).
See therelease notesfor a summary of version-to-version changes.
Source code isavailable on GitHub.If you find it lacking in any way, please don’t hesitate tobring it to my attention.CustomersThis could beyou! 👋Do you have a project that usesdyce?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/master/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#imageAs of version 1.1, HighRollin is |dyce-powered|!..|dyce-powered|image::https://raw.githubusercontent.com/posita/dyce/master/docs/dyce-powered.svg:align:top:target:https://posita.github.io/dyce/:alt:dyce-powered<!-- HTML -->As of version 1.1, HighRollin is<ahref="https://posita.github.io/dyce/"><imgsrc="https://raw.githubusercontent.com/posita/dyce/master/docs/dyce-powered.svg"alt="dyce-powered"style="vertical-align: middle;"></a>!A tastedyceprovides several core primitives.Hobjectsrepresent histograms for modeling finite discrete outcomes, like individual dice.Pobjectsrepresent pools (ordered sequences) of histograms.Robjects(coveredelsewhere) 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.>>>fromdyceimportH>>>d6=H(6)# a standard six-sided die>>>2@d6*3-4# 2d6 × 3 - 4H({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 secondH({False:21,True:15})>>>abs(d6-d6)# subtract the least of two six-sided dice from the greatestH({0:6,1:10,2:8,3:6,4:4,5:2})>>>fromdyceimportP>>>p_2d6=2@P(d6)# a pool of two six-sided dice>>>p_2d6.h()# pools can be collapsed into histogramsH({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 comparableTrueBy providing an optional argument to theP.hmethod, one can “take” individual dice from pools, ordered least to greatest.
(TheH.formatmethodprovides rudimentary visualization for convenience.)>>>p_2d6.h(0)# take the lowest die of 2d6H({1:11,2:9,3:7,4:5,5:3,6:1})>>>print(p_2d6.h(0).format(width=65))avg|2.53std|1.40var|1.971|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 2d6H({1:1,2:3,3:5,4:7,5:9,6:11})>>>print(p_2d6.h(-1).format(width=65))avg|4.47std|1.40var|1.971|2.78%|#2|8.33%|####3|13.89%|######4|19.44%|#########5|25.00%|############6|30.56%|###############Hobjectsprovide adistributionmethodand adistribution_xymethodto ease integration with plotting packages likematplotlib.>>>importmatplotlib# doctest: +SKIP>>>outcomes,probabilities=p_2d6.h(0).distribution_xy()>>>matplotlib.pyplot.bar(...[v-0.125forvinoutcomes],...probabilities,...alpha=0.75,...width=0.5,...label="Lowest",...)# doctest: +SKIP>>>outcomes,probabilities=p_2d6.h(-1).distribution_xy()>>>matplotlib.pyplot.bar(...[v+0.125forvinoutcomes],...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: +SKIPHobjectsandPobjectscan generate random rolls.>>>d6=H(6)>>>d6.roll()# doctest: +SKIP4>>>d10=H(10)-1>>>p_6d10=6@P(d10)>>>p_6d10.roll()# doctest: +SKIP(0,1,2,3,5,7)See the tutorials oncountingandrolling, as well as theAPI guidefor much more thorough treatments, including detailed examples.Design philosophydyceis 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.
Itknows, even if knowing is harder or more limiting.
Which, if we possess a modicum of humility, it often is.!!! 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 TverskyBecausedyceexposes 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,dyceis completely adequate for casual tinkering.
However, it really shines when used in larger contexts such as withMatplotliborJupyteror embedded in a special-purpose application.[^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.
It doesn’t mind.
It actually [kind of *likes* it](https://posita.github.io/dyce/0.4/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 fromRFC 1925, § 2.2,dyceincludes some conveniences, such as minor computation optimizations (e.g., theH.lowest_termsmethod, various other shorthands, etc.) and formatting conveniences (e.g., theH.distribution,H.distribution_xy, andH.formatmethods).Comparison to alternativesThe following is a best-effort[^3] summary of the differences between various available tools in this space.
Consider exploring theapplications and translationsfor 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.4/contrib/) if you observe discrepancies.dyceBogosian et al.dice_roll.pyKaronenpython-diceRobson et al.AnyDiceFlickd20Curse LLCDnDice“LordSembor”diceClements et al.dice-notationGarridodyceEykLatest release2021N/A2021Unknown20212016202120212009Actively 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.Licensedyceis licensed under theMIT License.
See the includedLICENSEfile for details.
Source code isavailable on GitHub.InstallationInstallation can be performed viaPyPI.%pipinstalldycelib
...Alternately, you can downloadthe sourceand runsetup.py.%gitclonehttps://github.com/posita/dyce.git
...
%cddyce
%pythonsetup.pyinstall
...Requirementsdycerequires a relatively modern version of Python:CPython(3.7+)PyPy(CPython 3.7+ compatible)It has the following runtime dependencies:typing-extensions(with Python <3.9)dycewill opportunistically use the following, if available at runtime:beartypefor yummy runtime type-checking goodness (0.8+)graphvizfor visualizingrollers and rollsmatplotlibfor visualizinghistograms and poolsIf you installbeartypefor type checking your own code, but don’t wantdyceto use it (e.g., for performance reasons), you can set theDYCE_BEARTYPEenvironment variable to a falsy[^9] value beforedyceis imported.[^9]:
I.E., one of:0,off,f,false, andno.See thehacking quick-startfor additional development and testing dependencies.