arjunnarayanan/par-quad-pinwheel-mitq-e2e-v1-4M

par-quad: pinwheel-mitq-e2e-v1-4M

The released agent from Playing to Par: Reinforcement Learning for Provably Optimal Quadrilateral Block Decompositions (Arjun Narayanan and Per-Olof Persson, UC Berkeley).

Paper · Code · Project page · Play Mesh Quest

The agent builds a quadrilateral block decomposition from a 2D domain's bare boundary. It aims for par: the lower bound on vertex irregularity that the discrete Gauss–Bonnet identity fixes from the domain's corner angles and topology alone, I(M) ≥ par(Ω) = |c(Ω) + 4χ|. A mesh that reaches par is provably optimal in its connectivity.

Model

• Algorithm: behaviour cloning on certified instances (optimal meshes walked backward into demonstrations), followed by 4,004,096 PPO steps.
• Network: 365k parameters. A convolution over the half-edge mesh (doubly connected edge list) that follows each half-edge's next, previous and twin. It has 4 layers of 96 features on 10 input features per half-edge. Because it operates per half-edge with pooling, it runs unchanged on domains larger than any it saw in training.
• Actions: inserting chords and vertices on the mesh, with invalid actions masked.
• Framework: Stable-Baselines3 2.6.0, PyTorch 2.7.1, Gymnasium 1.1.1.

Files

File
pinwheel-mitq-e2e-v1-4M.zip	the Stable-Baselines3 PPO checkpoint (includes the optimizer state, so training can resume)
pinwheel-mitq-e2e-v1.config.yml	the environment and training config it needs to load

Usage

The checkpoint's policy and feature extractor are classes in the par-quad repository, so load it from a clone of that repository (Python 3.11 or 3.12):

git clone https://github.com/ArjunNarayanan/par-quad.git
cd par-quad
python3.12 -m venv venv
venv/bin/pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cpu   # CPU-only machines
venv/bin/pip install -r requirements.txt huggingface_hub
export GEOGEN_PATH=tools/geo2d_lite

In Python:

from huggingface_hub import hf_hub_download
from src.geo2d_bridge import load_model

repo = "arjunnarayanan/par-quad-pinwheel-mitq-e2e-v1-4M"
checkpoint = hf_hub_download(repo, "pinwheel-mitq-e2e-v1-4M.zip")
config = hf_hub_download(repo, "pinwheel-mitq-e2e-v1.config.yml")
model = load_model(checkpoint, config)  # a stable_baselines3 PPO model

Or download the files and mesh one domain, writing out/demo.mp4 and out/demo.gif:

venv/bin/hf download arjunnarayanan/par-quad-pinwheel-mitq-e2e-v1-4M --local-dir models/hf
venv/bin/python utilities/animate_rollout.py -suite straight-holes -draw 10 -n 24 \
    -config models/hf/pinwheel-mitq-e2e-v1.config.yml \
    -checkpoint models/hf/pinwheel-mitq-e2e-v1-4M.zip -out out -name demo

The repository README covers the paper's full evaluation procedure, the Gmsh comparison, the curved-boundary repair search and training from scratch.

Results

Held-out mechanical parts under the paper's evaluation procedure (five attempts per domain at a doubled move budget with a split-and-continue repair, averaged over evaluation seeds). Excess is the median number of irregular vertices above par. At par counts domains meshed provably optimally.

96 domains, 8–24 corners

Method	all-quad	usable	excess	at par
Gmsh blossom	51	38	9	0
Gmsh frontal-quad	43	29	8	1
Gmsh quasi-structured	96	96	7.5	2
Gmsh blossom-full	96	96	26	0
This model	96.0	95.7	0	90.2

64 domains, 25–50 corners (twice the training size, no retraining)

Method	all-quad	usable	excess	at par
Gmsh blossom	26	18	39	0
Gmsh frontal-quad	15	14	34	0
Gmsh quasi-structured	64	60	22	0
Gmsh blossom-full	64	64	156	0
This model	64.0	62.0	0.75	31.0

Gmsh blossom and frontal-quad run at the agent's element count. Quasi-structured and blossom-full run at their natural sizes, 3–15× the agent's. Curved-boundary results (at par on 37 of 96 curved domains, none seen in training) and the full tables are in the paper.

Limitations

• Reproducing the tables: the evaluation domains come from geo2d, which has not been released yet. The repository ships a stand-in generator (tools/geo2d_lite) that runs everything, but it draws different domains from the paper's, so it does not reproduce the tables above.
• Scope: the agent meshes 2D domains only. It was trained on straight-sided domains of up to 24 corners, with up to two holes. Curved boundaries need the test-time repair search described in the paper.
• Pickle: the checkpoint is a Stable-Baselines3 zip, which contains pickled objects. Load it only from a source you trust.

Citation

@article{narayanan2026playing,
  title   = {Playing to Par: Reinforcement Learning for Provably Optimal
             Quadrilateral Block Decompositions},
  author  = {Narayanan, Arjun and Persson, Per-Olof},
  journal = {arXiv preprint arXiv:2609.32146},
  year    = {2026}
}