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
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 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 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