bluemira.display.plotter

api for plotting using matplotlib

Attributes

`UNIT_LABEL`
`X_LABEL`
`Y_LABEL`
`Z_LABEL`

Classes

`Zorder`	Layer ordering of common plots
`ViewDescriptor`	Descriptor for placements in dataclass
`DictOptionsDescriptor`	Keep defaults for options unless explicitly overwritten
`DefaultPlotOptions`	The options that are available for plotting objects in 2D.
`PlotOptions`	The options that are available for plotting objects
`BasePlotter`	Base utility plotting class
`PointsPlotter`	Base utility plotting class for points
`WirePlotter`	Base utility plotting class for bluemira wires
`FacePlotter`	Base utility plotting class for bluemira faces
`ComponentPlotter`	Base utility plotting class for bluemira faces
`Plottable`	Mixin class to make a class plottable in 2D by imparting a plot2d method and

Functions

`get_default_options`(→ PlotOptions)
`_validate_plot_inputs`(...)	Validate the lists of parts and options, applying some default options.
`_get_plotter_class`(part)
`plot_2d`(→ matplotlib.axes.Axes)	The implementation of the display API for BluemiraGeo parts.
`plot_3d`(→ matplotlib.axes.Axes)	The implementation of the display API for BluemiraGeo parts.
`_get_ndim`(→ int)
`_get_plan_dims`(→ list[str])
`plot_coordinates`(coords[, ax, points])	Plot Coordinates.
`_plot_3d`(coords[, ax])
`_plot_2d`(coords[, ax])
`plot_2d_mesh_plt`(, title[, ax])	Plots a 2D triangular mesh with optional face group coloring.
`plot_dolfinx_2d_mesh_plt`(, title[, ax])	Plot a 2D triangular mesh from a DOLFINx mesh using matplotlib by leveraging

Module Contents

bluemira.display.plotter.UNIT_LABEL = '[m]'

bluemira.display.plotter.X_LABEL = 'x [m]'

bluemira.display.plotter.Y_LABEL = 'y [m]'

bluemira.display.plotter.Z_LABEL = 'z [m]'

class bluemira.display.plotter.Zorder(*args, **kwds)

Bases: enum.Enum

Layer ordering of common plots

GRID = 0.5

POSITION_1D = 1

POSITION_2D = 2

PLASMACURRENT = 7

PSI = 8

FLUXSURFACE = 9

SEPARATRIX = 10

OXPOINT = 11

FACE = 20

WIRE = 30

POINTS = 35

RADIATION = 40

CONSTRAINT = 45

TEXT = 100

class bluemira.display.plotter.ViewDescriptor

Descriptor for placements in dataclass

_default

__set_name__(_, name: str)

Set the attribute name from a dataclass

Parameters:: name (str)

__get__(obj: Any, _) → tuple[numpy.ndarray, numpy.ndarray, float, str]

Get the view tuple

Returns:: the view attributes from the instance or defaults.
Parameters:: obj (Any)
Return type:: tuple[numpy.ndarray, numpy.ndarray, float, str]

__set__(obj: Any, value: str | tuple | bluemira.geometry.placement.BluemiraPlacement)

Set the view

Raises:

DisplayError – View not known

Parameters:

obj (Any)
value (str | tuple | bluemira.geometry.placement.BluemiraPlacement)

class bluemira.display.plotter.DictOptionsDescriptor(default_factory: collections.abc.Callable[[], dict[str, Any]] | None = None)

Keep defaults for options unless explicitly overwritten

Notes

The default will be reinforced if value set to new dictionary. Otherwise as a dictionary is mutable will act in the normal way.

po = PlotOptions()
po.wire_options["linewidth"] = 0.1  # overrides default
po.wire_options["zorder"] = 2  # adds new zorder option
# setting a new dictionary resets the defaults with zorder overridden
po.wire_options = {'zorder': 1}
del po.wire_options["linewidth"]  # linewidth unset

No checks are done on the contents of the dictionary.

Parameters:: default_factory (collections.abc.Callable[[], dict[str, Any]] | None)

default

__set_name__(_, name: str)

Set the attribute name from a dataclass

Parameters:: name (str)

__get__(obj: Any, _) → collections.abc.Callable[[], dict[str, Any]] | dict[str, Any]

Returns:: the options dictionary
Parameters:: obj (Any)
Return type:: collections.abc.Callable[[], dict[str, Any]] | dict[str, Any]

__set__(obj: Any, value: collections.abc.Callable[[], dict[str, Any]] | dict[str, Any])

Set the options dictionary

Parameters:

obj (Any)
value (collections.abc.Callable[[], dict[str, Any]] | dict[str, Any])

class bluemira.display.plotter.DefaultPlotOptions

The options that are available for plotting objects in 2D.

Parameters:

show_points – If True, points are plotted. By default False.
show_wires – If True, wires are plotted. By default True.
show_faces – If True, faces are plotted. By default True.
point_options – Dictionary with matplotlib options for points. By default {“s”: 10, “facecolors”: “blue”, “edgecolors”: “black”}
wire_options – Dictionary with matplotlib options for wires. By default {“color”: “black”, “linewidth”: “0.5”}
face_options – Dictionary with matplotlib options for faces. By default {“color”: “red”}
view – The reference view for plotting. As string, possible options are “xy”, “xz”, “yz”. By default ‘xz’.
ndiscr – The number of points to use when discretising a wire or face.
byedges – If True then wires or faces will be discretised respecting their edges.

show_points: bool = False

show_wires: bool = True

show_faces: bool = True

number_points: bool = False

point_options: DictOptionsDescriptor

wire_options: DictOptionsDescriptor

face_options: DictOptionsDescriptor

ndiscr: int = 100

byedges: bool = True

view: ViewDescriptor

_external_options: bool = True

property view_placement: bluemira.geometry.placement.BluemiraPlacement

returns: the view as BluemiraPlacement

Return type:: bluemira.geometry.placement.BluemiraPlacement

class bluemira.display.plotter.PlotOptions(**kwargs)

Bases: bluemira.display.tools.Options

The options that are available for plotting objects

__slots__ = ()

_options

bluemira.display.plotter.get_default_options() → PlotOptions

Returns:: the default plot options.
Return type:: PlotOptions

class bluemira.display.plotter.BasePlotter(options: PlotOptions | None = None, *, data: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None = None, **kwargs)

Bases: abc.ABC

Base utility plotting class

Parameters:

options (PlotOptions | None)
data (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None)

_CLASS_PLOT_OPTIONS: ClassVar

options

set_view(view: str | bluemira.geometry.placement.BluemiraPlacement)

Set the plotting view

Parameters:: view (str | bluemira.geometry.placement.BluemiraPlacement)

property ax: matplotlib.axes.Axes

returns: the axes object

Return type:: matplotlib.axes.Axes

abstract _check_obj(obj): Internal function that check if obj is an instance of the correct class

abstract _check_options(): Internal function that check if it is needed to plot something

initialise_plot_2d(ax=None): Initialise the plot environment

static show(): Function to show a plot

abstract _populate_data(obj: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component)

Internal function that makes the plot. It fills self._data and self._projected_data

Parameters:: obj (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component)

abstract _make_plot_2d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

_set_aspect_2d()

_set_label_2d()

_set_aspect_3d()

_set_label_3d()

plot_2d(obj: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component, ax: matplotlib.axes.Axes | None = None, *, show: bool = True) → matplotlib.axes.Axes

2D plotting method

Returns:

The axes with the plotted data.

Parameters:

obj (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component)
ax (matplotlib.axes.Axes | None)
show (bool)

Return type:

matplotlib.axes.Axes

initialise_plot_3d(ax=None): Initialise the plot environment

abstract _make_plot_3d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

plot_3d(obj: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component, ax: matplotlib.axes.Axes | None = None, *, show: bool = True) → matplotlib.axes.Axes

3D plotting method

Returns:

The axes with the plotted data.

Parameters:

obj (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component)
ax (matplotlib.axes.Axes | None)
show (bool)

Return type:

matplotlib.axes.Axes

class bluemira.display.plotter.PointsPlotter(options: PlotOptions | None = None, *, data: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None = None, **kwargs)

Bases: BasePlotter

Base utility plotting class for points

Parameters:

options (PlotOptions | None)
data (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None)

_CLASS_PLOT_OPTIONS: ClassVar

static _check_obj(obj)

Returns:: Always returns True.

Notes

This method currently always returns True.

_check_options()

Check if nothing has to be plotted

Returns:: True if the show_points option is set to True, otherwise False.

_populate_data(obj: numpy.typing.ArrayLike)

Internal function that makes the plot. It fills self._data and self._projected_data

Parameters:: obj (numpy.typing.ArrayLike)

_make_plot_2d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

_make_plot_3d(*args, **kwargs): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

class bluemira.display.plotter.WirePlotter(options: PlotOptions | None = None, *, data: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None = None, **kwargs)

Bases: BasePlotter

Base utility plotting class for bluemira wires

Parameters:

options (PlotOptions | None)
data (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None)

_CLASS_PLOT_OPTIONS: ClassVar

static _check_obj(obj)

Returns:: Always returns True if the object is a BluemiraWire.
Raises:: TypeError – If the object is not an instance of BluemiraWire.

_check_options()

Check if nothing has to be plotted

Returns:: True if nothing has to be plotted, otherwise False.

_populate_data(obj: bluemira.geometry.wire.BluemiraWire)

Internal function that makes the plot. It fills self._data and self._projected_data

Parameters:: obj (bluemira.geometry.wire.BluemiraWire)

_make_plot_2d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

_make_plot_3d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

class bluemira.display.plotter.FacePlotter(options: PlotOptions | None = None, *, data: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None = None, **kwargs)

Bases: BasePlotter

Base utility plotting class for bluemira faces

Parameters:

options (PlotOptions | None)
data (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None)

_CLASS_PLOT_OPTIONS: ClassVar

static _check_obj(obj: bluemira.geometry.face.BluemiraFace)

Returns:: Always returns True if the object is a BluemiraFace.
Raises:: TypeError – If the object is not an instance of BluemiraFace.
Parameters:: obj (bluemira.geometry.face.BluemiraFace)

_check_options()

Check if nothing has to be plotted

Returns:: True if nothing has to be plotted, otherwise False.

_populate_data(obj: bluemira.geometry.face.BluemiraFace)

Internal function that makes the plot. It fills self._data and self._projected_data

Parameters:: obj (bluemira.geometry.face.BluemiraFace)

_make_plot_2d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

_make_plot_3d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

class bluemira.display.plotter.ComponentPlotter(options: PlotOptions | None = None, *, data: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None = None, **kwargs)

Bases: BasePlotter

Base utility plotting class for bluemira faces

Parameters:

options (PlotOptions | None)
data (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component | None)

_CLASS_PLOT_OPTIONS: ClassVar

static _check_obj(obj: bluemira.base.components.Component)

Returns:: Always returns True if the object is a BluemiraComponent.
Raises:: TypeError – If the object is not an instance of BluemiraComponent.
Parameters:: obj (bluemira.base.components.Component)

_check_options()

Check if nothing has to be plotted

Returns:: True if nothing has to be plotted, otherwise False.

_create_plotters(comp: bluemira.base.components.Component) → collections.abc.Iterator[BasePlotter]

Parameters:: comp (bluemira.base.components.Component)
Return type:: collections.abc.Iterator[BasePlotter]

_populate_data(comp: bluemira.base.components.Component)

Internal function that makes the plot. It fills self._data and self._projected_data

Parameters:: comp (bluemira.base.components.Component)

_make_plot_2d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

_make_plot_3d(): Internal function that makes the plot. It should use self._data and self._projected_data, so _populate_data should be called before.

_set_aspect_3d()

bluemira.display.plotter._validate_plot_inputs(parts: bluemira.geometry.base.BluemiraGeoT | list[bluemira.geometry.base.BluemiraGeoT], options: PlotOptions | list[None] | list[PlotOptions] | None) → tuple[list[bluemira.geometry.base.BluemiraGeoT], list[PlotOptions] | list[None]]

Validate the lists of parts and options, applying some default options.

Returns:

validated lists of parts and options

Raises:

DisplayError – Number of options not equal to number of parts

Parameters:

parts (bluemira.geometry.base.BluemiraGeoT | list[bluemira.geometry.base.BluemiraGeoT])
options (PlotOptions | list[None] | list[PlotOptions] | None)

Return type:

tuple[list[bluemira.geometry.base.BluemiraGeoT], list[PlotOptions] | list[None]]

bluemira.display.plotter._get_plotter_class(part: numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component)

Returns:: the plotting class for a BluemiraGeo object.
Raises:: DisplayError – No plotter available for type of part
Parameters:: part (numpy.typing.ArrayLike | bluemira.geometry.coordinates.Coordinates | bluemira.geometry.base.BluemiraGeoT | bluemira.base.components.Component)

bluemira.display.plotter.plot_2d(parts: bluemira.geometry.base.BluemiraGeoT | collections.abc.Iterable[bluemira.geometry.base.BluemiraGeoT], options: PlotOptions | collections.abc.Iterable[PlotOptions] | collections.abc.Iterable[None] | None = None, ax: matplotlib.axes.Axes | None = None, *, show: bool = True, **kwargs) → matplotlib.axes.Axes

The implementation of the display API for BluemiraGeo parts.

Parameters:

parts (bluemira.geometry.base.BluemiraGeoT | collections.abc.Iterable[bluemira.geometry.base.BluemiraGeoT]) – The parts to display.
options (PlotOptions | collections.abc.Iterable[PlotOptions] | collections.abc.Iterable[None] | None) – The options to use to display the parts.
ax (matplotlib.axes.Axes | None) – The axes onto which to plot
show (bool) – Whether or not to show the plot immediately (default=True). Note that if using iPython or Jupyter, this has no effect; the plot is shown automatically.

Returns:

The axes with the plotted data.

Return type:

matplotlib.axes.Axes

bluemira.display.plotter.plot_3d(parts: bluemira.geometry.base.BluemiraGeoT | collections.abc.Iterable[bluemira.geometry.base.BluemiraGeoT], options: PlotOptions | collections.abc.Iterable[PlotOptions] | collections.abc.Iterable[None] | None = None, ax: matplotlib.axes.Axes | None = None, *, show: bool = True, **kwargs) → matplotlib.axes.Axes

The implementation of the display API for BluemiraGeo parts.

Parameters:

parts (Union[Part.Shape, List[Part.Shape]]) – The parts to display.
options (Optional[Union[Plot3DOptions, List[Plot3Options]]]) – The options to use to display the parts.
ax (Optional[Axes]) – The axes onto which to plot
show (bool) – Whether or not to show the plot immediately in the console. (default=True). Note that if using iPython or Jupyter, this has no effect; the plot is shown automatically.

Returns:

The axes with the plotted data.

Return type:

matplotlib.axes.Axes

class bluemira.display.plotter.Plottable

Mixin class to make a class plottable in 2D by imparting a plot2d method and options.

Notes

The implementing class must set the _plotter2D attribute to an instance of the appropriate Plotter2D class.

_plot_options: PlotOptions

property plot_options: PlotOptions

The options that will be used to display the object.

Return type:: PlotOptions

property _plotter: BasePlotter

The options that will be used to display the object.

Return type:: BasePlotter

plot_2d(ax: matplotlib.axes.Axes | None = None, *, show: bool = True) → matplotlib.axes.Axes

Default method to call display the object by calling into the Displayer’s display method.

Returns:

The axes with the plotted data.

Parameters:

ax (matplotlib.axes.Axes | None)
show (bool)

Return type:

matplotlib.axes.Axes

plot_3d(ax: matplotlib.axes.Axes | None = None, *, show: bool = True) → matplotlib.axes.Axes

Function to 3D plot a component.

Returns:

The axes with the plotted data.

Parameters:

ax (matplotlib.axes.Axes | None)
show (bool)

Return type:

matplotlib.axes.Axes

bluemira.display.plotter._get_ndim(coords: bluemira.geometry.coordinates.Coordinates) → int

Returns:: The number of dimensions in the coordinate data. Returns at least 2.
Parameters:: coords (bluemira.geometry.coordinates.Coordinates)
Return type:: int

bluemira.display.plotter._get_plan_dims(array: numpy.typing.ArrayLike) → list[str]

Returns:: A sorted list of axis labels (“x”, “y”, “z”) indicating which dimensions have variability.
Parameters:: array (numpy.typing.ArrayLike)
Return type:: list[str]

bluemira.display.plotter.plot_coordinates(coords: bluemira.geometry.coordinates.Coordinates, ax: matplotlib.axes.Axes | None = None, *, points: bool = False, **kwargs)

Plot Coordinates.

Parameters:

coords (Coordinates) – Coordinates to plot
ax (Axes) – Matplotlib axis on which to plot
edgecolor (str) – The edgecolor to plot the Coordinates with
facecolor (str) – The facecolor to plot the Coordinates fill with
alpha (float) – The transparency to plot the Coordinates fill with
points (bool)

bluemira.display.plotter._plot_3d(coords: bluemira.geometry.coordinates.Coordinates, ax: matplotlib.axes.Axes | None = None, **kwargs)

Parameters:

coords (bluemira.geometry.coordinates.Coordinates)
ax (matplotlib.axes.Axes | None)

bluemira.display.plotter._plot_2d(coords: bluemira.geometry.coordinates.Coordinates, ax: matplotlib.axes.Axes | None = None, *, points: bool, **kwargs)

Parameters:

coords (bluemira.geometry.coordinates.Coordinates)
ax (matplotlib.axes.Axes | None)
points (bool)

bluemira.display.plotter.plot_2d_mesh_plt(nodes: numpy.ndarray, faces: numpy.ndarray, face_groups: numpy.ndarray | None = None, group_colors: dict[int, str] | None = None, cmap: str = 'tab20', figsize: tuple = (6, 6), title: str = '2D Triangular Mesh', ax=None, *, show: bool = False) → matplotlib.pyplot.Axes

Plots a 2D triangular mesh with optional face group coloring.

If no face_groups and no group_colors are provided, only the triangle edges will be plotted without face coloring.

Parameters:

nodes (np.ndarray) – Array of node coordinates, shape (N, 2)
faces (np.ndarray) – Array of triangle indices, shape (M, 3)
face_groups (np.ndarray, optional) – Face group IDs for coloring, shape (M,)
group_colors (dict[int, str], optional) – Custom mapping from group ID to color
cmap (str) – Colormap used for automatic color assignment
figsize (tuple) – Figure size (only used if ax is None)
title (str) – Title of the plot
ax (matplotlib.axes.Axes, optional) – An existing Axes to plot on
show (bool) – Whether to display the plot with plt.show()

Returns:

The axes object the mesh is plotted on.

Return type:

matplotlib.axes.Axes

bluemira.display.plotter.plot_dolfinx_2d_mesh_plt(mesh: dolfinx.mesh.Mesh, face_groups: numpy.ndarray | None = None, group_colors: dict[int, str] | None = None, cmap: str = 'tab20', figsize: tuple = (6, 6), title: str = '2D Triangular Mesh (DOLFINx)', ax=None, *, show: bool = False) → matplotlib.pyplot.Axes

Plot a 2D triangular mesh from a DOLFINx mesh using matplotlib by leveraging plot_2d_mesh_plt.

Parameters:

mesh (dolfinx.mesh.Mesh) – A 2D DOLFINx triangular mesh.
face_groups (np.ndarray, optional) – Group IDs for each face (element), same length as number of cells.
group_colors (dict[int, str], optional) – Mapping from group ID to color.
cmap (str) – Colormap for automatic coloring of groups.
figsize (tuple) – Size of the figure if ax is None.
title (str) – Title of the plot.
ax (matplotlib.axes.Axes, optional) – Axes object to draw on.
show (bool) – Whether to show the plot immediately.

Returns:

The axes object used for plotting.

Return type:

matplotlib.axes.Axes

Raises:

ValueError – If the mesh is not a triangular mesh.