Skip to content

doc - document CI information #1975

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
jeremylt wants to merge 1 commit into
base: main
Choose a base branch
from
+46 −0
Open

doc - document CI information #1975

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 46 additions & 0 deletions doc/sphinx/source/libCEEDdev.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
Expand All @@ -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.
Expand All @@ -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`.
Expand All @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand Down Expand Up @@ -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
Expand All @@ -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.
Expand All @@ -299,3 +316,32 @@ 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`

When managing the installed dependencies, use the `phypid` account.

The following dependencies are built on the fly and cached:

* LIBXSMM

* Nek5000

* MFEM
Loading