spectre.postprocess.main

Module Contents

class spectre.postprocess.main.SPECTREout(filename=None, content=None)

Class for analyzing SPECTRE output, can be created using an output .h5 file or a SPECTRE object. Allows for analysis of the geometry and the Beltrami field(s) for this geometry.

The analysis scripts are in pure Python and based on Numba for speed.

classmethod from_spectre(spectre)

Initialize a SPECTREout object from a SPECTRE object.

Done by reading the data from the SPECTRE object and putting it into the same structure as if it had been read from a .h5 file. This allows for using the same analysis tools on both .h5 files and SPECTRE objects.

For analysis related to the magnetic field, requires the SPECTRE object to have the field information from either a run() or a force_real().

Args:: spectre (SPECTRE): SPECTRE object to be converted to SPECTREout.
Returns:: SPECTREout: SPECTREout object with the data from the SPECTRE object.

inventory(prefix='')

Recursively print all attributes, descending into nested SPECTREout groups.

Each item is printed as a /-separated path mirroring the HDF5 hierarchy (e.g. input/physics/Nvol).

Args:: prefix (str, optional): Path prefix prepended to each item name. Defaults to "".

plot_iota(xaxis='R', yaxis='i', reverse_y_axis=False, ax=None, plot=True, **kwargs)

Iota plots.

Args:

xaxis (str, optional): Choice of x-axis, 'R' (default) or 's'. yaxis (str, optional): Choice of y-axis, 'i' (default) or 'q'. reverse_y_axis (bool, optional): Reverse the y-axis. Defaults to False. ax (matplotlib.axes.Axes, optional): Axes to plot on. Defaults to None. plot (bool, optional): Whether to display the plot. Defaults to True. **kwargs: Additional keyword arguments passed to matplotlib.pyplot.scatter().

Raises:

ValueError: If xaxis or yaxis is not a valid option.

Returns:

tuple:

xdata (numpy.ndarray): x-axis values (coordinate R or flux label s).
ydata (numpy.ndarray): y-axis values (rotational transform \(\iota\) or safety factor q).

plot_jacobian(zetan=0.0, ax=None, **kwargs)

Plot the coordinate Jacobian across all volumes for a given toroidal cross-section.

The Jacobian is shown as a color map on the (R, Z) plane, with interface contours overlaid. The plot title reports the global maximum and minimum values.

Args:

zetan (float, optional): Toroidal angle in units of \(2\pi/N_{fp}\). Defaults to 0. ax (matplotlib.axes.Axes, optional): Axes to plot on. A new figure is created if None.

Defaults to None.

**kwargs: Additional keyword arguments (currently unused).

plot_infaces(surfaces=None, num_theta=400, zetan=0.0, ax=None, shift=0.0, color='r', prange='full', plot_axis=False, plot_comp_bndry=True, **kwargs)

Plot the interfaces and boundary of a SPECTRE equilibrium.

Args:

surfaces (array-like, optional): Indices of surfaces to plot. Defaults to all volumes. num_theta (int, optional): Number of poloidal points used to trace each surface.

Defaults to 400.

zetan (float, optional): Toroidal angle in units of \(2\pi/N_{fp}\). Defaults to 0. ax (matplotlib.axes.Axes, optional): Axes to plot on. Defaults to None. shift (float, optional): Radial shift applied to plotted coordinates. Defaults to 0. color (str, optional): Color of the plotted surfaces. Defaults to 'r'. prange (str, optional): Poloidal range to plot, one of 'full', 'upper', or

'lower'. Defaults to 'full'.

plot_axis (bool, optional): Whether to mark the coordinate axis (geometry 3 only).: Defaults to False.
plot_comp_bndry (bool, optional): Whether to plot the computational boundary when: Lfreebound is set. Defaults to True.

**kwargs: Additional keyword arguments passed to matplotlib.pyplot.plot().

Raises:

ValueError: If prange is not one of 'full', 'upper', or 'lower'. ValueError: If geometry is not 1, 2, or 3.

abstractmethod plot_infaces3D()

plot_field_mod(ivol=0, sarr=None, tarr=None, zarr=0.0, ax=None, colorbar=True, **kwargs)

Plot the magnetic field modulus \(|\vec{B}|\) in a volume at toroidal cross-section.

The field is shown as a color map. Axes and aspect ratio are set automatically based on the geometry (Igeometry 1: slab, 2: cylindrical, 3: toroidal).

Args:

ivol (int, optional): Volume index to evaluate the field in. Defaults to 0. sarr (array-like, optional): Radial coordinate samples in \([-1, 1]\).

Defaults to np.linspace(-0.999, 1, 32).

tarr (array-like, optional): Poloidal angle samples in \([0, 2\pi]\).: Defaults to np.linspace(0, 2\pi, 42).
zarr (float or array-like, optional): Toroidal angle (radians) at which to evaluate: the field. Defaults to 0.
ax (matplotlib.axes.Axes, optional): Axes to plot on. A new figure is created if None.: Defaults to None.
colorbar (bool, optional): Whether to add a colorbar labelled \(|\vec{B}|\).: Defaults to True.

**kwargs: Additional keyword arguments passed to matplotlib.pyplot.pcolormesh().

plot_poincare(zetan=0, prange='full', ax=None, **kwargs)

Plot the Fortran-based Poincaré data for a given toroidal cross-section.

Args:

zetan (float, optional): Toroidal angle in units of \(2\pi/N_{fp}\). Defaults to 0. prange (str, optional): Poloidal range to plot, one of 'full', 'upper', or

'lower'. Defaults to 'full'.

ax (matplotlib.axes.Axes, optional): Axes to plot on. Defaults to None. **kwargs: Additional keyword arguments passed to matplotlib.pyplot.scatter().

Returns:

matplotlib.collections.PathCollection: Return value matplotlib.pyplot.scatter().

plot_pressure(normalize=True, xaxis=None, tarr=None, zarr=None, ax=None, scalar=1.0, **kwargs)

Plot the stepped pressure profile.

Args:

normalize (bool, optional): If True, pressure is plotted in units of \(\mu_0\).: Defaults to True.
xaxis (str, optional): Choice of x-axis, 'tflux' (normalized toroidal flux,: default) or 'x' (major radius coordinate).
tarr (array-like, optional): Poloidal angle samples used when xaxis='x'.: Defaults to np.array([3.0]).
zarr (array-like, optional): Toroidal angle samples used when xaxis='x'.: Defaults to np.array([0.0]).
ax (matplotlib.axes.Axes, optional): Axes to plot on. A new figure is created if None.: Defaults to None.
scalar (float, optional): Multiplicative scaling factor applied to the pressure values.: Defaults to 1.0.

**kwargs: Additional keyword arguments passed to matplotlib.pyplot.plot().

trace_fieldlines(init_pts, num_phi_planes=32, num_transits=1, num_threads=1, batch_size=1, method='RK45', rtol=1e-07, atol=1e-07)

Trace field lines and generate a Poincaré section using the Python-based tracer.

Constructs a Field_Tracer from the equilibrium data, traces all provided initial points, and stores the result in self._tracer.

Args:

init_pts (list of numpy.ndarray): One array per volume, each of shape: (num_trajectories, 2), containing initial \((s, \theta)\) coordinates.
num_phi_planes (int, optional): Number of toroidal planes to record intersections.: Defaults to 32.
num_transits (int, optional): Number of toroidal transits to integrate per fieldline.: Defaults to 1.

num_threads (int, optional): Number of threads for parallel integration. Defaults to 1. batch_size (int, optional): Number of field lines dispatched per thread at a time.

Defaults to 1.

method (str, optional): ODE integrator, one of 'RK23', 'RK45', or 'DOP853'.: Defaults to 'RK45'.

rtol (float, optional): Relative tolerance of the ODE integrator. Defaults to 1e-7. atol (float, optional): Absolute tolerance of the ODE integrator. Defaults to 1e-7.

trace_one_fieldline(sth_init, ivol, num_phi_planes=32, num_transits=1, method='RK45', rtol=1e-07, atol=1e-07)

Trace a single field line from a given starting point.

On the first call a Field_Tracer is constructed from the equilibrium data and cached in self._tracer_single for subsequent calls.

Args:

sth_init (array-like): Initial \((s, \theta)\) coordinates of the field line. ivol (int): Index of the volume in which to start the trace. num_phi_planes (int, optional): Number of toroidal planes where to record intersection.

Defaults to 32.

num_transits (int, optional): Number of full toroidal transits to integrate.: Defaults to 1.
method (str, optional): ODE integrator, one of 'RK23', 'RK45', or 'DOP853'.: Defaults to 'RK45'.

rtol (float, optional): Relative tolerance of the ODE integrator. Defaults to 1e-7. atol (float, optional): Absolute tolerance of the ODE integrator. Defaults to 1e-7.

Returns:

tuple:

sth (array-like) – Final \((s, \theta)\) coordinates.
RZ (array-like) – Final \((R, Z)\) coordinates.
iota (float) – Estimated rotational transform at the final point.
flag (bool) – True if integration terminated early, False if it completed.

property tracer

find_axis(max_repeats=0, guess=None, plot=False, verbose=False)

Find the magnetic axis using root-finding on the field-line return map.

The result is also stored in self.r_magaxis and self.z_magaxis.

Args:

max_repeats (int, optional): Number of additional attempts with random initial guesses: if the root-finder fails. Defaults to 0.
guess (array-like, optional): Initial \((R, Z)\) estimate for the axis location.: Defaults to None.

plot (bool, optional): Whether to plot the root-finding progress. Defaults to False. verbose (bool, optional): Whether to print convergence information. Defaults to False.

Returns:

tuple:

rax (float) – \(R\) coordinate of the magnetic axis.
zax (float) – \(Z\) coordinate of the magnetic axis.
sax (float) – Radial coordinate \(s\) of the axis.
thax (float) – Poloidal angle \(\theta\) of the axis.