doc - document CI information

Author: jeremylt

doc/sphinx/source/libCEEDdev.md

@@ -1,5 +1,6 @@
 # Developer Notes
 
+
 ## Library Design
 
 LibCEED has a single user facing API for creating and using the libCEED objects ({ref}`CeedVector`, {ref}`CeedBasis`, etc).
@@ -19,6 +20,7 @@ If there are no performance specific considerations, it is generally recommended
 Any new functions must be well documented and tested.
 Once the user facing API and the default implementation are in place and verified correct via tests, then the developer can focus on hardware specific implementations (AVX, CUDA, HIP, etc.) as necessary.
 
+
 ## Backend Inheritance
 
 A Ceed backend is not required to implement all libCEED objects or {ref}`CeedOperator` methods.
@@ -40,11 +42,13 @@ There are three mechanisms by which a Ceed backend can inherit implementations f
    If an unimplemented method is called, then the parent `/gpu/cuda/gen` {ref}`Ceed` object uses its fallback `/gpu/cuda/ref` {ref}`Ceed` object to create a clone of the {ref}`CeedOperator`.
    This clone {ref}`CeedOperator` is then used for the unimplemented preconditioning support methods.
 
+
 ## Backend Families
 
 There are 4 general 'families' of backend implementations.
 As internal data layouts are specific to backend families, it is generally not possible to delegate between backend families.
 
+
 ### CPU Backends
 
 The basic CPU with the simplest implementation is `/cpu/self/ref/serial`.
@@ -63,6 +67,7 @@ The `/cpu/self/memcheck/*` backends delegate to the `/cpu/self/ref/*` backends.
 These backends replace many of the implementations with methods that include more verification checks and a memory management model that more closely matches the memory management for GPU backends.
 These backends rely upon the [Valgrind](https://valgrind.org/) Memcheck tool and Valgrind headers.
 
+
 ### GPU Backends
 
 The CUDA, HIP, and SYCL backend families all follow similar designs.
@@ -86,6 +91,7 @@ This kernel is compiled at runtime via NVRTC, HIPRTC, or OpenCL RTC.
 The `/gpu/*/magma` backends delegate to the corresponding `/gpu/cuda/ref` and `/gpu/hip/ref` backends.
 These backends provide better performance for {ref}`CeedBasis` kernels but do not have the improvements from the `/gpu/*/gen` backends for {ref}`CeedOperator`.
 
+
 ## Internal Layouts
 
 Ceed backends are free to use any E-vector and Q-vector data layout (including never fully forming these vectors) so long as the backend passes the `t5**` series tests and all examples.
@@ -111,6 +117,7 @@ There are several common layouts for L-vectors, E-vectors, and Q-vectors, detail
   - 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*num_comp*k`.
   - 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.
 
+
 ## CeedVector Array Access
 
 Backend implementations are expected to separately track 'owned' and 'borrowed' memory locations.
@@ -146,6 +153,7 @@ All backends may assume that array access will conform to these guidelines:
     Data synchronization is not required for the memory location returned by {c:func}`CeedVectorGetArrayWrite`.
     The caller should assume that all data at the memory location returned by {c:func}`CeedVectorGetArrayWrite` is *invalid*.
 
+
 ## Shape
 
 Backends often manipulate tensors of dimension greater than 2.
@@ -182,11 +190,13 @@ and
 
 are purely implicit -- one just indexes the same array using the appropriate convention.
 
+
 ## `restrict` Semantics
 
 QFunction arguments can be assumed to have `restrict` semantics.
 That is, each input and output array must reside in distinct memory without overlap.
 
+
 ## Style Guide
 
 Please check your code for style issues by running
@@ -209,13 +219,18 @@ Single line `if` statements are acceptable, but if `clang-format` forces it to b
 This is enforced automatically for all enabled backends via `make format`, with the exception of header files in the `include/ceed/jit-source` directory.
 These files cannot be automatically formatted by `clang-tidy`, as they cannot be compiled as standalone sources.
 
+
 ## Function Conventions
 
+
 ### Naming
+
 All functions in the libCEED library should be prefixed by `Ceed` and generally take a `Ceed` object as its first argument.
 If a function takes, for example, a `CeedOperator` as its first argument, then it should be prefixed with `CeedOperator`.
 
+
 ### Style
+
 Functions should adhere mostly to the PETSc function style, specifically:
 
 1. All local variables of a particular type (for example, `CeedInt`) should be listed on the same line if possible; otherwise, they should be listed on adjacent lines. For example,
@@ -265,6 +280,7 @@ int CeedInit(const char *resource, Ceed *ceed) {
     All other functions should have their *declarations* prefixed with `CEED_INTERN`.
     Function *definitions* should have neither.
 
+
 ## Clang-tidy
 
 Please check your code for common issues by running
@@ -280,6 +296,7 @@ To run on a single file, use
 for example.
 All issues reported by `make tidy` should be fixed.
 
+
 ## Include-What-You-Use
 
 Header inclusion for source files should follow the principal of 'include what you use' rather than relying upon transitive `#include` to define all symbols.
@@ -299,3 +316,34 @@ The `ceed-f64.h` and `ceed-f32.h` headers should only be included in `ceed.h`.
 #include <string.h>
 #include "ceed-avx.h"
 ```
+
+
+## Updating CI
+
+There are two main types of CI for libCEED - GitHub Actions and GitLab Runners.
+
+The GitHub Actions focus on CPU based tests without any external dependencies, for the C, Fortran, Rust, Python, and Julia interfaces.
+The GitHub Actions can be updated as required by editing the appropriate `.yml` file in `.github/workflows`.
+
+The GitLab Runners focus on GPU based tests and external dependencies.
+The GitLab Runners can be updated as required by editing `.gitlab-ci.yml` and updating the dependencies installed on Noether.
+
+The following dependencies are installed on Noether:
+
+* MAGMA: `/projects/MAGMA` and `/projects/hipMAGMA`
+
+* PETSc: `/projects/petsc`
+
+* deal.II: `/projects/dealii`
+
+The following dependencies are built on the fly and cached:
+
+* LIBXSMM
+
+* Nek5000
+
+When managing the installed dependencies, use the `phypid` account.
+
+Note: PETSc commit `7ada2a5134eeb4113b6693316dd2660902f08a96` must be reverted for libCEED fluid dynamics examples to pass (see [issue 1686](https://github.com/CEED/libCEED/issues/1686)).
+
+* MFEM