✨ Add custom job parameters to FoMaC (backport #1887) (#1891)

## Description

This PR adds the custom1-5 job parameters to FoMaC.

During implementing the [CUDAQ QDMI
Integration](NVIDIA/cuda-quantum#4882), I found
that currently FoMaC only exposes custom session parameters but not
custom job parameters (which is, e.g., crucial for using the [Amazon
Braket QDMI
Device](https://github.com/munich-quantum-software/amazon-braket-qdmi-device)).

## Checklist



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

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

- [ ] 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).
- [ ] AI-assisted commits include an `Assisted-by: [Model Name] via
[Tool Name]` footer.
- [ ] I confirm that I have personally reviewed and understood all
AI-generated content, and accept full responsibility for it.



(cherry picked from commit df90a5b)

---------

Co-authored-by: Patrick Hopf <81010725+flowerthrower@users.noreply.github.com>
Co-authored-by: Lukas Burgholzer <burgholzer@me.com>

Author: 3 people

CHANGELOG.md

@@ -10,6 +10,11 @@ releases may include breaking changes.
 
 ## [Unreleased]
 
+### Added
+
+- ✨ Add support for custom job parameters to C++ and Python FoMaC library
+  ([#1887]) ([**@flowerthrower**], [**@burgholzer**])
+
 ## [3.7.0] - 2026-07-09
 
 _If you are upgrading: please see [`UPGRADING.md`](UPGRADING.md#370)._
@@ -565,6 +570,7 @@ changelogs._
 
 <!-- PR links -->
 
+[#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
 [#1848]: https://github.com/munich-quantum-toolkit/core/pull/1848

bindings/fomac/fomac.cpp

@@ -19,6 +19,7 @@
 #include <nanobind/stl/optional.h> // NOLINT(misc-include-cleaner)
 #include <nanobind/stl/pair.h>     // NOLINT(misc-include-cleaner)
 #include <nanobind/stl/string.h>   // NOLINT(misc-include-cleaner)
+#include <nanobind/stl/variant.h>  // NOLINT(misc-include-cleaner)
 #include <nanobind/stl/vector.h>   // NOLINT(misc-include-cleaner)
 #include <qdmi/client.h>
 
@@ -270,8 +271,11 @@ All authentication parameters are optional and can be provided as keyword argume
              "Returns the list of program formats supported by the device.");
 
   device.def("submit_job", &fomac::Device::submitJob, "program"_a,
-             "program_format"_a, "num_shots"_a,
-             nb::rv_policy::reference_internal, "Submits a job to the device.");
+             "program_format"_a, "num_shots"_a, nb::kw_only(),
+             "custom1"_a = nb::none(), "custom2"_a = nb::none(),
+             "custom3"_a = nb::none(), "custom4"_a = nb::none(),
+             "custom5"_a = nb::none(), nb::rv_policy::reference_internal,
+             "Submits a job to the device.");
 
   device.def("__repr__", [](const fomac::Device& dev) {
     return "<Device name=\"" + dev.getName() + "\">";

include/mqt-core/fomac/FoMaC.hpp

@@ -28,9 +28,12 @@
 #include <string>
 #include <type_traits>
 #include <utility>
+#include <variant>
 #include <vector>
 
 namespace fomac {
+using CustomJobParameter = std::variant<std::string, bool, int, double>;
+
 /**
  * @brief Concept for ranges that are contiguous in memory and can be
  * constructed with a size.
@@ -105,8 +108,7 @@ template <typename U> struct remove_optional<std::optional<U>> {
  * with the underlying type of optional without caring about its optionality.
  * @tparam T The type to strip optional from.
  */
-template <typename T>
-using remove_optional_t = typename remove_optional<T>::type;
+template <typename T> using remove_optional_t = remove_optional<T>::type;
 
 /**
  * @brief Concept for types that are either size_constructible_contiguous_range
@@ -211,7 +213,7 @@ class Session {
   /// Query a session property.
   template <size_constructible_contiguous_range T>
   [[nodiscard]] T queryProperty(const QDMI_Session_Property prop) const {
-    using StrippedValueType = typename remove_optional_t<T>::value_type;
+    using StrippedValueType = remove_optional_t<T>::value_type;
 
     size_t size = 0;
     qdmi::throwIfError(QDMI_session_query_session_property(session_.get(), prop,
@@ -318,9 +320,13 @@ class Device {
   getSupportedProgramFormats() const;
 
   /// @see QDMI_job_submit
-  [[nodiscard]] Job submitJob(const std::string& program,
-                              QDMI_Program_Format format,
-                              size_t numShots) const;
+  [[nodiscard]] Job submitJob(
+      const std::string& program, QDMI_Program_Format format, size_t numShots,
+      const std::optional<CustomJobParameter>& custom1 = std::nullopt,
+      const std::optional<CustomJobParameter>& custom2 = std::nullopt,
+      const std::optional<CustomJobParameter>& custom3 = std::nullopt,
+      const std::optional<CustomJobParameter>& custom4 = std::nullopt,
+      const std::optional<CustomJobParameter>& custom5 = std::nullopt) const;
 
   auto operator<=>(const Device&) const noexcept = default;
 
@@ -389,6 +395,9 @@ class Device {
     }
   }
 
+  static void setCustomJobParam(QDMI_Job job, QDMI_Job_Parameter param,
+                                const CustomJobParameter& value);
+
   /// @brief The underlying device pointer.
   QDMI_Device device_;
 
@@ -566,8 +575,8 @@ class Site {
   [[nodiscard]] T queryProperty(const QDMI_Site_Property prop) const {
     if constexpr (string_or_optional_string<T>) {
       size_t size = 0;
-      auto result = QDMI_device_query_site_property(*device_, site_, prop, 0,
-                                                    nullptr, &size);
+      const auto result = QDMI_device_query_site_property(*device_, site_, prop,
+                                                          0, nullptr, &size);
       if constexpr (is_optional<T>) {
         if (result == QDMI_ERROR_NOTSUPPORTED) {
           return std::nullopt;
@@ -576,8 +585,6 @@ class Site {
       qdmi::throwIfError(result,
                          std::string("Querying size") + qdmi::toString(prop));
       std::string value(size - 1, '\0');
-      result = QDMI_device_query_site_property(*device_, site_, prop, size,
-                                               value.data(), nullptr);
       qdmi::throwIfError(QDMI_device_query_site_property(*device_, site_, prop,
                                                          size, value.data(),
                                                          nullptr),

python/mqt/core/fomac.pyi

@@ -251,7 +251,18 @@ class Device:
     def supported_program_formats(self) -> list[ProgramFormat]:
         """Returns the list of program formats supported by the device."""
 
-    def submit_job(self, program: str, program_format: ProgramFormat, num_shots: int) -> Job:
+    def submit_job(
+        self,
+        program: str,
+        program_format: ProgramFormat,
+        num_shots: int,
+        *,
+        custom1: str | bool | float | None = None,
+        custom2: str | bool | float | None = None,
+        custom3: str | bool | float | None = None,
+        custom4: str | bool | float | None = None,
+        custom5: str | bool | float | None = None,
+    ) -> Job:
         """Submits a job to the device."""
 
     def __eq__(self, arg: object, /) -> bool: ...

src/fomac/FoMaC.cpp

@@ -28,7 +28,9 @@
 #include <sstream>
 #include <stdexcept>
 #include <string>
+#include <type_traits>
 #include <utility>
+#include <variant>
 #include <vector>
 
 namespace fomac {
@@ -285,35 +287,70 @@ std::vector<QDMI_Program_Format> Device::getSupportedProgramFormats() const {
 }
 
 Job Device::submitJob(const std::string& program,
-                      const QDMI_Program_Format format,
-                      const size_t numShots) const {
+                      const QDMI_Program_Format format, const size_t numShots,
+                      const std::optional<CustomJobParameter>& custom1,
+                      const std::optional<CustomJobParameter>& custom2,
+                      const std::optional<CustomJobParameter>& custom3,
+                      const std::optional<CustomJobParameter>& custom4,
+                      const std::optional<CustomJobParameter>& custom5) const {
   QDMI_Job job = nullptr;
   qdmi::throwIfError(QDMI_device_create_job(device_, &job), "Creating job");
-  Job jobWrapper{job}; // RAII wrapper to prevent leaks in case of exceptions
+  Job jobWrapper{job};
 
-  // Set program format
   qdmi::throwIfError(QDMI_job_set_parameter(jobWrapper,
                                             QDMI_JOB_PARAMETER_PROGRAMFORMAT,
                                             sizeof(format), &format),
                      "Setting program format");
-
-  // Set program
   qdmi::throwIfError(
       QDMI_job_set_parameter(jobWrapper, QDMI_JOB_PARAMETER_PROGRAM,
                              program.size() + 1, program.c_str()),
       "Setting program");
-
-  // Set number of shots
   qdmi::throwIfError(QDMI_job_set_parameter(jobWrapper,
                                             QDMI_JOB_PARAMETER_SHOTSNUM,
                                             sizeof(numShots), &numShots),
                      "Setting number of shots");
 
-  // Submit the job
+  if (custom1.has_value()) {
+    setCustomJobParam(jobWrapper, QDMI_JOB_PARAMETER_CUSTOM1, *custom1);
+  }
+  if (custom2.has_value()) {
+    setCustomJobParam(jobWrapper, QDMI_JOB_PARAMETER_CUSTOM2, *custom2);
+  }
+  if (custom3.has_value()) {
+    setCustomJobParam(jobWrapper, QDMI_JOB_PARAMETER_CUSTOM3, *custom3);
+  }
+  if (custom4.has_value()) {
+    setCustomJobParam(jobWrapper, QDMI_JOB_PARAMETER_CUSTOM4, *custom4);
+  }
+  if (custom5.has_value()) {
+    setCustomJobParam(jobWrapper, QDMI_JOB_PARAMETER_CUSTOM5, *custom5);
+  }
+
   qdmi::throwIfError(QDMI_job_submit(jobWrapper), "Submitting job");
   return jobWrapper;
 }
 
+void Device::setCustomJobParam(QDMI_Job job, const QDMI_Job_Parameter param,
+                               const CustomJobParameter& value) {
+  std::visit(
+      [&]<typename CustomValue>(const CustomValue& customValue) {
+        using T = std::decay_t<CustomValue>;
+        if constexpr (std::is_same_v<T, std::string>) {
+          qdmi::throwIfError(QDMI_job_set_parameter(job, param,
+                                                    customValue.size() + 1,
+                                                    customValue.c_str()),
+                             "Setting custom parameter");
+        } else {
+          static_assert(std::is_trivially_copyable_v<T>,
+                        "Custom job parameters must be trivially copyable");
+          qdmi::throwIfError(
+              QDMI_job_set_parameter(job, param, sizeof(T), &customValue),
+              "Setting custom parameter");
+        }
+      },
+      value);
+}
+
 QDMI_Job_Status Job::check() const {
   QDMI_Job_Status status{};
   qdmi::throwIfError(QDMI_job_check(job_.get(), &status),

src/qdmi/driver/Driver.cpp

@@ -275,6 +275,16 @@ namespace {
     return QDMI_DEVICE_JOB_PARAMETER_PROGRAMFORMAT;
   case QDMI_JOB_PARAMETER_SHOTSNUM:
     return QDMI_DEVICE_JOB_PARAMETER_SHOTSNUM;
+  case QDMI_JOB_PARAMETER_CUSTOM1:
+    return QDMI_DEVICE_JOB_PARAMETER_CUSTOM1;
+  case QDMI_JOB_PARAMETER_CUSTOM2:
+    return QDMI_DEVICE_JOB_PARAMETER_CUSTOM2;
+  case QDMI_JOB_PARAMETER_CUSTOM3:
+    return QDMI_DEVICE_JOB_PARAMETER_CUSTOM3;
+  case QDMI_JOB_PARAMETER_CUSTOM4:
+    return QDMI_DEVICE_JOB_PARAMETER_CUSTOM4;
+  case QDMI_JOB_PARAMETER_CUSTOM5:
+    return QDMI_DEVICE_JOB_PARAMETER_CUSTOM5;
   default:
     return QDMI_DEVICE_JOB_PARAMETER_MAX;
   }
@@ -286,7 +296,8 @@ QDMI_Job_impl_d::~QDMI_Job_impl_d() {
 }
 auto QDMI_Job_impl_d::setParameter(QDMI_Job_Parameter param, const size_t size,
                                    const void* value) const -> int {
-  if ((value != nullptr && size == 0) || param >= QDMI_JOB_PARAMETER_MAX) {
+  if ((value != nullptr && size == 0) ||
+      IS_INVALID_ARGUMENT(param, QDMI_JOB_PARAMETER)) {
     return QDMI_ERROR_INVALIDARGUMENT;
   }
   return device_->getLibrary().device_job_set_parameter(

test/fomac/test_fomac.cpp

@@ -21,6 +21,7 @@
 #include <fstream>
 #include <new>
 #include <numbers>
+#include <optional>
 #include <ranges>
 #include <stdexcept>
 #include <string>
@@ -556,6 +557,51 @@ c = measure q;)";
   EXPECT_EQ(job.check(), QDMI_JOB_STATUS_DONE);
 }
 
+TEST_F(DDSimulatorDeviceTest, SubmitJobCustomSupportedTypes) {
+  constexpr auto qasm3Program = "OPENQASM 3.0;";
+
+  auto submitWithCustoms = [&](auto custom, const size_t which) {
+    try {
+      switch (which) {
+      case 1:
+        std::ignore = device.submitJob(qasm3Program, QDMI_PROGRAM_FORMAT_QASM3,
+                                       10, custom);
+        break;
+      case 2:
+        std::ignore = device.submitJob(qasm3Program, QDMI_PROGRAM_FORMAT_QASM3,
+                                       10, std::nullopt, custom);
+        break;
+      case 3:
+        std::ignore = device.submitJob(qasm3Program, QDMI_PROGRAM_FORMAT_QASM3,
+                                       10, std::nullopt, std::nullopt, custom);
+        break;
+      case 4:
+        std::ignore =
+            device.submitJob(qasm3Program, QDMI_PROGRAM_FORMAT_QASM3, 10,
+                             std::nullopt, std::nullopt, std::nullopt, custom);
+        break;
+      case 5:
+        std::ignore = device.submitJob(qasm3Program, QDMI_PROGRAM_FORMAT_QASM3,
+                                       10, std::nullopt, std::nullopt,
+                                       std::nullopt, std::nullopt, custom);
+        break;
+      default:
+        throw std::invalid_argument("Invalid 'which' value");
+      }
+    } catch (const std::runtime_error& e) {
+      const std::string errorMsg(e.what());
+      EXPECT_TRUE(errorMsg.find("Setting custom parameter") !=
+                  std::string::npos);
+    }
+  };
+  for (size_t i = 1; i <= 5; ++i) {
+    submitWithCustoms(std::string("custom"), i);
+    submitWithCustoms(42, i);
+    submitWithCustoms(3.14, i);
+    submitWithCustoms(true, i);
+  }
+}
+
 TEST_F(DDSimulatorDeviceTest, SubmitJobPreservesNumShots) {
   const std::string qasm3Program = R"(
 OPENQASM 3.0;

test/python/fomac/test_fomac.py

@@ -421,6 +421,20 @@ def test_device_submit_job_returns_valid_job(ddsim_device: Device) -> None:
     assert job.num_shots == 100
 
 
+def test_device_submit_job_handles_custom_parameters(ddsim_device: Device) -> None:
+    """Test that submit_job forwards custom job parameters to DDSIM."""
+    with pytest.raises(RuntimeError, match=r"Setting custom parameter: Not supported\."):
+        ddsim_device.submit_job("OPENQASM 3.0;", ProgramFormat.QASM3, 1, custom1="value")
+    with pytest.raises(RuntimeError, match=r"Setting custom parameter: Not supported\."):
+        ddsim_device.submit_job("OPENQASM 3.0;", ProgramFormat.QASM3, 1, custom2="value")
+    with pytest.raises(RuntimeError, match=r"Setting custom parameter: Not supported\."):
+        ddsim_device.submit_job("OPENQASM 3.0;", ProgramFormat.QASM3, 1, custom3="value")
+    with pytest.raises(RuntimeError, match=r"Setting custom parameter: Not supported\."):
+        ddsim_device.submit_job("OPENQASM 3.0;", ProgramFormat.QASM3, 1, custom4="value")
+    with pytest.raises(RuntimeError, match=r"Setting custom parameter: Not supported\."):
+        ddsim_device.submit_job("OPENQASM 3.0;", ProgramFormat.QASM3, 1, custom5="value")
+
+
 def test_device_submit_job_preserves_num_shots(ddsim_device: Device) -> None:
     """Test that different shot counts are correctly preserved."""
     qasm3_program = """

test/qdmi/driver/test_driver.cpp

@@ -168,6 +168,14 @@ TEST_P(DriverJobTest, JobSetParameter) {
   EXPECT_THAT(QDMI_job_set_parameter(job, QDMI_JOB_PARAMETER_SHOTSNUM,
                                      sizeof(size_t), &numShots),
               testing::AnyOf(QDMI_SUCCESS, QDMI_ERROR_NOTSUPPORTED));
+  constexpr std::array customParams{
+      QDMI_JOB_PARAMETER_CUSTOM1, QDMI_JOB_PARAMETER_CUSTOM2,
+      QDMI_JOB_PARAMETER_CUSTOM3, QDMI_JOB_PARAMETER_CUSTOM4,
+      QDMI_JOB_PARAMETER_CUSTOM5};
+  for (const auto param : customParams) {
+    EXPECT_THAT(QDMI_job_set_parameter(job, param, 0, nullptr),
+                testing::AnyOf(QDMI_SUCCESS, QDMI_ERROR_NOTSUPPORTED));
+  }
   EXPECT_EQ(QDMI_job_set_parameter(job, QDMI_JOB_PARAMETER_MAX, 0, nullptr),
             QDMI_ERROR_INVALIDARGUMENT);
 }