Skip to main content
`Ctrl`+`K`

# DMPlexSectionLoad

Loads section into a `DMPLEX`

## Synopsis

    #include "petscdmplex.h"
    PetscErrorCode DMPlexSectionLoad(DM dm, PetscViewer viewer, PeOp DM sectiondm, PetscSF globalToLocalPointSF, PeOp PetscSF *globalDofSF, PeOp PetscSF *localDofSF)

Collective

## Input Parameters

- dm - The `DM` that represents the topology

- viewer - The `PetscViewer` that represents the on-disk section (sectionA)

- sectiondm - The `DM` into which the on-disk section (sectionA) is migrated, can be `NULL`

- globalToLocalPointSF - The `PetscSF` returned by `DMPlexTopologyLoad(`) when loading dm from viewer

## Output Parameters

- globalDofSF - The `PetscSF` that migrates any on-disk `Vec` data associated with sectionA into a global `Vec` associated with the `sectiondm`’s global section (`NULL` if not needed)

- localDofSF - The `PetscSF` that migrates any on-disk `Vec` data associated with sectionA into a local `Vec` associated with the `sectiondm`’s local section (`NULL` if not needed)

## Notes

This function is a wrapper around `PetscSectionLoad()`; it loads, in addition to the raw section, a list of global point numbers that associates each on-disk section point with a global point number in [0, NX), where NX is the number of topology points in `dm`. Noting that globalToLocalPointSF associates each topology point in dm with a global number in [0, NX), one can readily establish an association of the on-disk section points with the topology points.

In general `dm` and `sectiondm` are two different objects, the former carrying the topology and the latter carrying the section, and have been given a topology name and a section name, respectively, with `PetscObjectSetName()`. In practice, however, they can be the same object (or in case `sectiondm` is `NULL`) if it carries both topology and section; in that case the name of the object is used as both the topology name and the section name.

The output parameter, `globalDofSF` (`localDofSF`), can later be used with `DMPlexGlobalVectorLoad()` (`DMPlexLocalVectorLoad()`) to load on-disk vectors into global (local) vectors associated with sectiondm’s global (local) section.

## Example using 2 processes

      NX (number of points on dm): 4
      sectionA                   : the on-disk section
      vecA                       : a vector associated with sectionA
      sectionB                   : sectiondm's local section constructed in this function
      vecB (local)               : a vector associated with sectiondm's local section
      vecB (global)              : a vector associated with sectiondm's global section

                                         rank 0    rank 1
      vecA (global)                  : [.0 .4 .1 | .2 .3]        <- to be loaded in DMPlexGlobalVectorLoad() or DMPlexLocalVectorLoad()
      sectionA->atlasOff             :       0 2 | 1             <- loaded in PetscSectionLoad()
      sectionA->atlasDof             :       1 3 | 1             <- loaded in PetscSectionLoad()
      sectionA's global point numbers:       0 2 | 3             <- loaded in DMPlexSectionLoad()
      [0, NX)                        :       0 1 | 2 3           <- conceptual partition used in globalToLocalPointSF
      sectionB's global point numbers:     0 1 3 | 3 2           <- associated with [0, NX) by globalToLocalPointSF
      sectionB->atlasDof             :     1 0 1 | 1 3
      sectionB->atlasOff (no perm)   :     0 1 1 | 0 1
      vecB (local)                   :   [.0 .4] | [.4 .1 .2 .3] <- to be constructed by calling DMPlexLocalVectorLoad() with localDofSF
      vecB (global)                  :    [.0 .4 | .1 .2 .3]     <- to be constructed by calling DMPlexGlobalVectorLoad() with globalDofSF

where “|” represents a partition of loaded data, and global point 3 is assumed to be owned by rank 0.

## See Also

DMPlex: Unstructured Grids, `DM`, `DMPLEX`, `DMLoad()`, `DMPlexTopologyLoad()`, `DMPlexCoordinatesLoad()`, `DMPlexLabelsLoad()`, `DMPlexGlobalVectorLoad()`, `DMPlexLocalVectorLoad()`, `PetscSectionLoad()`, `DMPlexSectionView()`, `PetscSF`, `PetscViewer`

## Level

advanced

## Location

src/dm/impls/plex/plex.c

## Examples

src/ts/tutorials/ex30.c

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