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