emout.plot package

Submodules

emout.plot.animation_plot module

Animation framework for time-series EMSES data.

FrameUpdater wraps a single data series and produces per-frame plots, while Animator orchestrates one or more updaters into a matplotlib.animation.FuncAnimation.

class emout.plot.animation_plot.Animator(layout)[source]

Bases: object

Orchestrate multiple FrameUpdaters into an animated plot.

property frames

Minimum frame count among managed FrameUpdaters.

plot(fig=None, action='to_html', filename=None, interval=200, repeat=True, show=False, savefilename=None, to_html=False)[source]

Create a GIF animation.

Parameters:

  • fig (Union[plt.Figure, None], optional) – Figure to use for rendering. If None, the current figure is used.

  • action (ANIMATER_PLOT_MODE, optional) – Post-generation action mode. ‘return’ returns (fig, animation), ‘show’ displays the animation, ‘to_html’ returns HTML, ‘save’ saves to filename.

  • filename (PathLike, optional) – Output file path when action=’save’.

  • interval (int, optional) – Frame interval in milliseconds.

  • repeat (bool, optional) – Whether to loop the animation.

  • show (bool, optional) – Deprecated. If True, treated as action=’show’.

  • savefilename (PathLike, optional) – Deprecated. When given, treated as action=’save’.

  • to_html (bool, optional) – Deprecated. If True, treated as action=’to_html’.

Returns:

Rendering result depending on action.

Return type:

object

property shape

Layout shape as (nrows, ncols).

class emout.plot.animation_plot.FrameUpdater(data, axis=0, title=None, notitle=False, offsets=None, use_si=True, **kwargs)[source]

Bases: object

Single data series frame updater for animation.

to_animator(layout=None)[source]

Convert to an Animator.

Parameters:

layout (List[List[List[FrameUpdater]]]) – Layout for the animation plot.

update(i)[source]

Render the slice for the specified frame.

Parameters:

i (int) – Frame number.

Return type:

None

emout.plot.animation_plot.flatten_list(l)[source]

Flatten a nested iterable into a 1-D sequence.

Parameters:

l (object) – Arbitrarily nested iterable. Strings and bytes are treated as single elements.

Returns:

Iterator that yields elements in flattened order.

Return type:

Iterator

emout.plot.basic_plot module

Low-level plotting helpers for scalar and vector fields.

Re-exports from _plot_2d and _plot_3d for backward compatibility.

emout.plot.basic_plot.figsize_with_2d(data2d, dpi=10)[source]

Compute figure size from 2-D data shape.

Parameters:

  • data2d (numpy.ndarray) – 2-D data array.

  • dpi (int, optional) – Pixels per data point, by default 10.

Returns:

Figure size in inches.

Return type:

(float, float)

emout.plot.basic_plot.plot_2d_contour(data2d, mesh=None, levels=None, colors=None, cmap=None, alpha=1, vmin=None, vmax=None, savefilename=None, figsize=None, xlabel=None, ylabel=None, title=None, dpi=10, fmt='%1.1f', fontsize=12, **kwargs)[source]

Plot 2-D contour lines.

Parameters:

  • data2d (numpy.ndarray) – 2-D data array.

  • mesh ((numpy.ndarray, numpy.ndarray), optional) – Mesh grid, by default None.

  • levels (int) – Number of contour levels, by default None.

  • alpha (float) – Opacity (0.0 to 1.0), by default 1.

  • savefilename (str, optional) – Output file path (None to skip saving), by default None.

  • cmap (matplotlib.Colormap or str or None, optional) – Colormap, by default None.

  • mask_color (str) – Color for masked positions, by default ‘gray’.

  • vmin (float, optional) – Minimum value, by default None.

  • vmax (float, optional) – Maximum value, by default None.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – X-axis label, by default None.

  • ylabel (str, optional) – Y-axis label, by default None.

  • title (str, optional) – Title, by default None.

  • interpolation (str, optional) – Interpolation method, by default ‘bilinear’.

  • dpi (int, optional) – Resolution (ignored when figsize is specified), by default 10.

  • fmt (str) – Contour label format, by default ‘%1.1f’.

  • fontsize (str) – Contour label font size, by default 12.

Returns:

Plotted image data (None when saved to file).

Return type:

AxesImage or None

emout.plot.basic_plot.plot_2d_streamline(x_data2d, y_data2d, mesh=None, savefilename=None, skip=1, figsize=None, xlabel=None, ylabel=None, title=None, dpi=10, color=None, cmap=None, norm='linear', vmin=None, vmax=None, density=1, **kwargs)[source]

Plot a 2-D streamline field.

Parameters:

  • x_data2d (numpy.ndarray) – 2-D data arrays for vector components.

  • y_data2d (numpy.ndarray) – 2-D data arrays for vector components.

  • mesh ((numpy.ndarray, numpy.ndarray), optional) – Mesh grid, by default None.

  • savefilename (str, optional) – Output file path (None to skip saving), by default None.

  • color (str) – Streamline color, by default None.

  • scale (float) – Vector magnitude scale factor (multiplied to final size), by default 1.

  • skip (int) – Plotting data interval, by default 1.

  • easy_to_read (bool) – If True, scale vectors to a legible size, by default True.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – X-axis label, by default None.

  • ylabel (str, optional) – Y-axis label, by default None.

  • title (str, optional) – Title, by default None.

  • interpolation (str, optional) – Interpolation method, by default ‘bilinear’.

  • dpi (int, optional) – Resolution (ignored when figsize is specified), by default 10.

Returns:

Plotted image data (None when saved to file).

Return type:

AxesImage or None

emout.plot.basic_plot.plot_2d_vector(x_data2d, y_data2d, mesh=None, savefilename=None, scale=1, scaler='standard', skip=1, easy_to_read=True, figsize=None, xlabel=None, ylabel=None, title=None, dpi=10, cmap=None, **kwargs)[source]

Plot a 2-D vector field.

Parameters:

  • x_data2d (numpy.ndarray) – 2-D data arrays for vector components.

  • y_data2d (numpy.ndarray) – 2-D data arrays for vector components.

  • mesh ((numpy.ndarray, numpy.ndarray), optional) – Mesh grid, by default None.

  • savefilename (str, optional) – Output file path (None to skip saving), by default None.

  • color (str) – Vector color, by default None.

  • scale (float) – Vector magnitude scale factor (multiplied to final size), by default 1.

  • skip (int) – Plotting data interval, by default 1.

  • easy_to_read (bool) – If True, scale vectors to a legible size, by default True.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – X-axis label, by default None.

  • ylabel (str, optional) – Y-axis label, by default None.

  • title (str, optional) – Title, by default None.

  • interpolation (str, optional) – Interpolation method, by default ‘bilinear’.

  • dpi (int, optional) – Resolution (ignored when figsize is specified), by default 10.

Returns:

Plotted image data (None when saved to file).

Return type:

AxesImage or None

emout.plot.basic_plot.plot_2dmap(data2d, mesh=None, savefilename=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, mask_color='gray', vmin=None, vmax=None, figsize=None, xlabel=None, ylabel=None, title=None, interpolation='bilinear', dpi=10, colorbar_label='', cbargs=None, add_colorbar=True, **kwargs)[source]

Plot a 2-D colormap.

Parameters:

  • data2d (numpy.ndarray) – 2-D data array.

  • mesh ((numpy.ndarray, numpy.ndarray), optional) – Mesh grid, by default None.

  • savefilename (str, optional) – Output file path (None to skip saving), by default None.

  • cmap (matplotlib.Colormap or str or None, optional) – Colormap, by default cm.coolwarm.

  • mask_color (str) – Color for masked positions, by default ‘gray’.

  • vmin (float, optional) – Minimum value, by default None.

  • vmax (float, optional) – Maximum value, by default None.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – X-axis label, by default None.

  • ylabel (str, optional) – Y-axis label, by default None.

  • title (str, optional) – Title, by default None.

  • interpolation (str, optional) – Interpolation method, by default ‘bilinear’.

  • dpi (int, optional) – Resolution (ignored when figsize is specified), by default 10.

  • add_colorbar (bool, optional) – If True, add a colorbar, by default True.

Returns:

Plotted image data (None when saved to file).

Return type:

AxesImage or None

emout.plot.basic_plot.plot_3d_quiver(x_data3d, y_data3d, z_data3d, ax3d=None, mesh=None, savefilename=None, scale=1, scaler='standard', skip=1, easy_to_read=True, figsize=None, xlabel=None, ylabel=None, title=None, dpi=10, cmap=None, **kwargs)[source]

Plot a 3-D quiver (vector) field.

Parameters:

  • x_data2d (numpy.ndarray) – 3-D data arrays for vector components.

  • y_data2d (numpy.ndarray) – 3-D data arrays for vector components.

  • mesh ((numpy.ndarray, numpy.ndarray), optional) – Mesh grid, by default None.

  • savefilename (str, optional) – Output file path (None to skip saving), by default None.

  • color (str) – Vector color, by default None.

  • scale (float) – Vector magnitude scale factor (multiplied to final size), by default 1.

  • skip (int) – Plotting data interval, by default 1.

  • easy_to_read (bool) – If True, scale vectors to a legible size, by default True.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – X-axis label, by default None.

  • ylabel (str, optional) – Y-axis label, by default None.

  • title (str, optional) – Title, by default None.

  • interpolation (str, optional) – Interpolation method, by default ‘bilinear’.

  • dpi (int, optional) – Resolution (ignored when figsize is specified), by default 10.

Returns:

Plotted image data (None when saved to file).

Return type:

AxesImage or None

emout.plot.basic_plot.plot_3d_streamline(x_data3d, y_data3d, z_data3d, ax=None, mesh=None, n_seeds=50, seed_points=None, max_length=200.0, step_size=0.5, color=None, cmap='viridis', colorby='magnitude', linewidth=1.0, alpha=0.8, xlabel=None, ylabel=None, zlabel=None, title=None, show=False, savefilename=None, figsize=None, **kwargs)[source]

Plot 3-D streamlines of a vector field using matplotlib.

Field lines are traced from seed_points (or randomly placed seeds) by integrating the normalised vector field with scipy.integrate.solve_ivp().

Parameters:

  • x_data3d (numpy.ndarray) – 3-D arrays of shape (nz, ny, nx) for each vector component.

  • y_data3d (numpy.ndarray) – 3-D arrays of shape (nz, ny, nx) for each vector component.

  • z_data3d (numpy.ndarray) – 3-D arrays of shape (nz, ny, nx) for each vector component.

  • ax (Axes3D, optional) – Target 3-D axes. Created automatically when None.

  • mesh (tuple of numpy.ndarray, optional) – (X, Y, Z) coordinate arrays.

  • n_seeds (int, default 50) – Number of random seed points (ignored when seed_points is set).

  • seed_points (numpy.ndarray, optional) – Explicit seed points of shape (N, 3) as (x, y, z).

  • max_length (float, default 200.0) – Maximum integration arc length per streamline.

  • step_size (float, default 0.5) – RK45 maximum step size in grid units.

  • color (str, optional) – Uniform line colour. Overrides cmap/colorby.

  • cmap (str, default "viridis") – Colour map when colorby is "magnitude".

  • colorby ({"magnitude", None}, default "magnitude") – Colour each segment by the local field magnitude.

  • linewidth (float, default 1.0)

  • alpha (float, default 0.8)

  • xlabel (str, optional)

  • ylabel (str, optional)

  • zlabel (str, optional)

  • title (str, optional)

  • show (bool, default False)

  • savefilename (path-like, optional)

  • figsize (tuple of float, optional)

  • **kwargs – Forwarded to ax.plot().

Return type:

Axes3D

emout.plot.basic_plot.plot_line(data1d, x=None, savefilename=None, vmin=None, vmax=None, figsize=None, xlabel=None, ylabel=None, label=None, title=None, **kwargs)[source]

Plot 1-D data.

Parameters:

  • data1d (array-like or scalar) – 1-D data to plot.

  • x (array-like or scalar) – 1-D data for the horizontal axis, by default None.

  • savefilename (str, optional) – Output file path, by default None.

  • vmin (float, optional) – Minimum value, by default None.

  • vmax (float, optional) – Maximum value, by default None.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – Horizontal axis label, by default None.

  • ylabel (str, optional) – Vertical axis label, by default None.

  • label (str, optional) – Legend label, by default None.

  • title (str, optional) – Title, by default None.

Returns:

Line object representing the plotted data (None when saved to file).

Return type:

Line2D or None

emout.plot.basic_plot.plot_surface(x, y, z, value, ax3d=None, add_colorbar=False, savefilename=None, cmap=<matplotlib.colors.LinearSegmentedColormap object>, mask_color='gray', vmin=None, vmax=None, figsize=None, xlabel=None, ylabel=None, zlabel=None, title=None, ninterp=1, function='linear', dpi=10, colorbar_label='', **kwargs)[source]

Plot a 3-D surface.

Parameters:

  • x ((numpy.ndarray, numpy.ndarray), optional) – X-coordinate mesh.

  • y ((numpy.ndarray, numpy.ndarray), optional) – Y-coordinate mesh.

  • z ((numpy.ndarray, numpy.ndarray), optional) – Z-coordinate mesh.

  • val ((numpy.ndarray, numpy.ndarray), optional) – Value mesh.

  • ax3d (Axes3D) – Axes3D object, by default None.

  • savefilename (str, optional) – Output file path (None to skip saving), by default None.

  • cmap (matplotlib.Colormap or str or None, optional) – Colormap, by default cm.coolwarm.

  • vmin (float, optional) – Minimum value, by default None.

  • vmax (float, optional) – Maximum value, by default None.

  • figsize ((float, float), optional) – Figure size, by default None.

  • xlabel (str, optional) – X-axis label, by default None.

  • ylabel (str, optional) – Y-axis label, by default None.

  • zlabel (str, optional) – Z-axis label, by default None.

  • title (str, optional) – Title, by default None.

  • dpi (int, optional) – Resolution (ignored when figsize is specified), by default 10.

Returns:

Plotted image data (None when saved to file).

Return type:

AxesImage or None

emout.plot.extra_plot module

Supplementary plotting helpers for boundary cross-sections with holes.

emout.plot.extra_plot.plot_hole_line(inp_or_data, unit=None, use_si=True, offsets=(0, 0), axis='xz', color='black', linewidth=None, fix_lims=True)[source]

Draw a rectangular hole outline on a 2-D plane.

Parameters:

  • inp_or_data (Union[InpFile, "Emout"]) – InpFile or Emout object.

  • unit (Units, optional) – Unit conversion object. Auto-detected when inp_or_data is Emout.

  • use_si (bool, optional) – If True, draw in SI units.

  • offsets (Tuple[int, int], optional) – Display offset in (x, y) directions.

  • axis (str, optional) – Cross-section axis to draw. Currently only “xz” is supported.

  • color (str, optional) – Line color.

  • linewidth (float, optional) – Line width.

  • fix_lims (bool, optional) – If True, fix axis limits before drawing.

Returns:

Line objects returned by plt.plot.

Return type:

list[matplotlib.lines.Line2D]

emout.plot.extra_plot.plot_line_of_hole_half(inp, off, unit)[source]

Draw auxiliary lines for a half-section hole shape on a 3-D axis.

Parameters:

  • inp (InpFile) – Input parameters containing hole definition.

  • off (int) – Offset width for extended display.

  • unit (UnitTranslator) – Unit conversion object.

Return type:

None

emout.plot.extra_plot.plot_surface_with_hole(data_xyz, inp, add_colorbar=True, show=False, vrange='minmax', **kwargs)[source]

Render a 3-D surface with a rectangular hole.

Internally calls data_xyz[…].plot(mode=”surf”, **kwargs) multiple times to draw the top, side, and bottom surfaces.

Parameters:

  • data_xyz (Data3d) – 3-D data to render.

  • inp (InpFile) – Input parameters containing hole geometry (xlrechole, etc.).

  • add_colorbar (bool, optional) – Whether to add a colorbar on the last (bottom) surface plot.

  • show (bool, optional) – If True, call plt.show() at the end.

  • vrange ({'minmax', 'center'}, optional) – Method for determining the color-scale range. ‘center’ uses a symmetric range centered at 0.

  • **kwargs (dict) – Arguments forwarded to Data2d.plot(mode=”surf”). Primarily use_si, offsets, cmap, vmin, vmax, xlabel, ylabel, zlabel, title, ninterp, function, figsize, dpi, and additional mpl_toolkits.mplot3d.Axes3D.plot_surface arguments.

Return type:

None

emout.plot.extra_plot.plot_surface_with_hole_half(data_xyz, inp, off=10, add_colorbar=True, show=False, vrange='minmax', **kwargs)[source]

Render a half cross-section surface of a rectangular hole.

Parameters:

  • data_xyz (Data3d) – 3-D data to render.

  • inp (InpFile) – Input parameters containing hole geometry (xlrechole, etc.).

  • off (int, optional) – Offset width for the cross-section.

  • add_colorbar (bool, optional) – Whether to add a colorbar on the last (bottom) surface plot.

  • show (bool, optional) – If True, call plt.show() at the end.

  • vrange ({'minmax', 'center'}, optional) – Method for determining the color-scale range.

  • **kwargs (dict) – Arguments forwarded to Data2d.plot(mode=”surf”). Primarily use_si, offsets, cmap, vmin, vmax, xlabel, ylabel, zlabel, title, ninterp, function, figsize, dpi, and additional mpl_toolkits.mplot3d.Axes3D.plot_surface arguments.

Return type:

None

Notes

An ax3d is created internally and set to kwargs[“ax3d”]. Any ax3d passed by the caller will be overwritten.

emout.plot.plot_cross_sections module

Cross-section plotting for MPIEMSES finbound boundaries.

Renders sphere, flat-surface, and rectangle boundaries on a 2-D plane using information from the plasma.inp parameter file.

emout.plot.plot_cross_sections.plot_cross_sections(data, axis='z', coord=0.0, ax=None, use_si=True, **kwargs)[source]

Plot cross-sections of boundary objects.

Parameters:

  • data (object) – Data to process.

  • axis (str, optional) – Target axis.

  • coord (float, optional) – Position at which to take the cross-section. For axis=’z’ this is a z coordinate; for axis=’x’/’y’ the corresponding coordinate.

  • ax (Optional[plt.Axes], optional) – Target Axes for drawing.

  • use_si (bool, optional) – If True, use SI units.

  • **kwargs (dict) – Extra keyword arguments forwarded to internal drawing functions.

Returns:

The Axes object with the rendered cross-sections.

Return type:

plt.Axes

emout.plot.pyvista_plot module

PyVista plotting helpers for scalar and vector fields.

Re-exports from submodules for backward compatibility.

emout.plot.pyvista_plot.create_plane_mesh(data2d, use_si=True, offsets=None, scalar_name=None)[source]

Create a PyVista plane mesh from a 2-D scalar field.

Parameters:

  • data2d (Data2d) – 2-D grid data to visualise.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • scalar_name (str, optional) – Name for the scalar data array attached to the mesh. Defaults to data2d.name.

Returns:

  • mesh (pyvista.StructuredGrid) – Plane mesh with scalar values attached.

  • scalar_name (str) – Name of the scalar array on the mesh.

  • axis_labels (dict[str, str]) – Axis label strings.

  • scalar_label (str) – Human-readable scalar label including units.

emout.plot.pyvista_plot.create_vector_mesh3d(x_data3d, y_data3d, z_data3d, use_si=True, offsets=None, vector_name='vectors', magnitude_name='magnitude')[source]

Create a PyVista mesh from three vector-component arrays.

Parameters:

  • x_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data. All three must share the same shape and spatial axes.

  • y_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data. All three must share the same shape and spatial axes.

  • z_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data. All three must share the same shape and spatial axes.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • vector_name (str, optional) – Name for the vector data array attached to the mesh.

  • magnitude_name (str, optional) – Name for the magnitude scalar array attached to the mesh.

Returns:

  • mesh (pyvista.ImageData) – Volume mesh with vector and magnitude arrays.

  • vector_name (str) – Name of the vector array on the mesh.

  • magnitude_name (str) – Name of the magnitude array on the mesh.

  • axis_labels (dict[str, str]) – Axis label strings.

emout.plot.pyvista_plot.create_volume_mesh(data3d, use_si=True, offsets=None, scalar_name=None)[source]

Create a PyVista volume mesh from a 3-D scalar field.

Parameters:

  • data3d (Data3d) – 3-D grid data to visualise.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • scalar_name (str, optional) – Name for the scalar data array attached to the mesh. Defaults to data3d.name.

Returns:

  • mesh (pyvista.ImageData) – Volume mesh with scalar values attached.

  • scalar_name (str) – Name of the scalar array on the mesh.

  • axis_labels (dict[str, str]) – Axis label strings.

  • scalar_label (str) – Human-readable scalar label including units.

emout.plot.pyvista_plot.plot_scalar_plane(data2d, plotter=None, use_si=True, offsets=None, show=False, cmap='viridis', clim=None, scalar_name=None, show_edges=False, add_scalar_bar=True, **kwargs)[source]

Plot a 2-D scalar field on a PyVista plane.

Parameters:

  • data2d (Data2d) – 2-D grid data to visualise.

  • plotter (pyvista.Plotter, optional) – Existing plotter to draw into. A new one is created if None.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • show (bool, optional) – If True, call plotter.show() before returning.

  • cmap (str, optional) – Colour-map name forwarded to PyVista.

  • clim (tuple of float, optional) – (vmin, vmax) colour limits.

  • scalar_name (str, optional) – Name for the scalar data array on the mesh.

  • show_edges (bool, optional) – Show mesh edge lines.

  • add_scalar_bar (bool, optional) – Add a colour-bar to the plotter.

  • **kwargs – Additional keyword arguments forwarded to plotter.add_mesh.

Returns:

The plotter instance used for rendering.

Return type:

pyvista.Plotter

emout.plot.pyvista_plot.plot_scalar_volume(data3d, mode='box', plotter=None, use_si=True, offsets=None, show=False, cmap='viridis', clim=None, opacity='sigmoid', contour_levels=8, scalar_name=None, add_outline=True, outline_color='white', add_scalar_bar=True, show_edges=False, **kwargs)[source]

Plot a 3-D scalar field as a volume rendering.

Parameters:

  • data3d (Data3d) – 3-D grid data to visualise.

  • mode ({'box', 'volume', 'slice', 'contour'}, optional) – Rendering mode. 'box' extracts the outer surface, 'volume' uses GPU volume rendering, 'slice' shows orthogonal slices, and 'contour' draws iso-surfaces.

  • plotter (pyvista.Plotter, optional) – Existing plotter to draw into. A new one is created if None.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • show (bool, optional) – If True, call plotter.show() before returning.

  • cmap (str, optional) – Colour-map name forwarded to PyVista.

  • clim (tuple of float, optional) – (vmin, vmax) colour limits.

  • opacity (float or str, optional) – Opacity for volume rendering. Can be a transfer function name such as 'sigmoid'.

  • contour_levels (int or np.ndarray, optional) – Number of iso-surfaces (or explicit levels) when mode=’contour’.

  • scalar_name (str, optional) – Name for the scalar data array on the mesh.

  • add_outline (bool, optional) – Draw an outline box around the volume.

  • outline_color (str, optional) – Colour of the outline box.

  • add_scalar_bar (bool, optional) – Add a colour-bar to the plotter.

  • show_edges (bool, optional) – Show mesh edge lines (used in 'box' mode).

  • **kwargs – Additional keyword arguments forwarded to plotter.add_mesh or plotter.add_volume.

Returns:

The plotter instance used for rendering.

Return type:

pyvista.Plotter

emout.plot.pyvista_plot.plot_vector_quiver3d(x_data3d, y_data3d, z_data3d, plotter=None, use_si=True, offsets=None, show=False, skip=2, scale_by_magnitude=True, factor=None, cmap='viridis', clim=None, add_scalar_bar=True, **kwargs)[source]

Plot a 3-D vector field as quiver arrows.

Parameters:

  • x_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data.

  • y_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data.

  • z_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data.

  • plotter (pyvista.Plotter, optional) – Existing plotter to draw into. A new one is created if None.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • show (bool, optional) – If True, call plotter.show() before returning.

  • skip (int or tuple of int, optional) – Down-sampling factor for quiver arrows. A single integer applies to all axes; a 3-tuple (skip_x, skip_y, skip_z) allows per-axis control.

  • scale_by_magnitude (bool, optional) – Scale arrow length by vector magnitude.

  • factor (float, optional) – Glyph scale factor. When None an automatic value is computed from the domain size and mean magnitude.

  • cmap (str, optional) – Colour-map name forwarded to PyVista.

  • clim (tuple of float, optional) – (vmin, vmax) colour limits.

  • add_scalar_bar (bool, optional) – Add a colour-bar to the plotter.

  • **kwargs – Additional keyword arguments forwarded to plotter.add_mesh.

Returns:

The plotter instance used for rendering.

Return type:

pyvista.Plotter

emout.plot.pyvista_plot.plot_vector_streamlines3d(x_data3d, y_data3d, z_data3d, plotter=None, use_si=True, offsets=None, show=False, n_points=200, source_radius=None, source_center=None, tube_radius=None, cmap='viridis', clim=None, add_scalar_bar=True, **kwargs)[source]

Plot a 3-D vector field as streamlines.

Parameters:

  • x_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data.

  • y_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data.

  • z_data3d (Data3d) – X-, Y-, and Z-component 3-D grid data.

  • plotter (pyvista.Plotter, optional) – Existing plotter to draw into. A new one is created if None.

  • use_si (bool, optional) – Convert coordinates and values to SI units.

  • offsets (tuple of (float or str or None), optional) – Per-axis positional offsets (x, y, z).

  • show (bool, optional) – If True, call plotter.show() before returning.

  • n_points (int, optional) – Number of seed points for streamline integration.

  • source_radius (float, optional) – Radius of the spherical seed source. Defaults to 25 % of the smallest domain extent.

  • source_center (tuple of float, optional) – Centre of the seed source. Defaults to the mesh centre.

  • tube_radius (float, optional) – If given, render streamlines as tubes with this radius.

  • cmap (str, optional) – Colour-map name forwarded to PyVista.

  • clim (tuple of float, optional) – (vmin, vmax) colour limits.

  • add_scalar_bar (bool, optional) – Add a colour-bar to the plotter.

  • **kwargs – Additional keyword arguments forwarded to mesh.streamlines.

Returns:

The plotter instance used for rendering.

Return type:

pyvista.Plotter

Raises:

RuntimeError – If no streamlines could be generated with the given parameters.

emout.plot.surface_cut package

surface_cut

Utilities for: - Uniform cell-centered 3D grid data (nz,ny,nx) - SciPy-based interpolation (Field3D) - Explicit triangle mesh surfaces (MeshSurface3D and friends) - Optional visualization utilities (plot_surfaces, RenderItem, …)

The legacy SDF-based implicit surface system (Surface3D and SurfaceCutter) was removed; everything goes through MeshSurface3D now. The high-level entry points for boundary meshes built from data.inp live in emout.emout.boundaries.

Star-import control is provided via __all__.

class emout.plot.surface_cut.Bounds3D(x, y, z)[source]

Bases: object

Axis-aligned 3-D bounding box.

expanded(frac=0.05)[source]

Return a new Bounds expanded by the given fraction.

Parameters:

frac (float, optional) – Fraction by which to expand each interval.

Returns:

Expanded bounding box.

Return type:

“Bounds3D”

x: Tuple[float, float]
y: Tuple[float, float]
z: Tuple[float, float]
class emout.plot.surface_cut.BoxMeshSurface(xmin, xmax, ymin, ymax, zmin, zmax, *, faces=None, resolution=(2, 2), resolution_scale=1.0)[source]

Bases: MeshSurface3D

Axis-aligned box (cuboid) mesh with selectable faces.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.CircleMeshSurface(center, axis, radius, *, ntheta=64, nradial=8, theta_range=None, flip_normal=False, resolution_scale=1.0)[source]

Bases: MeshSurface3D

Flat circular disc in a plane perpendicular to axis.

The disc is centered on center with the given radius. Its orientation is controlled by axis (the outward normal). Use it for the MPIEMSES circlex/circley/circlez boundary primitives or whenever you need a single filled disk in 3D.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.CompositeMeshSurface(children)[source]

Bases: MeshSurface3D

Composite mesh surface that concatenates child mesh surfaces.

Construct with a sequence of MeshSurface3D instances (or use the + operator on mesh surfaces). The composite’s mesh() calls each child’s mesh() and welds them into a single (V, F) pair using _combine_meshes.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.CylinderMeshSurface(center, axis, radius, *, length=None, tmin=None, tmax=None, parts=None, ntheta=64, naxial=2, nradial=8, theta_range=None, resolution_scale=1.0)[source]

Bases: MeshSurface3D

Finite cylinder surface with selectable side/top/bottom parts.

Optionally a theta_range may be given to take an angular subrange of the cylinder (e.g. a half section). A full 2π range (the default) yields a closed mesh.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.DiskMeshSurface(center, axis, outer_radius, inner_radius, *, length=None, tmin=None, tmax=None, parts=None, ntheta=64, naxial=2, nradial=8, theta_range=None, resolution_scale=1.0)[source]

Bases: MeshSurface3D

Annular disk (tube) with finite axial thickness.

Represents the MPIEMSES diskx/disky/diskz finbound primitive: a ring with outer and inner cylindrical walls plus two annular end caps. Unlike HollowCylinderMeshSurface (rectangular slab with a hole), the outer boundary here is also circular.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.Field3D(grid, data_zyx)[source]

Bases: object

Holds (nz,ny,nx) cell-centered data and a SciPy interpolator.

Note: RegularGridInterpolator expects axes in the same order as data indexing.

Here we define axes as (z, y, x) to match data[k,j,i].

sample(x, y, z)[source]

Interpolate the 3-D field at the given coordinates.

Parameters:

  • x (np.ndarray) – X-coordinate array.

  • y (np.ndarray) – Y-coordinate array.

  • z (np.ndarray) – Z-coordinate array.

Returns:

Interpolated values with the broadcast shape of x, y, z.

Return type:

np.ndarray

class emout.plot.surface_cut.HollowCylinderMeshSurface(center, axis, width, inner_radius, *, length=None, tmin=None, tmax=None, parts=None, ntheta=64, naxial=2, nradial=8, nwall=2, theta_range=None, resolution_scale=1.0)[source]

Bases: MeshSurface3D

Rectangular slab pierced by an axial cylindrical hole.

Despite the historical name, this surface is not a hollow cylinder. It represents a rectangular block extending along axis with a circular hole of inner_radius drilled through the middle. Use it when you want to highlight “a rectangle with a centered circular hole” plus the hole wall, for example to visualize a probe aperture on a planar electrode.

Geometry

  • The slab’s cross section in the plane perpendicular to axis is a rectangle of size width (a single float yields a square; a (width_u, width_v) tuple yields an arbitrary rectangle). The rectangle is centered on center in the local (e1, e2) frame derived from axis.

  • Axially the slab extends over length (centered on center) or, equivalently, tmin..tmax.

  • A cylindrical hole of inner_radius runs through the slab on the axis direction. It must fit inside the rectangle (inner_radius < min(width_u, width_v) / 2).

Parts

  • "outer" – the 4 rectangular side walls of the slab.

  • "inner" – the cylindrical hole surface (inward-facing).

  • "top" – the cap at tmax: rectangle with a central circular hole.

  • "bottom" – the cap at tmin: rectangle with a central circular hole.

Optional theta_range lets you take an angular subrange of every theta-parameterized part (inner hole and both caps). The rectangular side walls are unaffected — restrict them with parts if needed.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.MeshSurface3D[source]

Bases: ABC

Explicit triangle mesh surface for plot_surfaces.

Each subclass knows how to materialise a structured (V, F) triangle mesh for a specific shape (box, cylinder, sphere, …). Use + to compose multiple shapes into a CompositeMeshSurface and render() to wrap one in a RenderItem ready for emout.plot.surface_cut.plot_surfaces().

abstractmethod mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

render(**style_kwargs)[source]

Wrap this mesh surface in a RenderItem ready for plot_surfaces.

Parameters:

**style_kwargs – Forwarded to emout.plot.surface_cut.viz.RenderItem (e.g. style="solid", solid_color="0.7", alpha=0.5).

Returns:

A render item wrapping self.

Return type:

RenderItem

class emout.plot.surface_cut.PlaneWithCircleMeshSurface(center, axis, width, inner_radius, *, ntheta=64, nradial=8, theta_range=None, flip_normal=False, resolution_scale=1.0)[source]

Bases: MeshSurface3D

Flat rectangular plane containing a central circular hole.

Unlike HollowCylinderMeshSurface — which is a solid slab with a cylindrical hole through it — this surface is a zero-thickness panel. It is the natural representation for the MPIEMSES finbound primitives plane-with-circlex/y/z, where a single flat conducting plane has a round aperture cut out of it.

The rectangle is centered on center, lies in the plane perpendicular to axis and spans width ((width_u, width_v) in the local frame). The circular hole of inner_radius is concentric with the rectangle and must satisfy inner_radius < min(width_u, width_v) / 2.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.RectangleMeshSurface(center=None, axis=None, width=None, *, pmin=None, pmax=None, resolution=(2, 2), resolution_scale=1.0, flip_normal=False)[source]

Bases: MeshSurface3D

Single flat rectangular panel in 3D.

Two construction forms are accepted:

  1. Symmetric / oriented form — give center, axis, width:

    RectangleMeshSurface(
    center=(2.5, 4.0, 5.0),
    axis="z",
    width=(3.0, 4.0),
)

    The rectangle lies in the plane orthogonal to axis passing through center, with half-widths (width_u/2, width_v/2) in the local (e1, e2) frame derived from axis. This works for any axis direction (including non-axis-aligned 3-vectors).

  2. Corner form — give two opposite corners pmin and pmax:

    RectangleMeshSurface(pmin=(1, 2, 5), pmax=(4, 6, 5))

    Convenient for axis-aligned rectangles when you already know the extents but do not want to compute the centre by hand. pmin and pmax must share exactly one coordinate; that coordinate picks the perpendicular axis ("x", "y", or "z") and the remaining two coordinates define the rectangle’s extent.

Unlike BoxMeshSurface (which only produces axis-aligned faces), this class lets you place a single arbitrarily-oriented rectangular panel anywhere in space — convenient for highlighting a probe window, a transparent cutting plane, or any planar mark.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.RenderItem(surface, style='field', solid_color='0.6', alpha=None, draw_contours=True, edge_color=None, edge_lw=0.4)[source]

Bases: object

Rendering specification for a mesh surface.

style:

  • ‘field’: color by sampled field values (colormap)

  • ‘solid’: constant face color (e.g., gray cut faces)

alpha: float | None = None
draw_contours: bool = True
edge_color: str | None = None
edge_lw: float = 0.4
solid_color: str | Tuple[float, float, float] | Tuple[float, float, float, float] = '0.6'
style: Literal['field', 'solid'] = 'field'
surface: object
class emout.plot.surface_cut.SphereMeshSurface(center, radius, *, axis='z', ntheta=48, nphi=25, theta_range=None, phi_range=None, resolution_scale=1.0)[source]

Bases: MeshSurface3D

Sphere mesh via latitude–longitude parameterization.

The sphere of radius is centered on center. The local poles lie on axis (default "z"): latitude phi runs from -π/2 at the south pole to +π/2 at the north pole, and longitude theta wraps around in the (e1, e2) equatorial plane.

Optional theta_range and phi_range let you carve out a spherical wedge, hemisphere, or any rectangular patch on the sphere. When a cut exposes the sphere’s interior the open flat surfaces are not generated automatically; combine this class with other mesh surfaces if you need to cap them.

mesh()[source]

Return (V, F) mesh arrays.

Returns:

V is (n_vertices, 3) in (x, y, z) order and F is (n_faces, 3) triangle indices.

Return type:

tuple(np.ndarray, np.ndarray)

class emout.plot.surface_cut.UniformCellCenteredGrid(nx, ny, nz, dx, dy, dz, x0=0.0, y0=0.0, z0=0.0)[source]

Bases: object

Uniform, cell-centered grid for data shaped (nz, ny, nx).

Coordinates (cell centers):

x(i) = x0 + (i + 0.5) * dx y(j) = y0 + (j + 0.5) * dy z(k) = z0 + (k + 0.5) * dz

dx: float
dy: float
dz: float
extent_edges()[source]

Return the grid edge extents (not cell centers).

Returns:

(x_min, x_max), (y_min, y_max), (z_min, z_max).

Return type:

tuple(tuple(float, float), tuple(float, float), tuple(float, float))

nx: int
ny: int
nz: int
x0: float = 0.0
x_centers()[source]

Return x-direction cell center coordinates.

Returns:

Array of x center coordinates with length nx.

Return type:

np.ndarray

y0: float = 0.0
y_centers()[source]

Return y-direction cell center coordinates.

Returns:

Array of y center coordinates with length ny.

Return type:

np.ndarray

z0: float = 0.0
z_centers()[source]

Return z-direction cell center coordinates.

Returns:

Array of z center coordinates with length nz.

Return type:

np.ndarray

emout.plot.surface_cut.add_colorbar(fig, ax, *, cmap, norm, label='$\\phi$ (V)', cax=None, fraction=0.03, pad=0.08)[source]

Add a colorbar corresponding to the rendered plot.

Parameters:

  • fig (object) – Target Figure.

  • ax (object) – Target Axes.

  • cmap (object) – Colormap.

  • norm (object) – Color normalization.

  • label (str, optional) – Label string for the colorbar.

  • fraction (float, optional) – Width ratio of the colorbar (Figure.colorbar’s fraction).

  • pad (float, optional) – Spacing between the plot and the colorbar (Figure.colorbar’s pad).

Returns:

The added colorbar object.

Return type:

object

emout.plot.surface_cut.plot_surfaces(ax, *, field=None, surfaces, bounds=None, mode='cmap+cont', cmap_name='jet', vmin=None, vmax=None, alpha=1.0, contour_levels=10, contour_color='k', contour_lw=0.8, contour_on_top=True, contour_offset=0.0, contour_side='auto', clabel=False, clabel_fmt='{:g}', clabel_kwargs=None, clip_to_bounds=True)[source]

Render explicit triangle mesh surfaces with optional colormap + contours.

When clip_to_bounds is True (the default) every mesh is filtered against the resolved bounds (either the user-supplied box or the field/mesh-derived one) by dropping triangles whose centroid lies outside. Pass clip_to_bounds=False to disable the clip and render every mesh in full — useful when you intentionally want surfaces extending beyond the plot extent.

Side effect: this function sets ax.computed_zorder = False so it can pin the merged polygon collection behind the contour line collections via explicit set_zorder. mplot3d’s automatic inter-collection depth sort relies on a single per-collection z value that goes through the camera projection, which is camera-dependent and causes contours to vanish behind the polygon they were extracted from at certain viewpoints. Disabling computed_zorder makes the contour layering camera-independent. Per-triangle depth sort within the merged polygon collection still runs (it lives in Poly3DCollection.do_3d_projection) so interleaving meshes still render in the right order.

contour_offset defaults to 0.0 because shifting contour segments along the source triangle’s face normal breaks line continuity on curved surfaces: adjacent triangles share an edge but have different face normals, so the shared edge crossing gets pushed in two different directions and the contour fractures into per-triangle dashes. The polygon-vs-contour layering is already handled by the explicit set_zorder mechanism above, so an offset is not needed for visibility. Pass a small positive contour_offset only when working with strictly flat surfaces where every triangle shares the same normal.

Contour labels: when clabel=True one text label per level is placed at a representative midpoint along that level’s segments (closest segment midpoint to the level’s overall centroid). Format the value with clabel_fmt — either a Python format string like "{:.1f}" (default "{:g}") or a callable level -> str. Style the text via clabel_kwargs (forwarded to matplotlib.axes.Axes.text()); useful keys include fontsize, color, ha/va, bbox. Defaults are color=contour_color, fontsize=8, centered alignment.

contour_side controls back-face culling for contour extraction:

  • "auto" (default) — detect whether the mesh is closed (every edge shared by two triangles) or open (any boundary edges). Closed meshes get the front-facing cull so back-side contours don’t bleed through. Open meshes (e.g. a half cylinder built with theta_range, a flat RectangleMeshSurface, or a CompositeMeshSurface of mostly-open boundaries) keep every triangle because they have no back side to hide.

  • "front" / "back" — explicit normal-based cull.

  • "both" — keep every triangle, no culling.

Module contents

Plotting utilities for EMSES grid and vector data.

Re-exports 2-D colour-map, contour, quiver, and streamline helpers from basic_plot, boundary cross-section helpers from extra_plot, and the plot_cross_sections() convenience function.