kwant.plotter.plot

kwant.plotter.plot(sys, num_lead_cells=2, unit=None, site_symbol=None, site_size=None, site_color=None, site_edgecolor=None, site_lw=None, hop_color=None, hop_lw=None, lead_site_symbol=None, lead_site_size=None, lead_color=None, lead_site_edgecolor=None, lead_site_lw=None, lead_hop_lw=None, pos_transform=None, cmap='gray', colorbar=True, file=None, show=True, dpi=None, fig_size=None, ax=None)

Plot a system in 2 or 3 dimensions.

An alias exists for this common name: kwant.plot.

Parameters:

• sys (kwant.builder.Builder or kwant.system.FiniteSystem) – A system to be plotted.

• num_lead_cells (int) – Number of lead copies to be shown with the system.

• unit ('nn', 'pt', or float) –

  The unit used to specify symbol sizes and linewidths. Possible choices are:

  • ’nn’: unit is the shortest hopping or a typical nearst neighbor distance in the system if there are no hoppings. This means that symbol sizes/linewidths will scale as the zoom level of the figure is changed. Very short distances are discarded before searching for the shortest. This choice means that the symbols will scale if the figure is zoomed.

  • ’pt’: unit is points (point = 1/72 inch) in figure space. This means that symbols and linewidths will always be drawn with the same size independent of zoom level of the plot.

  • float: sizes are given in units of this value in real (system) space, and will accordingly scale as the plot is zoomed.

  The default value is ‘nn’, which allows to ensure that the images neighboring sites do not overlap.

• site_symbol (symbol specification, function, array, or None) –

  Symbol used for representing a site in the plot. Can be specified as

  • ’o’: circle with radius of 1 unit.

  • ’s’: square with inner circle radius of 1 unit.

  • ('p', nvert, angle): regular polygon with nvert vertices, rotated by angle. angle is given in degrees, and angle=0 corresponds to one edge of the polygon pointing upward. The radius of the inner circle is 1 unit. [Unsupported by plotly engine]

  • ’no symbol’: no symbol is plotted. [Unsupported by plotly engine]

  • ’S’, (‘P’, nvert, angle): as the lower-case variants described above, but with an area equal to a circle of radius 1. (Makes the visual size of the symbol equal to the size of a circle with radius 1). [Unsupported by plotly engine]

  • matplotlib.path.Path instance. [Unsupported by plotly engine]

  Instead of a single symbol, different symbols can be specified for different sites by passing a function that returns a valid symbol specification for each site, or by passing an array of symbols specifications (only for kwant.system.FiniteSystem).

• site_size (number, function, array, or None) – Relative (linear) size of the site symbol. An array may not be used when ‘syst’ is a kwant.Builder.

• site_color (matplotlib color description, function, array, or None) – A color used for plotting a site in the system. If a colormap is used, it should be a function returning single floats or a one-dimensional array of floats. By default sites are colored by their site family, using the current matplotlib color cycle. An array of colors may not be used when ‘syst’ is a kwant.Builder.

• site_edgecolor (matplotlib color description, function, array, or None) – Color used for plotting the edges of the site symbols. Only valid matplotlib color descriptions are allowed (and no combination of floats and colormap as for site_color). An array of colors may not be used when ‘syst’ is a kwant.Builder.

• site_lw (number, function, array, or None) – Linewidth of the site symbol edges. An array may not be used when ‘syst’ is a kwant.Builder.

• hop_color (matplotlib color description or a function) – Same as site_color, but for hoppings. A function is passed two sites in this case. (arrays are not allowed in this case).

• hop_lw (number, function, or None) – Linewidth of the hoppings.

• lead_site_symbol (symbol specification or None) – Symbol to be used for the leads. See site_symbol for allowed specifications. Note that for leads, only constants (i.e. no functions or arrays) are allowed. If None, then site_symbol is used if it is constant (i.e. no function or array), the default otherwise. The same holds for the other lead properties below.

• lead_site_size (number or None) – Relative (linear) size of the lead symbol

• lead_color (matplotlib color description or None) – For the leads, num_lead_cells copies of the lead unit cell are plotted. They are plotted in color fading from lead_color to white (alpha values in lead_color are supported) when moving from the system into the lead. Is also applied to the hoppings.

• lead_site_edgecolor (matplotlib color description or None) – Color of the symbol edges (no fading done).

• lead_site_lw (number or None) – Linewidth of the lead symbols.

• lead_hop_lw (number or None) – Linewidth of the lead hoppings.

• cmap (matplotlib color map or a sequence of two color maps or None) – The color map used for sites and optionally hoppings.

• pos_transform (function or None) – Transformation to be applied to the site position.

• colorbar (bool) – Whether to show a colorbar if colormap is used. Ignored if ax is provided.

• file (string or file object or None) – The output file. If None, output will be shown instead.

• show (bool) – Whether matplotlib.pyplot.show() is to be called, and the output is to be shown immediately. Defaults to True.

• dpi (float or None) – Number of pixels per inch. If not set the matplotlib default is used.

• fig_size (tuple or None) – Figure size (width, height) in inches. If not set, the default matplotlib value is used.

• ax (matplotlib.axes.Axes instance or None) – If ax is not None, no new figure is created, but the plot is done within the existing Axes ax. in this case, file, show, dpi and fig_size are ignored.

Returns:

fig – A figure with the output if ax is not set, else None.

Return type:

matplotlib figure

Notes

• If None is passed for a plot property, a default value depending on the dimension is chosen. Typically, the default values result in acceptable plots.

• The meaning of “site” depends on whether the system to be plotted is a builder or a low level system. For builders, a site is a kwant.builder.Site object. For low level systems, a site is an integer – the site number.

• color and symbol definitions may be tuples, but not lists or arrays. Arrays of values (linewidths, colors, sizes) may not be tuples.

• The dimensionality of the plot (2D vs 3D) is inferred from the coordinate array. If there are more than three coordinates, only the first three are used. If there is just one coordinate, the second one is padded with zeros.

• The system is scaled to fit the smaller dimension of the figure, given its aspect ratio.