sphinx/source/libCEEDdev.md

10 The basic implementation of these functions should typically be placed in `/interface/*.c` files.
12 …ED object can be added in `/include/ceed-impl.h`, with a corresponding `CEED_FTABLE_ENTRY` in `/in…
13 …n `/backends/[impl]/ceed-[impl]-[object].c`, the developer creates the backend implementation of t…
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`.
27 1. Delegation - Developers may use {c:func}`CeedSetDelegate` to set a general delegate {ref}`Ceed` …
31 2. Object delegation  - Developers may use {c:func}`CeedSetObjectDelegate` to set a delegate {ref}`…
35 …- Developers may use {c:func}`CeedSetOperatorFallbackCeed` to set a {ref}`Ceed` object to provide …
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…
73 …-vectors to E-vectors, then {ref}`CeedBasis` kernels map from the E-vectors to Q-vectors, then the…
91 Ceed backends are free to use any E-vector and Q-vector data layout (including never fully forming …
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…
121 If the user calls {c:func}`CeedVectorTakeArray` on the only memory location that contains valid dat…
122 …*, the user must set valid data by calling {c:func}`CeedVectorSetValue`, {c:func}`CeedVectorSetArr…
127 - Borrowed memory
129 …- {ref}`CeedVector` access to borrowed memory is set with {c:func}`CeedVectorSetArray` with `copy_…
130 … first call {c:func}`CeedVectorSetArray` with `copy_mode = CEED_USE_POINTER` for the appropriate p…
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.
146 …Data synchronization is not required for the memory location returned by {c:func}`CeedVectorGetArr…
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…
156 ```c
162 ```c
164   for (c = 0; c < num_comp; c++) {
167         u[((d*num_comp + c)*Q + q)*num_elem + e] = ...
170 This ordering is sometimes referred to as row-major or C-style.
173 ```c
179 ```c
183 are purely implicit -- one just indexes the same array using the appropriate convention.
190 ## Style Guide
192 Please check your code for style issues by running
196 In addition to those automatically enforced style rules, libCEED tends to follow the following code…
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
214 ### Style  subsection
215 Functions should adhere mostly to the PETSc function style, specifically:
218 ```c
220 CeedInt   a, b, c;
225 CeedInt a, b, c, *d, *e, **f;
233 6. In libCEED functions, variables must be declared at the beginning of the code block (C90 style),…
242 ```c
251   @return An error code: 0 - success, otherwise - failure
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).
274 `make interface/ceed.c.tidy`
279 ## Include-What-You-Use
283 Every symbol that is used in the source file `foo.c` should be defined in `foo.c`, `foo.h`, or in a…
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`.
291 ```c
296 #include "ceed-avx.h"