FEniCS · garth-wells · Feb 11, 2023 · Feb 11, 2023 · Feb 11, 2023 · Feb 11, 2023
diff --git a/cpp/demo/interpolation_different_meshes/main.cpp b/cpp/demo/interpolation_different_meshes/main.cpp
@@ -5,7 +5,7 @@
 // SPDX-License-Identifier:    LGPL-3.0-or-later
 
 #include <basix/e-lagrange.h>
-#include <dolfinx/fem/dolfin_fem.h>
+#include <dolfinx/fem/dolfinx_fem.h>
 #include <dolfinx/io/ADIOS2Writers.h>
 #include <dolfinx/mesh/generation.h>
 #include <memory>

diff --git a/cpp/dolfinx/common/CMakeLists.txt b/cpp/dolfinx/common/CMakeLists.txt
@@ -1,32 +1,32 @@
 set(HEADERS_common
-    ${CMAKE_CURRENT_SOURCE_DIR}/defines.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/dolfin_common.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/dolfin_doc.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/IndexMap.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/log.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/loguru.hpp
-    ${CMAKE_CURRENT_SOURCE_DIR}/sort.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/math.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/MPI.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/Scatterer.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/Table.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/Timer.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogger.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogManager.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/timing.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils.h
-    PARENT_SCOPE
+  ${CMAKE_CURRENT_SOURCE_DIR}/defines.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/dolfinx_common.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/dolfinx_doc.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/IndexMap.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/log.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/loguru.hpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/sort.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/math.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/MPI.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/Scatterer.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/Table.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/Timer.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogger.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogManager.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/timing.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/utils.h
+  PARENT_SCOPE
 )
 
 target_sources(
   dolfinx
   PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/defines.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/IndexMap.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/log.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/MPI.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/Table.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/Timer.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogger.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogManager.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/timing.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/IndexMap.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/log.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/MPI.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/Table.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/Timer.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogger.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/TimeLogManager.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/timing.cpp
 )
diff --git a/cpp/dolfinx/common/MPI.h b/cpp/dolfinx/common/MPI.h
@@ -25,7 +25,7 @@
 #define MPICH_IGNORE_CXX_SEEK 1
 #include <mpi.h>
 
-/// MPI support functionality
+/// @brief MPI support functionality
 namespace dolfinx::MPI
 {
 
@@ -36,8 +36,8 @@ enum class tag : int
   consensus_pex
 };
 
-/// A duplicate MPI communicator and manage lifetime of the
-/// communicator
+/// @brief A duplicate MPI communicator and manage lifetime of the
+/// communicator.
 class Comm
 {
 public:

diff --git a/cpp/dolfinx/common/dolfin_common.h → cpp/dolfinx/common/dolfinx_common.h b/cpp/dolfinx/common/dolfin_common.h → cpp/dolfinx/common/dolfinx_common.h
@@ -1,13 +1,12 @@
 #pragma once
 
-namespace dolfinx
-{
-/*! \namespace dolfinx::common
-    \brief Miscellaneous classes, functions and types
 
-    This namespace provides utility type functions for managing subsystems,
-   convenience classes and library-wide typedefs.
-*/
+/// @brief Miscellaneous classes, functions and types.
+///
+/// This namespace provides utility type functions for managing
+/// subsystems, convenience classes and library-wide typedefs.
+namespace dolfinx::common
+{
 }
 
 // DOLFINx common

diff --git a/cpp/dolfinx/common/dolfin_doc.h → cpp/dolfinx/common/dolfinx_doc.h b/cpp/dolfinx/common/dolfin_doc.h → cpp/dolfinx/common/dolfinx_doc.h
diff --git a/cpp/dolfinx/common/utils.h b/cpp/dolfinx/common/utils.h
@@ -13,6 +13,7 @@
 #include <utility>
 #include <vector>
 
+/// @namespace Generic tools
 namespace dolfinx::common
 {
 

diff --git a/cpp/dolfinx/dolfinx.h b/cpp/dolfinx/dolfinx.h
@@ -1,13 +1,18 @@
 #pragma once
 
+/// @brief Top-level namespace
+namespace dolfinx
+{
+}
+
 // DOLFINx interface
 
-#include <dolfinx/common/dolfin_common.h>
-#include <dolfinx/fem/dolfin_fem.h>
-#include <dolfinx/geometry/dolfin_geometry.h>
-#include <dolfinx/graph/dolfin_graph.h>
-#include <dolfinx/io/dolfin_io.h>
-#include <dolfinx/la/dolfin_la.h>
-#include <dolfinx/mesh/dolfin_mesh.h>
-#include <dolfinx/nls/dolfin_nls.h>
-#include <dolfinx/refinement/dolfin_refinement.h>
+#include <dolfinx/common/dolfinx_common.h>
+#include <dolfinx/fem/dolfinx_fem.h>
+#include <dolfinx/geometry/dolfinx_geometry.h>
+#include <dolfinx/graph/dolfinx_graph.h>
+#include <dolfinx/io/dolfinx_io.h>
+#include <dolfinx/la/dolfinx_la.h>
+#include <dolfinx/mesh/dolfinx_mesh.h>
+#include <dolfinx/nls/dolfinx_nls.h>
+#include <dolfinx/refinement/dolfinx_refinement.h>
diff --git a/cpp/dolfinx/fem/CMakeLists.txt b/cpp/dolfinx/fem/CMakeLists.txt
@@ -1,39 +1,39 @@
 set(HEADERS_fem
-    ${CMAKE_CURRENT_SOURCE_DIR}/Constant.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/CoordinateElement.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/DirichletBC.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/DofMap.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/ElementDofLayout.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/Expression.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/FiniteElement.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/Form.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/Function.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/FunctionSpace.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/assembler.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/assemble_matrix_impl.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/assemble_scalar_impl.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/assemble_vector_impl.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/discreteoperators.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/dofmapbuilder.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/dolfin_fem.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/interpolate.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/petsc.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/sparsitybuild.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils.h
-    PARENT_SCOPE
+  ${CMAKE_CURRENT_SOURCE_DIR}/Constant.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/CoordinateElement.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/DirichletBC.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/DofMap.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/ElementDofLayout.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/Expression.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/FiniteElement.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/Form.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/Function.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/FunctionSpace.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/assembler.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/assemble_matrix_impl.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/assemble_scalar_impl.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/assemble_vector_impl.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/discreteoperators.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/dofmapbuilder.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/dolfinx_fem.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/interpolate.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/petsc.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/sparsitybuild.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/utils.h
+  PARENT_SCOPE
 )
 
 target_sources(
   dolfinx
   PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/DirichletBC.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/CoordinateElement.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/DofMap.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/ElementDofLayout.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/FiniteElement.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/FunctionSpace.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/dofmapbuilder.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/interpolate.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/petsc.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/sparsitybuild.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/utils.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/CoordinateElement.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/DofMap.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/ElementDofLayout.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/FiniteElement.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/FunctionSpace.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/dofmapbuilder.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/interpolate.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/petsc.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/sparsitybuild.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/utils.cpp
 )
diff --git a/cpp/dolfinx/fem/DofMap.cpp b/cpp/dolfinx/fem/DofMap.cpp
@@ -182,7 +182,7 @@ bool DofMap::operator==(const DofMap& map) const
 //-----------------------------------------------------------------------------
 int DofMap::bs() const noexcept { return _bs; }
 //-----------------------------------------------------------------------------
-DofMap DofMap::extract_sub_dofmap(const std::vector<int>& component) const
+DofMap DofMap::extract_sub_dofmap(std::span<const int> component) const
 {
   assert(!component.empty());
 

diff --git a/cpp/dolfinx/fem/DofMap.h b/cpp/dolfinx/fem/DofMap.h
@@ -129,7 +129,7 @@ class DofMap
   /// @brief Extract subdofmap component
   /// @param[in] component The component indices
   /// @return The dofmap for the component
-  DofMap extract_sub_dofmap(const std::vector<int>& component) const;
+  DofMap extract_sub_dofmap(std::span<const int> component) const;
 
   /// @brief Create a "collapsed" dofmap (collapses a sub-dofmap)
   /// @param[in] comm MPI Communicator

diff --git a/cpp/dolfinx/fem/assemble_vector_impl.h b/cpp/dolfinx/fem/assemble_vector_impl.h
@@ -869,7 +869,7 @@ void lift_bc(std::span<T> b, const Form<T>& a, std::span<const T> constants,
 /// @param[in] scale Scaling to apply
 template <typename T>
 void apply_lifting(
-    std::span<T> b, const std::vector<std::shared_ptr<const Form<T>>> a,
+    std::span<T> b, std::vector<std::shared_ptr<const Form<T>>> a,
     const std::vector<std::span<const T>>& constants,
     const std::vector<std::map<std::pair<IntegralType, int>,
                                std::pair<std::span<const T>, int>>>& coeffs,

diff --git a/cpp/dolfinx/fem/dolfin_fem.h → cpp/dolfinx/fem/dolfinx_fem.h b/cpp/dolfinx/fem/dolfin_fem.h → cpp/dolfinx/fem/dolfinx_fem.h
@@ -1,12 +1,11 @@
 #pragma once
 
-namespace dolfinx
+/// @brief Finite element method functionality
+///
+/// Classes and algorithms for finite element method spaces and
+/// operations.
+namespace dolfinx::fem
 {
-/*! \namespace dolfinx::fem
-    \brief Finite element method functionality
-
-    Classes and algorithms for finite element method spaces and operations.
-*/
 }
 
 // DOLFINx fem interface

diff --git a/cpp/dolfinx/fem/petsc.h b/cpp/dolfinx/fem/petsc.h
@@ -26,7 +26,7 @@ template <typename T>
 class DirichletBC;
 class FunctionSpace;
 
-/// Helper functions for assembly into PETSc data structures
+/// @brief Helper functions for assembly into PETSc data structures
 namespace petsc
 {
 /// Create a matrix
@@ -71,9 +71,10 @@ Vec create_vector_nest(
 
 // -- Vectors ----------------------------------------------------------------
 
-/// Assemble linear form into an already allocated PETSc vector. Ghost
-/// contributions are not accumulated (not sent to owner). Caller is
-/// responsible for calling VecGhostUpdateBegin/End.
+/// @brief Assemble linear form into an already allocated PETSc vector.
+///
+/// Ghost contributions are not accumulated (not sent to owner). Caller
+/// is responsible for calling `VecGhostUpdateBegin/End`.
 ///
 /// @param[in,out] b The PETsc vector to assemble the form into. The
 /// vector must already be initialised with the correct size. The
@@ -104,6 +105,9 @@ void assemble_vector(Vec b, const Form<PetscScalar>& L);
 // FIXME: need to pass an array of Vec for x0?
 // FIXME: clarify zeroing of vector
 
+/// @brief Modify RHS vector to account for Dirichlet boundary
+/// conditions.
+///
 /// Modify b such that:
 ///
 ///   b <- b - scale * A_j (g_j - x0_j)

diff --git a/cpp/dolfinx/geometry/CMakeLists.txt b/cpp/dolfinx/geometry/CMakeLists.txt
@@ -1,14 +1,14 @@
 set(HEADERS_geometry
-    ${CMAKE_CURRENT_SOURCE_DIR}/BoundingBoxTree.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/gjk.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/dolfin_geometry.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/utils.h
-    PARENT_SCOPE
+  ${CMAKE_CURRENT_SOURCE_DIR}/BoundingBoxTree.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/gjk.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/dolfinx_geometry.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/utils.h
+  PARENT_SCOPE
 )
 
 target_sources(
   dolfinx
   PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/BoundingBoxTree.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/gjk.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/utils.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/gjk.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/utils.cpp
 )
diff --git a/cpp/dolfinx/geometry/dolfin_geometry.h b/cpp/dolfinx/geometry/dolfin_geometry.h
diff --git a/cpp/dolfinx/geometry/dolfinx_geometry.h b/cpp/dolfinx/geometry/dolfinx_geometry.h
@@ -0,0 +1,13 @@
+#pragma once
+
+/// @brief Geometry data structures and algorithms
+///
+/// Tools for geometric data structures and operations, e.g. searching.
+namespace dolfinx::geometry
+{
+}
+
+// DOLFINx geometry interface
+
+#include <dolfinx/geometry/BoundingBoxTree.h>
+#include <dolfinx/geometry/gjk.h>
diff --git a/cpp/dolfinx/graph/CMakeLists.txt b/cpp/dolfinx/graph/CMakeLists.txt
@@ -1,15 +1,15 @@
 set(HEADERS_graph
-    ${CMAKE_CURRENT_SOURCE_DIR}/AdjacencyList.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/dolfin_graph.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/ordering.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/partitioners.h
-    ${CMAKE_CURRENT_SOURCE_DIR}/partition.h
-    PARENT_SCOPE
+  ${CMAKE_CURRENT_SOURCE_DIR}/AdjacencyList.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/dolfinx_graph.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/ordering.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/partitioners.h
+  ${CMAKE_CURRENT_SOURCE_DIR}/partition.h
+  PARENT_SCOPE
 )
 
 target_sources(
   dolfinx
   PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/ordering.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/partitioners.cpp
-          ${CMAKE_CURRENT_SOURCE_DIR}/partition.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/partitioners.cpp
+  ${CMAKE_CURRENT_SOURCE_DIR}/partition.cpp
 )
diff --git a/cpp/dolfinx/graph/dolfin_graph.h b/cpp/dolfinx/graph/dolfin_graph.h
diff --git a/cpp/dolfinx/graph/dolfinx_graph.h b/cpp/dolfinx/graph/dolfinx_graph.h
@@ -0,0 +1,13 @@
+#pragma once
+
+/// @brief Graph data structures and algorithms.
+///
+/// Data structures for building and representing graphs, and algorithms
+/// on graphs, e.g., re-ordering and partitioning.
+namespace dolfinx::graph
+{
+}
+
+// DOLFINx graph interface
+
+#include <dolfinx/graph/partition.h>