# plasma_plots.phase_space

*module*

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**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/phase_space.py#L1-L1)

## plasma_plots.phase_space.phase_space_histogram

*function*

```python
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**

- `markers` (`xarray.Dataset or dict of str to xarray.Dataset`) — Per-marker variables with a ``marker`` dimension; a dict of species is binned together.
- `x` (`str`) — The position variable.
- `v` (`str`) — The velocity variable.
- `weight` (`str`) (default: `None`) — A variable of marker weights to sum, e.g. δf weights. Default: each marker counts 1.
- `bins` (`int or (int, int)`) (default: `64`) — The number of bins along ``x`` and ``v``. Default: 64.
- `limits` (`((float, float), (float, float))`) (default: `None`) — The binned ranges of ``x`` and ``v``. Default: the markers' extent.
- `density` (`bool`) (default: `False`) — Divide by the bin area, for a phase-space density. Default: ``False``.
- `**selection` (default: `{}`) — 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**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/phase_space.py#L70-L148)

## plasma_plots.phase_space.plot_phase_space

*function*

```python
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**

- `markers` (`xarray.Dataset or dict of str to xarray.Dataset`) — Per-marker variables with a ``marker`` dimension (and usually ``t``), or a dict of species names to such Datasets, drawn in one color each.
- `x` (`str`) — The position variable, on the horizontal axis.
- `v` (`str`) — The velocity variable, on the vertical axis.
- `kind` (`('scatter', 'histogram')`) (default: `"scatter"`) — Draw the markers as points, or bin them into a 2-D histogram of their weights (see [`phase_space_histogram()`][plasma_plots.phase_space.phase_space_histogram]). Default: ``"scatter"``.
- `species` (`str`) (default: `None`) — A variable or coordinate along ``marker`` naming each marker's species, drawn in one color each with a legend. Default: none.
- `color` (`str`) (default: `None`) — A variable to color the points by, with a color bar (not with ``species``). Default: one color per species.
- `weight` (`str`) (default: `None`) — The marker weights, summed by ``kind="histogram"``. Default: each marker counts 1.
- `bins` (`int or (int, int)`) (default: `64`) — The number of histogram bins along ``x`` and ``v``. Default: 64.
- `log` (`bool`) (default: `False`) — A logarithmic color scale for the histogram. Default: ``False``.
- `ax` (`matplotlib.axes.Axes`) (default: `None`) — The axes to draw into. Default: a new figure.
- `s` (`float`) (default: `4`) — The point size of a scatter. Default: 4.
- `alpha` (`float`) (default: `0.6`) — The point opacity of a scatter. Default: 0.6.
- `max_markers` (`int`) (default: `20000`) — Draw at most this many points per species (evenly strided), to keep large runs quick. ``None`` draws all. Default: 20000.
- `cmap` (`str or matplotlib.colors.Colormap`) (default: `None`) — The colormap of ``color`` or the histogram. Default: ``"viridis"``.
- `title` (`str`) (default: `None`) — The axes title. Default: the selected time, if any.
- `**selection` (default: `{}`) — 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.

> **See Also**
>
> [`phase_space_histogram()`][plasma_plots.phase_space.phase_space_histogram] : The histogram, without plotting it.

**Examples**

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

[View source](https://github.com/max-models/plasma-plots/blob/devel/src/plasma_plots/phase_space.py#L151-L320)
