dataset.plasma

Plots, diagnostics and data of an xarray.Dataset with per-marker variables, such as an orbits product.

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).

dataset.plasma.plot

Plots of one dataset, as dataset.plasma.plot.<kind>(...).

power_spectrum

power_spectrummethod#

View source

def power_spectrum(backend: Backend | None = None, **options)

Plot the power of a time_fft Dataset.

Parameters

Name	Type	Default	Description
**options		{}	The keyword options of plasma_plots.spectral_plots.plot_power_spectrum(), e.g. peaks=2.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the drawn artists; data holds the averaged "power" and the found "peaks".

See Also

plasma_plots.spectral_plots.plot_power_spectrum() : The function behind this method. ArrayAnalysis.time_fft() : The Dataset to plot.

Examples

>>> phi.plasma.analysis.time_fft(detrend=True).plasma.plot.power_spectrum(
...     peaks=2
... )

cross_spectrum

cross_spectrummethod#

View source

def cross_spectrum(omega_max: float | None = None, backend: Backend | None = None)

Plot the magnitude, coherence and phase of a cross_spectrum Dataset.

Parameters

Name	Type	Default	Description
omega_max	float	None	The highest frequency shown. Default: all.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the drawn artists; data holds "peak_omega" and "peak_phase_deg".

See Also

plasma_plots.spectral_plots.plot_cross_spectrum() : The function behind this method. ArrayAnalysis.cross_spectrum() : The Dataset to plot.

Examples

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

trajectories

trajectoriesmethod#

View source

def trajectories(max_markers: int = 200, show_paths: bool | None = None, ax=None, backend: Backend | None = None)

Plot the three-dimensional paths of saved markers, for an orbits product.

Parameters

Name	Type	Default	Description
max_markers	int	200	Draw only the first max_markers markers. Default: 200.
show_paths	bool	None	Draw each marker’s path, not only its last position. Default: True for up to 200 markers.
ax	mpl_toolkits.mplot3d.Axes3D	None	A 3-D axes to draw into. Default: a new figure.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the 3-D axes and the drawn artists.

See Also

plasma_plots.plotting.plot_marker_trajectories() : The function behind this method. DatasetData.trajectories() : The plotted markers, without plotting them. DatasetPlots.orbits_3d() : Interactive PyVista orbit lines.

Examples

>>> orbits.plasma.plot.trajectories(max_markers=200)

scatter

scattermethod#

View source

def scatter(x: str, y: str, color: str | None = None, ax=None, cmap=None, s: int = 8, color_at=None, background: xr.DataArray | None = None, background_options: dict | None = None, equal_aspect: bool | None = None, backend: Backend | None = None, **selection)

Scatter two marker variables, optionally colored by a third (e.g. density or a tracer).

Remaining dimensions such as t are selected by keyword, exactly like ArrayPlots.lineout(): an integer is a position (-1 the last), and a float is the nearest coordinate value. color_at colors by the values at another time (e.g. 0, the initial positions); background draws a field behind the markers.

Parameters

Name	Type	Default	Description
x	str	required	The data variable along the horizontal axis, e.g. the position "x".
y	str	required	The data variable along the vertical axis, e.g. the position "y".
color	str	None	A data variable to color the markers by, e.g. a Lagrangian tracer, weight or density, with a color bar. Default: one color.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
cmap	str or matplotlib.colors.Colormap	None	The colormap for color. Default: "viridis".
s	int	8	The marker size, in points². Default: 8.
color_at	int or float	None	Take the colors at another time (an integer position such as 0, or a float value), e.g. each marker’s initial position, to follow where fluid parcels go. Default: the selected time.
background	xarray.DataArray	None	A field drawn behind the markers at the same time (select its other dimensions first): on its own x/y dimensions if it has them (a Cartesian field), in logical coordinates if x/y are eta1/eta2/eta3, else in the physical plane of x/y (x, y, z; the field then needs its X, Y, Z coordinates).
background_options	dict	None	Passed to [plot_slice()][plot_slice] for the background (e.g. cmap, levels, fill=False).
equal_aspect	bool	None	Draw both axes to the same scale. Default: when x and y have the same units attribute (e.g. two positions), not for a phase space such as x against vx.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.
**selection		{}	The remaining dimensions, such as t, exactly like ArrayPlots.lineout(): an integer is a position (t=-1 the last), a float the nearest coordinate value.

Returns

PlotResult

The figure, the axes and the drawn artists.

See Also

plasma_plots.plotting.plot_marker_scatter() : The function behind this method. DatasetData.scatter() : The selected markers, without plotting them. DatasetPlots.animation() : The markers moving over time.

Examples

>>> markers.plasma.plot.scatter(x="x", y="y", color="density", t=-1)
>>> markers.plasma.plot.scatter(x="x", y="y", color="tracer", color_at=0, t=-1)

orbit_classification

orbit_classificationmethod#

View source

def orbit_classification(x: str = 'v_par', y: str | None = None, v_par: str = 'v_par', t=0, ax=None, s: int = 8, backend: Backend | None = None)

Plot markers in a phase-space plane, colored as passing, trapped or lost.

By default initial v_par against mu; for a guiding-center orbits product.

Parameters

Name	Type	Default	Description
x	str	'v_par'	The quantity along the horizontal axis. Default: "v_par".
y	str	None	The quantity along the vertical axis. Default: the magnetic moment mu (Particles5D), or v_perp if there is no mu (Particles5Dvperp).
v_par	str	'v_par'	The parallel velocity the classification uses. Default: "v_par".
t	int or float	0	The time of the plotted values: an integer position (default 0, the initial phase-space position, before any marker is lost; -1 the last), or a float nearest value.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
s	int	8	The marker size, in points². Default: 8.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the drawn artists; data["counts"] holds the number of markers per class.

See Also

plasma_plots.plotting.plot_orbit_classification() : The function behind this method. DatasetData.orbit_classification() : The plotted values, without plotting them. DatasetAnalysis.classify_orbits() : The classification alone.

Examples

>>> orbits.plasma.plot.orbit_classification()
>>> orbits.plasma.plot.orbit_classification(x="p_phi")

animation

animationmethod#

View source

def animation(x: str, y: str, color: str | None = None, color_at=None, background: xr.DataArray | None = None, background_options: dict | None = None, step: int = 1, max_frames: int | None = None, interval: int = 100, s: int = 8, cmap=None, trail: int | None = None, paths: bool = False, backend: Backend | None = None)

Animate the markers moving over time, optionally over a field animated in sync.

E.g. over an SPH density. Keep a reference to the returned animation.

Parameters

Name	Type	Default	Description
x	str	required	The data variable along the horizontal axis, e.g. the position "x"; "R" is √(x² + y²) when the data has no R of its own (with y="z" the poloidal plane).
y	str	required	The data variable along the vertical axis, e.g. the position "y".
color	str	None	A variable to color by: per frame, or fixed at the time color_at; or "classification", the orbit class of each marker (passing, trapped, lost; needs v_par, see classify_orbits()), with a legend. Default: one color.
color_at	int or float	None	Fix the colors at this time (an integer position, e.g. 0 for the initial position, to follow fluid parcels, or a float value). Default: the colors of each frame.
background	xarray.DataArray	None	A field drawn behind the markers: with a t dimension (other dimensions selected) at the nearest time of each frame, with shared color limits; without one, fixed (drawn once). On its own x/y dimensions if it has them (a Cartesian field), in logical coordinates if x/y are eta1/eta2/eta3, else in the physical plane of x/y (the field then needs its X, Y, Z coordinates).
background_options	dict	None	Rendering options for the background, as for [plot_slice()][plot_slice] (cmap, symmetric, levels, …).
step	int	1	Use every step-th time. Default: 1.
max_frames	int	None	Keep at most this many frames, evenly spaced over those step leaves (the first and last included), e.g. to keep a Plotly animation small. Default: all.
interval	int	100	The delay between frames, in milliseconds. Default: 100.
s	int	8	The marker size, in points². Default: 8.
cmap	str or matplotlib.colors.Colormap	None	The colormap for color. Default: "viridis".
trail	int	None	Draw each marker’s last trail samples as a faint line behind it. Default: none.
paths	bool	False	Draw each marker’s whole path, fixed and faint, under the animation. Default: False.
backend	('matplotlib', 'plotly')	"matplotlib"	Draw with Matplotlib, or as an interactive Plotly figure with a slider (in result.fig; needs plotly, see plasma_plots.plotly_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

matplotlib.animation.FuncAnimation or PlotResult

The animation; with backend="plotly" a result whose Plotly figure has a slider and Play/Pause buttons.

See Also

plasma_plots.plotting.animate_markers() : The function behind this method. DatasetPlots.scatter() : One frame, as a static plot.

Examples

>>> markers.plasma.plot.animation(
...     x="x", y="y", color="density", background=n, step=2
... )
>>> orbits.plasma.plot.animation(
...     x="R",
...     y="z",
...     color="classification",
...     trail=300,
...     paths=True,
...     background=psi,
... )

paths

pathsmethod#

View source

def paths(x: str = 'x', y: str = 'y', markers=6, near=None, background: xr.DataArray | None = None, background_options: dict | None = None, t=0, ax=None, backend: Backend | None = None)

Plot the paths of a few markers in a plane, with start and end markers.

Optionally over a field (e.g. stream-function contour lines).

Parameters

Name	Type	Default	Description
x	str	'x'	The quantity along the horizontal axis. Default: "x".
y	str	'y'	The quantity along the vertical axis. Default: "y".
markers	int or sequence of int	6	A number of markers (spread evenly over the saved markers) or a list of marker indices. Default: 6.
near	sequence of (float, float)	None	Picks instead the marker starting closest to each of a list of (x, y) points, e.g. a row across the domain.
background	xarray.DataArray	None	A field drawn behind the paths at the time t: on its own x/y dimensions if it has them (a Cartesian field), in logical coordinates if x/y are eta1/eta2/eta3, else in the physical plane of x/y (the field then needs its X, Y, Z coordinates).
background_options	dict	None	Passed to [plot_slice()][plot_slice] for the background, e.g. dict(levels=12, fill=False) for the contour lines of a stream function.
t	int or float	0	The time of the background: an integer position or a float value. Default: 0, the first.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the drawn artists; data["markers"] holds the chosen markers.

See Also

plasma_plots.plotting.plot_marker_paths() : The function behind this method.

Examples

>>> orbits.plasma.plot.paths(markers=4, background=psi.isel(t=0))

poloidal

poloidalmethod#

View source

def poloidal(color_by: str | None = 'classification', max_markers: int = 200, boundary: xr.DataArray | None = None, ax=None, backend: Backend | None = None)

Plot orbits projected onto the poloidal plane (R against z).

By default colored as passing, trapped or lost.

Parameters

Name	Type	Default	Description
color_by	str or None	'classification'	"classification" colors by orbit class (needs v_par, see classify_orbits()); "t" or the name of a (t, marker) variable (e.g. "v_par") colors each orbit along its path, with a color bar; None gives one color per marker. Default: "classification".
max_markers	int	200	Draw only the first max_markers markers. Default: 200.
boundary	xarray.DataArray	None	Any field with physical coordinates, whose outer (last eta1) surface is drawn at its first eta3 as the domain boundary.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the drawn lines.

See Also

plasma_plots.plotting.plot_orbit_poloidal() : The function behind this method. DatasetPlots.orbit_grid() : One panel per marker.

Examples

>>> orbits.plasma.plot.poloidal(boundary=field)

orbit_grid

orbit_gridmethod#

View source

def orbit_grid(markers=8, ncols: int = 4, boundary: xr.DataArray | None = None, backend: Backend | None = None)

Plot one small poloidal panel per marker, colored by orbit class.

Parameters

Name	Type	Default	Description
markers	int or sequence of int	8	A number of markers (spread over the classes when v_par is saved) or a list of marker indices. Default: 8.
ncols	int	4	The number of panels per row. Default: 4.
boundary	xarray.DataArray	None	A field with physical coordinates whose outer (last eta1) surface is drawn in every panel, at its first eta3.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the drawn lines; data["markers"] holds the plotted markers.

See Also

plasma_plots.plotting.plot_orbit_grid() : The function behind this method. DatasetPlots.poloidal() : All orbits in one panel.

Examples

>>> orbits.plasma.plot.orbit_grid(markers=8, ncols=4, boundary=field)
>>> orbits.plasma.plot.orbit_grid(markers=[3, 17, 42])

quantities

quantitiesmethod#

View source

def quantities(quantities=('v_par', 'mu'), markers=6, drift_of=('mu'), backend: Backend | None = None)

Plot saved orbit quantities over time for a few markers.

E.g. v_par bouncing, or the drift of the invariant mu.

Parameters

Name	Type	Default	Description
quantities	sequence of str	('v_par', 'mu')	The quantities, one panel each. Default: ("v_par", "mu").
markers	int or sequence of int	6	A number of markers (spread over the classes if v_par is saved, so passing and trapped ones both show) or a list of marker indices. Default: 6.
drift_of	bool or sequence of str	('mu')	The quantities shown as their change since t = 0 (default ("mu",), an invariant of guiding-center motion, so its drift measures the pusher’s accuracy); True for all, False for none.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, one axes per quantity and the drawn lines.

See Also

plasma_plots.plotting.plot_orbit_quantities() : The function behind this method.

Examples

>>> orbits.plasma.plot.quantities(markers=4)

orbits_3d

orbits_3dmethod#

View source

def orbits_3d(color_by: str = 't', max_markers: int = 200, tube_radius: float | None = None, cmap=None, domain: xr.DataArray | None = None, title: str | None = None, plotter=None)

Draw PyVista 3-D orbit lines, colored by "t", "classification" or any variable.

domain is a field whose boundary is drawn for context.

Parameters

Name	Type	Default	Description
color_by	str	't'	"t", "classification" (passing, trapped, lost, with a legend) or the name of any (t, marker) variable, e.g. "v_par". Default: "t".
max_markers	int	200	At most this many markers are drawn. Default: 200.
tube_radius	float	None	Draw the orbits as tubes of this radius. Default: plain lines.
cmap	str or matplotlib colormap	None	The colormap (not used for "classification"). Default: "viridis".
domain	xarray.DataArray	None	A field with physical coordinates whose outer surface is drawn translucently; other than eta1, eta2, eta3, its dimensions are taken at their first position.
title	str	None	Text in the scene’s corner. Default: "Marker orbits"; "" for none.
plotter	pyvista.Plotter	None	Draw into this scene instead of a new one, to combine several views.

Returns

pyvista.Plotter

The plotter with the orbits, not yet shown.

See Also

plasma_plots.pyvista_plots.pyvista_orbits() : The function behind this method. DatasetPlots.trajectories() : A static Matplotlib overview.

Examples

>>> orbits.plasma.plot.orbits_3d(
...     color_by="classification", domain=phi.isel(t=0)
... ).show()

poincare

poincaremethod#

View source

def poincare(coords: str = 'physical', color_by: str | None = 'line', s: float = 3.0, cmap=None, islands: bool = False, boundary: xr.DataArray | None = None, max_lines: int | None = None, ax=None, title: str | None = None, backend: Backend | None = None, **classification)

Plot the Poincaré section of these traced field lines.

Parameters

Name	Type	Default	Description
coords	('physical', 'logical')	"physical"	Draw R against z (physical), or the poloidal angle against the radial logical coordinate (logical). Default: "physical".
color_by	('line', 'iota', 'classification', 'connection_length', None)	"line"	One color per line (cycling), a color bar over each line’s rotational transform or connection length, or the classes of classify_field_lines() (surface, island, chaotic) with a legend; None for one color. Default: "line".
s	float	3.0	The marker size, in points². Default: 3.
cmap	str or matplotlib colormap	None	The colormap of "iota" and "connection_length". Default: "viridis".
islands	bool	False	Label the island chains with their n/m and widths. Default: False.
boundary	xarray.DataArray	None	A field with physical coordinates whose outermost surface is drawn at the section (physical coordinates only).
max_lines	int	None	Draw only the first max_lines lines. Default: all.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: the section’s label and angle.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.
**classification		{}	Options of classify_field_lines() (max_denominator, tolerance, threshold, min_spread), for color_by="classification" and islands_.

Returns

PlotResult

The figure, the axes and the scatters; data holds the section and, with islands, the chains and the classification.

See Also

plasma_plots.fieldline_plots.plot_poincare() : The function behind this method. DatasetData.poincare() : The punctures, without plotting them. DatasetAnalysis.islands() : The island chains alone.

Examples

>>> lines.plasma.plot.poincare(color_by="iota")
>>> lines.plasma.plot.poincare(color_by="classification", islands=True)

field_lines

field_linesmethod#

View source

def field_lines(plane: str = 'RZ', color_by: str | None = 'line', max_lines: int = 200, cmap=None, boundary: xr.DataArray | None = None, ax=None, title: str | None = None, backend: Backend | None = None)

Plot these traced field lines projected onto a plane, or in 3-D.

Parameters

Name	Type	Default	Description
plane	('RZ', 'XY', 'XZ', 'YZ', '3d')	"RZ"	The projection: the poloidal plane R-z (default), a Cartesian plane, or a 3-D axes.
color_by	('line', 'iota', 'absB', 's', None)	"line"	One color per line (cycling), each line colored by its rotational transform, or each line colored along its path by |B| or the arc length s (with a color bar; 2-D planes only); None for one color. Default: "line".
max_lines	int	200	Draw only the first max_lines lines. Default: 200.
cmap	str or matplotlib colormap	None	The colormap. Default: "viridis".
boundary	xarray.DataArray	None	A field with physical coordinates whose outermost surface is drawn in the RZ plane.
ax	matplotlib.axes.Axes	None	The axes to draw into (a 3-D axes for plane="3d"). Default: a new figure.
title	str	None	The title. Default: the lines’ label.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the lines.

See Also

plasma_plots.fieldline_plots.plot_field_lines() : The function behind this method. DatasetPlots.poincare() : Their punctures of a poloidal plane.

Examples

>>> lines.plasma.plot.field_lines(plane="RZ", color_by="iota")
>>> lines.plasma.plot.field_lines(plane="3d", max_lines=20)

footprint

footprintmethod#

View source

def footprint(log: bool = True, s: float = 14.0, cmap=None, ax=None, title: str | None = None, backend: Backend | None = None)

Plot where these open field lines leave the grid, colored by connection length.

Parameters

Name	Type	Default	Description
log	bool	True	Color by the decimal logarithm of the connection length. Default: True.
s	float	14.0	The marker size, in points². Default: 14.
cmap	str or matplotlib colormap	None	The colormap. Default: "viridis".
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: how many lines left the grid.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the scatter; data["footprint"] holds the exit points.

See Also

plasma_plots.fieldline_plots.plot_footprint() : The function behind this method. DatasetData.footprint() : The exit points, without plotting them. DatasetPlots.connection_length() : The connection lengths over the seeds.

Examples

>>> edge.plasma.plot.footprint()

connection_length

connection_lengthmethod#

View source

def connection_length(log: bool = True, cmap=None, s: float = 14.0, ax=None, title: str | None = None, backend: Backend | None = None)

Plot the connection length of each field line over its seed.

Parameters

Name	Type	Default	Description
log	bool	True	Show the decimal logarithm of the connection length. Default: True.
cmap	str or matplotlib colormap	None	The colormap. Default: "viridis".
s	float	14.0	The marker size of a scatter, in points². Default: 14.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: "connection length".
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the mesh or scatter; data["connection_length"].

See Also

plasma_plots.fieldline_plots.plot_connection_length() : The function behind this method. DatasetAnalysis.seed_grid() : The values over the seed grid.

Examples

>>> edge.plasma.plot.connection_length()

weight_histogram

weight_histogrammethod#

View source

def weight_histogram(weight: str = 'weight', t=-1, bins: int = 50, log: bool = True, density: bool = True, ax=None, title: str | None = None, backend: Backend | None = None)

Plot the distribution of the marker weights at one or several times.

Parameters

Name	Type	Default	Description
weight	str	'weight'	The weight variable. Default: "weight".
t	(int, float or sequence)	-1	The time(s): integer positions (-1 the last) or float nearest values, one or several. Default: -1.
bins	int	50	The number of bins, shared by all times. Default: 50.
log	bool	True	A logarithmic count axis. Default: True.
density	bool	True	Normalize each histogram to unit area. Default: True.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: the noise estimate at the last time shown.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and one outline per time; data["statistics"].

See Also

plasma_plots.plotting.plot_weight_histogram() : The function behind this method. DatasetAnalysis.weight_statistics() : The numbers.

Examples

>>> orbits.plasma.plot.weight_histogram(t=[0, 0.5, -1])

marker_density

marker_densitymethod#

View source

def marker_density(x: str = 'eta1', weight: str | None = 'weight', against: xr.DataArray | None = None, bins: int = 32, normalize: bool = True, ax=None, title: str | None = None, backend: Backend | None = None, **selection)

Plot where the markers are against what they represent, along one coordinate.

Parameters

Name	Type	Default	Description
x	str	'eta1'	The position variable to bin over, e.g. "eta1" or "x". Default: "eta1".
weight	str	'weight'	The weight variable, for the weighted density; None leaves it out. Default: "weight" (skipped when the Dataset has no such variable).
against	xarray.DataArray	None	A reference profile over the same coordinate (every other dimension selected, or with t matching markers), drawn dashed. Default: none.
bins	int	32	The number of bins. Default: 32.
normalize	bool	True	Divide each profile by the mean of its magnitude, so that the shapes compare (a δf perturbation sums to nearly nothing, so its plain mean would not do). Default: True.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: "marker density".
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.
**selection		{}	The time: t=-1 (default, the last) or a float nearest value.

Returns

PlotResult

The figure, the axes and the lines; data holds the densities.

See Also

plasma_plots.plotting.plot_marker_density() : The function behind this method. DatasetAnalysis.marker_density() : The binned densities.

Examples

>>> orbits.plasma.plot.marker_density(
...     x="eta1", against=n.isel(eta2=0, eta3=0), t=-1
... )

lost_fraction

lost_fractionmethod#

View source

def lost_fraction(weight: str | None = None, percent: bool = True, ax=None, title: str | None = None, backend: Backend | None = None)

Plot the fraction of markers lost from the domain, against time.

Parameters

Name	Type	Default	Description
weight	str	None	Weigh each marker by its initial value of this variable, i.e. count particles rather than markers. Default: count markers.
percent	bool	True	Show percentages. Default: True.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: the final fraction.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the line; data["lost_fraction"].

See Also

plasma_plots.plotting.plot_lost_fraction() : The function behind this method. DatasetAnalysis.lost_fraction() : The fraction alone.

Examples

>>> orbits.plasma.plot.lost_fraction(weight="weight")

loss_map

loss_mapmethod#

View source

def loss_map(x: str = 'v_par', y: str | None = None, t=0, absB=None, ax=None, s: int = 10, cmap=None, title: str | None = None, backend: Backend | None = None)

Plot which markers are lost, over their initial phase-space position, colored by when.

Parameters

Name	Type	Default	Description
x	str	'v_par'	The quantity along the horizontal axis: a variable, or "energy", "pitch" or "speed" (see loss_map()). Default: "v_par".
y	str	None	The vertical one. Default: "mu", or "v_perp" without mu.
t	int or float	0	The time of the plotted positions: an integer position (default 0) or a float nearest value.
absB	callable	None	|B|(x, y, z), for "energy" and "pitch".
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
s	int	10	The marker size, in points². Default: 10.
cmap	str or matplotlib.colors.Colormap	None	The colormap of the loss time. Default: "plasma".
title	str	None	The title. Default: how many markers are lost.
backend	('matplotlib', 'plotly', 'tikz')	"matplotlib"	Draw with Matplotlib, as an interactive Plotly figure, or as TikZ/pgfplots code for LaTeX (in result.fig; needs plotly or maxplotlib, see plasma_plots.plotly_backend and plasma_plots.tikz_backend). Default: the one set with plasma_plots.set_backend(), "matplotlib" unless changed.

Returns

PlotResult

The figure, the axes and the scatters; data["losses"].

See Also

plasma_plots.plotting.plot_loss_map() : The function behind this method. DatasetData.loss_map() : The values, without plotting them. DatasetPlots.orbit_classification() : Passing, trapped and lost markers.

Examples

>>> orbits.plasma.plot.loss_map(x="energy", y="pitch", absB=absB)

dataset.plasma.analysis

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

classify_orbits

classify_orbitsmethod#

View source

def classify_orbits(v_par: str = 'v_par') -> xr.DataArray

Classify each marker of this guiding-center orbits product: passing (0), trapped (1) or lost (-1).

See plasma_plots.analysis.classify_orbits() for the criteria.

Parameters

Name	Type	Default	Description
v_par	str	'v_par'	The name of the parallel-velocity variable. Default: "v_par".

Returns

xarray.DataArray

The class of each marker, over marker.

See Also

plasma_plots.analysis.classify_orbits() : The function behind this method. DatasetPlots.orbit_classification() : The markers in a phase-space plane, colored by class.

Examples

>>> orbits.plasma.analysis.classify_orbits()

orbit_invariants

orbit_invariantsmethod#

View source

def orbit_invariants(absB=None) -> xr.Dataset

Return the speed, guiding-centre energy and pitch of the saved orbits.

Parameters

Name	Type	Default	Description
absB	callable	None	|B|(x, y, z) as a function of the physical positions (numpy arrays), e.g. lambda x, y, z: out.equil.absB0(*out.domain.inverse_map(x, y, z)). Needed for the energy and the pitch.

Returns

xarray.Dataset

The invariants per marker and time.

See Also

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

Examples

>>> orbits.plasma.analysis.orbit_invariants(absB=absB_xyz)

bounce_period

bounce_periodmethod#

View source

def bounce_period(v_par: str = 'v_par') -> xr.DataArray

Return the bounce period of each trapped marker.

Parameters

Name	Type	Default	Description
v_par	str	'v_par'	The name of the parallel-velocity variable. Default: "v_par".

Returns

xarray.DataArray

The bounce period over marker.

See Also

plasma_plots.analysis.bounce_period() : The function behind this method. DatasetAnalysis.classify_orbits() : Which markers are trapped.

Examples

>>> orbits.plasma.analysis.bounce_period()

surface_average

surface_averagemethod#

View source

def surface_average(name: str, *, jacobian: str | None = 'Jac', domain=None, quadrature=None) -> xr.DataArray

Return the flux-surface average of one variable, with this Dataset’s Jacobian.

Parameters

Name	Type	Default	Description
name	str	required	The variable, e.g. "mod_B".
jacobian	str or None	'Jac'	The variable holding √g, used if the Dataset has it. None (or a missing variable) takes domain, else the numerical Jacobian of X, Y, Z. Default: "Jac", GVEC’s.
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

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

See Also

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

Examples

>>> ev.plasma.analysis.surface_average("mod_B")

poincare_section

poincare_sectionmethod#

View source

def poincare_section(angle: float | None = None) -> xr.Dataset

Return the punctures of a poloidal plane by these traced field lines.

Parameters

Name	Type	Default	Description
angle	float	None	The toroidal logical coordinate of the plane. Default: the traced section.

Returns

xarray.Dataset

The punctures over (puncture, line).

See Also

plasma_plots.fieldlines.poincare_section() : The function behind this method. DatasetPlots.poincare() : The plot.

Examples

>>> lines.plasma.analysis.poincare_section(angle=np.pi / 5)

rotational_transform

rotational_transformmethod#

View source

def rotational_transform() -> xr.DataArray

Return the rotational transform of each traced field line.

Returns

xarray.DataArray

iota over line.

See Also

plasma_plots.fieldlines.rotational_transform() : The function behind this method.

Examples

>>> lines.plasma.analysis.rotational_transform()

classify_field_lines

classify_field_linesmethod#

View source

def classify_field_lines(max_denominator: int = 12, tolerance: float | None = None, threshold: float = 0.1, min_spread: float | None = None) -> xr.DataArray

Classify each traced field line: on a flux surface (0), in an island (1) or chaotic (2).

Parameters

Name	Type	Default	Description
max_denominator	int	12	The largest m of the rationals considered. Default: 12.
tolerance	float	None	How close ι must be to n/m. Default: two over the number of toroidal transits of the line (the resolution of ι from the trace), at least 1e-3.
threshold	float	0.1	The median radial jump between punctures that are neighbours in the poloidal angle, relative to the line’s radial spread, above which a non-librating line is chaotic (a smooth curve through 100 punctures gives a few hundredths). Default: 0.1.
min_spread	float	None	The radial spread of the punctures (in the radial logical coordinate) below which a line is on a surface. Default: half the radial grid spacing of the traced field.

Returns

xarray.DataArray

The class of each line over line.

See Also

plasma_plots.fieldlines.classify_field_lines() : The function behind this method. DatasetAnalysis.islands() : The island chains and their widths.

Examples

>>> lines.plasma.analysis.classify_field_lines()

islands

islandsmethod#

View source

def islands(max_denominator: int = 12, tolerance: float | None = None, threshold: float = 0.1, min_spread: float | None = None) -> xr.Dataset

Return the island chains these traced field lines show, with their widths.

Parameters

Name	Type	Default	Description
max_denominator	int	12	The largest m of the rationals considered. Default: 12.
tolerance	float	None	How close ι must be to n/m; see classify_field_lines().
threshold	float	0.1	The chaos criterion of classify_field_lines(). Default: 0.1.
min_spread	float	None	The surface criterion of classify_field_lines(). Default: half the radial grid spacing.

Returns

xarray.Dataset

Over chain: n, m, width, center, …

See Also

plasma_plots.fieldlines.islands() : The function behind this method. DatasetPlots.poincare() : islands=True labels them.

Examples

>>> lines.plasma.analysis.islands().to_dataframe()

footprint

footprintmethod#

View source

def footprint() -> xr.Dataset

Return where these traced field lines left the grid, with their connection lengths.

Returns

xarray.Dataset

The exit points over line.

See Also

plasma_plots.fieldlines.footprint() : The function behind this method. DatasetPlots.footprint() : The plot.

Examples

>>> edge.plasma.analysis.footprint()

seed_grid

seed_gridmethod#

View source

def seed_grid(name: str = 'connection_length') -> xr.DataArray

Return a per-line quantity of these field lines over their grid of seeds.

Parameters

Name	Type	Default	Description
name	str	'connection_length'	The per-line variable. Default: "connection_length".

Returns

xarray.DataArray

name over the two varying seed coordinates.

See Also

plasma_plots.fieldlines.seed_grid() : The function behind this method. DatasetPlots.connection_length() : The plot of the connection lengths.

Examples

>>> edge.plasma.analysis.seed_grid("connection_length").plasma.plot.slice()

weight_statistics

weight_statisticsmethod#

View source

def weight_statistics(weight: str = 'weight') -> xr.Dataset

Return the statistics of the marker weights over time, with the noise estimate.

Parameters

Name	Type	Default	Description
weight	str	'weight'	The weight variable. Default: "weight", Struphy’s.

Returns

xarray.Dataset

mean, std, total, noise, effective_markers, … over t.

See Also

plasma_plots.analysis.weight_statistics() : The function behind this method. DatasetPlots.weight_histogram() : The distribution of the weights.

Examples

>>> orbits.plasma.analysis.weight_statistics().noise.plasma.plot.timeseries()

marker_density

marker_densitymethod#

View source

def marker_density(dims=('eta1'), bins=32, weight: str | None = None, ranges=None) -> xr.DataArray

Return the markers binned over position variables, per unit volume.

Parameters

Name	Type	Default	Description
dims	str or sequence of str	('eta1')	The position variables to bin over, e.g. ("eta1",) or ("x", "y"). Default: ("eta1",).
bins	int or sequence of int	32	The number of bins, for all or for each. Default: 32.
weight	str	None	Weigh each marker by this variable, e.g. "weight". Default: count the markers.
ranges	dict	None	{variable: (low, high)} bin ranges. Default: (0, 1) for the logical eta coordinates, the markers’ extent otherwise.

Returns

xarray.DataArray

The density over t and the binned variables.

See Also

plasma_plots.analysis.marker_density() : The function behind this method. DatasetPlots.marker_density() : Sampling against physical density.

Examples

>>> orbits.plasma.analysis.marker_density(dims="eta1", weight="weight")

lost_fraction

lost_fractionmethod#

View source

def lost_fraction(weight: str | None = None) -> xr.DataArray

Return the fraction of markers lost from the domain, over time.

Parameters

Name	Type	Default	Description
weight	str	None	Weigh each marker by its initial value of this variable, e.g. "weight". Default: count the markers.

Returns

xarray.DataArray

The fraction over t.

See Also

plasma_plots.analysis.lost_fraction() : The function behind this method. DatasetPlots.lost_fraction() : The plot.

Examples

>>> orbits.plasma.analysis.lost_fraction(weight="weight")

loss_map

loss_mapmethod#

View source

def loss_map(x: str = 'v_par', y: str | None = None, t=0, absB=None) -> xr.Dataset

Return each marker’s initial phase-space position, whether it is lost, and when.

Parameters

Name	Type	Default	Description
x	str	'v_par'	The first quantity. Default: "v_par".
y	str	None	The second quantity. Default: "mu", or "v_perp" without mu.
t	int or float	0	The time of the plotted values: an integer position (default 0, the initial one) or a float nearest value.
absB	callable	None	|B|(x, y, z), for "energy" and "pitch" (see orbit_invariants()).

Returns

xarray.Dataset

x, y, lost and loss_time over marker.

See Also

plasma_plots.analysis.loss_map() : The function behind this method. DatasetPlots.loss_map() : The plot.

Examples

>>> orbits.plasma.analysis.loss_map(x="energy", y="pitch", absB=absB)

dataset.plasma.data

The data behind each plot in :class:DatasetPlots, without rendering it.

trajectories

trajectoriesmethod#

View source

def trajectories(max_markers: int = 200) -> xr.Dataset

Return the marker-position subset DatasetPlots.trajectories() would plot.

Parameters

Name	Type	Default	Description
max_markers	int	200	Draw only the first max_markers markers. Default: 200.

Returns

xarray.Dataset

The orbits of the first max_markers markers.

Raises

ValueError

If the orbits lack x, y or z, or a marker dimension.

See Also

DatasetPlots.trajectories() : The plot of these markers.

Examples

>>> markers.plasma.data.trajectories(max_markers=50)

scatter

scattermethod#

View source

def scatter(x: str, y: str, color: str | None = None, color_at=None, **selection) -> xr.Dataset

Return the per-marker positions and colors DatasetPlots.scatter() would plot.

.to_dataframe() hands them straight to e.g. Plotly Express.

Parameters

Name	Type	Default	Description
x	str	required	The variables for the horizontal and vertical axes.
y	str	required	The variables for the horizontal and vertical axes.
color	str	None	The variable to color by. Default: none.
color_at	int or float	None	Take the colors at another time (an integer position such as 0, or a float value). Default: at the selected time.
**selection		{}	The other dimensions, e.g. t: an integer is a position (t=-1 the last), a float the nearest coordinate value.

Returns

xarray.Dataset

x, y and color over marker.

See Also

plasma_plots.plotting.prepare_marker_scatter() : The function behind this method. DatasetPlots.scatter() : The plot of these markers.

Examples

>>> markers.plasma.data.scatter(
...     x="x", y="y", color="density", t=-1
... ).to_dataframe()
>>> # colored by the start
>>> markers.plasma.data.scatter(x="x", y="y", color="x", color_at=0, t=-1)

orbit_classification

orbit_classificationmethod#

View source

def orbit_classification(x: str = 'v_par', y: str | None = None, v_par: str = 'v_par', t=0) -> xr.Dataset

Return the per-marker x, y and classification that orbit_classification plots.

The values DatasetPlots.orbit_classification() would plot.

Parameters

Name	Type	Default	Description
x	str	'v_par'	The quantity along the horizontal axis. Default: "v_par".
y	str	None	The quantity along the vertical axis. Default: the magnetic moment mu (Particles5D), or v_perp if there is no mu (Particles5Dvperp).
v_par	str	'v_par'	The parallel velocity the classification uses. Default: "v_par".
t	int or float	0	The time of the plotted values: an integer position (default 0, the initial phase-space position, before any marker is lost; -1 the last), or a float nearest value.

Returns

xarray.Dataset

x, y and classification over marker.

See Also

DatasetPlots.orbit_classification() : The plot of these values. plasma_plots.plotting.prepare_orbit_classification() : The function that prepares them.

Examples

>>> orbits.plasma.data.orbit_classification(x="p_phi")

poincare

poincaremethod#

View source

def poincare(angle: float | None = None) -> xr.Dataset

Return the punctures DatasetPlots.poincare() would plot.

Parameters

Name	Type	Default	Description
angle	float	None	The toroidal logical coordinate of the plane. Default: the traced section.

Returns

xarray.Dataset

The punctures over (puncture, line).

See Also

plasma_plots.fieldlines.poincare_section() : The function behind this method. DatasetPlots.poincare() : The plot of these punctures.

Examples

>>> lines.plasma.data.poincare().to_dataframe()

footprint

footprintmethod#

View source

def footprint() -> xr.Dataset

Return the exit points DatasetPlots.footprint() would plot.

Returns

xarray.Dataset

The exit points over line, with the connection lengths.

See Also

plasma_plots.fieldlines.footprint() : The function behind this method. DatasetPlots.footprint() : The plot of these points.

Examples

>>> edge.plasma.data.footprint()

loss_map

loss_mapmethod#

View source

def loss_map(x: str = 'v_par', y: str | None = None, t=0, absB=None) -> xr.Dataset

Return the per-marker values DatasetPlots.loss_map() would plot.

Parameters

Name	Type	Default	Description
x	str	'v_par'	The first quantity. Default: "v_par".
y	str	None	The second quantity. Default: "mu", or "v_perp" without mu.
t	int or float	0	The time of the plotted values: an integer position (default 0, the initial one) or a float nearest value.
absB	callable	None	|B|(x, y, z), for "energy" and "pitch" (see [orbit_invariants()][orbit_invariants]).

Returns

xarray.Dataset

x, y, lost and loss_time over marker.

See Also

plasma_plots.analysis.loss_map() : The function behind this method. DatasetPlots.loss_map() : The plot of these values.

Examples

>>> orbits.plasma.data.loss_map(x="energy", y="pitch", absB=absB)