✨ New QDMI Device to represent SC Devices (#1328)

## Description

This PR adds a—for the moment—minimalistic SC QDMI device that only
features a coupling map. The changes extend the QDMI device framework by
relocating the Device class to the qdmi::na namespace, adding a new
superconducting (SC) device backend with session and job management
APIs, introducing JSON-based device configuration and code generation
utilities, and providing a CLI tool and comprehensive test coverage for
the SC device.

## Checklist:

<!---
This checklist serves as a reminder of a couple of things that ensure
your pull request will be merged swiftly.
-->

- [x] The pull request only contains commits that are focused and
relevant to this change.
- [x] I have added appropriate tests that cover the new/changed
functionality.
- [x] I have updated the documentation to reflect these changes.
- [x] I have added entries to the changelog for any noteworthy
additions, changes, fixes, or removals.
- [x] I have added migration instructions to the upgrade guide (if
needed).
- [x] The changes follow the project's style guidelines and introduce no
new warnings.
- [x] The changes are fully tested and pass the CI checks.
- [x] I have reviewed my own code changes.

---------

Signed-off-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Signed-off-by: burgholzer <burgholzer@me.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Lukas Burgholzer <burgholzer@me.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Daniel Haag <121057143+denialhaag@users.noreply.github.com>
Co-authored-by: matthias <matthias.reumann@tum.de>

Author: 6 people

CHANGELOG.md

@@ -11,6 +11,7 @@ This project adheres to [Semantic Versioning], with the exception that minor rel
 
 ### Added
 
+- ✨ 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**])
 - ✨ Expose the QDMI job interface through FoMaC ([#1243]) ([**@marcelwa**], [**@burgholzer**])
@@ -265,6 +266,7 @@ _📚 Refer to the [GitHub Release Notes](https://github.com/munich-quantum-tool
 <!-- PR links -->
 
 [#1336]: https://github.com/munich-quantum-toolkit/core/pull/1336
+[#1328]: https://github.com/munich-quantum-toolkit/core/pull/1328
 [#1327]: https://github.com/munich-quantum-toolkit/core/pull/1327
 [#1310]: https://github.com/munich-quantum-toolkit/core/pull/1310
 [#1301]: https://github.com/munich-quantum-toolkit/core/pull/1301

include/mqt-core/na/device/Device.hpp

@@ -27,7 +27,7 @@
 #include <variant>
 #include <vector>
 
-namespace qdmi {
+namespace qdmi::na {
 class Device final {
   /// @brief Provides access to the device name.
   std::string name_;
@@ -118,7 +118,7 @@ class Device final {
   auto queryProperty(QDMI_Device_Property prop, size_t size, void* value,
                      size_t* sizeRet) -> int;
 };
-} // namespace qdmi
+} // namespace qdmi::na
 
 /**
  * @brief Implementation of the MQT_NA_QDMI_Device_Session structure.
@@ -216,46 +216,46 @@ struct MQT_NA_QDMI_Device_Job_impl_d {
    * @brief Sets a parameter for the job.
    * @see MQT_NA_QDMI_device_job_set_parameter
    */
-  static auto setParameter(QDMI_Device_Job_Parameter param, size_t size,
-                           const void* value) -> int;
+  auto setParameter(QDMI_Device_Job_Parameter param, size_t size,
+                    const void* value) -> int;
 
   /**
    * @brief Queries a property of the job.
    * @see MQT_NA_QDMI_device_job_query_property
    */
-  static auto queryProperty(QDMI_Device_Job_Property prop, size_t size,
-                            void* value, size_t* sizeRet) -> int;
+  auto queryProperty(QDMI_Device_Job_Property prop, size_t size, void* value,
+                     size_t* sizeRet) -> int;
 
   /**
    * @brief Submits the job to the device.
    * @see MQT_NA_QDMI_device_job_submit
    */
-  static auto submit() -> int;
+  auto submit() -> int;
 
   /**
    * @brief Cancels the job.
    * @see MQT_NA_QDMI_device_job_cancel
    */
-  static auto cancel() -> int;
+  auto cancel() -> int;
 
   /**
    * @brief Checks the status of the job.
    * @see MQT_NA_QDMI_device_job_check
    */
-  static auto check(QDMI_Job_Status* status) -> int;
+  auto check(QDMI_Job_Status* status) -> int;
 
   /**
    * @brief Waits for the job to complete but at most for the specified timeout.
    * @see MQT_NA_QDMI_device_job_wait
    */
-  static auto wait(size_t timeout) -> int;
+  auto wait(size_t timeout) -> int;
 
   /**
    * @brief Gets the results of the job.
    * @see MQT_NA_QDMI_device_job_get_results
    */
-  static auto getResults(QDMI_Job_Result result, size_t size, void* data,
-                         [[maybe_unused]] size_t* sizeRet) -> int;
+  auto getResults(QDMI_Job_Result result, size_t size, void* data,
+                  [[maybe_unused]] size_t* sizeRet) -> int;
 };
 
 /**

include/mqt-core/qdmi/Driver.hpp

@@ -140,6 +140,7 @@ class DynamicDeviceLibrary final : public DeviceLibrary {
 // Call the above macro for all static libraries that we want to support.
 DECLARE_STATIC_LIBRARY(MQT_NA)
 DECLARE_STATIC_LIBRARY(MQT_DDSIM)
+DECLARE_STATIC_LIBRARY(MQT_SC)
 
 /**
  * @brief The status of a session.
@@ -407,11 +408,22 @@ class Driver final {
 #ifndef _WIN32
   /**
    * @brief Adds a dynamic device library to the driver.
-   * @param libName is the path to the dynamic library to load.
-   * @param prefix is the prefix used for the device interface functions.
-   * @returns `true` if the library was successfully loaded, `false`
-   * if it was already loaded.
+   * @details This function attempts to load a dynamic library containing
+   * QDMI device interface functions. If the library is already loaded, the
+   * function returns `false`. Otherwise, it loads the library, initializes
+   * the device, and adds it to the list of devices.
+   *
+   * @param libName The path to the dynamic library to load.
+   * @param prefix The prefix used for the device interface functions in the
+   * library.
+   * @returns `true` if the library was successfully loaded, `false` if it was
+   * already loaded.
+   *
    * @note This function is only available on non-Windows platforms.
+   *
+   * @throws std::runtime_error If the library fails to load or the device
+   * cannot be initialized.
+   * @throws std::bad_alloc If memory allocation fails during the process.
    */
   auto addDynamicDeviceLibrary(const std::string& libName,
                                const std::string& prefix) -> bool;