Merge pull request #496 from CEED/v0.6changelog

v0.6: Release notes

Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "libCEED"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = v0.5
+PROJECT_NUMBER         = v0.6
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

ceed.pc.template

@@ -4,6 +4,6 @@ libdir=${prefix}/lib
 
 Name: CEED
 Description: Code for Efficient Extensible Discretization
-Version: 0.5
+Version: 0.6
 Cflags: -I${includedir}
 Libs: -L${libdir} -lceed

doc/sphinx/source/conf.py

@@ -249,7 +249,10 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org', None),
+    'numpy': ('https://numpy.org/devdocs', None),
+    }
 
 
 # -- Options for breathe --------------------------------------------------

doc/sphinx/source/intro.rst

@@ -4,7 +4,7 @@ Introduction
 Historically, conventional high-order finite element methods were rarely used for
 industrial problems because the Jacobian rapidly loses sparsity as the order is
 increased, leading to unaffordable solve times and memory requirements
-:cite:`Brown:2010`. This effect typically limited the order of accuracy to at most
+:cite:`brown2010`. This effect typically limited the order of accuracy to at most
 quadratic, especially because they are computationally advantageous in terms of
 floating point operations (FLOPS) per degree of freedom (DOF)---see
 :numref:`fig-assembledVsmatrix-free`---, despite the fast convergence and favorable

doc/sphinx/source/references.bib

@@ -1,4 +1,22 @@
-@article{Brown:2010,
+@article{arruda1993largestretch,
+  title={A three-dimensional constitutive model for the large stretch behavior of rubber elastic materials},
+  author={Arruda, Ellen M and Boyce, Mary C},
+  journal={Journal of the Mechanics and Physics of Solids},
+  volume={41},
+  number={2},
+  pages={389--412},
+  year={1993},
+  publisher={Elsevier}
+}
+
+@book{belytschko2013nonlinear,
+  title={Nonlinear finite elements for continua and structures},
+  author={Belytschko, Ted and Liu, Wing Kam and Moran, Brian and Elkhodary, Khalil},
+  year={2013},
+  publisher={John wiley \& sons}
+}
+
+@article{brown2010,
     Adsurl = {https://doi.org/10.1007/s10915-010-9396-8},
     Author = {{Brown}, J.},
     Journal = {Journal of Scientific Computing},
@@ -20,16 +38,13 @@ @article{giraldoetal2010
     doi = {10.1137/090775889}
 }
 
-@article{straka1993numerical,
-  title={Numerical solutions of a non-linear density current: A benchmark solution and comparisons},
-  author={Straka, Jerry M and Wilhelmson, Robert B and Wicker, Louis J and Anderson, John R and Droegemeier, Kelvin K},
-  journal={International Journal for Numerical Methods in Fluids},
-  volume={17},
-  number={1},
-  pages={1--22},
-  year={1993},
-  publisher={Wiley Online Library},
-  doi={10.1002/fld.1650170103}
+@Book{holzapfel2000nonlinear,
+ author={Holzapfel, Gerhard},
+ title={Nonlinear solid mechanics: a continuum approach for engineering},
+ publisher={Wiley},
+ year={2000},
+ address={Chichester New York},
+ isbn={978-0-471-82319-3}
 }
 
 @article{hughesetal2010,
@@ -49,21 +64,18 @@ @book{hughes2012finite
   publisher={Courier Corporation}
 }
 
-@book{belytschko2013nonlinear,
-  title={Nonlinear finite elements for continua and structures},
-  author={Belytschko, Ted and Liu, Wing Kam and Moran, Brian and Elkhodary, Khalil},
-  year={2013},
-  publisher={John wiley \& sons}
+@article{straka1993numerical,
+  title={Numerical solutions of a non-linear density current: A benchmark solution and comparisons},
+  author={Straka, Jerry M and Wilhelmson, Robert B and Wicker, Louis J and Anderson, John R and Droegemeier, Kelvin K},
+  journal={International Journal for Numerical Methods in Fluids},
+  volume={17},
+  number={1},
+  pages={1--22},
+  year={1993},
+  publisher={Wiley Online Library},
+  doi={10.1002/fld.1650170103}
 }
 
-@Book{holzapfel2000nonlinear,
- author={Holzapfel, Gerhard},
- title={Nonlinear solid mechanics: a continuum approach for engineering},
- publisher={Wiley},
- year={2000},
- address={Chichester New York},
- isbn={978-0-471-82319-3}
-}
 @article{williams2009roofline,
   title={Roofline: an insightful visual performance model for multicore architectures},
   author={Williams, Samuel and Waterman, Andrew and Patterson, David},
@@ -74,13 +86,3 @@ @article{williams2009roofline
   year={2009},
   publisher={ACM New York, NY, USA}
 }
-@article{arruda1993largestretch,
-  title={A three-dimensional constitutive model for the large stretch behavior of rubber elastic materials},
-  author={Arruda, Ellen M and Boyce, Mary C},
-  journal={Journal of the Mechanics and Physics of Solids},
-  volume={41},
-  number={2},
-  pages={389--412},
-  year={1993},
-  publisher={Elsevier}
-}

doc/sphinx/source/releasenotes.rst

@@ -5,6 +5,85 @@ On this page we provide a summary of the main API changes, new features and exam
 for each release of libCEED.
 
 
+.. _v0.6:
+
+v0.6 (Mar 29, 2020)
+----------------------------------------
+
+libCEED v0.6 contains numerous new features and examples, as well as expanded
+documentation in `this new website <https://libceed.readthedocs.io>`_.
+
+New features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* New Python interface using `CFFI <https://cffi.readthedocs.io/>`_ provides a nearly
+  1-1 correspondence with the C interface, plus some convenience features.  For instance,
+  data stored in the :cpp:type:`CeedVector` structure are available without copy as
+  :py:class:`numpy.ndarray`.  Short tutorials are provided in
+  `Binder <https://mybinder.org/v2/gh/CEED/libCEED/master?urlpath=lab/tree/examples/tutorials/>`_.
+* Linear QFunctions can be assembled as block-diagonal matrices (per quadrature point,
+  :cpp:func:`CeedOperatorAssembleLinearQFunction`) or to evaluate the diagonal
+  (:cpp:func:`CeedOperatorAssembleLinearDiagonal`).  These operations are useful for
+  preconditioning ingredients and are used in the libCEED's multigrid examples.
+* The inverse of separable operators can be obtained using
+  :cpp:func:`CeedOperatorCreateFDMElementInverse` and applied with
+  :cpp:func:`CeedOperatorApply`.  This is a useful preconditioning ingredient,
+  especially for Laplacians and related operators.
+* New functions: :cpp:func:`CeedVectorNorm`, :cpp:func:`CeedOperatorApplyAdd`,
+  :cpp:func:`CeedQFunctionView`, :cpp:func:`CeedOperatorView`.
+* Make public accessors for various attributes to facilitate writing composable code.
+* New backend: ``/cpu/self/memcheck/serial``.
+* QFunctions using variable-length array (VLA) pointer constructs can be used with CUDA
+  backends.  (Single source is coming soon for OCCA backends.)
+* Fix some missing edge cases in CUDA backend.
+
+Performance Improvements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* MAGMA backend performance optimization and non-tensor bases.
+* No-copy optimization in :cpp:func:`CeedOperatorApply`.
+
+Interface changes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+* Replace :code:`CeedElemRestrictionCreateIdentity` and
+  :code:`CeedElemRestrictionCreateBlocked` with more flexible
+  :cpp:func:`CeedElemRestrictionCreateStrided` and
+  :cpp:func:`CeedElemRestrictionCreateBlockedStrided`.
+* Add arguments to :cpp:func:`CeedQFunctionCreateIdentity`.
+* Replace ambiguous uses of :cpp:enum:`CeedTransposeMode` for L-vector identification
+  with :cpp:enum:`CeedInterlaceMode`.  This is now an attribute of the
+  :cpp:type:`CeedElemRestriction` (see :cpp:func:`CeedElemRestrictionCreate`) and no
+  longer passed as ``lmode`` arguments to :cpp:func:`CeedOperatorSetField` and
+  :cpp:func:`CeedElemRestrictionApply`.
+
+Examples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+libCEED-0.6 contains greatly expanded examples with :ref:`new documentation <Examples>`.
+Notable additions include:
+
+* Standalone :ref:`ex2-surface` (:file:`examples/ceed/ex2-surface`): compute the area of
+  a domain in 1, 2, and 3 dimensions by applying a Laplacian.
+* PETSc :ref:`example-petsc-area` (:file:`examples/petsc/area.c`): computes surface area
+  of domains (like the cube and sphere) by direct integration on a surface mesh;
+  demonstrates geometric dimension different from topological dimension.
+* PETSc :ref:`example-petsc-bps`:
+
+  * :file:`examples/petsc/bpsraw.c` (formerly ``bps.c``): transparent CUDA support.
+  * :file:`examples/petsc/bps.c` (formerly ``bpsdmplex.c``): performance improvements
+    and transparent CUDA support.
+  * :ref:`example-petsc-bps-sphere` (:file:`examples/petsc/bpssphere.c`):
+    generalizations of all CEED BPs to the surface of the sphere; demonstrates geometric
+    dimension different from topological dimension.
+
+* :ref:`example-petsc-multigrid` (:file:`examples/petsc/multigrid.c`): new p-multigrid
+  solver with algebraic multigrid coarse solve.
+* :ref:`example-petsc-navier-stokes` (:file:`examples/fluids/navierstokes.c`; formerly
+  ``examples/navier-stokes``): unstructured grid support (using PETSc's ``DMPlex``),
+  implicit time integration, SU/SUPG stabilization, free-slip boundary conditions, and
+  quasi-2D computational domain support.
+* :ref:`example-petsc-elasticity` (:file:`examples/solids/elasticity.c`): new solver for
+  linear elasticity, small-strain hyperelasticity, and globalized finite-strain
+  hyperelasticity using p-multigrid with algebraic multigrid coarse solve.
+
 .. _v0.5:
 
 v0.5 (Sep 18, 2019)

examples/ceed/index.rst

@@ -50,37 +50,17 @@ Similarly to :ref:`Ex1-Volume`, it computes:
    I = \int_{\partial \Omega} \mathbf{1} \, dS .
    :label: eq-ex2-surface
 
-but this time by solving a Laplace's equation for a harmonic function
-:math:`u(\mathbf{x})`. We write the Laplace's equation
+but this time by applying the divergence theorem using a Laplacian.
+In particular, we select :math:`u(\bm x) = x_0 + x_1 + x_2`, for which :math:`\nabla u = [1, 1, 1]^T`, and thus :math:`\nabla u \cdot \hat{\bm n} = 1`.
 
-.. math::
-   \nabla \cdot \nabla u = 0, \textrm{ for  } \mathbf{x} \in \Omega .
-   :label: eq-laplace
-
-We can rewrite this via the bilinear form :math:`a(\cdot, \cdot)` and the linear form
-:math:`\langle \cdot, \cdot \rangle` as
+Given Laplace's equation,
 
 .. math::
-   a(u,v) = \langle, v,f \rangle
+   -\nabla \cdot \nabla u = 0, \textrm{ for  } \mathbf{x} \in \Omega
 
-where :math:`v` is the test function, and for which :math:`\langle, v,f \rangle=0` in
-this case. We
-obtain
+multiply by a test function :math:`v` and integrate by parts to obtain
 
 .. math::
-   a(u,v)  = \int_\Omega v \nabla \cdot \nabla u \, dV =   \int_{\partial \Omega} v \nabla u \cdot \mathbf{n}\, dS - \int_\Omega \nabla v \cdot \nabla u \, dV  = 0 ,
-
-where we have used integration by parts.
+    \int_\Omega \nabla v \cdot \nabla u \, dV - \int_{\partial \Omega} v \nabla u \cdot \hat{\bm n}\, dS = 0 .
 
-:math:`a(u,v) = 0` because we have chosen :math:`u(\mathbf{x})` to be harmonic, so we
-can write
-
-.. math::
-   \int_{\partial \Omega} v \nabla u \cdot \mathbf{n}\, dS = \int_\Omega \nabla v \cdot \nabla u \, dV
-   :label: eq-laplace-by-parts
-
-and use the :ref:`CeedOperator` for Laplace's operator to compute the right-hand side of
-equation :math:numref:`eq-laplace-by-parts`. This way, the left-hand side of equation
-:math:numref:`eq-laplace-by-parts` (which gives :math:numref:`eq-ex2-surface` because
-we have chosen :math:`u(\mathbf{x}) = (x + y + z)` such that
-:math:`\nabla u \cdot \mathbf{n} = 1`) is readily found.
+Since we have chosen :math:`u` such that the boundary integrand is :math:`v 1`, we may evaluate the surface integral by applying the volumetric Laplacian and summing the result.

examples/solids/index.rst

@@ -458,7 +458,7 @@ That is, given the linearization point :math:`\bm F` and solution increment :mat
 #. conclude by :math:numref:`eq-diff-P`, where :math:`\bm S` is either stored or recomputed from its definition exactly as in the nonlinear residual evaluation.
 
 .. note::
-   The decision of whether to recompute or store functions of the current state :math:`\bm F` depends on a roofline analysis :cite:`williams2009roofline,Brown:2010` of the computation and the cost of the constitutive model.
+   The decision of whether to recompute or store functions of the current state :math:`\bm F` depends on a roofline analysis :cite:`williams2009roofline,brown2010` of the computation and the cost of the constitutive model.
    For low-order elements where flops tend to be in surplus relative to memory bandwidth, recomputation is likely to be preferable, where as the opposite may be true for high-order elements.
    Similarly, analysis with a simple constitutive model may see better performance while storing little or nothing while an expensive model such as Arruda-Boyce :cite:`arruda1993largestretch`, which contains many special functions, may be faster when using more storage to avoid recomputation.
    In the case where complete linearization is preferred, note the symmetry :math:`\mathsf C_{IJKL} = \mathsf C_{KLIJ}` evident in :math:numref:`eq-neo-hookean-incremental-stress-index`, thus :math:`\mathsf C` can be stored as a symmetric :math:`6\times 6` matrix, which has 21 unique entries.