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¶: Indicate that no CeedElemRestriction is provided by the user.

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 *orient, CeedElemRestriction *rstr)¶

Create a CeedElemRestriction with orientation sign.

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].
orient – [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 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 CeedElemRestrictionCreateBlocked(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt blk_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
blk_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 CeedElemRestrictionCreateBlockedStrided(Ceed ceed, CeedInt num_elem, CeedInt elem_size, CeedInt blk_size, CeedInt num_comp, CeedSize l_size, const CeedInt strides[3], CeedElemRestriction *rstr)¶

Create a blocked 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
blk_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 CeedElemRestrictionApplyUnsigned().

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 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 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 : blk_size] and block=3 will handle elements [3*blk_size : 4*blk_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 [blk_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 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 *blk_size)¶

Get the size of blocks in the CeedElemRestriction.

Advanced Functions

Parameters

rstr – [in] CeedElemRestriction
blk_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