# google-deepmind/open_spiel architecture

> Architecture diagram of the GitHub repository google-deepmind/open_spiel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google-deepmind/open_spiel
- Repository: https://github.com/google-deepmind/open_spiel

## Overview

##### 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”).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build System
    subgraph "Build System"
        CMakeRoot["CMakeLists.txt"]:::build
        CMakeCore["open_spiel/CMakeLists.txt"]:::build
        CMakeRoot --> CMakeCore
    end

    %% Core Engine & Artifacts
    CMakeCore --> Core["C++ Core Engine"]:::core
    Core --> Lib["libspiel (.so/.a)"]:::artifact

    %% Language Bindings
    subgraph "Bindings"
        PyBind["pybind11 modules"]:::bindings
        JuliaBind["Julia wrapper"]:::bindings
        RustBind["Rust bindings"]:::bindings
        GoBind["Go bindings"]:::bindings
    end
    Lib --> PyBind
    Lib --> JuliaBind
    Lib --> RustBind
    Lib --> GoBind

    %% Python Frontend Library
    subgraph "Python Frontend Library"
        PyAlg["Algorithms"]:::python
        PyBots["Bots"]:::python
        PyGames["Games API"]:::python
        PyMFG["Mean-Field Games"]:::python
        PyJAX["JAX support"]:::python
        PyTORCH["PyTorch support"]:::python
        PyTF["TensorFlow support"]:::python
        PyUtils["Utilities"]:::python
        PyExamples["Examples"]:::python
        PyPackage["setup.py / requirements.txt / MANIFEST.in"]:::python
    end
    PyBind --> PyAlg
    PyBind --> PyBots
    PyBind --> PyGames
    PyBind --> PyMFG
    PyBind --> PyJAX
    PyBind --> PyTORCH
    PyBind --> PyTF
    PyBind --> PyUtils
    PyBind --> PyExamples
    PyBind --> PyPackage

    %% Runtime Environment
    subgraph "Runtime Environment"
        PythonUser["Python / Jupyter Notebook"]:::env
    end
    PythonUser --> PyAlg
    PythonUser --> PyBots
    PythonUser --> PyGames
    PythonUser --> PyMFG
    PythonUser --> PyJAX
    PythonUser --> PyTORCH
    PythonUser --> PyTF
    PythonUser --> PyUtils

    %% External ML Frameworks
    subgraph "External ML Frameworks"
        Torch["PyTorch"]:::external
        TF["TensorFlow"]:::external
        JAX["JAX"]:::external
        ORTOOLS["OR-Tools"]:::external
    end
    PyTORCH --> Torch
    PyTF --> TF
    PyJAX --> JAX
    Core --> ORTOOLS

    %% Multilingual Clients
    subgraph "Multilingual Clients"
        JuliaClient["Julia Code"]:::client
        RustClient["Rust Code"]:::client
        GoClient["Go Code"]:::client
    end
    JuliaClient --> JuliaBind
    RustClient --> RustBind
    GoClient --> GoBind

    %% Documentation & Notebooks
    subgraph "Documentation & Notebooks"
        Docs["docs/"]:::docs
        Colab["open_spiel/colabs/"]:::docs
    end

    %% Click Events
    click Core "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/"
    click CMakeRoot "https://github.com/google-deepmind/open_spiel/blob/master/CMakeLists.txt"
    click CMakeCore "https://github.com/google-deepmind/open_spiel/blob/master/open_spiel/CMakeLists.txt"
    click PyBind "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/pybind11/"
    click JuliaBind "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/julia/wrapper/"
    click RustBind "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/rust/src/"
    click GoBind "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/go/"
    click PyAlg "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/algorithms/"
    click PyBots "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/bots/"
    click PyGames "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/games/"
    click PyMFG "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/mfg/"
    click PyJAX "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/jax/"
    click PyTORCH "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/pytorch/"
    click PyTF "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/algorithms/tf/"
    click PyUtils "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/utils/"
    click PyExamples "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/python/examples/"
    click PyPackage "https://github.com/google-deepmind/open_spiel/blob/master/setup.py"
    click Docs "https://github.com/google-deepmind/open_spiel/tree/master/docs/"
    click Colab "https://github.com/google-deepmind/open_spiel/tree/master/open_spiel/colabs/"

    %% Styles
    classDef build fill:#f9c,stroke:#333;
    classDef core fill:#ccf,stroke:#333;
    classDef artifact fill:#ace,stroke:#333;
    classDef bindings fill:#cfc,stroke:#333;
    classDef python fill:#fc9,stroke:#333;
    classDef env fill:#fcf,stroke:#333;
    classDef external fill:#ddd,stroke:#333;
    classDef client fill:#c9f,stroke:#333;
    classDef docs fill:#9cf,stroke:#333;
```
