essos.coils¶

Classes¶

`Curves`	Class to store the curves
`Coils`	Class to store the coils
`DiscretizedCoils`	Class to store coils from gamma (discretized curve coordinates) instead of Fourier coefficients

Functions¶

`_static_scale`(value)	A concrete scale as a Python float, so pytree metadata compares and hashes.
`_initialize_currents_scale`(currents, currents_scale)	Return a fixed current scale for normalized current dofs.
`_normalize_base_currents`(currents, curves)	Return base currents as a 1D array matching the number of base curves.
`_currents_as_array`(currents)
`_initialize_scale_fixed`(gamma, scale_fixed)	Return a fixed geometry scale for normalized gamma dofs.
`CreateEquallySpacedCurves`(→ Curves)	Creates n_curves equally spaced on a torus of major radius R and minor radius r using Fourier
`RotatedCurve`(curve, phi, flip)
`apply_symmetries_to_curves`(base_curves, nfp, stellsym)
`apply_symmetries_to_gammas`(base_gammas, nfp, stellsym)
`apply_symmetries_to_currents`(base_currents, nfp, stellsym)
`_resample_closed_curve_uniform_one`(→ jax.numpy.ndarray)	One-curve arclength resample to n_segments points on t∈[0,1), piecewise linear.
`_resample_closed_curve_uniform_batch`(→ jax.numpy.ndarray)	Batch arclength resample.
`_fit_real_fourier_batch`(→ jax.numpy.ndarray)	gamma_uni: (Ncoils, Nseg, 3), samples at t_j = j/Nseg, j=0..Nseg-1
`fit_dofs_from_coils`(→ tuple[jax.numpy.ndarray, ...)	Fast path (batched + JIT + rFFT).

Module Contents¶

class essos.coils.Curves(dofs: jax.numpy.ndarray, n_segments: int = 100, nfp: int = 1, stellsym: bool = True, scaling_type: int = 2, scaling_factor: float = 0.0, scale_fixed: float = 1.0)¶

Class to store the curves

dofs¶

Fourier Coefficients of the base curves

Type:: jnp.ndarray - shape (n_base_curves, 3, 2*order+1)

n_segments¶

Number of segments to discretize the curves

Type:: int

quadpoints¶

Quadrature points used to discretize the curves

Type:: jnp.ndarray - shape (n_segments,)

nfp¶

Number of field periods

Type:: int

stellsym¶

Stellarator symmetry

Type:: bool

order¶

Order of the Fourier series

Type:: int

n_base_curves¶

Number of base curves before applying symmetries

Type:: int

curves¶

Curves obtained by applying rotations and flipping corresponding to nfp fold rotational symmetry and optionally stellarator symmetry

Type:: jnp.ndarray - shape (n_base_curves*nfp*(1+stellsym), 3, 2*order+1)

gamma¶

Discretized curves

Type:: jnp.ndarray - shape (n_curves, n_segments, 3)

gamma_dash¶

Discretized curves derivatives

Type:: jnp.ndarray - shape (n_curves, n_segments, 3)

gamma_dashdash¶

Discretized curves second derivatives

Type:: jnp.ndarray - shape (n_curves, n_segments, 3)

_initialize_state(dofs, n_segments, nfp, stellsym, scaling_type, scaling_factor, scale_fixed, order=None)¶

static _normalize_scaling_type(scaling_type)¶: Map public scaling_type inputs to norm orders used internally.

static _compute_mode_scaling(order, scaling_type, scaling_factor, scale_fixed)¶

reset_cache()¶

property dofs¶

property dof_names¶: Names ordered exactly like dofs flattened in C order.

with_dofs(dofs)¶: Return a differentiable copy with new public curve dofs.

property n_segments¶

property nfp¶

property stellsym¶

property scaling_type¶

property scaling_factor¶

property scale_fixed¶

property scaling¶: Mode-by-mode scaling scale_fixed * exp(scaling_factor * ||mode_orders||).

property order¶

property n_base_curves¶

property curves¶

_compute_gamma()¶

property gamma¶

_compute_gamma_dash()¶

property gamma_dash¶

_compute_gamma_dashdash()¶

property gamma_dashdash¶

property length¶

static compute_curvature(gammadash, gammadashdash)¶

property curvature¶

copy()¶

__str__()¶

__repr__()¶

__len__()¶

__getitem__(key)¶

__add__(other)¶

__contains__(other)¶

__eq__(other)¶

__ne__(other)¶

__iter__()¶

__next__()¶

save_curves(filename: str)¶: Save the curves to a file

to_simsopt()¶

plot(ax=None, show=True, plot_derivative=False, close=False, axis_equal=True, color='brown', linewidth=3, label=None, **kwargs)¶

to_vtk(filename: str, close: bool = True, extra_data=None)¶

classmethod from_simsopt(simsopt_curves, nfp=1, stellsym=True, scaling_type=2, scaling_factor=0.0, scale_fixed=1.0)¶

Create a Curves object from a list of simsopt curves. This assumes curves have all nfp and stellsym symmetries.

Parameters:

scaling_type – accepted values are 'L1' or 1, 'L2' or 2, and 'Linfty' or -1.
scaling_factor – exponential weight used in the mode scaling.
scale_fixed – fixed multiplier applied to all modes.

Note

The norm choice is kept consistent with surfaces, but for the current 1D mode-order scaling it does not change the numerical scaling.

_tree_flatten()¶

classmethod _tree_unflatten(aux_data, children)¶

essos.coils._static_scale(value)¶: A concrete scale as a Python float, so pytree metadata compares and hashes.

essos.coils._initialize_currents_scale(currents, currents_scale)¶: Return a fixed current scale for normalized current dofs.

essos.coils._normalize_base_currents(currents, curves)¶: Return base currents as a 1D array matching the number of base curves.

essos.coils._currents_as_array(currents)¶

essos.coils._initialize_scale_fixed(gamma, scale_fixed)¶: Return a fixed geometry scale for normalized gamma dofs.

class essos.coils.Coils(curves: Curves, currents: jax.numpy.ndarray, currents_scale=None)¶

Class to store the coils

curves¶

Curves object storing the coil geometry

Type:: Curves

dofs_currents_raw¶

Non-normalized currents of the base curves

Type:: jnp.ndarray - shape (n_base_curves,)

currents_scale¶

Normalization factor for the currents

Type:: float

dofs_currents¶

Normalized currents of the base curves

Type:: jnp.ndarray - shape (n_base_curves,)

currents¶

Currents obtained by applying symmetries to the base currents

Type:: jnp.ndarray - shape (n_base_curves * nfp * (1 + stellsym),)

dofs_curves¶

Degrees of freedom of the curves

Type:: jnp.ndarray - shape (n_base_curves, 3, 2*order+1)

dofs¶

Degrees of freedom of the coils (curves and normalized currents)

Type:: jnp.ndarray - shape (n_base_curves * 3 * (2 * order + 1) + n_base_curves,)

_initialize_state(curves, currents_raw, currents_scale)¶

reset_cache()¶

property dofs_curves¶

property dofs_currents_raw¶

property currents_scale¶

property dofs_currents¶

property dofs¶

property dof_names¶: Names ordered exactly like the combined curve/current dofs.

with_dofs(dofs)¶: Return a differentiable copy with new curve and current dofs.

property x¶

property currents¶

property gamma¶

property gamma_dash¶

property gamma_dashdash¶

property length¶

property curvature¶

property nfp¶

property stellsym¶

property order¶

property n_segments¶

copy()¶

__str__()¶

__repr__()¶

__len__()¶

__getitem__(key)¶

__add__(other)¶

__exclude_coil__(index)¶

__contains__(other)¶

__eq__(other)¶

save_coils(filename: str, text='')¶: Save the coils to a file

to_simsopt()¶

to_json(filename: str)¶

Save coils to JSON with proper scaling metadata.

Saves raw unscaled DOFs (_dofs) along with all scaling parameters to ensure perfect reconstruction on load.

plot(*args, **kwargs)¶

to_vtk(*args, **kwargs)¶

to_mgrid(filename: str, **kwargs)¶: Write this coil field to a VMEC MGRID file; see essos.mgrid.coils_to_mgrid().

classmethod from_simsopt(simsopt_coils, nfp=1, stellsym=True, scaling_type=2, scaling_factor=0.0, scale_fixed=1.0)¶

Create coils from simsopt coils.

This assumes coils have all nfp and stellsym symmetries.

Parameters:

scaling_type – accepted values are 'L1' or 1, 'L2' or 2, and 'Linfty' or -1.
scaling_factor – exponential weight used in the mode scaling.
scale_fixed – fixed multiplier applied to all curve modes.

classmethod from_json(filename: str)¶

Load coils from JSON with proper scaling metadata.

Supports both new format (with raw DOFs and scaling) and legacy format (with scaled DOFs) for backward compatibility. The scaling metadata includes scaling_type, scaling_factor, and scale_fixed.

_tree_flatten()¶

classmethod _tree_unflatten(aux_data, children)¶

essos.coils.CreateEquallySpacedCurves(n_curves: int, order: int, R: float, r: float, n_segments: int = 100, nfp: int = 1, stellsym: bool = False, scaling_type: int = 2, scaling_factor: float = 0, scale_fixed: float = 1.0) → Curves¶

Creates n_curves equally spaced on a torus of major radius R and minor radius r using Fourier representation up to the specified order.

Parameters:

scaling_type – accepted values are 'L1' or 1, 'L2' or 2, and 'Linfty' or -1.
scaling_factor – exponential weight used in the mode scaling.
scale_fixed – fixed multiplier applied to all modes.

Note

The norm choice is kept consistent with surfaces, but for the current 1D mode-order scaling it does not change the numerical scaling.

essos.coils.RotatedCurve(curve, phi, flip)¶

essos.coils.apply_symmetries_to_curves(base_curves, nfp, stellsym)¶

essos.coils.apply_symmetries_to_gammas(base_gammas, nfp, stellsym)¶

essos.coils.apply_symmetries_to_currents(base_currents, nfp, stellsym)¶

essos.coils._resample_closed_curve_uniform_one(g: jax.numpy.ndarray, n_segments: int) → jax.numpy.ndarray¶: One-curve arclength resample to n_segments points on t∈[0,1), piecewise linear. g: (M,3) closed curve (first≈last not required; we close internally). Returns: (n_segments,3)

essos.coils._resample_closed_curve_uniform_batch(gammas: jax.numpy.ndarray, n_segments: int) → jax.numpy.ndarray¶: Batch arclength resample. gammas: (Ncoils, M, 3) (all curves same M; if not, pre-interp in index space). Returns: (Ncoils, n_segments, 3)

essos.coils._fit_real_fourier_batch(gamma_uni: jax.numpy.ndarray, order: int) → jax.numpy.ndarray¶: gamma_uni: (Ncoils, Nseg, 3), samples at t_j = j/Nseg, j=0..Nseg-1 Returns dofs: (Ncoils, 3, 2*order+1) with [a0, sin1, cos1, …, sinK, cosK].

essos.coils.fit_dofs_from_coils(coils_gamma: jax.numpy.ndarray, order: int, n_segments: int, assume_uniform: bool = False) → tuple[jax.numpy.ndarray, jax.numpy.ndarray]¶

Fast path (batched + JIT + rFFT). coils_gamma: (Ncoils, M, 3) JAX array. If M != n_segments and assume_uniform=True,

curves are uniformly subsampled in index space. If assume_uniform=False, do arclength resampling (slower but accurate).

Returns:: (Ncoils, 3, 2*order+1) gamma_resampled: (Ncoils, n_segments, 3)
Return type:: dofs

class essos.coils.DiscretizedCoils(gamma: jax.numpy.ndarray, currents: jax.numpy.ndarray, nfp: int = 1, stellsym: bool = False, currents_scale=None, scale_fixed=None)¶

Class to store coils from gamma (discretized curve coordinates) instead of Fourier coefficients

This class is compatible with the Coils class but stores dofs as the actual gamma values rather than Fourier expansion coefficients. Derivatives are computed numerically.

dofs_gamma¶

Base discretized curves (dofs)

Type:: jnp.ndarray - shape (n_base_curves, n_segments, 3)

gamma¶

Discretized curves after symmetry expansion

Type:: jnp.ndarray - shape (n_curves, n_segments, 3)

currents¶

Currents after symmetry expansion

Type:: jnp.ndarray - shape (n_curves,)

n_segments¶

Number of segments in the discretization

Type:: int

nfp¶

Number of field periods

Type:: int

stellsym¶

Stellarator symmetry

Type:: bool

dofs_currents_raw¶

Non-normalized base currents

Type:: jnp.ndarray - shape (n_base_curves,)

currents_scale¶

Normalization factor for the currents

Type:: float

dofs_currents¶

Normalized base currents

Type:: jnp.ndarray - shape (n_base_curves,)

_gamma¶

_dofs_currents_raw¶

_n_segments¶

_nfp = 1¶

_stellsym = False¶

_scale_fixed¶

_gamma_dash = None¶

_gamma_dashdash = None¶

_length = None¶

_curvature = None¶

_currents_scale¶

_dofs_currents = None¶

_currents = None¶

reset_cache()¶

property dofs_gamma¶

property gamma¶

property n_segments¶

property n_base_curves¶

property nfp¶

property stellsym¶

property scale_fixed¶

property dofs_currents_raw¶

property currents_scale¶

property dofs_currents¶

property currents¶

property dofs¶

property x¶

_compute_gamma_dash()¶: Compute first derivative using finite differences on periodic curve

_compute_gamma_dashdash()¶: Compute second derivative using finite differences on periodic curve

property gamma_dash¶

property gamma_dashdash¶

property length¶

static compute_curvature(gammadash, gammadashdash)¶

property curvature¶

copy()¶

__str__()¶

__repr__()¶

__len__()¶

__getitem__(key)¶

__add__(other)¶

__contains__(other)¶

__eq__(other)¶

__ne__(other)¶

__iter__()¶

__next__()¶

save_coils(filename: str, text='')¶: Save the coils to a file

to_json(filename: str)¶: Save coils to JSON file

classmethod from_json(filename: str)¶: Create DiscretizedCoils from JSON file

plot(ax=None, show=True, plot_derivative=False, close=False, axis_equal=True, color='brown', linewidth=3, label=None, **kwargs)¶: Plot the coils

to_vtk(filename: str, close: bool = True, extra_data=None)¶: Export coils to VTK format

to_simsopt()¶: Convert to simsopt coils

classmethod from_simsopt(simsopt_coils, nfp: int = 1, stellsym: bool = False)¶

Create from simsopt coils

Parameters:

simsopt_coils – List of simsopt coils or path to simsopt file
nfp – Number of field periods (default: 1)
stellsym – Stellarator symmetry (default: False)

classmethod from_Coils(coils: Coils)¶: Create from a standard Coils object

to_Coils(order: int = None) → Coils¶

Convert to standard Coils object

Parameters:: order – Fourier order for fitted curves (default: n_segments // 2 - 1)

_tree_flatten()¶

classmethod _tree_unflatten(aux_data, children)¶