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 PetscSections, ISs, Vecs, and Mats.

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 PetscSections, ISs, and Vecs.

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.

Level#

beginner

Location#

include/petscsectiontypes.h

Examples#

src/ts/tutorials/ex52.c
src/ts/tutorials/ex11.c
src/tao/tutorials/ex3.c
src/snes/tutorials/ex7.c
src/snes/tutorials/ex56.c
src/snes/tutorials/ex13.c
src/ts/tutorials/ex18.c
src/snes/tutorials/ex77.c
src/ts/tutorials/ex30.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