Devices & Geometry

The classes defined in superscreen.device, superscreen.geometry, and superscreen.parameter are used to set up the inputs to a SuperScreen simulation, namely:

• The geometry and penetration depth of all superconducting films

• The spatial distribution of the applied magnetic field

Devices

Device

class superscreen.Device(name, *, layers, films, holes=None, terminals=None, abstract_regions=None, length_units='um', solve_dtype='float32')

An object representing a device composed of one or more layers of thin film superconductor.

Parameters:

• name (str) – Name of the device.

• layers (Union[Sequence[Layer], Dict[str, Layer]]) – Layers making up the device.

• films (Union[Sequence[Polygon], Dict[str, Polygon]]) – Polygons representing regions of superconductor.

• holes (Union[Sequence[Polygon], Dict[str, Polygon], None]) – Holes representing holes in superconducting films.

• terminals (Optional[Dict[str, List[Polygon]]]) – A dict of {film_name: terminals} representing transport terminals in the device.

• abstract_regions (Union[Sequence[Polygon], Dict[str, Polygon], None]) – Polygons representing abstract regions in a device.

• length_units (str) – Distance units for the coordinate system.

• solve_dtype (Union[str, dtype]) – The float data type to use when solving the device.

property length_units: str

Length units used for the device geometry.

property solve_dtype: dtype

Numpy dtype to use for floating point numbers.

get_polygons(include_terminals=True)

Returns list of all Polygons in the device.

Parameters:

include_terminals (bool) – Include transport terminals in the list.

Return type:

List[Polygon]

Returns:

A list of all Polygons in the device.

property poly_points: ndarray

Shape (n, 2) array of (x, y) coordinates of all Polygons in the Device.

polygons_by_layer(polygon_type=None)

Returns a dict of {layer_name: list of polygons in layer}.

Parameters:

polygon_type (Optional[Literal['film', 'hole', 'abstract', 'terminal', 'all']]) – One of ‘film’, ‘hole’, ‘abstract’, ‘terminal’, or ‘all’, specifying which types of polygons to include.

Return type:

Dict[str, List[Polygon]]

Returns:

A dict of {layer_name: list of polygons in layer of the given type}.

holes_by_film()

Generates a mapping of films to holes contained in the film.

Return type:

Dict[str, List[Polygon]]

Returns:

A dict of {film_name: list of holes in the film}.

copy(with_mesh=True, copy_mesh=False)

Copy this Device to create a new one.

Parameters:

• with_mesh (bool) – Whether to shallow copy the meshes dictionary.

• copy_mesh (bool) – Whether to deepcopy the arrays defining the mesh.

Return type:

Device

Returns:

A new Device instance, copied from self

scale(xfact=1, yfact=1, origin=(0, 0))

Returns a new device with polygons scaled horizontally and/or vertically.

Negative xfact (yfact) can be used to reflect the device horizontally (vertically) about the origin.

Parameters:

• xfact (float) – Factor by which to scale the device horizontally.

• yfact (float) – Factor by which to scale the device vertically.

• origin (Tuple[float, float]) – (x, y) coorindates of the origin.

Return type:

Device

Returns:

The scaled superscreen.Device.

rotate(degrees, origin=(0, 0))

Returns a new device with polygons rotated a given amount counterclockwise about specified origin.

Parameters:

• degrees (float) – The amount by which to rotate the polygons.

• origin (Tuple[float, float]) – (x, y) coorindates of the origin.

Return type:

Device

Returns:

The rotated superscreen.Device.

mirror_layers(about_z=0.0)

Returns a new device with its layers mirrored about the plane z = about_z.

Parameters:

about_z (float) – The z-position of the plane (parallel to the x-y plane) about which to mirror the layers.

Return type:

Device

Returns:

The mirrored superscreen.Device.

translate(dx=0, dy=0, dz=0, inplace=False)

Translates the device polygons, layers, and meshes in space by a given amount.

Parameters:

• dx (float) – Distance by which to translate along the x-axis.

• dy (float) – Distance by which to translate along the y-axis.

• dz (float) – Distance by which to translate layers along the z-axis.

• inplace (bool) – If True, modifies the device (self) in-place and returns None, otherwise, creates a new device, translates it, and returns it.

Return type:

Device

Returns:

The translated device.

translation(dx, dy, dz=0)

A context manager that temporarily translates a device in-place, then returns it to its original position.

Parameters:

• dx (float) – Distance by which to translate polygons along the x-axis.

• dy (float) – Distance by which to translate polygons along the y-axis.

• dz (float) – Distance by which to translate layers along the z-axis.

make_mesh(buffer_factor=0.05, buffer=None, join_style='round', min_points=None, max_edge_length=None, preserve_boundary=False, smooth=0, **meshpy_kwargs)

Generates the triangular mesh for each film and stores them in the self.meshes dictionary.

The arguments buffer_factor, buffer, min_points, max_edge_length, and smooth can be specified either as a single value for all films or as a dict of {film_name: argument_value}.

Parameters:

• buffer_factor (Union[float, Dict[str, float], None]) – Buffer for the film bounding box(es), in units of the maximum film dimension. This argument is ignored if buffer is not None.

• buffer (Union[float, Dict[str, float], None]) – Buffer for the film bounding box(es), in length_units.

• join_style (str) – The join style for the buffered region (see superscreen.Polygon.buffer()).

• min_points (Union[int, Dict[str, int], None]) – Minimum number of vertices in the mesh. If None, then the number of vertices will be determined by meshpy_kwargs and the number of vertices in the underlying polygons.

• max_edge_length (Union[float, Dict[str, float], None]) – The maximum distance between vertices in the resulting mesh.

• preserve_boundary (bool) – Do not add any mesh sites to the boundary.

• smooth (Union[int, Dict[str, int]]) – Number of Laplacian smoothing iterations to perform.

• **meshpy_kwargs – Passed to meshpy.triangle.build().

Return type:

None

boundary_vertices(film)

An array of boundary vertex indices, ordered counterclockwise.

Parameters:

film (str) – The name of the film for which to find boundary indices.

Return type:

ndarray

Returns:

An array of indices for vertices that are on the film boundary, ordered counterclockwise.

mesh_stats_dict()

Returns a dictionary of information about all meshes.

Return type:

Optional[Dict[str, Dict[str, Union[int, float]]]]

mesh_stats(precision=3)

When called with in Jupyter notebook, displays a table of information about the mesh.

Parameters:

precision (int) – Number of digits after the decimal for float values.

Return type:

Optional[HTML]

Returns:

An HTML table of mesh statistics.

mutual_inductance_matrix(hole_polygon_mapping=None, units='pH', all_iterations=False, progress_bar=False, **solve_kwargs)

Calculates the mutual inductance matrix \(\mathbf{M}\) for the Device.

\(\mathbf{M}\) is defined such that element \(M_{ij}\) is the mutual inductance \(\Phi^f_{S_i} / I_j\) between hole \(j\) and polygon \(S_{i}\), which encloses hole \(i\). \(\Phi^f_{S_i}\) is the fluxoid for polygon \(S_i\) and \(I_j\) is the current circulating around hole \(j\).

Parameters:

• hole_polygon_mapping (Optional[Dict[str, ndarray]]) – A dict of {hole_name: polygon_coordinates} specifying a mapping between holes in the device and polygons enclosing those holes, for which the fluxoid will be calculated. The length of this dict, n_holes, will determine the dimension of the square mutual inductance matrix \(M\).

• units (str) – The units in which to report the mutual inductance.

• all_iterations (bool) – Whether to return mutual inductance matrices for all iterations + 1 solutions, or just the final solution.

• progress_bar (bool) – Display a progress bar.

• solve_kwargs – Keyword arguments passed to superscreen.solve.solve(), e.g. iterations.

Return type:

Union[ndarray, List[ndarray]]

Returns:

If all_iterations is False, returns a shape (n_holes, n_holes) mutual inductance matrix from the final iteration. Otherwise, returns a list of mutual inductance matrices, each with shape (n_holes, n_holes). The length of the list is 1 if the device has a single layer, or iterations + 1 if the device has multiple layers.

plot_polygons(ax=None, subplots=False, legend=False, figsize=None, **kwargs)

Plot all of the Device’s polygons.

Parameters:

• ax (Optional[Axes]) – matplotlib axis on which to plot. If None, a new figure is created.

• subplots (bool) – If True, plots each film on a different subplot.

• legend (bool) – Whether to add a legend.

• figsize (Optional[Tuple[float, float]]) – matplotlib figsize, only used if ax is None.

• kwargs – Passed to ax.plot() for the polygon boundaries.

Return type:

Tuple[Figure, Axes]

Returns:

Matplotlib Figure and Axes

plot_mesh(ax=None, subplots=False, figsize=None, show_sites=False, show_edges=True, site_color=None, edge_color=None, linewidth=0.75, linestyle='-', marker='.')

Plot all of the Device’s meshes.

Parameters:

• ax (Optional[Axes]) – matplotlib axis on which to plot. If None, a new figure is created.

• subplots (bool) – If True, plots each film on a different subplot.

• figsize (Optional[Tuple[float, float]]) – matplotlib figsize, only used if ax is None.

• show_sites (bool) – Whether to show the mesh sites.

• show_edges (bool) – Whether to show the mesh edges.

• site_color (Union[str, Sequence[float], None]) – The color for the sites.

• edge_color (Union[str, Sequence[float], None]) – The color for the edges.

• linewidth (float) – The line width for all edges.

• linestyle (str) – The line style for all edges.

• marker (str) – The marker to use for the mesh sites.

Return type:

Tuple[Figure, Axes]

Returns:

Matplotlib Figure and Axes

patches()

Returns a dict of {layer_name: {film_name: PathPatch}} for visualizing the device. `

Return type:

Dict[str, Dict[str, PathPatch]]

draw(ax=None, subplots=False, max_cols=3, legend=False, figsize=None, alpha=0.5, exclude=None, layer_order='increasing')

Draws all polygons in the device as matplotlib patches.

Parameters:

• ax (Optional[Axes]) – matplotlib axis on which to plot. If None, a new figure is created.

• subplots (bool) – If True, plots each layer on a different subplot.

• max_cols (int) – The maximum number of columns to create if subplots is True.

• legend (bool) – Whether to add a legend.

• figsize (Optional[Tuple[float, float]]) – matplotlib figsize, only used if ax is None.

• alpha (float) – The alpha (opacity) value for the patches (0 <= alpha <= 1).

• exclude (Union[str, List[str], None]) – A polygon name or list of polygon names to exclude from the figure.

• layer_order (str) – If "increasing" ("decreasing") draw polygons in increasing (decreasing) order by layer height layer.z0.

Return type:

Tuple[Figure, Union[Axes, ndarray]]

Returns:

Matplotlib Figre and Axes.

to_hdf5(path_or_group, save_mesh=True, compress=True)

Serializes the Device to and HDF5 file.

Parameters:

• path_or_group (Union[PathLike, Group]) – Path to an HDF5 file to create, or an open HD5F file.

• save_mesh (bool) – Whether to save the full mesh to file.

• compress (bool) – Save the minimum amount of data needed to recreate the mesh.

Return type:

None

static from_hdf5(path_or_group)

Loads a Device from an HDF5 file.

Parameters:

path_or_group (Union[PathLike, Group]) – Path to an HDF5 file to read, or an open HD5F file.

Return type:

Device

Returns:

The deserialized Device.

Layer

class superscreen.Layer(name, Lambda=None, london_lambda=None, thickness=None, z0=0)

A single layer of a superconducting device.

You can provide either an effective penetration depth Lambda, or both a London penetration depth (lambda_london) and a layer thickness. Lambda and london_lambda can either be real numers or instances of superscreen.Parameter which compute the penetration depth as a function of position.

Parameters:

• name (str) – Name of the layer.

• Lambda (Union[float, Parameter, None]) – The effective magnetic penetration depth of the superconducting film(s) in the layer.

• thickness (Optional[float]) – Thickness of the superconducting film(s) located in the layer.

• london_lambda (Union[float, Parameter, None]) – London penetration depth of the superconducting film(s) located in the layer.

• z0 (float) – Vertical location of the layer.

property Lambda: float | Parameter

Effective penetration depth of the superconductor.

Polygon

class superscreen.Polygon(name=None, *, layer=None, points)

A simply-connected polygon located in a Layer.

Parameters:

• name (Optional[str]) – Name of the polygon.

• layer (Optional[str]) – Name of the layer in which the polygon is located.

• points (Union[Polygon, ndarray, LineString, LinearRing, Polygon]) – The polygon vertices. This can be a shape (n, 2) array of x, y coordinates or a shapely LineString, LinearRing, or superscreen.Polygon.

property points: ndarray

A shape (n, 2) array of counter-clockwise-oriented polygon vertices.

property is_valid: bool

True if the superscreen.Polygon has a name and layer its geometry is valid.

property area: float

The area of the polygon.

property extents: Tuple[float, float]

Returns the total x, y extent of the polygon, (Delta_x, Delta_y).

property polygon: Polygon

A shapely superscreen.Polygon representing the superscreen.Polygon

property path: Path

A matplotlib.path.Path representing the polygon boundary.

set_name(name)

Sets the Polygon’s name and returns self.

Parameters:

name (Optional[str]) – The new name for the superscreen.Polygon

Return type:

Polygon

Returns:

self

set_layer(layer)

Sets the Polygon’s layer and returns self.

Parameters:

layer (Optional[str]) – The new layer for the superscreen.Polygon

Return type:

Polygon

Returns:

self

contains_points(points, index=False, radius=0)

Determines whether points lie within the polygon.

Parameters:

• points (ndarray) – Shape (n, 2) array of x, y coordinates.

• index (bool) – If True, then return the indices of the points in points that lie within the polygon. Otherwise, returns a shape (n, ) boolean array.

• radius (float) – An additional margin on self.path. See matplotlib.path.Path.contains_points().

Return type:

Union[bool, ndarray]

Returns:

If index is True, returns the indices of the points in points that lie within the polygon. Otherwise, returns a shape (n, ) boolean array indicating whether each point lies within the polygon.

on_boundary(points, radius=0.001, index=False)

Determines whether points lie within a given radius of the Polygon boundary.

Parameters:

• points (ndarray) – Shape (n, 2) array of x, y coordinates.

• radius (float) – Points within radius of the boundary are considered to lie on the boundary.

• index (bool) – If True, then return the indices of the points in points that lie on the boundary. Otherwise, returns a shape (n, ) boolean array.

Returns:

If index is True, returns the indices of the points in points that lie within the polygon. Otherwise, returns a shape (n, ) boolean array indicating whether each point lies within the polygon.

make_mesh(min_points=None, max_edge_length=None, convex_hull=False, smooth=0, build_operators=False, **meshpy_kwargs)

Creates a Mesh for the polygon.

Parameters:

• min_points (Optional[int]) – Minimum number of vertices in the mesh. If None, then the number of vertices will be determined by meshpy_kwargs and the number of vertices in the underlying polygons.

• max_edge_length (Optional[float]) – The maximum distance between vertices in the resulting mesh.

• convex_hull (bool) – If True, then the entire convex hull of the polygon (minus holes) will be meshed. Otherwise, only the polygon interior is meshed.

• smooth (int) – Number of Laplacian smoothing steps to perform.

• build_operators (bool) – Whether to build the superscreen.device.MeshOperators for the mesh.

• **meshpy_kwargs – Passed to meshpy.triangle.build().

Return type:

Mesh

rotate(degrees, origin=(0.0, 0.0), inplace=False)

Rotates the polygon counterclockwise by a given angle.

Parameters:

• degrees (float) – The amount by which to rotate the polygon.

• origin (Union[str, Tuple[float, float]]) – (x, y) coorindates about which to rotate, or the strings “center” (for the bounding box center) or “centroid” (for the polygon center of mass).

• inplace (bool) – If True, modify the polygon in place. Otherwise, return a modified copy.

Return type:

Polygon

Returns:

The rotated polygon.

translate(dx=0.0, dy=0.0, inplace=False)

Translates the polygon by a given distance.

Parameters:

• dx (float) – Distance by which to translate along the x-axis.

• dy (float) – Distance by which to translate along the y-axis.

• inplace (bool) – If True, modify the polygon in place. Otherwise, return a modified copy.

Return type:

Polygon

Returns:

The translated polygon.

scale(xfact=1.0, yfact=1.0, origin=(0, 0), inplace=False)

Scales the polygon horizontally by xfact and vertically by yfact.

Negative xfact (yfact) can be used to reflect the polygon horizontally (vertically) about the origin.

Parameters:

• xfact (float) – Distance by which to translate along the x-axis.

• yfact (float) – Distance by which to translate along the y-axis.

• origin (Union[str, Tuple[float, float]]) – (x, y) coorindates for the scaling origin, or the strings “center” (for the bounding box center) or “centroid” (for the polygon center of mass).

• inplace (bool) – If True, modify the polygon in place. Otherwise, return a modified copy.

Return type:

Polygon

Returns:

The scaled polygon.

union(*others, name=None)

Returns the union of the polygon and zero or more other polygons.

Parameters:

• others (Union[Polygon, ndarray, LineString, LinearRing, Polygon]) – One or more objects with which to join the polygon.

• name (Optional[str]) – A name for the resulting joined superscreen.Polygon (defaults to self.name.)

Return type:

Polygon

Returns:

A new Polygon instance representing the union of self and others.

intersection(*others, name=None)

Returns the intersection of the polygon and zero or more other polygons.

Parameters:

• others (Union[Polygon, ndarray, LineString, LinearRing, Polygon]) – One or more objects with which to join the polygon.

• name (Optional[str]) – A name for the resulting joined superscreen.Polygon (defaults to self.name.)

Return type:

Polygon

Returns:

A new Polygon instance representing the intersection of self and others.

difference(*others, symmetric=False, name=None)

Returns the difference of the polygon and zero more other polygons.

Parameters:

• others (Union[Polygon, ndarray, LineString, LinearRing, Polygon]) – One or more objects with which to join the polygon.

• symmetric (bool) – Whether to join via a symmetric difference operation (aka XOR). See the shapely documentation.

• name (Optional[str]) – A name for the resulting joined superscreen.Polygon (defaults to self.name.)

Return type:

Polygon

Returns:

A new Polygon instance representing the difference of self and others.

buffer(distance, join_style='mitre', mitre_limit=5.0, single_sided=True, as_polygon=True)

Returns polygon points or a new superscreen.Polygon object with vertices offset from self.points by a given distance. If distance > 0 this “inflates” the polygon, and if distance < 0 this shrinks the polygon.

Parameters:

• distance (float) – The amount by which to inflate or deflate the polygon.

• join_style (Union[str, int]) – One of “round” (1), “mitre” (2), or “bevel” (3). See the shapely documentation.

• mitre_limit (float) – See the shapely documentation.

• single_sided (bool) – See the shapely documentation.

• as_polygon (bool) – If True, returns a new superscreen.Polygon instance, otherwise returns a shape (n, 2) array of polygon vertices.

Return type:

Union[ndarray, Polygon]

Returns:

A new superscreen.Polygon or an array of vertices offset by distance.

resample(num_points=None, degree=1, smooth=0)

Resample vertices so that they are approximately uniformly distributed along the polygon boundary.

Parameters:

• num_points (Optional[int]) – Number of points to interpolate to. If num_points is None, the polygon is resampled to len(self.points) points. If num_points is not None and has a boolean value of False, then an unaltered copy of the polygon is returned.

• degree (int) – The degree of the spline with which to iterpolate. Defaults to 1 (linear spline).

• smooth (float) – Smoothing condition.

Return type:

Polygon

plot(ax=None, **kwargs)

Plots the Polygon’s vertices.

Parameters:

• ax (Optional[Axes]) – The matplotlib Axes on which to plot. If None is given, a new one is created.

• kwargs – Passed to ax.plot().

Return type:

Axes

Returns:

The matplotlib Axes.

classmethod from_union(items, *, name=None, layer=None)

Creates a new Polygon from the union of a sequence of polygons.

Parameters:

• items (Iterable[Union[Polygon, ndarray, LineString, LinearRing, Polygon]]) – A sequence of polygon-like objects to join.

• name (Optional[str]) – Name of the polygon.

• layer (Optional[str]) – Name of the layer in which the polygon is located.

Return type:

Polygon

Returns:

A new Polygon.

classmethod from_intersection(items, *, name=None, layer=None)

Creates a new Polygon from the intersection of a sequence of polygons.

Parameters:

• items (Iterable[Union[Polygon, ndarray, LineString, LinearRing, Polygon]]) – A sequence of polygon-like objects to join.

• name (Optional[str]) – Name of the polygon.

• layer (Optional[str]) – Name of the layer in which the polygon is located.

Return type:

Polygon

Returns:

A new Polygon.

classmethod from_difference(items, *, name=None, layer=None, symmetric=False)

Creates a new Polygon from the difference of a sequence of polygons.

Parameters:

• items (Iterable[Union[Polygon, ndarray, LineString, LinearRing, Polygon]]) – A sequence of polygon-like objects to join.

• name (Optional[str]) – Name of the polygon.

• layer (Optional[str]) – Name of the layer in which the polygon is located.

• symmetric (bool) – If True, creates a new Polygon from the “symmetric difference” (aka XOR) of the inputs.

Return type:

Polygon

Returns:

A new Polygon.

Meshing

class superscreen.Mesh(sites, elements, boundary_indices, vertex_areas, triangle_areas, edge_mesh, build_operators=True)

A triangular mesh of a simply- or multiply-connected polygon.

Tip

Use Mesh.from_triangulation() to create a new mesh from a triangulation.

Parameters:

• sites (Sequence[Tuple[float, float]]) – The (x, y) coordinates of the mesh vertices.

• elements (Sequence[Tuple[int, int, int]]) – A list of triplets that correspond to the indices of he vertices that form a triangle. [[0, 1, 2], [0, 1, 3]] corresponds to a triangle connecting vertices 0, 1, and 2 and another triangle connecting vertices 0, 1, and 3.

• boundary_indices (Sequence[int]) – Indices corresponding to the boundary.

• vertex_areas (Sequence[float]) – The areas corresponding to the sites or vertices.

• triangle_areas (Sequence[float]) – The areas of the triangular mesh elements.

• edge_mesh (EdgeMesh) – The edge mesh.

• build_operators (bool) – Whether to build the superscreen.device.MeshOperators for the mesh.

property triangulation: Triangulation

Matplotlib triangulation of the mesh.

stats()

Returns a dictionary of information about the mesh.

Return type:

Dict[str, Union[int, float]]

closest_site(xy)

Returns the index of the mesh site closest to (x, y).

Parameters:

xy (Tuple[float, float]) – A shape (2, ) or (2, 1) sequence of floats, (x, y).

Return type:

int

Returns:

The index of the mesh site closest to (x, y).

static from_triangulation(sites, elements, build_operators=True)

Create a triangular mesh from the coordinates of the triangle vertices and a list of indices corresponding to the vertices that connect to triangles.

Parameters:

• sites (Sequence[Tuple[float, float]]) – The (x, y) coordinates of the mesh sites.

• elements (Sequence[Tuple[int, int, int]]) – A list of triplets that correspond to the indices of the vertices that form a triangle. E.g. [[0, 1, 2], [0, 1, 3]] corresponds to a triangle connecting vertices 0, 1, and 2 and another triangle connecting vertices 0, 1, and 3.

• build_operators (bool) – Whether to build the superscreen.device.MeshOperators for the mesh.

Return type:

Mesh

Returns:

A new tdgl.finite_volume.Mesh instance

static find_boundary_indices(elements)

Find the boundary vertices.

Parameters:

elements (ndarray) – The triangular elements.

Return type:

ndarray

Returns:

An array of site indices corresponding to the boundary.

smooth(iterations, build_operators=True)

Perform Laplacian smoothing of the mesh, i.e., moving each interior vertex to the arithmetic average of its neighboring points.

Parameters:

• iterations (int) – The number of smoothing iterations to perform.

• build_operators (bool) – Whether to build the superscreen.device.MeshOperators for the mesh.

Return type:

Mesh

Returns:

A new Mesh with relaxed vertex positions.

plot(ax=None, show_sites=False, show_edges=True, site_color=None, edge_color='k', linewidth=0.75, linestyle='-', marker='.')

Plot the mesh.

Parameters:

• ax (Optional[Axes]) – A plt.Axes instance on which to plot the mesh.

• show_sites (bool) – Whether to show the mesh sites.

• show_edges (bool) – Whether to show the mesh edges.

• site_color (Union[str, Sequence[float], None]) – The color for the sites.

• edge_color (Union[str, Sequence[float], None]) – The color for the edges.

• linewidth (float) – The line width for all edges.

• linestyle (str) – The line style for all edges.

• marker (str) – The marker to use for the mesh sites.

Return type:

Axes

Returns:

The resulting plt.Axes

to_hdf5(h5group, compress=True)

Save the mesh to a h5py.Group.

Parameters:

• h5group (Group) – The h5py.Group into which to store the mesh.

• compress (bool) – If True, store only the sites and elements.

Return type:

None

static from_hdf5(h5group)

Load a mesh from an HDF5 file.

Parameters:

h5group (Group) – The HDF5 group to load the mesh from.

Return type:

Mesh

Returns:

The loaded mesh.

static is_restorable(h5group)

Returns True if the h5py.Group contains all of the data necessary to create a Mesh without re-computing any values.

Parameters:

h5group (Group) – The h5py.Group to check.

Return type:

bool

Returns:

Whether the mesh can be restored from the given group.

class superscreen.device.EdgeMesh(centers, edges, boundary_edge_indices, directions, edge_lengths)

A mesh composed of the edges in a triangular mesh.

Tip

Use EdgeMesh.from_mesh() to create from an existing mesh.

Parameters:

• centers (Sequence[Tuple[float, float]]) – The (x, y) coordinates for the edge_centers.

• edges (Sequence[Tuple[int, int]]) – The edges as a sequence of indices.

• boundary_edge_indices (Sequence[int]) – Edges on the boundary.

• directions (Sequence[Tuple[float, float]]) – Directions of the edges.

• edge_lengths (Sequence[float]) – Lengths of the edges.

static from_mesh(sites, elements)

Create edge mesh from mesh.

Parameters:

• sites (ndarray) – The (x, y) coordinates for the mesh vertices.

• elements (ndarray) – Elements for the mesh.

Return type:

EdgeMesh

Returns:

The edge mesh.

to_hdf5(h5group)

Save the data to a HDF5 file.

Parameters:

h5group (Group) – The HDF5 group to write the data to.

Return type:

None

classmethod from_hdf5(h5group)

Load edge mesh from file.

Parameters:

h5group (Group) – The HDF5 group to load from.

Return type:

EdgeMesh

Returns:

The loaded edge mesh.

class superscreen.device.MeshOperators(*, weights, Q, gradient_x, gradient_y, laplacian)

A container for the finite element operators for a superscreen.Mesh.

Parameters:

• weights (ndarray) – The mesh weights or effective vertex areas, shape (n, )

• Q (ndarray) – The kernel matrix Q, shape (n, n)

• gradient_x (spmatrix) – The x-gradient matrix, shape (n, n)

• gradient_y (spmatrix) – The y-gradient matrix, shape (n, n)

• laplacian (spmatrix) – The mesh Laplacian, shape (n, n)

static from_mesh(mesh)

Construct a superscreen.device.MeshOperators instance from a superscreen.Mesh.

Parameters:

mesh (Mesh) – The superscreen.Mesh

Return type:

MeshOperators

Returns:

A new superscreen.device.MeshOperators instance

copy()

Returns a deep copy.

Return type:

MeshOperators

static C_vector(points)

Computes the edge vector, C:

\[\begin{split}C_i &= \frac{1}{4\pi}\sum_{p,q=\pm1}\sqrt{(\Delta x - px_i)^{-2} + (\Delta y - qy_i)^{-2}}\\ \Delta x &= \frac{1}{2}(\mathrm{max}(x) - \mathrm{min}(x))\\ \Delta y &= \frac{1}{2}(\mathrm{max}(y) - \mathrm{min}(y))\end{split}\]

See Eq. 12 in [Brandt-PRB-2005], Eq. 16 in [Kirtley-RSI-2016], and Eq. 15 in [Kirtley-SST-2016].

Parameters:

points (ndarray) – Shape (n, 2) array of x, y coordinates of vertices.

Return type:

ndarray

Returns:

Shape (n, ) array, Ci

static Q_matrix(points, weights)

Computes the kernel matrix, Q:

\[Q_{ij} = (\delta_{ij}-1)q_{ij} + \delta_{ij}\frac{1}{w_{ij}}\left(C_i + \sum_{l\neq i}q_{il}w_{il}\right)\]

See Eq. 10 in [Brandt-PRB-2005], Eq. 11 in [Kirtley-RSI-2016], and Eq. 11 in [Kirtley-SST-2016].

Parameters:

• points (ndarray) – Shape (n, 2) array of mesh sites.

• weights (ndarray) – Shape (n, ) weight vector.

Return type:

ndarray

Returns:

Shape (n, n) array, Qij

superscreen.device.generate_mesh(poly_coords, hole_coords=None, min_points=None, max_edge_length=None, convex_hull=False, boundary=None, preserve_boundary=False, min_angle=32.5, **kwargs)

Generates a Delaunay mesh for a given set of polygon vertex coordinates.

Additional keyword arguments are passed to triangle.build().

Parameters:

• poly_coords (ndarray) – Shape (n, 2) array of polygon (x, y) coordinates.

• hole_coords (Optional[List[ndarray]]) – A list of arrays of hole boundary coordinates.

• min_points (Optional[int]) – The minimimum number of vertices in the resulting mesh.

• max_edge_length (Optional[float]) – The maximum distance between interior vertices in the resulting mesh.

• convex_hull (bool) – If True, then the entire convex hull of the polygon (minus holes) will be meshed. Otherwise, only the polygon interior is meshed.

• boundary (Optional[ndarray]) – Shape (m, 2) (where m <= n) array of (x, y) coordinates for points on the boundary of the polygon.

• preserve_boundary (bool) – Do not add any mesh sites to the boundary.

• min_angle (float) – The minimum angle in the mesh’s triangles. Setting a larger value will make the triangles closer to equilateral, but the mesh generation may fail if the value is too large.

Return type:

Tuple[ndarray, ndarray]

Returns:

Mesh vertex coordinates and triangle indices.

superscreen.device.smooth_mesh(points, triangles, iterations)

Perform Laplacian smoothing of the mesh, i.e., moving each interior vertex to the arithmetic average of its neighboring points.

Parameters:

• points (ndarray) – Shape (n, 2) array of vertex coordinates.

• triangles (ndarray) – Shape (m, 3) array of triangle indices.

• iterations (int) – The number of smoothing iterations to perform.

Return type:

Tuple[ndarray, ndarray]

Returns:

Smoothed mesh vertex coordinates and triangle indices.

Parameters

Parameter

class superscreen.Parameter(func, **kwargs)

A callable object that computes a scalar or vector quantity as a function of position coordinates x, y (and optionally z).

Addition, subtraction, multiplication, and division between multiple Parameters and/or real numbers (ints and floats) is supported. The result of any of these operations is a CompositeParameter object.

Parameters:

• func (Callable) – A callable/function that actually calculates the parameter’s value. The function must take x, y (and optionally z) as the first and only positional arguments, and all other arguments must be keyword arguments. Therefore func should have a signature like func(x, y, z, a=1, b=2, c=True), func(x, y, *, a, b, c), func(x, y, z, *, a, b, c), or func(x, y, z, *, a, b=None, c=3).

• kwargs – Keyword arguments for func.

CompositeParameter

class superscreen.parameter.CompositeParameter(left, right, op)

Bases: Parameter

A callable object that behaves like a superscreen.Parameter (i.e. it computes a scalar or vector quantity as a function of position coordinates x, y, z). A superscreen.parameter.CompositeParameter object is created as a result of mathematical operations between Parameters, CompositeParameters, and/or real numbers.

Addition, subtraction, multiplication, division, and exponentiation between Parameters, CompositeParameters and real numbers (ints and floats) are supported. The result of any of these operations is a new superscreen.parameter.CompositeParameter object.

Parameters:

• left (Union[int, float, Parameter, CompositeParameter]) – The object on the left-hand side of the operator.

• right (Union[int, float, Parameter, CompositeParameter]) – The object on the right-hand side of the operator.

• op (Union[Callable, str]) – The operator acting on left and right (or its string representation).

Constant

class superscreen.Constant(value, dimensions=2)

Bases: Parameter

A Parameter whose value doesn’t depend on position.

Geometry

superscreen.geometry.rotate(coords, angle_degrees)

Rotates an array of (x, y) coordinates counterclockwise by the specified angle.

Parameters:

• coords (ndarray) – Shape (n, 2) array of (x, y) coordinates.

• angle_degrees (float) – The angle by which to rotate the coordinates.

Return type:

ndarray

Returns:

Shape (n, 2) array of rotated coordinates (x’, y’)

superscreen.geometry.translate(coords, dx, dy)

Translates the given (x, y) coordinates in the palne by (dx, dy).

Parameters:

• coords (ndarray) – Shape (n, 2) array of (x, y) coordinates.

• dx (float) – Amount by which to translate in the x direction.

• dy (float) – Amount by which to translate in the y direction.

Return type:

ndarray

Returns:

Shape (n, 2) array of translated coordinates (x’, y’)

superscreen.geometry.ellipse(a, b, points=100, center=(0, 0), angle=0)

Returns the coordinates for an ellipse with major axis a and semimajor axis b, rotated by the specified angle about (0, 0), then translated to the specified center.

Parameters:

• a (float) – Major axis length

• b (float) – Semi-major axis length

• points (int) – Number of points in the circle

• center (Tuple[float, float]) – Coordinates of the center of the circle

• angle (float) – Angle (in degrees) by which to rotate counterclockwise about (0, 0) before translating to the specified center.

Returns:

A shape (points, 2) array of (x, y) coordinates

superscreen.geometry.circle(radius, points=100, center=(0, 0))

Returns the coordinates for a circle with a given radius, centered at the specified center.

Parameters:

• radius (float) – Radius of the circle

• points (int) – Number of points in the circle

• center (Tuple[float, float]) – Coordinates of the center of the circle

Return type:

ndarray

Returns:

A shape (points, 2) array of (x, y) coordinates

superscreen.geometry.box(width, height=None, points=101, center=(0, 0), angle=0)

Returns the coordinates for a rectangle with a given width and height, centered at the specified center.

Parameters:

• width (float) – Width of the rectangle (in the x direction).

• height (Optional[float]) – Height of the rectangle (in the y direction). If None is given, then height is set to width and the function returns a square.

• points (int) – The target number of points making up the box. The actual number of points may be slightly different than this value.

• center (Tuple[float, float]) – Coordinates of the center of the rectangle.

• angle (float) – Angle (in degrees) by which to rotate counterclockwise about (0, 0) after translating to the specified center.

Return type:

ndarray

Returns:

A shape (m, 2) or array of (x, y) coordinates.