From dfa8e3298603c4ff7970d9c72c103860d4fc0517 Mon Sep 17 00:00:00 2001 From: valeriabarra Date: Sun, 29 Mar 2020 12:03:42 -0600 Subject: [PATCH 1/4] v0.6: Add release notes --- doc/sphinx/source/releasenotes.rst | 45 ++++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/doc/sphinx/source/releasenotes.rst b/doc/sphinx/source/releasenotes.rst index c98156b010..7b974d3999 100644 --- a/doc/sphinx/source/releasenotes.rst +++ b/doc/sphinx/source/releasenotes.rst @@ -5,6 +5,51 @@ 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 was made again publicly available in the third full CEED software +distribution, release CEED 3.0. This release contained notable features, and +substantial additions in the examples suite. Some API changes were introduced, +including the change from ``CeedElemRestrictionCreateIdentity()`` to +``CeedElemRestrictionCreateStrided()`` +and the addition of ``ElemRestriction`` layout mode. The latter change +requires changing use of ``CEED_TRANSPOSE`` and ``CEED_NOTRANSPOSE`` to +``CEED_LAYOUT_NODE_COMPONENT`` and ``CEED_LAYOUT_COMPONENT_NODE``, +respectively, for ``CeedElemRestriction lmode`` in ``CeedElemRestrictionCreate*``. +The user still has the choice of interlacing fields by node, or viceversa, +interlacing nodes by fields, but this choice now is not declared when the +different ``CeedOperator`` fields are set with the ``CeedOperatorSetField()``, +rather when the restriction is created with ``CeedElemRestrictionCreate()``. + +For this release, the libCEED team has deployed libCEED's very first +`user manual `_! +And a C/Python interface, developed using the C Foreign Function Interface +(`CFFI `_) +for Python. CFFI allows to reuse most of the C declarations and requires only a +minimal adaptation of some of them. The C and Python APIs are mapped in a nearly +1:1 correspondence. For instance, data stored in the CeedVector structure are +associated to arrays defined via the numpy package. In fact, since libCEED heavily +relies on pointers and arrays to handle the data, a Python structure that resembles +the C arrays is needed. In details, numpy arrays allow this correspondence obtained +by passing the numpy array memory address as pointers to the libCEED C API. + +Moreover, in this release, libCEED's suite of PETSc application examples has +significantly expanded, including: An expanded Navier-Stokes miniapp, which now +features an implicit time-integration formulation, SU/SUPG stabilization methods, +free slip boundary conditions and quasi-2D computational domain for faster +execution; A Continuum Mechanics example, which features different constitutive +models, such as linear elasticity and hyperelasticity both at small and finite +strain; Calculation of surface areas including the case of the surface of a +cube and a cubed-sphere; And finally, the expansion of the set of PETSc Bakeoff +Problems (BPs) on the cubed-sphere. In what follows, we provide a detailed +description of the added examples. + +Backends available in this release, are the same ones available in :ref:`v0.5`. + + .. _v0.5: v0.5 (Sep 18, 2019) From ad916340c48cf27adff20966dbd27df2c4fd3d94 Mon Sep 17 00:00:00 2001 From: valeriabarra Date: Sun, 29 Mar 2020 12:43:50 -0600 Subject: [PATCH 2/4] User manual style: alphabetize refs --- doc/sphinx/source/intro.rst | 2 +- doc/sphinx/source/references.bib | 70 ++++++++++++++++---------------- examples/solids/index.rst | 2 +- 3 files changed, 38 insertions(+), 36 deletions(-) diff --git a/doc/sphinx/source/intro.rst b/doc/sphinx/source/intro.rst index f3ea201702..5bb66fefdb 100644 --- a/doc/sphinx/source/intro.rst +++ b/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 diff --git a/doc/sphinx/source/references.bib b/doc/sphinx/source/references.bib index eca4317450..5d775d42c5 100644 --- a/doc/sphinx/source/references.bib +++ b/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} -} diff --git a/examples/solids/index.rst b/examples/solids/index.rst index 6395d61600..c71cbcbe56 100644 --- a/examples/solids/index.rst +++ b/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. From 46defcf39517b86c1525e803d39cb5f205c4f424 Mon Sep 17 00:00:00 2001 From: Jed Brown Date: Sun, 29 Mar 2020 23:52:44 -0600 Subject: [PATCH 3/4] ex2-surface: fix documentation --- examples/ceed/index.rst | 34 +++++++--------------------------- 1 file changed, 7 insertions(+), 27 deletions(-) diff --git a/examples/ceed/index.rst b/examples/ceed/index.rst index 1fbdf9ee2c..42a1769357 100644 --- a/examples/ceed/index.rst +++ b/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. From 0696387f8d71d9a3881a19f78a7709d9da41ea57 Mon Sep 17 00:00:00 2001 From: Jed Brown Date: Sun, 29 Mar 2020 22:31:28 -0600 Subject: [PATCH 4/4] libCEED-0.6 Co-authored-by: Valeria Barra --- Doxyfile | 2 +- ceed.pc.template | 2 +- doc/sphinx/source/conf.py | 5 +- doc/sphinx/source/releasenotes.rst | 112 +++++++++++++++++++---------- 4 files changed, 79 insertions(+), 42 deletions(-) diff --git a/Doxyfile b/Doxyfile index 9161710a5e..9a616d00e5 100644 --- a/Doxyfile +++ b/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 diff --git a/ceed.pc.template b/ceed.pc.template index 1192987ca8..261550e0db 100644 --- a/ceed.pc.template +++ b/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 diff --git a/doc/sphinx/source/conf.py b/doc/sphinx/source/conf.py index adac6f4d91..bace03dab3 100755 --- a/doc/sphinx/source/conf.py +++ b/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 -------------------------------------------------- diff --git a/doc/sphinx/source/releasenotes.rst b/doc/sphinx/source/releasenotes.rst index 7b974d3999..da0e91c7d0 100644 --- a/doc/sphinx/source/releasenotes.rst +++ b/doc/sphinx/source/releasenotes.rst @@ -10,45 +10,79 @@ for each release of libCEED. v0.6 (Mar 29, 2020) ---------------------------------------- -libCEED v0.6 was made again publicly available in the third full CEED software -distribution, release CEED 3.0. This release contained notable features, and -substantial additions in the examples suite. Some API changes were introduced, -including the change from ``CeedElemRestrictionCreateIdentity()`` to -``CeedElemRestrictionCreateStrided()`` -and the addition of ``ElemRestriction`` layout mode. The latter change -requires changing use of ``CEED_TRANSPOSE`` and ``CEED_NOTRANSPOSE`` to -``CEED_LAYOUT_NODE_COMPONENT`` and ``CEED_LAYOUT_COMPONENT_NODE``, -respectively, for ``CeedElemRestriction lmode`` in ``CeedElemRestrictionCreate*``. -The user still has the choice of interlacing fields by node, or viceversa, -interlacing nodes by fields, but this choice now is not declared when the -different ``CeedOperator`` fields are set with the ``CeedOperatorSetField()``, -rather when the restriction is created with ``CeedElemRestrictionCreate()``. - -For this release, the libCEED team has deployed libCEED's very first -`user manual `_! -And a C/Python interface, developed using the C Foreign Function Interface -(`CFFI `_) -for Python. CFFI allows to reuse most of the C declarations and requires only a -minimal adaptation of some of them. The C and Python APIs are mapped in a nearly -1:1 correspondence. For instance, data stored in the CeedVector structure are -associated to arrays defined via the numpy package. In fact, since libCEED heavily -relies on pointers and arrays to handle the data, a Python structure that resembles -the C arrays is needed. In details, numpy arrays allow this correspondence obtained -by passing the numpy array memory address as pointers to the libCEED C API. - -Moreover, in this release, libCEED's suite of PETSc application examples has -significantly expanded, including: An expanded Navier-Stokes miniapp, which now -features an implicit time-integration formulation, SU/SUPG stabilization methods, -free slip boundary conditions and quasi-2D computational domain for faster -execution; A Continuum Mechanics example, which features different constitutive -models, such as linear elasticity and hyperelasticity both at small and finite -strain; Calculation of surface areas including the case of the surface of a -cube and a cubed-sphere; And finally, the expansion of the set of PETSc Bakeoff -Problems (BPs) on the cubed-sphere. In what follows, we provide a detailed -description of the added examples. - -Backends available in this release, are the same ones available in :ref:`v0.5`. - +libCEED v0.6 contains numerous new features and examples, as well as expanded +documentation in `this new website `_. + +New features +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +* New Python interface using `CFFI `_ 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 `_. +* 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 `. +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: