Metadata-Version: 2.4
Name: veqpy
Version: 1.0.0
Summary: VEQPy — Veloce EQuilibrium code
Author-email: rhzhang <rhzhang@mail.dlut.edu.cn>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://zhangtakeda.github.io
Project-URL: Repository, https://github.com/zhangtakeda/veqpy
Project-URL: Issues, https://github.com/zhangtakeda/veqpy/issues
Keywords: Grad-Shafranov,equilibrium,fusion,tokamak
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: orjson>=3.9
Requires-Dist: matplotlib>=3.7
Requires-Dist: scipy>=1.17.1
Requires-Dist: numba>=0.64.0
Requires-Dist: rich>=13
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: packaging>=24.2; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: ruff>=0.4; extra == "dev"
Requires-Dist: twine>=6.2; extra == "dev"
Dynamic: license-file

<p align="right">
  <a href="README.md">English</a> |
  <a href="docs/README_CN.md">中文</a>
</p>

<p>
  <img
    align="left"
    src="docs/assets/veqpy_banner.svg"
    alt="VEQPy logo"
  />
</p>

<br clear="left"><br>

[![Python](https://img.shields.io/badge/Python-3.12%2B-blue)](https://www.python.org/)
[![Package](https://img.shields.io/badge/package-veqpy-blue)](https://pypi.org/project/veqpy/)
[![License](https://img.shields.io/badge/License-BSD--3--Clause-green)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-pytest-informational)](tests/)
[![Style](https://img.shields.io/badge/style-ruff-black)](https://docs.astral.sh/ruff/)

> **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.

```bash
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:

```bash
.venv/bin/python -m pip install .
```

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

## Example Workflows

Basic demo:

```bash
.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:

```bash
.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

```bash
.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]](docs/details/reactive.md): minimal root state, formula-derived properties,
  lazy dependency validation, and snapshot consistency.
- [[registry.md]](docs/details/registry.md): registry-backed method families, source-route
  coordinate structure, and dispatch boundaries.
- [[serial.md]](docs/details/serial.md): root-state serialization, JSON/pickle handlers,
  and persistence boundaries.
- [[model.md]](docs/details/model.md): responsibilities, snapshot boundaries, and diagnostic
  interfaces for `Grid`, `Profile`, `Boundary`, `Geqdsk`, and `Equilibrium`.

Hot-path operator and solver:

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

Numerical construction:

- [[interpolation.md]](docs/details/interpolation.md): one-dimensional source-data remapping.
- [[quadrature.md]](docs/details/quadrature.md): semantics of radial quadrature schemes.
- [[calculus.md]](docs/details/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>

---

<p>
<img align="left" src="docs/assets/veqpy_icon.svg" width="150" alt="veqpy logo">

<strong>License</strong>:<br>
<em>BSD 3-Clause License</em><br>

<strong>Maintainer</strong> (rhzhang):<br>
<em>Homepage</em> - <em>https://zhangtakeda.github.io</em><br>
<em>Email</em> - <em>rhzhang@mail.dlut.edu.cn</em><br>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<em>zhangtakeda@gmail.com</em><br>

</p>
