Skip to content
Projects

plasma_plots.phase_space

Phase-space views of markers: position against velocity, as points or a weighted histogram.

A marker Dataset has a marker dimension (and usually t), with one variable per saved quantity, e.g. x and vx. [plot_phase_space()][plot_phase_space] draws one position against one velocity at a selected time, as a scatter of the markers or as a 2-D histogram of their weights, and tells species apart by color. The accessor exposes it as markers.plasma.plot.phase_space, and the histogram as markers.plasma.data.phase_space.

Examples

>>> markers.plasma.plot.phase_space(x="x", v="vx", t=-1)
>>> markers.plasma.plot.phase_space(
... x="x", v="vx", kind="histogram", weight="w", t=-1
... )
>>> plot_phase_space(
... {"electrons": electrons, "ions": ions}, x="x", v="vx", t=0
... )

Functions

NameDescription
phase_space_histogramBin markers into a 2-D histogram over a position and a velocity.
plot_phase_spacePlot markers in phase space, a position against a velocity.

phase_space_histogramfunction#

def phase_space_histogram(markers, *, x: str, v: str, weight: str | None = None, bins=64, limits=None, density: bool = False, **selection) -> xr.DataArray

Bin markers into a 2-D histogram over a position and a velocity.

Parameters

NameTypeDefaultDescription
markersxarray.Dataset or dict of str to xarray.DatasetrequiredPer-marker variables with a marker dimension; a dict of species is binned together.
xstrrequiredThe position variable.
vstrrequiredThe velocity variable.
weightstrNoneA variable of marker weights to sum, e.g. δf weights. Default: each marker counts 1.
binsint or (int, int)64The number of bins along x and v. Default: 64.
limits((float, float), (float, float))NoneThe binned ranges of x and v. Default: the markers’ extent.
densityboolFalseDivide by the bin area, for a phase-space density. Default: False.
**selection{}The other dimensions, e.g. t: an integer is a position (t=-1 the last), a float the nearest coordinate value.

Returns

xarray.DataArray
The summed weights over x and v (the bin centres).

Raises

ValueError
If a name is not a variable, or dimensions other than marker remain.

Examples

>>> f = markers.plasma.data.phase_space(x="x", v="vx", bins=(128, 64), t=-1)

plot_phase_spacefunction#

def plot_phase_space(markers, *, x: str, v: str, kind: str = 'scatter', species: str | None = None, color: str | None = None, weight: str | None = None, bins=64, log: bool = False, ax=None, s: float = 4, alpha: float = 0.6, max_markers: int | None = 20000, cmap=None, title: str | None = None, **selection)

Plot markers in phase space, a position against a velocity.

Parameters

NameTypeDefaultDescription
markersxarray.Dataset or dict of str to xarray.DatasetrequiredPer-marker variables with a marker dimension (and usually t), or a dict of species names to such Datasets, drawn in one color each.
xstrrequiredThe position variable, on the horizontal axis.
vstrrequiredThe velocity variable, on the vertical axis.
kind('scatter', 'histogram')"scatter"Draw the markers as points, or bin them into a 2-D histogram of their weights (see phase_space_histogram()). Default: "scatter".
speciesstrNoneA variable or coordinate along marker naming each marker’s species, drawn in one color each with a legend. Default: none.
colorstrNoneA variable to color the points by, with a color bar (not with species). Default: one color per species.
weightstrNoneThe marker weights, summed by kind="histogram". Default: each marker counts 1.
binsint or (int, int)64The number of histogram bins along x and v. Default: 64.
logboolFalseA logarithmic color scale for the histogram. Default: False.
axmatplotlib.axes.AxesNoneThe axes to draw into. Default: a new figure.
sfloat4The point size of a scatter. Default: 4.
alphafloat0.6The point opacity of a scatter. Default: 0.6.
max_markersint20000Draw at most this many points per species (evenly strided), to keep large runs quick. None draws all. Default: 20000.
cmapstr or matplotlib.colors.ColormapNoneThe colormap of color or the histogram. Default: "viridis".
titlestrNoneThe axes title. Default: the selected time, if any.
**selection{}The other dimensions, e.g. t: an integer is a position (t=-1 the last), a float the nearest coordinate value.

Returns

PlotResult
The figure, the axes, the drawn points or mesh, and for a histogram the binned values in data["histogram"].

Raises

ValueError
If kind is not one of the two, a name is not a variable, or dimensions other than marker remain.

Examples

>>> plot_phase_space(markers, x="x", v="vx", species="species", t=-1)
>>> plot_phase_space(
... markers, x="x", v="vx", kind="histogram", weight="w", log=True, t=0
... )