sphinx/source/libCEEDdev.md

5 LibCEED has a single user facing API for creating and using the libCEED objects ({ref}`CeedVector`,…
6 … backends are selected by instantiating a different {ref}`Ceed` object to create the other libCEED…
11 The interface should pass any computationally expensive or hardware specific operations to a backen…
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…
17 LibCEED generally follows a "CPU first" implementation strategy when adding new functionality to th…
18 If there are no performance specific considerations, it is generally recommended to include a basic…
24 A Ceed backend is not required to implement all libCeed objects or {ref}`CeedOperator` methods.
25 There are three mechanisms by which a Ceed backend can inherit implementations from another Ceed ba…
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 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.
40 …Ceed` object uses its fallback `/gpu/cuda/ref` {ref}`Ceed` object to create a clone of the {ref}`C…
55 The `/cpu/self/ref/blocked` backend updates the {ref}`CeedOperator` to use an E-vector and Q-vector…
63 … the implementations with methods that include more verification checks and a memory management mo…
73 …-vectors to E-vectors, then {ref}`CeedBasis` kernels map from the E-vectors to Q-vectors, then the…
83 These backends write a single comprehensive kernel to apply the action of the {ref}`CeedOperator`, …
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…
118 For any given precision and memory type, a backend should only have 'owned' or 'borrowed' memory, n…
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.
152 It is awkward to pass fully-specified multi-dimensional arrays using C99 and certain operations wil…
153 We frequently use comments to document shapes using a lexicographic ordering.
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…
212 If a function takes, for example, a `CeedOperator` as its first argument, then it should be prefixe…
217 1. All local variables of a particular type (for example, `CeedInt`) should be listed on the same l…
220 CeedInt   a, b, c;
225 CeedInt a, b, c, *d, *e, **f;
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.
234 …However, when variables are only used in a limited scope, it is encouraged to declare them in that…
235 7. Do not put a blank line immediately before `return CEED_ERROR_SUCCESS;`.
238 … description, a newline, a line stating whether the function is collective, a  newline, `@param` t…
240 …There should be a exactly one space between `@param[dir]` (where `dir` is `in`, `out`, or `in,out`…
244   @brief Initialize a `Ceed` context to use the specified resource.
246 …ll result in @ref CeedInt() printing the current libCEED version number and a list of current avai…
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).
272 To run on a single file, use
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`.
296 #include "ceed-avx.h"