Topologies

AbstractTopology

Abstract supertype of topologies, which define the connectivity of the elements of a mesh. Subtypes: IntervalTopology and Topology2D.

Subtypes implement the following interface:

• nelems
• domain(topology::AbstractTopology)
• mesh
• nlocalelems
• nneighbors
• nsendelems
• nghostelems
• localelemindex
• vertex_coordinates
• opposing_face
• face_node_index
• interior_faces
• ghost_faces
• vertex_node_index
• local_neighboring_elements
• ghost_neighboring_elements
• local_vertices
• ghost_vertices
• neighbors
• boundary_tags
• boundary_tag
• boundary_faces

IntervalTopology(context::ClimaComms.SingletonCommsContext, mesh::Meshes.IntervalMesh)
IntervalTopology(device::ClimaComms.AbstractDevice, mesh::Meshes.IntervalMesh)

Sequential topology on a Meshes.IntervalMesh. Only a SingletonCommsContext is supported.

Fields

• context: The ClimaComms context on which the topology is defined.
• mesh: The IntervalMesh.
• boundaries: NamedTuple mapping boundary names to boundary tags; empty for a periodic domain.

Topology2D(
    context::ClimaComms.AbstractCommsContext,
    mesh::Meshes.AbstractMesh{2},
    elemorder = Meshes.elements(mesh),
    elempid = nothing,
    orderindex = Meshes.linearindices(elemorder),
)

Distributed topology for 2D meshes. elemorder is a vector or other linear ordering of Meshes.elements(mesh), and orderindex its inverse. Elements are partitioned across processes in contiguous blocks of elemorder; elempid must be nothing (a user-supplied partition is not supported).

Elements are referred to in several ways:

• elem: an element of the mesh, often a CartesianIndex.
• gidx: "global index", an enumeration of all elements, with elemorder[gidx] == elem and orderindex[elem] == gidx.
• lidx: "local index", an enumeration of the elements local to this process, with local_elem_gidx[lidx] == gidx.
• sidx: "send index", an index into the send buffer. A local element has one sidx per process it is sent to, with send_elem_lidx[sidx] == lidx.
• ridx: "receive index", an index into the receive buffer of ghost elements, with recv_elem_gidx[ridx] == gidx.

Fields

Common to all processes:

• context: The ClimaComms context on which the topology is defined.
• mesh: The mesh on which the topology is constructed.
• elemorder: elemorder[gidx] is the element with global index gidx.
• orderindex: The inverse of elemorder: orderindex[elemorder[gidx]] == gidx.
• elempid: elempid[gidx] is the process id owning element gidx.

Specific to this process:

• local_elem_gidx: The global indices of the elements local to this process.
• neighbor_pids: Process ids of the neighboring processes.
• send_elem_lidx: Local indices of the elements copied to the send buffer.
• send_elem_lengths: Number of elements sent to each neighboring process.
• recv_elem_gidx: Global indices of the elements received.
• recv_elem_lengths: Number of elements received from each neighboring process.
• interior_faces: Vector of all unique interior faces (lidx, face, olidx, oface, reversed).
• ghost_faces: Vector of all ghost faces (lidx, face, ridx, oface, reversed).
• local_vertices: The (lidx, vert) pairs of the vertices of local elements that touch no ghost element.
• local_vertex_offset: Index in local_vertices of the first pair of each unique vertex.
• ghost_vertices: The (isghost, idx, vert) triples of the vertices of local elements that touch a ghost element; idx is the lidx if isghost is false and the ridx otherwise.
• ghost_vertex_offset: Index in ghost_vertices of the first triple of each unique vertex.
• local_neighbor_elem: The lidx of the neighboring local elements of each local element.
• local_neighbor_elem_offset: Index into local_neighbor_elem of the first neighbor of each element.
• ghost_neighbor_elem: The ridx of the neighboring ghost elements of each local element.
• ghost_neighbor_elem_offset: Index into ghost_neighbor_elem of the first neighbor of each element.
• boundaries: NamedTuple of vectors of (lidx, face) pairs for each boundary.
• internal_elems: Local elements (lidx) that touch no ghost element.
• perimeter_elems: Local elements (lidx) on the process boundary.
• nglobalvertices: Total number of unique vertices.
• nglobalfaces: Total number of unique non-boundary faces.
• ghost_vertex_gcidx: Global connection index of each unique ghost vertex.
• ghost_face_gcidx: Global connection index of each ghost face.
• comm_vertex_lengths: comm_vertex_lengths[i] is the number of unique vertices communicated to neighbor_pids[i].
• comm_face_lengths: comm_face_lengths[i] is the number of unique faces communicated to neighbor_pids[i].
• ghost_vertex_neighbor_loc: Positions in neighbor_pids of the processes each unique ghost vertex is sent to, as a ragged array.
• ghost_vertex_comm_idx_offset: Offsets of the ragged array ghost_vertex_neighbor_loc: ghost vertex i is sent to neighbor_pids[ghost_vertex_neighbor_loc[j]] for j in ghost_vertex_comm_idx_offset[i]:(ghost_vertex_comm_idx_offset[i + 1] - 1).
• repr_ghost_vertex: Representative local (lidx, vert) of each unique ghost vertex.
• ghost_face_neighbor_loc: Position in neighbor_pids of the process each ghost face is communicated to.

spacefillingcurve(mesh::Meshes.AbstractCubedSphere)

Return an element ordering elemorder for a cubed-sphere mesh based on a Gilbert space-filling curve through each panel.

spacefillingcurve(mesh::Meshes.RectilinearMesh)

Return an element ordering elemorder for a rectilinear mesh based on a Gilbert space-filling curve.

mesh(topology)

Return the mesh underlying topology.

nelems(topology)

Return the total number of elements in topology.

nlocalelems(topology)

Return the number of elements local to this process in topology.

nneighbors(topology)

Return the number of neighboring processes of this process in topology.

neighbors(topology)

Return a vector of the PIDs of the neighboring processes of this process.

vertex_coordinates(topology, elem)

Return a tuple of the coordinates of the vertices of element elem (two in 1D, four in 2D).

local_vertices(topology)

Return an iterator over the interior vertices of topology. Each vertex is an iterator over (lidx, vert) pairs.

opposing_face(topology, elem, face)

Return the face (opelem, opface, reversed) opposite face number face of element elem in topology.

• opelem: The opposing element number; 0 for a boundary, negative for a ghost element.
• opface: The opposing face number, or the boundary face number for a boundary.
• reversed: Whether the opposing face has the opposite orientation.

interior_faces(topology::AbstractTopology)

Return an iterator over the interior faces of topology. Each item is a 5-tuple of the form

(elem1, face1, elem2, face2, reversed)

where elemX, faceX are the element and face numbers, and reversed indicates whether they have opposing orientations.

boundary_tags(topology)

Return a Tuple or NamedTuple of the boundary tags of topology. A boundary tag is an integer that uniquely identifies a boundary.

boundary_tag(topology, name::Symbol)

Return the boundary tag of topology for the boundary named name. A boundary tag is an integer that uniquely identifies a boundary.

boundary_faces(topology, boundarytag)

Return an iterator over the faces of topology on the boundary with tag boundarytag. Each item is an (elem, face) pair.

local_neighboring_elements(topology::AbstractTopology, lidx::Integer)

Return an iterator over the local element indices of the local elements that are neighbors of the local element lidx in topology, excluding lidx itself.