Visualization

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

Fields

superscreen.visualization.plot_fields(solution, films=None, dataset='field', normalize=False, units=None, shading='flat', 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 the fields for one or more films in a Device.

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

Parameters:

  • solution (Solution) – The Solution from which to extract fields.

  • films (Union[str, List[str], None]) – Name(s) of films(s) for which to plot the fields. By default, the field is plotted for all films in the Device.

  • dataset (Literal['field', 'self_field', 'applied_field', 'field_from_other_films']) – Which set of fields to plot, either “field”, “self_field”, “applied_field”, or “field_from_other_films”.

  • 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 (Literal['flat', 'gouraud']) – 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, 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) anywhere in space.

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

Parameters:

  • solution (Solution) – The Solution from which to extract fields.

  • positions (Union[ndarray, Mesh]) – 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.

  • units (Optional[str]) – Units in which to plot the fields. Defaults to solution.field_units. This argument is ignored if normalize is True.

  • shading (Literal['flat', 'gouraud']) – 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, Axes]

Returns:

matplotlib figure and axes

Currents

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

Plots the sheet current density for one or more films in a Device.

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

Parameters:

  • solution (Solution) – The Solution from which to extract sheet current.

  • films (Union[str, List[str], None]) – Name(s) of film(s) for which to plot the sheet current. By default, the sheet current is plotted for all films in the Device.

  • units (Optional[str]) – Units in which to plot the current density. Defaults to solution.current_units / solution.device.length_units.

  • 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.

  • shading (Literal['flat', 'gouraud']) – May be "flat" or "gouraud". The latter does some interpolation.

  • 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.

  • grid_shape (Union[int, Tuple[int, int]]) – Shape of the rectangular grid used to contruct streamlines. If a single integer N is given, the grid will be square, shape = (N, N).

  • 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, films=None, units=None, max_cols=3, cmap='coolwarm', colorbar=True, shading='flat', auto_range_cutoff=None, share_color_scale=False, symmetric_color_scale=True, vmin=None, vmax=None, **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.

  • films (Union[str, List[str], None]) – Name(s) of films(s) for which to plot the stream function. By default, the stream function is plotted for all films 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.

  • colorbar (bool) – Whether to add a colorbar to each subplot.

  • shading (Literal['flat', 'gouraud']) – May be "flat" or "gouraud". The latter does some interpolation.

  • 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

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.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 (Literal['linear', 'cubic']) – The interpolation method to use: “linear” or “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.