PyGeoX: Programmable Geometric DSL

• PyGeoX is a programmable geometric DSL that translates natural language descriptions into Python programs generating exact geometric configurations.
• The system integrates a benchmark suite with approximately 100k synthetic problems and employs symbolic compilation for precise, differentiable constraint evaluation.
• It utilizes Saturating Additive Rewards (SAR) to mitigate outlier gradient masking, improving reinforcement learning performance on complex geometric constraints.

PyGeoX is a programmable geometric DSL and research stack for precision-critical geometric synthesis from natural language. It is introduced in "Internalizing Geometric Law: Learning from Solver Residuals for Precision-Critical Generation" (Cabral et al., 8 Jun 2026) as a system with three tightly coupled parts: a geometric DSL and engine that compiles declarative constraints into a differentiable residual vector and scalar loss, a benchmark-and-data pipeline consisting of PyGeoX-Bench and approximately 100k synthetic problems, and a reward design called Saturating Additive Rewards (SAR). In this formulation, PyGeoX serves both as a data generation engine and as an RL environment, targeting problems in which a LLM must generate exact numeric coordinates and radii that satisfy interacting geometric constraints rather than merely produce a plausible-looking diagram.

1. Definition and system composition

PyGeoX is designed around open-ended geometric synthesis from natural language, with the model required to generate a Python program whose output specifies a geometric configuration satisfying all stated relationships and property constraints (Cabral et al., 8 Jun 2026). The paper positions this as a response to precision hallucination in technical diagramming, CAD and parametric modeling, and kinematic mechanism design: outputs may be syntactically and semantically plausible while violating exact geometric laws such as incidence, perpendicularity, tangency, or metric equalities.

Component	Role	Quantitative detail
PyGeoX engine	Declarative geometry DSL, symbolic compilation, residual evaluation	35 object types, 38 relationships
PyGeoX-Bench	Held-out benchmark for evaluation	300 problems
Synthetic corpus	Training data pipeline	~100k problems

The system is not framed as a fixed-predicate solver alone. A central design goal is expressivity: the DSL supports basic primitives such as Point, Line, Circle, MinorArc, MajorArc, and Angle; polygonal objects including Polygon, CyclicPolygon, and regular polygons up to RegularOctagon; triangle classes such as EquilateralTriangle, IsoscelesTriangle, and RightTriangle; and quadrilateral classes such as Parallelogram, Rectangle, Square, Rhombus, Trapezoid, RightTrapezoid, and Kite (Cabral et al., 8 Jun 2026). Relationships include incidence, perpendicularity, parallels, tangency, polygon centers, rigid motions, containment, congruence, and similarity, while algebraic constraints include eq, neq, gt, lt, geq, and leq.

2. Problem setting: precision-critical geometric synthesis

The target task is to translate a free-form natural-language description into a construction whose entities satisfy dozens of interacting constraints simultaneously (Cabral et al., 8 Jun 2026). The output is continuous and structured: a model must emit exact numeric coordinates for points and radii for circles. This differs from QA-style geometry benchmarks, theorem-proving systems, and visual diagram generation because the objective is not to answer a scalar question, prove a theorem in a discrete proof space, or render an image approximately. The objective is to construct a valid configuration.

The paper emphasizes three sources of difficulty. First, correctness is strict: a candidate solution is considered correct only if the squared $2$-norm of the residual vector is sufficiently small,

$\|\mathbf{r}\|_2^2 < 10^{-3},$

where $\mathbf{r} = [r_1,\dots,r_C]$ is the vector of per-constraint violations (Cabral et al., 8 Jun 2026). Second, the search space is high-dimensional and continuous, since under-constrained geometry often admits infinitely many solutions up to similarity transforms. Third, constraints may be nonlinear and may include equalities, inequalities, and neq, as well as cross-property conditions such as equality between a polygon perimeter and a circle area.

This specification suggests a broader interpretation of PyGeoX as a verifier-centered geometry environment rather than a conventional diagramming tool. The LLM does not call PyGeoX from inside its generated code; instead, PyGeoX runs externally to reconstruct the scene, compute residuals, and supply rewards for learning (Cabral et al., 8 Jun 2026). A common misconception is therefore to treat PyGeoX as a black-box solver API invoked directly by the model. The published setup explicitly avoids that arrangement.

3. DSL, symbolic compilation, and solver mechanics

PyGeoX represents a geometric scene as a graph $G=(V,E)$, where $V$ consists of geometric objects with properties and derived scalars, and $E$ consists of constraints and relationships (Cabral et al., 8 Jun 2026). The interface is organized into three namespaces: scene.add for object instantiation, scene.relate for geometric relationships, and scene.constraint for algebraic constraints over scalar expressions such as distances, areas, angles, and perimeters.

The core technical pipeline is declarative $\rightarrow$ symbolic $\rightarrow$ differentiable. High-level relations are lowered into symbolic equalities and inequalities using SymPy. If $\mathbf{u}$ denotes the vector of all geometric variables, PyGeoX aggregates equalities $E_i(\mathbf{u})=0$, non-strict inequalities $\|\mathbf{r}\|_2^2 < 10^{-3},$0, strict inequalities $\|\mathbf{r}\|_2^2 < 10^{-3},$1, and not-equal constraints $\|\mathbf{r}\|_2^2 < 10^{-3},$2 into the scalar objective

$\|\mathbf{r}\|_2^2 < 10^{-3},$3

The defaults are $\|\mathbf{r}\|_2^2 < 10^{-3},$4 and $\|\mathbf{r}\|_2^2 < 10^{-3},$5 (Cabral et al., 8 Jun 2026).

The compiled objective is accelerated with Numba JIT, with reported speedups of $\|\mathbf{r}\|_2^2 < 10^{-3},$6–$\|\mathbf{r}\|_2^2 < 10^{-3},$7, and solving for reference configurations uses Basin-hopping with local L-BFGS-B refinement (Cabral et al., 8 Jun 2026). To discourage degenerate constructions in which points collapse, the solver may add a separation penalty,

$\|\mathbf{r}\|_2^2 < 10^{-3},$8

The significance of this architecture lies in the fact that PyGeoX exposes per-constraint residuals directly. The system can therefore act not only as a solver for dataset generation but also as a verifier for model-produced code. Each candidate program is executed in a sandbox, returns points and circles dictionaries, and is then evaluated by reconstructing the scene and computing the residual vector $\|\mathbf{r}\|_2^2 < 10^{-3},$9 (Cabral et al., 8 Jun 2026).

4. Residual-based learning and Outlier Gradient Masking

PyGeoX’s principal methodological contribution is the argument that global-norm rewards are poorly suited to RL with solver residuals (Cabral et al., 8 Jun 2026). A natural baseline is to minimize or reward the global error $\mathbf{r} = [r_1,\dots,r_C]$0, for example through

$\mathbf{r} = [r_1,\dots,r_C]$1

with $\mathbf{r} = [r_1,\dots,r_C]$2. The paper identifies the resulting failure mode as Outlier Gradient Masking: a single large residual can make the scalar reward essentially zero, thereby masking learning signal from all other constraints, including those that are nearly satisfied.

The paper contrasts global-norm rewards

$\mathbf{r} = [r_1,\dots,r_C]$3

with Saturating Additive Rewards

$\mathbf{r} = [r_1,\dots,r_C]$4

where $\mathbf{r} = [r_1,\dots,r_C]$5 is monotonically decreasing and $\mathbf{r} = [r_1,\dots,r_C]$6. The instantiation used in the paper is $\mathbf{r} = [r_1,\dots,r_C]$7 with $\mathbf{r} = [r_1,\dots,r_C]$8 (Cabral et al., 8 Jun 2026).

Two formal results clarify the distinction. First, as the number of constraints $\mathbf{r} = [r_1,\dots,r_C]$9 grows, the fraction of residual space producing nontrivial reward tends to $G=(V,E)$0 for global-norm rewards but to $G=(V,E)$1 for SAR. Second, the gradient of a global-norm reward with respect to a single residual depends on the global norm $G=(V,E)$2, whereas the SAR gradient with respect to residual $G=(V,E)$3 depends only on $G=(V,E)$4. This means that local progress on one constraint remains locally visible under SAR.

In practice, the paper does not use pure SAR alone. Instead it defines a composite reward

$G=(V,E)$5

with $G=(V,E)$6, $G=(V,E)$7, and $G=(V,E)$8, bounded overall in $G=(V,E)$9 (Cabral et al., 8 Jun 2026). The dense SAR term supplies shaping, the sparse bonus activates when $V$0, and the degeneracy penalty suppresses trivial or collapsed configurations.

5. Benchmark, data pipeline, and training regime

PyGeoX supports both procedural data generation and benchmark evaluation (Cabral et al., 8 Jun 2026). The synthetic corpus contains approximately 100k problems. The generation pipeline samples objects, relationships, and extra constraints from the DSL vocabulary, uses Qwen3-30B-A3B to expand seeds into full natural-language descriptions plus DSL code, and then uses the PyGeoX solver to compute coordinates, verify non-degeneracy and consistency, and discard failures. Each training sample includes a natural-language description, PyGeoX DSL code, a compiled per-constraint reward function, and a rendered image.

PyGeoX-Bench contains 300 held-out problems stratified by difficulty. The easy tier has one polygon with approximately 13 objects and 8 constraints; the medium tier has two polygons with approximately 15 objects and 10 constraints; and the hard tier has three polygons with approximately 23 objects and 16 constraints (Cabral et al., 8 Jun 2026). PyGeoX-Wild adds 86 out-of-distribution problems from a middle-school geometry benchmark with human-authored text and different constraint combinations. The primary metric is solving rate, defined as the fraction of one-shot generations that satisfy $V$1.

The training setup uses Qwen3-8B as the base model and treats the model as a code agent with access to Python, NumPy, SciPy, and SymPy, a 90-second timeout, and no access to PyGeoX from inside its code (Cabral et al., 8 Jun 2026). Supervised fine-tuning uses 15,666 teacher reasoning traces on medium problems from Qwen3-32B and weights the token-level log-likelihood by normalized reward,

$V$2

Reinforcement learning uses Group Relative Policy Optimization through OpenRLHF, cold-started from the base Qwen3-8B, on 10k medium problems, with $V$3 rollouts per prompt, maximum length 8192 tokens, learning rate $V$4, KL coefficient $V$5, PPO clipping $V$6, and $V$7 (Cabral et al., 8 Jun 2026).

6. Empirical results, limitations, and adjacent usages of the name

The principal empirical finding is that the composite SAR+S+D reward outperforms sparse-only and MSE-based alternatives, especially on the hard tier (Cabral et al., 8 Jun 2026). On PyGeoX-Bench, the base Qwen3-8B achieves solving rates of $V$8 on easy, $V$9 on medium, $E$0 on hard, and $E$1 on wild. Under RL with SAR+S+D, these become $E$2, $E$3, $E$4, and $E$5. RL with Sparse yields $E$6, $E$7, $E$8, and $E$9, whereas RL with MSE+S+D yields $\rightarrow$0, $\rightarrow$1, $\rightarrow$2, and $\rightarrow$3. The hard-tier comparison $\rightarrow$4 versus $\rightarrow$5 is the reported $\rightarrow$6 improvement over MSE-based rewards. The paper also reports that SAR+S+D solves problems in approximately $\rightarrow$7 fewer tokens on average than Sparse RL, and that approximately $\rightarrow$8 of successful hard-tier traces are ruler-and-compass-style constructive derivations rather than brute-force numerical search.

The limitations are explicit. The main experiments are confined to Qwen3-8B; attempts with Qwen3-1.7B and Llama-3.1-8B-Instruct failed because of weak baseline math and instruction following. The current scope is 2D static Euclidean geometry rather than 3D CAD, kinematics, or physical simulation. Running solvers in the RL loop remains computationally expensive, and even 35 object types and 38 relationships do not exhaust engineering-specific design constraints (Cabral et al., 8 Jun 2026). The paper therefore presents PyGeoX as a step toward precision tools rather than a complete engineering verification stack.

The name also sits near other Python-based geometry-related toolchains, and that proximity can invite confusion. A 2021 paper on a Python implementation of a two-dimensional structured mesh generator in generalized coordinates describes a PDE/CFD-oriented workflow based on Parametric Linear Splines, elliptic PDE grid generation, and monoblock and multiblock meshes; explanatory material characterizes this as “exactly the type of functionality one would expect from a PyGeoX-like tool,” but it is a distinct line of work centered on curvilinear mesh generation rather than symbolic geometric synthesis (Naozuka et al., 2021). Likewise, GeoX-Bench evaluates large multimodal models on cross-view geo-localization and pose estimation between panoramic ground views and satellite maps; despite the similarity in naming, it addresses geospatial reasoning rather than constructive Euclidean geometry (Zheng et al., 17 Nov 2025). In the published literature, PyGeoX proper refers to the DSL, benchmark, and residual-based training framework introduced in 2026 (Cabral et al., 8 Jun 2026).