How google-deepmind/open_spiel works
Main Components
• C++ Core Engine
• All code under open_spiel/ (spiel.cc/h, games/, algorithms/, utils/, etc.)
• Built with CMake into a static/shared library (“libspiel”)
• Language Bindings
• Python: pybind11 modules under open_spiel/python/pybind11
• Julia: wrapper in open_spiel/julia/wrapper
• Rust: open_spiel/rust/src with Rust/OpenSpiel bindings
• Go: open_spiel/go/ with example_go bindings
• Python Frontend Library
• Pure-Python algorithms & tools under open_spiel/python/algorithms, /bots, /games, /mfg, /pytorch, /tf, /jax, /utils, /examples
• setup.py for packaging, plus requirements.txt
• Build & Deployment
• CMake scripts (CMakeLists.txt) in root and subdirectories
• setup.py & MANIFEST.in for Python packaging
• Dockerfile.base and Dockerfile.jupyter for container images
• GitHub Actions workflows (.github/workflows/*.yml) for CI (build, test, wheel publishing)
• Documentation & Examples
• docs/ for Sphinx sources, readthedocs.yml
• Colab notebooks in open_spiel/colabs/
• Markdown READMEs for individual modules
Relationships & Data Flows
User invokes CMake → compiles C++ sources → produces libspiel (static/shared), headers
setup.py & pybind11 build → wraps libspiel into Python extension modules
Dockerfiles reference these two build steps for container images
GitHub Actions orchestrate these builds & run tests
• Runtime Flow (center):
Python User Code / Jupyter Notebook
→ imports open_spiel Python package (pure Python + extension modules)
→ calls pybind11 bindings functions
→ executes C++ core engine: instantiates Game objects, runs Algorithms, returns states/tensors
→ back in Python, results feed into ML modules (PyTorch/TensorFlow/JAX) for learning/training
→ optional persistence via Python utils (replay_buffer, data_logger)
• Multilingual Clients (bottom):
Julia code calls the Julia wrapper → C++ library
Rust client similarly via rust_open_spiel
Go via Go bindings → C++ core
• External Frameworks (right side):
ML frameworks: torch, tensorflow, jax
OR-Tools LP solver under open_spiel/algorithms/ortools
Other external libs: pybind11, gRPC (none here), Cython (none), etc.
Architectural Patterns & Design Principles
• Layered architecture:
• Core (C++ engine)
• Language Binding layer (pybind11, wrapper code)
• Python-level API & modules
• User code / notebooks
• Modularity & plugin style: easily add new games or algorithms in C++ or Python subdirectories
• Single-entry API for all games: common Game/State/Observer interfaces
• Separation of build vs. runtime concerns: CMake vs. Python packaging
• CI/CD pipeline integration
Detail Without Clutter
• Similarly group Python modules (algorithms, games, bots) into categories.
• Representative examples of extension points (e.g., “Add new game: implements Game interface”).