# Devices & Geometry¶

The classes defined in superscreen.device, superscreen.geometry, and superscreen.parameters 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, abstract_regions=None, length_units='um', solve_dtype='float64')[source]

An object representing a device composed of multiple layers of thin film superconductor.

Parameters:
property length_units: str

Length units used for the device geometry.

Return type:

str

property solve_dtype: dtype

Numpy dtype to use for floating point numbers.

Return type:

dtype

property layers: Dict[str, Layer]

Dict of {layer_name: layer}

Return type:
property films: Dict[str, Polygon]

Dict of {film_name: film_polygon}

Return type:
property holes: Dict[str, Polygon]

Dict of {hole_name: hole_polygon}

Return type:
property abstract_regions: Dict[str, Polygon]

Dict of {region_name: region_polygon}

Return type:
property polygons: Dict[str, Polygon]

A dict of {name: polygon} for all Polygons in the device.

Return type:
polygons_by_layer(polygon_type=None)[source]

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

Parameters:

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

Return type:
Returns:

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

For each layer, determines whether points lie within a polygon in that layer.

Parameters:
Return type:
Returns:

A dict of {layer_name: contains_points}. If index is True, then contains_points is an array of indices of the points in points that lie within any polygon in the layer. Otherwise, contains_points is a shape (n, ) boolean array indicating whether each point lies within a polygon in the layer.

property poly_points: ndarray

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

Return type:

ndarray

property vertex_distances: ndarray

An array of the mesh vertex-to-vertex distances.

Return type:

ndarray

property triangle_areas: ndarray

An array of the mesh triangle areas.

Return type:

ndarray

get_arrays(copy_arrays=False, dense=True)[source]

Returns a dict of the large arrays that belong to the device.

Parameters:
• copy_arrays (bool) – Whether to copy all of the arrays or just return references to the existing arrays.

• dense (bool) – Whether to convert any sparse matrices to dense numpy arrays.

Return type:
Returns:

A dict of arrays, with keys specified by Device.ARRAY_NAMES, or None if the arrays don’t exist.

set_arrays(arrays)[source]

Sets the Device’s large arrays from a dict like that returned by Device.get_arrays().

Parameters:

arrays (Dict[str, Union[ndarray, csr_matrix, Dict[str, ndarray]]]) – The dict containing the arrays to use.

Return type:

None

copy(with_arrays=True, copy_arrays=False)[source]

Copy this Device to create a new one.

Parameters:
• with_arrays (bool) – Whether to set the large arrays on the new Device.

• copy_arrays (bool) – Whether to create copies of the large arrays, or just return references to the existing arrays.

Return type:

Device

Returns:

A new Device instance, copied from self

scale(xfact=1, yfact=1, origin=(0, 0))[source]

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:
Return type:

Device

Returns:

The scaled superscreen.Device.

rotate(degrees, origin=(0, 0))[source]

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

Parameters:
Return type:

Device

Returns:

The rotated superscreen.Device.

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)[source]

Translates the device polygons, layers, and mesh 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)[source]

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

Parameters:
Return type:

None

make_mesh(bounding_polygon=None, compute_matrices=True, convex_hull=True, weight_method='half_cotangent', min_points=None, smooth=0, **meshpy_kwargs)[source]

Generates and optimizes the triangular mesh.

Parameters:
• compute_matrices (bool) – Whether to compute the field-independent matrices (weights, Q, Laplace operator) needed for Brandt simulations.

• convex_hull (bool) – If True, mesh the entire convex hull of the device’s polygons.

• weight_method (str) – Weight methods for computing the Laplace operator: one of “uniform”, “half_cotangent”, or “inv_euclidian”.

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

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

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

• bounding_polygon (str | None) –

Return type:

None

compute_matrices(weight_method='half_cotangent')[source]

Calculcates mesh weights, Laplace oeprator, and kernel functions.

Parameters:

weight_method (str) – Meshing scheme: either “uniform”, “half_cotangent”, or “inv_euclidian”.

Return type:

None

mutual_inductance_matrix(hole_polygon_mapping=None, units='pH', all_iterations=False, **solve_kwargs)[source]

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.

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

Return type:
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(ax=None, subplots=False, legend=True, figsize=None, mesh=False, mesh_kwargs={'color': 'k', 'lw': 0.5}, **kwargs)[source]

Plot all of the device’s polygons.

Parameters:
Return type:
Returns:

Matplotlib Figure and Axes

patches()[source]

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

Return type:
draw(ax=None, subplots=False, max_cols=3, legend=False, figsize=None, alpha=0.5, exclude=None, layer_order='increasing')[source]

Draws all polygons in the device as matplotlib patches.

Parameters:
Return type:
Returns:

Matplotlib Figre and Axes.

to_file(directory, save_mesh=True, compressed=True)[source]

Serializes the Device to disk.

Parameters:
• directory (str) – The name of the directory in which to save the Device (must either be empty or not yet exist).

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

• compressed (bool) – Whether to use numpy.savez_compressed rather than numpy.savez when saving the mesh.

Return type:

None

classmethod from_file(directory, compute_matrices=False)[source]

Creates a new Device from one serialized to disk.

Parameters:
• directory (str) – The directory from which to load the device.

• compute_matrices (bool) – Whether to compute the field-independent matrices for the device if the mesh already exists.

Return type:

Device

Returns:

### TransportDevice¶

class superscreen.TransportDevice(name, *, layer, film, source_terminals=None, drain_terminal=None, holes=None, abstract_regions=None, length_units='um', solve_dtype='float64')[source]

Bases: Device

An object representing a single-layer, single-film device to which a source-drain current bias can be applied.

There can be multiple source terminals, but only a single drain terminal. The drain terminal acts as a sink for currents from all source terminals.

Parameters:
property layers: Dict[str, Layer]

Dict of {layer_name: layer}

Return type:
property films: Dict[str, Polygon]

Dict of {film_name: film_polygon}

Return type:
copy(with_arrays=True, copy_arrays=False)[source]

Copy this Device to create a new one.

Parameters:
• with_arrays (bool) – Whether to set the large arrays on the new Device.

• copy_arrays (bool) – Whether to create copies of the large arrays, or just return references to the existing arrays.

Return type:

TransportDevice

Returns:

A new Device instance, copied from self

make_mesh(compute_matrices=True, weight_method='half_cotangent', min_points=None, smooth=0, **meshpy_kwargs)[source]

Generates and optimizes the triangular mesh.

Parameters:
• compute_matrices (bool) – Whether to compute the field-independent matrices (weights, Q, Laplace operator) needed for Brandt simulations.

• weight_method (str) – Weight methods for computing the Laplace operator: one of “uniform”, “half_cotangent”, or “inv_euclidian”.

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

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

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

Return type:

None

boundary_vertices()[source]

An array of boundary vertex indices, ordered counterclockwise.

Return type:

ndarray

Returns:

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

### Layer¶

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

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 Parameters which compute the penetration depth as a function of position.

Parameters:
property Lambda: float | Parameter

Effective penetration depth of the superconductor.

Return type:

### Polygon¶

class superscreen.Polygon(name=None, *, layer=None, points, mesh=True)[source]

A polygonal region located in a Layer.

Parameters:
property points: ndarray

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

Return type:

ndarray

property is_valid: bool

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

Return type:

bool

property area: float

The area of the polygon.

Return type:

float

property extents: Tuple[float, float]

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

Return type:
property polygon: Polygon

A shapely Polygon representing the Polygon.

Return type:

Polygon

property path: Path

A matplotlib.path.Path representing the polygon boundary.

Return type:

Path

Determines whether points lie within the polygon.

Parameters:
Return type:
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.

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, smooth=0, **meshpy_kwargs)[source]

Returns the vertices and triangles of a Delaunay mesh covering 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.

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

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

Return type:
Returns:

Mesh vertex coordinates and triangle indices

rotate(degrees, origin=(0.0, 0.0), inplace=False)[source]

Rotates the polygon counterclockwise by a given angle.

Parameters:
Return type:

Polygon

Returns:

The rotated polygon.

translate(dx=0.0, dy=0.0, inplace=False)[source]

Translates the polygon by a given distance.

Parameters:
Return type:

Polygon

Returns:

The translated polygon.

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

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:
Return type:

Polygon

Returns:

The scaled polygon.

union(*others, name=None)[source]

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

Parameters:
Return type:

Polygon

Returns:

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

intersection(*others, name=None)[source]

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

Parameters:
Return type:

Polygon

Returns:

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

difference(*others, symmetric=False, name=None)[source]

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

Parameters:
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)[source]

Returns polygon points or a new 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:
Return type:
Returns:

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

resample(num_points=None, degree=1, smooth=0)[source]

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)[source]

Plots the Polygon’s vertices.

Parameters:
Return type:

Axes

Returns:

The matplotlib Axes.

classmethod from_union(items, *, name=None, layer=None, mesh=True)[source]

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

Parameters:
Return type:

Polygon

Returns:

A new Polygon.

classmethod from_intersection(items, *, name=None, layer=None, mesh=True)[source]

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

Parameters:
Return type:

Polygon

Returns:

A new Polygon.

classmethod from_difference(items, *, name=None, layer=None, mesh=True, symmetric=False)[source]

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

Parameters:
Return type:

Polygon

Returns:

A new Polygon.

## Meshing¶

superscreen.device.generate_mesh(coords, min_points=None, convex_hull=False, boundary=None, **kwargs)[source]

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

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

Parameters:
Return type:
Returns:

Mesh vertex coordinates and triangle indices.

superscreen.device.smooth_mesh(points, triangles, iterations)[source]

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

Parameters:
Return type:
Returns:

Smoothed mesh vertex coordinates and triangle indices.

## Parameters¶

### Parameter¶

class superscreen.Parameter(func, **kwargs)[source]

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, operator_)[source]

Bases: Parameter

A callable object that behaves like a Parameter (i.e. it computes a scalar or vector quantity as a function of position coordinates x, y, z). A 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 CompositeParameter object.

Parameters:

### Constant¶

class superscreen.Constant(value, dimensions=2)[source]

Bases: Parameter

A Parameter whose value doesn’t depend on position.

## Geometry¶

superscreen.geometry.rotate(coords, angle_degrees)[source]

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

Parameters:
Return type:

ndarray

Returns:

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

superscreen.geometry.translate(coords, dx, dy)[source]

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

Parameters:
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)[source]

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:
Returns:

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

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

Parameters:
Return type:

ndarray

Returns:

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

superscreen.geometry.box(width, height=None, points_per_side=25, center=(0, 0), angle=0)[source]

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

Parameters:
Return type:

ndarray

Returns:

A shape (4 * points_per_side, 2)` array of (x, y) coordinates