sphinx/source/libCEEDdev.md

12 A new method for the associated libCEED object can be added in `/include/ceed-impl.h`, with a corre…
13 … implementation of the object, typically found in `/backends/[impl]/ceed-[impl]-[object].c`, the d…
24 A Ceed backend is not required to implement all libCeed objects or {ref}`CeedOperator` methods.
27 1. Delegation - Developers may use {c:func}`CeedSetDelegate` to set a general delegate {ref}`Ceed` …
29 …l` backend implements the `CeedTensorContract` object itself but delegates all other functionality…
31 2. Object delegation  - Developers may use {c:func}`CeedSetObjectDelegate` to set a delegate {ref}`…
35 3. Operator fallback - Developers may use {c:func}`CeedSetOperatorFallbackCeed` to set a {ref}`Ceed…
38 …allback, the parent backend and fallback backend must use compatible E-vector and Q-vector layouts.
55 The `/cpu/self/ref/blocked` backend updates the {ref}`CeedOperator` to use an E-vector and Q-vector…
68 The CUDA, HIP, and SYCL backend families all follow similar designs.
73 …-vectors to E-vectors, then {ref}`CeedBasis` kernels map from the E-vectors to Q-vectors, then the…
74 These kernels apply to all points across all elements in order to maximize the amount of work each …
79 All other libCEED objects are delegated to `/gpu/*/ref`.
91 … any E-vector and Q-vector data layout (including never fully forming these vectors) so long as th…
92 There are several common layouts for L-vectors, E-vectors, and Q-vectors, detailed below:
94 - **L-vector** layouts
96 …- L-vectors described by a standard {ref}`CeedElemRestriction` have a layout described by the `off…
97 …Data for node `i`, component `j`, element `k` can be found in the L-vector at index `offsets[i + k…
98 …- L-vectors described by a strided {ref}`CeedElemRestriction` have a layout described by the `stri…
99 …Data for node `i`, component `j`, element `k` can be found in the L-vector at index `i*strides[0] …
101 - **E-vector** layouts
103 …- If possible, backends should use {c:func}`CeedElemRestrictionSetELayout()` to use the `t2**` tes…
104 …If the backend uses a strided E-vector layout, then the data for node `i`, component `j`, element …
105 …- Backends may choose to use a non-strided E-vector layout; however, the `t2**` tests will not fun…
107 - **Q-vector** layouts
109 …- When the size of a {ref}`CeedQFunction` field is greater than `1`, data for quadrature point `i`…
111 …- When the {ref}`CeedQFunction` field has `emode` `CEED_EVAL_GRAD`, data for quadrature point `i`,…
112 …- Backend developers must take special care to ensure that the data in the Q-vectors for a field w…
125 All backends may assume that array access will conform to these guidelines:
127 - Borrowed memory
129 …- {ref}`CeedVector` access to borrowed memory is set with {c:func}`CeedVectorSetArray` with `copy_…
131   - {c:func}`CeedVectorTakeArray` cannot be called on a vector in a *invalid state*.
133 - Owned memory
135 …- Owned memory can be allocated by calling {c:func}`CeedVectorSetValue` or by calling {c:func}`Cee…
136 …- Owned memory can be set by calling {c:func}`CeedVectorSetArray` with `copy_mode = CEED_OWN_POINT…
137   - Owned memory can also be allocated by calling {c:func}`CeedVectorGetArrayWrite`.
140 - Data validity
142 …- Internal synchronization and user calls to {c:func}`CeedVectorSync` cannot be made on a vector i…
143 …- Calls to {c:func}`CeedVectorGetArray` and {c:func}`CeedVectorGetArrayRead` cannot be made on a v…
144 …- Calls to {c:func}`CeedVectorSetArray` and {c:func}`CeedVectorSetValue` can be made on a vector i…
145   - Calls to {c:func}`CeedVectorGetArrayWrite` can be made on a vector in an *invalid* state.
147 …The caller should assume that all data at the memory location returned by {c:func}`CeedVectorGetAr…
152 It is awkward to pass fully-specified multi-dimensional arrays using C99 and certain operations wil…
170 This ordering is sometimes referred to as row-major or C-style.
183 are purely implicit -- one just indexes the same array using the appropriate convention.
198 - Variable names: `snake_case`
199 - Strut members: `snake_case`
200 - Function and method names: `PascalCase` or language specific style
201 - Type names: `PascalCase` or language specific style
202 - Constant names: `CAPS_SNAKE_CASE` or language specific style
211 All functions in the libCEED library should be prefixed by `Ceed` and generally take a `Ceed` objec…
217 1. All local variables of a particular type (for example, `CeedInt`) should be listed on the same l…
229 3. Nearly all functions should have a return type of `int` and return a `CeedErrorType` to allow fo…
230 4. All functions must start with a single blank line after the local variable declarations.
231 5. All libCEED function calls must have their return value checked for errors using the `CeedCall()…
236 8. All libCEED functions must use Doxygen comment blocks before their *definition* (not declaration…
239 …All parameter lines in the Doxygen block should be formatted such that parameter names and descrip…
251   @return An error code: 0 - success, otherwise - failure
261     All other functions should have their *declarations* prefixed with `CEED_INTERN`.
264 ## Clang-tidy
270 which uses the `clang-tidy` utility included in recent releases of Clang.
271 This tool is much slower than actual compilation (`make -j8` parallelism helps).
277 All issues reported by `make tidy` should be fixed.
279 ## Include-What-You-Use
281 …pal of 'include what you use' rather than relying upon transitive `#include` to define all symbols.
284 Please check your code by running the tool [`include-what-you-use`](https://include-what-you-use.or…
285 Most issues reported by `include-what-you-use` should be fixed; however this rule is flexible to ac…
286 If you have `include-what-you-use` installed in a sibling directory to libCEED or set the environme…
289 The `ceed-f64.h` and `ceed-f32.h` headers should only be included in `ceed.h`.
296 #include "ceed-avx.h"