plasma_plots.fieldline_plots

Plots of traced field lines, from plasma_plots.fieldlines.

Poincaré sections, projections, footprints, connection lengths, profiles along the lines, and unfolded flux surfaces with field lines.

Each returns a PlotResult, whose data holds what was drawn.

Attributes

Name	Description
LINE_CLASS_COLORS	No description.
PLANES_2D	No description.

Functions

Name	Description
plot_along_field_lines	A field along traced field lines, one curve per line against the arc length.
plot_connection_length	The connection length of each field line over its seed.
plot_field_lines	Traced field lines projected onto a plane, or in 3-D.
plot_footprint	Where open field lines leave the grid, over the two angles, colored by connection length.
plot_poincare	A Poincaré plot: the punctures of a poloidal plane by traced field lines.
plot_surface_map	A quantity on a flux surface, unfolded over the toroidal and poloidal angles, with field lines.

LINE_CLASS_COLORSattributemodule attribute#

View source

LINE_CLASS_COLORS = {'surface': 'C0', 'island': 'C3', 'chaotic': '0.55'}

PLANES_2Dattributemodule attribute#

View source

PLANES_2D = {'RZ': ('R', 'z'), 'XY': ('x', 'y'), 'XZ': ('x', 'z'), 'YZ': ('y', 'z')}

plot_along_field_linesfunction#

View source

def plot_along_field_lines(samples: xr.DataArray, *, k_parallel: bool = False, method: str = 'fft', max_lines: int = 12, ax=None, title: str | None = None)

A field along traced field lines, one curve per line against the arc length.

Parameters

Name	Type	Default	Description
samples	xarray.DataArray	required	The field along the lines, from sample_along(), over (s, line) (every other dimension selected).
k_parallel	bool	False	Estimate each line’s parallel wavenumber (see parallel_wavenumber()) and put it in the legend. Default: False.
method	('fft', 'crossings')	"fft"	The estimate’s method. Default: "fft".
max_lines	int	12	Draw only the first max_lines lines. Default: 12.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
title	str	None	The title. Default: the samples’ label.

Returns

PlotResult

The figure, the axes and the lines; with k_parallel, data["k_parallel"] holds the estimates over line.

Raises

ValueError

If dimensions other than s and line remain.

See Also

plasma_plots.fieldlines.sample_along() : The samples.

Examples

>>> plot_along_field_lines(
...     sample_along(phi.isel(t=-1), lines), k_parallel=True
... )

plot_connection_lengthfunction#

View source

def plot_connection_length(lines: xr.Dataset, *, log: bool = True, cmap=None, s: float = 14.0, ax=None, title: str | None = None)

The connection length of each field line over its seed.

Seeds that form a grid of two coordinates (a dict of two arrays in trace_field_lines()) give a map over them; other seeds a scatter over their two varying coordinates (the radial and poloidal ones by default).

Parameters

Name	Type	Default	Description
lines	xarray.Dataset	required	The lines of trace_field_lines(), traced with direction="both" for the full connection length.
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".

Returns

PlotResult

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

Raises

ValueError

If no line left the grid.

See Also

plasma_plots.fieldlines.seed_grid() : The map’s values. plot_footprint() : Where the lines leave.

Examples

>>> plot_connection_length(edge)

plot_field_linesfunction#

View source

def plot_field_lines(lines: xr.Dataset, *, 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)

Traced field lines projected onto a plane, or in 3-D.

Parameters

Name	Type	Default	Description
lines	xarray.Dataset	required	The lines of trace_field_lines().
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.

Returns

PlotResult

The figure, the axes and the drawn lines.

Raises

ValueError

If plane or color_by is unknown.

See Also

plot_poincare() : The punctures of a poloidal plane.

Examples

>>> plot_field_lines(lines, plane="RZ", color_by="iota")
>>> plot_field_lines(lines, plane="3d", max_lines=20)

plot_footprintfunction#

View source

def plot_footprint(lines: xr.Dataset, *, log: bool = True, s: float = 14.0, cmap=None, ax=None, title: str | None = None)

Where open field lines leave the grid, over the two angles, colored by connection length.

Parameters

Name	Type	Default	Description
lines	xarray.Dataset	required	The lines of trace_field_lines() (or their footprint()), traced with direction="both" for the full connection length.
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.

Returns

PlotResult

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

See Also

plot_connection_length() : The connection lengths over the seeds. plasma_plots.fieldlines.footprint() : The exit points.

Examples

>>> plot_footprint(edge)

plot_poincarefunction#

View source

def plot_poincare(section: xr.Dataset, *, 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, **classification)

A Poincaré plot: the punctures of a poloidal plane by traced field lines.

Each line’s punctures trace a closed curve on a flux surface, a chain of m loops in an island, and a cloud where the field is chaotic.

Parameters

Name	Type	Default	Description
section	xarray.Dataset	required	A poincare_section(), or the lines of trace_field_lines() (cut at their section).
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	Find the island chains (islands()) and label each with its n/m and width near one of its O-points. 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.
**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 (one per line, or one per class); data holds the section, and with islands_ the islands Dataset and the classification.

Raises

ValueError

If coords or color_by is unknown.

See Also

plasma_plots.fieldlines.poincare_section() : The punctures. plasma_plots.fieldlines.islands() : The island chains.

Examples

>>> plot_poincare(lines, color_by="iota")
>>> plot_poincare(
...     poincare_section(lines, angle=0.3),
...     color_by="classification",
...     islands_=True,
... )

plot_surface_mapfunction#

View source

def plot_surface_map(data: xr.DataArray, *, x: str | None = None, y: str | None = None, iota=None, lines: xr.Dataset | None = None, count: int = 6, start: float = 0.0, turns: float | None = 2.0, line_color: str = 'w', ax=None, **options)

A quantity on a flux surface, unfolded over the toroidal and poloidal angles, with field lines.

The surface is a slice of the field at one radius; field lines on it are drawn either as straight lines of slope ι (in straight-field-line angles, e.g. GVEC’s Boozer or PEST angles, where θ = θ₀ + ι ζ), or as traced lines, or both (the straight ones dashed then). Where a line leaves the plot through a periodic edge it continues from the opposite one.

Parameters

Name	Type	Default	Description
data	xarray.DataArray	required	The quantity on the surface, with the two angles as its only dimensions (every other dimension selected, e.g. ev.mod_B.sel(rho=0.5)).
x	str	None	The toroidal angle. Default: the toroidal logical dimension.
y	str	None	The poloidal angle. Default: the poloidal logical dimension.
iota	float or xarray.DataArray	None	The rotational transform of the surface, or its profile over the radial coordinate, at whose value in data’s coordinates it is interpolated. Draws count straight field lines. Default: none.
lines	xarray.Dataset	None	Traced lines (trace_field_lines()), drawn over the angles as they are, every line in the Dataset. Default: none.
count	int	6	The number of straight lines, equally spaced in the poloidal angle. Default: 6.
start	float	0.0	The poloidal angle of the first straight line at the left edge. Default: 0.
turns	float	2.0	How many toroidal transits of each traced line to draw (a long line covers an irrational surface completely); None for all. Default: 2.
line_color	str	'w'	The color of the field lines. Default: white.
ax	matplotlib.axes.Axes	None	The axes to draw into. Default: a new figure.
**options		{}	Options of plot_slice() (cmap, levels, symmetric, overlays, …).

Returns

PlotResult

The figure, the axes, the mesh and the lines; data["iota"] holds the ι drawn.

Raises

ValueError

If data does not have exactly the two angles, or a profile iota cannot be interpolated because data has no scalar radial coordinate.

See Also

plasma_plots.plotting.plot_slice() : The surface itself.

Examples

>>> plot_surface_map(boozer.mod_B.sel(rho=0.5), iota=boozer.iota, count=8)
>>> plot_surface_map(phi.isel(t=-1).sel(eta1=0.5), lines=lines)