sphinx/source/libCEEDapi.md

9 In finite element formulations, the weak form of a Partial Differential Equation (PDE) is evaluated…
10 In particular, when high-order finite elements or spectral elements are used, the resulting sparse …
12 We present here the notation and the mathematical formulation adopted in libCEED.
14 We start by considering the discrete residual $F(u)=0$ formulation in weak form.
21 where $\bm{x} \in \mathbb{R}^d \supset \Omega$.
23 We want to find $u$ in a suitable space $V_D$, such that
29 for all $\bm v$ in the corresponding homogeneous space $V_0$, where $\bm f_0$ and $\bm f_1$ contain…
30 We notice here that $\bm f_0$ represents all terms in {eq}`residual` which multiply the (possibly v…
31 For an n-component problems in $d$ dimensions, $\bm f_0 \in \mathbb{R}^n$ and $\bm f_1 \in \mathbb{…
34 …th fields and spatial dimensions while a single dot represents contraction in just one, which shou…
38 In the code, the function that represents the weak form at quadrature points is called the {ref}`Ce…
39 In the {ref}`Examples` provided with the library (in the {file}`examples/` directory), we store the…
47 …imple *reference* element (e.g. the unit square) and applying a quadrature rule in reference space.
49 …in all finite element operators where the evaluation starts on *global (trial) degrees of freedom …
68 Note that in the case of adaptive mesh refinement (AMR), the restrictions $\bm{P}$ and $\bm{\mathca…
101 - In the case of AMR with hanging nodes (giving rise to hanging DoFs):
106 …> - in other words, an entry in an **E-vector** is obtained by copying an entry from the correspon…
111 - In the case of variable order spaces:
119 - In many cases it is useful to distinguish two types of vectors:
132 …> - the T in TA indicates that the data format represents an operator from a **T-vector** to a **T…
148   > - precompute and store $w\det(J)$ at all quadrature points in all mesh elements
163 Our focus in libCEED, instead, is on **partial assembly**, where we compute and store only $\bm{D}$…
173 …eir ranges, so $\bm{P}$, $\bm{\mathcal{E}}$ and $\bm{B}$ allow us to "zoom-in" to subdomain, eleme…
175 …r computational devices (CPUs, GPUs, etc.) as indicated by the shaded regions in the diagram above.
177 …erspective in these settings is that the operators $\bm{P}$, $\bm{\mathcal{E}}$, $\bm{B}$ and $\bm…
178 These components also naturally fall in different classes of numerical algorithms -- parallel (mult…
180 Currently in libCEED, it is assumed that the host application manages the global **T-vectors** and …
181 Our API is thus focused on the **L-vector** level, where the logical devices, which in the library …
182 Each MPI rank can use one or more {ref}`Ceed`s, and each {ref}`Ceed`, in turn, can represent one or…
191 The libCEED API takes an algebraic approach, where the user essentially describes in the *frontend*…
192 This is visualized in the schematic below; "active" and "passive" inputs/outputs will be discussed …
205 Our long-term vision is to include a variety of backend implementations in libCEED, ranging from re…
206 A simple reference backend implementation is provided in the file
219 To clarify these concepts and illustrate how they are combined in the API, consider the implementat…
225 In the following figure, we specialize the schematic used above for general operators so that it co…
232 … $\bm{D}$, and input/output vectors corresponding to the libCEED operators in the t500-operator te…
244 …e logical devices driving the same resource (though performance may suffer in case of oversubscrip…
247 The `setup` routine above computes and stores $\bm{D}$, in this case a scalar value in each quadrat…
248 These functions are turned into the {ref}`CeedQFunction` variables `qf_setup` and `qf_mass` in the …
259 … element size or by batching elements together to facilitate vectorization in other stages, and ca…
261 In addition to the function pointers (`setup` and `mass`), {ref}`CeedQFunction` constructors take a…
262 This is used by backends that support Just-In-Time (JIT) compilation (i.e., CUDA and HIP) to compil…
288 …r the mesh nodes, `basis_x`, and the unknown field, `basis_u`, are defined in the calls to the fun…
289 In this example, both the mesh and the unknown field use $H^1$ Lagrange finite elements of order 1 …
298 …this structure can be specified in terms of the `Q×P` matrices that evaluate values and gradients …
301 …odes, `elem_restr_x`, and the unknown field, `elem_restr_u`, are specified in the {c:func}`CeedEle…
302 Both of these specify directly the DoF indices for each element in the `ind_x` and `ind_u` arrays:
317 This technique is used to provide no-copy interfaces in all contexts that involve problem-sized dat…
352 …r `op_mass` and its {c:func}`CeedOperatorApply()` to the input **L-vector** `U` with output in `V`:
372 A number of function calls in the interface, such as {c:func}`CeedOperatorApply()`, are intended to…
373 …in the above example, `CEED_REQUEST_IMMEDIATE`, is used to express the request (from the user) for…
379 LibCEED provides a gallery of built-in {ref}`CeedQFunction`s in the {file}`gallery/` directory.
399 typically in a library initializer or "constructor" that runs automatically.
406 We'd love to talk with you if you're interested in packaging backends externally, and will work wit…