pyna.topo.fpt

Functional perturbation theory shift hierarchy for field-line topology.

This module is the public landing zone for perturbative shifts of orbits, trajectories, cycles, invariant tori, and invariant manifolds under a global magnetic-field change. The C++ backend lives in pyna._cyna; this module keeps the mathematical names and the field-cache convention visible.

For a toroidal field-line ODE

dX/dphi = f(X, phi) = (R * BR / BPhi, R * BZ / BPhi),

the first-order shift under a full-field perturbation is

d(delta_X)/dphi = A(X, phi) delta_X + delta_f(X, phi),

where A = partial f / partial (R, Z). delta_X_pol is the zero-initial particular solution. delta_X_cyc is the periodic cycle displacement:

delta_X_cyc(phi) = delta_X_pol(phi) + DP(phi) delta_X_cyc(phi0), (I - DP(T)) delta_X_cyc(phi0) = delta_X_pol(phi0 + T).

For field-period-symmetric stellarators, use T = 2*pi / Nfp for one field-period cycle, so the returned delta_X_cyc should repeat every field period.

Classes

OrbitPerturbationShift	First-order shift data along a traced field-line orbit.
TrajectoryPerturbationShift	Shift of an open trajectory with a specified initial displacement.
CyclePerturbationShift	Shift of a periodic cycle under a full magnetic-field change.
InvariantTorusPerturbationShift	Placeholder for invariant-torus shift solvers.
StableManifoldPerturbationShift	Placeholder for stable/unstable manifold shift solvers.

Functions

compute_cycle_shift(→ CyclePerturbationShift)	Compute cycle FPT shift from cylindrical vector-field objects.
compute_cycle_shift_from_cache(→ CyclePerturbationShift)	Compute delta_X_pol and periodic delta_X_cyc using cyna.

Module Contents

class pyna.topo.fpt.OrbitPerturbationShift

First-order shift data along a traced field-line orbit.

R: numpy.ndarray

Z: numpy.ndarray

phi: numpy.ndarray

DP: numpy.ndarray

delta_X_pol: numpy.ndarray

alive: numpy.ndarray

class pyna.topo.fpt.TrajectoryPerturbationShift

Bases: OrbitPerturbationShift

Shift of an open trajectory with a specified initial displacement.

class pyna.topo.fpt.CyclePerturbationShift

Bases: OrbitPerturbationShift

Shift of a periodic cycle under a full magnetic-field change.

delta_X_pol is the particular solution with zero initial displacement. delta_X_cyc is the periodic physical cycle shift. For an Nfp-periodic stellarator axis cycle, pass phi_span=2*pi/Nfp and verify that delta_X_cyc[-1] matches delta_X_cyc[0].

delta_X_cyc: numpy.ndarray

delta_X_cyc0: numpy.ndarray

property periodic_residual: numpy.ndarray

Return delta_X_cyc(end) - delta_X_cyc(start).

class pyna.topo.fpt.InvariantTorusPerturbationShift(*args, **kwargs)

Placeholder for invariant-torus shift solvers.

The public class is reserved here so callers can discover the intended FPT hierarchy. Fourier/KAM torus-shift implementations should land behind this name instead of creating ad-hoc modules.

class pyna.topo.fpt.StableManifoldPerturbationShift(*args, **kwargs)

Placeholder for stable/unstable manifold shift solvers.

Planned implementation: compute the X-cycle shift, perturb the DPm eigenvalue/eigenvector that defines the X-leg seed direction, deploy seed points with geometric spacing so one P^m image lands just beyond the last seed, advect each seed displacement along the field line, then report the normal component of the displaced manifold arc. The placeholder prevents future agents from creating duplicate one-off stable-manifold perturbation APIs.

pyna.topo.fpt.compute_cycle_shift(R0: float, Z0: float, phi0: float, phi_span: float, base_field: Any, pert_field: Any, *, dphi_out: float = 0.01, DPhi: float = 0.01, fd_eps: float = 0.0001) → CyclePerturbationShift

Compute cycle FPT shift from cylindrical vector-field objects.

base_field and pert_field may be VectorFieldCylind instances, compatible field-like objects, or legacy field-cache dicts.

pyna.topo.fpt.compute_cycle_shift_from_cache(R0: float, Z0: float, phi0: float, phi_span: float, base_field_cache: Any, pert_field_cache: Any, *, dphi_out: float = 0.01, DPhi: float = 0.01, fd_eps: float = 0.0001) → CyclePerturbationShift

Compute delta_X_pol and periodic delta_X_cyc using cyna.

base_field_cache and pert_field_cache may be VectorFieldCylind objects, compatible field-like objects, or legacy field-cache dicts containing BR, BZ, BPhi, R_grid, Z_grid, Phi_grid. Component order is always canonical BR, BZ, BPhi.