Skip to main content
`Ctrl`+`K`

# DMStagPopulateLocalToGlobalInjective

populate an internal 1-to-1 local-to-global map

## Synopsis

    #include "petscdmstag.h"
    #include "petscdmproduct.h"
    PetscErrorCode DMStagPopulateLocalToGlobalInjective(DM dm)

Collective

Creates an internal object which explicitly maps a single local degree of freedom to each global degree of freedom. This is used, if populated, instead of SCATTER_REVERSE_LOCAL with the (1-to-many, in general) global-to-local map, when DMLocalToGlobal() is called with INSERT_VALUES. This allows usage, for example, even in the periodic, 1-rank case, where the inverse of the global-to-local map, even when restricted to on-rank communication, is non-injective. This is at the cost of storing an additional VecScatter object inside each `DMSTAG` object.

## Input Parameter

- dm - the `DMSTAG` object

## Notes

In normal usage, library users shouldn’t be concerned with this function, as it is called during `DMSetUp()`, when required.

Returns immediately if the internal map is already populated.

## Developer Notes

This could, if desired, be moved up to a general `DM` routine. It would allow, for example, `DMDA` to support `DMLocalToGlobal()` with `INSERT_VALUES`, even in the single-rank periodic case.

## See Also

DMSTAG: Staggered, Structured Grid, `DMSTAG`, `DMLocalToGlobal()`, `VecScatter`

## Level

developer

## Location

src/dm/impls/stag/stagutils.c

## Implementations

DMStagPopulateLocalToGlobalInjective_1d() in src/dm/impls/stag/stag1d.c
DMStagPopulateLocalToGlobalInjective_2d() in src/dm/impls/stag/stag2d.c
DMStagPopulateLocalToGlobalInjective_3d() in src/dm/impls/stag/stag3d.c

Index of all DMStag routines
Table of Contents for all manual pages
Index of all manual pages