✨ QDMI authentication via FoMaC

CHANGELOG.md

@@ -11,6 +11,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Added
 
+- ✨ Add authentication support for QDMI sessions with token, username/password, auth file, auth URL, and project ID parameters ([#1355]) ([**@marcelwa**])
 - ✨ Add a new QDMI device that represents a superconducting architecture featuring a coupling map ([#1328]) ([**@ystade**])
 - ✨ Add bi-directional iterator that traverses the def-use chain of a qubit value ([#1310]) ([**@MatthiasReumann**])
 - ✨ Add `OptionalDependencyTester` to lazily handle optional Python dependencies like Qiskit ([#1243]) ([**@marcelwa**], [**@burgholzer**])
@@ -21,6 +22,10 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Changed
 
+- 🚚 Move `NA` QDMI device in its right place next to other QDMI devices ([#1355]) ([**@burgholzer**])
+- ♻️ Allow repeated loading of QDMI device library with potentially different session configurations ([#1355]) ([**@burgholzer**])
+- ♻️ Enable thread-safe reference counting for QDMI devices singletons ([#1355]) ([**@burgholzer**])
+- ♻️ Refactor `FoMaC` singleton to instantiable `Session` class with configurable authentication parameters ([#1355]) ([**@marcelwa**])
 - 👷 Stop testing on `ubuntu-22.04` and `ubuntu-22.04-arm` runners ([#1359]) ([**@denialhaag**], [**@burgholzer**])
 - 👷 Stop testing with `clang-19` and start testing with `clang-21` ([#1359]) ([**@denialhaag**], [**@burgholzer**])
 - 👷 Fix macOS tests with Homebrew Clang via new `munich-quantum-toolkit/workflows` version ([#1359]) ([**@denialhaag**], [**@burgholzer**])
@@ -33,6 +38,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Fixed
 
+- 🐛 Fix custom QDMI property and parameter handling in SC and NA devices ([#1355]) ([**@burgholzer**])
 - 🚨 Fix argument naming of `QuantumComputation` and `CompoundOperation` dunder methods for properly implementing the `MutableSequence` protocol ([#1338]) ([**@burgholzer**])
 - 🐛 Fix memory management in dynamic QDMI device by making it explicit ([#1336]) ([**@ystade**])
 
@@ -273,6 +279,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 
 [#1371]: https://github.com/munich-quantum-toolkit/core/pull/1371
 [#1359]: https://github.com/munich-quantum-toolkit/core/pull/1359
+[#1355]: https://github.com/munich-quantum-toolkit/core/pull/1355
 [#1338]: https://github.com/munich-quantum-toolkit/core/pull/1338
 [#1336]: https://github.com/munich-quantum-toolkit/core/pull/1336
 [#1328]: https://github.com/munich-quantum-toolkit/core/pull/1328

bindings/na/fomac/fomac.cpp

@@ -12,7 +12,7 @@
 // clang-format off
 #include "fomac/FoMaC.hpp"
 #include "na/fomac/Device.hpp"
-#include "na/device/Generator.hpp"
+#include "qdmi/na/Generator.hpp"
 
 #include <pybind11/cast.h>
 #include <pybind11/operators.h>
@@ -42,7 +42,7 @@ PYBIND11_MODULE(MQT_CORE_MODULE_NAME, m, py::mod_gil_not_used()) {
   pybind11::module_::import("mqt.core.fomac");
 
   auto device =
-      py::class_<na::FoMaC::Device, fomac::FoMaC::Device>(m, "Device");
+      py::class_<na::Session::Device, fomac::Session::Device>(m, "Device");
 
   auto lattice = py::class_<na::Device::Lattice>(device, "Lattice");
 
@@ -91,22 +91,22 @@ PYBIND11_MODULE(MQT_CORE_MODULE_NAME, m, py::mod_gil_not_used()) {
   lattice.def(py::self == py::self);
   lattice.def(py::self != py::self);
 
-  device.def_property_readonly("traps", &na::FoMaC::Device::getTraps);
-  device.def_property_readonly("t1", [](const na::FoMaC::Device& dev) {
+  device.def_property_readonly("traps", &na::Session::Device::getTraps);
+  device.def_property_readonly("t1", [](const na::Session::Device& dev) {
     return dev.getDecoherenceTimes().t1;
   });
-  device.def_property_readonly("t2", [](const na::FoMaC::Device& dev) {
+  device.def_property_readonly("t2", [](const na::Session::Device& dev) {
     return dev.getDecoherenceTimes().t2;
   });
-  device.def("__repr__", [](const fomac::FoMaC::Device& dev) {
+  device.def("__repr__", [](const fomac::Session::Device& dev) {
     return "<Device name=\"" + dev.getName() + "\">";
   });
   device.def(py::self == py::self);
   device.def(py::self != py::self);
 
-  m.def("devices", &na::FoMaC::getDevices);
+  m.def("devices", &na::Session::getDevices);
   device.def_static("try_create_from_device",
-                    &na::FoMaC::Device::tryCreateFromDevice, "device"_a);
+                    &na::Session::Device::tryCreateFromDevice, "device"_a);
 }
 // NOLINTEND(misc-redundant-expression)
 } // namespace mqt

docs/qdmi/driver.md

@@ -19,20 +19,23 @@ Other devices can be loaded dynamically at runtime via {cpp:func}`qdmi::Driver::
 
 The QDMI Driver is implemented in C++ and exposed to Python via [pybind11](https://pybind11.readthedocs.io).
 Direct binding of the QDMI Client interface functions is not feasible due to technical limitations.
-Instead, a FoMaC (Figure of Merits and Constraints) library defines wrapper classes ({cpp:class}`~fomac::FoMaC::Device`, {cpp:class}`~fomac::FoMaC::Device::Site`, {cpp:class}`~fomac::FoMaC::Device::Operation`) for the QDMI entities.
-These classes together with their methods are then exposed to Python, see {py:class}`~mqt.core.fomac.Device`, {py:class}`~mqt.core.fomac.Device.Site`, {py:class}`~mqt.core.fomac.Device.Operation`.
+Instead, a FoMaC (Figure of Merits and Constraints) library defines wrapper classes ({cpp:class}`~fomac::Session`, {cpp:class}`~fomac::Session::Device`, {cpp:class}`~fomac::Session::Device::Site`, {cpp:class}`~fomac::Session::Device::Operation`, {cpp:class}`~fomac::Session::Job`) for the QDMI entities.
+These classes together with their methods are then exposed to Python, see {py:class}`~mqt.core.fomac.Session`, {py:class}`~mqt.core.fomac.Device`, {py:class}`~mqt.core.fomac.Device.Site`, {py:class}`~mqt.core.fomac.Device.Operation`, {py:class}`~mqt.core.fomac.Job`.
 
 ## Usage
 
-The following example shows how to get a device from the QDMI driver and access its name.
+The following example shows how to create a session and get devices from the QDMI driver.
 
 ```{code-cell} ipython3
-from mqt.core.fomac import devices
+from mqt.core.fomac import Session
 
-# get a list of all available devices
-available_devices = devices()
+# Create a session to interact with QDMI devices
+session = Session()
 
-# print the name of every device (by default there is only the NA device)
+# Get a list of all available devices
+available_devices = session.get_devices()
+
+# Print the name of every device
 for device in available_devices:
     print(device.name())
 ```

docs/qdmi/qdmi_backend.md

@@ -102,6 +102,112 @@ filtered_ddsim = provider.backends(name="DDSIM")  # Matches "MQT Core DDSIM QDMI
 exact = provider.backends(name="MQT Core DDSIM QDMI Device")
 ```
 
+## Authentication
+
+The {py:class}`~mqt.core.plugins.qiskit.QDMIProvider` supports authentication for accessing QDMI devices that require credentials.
+Authentication parameters are passed to the provider constructor and forwarded to the underlying session.
+
+:::{note}
+The default local devices (MQT Core DDSIM QDMI Device, MQT NA Default QDMI Device) do not require authentication.
+Authentication is primarily used when connecting to remote quantum hardware.
+:::
+
+### Supported Authentication Methods
+
+The provider supports multiple authentication methods:
+
+- **Token-based authentication**: Using an API token or access token
+- **Username/password authentication**: Traditional credential-based authentication
+- **File-based authentication**: Reading credentials from a file
+- **URL-based authentication**: Connecting to an authentication server
+- **Project-based authentication**: Associating sessions with specific projects, e.g., for accounting or quota management
+
+### Using Authentication Tokens
+
+The most common authentication method is using an API token:
+
+```python
+from mqt.core.plugins.qiskit import QDMIProvider
+
+# Authenticate with a token
+provider = QDMIProvider(token="your_api_token_here")
+
+# Get backends
+backends = provider.backends()
+for backend in backends:
+    print(f"{backend.name}: {backend.target.num_qubits} qubits")
+```
+
+### Username and Password Authentication
+
+For services that use traditional username/password authentication:
+
+```python
+# Authenticate with username and password
+provider = QDMIProvider(username="your_username", password="your_password")
+
+# Access backend
+backend = provider.get_backend("RemoteQuantumDevice")
+```
+
+### File-Based Authentication
+
+Store credentials in a secure file for better security:
+
+```python
+# Authenticate using a credentials file
+# The file should contain authentication information in the format expected by the service
+provider = QDMIProvider(auth_file="/path/to/credentials.txt")
+```
+
+### Authentication Server URL
+
+Connect to a custom authentication server:
+
+```python
+# Use a custom authentication URL
+provider = QDMIProvider(auth_url="https://auth.quantum-service.com/api/v1/auth")
+```
+
+### Project-Based Authentication
+
+Associate your session with a specific project or organization:
+
+```python
+# Specify a project ID
+provider = QDMIProvider(
+    token="your_api_token", project_id="quantum-research-project-2024"
+)
+```
+
+### Combining Authentication Parameters
+
+Multiple authentication parameters can be combined for services that require multiple credentials:
+
+```python
+# Use multiple authentication parameters
+provider = QDMIProvider(
+    token="your_api_token",
+    username="your_username",
+    password="your_password",
+    project_id="your_project_id",
+    auth_url="https://custom-auth.example.com",
+)
+```
+
+### Authentication Error Handling
+
+When authentication fails, the provider raises a `RuntimeError`:
+
+```python
+try:
+    provider = QDMIProvider(token="invalid_token")
+    backends = provider.backends()
+except RuntimeError as e:
+    print(f"Authentication failed: {e}")
+    # Handle authentication error (e.g., prompt for valid credentials)
+```
+
 ## Device Capabilities and Target
 
 The backend automatically introspects the FoMaC (QDMI) device and constructs a Qiskit {py:class}`~qiskit.transpiler.Target`

include/mqt-core/fomac/FoMaC.hpp

@@ -18,6 +18,7 @@
 #include <iostream>
 #include <iterator>
 #include <map>
+#include <mutex>
 #include <optional>
 #include <qdmi/client.h>
 #include <ranges>
@@ -160,33 +161,56 @@ constexpr auto toString(QDMI_Session_Property prop) -> std::string {
   return "QDMI_SESSION_PROPERTY_UNKNOWN";
 }
 
+/// @returns the string representation of the given QDMI_SESSION_PARAMETER_T.
+auto toString(QDMI_SESSION_PARAMETER_T param) -> std::string;
+
 /// Throws an exception corresponding to the given QDMI_STATUS code.
 [[noreturn]] auto throwError(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 {
-  switch (result) {
-  case QDMI_SUCCESS:
-    break;
-  case QDMI_WARN_GENERAL:
-    std::cerr << "Warning: " << msg << "\n";
-    break;
-  default:
-    throwError(result, msg);
-  }
-}
+auto throwIfError(int result, const std::string& msg) -> void;
+
+/**
+ * @brief Configuration structure for session authentication parameters.
+ * @details All parameters are optional. Only set the parameters needed for
+ * your authentication method. Parameters are validated when the session is
+ * constructed.
+ */
+struct SessionConfig {
+  /// Authentication token
+  std::optional<std::string> token;
+  /// Path to file containing authentication information
+  std::optional<std::string> authFile;
+  /// URL to authentication server
+  std::optional<std::string> authUrl;
+  /// Username for authentication
+  std::optional<std::string> username;
+  /// Password for authentication
+  std::optional<std::string> password;
+  /// Project ID for session
+  std::optional<std::string> projectId;
+  /// Custom configuration parameter 1
+  std::optional<std::string> custom1;
+  /// Custom configuration parameter 2
+  std::optional<std::string> custom2;
+  /// Custom configuration parameter 3
+  std::optional<std::string> custom3;
+  /// Custom configuration parameter 4
+  std::optional<std::string> custom4;
+  /// Custom configuration parameter 5
+  std::optional<std::string> custom5;
+};
 
 /**
- * @brief Class representing the FoMaC library.
+ * @brief Class representing the Session 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 {
+class Session {
   /**
    * @brief Private token class.
-   * @details Only the FoMaC class can create instances of this class.
+   * @details Only the Session class can create instances of this class.
    */
   class Token {
   public:
@@ -608,7 +632,7 @@ class FoMaC {
      * @brief Constructs a Device object from a QDMI_Device handle.
      * @param device The QDMI_Device handle to wrap.
      */
-    Device(FoMaC::Token /* unused */, QDMI_Device device) : device_(device) {}
+    Device(Session::Token /* unused */, QDMI_Device device) : device_(device) {}
     /// @returns the underlying QDMI_Device object.
     [[nodiscard]] auto getQDMIDevice() const -> QDMI_Device { return device_; }
     // NOLINTNEXTLINE(google-explicit-constructor)
@@ -675,11 +699,6 @@ class FoMaC {
 private:
   QDMI_Session session_ = nullptr;
 
-  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 +715,28 @@ class FoMaC {
   }
 
 public:
-  virtual ~FoMaC();
-  // Delete copy constructors and assignment operators to prevent copying the
-  // singleton instance.
-  FoMaC(const FoMaC&) = delete;
-  FoMaC& operator=(const FoMaC&) = delete;
-  FoMaC(FoMaC&&) = default;
-  FoMaC& operator=(FoMaC&&) = default;
+  /**
+   * @brief Constructs a new QDMI Session with optional authentication.
+   * @param config Optional session configuration containing authentication
+   * parameters. If not provided, uses default (no authentication).
+   * @details Creates, allocates, and initializes a new QDMI session.
+   */
+  explicit Session(const SessionConfig& config = {});
+
+  /**
+   * @brief Destructor that releases the QDMI session.
+   */
+  ~Session();
+
+  // Delete copy constructors and assignment operators
+  Session(const Session&) = delete;
+  Session& operator=(const Session&) = delete;
+
+  // Allow move semantics
+  Session(Session&&) noexcept;
+  Session& operator=(Session&&) noexcept;
+
   /// @see QDMI_SESSION_PROPERTY_DEVICES
-  [[nodiscard]] static auto getDevices() -> std::vector<Device>;
+  [[nodiscard]] auto getDevices() -> std::vector<Device>;
 };
 } // namespace fomac