Skip to main content
`Ctrl`+`K`

# PetscSection

Provides a mapping from integers in a designated domain (defined by bounds `startp` to `endp`) to integers which can then be used for accessing entries in arrays, other `PetscSection`s, `IS`s, `Vec`s, and `Mat`s.

## Synopsis

    typedef struct _p_PetscSection *PetscSection;

One can think of `PetscSection` as a library-based tool for indexing into multi-dimensional jagged arrays which is needed since programming languages do not provide jagged array functionality baked into their syntax.

The domain, `startp` to `endp`, is called the chart of the `PetscSection()` and is set with `PetscSectionSetChart()` and accessed `PetscSectionGetChart()`. `startp` does not need to be 0, `endp` must be greater than or equal to `startp` and the bounds may be positive or negative.

The range of a `PetscSection` is in the space of contiguous sets of integers. These ranges are frequently interpreted as domains (charts, meaning lower and upper bounds) of other array-like objects, especially other `PetscSection`s, `IS`s, and `Vec`s.

For each point in the chart (from `startp` to `endp`) of a `PetscSection`, the output set is represented through an `offset` and a `count`, which can be obtained using `PetscSectionGetOffset()` and `PetscSectionGetDof()` respectively and can be set via `PetscSectionSetOffset()` and `PetscSectionSetDof()`. Lookup is typically using accessors or routines like `VecGetValuesSection()`

The indices returned by the `PetscSection` are appropriate for the kind of `Vec` it is associated with. For example, if the vector being indexed is a local vector, we call the section a local section. If the section indexes a global vector, we call it a global section. For parallel vectors, like global vectors, we use negative indices to indicate dofs owned by other processes.

Typically `PetscSections` are first constructed via a series of calls to `PetscSectionSetOffset()` and `PetscSectionSetDof()`, finalized via a call to `PetscSectionSetup()` and then used to index into arrays and other PETSc objects. The construction (setup) phase corresponds to providing all the information needed to define the multi-dimensional jagged array structure.

`PetscSection` is used heavily by `DMPLEX`. Simplier `DM`, such as `DMDA`, generally do not need `PetscSection` since their array access patterns are simplier and can be fully expressed using standard programming language array syntax, see DM commonality.

## See Also

PetscSection, `PetscSectionCreate()`, `PetscSectionGetOffset()`, `PetscSectionGetDof()`, `PetscSectionSetChart()`, `PetscSectionGetChart()`, `PetscSectionDestroy()`, `PetscSectionSym`, `PetscSectionSetup()`, `DM`, `DMDA`, `DMPLEX`

## Level

beginner

## Location

include/petscsectiontypes.h

## Examples

src/dm/impls/plex/tutorials/ex7.c
src/dm/impls/plex/tutorials/ex14.c
src/dm/impls/plex/tutorials/dmplexgetrestoreclosureindices.F90
src/dm/impls/plex/tutorials/ex1.c
src/dm/impls/plex/tutorials/ex14f90.F90
src/dm/impls/plex/tutorials/ex15.c
src/dm/impls/plex/tutorials/ex16.c
src/dm/impls/plex/tutorials/ex8.c
src/dm/impls/plex/tutorials/ex1f90.F90
src/dm/impls/plex/tutorials/ex6.c

## Implementations

_p_PetscSection in include/petsc/private/sectionimpl.h

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