GNUBG Neural Networks (gnubg-nn)

GNUBG Neural Networks (this package, gnubg-nn) is a library that provides Python bindings to the GNUBG neural-network evaluation engine — the same engine used for position analysis and cube decisions in the full GNU Backgammon application, but packaged as a standalone library for use in scripts, analysis tools, and applications. It is not the full backgammon game (GUI, match play, etc.).

Quick Start

gnubg_nn is a native Python extension module that wraps the GNUBG neural-net evaluation library, so you can call the same position-analysis and cube-decision routines that power the full GNU Backgammon application from any Python 3.10+ script or application. It’s ideal for batch processing, data-science workflows, or building custom tools and UIs.

Installation

Important: The PyPI package name is gnubg-nn, not gnubg. Installing gnubg will install the unrelated full GNU Backgammon application. The correct command is:

pip install gnubg-nn

Then import it as:

import gnubg_nn

Note: The engine (neural-network weights, bear-off tables, etc.) initialises automatically on import — you do not need to call initnet().

Getting Started

import gnubg_nn

# Convert a 14-char Base64 Position ID to a 2x25 board
board = gnubg_nn.board_from_position_id("4HPwATDgc/ABMA")

# Evaluate win/gammon/backgammon probabilities at 2 plies
probs = gnubg_nn.probabilities(board, gnubg_nn.p_0plus1)
win, win_gammon, win_bg, lose_gammon, lose_bg = probs

print(f"Win: {win:.3f}, Gammon: {win_gammon:.3f}, Backgammon: {win_bg:.3f}")

# Find the best move for an opening 6-5 roll
moves = gnubg_nn.moves(board, 6, 5)
best = gnubg_nn.best_move(board, 6, 5)
print(f"Best move key: {best}")

Training the Neural Network

You can also train the neural network weights against labeled position data using the Trainer class:

import gnubg_nn

# Create a trainer from a list of training positions
# Each entry: 20-char position key + 5 space-separated probability values
training_data = [
    "ABCDEFGHIJ0123456789 0.5 0.1 0.05 0.1 0.05",  # position key + probs
    "JIHGFEDCBA9876543210 0.6 0.15 0.08 0.08 0.04",
]

trainer = gnubg_nn.Trainer(training_data)

# Check initial training errors (RMS + max error for 6 metrics)
errors = trainer.errors()
print(f"Initial error: {errors[2]:.4f}")

# Train for one epoch at learning rate 0.01
trainer.train(0.01)

# Check errors after training
errors = trainer.errors()
print(f"After training: {errors[2]:.4f}")

The Trainer class supports options for training against the pruned net, ignoring backgammon components, and restricting to specific neural net inputs. See the API documentation for details.

That’s all you need to get up and running! For detailed API docs, advanced build options, and configuration, see the sections below or visit the full documentation on ReadTheDocs.

• ReadTheDocs https://gnubg.readthedocs.io/en/latest/
• GNU Backgammon (full application): https://www.gnu.org/software/gnubg/
• Original Documentation: http://www.gnubg.org/documentation/doku.php?id=gnu_backgammon_faq
• Mailing list: https://lists.gnu.org/mailman/listinfo/gnubg
• Source code: https://github.com/StonesAndDice/gnubg-nn-pypi
• GNUBG Neural Networks (gnubg-nn) upstream: https://git.savannah.gnu.org/cgit/gnubg/gnubg-nn.git
• Contributing: https://savannah.gnu.org/people/
• Credits: https://git.savannah.gnu.org/cgit/gnubg.git/tree/credits.sh

It provides:

• Engine initialization & data loading (neural-net weights, opening-book, bear-off tables)
• Position classification (classify) & public-evaluation best move (pub_best_move)
• Board ↔ ID conversions (board_from_position_id, board_from_position_key, key_of_board, position_id)
• Dice utilities (roll) & cube utilities (best_move, pub_eval_score)
• Bear-off tools (bearoff_id_2_pos, bearoff_probabilities)
• Legal-move enumeration (moves) & probabilistic evaluation (probabilities)
• Monte-Carlo rollouts (rollout, cubeful_rollout)
• Equity lookup (equities.value(xAway, oAway))
• Neural-net training (Trainer class for tuning weights against labeled positions)
• Runtime engine tuning via the set submodule

🧪 Platform Compatibility

Notes:

• ✅ = Built and available
• ❌ = Not built
• macOS universal2 = Supports both ARM64 and x86-64 architectures

Testing

gnubg-nn-pypi has some basic unit testing. After installation, run:

python3 -m unittest discover -s gnubg_nn.tests

AI-Assisted Development

Parts of this project were developed with the assistance of generative AI tools.

Specifically, the following models were used:

• GPT-4o (OpenAI ChatGPT)
• o4-mini-high (OpenAI ChatGPT)
• Haiku 4.5 (Anthropic)
• Opus 4.8 (Anthropic)

These models were used to assist with code generation, documentation drafting, and architectural guidance. All outputs were reviewed and curated by a human before inclusion.

⚠️ Disclaimer:
Although human-reviewed, some AI-generated content may contain mistakes, inaccuracies, or outdated practices. Contributors and users should critically assess all code, comments, and documentation. We welcome corrections and improvements via pull requests or issues.

Code of Conduct

Please read the Code of Conduct to learn how to interact positively.

Contributing

Your expertise and enthusiasm are welcome! You can contribute by:

• Reviewing and testing pull requests
• Reporting and triaging issues
• Improving documentation, tutorials, and examples
• Enhancing engine parameters or submodules
• Maintaining website or branding assets
• Translating materials
• Assisting with outreach and onboarding
• Writing grant proposals or helping with fundraising

For more information, see our Contributing Guide. If you’re unsure where to start, open an issue or join the discussion on our mailing list!

Acknowledgments

This project builds upon the extensive work of the GNU Backgammon (GNUBG) community. The gnubg-nn library is the neural network evaluation component; the full backgammon application (GUI, match play, etc.) is maintained separately. We specifically acknowledge the pygnubg program developed by Joseph Heled.

We express our gratitude to all contributors who have dedicated their time and expertise to the development of the GNUBG neural network library and its Python bindings.

• AUTHORS.md: A list of primary contributors to the gnubg-nn-pypi project can be found here.
• GNU Backgammon (full project) credits.sh: For a comprehensive list of contributors to the full GNUBG application, please refer to the credits.sh file.

We also thank the broader GNUBG community, including testers, translators, and mailing list participants, for their invaluable support.