magnelio.plots#

Plotting components — the free functions behind the .plot() methods.

The primary plotting path is the methods on the objects themselves (model.plot(), model.plot_cross_section(), report.plot(), monitor.plot(), result.plot_s()); this module is their public home for direct use on objects you assembled yourself.

magnelio.plots.plot_cross_section(geometry, normal, position, *, mesh=None, scale_mm=True, flip=False, ax=None, title=None, deflection=0.0001, outline_transparent=True, show_wires=True, show_ports=True, slab=0.0)#

Plot a 2D cross-section of 3D geometry at an axis-aligned plane.

Intersects every shape in geometry with the specified plane and renders the resulting polygons as matplotlib patches, coloured by material. Shapes with a fully transparent material (air/vacuum) are drawn as a dashed outline instead of being skipped — for a cavity carved into a conducting background, that outline is the wall.

Features that carry no volume are drawn too, since a picture of a wire antenna showing only its air box is not a picture of the model: thin wires from their curve, discrete ports and lumped elements from their two endpoints, and face ports along the domain edge they occupy. Each appears as a line where the cut runs along it and as a ring where the cut passes through it.

Parameters:

  • geometry (GeometryModel) – Geometry model containing the shapes to slice.

  • normal (str) – Normal axis of the cutting plane: 'x', 'y', or 'z'.

  • position (float) – Position along the normal axis in metres.

  • mesh (Mesh or None, optional) – If given, overlay the mesh grid lines for the cutting plane.

  • scale_mm (bool, optional) – If True (default), display axes in millimetres.

  • flip (bool, optional) – If True, swap the horizontal and vertical axes. Useful for structures that are tall and narrow in the default (u, v) layout (e.g. a long transmission line sliced at x = const).

  • ax (matplotlib.axes.Axes or None, optional) – Existing axes to draw into. A new figure is created when None.

  • title (str or None, optional) – Plot title. Defaults to "Cross-section at <axis> = <pos> <unit>".

  • deflection (float, optional) – Chordal deflection for curve tessellation [m]. Passed through to cross_section_polygons().

  • outline_transparent (bool, optional) – Draw transparent-material shapes as dashed outlines (default True). Set False to skip them entirely (pre-existing behaviour). Shapes whose material has visible=False are always skipped.

  • show_wires (bool, optional) – Draw ThinWire conductors (default True). A wire is a sub-cell model, so it is drawn at a fixed line width rather than to its radius — which would be invisible. The cut counts as passing through a wire when it comes within one radius of it.

  • show_ports (bool, optional) – Draw the model’s declared ports and lumped elements (default True), labelled. A port declared on a bbox face parallel to the cut is not drawn: it would cover the entire section.

  • slab (float, optional) – Half-thickness of the layer the picture stands for [m], zero by default (a mathematical plane). Volume-free features — thin wires, discrete ports, lumped elements — are drawn when they fall within this distance of the plane. Field plots pass the half-height of the cell layer they display, so a wire on a grid node still appears in a picture whose field samples sit half a cell off it.

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (matplotlib.axes.Axes)

Return type:

tuple[‘matplotlib.figure.Figure’, ‘matplotlib.axes.Axes’]

magnelio.plots.plot_field_scalar(xc, yc, values, *, xlabel='u', ylabel='v', title='', clabel='', ax=None, scale_mm=True, cmap='viridis', vmin=None, vmax=None, symmetric=False, plot_type='color', contour_levels=16, flip=False, geometry=None)#

Scalar 2D field plot (pcolormesh or contourf).

Parameters:

  • xc (np.ndarray) – Cell-centre coordinates of the two in-plane axes.

  • yc (np.ndarray) – Cell-centre coordinates of the two in-plane axes.

  • values (np.ndarray) – Real-valued 2D array, shape (len(xc), len(yc)).

  • xlabel (str) – Axis labels (without unit suffix).

  • ylabel (str) – Axis labels (without unit suffix).

  • title (str) – Axes title.

  • clabel (str) – Colour-bar label.

  • scale_mm (bool) – If True, multiply coordinates by 1e3 and label in mm.

  • cmap (str) – Matplotlib colourmap.

  • vmin (float or None) – Explicit colour limits.

  • vmax (float or None) – Explicit colour limits.

  • symmetric (bool) – If True and vmin/vmax not set, use symmetric limits [-M, M].

  • plot_type (str) – "color" (pcolormesh) or "contour" (filled contours).

  • contour_levels (int) – Number of contour levels (contour mode only).

  • flip (bool) – Swap horizontal and vertical axes.

  • geometry (GeometryOverlay) – Optional geometry overlay.

  • ax (matplotlib.axes.Axes | None)

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (matplotlib.axes.Axes)

Return type:

tuple[‘matplotlib.figure.Figure’, ‘matplotlib.axes.Axes’]

magnelio.plots.plot_field_vector(xc, yc, u, v, *, w=None, valid=None, xlabel='u', ylabel='v', wlabel='n', title='', clabel=None, ax=None, scale_mm=True, cmap='viridis', density=20, normalize_arrows=False, vmax=None, threshold=0.0, auto_scale=True, quiver_scale=None, flip=False, geometry=None)#

Quiver plot for a 2D slice of a vector field.

The data is interpolated onto an isotropic arrow raster spanning the slice (see density): arrow positions are a property of the picture, not of the computational grid, so a locally refined mesh no longer shows up as clustered arrows.

Arrows show the in-plane vector components. When the out-of-plane component w is given, arrow colour encodes the full 3D magnitude, and grid points whose vector tilts out of the plane by more than ~72° (|w| >= 3x the in-plane part, at significant magnitude) are drawn as circle markers instead of unreadable foreshortened arrows: a filled circle with a centre dot (⊙) where the field points along the positive normal axis, with a cross (⊗) along the negative one. Without w the plot shows the in-plane projection only and the colour bar is labelled accordingly.

Parameters:

  • xc (np.ndarray) – Cell-centre coordinates of the two in-plane axes.

  • yc (np.ndarray) – Cell-centre coordinates of the two in-plane axes.

  • u (np.ndarray) – In-plane vector components, shape (len(xc), len(yc)).

  • v (np.ndarray) – In-plane vector components, shape (len(xc), len(yc)).

  • w (np.ndarray or None) – Out-of-plane (normal) component on the same grid. Enables the full-magnitude colouring and the ⊙/⊗ markers.

  • valid (np.ndarray or None) – Boolean mask of cells carrying field data, same shape as u. False marks a cell the field does not live in (buried in a conductor); it is excluded from the interpolation stencil rather than read as zero, and raster points dominated by such cells stay blank. None treats every cell as valid.

  • xlabel (str) – In-plane axis labels (without unit suffix).

  • ylabel (str) – In-plane axis labels (without unit suffix).

  • wlabel (str) – Name of the normal axis (e.g. "y"), used in the ⊙/⊗ marker legend.

  • clabel (str or None) – Colour-bar label. Default: "Field magnitude" when w is given, "In-plane field magnitude" otherwise.

  • density (int) – Number of arrows along the longer in-plane axis. The field is interpolated onto an isotropic raster of that spacing, so the arrow pattern shows the field rather than the local refinement of the computational grid.

  • normalize_arrows (bool) – If True, arrows have unit length and colour encodes magnitude (port-mode style). If False, arrow length is proportional to field strength (monitor style).

  • vmax (float or None) – Clip arrow length and colour at this magnitude.

  • threshold (float) – Suppress arrows below this fraction of peak magnitude. With w, max(threshold, 0.02) of the peak is also the significance floor below which no ⊙/⊗ marker is drawn.

  • auto_scale (bool) – Compute the quiver scale so the peak magnitude (full 3D with w, in-plane without) maps to ~ one cell spacing; arrow length over colour then reads as the out-of-plane tilt.

  • quiver_scale (float or None) – Explicit quiver scale override (e.g. for interact() fixed-scale animations). Overrides auto_scale.

  • flip (bool) – Swap horizontal and vertical axes.

  • geometry (GeometryOverlay) – Optional geometry overlay.

  • title (str)

  • ax (matplotlib.axes.Axes | None)

  • scale_mm (bool)

  • cmap (str)

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (matplotlib.axes.Axes)

Return type:

tuple[‘matplotlib.figure.Figure’, ‘matplotlib.axes.Axes’]

magnelio.plots.plot_pattern_3d(theta, phi, values, *, db=True, floor_db=-40.0, ax=None, cmap=None, title=None)#

3D radiation surface: radius proportional to the pattern.

In dB mode the radius is value_dB − floor_dB clipped at zero, so the floor collapses to the origin and nulls stay visible as indentations.

Parameters:

  • theta (array_like) – Spherical angle grids [rad]; θ from +z, φ from +x.

  • phi (array_like) – Spherical angle grids [rad]; θ from +z, φ from +x.

  • values (array_like) – Pattern quantity on the (θ, φ) grid (linear), shape (len(theta), len(phi)).

  • db (bool, default True) – Radius from the dB value (with floor_db) instead of linear.

  • floor_db (float, default -40.0) – Radius origin for the dB display.

  • cmap (str, optional) – Colormap for the radius shading (default "viridis").

  • ax (mpl_toolkits.mplot3d.axes3d.Axes3D, optional) – 3D axes to draw into; a new figure is created otherwise.

  • title (str | None)

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (mpl_toolkits.mplot3d.axes3d.Axes3D)

magnelio.plots.plot_pattern_cut(angles, values, *, db=True, floor_db=-40.0, ax=None, label=None, title=None)#

Polar plot of one pattern cut.

Follows the antenna-plot convention: the zero angle points up and angles run clockwise, so a θ-cut shows the zenith at the top.

Parameters:

  • angles (array_like) – Cut angles [rad].

  • values (array_like) – Pattern quantity along the cut (linear, e.g. gain or directivity).

  • db (bool, default True) – Radial axis in dB (with floor_db) instead of linear.

  • floor_db (float, default -40.0) – Clip floor and radial-axis minimum for the dB display.

  • label (str, optional) – Legend label for this trace.

  • ax (matplotlib.projections.polar.PolarAxes, optional) – Polar axes to draw into; a new figure is created otherwise.

  • title (str | None)

Returns:

  • fig (matplotlib.figure.Figure)

  • ax (matplotlib.projections.polar.PolarAxes)

magnelio.plots.show_geometry(geometry, *, size=(800, 500), render_edges=True, edge_color='#202020', quality=1.0)#

Interactive 3D view of a GeometryModel.

Uses the pythonocc JupyterRenderer widget. Each shape is coloured according to its material (same palette as plot_cross_section()). Air/vacuum shapes are rendered semi-transparent so that internal structure is visible.

Calling this function directly displays the widget as a side-effect via IPython.display; the return value is None.

Parameters:

  • geometry (GeometryModel or list of shapes) – The geometry to display.

  • size ((int, int)) – Widget size in pixels (width, height).

  • render_edges (bool) – Draw tessellation edges on every shape.

  • edge_color (str) – Hex colour for edges.

  • quality (float) – Tessellation quality (higher = finer mesh, slower).