pyna -- Python DYNAmics

pyna (Python DYNAmics) is a research library for dynamical systems and magnetic confinement fusion (MCF) plasma physics. It covers the full workflow from analytic equilibria and field-line tracing to topological island analysis, manifold visualization, and non-resonant torus deformation theory.

Author: Wenyin Wei · PyPI: pyna-chaos · Julia companion: Juna.jl

Production magnetic-field-line tracing belongs in pyna/cyna; downstream projects should call these tracing APIs instead of adding Python RK4 hot loops. See FIELD_LINE_TRACING_POLICY.md.

FPT naming convention: progress_* means a fixed source phase phi_s and a moving endpoint phi_e; evolve_*_cycle_* means a cycle-attached object whose base phase moves, with phi_s and phi_e = phi_s + 2*pi*m moving together. This distinction is part of the public API vocabulary.

✨ Highlights

📦 Installation

# Stable release (PyPI)
pip install pyna-chaos

# Development version
git clone https://github.com/WenyinWei/pyna.git
cd pyna
pip install -e ".[dev]"

# Optional Python-side GPU dependencies (CUDA 12 CuPy stack)
pip install "pyna-chaos[cuda]"

cyna C++ tracing core

pyna._cyna is part of the supported runtime surface, not an optional extra. PyPI releases are built as platform wheels for Linux, Windows, and macOS across CPython 3.9, 3.10, 3.11, 3.12, and 3.13. On those platforms, pip install pyna-chaos should install a wheel with _cyna_ext already included.

If no wheel matches your platform, pip falls back to the source distribution and builds cyna locally with xmake:

pip install pyna-chaos
python -c "import pyna._cyna as c; print(c.is_available())"

For development installs:

git clone https://github.com/WenyinWei/pyna.git
cd pyna
pip install -e ".[dev]"
python -c "import pyna._cyna as c; assert c.is_available(); print(c.get_version())"

Source builds require a C++17 compiler, pybind11 headers, and xmake. If xmake or a compiler is missing, setup.py attempts to bootstrap a minimal toolchain on Windows, macOS, and Linux before building. Set CYNA_SKIP_TOOL_INSTALL=1 in controlled CI images where xmake/compiler provisioning is handled externally. An install that cannot build or load _cyna_ext fails; this prevents downstream projects from silently running without the production tracing backend.

Published PyPI wheels are CPU-only and do not link against CUDA; the wheel CI sets CYNA_WITH_CUDA=0 explicitly. For local source builds, leaving CYNA_WITH_CUDA unset attempts to build an optional runtime CUDA backend when nvcc is available. The main _cyna_ext module remains CPU-only and falls back cleanly if that backend is absent. Set CYNA_WITH_CUDA=0 to force a CPU-only local build, or CYNA_WITH_CUDA=1 to require the CUDA backend build. Check pyna._cyna.cuda_backend_available() at runtime when you need to know whether the optional backend loaded.

🚀 Quick Start

Field-line tracing

from pyna.toroidal.equilibrium.Solovev import solovev_iter_like
from pyna.flt import FieldLineTracer
import numpy as np

eq = solovev_iter_like()

# FieldLineTracer expects f([R, Z, phi]) → [BR, BZ, Bphi]
def solovev_field(y):
    R, Z, phi = y
    BR, BZ = eq.BR_BZ(R, Z)
    return np.array([BR, BZ, eq.Bphi(R)])

tracer = FieldLineTracer(solovev_field)
trajectory = tracer.trace(np.array([2.0, 0.0, 0.0]), 200 * 2 * np.pi)

Poincaré crossings and island chains

import numpy as np
from pyna.flt import FieldLineTracer
from pyna.topo.poincare import PoincareAccumulator, poincare_from_fieldlines
from pyna.topo.section import ToroidalSection

# Canonical section type for topology APIs.
section = ToroidalSection(0.0)
acc = PoincareAccumulator([section])

# or trace directly from field lines
start_pts = np.array([
    [1.8, 0.0, 0.0],
    [2.0, 0.0, 0.0],
    [2.2, 0.0, 0.0],
])
acc = poincare_from_fieldlines(
    field_func=field_func,
    start_pts=start_pts,
    sections=[section],
    t_max=500 * 2 * np.pi,
    backend=tracer,
)
crossings = acc.crossing_array(0)

EAST tokamak manifold visualization

from pyna.toroidal.visual.tokamak_manifold import (
    plot_equilibrium_cross_section,
    plot_poincare_orbits,
    plot_manifold_1d,
)
import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(5, 7))
plot_equilibrium_cross_section(fig, ax, eq)
plot_poincare_orbits(fig, ax, orbits, cmap_by='psi_norm')
plot_manifold_1d(fig, ax, stable_manifold_RZ, unstable=False)
plot_manifold_1d(fig, ax, unstable_manifold_RZ, unstable=True)
plt.savefig("east_manifold.png", dpi=300)

Torus deformation calculation

import numpy as np
from pyna import toroidal

# The package root now exposes the preferred toroidal namespace directly.
non_resonant_deformation_spectrum = toroidal.non_resonant_deformation_spectrum
poincare_section_deformation = toroidal.poincare_section_deformation
mean_radial_displacement = toroidal.mean_radial_displacement
split_radial_perturbation_spectrum = toroidal.split_radial_perturbation_spectrum

# Define perturbation spectrum (m, n, δBr, δBθ, δBφ in T·m)
m = np.array([1, 2, 3])
n = np.array([1, 1, 1])
dBr = np.array([1e-4+0j, 5e-5+0j, 2e-5+0j])
dBth = np.zeros(3, dtype=complex)
dBph = np.zeros(3, dtype=complex)

split = split_radial_perturbation_spectrum(m, n, dBr, iota=0.35)
spec = split.nonresonant_deformation(
    iota=0.35, Bphi=4.5, Btheta=0.3,
    dBth_mn=dBth, dBph_mn=dBph,
)
mean_dr = mean_radial_displacement(delta_iota=1e-4, iota_prime=-0.1)
print(f"Mean radial displacement: {mean_dr:.4f} m")

📂 Module Overview

Core dynamical systems

Toroidal plasma physics (pyna.toroidal)

pyna.toroidal is the toroidal-geometry namespace for coordinates, coils, diagnostics, control helpers, and visualisation.

🔬 Theory

Non-resonant torus deformation

Under an external perturbation δB, each invariant torus (flux surface) deforms analytically. The displacement field δr = (δr, δθ, δφ) is computed in Fourier space via the formula (Theorem 2 of Wei 2025):

(δr)_mn = (δBr)_mn / [i · (mι + n) · Bφ]

For axisymmetric (n = 0) poloidal-field coil perturbations the mean radial shift reduces to:

⟨δr⟩ = −δι / ι'

where δι is the first-order rotational-transform variation. Resonant B^r Fourier components (mι+n=0) are separated for island-width analysis, while non-resonant components drive smooth flux-surface deformation. These results are implemented in pyna.toroidal.torus_deformation.

Poincaré maps & manifolds

A Poincaré section φ = φ₀ turns the continuous field-line flow into an area-preserving 2-D map. Near an X-point the stable (W^s) and unstable (W^u) manifolds intersect transversally, generating the heteroclinic tangle responsible for chaotic transport. pyna.topo provides algorithms to compute, visualize, and measure these structures.

Grad-Shafranov equilibrium

Toroidal MHD equilibrium satisfies ΔψGS = −μ₀R²dp/dψ − F dF/dψ. pyna.toroidal.equilibrium exposes Solov'ev analytic solutions and a numerical GS solver with free-boundary capability.

📚 Documentation

Full documentation (API reference, tutorials, theory notes) is hosted at: https://wenyinwei.github.io/pyna/

🤝 Contributing

Contributions are welcome! Please open an issue or pull request on GitHub.

📄 License

LGPL-3.0-or-later © 2024-2026 Wenyin Wei