1# Developer Notes 2 3## Style Guide 4 5Please check your code for style issues by running 6 7`make style` 8 9In addition to those automatically enforced style rules, libCEED tends to follow the following code style conventions: 10 11- Variable names: `snake_case` 12- Strut members: `snake_case` 13- Function and method names: `PascalCase` or language specific style 14- Type names: `PascalCase` or language specific style 15- Constant names: `CAPS_SNAKE_CASE` or language specific style 16 17Also, documentation files should have one sentence per line to help make git diffs clearer and less disruptive. 18 19## Clang-tidy 20 21Please check your code for common issues by running 22 23`make tidy` 24 25which uses the `clang-tidy` utility included in recent releases of Clang. This 26tool is much slower than actual compilation (`make -j8` parallelism helps). To 27run on a single file, use 28 29`make interface/ceed.c.tidy` 30 31for example. All issues reported by `make tidy` should be fixed. 32 33## Header Files 34 35Header inclusion for source files should follow the principal of 'include what you use' rather than relying upon transitive `#include` to define all symbols. 36 37Every symbol that is used in the source file `foo.c` should be defined in `foo.c`, `foo.h`, or in a header file ``` #include``d in one of these two locations. 38Please check your code by running the tool ``include-what-you-use ``` to see recommendations for changes to your source. 39Most 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. 40 41Header files should be listed in alphabetical order, with installed headers preceding local headers and `ceed` headers being listed first. 42 43```c 44#include <ceed.h> 45#include <ceed/backend.h> 46#include <stdbool.h> 47#include <string.h> 48#include "ceed-avx.h" 49``` 50 51## Shape 52 53Backends often manipulate tensors of dimension greater than 2. It is 54awkward to pass fully-specified multi-dimensional arrays using C99 and 55certain operations will flatten/reshape the tensors for computational 56convenience. We frequently use comments to document shapes using a 57lexicographic ordering. For example, the comment 58 59```c 60// u has shape [dim, num_comp, Q, num_elem] 61``` 62 63means that it can be traversed as 64 65```c 66for (d=0; d<dim; d++) 67 for (c=0; c<num_comp; c++) 68 for (q=0; q<Q; q++) 69 for (e=0; e<num_elem; e++) 70 u[((d*num_comp + c)*Q + q)*nnum_elemlem + e] = ... 71``` 72 73This ordering is sometimes referred to as row-major or C-style. Note 74that flattening such as 75 76```c 77// u has shape [dim, num_comp, Q*num_elem] 78``` 79 80and 81 82```c 83// u has shape [dim*num_comp, Q, num_elem] 84``` 85 86are purely implicit -- one just indexes the same array using the 87appropriate convention. 88 89## Internal Layouts 90 91Ceed 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. 92There are several common layouts for **L-vectors**, **E-vectors**, and **Q-vectors**, detailed below: 93 94- **L-vector** layouts 95 96 - **L-vectors** described by a {ref}`CeedElemRestriction` have a layout described by the `offsets` array and `comp_stride` parameter. 97 Data for node `i`, component `j`, element `k` can be found in the **L-vector** at index `offsets[i + k*elem_size] + j*comp_stride`. 98 - **L-vectors** described by a strided {ref}`CeedElemRestriction` have a layout described by the `strides` array. 99 Data for node `i`, component `j`, element `k` can be found in the **L-vector** at index `i*strides[0] + j*strides[1] + k*strides[2]`. 100 101- **E-vector** layouts 102 103 - If possible, backends should use {c:func}`CeedElemRestrictionSetELayout()` to use the `t2**` tests. 104 If the backend uses a strided **E-vector** layout, then the data for node `i`, component `j`, element `k` in the **E-vector** is given by `i*layout[0] + j*layout[1] + k*layout[2]`. 105 - 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. 106 107- **Q-vector** layouts 108 109 - When the size of a {ref}`CeedQFunction` field is greater than `1`, data for quadrature point `i` component `j` can be found in the **Q-vector** at index `i + Q*j`. 110 Backends are free to provide the quadrature points in any order. 111 - When the {ref}`CeedQFunction` field has `emode` `CEED_EVAL_GRAD`, data for quadrature point `i`, component `j`, derivative `k` can be found in the **Q-vector** at index `i + Q*j + Q*size*k`. 112 - Note that backend developers must take special care to ensure that the data in the **Q-vectors** for a field with `emode` `CEED_EVAL_NONE` is properly ordered when the backend uses different layouts for **E-vectors** and **Q-vectors**. 113 114## Backend Inheritance 115 116There are three mechanisms by which a Ceed backend can inherit implementation from another Ceed backend. 117These options are set in the backend initialization routine. 118 1191. Delegation - Developers may use {c:func}`CeedSetDelegate()` to set a backend that will provide the implementation of any unimplemented Ceed objects. 1202. Object delegation - Developers may use {c:func}`CeedSetObjectDelegate()` to set a backend that will provide the implementation of a specific unimplemented Ceed object. 121 Object delegation has higher precedence than delegation. 1223. Operator fallback - Developers may use {c:func}`CeedSetOperatorFallbackResource()` to set a {ref}`Ceed` resource that will provide the implementation of unimplemented {ref}`CeedOperator` methods. 123 A fallback {ref}`Ceed` with this resource will only be instantiated if a method is called that is not implemented by the parent {ref}`Ceed`. 124 In order to use the fallback mechanism, the parent {ref}`Ceed` and fallback resource must use compatible **E-vector** and **Q-vector** layouts. 125