✨ Add typed custom property and result queries to the C++ and Python FoMaC libraries (backport #1895) (#1896)

## Description

This PR allows querying custom QDMI properties through MQT Core's C++
and Python FoMaC implementations.
This allows to read any custom information exported by a device from C++
and Python via typed accessors.

Assisted-by gpt-5.6-sol via Codex CLI

## Checklist



- [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.

**If PR contains AI-assisted content:**

- [x] I have disclosed the use of AI tools in the PR description as per
our [AI Usage
Guidelines](https://github.com/munich-quantum-toolkit/core/blob/main/docs/ai_usage.md).
- [x] AI-assisted commits include an `Assisted-by: [Model Name] via
[Tool Name]` footer.
- [x] I confirm that I have personally reviewed and understood all
AI-generated content, and accept full responsibility for it.



(cherry picked from commit 2c9971e)

Co-authored-by: Lukas Burgholzer <burgholzer@me.com>

Author: mergify[bot]

.license-tools-config.json

@@ -35,6 +35,7 @@
     "uv\\.lock",
     "py\\.typed",
     ".*build.*",
-    "(^|/)LICENSE$"
+    "(^|/)LICENSE$",
+    "patterns.txt"
   ]
 }

CHANGELOG.md

@@ -12,6 +12,8 @@ releases may include breaking changes.
 
 ### Added
 
+- ✨ Add typed custom property and result queries to the C++ and Python FoMaC
+  libraries ([#1895]) ([**@burgholzer**])
 - ✨ Add support for custom job parameters to C++ and Python FoMaC library
   ([#1887]) ([**@flowerthrower**], [**@burgholzer**])
 
@@ -570,6 +572,7 @@ changelogs._
 
 <!-- PR links -->
 
+[#1895]: https://github.com/munich-quantum-toolkit/core/pull/1895
 [#1887]: https://github.com/munich-quantum-toolkit/core/pull/1887
 [#1873]: https://github.com/munich-quantum-toolkit/core/pull/1873
 [#1849]: https://github.com/munich-quantum-toolkit/core/pull/1849

bindings/fomac/fomac.cpp

@@ -23,6 +23,7 @@
 #include <nanobind/stl/vector.h>   // NOLINT(misc-include-cleaner)
 #include <qdmi/client.h>
 
+#include <cstddef>
 #include <optional>
 #include <string>
 #include <utility>
@@ -33,6 +34,44 @@ namespace mqt {
 namespace nb = nanobind;
 using namespace nb::literals;
 
+namespace {
+template <typename Query>
+[[nodiscard]] nb::object queryCustomValue(Query query,
+                                          const nb::handle valueType) {
+  const auto returnValue =
+      []<typename T>(std::optional<T> value) -> nb::object {
+    if (!value.has_value()) {
+      return nb::none();
+    }
+    return nb::cast(std::move(*value));
+  };
+
+  const auto builtins = nb::builtins();
+  if (valueType.is(builtins["str"])) {
+    return returnValue(query.template operator()<std::string>());
+  }
+  if (valueType.is(builtins["bool"])) {
+    return returnValue(query.template operator()<bool>());
+  }
+  if (valueType.is(builtins["int"])) {
+    return returnValue(query.template operator()<int>());
+  }
+  if (valueType.is(builtins["float"])) {
+    return returnValue(query.template operator()<double>());
+  }
+  if (valueType.is(builtins["bytes"])) {
+    const auto value = query.template operator()<std::vector<std::byte>>();
+    if (!value.has_value()) {
+      return nb::none();
+    }
+    return nb::bytes(reinterpret_cast<const char*>(value->data()),
+                     value->size());
+  }
+  throw nb::type_error(
+      "value_type must be exactly str, bool, int, float, or bytes");
+}
+} // namespace
+
 NB_MODULE(MQT_CORE_MODULE_NAME, m) {
   // Session class
   auto session = nb::class_<fomac::Session>(
@@ -157,6 +196,47 @@ All authentication parameters are optional and can be provided as keyword argume
           "Returns the sparse probabilities from the job (typically only "
           "available from simulator devices).");
 
+  job.def(
+      "query_custom_property",
+      [](const fomac::Job& self, const fomac::CustomProperty customProperty,
+         const nb::handle valueType) {
+        return queryCustomValue(
+            [&self, customProperty]<fomac::custom_property_value T>() {
+              return self.queryCustomProperty<T>(customProperty);
+            },
+            valueType);
+      },
+      "custom_property"_a, "value_type"_a,
+      nb::sig("def query_custom_property(self, custom_property: "
+              "CustomProperty, "
+              "value_type: type[str] | type[bool] | type[int] | type[float] | "
+              "type[bytes]) -> str | bool | int | float | bytes | None"),
+      R"pb(Query an implementation-defined custom job property.
+
+The caller must provide the type documented by the device implementation.
+Use ``bytes`` to retrieve the value without interpretation. Returns ``None``
+when the custom slot is unsupported.)pb");
+
+  job.def(
+      "get_custom_result",
+      [](const fomac::Job& self, const fomac::CustomProperty customProperty,
+         const nb::handle valueType) {
+        return queryCustomValue(
+            [&self, customProperty]<fomac::custom_property_value T>() {
+              return self.getCustomResult<T>(customProperty);
+            },
+            valueType);
+      },
+      "custom_property"_a, "value_type"_a,
+      nb::sig("def get_custom_result(self, custom_property: CustomProperty, "
+              "value_type: type[str] | type[bool] | type[int] | type[float] | "
+              "type[bytes]) -> str | bool | int | float | bytes | None"),
+      R"pb(Return an implementation-defined custom job result.
+
+The caller must provide the type documented by the device implementation.
+Use ``bytes`` to retrieve the value without interpretation. Returns ``None``
+when the custom slot is unsupported.)pb");
+
   job.def_prop_ro("id", &fomac::Job::getId, "The job ID.");
 
   job.def_prop_ro("program_format", &fomac::Job::getProgramFormat,
@@ -200,6 +280,15 @@ All authentication parameters are optional and can be provided as keyword argume
       .value("CUSTOM4", QDMI_PROGRAM_FORMAT_CUSTOM4)
       .value("CUSTOM5", QDMI_PROGRAM_FORMAT_CUSTOM5);
 
+  nb::enum_<fomac::CustomProperty>(
+      m, "CustomProperty",
+      "An implementation-defined custom property or result slot.")
+      .value("CUSTOM1", fomac::CustomProperty::Custom1)
+      .value("CUSTOM2", fomac::CustomProperty::Custom2)
+      .value("CUSTOM3", fomac::CustomProperty::Custom3)
+      .value("CUSTOM4", fomac::CustomProperty::Custom4)
+      .value("CUSTOM5", fomac::CustomProperty::Custom5);
+
   // Device class
   auto device = nb::class_<fomac::Device>(
       m, "Device",
@@ -270,6 +359,27 @@ All authentication parameters are optional and can be provided as keyword argume
              &fomac::Device::getSupportedProgramFormats,
              "Returns the list of program formats supported by the device.");
 
+  device.def(
+      "query_custom_property",
+      [](const fomac::Device& self, const fomac::CustomProperty customProperty,
+         const nb::handle valueType) {
+        return queryCustomValue(
+            [&self, customProperty]<fomac::custom_property_value T>() {
+              return self.queryCustomProperty<T>(customProperty);
+            },
+            valueType);
+      },
+      "custom_property"_a, "value_type"_a,
+      nb::sig("def query_custom_property(self, custom_property: "
+              "CustomProperty, "
+              "value_type: type[str] | type[bool] | type[int] | type[float] | "
+              "type[bytes]) -> str | bool | int | float | bytes | None"),
+      R"pb(Query an implementation-defined custom device property.
+
+The caller must provide the type documented by the device implementation.
+Use ``bytes`` to retrieve the value without interpretation. Returns ``None``
+when the custom slot is unsupported.)pb");
+
   device.def("submit_job", &fomac::Device::submitJob, "program"_a,
              "program_format"_a, "num_shots"_a, nb::kw_only(),
              "custom1"_a = nb::none(), "custom2"_a = nb::none(),
@@ -328,6 +438,27 @@ All authentication parameters are optional and can be provided as keyword argume
   site.def("submodule_index", &fomac::Site::getSubmoduleIndex,
            "Returns the index of the submodule the site belongs to.");
 
+  site.def(
+      "query_custom_property",
+      [](const fomac::Site& self, const fomac::CustomProperty customProperty,
+         const nb::handle valueType) {
+        return queryCustomValue(
+            [&self, customProperty]<fomac::custom_property_value T>() {
+              return self.queryCustomProperty<T>(customProperty);
+            },
+            valueType);
+      },
+      "custom_property"_a, "value_type"_a,
+      nb::sig("def query_custom_property(self, custom_property: "
+              "CustomProperty, "
+              "value_type: type[str] | type[bool] | type[int] | type[float] | "
+              "type[bytes]) -> str | bool | int | float | bytes | None"),
+      R"pb(Query an implementation-defined custom site property.
+
+The caller must provide the type documented by the device implementation.
+Use ``bytes`` to retrieve the value without interpretation. Returns ``None``
+when the custom slot is unsupported.)pb");
+
   site.def("__repr__", [](const fomac::Site& s) {
     return "<Site index=" + std::to_string(s.getIndex()) + ">";
   });
@@ -399,6 +530,34 @@ All authentication parameters are optional and can be provided as keyword argume
                 "params"_a.sig("...") = std::vector<double>{},
                 "Returns the mean shuttling speed of the operation.");
 
+  operation.def(
+      "query_custom_property",
+      [](const fomac::Operation& self,
+         const fomac::CustomProperty customProperty, const nb::handle valueType,
+         const std::vector<fomac::Site>& sites,
+         const std::vector<double>& params) {
+        return queryCustomValue(
+            [&self, customProperty, &sites,
+             &params]<fomac::custom_property_value T>() {
+              return self.queryCustomProperty<T>(customProperty, sites, params);
+            },
+            valueType);
+      },
+      "custom_property"_a, "value_type"_a,
+      "sites"_a.sig("...") = std::vector<fomac::Site>{},
+      "params"_a.sig("...") = std::vector<double>{},
+      nb::sig("def query_custom_property(self, custom_property: "
+              "CustomProperty, "
+              "value_type: type[str] | type[bool] | type[int] | type[float] | "
+              "type[bytes], sites: Sequence[mqt.core.fomac.Device.Site] = "
+              "..., params: Sequence[float] = ...) -> str | bool | int | "
+              "float | bytes | None"),
+      R"pb(Query an implementation-defined custom operation property.
+
+The caller must provide the type documented by the device implementation.
+Use ``bytes`` to retrieve the value without interpretation. Returns ``None``
+when the custom slot is unsupported.)pb");
+
   operation.def("__repr__", [](const fomac::Operation& op) {
     return "<Operation name=\"" + op.getName() + "\">";
   });

bindings/fomac/patterns.txt

@@ -0,0 +1,87 @@
+mqt\.core\.fomac\.(?:Job|Device|Device\.Site)\.query_custom_property$:
+    \from typing import overload
+    @overload
+    def query_custom_property(self, custom_property: CustomProperty, value_type: type[str]) -> str | None: ...
+    @overload
+    def query_custom_property(self, custom_property: CustomProperty, value_type: type[bool]) -> bool | None: ...
+    @overload
+    def query_custom_property(self, custom_property: CustomProperty, value_type: type[int]) -> int | None: ...
+    @overload
+    def query_custom_property(self, custom_property: CustomProperty, value_type: type[float]) -> float | None: ...
+    @overload
+    def query_custom_property(self, custom_property: CustomProperty, value_type: type[bytes]) -> bytes | None: ...
+    @overload
+    def query_custom_property(
+        self, custom_property: CustomProperty, value_type: type[str | bool | int | float | bytes]
+    ) -> str | bool | int | float | bytes | None:
+        \doc
+
+mqt\.core\.fomac\.Job\.get_custom_result$:
+    \from typing import overload
+    @overload
+    def get_custom_result(self, custom_property: CustomProperty, value_type: type[str]) -> str | None: ...
+    @overload
+    def get_custom_result(self, custom_property: CustomProperty, value_type: type[bool]) -> bool | None: ...
+    @overload
+    def get_custom_result(self, custom_property: CustomProperty, value_type: type[int]) -> int | None: ...
+    @overload
+    def get_custom_result(self, custom_property: CustomProperty, value_type: type[float]) -> float | None: ...
+    @overload
+    def get_custom_result(self, custom_property: CustomProperty, value_type: type[bytes]) -> bytes | None: ...
+    @overload
+    def get_custom_result(
+        self, custom_property: CustomProperty, value_type: type[str | bool | int | float | bytes]
+    ) -> str | bool | int | float | bytes | None:
+        \doc
+
+mqt\.core\.fomac\.Device\.Operation\.query_custom_property$:
+    \from typing import overload
+    @overload
+    def query_custom_property(
+        self,
+        custom_property: CustomProperty,
+        value_type: type[str],
+        sites: Sequence[Device.Site] = ...,
+        params: Sequence[float] = ...,
+    ) -> str | None: ...
+    @overload
+    def query_custom_property(
+        self,
+        custom_property: CustomProperty,
+        value_type: type[bool],
+        sites: Sequence[Device.Site] = ...,
+        params: Sequence[float] = ...,
+    ) -> bool | None: ...
+    @overload
+    def query_custom_property(
+        self,
+        custom_property: CustomProperty,
+        value_type: type[int],
+        sites: Sequence[Device.Site] = ...,
+        params: Sequence[float] = ...,
+    ) -> int | None: ...
+    @overload
+    def query_custom_property(
+        self,
+        custom_property: CustomProperty,
+        value_type: type[float],
+        sites: Sequence[Device.Site] = ...,
+        params: Sequence[float] = ...,
+    ) -> float | None: ...
+    @overload
+    def query_custom_property(
+        self,
+        custom_property: CustomProperty,
+        value_type: type[bytes],
+        sites: Sequence[Device.Site] = ...,
+        params: Sequence[float] = ...,
+    ) -> bytes | None: ...
+    @overload
+    def query_custom_property(
+        self,
+        custom_property: CustomProperty,
+        value_type: type[str | bool | int | float | bytes],
+        sites: Sequence[Device.Site] = ...,
+        params: Sequence[float] = ...,
+    ) -> str | bool | int | float | bytes | None:
+        \doc