doc - improve internal API documentation (#1834)

* doc - improve internal API documentation

* doc - clarify delegation

* doc - update wording for clarity

Co-authored-by: James Wright <[email protected]>

* doc - clarify memcheck==valgrind

* doc - clarify shared gpu backends

* doc - clarify l/e/q-vecs

* doc - clarify occa backend status

* doc - more inheritance clarification

* doc - minor claification to QF fields

* minor - remove unneeded variables

* doc - update inheritance language

* doc - update shared description

* doc - more gpu notes

* doc - update fallback description

* doc - clarify fallback is only for pc support

* doc - minor updates to user facing GPU section

* doc - minor reordering of major sections

---------

Co-authored-by: James Wright <[email protected]>

Author: jeremylt

backends/cuda-gen/ceed-cuda-gen.c

@@ -18,7 +18,6 @@
 //------------------------------------------------------------------------------
 static int CeedInit_Cuda_gen(const char *resource, Ceed ceed) {
   char      *resource_root;
-  const char fallback_resource[] = "/gpu/cuda/ref";
   Ceed       ceed_shared;
   Ceed_Cuda *data;
 
@@ -35,7 +34,7 @@ static int CeedInit_Cuda_gen(const char *resource, Ceed ceed) {
   CeedCallBackend(CeedSetDelegate(ceed, ceed_shared));
   CeedCallBackend(CeedDestroy(&ceed_shared));
 
-  CeedCallBackend(CeedSetOperatorFallbackResource(ceed, fallback_resource));
+  CeedCallBackend(CeedSetOperatorFallbackResource(ceed, "/gpu/cuda/ref"));
 
   CeedCallBackend(CeedSetBackendFunction(ceed, "Ceed", ceed, "QFunctionCreate", CeedQFunctionCreate_Cuda_gen));
   CeedCallBackend(CeedSetBackendFunction(ceed, "Ceed", ceed, "OperatorCreate", CeedOperatorCreate_Cuda_gen));

backends/hip-gen/ceed-hip-gen.c

@@ -17,10 +17,9 @@
 // Backend init
 //------------------------------------------------------------------------------
 static int CeedInit_Hip_gen(const char *resource, Ceed ceed) {
-  char      *resource_root;
-  const char fallback_resource[] = "/gpu/hip/ref";
-  Ceed       ceed_shared;
-  Ceed_Hip  *data;
+  char     *resource_root;
+  Ceed      ceed_shared;
+  Ceed_Hip *data;
 
   CeedCallBackend(CeedGetResourceRoot(ceed, resource, ":", &resource_root));
   CeedCheck(!strcmp(resource_root, "/gpu/hip") || !strcmp(resource_root, "/gpu/hip/gen"), ceed, CEED_ERROR_BACKEND,
@@ -35,7 +34,7 @@ static int CeedInit_Hip_gen(const char *resource, Ceed ceed) {
   CeedCallBackend(CeedSetDelegate(ceed, ceed_shared));
   CeedCallBackend(CeedDestroy(&ceed_shared));
 
-  CeedCallBackend(CeedSetOperatorFallbackResource(ceed, fallback_resource));
+  CeedCallBackend(CeedSetOperatorFallbackResource(ceed, "/gpu/hip/ref"));
 
   CeedCallBackend(CeedSetBackendFunction(ceed, "Ceed", ceed, "QFunctionCreate", CeedQFunctionCreate_Hip_gen));
   CeedCallBackend(CeedSetBackendFunction(ceed, "Ceed", ceed, "OperatorCreate", CeedOperatorCreate_Hip_gen));

backends/sycl-gen/ceed-sycl-gen.sycl.cpp

@@ -21,7 +21,6 @@ static int CeedInit_Sycl_gen(const char *resource, Ceed ceed) {
   Ceed       ceed_shared;
   Ceed_Sycl *data;
   char      *resource_root;
-  const char fallback_resource[] = "/gpu/sycl/ref";
 
   CeedCallBackend(CeedGetResourceRoot(ceed, resource, ":device_id=", &resource_root));
   CeedCheck(!strcmp(resource_root, "/gpu/sycl") || !strcmp(resource_root, "/gpu/sycl/gen"), ceed, CEED_ERROR_BACKEND,
@@ -37,7 +36,7 @@ static int CeedInit_Sycl_gen(const char *resource, Ceed ceed) {
   CeedCallBackend(CeedSetStream_Sycl(ceed_shared, &(data->sycl_queue)));
   CeedCallBackend(CeedDestroy(&ceed_shared));
 
-  CeedCallBackend(CeedSetOperatorFallbackResource(ceed, fallback_resource));
+  CeedCallBackend(CeedSetOperatorFallbackResource(ceed, "/gpu/sycl/ref"));
 
   Ceed ceed_fallback = NULL;
   CeedCallBackend(CeedGetOperatorFallbackCeed(ceed, &ceed_fallback));

doc/sphinx/source/gpu.md

@@ -7,11 +7,12 @@ Code that produces correct results with CPU backends will produce correct result
 
 The filepath to the user source code is passed in {c:func}`CeedQFunctionCreateInterior` as the `source` argument.
 This filepath should typically be an absolute path to ensure the JiT compilation can locate the source file.
-The filepath may also be relative to a root directory set with {c:func}`CeedAddJitSourceRoot`.
-The {c:macro}`CEED_QFUNCTION` macro automatically creates a string with the absolute path stored in the variable `user_loc` for a {c:type}`CeedQFunctionUser` called `user`.
+The filepath may also be a relative path with respect to a root directory set with {c:func}`CeedAddJitSourceRoot`.
+The {c:macro}`CEED_QFUNCTION` macro automatically creates a string with the absolute path, for example a {c:type}`CeedQFunctionUser` called `user` would have this string stored in the variable `user_loc`.
 
-The entire contents of this file and all locally included files (`#include "foo.h"`) are used during JiT compilation for GPU backends.
-Installed headers (`#include <bar.h>`) are omitted in the source code passed to JiT, but the compilation environment may supply common headers such as `<math.h>`.
+The entire contents of this source file and all included files are used during JiT compilation for GPU backends.
+Include statements for system headers that are required for CPU compilation but are not available in GPU compilation environments should be guarded with `#ifdef CEED_RUNNING_JIT_PASS`.
+Any function definitions in these system headers must still be available in the GPU compilation environments, such as the contents of `<math.h>`.
 These source file must only contain syntax constructs supported by C99 and all targeted backends (i.e. CUDA for `/gpu/cuda`, OpenCL/SYCL for `/gpu/sycl`, etc.).
 
 All source files must be at the provided filepath at runtime for JiT to function.
@@ -20,10 +21,10 @@ All source files must be at the provided filepath at runtime for JiT to function
 
 GPU backends require stricter adherence to memory access assumptions, but CPU backends may occasionally report correct results despite violations of memory access assumptions.
 Both `CeedVector` and `CeedQFunctionContext` have read-only and read-write accessors, and `CeedVector` allow write-only access.
-Read-only access of `CeedVector` and `CeedQFunctionContext` memory spaces must be respected for proper GPU behavior.
+Read-only access of `CeedVector` and `CeedQFunctionContext` memory spaces must be respected for to ensure proper GPU behavior.
 Write-only access of `CeedVector` memory spaces asserts that all data in the `CeedVector` is invalid until overwritten.
 
-`CeedQFunction` assume that all input arrays are read-only and all output arrays are write-only and the {c:type}`CeedQFunctionUser` must adhere to these assumptions, only reading data in the input arrays and fully overwriting the output arrays.
+`CeedQFunction` assume that all input arrays are read-only and all output arrays are write-only and the {c:type}`CeedQFunctionUser` must adhere to these assumptions, only reading data in the input arrays and fully overwriting all entries in the output arrays.
 Additionally, {c:type}`CeedQFunctionUser` have read-write access for `CeedQFunctionContext` data, unless {c:func}`CeedQFunctionSetContextWritable` was used to indicate that read-only access is sufficient.
 
 The `/cpu/self/memcheck` backends explicitly verify read-only and write-only memory access assumptions.

doc/sphinx/source/index.md

@@ -8,9 +8,9 @@ intro
 gettingstarted
 libCEEDapi
 examples/index
+api/index
 ffi
 gpu
-api/index
 precision
 libCEEDdev
 Contributing <CONTRIBUTING>