--- title: 'PyGeoX: Programmable Geometric DSL' url: https://www.emergentmind.com/topics/pygeox type: topic --- # PyGeoX: Programmable Geometric DSL 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" [2606.09278] 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 language model 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 [2606.09278]. 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` [2606.09278]. 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 [2606.09278]. 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 [2606.09278]. 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 language model does not call PyGeoX from inside its generated code; instead, PyGeoX runs externally to reconstruct the scene, compute residuals, and supply rewards for learning [2606.09278]. 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 [2606.09278]. 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 \(G_j(\mathbf{u})\ge 0\), strict inequalities \(S_k(\mathbf{u})>0\), and not-equal constraints \(N_\ell(\mathbf{u})\neq 0\) into the scalar objective $$ \mathcal{E}(\mathbf{u}) = \alpha \sum_i E_i(\mathbf{u})^2 + \beta \sum_j \max(0, -G_j(\mathbf{u}))^2 + \beta \sum_k \max(0, \epsilon - S_k(\mathbf{u}))^2 + \gamma \sum_\ell \mathds{1}_{|N_\ell(\mathbf{u})| < \epsilon}. $$ The defaults are \(\alpha=\beta=\gamma=1.0\) and \(\epsilon=10^{-4}\) [2606.09278]. The compiled objective is accelerated with Numba JIT, with reported speedups of \(10\)–\(50\times\), and solving for reference configurations uses Basin-hopping with local L-BFGS-B refinement [2606.09278]. To discourage degenerate constructions in which points collapse, the solver may add a separation penalty, $$ \mathcal{L}_{\text{sep}} = \delta \sum_{i \ne j} \max(0, d_{\min}^2 - \|p_i - p_j\|^2). $$ 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}\) [2606.09278]. ## 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 [2606.09278]. A natural baseline is to minimize or reward the global error \(\|\mathbf{r}\|_2^2\), for example through $$ \mathcal{R}_{\text{MSE}}(\mathbf{r}) = \exp\bigl(-\|\mathbf{r}\|_2^2 / T_{\text{mse}}\bigr), $$ with \(T_{\text{mse}}=10\). 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 $$ \mathcal{R}_G(\mathbf{r}) = \phi(\|\mathbf{r}\|_p) $$ with **Saturating Additive Rewards** $$ \mathcal{R}_{\text{SAR}}(\mathbf{r}) = \sum_{i=1}^C \phi(r_i), $$ where \(\phi:\mathbb{R}_{\ge 0}\to[0,1]\) is monotonically decreasing and \(\lim_{r\to\infty}\phi(r)=0\). The instantiation used in the paper is \(\phi(r)=e^{-r/T}\) with \(T=0.1\) [2606.09278]. Two formal results clarify the distinction. First, as the number of constraints \(C\) grows, the fraction of residual space producing nontrivial reward tends to \(0\) for global-norm rewards but to \(1\) for SAR. Second, the gradient of a global-norm reward with respect to a single residual depends on the global norm \(L=\|\mathbf{r}\|_p\), whereas the SAR gradient with respect to residual \(r_i\) depends only on \(r_i\). 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 $$ \mathcal{R} = \frac{w}{C} \sum_{i=1}^{C} e^{-r_i/T} + \mathbb{I}_{\text{suc}} \cdot R_{\text{bonus}} - \min(4, C_{\text{deg}}), $$ with \(w=6.0\), \(T=0.1\), and \(R_{\text{bonus}}=4.0\), bounded overall in \([-4,10]\) [2606.09278]. The dense SAR term supplies shaping, the sparse bonus activates when \(\|\mathbf{r}\|_2^2<10^{-3}\), 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 [2606.09278]. 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 [2606.09278]. 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 \(\|\mathbf{r}\|_2^2<10^{-3}\). 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 [2606.09278]. 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, $$ \mathcal{L} = -\sum_i \tilde{\mathcal{R}}_i \sum_j \log p(y_{i,j}\mid y_{i,