Monte Carlo Die Simulator

Author: Lucas Andersen

Project: Monte Carlo Die Simulator

This module will implement a simple Monte Carlo simulator using a set of three related classes - a Die class, a Game class, and an Analyzer class. Note that Game objects are initialized with a Die object, and Analyzer objects are initialized with a Game object.

To begin using the module, clone the repository and install the package locally, like so:

git clone 
git @github.com:leandersen/Die_Game.git
cd montecarlo
pip install .

---

Synopsis

Import and use the code to create dice, play a game, and analyze a game, like so:

import numpy as np
from montecarlo.montecarlo import Die, Game, Analyzer

# Create an array of faces
faces = np.array([1, 2, 3, 4, 5, 6])

# Create dice
die_1 = Die(faces)
die_2 = Die(faces)

# Change the weight of a die
die_1.change_weight(face_value = 1, new_weight = 3)

# Roll a die
die_1.roll_die(n_rolls = 10)

# Show properties of die
die_1.show_die()

# Play a game
game = Game([die_1, die_2])
game.play_game(rolls = 15)

# Show the results
game.show_results(form = 'narrow')

#Analyze a game
analyzer = Analyzer(game)
analyzer.jackpot()
analyzer.face_count()
analyzer.combo_count()
analyzer.perm_count()

---

API Description:

Die Class

Die object that can be rolled and modified. Initializes a die with specified faces and equal weights. Allows rolling and weight modification.

__init__(faces)

Initializes the Die object

• Parameters
  • faces: numpy.ndarray
    • Array of unique face values, which may be strings or numbers.

change_weight(face_value, new_weight)

Changes the weight of a single face of a die.

• Parameters
  • face_value: str/int/float
    • The face value to change.
  • new_weight: int/float
    • New weight for the specified face.

roll_die(n_rolls = 1)

Rolls the die a specified number of times.

• Parameters

  • n_rolls: int
    • Number of rolls to perform (defaults to 1).

• Return

  • results: list
    • A list of outcomes from rolling the die.

show_die()

Returns die faces and weights in a DataFrame.

• Return
  • Die info: pandas.DataFrame
    • DataFrame with face values as index and weights as column.

Game Class

Game of dice rolls using Die objects. Rolls multiple similar dice a specified number of times and stores results.

__init__(dice)

Initializes the Game object.

• Parameters
  • dice: list
    • List of die objects with identical faces.

play_game(rolls = 1)

Roll all dice a specified number of times.

• Parameters
  • rolls: int
    • Number of rolls for each die (defaults to 1).

show_results(form = 'wide')

Displays game results.

• Parameters

  • form: str
    • The output format can be either 'wide' or 'narrow' (defaults to 'wide').

• Return

  • Game results: pandas.DataFrame
    • A DataFrame of game results.

Analyzer Class

Analyzer for game results. Analyzes game statistics like jackpots, face counts per roll, combinations, and permutations.

__init__(game)

Initializes the Analyzer object.

• Parameters
  • game: Game
    • A previously played Game object.

jackpot()

Counts number of jackpots. A jackpot is a roll where all dice show the same face.

• Return
  • jackpot: int
    • Number of jackpots.

face_count()

Counts face frequencies per roll.

• Return
  • face_counts: pandas.DataFrame
    • DataFrame of face counts for each roll.

combo_count(sort = False)

Counts unique combinations of outcomes. Combinations are order-independent.

• Parameters

  • sort: bool
    • If True, the index is sorted (defaults to False).

• Return

  • combo_counts: pandas.DataFrame
    • DataFrame with MultiIndex of combinations and their counts.

perm_count(sort = False)

Counts unique permutations of outcomes. Permutations are order-dependent.

• Parameters

  • sort: bool
    • If True, the index is sorted (defaults to False).

• Return

  • perm_counts: pandas.DataFrame
    • DataFrame with MultiIndex of permutations and their counts