array.plasma.analysis

Numerical diagnostics of one labeled xarray.DataArray, as array.plasma.analysis.<method>(...). They return labeled arrays and Datasets, so their results can be plotted with .plasma.plot in turn.

Where the accessors come from

The examples use output of a Struphy Output, which loads plasma-plots and its .plasma accessors. For other xarray data, run import plasma_plots first (see Getting started).

array.plasma.analysis

Quantitative diagnostics of one array, as array.plasma.analysis.<quantity>(...).

growth_rate

growth_ratemethod#

View source

def growth_rate(window: tuple[float | None, float | None] = (None, None), amplitude: bool = False)

Fit exp(rate * t + intercept) to this time series within window.

Parameters

Name	Type	Default	Description
window	(float or None, float or None)	(None, None)	The time interval (t0, t1) of the fitted samples; None for an open end. Default: every sample.
amplitude	bool	False	The series is quadratic in an amplitude (e.g. an energy): return the amplitude’s rate. Default: False.

Returns

FitResult or None

.rate, .intercept, .time and .fitted; None with fewer than two valid samples.

See Also

plasma_plots.analysis.growth_rate() : The function behind this method. ArrayAnalysis.damping_rate() : The same fit to the envelope of an oscillating series. ArrayPlots.timeseries() : The series with the fit drawn (fit=).

Examples

>>> energy.plasma.analysis.growth_rate(window=(0.0, 5.0), amplitude=True).rate

damping_rate

damping_ratemethod#

View source

def damping_rate(window: tuple[float | None, float | None] = (None, None), amplitude: bool = False)

Fit exponential decay to the envelope of this oscillating time series.

Parameters

Name	Type	Default	Description
window	(float or None, float or None)	(None, None)	The time interval (t0, t1) of the peaks that are used; None for an open end. Default: every sample.
amplitude	bool	False	The series is quadratic in an amplitude (e.g. an energy): return the amplitude’s rate. Default: False.

Returns

FitResult or None

The fit to the peaks; the rate is negative for damping. None with fewer than two valid peaks.

See Also

plasma_plots.analysis.damping_rate() : The function behind this method. ArrayAnalysis.growth_rate() : The same fit to the series itself. ArrayAnalysis.envelope() : The peaks that are fitted.

Examples

>>> energy.plasma.analysis.damping_rate(amplitude=True).rate

oscillation_frequency

oscillation_frequencymethod#

View source

def oscillation_frequency(window: tuple[float | None, float | None] = (None, None), method: str = 'zero_crossings', detrend: bool = True)

Measure the frequency of this oscillating time series from its zero crossings or peaks.

Parameters

Name	Type	Default	Description
window	(float or None, float or None)	(None, None)	The time interval (t0, t1) used; None for an open end. Default: every sample.
method	('zero_crossings', 'peaks')	"zero_crossings"	Count the crossings of the mean (half a period apart), or the maxima (a period apart; for a signal that does not cross its mean, e.g. an energy, whose peaks are half the field’s period apart). Default: "zero_crossings".
detrend	bool	True	Subtract the mean over the window first, so that crossings are of the mean. Default: True.

Returns

OscillationFit or None

omega, period and the times of the crossings or peaks used; None with fewer than two.

See Also

plasma_plots.analysis.oscillation_frequency() : The function behind this method. ArrayAnalysis.damping_rate() : The decay of the same oscillation.

Examples

>>> probe.plasma.analysis.oscillation_frequency(window=(5.0, 40.0)).omega

map_coordinate

map_coordinatemethod#

View source

def map_coordinate(dim: str, mapping, *, name: str | None = None, units: str | None = None, label: str | None = None) -> xr.DataArray

Replace a coordinate by a function of it, e.g. eta1 by the minor radius in meters.

Parameters

Name	Type	Default	Description
dim	str	required	The dimension whose coordinate is mapped, e.g. "eta1".
mapping	callable or float	required	A function of the coordinate’s values (lambda eta1: 0.1 + 0.9 * eta1), or a factor (a length, for length * eta1).
name	str	None	The name of the new dimension, e.g. "r". Default: keep dim.
units	str	None	The new coordinate’s units, e.g. "m". Default: none.
label	str	None	The new coordinate’s axis label (its long_name), mathtext allowed. Default: name.

Returns

xarray.DataArray

The array over the new coordinate, which every plot then draws and labels.

See Also

plasma_plots.arrays.map_coordinate() : The function behind this method.

Examples

>>> r_T = T.plasma.analysis.map_coordinate(
...     "eta1", lambda eta1: 0.1 + 0.9 * eta1, name="r", units="m"
... )
>>> r_T.plasma.plot.profiles(x="r", eta2=0, eta3=0)

envelope

envelopemethod#

View source

def envelope() -> xr.DataArray

Return the local maxima of this time series.

Returns

xarray.DataArray

The peaks, over their times t.

See Also

plasma_plots.analysis.envelope() : The function behind this method.

norm

normmethod#

View source

def norm(dims=None, squared: bool = False) -> xr.DataArray

Return the L2 norm over dims (default: every dimension except t).

Parameters

Name	Type	Default	Description
dims	str or sequence of str	None	The dimensions summed over. Default: every dimension except t.
squared	bool	False	Return the squared norm Σ f² instead. Default: False.

Returns

xarray.DataArray

The norm over the remaining dimensions, e.g. t.

See Also

plasma_plots.analysis.norm() : The function behind this method.

Examples

>>> div_B.plasma.analysis.norm()

drift

driftmethod#

View source

def drift(ref=None) -> xr.DataArray

Return the signed deviation of this time series from ref or from its first sample.

Parameters

Name	Type	Default	Description
ref	float or array_like or xarray.DataArray	None	The reference, broadcast against data. Default: data at the first time sample.

Returns

xarray.DataArray

The deviation over t.

See Also

plasma_plots.analysis.drift() : The function behind this method. ArrayAnalysis.relative_error() : The absolute relative deviation.

Examples

>>> energy.plasma.analysis.drift().plasma.plot.timeseries()

relative_error

relative_errormethod#

View source

def relative_error(ref=None, skip_first: bool = True) -> xr.DataArray

Return the absolute relative deviation from ref or from this series’ first sample.

Parameters

Name	Type	Default	Description
ref	float or array_like or xarray.DataArray	None	The reference, broadcast against data; must be non-zero everywhere. Default: data at the first time sample.
skip_first	bool	True	Leave out the first time sample (zero against the default reference). Default: True.

Returns

xarray.DataArray

The relative deviation over t.

See Also

plasma_plots.analysis.relative_error() : The function behind this method. ArrayAnalysis.drift() : The signed deviation.

Examples

>>> energy.plasma.analysis.relative_error(ref=exact_solution)

spatial_average

spatial_averagemethod#

View source

def spatial_average(dims=None) -> xr.DataArray

Return the mean over the logical space dimensions eta1, eta2, eta3 (or dims).

For a binned e1_v1 distribution this is f(v1, t) averaged over space.

Parameters

Name	Type	Default	Description
dims	str or sequence of str	None	The dimensions averaged over. Default: every logical dimension (eta1, eta2, eta3, or GVEC’s rho, theta, zeta) that data has.

Returns

xarray.DataArray

The mean over the remaining dimensions.

See Also

plasma_plots.analysis.spatial_average() : The function behind this method.

Examples

>>> distribution.plasma.analysis.spatial_average()

velocity_moments

velocity_momentsmethod#

View source

def velocity_moments(dims=None) -> xr.Dataset

Return density, mean velocity and variance of a binned distribution over its velocity dimensions.

See plasma_plots.analysis.velocity_moments() for the definitions.

Parameters

Name	Type	Default	Description
dims	str or sequence of str	None	The velocity dimensions integrated over, each with a coordinate of at least two bins. Default: every one of v1, v2, v3 that f has.

Returns

xarray.Dataset

The moments, over the remaining dimensions.

See Also

plasma_plots.analysis.velocity_moments() : The function behind this method.

Examples

>>> distribution.plasma.analysis.velocity_moments()

dispersion

dispersionmethod#

View source

def dispersion(dim: str | None = None, detrend: bool = True) -> xr.DataArray

Return the space-time power spectrum of this (t, dim) field.

A plain FFT, as a function of angular frequency and wavenumber: the data behind a dispersion-relation plot (ArrayPlots.dispersion()). dim defaults to the sole dimension other than t; select every other dimension away first. omega comes out in the angular-frequency units implied by t’s spacing (e.g. rad/s for physical seconds, or a normalized angular frequency for normalized time).

Parameters

Name	Type	Default	Description
dim	str	None	The spatial dimension. Default: the sole dimension other than t.
detrend	bool	True	Remove the time-mean at each point of dim first, which otherwise dominates the spectrum as a spurious zero-frequency line. Default: True.

Returns

xarray.DataArray

The power over omega and the wavenumber.

See Also

plasma_plots.analysis.power_spectrum() : The function behind this method, and the definition. ArrayPlots.dispersion() : The plot of this spectrum. ArrayAnalysis.fit_branches() : Straight branches fitted to it.

Examples

>>> spectrum = E.isel(eta2=0, eta3=0).plasma.analysis.dispersion()

fit_branches

fit_branchesmethod#

View source

def fit_branches(n_branches: int, k_range: tuple[float, float] | None = None, noise_level: float = 0.5, order: int = 10)

Fit straight dispersion branches (omega = v * k) to this (omega, k) power spectrum.

Parameters

Name	Type	Default	Description
n_branches	int	required	The number of branches, at least 1.
k_range	(float, float)	None	The interval of non-negative k’s that are scanned. Default: (k.max() / 8, k.max() / 2), which in practice skips both the low-k region where branches have not yet separated, and the folded Nyquist edge.
noise_level	float	0.5	Maxima count only above this fraction of the column’s peak power. Default: 0.5.
order	int	10	A local maximum must exceed every one of its order neighbors on both sides along omega (out-of-range neighbors are clipped to the edge sample, as in scipy.signal.argrelextrema). Default: 10.

Returns

list of BranchFit

One fit per branch.

See Also

plasma_plots.analysis.fit_dispersion_branches() : The function behind this method. ArrayAnalysis.dispersion() : The spectrum to fit. ArrayAnalysis.trace_branch() : The measured frequency along a curved branch.

Examples

>>> field.plasma.analysis.dispersion().plasma.analysis.fit_branches(
...     n_branches=2
... )

fft

fftmethod#

View source

def fft(dim: str, detrend: bool = False, window: str | None = None) -> xr.DataArray

Return the two-sided Fourier coefficients along dim.

Parameters

Name	Type	Default	Description
dim	str	required	The dimension to transform.
detrend	bool	False	Subtract the mean along dim first. Default: False.
window	(None, 'hann')	None	Multiply by a periodic Hann window (see [hann()][hann]) first. Default: None (boxcar).

Returns

xarray.DataArray

The complex coefficients.

See Also

plasma_plots.spectral.fft() : The function behind this method. ArrayAnalysis.time_fft() : The one-sided transform in time.

Examples

>>> phi.plasma.analysis.fft(dim="eta1")

time_fft

time_fftmethod#

View source

def time_fft(detrend: bool = False, window: str | None = None) -> xr.Dataset

Return the one-sided temporal coefficients and the power per bin.

Parameters

Name	Type	Default	Description
detrend	bool	False	Subtract the temporal mean first. Default: False.
window	(None, 'hann')	None	Multiply by a periodic Hann window (see [hann()][hann]) first. Default: None (boxcar).

Returns

xarray.Dataset

coefficients and power over omega and the other dimensions.

See Also

plasma_plots.spectral.time_fft() : The function behind this method. ArrayPlots.power_spectrum() : The plot of the power.

Examples

>>> phi.plasma.analysis.time_fft(detrend=True)

filter_time

filter_timemethod#

View source

def filter_time(dims=None, omega_min: float = 1e-08, pad_bins: int = 0)

Return the dominant frequency band, reconstructed.

Parameters

Name	Type	Default	Description
dims	str or sequence of str	None	Non-time dimensions to sum the power over before choosing the band. Default: all dimensions except t and component. Pass dims=() for independent filtering at each point.
omega_min	float	1e-08	Finite, positive lowest frequency considered, which excludes DC. Default: 1e-8.
pad_bins	int	0	Nonnegative number of extra bins on each side of the band. Default: 0.

Returns

TimeFilterResult

The band and the reconstructed signal.

See Also

plasma_plots.spectral.filter_time() : The function behind this method. ArrayPlots.filtered() : A probe of the signal against the reconstruction.

Examples

>>> band = phi.plasma.analysis.filter_time(dims=("eta1", "eta2", "eta3"))

band_filter

band_filtermethod#

View source

def band_filter(omega_lo: float, omega_hi: float, *, detrend: bool = False) -> xr.DataArray

Return only the frequencies in [omega_lo, omega_hi].

Parameters

Name	Type	Default	Description
omega_lo	float	required	The lowest angular frequency kept.
omega_hi	float	required	The highest angular frequency kept, at least omega_lo.
detrend	bool	False	Subtract the temporal mean first; the result then has zero mean even if the band includes DC. Default: False.

Returns

xarray.DataArray

The filtered signal, on this array’s grid.

See Also

plasma_plots.spectral.band_filter() : The function behind this method. ArrayAnalysis.filter_time() : The dominant band, found automatically.

Examples

>>> phi.plasma.analysis.band_filter(0.08, 0.11)

spectral_peaks

spectral_peaksmethod#

View source

def spectral_peaks(n_peaks: int = 3, dims=None, omega_min: float = 1e-08, detrend=True, window=None) -> xr.Dataset

Return the strongest spectral peaks, with sub-bin frequencies.

Parameters

Name	Type	Default	Description
n_peaks	int	3	The number of peaks to return at most. Default: 3.
dims	str or sequence of str	None	Dimensions to sum the power over. Default: every dimension but omega. Only omega may remain.
omega_min	float	1e-08	The lowest frequency a peak may have, which excludes DC. Default: 1e-8.
detrend	bool or int	True	For a time series: True subtracts the mean, False nothing, and an integer is the degree of a least-squares polynomial in t removed at every point first. An energy such as LinearMHD’s en_U oscillates at twice the wave frequency around a slow trend, so its peaks with detrend=2 sit at 2 * omega. Ignored for spectra. Default: True.
window	(None, 'hann')	None	Window applied before transforming a time series. Default: None.

Returns

xarray.Dataset

The peaks, strongest first.

See Also

plasma_plots.spectral.spectral_peaks() : The function behind this method. ArrayPlots.power_spectrum() : The spectrum with the peaks labeled (peaks=).

Examples

>>> phi.plasma.analysis.spectral_peaks(n_peaks=2)

spectrogram

spectrogrammethod#

View source

def spectrogram(length, step=None, detrend: bool = True, window: str | None = 'hann') -> xr.DataArray

Return power spectra in sliding time windows.

Parameters

Name	Type	Default	Description
length	int or float	required	The window length: a sample count (integer, 4 to the number of samples) or a time span (float).
step	int or float	None	The shift between windows: a sample count (integer) or a time span (float). Default: a quarter of length.
detrend	bool	True	Subtract each window’s mean. Default: True.
window	('hann', None)	"hann"	The taper of each window, not compensated for. Default: "hann".

Returns

xarray.DataArray

The power over (t, omega, ...), t being each window’s center.

See Also

plasma_plots.spectral.spectrogram() : The function behind this method. ArrayPlots.spectrogram() : The plot of these spectra.

Examples

>>> signal.plasma.analysis.spectrogram(length=200.0, step=10.0)

mode_spectrum

mode_spectrummethod#

View source

def mode_spectrum(dims=None, names=('m', 'n'), periods=None, scale=None) -> xr.DataArray

Return the complex amplitudes over poloidal/toroidal mode numbers.

Parameters

Name	Type	Default	Description
dims	str or sequence of str	None	The periodic dimensions to transform. Default: the two angles of the logical dimensions (see plasma_plots.arrays.logical_dims()), ("eta2", "eta3") for Struphy.
names	str or sequence of str	('m', 'n')	The name of the mode number of each dimension, one per dimension. Default: ("m", "n").
periods	float or sequence of float	None	Each direction’s period in its coordinate: one number for all, or one per dimension. Default: the coordinate’s period attribute (see plasma_plots.arrays.angle_period()), else 1.0.
scale	int or sequence of int	None	Multiplies the mode numbers (one number, or one per dimension; cast to integers), e.g. scale=(1, 6) labels a sixth of a torus (Struphy’s tor_period=6) with full-torus toroidal mode numbers. Default: 2π over the period attribute of an angle (nfp for GVEC’s toroidal angle), else 1.

Returns

xarray.DataArray

The amplitudes over the mode numbers names and every remaining dimension.

See Also

plasma_plots.spectral.mode_spectrum() : The function behind this method. ArrayAnalysis.mode_amplitudes() : Real amplitudes of this spectrum.

Examples

>>> modes = phi.plasma.analysis.mode_spectrum()

mode_amplitudes

mode_amplitudesmethod#

View source

def mode_amplitudes(top: int | None = None, real: bool = True, relative: bool = False) -> xr.DataArray

Return the real amplitudes of this mode spectrum along one mode dimension.

Parameters

Name	Type	Default	Description
top	int	None	Keep only the top modes with the largest peak amplitude over every other dimension, strongest first. Default: all modes.
real	bool	True	The field is real: each (m, n) is combined with its conjugate (-m, -n). Only the half with the first nonzero mode number positive is kept, and its amplitude doubled, so a field A cos(...) gives A. A mode without a twin on the grid (the mean, or the Nyquist mode of an even grid) is kept as it is. Default: True.
relative	bool	False	Divide by the amplitude of the mean (the mode with all numbers zero), which is then left out: e.g. density perturbations relative to the background density, as growth plots of an instability often show. NaN where the mean vanishes. Default: False.

Returns

xarray.DataArray

The amplitudes over mode and every remaining dimension.

See Also

plasma_plots.spectral.mode_amplitudes() : The function behind this method. ArrayAnalysis.mode_spectrum() : The spectrum this is applied to.

Examples

>>> phi.plasma.analysis.mode_spectrum().plasma.analysis.mode_amplitudes(top=4)

mode_structure

mode_structuremethod#

View source

def mode_structure(omega: float, *, window: str | None = 'hann', detrend: bool = True) -> xr.DataArray

Return the complex amplitude at the exact frequency omega at every point.

Parameters

Name	Type	Default	Description
omega	float	required	The angular frequency ω.
window	('hann', None)	"hann"	The weights w(t): a periodic Hann window, or None for uniform weights. Default: "hann".
detrend	bool	True	Subtract the temporal mean at every point first. Default: True.

Returns

xarray.DataArray

The complex amplitude over every dimension but t.

See Also

plasma_plots.spectral.mode_structure() : The function behind this method. ArrayPlots.mode_profiles() : The harmonics of this eigenfunction (omega=).

Examples

>>> phi.plasma.analysis.mode_structure(omega)

cross_spectrum

cross_spectrummethod#

View source

def cross_spectrum(other: xr.DataArray, *, dims=None, detrend: bool = True, window=None) -> xr.Dataset

Return the cross-spectrum, phase (of other relative to this) and coherence.

Parameters

Name	Type	Default	Description
other	xarray.DataArray	required	The second signal, on the same time grid; its phase is relative to this one.
dims	str or sequence of str	None	Dimensions to sum the cross-spectrum over, as an ensemble. Default: none (no coherence).
detrend	bool	True	Subtract each signal’s temporal mean first. Default: True.
window	(None, 'hann')	None	Window applied to both signals before transforming. Default: None.

Returns

xarray.Dataset

The cross-spectrum, phase and (with dims) coherence over omega.

See Also

plasma_plots.spectral.cross_spectrum() : The function behind this method. ArrayPlots.cross_spectrum() : The plot of this spectrum.

Examples

>>> u.plasma.analysis.cross_spectrum(b, dims="eta3")

matrix_pencil

matrix_pencilmethod#

View source

def matrix_pencil(n_modes: int = 1, pencil: int | None = None, detrend: bool = False) -> xr.Dataset

Return frequencies and growth rates beyond the FFT resolution.

Parameters

Name	Type	Default	Description
n_modes	int	1	The number of modes to fit and return: real oscillations for a real signal, complex exponentials for a complex one. The fit needs well over 2 * n_modes samples. Default: 1.
pencil	int	None	The pencil parameter (Hankel matrix width minus one), which trades noise robustness against resolution. Default: N // 2.
detrend	bool	False	Subtract the mean first. Default: False.

Returns

xarray.Dataset

omega, gamma, amplitude and phase along mode, strongest first.

See Also

plasma_plots.spectral.matrix_pencil() : The function behind this method. ArrayPlots.pencil_fit() : The plot of this fit.

Examples

>>> probe.plasma.analysis.matrix_pencil(n_modes=1)

gradient

gradientmethod#

View source

def gradient(domain=None) -> xr.DataArray

Return the Cartesian gradient of this scalar field on a mapped domain.

Parameters

Name	Type	Default	Description
domain	struphy domain	None	The mapping (out.domain), for the exact Jacobian. Default: differentiate the X, Y, Z coordinates numerically.

Returns

xarray.DataArray

The gradient, with a component dimension (x, y, z).

See Also

plasma_plots.analysis.gradient() : The function behind this method.

Examples

>>> phi.plasma.analysis.gradient()

surface_average

surface_averagemethod#

View source

def surface_average(jacobian=None, domain=None, quadrature=None) -> xr.DataArray

Return the flux-surface average of this field over its two angles.

Parameters

Name	Type	Default	Description
jacobian	xarray.DataArray	None	√g on the same grid, e.g. GVEC’s Jac (its absolute value is used). Default: from domain, else the numerical Jacobian of the X, Y, Z coordinates, which needs at least two radial points.
domain	struphy domain	None	The mapping, for the exact √g of a Struphy run.
quadrature	dict	None	Explicit weights for the angles, as for [volume_integral()][volume_integral].

Returns

xarray.DataArray

⟨f⟩ over the radius and every non-spatial dimension.

See Also

plasma_plots.analysis.surface_average() : The function behind this method. DatasetAnalysis.surface_average() : The same, with the Dataset’s Jac.

Examples

>>> ev.mod_B.plasma.analysis.surface_average(jacobian=ev.Jac)

rational_surfaces

rational_surfacesmethod#

View source

def rational_surfaces(count: int = 4, nfp: int | None = None, max_denominator: int = 12) -> xr.DataArray

Return where this rotational transform (or safety factor) profile is a low-order rational.

Parameters

Name	Type	Default	Description
count	int	4	The number of rational values. Default: 4.
nfp	int	None	The numerators are multiples of it. Default: the profile’s nfp attribute (GVEC’s, see plasma_plots.gvec.from_gvec()), else 1.
max_denominator	int	12	The largest m. Default: 12.

Returns

xarray.DataArray

The positions over surface, with the coordinates n, m and value.

See Also

plasma_plots.analysis.rational_surfaces() : The function behind this method. ArrayPlots.lineout() : rationals= marks them on the profile.

Examples

>>> ev.iota.plasma.analysis.rational_surfaces(count=3)

error

errormethod#

View source

def error(exact, *, norm: str = 'rms', relative: bool = False, dims=None, weighted: bool = False, domain=None, args=None) -> xr.DataArray

Return the error against an exact solution (an array or a function of the coordinates).

Parameters

Name	Type	Default	Description
exact	(callable, array_like, number or xarray.DataArray)	required	The exact solution: an array (aligned with data, or broadcast to it) or a function of its coordinates, evaluated with [evaluate_on()][evaluate_on], e.g. lambda x, y, z, t: ....
norm	('rms', 'max', 'l1', 'l2', 'pointwise')	"rms"	"pointwise" is the difference data − exact itself; "max" the largest absolute difference; "l1" the mean (or, weighted, the integral) of |data − exact|; "l2" the square root of the mean (or integral) of |data − exact|²; "rms" (default) as "l2", divided by the volume when weighted.
relative	bool	False	Divide by the same norm of the exact solution; for "pointwise", by the largest |exact| over the whole array. Default: False.
dims	str or sequence of str	None	The dimensions the norm is taken over. Default: every dimension but t. Weighted norms need exactly eta1, eta2, eta3.
weighted	bool	False	Integrate over the physical volume instead of averaging over the grid points (no effect on "max" and "pointwise"). Default: False.
domain	struphy domain	None	The mapping (out.domain), for the exact |√g| of weighted norms. Default: from the X, Y, Z coordinates.
args	sequence of str	None	The coordinates passed to a callable exact, as in [evaluate_on()][evaluate_on]. Default: X, Y, Z (or the logical dimensions), then t.

Returns

xarray.DataArray

The error, over the dimensions not reduced by norm.

See Also

plasma_plots.analysis.error() : The function behind this method.

Examples

>>> T.plasma.analysis.error(exact, relative=True)
>>> T.plasma.analysis.error(exact, norm="max")

project_mode

project_modemethod#

View source

def project_mode(dim: str, number: float, kind: str = 'sin', period: float = 1.0, bin_correction: bool = False) -> xr.DataArray

Return the amplitude of one Fourier mode along dim.

Parameters

Name	Type	Default	Description
dim	str	required	The periodic dimension, e.g. "eta1".
number	float	required	The mode number, not a wavenumber: k = 2π number / L.
kind	('sin', 'cos', 'complex')	"sin"	"sin" (default) gives a of a sin(2π number x / period): 2 ⟨f sin(…)⟩; "cos" the cosine amplitude, and "complex" the complex amplitude 2 ⟨f exp(−i…)⟩ (abs() the amplitude, np.angle() the phase).
period	float	1.0	The period of dim. Default: 1, the logical unit interval.
bin_correction	bool	False	Undo the damping of binned particle data, whose bins average the mode over their width h: divide by sinc(number h / period). Default: False.

Returns

xarray.DataArray

The amplitude over the other dimensions.

See Also

plasma_plots.analysis.project_mode() : The function behind this method.

Examples

>>> rho.plasma.analysis.project_mode(dim="eta2", number=3, kind="complex")

divergence

divergencemethod#

View source

def divergence(components: str = 'cartesian', domain=None) -> xr.DataArray

Return the divergence of this vector field.

Parameters

Name	Type	Default	Description
components	('cartesian', 'contravariant')	"cartesian"	What the components are, as for the 3-D views: "cartesian" (default) (x, y, z), or "contravariant" components, which are pushed forward first.
domain	struphy domain	None	The mapping (out.domain), for the exact Jacobian. Default: from the X, Y, Z coordinates.

Returns

xarray.DataArray

The divergence, without the component dimension.

See Also

plasma_plots.analysis.divergence() : The function behind this method.

Examples

>>> B.plasma.analysis.divergence()

curl

curlmethod#

View source

def curl(components: str = 'cartesian', domain=None) -> xr.DataArray

Return the curl of this vector field, in Cartesian components.

Parameters

Name	Type	Default	Description
components	('cartesian', 'contravariant')	"cartesian"	What the components are: "cartesian" (default) (x, y, z), or "contravariant" components, which are pushed forward first.
domain	struphy domain	None	The mapping (out.domain), for the exact Jacobian. Default: from the X, Y, Z coordinates.

Returns

xarray.DataArray

The curl, with a component dimension.

See Also

plasma_plots.analysis.curl() : The function behind this method.

Examples

>>> B.plasma.analysis.curl()

flux_function

flux_functionmethod#

View source

def flux_function() -> xr.DataArray

Return the flux (or stream) function of this 2-D in-plane field.

Returns

xarray.DataArray

The flux function, without the component dimension.

See Also

plasma_plots.analysis.flux_function() : The function behind this method.

Examples

>>> B.plasma.analysis.flux_function()

cylindrical_components

cylindrical_componentsmethod#

View source

def cylindrical_components() -> xr.DataArray

Return the Cartesian components rotated to (R, phi, Z).

Returns

xarray.DataArray

The vector field in cylindrical components.

See Also

plasma_plots.analysis.cylindrical_components() : The function behind this method. ArrayAnalysis.toroidal_components() : Components about a magnetic axis.

Examples

>>> E.plasma.analysis.cylindrical_components()

toroidal_components

toroidal_componentsmethod#

View source

def toroidal_components(R0: float, Z0: float = 0.0) -> xr.DataArray

Return the Cartesian components rotated to (radial, poloidal, toroidal) about an axis at R0.

Parameters

Name	Type	Default	Description
R0	float	required	The major radius of the magnetic axis.
Z0	float	0.0	The height of the magnetic axis. Default: 0.

Returns

xarray.DataArray

The vector field in toroidal components.

See Also

plasma_plots.analysis.toroidal_components() : The function behind this method. ArrayAnalysis.cylindrical_components() : Components about the Z axis.

Examples

>>> u.plasma.analysis.toroidal_components(R0=3.0)

polar_coordinates

polar_coordinatesmethod#

View source

def polar_coordinates(center=(0.0, 0.0)) -> xr.DataArray

Return this array with coordinates r and theta in the X-Y plane.

Parameters

Name	Type	Default	Description
center	(float, float)	(0.0, 0.0)	The origin (X, Y) of the polar coordinates. Default: (0.0, 0.0).

Returns

xarray.DataArray

This array with the added coordinates.

See Also

plasma_plots.analysis.polar_coordinates() : The function behind this method.

Examples

>>> n.plasma.analysis.polar_coordinates(center=(0.0, 0.0))

trace_branch

trace_branchmethod#

View source

def trace_branch(theory, *, window: float = 0.2, k_range=None, threshold: float = 0.001) -> xr.Dataset

Return the measured frequency of a dispersion branch near theory(k) in this (omega, k) spectrum.

Parameters

Name	Type	Default	Description
theory	callable	required	The expected branch omega(k), applied to an array of k; of a complex frequency (as plasma_plots.theory returns), the real part is used.
window	float	0.2	The relative half-width of the search window about the theory. Default: 0.2.
k_range	(float, float)	None	The k interval to trace (negative k are never traced). Default: every k >= 0.
threshold	float	0.001	Maxima weaker than this times the strongest one found count as no wave. Default: 1e-3.

Returns

xarray.Dataset

The measured branch over k.

See Also

plasma_plots.spectral.trace_branch() : The function behind this method. ArrayPlots.against_theory() : The measured frequencies against the theory.

Examples

>>> spectrum.plasma.analysis.trace_branch(
...     bohm_gross, window=0.2, k_range=(1.5, 5.5)
... )

drop_periodic_endpoint

drop_periodic_endpointmethod#

View source

def drop_periodic_endpoint(dim: str, *, period: float = 1.0) -> xr.DataArray

Return this array without a duplicated periodic endpoint along dim.

Parameters

Name	Type	Default	Description
dim	str	required	The periodic dimension.
period	float	1.0	The period in the coordinate of dim. Default: 1.0.

Returns

xarray.DataArray

This array, one point shorter along dim if its last point repeats the first.

See Also

plasma_plots.spectral.drop_periodic_endpoint() : The function behind this method.

field_lines

field_linesmethod#

View source

def field_lines(seeds=8, turns: float | None = None, length: float | None = None, step: float | None = None, direction: str = 'forward', section: float | None = None, stride: int | None = None, components: str = 'cartesian', **selection) -> xr.Dataset

Trace field lines of this vector field through its mapped grid.

Parameters

Name	Type	Default	Description
seeds	(int, dict, array_like or xarray.Dataset)	8	Where the lines start, in logical coordinates: a number of seeds spread along the radial coordinate at the first poloidal and toroidal grid values (the outboard midplane of a torus whose angles start at 0); a dict of logical coordinates to values or 1-D arrays, which are combined into a grid of seeds (e.g. {"rho": 0.95, "theta": thetas, "zeta": zetas} for a connection-length map; a missing coordinate takes its first grid value); an (n, 3) array of points in the order of the logical dimensions; or a Dataset with one variable per logical coordinate. Default: 8.
turns	float	None	Stop a line after this many toroidal transits (turns of the torus: nfp periods of the toroidal logical coordinate, i.e. 2π of GVEC’s toroidal angle, one period of Struphy’s eta3). Default: 20 when the toroidal direction wraps around, else none.
length	float	None	Stop a line after this arc length, in the units of X, Y, Z. Default: with turns, 1.5 times the length turns circles through the seeds’ mean major radius would take (a safety net); without, four times the grid’s extent.
step	float	None	The step of arc length of the integrator. Default: the median spacing of the grid points (trilinear interpolation limits the accuracy before the step does).
direction	('forward', 'backward', 'both')	"forward"	Along the field, against it, or each seed in both directions (two lines per seed, with the coordinates seed and direction telling them apart; the connection length is then the sum of both). Default: "forward".
section	float	None	The toroidal logical coordinate of the poloidal plane whose punctures are recorded. Default: the first toroidal grid value (e.g. zeta = 0).
stride	int	None	Save every stride-th step of each line. Default: as many as keep each line at about 20 000 samples at most; the punctures, transits and lengths count every step regardless.
components	('cartesian', 'contravariant')	"cartesian"	What the components are: "cartesian" (default) (x, y, z), or contravariant logical components, as for plasma_plots.analysis.divergence().
**selection		{}	The other dimensions, e.g. t=-1: an integer is a position, a float the nearest coordinate value.

Returns

xarray.Dataset

The lines over (s, line) with their punctures, rotational transforms and connection lengths; it has .plasma.plot.poincare(), .footprint() and the other field-line plots.

See Also

plasma_plots.fieldlines.trace_field_lines() : The function behind this method. DatasetPlots.poincare() : The Poincaré plot of the lines. ArrayAnalysis.sample_along() : A field along them.

Examples

>>> lines = B.plasma.analysis.field_lines(seeds=12, turns=100, t=-1)
>>> lines.plasma.plot.poincare(color_by="iota")
>>> edge = B.plasma.analysis.field_lines(
...     seeds={"eta1": 0.98, "eta2": np.linspace(0, 1, 32)},
...     direction="both",
...     t=-1,
... )

sample_along

sample_alongmethod#

View source

def sample_along(lines: xr.Dataset) -> xr.DataArray

Return this scalar field interpolated along traced field lines.

Parameters

Name	Type	Description
lines	xarray.Dataset	The lines of [trace_field_lines()][trace_field_lines].

Returns

xarray.DataArray

The field over (s, line) after its other dimensions.

See Also

plasma_plots.fieldlines.sample_along() : The function behind this method. ArrayAnalysis.parallel_wavenumber() : The dominant wavenumber along each line. ArrayPlots.along_field_lines() : The plot.

Examples

>>> along = phi.plasma.analysis.sample_along(lines)
>>> along.isel(line=0).plasma.plot.slice(x="s", y="t")

parallel_wavenumber

parallel_wavenumbermethod#

View source

def parallel_wavenumber(lines: xr.Dataset | None = None, method: str = 'fft', detrend: bool = True) -> xr.DataArray

Return the dominant parallel wavenumber of this field along field lines.

Parameters

Name	Type	Default	Description
lines	xarray.Dataset	None	Traced lines to sample this field along first. Default: this array already is the samples of sample_along(), over (s, line).
method	('fft', 'crossings')	"fft"	How to estimate it. Default: "fft".
detrend	bool	True	Remove the mean along each line first. Default: True.

Returns

xarray.DataArray

k_parallel over line and the other dimensions.

See Also

plasma_plots.fieldlines.parallel_wavenumber() : The function behind this method. plasma_plots.theory.waves.parallel_wavenumber() : The expected (n + m/q)/R₀.

Examples

>>> phi.plasma.analysis.parallel_wavenumber(lines=lines)

boozer_spectrum

boozer_spectrummethod#

View source

def boozer_spectrum(top: int | None = None, angles: str = 'boozer') -> xr.DataArray

Return the Boozer harmonics B_mn of this quantity over the radius.

Parameters

Name	Type	Default	Description
top	int	None	Keep only the top harmonics with the largest peak amplitude over the radius, strongest first. Default: all.
angles	('boozer', 'any')	"boozer"	Require the Boozer angles theta_B, zeta_B (default), or take the harmonics in whatever angles the field has (not a Boozer spectrum then; e.g. for a comparison).

Returns

xarray.DataArray

The real amplitudes over mode (with m, n) and the radius.

See Also

plasma_plots.analysis.boozer_spectrum() : The function behind this method. ArrayAnalysis.quasisymmetry_error() : The symmetry-breaking part. ArrayPlots.boozer_spectrum() : The plot.

Examples

>>> boozer.mod_B.plasma.analysis.boozer_spectrum(top=8)

quasisymmetry_error

quasisymmetry_errormethod#

View source

def quasisymmetry_error(helicity='QA', angles: str = 'boozer') -> xr.DataArray

Return the quasi-symmetry error of this |B| on each flux surface.

Parameters

Name	Type	Default	Description
helicity	('QA', 'QP', 'QH')	"QA"	The symmetry: a name, or (M, N) with N a full-torus toroidal mode number (its sign picks the handedness). Default: "QA".
angles	('boozer', 'any')	"boozer"	As for boozer_spectrum().

Returns

xarray.DataArray

f_QS over the radius.

See Also

plasma_plots.analysis.quasisymmetry_error() : The function behind this method. ArrayAnalysis.boozer_spectrum() : The harmonics it is computed from.

Examples

>>> boozer.mod_B.plasma.analysis.quasisymmetry_error(helicity="QH")

critical_points

critical_pointsmethod#

View source

def critical_points(refine: bool = True) -> xr.Dataset

Return the O-points and X-points of this flux function (at every time).

Parameters

Name	Type	Default	Description
refine	bool	True	Locate the zero within the cell by Newton’s method (the cell’s centre otherwise). Default: True.

Returns

xarray.Dataset

The points over point (and t): positions, values and kinds.

See Also

plasma_plots.analysis.critical_points() : The function behind this method. ArrayAnalysis.reconnected_flux() : The flux between them over time. ArrayPlots.critical_points() : The plot.

Examples

>>> B.plasma.analysis.flux_function().plasma.analysis.critical_points()

reconnected_flux

reconnected_fluxmethod#

View source

def reconnected_flux(relative: bool = True, o_point=None, x_point=None) -> xr.DataArray

Return the reconnected flux over time: this flux function between an O- and an X-point.

Parameters

Name	Type	Default	Description
relative	bool	True	Subtract the value at the first time. Default: True.
o_point	(float, float)	None	The logical coordinates near which to look for the O-point. Default: the dominant island’s.
x_point	(float, float)	None	The same for the X-point.

Returns

xarray.DataArray

ΔΨ(t).

See Also

plasma_plots.analysis.reconnected_flux() : The function behind this method. ArrayAnalysis.growth_rate() : Its growth rate.

Examples

>>> A = B.plasma.analysis.flux_function()
>>> A.plasma.analysis.reconnected_flux().plasma.plot.timeseries(
...     fit=(10.0, 30.0)
... )