sphinx/source/releasenotes.md

11 - Add `bool` field type for `CeedQFunctionContext` and related interfaces to use `bool` fields.
12 - `CEED_BASIS_COLLOCATED` removed; users should only use `CEED_BASIS_NONE`.
13 - Remove unneeded pointer for `CeedElemRestrictionGetELayout`.
14 - Change QFunction source include file handling in JiT compilers
15 …- Add `CEED_RUNNING_JIT_PASS` compiler definition for wrapping header files that device JiT compil…
16 …- Users should now prefer `#include <ceed/types.h>` rather than `#include <ceed.h>` in QFunction s…
17 - Require use of `Ceed*Destroy()` on Ceed objects returned from `Ceed*Get*()`.
18 - Rename `CeedCompositeOperatorCreate()` to `CeedOperatorCreateComposite()` for uniformity.
19 - Rename `CeedCompositeOperator*()` to `CeedOperatorComposite*()` for uniformity.
23 - Add `CeedOperatorCreateAtPoints` which evaluates the `CeedQFunction` at arbitrary locations in ea…
24 - Add `CeedElemRestrictionGetLLayout` to provide L-vector layout for strided `CeedElemRestriction` …
25 - Add `CeedVectorReturnCeed` and similar when parent `Ceed` context for a libCEED object is only ne…
26 - Enable `#pragma once` for all JiT source; remove duplicate includes in JiT source string before c…
27 - Allow user to set additional compiler options for CUDA and HIP JiT.
28 …oo/bar")` will be used to set `-Ifoo/bar` and defines set with `CeedAddJitDefine(ceed, "foo=bar")`…
29 - Added non-tensor basis support to code generation backends `/gpu/cuda/gen` and `/gpu/hip/gen`.
30 - Added support to code generation backends `/gpu/cuda/gen` and `/gpu/hip/gen` for operators with b…
31 - Add `CeedGetGitVersion()` to access the Git commit and dirty state of the repository at build tim…
32 - Add `CeedGetBuildConfiguration()` to access compilers, flags, and related information about the b…
36 - Add deal.II example with CEED BP suite.
40 - OCCA backends were retired.
42 (v0-12)=
48 - Update `CeedOperatorContext*` functions to `CeedOperator*Context*` functions for consistency.
50 - Removed `CeedBasisSetNumQuadraturePoints` as redundant and bug-prone interface.
54 - Added {c:func}`CeedOperatorGetFieldByName` to access a specific `CeedOperatorField` by its name.
55 - Update `/cpu/self/memcheck/*` backends to help verify `CeedVector` array access assumptions and `…
56 - Update {c:func}`CeedOperatorLinearAssembleDiagonal` to provide default implementation that suppor…
57 - Added Sycl backends `/gpu/sycl/ref`, `/gpu/sycl/shared`, and `/gpu/sycl/gen`.
58 - Added {c:func}`CeedBasisApplyAtPoints` for evaluation of values and derivatives at arbitrary poin…
59 - Added support for non-tensor $H(\text{curl})$ finite element spaces with {c:func}`CeedBasisCreate…
60 - Added {c:func}`CeedElemRestrictionCreateCurlOriented`, similar to {c:func}`CeedElemRestrictionCre…
61 - Added {c:func}`CeedOperatorLinearAssemblePointBlockDiagonalSymbolic` to create COO mapping for ma…
62 - Added support for application codes which manage multiple {ref}`Ceed` objects, parallelized acros…
66 - Add `DMSwarm` example demonstrating interpolation from background mesh to swarm points and projec…
68 #### {ref}`example-petsc-bps`
70 - Requires PETSc version 3.19 or later.
72 #### {ref}`example-petsc-navier-stokes`
74 - Updated restart and checkpointing interface.
75 - Add data-driven subgrid-stress model.
76 - Add differential filtering of solution.
77 - Add turbulence statistics collection over spanwise-symmetric geometries.
78 - Add Taylor-Green vortex initial condition.
79 - Add Riemann-based outflow boundary conditions.
80 - Added vortex shedding and flow past cylinder example, including calculations for lift, drag, and …
81 - Add Internal Damping Layer (IDL) for helping turbulent simulation stability.
82 - Derive `CeedBasis` from `PetscFE`, and various other internal maintainability updates.
84 (v0-11)=
90 - Added {c:func}`CeedOperatorSetName` for more readable {c:func}`CeedOperatorView` output.
91 - Added {c:func}`CeedBasisCreateProjection` to facilitate interpolation between nodes for separate …
92 - Rename and move {c:func}`CeedCompositeOperatorGetNumSub` and {c:func}`CeedCompositeOperatorGetSub…
93 - Renamed `CEED_BASIS_COLLOCATED` to `CEED_BASIS_NONE` for clarity.
98 - Update `/cpu/self/memcheck/*` backends to help verify `CeedQFunctionContext` data sizes provided …
99 - Improved support for $H(\text{div})$ bases.
100 - Added `CeedInt_FMT` to support potential future use of larger integer sizes.
101 - Added `CEED_QFUNCTION_ATTR` for setting compiler attributes/pragmas to `CEED_QFUNCTION_HELPER` an…
102 - OCCA backend updated to latest OCCA release; DPC++ and OMP OCCA modes enabled.
108 - Fix bug in setting device id for GPU backends.
109 - Fix storing of indices for `CeedElemRestriction` on the host with GPU backends.
110 - Fix `CeedElemRestriction` sizing for {c:func}`CeedOperatorAssemblePointBlockDiagonal`.
111 - Fix bugs in CPU implementation of {c:func}`CeedOperatorLinearAssemble` when there are different n…
115 #### {ref}`example-petsc-navier-stokes`
117 - Various performance enhancements, analytic matrix-free and assembled Jacobian, and PETSc solver c…
118 - Refactored to improve code reuse and modularity.
119 - Support for primitive variables for more accurate boundary layers and all-speed flow.
120 - Added $YZ\beta$ shock capturing scheme and Shock Tube example.
121 - Added Channel example, with comparison to analytic solutions.
122 - Added Flat Plate with boundary layer mesh and compressible Blasius inflow condition based on Cheb…
123 - Added strong and weak synthetic turbulence generation (STG) inflow boundary conditions.
124 - Added "freestream" boundary conditions based on HLLC Riemann solver.
125 - Automated stabilization coefficients for different basis degree.
127 #### {ref}`example-petsc-bps`
129 - Support for convergence studies.
133 - Refactored `/gpu/cuda/shared` and `/gpu/cuda/gen` as well as `/gpu/hip/shared` and `/gpu/hip/gen`…
134 - Enabled support for `p > 8` for `/gpu/*/shared` backends.
135 - Switch to `clang-format` over `astyle` for automatic formatting; Makefile command changed to `mak…
136 - Improved test harness.
138 (v0-10-1)=
144 - Added {c:func}`CeedQFunctionSetUserFlopsEstimate` and {c:func}`CeedOperatorGetFlopsEstimate` to f…
148 - Switched MAGMA backends to use runtime compilation for tensor basis kernels (and element restrict…
153 - Install JiT source files in install directory to fix GPU functionality for installed libCEED.
155 (v0-10)=
161 - Update {c:func}`CeedQFunctionGetFields` and {c:func}`CeedOperatorGetFields` to include number of …
162 - Promote to the public API: QFunction and Operator field objects, `CeedQFunctionField` and `CeedOp…
163 - Clarify and document conditions where `CeedQFunction` and `CeedOperator` become immutable and no …
164 - Add {c:func}`CeedOperatorLinearAssembleQFunctionBuildOrUpdate` to reduce object creation overhead…
165 - Promote {c:func}`CeedOperatorCheckReady`to the public API to facilitate interactive interfaces.
166 - Warning added when compiling OCCA backend to alert users that this backend is experimental.
167 - `ceed-backend.h`, `ceed-hash.h`, and `ceed-khash.h` removed. Users should use `ceed/backend.h`, `…
168 - Added {c:func}`CeedQFunctionGetKernelName`; refactored {c:func}`CeedQFunctionGetSourcePath` to ex…
169 - Clarify documentation for {c:func}`CeedVectorTakeArray`; this function will error if {c:func}`Cee…
170 - Added {c:func}`CeedVectorGetArrayWrite` that allows access to uninitialized arrays; require initi…
171 - Added {c:func}`CeedQFunctionContextRegisterDouble` and {c:func}`CeedQFunctionContextRegisterInt32…
172 - Added {c:func}`CeedQFunctionContextGetFieldDescriptions` to retrieve user defined descriptions of…
173 - Renamed `CeedElemTopology` entries for clearer namespacing between libCEED enums.
174 - Added type `CeedSize` equivalent to `ptrdiff_t` for array sizes in {c:func}`CeedVectorCreate`, {c…
175 - Added {c:func}`CeedOperatorSetQFunctionUpdated` to facilitate QFunction data re-use between opera…
176 - Added {c:func}`CeedOperatorGetActiveVectorLengths` to get shape of CeedOperator.
180 - `CeedScalar` can now be set as `float` or `double` at compile time.
181 - Added JiT utilities in `ceed/jit-tools.h` to reduce duplicated code in GPU backends.
182 - Added support for JiT of QFunctions with `#include "relative/path/local-file.h"` statements for a…
183 - Remove need to guard library headers in QFunction source for code generation backends.
184 - `CeedDebugEnv()` macro created to provide debugging outputs when Ceed context is not present.
185 - Added {c:func}`CeedStringAllocCopy` to reduce repeated code for copying strings internally.
186 - Added {c:func}`CeedPathConcatenate` to facilitate loading kernel source files with a path relativ…
187 - Added support for non-tensor $H(\text{div})$ elements, to include CPU backend implementations and…
188 - Added {c:func}`CeedQFunctionSetContextWritable` and read-only access to `CeedQFunctionContext` da…
189 - Added support for element matrix assembly in GPU backends.
193 - Refactored preconditioner support internally to facilitate future development and improve GPU com…
194 - `Include-what-you-use` makefile target added as `make iwyu`.
195 - Create backend constant `CEED_FIELD_MAX` to reduce magic numbers in codebase.
196 - Put GPU JiTed kernel source code into separate files.
197 - Dropped legacy version support in PETSc based examples to better utilize PETSc DMPlex and Mat upd…
199 (v0-9)=
205 - Minor modification in error handling macro to silence pedantic warnings when compiling with Clang…
209 - Add {c:func}`CeedVectorAXPY` and {c:func}`CeedVectorPointwiseMult` as a convenience for stand-alo…
210 - Add `CEED_QFUNCTION_HELPER` macro to properly annotate QFunction helper functions for code genera…
211 - Add `CeedPragmaOptimizeOff` macro for code that is sensitive to floating point errors from fast m…
212 - Rust support: split `libceed-sys` crate out of `libceed` and [publish both on crates.io](https://…
218 - Solid mechanics mini-app updated to explore the performance impacts of various formulations in th…
219 - Fluid mechanics example adds GPU support and improves modularity.
223 - The `/cpu/self/tmpl` and `/cpu/self/tmpl/sub` backends have been removed. These backends were int…
225 (v0-8)=
231 - Error handling improved to include enumerated error codes for C interface return values.
232 - Installed headers that will follow semantic versioning were moved to {code}`include/ceed` directo…
236 - Julia and Rust interfaces added, providing a nearly 1-1 correspondence with the C interface, plus…
237 - Static libraries can be built with `make STATIC=1` and the pkg-config file is installed according…
238 - Add {c:func}`CeedOperatorLinearAssembleSymbolic` and {c:func}`CeedOperatorLinearAssemble` to supp…
242 - New HIP MAGMA backends for hipMAGMA library users: `/gpu/hip/magma` and `/gpu/hip/magma/det`.
243 - New HIP backends for improved tensor basis performance: `/gpu/hip/shared` and `/gpu/hip/gen`.
247 - {ref}`example-petsc-elasticity` example updated with traction boundary conditions and improved Di…
248 - {ref}`example-petsc-elasticity` example updated with Neo-Hookean hyperelasticity in current confi…
249 - {ref}`example-petsc-navier-stokes` example updated with isentropic traveling vortex test case, an…
250 - {ref}`example-petsc-navier-stokes` example updated with support for performing convergence study …
252 (v0-7)=
258 - Replace limited {code}`CeedInterlaceMode` with more flexible component stride {code}`compstride` …
261 - Replace various uses of {code}`Ceed*Get*Status` with {code}`Ceed*Is*` in the backend API to match…
262 - Replace {code}`CeedOperatorAssembleLinearDiagonal` with {c:func}`CeedOperatorLinearAssembleDiagon…
263 - Linear Operators can be assembled as point-block diagonal matrices with {c:func}`CeedOperatorLine…
264 - Diagonal assemble interface changed to accept a {ref}`CeedVector` instead of a pointer to a {ref}…
265 - Added {c:func}`CeedOperatorLinearAssembleAddDiagonal` and {c:func}`CeedOperatorLinearAssembleAddP…
266 - Added {c:func}`CeedVectorTakeAray` to sync and remove libCEED read/write access to an allocated a…
268 - Added {code}`CeedQFunctionContext` object to manage user QFunction context data and reduce copies…
269 - Added {c:func}`CeedOperatorMultigridLevelCreate`, {c:func}`CeedOperatorMultigridLevelCreateTensor…
273 - New HIP backend: `/gpu/hip/ref`.
274 - CeedQFunction support for user `CUfunction`s in some backends
278 - OCCA backend rebuilt to facilitate future performance enhancements.
279 - PETSc BPs suite improved to reduce noise due to multiple calls to {code}`mpiexec`.
283 - {ref}`example-petsc-elasticity` example updated with strain energy computation and more flexible …
287 - The `/gpu/cuda/reg` backend has been removed, with its core features moved into `/gpu/cuda/ref` a…
289 (v0-6)=
298 - New Python interface using [CFFI](https://cffi.readthedocs.io/) provides a nearly
299   1-1 correspondence with the C interface, plus some convenience features.  For instance,
303 - Linear QFunctions can be assembled as block-diagonal matrices (per quadrature point,
307 - The inverse of separable operators can be obtained using
311 - New functions: {c:func}`CeedVectorNorm`, {c:func}`CeedOperatorApplyAdd`,
313 - Make public accessors for various attributes to facilitate writing composable code.
314 - New backend: `/cpu/self/memcheck/serial`.
315 - QFunctions using variable-length array (VLA) pointer constructs can be used with CUDA
317 - Fix some missing edge cases in CUDA backend.
321 - MAGMA backend performance optimization and non-tensor bases.
322 - No-copy optimization in {c:func}`CeedOperatorApply`.
326 - Replace {code}`CeedElemRestrictionCreateIdentity` and
330 - Add arguments to {c:func}`CeedQFunctionCreateIdentity`.
331 - Replace ambiguous uses of {cpp:enum}`CeedTransposeMode` for L-vector identification
339 libCEED-0.6 contains greatly expanded examples with {ref}`new documentation <Examples>`.
342 - Standalone {ref}`ex2-surface` ({file}`examples/ceed/ex2-surface`): compute the area of
345 - PETSc {ref}`example-petsc-area` ({file}`examples/petsc/area.c`): computes surface area
349 - PETSc {ref}`example-petsc-bps`:
351   - {file}`examples/petsc/bpsraw.c` (formerly `bps.c`): transparent CUDA support.
352   - {file}`examples/petsc/bps.c` (formerly `bpsdmplex.c`): performance improvements
354   - {ref}`example-petsc-bps-sphere` ({file}`examples/petsc/bpssphere.c`):
358 - {ref}`example-petsc-multigrid` ({file}`examples/petsc/multigrid.c`): new p-multigrid
361 - {ref}`example-petsc-navier-stokes` ({file}`examples/fluids/navierstokes.c`; formerly
362   `examples/navier-stokes`): unstructured grid support (using PETSc's `DMPlex`),
363   implicit time integration, SU/SUPG stabilization, free-slip boundary conditions, and
364   quasi-2D computational domain support.
366 - {ref}`example-petsc-elasticity` ({file}`examples/solids/elasticity.c`): new solver for
367   linear elasticity, small-strain hyperelasticity, and globalized finite-strain
368   hyperelasticity using p-multigrid with algebraic multigrid coarse solve.
370 (v0-5)=
375 the family of backends, of which, the new `cuda-gen` backend achieves state-of-the-art
376 performance using single-source {ref}`CeedQFunction`. From this release, users
377 can define Q-Functions in a single source code independently of the targeted backend
378 with the aid of a new macro `CEED QFUNCTION` to support JIT (Just-In-Time) and CPU
387 written in pure C and use partial **E-vectors** to improve performance) and the
395 identity Q-Functions were introduced, and the PETSc benchmark problems were expanded
396 to include unstructured meshes handling were. For this expansion, the prior version of
398 renamed `bpsraw`, and the new version of the BPs, which can handle data associated
400 problems, namely BP2 and BP4 (the vector-valued versions of BP1 and BP3, respectively),
401 and BP5 and BP6 (the collocated versions---for which the quadrature points are the same
402 as the Gauss Lobatto nodes---of BP3 and BP4 respectively) were added to the PETSc
408 | CEED resource (`-ceed`)  | Backend                                             |
409 |--------------------------|-----------------------------------------------------|
431 :::{list-table}
432 :header-rows: 1
434 * - User code
435   - Example
436 * - `ceed`
437   - * ex1 (volume)
439 * - `mfem`
440   - * BP1 (scalar mass operator)
442 * - `petsc`
443   - * BP1 (scalar mass operator)
449     * Navier-Stokes
450 * - `nek5000`
451   - * BP1 (scalar mass operator)
455 (v0-4)=
462 support for operator composition, performance benchmarking, and a Navier-Stokes demo.
479 A new explicit time-stepping Navier-Stokes solver was added to the family of libCEED
480 examples in the `examples/petsc` directory (see {ref}`example-petsc-navier-stokes`).
481 This example solves the time-dependent Navier-Stokes equations of compressible gas
482 dynamics in a static Eulerian three-dimensional frame, using structured high-order
483 finite/spectral element spatial discretizations and explicit high-order time-stepping
484 (available in PETSc). Moreover, the Navier-Stokes example was developed using PETSc,
490 | CEED resource (`-ceed`)  | Backend                                             |
491 |--------------------------|-----------------------------------------------------|
509 :::{list-table}
510 :header-rows: 1
512 * - User code
513   - Example
514 * - `ceed`
515   - * ex1 (volume)
516 * - `mfem`
517   - * BP1 (scalar mass operator)
519 * - `petsc`
520   - * BP1 (scalar mass operator)
522     * Navier-Stokes
523 * - `nek5000`
524   - * BP1 (scalar mass operator)
528 (v0-3)=
533 non-tensor bases, backend optimization, and improved Fortran interface. This release
543 it enables effective use of arbitrary-length SIMD while maintaining cache locality.
547 automatically supports non-polynomial and non-interpolatory bases, thus is more general
552 | CEED resource (`-ceed`) | Backend                                             |
553 |-------------------------|-----------------------------------------------------|
565 :::{list-table}
566 :header-rows: 1
568 * - User code
569   - Example
570 * - `ceed`
571   - * ex1 (volume)
572 * - `mfem`
573   - * BP1 (scalar mass operator)
575 * - `petsc`
576   - * BP1 (scalar mass operator)
578 * - `nek5000`
579   - * BP1 (scalar mass operator)
583 (v0-21)=
594 In general, the MAGMA-specific data structures keep the libCEED pointers to CPU data
601 | CEED resource (`-ceed`) | Backend                         |
602 |-------------------------|---------------------------------|
612 :::{list-table}
613 :header-rows: 1
615 * - User code
616   - Example
617 * - `ceed`
618   - * ex1 (volume)
619 * - `mfem`
620   - * BP1 (scalar mass operator)
622 * - `petsc`
623   - * BP1 (scalar mass operator)
624 * - `nek5000`
625   - * BP1 (scalar mass operator)
628 (v0-2)=
634 a common, easy-to-use build environment, where the user can build the CEED distribution
644 | CEED resource (`-ceed`) | Backend                         |
645 |-------------------------|---------------------------------|
654 :::{list-table}
655 :header-rows: 1
657 * - User code
658   - Example
659 * - `ceed`
660   - * ex1 (volume)
661 * - `mfem`
662   - * BP1 (scalar mass operator)
664 * - `petsc`
665   - * BP1 (scalar mass operator)
666 * - `nek5000`
667   - * BP1 (scalar mass operator)
670 (v0-1)=
674 Initial low-level API of the CEED project. The low-level API provides a set of Finite
675 Elements kernels and components for writing new low-level kernels. Examples include:
677 partial assembly and action for efficient high-order operators like mass, diffusion,
678 advection, etc. The main goal of the low-level API is to establish the basis for the
679 high-level API. Also, identifying such low-level kernels and providing a reference
692 | CEED resource (`-ceed`) | Backend                         |
693 |-------------------------|---------------------------------|
702 |-----------------------|-----------------------------------|