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 requre 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 object where the CeedElemRestriction will be created
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 object where the CeedElemRestriction will be created
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] Array of shape [num_elem, elem_size] with bool 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 object where the CeedElemRestriction will be created
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(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 object where the CeedElemRestriction will be created
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 with vectors created by a 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 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 object where the CeedElemRestriction will be created
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 called by backends.

Backend Developer Functions

Parameters:

ceed – [in] Ceed object where the CeedElemRestriction will be created
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 called by backends.

Backend Developer Functions

Parameters:

ceed – [in] Ceed object where the CeedElemRestriction will be created.
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] Array of shape [num_elem, elem_size] with bool 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 called by backends.

Backend Developer Functions

Parameters:

ceed – [in] Ceed object where the CeedElemRestriction will be created.
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(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 called by backends.

User Functions

Parameters:

ceed – [in] Ceed object where the CeedElemRestriction will be created
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 with vectors created by a 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 CeedVectors 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_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 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

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 l-vector for a points CeedElemRestriction.

User Functions

Parameters:

rstr – [in] CeedElemRestriction
num_points – [out] The number of points in the l-vector

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 points CeedElemRestriction.

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 CeedElemRestrictionGetMaxPointsInElement(CeedElemRestriction rstr, CeedInt *max_points)

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

Advanced Functions

Parameters:

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

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetLVectorSize(CeedElemRestriction rstr, CeedSize *l_size)

Get the size of the l-vector for a CeedElemRestriction.

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
l_size – [out] Variable to store number of nodes

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetNumComponents(CeedElemRestriction rstr, CeedInt *num_comp)

Get the number of components in the elements of a CeedElemRestriction.

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
num_comp – [out] Variable to store number of components

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetNumBlocks(CeedElemRestriction rstr, CeedInt *num_block)

Get the number of blocks in a CeedElemRestriction.

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
num_block – [out] Variable to store number of blocks

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetBlockSize(CeedElemRestriction rstr, CeedInt *block_size)

Get the size of blocks in the CeedElemRestriction.

Advanced Functions

Parameters:

rstr – [in] CeedElemRestriction
block_size – [out] Variable to store size of blocks

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionGetMultiplicity(CeedElemRestriction rstr, CeedVector mult)

Get the multiplicity of nodes in a CeedElemRestriction.

User Functions

Parameters:

rstr – [in] CeedElemRestriction
mult – [out] Vector to store multiplicity (of size l_size)

Returns:

An error code: 0 - success, otherwise - failure

int CeedElemRestrictionView(CeedElemRestriction rstr, FILE *stream)

View a CeedElemRestriction.

User Functions

Parameters:

rstr – [in] CeedElemRestriction to view
stream – [in] Stream to write; typically stdout/stderr or a file

Returns:

Error code: 0 - success, otherwise - failure

int CeedElemRestrictionDestroy(CeedElemRestriction *rstr)

Destroy a CeedElemRestriction.

User Functions

Parameters:

rstr – [inout] CeedElemRestriction to destroy

Returns:

An error code: 0 - success, otherwise - failure