Issue 525 FE Basis refactor implementation

.github/workflows/documentation.yml

@@ -10,7 +10,7 @@ jobs:
       - uses: actions/checkout@v4
       - name: Build doxygen documentation
         run: |
-          sudo apt install -y doxygen
+          sudo apt install -y doxygen graphviz
           doxygen Documentation/Doxyfile
       - name: Save documentation
         uses: actions/upload-artifact@v4

Code/Source/solver/CMakeLists.txt

@@ -23,15 +23,18 @@
 # LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 # NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 
-set(CMAKE_CXX_STANDARD 17)
+set(CMAKE_CXX_STANDARD 20)
 set(CMAKE_CXX_STANDARD_REQUIRED True)
 
 include_directories(${SV_SOURCE_DIR}/ThirdParty/eigen/include)
+include_directories(${SV_SOURCE_DIR}/ThirdParty/eigen/include/eigen3)
 include_directories(${SV_SOURCE_DIR}/ThirdParty/parmetis_internal/simvascular_parmetis_internal/ParMETISLib)
 include_directories(${SV_SOURCE_DIR}/ThirdParty/tetgen/simvascular_tetgen)
 include_directories(${SV_SOURCE_DIR}/ThirdParty/tinyxml/simvascular_tinyxml)
 include_directories(${MPI_C_INCLUDE_PATH})
+include_directories(${CMAKE_CURRENT_SOURCE_DIR})
 include_directories(${CMAKE_CURRENT_SOURCE_DIR}/Core)
+include_directories(${CMAKE_CURRENT_SOURCE_DIR}/FE)
 include_directories(${CMAKE_CURRENT_SOURCE_DIR}/FE/Common)
 
 # Find Trilinos package if requested
@@ -86,7 +89,7 @@ endif()
 # add trilinos flags and defines
 if(USE_TRILINOS)
   ADD_DEFINITIONS(-DWITH_TRILINOS)
-  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++11")
+  set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=c++${CMAKE_CXX_STANDARD}")
 endif()
 
 # Build with the PETSc linear algebra package.
@@ -245,9 +248,21 @@ file(GLOB SOLVER_FE_COMMON_SRCS CONFIGURE_DEPENDS
   FE/Common/*.h
 )
 
+file(GLOB SOLVER_FE_BASIS_SRCS CONFIGURE_DEPENDS
+  FE/Basis/*.cpp
+  FE/Basis/*.h
+)
+
+file(GLOB SOLVER_FE_MATH_SRCS CONFIGURE_DEPENDS
+  FE/Math/*.cpp
+  FE/Math/*.h
+)
+
 list(APPEND CSRCS
   ${SOLVER_CORE_SRCS}
   ${SOLVER_FE_COMMON_SRCS}
+  ${SOLVER_FE_BASIS_SRCS}
+  ${SOLVER_FE_MATH_SRCS}
 )
 
   # Set PETSc interace code.
@@ -324,16 +339,24 @@ if(ENABLE_UNIT_TEST)
 
   # link pthread on ubuntu20
   find_package(Threads REQUIRED)
-
+  include(FetchContent)
   # install Google Test
   #if(NOT TARGET gtest_main AND NOT TARGET gtest)
-  include(FetchContent)
   FetchContent_Declare(
-    googletest
-    URL https://github.com/google/googletest/archive/refs/heads/main.zip
-    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+          googletest
+          GIT_REPOSITORY https://github.com/google/googletest.git
+          GIT_TAG v1.17.0
+          DOWNLOAD_EXTRACT_TIMESTAMP TRUE
   )
   FetchContent_MakeAvailable(googletest)
+
+  if(CMAKE_CXX_COMPILER_ID MATCHES "Clang" AND CMAKE_CXX_STANDARD GREATER_EQUAL 20)
+    foreach(GTEST_TARGET gtest gtest_main gmock gmock_main)
+      if(TARGET ${GTEST_TARGET})
+        target_compile_options(${GTEST_TARGET} PRIVATE -std=gnu++17)
+      endif()
+    endforeach()
+  endif()
   #endif()
 
   enable_testing()

Code/Source/solver/Core/Exception.h

@@ -11,6 +11,7 @@
 #include <sstream>
 #include <string>
 #include <string_view>
+#include <type_traits>
 #include <utility>
 #include <vector>
 
@@ -281,12 +282,23 @@ class ExceptionBase : public std::exception {
         rebuild_what();
     }
 
+    /// @brief Record the originating source location and refresh what().
+    ///
+    /// @details Called by raise() after construction, so exception constructors
+    /// do not need to accept (and forward) the file/line/function themselves.
+    void set_source_location(const SourceLocation& location)
+    {
+        context_.set_source_location(location.file, location.line,
+                                     location.function);
+        rebuild_what();
+    }
+
     virtual ~ExceptionBase() noexcept = default;
 
 protected:
     ExceptionBase(std::string message, StatusCode status,
-                  std::string_view subsystem_label, const char* file,
-                  int line, const char* function)
+                  std::string_view subsystem_label, const char* file = "",
+                  int line = 0, const char* function = "")
         : message_(std::move(message)),
           subsystem_label_(subsystem_label.empty() ? std::string_view("Exception")
                                                    : subsystem_label)
@@ -323,28 +335,51 @@ class CoreException : public ExceptionBase {
     }
 };
 
-class ParseException : public CoreException {
-public:
-    ParseException(const std::string& message,
-                   const char* file = "",
-                   int line = 0,
-                   const char* function = "")
-        : CoreException(message, StatusCode::ParseError, file, line, function)
-    {
+/**
+ * @brief Define a simple, message-only exception type in one line.
+ *
+ * @details Expands to a class @p Name deriving from @p Base with a single
+ * `explicit Name(const std::string& message)` constructor that records @p Status.
+ * Use it for exceptions that carry only a message; write the class by hand when it
+ * needs extra structured context (members and accessors). The source location is
+ * stamped by raise(), so no file/line/function constructor is needed.
+ *
+ * @p Base must be an ExceptionBase-derived type whose constructor accepts
+ * `(const std::string&, StatusCode)` (CoreException, FEException, and the
+ * subsystem bases do).
+ *
+ * @code
+ * SVMP_DEFINE_EXCEPTION(ParseException, CoreException, StatusCode::ParseError);
+ * @endcode
+ */
+#define SVMP_DEFINE_EXCEPTION(Name, Base, Status)                              \
+    class Name : public Base {                                                 \
+    public:                                                                    \
+        explicit Name(const std::string& message)                             \
+            : Base(message, (Status))                                          \
+        {                                                                      \
+        }                                                                      \
     }
-};
 
-class DependencyException : public CoreException {
-public:
-    DependencyException(const std::string& message,
-                        const char* file = "",
-                        int line = 0,
-                        const char* function = "")
-        : CoreException(message, StatusCode::DependencyError, file, line,
-                        function)
-    {
-    }
-};
+/// @brief A parsing or input-format error.
+SVMP_DEFINE_EXCEPTION(ParseException, CoreException, StatusCode::ParseError);
+
+/// @brief A required dependency is missing or failed to load.
+SVMP_DEFINE_EXCEPTION(DependencyException, CoreException,
+                      StatusCode::DependencyError);
+
+/// @brief A requested operation or feature is not implemented.
+///
+/// @details The default exception raised by not_implemented().
+SVMP_DEFINE_EXCEPTION(NotImplementedException, CoreException,
+                      StatusCode::NotImplemented);
+
+/// @brief An index is outside its valid range.
+///
+/// @details The default exception raised by check_index(); the status code is
+/// InvalidArgument because an out-of-range index is a caller error.
+SVMP_DEFINE_EXCEPTION(IndexOutOfRangeException, CoreException,
+                      StatusCode::InvalidArgument);
 
 inline void ExceptionRuntime::install_terminate_handler()
 {
@@ -366,37 +401,168 @@ inline void ExceptionRuntime::install_terminate_handler()
     });
 }
 
+/**
+ * @brief A diagnostic message bundled with the source location where it was written.
+ *
+ * @details The core helpers (raise(), check(), throw_if(), check_not_null()) take
+ * a Diagnostic in place of an explicit source location. Its file/line/function
+ * arguments default to the compiler builtins __builtin_FILE()/__builtin_LINE()/
+ * __builtin_FUNCTION(), which capture the caller's location, so a string literal
+ * or std::string passed at the call site is implicitly wrapped into a Diagnostic
+ * that records exactly where the call appears -- callers do not pass SVMP_HERE:
+ * @code
+ * svmp::check<MyException>(ptr != nullptr, "pointer must not be null");
+ * @endcode
+ */
+class Diagnostic {
+public:
+    /**
+     * @brief Wrap a message, capturing the caller's source location by default.
+     * @param message The diagnostic message.
+     * @param file Source file; defaults to the caller's via __builtin_FILE().
+     * @param line Source line; defaults to the caller's via __builtin_LINE().
+     * @param function Function; defaults to the caller's via __builtin_FUNCTION().
+     */
+    Diagnostic(const char* message,
+               const char* file = __builtin_FILE(),
+               int line = __builtin_LINE(),
+               const char* function = __builtin_FUNCTION())
+        : message_(message), location_{file, line, function}
+    {
+    }
+    /**
+     * @brief Wrap a message, capturing the caller's source location by default.
+     * @param message The diagnostic message.
+     * @param file Source file; defaults to the caller's via __builtin_FILE().
+     * @param line Source line; defaults to the caller's via __builtin_LINE().
+     * @param function Function; defaults to the caller's via __builtin_FUNCTION().
+     */
+    Diagnostic(std::string message,
+               const char* file = __builtin_FILE(),
+               int line = __builtin_LINE(),
+               const char* function = __builtin_FUNCTION())
+        : message_(std::move(message)), location_{file, line, function}
+    {
+    }
+
+    /**
+     * @brief The diagnostic message.
+     * @return The stored message.
+     */
+    const std::string& message() const noexcept { return message_; }
+    /**
+     * @brief The source location captured when the Diagnostic was constructed.
+     * @return The stored source location.
+     */
+    const SourceLocation& location() const noexcept { return location_; }
+
+private:
+    std::string message_;
+    SourceLocation location_;
+};
+
+/**
+ * @brief Construct @p ExceptionT from the diagnostic message and @p args, stamp
+ * the source location, and throw it.
+ *
+ * @details @p diagnostic carries the message and the source location captured at
+ * the call site; @p args are forwarded to the exception constructor after the
+ * message. The location is recorded via ExceptionBase::set_source_location(), so
+ * exception types never need a file/line/function constructor -- a `(message)`
+ * (plus any structured-context) constructor is enough.
+ */
 template <class ExceptionT, class... Args>
-[[noreturn]] void raise(SourceLocation location, Args&&... args)
+[[noreturn]] void raise(Diagnostic diagnostic, Args&&... args)
 {
-    throw ExceptionT(std::forward<Args>(args)..., location.file, location.line,
-                     location.function);
+    static_assert(std::is_base_of_v<ExceptionBase, ExceptionT>,
+                  "raise<>() requires an svmp::ExceptionBase-derived exception type");
+    ExceptionT exception(diagnostic.message(), std::forward<Args>(args)...);
+    exception.set_source_location(diagnostic.location());
+    throw exception;
 }
 
+/**
+ * @brief Raise @p ExceptionT when @p condition is false (a required condition).
+ *
+ * @details The general success-condition check, used for argument, state, and
+ * invariant validation: `check<E>(ptr != nullptr, "...")`. throw_if() is the
+ * logical inverse -- it raises when its condition is true.
+ */
 template <class ExceptionT, class... Args>
-void check(bool condition, SourceLocation location, Args&&... args)
+void check(bool condition, Diagnostic diagnostic, Args&&... args)
 {
     if (!condition) {
-        raise<ExceptionT>(location, std::forward<Args>(args)...);
+        raise<ExceptionT>(std::move(diagnostic), std::forward<Args>(args)...);
     }
 }
 
-template <class ExceptionT, class... Args>
-void check_arg(bool condition, SourceLocation location, Args&&... args)
+/**
+ * @brief Raise @p ExceptionT when @p ptr is null.
+ */
+template <class ExceptionT, class PointerT, class... Args>
+void check_not_null(PointerT ptr, Diagnostic diagnostic, Args&&... args)
 {
-    if (!condition) {
-        raise<ExceptionT>(location, std::forward<Args>(args)...);
+    if (ptr == nullptr) {
+        raise<ExceptionT>(std::move(diagnostic), std::forward<Args>(args)...);
     }
 }
 
-template <class ExceptionT, class PointerT, class... Args>
-void check_not_null(PointerT ptr, SourceLocation location, Args&&... args)
+/**
+ * @brief Raise @p ExceptionT when @p condition is true.
+ *
+ * @details The logical inverse of check(): check() raises when its condition is
+ * false (a required condition); throw_if() raises when its condition is true (a
+ * failure condition). The two are not interchangeable.
+ */
+template <class ExceptionT, class... Args>
+void throw_if(bool condition, Diagnostic diagnostic, Args&&... args)
 {
-    if (ptr == nullptr) {
-        raise<ExceptionT>(location, std::forward<Args>(args)...);
+    if (condition) {
+        raise<ExceptionT>(std::move(diagnostic), std::forward<Args>(args)...);
     }
 }
 
+/**
+ * @brief Raise an exception when @p index is outside [0, @p size).
+ *
+ * @details @p ExceptionT defaults to IndexOutOfRangeException; supply a different
+ * type only when a subsystem needs its own exception. The bounds message and the
+ * source location are generated automatically.
+ */
+template <class ExceptionT = IndexOutOfRangeException, class IndexT, class SizeT>
+void check_index(IndexT index, SizeT size,
+                 const char* file = __builtin_FILE(),
+                 int line = __builtin_LINE(),
+                 const char* function = __builtin_FUNCTION())
+{
+    const long long index_value = static_cast<long long>(index);
+    const long long size_value = static_cast<long long>(size);
+    check<ExceptionT>(
+        index_value >= 0 && index_value < size_value,
+        Diagnostic("Index " + std::to_string(index_value) + " out of bounds [0, " +
+                       std::to_string(size_value) + ")",
+                   file, line, function));
+}
+
+/**
+ * @brief Raise an exception reporting an unimplemented feature, with a message.
+ *
+ * @details @p ExceptionT defaults to NotImplementedException, so most call sites
+ * pass only a message:
+ * @code
+ * svmp::not_implemented("GPU assembly is not supported");
+ * @endcode
+ * Pass a different exception type explicitly only when a subsystem needs one.
+ */
+template <class ExceptionT = NotImplementedException>
+[[noreturn]] void not_implemented(std::string message,
+                                  const char* file = __builtin_FILE(),
+                                  int line = __builtin_LINE(),
+                                  const char* function = __builtin_FUNCTION())
+{
+    raise<ExceptionT>(Diagnostic(std::move(message), file, line, function));
+}
+
 } // namespace svmp
 
 #define SVMP_HERE ::svmp::SourceLocation{__FILE__, __LINE__, __func__}
@@ -405,7 +571,7 @@ void check_not_null(PointerT ptr, SourceLocation location, Args&&... args)
 #define SVMP_DEBUG_CHECK(ExceptionT, condition, ...)                         \
     do {                                                                     \
         if (!(condition)) {                                                  \
-            ::svmp::raise<ExceptionT>(SVMP_HERE, __VA_ARGS__);               \
+            ::svmp::raise<ExceptionT>(__VA_ARGS__);                          \
         }                                                                    \
     } while (false)
 #else