Plotting¶

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.

• **kwds –

  Arbitrary keyword arguments, passed unmodified to the implied specialisation.

Returns:

• variable –

  The return type depends on which specialisation is called.

Raises:

• Exception –

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

Plot points.

Parameters:

• x ([`numpy.ndarray`][numpy.ndarray]) –

  A \(N \times 3\) two dimensional array of \(N\) points to plot.

• axs ([`matplotlib.axes.Axes`][matplotlib.axes.Axes], default: None ) –

  The axes in which to add the plotted points. If None then matplotlib.pyplot.gca is used to get or spawn the current axes.

• title (str, default: None ) –

  An optional title for the plotting axes axs

• show (bool, default: True ) –

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

Plot points with lines.

Parameters:

• x ([`numpy.ndarray`][numpy.ndarray]) –

  A \(N \times 3\) two dimension array of \(N\) points to plot.

• y ([`numpy.ndarray`][numpy.ndarray]) –

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

• axs ([`matplotlib.axes.Axes`][matplotlib.axes.Axes], default: None ) –

  The axes in which to add the plotted points. If None then matplotlib.pyplot.gca is used to get or spawn the current axes.

• title (str, default: None ) –

  An optional title for the plotting axes axs

• show (bool, default: True ) –

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

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`][matplotlib.axes.Axes], default: None ) –

  The axes in which to add the plotted points. If None then matplotlib.pyplot.gca is used to get or spawn the current axes.

• origin ([`numpy.ndarray`][numpy.ndarray],tuple,list, default: [`numpy.ndarray`][numpy.ndarray],tuple,list ) –

  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`][numpy.ndarray], default: None ) –

  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, default: 'invA' ) –

  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, default: True ) –

  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, default: False ) –

  Whether to plot vectors from the origin through each first Brillouin zone face centre.

• show (bool, default: True ) –

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

• color (optional, default: 'b' ) –

  The face color of the drawn polyhedra.

• edgecolor (optional, default: 'k' ) –

  The edge color of the drawn polyhedra.

• linewidth (float, default: 1 ) –

  The edge line width of drawn polyhedra.

• alpha (float, default: 0.2 ) –

  The face alpha of drawn polyhedra.

Returns:

• `matplotlib:axes:Axes` –

  The value of axs after plotting.

Plot a single polyhedron.

Parameters:

• poly ([`brille._brille.Polyhedron`][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`][matplotlib.axes.Axes], default: None ) –

  The 3D axes in which to add the polyhedron facets. If None then matplotlib.pyplot.gca is used to get or spawn the current axes.

• setlims (bool, default: True ) –

  Whether to change the limits of axs to match the limits of the extent of poly.vertices.

• show (bool, default: True ) –

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

Other Parameters:

• origin ([`numpy.ndarray`][numpy.ndarray],tuple,list) –

  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) –

  The edge line style of dranw polygons.

• linewidth (float) –

  The edge line width of drawn polygons.

• alpha (float) –

  The face alpha of drawn polygons.

Returns:

• `matplotlib:axes:Axes` –

  The value of axs after plotting.

Plot a single tetrahedron.

Parameters:

• verts ([`numpy.ndarray`][numpy.ndarray]) –

  A \(4 \times 3\) array of the four vertices of the tetrahedron.

• axs ([`matplotlib.axes.Axes`][matplotlib.axes.Axes], default: None ) –

  The 3D axes in which to add the polyhedron facets. If None then matplotlib.pyplot.gca is used to get or spawn the current axes.

• show (bool, default: True ) –

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

Other Parameters:

• origin ([`numpy.ndarray`][numpy.ndarray],tuple,list) –

  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) –

  The edge line style of dranw polygons.

• linewidth (float) –

  The edge line width of drawn polygons.

• alpha (float) –

  The face alpha of drawn polygons.

Returns:

• `matplotlib:axes:Axes` –

  The value of axs after plotting.

Plot a number of tetrahedra.

Parameters:

• allverts ([`numpy.ndarray`][numpy.ndarray]) –

  A \((N \ge 4) \times 3\) array of the vertices of all tetrahedra

• tetidx –

  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`][matplotlib.axes.Axes], default: None ) –

  The 3D axes in which to add the polyhedron facets. If None then matplotlib.pyplot.gca is used to get or spawn the current axes.

Other Parameters:

• color ((arraylike, str, iterable)) –

  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.

Visualise a single wrapped polyhedron

Parameters:

• polyhedron (Union[VisPolyhedron, Polyhedron, LPolyhedron]) –

  The polyhedron to be visualised. Any object with similar vertices and faces properties may work as well.

• kwargs –

  Optional keyword arguments for the VisPolyhedron constructor. Only used if a Polyhedron or LPolyhedron is provided as input.

  face_color : Union[str, vispy.color.Color] The face color used for Polyhedron or LPolyhedron object input. edge_color : Union[str, vispy.color.Color] The edge color used for Polyhedron or LPolyhedron object input. fill : bool Control drawing the faces of the Polyhedron or LPolyhedron object. outline : bool Control drawing the edges of the Polyhedron or LPolyhedron object.

Visualise multiple polyhedra

Parameters:

• polyhedra (List[Union[VisPolyhedron, Polyhedron, LPolyhedron]]) –

  The polyhedron to be visualised. Any object with similar vertices and faces properties may work as well.

• kwargs –

  Optional keyword arguments for the VisPolyhedron constructor. Only used if a Polyhedron or LPolyhedron is provided in the polyhedron list.

  face_color : Union[List[Union[str, vispy.color.Color]],Union[str, vispy.color.Color]] A single face color used for all Polyhedron and LPolyhedron objects or a list of colors which will be tiled to the size of the full polyhedra list. edge_color : Union[List[Union[str, vispy.color.Color]],Union[str, vispy.color.Color]] A single edge color used for all Polyhedron and LPolyhedron objects or a list of colors which will be tiled to the size of the full polyhedra list. fill : Union[List[bool], bool] A single value to control drawing the faces of all Polyhedron and LPolyhedron objects or a list of boolean values which will be tiled to the size of the full polyhedra list. outline : Union[List[bool], bool] A single value to control drawing the edges of all Polyhedron and LPolyhedron objects or a list of boolean values which will be tiled to the size of the full polyhedra list. opacity : Union[List[float], float] A single value to control face opacity of all Polyhedron and LPolyhedron objects or a list of floating point values which will be tiled to the size of the full polyhedra list.

Construct as VisPy mesh from a Polyhedron object

Construct a list of VisPy Line objects from the edges of a Polyhedron object

Construct a list of colors for use in displaying Polyhedron objects

Parameters:

• n (int) –

  The number of colors required

• color (Union[List[Union[str, Color]], Union[str, Color]], default: None ) –

  If color is not provided, the list of all colors known to VisPy will be used

Returns:

• List[Color] –

  A length-n list of colors. If the starting value of color is less than length-n, it will be tiled to length-n.

Examples:

>>> make_colours(7, ['red', 'blue', 'green'])
[Color('red'), Color('blue'), Color('green'), Color('red'), Color('blue'), Color('green'), Color('red')]

>>> from vispy.color import Color
>>> make_colors(4, Color('black'))
[Color('black'), Color('black'), Color('black'), Color('black')]

Construct a 1-D list of values for use in displaying Polyhedron objects

Parameters:

• n (int) –

  The number of colors required

• val (Union[List[T], T]) –

Returns:

• List[T] –

  A length-n list of values. If the starting value is less than length-n, it will be tiled to length-n. If the input list is longer than the requested list length, it will be truncated.

Examples:

>>> make_list(10, [True, False, True, True])
[True, False, True, True, True, False, True, True, True, False]

The items in the input list should all be the same type. In the case of numeric types, the numpy type promotion rules will cast them all to a consistent type before tiling or truncating. So an 'unused' input value may influence the type of the returned values.

>>> make_list(2, [2, 101, 3.14159])
[2.0, 101.0]