{"id":44975912,"url":"https://github.com/k-l-lambda/trigo.cpp","last_synced_at":"2026-02-18T17:04:32.554Z","repository":{"id":327584867,"uuid":"1109701940","full_name":"k-l-lambda/trigo.cpp","owner":"k-l-lambda","description":"High-performance C++/CUDA implementation of Monte Carlo Tree Search for Trigo (3D Go) training data generation.","archived":false,"fork":false,"pushed_at":"2025-12-21T15:56:09.000Z","size":713,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-21T16:34:44.520Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/k-l-lambda.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-04T06:58:03.000Z","updated_at":"2025-12-05T15:20:12.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/k-l-lambda/trigo.cpp","commit_stats":null,"previous_names":["k-l-lambda/trigo.cpp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/k-l-lambda/trigo.cpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Ftrigo.cpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Ftrigo.cpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Ftrigo.cpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Ftrigo.cpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/k-l-lambda","download_url":"https://codeload.github.com/k-l-lambda/trigo.cpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/k-l-lambda%2Ftrigo.cpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29587066,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-18T16:55:40.614Z","status":"ssl_error","status_checked_at":"2026-02-18T16:55:37.558Z","response_time":162,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-18T17:04:31.469Z","updated_at":"2026-02-18T17:04:32.535Z","avatar_url":"https://github.com/k-l-lambda.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Trigo.cpp - High-Performance C++ Tools for Trigo AI\n\nC++/CUDA inference and self-play tools for [Trigo](https://github.com/k-l-lambda/trigo) (3D Go). Provides ONNX Runtime-based neural network inference, AlphaZero-style MCTS, and high-performance self-play data generation for the [TrigoRL training pipeline](../trigoRL).\n\n## Overview\n\nThis project implements production-ready tools for Trigo AI development:\n\n**Key Features**:\n- 🚀 **ONNX Runtime Integration**: CPU and GPU inference with trained models\n- 🎯 **AlphaZero MCTS**: Value network evaluation (255× faster than random rollouts)\n- 🔧 **Self-Play Generator**: Command-line tool for training data generation\n- 🎲 **Random Board Selection**: 220 candidate shapes (2D and 3D) for diverse training\n- ✅ **Cross-Language Validation**: 100% compatibility with TypeScript reference\n- 📦 **Multiple Policies**: Random, Neural, Pure MCTS, AlphaZero MCTS\n- 📊 **TGN Format**: Compatible with TrigoRL training pipeline\n\n## Quick Start\n\n### Prerequisites\n\n- CMake 3.18+\n- GCC 9+ or Clang 10+\n- CUDA Toolkit 11.0+ (optional, for GPU inference)\n- ONNX Runtime 1.17.0+ (provided in repository)\n\n### Build\n\n```bash\n# Clone repository\ncd /path/to/trigo.cpp\n\n# Create build directory\nmkdir build \u0026\u0026 cd build\n\n# Configure and build\ncmake .. -DCMAKE_BUILD_TYPE=Release\nmake -j$(nproc)\n\n# Run tests\n./test_trigo_game\n./test_alphazero_mcts\n```\n\n### Usage\n\n#### Self-Play Data Generation\n\n**Generate games with random board shapes (recommended for training):**\n```bash\n# Random board selection from 220 candidates (2D: 2-13×1-13×1, 3D: 2-5×2-5×2-5)\n# This creates a diverse dataset covering various board sizes\nexport TRIGO_FORCE_CPU=1\n\n./self_play_generator \\\n    --num-games 100 \\\n    --random-board \\\n    --black-policy mcts \\\n    --white-policy mcts \\\n    --model ../models/trained_shared \\\n    --output /path/to/data/mcts_games \\\n    --seed 42\n\n# With custom board ranges (e.g., small 2D boards only)\n./self_play_generator \\\n    --num-games 100 \\\n    --random-board \\\n    --board-ranges \"3-9x3-9x1-1,2-3x2-3x2-2\" \\\n    --black-policy mcts \\\n    --white-policy mcts \\\n    --model ../models/trained_shared \\\n    --output /path/to/data/mcts_games\n```\n\n**Generate games with fixed board size:**\n```bash\n# AlphaZero-style MCTS with value network on 5×5×5 board\n# Force CPU for best performance (1.52× faster than GPU for batch=1 MCTS)\nexport TRIGO_FORCE_CPU=1\n\n./self_play_generator \\\n    --num-games 100 \\\n    --board 5x5x5 \\\n    --black-policy mcts \\\n    --white-policy mcts \\\n    --model ../models/trained_shared \\\n    --output /path/to/data/mcts_games \\\n    --seed 42\n\n# With custom MCTS parameters\n./self_play_generator \\\n    --num-games 100 \\\n    --board 5x5x5 \\\n    --black-policy mcts \\\n    --white-policy mcts \\\n    --model ../models/trained_shared \\\n    --mcts-simulations 50 \\\n    --mcts-c-puct 1.5 \\\n    --output /path/to/data/mcts_games\n```\n\n**Generate games with neural policy (faster, less exploration):**\n```bash\n./self_play_generator \\\n    --num-games 1000 \\\n    --board 5x5x5 \\\n    --black-policy neural \\\n    --white-policy neural \\\n    --model ../models/trained_shared \\\n    --output /path/to/data/neural_games\n```\n\n**Generate baseline games with random policy:**\n```bash\n# Random policy with random board shapes\n./self_play_generator \\\n    --num-games 10000 \\\n    --random-board \\\n    --black-policy random \\\n    --white-policy random \\\n    --output /path/to/data/random_games \\\n    --seed 42\n\n# Random policy with fixed board\n./self_play_generator \\\n    --num-games 10000 \\\n    --board 5x5x5 \\\n    --black-policy random \\\n    --white-policy random \\\n    --output /path/to/data/random_games \\\n    --seed 42\n```\n\n#### Board Shape Options\n\nThe generator supports two modes for board shape selection:\n\n**Fixed Board (--board):**\n```bash\n--board 5x5x5    # Fixed 5×5×5 board for all games\n--board 9x9x1    # Fixed 9×9×1 (2D) board for all games\n--board 13x13x1  # Fixed 13×13 (traditional Go size)\n```\n\n**Random Board (--random-board):**\n```bash\n--random-board   # Randomly select from 220 candidate shapes per game\n```\n\nThe random board mode uses default ranges:\n- **2D boards**: 2-13×1-13×1 (156 shapes)\n- **3D boards**: 2-5×2-5×2-5 (64 shapes)\n- **Total**: 220 candidate shapes\n\n**Custom Board Ranges (--board-ranges):**\n\nYou can specify custom ranges with `--board-ranges` (requires `--random-board`):\n\n```bash\n# Format: \"minX-maxXxminY-maxYxminZ-maxZ,...\"\n--random-board --board-ranges \"2-13x1-13x1-1,2-5x2-5x2-5\"  # Default (220 shapes)\n--random-board --board-ranges \"3-9x3-9x1-1\"                 # Small 2D boards only\n--random-board --board-ranges \"2-3x2-3x2-3\"                 # Tiny 3D boards only\n--random-board --board-ranges \"5-5x5-5x5-5,9-9x9-9x1-1\"    # Mix of 5×5×5 and 9×9\n```\n\n**Range Format**: `minX-maxXxminY-maxYxminZ-maxZ`\n- Multiple ranges can be comma-separated\n- Each range generates all combinations within bounds\n- Example: `2-3x2-3x1-1` generates: 2×2×1, 2×3×1, 3×2×1, 3×3×1 (4 shapes)\n\nRandom board selection is recommended for training diverse models that generalize across board sizes.\n\n**Parameter Rules**:\n- `--board` and `--random-board` are mutually exclusive\n- `--board-ranges` requires `--random-board`\n\n#### Policy Options\n\nAvailable policy types:\n- `random` - Random valid moves (fast, no model required)\n- `neural` - Direct neural network inference (requires `--model`)\n- `mcts` - AlphaZero MCTS with value network (requires `--model`)\n\n#### MCTS Parameters\n\n- `--mcts-simulations N` - Number of MCTS simulations per move (default: 50)\n- `--mcts-c-puct F` - Exploration constant for PUCT formula (default: 1.5)\n- `--mcts-temperature F` - Temperature for move selection (default: 1.0)\n- `--mcts-dirichlet-alpha F` - Dirichlet noise alpha for root exploration (default: 0.3)\n\n#### Model Path\n\nThe `--model` parameter should point to a directory containing the 3-model ONNX architecture:\n```\nmodels/trained_shared/\n├── base_model.onnx       # Shared transformer base\n├── policy_head.onnx      # Policy network\n└── value_head.onnx       # Value network\n```\n\nModels are exported from TrigoRL using `exportOnnx.py`.\n\n#### Performance Tips\n\n**For Self-Play Generation:**\n- Use `TRIGO_FORCE_CPU=1` for MCTS (CPU is 1.52× faster than GPU)\n- MCTS with 50 simulations: ~280ms per move on CPU\n- Can generate 10,000 games in 32.5 hours on a single CPU\n\n**For GPU Inference:**\n- GPU is recommended only for training with large batches (256+)\n- Small batch sizes (batch=1) underutilize GPU parallelism\n- GPU shows ~1.52× performance penalty for MCTS due to kernel launch overhead\n\n## Architecture\n\n### Component Stack\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│  Python Training Pipeline (TrigoRL) - SEPARATE PROJECT      │\n│  ├─ PyTorch Model Training                                   │\n│  ├─ ONNX Model Export (exportOnnx.py)                        │\n│  ├─ Training Data Loading (.tgn files)                       │\n│  └─ Weights \u0026 Biases Integration                             │\n└─────────────────────────────────────────────────────────────┘\n                           ↓ exports\n                    ONNX Models (.onnx)\n                           ↓ uses\n┌─────────────────────────────────────────────────────────────┐\n│  C++ Inference \u0026 Generation Tools (trigo.cpp) - THIS PROJECT│\n│  ├─ SharedModelInferencer (ONNX Runtime + CUDA)             │\n│  │   ├─ Policy Network Inference                             │\n│  │   ├─ Value Network Inference                              │\n│  │   └─ Prefix Tree Attention Builder                        │\n│  ├─ TrigoGame (3D Go rules engine)                           │\n│  │   ├─ Board State Management                               │\n│  │   ├─ Move Validation                                      │\n│  │   ├─ Capture \u0026 Ko Detection                               │\n│  │   └─ Territory Calculation                                │\n│  ├─ MCTS (Monte Carlo Tree Search)                           │\n│  │   ├─ AlphaZero MCTS (PUCT, value network) - Production   │\n│  │   └─ Pure MCTS (UCB1, random rollouts) - Reference       │\n│  ├─ Self-Play Generator (data generation tool)               │\n│  │   ├─ Random Board Selection (220 candidates)              │\n│  │   ├─ RandomPolicy                                         │\n│  │   ├─ NeuralPolicy (ONNX inference)                        │\n│  │   ├─ MCTSPolicy (Pure MCTS)                               │\n│  │   └─ TGN File Export                                      │\n│  └─ Python Bindings (pybind11) [future]                     │\n└─────────────────────────────────────────────────────────────┘\n                           ↓ generates\n                    Training Data (.tgn)\n                           ↓ feeds back to\n                      TrigoRL Pipeline\n```\n\n### Directory Structure\n\n```\ntrigo.cpp/\n├── include/              # Public C++ headers\n│   ├── trigo_game.hpp               # 3D Go game engine\n│   ├── trigo_coords.hpp             # ab0yz coordinate system\n│   ├── trigo_game_utils.hpp         # Capture, Ko, territory\n│   ├── board_shape_candidates.hpp   # Random board shape generation\n│   ├── mcts.hpp                     # AlphaZero MCTS (value network)\n│   ├── mcts_moc.hpp                 # Pure MCTS (random rollouts)\n│   ├── self_play_policy.hpp         # Policy interfaces\n│   ├── shared_model_inferencer.hpp  # ONNX Runtime wrapper\n│   ├── prefix_tree_builder.hpp      # Tree attention\n│   ├── tgn_tokenizer.hpp            # TGN tokenization\n│   └── tgn_utils.hpp                # TGN generation utilities\n├── src/                  # Implementation\n│   ├── trigo_game.cpp\n│   ├── shared_model_inferencer.cpp\n│   ├── tgn_tokenizer.cpp\n│   ├── prefix_tree_builder.cpp\n│   └── self_play_generator.cpp      # Main CLI tool\n├── tests/                # Unit tests\n│   ├── test_trigo_game.cpp\n│   ├── test_mcts.cpp\n│   ├── test_alphazero_mcts.cpp\n│   ├── test_neural_policy_inference.cpp\n│   └── ...\n├── models/               # Trained ONNX models\n│   └── trained_shared/\n│       ├── base_model.onnx\n│       ├── policy_head.onnx\n│       └── value_head.onnx\n├── docs/                 # Documentation\n│   └── PLAN.md           # Development roadmap\n├── CMakeLists.txt\n└── README.md\n```\n\n## Performance\n\n### C++ vs TypeScript MCTS Performance\n\nComprehensive benchmarking (December 2025) shows significant performance advantages:\n\n| Implementation | Time per Move | Games per Minute | Speedup vs TypeScript |\n|----------------|---------------|------------------|----------------------|\n| **C++ CPU (MCTS)** | 280ms | 3.6 games/min | **6.59×** |\n| **C++ GPU (MCTS)** | 335ms | 3.0 games/min | 5.51× |\n| TypeScript (MCTS) | 1846ms | 0.65 games/min | 1× (baseline) |\n\n**Key Findings:**\n- **C++ is 5.47× faster** than TypeScript for MCTS self-play\n- **CPU outperforms GPU by 1.52×** for batch=1 MCTS workloads\n- Can generate **10,000 games in 32.5 hours** on a single CPU\n\n### Value Network vs Random Rollouts\n\nAlphaZero-style MCTS with value network provides massive speedup over traditional rollouts:\n\n| Implementation | Time per simulation | 50 simulations | 800 simulations |\n|----------------|---------------------|----------------|-----------------|\n| PureMCTS (rollouts) | 923ms | 46 seconds | 12+ minutes |\n| MCTS (value network) | 3.6ms | 180ms | 2.9 seconds |\n| **Speedup** | **255×** | **255×** | **255×** |\n\n**Test Configuration:**\n- Board: 5×5×1\n- MCTS simulations: 50 per move\n- Model: Dynamic ONNX shared architecture\n- Hardware: Multi-core CPU + RTX 3090 (24GB)\n\n### Why CPU is Faster Than GPU for MCTS\n\nFor batch=1 MCTS workloads, CPU shows better performance due to:\n- **Kernel launch overhead**: ~100-150μs per GPU call dominates small inference\n- **Memory transfers**: 7 additional Memcpy operations for GPU\n- **Underutilization**: GPU cores 99% idle with batch=1\n- **Operator fallback**: Some operators fall back to CPU\n\n**Recommendation:**\n- ✅ Use CPU for MCTS self-play (batch=1)\n- ✅ Use GPU for training (batch=256+)\n- ✅ Future: Batch MCTS leaf evaluation for GPU (64-256 positions simultaneously)\n\n### Production Capacity\n\n**Single CPU Performance:**\n- 7.7 games per minute (MCTS, 50 simulations/move)\n- 10,000 games in 32.5 hours\n- Ready for large-scale RL training pipelines\n\n## Implementation Status\n\n### ✅ Phase 1: Model Inference - COMPLETE\n\n- ✅ `SharedModelInferencer` - ONNX Runtime with shared base model\n- ✅ `TGNTokenizer` - Compatible with Python training tokenizer\n- ✅ `PrefixTreeBuilder` - Tree attention support\n- ✅ ONNX models can be loaded and run\n- ✅ Model format: 3-model architecture (base + policy_head + value_head)\n\n### ✅ Phase 2: Game Engine - COMPLETE\n\n- ✅ `TrigoGame` - Complete 3D Go engine\n- ✅ `trigo_coords.hpp` - ab0yz coordinate encoding\n- ✅ `trigo_game_utils.hpp` - Capture, Ko, territory\n- ✅ `tgn_utils.hpp` - Shared TGN generation\n- ✅ Cross-language validation (100/100 games vs TypeScript)\n\n### ✅ Phase 3: MCTS Algorithm - COMPLETE\n\n- ✅ PureMCTS with random rollouts (`include/mcts_moc.hpp`)\n  - UCB1 selection, tree expansion, backpropagation working\n  - Reference implementation for validation\n  - Performance: ~923ms per simulation\n- ✅ AlphaZero-style MCTS with value network (`include/mcts.hpp`)\n  - Uses `SharedModelInferencer::value_inference()` for evaluation\n  - PUCT formula for exploration\n  - **Performance: 255× speedup** (~3.6ms per simulation)\n  - Production-ready implementation\n\n### 🚧 Phase 4: GPU Acceleration - FUTURE\n\n- Planned: CUDA MCTS kernels for parallel tree operations\n- Planned: Batched neural network inference\n- Target: 50-100 games/sec on GPU\n\n## Validation\n\nThe implementation is validated against the TypeScript golden reference at `trigoRL/third_party/trigo/trigo-web/`.\n\n**Validation Results**:\n- ✅ 100/100 games match TypeScript implementation\n- ✅ All moves legal (capture, Ko, suicide rules)\n- ✅ Territory scoring matches\n- ✅ TGN format parseable by TGNValueDataset\n- ✅ Games terminate correctly\n\n## Integration with TrigoRL Training\n\n### Data Flow\n\n1. **TrigoRL** trains models → exports `.onnx` files\n2. **trigo.cpp** loads `.onnx` → runs self-play → generates `.tgn` files\n3. **TrigoRL** loads `.tgn` files → continues training (iterative improvement)\n\n### Model Format\n\nThe project uses a 3-model architecture:\n- `base_model.onnx` - Shared transformer base\n- `policy_head.onnx` - Policy network (move prediction)\n- `value_head.onnx` - Value network (position evaluation)\n\nModels are exported from TrigoRL using `exportOnnx.py`.\n\n## Development\n\n### Building Tests\n\n```bash\ncd build\n\n# Build specific test\nmake test_trigo_game\n\n# Run test\n./test_trigo_game\n```\n\n### Available Tests\n\n- `test_trigo_game` - Game engine validation\n- `test_trigo_coords` - Coordinate system\n- `test_trigo_game_utils` - Go rules (capture, Ko)\n- `test_mcts` - Pure MCTS implementation\n- `test_alphazero_mcts` - AlphaZero MCTS performance\n- `test_neural_policy_inference` - Neural policy\n- `test_tgn_consistency` - TGN format validation\n- `test_game_replay` - Cross-language validation\n\n### Code Style\n\n- C++17 standard\n- Modern C++ (curly braces on standalone lines, tab indentation)\n- Comprehensive comments\n- DRY principle (avoid code duplication)\n\n## Documentation\n\n- [Development Plan](docs/PLAN.md) - Roadmap and implementation status\n- [Model Inference](docs/research/MODEL_INFERENCE.md) - ONNX Runtime integration\n- [CUDA Inference](docs/research/CUDA_INFERENCE.md) - GPU acceleration research\n- [Validation Report](docs/research/VALIDATION_REPORT.md) - Cross-language validation\n\n## References\n\n- [Trigo Game Rules](https://github.com/k-l-lambda/trigo)\n- [TrigoRL Training Pipeline](../trigoRL)\n- [AlphaZero Paper](https://arxiv.org/abs/1712.01815)\n- [ONNX Runtime](https://onnxruntime.ai/)\n\n## License\n\n[Specify license]\n\n---\n\n**Project Scope**: C++/CUDA tools for Trigo game engine and MCTS self-play generation\n\n**Goal**: Provide high-performance tools for TrigoRL training pipeline\n\n**Status**: Phases 1-3 Complete - Production-ready self-play generation with AlphaZero MCTS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-l-lambda%2Ftrigo.cpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fk-l-lambda%2Ftrigo.cpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fk-l-lambda%2Ftrigo.cpp/lists"}