C++ libraries and API reference

The native C++ API reference documents the installed public headers, including decision diagrams, benchmarks, and QDMI. It is generated from the same source revision as this guide.

Use the wheel’s native runtime

The Python wheel supplies the QDMI driver, device bundles, and the mqt-core executable. Its CMake package exposes the QDMI C interfaces; C++ DD, QDMI client, and benchmark libraries require a source installation.

This application runs one deterministic shot through DDSIM’s worker using the builtin driver’s C interface. Its bundle contains only the DDSIM device. Save it as main.cpp:

#include "qdmi/client.h"

#include <cstddef>
#include <stdexcept>
#include <string>

void check(int status) {
  if (status != QDMI_SUCCESS) {
    throw std::runtime_error("QDMI error: " + std::to_string(status));
  }
}

int main() {
  QDMI_Session session = nullptr;
  check(QDMI_session_alloc(&session));
  check(QDMI_session_init(session));
  QDMI_Device device = nullptr;
  check(QDMI_session_query_session_property(session,
                                            QDMI_SESSION_PROPERTY_DEVICES,
                                            sizeof(device), &device, nullptr));

  QDMI_Job job = nullptr;
  check(QDMI_device_create_job(device, &job));
  const char circuit[] = "OPENQASM 3.0; include \"stdgates.inc\"; "
                         "bit[1] c; x $0; c[0] = measure $0;";
  const void* program = circuit;
  const size_t length = sizeof(circuit);
  const size_t shots = 1;
  check(QDMI_job_set_programs(job, QDMI_PROGRAM_FORMAT_QASM3, 1, &length,
                              &program));
  check(QDMI_job_set_parameter(job, QDMI_JOB_PARAMETER_SHOTSNUM, sizeof(shots),
                               &shots));
  check(QDMI_job_submit(job));
  check(QDMI_job_wait(job, 30000));

  char result[2] = {};
  check(QDMI_job_get_results(job, 0, QDMI_JOB_RESULT_SHOTS, sizeof(result),
                             result, nullptr));
  QDMI_job_free(job);
  QDMI_session_free(session);
  if (std::string(result) != "1") {
    return 1;
  }
}

Save the following as CMakeLists.txt:

cmake_minimum_required(VERSION 3.28)
project(qdmi-example LANGUAGES CXX)
find_package(mqt-core CONFIG REQUIRED COMPONENTS Runtime)
add_executable(qdmi-example main.cpp)
target_compile_features(qdmi-example PRIVATE cxx_std_20)
target_link_libraries(qdmi-example PRIVATE MQT::CoreQDMIDriver)
mqt_copy_qdmi_runtime(qdmi-example MQT::CoreQDMI_DDSIM_Device)

enable_testing()
add_test(NAME qdmi-runtime COMMAND qdmi-example)

With the wheel installed in the active environment, run:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_PREFIX_PATH="$(mqt-core --cmake-dir)"
cmake --build build --config Release
ctest --test-dir build -C Release --output-on-failure

The application returns success after checking that DDSIM measured 1. The Runtime component requires no LLVM SDK.

CMake provides the MQT::mqt-core imported executable target. Use mqt-core compile and mqt-core bench in custom commands or from the command line. DDSIM launches mqt-core simulate --worker-socket <socket> as a separate process using its internal worker protocol.

Use the C++ development libraries

Build and install MQT Core from source, then request the Development component. It provides MQT::CoreDD, MQT::CoreQDMI, and MQT::CoreBench. The DD, QDMI C++ client, and benchmark libraries are static so LLVM errors stay within the consuming binary. Compile consumers with a compatible C++ toolchain. Development consumers require an LLVM SDK matching the major and minor version used to build MQT Core. CMake finds LLVM and propagates its headers and libraries through the imported targets.

find_package(mqt-core CONFIG REQUIRED COMPONENTS Development)
target_link_libraries(my-application PRIVATE MQT::CoreDD)

Point CMAKE_PREFIX_PATH at the source installation’s prefix. See Installation for source builds and other CMake integration options.

Handle native errors

Fallible native operations return llvm::Expected<T> or llvm::Error. Check an Expected before accessing its value; consume or propagate its takeError() on failure. An Error converts to true on failure. Infallible operations return ordinary values or void; optional<T> represents successful absence, such as an unsupported optional QDMI property.

Use create(...) for fallible construction:

#include "dd/Package.hpp"
#include "llvm/Support/Error.h"
#include "llvm/Support/raw_ostream.h"

auto package = dd::Package::create(2);
if (!package) {
  llvm::logAllUnhandledErrors(package.takeError(), llvm::errs());
  return 1;
}

Errors own their messages and categories. Bindings translate them to Python exceptions. MLIR operations with a caller-owned context use FailureOr<T> or LogicalResult and report through that context’s diagnostic engine. Native compilation boundaries capture those diagnostics in an owned error.

QDMI C interfaces retain status codes and local provider logging. C++ wrappers preserve the original provider status in the error’s std::error_code. Allocation exhaustion is outside the native recoverable-error contract; existing QDMI session and job handle allocations still return an error status. See driver resource limits and QIR runtime failures for direct execution.

Extend the compiler or QIR runtime

The MLIR compiler and QIR runtime use source-tree C++ interfaces. They are not part of the installed public-header reference above. See device compilation from C++, the QIR runtime guide, and the MLIR dialect and pass references.

DD input and output

DD serializers, DOT exporters, statistics and number printers write to llvm::raw_ostream. The caller owns the stream and checks any sink errors; file-writing overloads report failures with llvm::Error. Use llvm::raw_string_ostream to collect output in a std::string.

Package::deserialize reads borrowed llvm::StringRef bytes, including embedded NUL bytes. Use Package::deserializeFile for a filename. Binary serialization retains its native representation and is not portable between architectures. Serialized decimal weights are locale-independent; finite subnormal values are preserved. Complex weights use an explicit + or - between real and imaginary components, such as 1 - 2e3i.