sphinx/source/libCEEDdev.md

6 …iating a different {ref}`Ceed` object to create the other libCEED objects, in a [bridge pattern](h…
9 …, developers should place the function definitions for the user facing API in the header `/include…
10 The basic implementation of these functions should typically be placed in `/interface/*.c` files.
12 …e associated libCEED object can be added in `/include/ceed-impl.h`, with a corresponding `CEED_FTA…
13 Then in the creation of the backend specific implementation of the object, typically found in `/bac…
14 …pplemental functions intended to be used in the interface or by the backends may be added to the b…
15 The basic implementation of these functions should also be placed in `/interface/*.c` files.
18 …ons, it is generally recommended to include a basic CPU default implementation in `/interface/*.c`.
20 Once the user facing API and the default implementation are in place and verified correct via tests…
37 …Like the delegates above, this fallback {ref}`Ceed` object should be created and set in the backen…
38 …In order to use operator fallback, the parent backend and fallback backend must use compatible E-v…
56 …ackends update the {ref}`CeedOperator` to apply the action of the operator in 1 or 8 element batch…
73 In these backends, the operator is applied in multiple separate kernel launches, following the libC…
74 These kernels apply to all points across all elements in order to maximize the amount of work each …
97 …Data for node `i`, component `j`, element `k` can be found in the L-vector at index `offsets[i + k…
99 …Data for node `i`, component `j`, element `k` can be found in the L-vector at index `i*strides[0] …
104 …ed E-vector layout, then the data for node `i`, component `j`, element `k` in the E-vector is give…
105 …s will not function correctly in this case and these tests will need to be marked as allowable fai…
109 … `i` component `j` can be found in the Q-vector at index `i + Q*j`, where `Q` is the total number …
110     Backends are free to provide the quadrature points in any order.
111 … data for quadrature point `i`, component `j`, derivative `k` can be found in the Q-vector at inde…
112 …- Backend developers must take special care to ensure that the data in the Q-vectors for a field w…
121 …memory location that contains valid data, then the {ref}`CeedVector` is left in an *invalid state*.
131   - {c:func}`CeedVectorTakeArray` cannot be called on a vector in a *invalid state*.
138     The user is responsible for manually setting the contents of the array in this case.
142 …zation and user calls to {c:func}`CeedVectorSync` cannot be made on a vector in an *invalid state*.
143 …torGetArray` and {c:func}`CeedVectorGetArrayRead` cannot be made on a vector in an *invalid state*.
144 …CeedVectorSetArray` and {c:func}`CeedVectorSetValue` can be made on a vector in an *invalid state*.
145   - Calls to {c:func}`CeedVectorGetArrayWrite` can be made on a vector in an *invalid* state.
188 That is, each input and output array must reside in distinct memory without overlap.
196 In addition to those automatically enforced style rules, libCEED tends to follow the following code…
204 In general, variable and function names should avoid abbreviations and err on the side of verbosity…
211 All functions in the libCEED library should be prefixed by `Ceed` and generally take a `Ceed` objec…
228 2. Local variables should be initialized in their declaration when possible.
232    This should be wrapped around the function in question.
233 6. In libCEED functions, variables must be declared at the beginning of the code block (C90 style),…
234 …However, when variables are only used in a limited scope, it is encouraged to declare them in that…
238 …tags for each parameter, a newline, and a `@return` line formatted exactly as in the example below.
239 …All parameter lines in the Doxygen block should be formatted such that parameter names and descrip…
240 …There should be a exactly one space between `@param[dir]` (where `dir` is `in`, `out`, or `in,out`…
246 …Note: Prefixing the resource with "help:" (e.g. "help:/cpu/self") will result in @ref CeedInt() pr…
248   @param[in]  resource Resource to use, e.g., "/cpu/self"
259 9. Function declarations should include parameter names, which must exactly match those in the func…
260 10. External functions, i.e. those used in tests or examples, must have their *declarations* prefix…
270 which uses the `clang-tidy` utility included in recent releases of Clang.
283 Every symbol that is used in the source file `foo.c` should be defined in `foo.c`, `foo.h`, or in a…
285 …ed; however this rule is flexible to account for differences in header file organization in extern…
286 If you have `include-what-you-use` installed in a sibling directory to libCEED or set the environme…
288 Header files should be listed in alphabetical order, with installed headers preceding local headers…
289 The `ceed-f64.h` and `ceed-f32.h` headers should only be included in `ceed.h`.