core

The Nim Game core

This main class implements the init and maintenance of heaps, movements of coins, records the statuses and calculates decisions.

class core.Nim(error_rate: typedefs.ErrorRate_T = 0, heapcount_range: typedefs.HeapCoinRange_T = (3, 15), coincount_range: typedefs.HeapCoinRange_T = (1, 20), misere: bool = True)

The main class to implement the Nim game

This class publishes the following methods. See also the calculation methods from the mixin in calculations.

Instance Methods:

setup_heaps()

This creates and initiates the heaps attribute.

set_start()

It sets which party is to start the game.

do_move()

It makes a move, and swaps the activeplayer.

get_heapstatus()

You can get the heaps status (coins in heaps) in a string.

game_end()

It tells you whether the game has ended.

Instance Attributes:

heaps

This list contans the number of coins in the heaps. This is initiated in setup_heaps() and the actual status can be retrieved with get_heapstatus().

activeplayer

This str is either the “Computer” or “Player” during the game. Or “start” in the very beginning when starting player has not been selected yet.

Parameters

• error_rate –

  The rate percentage of mistakes the Computer is to make. By deafult it is 0%, i.e. the computer never makes mistakes, and the Player has no chance to win (unless the Player decides who to start and never makes mistakes). If it was set to the extreme 100%, the Computer would always intentionally make wrong moves, practically making all attempts to lose. NB, if the Player does the same, the Computer may still win.

  For testing, when moves of both parties are calculated by the program, the error rate of both parties can be set with the typedefs.ErrorRate. This can be used to create staistics of games played by differently skilled players. NB, still, the 1^st party will be reported in the results as Computer, and the 2^nd as Player, just to name them.

• heapcount_range – The min and max number of heaps to be set up. Less than 3 heaps makes little sense, more than 15 is a bit of an overkill. So, the default is (3-15), but it can be set otherwise. NB, since the heaps are displayed with letters (A-Z), the heap number is limited to 26.

• coincount_range – The min and max number of coins to be set up in a heap. Less than 1 coin makes no sense, more than 20 is a bit of an overkill. So, the default is (1-20). NB, since the heap contents are displayed in max 2 digits, the coin number is limited to 99.

• misere – Whether it is the “misère” version of the game.

do_move(move: Move) → None

Remove given number of coins from a given heap

Before doing the coin removal, check for illegal moves and report issues.

After the given number of coins have been removed from a given heap, swap the active player.

Parameters

move – The designation of the heap and the number of coins to be removed from that heap. Heap designation can be a letter or a number (starting from 0).

game_end() → bool

Identify whether the game ended, i.e. all heaps are empty

Simply add up all the coins and return the boolean negate of the sum.

Returns

The flag to indicate game end.

get_heapstatus() → str

Get the heap status in a formatted string

Returns

The number of coins per heap. Also header at the start.

set_error_rate(error_rate: typedefs.ErrorRate_T) → None

Set the required error rate, even during a game

Parameters

error_rate – The error rate to be set from the next move on

set_start(myturn: typedefs.MyTurn_T = 'a') → None

Set the starting party

User can explicitly set which party is to start. This makes sense if this decision is made based on the starting heap status.

You can also ask for random selection.

By default the computer makes the decision using 2 factors. First it figures out whether the heap status is beneficial for starting, i.e. it is a winning status. Then it checks the required error rate and it intentionally makes a wrong decision with higher likelihood if the error_rate is higher.

The myturn argument is converted to a boolean, if it arrives as a str, see the parameter description below. No issues with “overwriting” it, because str is unmutable, i.e. the default remains the ‘a’ for subsequent calls and also the outer variable, where the argument comes from, remains unaffected.

The (converted) myturn value is then used in a bool context. If it is of any other type, it is still interpreted as a bool. E.g. an empty list will act like a False, i.e. Computer will start.

The attribute nextturn is a __next__() of itertools.cycle. Calling “nextturn()” infinitely yields the swapped player names. This attribute is used in do_move() to change the active player.

Parameters

myturn –

The logical value from the Player’s point of view.

• ’a’ (by default): the Computer figures out which party is to start the game, based on the heap counts and the required error rate

• truthy or ‘p’: Player

• falsy or ‘c’: Computer

• ’r’: random

setup_heaps(heapcounts: Optional[list] = None) → None

Initial setup of heaps of coins

If heapcounts is provided the number of heaps and the number of coins in each heap is checked whether they fall into the set valid range. Exception is raised if not.

Parameters

heapcounts – The list elements state the number of coins in each heap. If no list is provided, a random number of heaps are created with a random number of coins.