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 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 toCeedElemRestrictionApplyUnsigned()
.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 thatrstr_copy
is a pointer to a CeedElemRestriction. This CeedElemRestriction will be destroyed ifrstr_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