API Reference

This section documents the public Python API provided by the gnubg-nn-pypi package — the GNUBG neural network evaluation library (position analysis, cube decisions, rollouts), not the full GNU Backgammon application. It includes functions for evaluating positions, loading neural nets, and accessing internal neural net state.

gnubg.bearoff_id_2_pos(id) -> Tuple[int, int, int, int, int, int]

bearoff_id_2_pos(id)

Converts a bearoff ID into a 6-point position tuple using the internal GNU Backgammon bearoff database.

Parameters:: id (int or Sequence[int]) – Either an integer ID or a 6-element sequence representing the bearoff state.
Returns:: A tuple of six integers representing the number of checkers on each of the first six points.

The returned tuple maps the bearoff configuration for a single player. This is useful for reconstructing endgame positions or feeding inputs into evaluation functions that rely on bearoff-specific features.

Raises:: TypeError – If the input is not a valid integer or 6-element sequence.

Example:

>>> gnubg.bearoff_id_2_pos(42)
(0, 1, 0, 2, 3, 9)

gnubg.bearoff_probabilities(id) -> Tuple[float, …]

bearoff_probabilities(id)

Returns the probability distribution of winning in n moves from a given bearoff position.

Parameters:: id (int or Sequence[int]) – Either a bearoff ID integer or a 6-element tuple representing a bearoff state.
Returns:: A tuple of floats representing the probabilities of bearing off in exactly 1, 2, …, N moves.

The returned tuple may be padded with leading zeros if the bearoff record starts later than move 1. The actual data is retrieved from the compiled GNU Backgammon bearoff database.

Raises:: TypeError – If the input is not a valid bearoff ID or 6-tuple.

Example:

>>> gnubg.bearoff_probabilities(42)
(0.0, 0.0, 0.15, 0.33, 0.52)

In this example, the probabilities of bearing off in 3, 4, and 5 moves are 15%, 33%, and 52%, respectively.

gnubg.best_move(pos, dice1, dice2, n=0, s=’O’, b=False, r=False, list=False, reduced=False)

best_move(pos, dice1, dice2, n=0, s='O', b=False, r=False, list=False, reduced=False)

Calculates the best move(s) for a given board state and dice roll using ply-based neural network evaluation.

Parameters:

pos (list[list[int]]) – A 2x25 board array representing the full game state for both players.
dice1 (int) – First die roll (1–6).
dice2 (int) – Second die roll (1–6).
n (int) – Evaluation depth (ply). Default is 0-ply.
s (str) – Which side to move (‘X’ or ‘O’). Default is ‘O’.
b (bool) – Return the new board position after move if True.
r (bool) – Return resign suggestion value (0/1/2) if True.
list (bool) – Include a full list of alternate legal moves and their evaluations.
reduced (bool) – Use reduced evaluation (faster, less accurate).

Returns:

If b, r, or list are all False, returns a tuple of move steps: [(from, to), (from, to), ...]

If any of b, r, or list is True, returns a tuple: (best_move, board_str?, resign_code?, move_list?) depending on flags.

Raises:

ValueError – On invalid dice, ply depth, or side specification.

Examples

>>> gnubg.best_move(pos, 2, 1)
[(6, 5), (13, 11)]

>>> gnubg.best_move(pos, 6, 6, n=2, b=True, r=True, list=True)
(
   [(6, 12), (8, 14), (13, 19), (1, 7)],
   'board string after move...',
   0,
   [
      ('position_id', (13, 19, 6, 12, 1, 7, 8, 14), (0.90, 0.35, 0.12, 0.01, 0.00), 0.031),
      ...
   ]
)

The full move list includes all reasonable alternatives with their evaluation probabilities and match scores.

gnubg.board_from_position_id(pos_id) -> List[List[int]]

board_from_position_id(pos_id)

Converts a GNU Backgammon Position ID string into a 2x25 board matrix representing both players’ checkers.

Parameters:: pos_id (str) – A 14-character GNUBG Position ID string (e.g., “4HPwATDgc/ABMA”).
Returns:: A nested list of integers in the shape [2][25]. The first sublist represents the X side, the second the O side. Each list contains 25 elements: - Points 1–24: checker counts - Index 0: off or bar position (varies by GNUBG convention)
Raises:: ValueError – If the input string is malformed or of the wrong length.

Example

>>> gnubg.board_from_position_id("4HPwATDgc/ABMA")
[
   [0, 0, 0, 2, 0, 0, ..., 5],  # X's checkers
   [0, 0, 0, 0, 3, 2, ..., 0]   # O's checkers
]

This output represents the internal format used by GNUBG to evaluate and simulate moves on the board.

gnubg.board_from_position_key(key) -> List[List[int]]

board_from_position_key(key)

Converts a GNUBG board key string (e.g. from a move list or match log) into a 2x25 matrix representing both players’ checkers.

Parameters:: key (str) – A GNUBG position key string (e.g., “X0uASbDgc/ABMA:MAAAABAAIAAA”).
Returns:: A nested list [2][25] representing the board for the X and O sides.

Each sublist contains: - Index 1–24: points on the board - Index 0: special off/bar/checker area (GNUBG convention)

Raises:: ValueError – If the position key is invalid or not parseable.

Example

>>> gnubg.board_from_position_key("X0uASbDgc/ABMA:MAAAABAAIAAA")
[
   [0, 0, 0, 2, 0, 0, ..., 5],  # X's side
   [0, 0, 0, 0, 3, 2, ..., 0]   # O's side
]

This is a lower-level equivalent of board_from_position_id, used when working with full match position keys.

Position Class Constants

These integer constants represent how a backgammon position is classified by GNUBG’s internal logic. You can use them with classify_position() or interpret output from analysis modules.

c_bearoff

Indicates a bearoff position where one or both players are removing checkers from their home board.

Value:: integer (e.g. 0 or 4 depending on GNUBG compile-time settings)

c_race

A position where no checkers are in contact and both players are racing to bear off.

Value:: integer constant

c_crashed: A position where one side is blocked and checker distribution is lopsided (e.g. trapped behind a prime).

c_contact: Default classification for general positions with live contact between players’ checkers.

c_over: The game is over. No moves are available.

c_backcontain: (Optional) A special class for backgame or containment scenarios, used if GNUBG is compiled with CONTAINMENT_CODE.

Example

cls = gnubg.classify_position(board)
if cls == gnubg.c_bearoff:
    print("Bearoff phase")
elif cls == gnubg.c_contact:
    print("Still in contact")

gnubg.classify(board) -> int

classify(board)

Classifies a board position into one of GNUBG’s internal position types such as contact, race, or bearoff.

Parameters:

board (list[list[int]]) – A 2x25 list of integers representing the checker layout for both players.

Returns:

An integer constant corresponding to one of:

gnubg.c_contact
gnubg.c_race
gnubg.c_crashed
gnubg.c_bearoff
gnubg.c_over
gnubg.c_backcontain (if compiled with support)

Raises:

ValueError – If the board input is not a valid 2x25 structure.

Example

>>> cls = gnubg.classify(board)
>>> if cls == gnubg.c_race:
...     print("This is a race position.")

gnubg.cubeful_rollout(pos, ngames=576, side=’X’, ply=0) -> Tuple[float, …]

cubeful_rollout(pos, ngames=576, side='X', ply=0)

Performs a cubeful rollout on a given backgammon position using GNUBG’s rollout engine.

This function simulates a large number of games from the specified position using lookahead (ply) and cube handling, returning statistical estimates such as win/gammon/backgammon rates.

Parameters:

pos (object) – A position object or board suitable for GNUBG’s AnalyzeBoard (e.g. 2x25 board or position ID).
ngames (int) – Number of rollout simulations to run (default: 576).
side (str) – The player on turn, either ‘X’ or ‘O’.
ply (int) – The number of plies (0, 1, or 2) to use in lookahead during each rollout simulation.

Returns:

A tuple of 13 floats with rollout statistics:

win percentage
win gammon %
win backgammon %
lose %
lose gammon %
lose backgammon %
equity
equity (cubeful)
standard error
confidence interval
cube decisions
take point
gammon value

Raises:

ValueError – If the side is not ‘X’ or ‘O’, or if the board cannot be parsed.

Example

>>> gnubg.cubeful_rollout(board, ngames=1024, side='O', ply=1)
(0.49, 0.21, 0.02, 0.51, 0.18, 0.01, -0.081, -0.079, 0.0031, ..., 0.26)

These results can be used to evaluate cube decisions, risk/reward, and overall strategy in match play or money games.

equities.value(x_away, o_away) -> float

equities.value(x_away, o_away)

Returns the match equity for the given score in a match using the currently loaded Match Equity Table (MET).

Parameters:

x_away (int) – Number of points player X needs to win the match (0–25).
o_away (int) – Number of points player O needs to win the match (0–25).

Returns:

A float representing the match-winning chance (MWC) for player X at the specified score.

This function queries the preloaded MET and returns the normalized equity for the match situation. It’s primarily useful in match play for cube decision logic and overall strategic evaluation.

Raises:: ValueError – If either score is outside the 0–25 range.

Example

>>> equities.value(3, 2)
0.638

In this example, if X is 3-away and O is 2-away, X has a 63.8% chance of winning the match.

gnubg.key_of_board(board) -> str

key_of_board(board)

Converts a 2×25 board array into a GNUBG position key string (used for position lookup, storage, and export).

Parameters:: board (list[list[int]]) – A 2×25 nested list representing the full game state for both players.
Returns:: A 20-character GNUBG position key string (uppercase A–Z).

This function performs the reverse of board_from_position_key(). The key string encodes the board state for fast comparison, storage, and referencing in GNUBG tools and formats (like match logs and move records).

Raises:: ValueError – If the input is not a valid 2×25 board.

Example

>>> gnubg.key_of_board([
...   [0, 0, 0, 2, ..., 5],
...   [0, 0, 0, 0, ..., 0]
... ])
'X0uASbDgc/ABMA:MAAAABAAIAAA'

This output can be used with GNUBG’s board_from_position_key to reconstruct the board from its key.

gnubg.moves(board, die1, die2, verbose=False) -> Tuple[…]

moves(board, die1, die2, verbose=False)

Generates all legal move options from a given board state and dice roll.

Parameters:

board (list[list[int]]) – A 2×25 nested list representing the full board state for both players.
die1 (int) – First die roll (1–6).
die2 (int) – Second die roll (1–6).
verbose (bool) – If True, returns each move as a tuple of position key and move steps. If False, returns just the position keys.

Returns:

A tuple of legal move options. The format depends on verbose: - If verbose=False (default): (key1, key2, ...)

where each key is a 20-character GNUBG position key string.

If verbose=True: ((key1, [(from, to), ...]), ...)

Raises:

ValueError – If the board or dice are invalid.

Example

>>> gnubg.moves(board, 3, 1)
('X1uASbDgc/ACMA:MAAAABAAIAAA', 'X2uASbDgc/ABMA:MAAAABAAIAAA', ...)

>>> gnubg.moves(board, 6, 4, verbose=True)
(
  ('X1uASbDgc/ABMA:MAAAABAAIAAA', [(13, 19), (8, 14)]),
  ('X2uASbDgc/ACMA:MAAAABAAIAAA', [(6, 12), (13, 19)]),
  ...
)

This is the core legal move generator used internally by GNUBG before move filtering or evaluation.

gnubg.one_checker_race(pips) -> Optional[Tuple[float, float]]

one_checker_race(pips)

Estimates the win probability and standard deviation for a simple one-checker bearoff race using GNUBG’s analytical model.

Parameters:: pips (int) – The number of pips (points) remaining to bear off a single checker.
Returns:: A tuple (equity, std_dev) of floats if calculable, or None if the pip count is unsupported.

This function uses GNUBG’s built-in analytical model ocr() to evaluate highly simplified race endgames, typically used in special training positions or theoretical studies.

Raises:: ValueError – If the pip count is not an integer or out of range.

Example

>>> gnubg.one_checker_race(10)
(0.273, 0.065)

This indicates a 27.3% chance of winning from a 10-pip position with the standard deviation of outcomes at ~0.065.

Ply Evaluation Strategy Constants

These constants are used to identify evaluation modes or neural net paths selected during multi-ply rollout, pruning, or classification strategies in GNUBG.

p_0plus1: Hybrid evaluation: 0-ply followed by 1-ply filtering (1+½ strategy).

p_1sbear: 1-ply evaluation with bearoff filtering.

p_1srace: 1-ply evaluation in race-only scenarios.

p_bearoff: Position falls into exact bearoff category (database-driven evaluation).

p_osr: One-sided race evaluation (special case of bearoff or non-contact).

p_prune: Evaluation strategy using pruned neural networks for speed.

p_race: Standard race-only neural network evaluation.

These are typically returned internally by rollout routines or may be useful for logging/debugging advanced evaluations.

Example

eval_type = gnubg.p_1srace
if rollout_result_type == gnubg.p_prune:
    print("Used pruned network evaluation")

gnubg.position_id(board) -> str

position_id(board)

Converts a 2×25 backgammon board array into a 14-character GNUBG Position ID string.

Parameters:: board (list[list[int]]) – A nested list representing the full board state for both players.
Returns:: A 14-character Position ID string (base64 encoded), suitable for evaluation, storage, or UI display.

This is the inverse of board_from_position_id(). The Position ID is a compact string uniquely representing a board state.

Raises:: ValueError – If the input is not a valid 2×25 list.

Example

>>> gnubg.position_id([
...   [0, 0, 0, 2, ..., 5],
...   [0, 0, 0, 0, ..., 0]
... ])
'4HPwATDgc/ABMA'

This Position ID can be passed to GNUBG-compatible tools or used in analysis pipelines.

gnubg.probabilities(board, ply, nr=1296) -> Tuple[float, float, float, float, float]

probabilities(board, ply, nr=1296)

Calculates win probabilities and related equity values for a given board using the specified evaluation strategy.

Parameters:

board (list[list[int]]) – A 2×25 list representing the backgammon board state for both players.
ply (int) – Evaluation mode, must be one of: - gnubg.p_osr - gnubg.p_bearoff - gnubg.p_prune - gnubg.p_1sbear - gnubg.p_race - gnubg.p_0plus1 - gnubg.p_1srace
nr (int, optional) – Number of rollouts (used for OSR race mode). Default is 1296.

Returns:

A tuple of five floats: (win, win_gammon, win_backgammon, lose_gammon, lose_backgammon)

These values represent the outcome probabilities under the given evaluation logic.

Raises:

RuntimeError – If the board is not a race in p_osr mode or the OS bearoff DB is unavailable.
ValueError – On invalid board structure.

Example

>>> gnubg.probabilities(board, gnubg.p_prune)
(0.637, 0.182, 0.042, 0.103, 0.036)

These outputs help guide move selection, cube decisions, or match strategy depending on the game’s phase.

gnubg.pub_best_move(board, die1, die2) -> List[int]

pub_best_move(board, die1, die2)

Returns the best move from a given board and dice roll using GNUBG’s public evaluation function (non-ply-based, non-neural).

Parameters:

board (list[list[int]]) – A 2×25 board array representing the full game state.
die1 (int) – First die roll (1–6).
die2 (int) – Second die roll (1–6).

Returns:

A flat list of integers representing the move: [from1, to1, from2, to2, ...]

Each index is 1-based and refers to points on the backgammon board. The number of pairs returned depends on the number of checkers moved.

Raises:

ValueError – If the board is not valid.
RuntimeError – If no valid move is found.

Example

>>> gnubg.pub_best_move(board, 6, 1)
[13, 19, 8, 9]

This represents two moves: checker from 13→19 and from 8→9.

gnubg.pub_eval_score(board) -> float

pub_eval_score(board)

Computes a simple evaluation score for the current position using GNUBG’s public (non-neural) evaluation model.

This is a fast heuristic score used in early filtering, testing, or simpler bots.

Parameters:: board (list[list[int]]) – A 2×25 board array representing the full backgammon position.
Returns:: A float evaluation score. Positive values favor player X; negative values favor player O.
Raises:: ValueError – If the input is not a valid 2×25 board.

Example

>>> gnubg.pub_eval_score(board)
-0.172

This indicates that player O is slightly favored in the current position.

Rollout Type Constants

These constants define how GNUBG classifies or initiates rollout evaluations for a given position.

ro_auto: Automatically detect the appropriate rollout type (e.g., contact, race, or bearoff) based on position classification.

ro_race: Force a race-type rollout, typically used when both players are in a pure bear-off race and contact is no longer possible.

ro_bearoff: Use precomputed bearoff databases during rollout; only valid if both players are in known bearoff configurations.

ro_over: Indicates that the game is over (no rollout needed or possible).

Example

rollout_type = gnubg.ro_auto
if rollout_type == gnubg.ro_race:
    print("Running race-specific rollout")

gnubg.roll() -> Tuple[int, int]

roll()

Simulates a roll of two six-sided dice using GNUBG’s internal RNG and rules.

Returns:: A tuple of two integers in the range 1–6: (die1, die2)

This function can be used for simulating games, testing move generators, or interactive play scenarios.

Example

>>> gnubg.roll()
(3, 5)

gnubg.rollout(pos, ngames=1296, n=0, level=gnubg.ro_auto, nt=500, std=False) -> Union[Tuple[float, …], Tuple[Tuple[float, …], Tuple[float, …]]]

rollout(pos, ngames=1296, n=0, level=gnubg.ro_auto, nt=500, std=False)

Performs a cubeless rollout simulation of a backgammon position using GNUBG’s AnalyzeBoard logic.

This simulates many games (default 1296) from the specified position, using a specified ply depth and rollout mode.

Parameters:

pos (object) – A board object (2×25 list or structured input accepted by GNUBG).
ngames (int) – Number of games to simulate (default 1296).
n (int) – Number of plies to evaluate at (0, 1, or 2).
level (int) – Rollout type. Must be one of: - gnubg.ro_auto - gnubg.ro_race - gnubg.ro_bearoff - gnubg.ro_over
nt (int) – Truncation threshold (default 500 games).
std (bool) – If True, also return standard deviation (std error) values.

Returns:

Either a 5-tuple of outcome probabilities or a 2-tuple with both means and standard deviations: - (win, win_gammon, win_backgammon, lose_gammon, lose_backgammon) - or: ((...), (stddevs...)) if std=True

Raises:

ValueError – If ngames is zero or negative.

Example

>>> gnubg.rollout(board)
(0.44, 0.21, 0.01, 0.31, 0.03)

>>> gnubg.rollout(board, std=True)
((0.44, 0.21, 0.01, 0.31, 0.03), (0.03, 0.02, 0.01, 0.02, 0.01))

This function provides accurate statistical approximations of long-term game outcomes from a given position.

gnubg.set

The set submodule provides configuration methods for adjusting internal GNUBG simulation behavior and evaluation settings.

Available Methods

set.seed(seed)

Set the seed for the internal pseudo-random number generator used in dice rolls and rollouts.

Parameters:: seed (int) – A positive integer seed value.

set.shortcuts(flags)

Enable or disable evaluation shortcuts used in simulation (used internally for debugging or performance tuning).

Parameters:: flags (int) – Integer bitmask to control shortcut behavior.

set.osdb(enabled)

Enable or disable the use of the One-Sided Bearoff Database.

Parameters:: enabled (bool) – True to enable, False to disable.

set.ps(flags)

Set pruning/move filtering flags.

Parameters:: flags (int) – Integer bitmask for move filters.

set.equities(table_id)

Select the match equity table to use.

Parameters:: table_id (int) – An integer referring to a preloaded MET.

set.score(x_away, o_away)

Set the current match score for X and O.

Parameters:

x_away (int) – Points X needs to win the match (0–25).
o_away (int) – Points O needs to win the match.

set.cube(owner, value, centered)

Set the cube state for evaluation.

Parameters:

owner (str) – ‘X’, ‘O’, or ‘C’ (centered).
value (int) – Cube value (1, 2, 4, …).
centered (bool) – Boolean indicating if the cube is centered.

Example

import gnubg.set as gset

gset.seed(42)
gset.score(3, 2)
gset.cube('O', 2, False)

Engine Initialisation

The GNUBG neural-network engine (weights, bearoff tables, opening book) is initialised automatically when you import the package. You do not need to call any initialisation function:

import gnubg_nn  # engine ready immediately

If you encounter examples from the original pygnubg library that call initnet() or gnubg.initnet(), those calls are not needed and will raise AttributeError — simply remove them.

Migration from pygnubg / Legacy Names

The gnubg-nn package modernises function names relative to the original pygnubg library. If you are porting old code, use the following mapping:

Old name (pygnubg)	New name (gnubg-nn)	Notes
`initnet()`	(not needed)	Auto-called on import
`boardfromkey(key)`	`board_from_position_key(key)`	20-char A–Z key
`boardfromid(id)`	`board_from_position_id(id)`	14-char Base64 Position ID
`keyofboard(board)`	`key_of_board(board)`
`posid(board)` / `id(board)`	`position_id(board)`
`bestmove(...)`	`best_move(...)`
`pubbestmove(board, d1, d2)`	`pub_best_move(board, d1, d2)`

Deprecated aliases (boardfromkey, boardfromid, bestmove) are available in gnubg_nn for backwards compatibility but will be removed in a future release.

Package Name

Warning

The PyPI package name is gnubg-nn, not gnubg. Installing gnubg installs the unrelated full GNU Backgammon application package, which exposes a different and incompatible API. Always install with:

pip install gnubg-nn

and import with:

import gnubg_nn