PetscSection - Low-level Interface

The PetscSection component provides a flexible mechanism for describing the layout of degrees of freedom (DOFs) in a discretization, particularly for finite element methods and other multi-field problems where different points have different numbers of DOFs.

Overview

PetscSection is used to:

Define DOF layouts: Specify how many DOFs exist at each point (vertex, edge, face, cell)
Multi-field problems: Handle systems with multiple variables per point
Local-to-global mapping: Convert between local and global numbering
FEM discretizations: Manage DOF distributions for finite elements
DM integration: Work with DM objects for mesh-based computations

A section maps from points (mesh entities like vertices, cells) to DOF ranges, answering:

How many DOFs are at point p?
What is the offset of the DOFs for point p?
Which field do specific DOFs belong to?

Basic Usage

using PETSc, MPI

# Initialize MPI and PETSc
MPI.Init()
petsclib = PETSc.getlib()
PETSc.initialize(petsclib)
PetscInt = petsclib.PetscInt

# Create a section
section = LibPETSc.PetscSectionCreate(petsclib, LibPETSc.PETSC_COMM_SELF)

# Set chart: range of valid point indices [pStart, pEnd)
LibPETSc.PetscSectionSetChart(petsclib, section, 0, 10)

# Set DOF count for each point
for p in 0:9
    num_dofs = (p < 4) ? 1 : 2  # Different DOFs per point
    LibPETSc.PetscSectionSetDof(petsclib, section, p, num_dofs)
end

# Setup: compute offsets
LibPETSc.PetscSectionSetUp(petsclib, section)

# Query the section
dof = LibPETSc.PetscSectionGetDof(petsclib, section, 5)
println("DOF count for point 5: ", dof)

offset = LibPETSc.PetscSectionGetOffset(petsclib, section, 5)
println("Offset for point 5: ", offset)

# Get total storage size
storage_size = LibPETSc.PetscSectionGetStorageSize(petsclib, section)
println("Total storage size: ", storage_size)

# Cleanup
LibPETSc.PetscSectionDestroy(petsclib, section)

PETSc.finalize(petsclib)
MPI.Finalize()

Multi-Field Sections

For problems with multiple fields (e.g., velocity + pressure):

# Create section with 2 fields
section = LibPETSc.PetscSectionCreate(petsclib, LibPETSc.PETSC_COMM_SELF)

LibPETSc.PetscSectionSetNumFields(petsclib, section, 2)

# Set field names
LibPETSc.PetscSectionSetFieldName(petsclib, section, 0, "velocity")
LibPETSc.PetscSectionSetFieldName(petsclib, section, 1, "pressure")

# Set chart
LibPETSc.PetscSectionSetChart(petsclib, section, 0, 10)

# Set field components: velocity has 3 components (vx, vy, vz), pressure has 1
LibPETSc.PetscSectionSetFieldComponents(petsclib, section, 0, 3)
LibPETSc.PetscSectionSetFieldComponents(petsclib, section, 1, 1)

# Set DOFs per field per point
for p in 0:9
    LibPETSc.PetscSectionSetFieldDof(petsclib, section, p, 0, 3)  # 3 velocity DOFs
    LibPETSc.PetscSectionSetFieldDof(petsclib, section, p, 1, 1)  # 1 pressure DOF
    LibPETSc.PetscSectionSetDof(petsclib, section, p, 4)          # Total: 4 DOFs
end

LibPETSc.PetscSectionSetUp(petsclib, section)

Constrained DOFs

Mark certain DOFs as constrained (e.g., for boundary conditions):

# Set chart and DOFs, then before PetscSectionSetUp:
# Set constraint DOF count
LibPETSc.PetscSectionSetConstraintDof(petsclib, section, point, num_constrained)

LibPETSc.PetscSectionSetUp(petsclib, section)

# After set-up: specify which of the point's DOFs are constrained
constrained_indices = PetscInt[0, 2]
LibPETSc.PetscSectionSetConstraintIndices(petsclib, section, point, constrained_indices)

# Storage size excluding the constrained DOFs
LibPETSc.PetscSectionGetConstrainedStorageSize(petsclib, section)

Integration with DM

Sections are commonly used with DM objects:

# Get the local (ghosted) section of a DM; the DM owns it
local_section = LibPETSc.DMGetLocalSection(petsclib, dm)

# Set a section on a DM
LibPETSc.DMSetLocalSection(petsclib, dm, section)

# Get the global section (owned DOFs only, built on demand)
global_section = LibPETSc.DMGetGlobalSection(petsclib, dm)

Common Workflows

1. FEM Discretization

# Create section for Q1 finite elements on structured grid
# - Vertices: 1 DOF each
# - Cells: 0 DOFs

section = LibPETSc.PetscSectionCreate(petsclib, comm)

LibPETSc.PetscSectionSetChart(petsclib, section, vStart, cEnd)

# Set DOFs (vStart to vEnd are vertices, vEnd to cEnd are cells)
for v in vStart:vEnd-1
    LibPETSc.PetscSectionSetDof(petsclib, section, v, 1)
end

LibPETSc.PetscSectionSetUp(petsclib, section)

2. Point Closure

Get all DOFs in the closure of a point (point + its boundary):

# Get the closure of a cell: `closure` holds 2 * npoints entries, (point, orientation) pairs
npoints, closure = LibPETSc.DMPlexGetTransitiveClosure(petsclib, dm, cell, LibPETSc.PETSC_TRUE)

# Map closure points to DOF offsets using the section
for i in 1:npoints
    p = closure[2i - 1]
    dof = LibPETSc.PetscSectionGetDof(petsclib, section, p)
    off = LibPETSc.PetscSectionGetOffset(petsclib, section, p)
    # ... DOFs of point p are off:off+dof-1 ...
end

# Hand the closure array back to PETSc
LibPETSc.DMPlexRestoreTransitiveClosure(petsclib, dm, cell, LibPETSc.PETSC_TRUE, npoints, closure)

Querying Section Properties

# Get total number of fields
num_fields = LibPETSc.PetscSectionGetNumFields(petsclib, section)

# Get field components
components = LibPETSc.PetscSectionGetFieldComponents(petsclib, section, field)

# Get field name (returns String directly)
name = LibPETSc.PetscSectionGetFieldName(petsclib, section, field)

# Get maximum DOF count across all points
max_dof = LibPETSc.PetscSectionGetMaxDof(petsclib, section)

Cloning and Permutation

# Clone a section
new_section = LibPETSc.PetscSectionClone(petsclib, section)

Function Reference

PETSc.LibPETSc.PetscSectionAddConstraintDof — Method

PetscSectionAddConstraintDof(petsclib::PetscLibType, s::PetscSection, point::PetscInt, numDof::PetscInt)

Increment the number of constrained degrees of freedom associated with a given point.

Not Collective

Input Parameters:

s - the PetscSection
point - the point
numDof - the number of additional dof which are fixed by constraints

Level: intermediate

See also: PetscSection, PetscSection, PetscSectionAddDof(), PetscSectionGetConstraintDof(), PetscSectionCreate()

External Links