Visualization¶

The superscreen.visualization module contains functions used to visualize the results contained in a superscreen.Solution.

Fields¶

superscreen.visualization.plot_fields(solution, layers=None, dataset='fields', normalize=False, units=None, shading='gouraud', max_cols=3, cmap='cividis', colorbar=True, auto_range_cutoff=None, share_color_scale=False, symmetric_color_scale=False, vmin=None, vmax=None, cross_section_coords=None, **kwargs)[source]¶

Plots either the total field or the screening field for multiple layers in a Device.

Additional keyword arguments are passed to plt.subplots().

Parameters:

solution (Solution) – The Solution from which to extract fields.
layers (Union[str, List[str], None]) – Name(s) of layer(s) for which to plot the fields. By default, the stream function is plotted for all layers in the Device.
dataset (str) – Which set of fields to plot, either “fields” or “screening_fields”.
normalize (bool) – Whether to normalize the fields by the applied field.
units (Optional[str]) – Units in which to plot the fields. Defaults to solution.field_units. This argument is ignored if normalize is True.
shading (str) – May be "flat" or "gouraud". The latter does some interpolation.
max_cols (int) – Maximum number of columns in the grid of subplots.
cmap (str) – Name of the matplotlib colormap to use.
colorbar (bool) – Whether to add a colorbar to each subplot.
auto_range_cutoff (Union[float, Tuple[float, float], None]) – Cutoff percentile for auto_range_iqr.
share_color_scale (bool) – Whether to force all layers to use the same color scale.
symmetric_color_scale (bool) – Whether to use a symmetric color scale (vmin = -vmax).
vmin (Optional[float]) – Color scale minimum to use for all layers
vmax (Optional[float]) – Color scale maximum to use for all layers
cross_section_coords (Union[ndarray, Sequence[ndarray], None]) – Shape (m, 2) array of (x, y) coordinates for a cross-section (or a list of such arrays).

Return type:

Tuple[Figure, ndarray]

Returns:

matplotlib figure and axes

superscreen.visualization.plot_field_at_positions(solution, positions, zs=None, vector=False, units=None, shading='gouraud', cmap='cividis', colorbar=True, auto_range_cutoff=None, share_color_scale=False, symmetric_color_scale=False, vmin=None, vmax=None, cross_section_coords=None, **kwargs)[source]¶

Plots the total field (either all three components or just the z component) at a given set of positions (x, y, z) outside of the device.

Additional keyword arguments are passed to plt.subplots().

Parameters:

solution (Solution) – The Solution from which to extract fields.
positions (ndarray) – Shape (m, 2) array of (x, y) coordinates, or (m, 3) array of (x, y, z) coordinates at which to calculate the magnetic field. A single list like [x, y] or [x, y, z] is also allowed.
zs (Union[float, ndarray, None]) – z coordinates at which to calculate the field. If positions has shape (m, 3), then this argument is not allowed. If zs is a scalar, then the fields are calculated in a plane parallel to the x-y plane. If zs is any array, then it must be same length as positions.
vector (bool) – Whether to return the full vector magnetic field or just the z component.
units (Optional[str]) – Units in which to plot the fields. Defaults to solution.field_units. This argument is ignored if normalize is True.
shading (str) – May be "flat" or "gouraud". The latter does some interpolation.
max_cols – Maximum number of columns in the grid of subplots.
cmap (str) – Name of the matplotlib colormap to use.
colorbar (bool) – Whether to add a colorbar to each subplot.
auto_range_cutoff (Union[float, Tuple[float, float], None]) – Cutoff percentile for auto_range_iqr.
share_color_scale (bool) – Whether to force all layers to use the same color scale.
symmetric_color_scale (bool) – Whether to use a symmetric color scale (vmin = -vmax).
vmin (Optional[float]) – Color scale minimum to use for all layers
vmax (Optional[float]) – Color scale maximum to use for all layers
cross_section_coords (Union[float, List[float], None]) – Shape (m, 2) array of (x, y) coordinates for a cross-section (or a list of such arrays).

Return type:

Tuple[Figure, ndarray]

Returns:

matplotlib figure and axes

Currents¶

superscreen.visualization.plot_currents(solution, layers=None, units=None, grid_shape=(200, 200), grid_method='cubic', max_cols=3, cmap='inferno', colorbar=True, auto_range_cutoff=None, share_color_scale=False, symmetric_color_scale=False, vmin=None, vmax=None, streamplot=True, min_stream_amp=0.025, cross_section_coords=None, **kwargs)[source]¶

Plots the current density (sheet current) for each layer in a Device.

Additional keyword arguments are passed to plt.subplots().

Parameters:

solution (Solution) – The Solution from which to extract sheet current.
layers (Union[str, List[str], None]) – Name(s) of layer(s) for which to plot the sheet current. By default, the stream function is plotted for all layers in the Device.
units (Optional[str]) – Units in which to plot the current density. Defaults to solution.current_units / solution.device.length_units.
grid_shape (Union[int, Tuple[int, int]]) – Shape of the desired rectangular grid. If a single integer n is given, then the grid will be square, shape = (n, n).
grid_method (str) – Interpolation method to use (see scipy.interpolate.griddata).
max_cols (int) – Maximum number of columns in the grid of subplots.
cmap (str) – Name of the matplotlib colormap to use.
colorbar (bool) – Whether to add a colorbar to each subplot.
auto_range_cutoff (Union[float, Tuple[float, float], None]) – Cutoff percentile for auto_range_iqr.
share_color_scale (bool) – Whether to force all layers to use the same color scale.
symmetric_color_scale (bool) – Whether to use a symmetric color scale (vmin = -vmax).
vmin (Optional[float]) – Color scale minimum to use for all layers (ignored if share_color_scale is True).
vmax (Optional[float]) – Color scale maximum to use for all layers (ignored if share_color_scale is True).
streamplot (bool) – Whether to overlay current streamlines on the plot.
min_stream_amp (float) – Streamlines will not be drawn anywhere the current density is less than min_stream_amp * max(current_density). This avoids streamlines being drawn where there is no current flowing.
cross_section_coords (Union[ndarray, Sequence[ndarray], None]) – Shape (m, 2) array of (x, y) coordinates for a cross-section (or a list of such arrays).

Return type:

Tuple[Figure, ndarray]

Returns:

matplotlib figure and axes

Stream Functions¶

superscreen.visualization.plot_streams(solution, layers=None, units=None, max_cols=3, cmap='magma', levels=101, colorbar=True, filled=True, **kwargs)[source]¶

Plots the stream function for multiple layers in a Device.

Additional keyword arguments are passed to plt.subplots().

Parameters:

solution (Solution) – The Solution from which to extract stream functions.
layers (Union[str, List[str], None]) – Name(s) of layer(s) for which to plot the stream function. By default, the stream function is plotted for all layers in the Device.
units (Optional[str]) – Units in which to plot the stream function. Defaults to solution.current_units.
max_cols (int) – Maximum number of columns in the grid of subplots.
cmap (str) – Name of the matplotlib colormap to use.
levels (int) – Number of contour levels to used.
colorbar (bool) – Whether to add a colorbar to each subplot.
filled (bool) – If True, plots filled contours.

Return type:

Tuple[Figure, ndarray]

Returns:

matplotlib figure and axes

Miscellaneous¶

superscreen.visualization.plot_mutual_inductance(M, diff=False, iteration_offset=0, absolute=False, ax=None, figsize=None, logy=False, grid=True, legend=True, **kwargs)[source]¶

Plot the convergence vs. iteration of a set of mutual inductance matrices, given by the output of superscreen.Device.mutual_inductance_matrix() with all_iterations=True.

Parameters:

M (Union[ndarray, List[ndarray]]) – A length m list of shape (n, n) mutual inductance matrices, or a shape (m, n, n) array representing the same.
diff (bool) – If True, plots the difference in mutual inductance between subsequent iterations.
iteration_offset (int) – The first iteration (index in M) to consider when calculating convergence.
absolute (bool) – If True (and diff is True), plots the absolute change in mutual inductance vs. iteration, otherwise plots relative change.
ax (Optional[Axes]) – Matplotlib Axes instance on which to plot.
figsize (Optional[Tuple[float, float]]) – Matplotlib figure size to create if ax is None.
logy (bool) – If True, sets the y axis scaling to logarithmic.
grid (bool) – If True, turns on plot grid lines.
legend (bool) – If True, adds a legend to the plot.
kwargs – Passed to ax.plot().

Return type:

Tuple[Figure, Axes]

Returns:

Matplotlib Figure and Axes.

superscreen.visualization.plot_polygon_flux(solutions, diff=False, iteration_offset=0, absolute=False, units=None, ax=None, figsize=None, logy=False, grid=True, legend=True, **kwargs)[source]¶

Plot the convergence vs. iteration of the flux through all polygons in a Device, given by the output of superscreen.solve()

Parameters:

solutions (List[Solution]) – A list of Solutions, one per solve iteration.
diff (bool) – If True, plots the difference in flux between subsequent iterations.
iteration_offset (int) – The first iteration (index in solutions) to consider when calculating convergence.
absolute (bool) – If True (and diff is True), plots the absolute change in flux vs. iteration, otherwise plots relative change.
units (Optional[str]) – The flux units to display if absolute is True.
ax (Optional[Axes]) – Matplotlib Axes instance on which to plot.
figsize (Optional[Tuple[float, float]]) – Matplotlib figure size to create if ax is None.
logy (bool) – If True, sets the y axis scaling to logarithmic.
grid (bool) – If True, turns on plot grid lines.
legend (bool) – If True, adds a legend to the plot.
kwargs – Passed to ax.plot().

Return type:

Tuple[Figure, Axes]

Returns:

Matplotlib Figure and Axes.

Supporting Functions¶

superscreen.visualization.auto_range_iqr(data_array, cutoff_percentile=1)[source]¶

Get the min and max range of the provided array that excludes outliers following the IQR rule.

This function computes the inter-quartile-range (IQR), defined by Q3-Q1, i.e. the percentiles for 75 and 25 percent of the distribution. The region without outliers is defined by [Q1-1.5*IQR, Q3+1.5*IQR]. Taken from qcodes.

Parameters:

data_array (ndarray) – Array of arbitrary dimension containing the statistical data.
cutoff_percentile (Union[float, Tuple[float, float]]) – Percentile of data that may maximally be clipped on both sides of the distribution. If given a tuple (a, b) the percentile limits will be a and 100-b.

Return type:

Tuple[float, float]

Returns:

vmin, vmax

superscreen.visualization.auto_grid(num_plots, max_cols=3, delaxes=True, **kwargs)[source]¶

Creates a grid of at least num_plots subplots with at most max_cols columns.

Additional keyword arguments are passed to plt.subplots().

Parameters:

num_plots (int) – Total number of plots that will be populated.
max_cols (int) – Maximum number of columns in the grid.
delaxes (bool) – Whether to remove unused axes.

Return type:

Tuple[Figure, ndarray]

Returns:

matplotlib figure and axes

superscreen.visualization.grids_to_vecs(xgrid, ygrid)[source]¶

Extracts coordinate vectors from 2D meshgrids.

Parameters:

xgrid (ndarray) – meshgrid of x coordinates
ygrid (ndarray) – meshgrid of y coordinates

Return type:

Tuple[ndarray, ndarray]

Returns:

vector of x coordinates, vector of y coordinates

superscreen.visualization.setup_color_limits(dict_of_arrays, vmin=None, vmax=None, share_color_scale=False, symmetric_color_scale=False, auto_range_cutoff=None)[source]¶

Set up color limits (vmin, vmax) for a dictionary of numpy arrays.

Parameters:

dict_of_arrays (Dict[str, ndarray]) – Dict of {name: array} for which to compute color limits.
vmin (Optional[float]) – If provided, this vmin will be used for all arrays. If vmin is not None, then vmax must also not be None.
vmax (Optional[float]) – If provided, this vmax will be used for all arrays. If vmax is not None, then vmin must also not be None.
share_color_scale (bool) – Whether to force all arrays to share the same color scale. This option is ignored if vmin and vmax are provided.
symmetric_color_scale (bool) – Whether to use a symmetric color scale (vmin = -vmax). This option is ignored if vmin and vmax are provided.
auto_range_cutoff (Union[float, Tuple[float, float], None]) – Cutoff percentile for auto_range_iqr.

Return type:

Dict[str, Tuple[float, float]]

Returns:

A dict of {name: (vmin, vmax)}

superscreen.visualization.plot_streams_layer(solution, layer, units=None, ax=None, cmap='magma', levels=101, colorbar=True, filled=True, **kwargs)[source]¶

Plots the stream function for a single layer in a Device.

Additional keyword arguments are passed to plt.subplots() if ax is None.

Parameters:

solution (Solution) – The Solution from which to extract the stream function.
layer (str) – Name of the layer in solution.device.layers for which to plot the stream function.
units (Optional[str]) – Units in which to plot the stream function. Defaults to solution.current_units.
ax (Optional[Axes]) – matplotlib axis on which to plot the data. If None is provided, a new figure is created.
cmap (str) – Name of the matplotlib colormap to use.
levels (int) – Number of contour levels to used.
colorbar (bool) – Whether to add a colorbar to the plot.
filled (bool) – If True, plots filled contours.

Return type:

Tuple[Axes, Optional[Colorbar]]

Returns:

matplotlib axis and Colorbar if one was created (None otherwise)

superscreen.visualization.cross_section(dataset_coords, dataset_values, cross_section_coords, interp_method='linear')[source]¶

Takes a cross-section of the specified dataset values along a path given by the given dataset coordinates.

Parameters:

dataset_coords (ndarray) – A shape (n, 2) array of (x, y) coordinates for the dataset.
dataset_values (ndarray) – A shape (n, ) array of dataset values of which to take a cross-section.
cross_section_coords (Union[ndarray, Sequence[ndarray]]) – A shape (m, 2) array of (x, y) coordinates specifying the cross-section path (or a list of such arrays for multiple cross sections).
interp_method (str) – The interpolation method to use: “nearest”, “linear”, “cubic”.

Return type:

Tuple[List[ndarray], List[ndarray], List[ndarray]]

Returns:

A list of coordinate arrays, a list of curvilinear coordinate (path) arrays, and a list of cross section values.