---
license: mit
library_name: alpha-zero-hexcrystal
tags:
  - pytorch
  - hexagonal-grid
  - spatial-encoder
  - reinforcement-learning
  - alphazero
---

# Hex-Crystalline Spatial Encoder

A spatial encoder for **hexagonal grids represented on a rectangular array**,
trained inside an AlphaZero-style agent for a simplified 4X strategy game. It
depends on nothing but PyTorch, so it can be reused for any hex-lattice problem —
board games, hex-tiled sensor arrays, or other six-neighbour topologies — without
the surrounding game code.

```python
from alpha_zero.hexcrystal.hub_mixin import HexSpatialEncoderForHub

encoder = HexSpatialEncoderForHub.from_pretrained("<repo-id>")
tokens = encoder(spatial)          # (B, C, H, W) -> (B, num_tokens, embed_dim)
```

Install with `pip install -e '.[hub]'` from the source repository.

## What this model actually does

Read this section before assuming behaviour from the name. Earlier documentation
in the source repository described features this encoder does **not** have; that
drift is corrected here and in the code.

The forward pass, in order:

1. **Even-q offset hexagonal convolution.** A 7-tap kernel — the centre tile plus
   its six neighbours — applied by gathering pre-computed adjacency indices.
   Off-board neighbours carry a `-1` sentinel and are masked. The stack runs at
   constant resolution: there is no pyramid, no dilation, and no configurable
   ring radius.
2. **Adaptive average pooling to a fixed token grid, then a linear projection.**
   This is the encoder's most consequential property: **pooling discards fine
   spatial structure** before tokenization. If your task needs per-tile fidelity
   at the output, this bottleneck is the first thing to reconsider.
3. **Optional crystalline lattice layer.** A set of learned transforms
   initialised to a symmetry group (hexagonal, cubic, or tetrahedral), combined
   by a softmax-weighted sum or a small attention over the **transform axis**.
   This is not spatial attention and involves no hex-neighbour masking.

What it does **not** contain, despite claims that circulated in earlier docs:

| Claimed | Reality |
|---|---|
| Axial coordinates | Even-q offset only; other systems raise `ValueError` |
| Ring-distance positional encoding | No positional encoding at all — position comes from the downstream transformer's learned `pos_embed` |
| Multi-scale convolutions | Flat, same-resolution stack |
| Attention over hex neighbourhoods | Attention is over transforms, not tiles |

## Intended use

**Intended.** A drop-in replacement for patch embedding when your input has hex
topology; a starting point for hex-aware architectures; a reference
implementation of even-q offset adjacency in PyTorch.

**Not intended.** This is **not** a strong game-playing model. It is one
component of an agent trained at small scale for research purposes. Do not deploy
it as a Civilization VI opponent or treat its weights as competitive.

## Training

Trained as the spatial encoder of a transformer policy/value network, via
AlphaZero-style self-play with Gumbel MCTS on **MicroCiv**, a simplified 4X
environment with a 13-channel state encoding on a square board. Training used
self-play trajectories only; there is no human gameplay data, and no external
dataset is involved.

## Evaluation

The two encoders were trained from identical code, seed, and budget, differing
only in encoder type, then played head to head. Full methodology and the
generating script are in the source repository (`scripts/run_encoder_ab.py`).

| hex_crystalline vs patch_embed | Value |
|---|---|
| Games | 800 |
| W/D/L | 142/588/70 |
| Score rate | 0.545 |
| Wilson 95% CI | [0.510, 0.579] |
| Elo difference | +31.4 |


### Evaluation scope and limitations

Read the confidence interval, not just the point estimate.

- **Reduced scale.** MicroCiv with a 13-channel encoder on a small board, a
  modest iteration budget, and CPU training. These are not full-Civilization VI
  results and do not extrapolate to one.
- **A single training run per arm.** Training-run variance is therefore **not
  captured**: the interval reflects game-sampling noise only, and a different
  seed could plausibly reorder the arms.
- **Differences smaller than the interval half-width are not resolved.** Where
  the interval spans 0.5, the honest reading is that this run does not
  distinguish the two encoders — not that they are equal, and not that the
  point estimate is real.
- **Draws are scored 0.5** in the score rate; win/draw/loss counts are reported
  separately so the raw outcome is recoverable.

The value of this evaluation is that it is reproducible, same-code, same-seed,
and bounded — not that it settles which encoder is better.

## Architecture details

| Property | Value |
|---|---|
| Coordinate system | Even-q offset (flat-top hexes) |
| Kernel | 7-tap (centre + 6 neighbours) via gather |
| Symmetry groups | `hexagonal` (6), `cubic` (8), `tetrahedral` (12) transforms |
| Tokenization | Adaptive average pool → linear projection |
| Output shape | `(batch, num_output_tokens, embed_dim)` |
| Weights format | safetensors |
| Dependencies | PyTorch only |

Configuration is a flat `config.json` and round-trips through
`HexEncoderConfig.from_dict`. The adjacency indices are registered buffers, so
they travel with `.to(device)` and appear in the `state_dict`.

## Reproducing

```bash
python scripts/run_encoder_ab.py train --iterations N --games-per-iter M
python scripts/run_encoder_ab.py arena --num_games K
python scripts/run_encoder_ab.py report
```

Both arms take the same seed, and the environment seed is threaded into
self-play so game streams are reproducible — seeding the global RNGs alone is
not sufficient, because the environment holds its own generator.

## Citation

If you use this encoder, please cite the repository. The exact commit that
produced these weights is recorded in the evidence report alongside the
training budget.