Dicechanics getting started

Dicechanics is a general-purpose dice probability calculator that provides an easy-to-use interface.

A three-tier system of immutable classes is exposed

  1. Die, the base primitive of dicechanics

  2. Pool, a group of mixed dice

  3. Bag, a pool of pools(Currently not implemented)

Creating a die

Creating a Die is easy; you invoke the d function.

import ttstatistics.dicechanics as ds
d6 = ds.d(6)

The above creates a six-sided die with faces 1,2,3,4,5,6 all represented once.

Another way is to give a list of faces you want.

ds.d([1,1,2,3,4,5,6])

Repeated faces are counted and taken into consideration, so this die is a 7-sided Die with two faces with a ´1´.

Instead of the above, you can use a string which can be expanded

ds.d("1:2,2..6")

It follows this syntax:

ds.d("<start>..<end>:<repeat>, <new statement>")

Creating a pool

The most common way to create a pool is to use the @ operator on a primitive.

pool = 3 @ d6

Which creates a pool of 3 six-sided dice, another way is with a dict and the pool function.

ds.pool({d6:3})

The dice are the keys, and the amount is the value of said die.

Extending pools

To extend pools, you add another pool to it.

p = 3@d6 + 1@d8

Or you can extend it one die at a time.

p.extend(d10)

Operating on a pool

A pool by itself does nothing; through the context of an operation, it gains meaning. The following operations are predefined:

  1. sum(pool): Sums the outcomes.

  2. mult(pool): Multiplies the outcomes.

  3. max(pool): Finds the maximum outcome.

  4. min(pool): Finds the minimum outcomes. There is a fifth function named perform that allows one to write custom operations:

def addDoubleY(x, y):
    return x+y*2

perform(myPool, addDoubleY)

All of these operations collapse the pool into a primitive.

Choosing a subset of pool outcomes

Let’s start by understanding what a pool subset is. Consider that you roll 3d6. A possible set of sorted outcomes is [1, 3, 6]. If we then want to sum the lowest outcome and highest outcome, we choose those indices: sum([1,3,6][::2]). This is also how you select subsets with the pool class.

pool = 3@d6
ds.sum(pool[::2])

or

ds.sum(pool[0,-1])

Using binary die operators to create new primitives

You can create new primitives through binary and unary operations; Meaning, instead of using a pool to find the probability of 2d6, you can add the two primitives together.

_2d6 = d6 + d6

Visualising results

Printing a primitive shows a probability graph.

>>> print(sum(2@d6))
Die with mu - 7.00, sigma - 2.42
--------------------------------
 2|### 2.78%
 3|####### 5.56%
 4|########## 8.33%
 5|############# 11.11%
 6|################# 13.89%
 7|#################### 16.67%
 8|################# 13.89%
 9|############# 11.11%
10|########## 8.33%
11|####### 5.56%
12|### 2.78%

Here, mu is the mean and sigma is the standard deviation.

Assessing die data

To access the data inside a Die you use the keys, values or items methods.

for face, probability in d6.items():
    print(face, probability)

output

1 0.16666666666666666
2 0.16666666666666666
3 0.16666666666666666
4 0.16666666666666666
5 0.16666666666666666
6 0.16666666666666666

This allows you to use a plotting library to visualize the probabilities.