FAQ

FAQ

Common questions while learning the framework. Add new ones via issue or PR.

Click any question to expand it.

---

Setup

The engine will not compile, what compiler do I need?

Any of cc, gcc, or clang on PATH. On macOS install Xcode Command Line Tools (xcode-select --install). On Linux apt install build-essential is enough. On Windows install MSVC build tools or use WSL.

If pip installed a pre-built wheel for your platform you do not need a compiler at all. Verify with python -c "import hexbot; print(hexbot.HexGame())".

Which device should I use? CPU, MPS, or CUDA?

Whichever you have. The framework auto-detects.

• CUDA: fastest by a wide margin. Mixed precision FP16 gives another 2x.
• MPS: Apple Silicon. Works, but torch.compile is finicky, disable it if you see crashes.
• CPU: slow but stable, fine for inference and short experiments.

Force a device with device='cuda', 'mps', or 'cpu' arguments where supported.

Training

Why is training so slow on my machine?

Self-play game generation dominates. Each game runs MCTS at every move, which is many network evaluations.

Levers in order of impact:

1. Lower MCTS sims: --sims 50 (default ~200).
2. Use a smaller network: --config fast (656K params vs 3.9M).
3. Reduce games per iteration: --games 16.
4. Run on GPU if you are not already.

See Configuration for the full set.

Why does Orca not beat me yet?

The shipped checkpoint is iteration 65, early stage. The framework is designed to keep training; the included weights are a starting point, not a finished product. Run python -m orca.train --iterations 100 and the bot will improve substantially.

My loss bounces around or hits NaN

NaN usually means a bug in mixed precision or an extreme value somewhere. Try --no-fp16 to disable mixed precision and see if the loss stabilizes. If yes, file an issue: fp16 paths sometimes have edge cases.

A bouncing-but-not-diverging loss is normal in AlphaZero training. The replay buffer mixes data from many policy generations.

How long until decent ELO?

On a single GPU with default settings, rough milestones:

• Iteration 10: beats random consistently
• Iteration 30: beats heuristic >70%
• Iteration 100: starts to look strategically coherent
• Iteration 300+: competitive on hexo.did.science

Can I distribute training across multiple GPUs?

Yes. See orca.distributed: PyTorch DDP across GPUs on one machine, Ray for multi-machine. Also covered in Training Guide.

Inference

How do I play against my bot in a browser?

Run python train_dashboard.py and open the Play tab. Drag stones onto the board, the bot responds.

For playing on hexo.did.science under your own account, see Playing Online.

Where does the checkpoint live?

orca/checkpoint.pt is the bundled one. When you train, new checkpoints write to hex_checkpoint_*.pt at the project root and the best one is kept as hex_best.pt.

Can I serve the bot as an API?

The dashboard already exposes one. See Dashboard Guide.

Architecture

Why an infinite board?

Connect-6's actual rules allow play anywhere. The engine maintains a candidate set of cells near existing stones to keep search bounded, so you never compute legal moves over the entire infinite grid.

Why C for the engine?

Hot path is place, undo, scored_moves. Doing this in Python would be 50 to 100x slower. The C engine uses bitboards and no allocation, hitting ~1.4M place/undo cycles per second on M-series.

Why six neural network architectures?

To make architecture choice a tunable variable rather than a hardcoded assumption. hex-masked is the recommended default, large for max strength, hex-gnn and multiscale are experimental.

Misc

Lost my checkpoint, can I recover from the replay buffer?

Partially. The replay buffer (replay_buffer.pkl) has (state, policy, value) tuples. With enough buffer you can retrain a new network via SFT on those samples, but you lose the architectural details unless they were saved.

Can I plug in my own bot or network?

Yes. See Plugin System.