1a4963045SJacob Faibussowitsch #pragma once 2ea844a1aSMatthew Knepley 3ce78bad3SBarry Smith /* MANSEC = Vec */ 4ac09b921SBarry Smith /* SUBMANSEC = PetscSection */ 5ac09b921SBarry Smith 6ea844a1aSMatthew Knepley /*S 7*dac9a9d1SBarry Smith PetscSection - Provides a mapping from integers in a designated domain (defined by bounds `startp` to `endp`) to integers which can then be used 8*dac9a9d1SBarry Smith for accessing entries in arrays, other `PetscSection`s, `IS`s, `Vec`s, and `Mat`s. 9*dac9a9d1SBarry Smith 10*dac9a9d1SBarry Smith One can think of `PetscSection` as a library-based tool for indexing into multi-dimensional jagged arrays which is needed 11*dac9a9d1SBarry Smith since programming languages do not provide jagged array functionality baked into their syntax. 12*dac9a9d1SBarry Smith 13*dac9a9d1SBarry Smith The domain, `startp` to `endp`, is called the chart of the `PetscSection()` and is set with `PetscSectionSetChart()` and accessed 14*dac9a9d1SBarry Smith `PetscSectionGetChart()`. `startp` does not need to be 0, `endp` must be greater than or equal to `startp` and the bounds 15*dac9a9d1SBarry Smith may be positive or negative. 16ea844a1aSMatthew Knepley 1720662ed9SBarry Smith The range of a `PetscSection` is in the space of 18*dac9a9d1SBarry Smith contiguous sets of integers. These ranges are frequently interpreted as domains (charts, meaning lower and upper bounds) of other array-like objects, 19*dac9a9d1SBarry Smith especially other `PetscSection`s, `IS`s, and `Vec`s. 20ea844a1aSMatthew Knepley 21*dac9a9d1SBarry Smith For each point in the chart (from `startp` to `endp`) of a `PetscSection`, the output set is represented through an `offset` and a 22*dac9a9d1SBarry Smith `count`, which can be obtained using `PetscSectionGetOffset()` and `PetscSectionGetDof()` respectively and can be set via 23*dac9a9d1SBarry Smith `PetscSectionSetOffset()` and `PetscSectionSetDof()`. Lookup is typically using 24*dac9a9d1SBarry Smith accessors or routines like `VecGetValuesSection()` 25*dac9a9d1SBarry Smith 26*dac9a9d1SBarry Smith The indices returned by the `PetscSection` 2720662ed9SBarry Smith 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 2820662ed9SBarry Smith local section. If the section indexes a global vector, we call it a global section. For parallel vectors, like global vectors, we use negative 2920662ed9SBarry Smith indices to indicate dofs owned by other processes. 30db527f05SMatthew G. Knepley 31*dac9a9d1SBarry Smith Typically `PetscSections` are first constructed via a series of calls to `PetscSectionSetOffset()` and `PetscSectionSetDof()`, finalized via 32*dac9a9d1SBarry Smith a call to `PetscSectionSetup()` and then used to index into arrays and other PETSc objects. The construction (setup) phase corresponds to providing all 33*dac9a9d1SBarry Smith the information needed to define the multi-dimensional jagged array structure. 34*dac9a9d1SBarry Smith 35*dac9a9d1SBarry Smith `PetscSection` is used heavily by `DMPLEX`. Simplier `DM`, such as `DMDA`, generally do not need `PetscSection` since their array access patterns 36*dac9a9d1SBarry Smith are simplier and can be fully expressed using standard programming language array syntax, see [DM commonality](ch_dmcommonality). 37*dac9a9d1SBarry Smith 38ea844a1aSMatthew Knepley Level: beginner 39ea844a1aSMatthew Knepley 40*dac9a9d1SBarry Smith .seealso: [PetscSection](ch_petscsection), `PetscSectionCreate()`, `PetscSectionGetOffset()`, `PetscSectionGetOffset()`, `PetscSectionSetChart()`, 41*dac9a9d1SBarry Smith `PetscSectionGetChart()`, `PetscSectionDestroy()`, `PetscSectionSym`, `PetscSectionSetup()`, `DM`, `DMDA`, `DMPLEX` 42ea844a1aSMatthew Knepley S*/ 43ea844a1aSMatthew Knepley typedef struct _p_PetscSection *PetscSection; 44ea844a1aSMatthew Knepley 45ea844a1aSMatthew Knepley /*S 4687497f52SBarry Smith PetscSectionSym - Symmetries of the data referenced by a `PetscSection`. 47ea844a1aSMatthew Knepley 4887497f52SBarry Smith Often the order of data index by a `PetscSection` is meaningful, and describes additional structure, such as points on a 49ea844a1aSMatthew Knepley line, grid, or lattice. If the data is accessed from a different "orientation", then the image of the data under 5087497f52SBarry Smith access then undergoes a symmetry transformation. A `PetscSectionSym` specifies these symmetries. The types of 51ea844a1aSMatthew Knepley symmetries that can be specified are of the form R * P, where R is a diagonal matrix of scalars, and P is a permutation. 52ea844a1aSMatthew Knepley 53ea844a1aSMatthew Knepley Level: developer 54ea844a1aSMatthew Knepley 55b0c76368SJames Wright .seealso: [PetscSection](ch_petscsection), `PetscSection`, `PetscSectionSymCreate()`, `PetscSectionSymDestroy()`, `PetscSectionSetSym()`, `PetscSectionGetSym()`, `PetscSectionSetFieldSym()`, 56db781477SPatrick Sanan `PetscSectionGetFieldSym()`, `PetscSectionGetSymPoints()`, `PetscSectionSymType`, `PetscSectionSymSetType()`, `PetscSectionSymGetType()` 57ea844a1aSMatthew Knepley S*/ 58ea844a1aSMatthew Knepley typedef struct _p_PetscSectionSym *PetscSectionSym; 59ea844a1aSMatthew Knepley 60ea844a1aSMatthew Knepley /*J 6187497f52SBarry Smith PetscSectionSymType - String with the name of a `PetscSectionSym` type. 62ea844a1aSMatthew Knepley 63ea844a1aSMatthew Knepley Level: developer 64ea844a1aSMatthew Knepley 6587497f52SBarry Smith Note: 6687497f52SBarry Smith `PetscSectionSym` has no default implementation, but is used by `DM` in `PetscSectionSymCreateLabel()`. 67ea844a1aSMatthew Knepley 68b0c76368SJames Wright .seealso: [PetscSection](ch_petscsection), `PetscSectionSymSetType()`, `PetscSectionSymGetType()`, `PetscSectionSym`, `PetscSectionSymCreate()`, `PetscSectionSymRegister()` 69ea844a1aSMatthew Knepley J*/ 70ea844a1aSMatthew Knepley typedef const char *PetscSectionSymType; 71