Plotting utilities for brille

brille.plotting.plot(*args, **kwds)

A gateway plotting function which infers intention from its input.

There are a number of plotting routines within this module that have names associated with their intended input and functionality. Their signatures are sufficiently distinct that the intended plotting function can be determined by examining the calling signature alone. This function takes any input and calls one of plot_bz(), plot_polyhedron(), plot_points(), plot_points_with_lines(), or plot_tetrahedra(), depending on the input provided.

Parameters:

  • *args – Variable length argument list, used exclusively for determining the implied plotting specialisation.

  • **kwargs – Arbitrary keyword arguments, passed unmodified to the implied specialisation.

Returns:

The return type depends on which specialisation is called.

Return type:

variable

Raises:

Exception – If the specialisation can not be inferred from *args then an exception is raised.

brille.plotting.plot_bz(bz, axs=None, origin=None, Q=None, units='invA', irreducible=True, face_vectors=False, show=True, color='b', edgecolor='k', linewidth=1, alpha=0.2)

Plot a BrillouinZone or related object.

Draw the faces of a first Brillouin zone and/or irreducible Brillouin zone polyhedron, plus additional structures.

Parameters:

  • bz (BrillouinZone, BZMeshQdc, BZMeshQcc, BZMeshQdd, BZNestQdc, BZNestQcc, BZNestQdd, BZTrellisQdc, BZTrellisQcc, BZTrellisQ) – The object containing information about a first Brillouin zone and/or an irreducible Brillouin zone.

  • axs (matplotlib.axes.Axes, optional) – The axes in which to add the plotted points. If None then matplotlib.axes.gca() is used to get or spawn the current axes.

  • origin ({numpy.ndarray,tuple,list}, optional) – The origin of the plotting coordinate system, all drawn information is relative to this vector. Any 3-element object convertible to a numpy.ndarray is valid input. Invalid input is replaced by the zero-vector.

  • Q (numpy.ndarray, optional) – A \(N \times 3\) array of points to draw after the first/irreducible Brillouin zone polyhedron. If bz is not a BrillouinZone and input Q is None, Q will be replaced by the contents of bz.rlu or bz.invA, depending on the value of units; otherwise the units of Q are assumed to be the same as units.

  • units (str, optional) – The units in which to plot the first/irreducible Brillouin zone.

    valid units

    corresponding to

    'invA'

    inverse ångstrom

    'rlu'

    reciprocal lattice units of the conventional cell

    'primitive'

    reciprocal lattice units of the primitive cell

  • irreducible (bool, optional) – Whether to plot the irreducible Brillouin zone polyhedron when it is present. When True, the first Brillouin zone edges are plotted as well.

  • face_vectors (bool, optional) – Whether to plot vectors from the origin through each first Brillouin zone face centre.

  • show (bool, optional) – Whether to call matplotlib.pyplot.show() after adding the points to axs; this is mostly useful in non-interactive environments.

  • color (optional) – The face color of the drawn polyhedra.

  • edgecolor (optional) – The edge color of the drawn polyhedra.

  • linewidth (float, optional) – The edge line width of drawn polyhedra.

  • alpha (float, optional) – The face alpha of drawn polyhedra.

Returns:

The value of axs after plotting.

Return type:

matplotlib:axes:Axes

brille.plotting.plot_points(x, axs=None, title=None, show=True)

Plot points.

Parameters:

  • x (numpy.ndarray) – A \(N \times 3\) two dimensional array of \(N\) points to plot.

  • axs (matplotlib.axes.Axes, optional) – The axes in which to add the plotted points. If None then matplotlib.axes.gca() is used to get or spawn the current axes.

  • title (str, optional) – An optional title for the plotting axes axs

  • show (bool, optional) – Whether to call matplotlib.pyplot.show() after adding the points to axs; this is mostly useful in non-interactive environments.

brille.plotting.plot_points_with_lines(x, y, axs=None, title=None, show=True)

Plot points with lines.

Parameters:

  • x (numpy.ndarray) – A \(N \times 3\) two dimension array of \(N\) points to plot.

  • y (numpy.ndarray) – A \((M+1) \times 3\) two dimensional array of the endpoints of \(M\) connected line segments to plot.

  • axs (matplotlib.axes.Axes, optional) – The axes in which to add the plotted points. If None then matplotlib.axes.gca() is used to get or spawn the current axes.

  • title (str, optional) – An optional title for the plotting axes axs

  • show (bool, optional) – Whether to call matplotlib.pyplot.show() after adding the points to axs; this is mostly useful in non-interactive environments.

Note

The \(M\) line segments defined by y are drawn before the points in x.

brille.plotting.plot_polyhedron(poly, axs=None, setlims=True, show=True, **kwds)

Plot a single polyhedron.

Parameters:

  • poly (brille._brille.Polyhedron) – Any object with both a vertices and vertices_per_face field could work with thie plotting function, however it is anticipated that a brille._brille.Polyhedron will be provided.

  • axs (matplotlib.axes.Axes, optional) – The 3D axes in which to add the polyhedron facets. If None then matplotlib.axes.gca() is used to get or spawn the current axes.

  • setlims (bool, optional) – Whether to change the limits of axs to match the limits of the extent of poly.vertices.

  • show (bool, optional) – Whether to call matplotlib.pyplot.show() after adding the points to axs; this is mostly useful in non-interactive environments.

  • origin ({numpy.ndarray,tuple,list}, optional) – The origin of the plotting coordinate system, all drawn information is relative to this vector. Any 3-element object convertible to a numpy.ndarray is valid input. Invalid input is replaced by the zero-vector.

  • color (optional) – The face color of the drawn polygons.

  • edgecolor (optional) – The edge color of the drawn polygons.

  • linestyle (str, optional) – The edge line style of dranw polygons.

  • linewidth (float, optional) – The edge line width of drawn polygons.

  • alpha (float, optional) – The face alpha of drawn polygons.

Returns:

The value of axs after plotting.

Return type:

matplotlib:axes:Axes

brille.plotting.plot_tetrahedra(allverts, tetidx, axs=None, **kwds)

Plot a number of tetrahedra.

Parameters:

  • allverts (numpy.ndarray) – A \((N \ge 4) \times 3\) array of the vertices of all tetrahedra

  • tetidx (numpy.ndarray) – A \(M \times 4\) array of the indices of allverts which make up each of the \(M\) tetrahedra to be plotted. The values of tetidx should obey the inequalities min(tetidx) ≥ 0 and max(tetidx) < N.

  • axs (matplotlib.axes.Axes, optional) – The 3D axes in which to add the polyhedron facets. If None then matplotlib.axes.gca() is used to get or spawn the current axes.

  • color ({arraylike, str, iterable}, optional) – The specified color will be used to produce a list of \(M\) colors to use in plotting the \(M\) tetrahedra. If color has three elements or is a str it is assumed to represent a single RGB value. In all cases the single or multiple colors provided in color are tiled into a list with at least \(M\) elements before being truncated. If no color is provided, a list of all named colors known to matplotlib.colors is tiled.

brille.plotting.plot_tetrahedron(verts, axs=None, show=True, **kwds)

Plot a single tetrahedron.

Parameters:

  • verts (numpy.ndarray) – A \(4 \times 3\) array of the four vertices of the tetrahedron.

  • axs (matplotlib.axes.Axes, optional) – The 3D axes in which to add the polyhedron facets. If None then matplotlib.axes.gca() is used to get or spawn the current axes.

  • show (bool, optional) – Whether to call matplotlib.pyplot.show() after adding the points to axs; this is mostly useful in non-interactive environments.

  • origin ({numpy.ndarray,tuple,list}, optional) – The origin of the plotting coordinate system, all drawn information is relative to this vector. Any 3-element object convertible to a numpy.ndarray is valid input. Invalid input is replaced by the zero-vector.

  • color (optional) – The face color of the drawn polygons.

  • edgecolor (optional) – The edge color of the drawn polygons.

  • linestyle (str, optional) – The edge line style of dranw polygons.

  • linewidth (float, optional) – The edge line width of drawn polygons.

  • alpha (float, optional) – The face alpha of drawn polygons.

Returns:

The value of axs after plotting.

Return type:

matplotlib:axes:Axes