pyna.topo.toroidal_cycle

Toroidal periodic-orbit traces and Newton solvers.

This module is explicitly for toroidal field-line dynamics parameterised by phi. It stores sampled toroidal periodic-orbit traces and provides Newton search utilities in (R, Z, phi).

Classes

ToroidalPeriodicOrbitTrace

A periodic field-line orbit.

Functions

poincare_map_n(→ Tuple[float, float])	Integrate field line for n toroidal turns, return final (R, Z).
poincare_map_n_trajectory(→ numpy.ndarray)	Integrate field line for n_turns, return full (R, Z, phi) trajectory.
jacobian_of_poincare_map(→ numpy.ndarray)	Finite-difference Jacobian ∂(R_f, Z_f)/∂(R_0, Z_0) of n-turn Poincaré map.
find_cycle(→ Optional[ToroidalPeriodicOrbitTrace])	Find a periodic orbit starting from init_rzphi using Newton-Raphson.
find_all_cycles_near_resonance(→ list)	Find all O- and X-point cycles near the q=m/n resonant surface.

Module Contents

class pyna.topo.toroidal_cycle.ToroidalPeriodicOrbitTrace

A periodic field-line orbit.

rzphi0

Starting point (R, Z, phi0).

Type:

ndarray, shape (3,)

period_m

Number of toroidal turns (period of Poincaré map). Corresponds to m in q=m/n notation: P^m(x) = x.

Type:

int

trajectory

Full orbit trajectory (R, Z, phi).

Type:

ndarray, shape (N, 3)

DPm

Monodromy matrix DPm = DX_pol(phi_end), phi_end = 2π·m. Eigenvalues characterize stability.

Type:

ndarray, shape (2, 2)

rzphi0: numpy.ndarray

period_m: int

trajectory: numpy.ndarray

DPm: numpy.ndarray

property period_n: int

Alias for period_m (backward compatibility).

property Jac: numpy.ndarray

Deprecated alias for DPm.

property is_stable: bool

True if |eigenvalues| ≤ 1 (elliptic, O-point type).

property eigenvalues: numpy.ndarray

property stability_index: float

Tr(DPm)/2 for a 2x2 symplectic map. |k|<1 → elliptic, |k|>1 → hyperbolic.

property kind: str

X, O, P, or U.

Type:

Return determinant-checked monodromy kind

section_cut(section) → list

Return the point(s) at which this orbit crosses a toroidal section.

Parameters:

section (float | ToroidalSection) – Toroidal section angle (radians) or a concrete ToroidalSection.

Returns:

• list of dict, each with keys 'R', 'Z', 'phi', 'kind'.

• Returns an empty list if the trajectory is not available or no

• crossing is found within tolerance.

diagnostics() → dict

pyna.topo.toroidal_cycle.poincare_map_n(field_func: Callable, rzphi0, n_turns: int, dt: float = 0.05, RZlimit: Tuple | None = None) → Tuple[float, float]

Integrate field line for n toroidal turns, return final (R, Z).

The integration uses the toroidal angle φ as the independent variable.

Parameters:

• field_func (callable) – field_func(rzphi) → (dR/dl, dZ/dl, dphi/dl).

• rzphi0 (array-like (3,)) – Starting point (R, Z, phi).

• n_turns (int) – Number of toroidal turns to integrate (φ increases by 2π·n_turns).

• dt (float) – Step size in φ (radians) for the integrator.

• RZlimit (tuple or None) – Optional (R_min, R_max, Z_min, Z_max) domain boundary.

Returns:

(R_final, Z_final) or (nan, nan) if field left domain.

pyna.topo.toroidal_cycle.poincare_map_n_trajectory(field_func: Callable, rzphi0, n_turns: int, dt: float = 0.05, RZlimit: Tuple | None = None) → numpy.ndarray

Integrate field line for n_turns, return full (R, Z, phi) trajectory.

pyna.topo.toroidal_cycle.jacobian_of_poincare_map(field_func: Callable, rzphi0, n_turns: int, dt: float = 0.05, eps: float = 1e-05) → numpy.ndarray

Finite-difference Jacobian ∂(R_f, Z_f)/∂(R_0, Z_0) of n-turn Poincaré map.

Parameters:

• field_func (callable)

• rzphi0 (array-like (3,))

• n_turns (int)

• dt (float) – Integration step size.

• eps (float) – Finite-difference perturbation.

Returns:

DPm (ndarray, shape (2, 2)) – Monodromy matrix (Jacobian of the n-turn Poincaré map). det(DPm) ≈ 1 for area-preserving.

pyna.topo.toroidal_cycle.find_cycle(field_func: Callable, init_rzphi: numpy.ndarray, n_turns: int = 1, dt: float = 0.05, RZlimit: Tuple | None = None, max_iter: int = 50, tol: float = 1e-08, n_fallback_seeds: int = 12, fallback_radius: float = 0.05) → ToroidalPeriodicOrbitTrace | None

Find a periodic orbit starting from init_rzphi using Newton-Raphson.

G(x0) = P^n(x0) - x0 = 0

If Newton diverges or leaves domain, automatically tries n_fallback_seeds alternative starting points distributed on a circle of radius fallback_radius around init_rzphi.

Parameters:

• field_func (callable) – Field function f(rzphi) → (dR/dl, dZ/dl, dphi/dl).

• init_rzphi (array (3,)) – Initial guess (R0, Z0, phi0).

• n_turns (int) – Period (number of toroidal turns).

• dt (float) – Integration step size in φ.

• RZlimit (tuple or None) – Domain limits (R_min, R_max, Z_min, Z_max).

• max_iter (int) – Maximum Newton iterations.

• tol (float) – Convergence tolerance on |G(x0)|.

• n_fallback_seeds (int) – Number of fallback seeds to try if primary Newton fails.

• fallback_radius (float) – Radius around init_rzphi for fallback seeds.

Returns:

ToroidalPeriodicOrbitTrace or None if not found.

pyna.topo.toroidal_cycle.find_all_cycles_near_resonance(field_func: Callable, equilibrium, m: int, n: int, n_seeds: int = 8, dt: float = 0.05, RZlimit: Tuple | None = None) → list

Find all O- and X-point cycles near the q=m/n resonant surface.

For a q = m/n resonance, there are m O-points and m X-points at equally spaced angular positions around the resonant surface. This function seeds the Newton-Raphson solver at 2·m·n_seeds angular positions around the resonant flux surface and deduplicates the resulting orbits.

Parameters:

• field_func (callable)

• equilibrium (StellaratorSimple or similar) – Must have resonant_psi(m, n) and R0, r0 attributes.

• m (int) – Mode numbers defining the resonance q = m/n.

• n (int) – Mode numbers defining the resonance q = m/n.

• n_seeds (int) – Number of angular seeds per expected fixed point.

• dt (float) – Integration step.

• RZlimit (tuple or None)

Returns:

list of ToroidalPeriodicOrbitTrace