dice

README

dice

Package dice provides functions for simulating and analyzing dice probabilities.

Monte Carlo

For Monte Carlo simulations, i.e. Rolling dice a large number of times to get the approximate result, you can use any of: Roll(Dice), Dice.Roll() or Die.Roll().

Die.Roll rolls a single die, Roll(Dice) and Dice.Roll() roll multiple dice.

Keep in mind that programs will always return the same dice rolls unless you provide a different seed every time, (see "random.Seed").

Enumeration

If you wish to determine exact results of a die roll, you can enumerate a roll table by calling NewTable(DiceToRoll).

TODO: Add Table.Verify()

Installation

$ go get -u github.com/sbrow/prob/dice

Documentation

Overview

Package dice provides functions for simulating and analyzing dice probabilities.

Monte Carlo

For Monte Carlo simulations, i.e. Rolling dice a large number of times to get the approximate result, you can use any of: Roll(Dice), Dice.Roll() or Die.Roll().

Die.Roll rolls a single die, Roll(Dice) and Dice.Roll() roll multiple dice.

Keep in mind that programs will always return the same dice rolls unless you provide a different seed every time, (see "random.Seed").

Enumeration

If you wish to determine exact results of a die roll, you can enumerate a roll table by calling NewTable(DiceToRoll).

TODO: Add Table.Verify()

Example (Enumeration)

package main

import (
	"fmt"

	"github.com/sbrow/prob/dice"
)

func main() {
	d := dice.New(dice.D4(), dice.D4())
	table, err := dice.NewTable(d)
	if err != nil {
		panic(err)
	}
	fmt.Println(table.Data)

}

Output:

[[1+1] [1+2] [1+3] [1+4] [2+1] [2+2] [2+3] [2+4] [3+1] [3+2] [3+3] [3+4] [4+1] [4+2] [4+3] [4+4]]

Example (MonteCarlo)

main()

package main

import (
	"fmt"

	"github.com/sbrow/prob/dice"
)

// Run a simulation n times.
func MonteCarlo(n int) map[string]int {
	// The number of times each side was rolled
	counts := map[string]int{}
	die := dice.D6()
	var result string
	for i := 0; i < n; i++ {
		result = die.Roll()
		counts[result]++
	}
	return counts
}

// main()
func main() {
	// Roll a die 10,000 times.
	results := MonteCarlo(10000)
	fmt.Println("1:", results["1"])
	fmt.Println("2:", results["2"])
	fmt.Println("3:", results["3"])
	fmt.Println("4:", results["4"])
	fmt.Println("5:", results["5"])
	fmt.Println("6:", results["6"])

}

Output:

1: 1678
2: 1631
3: 1666
4: 1667
5: 1680
6: 1678

Index

• Variables
• func DeleteData() error
• func Roll(dice ...Die) []string
• type Dice
  • func New(die ...Die) Dice
  • func (d Dice) Len() int
  • func (d Dice) Less(i, j int) bool
  • func (d Dice) Name() string
  • func (d Dice) Roll() []string
  • func (d Dice) Sort()
  • func (d Dice) Swap(i, j int)
• type Die
  • func D10() Die
  • func D12() Die
  • func D20() Die
  • func D4() Die
  • func D6() Die
  • func D8() Die
  • func NewDie(name string, sides ...string) *Die
  • func (d Die) Roll() string
• type Table
  • func NewTable(dice Dice) (*Table, error)
  • func (t *Table) Name() string

Examples

• Package (Enumeration)
• Package (MonteCarlo)
• Dice.Name
• Roll

Variables

var DataDir = filepath.Join(os.Getenv("GOPATH"), "data")

DataDir is the default directory to store Tables in.

var Delim = "+"

Delim specifies the delimiter to use for dice in a roll.

Functions

func DeleteData

func DeleteData() error

DeleteData deletes the contents of DataDir.

func Roll

func Roll(dice ...Die) []string

Roll returns a random side from each of the given dice.

Example

fmt.Println(Roll(D6(), D6()))

Output:

[2 1]

Types

type Dice

type Dice []Die

Dice is a collection of 0 or more Die structs.

func New

func New(die ...Die) Dice

New returns a new set of Dice.

func (Dice) Len

func (d Dice) Len() int

Len returns the number of Dice in the set.

func (Dice) Less

func (d Dice) Less(i, j int) bool

Less returns whether the Die at i should be sorted before the Die at j.

func (Dice) Name

func (d Dice) Name() string

Name returns a formatted concatenation of the names of each die. Names of unlike dice are appended to the name, whereas names of like dice are compressed using standard dice notation- i.e. 3, six-sided dice = "3d6".

Names are sorted in descending order, first by quantity of each dice type, then by the number of sides each dice type has.

FIXME: Dice with <10 sides are being sorted lower than dice with 10+ sides.

Example

dice := Dice{D8(), D4(), D10(), D6(), D4(), D6()}
fmt.Print(dice.Name())

Output:

2d6+2d4+1d8+1d10

func (Dice) Roll

func (d Dice) Roll() []string

Roll returns a random side from each Die in the Dice.

func (Dice) Sort

func (d Dice) Sort()

Sort sorts the dice in descending order of number of sides.

func (Dice) Swap

func (d Dice) Swap(i, j int)

Swap swaps the elements with indexes i and j.

type Die

type Die struct {
	Name  string
	Sides []string
}

Die represents a physical n-sided die.

func D10

func D10() Die

D10 returns a standard, ten-sided die.

func D12

func D12() Die

D12 returns a standard, twelve-sided die.

func D20

func D20() Die

D20 returns a standard, twelve-sided die.

func D4

func D4() Die

D4 returns a standard, four-sided die.

func D6

func D6() Die

D6 returns a standard, six-sided die.

func D8

func D8() Die

D8 returns a standard, eight-sided die.

func NewDie

func NewDie(name string, sides ...string) *Die

NewDie returns a new Die type with the given name and sides.

func (Die) Roll

func (d Die) Roll() string

Roll returns a side of the Die at random.

type Table

type Table struct {
	Dice Dice       // The Dice in the table.
	Data [][]string // The possibility space of the dice when each is rolled once.
}

Table holds a roll table for a set of dice.

func NewTable

func NewTable(dice Dice) (*Table, error)

NewTable returns a dice table from the given dice.

If the table already exists in DataDir, it is loaded.

If the table does not already exist in DataDir, NewTable looks for parent tables until it finds one or hits rock bottom, then generates the remaining data.

For example, if we call with an empty DataDir:

OneD6 := NewTable(D6())

The table will be generated from scratch. If we then call:

ThreeD6 := NewTable(D6(), D6(), D6())

NewTable will start by loading the saved version of OneD6 from disk, and then generate the other two Dice.

func (*Table) Name

func (t *Table) Name() string

Name returns the name of the table, which is determined by its Dice.