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
| Name | Description |
|---|---|
ORBIT_CLASS_COLORS | No description. |
RENDERERS | No description. |
SCENE_EXTRA | No description. |
Classes
| Name | Description |
|---|---|
Scene | A pyvista.Plotter displayed as an interactive 3-D scene; see scene(). |
Functions
| Name | Description |
|---|---|
boundary_faces | Return the real boundary faces of a point array, see boundary_keys(). |
boundary_keys | Find the logical faces of a (n1, n2, n3, 3) point array that are real boundaries. |
coil_polylines | Coils as one closed pyvista.PolyData line per coil, with point data color_by. |
is_flat | Whether a structured grid has a single point in one logical direction (a 2-D run or cut). |
orbit_polylines | Marker orbits as one pyvista.PolyData line per marker, with point data color_by. |
prepare_slices_3d | The logical cuts of a scalar (eta1, eta2, eta3) field that pyvista_slices() draws. |
push_forward | Cartesian components of a vector field given by contravariant logical components. |
pyvista_coils | Stellarator coils as tubes, optionally around the plasma surface. |
pyvista_domain | The mapping of a Struphy domain as a wireframe of logical grid lines. |
pyvista_glyphs | Arrows of a selected (component, eta1, eta2, eta3) vector field, colored by magnitude. |
pyvista_isosurface | Contour surfaces of a selected scalar (eta1, eta2, eta3) field in physical space. |
pyvista_orbits | Marker orbits as 3-D lines (or tubes), colored by time, orbit class, or any variable. |
pyvista_points | Point sets in physical space, such as samples, grid nodes or crossings, optionally with arrows. |
pyvista_slices | Surfaces of constant logical coordinate through a scalar field, drawn in physical space. |
pyvista_streamlines | Field lines of a selected vector field, e.g. magnetic field lines, colored by magnitude. |
pyvista_surfaces | Surface meshes in physical space, such as geometry or marching-cubes surfaces. |
save_movie | Render one 3-D view per sweep step into a GIF (.gif) or video (.mp4, ...). |
save_vtk | Write a field to VTK structured grids (.vts) on its physical points, for ParaView. |
scene | Show a pyvista.Plotter as an interactive 3-D scene in a notebook. |
scene_to_plotly | Convert a pyvista.Plotter into an interactive Plotly 3-D figure. |
structured_grid | A 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
| Name | Type | Default | Description |
|---|---|---|---|
plotter | pyvista.Plotter | required | The scene, off screen. |
alt | str | None | A text alternative for the screenshot. |
title | str | None | A title for the scene. |
window_size | (int, int) | None | The 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". |
decimate | float | None | Fraction of the triangles to remove from each surface in the vtk.js export (e.g. 0.5). Default: keep them all. |
altattributeinstance attribute#
alt = altbackendattributeinstance attribute#
backend = backenddecimateattributeinstance attribute#
decimate = decimateplotterattributeinstance attribute#
plotter = plottertitleattributeinstance attribute#
title = titlewindow_sizeattributeinstance attribute#
window_size = window_sizehtmlmethod#
def html() -> strThe 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
sceneextra).
pngmethod#
def png() -> bytesThe 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) -> strWrite the scene to a standalone HTML file.
Parameters
| Name | Type | Description |
|---|---|---|
path | str or pathlib.Path | The file to write. |
Returns
strpath, as a string.
save_pngmethod#
def save_png(path) -> strWrite the screenshot to a PNG file.
Parameters
| Name | Type | Description |
|---|---|---|
path | str or pathlib.Path | The file to write. |
Returns
strpath, as a string.
to_plotlymethod#
def to_plotly(**options)The scene as a Plotly 3-D figure; see scene_to_plotly().
Parameters
| Name | Default | Description |
|---|---|---|
**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
| Name | Type | Description |
|---|---|---|
points | numpy.ndarray | Physical 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
| Name | Type | Description |
|---|---|---|
points | numpy.ndarray | Physical points, shape (n1, n2, n3, 3). |
Returns
list of (int, int)(axis, index)of each boundary face;indexis0or-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
| Name | Type | Default | Description |
|---|---|---|---|
coils | xarray.Dataset | required | Coils over (coil, s) with coordinates X, Y, Z, from
plasma_plots.from_coilset(). |
color_by | str | None | A 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
coilsisn’t over(coil, s), lacksX,Y,Z, orcolor_byisn’t a variable overcoilor(coil, s).
is_flatfunction#
def is_flat(grid) -> boolWhether a structured grid has a single point in one logical direction (a 2-D run or cut).
Parameters
| Name | Type | Description |
|---|---|---|
grid | pyvista.StructuredGrid | The grid, e.g. from structured_grid(). |
Returns
boolTrueif 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
| Name | Type | Default | Description |
|---|---|---|---|
orbits | xarray.Dataset | required | Marker orbits with dims (t, marker) and physical positions x, y, z. |
color_by | str | 't' | The point data to attach: "t", "classification" or a variable name.
Default: "t". |
max_markers | int | 200 | At 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_byis neither"t","classification"nor a variable oforbits.
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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A scalar field with dims (eta1, eta2, eta3) and physical coordinates X, Y,
Z. |
cuts | dict | None | {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.DataArrayCartesian 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
| Name | Type | Description |
|---|---|---|
data | xarray.DataArray | The vector field, dims (component, eta1, eta2, eta3) with three contravariant
components and physical coordinates X, Y, Z. |
Returns
xarray.DataArray- The Cartesian
x,y,zcomponents, 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
| Name | Type | Default | Description |
|---|---|---|---|
coils | xarray.Dataset | required | Coils over (coil, s) with coordinates X, Y, Z, from
plasma_plots.from_coilset(). |
color_by | str | None | Color 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. |
color | color | '#b87333' | The coils’ color without color_by; any Matplotlib color. Default: copper. |
tube_radius | float | None | Radius of the tubes, in m. Default: 0.4 % of the coils’ extent; 0 for plain lines. |
cmap | str or matplotlib colormap | None | The colormap for color_by. Default: "viridis". |
clim | (float, float) | None | Color limits for color_by. Default: the values’ range. |
surface | xarray.Dataset or xarray.DataArray | None | The 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_opacity | float | 1.0 | Opacity of the surface. Default: 1. |
surface_cmap | str or matplotlib colormap | None | The colormap of a DataArray surface. Default: "plasma". |
surface_clim | (float, float) | None | Color limits of a DataArray surface, e.g. to compare two scenes on one scale.
Default: the values’ range. |
title | str | None | Text in the scene’s corner. Default: "Coils"; "" for none. |
plotter | pyvista.Plotter | None | Draw 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_byare not as described, orsurfacelacksX,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
| Name | Type | Default | Description |
|---|---|---|---|
domain | callable | required | A Struphy domain (mapping), e.g. out.domain, called as
domain(eta1, eta2, eta3, squeeze_out=False) to give x, y, z. |
n1 | int | 8 | Grid lines along eta1. Default: 8. |
n2 | int | 32 | Grid lines along eta2. Default: 32. |
n3 | int | 32 | Grid lines along eta3. Default: 32. |
resolution | int | 4 | Samples per line spacing, so curved lines stay smooth. Default: 4. |
color | str | 'black' | Color of the grid lines. Default: "black". |
surface | bool | True | Draw the translucent boundary surface. Default: True. |
cross_section | bool | True | Also draw grid lines over the eta3 = 0 face. Default: True. |
title | str | None | Text in the scene’s corner. Default: "Domain"; "" for none. |
plotter | pyvista.Plotter | None | Draw 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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A 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". |
stride | int | 2 | Draw an arrow at every stride-th point in every direction. Default: 2. |
scale | float | None | Arrow length of the largest vector, in physical units. Default: a tenth of the domain size. |
cmap | str or matplotlib colormap | 'viridis' | The colormap of the magnitude. Default: "viridis". |
show_domain | bool | True | Draw the domain’s outer surface translucently for context. Default: True. |
title | str | None | Text in the scene’s corner. Default: the field’s label; "" for none. |
plotter | pyvista.Plotter | None | Draw 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
strideis less than 1,componentsis 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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A scalar field with dims (eta1, eta2, eta3) (every other dimension selected; one
logical dimension may be selected away) and physical coordinates X, Y, Z. |
values | int or list of float | 5 | The number of evenly spaced levels strictly between the color limits, or explicit levels. Default: 5. |
cmap | str or matplotlib colormap | 'viridis' | The colormap. Default: "viridis". |
opacity | float or sequence of float | 1.0 | Opacity 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. |
colors | color or sequence of colors | None | Colors 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). |
labels | sequence of str | None | One legend entry per level; giving them shows the legend even without colors.
Default: "level <value>". |
clim | (float, float) | None | Color limits; default from the field’s values, see symmetric and robust. |
show_domain | bool | True | Draw the domain’s outer surface translucently for context (3-D fields only).
Default: True. |
title | str | None | Text in the scene’s corner. Default: the field’s label; "" for none. |
symmetric | bool | False | Color limits symmetric about zero. Default: False. |
robust | bool | False | Color limits from percentiles instead of the extremes, so outliers don’t wash out the
colors. Default: False. |
plotter | pyvista.Plotter | None | Draw 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,colorsorlabelsdon’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
| Name | Type | Default | Description |
|---|---|---|---|
orbits | xarray.Dataset | required | Marker orbits with dims (t, marker) and physical positions x, y, z. |
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 scene, not yet shown: call
.show()or.screenshot(path).
Raises
ValueError- If
color_byis neither"t","classification"nor a variable oforbits.
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
| Name | Type | Default | Description |
|---|---|---|---|
points | array, sequence of arrays, or dict of str to array | required | One 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. |
labels | sequence of str | None | One label per set, for the legend. Default: the dict’s keys, else none. |
colors | color, sequence of colors, or dict of str to color | None | Colors of the sets, by position or by label; any Matplotlib color. Default:
Matplotlib’s color cycle, continued from earlier calls into the same plotter. |
scalars | callable, array, sequence of arrays, or dict of str to array | None | Color 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. |
cmap | str or matplotlib colormap | None | The colormap for scalars. Default: "viridis". |
clim | (float, float) | None | Color limits for scalars. Default: the range over all sets. |
size | float, sequence of float, or dict of str to float | 8 | Point size in pixels, one for all or by position or label. Default: 8. |
opacity | float, sequence of float, or dict of str to float | 1.0 | Opacity of the sets (and their arrows), one for all or by position or label. Default: 1. |
vectors | array, sequence of arrays, or dict of str to array | None | A 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_scale | float | None | The 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. |
title | str | None | Text in the scene’s corner. Default: none. |
legend | bool | True | Put the labels in the scene’s legend, shown when it has two or more entries (not with
scalars). Default: True. |
plotter | pyvista.Plotter | None | Draw 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,scalarsorvectorsdon’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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A scalar field with dims (eta1, eta2, eta3) (every other dimension selected; one
logical dimension may be selected away) and physical coordinates X, Y, Z. |
cuts | dict | None | {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. |
cmap | str or matplotlib colormap | 'viridis' | The colormap. Default: "viridis". |
clim | (float, float) | None | Color limits, shared by every cut; default from the whole field’s values, see
symmetric and robust. |
show_domain | bool | True | Draw the domain’s outer surface translucently for context. Not drawn when the whole plane of a
2-D field is shown. Default: True. |
title | str | None | Text in the scene’s corner. Default: the field’s label; "" for none. |
symmetric | bool | False | Color limits symmetric about zero. Default: False. |
robust | bool | False | Color limits from percentiles instead of the extremes, so outliers don’t wash out the
colors. Default: False. |
opacity | float | 1.0 | Opacity of the cuts, from 0 (invisible) to 1, e.g. to see what is drawn inside a flux
surface. Default: 1.0. |
plotter | pyvista.Plotter | None | Draw 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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A 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_points | int | 100 | The number of seed points (at most the number of grid points when seeding on the grid). Default: 100. |
source_radius | float | None | Seed 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) | None | Seed in a sphere around this physical point instead of at grid points. Default (when
source_radius is given): the bounding-box center. |
max_length | float | None | Maximum length of each line. Default: four times the domain size. |
tube_radius | float | None | Draw the lines as tubes of this radius. Default: plain lines. |
cmap | str or matplotlib colormap | 'viridis' | The colormap of the magnitude. Default: "viridis". |
show_domain | bool | True | Draw the domain’s outer surface translucently for context. Default: True. |
title | str | None | Text in the scene’s corner. Default: "<label> field lines"; "" for none. |
plotter | pyvista.Plotter | None | Draw 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
componentsis 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
| Name | Type | Default | Description |
|---|---|---|---|
meshes | mesh, sequence of meshes, or dict of str to mesh | required | A 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. |
labels | sequence of str | None | One label per mesh, for the legend. Default: the dict’s keys, else none. |
colors | color, sequence of colors, or dict of str to color | None | Colors of the meshes, by position or by label; any Matplotlib color. Default:
Matplotlib’s color cycle, continued from earlier calls into the same plotter. |
scalars | str or callable | None | Color 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. |
cmap | str or matplotlib colormap | None | The colormap for scalars. Default: "viridis". |
clim | (float, float) | None | Color limits for scalars. Default: the range over all meshes. |
opacity | float, sequence of float, or dict of str to float | 1.0 | Opacity of the meshes, one for all or by position or label. Default: 1. |
show_edges | bool | False | Draw the mesh edges. Default: False. |
title | str | None | Text in the scene’s corner. Default: none. |
legend | bool | True | Put the labels in the scene’s legend, shown when it has two or more entries (not with
scalars). Default: True. |
plotter | pyvista.Plotter | None | Draw 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,colorsoropacitydon’t match the meshes, faces index missing vertices, or a mesh lacks thescalarsarray.
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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A field with dimension sweep plus what the view kind needs (see
pyvista_slices(), pyvista_glyphs(), …). |
path | str or pathlib.Path | required | The 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". |
sweep | str | 't' | The dimension to step through, one frame per step. Default: "t". |
step | int | 1 | Use every step-th position of sweep. Default: 1. |
framerate | int | 10 | Frames per second. Default: 10. |
clim | (float, float) | None | Color 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
kindis unknown,stepisn’t a positive integer, ordatahas nosweepdimension.
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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A field over (eta1, eta2, eta3) (and optionally t and component) with
physical coordinates X, Y, Z; every other dimension selected. |
path | str or pathlib.Path | required | The .vts file (the suffix is set to .vts), or with a t dimension the
directory to write into (created if needed). |
name | str | None | The 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
.vtsfile, or the.pvdcollection followed by one.vtsfile 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) -> SceneShow 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
| Name | Type | Default | Description |
|---|---|---|---|
plotter | pyvista.Plotter | required | The scene, e.g. from phi.plasma.plot.isosurface(...). Set its camera first. |
alt | str | None | A text alternative for the screenshot. |
title | str | None | A title for the scene, e.g. of the frame it is shown in. |
window_size | (int, int) | None | The 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". |
decimate | float | None | Fraction 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
| Name | Type | Default | Description |
|---|---|---|---|
plotter | pyvista.Plotter | required | The scene. |
max_faces | int or None | 200000 | Surfaces 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
| Name | Type | Default | Description |
|---|---|---|---|
data | xarray.DataArray | required | A 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. |
name | str | None | The 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()