veqpy 1.0.0

VEQPy — Veloce EQuilibrium code

English | 中文

Article-specific computation and visualization scripts will be released as a tagged artifact accompanying the first public arXiv version of paper "Zhang2026".

VEQPy

VEQPy is the Python implementation of VEQ (Veloce EQuilibrium), a fast parametric Grad--Shafranov solver for fixed-boundary, axisymmetric tokamak equilibria. It is designed for repeated modeling calls that require low-latency access to continuous fixed-boundary geometry. Unlike grid-map equilibrium solvers whose primary unknowns are two-dimensional flux values, VEQPy solves for MXH-type flux-surface harmonics together with shifted-Chebyshev radial profile/source coefficients. The primary nonlinear system is the finite-dimensional projection of the Grad--Shafranov residual onto this representation; its solution is a continuous equilibrium snapshot that can be resampled, serialized, and diagnosed. Sampled local strong-form residuals and optional collocation polish are used as diagnostics or post-processing on the same representation; they do not redefine the primary solve.

VEQPy is suited to parameter scans, source preprocessing, control-oriented iteration, transport coupling, and surrogate-model workflows. It retains richer two-dimensional shaping and residual diagnostics than low-order shape models, while remaining lighter and easier to reuse than full solver-native equilibrium or reconstruction pipelines.

Feature Overview

• Compact equilibrium representation: fixed-boundary flux surfaces, shaping profiles, and source-related radial profiles are represented by coefficients, with a continuous Equilibrium snapshot produced after the solve.
• Unified source route layer: PF, PP, PI, PJ1, PJ2, and PQ routes map pressure-gradient, toroidal-field, flux-gradient, current-related, or safety-factor information to one finite-dimensional residual assembly.
• Explicit runtime boundary: Grid + OperatorCase -> Operator -> Solver -> Equilibrium separates packed coefficients, runtime workspaces, nonlinear solve orchestration, and post-solve snapshots.
• GEQDSK workflow support: GEQDSK I/O, fixed-boundary fitting from GEQDSK boundaries, snapshot export, flux-surface comparison, and common diagnostics.
• Formula-oriented model objects: Grid, Profile, and Equilibrium use reactive derived properties to store minimal root state and lazily reconstruct geometry and physics diagnostics by formula.

VEQPy is not a free-boundary equilibrium solver and does not aim to replace CHEASE, EFIT, ECOM, DESC, or related tools in contexts that require their own variables, boundary treatments, experimental constraints, solver-native outputs, or solver-native certificates. Its role is a fixed-boundary, continuously parameterized equilibrium solve and geometry-diagnostic layer for repeated calls.

Installation

VEQPy requires Python 3.12 or newer. The recommended source-checkout setup uses a project-local virtual environment. The dev extra installs the runtime dependencies together with pytest, ruff, build, twine, and other development helpers into that environment.

git clone https://github.com/zhangtakeda/veqpy.git
cd veqpy
python3.12 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -e ".[dev]"

For a runtime-only local install, omit the dev extra:

.venv/bin/python -m pip install .

All commands below use .venv explicitly; activating the environment is optional.

Example Workflows

Basic demo:

.venv/bin/python examples/minimal_equilibrium.py

This script builds a smooth fixed-boundary case, solves an equilibrium using PF(psin) source input, writes an Equilibrium JSON snapshot, and generates a flux-surface figure.

GEQDSK demo:

.venv/bin/python examples/geqdsk_workflow.py

This script reads an EFIT-style GEQDSK file, fits it as a VEQPy fixed boundary, solves a PF(psin) case with an Ip constraint using one-dimensional source profiles from the GEQDSK file, and writes a VEQPy-vs-GEQDSK flux-surface comparison figure. Reproducible scripts for manuscript figures will be released in the corresponding tagged artifact package for the first public arXiv version.

Development Checks

.venv/bin/python -m compileall -q veqpy tests examples
.venv/bin/ruff check veqpy tests examples
.venv/bin/python -m pytest

Implementation Documentation

Design patterns and model layer:

• [reactive.md]: minimal root state, formula-derived properties, lazy dependency validation, and snapshot consistency.
• [registry.md]: registry-backed method families, source-route coordinate structure, and dispatch boundaries.
• [serial.md]: root-state serialization, JSON/pickle handlers, and persistence boundaries.
• [model.md]: responsibilities, snapshot boundaries, and diagnostic interfaces for Grid, Profile, Boundary, Geqdsk, and Equilibrium.

Hot-path operator and solver:

• [operator.md]: packed layout, build plan, stage pipeline, and runtime/snapshot separation.
• [solver.md]: nonlinear solve lifecycle, fallback behavior, residual normalization, and collocation polish.

Numerical construction:

• [interpolation.md]: one-dimensional source-data remapping.
• [quadrature.md]: semantics of radial quadrature schemes.
• [calculus.md]: scheme boundaries for radial differentiation and integration matrices.

Paper and Reproducibility Resources

VEQPy is associated with the companion manuscript "VEQ: a fast parametric Grad--Shafranov solver for fixed-boundary tokamak equilibria with flexible source inputs". The article-specific reproduction package will be released as a tagged artifact accompanying the first public arXiv version. It will include figure scripts, benchmark scripts, GEQDSK inputs or generation scripts, rendered figures, and dependency metadata.

Related VEQ-family and representation papers include:

• Huasheng Xie and Yueyan Li, "What Is the Minimum Number of Parameters Required to Represent Solutions of the Grad-Shafranov Equation?", arXiv:2601.02942, 2026. https://arxiv.org/abs/2601.02942
• Xingyu Li, Huasheng Xie, Lai Wei, and Zhengxiong Wang, "Investigation of Toroidal Rotation Effects on Spherical Torus Equilibria using the Fast Spectral Solver VEQ-R", arXiv:2602.11422, 2026. https://arxiv.org/abs/2602.11422

---

License:
BSD 3-Clause License

Maintainer (rhzhang):
Homepage - https://zhangtakeda.github.io
Email - [e-mail]
            [e-mail]