Merge branch 'mahf708/emulators/inference' (PR #8048)

adding a mostly performative/stub inference backend (we will add libtorch,
pytroch, lapis, onnxruntime, etc. in the future).

[BFB]

Author: jeff-cohere

components/emulators/common/src/CMakeLists.txt

@@ -1,11 +1,14 @@
-# Common source library
+# Common emulator library
 
 add_library(emulator_common
   emulator.cpp
+  inference/stub_inference_backend.cpp
+  inference/create_inference_backend.cpp
 )
 
 target_compile_features(emulator_common PUBLIC cxx_std_17)
 
 target_include_directories(emulator_common PUBLIC
   ${CMAKE_CURRENT_SOURCE_DIR}
+  ${CMAKE_CURRENT_SOURCE_DIR}/inference
 )

components/emulators/common/src/emulator.hpp

@@ -3,8 +3,8 @@
  * @brief Abstract base class for all E3SM emulators.
  */
 
-#ifndef EMULATOR_HPP
-#define EMULATOR_HPP
+#ifndef E3SM_EMULATOR_HPP
+#define E3SM_EMULATOR_HPP
 
 #include <string>
 
@@ -67,4 +67,4 @@ class Emulator {
 
 } // namespace emulator
 
-#endif // EMULATOR_HPP
+#endif // E3SM_EMULATOR_HPP

components/emulators/common/src/emulator_registry.hpp

@@ -6,8 +6,8 @@
  * for creating and retrieving emulator instances by name.
  */
 
-#ifndef EMULATOR_REGISTRY_HPP
-#define EMULATOR_REGISTRY_HPP
+#ifndef E3SM_EMULATOR_REGISTRY_HPP
+#define E3SM_EMULATOR_REGISTRY_HPP
 
 #include <any>
 #include <memory>
@@ -154,4 +154,4 @@ inline void cleanup_emulator_registry() {
 
 } // namespace emulator
 
-#endif // EMULATOR_REGISTRY_HPP
+#endif // E3SM_EMULATOR_REGISTRY_HPP

components/emulators/common/src/inference/create_inference_backend.cpp

@@ -0,0 +1,23 @@
+/**
+ * @file create_backend.cpp
+ * @brief Factory for creating inference backends.
+ */
+
+#include "create_inference_backend.hpp"
+#include "stub_inference_backend.hpp"
+
+namespace emulator {
+namespace inference {
+
+std::shared_ptr<InferenceBackend>
+create_backend(BackendType type, const InferenceConfig &config) {
+  switch (type) {
+  case BackendType::STUB:
+    return std::make_shared<StubBackend>(config);
+  default:
+    return std::make_shared<StubBackend>(config);
+  }
+}
+
+} // namespace inference
+} // namespace emulator

components/emulators/common/src/inference/create_inference_backend.hpp

@@ -0,0 +1,28 @@
+/**
+ * @file create_backend.hpp
+ * @brief Factory for creating inference backends.
+ */
+
+#ifndef E3SM_EMULATOR_CREATE_INFERENCE_BACKEND_HPP
+#define E3SM_EMULATOR_CREATE_INFERENCE_BACKEND_HPP
+
+#include <memory>
+
+#include "inference_backend.hpp"
+
+namespace emulator {
+namespace inference {
+
+/**
+ * @brief Create an inference backend by type.
+ * @param type Backend type to create
+ * @param config Configuration for the backend
+ * @return Shared pointer to new backend instance
+ */
+std::shared_ptr<InferenceBackend>
+create_backend(BackendType type, const InferenceConfig &config);
+
+} // namespace inference
+} // namespace emulator
+
+#endif // E3SM_EMULATOR_CREATE_INFERENCE_BACKEND_HPP

components/emulators/common/src/inference/inference_backend.hpp

@@ -0,0 +1,73 @@
+/**
+ * @file inference_backend.hpp
+ * @brief Abstract interface for neural network inference backends.
+ */
+
+#ifndef E3SM_EMULATOR_INFERENCE_BACKEND_HPP
+#define E3SM_EMULATOR_INFERENCE_BACKEND_HPP
+
+#include <string>
+
+namespace emulator {
+namespace inference {
+
+/**
+ * @brief Enumeration of available inference backend types.
+ */
+enum class BackendType {
+  STUB, ///< No-op backend for testing (no ML dependencies)
+};
+
+/**
+ * @brief Minimal configuration for inference backends.
+ */
+struct InferenceConfig {
+  int input_channels = 0;  ///< Number of input features per grid point
+  int output_channels = 0; ///< Number of output features per grid point
+  bool verbose = false;    ///< Enable verbose output (for debugging)
+};
+
+/**
+ * @brief Abstract interface for inference backends.
+ *
+ * Provides a unified API for running neural network inference.
+ * All backends:
+ * - Accept input as a flat array [batch_size * input_channels]
+ * - Produce output as a flat array [batch_size * output_channels]
+ *
+ * Backends are fully configured on construction (config is passed
+ * to the constructor). No separate initialization step is needed.
+ */
+class InferenceBackend {
+public:
+  explicit InferenceBackend(const InferenceConfig &config) : m_config(config) {}
+  virtual ~InferenceBackend() = default;
+
+  /**
+   * @brief Run inference on input data.
+   * @param inputs  Input data array [batch_size * input_channels]
+   * @param outputs Output data array [batch_size * output_channels]
+   * @param batch_size Number of samples in the batch
+   * @return true if inference succeeded
+   */
+  virtual bool infer(const double *inputs, double *outputs,
+                     int batch_size = 1) = 0;
+
+  /**
+   * @brief Release resources and finalize the backend.
+   */
+  virtual void finalize() = 0;
+
+  /**
+   * @brief Get the human-readable name of this backend.
+   */
+  virtual std::string name() const = 0;
+
+protected:
+  InferenceConfig m_config; ///< Backend configuration
+};
+
+} // namespace inference
+} // namespace emulator
+
+#endif // E3SM_EMULATOR_INFERENCE_BACKEND_HPP

components/emulators/common/src/inference/stub_inference_backend.cpp

@@ -0,0 +1,42 @@
+/**
+ * @file stub_backend.cpp
+ * @brief Stub inference backend implementation.
+ *
+ * Provides a no-op backend for testing the emulator framework without
+ * requiring ML dependencies. Leaves outputs unchanged.
+ */
+
+#include "stub_inference_backend.hpp"
+
+namespace emulator {
+namespace inference {
+
+/**
+ * @brief Run stub inference (no-op).
+ *
+ * Leaves outputs unchanged. Useful for testing the data pipeline
+ * without actual model inference.
+ *
+ * @param inputs  Input data (unused)
+ * @param outputs Output data (unchanged)
+ * @param batch_size Number of samples in batch (unused)
+ * @return Always returns true
+ */
+bool StubBackend::infer(const double *inputs, double *outputs, int batch_size) {
+  (void)inputs;     // Unused
+  (void)outputs;    // Unchanged
+  (void)batch_size; // Unused
+
+  // No-op: leave outputs unchanged
+  return true;
+}
+
+/**
+ * @brief Finalize the stub backend.
+ *
+ * No-op for stub backend; included for interface compliance.
+ */
+void StubBackend::finalize() {}
+
+} // namespace inference
+} // namespace emulator

components/emulators/common/src/inference/stub_inference_backend.hpp

@@ -0,0 +1,42 @@
+/**
+ * @file stub_backend.hpp
+ * @brief Stub inference backend for testing without ML dependencies.
+ */
+
+#ifndef E3SM_EMULATOR_STUB_INFERENCE_BACKEND_HPP
+#define E3SM_EMULATOR_STUB_INFERENCE_BACKEND_HPP
+
+#include "inference_backend.hpp"
+
+namespace emulator {
+namespace inference {
+
+/**
+ * @brief Stub backend for testing without actual inference.
+ *
+ * Leaves outputs unchanged. Useful for testing the data pipeline
+ * without actual model inference.
+ *
+ * @see InferenceBackend for the base interface
+ */
+class StubBackend : public InferenceBackend {
+public:
+  explicit StubBackend(const InferenceConfig &config)
+      : InferenceBackend(config) {}
+  ~StubBackend() override = default;
+
+  /// @copydoc InferenceBackend::infer
+  bool infer(const double *inputs, double *outputs,
+             int batch_size = 1) override;
+
+  /// @copydoc InferenceBackend::finalize
+  void finalize() override;
+
+  /// @copydoc InferenceBackend::name
+  std::string name() const override { return "Stub"; }
+};
+
+} // namespace inference
+} // namespace emulator
+
+#endif // E3SM_EMULATOR_STUB_INFERENCE_BACKEND_HPP

components/emulators/common/tests/CMakeLists.txt

@@ -11,3 +11,17 @@ add_executable(test_emulator test_emulator.cpp)
 target_link_libraries(test_emulator PRIVATE emulator_common)
 target_include_directories(test_emulator PRIVATE ${CATCH2_INCLUDE_DIR})
 add_test(NAME emulator_tests COMMAND test_emulator)
+
+# Test for InferenceConfig and utilities
+add_executable(test_inference_config test_inference_config.cpp)
+target_link_libraries(test_inference_config PRIVATE emulator_common)
+target_include_directories(test_inference_config PRIVATE ${CATCH2_INCLUDE_DIR})
+add_test(NAME inference_config_tests COMMAND test_inference_config)
+
+# Test for StubBackend
+add_executable(test_inference_stub_backend test_inference_stub_backend.cpp)
+target_link_libraries(test_inference_stub_backend PRIVATE emulator_common)
+target_include_directories(test_inference_stub_backend PRIVATE ${CATCH2_INCLUDE_DIR})
+add_test(NAME inference_stub_backend_tests COMMAND test_inference_stub_backend)
+
+

components/emulators/common/tests/test_inference_config.cpp

@@ -0,0 +1,32 @@
+// Catch2 v2 single header
+#define CATCH_CONFIG_MAIN
+#include <catch2/catch.hpp>
+
+#include "create_inference_backend.hpp"
+
+namespace emulator {
+namespace inference {
+namespace test {
+
+TEST_CASE("InferenceConfig defaults", "[inference_config]") {
+  InferenceConfig config;
+
+  REQUIRE(config.input_channels == 0);
+  REQUIRE(config.output_channels == 0);
+  REQUIRE_FALSE(config.verbose);
+}
+
+TEST_CASE("InferenceConfig can be set", "[inference_config]") {
+  InferenceConfig config;
+  config.input_channels = 10;
+  config.output_channels = 5;
+  config.verbose = true;
+
+  REQUIRE(config.input_channels == 10);
+  REQUIRE(config.output_channels == 5);
+  REQUIRE(config.verbose);
+}
+
+} // namespace test
+} // namespace inference
+} // namespace emulator