plotting module

class wakis.plotting.PlotMixin[source]

Bases: object

Plotting mixin providing 1D/2D/3D visualization helpers.

inspect(wake=None, window_size=None, off_screen=False, opacity=1.0, inactive_opacity=0.1, add_silhouette=False, specular=0.5, smooth_shading=False)[source]

Interactive inspection of STL solids and optional wake geometry.

Provides a PyVista-based UI to toggle visibility and highlighting for the package STL solids. When a wake object is provided the method also creates a beam and an integration-path actor and exposes check boxes to toggle them. A master checkbox toggles all solids at once.

Parameters

  • wake (object or None, optional) – Optional wake-like object (for example a WakeSolver instance) that provides xsource, ysource, xtest and ytest attributes used to place a beam and an integration path. When provided the object is stored as self.wake. Default None.

  • window_size (sequence or None, optional) – Tuple (width, height) passed to pyvista.Plotter to set the window size. Default None (use PyVista defaults).

  • off_screen (bool, optional) – If True the plotter is not shown interactively and the method returns the created pyvista.Plotter instance for programmatic control and screenshot capture. Default False.

  • opacity (float, optional) – Opacity applied to solids when they are active/highlighted (default 1.0).

  • inactive_opacity (float, optional) – Opacity applied to solids when inactive (default 0.1).

  • add_silhouette (bool, optional) – When True add a silhouette actor behind each solid for emphasis.

  • specular (float, optional) – Specular lighting value forwarded to pyvista.Plotter.add_mesh for STL actors (default 0.5).

  • smooth_shading (bool, optional) – Enable smooth shading for STL meshes (default False).

Returns

Returns the created pyvista.Plotter when off_screen is True so the caller can save screenshots or control rendering programmatically. Otherwise shows the interactive window and returns None.

Return type

pyvista.Plotter or None

Notes

  • The method expects self.stl_solids and self.stl_colors to be populated and uses self.grid.read_stl(key) to load surfaces.

  • When running under MPI the method prints a warning and returns immediately (interactive plotting is not supported under MPI).

plot1D(field='E', component='z', line='z', pos=[0.5], xscale='linear', yscale='linear', xlim=None, ylim=None, figsize=[8, 4], title=None, off_screen=False, n=None, colors=None, **kwargs)[source]

Built-in 1D plotting of a field line using matplotlib.

Plots 1D cuts along a grid line (x, y or z) for the selected field component. Supports plotting multiple positions and MPI gathering when running in parallel.

Parameters

  • field (str, optional) – Field to plot: β€˜E’, β€˜H’, or β€˜J’. Two-letter values (e.g. β€˜Ex’) are accepted and override component. Default β€˜E’.

  • component (str, optional) – Component to plot (β€˜x’,’y’,’z’,’Abs’). Default β€˜z’.

  • line (str or sequence, optional) – Line specification as β€˜x’,’y’,’z’ or a sequence of three indices or slices (e.g. [0, slice(10,Ny-10), 0]). Default β€˜z’.

  • pos (float or sequence, optional) – Relative position(s) (0-1) used when line is a single-axis specifier. Default 0.5.

  • xscale (str, optional) – Axis scaling passed to matplotlib (default β€˜linear’).

  • yscale (str, optional) – Axis scaling passed to matplotlib (default β€˜linear’).

  • xlim (sequence, optional) – Axis limits for the plot.

  • ylim (sequence, optional) – Axis limits for the plot.

  • figsize (sequence, optional) – Figure size for the matplotlib figure (default [8,4]).

  • title (str, optional) – Basename used to save screenshots when off_screen=True.

  • off_screen (bool, optional) – If True save the figure to disk instead of showing it interactively.

  • n (int, optional) – Timestep index appended to saved filenames.

  • colors (sequence, optional) – Colors used for each plotted line when multiple positions are requested.

  • **kwargs (dict) – Extra keyword arguments forwarded to matplotlib.axes.Axes.plot.

Return type

None

Notes

  • When running with MPI (use_mpi=True), only rank 0 will display or save the figure.

plot2D(field='E', component='z', plane='ZY', pos=0.5, norm=None, vmin=None, vmax=None, figsize=[8, 4], cmap='jet', patch_alpha=0.1, patch_reverse=False, add_patch=False, title=None, off_screen=False, n=None, interpolation='antialiased', dpi=100, return_handles=False)[source]

Built-in 2D plotting of a field slice using matplotlib.

Renders a 2D cut through the structured grid and displays the selected field component using matplotlib.pyplot.imshow. Optionally adds a patch showing STL masks as overlays.

Parameters

  • field (str, optional) – Field to plot: β€˜E’, β€˜H’, or β€˜J’. Two-letter values (e.g. β€˜Ex’) are accepted and override component. Default β€˜E’.

  • component (str, optional) – Component to plot (β€˜x’,’y’,’z’,’Abs’). Default β€˜z’.

  • plane (str or sequence, optional) – Cut plane specified as β€˜XY’, β€˜ZY’, β€˜ZX’ or a sequence of slices and an integer index [x,y,z]. Default β€˜XZ’.

  • pos (float, optional) – Relative position in the normal direction for the cut (0-1). Default 0.5 (center).

  • norm (str or None, optional) – Color normalization for imshow (β€˜linear’,’log’,’symlog’).

  • vmin (scalar, optional) – Color limits for the plot.

  • vmax (scalar, optional) – Color limits for the plot.

  • figsize (sequence, optional) – Figure size for the matplotlib figure (default [8,4]).

  • cmap (str, optional) – Colormap for the field plot (default β€˜jet’).

  • patch_alpha (float, optional) – Alpha value for STL mask overlays (default 0.1).

  • patch_reverse (bool, optional) – If True, reverse the mask for the patch overlay.

  • add_patch (str or list, optional) – STL key or list of keys to overlay as a mask patch on the plot.

  • title (str, optional) – Basename used to save screenshots when off_screen=True.

  • off_screen (bool, optional) – If True save the figure to disk instead of showing it interactively.

  • n (int, optional) – Timestep index appended to saved filenames.

  • interpolation (str, optional) – Interpolation method for imshow (default β€˜antialiased’).

  • dpi (int, optional) – Dots per inch for the figure (default 100).

  • return_handles (bool, optional) – If True return the (fig, ax) handles instead of showing.

Returns

Returns (fig, ax) if return_handles=True, otherwise None.

Return type

None or tuple

Notes

  • When running with MPI (use_mpi=True), only rank 0 will display or save the figure.

  • STL patch overlays are not supported when running under MPI.

plot3D(field='E', component='z', clim=None, hide_solids=None, show_solids=None, add_stl=None, stl_opacity=0.1, stl_colors='white', title=None, cmap='jet', clip_interactive=True, clip_normal='-y', clip_box=False, clip_bounds=None, off_screen=False, zoom=0.5, camera_position=None, nan_opacity=1.0, n=None)[source]

Built-in 3D plotting using PyVista.

Displays a cell-centered field (E, H or J) on the structured grid using PyVista. Optionally overlays STL solids, clipping widgets or a static clip box. When rendered off-screen the plot can be saved to a PNG file for later composition into animations.

Parameters

  • field (str, optional) – 3D field magnitude to plot: β€˜E’, β€˜H’, or β€˜J’. A two-letter value (e.g., β€˜Ex’) is accepted to plot a single component; in that case component is overridden. Default β€˜E’.

  • component (str, optional) – Component of the field to plot: β€˜x’, β€˜y’, β€˜z’, or β€˜Abs’. Default β€˜z’. Overridden when field contains a component.

  • clim (sequence, optional) – Colorbar limits for the field plot as [min, max].

  • hide_solids (str, list, or None, optional) – If provided, mask values inside the named STL solids to np.nan. NaNs are shown in grey due to a known PyVista opacity limitation.

  • show_solids (str, list, or None, optional) – If provided, mask values outside the named STL solids to np.nan.

  • add_stl (str or list, optional) – STL solid key or list of keys to add to the scene via pv.add_mesh.

  • stl_opacity (float, optional) – Opacity for STL surfaces (0 transparent, 1 opaque). Default 0.1.

  • stl_colors (str or list, optional) – Color or list of colors for STL surfaces (default β€˜white’).

  • title (str, optional) – Basename used to save screenshots when off_screen=True.

  • cmap (str, optional) – Colormap name for the field display (default β€˜jet’).

  • clip_interactive (bool, optional) – Enable an interactive clipping plane widget (default False).

  • clip_normal (str, optional) – Normal direction for the interactive clip plane (default β€˜-y’).

  • clip_box (bool, optional) – Enable a static box clipping of the domain (default False).

  • clip_bounds (sequence, optional) – Box bounds as [xmin,xmax,ymin,ymax,zmin,zmax] when clip_box is active.

  • off_screen (bool, optional) – Render off-screen and save screenshots instead of opening an interactive window (default False).

  • zoom (float, optional) – Camera zoom factor (default 0.5).

  • camera_position (str, sequence, or None, optional) – Camera position preset or coordinates (default None).

  • nan_opacity (float, optional) – Opacity for NaN values produced by masking (default 1.0).

  • n (int, optional) – Timestep index appended to saved screenshot filenames.

Return type

None

Notes

  • When running with MPI (use_mpi=True), plotting is not supported.

  • The method modifies the PyVista plotter state and may save screenshots if off_screen=True.

plot3DonSTL(field='E', component='z', clim=None, cmap='jet', log_scale=False, stl_with_field=None, field_opacity=1.0, tolerance=None, stl_transparent=None, stl_opacity=0.1, stl_colors='white', clip_plane=False, clip_interactive=False, clip_normal='-x', clip_origin=[0, 0, 0], clip_box=False, clip_bounds=None, title=None, off_screen=False, n=None, zoom=0.5, camera_position=None, **kwargs)[source]

Built-in 3D plotting sampling fields onto STL surfaces.

Samples a cell-centered field onto STL surfaces and visualizes the sampled field. Supports clipping with a plane or a static box and rendering the STL surfaces with or without sampled field data.

Parameters

  • field (str, optional) – Field to sample and plot: β€˜E’, β€˜H’, or β€˜J’. Two-letter values like β€˜Ex’ are accepted and override component. Default β€˜E’.

  • component (str, optional) – Component to plot (β€˜x’, β€˜y’, β€˜z’, β€˜Abs’). Default β€˜z’.

  • clim (sequence, optional) – Color limits for the plotted field.

  • cmap (str, Colormap, optional) – Colormap for field rendering (default β€˜jet’).

  • log_scale (bool, optional) – Use logarithmic color scaling when True (default False).

  • stl_with_field (str or list, optional) – STL key or list of keys whose surfaces will be sampled with the selected field.

  • field_opacity (float, optional) – Opacity for the sampled field rendering on STL surfaces.

  • tolerance (float, optional) – Sampling tolerance passed to pyvista.PolyData.sample.

  • stl_transparent (str or list, optional) – STL solids to add to the scene with transparent rendering.

  • stl_opacity (float, optional) – Opacity for non-sampled STL solids (default 0.1).

  • stl_colors (str or list, optional) – Colors used for STL solids (default β€˜white’).

  • clip_interactive (bool, optional) – Enable an interactive clipping plane for sampled surfaces.

  • clip_plane (bool, optional) – Clip the STL surface with a plane and show the field on the plane.

  • clip_normal (str, optional) – Normal direction for clipping operations (default β€˜-x’).

  • clip_origin (sequence, optional) – Origin for planar clipping when clip_plane is True.

  • clip_box (bool, optional) – Clip sampled surfaces using a static box (default False).

  • clip_bounds (sequence, optional) – Bounds for the static clip box as [xmin,xmax,ymin,ymax,zmin,zmax].

  • title (str, optional) – Basename used to save screenshots when off_screen=True.

  • off_screen (bool, optional) – Render off-screen and save screenshots when True.

  • n (int, optional) – Timestep index appended to saved filenames.

  • zoom (float, optional) – Camera zoom factor (default 0.5).

  • camera_position (str, sequence, or None, optional) – Camera position preset or coordinates (default None).

  • **kwargs (dict) – Extra keyword arguments forwarded to pyvista.Plotter.add_mesh.

Return type

None

Notes

  • When running with MPI (use_mpi=True), plotting is not supported.

  • The method modifies the PyVista plotter state and may save screenshots if off_screen=True.