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

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

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

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}
}