✨ QDMI authentication via FoMaC

bindings/fomac/fomac.cpp

@@ -26,6 +26,23 @@ namespace py = pybind11;
 using namespace py::literals;
 
 PYBIND11_MODULE(MQT_CORE_MODULE_NAME, m, py::mod_gil_not_used()) {
+  // SessionParameter enum
+  py::native_enum<fomac::SessionParameter>(
+      m, "SessionParameter", "enum.Enum",
+      "Session parameters for authentication and configuration.")
+      .value("TOKEN", fomac::SessionParameter::TOKEN)
+      .value("AUTHFILE", fomac::SessionParameter::AUTHFILE)
+      .value("AUTHURL", fomac::SessionParameter::AUTHURL)
+      .value("USERNAME", fomac::SessionParameter::USERNAME)
+      .value("PASSWORD", fomac::SessionParameter::PASSWORD)
+      .value("PROJECTID", fomac::SessionParameter::PROJECTID)
+      .value("CUSTOM1", fomac::SessionParameter::CUSTOM1)
+      .value("CUSTOM2", fomac::SessionParameter::CUSTOM2)
+      .value("CUSTOM3", fomac::SessionParameter::CUSTOM3)
+      .value("CUSTOM4", fomac::SessionParameter::CUSTOM4)
+      .value("CUSTOM5", fomac::SessionParameter::CUSTOM5)
+      .finalize();
+
   // Job class
   auto job = py::class_<fomac::FoMaC::Job>(m, "Job");
   job.def("check", &fomac::FoMaC::Job::check);
@@ -183,7 +200,17 @@ PYBIND11_MODULE(MQT_CORE_MODULE_NAME, m, py::mod_gil_not_used()) {
   device.def(py::self == py::self); // NOLINT(misc-redundant-expression)
   device.def(py::self != py::self); // NOLINT(misc-redundant-expression)
 
-  m.def("devices", &fomac::FoMaC::getDevices);
+  // FoMaC class (exposed as Session in Python)
+  auto fomac = py::class_<fomac::FoMaC>(m, "Session");
+  fomac.def(py::init<>());
+  fomac.def("set_session_parameter", &fomac::FoMaC::setSessionParameter,
+            "param"_a, "value"_a);
+  fomac.def("get_devices", &fomac::FoMaC::getDevices);
+
+  // Module-level convenience functions (use default session)
+  m.def("set_session_parameter", &fomac::setSessionParameter, "param"_a,
+        "value"_a);
+  m.def("devices", &fomac::getDevices);
 }
 
 } // namespace mqt

include/mqt-core/fomac/FoMaC.hpp

@@ -18,11 +18,13 @@
 #include <iostream>
 #include <iterator>
 #include <map>
+#include <mutex>
 #include <optional>
 #include <qdmi/client.h>
 #include <ranges>
 #include <string>
 #include <type_traits>
+#include <unordered_map>
 #include <utility>
 #include <vector>
 
@@ -141,30 +143,64 @@ concept maybe_optional_value_or_string_or_vector =
     value_or_string_or_vector<remove_optional_t<T>>;
 
 /// @returns the string representation of the given QDMI_STATUS.
-auto toString(QDMI_STATUS result) -> std::string;
+auto toString(const QDMI_STATUS result) -> std::string;
 
 /// @returns the string representation of the given QDMI_Site_Property.
-auto toString(QDMI_Site_Property prop) -> std::string;
+auto toString(const QDMI_Site_Property prop) -> std::string;
 
 /// @returns the string representation of the given QDMI_Operation_Property.
-auto toString(QDMI_Operation_Property prop) -> std::string;
+auto toString(const QDMI_Operation_Property prop) -> std::string;
 
 /// @returns the string representation of the given QDMI_Device_Property.
-auto toString(QDMI_Device_Property prop) -> std::string;
+auto toString(const QDMI_Device_Property prop) -> std::string;
 
 /// @returns the string representation of the given QDMI_Session_Property.
-constexpr auto toString(QDMI_Session_Property prop) -> std::string {
+constexpr auto toString(const QDMI_Session_Property prop) -> std::string {
   if (prop == QDMI_SESSION_PROPERTY_DEVICES) {
     return "QDMI_SESSION_PROPERTY_DEVICES";
   }
   return "QDMI_SESSION_PROPERTY_UNKNOWN";
 }
 
+/**
+ * @brief Session parameters for authentication and configuration.
+ * @details These parameters must be set before the session is initialized
+ * (i.e., before the first call to getDevices()).
+ * @see QDMI_SESSION_PARAMETER_T
+ */
+enum class SessionParameter {
+  /// Authentication token
+  TOKEN = QDMI_SESSION_PARAMETER_TOKEN,
+  /// Path to authentication file
+  AUTHFILE = QDMI_SESSION_PARAMETER_AUTHFILE,
+  /// URL to authentication server
+  AUTHURL = QDMI_SESSION_PARAMETER_AUTHURL,
+  /// Username for authentication
+  USERNAME = QDMI_SESSION_PARAMETER_USERNAME,
+  /// Password for authentication
+  PASSWORD = QDMI_SESSION_PARAMETER_PASSWORD,
+  /// Project ID for session
+  PROJECTID = QDMI_SESSION_PARAMETER_PROJECTID,
+  /// Custom parameter 1 (driver-defined)
+  CUSTOM1 = QDMI_SESSION_PARAMETER_CUSTOM1,
+  /// Custom parameter 2 (driver-defined)
+  CUSTOM2 = QDMI_SESSION_PARAMETER_CUSTOM2,
+  /// Custom parameter 3 (driver-defined)
+  CUSTOM3 = QDMI_SESSION_PARAMETER_CUSTOM3,
+  /// Custom parameter 4 (driver-defined)
+  CUSTOM4 = QDMI_SESSION_PARAMETER_CUSTOM4,
+  /// Custom parameter 5 (driver-defined)
+  CUSTOM5 = QDMI_SESSION_PARAMETER_CUSTOM5
+};
+
+/// @returns the string representation of the given SessionParameter.
+auto toString(const SessionParameter param) -> std::string;
+
 /// Throws an exception corresponding to the given QDMI_STATUS code.
-[[noreturn]] auto throwError(int result, const std::string& msg) -> void;
+[[noreturn]] auto throwError(const int result, const std::string& msg) -> void;
 
 /// Throws an exception if the result indicates an error.
-inline auto throwIfError(int result, const std::string& msg) -> void {
+inline auto throwIfError(const int result, const std::string& msg) -> void {
   switch (result) {
   case QDMI_SUCCESS:
     break;
@@ -180,7 +216,6 @@ inline auto throwIfError(int result, const std::string& msg) -> void {
  * @brief Class representing the FoMaC library.
  * @details This class provides methods to query available devices and
  * manage the QDMI session.
- * @note This class is a singleton.
  * @see QDMI_Session
  */
 class FoMaC {
@@ -674,12 +709,13 @@ class FoMaC {
 
 private:
   QDMI_Session session_ = nullptr;
+  mutable std::mutex mutex_;
+  bool initialized_ = false;
+  std::unordered_map<SessionParameter, std::string> pendingParameters_;
+
+  /// @brief Ensures the session is initialized, applying pending parameters
+  auto ensureInitialized() -> void;
 
-  FoMaC();
-  static auto get() -> FoMaC& {
-    static FoMaC instance;
-    return instance;
-  }
   template <size_constructible_contiguous_range T>
   [[nodiscard]] auto queryProperty(const QDMI_Session_Property prop) const
       -> T {
@@ -696,14 +732,65 @@ class FoMaC {
   }
 
 public:
+  /**
+   * @brief Constructs a new FoMaC session.
+   * @details Creates and allocates a new QDMI session. The session is not
+   * initialized until the first call to getDevices() or after setting
+   * authentication parameters.
+   */
+  FoMaC();
+
+  /**
+   * @brief Destructor that releases the QDMI session.
+   */
   virtual ~FoMaC();
-  // Delete copy constructors and assignment operators to prevent copying the
-  // singleton instance.
+
+  // Delete copy constructors and assignment operators
   FoMaC(const FoMaC&) = delete;
   FoMaC& operator=(const FoMaC&) = delete;
-  FoMaC(FoMaC&&) = default;
-  FoMaC& operator=(FoMaC&&) = default;
+
+  // Allow move semantics
+  FoMaC(FoMaC&&) noexcept;
+  FoMaC& operator=(FoMaC&&) noexcept;
+
+  /**
+   * @brief Set a session parameter for authentication.
+   * @details This method must be called before the first call to getDevices().
+   * Once the session is initialized, parameters cannot be changed.
+   * For AUTHFILE parameter, the file path is validated for existence.
+   * For AUTHURL parameter, basic URL format validation is performed.
+   * @param param The parameter to set
+   * @param value The value to set
+   * @throws std::runtime_error if the session is already initialized
+   * @throws std::runtime_error if validation fails (file not found, invalid
+   * URL)
+   * @see QDMI_session_set_parameter
+   */
+  auto setSessionParameter(const SessionParameter param,
+                           const std::string& value) -> void;
+
   /// @see QDMI_SESSION_PROPERTY_DEVICES
-  [[nodiscard]] static auto getDevices() -> std::vector<Device>;
+  [[nodiscard]] auto getDevices() -> std::vector<Device>;
 };
+
+/**
+ * @brief Get devices from a default FoMaC session.
+ * @details This is a convenience function that uses a static default FoMaC
+ * instance. For custom authentication or multiple sessions, create FoMaC
+ * instances directly.
+ * @return Vector of available devices
+ */
+[[nodiscard]] auto getDevices() -> std::vector<FoMaC::Device>;
+
+/**
+ * @brief Set a session parameter on the default FoMaC session.
+ * @details This is a convenience function for the default session.
+ * For multiple sessions, create FoMaC instances directly.
+ * @param param The parameter to set
+ * @param value The value to set
+ * @see FoMaC::setSessionParameter
+ */
+auto setSessionParameter(SessionParameter param, const std::string& value)
+    -> void;
+
 } // namespace fomac

python/mqt/core/fomac.pyi

@@ -13,7 +13,10 @@ __all__ = [
     "Device",
     "Job",
     "ProgramFormat",
+    "Session",
+    "SessionParameter",
     "devices",
+    "set_session_parameter",
 ]
 
 class ProgramFormat(Enum):
@@ -34,6 +37,73 @@ class ProgramFormat(Enum):
     CUSTOM4 = ...
     CUSTOM5 = ...
 
+class SessionParameter(Enum):
+    """Session parameters for authentication and configuration.
+
+    These parameters must be set before the first call to devices().
+    """
+
+    TOKEN = ...
+    """Authentication token"""
+    AUTHFILE = ...
+    """Path to authentication file"""
+    AUTHURL = ...
+    """URL to authentication server"""
+    USERNAME = ...
+    """Username for authentication"""
+    PASSWORD = ...
+    """Password for authentication"""
+    PROJECTID = ...
+    """Project ID for session"""
+    CUSTOM1 = ...
+    """Custom parameter 1 (driver-defined)"""
+    CUSTOM2 = ...
+    """Custom parameter 2 (driver-defined)"""
+    CUSTOM3 = ...
+    """Custom parameter 3 (driver-defined)"""
+    CUSTOM4 = ...
+    """Custom parameter 4 (driver-defined)"""
+    CUSTOM5 = ...
+    """Custom parameter 5 (driver-defined)"""
+
+class Session:
+    """A FoMaC session for managing QDMI devices.
+
+    Allows creating isolated sessions with independent authentication settings.
+    """
+
+    def __init__(self) -> None:
+        """Create a new FoMaC session."""
+
+    def set_session_parameter(self, param: SessionParameter, value: str) -> None:
+        """Set a session parameter for authentication.
+
+        This method must be called before the first call to get_devices().
+        Once the session is initialized, parameters cannot be changed.
+
+        Args:
+            param: The session parameter to set
+            value: The parameter value as a string
+
+        Raises:
+            RuntimeError: If session is already initialized
+            RuntimeError: If AUTHFILE does not exist
+            RuntimeError: If AUTHURL has invalid format
+
+        Example:
+            >>> from mqt.core.fomac import Session, SessionParameter
+            >>> session = Session()
+            >>> session.set_session_parameter(SessionParameter.TOKEN, "my_token")
+            >>> devices = session.get_devices()
+        """
+
+    def get_devices(self) -> list[Device]:
+        """Get available devices from this session.
+
+        Returns:
+            List of available devices
+        """
+
 class Job:
     """A job represents a submitted quantum program execution."""
 
@@ -205,5 +275,39 @@ class Device:
     def __ne__(self, other: object) -> bool:
         """Checks if two devices are not equal."""
 
+def set_session_parameter(param: SessionParameter, value: str) -> None:
+    """Set a session parameter for authentication on the default session.
+
+    This function must be called before the first call to devices().
+    Once the session is initialized, parameters cannot be changed.
+
+    For custom sessions or multiple sessions, use the Session class directly.
+
+    Args:
+        param: The session parameter to set
+        value: The parameter value as a string
+
+    Raises:
+        RuntimeError: If session is already initialized
+        RuntimeError: If AUTHFILE does not exist
+        RuntimeError: If AUTHURL has invalid format
+
+    Example:
+        >>> import mqt.core.fomac as fomac
+        >>> fomac.set_session_parameter(fomac.SessionParameter.TOKEN, "my_token")
+        >>> devices = fomac.devices()
+
+        # Or use Session class for isolated sessions:
+        >>> session = fomac.Session()
+        >>> session.set_session_parameter(fomac.SessionParameter.TOKEN, "token")
+        >>> session_devices = session.get_devices()
+    """
+
 def devices() -> list[Device]:
-    """Returns a list of available devices."""
+    """Returns a list of available devices from the default session.
+
+    For custom sessions, create a Session instance and use its get_devices() method.
+
+    Returns:
+        List of available devices
+    """