Backends often manipulate tensors of dimension greater than 2. It is awkward to pass fully-specified multi-dimensional arrays using C99 and certain operations will flatten/reshape the tensors for computational convenience. We frequently use comments to document shapes using a lexicographic ordering. For example, the comment
// u has shape [dim, ncomp, Q, nelem]
means that it can be traversed as
for (d=0; d<dim; d++) for (c=0; c<ncomp; c++) for (q=0; q<Q; q++) for (e=0; e<nelem; e++) u[((d*ncomp + c)*Q + q)*nelem + e] = ...
This ordering is sometimes referred to as row-major or C-style. Note that flattening such as
// u has shape [dim, ncomp, Q*nelem]
// u has shape [dim*ncomp, Q, nelem]
are purely implicit – one just indexes the same array using the appropriate convention.
Ceed backends are free to use any E-vector and Q-vector data layout, to include never fully forming these vectors, so long as the backend passes the
t5** series tests and all examples.
There are several common layouts for L-vectors, E-vectors, and Q-vectors, detailed below:
L-vectors described by a CeedElemRestriction have a layout described by the
compstrideparameter. Data for node
kcan be found in the L-vector at index
offsets[i + k*elemsize] + j*compstride.
L-vectors described by a strided CeedElemRestriction have a layout described by the
stridesarray. Data for node
kcan be found in the L-vector at index
i*strides + j*strides + k*strides.
If possible, backends should use
CeedElemRestrictionSetELayout()to use the
t2**tests. If the backend uses a strided E-vector layout, then the data for node
kin the E-vector is given by
i*layout + j*layout + k*layout.
Backends may choose to use a non-strided E-vector layout; however, the
t2**tests will not function correctly in this case and the tests will need to be whitelisted for the backend to pass the test suite.
When the size of a CeedQFunction field is greater than
1, data for quadrature point
jcan be found in the Q-vector at index
i + Q*j. Backends are free to provide the quadrature points in any order.
When the CeedQFunction field has
CEED_EVAL_GRAD, data for quadrature point
kcan be found in the Q-vector at index
i + Q*j + Q*size*k.
Note that backend developers must take special care to ensure that the data in the Q-vectors for a field with
CEED_EVAL_NONEis properly ordered when the backend uses different layouts for E-vectors and Q-vectors.
There are three mechanisms by which a Ceed backend can inherit implementation from another Ceed backend. These options are set in the backend initialization routine.
Delegation - Developers may use
CeedSetDelegate()to set a backend that will provide the implementation of any unimplemented Ceed objects.
Object delegation - Developers may use
CeedSetObjectDelegate()to set a backend that will provide the implementation of a specific unimplemented Ceed object. Object delegation has higher precedence than delegation.
Operator fallback - Developers may use
CeedSetOperatorFallbackResource()to set a Ceed resource that will provide the implementation of unimplemented CeedOperator methods. A fallback Ceed with this resource will only be instantiated if a method is called that is not implemented by the parent Ceed. In order to use the fallback mechanism, the parent Ceed and fallback resource must use compatible E-vector and Q-vector layouts.
Please check your code for common issues by running
which uses the
clang-tidy utility included in recent releases of Clang. This
tool is much slower than actual compilation (
make -j8 parallelism helps). To
run on a single file, use
for example. All issues reported by
make tidy should be fixed.
Header inclusion for source files should follow the principal of ‘include what you use’ rather than relying upon transitive ``#include``s to define all symbols.
Every symbol that is used in the source file
foo.c should be defined in
foo.h, or in a header file
#include``d in one of these two locations.
Please check your code by running the tool ``include-what-you-use to see recommendations for changes to your source.
Most issues reported by
include-what-you-use should be fixed; however this rule is flexible to account for differences in header file organization in external libraries.
Header files should be listed in alphabetical order, with installed headers preceding local headers and
ceed headers being listed first.