Finite Volume Methods

The tdgl.finite_volume module contains the implementation of the finite volume methods described in the Theoretical Background.

Finite Volume Meshes

class tdgl.finite_volume.Mesh(sites, elements, boundary_indices, areas=None, dual_sites=None, edge_mesh=None, voronoi_polygons=None)[source]

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.
areas (Optional[Sequence[float]]) – The areas corresponding to the sites.
dual_sites (Optional[Sequence[Tuple[float, float]]]) – The (x, y) coordinates of the dual (Voronoi) mesh vertices
edge_mesh (Optional[EdgeMesh]) – The edge mesh.
voronoi_polygons (Optional[List[Sequence[Tuple[float, float]]]]) – A list of Voronoi polygon vertices. There is one set of Voronoi polygon vertices for each mesh site.

property x: ndarray: The x-coordinates of the mesh sites.

property y: ndarray: The y-coordinates of the mesh sites.

property center_of_mass: Tuple[float, float]: The (x, y) coordinates of the center of mass of the mesh.

closest_site(xy)[source]

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, create_submesh=True)[source]

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.
create_submesh (bool) – Whether to generate the corresponding tdgl.finit_volume.EdgeMesh and Voronoi dual mesh.

Return type:

Mesh

Returns:

A new tdgl.finite_volume.Mesh instance

static find_boundary_indices(elements)[source]

Find the boundary vertices.

Parameters:: elements (ndarray) – The triangular elements.
Return type:: ndarray
Returns:: An array of site indices corresponding to the boundary.

static compute_voronoi_areas_polygons(sites, elements, dual_sites, edge_mesh, boundary_indices)[source]

Compute the area and indices of the Voronoi region for each vertex.

Parameters:

sites (ndarray) – The (x, y) coordinates of the mesh sites.
elements (ndarray) – The mesh triangle indices.
dual_sites (ndarray) – The (x, y) coordinates of the dual mesh vertices.
edge_mesh (EdgeMesh) – A tdgl.finite_volume.EdgeMesh instance for the triangulation defined by sites and elements.
boundary_indices (ndarray) – The site indices corresponding to the boundary.

Return type:

Tuple[ndarray, ndarray]

Returns:

The Voronoi cell areas and the counterclockwise-oriented vertices of the Voronoi cells.

get_quantity_on_site(quantity_on_edge, vector=True, use_cupy=False)[source]

Compute the quantity on site by averaging over all edges connecting to each site.

Parameters:

quantity_on_edge (ndarray) – Observable on the edges.
vector (bool) – Whether quantity_on_edge is a vector quantity.
interface. (use_cupy. Whether to use cupy) –
use_cupy (bool) –

Return type:

ndarray

Returns:

The quantity vector or scalar at each site.

smooth(iterations, create_submesh=True)[source]

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.
create_submesh (bool) – Whether to create the dual mesh and edge mesh.

Return type:

Mesh

Returns:

A new tdgl.finite_volume.Mesh with relaxed vertex positions.

plot(ax=None, show_sites=True, show_edges=False, show_dual_edges=True, show_voronoi_centroids=False, site_color=None, edge_color='k', centroid_color=None, dual_edge_color='k', linewidth=0.75, linestyle='-', marker='.')[source]

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.
show_dual_edges (bool) – Whether to show the dual mesh edges.
show_voronoi_centroids (bool) – Whether to show the centroid of each Voronoi cell.
site_color (Union[str, Sequence[float], None]) – The color for the sites.
edge_color (Union[str, Sequence[float], None]) – The color for the edges.
dual_edge_color (Union[str, Sequence[float], None]) – The color for the dual edges.
centroid_color (Union[str, Sequence[float], None]) – The color for the Voronoi centroids.
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 and Voronoi centroids.

Return type:

Axes

Returns:

The resulting plt.Axes

to_hdf5(h5group, compress=False)[source]

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

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

Returns True if the h5py.Group contains all of the data necessary to create a tdgl.finite_volume.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 tdgl.finite_volume.EdgeMesh(centers, edges, boundary_edge_indices, directions, edge_lengths, dual_edge_lengths)[source]

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.
dual_edge_lengths (Sequence[float]) – Length of the dual edges.

property x: ndarray: The x-coordinates of the edge centers.

property y: ndarray: The y-coordinates of the edge centers.

static from_mesh(sites, elements, dual_sites)[source]

Create edge mesh from mesh.

Parameters:

sites (ndarray) – The (x, y) coordinates for the mesh vertices.
elements (ndarray) – Elements for the mesh.
dual_sites (ndarray) – The (xm y) coordinates for the dual mesh vertices.

Return type:

EdgeMesh

Returns:

The edge mesh.

to_hdf5(h5group)[source]

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

Load edge mesh from file.

Parameters:: h5group (Group) – The HDF5 group to load from.
Return type:: EdgeMesh
Returns:: The loaded edge mesh.

Matrices

class tdgl.finite_volume.MeshOperators(mesh, sparse_solver, use_cupy=False, fixed_sites=None, fix_psi=True)[source]

A container for the finite volume operators for a given mesh.

Parameters:

mesh (Mesh) – The tdgl.finite_volume.Mesh instance for which to construct operators.
sparse_solver (SparseSolver) – The sparse solver for which to build mesh operators.
use_cupy (bool) – Use CuPy for linear algebra.
fixed_sites (Optional[ndarray]) – The indices of any sites for which the value of \(\psi\) and \(\mu\) are fixed as boundary conditions.
fix_psi (bool) –

build_operators()[source]

Construct the vector potential-independent operators.

Return type:: None

set_link_exponents(link_exponents)[source]

Set the link variables and construct the covarient gradient and Laplacian for psi.

Parameters:: link_exponents (ndarray) – The value is integrated, exponentiated and used as a link variable.
Return type:: None

get_supercurrent(psi)[source]

Compute the supercurrent on the edges.

Parameters:: psi (ndarray) – The value of the complex order parameter.
Returns:: The supercurrent at each edge.

tdgl.finite_volume.operators.build_divergence(mesh)[source]

Build the divergence matrix that takes the divergence of a function living on the edges onto the sites.

Parameters:: mesh (Mesh) – The mesh.
Return type:: csr_array
Returns:: The divergence matrix.

tdgl.finite_volume.operators.build_gradient(mesh, link_exponents=None, weights=None)[source]

Build the gradient for a function living on the sites onto the edges.

Parameters:

mesh (Mesh) – The mesh.
link_exponents (Optional[ndarray]) – The value is integrated, exponentiated and used as a link variable.
weights (Optional[ndarray]) –

Return type:

csr_array

Returns:

The gradient matrix.

tdgl.finite_volume.operators.build_laplacian(mesh, link_exponents=None, fixed_sites=None, free_rows=None, fixed_sites_eigenvalues=1, weights=None)[source]

Build a Laplacian matrix on a given mesh.

The default boundary condition is homogenous Neumann conditions. To get Dirichlet conditions, add fixed sites. To get non-homogenous Neumann condition, the flux needs to be specified using a Neumann boundary Laplacian matrix.

Parameters:

mesh (Mesh) – The mesh.
link_exponents (Optional[ndarray]) – The value is integrated, exponentiated and used as a link variable.
fixed_sites (Optional[ndarray]) – The sites to hold fixed.
fixed_sites_eigenvalues (float) – The eigenvalues for the fixed sites.
free_rows (Optional[ndarray]) –
weights (Optional[ndarray]) –

Return type:

Tuple[csc_array, ndarray]

Returns:

The Laplacian matrix and indices of non-fixed rows.

tdgl.finite_volume.operators.build_neumann_boundary_laplacian(mesh, fixed_sites=None)[source]

Build extra matrix for the Laplacian to set non-homogenous Neumann boundary conditions.

Parameters:

mesh (Mesh) – The mesh.
fixed_sites (Optional[ndarray]) – The fixed sites.

Return type:

csr_array

Returns:

The Neumann boundary matrix.