Add runtime C-API for arbitrary-basis measurement operations (#1674)

**Context:** A pass to convert the `mbqc.measure_in_basis` MLIR
operation (in the `mbqc` dialect) into the LLVM dialect was added in
#1679. In order to execute a compiled program containing this operation,
we require a runtime function defined in the Catalyst runtime C-API.

**Description of the Change:** Adds a new runtime stub to the Catalyst
runtime C-API called `__catalyst__mbqc__measure_in_basis()`. This
runtime function is effectively the same as the current
`__catalyst__qis__Measure()` runtime function for computational-basis
mid-circuit measurements since we will be validating the QJIT-compiled
MBQC workloads on the null.qubit device and do not require that it fully
simulates arbitrary-basis measurements—rather we treat it as a
placeholder for now in order to make the workload executable (see
Shortcut story linked below for details).


[[sc-89637](https://app.shortcut.com/xanaduai/story/89637/add-runtime-c-api-for-arbitrary-basis-measurement-operations)]

Author: joeycarter

doc/releases/changelog-dev.md

@@ -69,6 +69,14 @@
   [(#1663)](https://github.com/PennyLaneAI/catalyst/pull/1663)
   [(#1679)](https://github.com/PennyLaneAI/catalyst/pull/1679)
 
+* The Catalyst Runtime C-API now includes a stub for the experimental `mbqc.measure_in_basis`
+  operation, `__catalyst__mbqc__measure_in_basis()`, allowing for mock execution of MBQC workloads
+  containing parameterized arbitrary-basis measurements.
+  [(#1674)](https://github.com/PennyLaneAI/catalyst/pull/1674)
+
+  This runtime stub is currently for mock execution only and should be treated as a placeholder
+  operation. Internally, it functions just as a computational-basis measurement instruction.
+
 * The utility function `EnsureFunctionDeclaration` is refactored into the `Utils` of the `Catalyst` dialect, instead of being duplicated in each individual dialect.
   [(#1683)](https://github.com/PennyLaneAI/catalyst/pull/1683)
 

runtime/Makefile

@@ -41,7 +41,7 @@ ASAN_COMMAND = $(ASAN_FLAGS)
 endif
 
 BUILD_TARGETS := rt_capi rtd_null_qubit
-TEST_TARGETS := runner_tests_qir_runtime
+TEST_TARGETS := runner_tests_qir_runtime runner_tests_mbqc_runtime
 
 ifeq ($(ENABLE_OPENQASM), ON)
 	BUILD_TARGETS += rtd_openqasm
@@ -97,6 +97,8 @@ test: BUILD_TYPE?=RelWithDebInfo
 test: test_runner
 	@echo "Catalyst runtime test suite - NullQubit"
 	$(ASAN_COMMAND) $(RT_BUILD_DIR)/tests/runner_tests_qir_runtime
+	@echo "Catalyst MBQC runtime test suite"
+	$(ASAN_COMMAND) $(RT_BUILD_DIR)/tests/runner_tests_mbqc_runtime
 ifeq ($(ENABLE_OPENQASM), ON)
 	# Test the OpenQasm devices C++ tests
 	$(ASAN_COMMAND) $(PY_ASAN_OPTIONS) $(RT_BUILD_DIR)/tests/runner_tests_openqasm
@@ -116,6 +118,7 @@ coverage: export LLVM_PROFILE_FILE := $(RT_BUILD_DIR)/tests/%m.profraw
 coverage: test_runner
 	@echo "check C++ code coverage"
 	$(ASAN_COMMAND) $(RT_BUILD_DIR)/tests/runner_tests_qir_runtime
+	$(ASAN_COMMAND) $(RT_BUILD_DIR)/tests/runner_tests_mbqc_runtime
 ifeq ($(ENABLE_OPENQASM), ON)
 	$(ASAN_COMMAND) $(PY_ASAN_OPTIONS) $(RT_BUILD_DIR)/tests/runner_tests_openqasm
 endif
@@ -131,6 +134,7 @@ else
 	xcrun llvm-cov show -instr-profile $(RT_BUILD_DIR)/tests/rt_test_coverage.profdata \
 		-object $(RT_BUILD_DIR)/tests/runner_tests_openqasm \
 		$(RT_BUILD_DIR)/tests/runner_tests_qir_runtime \
+		$(RT_BUILD_DIR)/tests/runner_tests_mbqc_runtime \
 		-format=html -output-dir=$(RT_BUILD_DIR)/coverage_html \
 		$(MK_DIR)/include $(MK_DIR)/lib $(MK_DIR)/tests
 endif

runtime/include/RuntimeCAPI.h

@@ -104,6 +104,10 @@ void __catalyst__qis__State(MemRefT_CplxT_double_1d *, int64_t, /*qubits*/...);
 void __catalyst__qis__Gradient(int64_t, /*results*/...);
 void __catalyst__qis__Gradient_params(MemRefT_int64_1d *, int64_t, /*results*/...);
 
+// MBQC operations
+RESULT *__catalyst__mbqc__measure_in_basis(QUBIT *, uint32_t, double, int32_t);
+
+// Async runtime error
 void __catalyst__host__rt__unrecoverable_error();
 
 #ifdef __cplusplus

runtime/lib/capi/RuntimeCAPI.cpp

@@ -1031,4 +1031,26 @@ int8_t *__catalyst__rt__array_get_element_ptr_1d(QirArray *ptr, int64_t idx)
     QubitIdType *data = qubit_vector_ptr->data();
     return (int8_t *)&data[idx];
 }
+
+// -------------------------------------------------------------------------- //
+// MBQC Runtime CAPI
+// -------------------------------------------------------------------------- //
+
+// NOTE: Currently this runtime operations is exactly the same as __catalyst__qis__Measure();
+//       we effectively treat it as a no-op for now. When hardware devices that natively support
+//       mid-circuit measurements in an arbitrary basis are available, we will create a new
+//       QuantumDevice to implement this functionality according to the hardware specs.
+RESULT *__catalyst__mbqc__measure_in_basis(QUBIT *wire, uint32_t plane, double angle,
+                                           int32_t postselect)
+{
+    std::optional<int32_t> postselectOpt{postselect};
+
+    // Any value different to 0 or 1 denotes absence of postselect, and it is hence turned into
+    // std::nullopt at the C++ interface
+    if (postselect != 0 && postselect != 1) {
+        postselectOpt = std::nullopt;
+    }
+
+    return getQuantumDevicePtr()->Measure(reinterpret_cast<QubitIdType>(wire), postselectOpt);
+}
 }

runtime/tests/CMakeLists.txt

@@ -116,3 +116,18 @@ if(ENABLE_OQD)
 
     catch_discover_tests(runner_tests_oqd)
 endif()
+
+
+# MBQC test suite
+add_executable(runner_tests_mbqc_runtime)
+target_sources(runner_tests_mbqc_runtime PRIVATE
+    Test_MBQC.cpp
+)
+
+target_link_libraries(runner_tests_mbqc_runtime PRIVATE
+    Catch2WithMain
+    catalyst_runtime_testing
+    rtd_null_qubit
+)
+
+catch_discover_tests(runner_tests_mbqc_runtime)

runtime/tests/Test_MBQC.cpp

@@ -0,0 +1,48 @@
+// Copyright 2025 Xanadu Quantum Technologies Inc.
+
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+
+//     http://www.apache.org/licenses/LICENSE-2.0
+
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#include <catch2/catch_approx.hpp>
+#include <catch2/catch_test_macros.hpp>
+
+#include "RuntimeCAPI.h"
+
+// -------------------------------------------------------------------------- //
+// MBQC Runtime Tests
+// -------------------------------------------------------------------------- //
+
+TEST_CASE("Test __catalyst__mbqc__measure_in_basis, device=null.qubit", "[MBQC]")
+{
+    __catalyst__rt__initialize(nullptr);
+
+    const std::string rtd_name{"null.qubit"};
+    __catalyst__rt__device_init((int8_t *)rtd_name.c_str(), nullptr, nullptr, 0);
+
+    const size_t num_qubits = 1;
+    QirArray *qs = __catalyst__rt__qubit_allocate_array(num_qubits);
+
+    QUBIT **q0 = (QUBIT **)__catalyst__rt__array_get_element_ptr_1d(qs, 0);
+
+    CHECK(reinterpret_cast<QubitIdType>(*q0) == 0);
+
+    // Recall that the basis states for arbitrary-basis measurements are parameterized by a plane
+    // (either XY, YZ or ZX) and a rotation angle about that plane. See the `mbqc.measure_in_basis`
+    // op definition in mlir/include/MBQC/IR/MBQCOps.td for details on these parameters and how they
+    // are encoded.
+    RESULT *mres = __catalyst__mbqc__measure_in_basis(*q0, 0U /*plane*/, 0.0 /*angle*/, -1);
+
+    CHECK(*mres == false); // For null.qubit, measurement result is always 0 (false)
+
+    __catalyst__rt__device_release();
+    __catalyst__rt__finalize();
+}