Actual source code: petscsectiontypes.h

      1: #pragma once

      3: /* MANSEC = Vec */
      4: /* SUBMANSEC = PetscSection */

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

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

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

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

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

     26:   The indices returned by the `PetscSection`
     27:   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
     28:   local section. If the section indexes a global vector, we call it a global section. For parallel vectors, like global vectors, we use negative
     29:   indices to indicate dofs owned by other processes.

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

     35:   `PetscSection` is used heavily by `DMPLEX`. Simpler `DM`, such as `DMDA`, generally do not need `PetscSection` since their array access patterns
     36:   are simpler and can be fully expressed using standard programming language array syntax, see [DM commonality](ch_dmcommonality).

     38:   Level: beginner

     40: .seealso: [PetscSection](ch_petscsection), `PetscSectionCreate()`, `PetscSectionGetOffset()`, `PetscSectionGetDof()`, `PetscSectionSetChart()`,
     41:           `PetscSectionGetChart()`, `PetscSectionDestroy()`, `PetscSectionSym`, `PetscSectionSetup()`, `DM`, `DMDA`, `DMPLEX`
     42: S*/
     43: typedef struct _p_PetscSection *PetscSection;

     45: /*S
     46:   PetscSectionSym - Symmetries of the data referenced by a `PetscSection`.

     48:   Often the order of data index by a `PetscSection` is meaningful, and describes additional structure, such as points on a
     49:   line, grid, or lattice.  If the data is accessed from a different "orientation", then the image of the data under
     50:   access then undergoes a symmetry transformation.  A `PetscSectionSym` specifies these symmetries.  The types of
     51:   symmetries that can be specified are of the form R * P, where R is a diagonal matrix of scalars, and P is a permutation.

     53:   Level: developer

     55: .seealso: [PetscSection](ch_petscsection), `PetscSection`, `PetscSectionSymCreate()`, `PetscSectionSymDestroy()`, `PetscSectionSetSym()`, `PetscSectionGetSym()`, `PetscSectionSetFieldSym()`,
     56:           `PetscSectionGetFieldSym()`, `PetscSectionGetSymPoints()`, `PetscSectionSymType`, `PetscSectionSymSetType()`, `PetscSectionSymGetType()`
     57: S*/
     58: typedef struct _p_PetscSectionSym *PetscSectionSym;

     60: /*J
     61:   PetscSectionSymType - String with the name of a `PetscSectionSym` type.

     63:   Level: developer

     65:   Note:
     66:   `PetscSectionSym` has no default implementation, but is used by `DM` in `PetscSectionSymCreateLabel()`.

     68: .seealso: [PetscSection](ch_petscsection), `PetscSectionSymSetType()`, `PetscSectionSymGetType()`, `PetscSectionSym`, `PetscSectionSymCreate()`, `PetscSectionSymRegister()`
     69: J*/
     70: typedef const char *PetscSectionSymType;