CeedElemRestriction

A CeedElemRestriction decomposes elements and groups the degrees of freedom (DoFs) according to the different elements they belong to.

Expressing element decomposition and degrees of freedom over a mesh

typedef struct CeedElemRestriction_private *CeedElemRestriction: Handle for object describing restriction to elements.

const CeedInt CEED_STRIDES_BACKEND[3] = {0}: Indicate that the stride is determined by the backend.

const CeedElemRestriction CEED_ELEMRESTRICTION_NONE = &ceed_elemrestriction_none: Argument for CeedOperatorSetField() indicating that the field does not require a CeedElemRestriction

int CeedElemRestrictionCreate(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr)

Create a CeedElemRestriction

User Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array
elem_size – [in] Size (number of “nodes”) per element
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
comp_stride – [in] Stride between components for the same L-vector “node”. Data for node i, component j, element k can be found in the L-vector at index offsets[i + k*elem_size] + j*comp_stride.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of shape [num_elem, elem_size]. Row i holds the ordered list of the offsets (into the input CeedVector) for the unknowns corresponding to element i, where 0 <= i < num_elem. All offsets must be in the range [0, l_size - 1].
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, const bool *orients, CeedElemRestriction *rstr)

Create a CeedElemRestriction with orientation signs.

User Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array
elem_size – [in] Size (number of “nodes”) per element
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
comp_stride – [in] Stride between components for the same L-vector “node”. Data for node i, component j, element k can be found in the L-vector at index offsets[i + k*elem_size] + j*comp_stride.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of shape [num_elem, elem_size]. Row i holds the ordered list of the offsets (into the input CeedVector) for the unknowns corresponding to element i, where 0 <= i < num_elem. All offsets must be in the range [0, l_size - 1].
orients – [in] Boolean array of shape [num_elem, elem_size] with false for positively oriented and true to flip the orientation
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateCurlOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, const CeedInt8 *curl_orients, CeedElemRestriction *rstr)

Create a CeedElemRestriction with a general tridiagonal transformation matrix for curl-conforming elements.

User Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array
elem_size – [in] Size (number of “nodes”) per element
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
comp_stride – [in] Stride between components for the same L-vector “node”. Data for node i, component j, element k can be found in the L-vector at index offsets[i + k*elem_size] + j*comp_stride.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of shape [num_elem, elem_size]. Row i holds the ordered list of the offsets (into the input CeedVector) for the unknowns corresponding to element i, where 0 <= i < num_elem. All offsets must be in the range [0, l_size - 1].
curl_orients – [in] Array of shape [num_elem, 3 * elem_size] representing a row-major tridiagonal matrix (curl_orients[i * 3 * elem_size] = curl_orients[(i + 1) * 3 * elem_size - 1] = 0, where 0 <= i < num_elem) which is applied to the element unknowns upon restriction. This orientation matrix allows for pairs of face degrees of freedom on elements for \(H(\mathrm{curl})\) spaces to be coupled in the element restriction operation, which is a way to resolve face orientation issues for 3D meshes (https://dl.acm.org/doi/pdf/10.1145/3524456).
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt num_comp, CeedSize l_size, const CeedInt strides[3], CeedElemRestriction *rstr)

Create a strided CeedElemRestriction

User Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described by the restriction
elem_size – [in] Size (number of “nodes”) per element
num_comp – [in] Number of field components per interpolation “node” (1 for scalar fields)
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
strides – [in] Array for strides between [nodes, components, elements]. Data for node i, component j, element k can be found in the L-vector at index i*strides[0] + j*strides[1] + k*strides[2]. CEED_STRIDES_BACKEND may be used for CeedVector ordered by the same Ceed backend. CEED_STRIDES_BACKEND should only be used pass data between CeedOperator created with the same Ceed backend. The L-vector layout will, in general, be different between Ceed backends.
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateAtPoints(Ceed ceed, CeedInt num_elem, CeedInt num_points, CeedInt num_comp, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr)

Create a points CeedElemRestriction, for restricting for restricting from a all local points to the current element in which they are located.

The offsets array is arranged as

element_0_start_index element_1_start_index … element_n_start_index element_n_stop_index element_0_point_0 element_0_point_1 …

Backend Developer Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array
num_points – [in] Number of points described in the offsets array
num_comp – [in] Number of field components per interpolation node (1 for scalar fields). Components are assumed to be contiguous by point.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of size num_elem + 1 + num_points. The first portion of the offsets array holds the ranges of indices corresponding to each element. The second portion holds the indices for each element.
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateBlocked(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, CeedElemRestriction *rstr)

Create a blocked CeedElemRestriction, typically only used by backends.

Backend Developer Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array
elem_size – [in] Size (number of unknowns) per element
block_size – [in] Number of elements in a block
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
comp_stride – [in] Stride between components for the same L-vector “node”. Data for node i, component j, element k can be found in the L-vector at index offsets[i + k*elem_size] + j*comp_stride.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of shape [num_elem, elem_size]. Row i holds the ordered list of the offsets (into the input CeedVector) for the unknowns corresponding to element i, where 0 <= i < num_elem. All offsets must be in the range [0, l_size - 1]. The backend will permute and pad this array to the desired ordering for the blocksize, which is typically given by the backend. The default reordering is to interlace elements.
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateBlockedOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, const bool *orients, CeedElemRestriction *rstr)

Create a blocked oriented CeedElemRestriction, typically only used by backends.

Backend Developer Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array.
elem_size – [in] Size (number of unknowns) per element
block_size – [in] Number of elements in a block
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
comp_stride – [in] Stride between components for the same L-vector “node”. Data for node i, component j, element k can be found in the L-vector at index offsets[i + k*elem_size] + j*comp_stride.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of shape [num_elem, elem_size]. Row i holds the ordered list of the offsets (into the input CeedVector) for the unknowns corresponding to element i, where 0 <= i < num_elem. All offsets must be in the range [0, l_size - 1]. The backend will permute and pad this array to the desired ordering for the blocksize, which is typically given by the backend. The default reordering is to interlace elements.
orients – [in] Boolean array of shape [num_elem, elem_size] with false for positively oriented and true to flip the orientation. Will also be permuted and padded similarly to offsets.
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateBlockedCurlOriented(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, CeedInt comp_stride, CeedSize l_size, CeedMemType mem_type, CeedCopyMode copy_mode, const CeedInt *offsets, const CeedInt8 *curl_orients, CeedElemRestriction *rstr)

Create a blocked curl-oriented CeedElemRestriction, typically only used by backends.

Backend Developer Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described in the offsets array.
elem_size – [in] Size (number of unknowns) per element
block_size – [in] Number of elements in a block
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
comp_stride – [in] Stride between components for the same L-vector “node”. Data for node i, component j, element k can be found in the L-vector at index offsets[i + k*elem_size] + j*comp_stride.
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
mem_type – [in] Memory type of the offsets array, see CeedMemType
copy_mode – [in] Copy mode for the offsets array, see CeedCopyMode
offsets – [in] Array of shape [num_elem, elem_size]. Row i holds the ordered list of the offsets (into the input CeedVector) for the unknowns corresponding to element i, where 0 <= i < num_elem. All offsets must be in the range [0, l_size - 1]. The backend will permute and pad this array to the desired ordering for the blocksize, which is typically given by the backend. The default reordering is to interlace elements.
curl_orients – [in] Array of shape [num_elem, 3 * elem_size] representing a row-major tridiagonal matrix (curl_orients[i * 3 * elem_size] = curl_orients[(i + 1) * 3 * elem_size - 1] = 0, where 0 <= i < num_elem) which is applied to the element unknowns upon restriction. This orientation matrix allows for pairs of face degrees of freedom on elements for \(H(\mathrm{curl})\) spaces to be coupled in the element restriction operation, which is a way to resolve face orientation issues for 3D meshes (https://dl.acm.org/doi/pdf/10.1145/3524456). Will also be permuted and padded similarly to offsets.
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateBlockedStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt block_size, CeedInt num_comp, CeedSize l_size, const CeedInt strides[3], CeedElemRestriction *rstr)

Create a blocked strided CeedElemRestriction, typically only used by backends.

User Functions

Parameters:

ceed – [in] Ceed context used to create the CeedElemRestriction
num_elem – [in] Number of elements described by the restriction
elem_size – [in] Size (number of “nodes”) per element
block_size – [in] Number of elements in a block
num_comp – [in] Number of field components per interpolation node (1 for scalar fields)
l_size – [in] The size of the L-vector. This vector may be larger than the elements and fields given by this restriction.
strides – [in] Array for strides between [nodes, components, elements]. Data for node i, component j, element k can be found in the L-vector at index i*strides[0] + j*strides[1] +k*strides[2]. CEED_STRIDES_BACKEND may be used for CeedVector ordered by the same Ceed backend.
rstr – [out] Address of the variable where the newly created CeedElemRestriction will be stored

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateUnsignedCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_unsigned)

Copy the pointer to a CeedElemRestriction and set CeedElemRestrictionApply() implementation to use the unsigned version.

Both pointers should be destroyed with CeedElemRestrictionDestroy().

User Functions

Parameters:

rstr – [in] CeedElemRestriction to create unsigned reference to
rstr_unsigned – [inout] Variable to store unsigned CeedElemRestriction

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateUnorientedCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_unoriented)

Copy the pointer to a CeedElemRestriction and set CeedElemRestrictionApply() implementation to use the unoriented version.

Both pointers should be destroyed with CeedElemRestrictionDestroy().

User Functions

Parameters:

rstr – [in] CeedElemRestriction to create unoriented reference to
rstr_unoriented – [inout] Variable to store unoriented CeedElemRestriction

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionReferenceCopy(CeedElemRestriction rstr, CeedElemRestriction *rstr_copy)

Copy the pointer to a CeedElemRestriction.

Both pointers should be destroyed with CeedElemRestrictionDestroy().

Note: If the value of *rstr_copy passed into this function is non-NULL, then it is assumed that *rstr_copy is a pointer to a CeedElemRestriction. This CeedElemRestriction will be destroyed if *rstr_copy is the only reference to this CeedElemRestriction.

User Functions

Parameters:

rstr – [in] CeedElemRestriction to copy reference to
rstr_copy – [inout] Variable to store copied reference

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionCreateVector(CeedElemRestriction rstr, CeedVector *l_vec, CeedVector *e_vec)

Create CeedVector associated with a CeedElemRestriction

User Functions

Parameters:

rstr – [in] CeedElemRestriction
l_vec – [out] The address of the L-vector to be created, or NULL
e_vec – [out] The address of the E-vector to be created, or NULL

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionApply(CeedElemRestriction rstr, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, CeedRequest *request)

Restrict an L-vector to an E-vector or apply its transpose.

User Functions

Parameters:

rstr – [in] CeedElemRestriction
t_mode – [in] Apply restriction or transpose
u – [in] Input vector (of size l_size when t_mode = CEED_NOTRANSPOSE)
ru – [out] Output vector (of shape [num_elem * elem_size] when t_mode = CEED_NOTRANSPOSE). Ordering of the e-vector is decided by the backend.
request – [in] Request or CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionApplyAtPointsInElement(CeedElemRestriction rstr, CeedInt elem, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, CeedRequest *request)

Restrict an L-vector of points to a single element or apply its transpose.

User Functions

Parameters:

rstr – [in] CeedElemRestriction
elem – [in] Element number in range [0, num_elem)
t_mode – [in] Apply restriction or transpose
u – [in] Input vector (of size l_size when t_mode = CEED_NOTRANSPOSE)
ru – [out] Output vector (of shape [num_points * num_comp] when t_mode = CEED_NOTRANSPOSE). Ordering of the e-vector is decided by the backend.
request – [in] Request or CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionApplyBlock(CeedElemRestriction rstr, CeedInt block, CeedTransposeMode t_mode, CeedVector u, CeedVector ru, CeedRequest *request)

Restrict an L-vector to a block of an E-vector or apply its transpose.

Backend Developer Functions

Parameters:

rstr – [in] CeedElemRestriction
block – [in] Block number to restrict to/from, i.e. block = 0 will handle elements [0 : block_size] and block = 3 will handle elements [3*block_size : 4*block_size]
t_mode – [in] Apply restriction or transpose
u – [in] Input vector (of size l_size when t_mode = CEED_NOTRANSPOSE)
ru – [out] Output vector (of shape [block_size * elem_size] when t_mode = CEED_NOTRANSPOSE). Ordering of the e-vector is decided by the backend.
request – [in] Request or CEED_REQUEST_IMMEDIATE

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetCeed(CeedElemRestriction rstr, Ceed *ceed)

Get the Ceed associated with a CeedElemRestriction

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
ceed – [out] Variable to store Ceed

Returns:

An error code: 0 - success, otherwise - failure

Ceed CeedElemRestrictionReturnCeed(CeedElemRestriction rstr)

Return the Ceed associated with a CeedElemRestriction

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction

Returns:

Ceed associated with the rstr

int CeedElemRestrictionGetCompStride(CeedElemRestriction rstr, CeedInt *comp_stride)

Get the L-vector component stride.

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
comp_stride – [out] Variable to store component stride

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetNumElements(CeedElemRestriction rstr, CeedInt *num_elem)

Get the total number of elements in the range of a CeedElemRestriction

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
num_elem – [out] Variable to store number of elements

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetElementSize(CeedElemRestriction rstr, CeedInt *elem_size)

Get the size of elements in the CeedElemRestriction

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
elem_size – [out] Variable to store size of elements

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetNumPoints(CeedElemRestriction rstr, CeedInt *num_points)

Get the number of points in the offsets array for a points CeedElemRestriction

User Functions

Parameters:

rstr – [in] CeedElemRestriction
num_points – [out] The number of points in the offsets array

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetNumPointsInElement(CeedElemRestriction rstr, CeedInt elem, CeedInt *num_points)

Get the number of points in an element of a CeedElemRestriction at points.

User Functions

Parameters:

rstr – [in] CeedElemRestriction
elem – [in] Index number of element to retrieve the number of points for
num_points – [out] The number of points in the element at index elem

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetMinMaxPointsInElement(CeedElemRestriction rstr, CeedInt *min_points, CeedInt *max_points)

Get the minimum and/or maximum number of points in an element for a CeedElemRestriction at points.

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
min_points – [out] Variable to minimum number of points in an element, or NULL
max_points – [out] Variable to maximum number of points in an element, or NULL

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetMaxPointsInElement(CeedElemRestriction rstr, CeedInt *max_points)

Get the maximum number of points in an element for a CeedElemRestriction at points.

User Functions