plotting module

class wakis.plotting.PlotMixinGrid[source]

Bases: object

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

inspect(add_stl=None, stl_opacity=0.5, stl_colors=None, anti_aliasing='ssaa', smooth_shading=True, off_screen=False)[source]

Interactive 3D inspector showing grid and STL geometries.

Parameters

  • add_stl (str or list, optional) – Key or list of keys of STL solids to include. If None, all solids are shown.

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

  • stl_colors (str, list, or dict, optional) – Color specification for STL surfaces; defaults to self.stl_colors.

  • anti_aliasing (str or None, optional) – Anti-aliasing mode to enable in the plotter (default β€˜ssaa’).

  • smooth_shading (bool, optional) – Enable smooth shading for surfaces (default True).

  • off_screen (bool, optional) – If True, return the off-screen plotter object instead of showing an interactive window.

Returns

pl – The plotter object if off_screen is True, otherwise None.

Return type

pyvista.Plotter or None

plot_snap_points(snap_solids=None, snap_tol=1e-8)[source]

Plot snap points extracted from STL feature edges for mesh refinement.

Parameters

  • snap_solids (list or None, optional) – STL solids to use for snap point extraction. Default is all.

  • snap_tol (float, optional) – Tolerance for snap point detection.

plot_solids(bounding_box=False, show_grid=False, anti_aliasing=None, opacity=1.0, specular=0.5, smooth_shading=False, off_screen=False, **kwargs)[source]

Generate a 3D visualization of imported STL geometries using PyVista.

Parameters

  • bounding_box (bool, optional) – If True, adds a bounding box around the plotted geometry (default False).

  • show_grid (bool, optional) – If True, overlays the grid wireframe on the scene (default False).

  • anti_aliasing (str or None, optional) – Anti-aliasing mode passed to PyVista (default: None).

  • opacity (float, optional) – Opacity for solids (1.0 opaque, 0.0 transparent). Default 1.0.

  • specular (float, optional) – Specular lighting strength, higher is shinier (default 0.5).

  • smooth_shading (bool, optional) – Enable smooth shading for surface rendering (default False).

  • off_screen (bool, optional) – If True, export to HTML instead of opening an interactive window.

  • **kwargs (dict) – Additional keyword args forwarded to pyvista.add_mesh.

Notes

  • Colors come from self.stl_colors when available.

  • Solids labeled β€˜vacuum’ are rendered with reduced opacity by default.

plot_stl_mask(stl_solid, cmap='viridis', bounding_box=True, clip_plane='x', add_stl=True, stl_opacity=0.1, stl_colors=None, anti_aliasing='ssaa', smooth_shading=False, off_screen=False)[source]

Interactive 3D visualization of the structured grid mask and imported STL geometries.

This routine uses PyVista to display the grid scalar field corresponding to a chosen STL mask. It provides interactive slider widgets to clip the domain along the X, Y, and Z directions. At each slider position, the clipped scalar field is shown with a colormap while the grid structure is shown as a 2D slice in wireframe. Optionally, one or more STL geometries can be added to the scene, along with a bounding box of the simulation domain.

Parameters

  • stl_solid (str) – Key name of the stl_solids dictionary to retrieve the mask for visualization (used as the scalar field).

  • cmap (str, optional) – Colormap used to visualize the clipped scalar values. Default β€˜viridis’.

  • bounding_box (bool, optional) – If True, add a static wireframe bounding box of the simulation domain.

  • show_grid (bool, optional) – If True, adds the computational grid overlay on the clipped slice.

  • add_stl ({True, 'all', str, list[str]}, optional) –

    STL geometries to add. Default True adds the STL solid corresponding to the mask.

    If β€˜all’, add all STL solids. If a string, add the STL solid with that key. If a list of strings, add the STL solids with those keys. False or None will not add any STL solids.

  • stl_opacity (float, optional) – Opacity of the STL surfaces (0 = fully transparent, 1 = fully opaque).

  • stl_colors (str, list[str], dict, or None, optional) – Color(s) of the STL surfaces.

  • xmax (float, optional) – Initial clipping positions along each axis. If None, use the maximum domain extent.

  • ymax (float, optional) – Initial clipping positions along each axis. If None, use the maximum domain extent.

  • zmax (float, optional) – Initial clipping positions along each axis. If None, use the maximum domain extent.

  • anti_aliasing ({'ssaa', 'fxaa', None}, optional) – Anti-aliasing mode passed to pl.enable_anti_aliasing.

  • smooth_shading (bool, optional) – Enable smooth shading for STL surfaces. Default False.

  • off_screen (bool, optional) – If True, render off-screen and export the scene to HTML.

Notes

  • Three sliders (X, Y, Z) control clipping of the scalar field by a box.

  • STL solids can be visualized in transparent mode.

  • A static domain bounding box can be added for reference.

plot_stl_mask_slice(stl_solid, plane='ZX', position=None, cmap='viridis', bounding_box=False, show_grid=True, add_stl=False, stl_opacity=0.1, stl_colors=None, smooth_shading=False, off_screen=False)[source]

Interactive 2D slice visualization of the structured grid STL mask.

Lighter alternative to plot_stl_mask() for heavy grids (>10M cells). Instead of clipping the full 3D domain, only a single 2D slice is rendered at a time. A slider widget controls the slice position along the axis normal to the chosen plane.

Parameters

  • stl_solid (str) – Key name of the stl_solids dictionary to retrieve the mask for visualization (used as the scalar field).

  • plane ({'XY', 'YX', 'ZY', 'YZ', 'ZX', 'XZ'}, optional) –

    Plane of the slice. Default β€˜ZX’.

    • ’XY’ / β€˜YX’ β†’ normal along Z, slider controls Z position.

    • ’ZY’ / β€˜YZ’ β†’ normal along X, slider controls X position.

    • ’ZX’ / β€˜XZ’ β†’ normal along Y, slider controls Y position.

  • position (float or None, optional) – Initial position of the slice along the normal axis. If None, uses the center of the domain along that axis.

  • cmap (str, optional) – Colormap used to visualize the scalar values. Default β€˜viridis’.

  • bounding_box (bool, optional) – If True, add a static wireframe bounding box of the simulation domain.

  • add_stl ({True, 'all', str, list[str]}, optional) –

    STL geometries to add. Default True adds the STL solid corresponding to the mask.

    If β€˜all’, add all STL solids. If a string, add the STL solid with that key. If a list of strings, add the STL solids with those keys. False or None will not add any STL solids.

  • stl_opacity (float, optional) – Opacity of the STL surfaces (0 = fully transparent, 1 = fully opaque).

  • stl_colors (str, list[str], dict, or None, optional) – Color(s) of the STL surfaces.

  • smooth_shading (bool, optional) – Enable smooth shading for STL surfaces. Default False.

  • off_screen (bool, optional) – If True, render off-screen and return the plotter object.

Notes

  • Only a single 2D slice of the domain is rendered at a time, making this much lighter than plot_stl_mask() for large grids.

  • The slider controls the slice position along the normal to the chosen plane.
    • The selected stl_solid intersection with the plane is overlaid as a

      contour line for easier visual alignment.

class wakis.plotting.PlotMixinSolver[source]

Bases: object

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

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, backend='matplotlib')[source]

Built-in 2D plotting of a field slice.

Renders a 2D cut through the structured grid using either a matplotlib (imshow) or PyVista (static slice) backend.

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 β€˜ZY’.

  • 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’). Matplotlib backend only.

  • 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 overlays (default 0.1).

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

  • add_patch (str or list, optional) – STL key or list of keys to overlay. Matplotlib: drawn as a filled mask patch. PyVista: drawn as STL contour lines on the slice.

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

  • off_screen (bool, optional) – Matplotlib: save figure to disk. PyVista: return plotter object.

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

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

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

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

  • backend ({'matplotlib', 'pyvista'}, optional) – Visualization backend. Default β€˜matplotlib’.

Returns

  • (fig, ax) when backend='matplotlib' and return_handles=True or off_screen=True.

  • pyvista.Plotter when backend='pyvista' and off_screen=True.

  • None otherwise.

Return type

None or tuple or pyvista.Plotter

Notes

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

  • 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.