DM (Domain Management)

DMAdaptInterpolator(petsclib::PetscLibType,dmc::PetscDM, dmf::PetscDM, In::PetscMat, smoother::PetscKSP, MF::PetscMat, MC::PetscMat, InAdapt::PetscMat, user::Cvoid)

External Links

• PETSc Manual: DM/DMAdaptInterpolator

DMAdaptLabel(petsclib::PetscLibType,dm::PetscDM, label::DMLabel, dmAdapt::PetscDM)

Adapt a DM based on a DMLabel with values interpreted as coarsening and refining flags. Specific implementations of DM maybe have specialized flags, but all implementations should accept flag values DM_ADAPT_DETERMINE, DM_ADAPT_KEEP, DM_ADAPT_REFINE, and, DM_ADAPT_COARSEN.

Collective

Input Parameters:

• dm - the pre-adaptation DM object
• label - label with the flags

Output Parameters:

• dmAdapt - the adapted DM object: may be NULL if an adapted DM could not be produced.

Level: intermediate

-seealso: DM, DMAdaptMetric(), DMCoarsen(), DMRefine()

External Links

• PETSc Manual: DM/DMAdaptLabel

DMAdaptMetric(petsclib::PetscLibType,dm::PetscDM, metric::PetscVec, bdLabel::DMLabel, rgLabel::DMLabel, dmAdapt::PetscDM)

Generates a mesh adapted to the specified metric field.

Input Parameters:

• dm - The DM object
• metric - The metric to which the mesh is adapted, defined vertex-wise.
• bdLabel - Label for boundary tags, which will be preserved in the output mesh. bdLabel should be NULL if there is no such label, and should be different from "boundary".
• rgLabel - Label for cell tags, which will be preserved in the output mesh. rgLabel should be NULL if there is no such label, and should be different from "regions".

Output Parameter:

• dmAdapt - Pointer to the DM object containing the adapted mesh

-seealso: DMAdaptLabel(), DMCoarsen(), DMRefine()

External Links

• PETSc Manual: DM/DMAdaptMetric

bd::PetscInt = DMAddBoundary(petsclib::PetscLibType,dm::PetscDM, type::DMBoundaryConditionType, name::String, label::DMLabel, Nv::PetscInt, values::Vector{PetscInt}, field::PetscInt, Nc::PetscInt, comps::Vector{PetscInt}, bcFunc::PetscVoidFn, bcFunc_t::PetscVoidFn, ctx::Cvoid)

Add a boundary condition, for a single field, to a model represented by a DM

Collective

Input Parameters:

• dm - The DM, with a PetscDS that matches the problem being constrained
• type - The type of condition, e.g. DM_BC_ESSENTIAL_ANALYTIC, DM_BC_ESSENTIAL_FIELD (Dirichlet), or DM_BC_NATURAL (Neumann)
• name - The BC name
• label - The label defining constrained points
• Nv - The number of DMLabel values for constrained points
• values - An array of values for constrained points
• field - The field to constrain
• Nc - The number of constrained field components (0 will constrain all components)
• comps - An array of constrained component numbers
• bcFunc - A pointwise function giving boundary values
• bcFunc_t - A pointwise function giving the time derivative of the boundary values, or NULL
• ctx - An optional user context for bcFunc

Output Parameter:

• bd - (Optional) Boundary number

Options Database Keys:

• -bc_<boundary name> <num> - Overrides the boundary ids
• -bc_<boundary name>_comp <num> - Overrides the boundary components

Level: intermediate

Notes: If the DM is of type DMPLEX and the field is of type PetscFE, then this function completes the label using DMPlexLabelComplete().

Both bcFunc and bcFunct will depend on the boundary condition type. If the type if `DMBC_ESSENTIAL`, then the calling sequence is: -vb void bcFunc(PetscInt dim, PetscReal time, const PetscReal x[], PetscInt Nc, PetscScalar bcval[]) -ve

If the type is DM_BC_ESSENTIAL_FIELD or other _FIELD value, then the calling sequence is:

-vb void bcFunc(PetscInt dim, PetscInt Nf, PetscInt NfAux, const PetscInt uOff[], const PetscInt uOffx[], const PetscScalar u[], const PetscScalar ut[], const PetscScalar ux[], const PetscInt aOff[], const PetscInt aOffx[], const PetscScalar a[], const PetscScalar at[], const PetscScalar ax[], PetscReal time, const PetscReal x[], PetscScalar bcval[]) -ve

• dim - the spatial dimension
• Nf - the number of fields
• uOff - the offset into u[] and u_t[] for each field
• uOff_x - the offset into u_x[] for each field
• u - each field evaluated at the current point
• u_t - the time derivative of each field evaluated at the current point
• u_x - the gradient of each field evaluated at the current point
• aOff - the offset into a[] and a_t[] for each auxiliary field
• aOff_x - the offset into a_x[] for each auxiliary field
• a - each auxiliary field evaluated at the current point
• a_t - the time derivative of each auxiliary field evaluated at the current point
• a_x - the gradient of auxiliary each field evaluated at the current point
• t - current time
• x - coordinates of the current point
• numConstants - number of constant parameters
• constants - constant parameters
• bcval - output values at the current point

See also:

DM, DSGetBoundary(), PetscDSAddBoundary()

External Links

• PETSc Manual: DM/DMAddBoundary

DMAddField(petsclib::PetscLibType,dm::PetscDM, label::DMLabel, disc::PetscObject)

Add a field to a DM object. A field is a function space defined by of a set of discretization points (geometric entities) and a discretization object that defines the function space associated with those points.

Logically Collective

Input Parameters:

• dm - The DM
• label - The label indicating the support of the field, or NULL for the entire mesh
• disc - The discretization object

Level: intermediate

Notes: The label already exists or will be added to the DM with DMSetLabel().

For example, a piecewise continuous pressure field can be defined by coefficients at the cell centers of a mesh and piecewise constant functions within each cell. Thus a specific function in the space is defined by the combination of a Vec containing the coefficients, a DM defining the geometry entities, a DMLabel indicating a subset of those geometric entities, and a discretization object, such as a PetscFE.

Fortran Note: Use the argument PetscObjectCast(disc) as the second argument

See also:

DM, DMSetLabel(), DMSetField(), DMGetField(), PetscFE

External Links

• PETSc Manual: DM/DMAddField

DMAddLabel(petsclib::PetscLibType,dm::PetscDM, label::DMLabel)

Add the label to this DM

Not Collective

Input Parameters:

• dm - The DM object
• label - The DMLabel

Level: developer

See also:

DM, DMLabel, DMCreateLabel(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMAddLabel

DMAppendOptionsPrefix(petsclib::PetscLibType,dm::PetscDM, prefix::String)

Appends an additional string to an already existing prefix used for searching for DM options in the options database.

Logically Collective

Input Parameters:

• dm - the DM context
• prefix - the string to append to the current prefix

Level: advanced

Note: If the DM does not currently have an options prefix then this value is used alone as the prefix as if DMSetOptionsPrefix() had been called. A hyphen (-) must NOT be given at the beginning of the prefix name. The first character of all runtime options is AUTOMATICALLY the hyphen.

See also:

DM, DMSetOptionsPrefix(), DMGetOptionsPrefix(), PetscObjectAppendOptionsPrefix(), DMSetFromOptions()

External Links

• PETSc Manual: DM/DMAppendOptionsPrefix

DMCheckInterpolator(petsclib::PetscLibType,dmf::PetscDM, In::PetscMat, MC::PetscMat, MF::PetscMat, tol::PetscReal)

External Links

• PETSc Manual: DM/DMCheckInterpolator

DMClearAuxiliaryVec(petsclib::PetscLibType,dm::PetscDM)

Destroys the auxiliary vector information and creates a new empty one

Not Collective

Input Parameter:

• dm - The DM

Level: advanced

See also:

DM, DMCopyAuxiliaryVec(), DMGetNumAuxiliaryVec(), DMGetAuxiliaryVec(), DMSetAuxiliaryVec()

External Links

• PETSc Manual: DM/DMClearAuxiliaryVec

DMClearDS(petsclib::PetscLibType,dm::PetscDM)

Remove all discrete systems from the DM

Logically Collective

Input Parameter:

• dm - The DM

Level: intermediate

See also:

DM, DMGetNumDS(), DMGetDS(), DMSetField()

External Links

• PETSc Manual: DM/DMClearDS

DMClearFields(petsclib::PetscLibType,dm::PetscDM)

Remove all fields from the DM

Logically Collective

Input Parameter:

• dm - The DM

Level: intermediate

See also:

DM, DMGetNumFields(), DMSetNumFields(), DMSetField()

External Links

• PETSc Manual: DM/DMClearFields

DMClearGlobalVectors(petsclib::PetscLibType,dm::PetscDM)

Destroys all the global vectors that have been created for DMGetGlobalVector() calls in this DM

Collective

Input Parameter:

• dm - the DM

Level: developer

-seealso: DM, DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(), DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMRestoreLocalVector() VecStrideMax(), VecStrideMin(), VecStrideNorm(), DMClearLocalVectors()

External Links

• PETSc Manual: DM/DMClearGlobalVectors

DMClearLabelStratum(petsclib::PetscLibType,dm::PetscDM, name::String, value::PetscInt)

Remove all points from a stratum from a DMLabel

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name
• value - The label value for this point

Output Parameter:

Level: beginner

See also:

DM, DMLabel, DMLabelClearStratum(), DMSetLabelValue(), DMGetStratumIS(), DMClearLabelValue()

External Links

• PETSc Manual: DM/DMClearLabelStratum

DMClearLabelValue(petsclib::PetscLibType,dm::PetscDM, name::String, point::PetscInt, value::PetscInt)

Remove a point from a DMLabel with given value

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name
• point - The mesh point
• value - The label value for this point

Level: beginner

See also:

DM, DMLabelClearValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMClearLabelValue

DMClearLocalVectors(petsclib::PetscLibType,dm::PetscDM)

Destroys all the local vectors that have been created for DMGetLocalVector() calls in this DM

Collective

Input Parameter:

• dm - the DM

Level: developer

-seealso: DM, DMCreateLocalVector(), VecDuplicate(), VecDuplicateVecs(), DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMLocalToLocalBegin(), DMLocalToLocalEnd(), DMRestoreLocalVector() VecStrideMax(), VecStrideMin(), VecStrideNorm(), DMClearGlobalVectors()

External Links

• PETSc Manual: DM/DMClearLocalVectors

DMClearNamedGlobalVectors(petsclib::PetscLibType,dm::PetscDM)

Destroys all the named global vectors that have been created with DMGetNamedGlobalVector() in this DM

Collective

Input Parameter:

• dm - the DM

Level: developer

-seealso: DM, DMGetNamedGlobalVector(), DMGetNamedLocalVector(), DMClearNamedLocalVectors()

External Links

• PETSc Manual: DM/DMClearNamedGlobalVectors

DMClearNamedLocalVectors(petsclib::PetscLibType,dm::PetscDM)

Destroys all the named local vectors that have been created with DMGetNamedLocalVector() in this DM

Collective

Input Parameter:

• dm - the DM

Level: developer

-seealso: DM, DMGetNamedGlobalVector(), DMGetNamedLocalVector(), DMClearNamedGlobalVectors()

External Links

• PETSc Manual: DM/DMClearNamedLocalVectors

DMClone(petsclib::PetscLibType,dm::PetscDM, newdm::PetscDM)

Creates a DM object with the same topology as the original.

Collective

Input Parameter:

• dm - The original DM object

Output Parameter:

• newdm - The new DM object

Level: beginner

Notes: For some DM implementations this is a shallow clone, the result of which may share (reference counted) information with its parent. For example, DMClone() applied to a DMPLEX object will result in a new DMPLEX that shares the topology with the original DMPLEX. It does not share the PetscSection of the original DM.

The clone is considered set up if the original has been set up.

Use DMConvert() for a general way to create new DM from a given DM

See also:

DM, DMDestroy(), DMCreate(), DMSetType(), DMSetLocalSection(), DMSetGlobalSection(), DMPLEX, DMConvert()

External Links

• PETSc Manual: DM/DMClone

DMCoarsen(petsclib::PetscLibType,dm::PetscDM, comm::MPI_Comm, dmc::PetscDM)

Coarsens a DM object using a standard, non

Collective

Input Parameters:

• dm - the DM object
• comm - the communicator to contain the new DM object (or MPI_COMM_NULL)

Output Parameter:

• dmc - the coarsened DM

Level: developer

See also:

DM, DMRefine(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateDomainDecomposition(), DMCoarsenHookAdd(), DMCoarsenHookRemove()

External Links

• PETSc Manual: DM/DMCoarsen

DMCoarsenHierarchy(petsclib::PetscLibType,dm::PetscDM, nlevels::PetscInt, dmc::Vector{PetscDM})

Coarsens a DM object, all levels at once

Collective

Input Parameters:

• dm - the DM object
• nlevels - the number of levels of coarsening

Output Parameter:

• dmc - the coarsened DM hierarchy

Level: developer

See also:

DM, DMCoarsen(), DMRefineHierarchy(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()

External Links

• PETSc Manual: DM/DMCoarsenHierarchy

DMCoarsenHookAdd(petsclib::PetscLibType,fine::PetscDM, coarsenhook::external, restricthook::external, ctx::Cvoid)

adds a callback to be run when restricting a nonlinear problem to the coarse grid

Logically Collective; No Fortran Support

Input Parameters:

• fine - DM on which to run a hook when restricting to a coarser level
• coarsenhook - function to run when setting up a coarser level
• restricthook - function to run to update data on coarser levels (called once per SNESSolve())
• ctx - [optional] user-defined context for provide data for the hooks (may be NULL)

Calling sequence of coarsenhook:

• fine - fine level DM
• coarse - coarse level DM to restrict problem to
• ctx - optional user-defined function context

Calling sequence of restricthook:

• fine - fine level DM
• mrestrict - matrix restricting a fine-level solution to the coarse grid, usually the transpose of the interpolation
• rscale - scaling vector for restriction
• inject - matrix restricting by injection
• coarse - coarse level DM to update
• ctx - optional user-defined function context

Level: advanced

Notes: This function is only needed if auxiliary data, attached to the DM with PetscObjectCompose(), needs to be set up or passed from the fine DM to the coarse DM.

If this function is called multiple times, the hooks will be run in the order they are added.

In order to compose with nonlinear preconditioning without duplicating storage, the hook should be implemented to extract the finest level information from its context (instead of from the SNES).

The hooks are automatically called by DMRestrict()

See also:

DM, DMCoarsenHookRemove(), DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()

External Links

• PETSc Manual: DM/DMCoarsenHookAdd

DMCoarsenHookRemove(petsclib::PetscLibType,fine::PetscDM, coarsenhook::external, restricthook::external, ctx::Cvoid)

remove a callback set with DMCoarsenHookAdd()

Logically Collective; No Fortran Support

Input Parameters:

• fine - DM on which to run a hook when restricting to a coarser level
• coarsenhook - function to run when setting up a coarser level
• restricthook - function to run to update data on coarser levels
• ctx - [optional] user-defined context for provide data for the hooks (may be NULL)

Level: advanced

Notes: This function does nothing if the coarsenhook is not in the list.

See DMCoarsenHookAdd() for the calling sequence of coarsenhook and restricthook

See also:

DM, DMCoarsenHookAdd(), DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()

External Links

• PETSc Manual: DM/DMCoarsenHookRemove

equal::PetscBool = DMCompareLabels(petsclib::PetscLibType,dm0::PetscDM, dm1::PetscDM, message::String)

Compare labels between two DM objects

Collective; No Fortran Support

Input Parameters:

• dm0 - First DM object
• dm1 - Second DM object

Output Parameters:

• equal - (Optional) Flag whether labels of dm0 and dm1 are the same
• message - (Optional) Message describing the difference, or NULL if there is no difference

Level: intermediate

Notes: The output flag equal will be the same on all processes.

If equal is passed as NULL and difference is found, an error is thrown on all processes.

Make sure to pass equal is NULL on all processes or none of them.

The output message is set independently on each rank.

message must be freed with PetscFree()

If message is passed as NULL and a difference is found, the difference description is printed to stderr in synchronized manner.

Make sure to pass message as NULL on all processes or no processes.

Labels are matched by name. If the number of labels and their names are equal, DMLabelCompare() is used to compare each pair of labels with the same name.

Developer Note: Cannot automatically generate the Fortran stub because message must be freed with PetscFree()

See also:

DM, DMLabel, DMAddLabel(), DMCopyLabelsMode, DMLabelCompare()

External Links

• PETSc Manual: DM/DMCompareLabels

DMComputeError(petsclib::PetscLibType,dm::PetscDM, sol::PetscVec, errors::Vector{PetscReal}, errorVec::PetscVec)

Computes the error assuming the user has provided the exact solution functions

Collective

Input Parameters:

• dm - The DM
• sol - The solution vector

Input/Output Parameter:

• errors - An array of length Nf, the number of fields, or NULL for no output; on output

contains the error in each field

Output Parameter:

• errorVec - A vector to hold the cellwise error (may be NULL)

Level: developer

Note: The exact solutions come from the PetscDS object, and the time comes from DMGetOutputSequenceNumber().

See also:

DM, DMMonitorSet(), DMGetRegionNumDS(), PetscDSGetExactSolution(), DMGetOutputSequenceNumber()

External Links

• PETSc Manual: DM/DMComputeError

DMComputeExactSolution(petsclib::PetscLibType,dm::PetscDM, time::PetscReal, u::PetscVec, u_t::PetscVec)

Compute the exact solution for a given DM, using the PetscDS information.

Collective

Input Parameters:

• dm - The DM
• time - The time

Output Parameters:

• u - The vector will be filled with exact solution values, or NULL
• u_t - The vector will be filled with the time derivative of exact solution values, or NULL

Level: developer

Note: The user must call PetscDSSetExactSolution() before using this routine

See also:

DM, PetscDSSetExactSolution()

External Links

• PETSc Manual: DM/DMComputeExactSolution

DMComputeVariableBounds(petsclib::PetscLibType,dm::PetscDM, xl::PetscVec, xu::PetscVec)

compute variable bounds used by SNESVI.

Logically Collective

Input Parameter:

• dm - the DM object

Output Parameters:

• xl - lower bound
• xu - upper bound

Level: advanced

Note: This is generally not called by users. It calls the function provided by the user with DMSetVariableBounds()

See also:

DM, DMHasVariableBounds(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMGetApplicationContext()

External Links

• PETSc Manual: DM/DMComputeVariableBounds

DMConvert(petsclib::PetscLibType,dm::PetscDM, newtype::DMType, M::PetscDM)

Converts a DM to another DM, either of the same or different type.

Collective

Input Parameters:

• dm - the DM
• newtype - new DM type (use "same" for the same type)

Output Parameter:

• M - pointer to new DM

Level: intermediate

Note: Cannot be used to convert a sequential DM to a parallel or a parallel to sequential, the MPI communicator of the generated DM is always the same as the communicator of the input DM.

See also:

DM, DMSetType(), DMCreate(), DMClone()

External Links

• PETSc Manual: DM/DMConvert

DMCopyAuxiliaryVec(petsclib::PetscLibType,dm::PetscDM, dmNew::PetscDM)

Copy the auxiliary vector data on a DM to a new DM

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• dmNew - The new DM, now with the same auxiliary data

Level: advanced

Note: This is a shallow copy of the auxiliary vectors

See also:

DM, DMClearAuxiliaryVec(), DMGetNumAuxiliaryVec(), DMGetAuxiliaryVec(), DMSetAuxiliaryVec()

External Links

• PETSc Manual: DM/DMCopyAuxiliaryVec

DMCopyDMKSP(petsclib::PetscLibType,dmsrc::PetscDM, dmdest::PetscDM)

copies a DM DMKSP context to a new DM

Logically Collective

Input Parameters:

• dmsrc - DM to obtain context from
• dmdest - DM to add context to

Level: developer

-seealso: , DMKSP, DM, KSP, DMGetDMKSP(), KSPSetDM()

External Links

• PETSc Manual: Ksp/DMCopyDMKSP

DMCopyDMSNES(petsclib::PetscLibType,dmsrc::PetscDM, dmdest::PetscDM)

copies a DMSNES context to a new DM

Logically Collective

Input Parameters:

• dmsrc - DM to obtain context from
• dmdest - DM to add context to

Level: developer

-seealso: , DMSNES, DMGetDMSNES(), SNESSetDM()

External Links

• PETSc Manual: Snes/DMCopyDMSNES

DMCopyDS(petsclib::PetscLibType,dm::PetscDM, minDegree::PetscInt, maxDegree::PetscInt, newdm::PetscDM)

Copy the discrete systems for the DM into another DM

Collective

Input Parameters:

• dm - The DM
• minDegree - Minimum degree for a discretization, or PETSC_DETERMINE for no limit
• maxDegree - Maximum degree for a discretization, or PETSC_DETERMINE for no limit

Output Parameter:

• newdm - The DM

Level: advanced

See also:

DM, DMCopyFields(), DMAddField(), DMGetDS(), DMGetCellDS(), DMGetRegionDS(), DMSetRegionDS()

External Links

• PETSc Manual: DM/DMCopyDS

DMCopyDisc(petsclib::PetscLibType,dm::PetscDM, newdm::PetscDM)

Copy the fields and discrete systems for the DM into another DM

Collective

Input Parameter:

• dm - The DM

Output Parameter:

• newdm - The DM

Level: advanced

Developer Note: Really ugly name, nothing in PETSc is called a Disc plus it is an ugly abbreviation

See also:

DM, DMCopyFields(), DMCopyDS()

External Links

• PETSc Manual: DM/DMCopyDisc

DMCopyFields(petsclib::PetscLibType,dm::PetscDM, minDegree::PetscInt, maxDegree::PetscInt, newdm::PetscDM)

Copy the discretizations for the DM into another DM

Collective

Input Parameters:

• dm - The DM
• minDegree - Minimum degree for a discretization, or PETSC_DETERMINE for no limit
• maxDegree - Maximum degree for a discretization, or PETSC_DETERMINE for no limit

Output Parameter:

• newdm - The DM

Level: advanced

See also:

DM, DMGetField(), DMSetField(), DMAddField(), DMCopyDS(), DMGetDS(), DMGetCellDS()

External Links

• PETSc Manual: DM/DMCopyFields

DMCopyLabels(petsclib::PetscLibType,dmA::PetscDM, dmB::PetscDM, mode::PetscCopyMode, all::PetscBool, emode::DMCopyLabelsMode)

Copy labels from one DM mesh to another DM with a superset of the points

Collective

Input Parameters:

• dmA - The DM object with initial labels
• dmB - The DM object to which labels are copied
• mode - Copy labels by pointers (PETSC_OWN_POINTER) or duplicate them (PETSC_COPY_VALUES)
• all - Copy all labels including "depth", "dim", and "celltype" (PETSC_TRUE) which are otherwise ignored (PETSC_FALSE)
• emode - How to behave when a DMLabel in the source and destination DMs with the same name is encountered (see DMCopyLabelsMode)

Level: intermediate

Note: This is typically used when interpolating or otherwise adding to a mesh, or testing.

See also:

DM, DMLabel, DMAddLabel(), DMCopyLabelsMode

External Links

• PETSc Manual: DM/DMCopyLabels

DMCopyTransform(petsclib::PetscLibType,dm::PetscDM, newdm::PetscDM)

External Links

• PETSc Manual: DM/DMCopyTransform

dm::PetscDM = DMCreate(petsclib::PetscLibType,comm::MPI_Comm)

Creates an empty DM object. DMs are the abstract objects in PETSc that mediate between meshes and discretizations and the algebraic solvers, time integrators, and optimization algorithms in PETSc.

Collective

Input Parameter:

• comm - The communicator for the DM object

Output Parameter:

• dm - The DM object

Level: beginner

Notes: See DMType for a brief summary of available DM.

The type must then be set with DMSetType(). If you never call DMSetType() it will generate an error when you try to use the dm.

DM is an orphan initialism or orphan acronym, the letters have no meaning and never did.

See also:

DM, DMSetType(), DMType, DMDACreate(), DMDA, DMSLICED, DMCOMPOSITE, DMPLEX, DMMOAB, DMNETWORK

External Links

• PETSc Manual: DM/DMCreate

coloring::ISColoring = DMCreateColoring(petsclib::PetscLibType,dm::PetscDM, ctype::ISColoringType)

Gets coloring of a graph associated with the DM. Often the graph represents the operator matrix associated with the discretization of a PDE on the DM.

Collective

Input Parameters:

• dm - the DM object
• ctype - IS_COLORING_LOCAL or IS_COLORING_GLOBAL

Output Parameter:

• coloring - the coloring

Level: developer

Notes: Coloring of matrices can also be computed directly from the sparse matrix nonzero structure via the MatColoring object or from the mesh from which the matrix comes from (what this function provides). In general using the mesh produces a more optimal coloring (fewer colors).

This produces a coloring with the distance of 2, see MatSetColoringDistance() which can be used for efficiently computing Jacobians with MatFDColoringCreate() For DMDA in three dimensions with periodic boundary conditions the number of grid points in each dimension must be divisible by 2*stencil_width + 1, otherwise an error will be generated.

See also:

DM, ISColoring, DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateMatrix(), DMCreateMassMatrix(), DMSetMatType(), MatColoring, MatFDColoringCreate()

External Links

• PETSc Manual: DM/DMCreateColoring

DMCreateDS(petsclib::PetscLibType,dm::PetscDM)

Create the discrete systems for the DM based upon the fields added to the DM

Collective

Input Parameter:

• dm - The DM

Options Database Key:

• -dm_petscds_view - View all the PetscDS objects in this DM

Level: intermediate

Developer Note: The name of this function is wrong. Create functions always return the created object as one of the arguments.

See also:

DM, DMSetField, DMAddField(), DMGetDS(), DMGetCellDS(), DMGetRegionDS(), DMSetRegionDS()

External Links

• PETSc Manual: DM/DMCreateDS

n::PetscInt,namelist::Cchar,innerislist::Vector{IS},outerislist::Vector{IS},dmlist::Vector{PetscDM} = DMCreateDomainDecomposition(petsclib::PetscLibType,dm::PetscDM)

Returns lists of IS objects defining a decomposition of a problem into subproblems corresponding to restrictions to pairs of nested subdomains.

Not Collective

Input Parameter:

• dm - the DM object

Output Parameters:

• n - The number of subproblems in the domain decomposition (or NULL if not requested), also the length of the four arrays below
• namelist - The name for each subdomain (or NULL if not requested)
• innerislist - The global indices for each inner subdomain (or NULL, if not requested)
• outerislist - The global indices for each outer subdomain (or NULL, if not requested)
• dmlist - The DMs for each subdomain subproblem (or NULL, if not requested; if NULL is returned, no DMs are defined)

Level: intermediate

Notes: Each IS contains the global indices of the dofs of the corresponding subdomains with in the dofs of the original DM. The inner subdomains conceptually define a nonoverlapping covering, while outer subdomains can overlap.

The optional list of DMs define a DM for each subproblem.

The user is responsible for freeing all requested arrays. In particular, every entry of namelist should be freed with PetscFree(), every entry of innerislist and outerislist should be destroyed with ISDestroy(), every entry of dmlist should be destroyed with DMDestroy(), and all of the arrays should be freed with PetscFree().

Developer Notes: The dmlist is for the inner subdomains or the outer subdomains or all subdomains?

The names are inconsistent, the hooks use DMSubDomainHook which is nothing like DMCreateDomainDecomposition() while DMRefineHook is used for DMRefine().

See also:

DM, DMCreateFieldDecomposition(), DMDestroy(), DMCreateDomainDecompositionScatters(), DMView(), DMCreateInterpolation(), DMSubDomainHookAdd(), DMSubDomainHookRemove(),DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMRefine(), DMCoarsen()

External Links

• PETSc Manual: DM/DMCreateDomainDecomposition

iscat::Vector{VecScatter},oscat::Vector{VecScatter},gscat::Vector{VecScatter} = DMCreateDomainDecompositionScatters(petsclib::PetscLibType,dm::PetscDM, n::PetscInt, subdms::PetscDM)

Returns scatters to the subdomain vectors from the global vector for subdomains created with DMCreateDomainDecomposition()

Not Collective

Input Parameters:

• dm - the DM object
• n - the number of subdomains
• subdms - the local subdomains

Output Parameters:

• iscat - scatter from global vector to nonoverlapping global vector entries on subdomain
• oscat - scatter from global vector to overlapping global vector entries on subdomain
• gscat - scatter from global vector to local vector on subdomain (fills in ghosts)

Level: developer

Note: This is an alternative to the iis and ois arguments in DMCreateDomainDecomposition() that allow for the solution of general nonlinear problems with overlapping subdomain methods. While merely having index sets that enable subsets of the residual equations to be created is fine for linear problems, nonlinear problems require local assembly of solution and residual data.

Developer Note: Can the subdms input be anything or are they exactly the DM obtained from DMCreateDomainDecomposition()?

See also:

DM, DMCreateDomainDecomposition(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMCreateFieldIS()

External Links

• PETSc Manual: DM/DMCreateDomainDecompositionScatters

fem::PetscFE = DMCreateFEDefault(petsclib::PetscLibType,dm::PetscDM, Nc::PetscInt, prefix::String, qorder::PetscInt)

Create a PetscFE based on the celltype for the mesh

Not Collective

Input Parameters:

• dm - The DM
• Nc - The number of components for the field
• prefix - The options prefix for the output PetscFE, or NULL
• qorder - The quadrature order or PETSC_DETERMINE to use PetscSpace polynomial degree

Output Parameter:

• fem - The PetscFE

Level: intermediate

Note: This is a convenience method that just calls PetscFECreateByCell() underneath.

See also:

DM, PetscFECreateByCell(), DMAddField(), DMCreateDS(), DMGetCellDS(), DMGetRegionDS()

External Links

• PETSc Manual: DM/DMCreateFEDefault

len::PetscInt,namelist::Cchar,islist::Vector{IS},dmlist::Vector{PetscDM} = DMCreateFieldDecomposition(petsclib::PetscLibType,dm::PetscDM)

Returns a list of IS objects defining a decomposition of a problem into subproblems corresponding to different fields.

Not Collective; No Fortran Support

Input Parameter:

• dm - the DM object

Output Parameters:

• len - The number of fields (or NULL if not requested)
• namelist - The name for each field (or NULL if not requested)
• islist - The global indices for each field (or NULL if not requested)
• dmlist - The DMs for each field subproblem (or NULL, if not requested; if NULL is returned, no DMs are defined)

Level: intermediate

Notes: Each IS contains the global indices of the dofs of the corresponding field, defined by DMAddField(). The optional list of DMs define the DM for each subproblem.

The same as DMCreateFieldIS() but also returns a DM for each field.

The user is responsible for freeing all requested arrays. In particular, every entry of namelist should be freed with PetscFree(), every entry of islist should be destroyed with ISDestroy(), every entry of dmlist should be destroyed with DMDestroy(), and all of the arrays should be freed with PetscFree().

Fortran Notes: Use the declarations -vb character(80), pointer :: namelist(:) IS, pointer :: islist(:) DM, pointer :: dmlist(:) -ve

namelist must be provided, islist may be PETSC_NULL_IS_POINTER and dmlist may be PETSC_NULL_DM_POINTER

Use DMDestroyFieldDecomposition() to free the returned objects

Developer Notes: It is not clear why this function and DMCreateFieldIS() exist. Having two seems redundant and confusing.

Unlike DMRefine(), DMCoarsen(), and DMCreateDomainDecomposition() this provides no mechanism to provide hooks that are called after the decomposition is computed.

See also:

DM, DMAddField(), DMCreateFieldIS(), DMCreateSubDM(), DMCreateDomainDecomposition(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMRefine(), DMCoarsen()

External Links

• PETSc Manual: DM/DMCreateFieldDecomposition

numFields::PetscInt,fieldNames::Cchar,fields::Vector{IS} = DMCreateFieldIS(petsclib::PetscLibType,dm::PetscDM)

Creates a set of IS objects with the global indices of dofs for each field defined with DMAddField()

Not Collective; No Fortran Support

Input Parameter:

• dm - the DM object

Output Parameters:

• numFields - The number of fields (or NULL if not requested)
• fieldNames - The name of each field (or NULL if not requested)
• fields - The global indices for each field (or NULL if not requested)

Level: intermediate

Note: The user is responsible for freeing all requested arrays. In particular, every entry of fieldNames should be freed with PetscFree(), every entry of fields should be destroyed with ISDestroy(), and both arrays should be freed with PetscFree().

Developer Note: It is not clear why both this function and DMCreateFieldDecomposition() exist. Having two seems redundant and confusing. This function should likely be removed.

See also:

DM, DMAddField(), DMGetField(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateFieldDecomposition()

External Links

• PETSc Manual: DM/DMCreateFieldIS

vec::PetscVec = DMCreateGlobalVector(petsclib::PetscLibType,dm::PetscDM)

Creates a global vector from a DM object. A global vector is a parallel vector that has no duplicate values shared between MPI ranks, that is it has no ghost locations.

Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• vec - the global vector

Level: beginner

See also:

DM, Vec, DMCreateLocalVector(), DMGetGlobalVector(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMGlobalToLocalBegin(), DMGlobalToLocalEnd()

External Links

• PETSc Manual: DM/DMCreateGlobalVector

mat::PetscMat = DMCreateGradientMatrix(petsclib::PetscLibType,dmc::PetscDM, dmf::PetscDM)

Gets the gradient matrix between two DM objects Collective

Input Parameters:

• dmc - the target DM object
• dmf - the source DM object, can be NULL

Output Parameter:

• mat - the gradient matrix

Level: developer

Notes: For DMPLEX the finite element model for the DM must have been already provided.

See also:

DM, DMCreateMassMatrix(), DMCreateMassMatrixLumped(), DMCreateMatrix(), DMRefine(), DMCoarsen(), DMCreateRestriction(), DMCreateInterpolation(), DMCreateInjection()

External Links

• PETSc Manual: DM/DMCreateGradientMatrix

mat::PetscMat = DMCreateInjection(petsclib::PetscLibType,dac::PetscDM, daf::PetscDM)

Gets injection matrix between two DM objects.

Collective

Input Parameters:

• dac - the DM object
• daf - the second, finer DM object

Output Parameter:

• mat - the injection

Level: developer

Notes: This is an operator that applied to a vector obtained with DMCreateGlobalVector() on the fine grid maps the values to a vector on the vector on the coarse DM by simply selecting the values on the coarse grid points. This compares to the operator obtained by DMCreateRestriction() or the transpose of the operator obtained by DMCreateInterpolation() that uses a "local weighted average" of the values around the coarse grid point as the coarse grid value.

For DMDA objects this only works for "uniform refinement", that is the refined mesh was obtained DMRefine() or the coarse mesh was obtained by DMCoarsen(). The coordinates set into the DMDA are completely ignored in computing the injection.

See also:

DM, DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMCreateInterpolation(), DMCreateRestriction(), MatRestrict(), MatInterpolate()

External Links

• PETSc Manual: DM/DMCreateInjection

mat::PetscMat,vec::PetscVec = DMCreateInterpolation(petsclib::PetscLibType,dmc::PetscDM, dmf::PetscDM)

Gets the interpolation matrix between two DM objects. The resulting matrix map degrees of freedom in the vector obtained by DMCreateGlobalVector() on the coarse DM to similar vectors on the fine grid DM.

Collective

Input Parameters:

• dmc - the DM object
• dmf - the second, finer DM object

Output Parameters:

• mat - the interpolation
• vec - the scaling (optional, pass NULL if not needed), see DMCreateInterpolationScale()

Level: developer

Notes: For DMDA objects this only works for "uniform refinement", that is the refined mesh was obtained DMRefine() or the coarse mesh was obtained by DMCoarsen(). The coordinates set into the DMDA are completely ignored in computing the interpolation.

For DMDA objects you can use this interpolation (more precisely the interpolation from the DMGetCoordinateDM()) to interpolate the mesh coordinate vectors EXCEPT in the periodic case where it does not make sense since the coordinate vectors are not periodic.

See also:

DM, DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMRefine(), DMCoarsen(), DMCreateRestriction(), DMCreateInterpolationScale()

External Links

• PETSc Manual: DM/DMCreateInterpolation

scale::PetscVec = DMCreateInterpolationScale(petsclib::PetscLibType,dac::PetscDM, daf::PetscDM, mat::PetscMat)

Forms L = 1/(R*1) where 1 is the vector of all ones, and R is the transpose of the interpolation between the DM.

Input Parameters:

• dac - DM that defines a coarse mesh
• daf - DM that defines a fine mesh
• mat - the restriction (or interpolation operator) from fine to coarse

Output Parameter:

• scale - the scaled vector

Level: advanced

Note: xcoarse = diag(L)Rxfine preserves scale and is thus suitable for state (versus residual) restriction. In other words xcoarse is the coarse representation of xfine.

Developer Note: If the fine-scale DMDA has the -dmbindbelow option set to true, then DMCreateInterpolationScale() calls MatSetBindingPropagates() on the restriction/interpolation operator to set the bindingpropagates flag to true.

See also:

DM, MatRestrict(), MatInterpolate(), DMCreateInterpolation(), DMCreateRestriction(), DMCreateGlobalVector()

External Links

• PETSc Manual: DM/DMCreateInterpolationScale

DMCreateLabel(petsclib::PetscLibType,dm::PetscDM, name::String)

Create a label of the given name if it does not already exist in the DM

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name

Level: intermediate

See also:

DM, DMLabelCreate(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMCreateLabel

DMCreateLabelAtIndex(petsclib::PetscLibType,dm::PetscDM, l::PetscInt, name::String)

Create a label of the given name at the given index. If it already exists in the DM, move it to this index.

Not Collective

Input Parameters:

• dm - The DM object
• l - The index for the label
• name - The label name

Level: intermediate

See also:

DM, DMCreateLabel(), DMLabelCreate(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMCreateLabelAtIndex

vec::PetscVec = DMCreateLocalVector(petsclib::PetscLibType,dm::PetscDM)

Creates a local vector from a DM object.

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• vec - the local vector

Level: beginner

Note: A local vector usually has ghost locations that contain values that are owned by different MPI ranks. A global vector has no ghost locations.

See also:

DM, Vec, DMCreateGlobalVector(), DMGetLocalVector(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix() DMGlobalToLocalBegin(), DMGlobalToLocalEnd()

External Links

• PETSc Manual: DM/DMCreateLocalVector

mat::PetscMat = DMCreateMassMatrix(petsclib::PetscLibType,dmc::PetscDM, dmf::PetscDM)

Gets the mass matrix between two DM objects Collective

Input Parameters:

• dmc - the target DM object
• dmf - the source DM object, can be NULL

Output Parameter:

• mat - the mass matrix

Level: developer

See also:

DM, DMCreateMassMatrixLumped(), DMCreateMatrix(), DMRefine(), DMCoarsen(), DMCreateRestriction(), DMCreateInterpolation(), DMCreateInjection()

External Links

• PETSc Manual: DM/DMCreateMassMatrix

llm::PetscVec,lm::PetscVec = DMCreateMassMatrixLumped(petsclib::PetscLibType,dm::PetscDM)

Gets the lumped mass matrix for a given DM

Collective

Input Parameter:

• dm - the DM object

Output Parameters:

• llm - the local lumped mass matrix, which is a diagonal matrix, represented as a vector
• lm - the global lumped mass matrix, which is a diagonal matrix, represented as a vector

Level: developer

Note: See DMCreateMassMatrix() for how to create the non-lumped version of the mass matrix.

See also:

DM, DMCreateMassMatrix(), DMCreateMatrix(), DMRefine(), DMCoarsen(), DMCreateRestriction(), DMCreateInterpolation(), DMCreateInjection()

External Links

• PETSc Manual: DM/DMCreateMassMatrixLumped

mat::PetscMat = DMCreateMatrix(petsclib::PetscLibType,dm::PetscDM)

Gets an empty matrix for a DM that is most commonly used to store the Jacobian of a discrete PDE operator.

Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• mat - the empty Jacobian

Options Database Key:

• -dm_preallocate_only - Only preallocate the matrix for DMCreateMatrix() and DMCreateMassMatrix(), but do not fill it with zeros

Level: beginner

Notes: This properly preallocates the number of nonzeros in the sparse matrix so you do not need to do it yourself.

By default it also sets the nonzero structure and puts in the zero entries. To prevent setting the nonzero pattern call DMSetMatrixPreallocateOnly()

For DMDA, when you call MatView() on this matrix it is displayed using the global natural ordering, NOT in the ordering used internally by PETSc.

For DMDA, in general it is easiest to use MatSetValuesStencil() or MatSetValuesLocal() to put values into the matrix because MatSetValues() requires the indices for the global numbering for the DMDA which is complic`ated to compute

See also:

DM, DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMSetMatType(), DMCreateMassMatrix()

External Links

• PETSc Manual: DM/DMCreateMatrix

mat::PetscMat = DMCreateRestriction(petsclib::PetscLibType,dmc::PetscDM, dmf::PetscDM)

Gets restriction matrix between two DM objects. The resulting matrix map degrees of freedom in the vector obtained by DMCreateGlobalVector() on the fine DM to similar vectors on the coarse grid DM.

Collective

Input Parameters:

• dmc - the DM object
• dmf - the second, finer DM object

Output Parameter:

• mat - the restriction

Level: developer

Note: This only works for DMSTAG. For many situations either the transpose of the operator obtained with DMCreateInterpolation() or that matrix multiplied by the vector obtained with DMCreateInterpolationScale() provides the desired object.

See also:

DM, DMRestrict(), DMInterpolate(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMRefine(), DMCoarsen(), DMCreateInterpolation()

External Links

• PETSc Manual: DM/DMCreateRestriction

perm::IS,blockStarts::PetscBT = DMCreateSectionPermutation(petsclib::PetscLibType,dm::PetscDM)

Create a permutation of the PetscSection chart and optionally a block structure.

Input Parameter:

• dm - The DM

Output Parameters:

• perm - A permutation of the mesh points in the chart
• blockStarts - A high bit is set for the point that begins every block, or NULL for default blocking

Level: developer

See also:

DM, PetscSection, DMGetLocalSection(), DMGetGlobalSection()

External Links

• PETSc Manual: DM/DMCreateSectionPermutation

DMCreateSectionSF(petsclib::PetscLibType,dm::PetscDM, locSection::PetscSection, globalSection::PetscSection)

Create the PetscSF encoding the parallel dof overlap for the DM based upon the PetscSections describing the data layout.

Input Parameters:

• dm - The DM
• localSection - PetscSection describing the local data layout
• globalSection - PetscSection describing the global data layout

Level: developer

Note: One usually uses DMGetSectionSF() to obtain the PetscSF

Developer Note: Since this routine has for arguments the two sections from the DM and puts the resulting PetscSF directly into the DM, perhaps this function should not take the local and global sections as input and should just obtain them from the DM? Plus PETSc creation functions return the thing they create, this returns nothing

See also:

DM, DMGetSectionSF(), DMSetSectionSF(), DMGetLocalSection(), DMGetGlobalSection()

External Links

• PETSc Manual: DM/DMCreateSectionSF

is::IS,subdm::PetscDM = DMCreateSectionSubDM(petsclib::PetscLibType,dm::PetscDM, numFields::PetscInt, fields::Vector{PetscInt}, numComps::Vector{PetscInt}, comps::Vector{PetscInt})

Returns an IS and subDM containing a PetscSection that encapsulates a subproblem defined by a subset of the fields in a PetscSection in the DM.

Not Collective

Input Parameters:

• dm - The DM object
• numFields - The number of fields to incorporate into subdm
• fields - The field numbers of the selected fields
• numComps - The number of components from each field to incorporate into subdm, or PETSC_DECIDE for all components
• comps - The component numbers of the selected fields (omitted for PTESC_DECIDE fields)

Output Parameters:

• is - The global indices for the subproblem or NULL
• subdm - The DM for the subproblem, which must already have be cloned from dm or NULL

Level: intermediate

-seealso: DMCreateSubDM(), DMGetLocalSection(), DMPlexSetMigrationSF(), DMView()

External Links

• PETSc Manual: DM/DMCreateSectionSubDM

is::Vector{IS},superdm::PetscDM = DMCreateSectionSuperDM(petsclib::PetscLibType,dms::Vector{PetscDM}, len::PetscInt)

Returns an arrays of IS and a DM containing a PetscSection that encapsulates a superproblem defined by the array of DM and their PetscSection

Not Collective

Input Parameters:

• dms - The DM objects, the must all have the same topology; for example obtained with DMClone()
• len - The number of DM in dms

Output Parameters:

• is - The global indices for the subproblem, or NULL
• superdm - The DM for the superproblem, which must already have be cloned and contain the same topology as the dms

Level: intermediate

-seealso: DMCreateSuperDM(), DMGetLocalSection(), DMPlexSetMigrationSF(), DMView()

External Links

• PETSc Manual: DM/DMCreateSectionSuperDM

is::IS,subdm::PetscDM = DMCreateSubDM(petsclib::PetscLibType,dm::PetscDM, numFields::PetscInt, fields::Vector{PetscInt})

Returns an IS and DM encapsulating a subproblem defined by the fields passed in. The fields are defined by DMCreateFieldIS().

Not collective

Input Parameters:

• dm - The DM object
• numFields - The number of fields to select
• fields - The field numbers of the selected fields

Output Parameters:

• is - The global indices for all the degrees of freedom in the new sub DM, use NULL if not needed
• subdm - The DM for the subproblem, use NULL if not needed

Level: intermediate

Note: You need to call DMPlexSetMigrationSF() on the original DM if you want the Global-To-Natural map to be automatically constructed

See also:

DM, DMCreateFieldIS(), DMCreateFieldDecomposition(), DMAddField(), DMCreateSuperDM(), IS, VecISCopy(), DMPlexSetMigrationSF(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix()

External Links

• PETSc Manual: DM/DMCreateSubDM

is::Vector{IS},superdm::PetscDM = DMCreateSuperDM(petsclib::PetscLibType,dms::Vector{PetscDM}, n::PetscInt)

Returns an arrays of IS and a single DM encapsulating a superproblem defined by multiple DMs passed in.

Not collective

Input Parameters:

• dms - The DM objects
• n - The number of DMs

Output Parameters:

• is - The global indices for each of subproblem within the super DM, or NULL, its length is n
• superdm - The DM for the superproblem

Level: intermediate

Note: You need to call DMPlexSetMigrationSF() on the original DM if you want the Global-To-Natural map to be automatically constructed

See also:

DM, DMCreateSubDM(), DMPlexSetMigrationSF(), DMDestroy(), DMView(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMCreateFieldIS(), DMCreateDomainDecomposition()

External Links

• PETSc Manual: DM/DMCreateSuperDM

DMDestroy(petsclib::PetscLibType,dm::PetscDM)

Destroys a DM.

Collective

Input Parameter:

• dm - the DM object to destroy

Level: developer

See also:

DM, DMCreate(), DMType, DMSetType(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix()

External Links

• PETSc Manual: DM/DMDestroy

DMDestroyVI(petsclib::PetscLibType,dm::PetscDM)

External Links

• PETSc Manual: Snes/DMDestroyVI

DMExtrude(petsclib::PetscLibType,dm::PetscDM, layers::PetscInt, dme::PetscDM)

Extrude a DM object from a surface

Collective

Input Parameters:

• dm - the DM object
• layers - the number of extruded cell layers

Output Parameter:

• dme - the extruded DM, or NULL

Level: developer

Note: If no extrusion was done, the return value is NULL

See also:

DM, DMRefine(), DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector()

External Links

• PETSc Manual: DM/DMExtrude

DMFinalizePackage(petsclib::PetscLibType)

This function finalizes everything in the DM package. It is called from PetscFinalize().

Level: developer

-seealso: PetscInitialize()

External Links

• PETSc Manual: DM/DMFinalizePackage

num::PetscInt = DMFindRegionNum(petsclib::PetscLibType,dm::PetscDM, ds::PetscDS)

Find the region number for a given PetscDS, or

Not Collective

Input Parameters:

• dm - The DM
• ds - The PetscDS defined on the given region

Output Parameter:

• num - The region number, in [0, Nds), or -1 if not found

Level: advanced

See also:

DM, DMGetRegionNumDS(), DMGetRegionDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()

External Links

• PETSc Manual: DM/DMFindRegionNum

DMGenerateRegister(petsclib::PetscLibType,sname::String, fnc::external, rfnc::external, alfnc::external, dim::PetscInt)

Adds a grid generator to DM

Not Collective, No Fortran Support

Input Parameters:

• sname - name of a new user-defined grid generator
• fnc - generator function
• rfnc - refinement function
• alfnc - adapt by label function
• dim - dimension of boundary of domain

-seealso: DM, DMGenerateRegisterAll(), DMPlexGenerate(), DMGenerateRegisterDestroy()

External Links

• PETSc Manual: DM/DMGenerateRegister

DMGenerateRegisterAll(petsclib::PetscLibType)

Registers all of the mesh generation methods in the DM package.

Not Collective

Level: advanced

-seealso: DM, DMGenerateRegisterDestroy()

External Links

• PETSc Manual: DM/DMGenerateRegisterAll

DMGenerateRegisterDestroy(petsclib::PetscLibType)

External Links

• PETSc Manual: DM/DMGenerateRegisterDestroy

DMGeomModelRegister(petsclib::PetscLibType,sname::String, fnc::external)

Adds a geometry model to DM

Not Collective, No Fortran Support

Input Parameters:

• sname - name of a new user-defined geometry model
• fnc - geometry model function

-seealso: DM, DMGeomModelRegisterAll(), DMPlexGeomModel(), DMGeomModelRegisterDestroy()

External Links

• PETSc Manual: DM/DMGeomModelRegister

DMGeomModelRegisterAll(petsclib::PetscLibType)

Registers all of the geometry model methods in the DM package.

Not Collective

Level: advanced

-seealso: DM, DMGeomModelRegisterDestroy()

External Links

• PETSc Manual: DM/DMGeomModelRegisterAll

DMGeomModelRegisterDestroy(petsclib::PetscLibType)

External Links

• PETSc Manual: DM/DMGeomModelRegisterDestroy

useCone::PetscBool,useClosure::PetscBool = DMGetAdjacency(petsclib::PetscLibType,dm::PetscDM, f::PetscInt)

Returns the flags for determining variable influence

Not Collective

Input Parameters:

• dm - The DM object
• f - The field number, or PETSC_DEFAULT for the default adjacency

Output Parameters:

• useCone - Flag for variable influence starting with the cone operation
• useClosure - Flag for variable influence using transitive closure

Level: developer

Notes: -v FEM: Two points p and q are adjacent if q in closure(star(p)), useCone = PETSCFALSE, useClosure = PETSCTRUE FVM: Two points p and q are adjacent if q in support(p+cone(p)), useCone = PETSCTRUE, useClosure = PETSCFALSE FVM++: Two points p and q are adjacent if q in star(closure(p)), useCone = PETSCTRUE, useClosure = PETSCTRUE -ve Further explanation can be found in the User's Manual Section on the Influence of Variables on One Another.

See also:

DM, DMSetAdjacency(), DMGetField(), DMSetField()

External Links

• PETSc Manual: DM/DMGetAdjacency

DMGetApplicationContext(petsclib::PetscLibType,dm::PetscDM, ctx::PeCtx)

Gets a user context from a DM object provided with DMSetApplicationContext()

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• ctx - a pointer to the user context

Level: intermediate

Note: A user context is a way to pass problem specific information that is accessible whenever the DM is available

Fortran Notes: This only works when the context is a Fortran derived type (it cannot be a PetscObject) and you must write a Fortran interface definition for this function that tells the Fortran compiler the derived data type that is returned as the ctx argument. For example, -vb Interface DMGetApplicationContext Subroutine DMGetApplicationContext(dm,ctx,ierr) #include <petsc/finclude/petscdm.h> use petscdm DM dm type(tUsertype), pointer :: ctx PetscErrorCode ierr End Subroutine End Interface DMGetApplicationContext -ve

The prototype for ctx must be -vb type(tUsertype), pointer :: ctx -ve

See also:

DM, DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix()

External Links

• PETSc Manual: DM/DMGetApplicationContext

values::Vector{PetscInt},parts::Vector{PetscInt} = DMGetAuxiliaryLabels(petsclib::PetscLibType,dm::PetscDM, labels::Vector{DMLabel})

Get the labels, values, and parts for all auxiliary vectors in this DM

Not Collective

Input Parameter:

• dm - The DM

Output Parameters:

• labels - The DMLabels for each Vec
• values - The label values for each Vec
• parts - The equation parts for each Vec

Level: advanced

Note: The arrays passed in must be at least as large as DMGetNumAuxiliaryVec().

See also:

DM, DMClearAuxiliaryVec(), DMGetNumAuxiliaryVec(), DMGetAuxiliaryVec(), DMSetAuxiliaryVec(), DMCopyAuxiliaryVec()

External Links

• PETSc Manual: DM/DMGetAuxiliaryLabels

DMGetAuxiliaryVec(petsclib::PetscLibType,dm::PetscDM, label::DMLabel, value::PetscInt, part::PetscInt, aux::PetscVec)

Get the auxiliary vector for region specified by the given label and value, and equation part

Not Collective

Input Parameters:

• dm - The DM
• label - The DMLabel
• value - The label value indicating the region
• part - The equation part, or 0 if unused

Output Parameter:

• aux - The Vec holding auxiliary field data

Level: advanced

Note: If no auxiliary vector is found for this (label, value), (NULL, 0, 0) is checked as well.

See also:

DM, DMClearAuxiliaryVec(), DMSetAuxiliaryVec(), DMGetNumAuxiliaryVec(), DMGetAuxiliaryLabels()

External Links

• PETSc Manual: DM/DMGetAuxiliaryVec

useCone::PetscBool,useClosure::PetscBool = DMGetBasicAdjacency(petsclib::PetscLibType,dm::PetscDM)

Returns the flags for determining variable influence, using either the default or field 0 if it is defined

Not collective

Input Parameter:

• dm - The DM object

Output Parameters:

• useCone - Flag for variable influence starting with the cone operation
• useClosure - Flag for variable influence using transitive closure

Level: developer

Notes: -vb FEM: Two points p and q are adjacent if q in closure(star(p)), useCone = PETSCFALSE, useClosure = PETSCTRUE FVM: Two points p and q are adjacent if q in support(p+cone(p)), useCone = PETSCTRUE, useClosure = PETSCFALSE FVM++: Two points p and q are adjacent if q in star(closure(p)), useCone = PETSCTRUE, useClosure = PETSCTRUE -ve

See also:

DM, DMSetBasicAdjacency(), DMGetField(), DMSetField()

External Links

• PETSc Manual: DM/DMGetBasicAdjacency

bs::PetscInt = DMGetBlockSize(petsclib::PetscLibType,dm::PetscDM)

Gets the inherent block size associated with a DM

Not Collective

Input Parameter:

• dm - the DM with block structure

Output Parameter:

• bs - the block size, 1 implies no exploitable block structure

Level: intermediate

Notes: This might be the number of degrees of freedom at each grid point for a structured grid.

Complex DM that represent multiphysics or staggered grids or mixed-methods do not generally have a single inherent block size, but rather different locations in the vectors may have a different block size.

See also:

DM, ISCreateBlock(), VecSetBlockSize(), MatSetBlockSize(), DMGetLocalToGlobalMapping()

External Links

• PETSc Manual: DM/DMGetBlockSize

btype::DMBlockingType = DMGetBlockingType(petsclib::PetscLibType,dm::PetscDM)

get the blocking granularity to be used for variable block size DMCreateMatrix() is called

Not Collective

Input Parameter:

• dm - the DM

Output Parameter:

• btype - block by topological point or field node

Level: advanced

See also:

DM, DMCreateMatrix(), MatSetVariableBlockSizes()

External Links

• PETSc Manual: DM/DMGetBlockingType

gmin::Vector{PetscReal},gmax::Vector{PetscReal} = DMGetBoundingBox(petsclib::PetscLibType,dm::PetscDM)

Returns the global bounding box for the DM.

Collective

Input Parameter:

• dm - the DM

Output Parameters:

• gmin - global minimum coordinates (length coord dim, optional)
• gmax - global maximum coordinates (length coord dim, optional)

Level: beginner

-seealso: DM, DMGetLocalBoundingBox(), DMGetCoordinates(), DMGetCoordinatesLocal()

External Links

• PETSc Manual: DM/DMGetBoundingBox

DMGetCellCoordinateDM(petsclib::PetscLibType,dm::PetscDM, cdm::PetscDM)

Gets the DM that prescribes cellwise coordinate layout and scatters between global and local cellwise coordinates

Collective

Input Parameter:

• dm - the DM

Output Parameter:

• cdm - cellwise coordinate DM, or NULL if they are not defined

Level: intermediate

-seealso: DM, DMSetCellCoordinateDM(), DMSetCellCoordinates(), DMSetCellCoordinatesLocal(), DMGetCellCoordinates(), DMGetCellCoordinatesLocal(), DMLocalizeCoordinates(), DMSetCoordinateDM(), DMGetCoordinateDM()

External Links

• PETSc Manual: DM/DMGetCellCoordinateDM

DMGetCellCoordinateSection(petsclib::PetscLibType,dm::PetscDM, section::PetscSection)

Retrieve the PetscSection of cellwise coordinate values over the mesh.

Collective

Input Parameter:

• dm - The DM object

Output Parameter:

• section - The PetscSection object, or NULL if no cellwise coordinates are defined

Level: intermediate

-seealso: DM, DMGetCoordinateSection(), DMSetCellCoordinateSection(), DMGetCellCoordinateDM(), DMGetCoordinateDM(), DMGetLocalSection(), DMSetLocalSection()

External Links

• PETSc Manual: DM/DMGetCellCoordinateSection

DMGetCellCoordinates(petsclib::PetscLibType,dm::PetscDM, c::PetscVec)

Gets a global vector with the cellwise coordinates associated with the DM.

Collective

Input Parameter:

• dm - the DM

Output Parameter:

• c - global coordinate vector

Level: intermediate

-seealso: DM, DMGetCoordinates(), DMSetCellCoordinates(), DMGetCellCoordinatesLocal(), DMGetCellCoordinateDM()

External Links

• PETSc Manual: DM/DMGetCellCoordinates

DMGetCellCoordinatesLocal(petsclib::PetscLibType,dm::PetscDM, c::PetscVec)

Gets a local vector with the cellwise coordinates associated with the DM.

Collective

Input Parameter:

• dm - the DM

Output Parameter:

• c - coordinate vector

Level: intermediate

-seealso: DM, DMSetCellCoordinatesLocal(), DMGetCellCoordinates(), DMSetCellCoordinates(), DMGetCellCoordinateDM(), DMGetCellCoordinatesLocalNoncollective()

External Links

• PETSc Manual: DM/DMGetCellCoordinatesLocal

DMGetCellCoordinatesLocalNoncollective(petsclib::PetscLibType,dm::PetscDM, c::PetscVec)

Non

Not Collective

Input Parameter:

• dm - the DM

Output Parameter:

• c - cellwise coordinate vector

Level: advanced

-seealso: DM, DMGetCellCoordinatesLocalSetUp(), DMGetCellCoordinatesLocal(), DMSetCellCoordinatesLocal(), DMGetCellCoordinates(), DMSetCellCoordinates(), DMGetCellCoordinateDM()

External Links

• PETSc Manual: DM/DMGetCellCoordinatesLocalNoncollective

DMGetCellCoordinatesLocalSetUp(petsclib::PetscLibType,dm::PetscDM)

Prepares a local vector of cellwise coordinates, so that DMGetCellCoordinatesLocalNoncollective() can be used as non

Collective

Input Parameter:

• dm - the DM

Level: advanced

-seealso: DM, DMGetCellCoordinatesLocalNoncollective()

External Links

• PETSc Manual: DM/DMGetCellCoordinatesLocalSetUp

DMGetCellDS(petsclib::PetscLibType,dm::PetscDM, point::PetscInt, ds::PetscDS, dsIn::PetscDS)

Get the PetscDS defined on a given cell

Not Collective

Input Parameters:

• dm - The DM
• point - Cell for the PetscDS

Output Parameters:

• ds - The PetscDS defined on the given cell
• dsIn - The PetscDS for input on the given cell, or NULL if the same ds

Level: developer

See also:

DM, DMGetDS(), DMSetRegionDS()

External Links

• PETSc Manual: DM/DMGetCellDS

DMGetCoarseDM(petsclib::PetscLibType,dm::PetscDM, cdm::PetscDM)

Get the coarse DMfrom which this DM was obtained by refinement

Not Collective

Input Parameter:

• dm - The DM object

Output Parameter:

• cdm - The coarse DM

Level: intermediate

See also:

DM, DMSetCoarseDM(), DMCoarsen()

External Links

• PETSc Manual: DM/DMGetCoarseDM

level::PetscInt = DMGetCoarsenLevel(petsclib::PetscLibType,dm::PetscDM)

Gets the number of coarsenings that have generated this DM.

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• level - number of coarsenings

Level: developer

See also:

DM, DMCoarsen(), DMSetCoarsenLevel(), DMGetRefineLevel(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()

External Links

• PETSc Manual: DM/DMGetCoarsenLevel

compatible::PetscBool,set::PetscBool = DMGetCompatibility(petsclib::PetscLibType,dm1::PetscDM, dm2::PetscDM)

determine if two DMs are compatible

Collective

Input Parameters:

• dm1 - the first DM
• dm2 - the second DM

Output Parameters:

• compatible - whether or not the two DMs are compatible
• set - whether or not the compatible value was actually determined and set

Level: advanced

Notes: Two DMs are deemed compatible if they represent the same parallel decomposition of the same topology. This implies that the section (field data) on one "makes sense" with respect to the topology and parallel decomposition of the other. Loosely speaking, compatible DMs represent the same domain and parallel decomposition, but hold different data.

Typically, one would confirm compatibility if intending to simultaneously iterate over a pair of vectors obtained from different DMs.

For example, two DMDA objects are compatible if they have the same local and global sizes and the same stencil width. They can have different numbers of degrees of freedom per node. Thus, one could use the node numbering from either DM in bounds for a loop over vectors derived from either DM.

Consider the operation of summing data living on a 2-dof DMDA to data living on a 1-dof DMDA, which should be compatible, as in the following snippet. -vb -.. PetscCall(DMGetCompatibility(da1,da2,&compatible,&set)); if (set && compatible) { PetscCall(DMDAVecGetArrayDOF(da1,vec1,&arr1)); PetscCall(DMDAVecGetArrayDOF(da2,vec2,&arr2)); PetscCall(DMDAGetCorners(da1,&x,&y,NULL,&m,&n,NULL)); for (j=y; j<y+n; ++j) { for (i=x; i<x+m, ++i) { arr1[j][i][0] = arr2[j][i][0] + arr2[j][i][1]; } } PetscCall(DMDAVecRestoreArrayDOF(da1,vec1,&arr1)); PetscCall(DMDAVecRestoreArrayDOF(da2,vec2,&arr2)); } else { SETERRQ(PetscObjectComm((PetscObject)da1,PETSCERRARG_INCOMP,"DMDA objects incompatible"); } -.. -ve

Checking compatibility might be expensive for a given implementation of DM, or might be impossible to unambiguously confirm or deny. For this reason, this function may decline to determine compatibility, and hence users should always check the "set" output parameter.

A DM is always compatible with itself.

In the current implementation, DMs which live on "unequal" communicators (MPIUNEQUAL in the terminology of MPIComm_compare()) are always deemed incompatible.

This function is labeled "Collective," as information about all subdomains is required on each rank. However, in DM implementations which store all this information locally, this function may be merely "Logically Collective".

Developer Note: Compatibility is assumed to be a symmetric concept; DM A is compatible with DM B iff B is compatible with A. Thus, this function checks the implementations of both dm and dmc (if they are of different types), attempting to determine compatibility. It is left to DM implementers to ensure that symmetry is preserved. The simplest way to do this is, when implementing type-specific logic for this function, is to check for existing logic in the implementation of other DM types and let *set = PETSC_FALSE if found.

See also:

DM, DMDACreateCompatibleDMDA(), DMStagCreateCompatibleDMStag()

External Links

• PETSc Manual: DM/DMGetCompatibility

cdm::PetscDM = DMGetCoordinateDM(petsclib::PetscLibType,dm::PetscDM)

Gets the DM that prescribes coordinate layout and scatters between global and local coordinates

Collective

Input Parameter:

• dm - the DM

Output Parameter:

• cdm - coordinate DM

Level: intermediate

-seealso: DM, DMSetCoordinateDM(), DMSetCoordinates(), DMSetCoordinatesLocal(), DMGetCoordinates(), DMGetCoordinatesLocal(), DMGSetCellCoordinateDM(),

External Links

• PETSc Manual: DM/DMGetCoordinateDM

dim::PetscInt = DMGetCoordinateDim(petsclib::PetscLibType,dm::PetscDM)

Retrieve the dimension of the embedding space for coordinate values. For example a mesh on the surface of a sphere would have a 3 dimensional embedding space

Not Collective

Input Parameter:

• dm - The DM object

Output Parameter:

• dim - The embedding dimension

Level: intermediate

-seealso: DM, DMSetCoordinateDim(), DMGetCoordinateSection(), DMGetCoordinateDM(), DMGetLocalSection(), DMSetLocalSection()

External Links

• PETSc Manual: DM/DMGetCoordinateDim

DMGetCoordinateField(petsclib::PetscLibType,dm::PetscDM, field::DMField)

External Links

• PETSc Manual: DM/DMGetCoordinateField

DMGetCoordinateSection(petsclib::PetscLibType,dm::PetscDM, section::PetscSection)

Retrieve the PetscSection of coordinate values over the mesh.

Collective

Input Parameter:

• dm - The DM object

Output Parameter:

• section - The PetscSection object

Level: intermediate

-seealso: DM, DMGetCoordinateDM(), DMGetLocalSection(), DMSetLocalSection()

External Links

• PETSc Manual: DM/DMGetCoordinateSection

DMGetCoordinates(petsclib::PetscLibType,dm::PetscDM, c::PetscVec)

Gets a global vector with the coordinates associated with the DM.

Collective if the global vector with coordinates has not been set yet but the local vector with coordinates has been set

Input Parameter:

• dm - the DM

Output Parameter:

• c - global coordinate vector

Level: intermediate

-seealso: DM, DMDA, DMSetCoordinates(), DMGetCoordinatesLocal(), DMGetCoordinateDM(), DMDASetUniformCoordinates()

External Links

• PETSc Manual: DM/DMGetCoordinates

DMGetCoordinatesLocal(petsclib::PetscLibType,dm::PetscDM, c::PetscVec)

Gets a local vector with the coordinates associated with the DM.

Collective the first time it is called

Input Parameter:

• dm - the DM

Output Parameter:

• c - coordinate vector

Level: intermediate

-seealso: DM, DMSetCoordinatesLocal(), DMGetCoordinates(), DMSetCoordinates(), DMGetCoordinateDM(), DMGetCoordinatesLocalNoncollective()

External Links

• PETSc Manual: DM/DMGetCoordinatesLocal

DMGetCoordinatesLocalNoncollective(petsclib::PetscLibType,dm::PetscDM, c::PetscVec)

Non

Not Collective

Input Parameter:

• dm - the DM

Output Parameter:

• c - coordinate vector

Level: advanced

-seealso: DM, DMGetCoordinatesLocalSetUp(), DMGetCoordinatesLocal(), DMSetCoordinatesLocal(), DMGetCoordinates(), DMSetCoordinates(), DMGetCoordinateDM()

External Links

• PETSc Manual: DM/DMGetCoordinatesLocalNoncollective

DMGetCoordinatesLocalSetUp(petsclib::PetscLibType,dm::PetscDM)

Prepares a local vector of coordinates, so that DMGetCoordinatesLocalNoncollective() can be used as non

Collective

Input Parameter:

• dm - the DM

Level: advanced

-seealso: DM, DMSetCoordinates(), DMGetCoordinatesLocalNoncollective()

External Links

• PETSc Manual: DM/DMGetCoordinatesLocalSetUp

DMGetCoordinatesLocalTuple(petsclib::PetscLibType,dm::PetscDM, p::IS, pCoordSection::PetscSection, pCoord::PetscVec)

Gets a local vector with the coordinates of specified points and the section describing its layout.

Not Collective

Input Parameters:

• dm - the DM
• p - the IS of points whose coordinates will be returned

Output Parameters:

• pCoordSection - the PetscSection describing the layout of pCoord, i.e. each point corresponds to one point in p, and DOFs correspond to coordinates
• pCoord - the Vec with coordinates of points in p

Level: advanced

-seealso: DM, DMDA, DMSetCoordinatesLocal(), DMGetCoordinatesLocal(), DMGetCoordinatesLocalNoncollective(), DMGetCoordinatesLocalSetUp(), DMGetCoordinates(), DMSetCoordinates(), DMGetCoordinateDM()

External Links

• PETSc Manual: DM/DMGetCoordinatesLocalTuple

areLocalized::PetscBool = DMGetCoordinatesLocalized(petsclib::PetscLibType,dm::PetscDM)

Check if the DM coordinates have been localized for cells

Collective

Input Parameter:

• dm - The DM

Output Parameter:

• areLocalized - PETSC_TRUE if localized

Level: developer

-seealso: DM, DMLocalizeCoordinates(), DMSetPeriodicity(), DMGetCoordinatesLocalizedLocal()

External Links

• PETSc Manual: DM/DMGetCoordinatesLocalized

areLocalized::PetscBool = DMGetCoordinatesLocalizedLocal(petsclib::PetscLibType,dm::PetscDM)

Check if the DM coordinates have been localized for cells on this process

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• areLocalized - PETSC_TRUE if localized

Level: developer

-seealso: DM, DMLocalizeCoordinates(), DMGetCoordinatesLocalized(), DMSetPeriodicity()

External Links

• PETSc Manual: DM/DMGetCoordinatesLocalizedLocal

DMGetDS(petsclib::PetscLibType,dm::PetscDM, ds::PetscDS)

Get the default PetscDS

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• ds - The default PetscDS

Level: intermediate

Note: The ds is owned by the dm and should not be destroyed directly.

See also:

DM, DMGetCellDS(), DMGetRegionDS()

External Links

• PETSc Manual: DM/DMGetDS

DMGetDefaultConstraints(petsclib::PetscLibType,dm::PetscDM, section::PetscSection, mat::PetscMat, bias::PetscVec)

Get the PetscSection and Mat that specify the local constraint interpolation. See DMSetDefaultConstraints() for a description of the purpose of constraint interpolation.

not Collective

Input Parameter:

• dm - The DM

Output Parameters:

• section - The PetscSection describing the range of the constraint matrix: relates rows of the constraint matrix to dofs of the default section. Returns NULL if there are no local constraints.
• mat - The Mat that interpolates local constraints: its width should be the layout size of the default section. Returns NULL if there are no local constraints.
• bias - Vector containing bias to be added to constrained dofs

Level: advanced

Note: This gets borrowed references, so the user should not destroy the PetscSection, Mat, or Vec.

See also:

DM, DMSetDefaultConstraints()

External Links

• PETSc Manual: DM/DMGetDefaultConstraints

pStart::PetscInt,pEnd::PetscInt = DMGetDimPoints(petsclib::PetscLibType,dm::PetscDM, dim::PetscInt)

Get the half

Collective

Input Parameters:

• dm - the DM
• dim - the dimension

Output Parameters:

• pStart - The first point of the given dimension
• pEnd - The first point following points of the given dimension

Level: intermediate

Note: The points are vertices in the Hasse diagram encoding the topology. This is explained in https://arxiv.org/abs/0908.4427. If no points exist of this dimension in the storage scheme, then the interval is empty.

See also:

DM, DMPLEX, DMPlexGetDepthStratum(), DMPlexGetHeightStratum()

External Links

• PETSc Manual: DM/DMGetDimPoints

dim::PetscInt = DMGetDimension(petsclib::PetscLibType,dm::PetscDM)

Return the topological dimension of the DM

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• dim - The topological dimension

Level: beginner

See also:

DM, DMSetDimension(), DMCreate()

External Links

• PETSc Manual: DM/DMGetDimension

pA::PetscInt = DMGetEnclosurePoint(petsclib::PetscLibType,dmA::PetscDM, dmB::PetscDM, etype::DMEnclosureType, pB::PetscInt)

Get the point pA in dmA which corresponds to the point pB in dmB

Input Parameters:

• dmA - The first DM
• dmB - The second DM
• etype - The type of enclosure relation that dmA has to dmB
• pB - A point of dmB

Output Parameter:

• pA - The corresponding point of dmA

Level: intermediate

-seealso: , DM, DMPLEX, DMGetEnclosureRelation()

External Links

• PETSc Manual: DM/DMGetEnclosurePoint

DMGetEnclosureRelation(petsclib::PetscLibType,dmA::PetscDM, dmB::PetscDM, rel::DMEnclosureType)

Get the relationship between dmA and dmB

Input Parameters:

• dmA - The first DM
• dmB - The second DM

Output Parameter:

• rel - The relation of dmA to dmB

Level: intermediate

-seealso: , DM, DMPLEX, DMGetEnclosurePoint()

External Links

• PETSc Manual: DM/DMGetEnclosureRelation

DMGetField(petsclib::PetscLibType,dm::PetscDM, f::PetscInt, label::DMLabel, disc::PetscObject)

Return the DMLabel and discretization object for a given DM field

Not Collective

Input Parameters:

• dm - The DM
• f - The field number

Output Parameters:

• label - The label indicating the support of the field, or NULL for the entire mesh (pass in NULL if not needed)
• disc - The discretization object (pass in NULL if not needed)

Level: intermediate

See also:

DM, DMAddField(), DMSetField()

External Links

• PETSc Manual: DM/DMGetField

avoidTensor::PetscBool = DMGetFieldAvoidTensor(petsclib::PetscLibType,dm::PetscDM, f::PetscInt)

Get flag to avoid defining the field on tensor cells

Not Collective

Input Parameters:

• dm - The DM
• f - The field index

Output Parameter:

• avoidTensor - The flag to avoid defining the field on tensor cells

Level: intermediate

See also:

DM, DMAddField(), DMSetField(), DMGetField(), DMSetFieldAvoidTensor()

External Links

• PETSc Manual: DM/DMGetFieldAvoidTensor

DMGetFineDM(petsclib::PetscLibType,dm::PetscDM, fdm::PetscDM)

Get the fine mesh from which this DM was obtained by coarsening

Input Parameter:

• dm - The DM object

Output Parameter:

• fdm - The fine DM

Level: intermediate

See also:

DM, DMSetFineDM(), DMCoarsen(), DMRefine()

External Links

• PETSc Manual: DM/DMGetFineDM

point::PetscInt = DMGetFirstLabeledPoint(petsclib::PetscLibType,dm::PetscDM, odm::PetscDM, label::DMLabel, numIds::PetscInt, ids::Vector{PetscInt}, height::PetscInt, ds::PetscDS)

Find first labeled point in odm such that the corresponding point in dm has the specified height. Return point and the corresponding ds.

Input Parameters:

• dm - the DM
• odm - the enclosing DM
• label - label for DM domain, or NULL for whole domain
• numIds - the number of ids
• ids - An array of the label ids in sequence for the domain
• height - Height of target cells in DMPLEX topology

Output Parameters:

• point - the first labeled point
• ds - the PetscDS corresponding to the first labeled point

Level: developer

-seealso: , DM, DMPLEX, DMPlexSetActivePoint(), DMLabel, PetscDS

External Links

• PETSc Manual: DM/DMGetFirstLabeledPoint

DMGetGlobalSection(petsclib::PetscLibType,dm::PetscDM, section::PetscSection)

Get the PetscSection encoding the global data layout for the DM.

Collective

Input Parameter:

• dm - The DM

Output Parameter:

• section - The PetscSection

Level: intermediate

Note: This gets a borrowed reference, so the user should not destroy this PetscSection.

See also:

DM, DMSetLocalSection(), DMGetLocalSection()

External Links

• PETSc Manual: DM/DMGetGlobalSection

DMGetGlobalVector(petsclib::PetscLibType,dm::PetscDM, g::PetscVec)

Gets a PETSc vector that may be used with the DM global routines.

Collective

Input Parameter:

• dm - the DM

Output Parameter:

• g - the global vector

Level: beginner

-seealso: DM, DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(), DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMRestoreLocalVector() VecStrideMax(), VecStrideMin(), VecStrideNorm(), DMClearGlobalVectors(), DMGetNamedGlobalVector(), DMGetNamedLocalVector()

External Links

• PETSc Manual: DM/DMGetGlobalVector

ctype::ISColoringType = DMGetISColoringType(petsclib::PetscLibType,dm::PetscDM)

Gets the type of coloring, IS_COLORING_GLOBAL or IS_COLORING_LOCAL that is created by the DM

Logically Collective

Input Parameter:

• dm - the DM context

Output Parameter:

• ctype - the matrix type

Options Database Key:

• -dm_is_coloring_type - global or local

Level: intermediate

See also:

DM, DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMCreateMatrix(), DMCreateMassMatrix(), DMSetMatrixPreallocateOnly(), MatType, DMGetMatType(), ISColoringType, IS_COLORING_GLOBAL, IS_COLORING_LOCAL

External Links

• PETSc Manual: DM/DMGetISColoringType

DMGetLabel(petsclib::PetscLibType,dm::PetscDM, name::String, label::DMLabel)

Return the label of a given name, or NULL, from a DM

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name

Output Parameter:

• label - The DMLabel, or NULL if the label is absent

Default labels in a DMPLEX:

• "depth" - Holds the depth (co-dimension) of each mesh point
• "celltype" - Holds the topological type of each cell
• "ghost" - If the DM is distributed with overlap, this marks the cells and faces in the overlap
• "Cell Sets" - Mirrors the cell sets defined by GMsh and ExodusII
• "Face Sets" - Mirrors the face sets defined by GMsh and ExodusII
• "Vertex Sets" - Mirrors the vertex sets defined by GMsh

Level: intermediate

See also:

DM, DMLabel, DMHasLabel(), DMGetLabelByNum(), DMAddLabel(), DMCreateLabel(), DMPlexGetDepthLabel(), DMPlexGetCellType()

External Links

• PETSc Manual: DM/DMGetLabel

DMGetLabelByNum(petsclib::PetscLibType,dm::PetscDM, n::PetscInt, label::DMLabel)

Return the nth label on a DM

Not Collective

Input Parameters:

• dm - The DM object
• n - the label number

Output Parameter:

• label - the label

Level: intermediate

See also:

DM, DMLabel, DMAddLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMGetLabelByNum

DMGetLabelIdIS(petsclib::PetscLibType,dm::PetscDM, name::String, ids::IS)

Get the DMLabelGetValueIS() from a DMLabel in the DM

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name

Output Parameter:

• ids - The integer ids, or NULL if the label does not exist

Level: beginner

See also:

DM, DMLabelGetValueIS(), DMGetLabelSize()

External Links

• PETSc Manual: DM/DMGetLabelIdIS

DMGetLabelName(petsclib::PetscLibType,dm::PetscDM, n::PetscInt, name::String)

Return the name of nth label

Not Collective

Input Parameters:

• dm - The DM object
• n - the label number

Output Parameter:

• name - the label name

Level: intermediate

Developer Note: Some of the functions that appropriate on labels using their number have the suffix ByNum, others do not.

See also:

DM, DMLabel, DMGetLabelByNum(), DMGetLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMGetLabelName

output::PetscBool = DMGetLabelOutput(petsclib::PetscLibType,dm::PetscDM, name::String)

Get the output flag for a given label

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name

Output Parameter:

• output - The flag for output

Level: developer

See also:

DM, DMLabel, DMSetLabelOutput(), DMCreateLabel(), DMHasLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMGetLabelOutput

size::PetscInt = DMGetLabelSize(petsclib::PetscLibType,dm::PetscDM, name::String)

Get the value of DMLabelGetNumValues() of a DMLabel in the DM

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name

Output Parameter:

• size - The number of different integer ids, or 0 if the label does not exist

Level: beginner

Developer Note: This should be renamed to something like DMGetLabelNumValues() or removed.

See also:

DM, DMLabelGetNumValues(), DMSetLabelValue(), DMGetLabel()

External Links

• PETSc Manual: DM/DMGetLabelSize

value::PetscInt = DMGetLabelValue(petsclib::PetscLibType,dm::PetscDM, name::String, point::PetscInt)

Get the value in a DMLabel for the given point, with

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name
• point - The mesh point

Output Parameter:

• value - The label value for this point, or -1 if the point is not in the label

Level: beginner

See also:

DM, DMLabelGetValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMGetLabelValue

lmin::Vector{PetscReal},lmax::Vector{PetscReal} = DMGetLocalBoundingBox(petsclib::PetscLibType,dm::PetscDM)

Returns the bounding box for the piece of the DM on this process.

Not Collective

Input Parameter:

• dm - the DM

Output Parameters:

• lmin - local minimum coordinates (length coord dim, optional)
• lmax - local maximum coordinates (length coord dim, optional)

Level: beginner

-seealso: DM, DMGetCoordinates(), DMGetCoordinatesLocal(), DMGetBoundingBox()

External Links

• PETSc Manual: DM/DMGetLocalBoundingBox

DMGetLocalSection(petsclib::PetscLibType,dm::PetscDM, section::PetscSection)

Get the PetscSection encoding the local data layout for the DM.

Input Parameter:

• dm - The DM

Output Parameter:

• section - The PetscSection

Options Database Key:

• -dm_petscsection_view - View the section created by the DM

Level: intermediate

Note: This gets a borrowed reference, so the user should not destroy this PetscSection.

See also:

DM, DMSetLocalSection(), DMGetGlobalSection()

External Links

• PETSc Manual: DM/DMGetLocalSection

DMGetLocalToGlobalMapping(petsclib::PetscLibType,dm::PetscDM, ltog::ISLocalToGlobalMapping)

Accesses the local

Collective

Input Parameter:

• dm - the DM that provides the mapping

Output Parameter:

• ltog - the mapping

Level: advanced

Notes: The global to local mapping allows one to set values into the global vector or matrix using VecSetValuesLocal() and MatSetValuesLocal()

Vectors obtained with DMCreateGlobalVector() and matrices obtained with DMCreateMatrix() already contain the global mapping so you do need to use this function with those objects.

This mapping can then be used by VecSetLocalToGlobalMapping() or MatSetLocalToGlobalMapping().

See also:

DM, DMCreateLocalVector(), DMCreateGlobalVector(), VecSetLocalToGlobalMapping(), MatSetLocalToGlobalMapping(), DMCreateMatrix()

External Links

• PETSc Manual: DM/DMGetLocalToGlobalMapping

 g::PetscVec = DMGetLocalVector(petsclib::PetscLibType,dm::PetscDM)

Gets a PETSc vector that may be used with the DM local routines. This vector has spaces for the ghost values.

Not Collective

Input Parameter:

• dm - the DM

Output Parameter:

• g - the local vector

Note: The vector values are NOT initialized and may have garbage in them, so you may need to zero them.

The output parameter, g, is a regular PETSc vector that should be returned with DMRestoreLocalVector() DO NOT call VecDestroy() on it.

This is intended to be used for vectors you need for a short time, like within a single function call. For vectors that you intend to keep around (for example in a C struct) or pass around large parts of your code you should use DMCreateLocalVector().

VecStride*() operations can be useful when using DM with dof > 1

Level: beginner

-seealso: DM, DMCreateGlobalVector(), VecDuplicate(), VecDuplicateVecs(), DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMGlobalToLocalBegin(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMCreateLocalVector(), DMRestoreLocalVector(), VecStrideMax(), VecStrideMin(), VecStrideNorm(), DMClearLocalVectors(), DMGetNamedGlobalVector(), DMGetNamedLocalVector()

External Links

• PETSc Manual: DM/DMGetLocalVector

ctype::MatType = DMGetMatType(petsclib::PetscLibType,dm::PetscDM)

Gets the type of matrix that would be created with DMCreateMatrix()

Logically Collective

Input Parameter:

• dm - the DM context

Output Parameter:

• ctype - the matrix type

Level: intermediate

See also:

DM, DMDACreate1d(), DMDACreate2d(), DMDACreate3d(), DMCreateMatrix(), DMCreateMassMatrix(), DMSetMatrixPreallocateOnly(), MatType, DMSetMatType()

External Links

• PETSc Manual: DM/DMGetMatType

DMGetNamedGlobalVector(petsclib::PetscLibType,dm::PetscDM, name::String, X::PetscVec)

get access to a named, persistent global vector

Collective

Input Parameters:

• dm - DM to hold named vectors
• name - unique name for X

Output Parameter:

• X - named Vec

Level: developer

-seealso: DM, DMRestoreNamedGlobalVector(), DMHasNamedGlobalVector(), DMClearNamedGlobalVectors(), DMGetGlobalVector(), DMGetLocalVector()

External Links

• PETSc Manual: DM/DMGetNamedGlobalVector

DMGetNamedLocalVector(petsclib::PetscLibType,dm::PetscDM, name::String, X::PetscVec)

get access to a named, persistent local vector

Not Collective

Input Parameters:

• dm - DM to hold named vectors
• name - unique name for X

Output Parameter:

• X - named Vec

Level: developer

-seealso: DM, DMGetNamedGlobalVector(), DMRestoreNamedLocalVector(), DMHasNamedLocalVector(), DMClearNamedLocalVectors(), DMGetGlobalVector(), DMGetLocalVector()

External Links

• PETSc Manual: DM/DMGetNamedLocalVector

DMGetNaturalSF(petsclib::PetscLibType,dm::PetscDM, sf::PetscSF)

Get the PetscSF encoding the map back to the original mesh ordering

Input Parameter:

• dm - The DM

Output Parameter:

• sf - The PetscSF

Level: intermediate

Note: This gets a borrowed reference, so the user should not destroy this PetscSF.

See also:

DM, DMSetNaturalSF(), DMSetUseNatural(), DMGetUseNatural(), DMPlexCreateGlobalToNaturalSF(), DMPlexDistribute()

External Links

• PETSc Manual: DM/DMGetNaturalSF

nranks::PetscInt = DMGetNeighbors(petsclib::PetscLibType,dm::PetscDM, ranks::Vector{PetscMPIInt})

Gets an array containing the MPI ranks of all the processes neighbors

Not Collective

Input Parameter:

• dm - The DM

Output Parameters:

• nranks - the number of neighbours
• ranks - the neighbors ranks

Level: beginner

Note: Do not free the array, it is freed when the DM is destroyed.

See also:

DM, DMDAGetNeighbors(), PetscSFGetRootRanks()

External Links

• PETSc Manual: DM/DMGetNeighbors

numAux::PetscInt = DMGetNumAuxiliaryVec(petsclib::PetscLibType,dm::PetscDM)

Get the number of auxiliary vectors associated with this DM

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• numAux - The number of auxiliary data vectors

Level: advanced

See also:

DM, DMClearAuxiliaryVec(), DMSetAuxiliaryVec(), DMGetAuxiliaryLabels(), DMGetAuxiliaryVec()

External Links

• PETSc Manual: DM/DMGetNumAuxiliaryVec

Nds::PetscInt = DMGetNumDS(petsclib::PetscLibType,dm::PetscDM)

Get the number of discrete systems in the DM

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• Nds - The number of PetscDS objects

Level: intermediate

See also:

DM, DMGetDS(), DMGetCellDS()

External Links

• PETSc Manual: DM/DMGetNumDS

numFields::PetscInt = DMGetNumFields(petsclib::PetscLibType,dm::PetscDM)

Get the number of fields in the DM

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• numFields - The number of fields

Level: intermediate

See also:

DM, DMSetNumFields(), DMSetField()

External Links

• PETSc Manual: DM/DMGetNumFields

numLabels::PetscInt = DMGetNumLabels(petsclib::PetscLibType,dm::PetscDM)

Return the number of labels defined by on the DM

Not Collective

Input Parameter:

• dm - The DM object

Output Parameter:

• numLabels - the number of Labels

Level: intermediate

See also:

DM, DMLabel, DMGetLabelByNum(), DMGetLabelName(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMGetNumLabels

DMGetOptionsPrefix(petsclib::PetscLibType,dm::PetscDM, prefix::String)

Gets the prefix used for searching for all DM options in the options database.

Not Collective

Input Parameter:

• dm - the DM context

Output Parameter:

• prefix - pointer to the prefix string used is returned

Level: advanced

See also:

DM, DMSetOptionsPrefix(), DMAppendOptionsPrefix(), DMSetFromOptions()

External Links

• PETSc Manual: DM/DMGetOptionsPrefix

DMGetOutputDM(petsclib::PetscLibType,dm::PetscDM, odm::PetscDM)

Retrieve the DM associated with the layout for output

Collective

Input Parameter:

• dm - The original DM

Output Parameter:

• odm - The DM which provides the layout for output

Level: intermediate

Note: In some situations the vector obtained with DMCreateGlobalVector() excludes points for degrees of freedom that are associated with fixed (Dirichelet) boundary conditions since the algebraic solver does not solve for those variables. The output DM includes these excluded points and its global vector contains the locations for those dof so that they can be output to a file or other viewer along with the unconstrained dof.

See also:

DM, VecView(), DMGetGlobalSection(), DMCreateGlobalVector(), PetscSectionHasConstraints(), DMSetGlobalSection()

External Links

• PETSc Manual: DM/DMGetOutputDM

len::PetscInt = DMGetOutputSequenceLength(petsclib::PetscLibType,dm::PetscDM, viewer::PetscViewer, name::String)

Retrieve the number of sequence values from a PetscViewer

Input Parameters:

• dm - The original DM
• viewer - The PetscViewer to get it from
• name - The sequence name

Output Parameter:

• len - The length of the output sequence

Level: intermediate

Note: This is intended for output that should appear in sequence, for instance a set of timesteps in an PETSCVIEWERHDF5 file, or a set of realizations of a stochastic system.

Developer Note: It is unclear at the user API level why a DM is needed as input

See also:

DM, DMGetOutputSequenceNumber(), DMSetOutputSequenceNumber(), VecView()

External Links

• PETSc Manual: DM/DMGetOutputSequenceLength

num::PetscInt,val::PetscReal = DMGetOutputSequenceNumber(petsclib::PetscLibType,dm::PetscDM)

Retrieve the sequence number/value for output

Input Parameter:

• dm - The original DM

Output Parameters:

• num - The output sequence number
• val - The output sequence value

Level: intermediate

Note: This is intended for output that should appear in sequence, for instance a set of timesteps in an PETSCVIEWERHDF5 file, or a set of realizations of a stochastic system.

Developer Note: The DM serves as a convenient place to store the current iteration value. The iteration is not not directly related to the DM.

See also:

DM, VecView()

External Links

• PETSc Manual: DM/DMGetOutputSequenceNumber

maxCell::Vector{PetscReal},Lstart::Vector{PetscReal},L::Vector{PetscReal} = DMGetPeriodicity(petsclib::PetscLibType,dm::PetscDM)

Get the description of mesh periodicity

Not collective

Input Parameter:

• dm - The DM object

Output Parameters:

• maxCell - Over distances greater than this, we can assume a point has crossed over to another sheet, when trying to localize cell coordinates
• Lstart - If we assume the mesh is a torus, this is the start of each coordinate, or NULL for 0.0
• L - If we assume the mesh is a torus, this is the length of each coordinate, otherwise it is < 0.0

Level: developer

-seealso: DM

External Links

• PETSc Manual: DM/DMGetPeriodicity

DMGetPointSF(petsclib::PetscLibType,dm::PetscDM, sf::PetscSF)

Get the PetscSF encoding the parallel section point overlap for the DM.

Not collective but the resulting PetscSF is collective

Input Parameter:

• dm - The DM

Output Parameter:

• sf - The PetscSF

Level: intermediate

Note: This gets a borrowed reference, so the user should not destroy this PetscSF.

See also:

DM, DMSetPointSF(), DMGetSectionSF(), DMSetSectionSF(), DMCreateSectionSF()

External Links

• PETSc Manual: DM/DMGetPointSF

level::PetscInt = DMGetRefineLevel(petsclib::PetscLibType,dm::PetscDM)

Gets the number of refinements that have generated this DM from some initial DM.

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• level - number of refinements

Level: developer

Note: This can be used, by example, to set the number of coarser levels associated with this DM for a multigrid solver.

See also:

DM, DMRefine(), DMCoarsen(), DMGetCoarsenLevel(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation()

External Links

• PETSc Manual: DM/DMGetRefineLevel

DMGetRegionDS(petsclib::PetscLibType,dm::PetscDM, label::DMLabel, fields::IS, ds::PetscDS, dsIn::PetscDS)

Get the PetscDS for a given mesh region, defined by a DMLabel

Not Collective

Input Parameters:

• dm - The DM
• label - The DMLabel defining the mesh region, or NULL for the entire mesh

Output Parameters:

• fields - The IS containing the DM field numbers for the fields in this PetscDS, or NULL
• ds - The PetscDS defined on the given region, or NULL
• dsIn - The PetscDS for input in the given region, or NULL

Level: advanced

Note: If a non-NULL label is given, but there is no PetscDS on that specific label, the PetscDS for the full domain (if present) is returned. Returns with fields = NULL and ds = NULL if there is no PetscDS for the full domain.

See also:

DM, DMGetRegionNumDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()

External Links

• PETSc Manual: DM/DMGetRegionDS

DMGetRegionNumDS(petsclib::PetscLibType,dm::PetscDM, num::PetscInt, label::DMLabel, fields::IS, ds::PetscDS, dsIn::PetscDS)

Get the PetscDS for a given mesh region, defined by the region number

Not Collective

Input Parameters:

• dm - The DM
• num - The region number, in [0, Nds)

Output Parameters:

• label - The region label, or NULL
• fields - The IS containing the DM field numbers for the fields in this PetscDS, or NULL
• ds - The PetscDS defined on the given region, or NULL
• dsIn - The PetscDS for input in the given region, or NULL

Level: advanced

See also:

DM, DMGetRegionDS(), DMSetRegionDS(), DMGetDS(), DMGetCellDS()

External Links

• PETSc Manual: DM/DMGetRegionNumDS

DMGetSectionSF(petsclib::PetscLibType,dm::PetscDM, sf::PetscSF)

Get the PetscSF encoding the parallel dof overlap for the DM. If it has not been set, it is created from the default PetscSection layouts in the DM.

Input Parameter:

• dm - The DM

Output Parameter:

• sf - The PetscSF

Level: intermediate

Note: This gets a borrowed reference, so the user should not destroy this PetscSF.

See also:

DM, DMSetSectionSF(), DMCreateSectionSF()

External Links

• PETSc Manual: DM/DMGetSectionSF

sparse::PetscBool = DMGetSparseLocalize(petsclib::PetscLibType,dm::PetscDM)

Check if the DM coordinates should be localized only for cells near the periodic boundary.

Not collective

Input Parameter:

• dm - The DM

Output Parameter:

• sparse - PETSC_TRUE if only cells near the periodic boundary are localized

Level: intermediate

-seealso: DMSetSparseLocalize(), DMLocalizeCoordinates(), DMSetPeriodicity()

External Links

• PETSc Manual: DM/DMGetSparseLocalize

DMGetStratumIS(petsclib::PetscLibType,dm::PetscDM, name::String, value::PetscInt, points::IS)

Get the points in a label stratum

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name
• value - The stratum value

Output Parameter:

• points - The stratum points, or NULL if the label does not exist or does not have that value

Level: beginner

See also:

DM, DMLabelGetStratumIS(), DMGetStratumSize()

External Links

• PETSc Manual: DM/DMGetStratumIS

size::PetscInt = DMGetStratumSize(petsclib::PetscLibType,dm::PetscDM, name::String, value::PetscInt)

Get the number of points in a label stratum

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name of the stratum
• value - The stratum value

Output Parameter:

• size - The number of points, also called the stratum size

Level: beginner

See also:

DM, DMLabelGetStratumSize(), DMGetLabelSize(), DMGetLabelIds()

External Links

• PETSc Manual: DM/DMGetStratumSize

type::DMType = DMGetType(petsclib::PetscLibType,dm::PetscDM)

Gets the DM type name (as a string) from the DM.

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• type - The DMType name

Level: intermediate

See also:

DM, DMType, DMDA, DMPLEX, DMSetType(), DMCreate()

External Links

• PETSc Manual: DM/DMGetType

useNatural::PetscBool = DMGetUseNatural(petsclib::PetscLibType,dm::PetscDM)

Get the flag for creating a mapping to the natural order when a DM is (re)distributed in parallel

Not Collective

Input Parameter:

• dm - The DM

Output Parameter:

• useNatural - PETSC_TRUE to build the mapping to a natural order during distribution

Level: beginner

See also:

DM, DMSetUseNatural(), DMCreate()

External Links

• PETSc Manual: DM/DMGetUseNatural

ctype::VecType = DMGetVecType(petsclib::PetscLibType,da::PetscDM)

Gets the type of vector created with DMCreateLocalVector() and DMCreateGlobalVector()

Logically Collective

Input Parameter:

• da - initial distributed array

Output Parameter:

• ctype - the vector type

Level: intermediate

See also:

DM, DMCreate(), DMDestroy(), DMDAInterpolationType, VecType, DMSetMatType(), DMGetMatType(), DMSetVecType()

External Links

• PETSc Manual: DM/DMGetVecType

DMGlobalToLocal(petsclib::PetscLibType,dm::PetscDM, g::PetscVec, mode::InsertMode, l::PetscVec)

update local vectors from global vector

Neighbor-wise Collective

Input Parameters:

• dm - the DM object
• g - the global vector
• mode - INSERT_VALUES or ADD_VALUES
• l - the local vector

Level: beginner

Notes: The communication involved in this update can be overlapped with computation by instead using DMGlobalToLocalBegin() and DMGlobalToLocalEnd().

DMGlobalToLocalHookAdd() may be used to provide additional operations that are performed during the update process.

See also:

DM, DMGlobalToLocalHookAdd(), DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMLocalToGlobal(), DMLocalToGlobalEnd(), DMGlobalToLocalBegin() DMGlobalToLocalEnd()

External Links

• PETSc Manual: DM/DMGlobalToLocal

DMGlobalToLocalBegin(petsclib::PetscLibType,dm::PetscDM, g::PetscVec, mode::InsertMode, l::PetscVec)

Begins updating local vectors from global vector

Neighbor-wise Collective

Input Parameters:

• dm - the DM object
• g - the global vector
• mode - INSERT_VALUES or ADD_VALUES
• l - the local vector

Level: intermediate

Notes: The operation is completed with DMGlobalToLocalEnd()

One can perform local computations between the DMGlobalToLocalBegin() and DMGlobalToLocalEnd() to overlap communication and computation

DMGlobalToLocal() is a short form of DMGlobalToLocalBegin() and DMGlobalToLocalEnd()

DMGlobalToLocalHookAdd() may be used to provide additional operations that are performed during the update process.

See also:

DM, DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocal(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMLocalToGlobal(), DMLocalToGlobalEnd()

External Links

• PETSc Manual: DM/DMGlobalToLocalBegin

DMGlobalToLocalBeginDefaultShell(petsclib::PetscLibType,dm::PetscDM, g::PetscVec, mode::InsertMode, l::PetscVec)

Uses the GlobalToLocal VecScatter context set by the user to begin a global to local scatter

Collective

Input Parameters:

• dm - DMSHELL
• g - global vector
• mode - InsertMode
• l - local vector

Level: advanced

-seealso: DM, DMSHELL, DMGlobalToLocalEndDefaultShell()

External Links

• PETSc Manual: DM/DMGlobalToLocalBeginDefaultShell

DMGlobalToLocalEnd(petsclib::PetscLibType,dm::PetscDM, g::PetscVec, mode::InsertMode, l::PetscVec)

Ends updating local vectors from global vector

Neighbor-wise Collective

Input Parameters:

• dm - the DM object
• g - the global vector
• mode - INSERT_VALUES or ADD_VALUES
• l - the local vector

Level: intermediate

Note: See DMGlobalToLocalBegin() for details.

See also:

DM, DMCoarsen(), DMDestroy(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMGlobalToLocal(), DMLocalToGlobalBegin(), DMLocalToGlobal(), DMLocalToGlobalEnd()

External Links

• PETSc Manual: DM/DMGlobalToLocalEnd

DMGlobalToLocalEndDefaultShell(petsclib::PetscLibType,dm::PetscDM, g::PetscVec, mode::InsertMode, l::PetscVec)

Uses the GlobalToLocal VecScatter context set by the user to end a global to local scatter Collective

Input Parameters:

• dm - DMSHELL
• g - global vector
• mode - InsertMode
• l - local vector

Level: advanced

-seealso: DM, DMSHELL, DMGlobalToLocalBeginDefaultShell()

External Links

• PETSc Manual: DM/DMGlobalToLocalEndDefaultShell

DMGlobalToLocalHookAdd(petsclib::PetscLibType,dm::PetscDM, beginhook::external, endhook::external, ctx::Cvoid)

adds a callback to be run when DMGlobalToLocal() is called

Logically Collective

Input Parameters:

• dm - the DM
• beginhook - function to run at the beginning of DMGlobalToLocalBegin()
• endhook - function to run after DMGlobalToLocalEnd() has completed
• ctx - [optional] user-defined context for provide data for the hooks (may be NULL)

Calling sequence of beginhook:

• dm - global DM
• g - global vector
• mode - mode
• l - local vector
• ctx - optional user-defined function context

Calling sequence of endhook:

• dm - global DM
• g - global vector
• mode - mode
• l - local vector
• ctx - optional user-defined function context

Level: advanced

Note: The hook may be used to provide, for example, values that represent boundary conditions in the local vectors that do not exist on the global vector.

See also:

DM, DMGlobalToLocal(), DMRefineHookAdd(), SNESFASGetInterpolation(), SNESFASGetInjection(), PetscObjectCompose(), PetscContainerCreate()

External Links

• PETSc Manual: DM/DMGlobalToLocalHookAdd

DMGlobalToLocalSolve(petsclib::PetscLibType,dm::PetscDM, x::PetscVec, y::PetscVec)

Solve for the global vector that is mapped to a given local vector by DMGlobalToLocalBegin()/DMGlobalToLocalEnd() with mode INSERT_VALUES.

Collective

Input Parameters:

• dm - The DM object
• x - The local vector
• y - The global vector: the input value of this variable is used as an initial guess

Output Parameter:

• y - The least-squares solution

Level: advanced

Note: It is assumed that the sum of all the local vector sizes is greater than or equal to the global vector size, so the solution is a least-squares solution. It is also assumed that DMLocalToGlobalBegin()/DMLocalToGlobalEnd() with mode ADD_VALUES is the adjoint of the global-to-local map, so that the least-squares solution may be found by the normal equations.

If the DM is of type DMPLEX, then y is the solution of L^T * D * L * y = L^T * D * x , where D is a diagonal mask that is 1 for every point in the union of the closures of the local cells and 0 otherwise. This difference is only relevant if there are anchor points that are not in the closure of any local cell (see DMPlexGetAnchors()/DMPlexSetAnchors()).

What is L?

If this solves for a global vector from a local vector why is not called DMLocalToGlobalSolve()?

See also:

DM, DMGlobalToLocalBegin(), DMGlobalToLocalEnd(), DMLocalToGlobalBegin(), DMLocalToGlobalEnd(), DMPlexGetAnchors(), DMPlexSetAnchors()

External Links

• PETSc Manual: DM/DMGlobalToLocalSolve

flg::PetscBool = DMHasBasisTransform(petsclib::PetscLibType,dm::PetscDM)

Whether the DM employs a basis transformation from functions in global vectors to functions in local vectors

Input Parameter:

• dm - The DM

Output Parameter:

• flg - PETSC_TRUE if a basis transformation should be done

Level: developer

See also:

DM, DMPlexGlobalToLocalBasis(), DMPlexLocalToGlobalBasis(), DMPlexCreateBasisRotation()

External Links

• PETSc Manual: DM/DMHasBasisTransform

hasBound::PetscBool = DMHasBound(petsclib::PetscLibType,dm::PetscDM)

Determine whether a bound condition was specified

Logically collective

Input Parameter:

• dm - The DM, with a PetscDS that matches the problem being constrained

Output Parameter:

• hasBound - Flag indicating if a bound condition was specified

Level: intermediate

See also:

DM, DSAddBoundary(), PetscDSAddBoundary()

External Links

• PETSc Manual: DM/DMHasBound

flg::PetscBool = DMHasColoring(petsclib::PetscLibType,dm::PetscDM)

does the DM object have a method of providing a coloring?

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• flg - PETSC_TRUE if the DM has facilities for DMCreateColoring().

Level: developer

See also:

DM, DMCreateColoring()

External Links

• PETSc Manual: DM/DMHasColoring

flg::PetscBool = DMHasCreateInjection(petsclib::PetscLibType,dm::PetscDM)

does the DM object have a method of providing an injection?

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• flg - PETSC_TRUE if the DM has facilities for DMCreateInjection().

Level: developer

See also:

DM, DMCreateInjection(), DMHasCreateRestriction(), DMHasCreateInterpolation()

External Links

• PETSc Manual: DM/DMHasCreateInjection

flg::PetscBool = DMHasCreateRestriction(petsclib::PetscLibType,dm::PetscDM)

does the DM object have a method of providing a restriction?

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• flg - PETSC_TRUE if the DM has facilities for DMCreateRestriction().

Level: developer

See also:

DM, DMCreateRestriction(), DMHasCreateInterpolation(), DMHasCreateInjection()

External Links

• PETSc Manual: DM/DMHasCreateRestriction

hasLabel::PetscBool = DMHasLabel(petsclib::PetscLibType,dm::PetscDM, name::String)

Determine whether the DM has a label of a given name

Not Collective

Input Parameters:

• dm - The DM object
• name - The label name

Output Parameter:

• hasLabel - PETSC_TRUE if the label is present

Level: intermediate

See also:

DM, DMLabel, DMGetLabel(), DMGetLabelByNum(), DMCreateLabel(), DMGetLabelValue(), DMSetLabelValue(), DMGetStratumIS()

External Links

• PETSc Manual: DM/DMHasLabel

exists::PetscBool = DMHasNamedGlobalVector(petsclib::PetscLibType,dm::PetscDM, name::String)

check for a named, persistent global vector created with DMGetNamedGlobalVector()

Not Collective

Input Parameters:

• dm - DM to hold named vectors
• name - unique name for Vec

Output Parameter:

• exists - true if the vector was previously created

Level: developer

-seealso: DM, DMGetNamedGlobalVector(), DMRestoreNamedLocalVector(), DMClearNamedGlobalVectors()

External Links

• PETSc Manual: DM/DMHasNamedGlobalVector

exists::PetscBool = DMHasNamedLocalVector(petsclib::PetscLibType,dm::PetscDM, name::String)

check for a named, persistent local vector created with DMGetNamedLocalVector()

Not Collective

Input Parameters:

• dm - DM to hold named vectors
• name - unique name for Vec

Output Parameter:

• exists - true if the vector was previously created

Level: developer

-seealso: DM, DMGetNamedGlobalVector(), DMRestoreNamedLocalVector(), DMClearNamedLocalVectors()

External Links

• PETSc Manual: DM/DMHasNamedLocalVector

flg::PetscBool = DMHasVariableBounds(petsclib::PetscLibType,dm::PetscDM)

does the DM object have a variable bounds function?

Not Collective

Input Parameter:

• dm - the DM object to destroy

Output Parameter:

• flg - PETSC_TRUE if the variable bounds function exists

Level: developer

See also:

DM, DMComputeVariableBounds(), DMView(), DMCreateGlobalVector(), DMCreateInterpolation(), DMCreateColoring(), DMCreateMatrix(), DMCreateMassMatrix(), DMGetApplicationContext()

External Links

• PETSc Manual: DM/DMHasVariableBounds

DMInitializePackage(petsclib::PetscLibType)

This function initializes everything in the DM package. It is called from PetscDLLibraryRegister_petscdm() when using dynamic libraries, and on the first call to DMCreate() or similar routines when using shared or static libraries.

Level: developer

-seealso: PetscInitialize()

External Links

• PETSc Manual: DM/DMInitializePackage

DMInterpolate(petsclib::PetscLibType,coarse::PetscDM, interp::PetscMat, fine::PetscDM)

interpolates user

Collective if any hooks are

Input Parameters:

• coarse - coarser DM to use as a base
• interp - interpolation matrix, apply using MatInterpolate()
• fine - finer DM to update

Level: developer

Developer Note: This routine is called DMInterpolate() while the hook is called DMRefineHookAdd(). It would be better to have an an API with consistent terminology.

See also:

DM, DMRefineHookAdd(), MatInterpolate()

External Links

• PETSc Manual: DM/DMInterpolate

DMInterpolateSolution(petsclib::PetscLibType,coarse::PetscDM, fine::PetscDM, interp::PetscMat, coarseSol::PetscVec, fineSol::PetscVec)

Interpolates a solution from a coarse mesh to a fine mesh.

Collective

Input Parameters:

• coarse - coarse DM
• fine - fine DM
• interp - (optional) the matrix computed by DMCreateInterpolation(). Implementations may not need this, but if it

is available it can avoid some recomputation. If it is provided, MatInterpolate() will be used if the coarse DM does not have a specialized implementation.

• coarseSol - solution on the coarse mesh

Output Parameter:

• fineSol - the interpolation of coarseSol to the fine mesh

Level: developer

Note: This function exists because the interpolation of a solution vector between meshes is not always a linear map. For example, if a boundary value problem has an inhomogeneous Dirichlet boundary condition that is compressed out of the solution vector. Or if interpolation is inherently a nonlinear operation, such as a method using slope-limiting reconstruction.

Developer Note: This doesn't just interpolate "solutions" so its API name is questionable.

See also:

DM, DMInterpolate(), DMCreateInterpolation()

External Links

• PETSc Manual: DM/DMInterpolateSolution

DMInterpolationAddPoints(petsclib::PetscLibType,ctx::DMInterpolationInfo, n::PetscInt, points::Vector{PetscReal})

Add points at which we will interpolate the fields

Not Collective

Input Parameters:

• ctx - the context
• n - the number of points
• points - the coordinates for each point, an array of size n * dim

Level: intermediate

Note: The input coordinate information is copied into the object.

See also:

DM, DMInterpolationInfo, DMInterpolationSetDim(), DMInterpolationEvaluate(), DMInterpolationCreate()

External Links

• PETSc Manual: DM/DMInterpolationAddPoints

ctx::DMInterpolationInfo = DMInterpolationCreate(petsclib::PetscLibType,comm::MPI_Comm)

Creates a DMInterpolationInfo context

Collective

Input Parameter:

• comm - the communicator

Output Parameter:

• ctx - the context

Level: beginner

Developer Note: The naming is incorrect, either the object should be named DMInterpolation or all the routines should begin with DMInterpolationInfo

See also:

DM, DMInterpolationInfo, DMInterpolationEvaluate(), DMInterpolationAddPoints(), DMInterpolationDestroy()

External Links

• PETSc Manual: DM/DMInterpolationCreate

DMInterpolationDestroy(petsclib::PetscLibType,ctx::DMInterpolationInfo)

Destroys a DMInterpolationInfo context

Collective

Input Parameter:

• ctx - the context

Level: beginner

See also:

DM, DMInterpolationInfo, DMInterpolationEvaluate(), DMInterpolationAddPoints(), DMInterpolationCreate()

External Links

• PETSc Manual: DM/DMInterpolationDestroy

DMInterpolationEvaluate(petsclib::PetscLibType,ctx::DMInterpolationInfo, dm::PetscDM, x::PetscVec, v::PetscVec)

Using the input from dm and x, calculates interpolated field values at the interpolation points.

Input Parameters:

• ctx - The DMInterpolationInfo context obtained with DMInterpolationCreate()
• dm - The DM
• x - The local vector containing the field to be interpolated, can be created with DMCreateGlobalVector()

Output Parameter:

• v - The vector containing the interpolated values, obtained with DMInterpolationGetVector()

Level: beginner

See also:

DM, DMInterpolationInfo, DMInterpolationGetVector(), DMInterpolationAddPoints(), DMInterpolationCreate(), DMInterpolationGetCoordinates()

External Links

• PETSc Manual: DM/DMInterpolationEvaluate

DMInterpolationGetCoordinates(petsclib::PetscLibType,ctx::DMInterpolationInfo, coordinates::PetscVec)

Gets a Vec with the coordinates of each interpolation point

Collective

Input Parameter:

• ctx - the context

Output Parameter:

• coordinates - the coordinates of interpolation points

Level: intermediate

Note: The local vector entries correspond to interpolation points lying on this process, according to the associated DM. This is a borrowed vector that the user should not destroy.

See also:

DM, DMInterpolationInfo, DMInterpolationEvaluate(), DMInterpolationAddPoints(), DMInterpolationCreate()

External Links

• PETSc Manual: DM/DMInterpolationGetCoordinates

dim::PetscInt = DMInterpolationGetDim(petsclib::PetscLibType,ctx::DMInterpolationInfo)

Gets the spatial dimension for the interpolation context

Not Collective

Input Parameter:

• ctx - the context

Output Parameter:

• dim - the spatial dimension

Level: intermediate

See also:

DM, DMInterpolationInfo, DMInterpolationSetDim(), DMInterpolationEvaluate(), DMInterpolationAddPoints()

External Links

• PETSc Manual: DM/DMInterpolationGetDim

dof::PetscInt = DMInterpolationGetDof(petsclib::PetscLibType,ctx::DMInterpolationInfo)

Gets the number of fields interpolated at a point for the interpolation context

Not Collective

Input Parameter:

• ctx - the context

Output Parameter:

• dof - the number of fields

Level: intermediate

See also:

DM, DMInterpolationInfo, DMInterpolationSetDof(), DMInterpolationEvaluate(), DMInterpolationAddPoints()

External Links

• PETSc Manual: DM/DMInterpolationGetDof

DMInterpolationGetVector(petsclib::PetscLibType,ctx::DMInterpolationInfo, v::PetscVec)

Gets a Vec which can hold all the interpolated field values

Collective

Input Parameter:

• ctx - the context

Output Parameter:

• v - a vector capable of holding the interpolated field values

Level: intermediate

Note: This vector should be returned using DMInterpolationRestoreVector().

See also:

DM, DMInterpolationInfo, DMInterpolationRestoreVector(), DMInterpolationEvaluate(), DMInterpolationAddPoints(), DMInterpolationCreate()

External Links

• PETSc Manual: DM/DMInterpolationGetVector

DMInterpolationRestoreVector(petsclib::PetscLibType,ctx::DMInterpolationInfo, v::PetscVec)

Returns a Vec which can hold all the interpolated field values

Collective

Input Parameters:

• ctx - the context
• v - a vector capable of holding the interpolated field values

Level: intermediate

See also:

DM, DMInterpolationInfo, DMInterpolationGetVector(), DMInterpolationEvaluate(), DMInterpolationAddPoints(), DMInterpolationCreate()

External Links

• PETSc Manual: DM/DMInterpolationRestoreVector

DMInterpolationSetDim(petsclib::PetscLibType,ctx::DMInterpolationInfo, dim::PetscInt)

Sets the spatial dimension for the interpolation context

Not Collective

Input Parameters:

• ctx - the context
• dim - the spatial dimension

Level: intermediate

See also:

DM, DMInterpolationInfo, DMInterpolationGetDim(), DMInterpolationEvaluate(), DMInterpolationAddPoints()

External Links

• PETSc Manual: DM/DMInterpolationSetDim

DMInterpolationSetDof(petsclib::PetscLibType,ctx::DMInterpolationInfo, dof::PetscInt)

Sets the number of fields interpolated at a point for the interpolation context

Not Collective

Input Parameters:

• ctx - the context
• dof - the number of fields

Level: intermediate

See also:

DM, DMInterpolationInfo, DMInterpolationGetDof(), DMInterpolationEvaluate(), DMInterpolationAddPoints()

External Links

• PETSc Manual: DM/DMInterpolationSetDof

DMInterpolationSetUp(petsclib::PetscLibType,ctx::DMInterpolationInfo, dm::PetscDM, redundantPoints::PetscBool, ignoreOutsideDomain::PetscBool)

Compute spatial indices for point location during interpolation

Collective

Input Parameters:

• ctx - the context
• dm - the DM for the function space used for interpolation
• redundantPoints - If PETSC_TRUE, all processes are passing in the same array of points. Otherwise, points need to be communicated among processes.
• ignoreOutsideDomain - If PETSC_TRUE, ignore points outside the domain, otherwise return an error

Level: intermediate

See also:

DM, DMInterpolationInfo, DMInterpolationEvaluate(), DMInterpolationAddPoints(), DMInterpolationCreate()

External Links

• PETSc Manual: DM/DMInterpolationSetUp

isBd::PetscBool = DMIsBoundaryPoint(petsclib::PetscLibType,dm::PetscDM, point::PetscInt)

External Links

• PETSc Manual: DM/DMIsBoundaryPoint

isForest::PetscBool = DMIsForest(petsclib::PetscLibType,dm::PetscDM)

Check whether a DM uses the DMFOREST interface for hierarchically

Not Collective

Input Parameter:

• dm - the DM object

Output Parameter:

• isForest - whether dm is a subtype of DMFOREST

Level: intermediate

-seealso: DMFOREST, DMForestRegisterType()

External Links

• PETSc Manual: DM/DMIsForest

DMKSPGetComputeInitialGuess(petsclib::PetscLibType,dm::PetscDM, func::KSPComputeInitialGuessFn, ctx::Cvoid)

get KSP initial guess evaluation function

Not Collective

Input Parameter:

• dm - DM used with a KSP

Output Parameters:

• func - initial guess evaluation function, for calling sequence see KSPComputeInitialGuessFn
• ctx - context for right-hand side evaluation

Level: advanced

-seealso: , DMKSP, DM, KSP, DMKSPSetContext(), KSPSetComputeRHS(), DMKSPSetComputeRHS(), KSPComputeInitialGuessFn

External Links

• PETSc Manual: Ksp/DMKSPGetComputeInitialGuess

DMKSPGetComputeOperators(petsclib::PetscLibType,dm::PetscDM, func::KSPComputeOperatorsFn, ctx::Cvoid)

get KSP matrix evaluation function

Not Collective

Input Parameter:

• dm - DM used with a KSP

Output Parameters:

• func - matrix evaluation function, for calling sequence see KSPComputeOperatorsFn
• ctx - context for matrix evaluation

Level: developer

-seealso: , DMKSP, DM, KSP, DMKSPSetContext(), KSPSetComputeOperators(), DMKSPSetComputeOperators(), KSPComputeOperatorsFn

External Links

• PETSc Manual: Ksp/DMKSPGetComputeOperators

DMKSPGetComputeRHS(petsclib::PetscLibType,dm::PetscDM, func::KSPComputeRHSFn, ctx::Cvoid)

get KSP right

Not Collective

Input Parameter:

• dm - DM to be used with KSP

Output Parameters:

• func - right-hand side evaluation function, for calling sequence see KSPComputeRHSFn
• ctx - context for right-hand side evaluation