Documentation for the package, Game analysis (#21)

* Update docs for the package.

* Add better descriptions to READMEs with examples, add notebook exploring game properties.

README.md

@@ -1,7 +1,16 @@
 # Mathematico
 
-A classic game, for unlimited number of players. Each player keeps track of their own board
-and after 25 random choices of numbers, the score is calculated for each player and the highest score wins.
+A classic game, for unlimited number of players. Each player keeps track of
+their own board and after 25 random choices of numbers, the score is calculated
+for each player and the highest score wins.
+
+> **note**: You can try it!
+    <ul>
+        <li>[on Google Colab](https://colab.research.google.com/drive/1HuVb5_FK9T3tkA8OjjQ40LhsSiQ1wlXm?usp=sharing) this is the version that uses rules as descibed in this README
+        </li>
+        <li>[other implementation](https://yetty.github.io/Matematico/) with the description in Czech language
+        </li>
+    </ul>
 
 
 ## Rules of the Game
@@ -14,24 +23,24 @@ resulting scores are computed (see below) for each board, and the player with th
 ### Scoring System
 
 For each line, row and two longest diagonals, the points are computed based on the following table
-and are summed across all rows, columns and diagonals. In addition, if the score in a diagonal 
-is non-zero, the player is awarded *10 bonus points* for each such diagonal. 
+and are summed across all rows, columns and diagonals. In addition, if the score in a diagonal
+is non-zero, the player is awarded *10 bonus points* for each such diagonal.
 
 *The numbers in the rows, columns and diagonals can be in __ANY__ order.*
 
- 
-|             Rule                 |     Example    | Points 
-|--------------------------------- | -------------- | ------- 
-|    One pair                      |  1  2  3  4  1 |   10 
-|    Two pairs                     |  1  2  2  3  1 |   20 
-|    Three of a kind               |  5  6  7  7  7 |   40 
-|    Full House                    |  1  1  2  2  2 |   80 
-|    Four of a kind (not number 1) |  1  2  2  2  2 |  160 
-|    Four ones                     |  1  1  5  1  1 |  200 
-|    Straight                      |  5  7  9  8  6 |   50 
-|    Three 1s and two 13s          |  1 13  1 13  1 |  100 
+
+|             Rule                 |     Example    | Points
+|--------------------------------- | -------------- | -------
+|    One pair                      |  1  2  3  4  1 |   10
+|    Two pairs                     |  1  2  2  3  1 |   20
+|    Three of a kind               |  5  6  7  7  7 |   40
+|    Full House                    |  1  1  2  2  2 |   80
+|    Four of a kind (not number 1) |  1  2  2  2  2 |  160
+|    Four ones                     |  1  1  5  1  1 |  200
+|    Straight                      |  5  7  9  8  6 |   50
+|    Three 1s and two 13s          |  1 13  1 13  1 |  100
 |    Numbers 1, 10, 11, 12, 13     | 12 11 13  1 10 |  150
-               
+
 
 For each row, column and diagonal, only the highest score is applied, i.e. it is forbidden
 to combine two scoring rules for one line.

game/README.md

@@ -1,37 +1,104 @@
 # Mathematico
 
-A classic game, for unlimited number of players. Each player keeps track of their own board
-and after 25 random choices of numbers, the score is calculated for each player and the highest score wins.
+This package represents a game Mathematico as described [here](../README.md).
 
 
-## Rules of the Game
+## Installation
 
-The game of Mathematico is played on a *5x5 grid*. In each round, a card with a number is drawn
-from the deck consisting of cards with numbers in range 1-13, with 4 copies of each, and players
-are obliged to fill the number in one of the empty cells on their board. When the boards are full,
-resulting scores are computed (see below) for each board, and the player with the highest score wins.
+The package is not published yet, therefore in order to install it, you
+need to install the package from the github, using the following commands:
 
-### Scoring System
+> **Warning:**  This code uses folder `./tmp/` as a temporary directory to
+download to and extract the package from - this directory gets deleted.
 
-For each line, row and two longest diagonals, the points are computed based on the following table
-and are summed across all rows, columns and diagonals. In addition, if the score in a diagonal 
-is non-zero, the player is awarded *10 bonus points* for each such diagonal. 
+```bash
+git clone --quiet https://github.com/balgot/mathematico.git tmp || git -C tmp pull
+cd tmp/game && python -m pip install --quiet .
+rm -rf tmp
+```
 
-*The numbers in the rows, columns and diagonals can be in __ANY__ order.*
 
-
-|             Rule                 |     Example    | Points 
-|--------------------------------- | -------------- | ------- 
-|    One pair                      |  1  2  3  4  1 |   10 
-|    Two pairs                     |  1  2  2  3  1 |   20 
-|    Three of a kind               |  5  6  7  7  7 |   40 
-|    Full House                    |  1  1  2  2  2 |   80 
-|    Four of a kind (not number 1) |  1  2  2  2  2 |  160 
-|    Four ones                     |  1  1  5  1  1 |  200 
-|    Straight                      |  5  7  9  8  6 |   50 
-|    Three 1s and two 13s          |  1 13  1 13  1 |  100 
-|    Numbers 1, 10, 11, 12, 13     | 12 11 13  1 10 |  150
-
+## Usage
 
-For each row, column and diagonal, only the highest score is applied, i.e. it is forbidden
-to combine two scoring rules for one line.
+In order to play the game, you need to supply a `Player` instance to the
+`Mathematico` object, e.g.:
+
+```python
+from mathematico import Mathematico, RandomPlayer
+
+game = Mathematico()
+player1 = RandomPlayer()
+game.add_player(player1)
+game.add_player(RandomPlayer())
+game.play()
+```
+
+With the possible output representing achieved score for each player:
+
+```
+[90, 70]
+```
+
+To see the resulting game board, use:
+
+```python
+print(player1.board)
+```
+
+```
++--+--+--+--+--+
+| 2|13| 3| 8| 7|
++--+--+--+--+--+
+|11| 4| 1| 2| 4|
++--+--+--+--+--+
+| 3|10| 4| 4| 6|
++--+--+--+--+--+
+| 5| 2| 1|12| 3|
++--+--+--+--+--+
+|13|12|11|12| 8|
++--+--+--+--+--+
+```
+
+### Arena
+
+The class `Mathematico` plays only one game, to simulate multiple rounds,
+use the `Arena`:
+
+```python
+from mathematico import Arena
+
+arena = Arena()
+arena.add_player(player1, verbose=False)
+arena.run(rounds=3)
+```
+
+which returns the results in each round, e.g.:
+
+```
+[[80, 60, 160]]
+```
+
+
+
+### Players
+
+The package contains implementation of 3 player classes:
+
+* `HumanPlayer` - that uses console input/ouput to interact and accept the
+position of the next move
+* `RandomPlayer` - this player plays random valid move
+* `SimulationPlayer` - this player runs a number of simulations and finds the
+move that leads to the largest expected payoff
+
+
+#### Custom Player
+
+To implement a custom player, it should conform to the interface of abstract
+class `Player` and implement the following methods:
+
+* `move(card: int) -> None` - place the card on your board, `self.board` which
+is inherited from `Player` base class
+    > _note_: this allows for cheating by not placing the numbers immediately, but it is the desired behaviour
+
+* `reset() -> None` - reset the player to the initial state before the next
+game can start