Add timestepper

CMakeLists.txt

@@ -45,6 +45,7 @@ option(PCMS_ENABLE_CLIENT "enable the coupling client implementation" ON)
 option(PCMS_ENABLE_XGC "enable xgc field adapter" ON)
 option(PCMS_ENABLE_OMEGA_H "enable Omega_h field adapter" OFF)
 option(PCMS_ENABLE_MFEM "enable MFEM field adapter" OFF)
+option(PCMS_ENABLE_TRANSIENT "Enable pcms transient module" ON)
 option(PCMS_ENABLE_C "Enable pcms C api" ON)
 option(PCMS_ENABLE_Python "Enable pcms Python api" OFF)
 

config.cmake.in

@@ -34,6 +34,9 @@ if(@PCMS_ENABLE_MFEM@)
 endif()
 
 include("${CMAKE_CURRENT_LIST_DIR}/pcms_utility-targets.cmake")
+if(@PCMS_ENABLE_TRANSIENT@)
+    include("${CMAKE_CURRENT_LIST_DIR}/pcms_transient-targets.cmake")
+endif()
 include("${CMAKE_CURRENT_LIST_DIR}/pcms_discretization-targets.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/pcms_localization-targets.cmake")
 include("${CMAKE_CURRENT_LIST_DIR}/pcms_field-targets.cmake")

src/CMakeLists.txt

@@ -14,6 +14,9 @@ configure_file(pcms/configuration.h.in pcms/configuration.h)
 list(APPEND PCMS_HEADERS ${CMAKE_CURRENT_BINARY_DIR}/pcms/version.h ${CMAKE_CURRENT_BINARY_DIR}/pcms/configuration.h)
 
 add_subdirectory(pcms/utility)
+if(PCMS_ENABLE_TRANSIENT)
+  add_subdirectory(pcms/transient)
+endif()
 add_subdirectory(pcms/discretization)
 add_subdirectory(pcms/localization)
 add_subdirectory(pcms/field)
@@ -88,6 +91,9 @@ install(
 
 add_library(pcms_pcms INTERFACE)
 target_link_libraries(pcms_pcms INTERFACE pcms::core)
+if(PCMS_ENABLE_TRANSIENT)
+  target_link_libraries(pcms_pcms INTERFACE pcms::transient)
+endif()
 set_target_properties(pcms_pcms PROPERTIES EXPORT_NAME pcms)
 if (PCMS_ENABLE_Python)
   # Disable LTO/IPO before adding Python subdirectory to avoid fatbinData conflicts

src/pcms/configuration.h.in

@@ -4,6 +4,7 @@
 #cmakedefine PCMS_ENABLE_OMEGA_H
 #cmakedefine PCMS_ENABLE_MFEM
 #cmakedefine PCMS_ENABLE_C
+#cmakedefine PCMS_ENABLE_TRANSIENT
 #cmakedefine PCMS_ENABLE_PRINT
 #cmakedefine PCMS_ENABLE_Fortran
 #cmakedefine PCMS_ENABLE_MESHFIELDS

src/pcms/transient/CMakeLists.txt

@@ -0,0 +1,33 @@
+set(PCMS_TRANSIENT_HEADERS timestepper.hpp)
+set(PCMS_TRANSIENT_SOURCES timestepper.cpp)
+
+add_library(pcms_transient ${PCMS_TRANSIENT_SOURCES})
+set_target_properties(pcms_transient PROPERTIES EXPORT_NAME transient)
+add_library(pcms::transient ALIAS pcms_transient)
+
+target_sources(
+  pcms_transient
+  PUBLIC FILE_SET transient
+         TYPE HEADERS
+         BASE_DIRS ${CMAKE_CURRENT_SOURCE_DIR}/..
+         FILES ${PCMS_TRANSIENT_HEADERS})
+target_compile_features(pcms_transient PUBLIC cxx_std_20)
+target_link_libraries(pcms_transient PUBLIC pcms::utility)
+target_include_directories(
+  pcms_transient
+  PUBLIC $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/../..>
+         $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>)
+
+install(
+  TARGETS pcms_transient
+  EXPORT pcms_transient-targets
+  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
+  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
+  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/pcms/transient
+  FILE_SET transient DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/pcms)
+
+install(
+  EXPORT pcms_transient-targets
+  NAMESPACE pcms::
+  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/pcms)

src/pcms/transient/timestepper.cpp

@@ -0,0 +1,18 @@
+#include "pcms/transient/timestepper.hpp"
+
+namespace pcms
+{
+
+FixedTimestepper::FixedTimestepper(Real dt) : dt_(dt) {}
+
+Real FixedTimestepper::InitialStep() const
+{
+  return dt_;
+}
+
+Step FixedTimestepper::UpdateStep(Real, Real)
+{
+  return {true, dt_};
+}
+
+} // namespace pcms

src/pcms/transient/timestepper.hpp

@@ -0,0 +1,54 @@
+#ifndef PCMS_TRANSIENT_TIMESTEPPER_HPP
+#define PCMS_TRANSIENT_TIMESTEPPER_HPP
+
+#include "pcms/utility/types.h"
+
+namespace pcms
+{
+
+/// Result of Timestepper::UpdateStep.
+struct Step
+{
+  /// Whether the completed time window is accepted.
+  bool accepted;
+  /// Positive step size to try next.
+  Real next_step;
+};
+
+/// Decides whether to accept a completed time window and selects the next step.
+class Timestepper
+{
+public:
+  /// \return The positive step size used for the first coupling window.
+  [[nodiscard]] virtual Real InitialStep() const = 0;
+
+  /// Decide whether to accept a completed time window and pick the next step.
+  /// \param dt  The time step that was actually completed.
+  /// \param err Normalized error of the completed step.
+  /// \return Whether the step is accepted and the positive step size to try
+  /// next.
+  [[nodiscard]] virtual Step UpdateStep(Real dt, Real err) = 0;
+
+  virtual ~Timestepper() = default;
+};
+
+/// Always accepts and keeps a constant time step.
+class FixedTimestepper : public Timestepper
+{
+public:
+  /// \param dt Positive step size used for every window.
+  explicit FixedTimestepper(Real dt);
+
+  /// \return The configured fixed step.
+  Real InitialStep() const override;
+
+  /// Ignores \p dt and \p err; always accepts and returns the fixed step.
+  Step UpdateStep(Real dt, Real err) override;
+
+private:
+  Real dt_;
+};
+
+} // namespace pcms
+
+#endif // PCMS_TRANSIENT_TIMESTEPPER_HPP

test/CMakeLists.txt

@@ -489,6 +489,12 @@ if(Catch2_FOUND)
 
  include(Catch)
    Catch_discover_tests(unit_tests)
+   if(PCMS_ENABLE_TRANSIENT)
+     add_executable(test_transient_timestepper test_transient_timestepper.cpp)
+     target_link_libraries(test_transient_timestepper
+             PRIVATE Catch2::Catch2WithMain pcms::transient)
+     Catch_discover_tests(test_transient_timestepper)
+   endif()
 else()
   message(WARNING "Catch2 not found. Disabling Unit Tests")
 endif()

test/test_transient_timestepper.cpp

@@ -0,0 +1,21 @@
+#include <catch2/catch_approx.hpp>
+#include <catch2/catch_test_macros.hpp>
+
+#include "pcms/transient/timestepper.hpp"
+
+using namespace pcms;
+
+TEST_CASE("FixedTimestepper always accepts its configured step", "[transient]")
+{
+  // 0.25 represents a positive fixed window size.
+  FixedTimestepper timestepper(0.25);
+
+  // The completed step (0.1) and large normalized error (100).
+  // A fixed controller ignores both.
+  const auto [accepted, next_step] = timestepper.UpdateStep(0.1, 100.0);
+
+  // The first window must use the user-configured size.
+  REQUIRE(timestepper.InitialStep() == Catch::Approx(0.25));
+  REQUIRE(accepted);
+  REQUIRE(next_step == Catch::Approx(0.25));
+}