Skip to content
Projects

plasma_plots.pyvista_plots

Three-dimensional PyVista views of labeled Struphy output.

Every function returns a pyvista.Plotter without showing it: call .show() in an interactive session or notebook, or .screenshot(path) (with pyvista.OFF_SCREEN = True in batch jobs). Pass plotter= to draw several views into one scene.

[pyvista_surfaces()][pyvista_surfaces] draws any surface meshes (geometry, marching-cubes surfaces) in the same style, and [pyvista_points()][pyvista_points] labelled point sets with optional arrows; in one scene they continue one color cycle and share one legend. scene() shows a plotter as an interactive 3-D scene in a notebook, which docs sites built from notebooks embed as they are.

Fields need their physical X, Y, Z coordinates attached, as every Struphy field product has; orbits need physical positions x, y, z.

Attributes

NameDescription
ORBIT_CLASS_COLORSNo description.
RENDERERSNo description.
SCENE_EXTRANo description.

Classes

NameDescription
SceneA pyvista.Plotter displayed as an interactive 3-D scene; see scene().

Functions

NameDescription
boundary_facesReturn the real boundary faces of a point array, see boundary_keys().
boundary_keysFind the logical faces of a (n1, n2, n3, 3) point array that are real boundaries.
coil_polylinesCoils as one closed pyvista.PolyData line per coil, with point data color_by.
is_flatWhether a structured grid has a single point in one logical direction (a 2-D run or cut).
orbit_polylinesMarker orbits as one pyvista.PolyData line per marker, with point data color_by.
prepare_slices_3dThe logical cuts of a scalar (eta1, eta2, eta3) field that pyvista_slices() draws.
push_forwardCartesian components of a vector field given by contravariant logical components.
pyvista_coilsStellarator coils as tubes, optionally around the plasma surface.
pyvista_domainThe mapping of a Struphy domain as a wireframe of logical grid lines.
pyvista_glyphsArrows of a selected (component, eta1, eta2, eta3) vector field, colored by magnitude.
pyvista_isosurfaceContour surfaces of a selected scalar (eta1, eta2, eta3) field in physical space.
pyvista_orbitsMarker orbits as 3-D lines (or tubes), colored by time, orbit class, or any variable.
pyvista_pointsPoint sets in physical space, such as samples, grid nodes or crossings, optionally with arrows.
pyvista_slicesSurfaces of constant logical coordinate through a scalar field, drawn in physical space.
pyvista_streamlinesField lines of a selected vector field, e.g. magnetic field lines, colored by magnitude.
pyvista_surfacesSurface meshes in physical space, such as geometry or marching-cubes surfaces.
save_movieRender one 3-D view per sweep step into a GIF (.gif) or video (.mp4, ...).
save_vtkWrite a field to VTK structured grids (.vts) on its physical points, for ParaView.
sceneShow a pyvista.Plotter as an interactive 3-D scene in a notebook.
scene_to_plotlyConvert a pyvista.Plotter into an interactive Plotly 3-D figure.
structured_gridA pyvista.StructuredGrid of a selected (eta1, eta2, eta3) field on its physical points.

ORBIT_CLASS_COLORSattributemodule attribute#

ORBIT_CLASS_COLORS = {'passing': 'tab:blue', 'trapped': 'tab:orange', 'lost': 'grey'}

RENDERERSattributemodule attribute#

RENDERERS = {
  'isosurface': pyvista_isosurface,
  'slices': pyvista_slices,
  'glyphs': pyvista_glyphs,
  'streamlines': pyvista_streamlines
}

SCENE_EXTRAattributemodule attribute#

SCENE_EXTRA = 'pip install "plasma-plots[scene]"'

Sceneclass#

class Scene(plotter, *, alt: str | None = None, title: str | None = None, window_size=None, backend: Literal['vtkjs', 'plotly'] = 'vtkjs', decimate: float | None = None)

A pyvista.Plotter displayed as an interactive 3-D scene; see scene().

The PNG and the HTML are rendered from the plotter the first time they are needed and kept, so later changes to the plotter don’t show.

Parameters

NameTypeDefaultDescription
plotterpyvista.PlotterrequiredThe scene, off screen.
altstrNoneA text alternative for the screenshot.
titlestrNoneA title for the scene.
window_size(int, int)NoneThe screenshot’s size in pixels. Default: the plotter’s window size.
backend('vtkjs', 'plotly')"vtkjs"How a notebook shows the scene; see scene(). Default: "vtkjs".
decimatefloatNoneFraction of the triangles to remove from each surface in the vtk.js export (e.g. 0.5). Default: keep them all.

altattributeinstance attribute#

alt = alt

backendattributeinstance attribute#

backend = backend

decimateattributeinstance attribute#

decimate = decimate

plotterattributeinstance attribute#

plotter = plotter

titleattributeinstance attribute#

title = title

window_sizeattributeinstance attribute#

window_size = window_size

htmlmethod#

def html() -> str

The scene as a standalone HTML page, vtk.js inlined (plotter.trame.export_html).

vtk.js receives colors already mapped to RGB, so its own color bar would read 0-255: the plotter’s scalar bars are hidden in the export and drawn as an HTML overlay with the right values instead. Surfaces are thinned by decimate; most of a small scene’s few MB is the inlined vtk.js viewer itself.

Returns

str
The HTML document.

Raises

ImportError
If trame-pyvista isn’t installed (the scene extra).

pngmethod#

def png() -> bytes

The screenshot of the plotter, as PNG bytes.

Returns

bytes
The PNG file’s content.

Raises

RuntimeError
If the plotter isn’t off screen and hasn’t been shown.

save_htmlmethod#

def save_html(path) -> str

Write the scene to a standalone HTML file.

Parameters

NameTypeDescription
pathstr or pathlib.PathThe file to write.

Returns

str
path, as a string.

save_pngmethod#

def save_png(path) -> str

Write the screenshot to a PNG file.

Parameters

NameTypeDescription
pathstr or pathlib.PathThe file to write.

Returns

str
path, as a string.

to_plotlymethod#

def to_plotly(**options)

The scene as a Plotly 3-D figure; see scene_to_plotly().

Parameters

NameDefaultDescription
**options{}Passed to scene_to_plotly(), e.g. max_faces.

Returns

plotly.graph_objects.Figure
The figure.

boundary_facesfunction#

def boundary_faces(points: np.ndarray) -> list[np.ndarray]

Return the real boundary faces of a point array, see boundary_keys().

Parameters

NameTypeDescription
pointsnumpy.ndarrayPhysical points, shape (n1, n2, n3, 3).

Returns

list of numpy.ndarray
The points of each face, with a size-one axis in the face’s logical direction.

boundary_keysfunction#

def boundary_keys(points: np.ndarray) -> list[tuple[int, int]]

Find the logical faces of a (n1, n2, n3, 3) point array that are real boundaries.

Faces that collapse to a line or point (a polar axis) and pairs of opposite faces that coincide (the seam of a periodic direction, e.g. phi = 0 of a full torus) are dropped. A grid that is flat in one direction (a 2-D run) is its own single face.

Parameters

NameTypeDescription
pointsnumpy.ndarrayPhysical points, shape (n1, n2, n3, 3).

Returns

list of (int, int)
(axis, index) of each boundary face; index is 0 or -1.

coil_polylinesfunction#

def coil_polylines(coils: xr.Dataset, *, color_by: str | None = None)

Coils as one closed pyvista.PolyData line per coil, with point data color_by.

Parameters

NameTypeDefaultDescription
coilsxarray.DatasetrequiredCoils over (coil, s) with coordinates X, Y, Z, from plasma_plots.from_coilset().
color_bystrNoneA variable (or coordinate) over coil or (coil, s) to attach as point data, e.g. "current", "curvature" or "unique_coil". Default: none.

Returns

pyvista.PolyData
The coils, each closed by repeating its first point.

Raises

ValueError
If coils isn’t over (coil, s), lacks X, Y, Z, or color_by isn’t a variable over coil or (coil, s).

is_flatfunction#

def is_flat(grid) -> bool

Whether a structured grid has a single point in one logical direction (a 2-D run or cut).

Parameters

NameTypeDescription
gridpyvista.StructuredGridThe grid, e.g. from structured_grid().

Returns

bool
True if any of the grid’s dimensions is 1.

orbit_polylinesfunction#

def orbit_polylines(orbits: xr.Dataset, *, color_by: str = 't', max_markers: int = 200)

Marker orbits as one pyvista.PolyData line per marker, with point data color_by.

Samples where a marker is lost (every quantity zero) are dropped. color_by is "t", "classification" (see classify_orbits()), or the name of any (t, marker) variable, e.g. "v_par" or "weight".

Parameters

NameTypeDefaultDescription
orbitsxarray.DatasetrequiredMarker orbits with dims (t, marker) and physical positions x, y, z.
color_bystr't'The point data to attach: "t", "classification" or a variable name. Default: "t".
max_markersint200At most this many markers are used. Default: 200.

Returns

pyvista.PolyData
One line per marker with at least two samples left, and point data color_by; empty if no marker has.

Raises

ValueError
If color_by is neither "t", "classification" nor a variable of orbits.

prepare_slices_3dfunction#

def prepare_slices_3d(data: xr.DataArray, *, cuts: dict | None = None) -> list[xr.DataArray]

The logical cuts of a scalar (eta1, eta2, eta3) field that pyvista_slices() draws.

cuts maps eta1/eta2/eta3 to one position or a list: a float is the nearest logical coordinate, an integer a grid index (-1 the last). The default is the middle of every dimension with more than one point, or for a 2-D field (one dimension with a single point) the whole plane. Each cut keeps its size-one dimension, so it still maps onto a surface in physical space.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA scalar field with dims (eta1, eta2, eta3) and physical coordinates X, Y, Z.
cutsdictNone{dim: position or list of positions} along eta1, eta2, eta3.

Returns

list of xarray.DataArray
One array per cut, in the order of cuts.

Raises

ValueError
If a cut is along another dimension.
TypeError
If a position is neither an integer nor a float.

push_forwardfunction#

def push_forward(data: xr.DataArray) -> xr.DataArray

Cartesian components of a vector field given by contravariant logical components.

data has dims (component, eta1, eta2, eta3), e.g. from out.evaluate(name, eta1=..., eta2=..., eta3=..., representation="v"). The Cartesian field is sum_i v^i dX/de_i, with the Jacobian of the mapping differentiated numerically from the attached X, Y, Z coordinates, so every logical direction needs at least two points.

Parameters

NameTypeDescription
dataxarray.DataArrayThe vector field, dims (component, eta1, eta2, eta3) with three contravariant components and physical coordinates X, Y, Z.

Returns

xarray.DataArray
The Cartesian x, y, z components, same dims and coordinates, labeled "<label> (Cartesian)".

Raises

ValueError
If the field doesn’t have three components or a logical direction has fewer than two points.

Examples

>>> B_xyz = push_forward(
... out.evaluate("em_fields/b_field", representation="v").isel(t=-1)
... )

pyvista_coilsfunction#

def pyvista_coils(coils: xr.Dataset, *, color_by: str | None = None, color='#b87333', tube_radius: float | None = None, cmap=None, clim=None, surface=None, surface_opacity: float = 1.0, surface_cmap=None, surface_clim=None, title: str | None = None, plotter=None)

Stellarator coils as tubes, optionally around the plasma surface.

Parameters

NameTypeDefaultDescription
coilsxarray.DatasetrequiredCoils over (coil, s) with coordinates X, Y, Z, from plasma_plots.from_coilset().
color_bystrNoneColor the coils by a variable over coil or (coil, s): "current", "curvature", "length", "unique_coil", or one added to the Dataset such as the distances of plasma_plots.coils.distance_to_surface(). Default: one color.
colorcolor'#b87333'The coils’ color without color_by; any Matplotlib color. Default: copper.
tube_radiusfloatNoneRadius of the tubes, in m. Default: 0.4 % of the coils’ extent; 0 for plain lines.
cmapstr or matplotlib colormapNoneThe colormap for color_by. Default: "viridis".
clim(float, float)NoneColor limits for color_by. Default: the values’ range.
surfacexarray.Dataset or xarray.DataArrayNoneThe plasma: a Dataset (e.g. plasma_plots.from_boundary()) is drawn in grey, a DataArray (e.g. |B| on the last surface of plasma_plots.from_desc() over the whole torus) colored by its values. Its logical dimensions are rho, theta, zeta with a single rho.
surface_opacityfloat1.0Opacity of the surface. Default: 1.
surface_cmapstr or matplotlib colormapNoneThe colormap of a DataArray surface. Default: "plasma".
surface_clim(float, float)NoneColor limits of a DataArray surface, e.g. to compare two scenes on one scale. Default: the values’ range.
titlestrNoneText in the scene’s corner. Default: "Coils"; "" for none.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

ValueError
If the coils or color_by are not as described, or surface lacks X, Y, Z.

Examples

>>> coils = plasma_plots.from_coilset(coilset)
>>> plasma = plasma_plots.from_boundary(boundary)
>>> pyvista_coils(coils, color_by="curvature", surface=plasma).show()

pyvista_domainfunction#

def pyvista_domain(domain, *, n1: int = 8, n2: int = 32, n3: int = 32, resolution: int = 4, color='black', surface: bool = True, cross_section: bool = True, title: str | None = None, plotter=None)

The mapping of a Struphy domain as a wireframe of logical grid lines.

Grid lines are drawn on the real boundary faces (see boundary_keys(); for a torus the outer and inner surfaces) and, with cross_section, over the whole eta3 = 0 face (for a torus a poloidal cross-section). n1, n2, n3 lines per direction, each sampled resolution times finer so curved lines stay smooth. surface adds the translucent boundary. Useful to check the geometry (and its orientation) of a run; n3=1 shows a 2-D run’s plane.

Parameters

NameTypeDefaultDescription
domaincallablerequiredA Struphy domain (mapping), e.g. out.domain, called as domain(eta1, eta2, eta3, squeeze_out=False) to give x, y, z.
n1int8Grid lines along eta1. Default: 8.
n2int32Grid lines along eta2. Default: 32.
n3int32Grid lines along eta3. Default: 32.
resolutionint4Samples per line spacing, so curved lines stay smooth. Default: 4.
colorstr'black'Color of the grid lines. Default: "black".
surfaceboolTrueDraw the translucent boundary surface. Default: True.
cross_sectionboolTrueAlso draw grid lines over the eta3 = 0 face. Default: True.
titlestrNoneText in the scene’s corner. Default: "Domain"; "" for none.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the domain when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Examples

>>> pyvista_domain(out.domain).show()
>>> pyvista_domain(out.domain, n3=1, surface=False).show()

pyvista_glyphsfunction#

def pyvista_glyphs(data: xr.DataArray, *, components: Literal['cartesian', 'contravariant'] = 'cartesian', stride: int = 2, scale: float | None = None, cmap='viridis', show_domain: bool = True, title: str | None = None, plotter=None)

Arrows of a selected (component, eta1, eta2, eta3) vector field, colored by magnitude.

components="cartesian" (default) for x/y/z components, e.g. a *_phy product; "contravariant" for logical components, pushed forward by push_forward(). stride thins the grid in every direction; scale is the arrow length of the largest vector (default: a tenth of the domain size).

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA vector field with dims (component, eta1, eta2, eta3) (three components, every other dimension selected) and physical coordinates X, Y, Z.
components('cartesian', 'contravariant')"cartesian"How to read the components: Cartesian x/y/z, or contravariant logical components, pushed forward. Default: "cartesian".
strideint2Draw an arrow at every stride-th point in every direction. Default: 2.
scalefloatNoneArrow length of the largest vector, in physical units. Default: a tenth of the domain size.
cmapstr or matplotlib colormap'viridis'The colormap of the magnitude. Default: "viridis".
show_domainboolTrueDraw the domain’s outer surface translucently for context. Default: True.
titlestrNoneText in the scene’s corner. Default: the field’s label; "" for none.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

ValueError
If stride is less than 1, components is unknown, or the field isn’t a three-component field over the logical dimensions with physical coordinates.

Examples

>>> pyvista_glyphs(B.isel(t=-1), stride=3).show()
>>> pyvista_glyphs(B.isel(t=-1), components="contravariant", scale=0.2).show()

pyvista_isosurfacefunction#

def pyvista_isosurface(data: xr.DataArray, *, values: int | list[float] = 5, cmap='viridis', opacity: float | list[float] = 1.0, colors=None, labels: list[str] | None = None, clim=None, show_domain: bool = True, title: str | None = None, symmetric: bool = False, robust: bool = False, plotter=None)

Contour surfaces of a selected scalar (eta1, eta2, eta3) field in physical space.

values is the number of evenly spaced levels, or explicit levels (between the color limits, which symmetric/robust set as in color_limits()). Each level is colored from cmap with a scalar bar, or with its own colors and a legend of the levels instead; opacity may differ per level too, e.g. an opaque surface inside a translucent shell. show_domain draws the domain’s outer surface translucently for context. For a 2-D field (one logical direction with a single point) the levels are contour lines over the colored plane.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA scalar field with dims (eta1, eta2, eta3) (every other dimension selected; one logical dimension may be selected away) and physical coordinates X, Y, Z.
valuesint or list of float5The number of evenly spaced levels strictly between the color limits, or explicit levels. Default: 5.
cmapstr or matplotlib colormap'viridis'The colormap. Default: "viridis".
opacityfloat or sequence of float1.0Opacity of the surfaces, one for all or one per level. For a 2-D field a single value is the plane’s opacity and a sequence sets the contour lines’ (the plane is then opaque). Default: 1.
colorscolor or sequence of colorsNoneColors of the surfaces (of the contour lines for a 2-D field), one for all or one per level; any Matplotlib color. They replace the colormap and its scalar bar with a legend of the levels (the plane of a 2-D field keeps the colormap). Default: from cmap (black lines for a 2-D field).
labelssequence of strNoneOne legend entry per level; giving them shows the legend even without colors. Default: "level <value>".
clim(float, float)NoneColor limits; default from the field’s values, see symmetric and robust.
show_domainboolTrueDraw the domain’s outer surface translucently for context (3-D fields only). Default: True.
titlestrNoneText in the scene’s corner. Default: the field’s label; "" for none.
symmetricboolFalseColor limits symmetric about zero. Default: False.
robustboolFalseColor limits from percentiles instead of the extremes, so outliers don’t wash out the colors. Default: False.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path). The surfaces are the actors "isosurface 0", "isosurface 1", … in the order of the levels.

Raises

ValueError
If other dimensions remain, the physical coordinates are missing, or opacity, colors or labels don’t have one entry per level.

Examples

>>> pyvista_isosurface(phi.isel(t=-1), values=[-0.1, 0.1]).show()
>>> pyvista_isosurface(phi.isel(t=-1), symmetric=True, opacity=0.6).show()

An opaque surface inside a translucent shell:

>>> pyvista_isosurface(
... distance,
... values=[0, 0.2],
... colors=["tab:blue", "lightgrey"],
... opacity=[1, 0.3],
... ).show()

pyvista_orbitsfunction#

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

Marker orbits as 3-D lines (or tubes), colored by time, orbit class, or any variable.

domain is any field with physical coordinates whose outer surface is drawn translucently for context. See orbit_polylines() for color_by.

Parameters

NameTypeDefaultDescription
orbitsxarray.DatasetrequiredMarker orbits with dims (t, marker) and physical positions x, y, z.
color_bystr't'"t", "classification" (passing, trapped, lost, with a legend) or the name of any (t, marker) variable, e.g. "v_par". Default: "t".
max_markersint200At most this many markers are drawn. Default: 200.
tube_radiusfloatNoneDraw the orbits as tubes of this radius. Default: plain lines.
cmapstr or matplotlib colormapNoneThe colormap (not used for "classification"). Default: "viridis".
domainxarray.DataArrayNoneA field with physical coordinates whose outer surface is drawn translucently; other than eta1, eta2, eta3, its dimensions are taken at their first position.
titlestrNoneText in the scene’s corner. Default: "Marker orbits"; "" for none.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

ValueError
If color_by is neither "t", "classification" nor a variable of orbits.

Examples

>>> pyvista_orbits(out.kinetic_ions.orbits, color_by="classification").show()
>>> pyvista_orbits(
... out.kinetic_ions.orbits, color_by="v_par", domain=phi, tube_radius=0.01
... ).show()

pyvista_pointsfunction#

def pyvista_points(points, *, labels=None, colors=None, scalars=None, cmap=None, clim=None, size=8, opacity=1.0, vectors=None, vector_scale: float | None = None, title: str | None = None, legend: bool = True, plotter=None)

Point sets in physical space, such as samples, grid nodes or crossings, optionally with arrows.

Each set gets its own color from Matplotlib’s color cycle, and the labels go in a legend when there is more than one. Drawn into a scene with plotter=, e.g. after pyvista_surfaces(), the color cycle continues and the scene keeps one legend of the labelled surfaces and point sets. With scalars, the points are colored by a value instead, on one color scale with a scalar bar. vectors adds an arrow at every point, e.g. surface normals.

Parameters

NameTypeDefaultDescription
pointsarray, sequence of arrays, or dict of str to arrayrequiredOne set of points is an (n, 3) array, or (3, n) component-major as simgeometry stores points: the last axis holds the coordinates when its length is 3 (or 2), else the first axis does, so a (3, 3) array is three points as rows. (n, 2) points lie in the z = 0 plane. A dict’s keys are the labels. Empty sets are skipped.
labelssequence of strNoneOne label per set, for the legend. Default: the dict’s keys, else none.
colorscolor, sequence of colors, or dict of str to colorNoneColors of the sets, by position or by label; any Matplotlib color. Default: Matplotlib’s color cycle, continued from earlier calls into the same plotter.
scalarscallable, array, sequence of arrays, or dict of str to arrayNoneColor by scalars(points), a function of the (n, 3) points of each set that returns n values, or by given values: n per set, with the same options as points. The scalar bar shows the function’s name, else “value”. NaN values are drawn in the NaN color. Default: plain colors.
cmapstr or matplotlib colormapNoneThe colormap for scalars. Default: "viridis".
clim(float, float)NoneColor limits for scalars. Default: the range over all sets.
sizefloat, sequence of float, or dict of str to float8Point size in pixels, one for all or by position or label. Default: 8.
opacityfloat, sequence of float, or dict of str to float1.0Opacity of the sets (and their arrows), one for all or by position or label. Default: 1.
vectorsarray, sequence of arrays, or dict of str to arrayNoneA vector at every point, drawn as an arrow from it in the set’s color: (n, 3) or (3, n) per set, with the same options as points; a dict may leave sets out, and None in a sequence draws no arrows for that set. Default: no arrows.
vector_scalefloatNoneThe length of the longest arrow, in physical units; the others are scaled by their magnitude (unit normals are all this long). Default: 5% of the scene’s extent.
titlestrNoneText in the scene’s corner. Default: none.
legendboolTruePut the labels in the scene’s legend, shown when it has two or more entries (not with scalars). Default: True.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the points when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

ValueError
If an array has none of the accepted shapes, or labels, colors, size, opacity, scalars or vectors don’t match the point sets.

Examples

>>> import pyvista as pv
>>> sphere = pv.Sphere()
>>> plotter = pyvista_surfaces({"sphere": sphere}, opacity=0.3)
>>> pyvista_points(
... {"vertices": sphere.points, "center": [0.0, 0.0, 0.0]},
... vectors={"vertices": sphere.point_normals},
... plotter=plotter,
... ).show()
>>> pyvista_points(np.random.rand(3, 500), scalars=lambda p: p[:, 2]).show()

pyvista_slicesfunction#

def pyvista_slices(data: xr.DataArray, *, cuts: dict | None = None, cmap='viridis', clim=None, show_domain: bool = True, title: str | None = None, symmetric: bool = False, robust: bool = False, opacity: float = 1.0, plotter=None)

Surfaces of constant logical coordinate through a scalar field, drawn in physical space.

On a mapped domain these are the natural cuts: cuts={"eta3": [0, 0.25]} gives poloidal cross-sections of a torus, cuts={"eta1": 0.8} the field on one flux surface. See prepare_slices_3d() for cuts; color limits are shared by every cut.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA scalar field with dims (eta1, eta2, eta3) (every other dimension selected; one logical dimension may be selected away) and physical coordinates X, Y, Z.
cutsdictNone{dim: position or list of positions} along eta1, eta2, eta3: a float is the nearest logical coordinate, an integer a grid index (-1 the last). Default: the middle of every dimension, or the whole plane of a 2-D field.
cmapstr or matplotlib colormap'viridis'The colormap. Default: "viridis".
clim(float, float)NoneColor limits, shared by every cut; default from the whole field’s values, see symmetric and robust.
show_domainboolTrueDraw the domain’s outer surface translucently for context. Not drawn when the whole plane of a 2-D field is shown. Default: True.
titlestrNoneText in the scene’s corner. Default: the field’s label; "" for none.
symmetricboolFalseColor limits symmetric about zero. Default: False.
robustboolFalseColor limits from percentiles instead of the extremes, so outliers don’t wash out the colors. Default: False.
opacityfloat1.0Opacity of the cuts, from 0 (invisible) to 1, e.g. to see what is drawn inside a flux surface. Default: 1.0.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

ValueError
If other dimensions remain, the physical coordinates are missing, or a cut is along another dimension.

Examples

>>> pyvista_slices(phi.isel(t=-1), cuts={"eta3": [0, 0.25]}).show()
>>> pyvista_slices(phi.isel(t=-1), cuts={"eta1": 0.8}, symmetric=True).show()
>>> pyvista_slices(phi.isel(t=-1), cuts={"eta1": 1.0}, opacity=0.35).show()

pyvista_streamlinesfunction#

def pyvista_streamlines(data: xr.DataArray, *, components: Literal['cartesian', 'contravariant'] = 'cartesian', n_points: int = 100, source_radius: float | None = None, source_center=None, max_length: float | None = None, tube_radius: float | None = None, cmap='viridis', show_domain: bool = True, title: str | None = None, plotter=None)

Field lines of a selected vector field, e.g. magnetic field lines, colored by magnitude.

Lines are traced in both directions from n_points seeds: by default grid points drawn at random (reproducibly) across the domain, or, given source_center and/or source_radius, points in that sphere (radius default: a quarter of the domain size; center default: the bounding-box center, which can lie outside a curved domain). For a 2-D field the lines stay on the plane (the out-of-plane component is ignored). See pyvista_glyphs() for components.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA vector field with dims (component, eta1, eta2, eta3) (three components, every other dimension selected) and physical coordinates X, Y, Z.
components('cartesian', 'contravariant')"cartesian"How to read the components: Cartesian x/y/z, or contravariant logical components, pushed forward by push_forward(). Default: "cartesian".
n_pointsint100The number of seed points (at most the number of grid points when seeding on the grid). Default: 100.
source_radiusfloatNoneSeed in a sphere of this radius instead of at grid points. Default (when source_center is given): a quarter of the domain size.
source_center(float, float, float)NoneSeed in a sphere around this physical point instead of at grid points. Default (when source_radius is given): the bounding-box center.
max_lengthfloatNoneMaximum length of each line. Default: four times the domain size.
tube_radiusfloatNoneDraw the lines as tubes of this radius. Default: plain lines.
cmapstr or matplotlib colormap'viridis'The colormap of the magnitude. Default: "viridis".
show_domainboolTrueDraw the domain’s outer surface translucently for context. Default: True.
titlestrNoneText in the scene’s corner. Default: "<label> field lines"; "" for none.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the field when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

ValueError
If components is unknown, or the field isn’t a three-component field over the logical dimensions with physical coordinates.

Examples

>>> pyvista_streamlines(B.isel(t=-1)).show()
>>> pyvista_streamlines(
... B.isel(t=-1),
... source_center=(3.0, 0.0, 0.0),
... source_radius=0.5,
... tube_radius=0.01,
... ).show()

pyvista_surfacesfunction#

def pyvista_surfaces(meshes, *, labels=None, colors=None, scalars=None, cmap=None, clim=None, opacity=1.0, show_edges: bool = False, title: str | None = None, legend: bool = True, plotter=None)

Surface meshes in physical space, such as geometry or marching-cubes surfaces.

Each mesh gets its own color from Matplotlib’s color cycle (C0, C1, …), and the labels go in a legend when there is more than one. Drawn into a scene with plotter=, the color cycle continues and the legend lists the labelled meshes and point sets (pyvista_points()) of every call. With scalars, the surfaces are colored by a value instead, on one color scale with a scalar bar, e.g. conductors by their potential. A flat scene (every point in one plane) is viewed face on.

Parameters

NameTypeDefaultDescription
meshesmesh, sequence of meshes, or dict of str to meshrequiredA mesh is a pyvista.PolyData (any other pyvista dataset is drawn by its surface), a (vertices, faces) pair of arrays with shapes (n, 3) and (m, 3) (triangles, as from skimage.measure.marching_cubes), or an object with vertices and cells such as simgeometry’s SurfaceMesh. Faces with two columns are line segments, and (n, 2) vertices lie in the z = 0 plane. A dict’s keys are the labels. Empty meshes are skipped.
labelssequence of strNoneOne label per mesh, for the legend. Default: the dict’s keys, else none.
colorscolor, sequence of colors, or dict of str to colorNoneColors of the meshes, by position or by label; any Matplotlib color. Default: Matplotlib’s color cycle, continued from earlier calls into the same plotter.
scalarsstr or callableNoneColor by this point-data array of every mesh, or by scalars(points), a function of the (n, 3) points that returns n values. The scalar bar shows the array’s name, or the function’s name. Default: plain colors.
cmapstr or matplotlib colormapNoneThe colormap for scalars. Default: "viridis".
clim(float, float)NoneColor limits for scalars. Default: the range over all meshes.
opacityfloat, sequence of float, or dict of str to float1.0Opacity of the meshes, one for all or by position or label. Default: 1.
show_edgesboolFalseDraw the mesh edges. Default: False.
titlestrNoneText in the scene’s corner. Default: none.
legendboolTruePut the labels in the scene’s legend, shown when it has two or more entries (not with scalars). Default: True.
plotterpyvista.PlotterNoneDraw into this scene instead of a new one, to combine several views. The camera is only aimed at the surfaces when this function creates the plotter.

Returns

pyvista.Plotter
The scene, not yet shown: call .show() or .screenshot(path).

Raises

TypeError
If a mesh is none of the accepted kinds.
ValueError
If labels, colors or opacity don’t match the meshes, faces index missing vertices, or a mesh lacks the scalars array.

Examples

>>> import pyvista as pv
>>> pyvista_surfaces(
... {"inner": pv.Sphere(radius=0.5), "outer": pv.Sphere()},
... opacity={"inner": 1.0, "outer": 0.3},
... ).show()
>>> vertices, faces, _, _ = skimage.measure.marching_cubes(values, level=0)
>>> pyvista_surfaces(
... (vertices, faces), scalars=lambda p: p[:, 2], show_edges=True
... ).show()

save_moviefunction#

def save_movie(data: xr.DataArray, path, *, kind: Literal['isosurface', 'slices', 'glyphs', 'streamlines'] = 'slices', sweep: str = 't', step: int = 1, framerate: int = 10, clim=None, window_size=(1024, 768), **options)

Render one 3-D view per sweep step into a GIF (.gif) or video (.mp4, …).

kind picks the view and options are passed on to it. Scalar views share color limits over the whole sweep (override with clim), and the camera is fixed after the first frame. GIFs need imageio, videos imageio-ffmpeg.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA field with dimension sweep plus what the view kind needs (see pyvista_slices(), pyvista_glyphs(), …).
pathstr or pathlib.PathrequiredThe output file: a GIF for .gif, a video (e.g. .mp4) for any other suffix.
kind('isosurface', 'slices', 'glyphs', 'streamlines')"isosurface"The view of each frame. Default: "slices".
sweepstr't'The dimension to step through, one frame per step. Default: "t".
stepint1Use every step-th position of sweep. Default: 1.
framerateint10Frames per second. Default: 10.
clim(float, float)NoneColor limits of the scalar views ("isosurface", "slices"). Default: from the whole sweep, with the symmetric and robust options.
window_size(int, int)(1024, 768)Frame size in pixels. Default: (1024, 768).
**options{}Passed on to the view, e.g. cuts or cmap. A title is prefixed to each frame’s "<sweep> = <value>" label (default: the field’s label).

Returns

str
The path of the written file.

Raises

ValueError
If kind is unknown, step isn’t a positive integer, or data has no sweep dimension.

Examples

>>> save_movie(phi, "phi.gif", cuts={"eta3": 0}, symmetric=True)
>>> save_movie(B, "B.mp4", kind="glyphs", step=2)

save_vtkfunction#

def save_vtk(data: xr.DataArray, path, *, name: str | None = None) -> list[str]

Write a field to VTK structured grids (.vts) on its physical points, for ParaView.

With a t dimension, one file per time is written into the directory path, plus a .pvd collection that ParaView opens as a time series; without one, path is a single .vts file. Vector fields (component) become point vectors. Any array works, e.g. a filter_time() result, so filtered modes can be inspected in ParaView too.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA field over (eta1, eta2, eta3) (and optionally t and component) with physical coordinates X, Y, Z; every other dimension selected.
pathstr or pathlib.PathrequiredThe .vts file (the suffix is set to .vts), or with a t dimension the directory to write into (created if needed).
namestrNoneThe name of the point data, also the file stem in a time series. Default: the field’s label.

Returns

list of str
The written paths: the .vts file, or the .pvd collection followed by one .vts file per time.

Examples

>>> save_vtk(phi, "vtk/phi")
>>> save_vtk(phi.isel(t=-1), "phi_last.vts")

scenefunction#

def scene(plotter, *, alt: str | None = None, title: str | None = None, window_size=None, backend: Literal['vtkjs', 'plotly'] = 'vtkjs', decimate: float | None = None) -> Scene

Show a pyvista.Plotter as an interactive 3-D scene in a notebook.

As the last expression of a cell, the result displays as a standalone vtk.js page (text/html) plus a screenshot (image/png). Jupyter shows the page; docs sites built from the notebook show the screenshot and swap in the scene on click. alt and title travel in the output’s "pyvista-scene" metadata.

The screenshot needs an off-screen plotter: plotters created in a notebook are, and in a script set pyvista.OFF_SCREEN = True (or pass off_screen=True) before creating one. The export needs trame-pyvista: pip install "plasma-plots[scene]".

With backend="plotly" the scene displays as a Plotly 3-D figure instead (scene_to_plotly()): lighter, themed like the page and with values on hover, but without vtk.js’ rendering of large meshes. It needs neither a screenshot nor trame.

Parameters

NameTypeDefaultDescription
plotterpyvista.PlotterrequiredThe scene, e.g. from phi.plasma.plot.isosurface(...). Set its camera first.
altstrNoneA text alternative for the screenshot.
titlestrNoneA title for the scene, e.g. of the frame it is shown in.
window_size(int, int)NoneThe screenshot’s size in pixels. Default: the plotter’s window size.
backend('vtkjs', 'plotly')"vtkjs"A vtk.js page with a screenshot, or a Plotly figure. Default: "vtkjs".
decimatefloatNoneFraction of each surface’s triangles to drop in the vtk.js export. Default: none.

Returns

Scene
Displays itself in Jupyter; .save_png(path) and .save_html(path) write the two files, e.g. for a docs page.

Examples

>>> plotter = phi.plasma.plot.isosurface(values=[-0.5, 0.5], t=-1)
>>> plasma_plots.scene(plotter, alt="Two isosurfaces of phi")

scene_to_plotlyfunction#

def scene_to_plotly(plotter, *, max_faces: int | None = 200000)

Convert a pyvista.Plotter into an interactive Plotly 3-D figure.

Surfaces become Mesh3d traces (colored by their scalars on the plotter’s color scale, or in their solid color), lines and point sets Scatter3d traces, each with its opacity. The first colored surface carries a color bar titled like the plotter’s scalar bar. The camera follows the plotter’s. A Plotly figure is lighter than a vtk.js page (no viewer inlined), follows the page’s theme and shows values on hover; prefer the vtk.js scene of scene() for very large meshes.

Parameters

NameTypeDefaultDescription
plotterpyvista.PlotterrequiredThe scene.
max_facesint or None200000Surfaces with more triangles are decimated to about this many (None keeps them). Default: 200 000.

Returns

plotly.graph_objects.Figure
The figure.

Examples

>>> plotter = torus.mod_B.plasma.plot.slices_3d(cuts={"rho": [1.0]})
>>> scene_to_plotly(plotter).show()

structured_gridfunction#

def structured_grid(data: xr.DataArray, *, name: str | None = None)

A pyvista.StructuredGrid of a selected (eta1, eta2, eta3) field on its physical points.

A scalar field becomes point data name (default: the field’s label); a vector field with a component dimension of three Cartesian components becomes point vectors name, plus their magnitude as "|name|". Periodic directions are closed, see plasma_plots.arrays.close_periodic(). The grid is useful directly for any PyVista filter.

Parameters

NameTypeDefaultDescription
dataxarray.DataArrayrequiredA field with dims (eta1, eta2, eta3) (one of them may be selected away), or (component, eta1, eta2, eta3) for a vector field, and physical coordinates X, Y, Z.
namestrNoneThe name of the point data. Default: the field’s label.

Returns

pyvista.StructuredGrid
The grid with the field as its active scalars or vectors.

Raises

ValueError
If other dimensions remain, the physical coordinates are missing, fewer than two logical dimensions are left, or a vector field doesn’t have three components.

Examples

>>> grid = structured_grid(phi.isel(t=-1))
>>> grid.contour([0.0]).plot()