DMPlexCreateColoringLabel#

Gets coloring of the connectivity graph of the DMPlex points at a given depth that are marked by a DMLabel.

Synopsis#

#include "petscdmplex.h"   
PetscErrorCode DMPlexCreateColoringLabel(DM dm, PetscInt depth, PetscInt distance, DMLabel label, PetscInt value, ISColoring *coloring)

Collective

Input Parameters#

dm - the DMPlex object
depth - the dimension of the entities in the connectivity graph.
distance - how far through the mesh a point reaches, in applications of the adjacency (1 for a star, 2 for its closure).
label - the DMLabel selecting the points to color, or NULL to color the whole stratum
value - the stratum value of label selecting the points, ignored when label is NULL

Output Parameter#

coloring - the coloring, in DMPlex point numbers

Options Database Keys#

-dm_plex_coloring_local - color the points each process owns by themselves, without communicating
-dm_plex_coloring_ordering_type name - order the points with MatGetOrdering() before coloring them
-dm_plex_coloring_mat_coloring_type name - the MatColoringType used to color the connectivity graph
-dm_plex_coloring_mat_coloring_weight_type (RANDOM|LEXICAL|LF|SL) - the vertex weighting, which sets the order in which points are colored

Notes#

The graph is the subgraph induced by the selected points: two selected points are connected exactly when one lies in the other’s neighborhood, the points that distance applications of the adjacency reach. Restricting the graph this way, rather than coloring the whole stratum and discarding the unselected points afterwards, both costs work proportional to the selected set and uses fewer colors, since points whose neighbors are all unselected become isolated and can share a color.

Points of one color lie outside one another’s neighborhoods, which is exactly the statement that the patches of that reach are disjoint: with distance one their stars share no cell, and with distance two the closures of those stars, which is what a Vanka patch spans, share no point. Counting hops through the mesh rather than through the graph is what makes this hold at every depth. At depth zero the two agree, but the cell stratum induces no edges at all, since the finite-element adjacency of a cell is its own closure, and only a neighborhood reaching past that cell separates one cell patch from the next.

The adjacency is the one configured on dm by DMSetBasicAdjacency(). For grouping patches, that must be the finite-element adjacency (useCone PETSC_FALSE, useClosure PETSC_TRUE), for which two vertices are adjacent exactly when they share a cell. In parallel the neighborhood of an owned point must be complete on its process, so the mesh overlap has to be at least distance.

By default the graph spans the whole mesh, so a point is colored against its neighbors on other processes and the coloring is the same one a serial run would produce. With -dm_plex_coloring_local each process instead colors the graph its own points induce, on PETSC_COMM_SELF, needing no communication and at most as many colors, but the resulting colors are only meaningful process by process and their number varies between processes. That suits a caller that consumes each process’s colors on their own, such as PCPATCH, which only builds patches around the points a process owns, and never one that treats a color as a global object.

MATCOLORINGGREEDY colors the points in order of decreasing weight, so the ordering determines the number of colors. This routine defaults to MAT_COLORING_WEIGHT_LEXICAL, which sweeps in the point numbering and yields the optimal four colors on a structured grid, where the MatColoring default of random weights uses seven. Use -dm_plex_coloring_ordering_type to sweep in a different order when the point numbering has no locality. A bandwidth-reducing ordering is not what serves a coloring: MATORDERINGRCM is a wavefront, and sweeping a structured grid diagonally costs it six colors rather than four. MatGetOrdering() reaches the graph through MatGetRowIJ(), which is not supported for parallel matrices, so requesting an ordering on more than one process raises an error.