Rodin::Geometry::Shard class

#include <Rodin/Geometry/Shard.h>

Local vs distributed indices

Every entity stored in a shard has a local shard index. This is the index used by the inherited local mesh API.

In addition, each shard entity corresponds to an entity of the distributed mesh. For every topological dimension , Shard stores a bidirectional map

through PolytopeMap.

Therefore:

• all inherited Mesh<Context::Local> methods use local shard indices,
• getPolytopeMap(d) is used to recover the corresponding distributed index.

Local state semantics

Each local shard entity is classified by two orthogonal notions:

• whether it belongs to the local partition, and
• which partition owns it.

The following three mutually exclusive states are used:

• Owned: The entity belongs to the local partition and this partition is its designated owner.

  Owned entities are the ones on which assembly, counting, and global reductions should typically be performed.

• Shared: The entity belongs to the local partition but is owned by another partition.

  Shared entities are part of the partition’s geometric/topological domain, but this rank is not responsible for their global contribution.

• Ghost: The entity does not belong to the local partition but is present locally as overlap because it is needed by neighboring local entities, for example for stencil support, adjacency completeness, or distributed connectivity.

  A ghost entity is always owned by another partition.

In particular:

• Owned ∪ Shared are exactly the entities that define the local partition,
• Ghost entities form the overlap with neighboring partitions,
• every distributed entity present on multiple partitions has exactly one owner.

After finalization, users normally reason in terms of:

• isOwned(d, i)
• isShared(d, i)
• isGhost(d, i)
• isLocal(d, i) (equivalent to Owned || Shared)

Owner map

For each dimension , getOwner(d) stores

That is, this map is meaningful for entities in state Shared or Ghost.

In particular:

• if i is Owned, then getOwner(d) need not contain i,
• if i is Shared or Ghost, then getOwner(d).at(i) gives the rank that owns the entity.

Halo map

For each dimension , getHalo(d) stores

So the halo map is dual to the owner map:

• owner is attached to non-owned local entities (Shared or Ghost),
• halo is attached to owned local entities.

If k is an owned local entity of dimension d, then getHalo(d).at(k) is the set of remote ranks that also contain the same distributed entity, either as Shared or as Ghost.

This information is useful for:

• distributed numbering,
• synchronization,
• neighborhood-restricted communication,
• distributed connectivity discovery.

Geometric and topological contents

A shard is not just a set of cells. It generally contains lower-dimensional entities as well, for example vertices, edges, and faces needed by the local finite element space or by local topological queries.

In particular, a finalized shard may contain:

• owned entities,
• shared entities,
• ghost entities,
• local incidences inherited from the distributed mesh and filtered to the shard contents.

Thus Shard is intended to be a self-consistent local mesh with overlap.

Construction model

Shard::Builder constructs a shard incrementally from either:

• a parent mesh (Mode::Parent), or
• explicit direct insertion of vertices and polytopes (Mode::Direct).

In parent-based mode, a typical construction pattern is:

Shard::Builder builder;
builder.initialize(parentMesh);

// insert owned entities
builder.include({D, cellIdx}, Shard::State::Owned);

// insert overlap entities
builder.include({D, neighborCellIdx}, Shard::State::Ghost);

Shard shard = builder.finalize();

include() is idempotent with respect to the parent index: if the entity is already present in the shard, it is not duplicated. The returned pair is:

• the local shard index of the entity,
• a boolean telling whether the entity was newly inserted.

Finalization guarantees

After Builder::finalize():

• all local entity indices are stable,
• inherited local mesh queries operate on shard-local indices,
• getPolytopeMap(d) maps shard-local entities back to distributed or parent indices,
• isOwned(), isShared(), isGhost(), and isLocal() are available for every local entity,
• getOwner(d) is defined for non-owned local entities (Shared or Ghost),
• getHalo(d) is defined for owned local entities.

Important convention

A shard does not itself define a distributed global numbering of mesh entities or degrees of freedom. It only provides:

• a local mesh with overlap,
• partition/ownership metadata,
• distributed-to-local and local-to-distributed index correspondences.

Global distributed numbering is a higher-level concern handled for example by MPI finite element spaces.

Base classes

template<>

class Mesh<Context::Local>

Represents the subdivision of some domain into faces of (possibly) different geometries.

Public types

class Builder

Incremental builder for Shard.

struct PolytopeMap

Bidirectional correspondence between local shard and distributed indices.

enum class State: uint8_t { Shared = 0, Owned = 1, Ghost = 2 }

Local state of a shard entity.

using ContextType = Rodin::Context::Local

Context type (always local for shards).

using Parent = Mesh<ContextType>

Parent mesh type.

Constructors, destructors, conversion operators

Shard() defaulted

Default constructor.

Shard(const Shard& other)

Copy constructor.

Shard(Shard&& other)

Move constructor.

Public functions

auto operator=(Shard&& other) -> Shard&

Move assignment operator.

auto isGhost(size_t d, Index idx) const -> bool

Tests whether a local entity is ghost.

auto isOwned(size_t d, Index idx) const -> bool

Tests whether a local entity is owned.

auto isShared(size_t d, Index idx) const -> bool

Tests whether a local entity is shared.

auto isLocal(size_t d, Index idx) const -> bool

Tests whether a local entity belongs to the local partition.

auto getOwner(size_t d) const -> const UnorderedMap<Index, Index>&

Returns the owner map for dimension d.

auto getOwner(size_t d) -> UnorderedMap<Index, Index>&

Returns the owner map for dimension d.

auto getHalo(size_t d) const -> const UnorderedMap<Index, IndexSet>&

Returns the halo map for dimension d.

auto getHalo(size_t d) -> UnorderedMap<Index, IndexSet>&

Returns the halo map for dimension d.

auto getState(size_t d) const -> const std::vector<State>&

Returns the local state array for dimension d.

auto getState(size_t d) -> std::vector<State>&

Returns the local state array for dimension d.

auto getPolytopeMap(size_t d) const -> const PolytopeMap&

Returns the local/distributed polytope map for dimension d.

auto getPolytopeMap(size_t d) -> PolytopeMap&

Returns the local/distributed polytope map for dimension d.

template<class Archive>

void serialize(Archive& ar, const unsigned int version)

Serialization method.

Enum documentation

Function documentation