Add substitute_node_with_dag to c api

This commit adds a new function qk_dag_substitute_node_with_dag to the C
api. This facilitates in place substitute from the new dag api. This is
fairly mechanical addition to the api as
`DAGCircuit::substitute_node_with_dag()` is already rust native. So
we only need to expose that inteface to C. The only difference between
the C and existing internal rust interface is that the qubit, clbit, and
var mapping arguments are not exposed to C. These options aren't
commonly used, and if the user needs to map the ordering they can do
that during replacement dag construction rather that at substitution
time.

Fixes #15190

Author: mtreinish

Cargo.lock

@@ -38,6 +38,7 @@ rand_pcg = "0.9"
 rand_distr = "0.5"
 num-traits = "0.2"
 uuid = { version = "1.18", features = ["v4", "fast-rng"], default-features = false }
+anyhow = "1.0"
 
 # Most of the crates don't need the feature `extension-module`, since only `qiskit-pyext` builds an
 # actual C extension (the feature disables linking in `libpython`, which is forbidden in Python

Cargo.toml

@@ -30,6 +30,7 @@ nalgebra.workspace = true
 hashbrown.workspace = true
 rand.workspace = true
 rand_pcg.workspace = true
+anyhow.workspace = true
 
 [build-dependencies]
 cbindgen = "0.29"

crates/cext/Cargo.toml

@@ -10,8 +10,10 @@
 // copyright notice, and modified files need to carry a notice indicating
 // that they have been altered from the originals.
 
+use anyhow::Error;
 use num_complex::Complex64;
 use smallvec::smallvec;
+use std::ffi::{CString, c_char};
 
 use qiskit_circuit::Qubit;
 use qiskit_circuit::bit::{ClassicalRegister, QuantumRegister};
@@ -23,6 +25,7 @@ use qiskit_circuit::operations::{
 };
 
 use crate::circuit::unitary_from_pointer;
+use crate::exit_codes::ExitCode;
 use crate::pointers::{const_ptr_as_ref, mut_ptr_as_ref};
 
 /// @ingroup QkDag
@@ -968,3 +971,96 @@ pub unsafe extern "C" fn qk_dag_topological_op_nodes(dag: *const DAGCircuit, out
         unsafe { out_order.add(i).write(node.index() as u32) }
     }
 }
+
+/// @ingroup QkDag
+/// Replace a node in a `QkDag` with a subcircuit specfied by another `QkDag`
+///
+/// @param dag A pointer to the DAG.
+/// @param node The node index of the operation to replace with the other `QkDag`. This
+///     must be the node index for an operation node in ``dag`` and the qargs and cargs
+///     count must match the number of qubits and clbits in `replacement`.
+/// @param replacement The other `QkDag` to replace `node` with. This dag must have
+///     the same number of qubits as the operation for ``node``. The node
+///     bit ordering will be ordering will be handled in order, so `qargs[0]` for
+///     `node` will be mapped to `qubits[0]` in `replacement`, `qargs[1]` to
+///     `qubits[0]`, etc. The same pattern applies to classical bits too.
+/// @param error A pointer to a pointer with an nul terminated string with an
+///     error description. If the function fails a pointer to the string with
+///     the error description will be written to this pointer. That pointer
+///     needs to be freed with `qk_str_free`. This can be a null pointer in
+///     which case the error will not be written out.
+///
+/// @returns The return code for the operation, ``QkExitCode_Success`` means success and all
+///   other values indicate an error.
+///
+/// # Example
+///
+/// ```c
+/// QkDag *dag = qk_dag_new();
+/// QkQuantumRegister *qr = qk_quantum_register_new(1, "my_register");
+/// qk_dag_add_quantum_register(dag, qr);
+///
+/// uint32_t qubit[1] = {0};
+/// uint32_t node_to_replace = qk_dag_apply_gate(dag, QkGate_H, qubit, NULL, false);
+/// qk_dag_apply_gate(dag, QkGate_S, qubit, NULL, false);
+///
+/// // Build replacement dag for H
+/// QkDag *replacement = qk_dag_new();
+/// QkQuantumRegister *replacement_qr = qk_quantum_register_new(1, "other");
+/// qk_dag_add_quantum_register(replacement, replacement_qr);
+/// double pi_param [1] = {3.14159,};
+/// qk_dag_apply_gate(replacement, QkGate_RZ, qubit, pi_param, false);
+/// qk_dag_apply_gate(replacement, QkGate_SX, qubit, NULL, false);
+/// qk_dag_apply_gate(replacement, QkGate_RZ, qubit, pi_param, false);
+///
+/// qk_dag_substitute_node_with_dag(dag, node_to_replace, replacement, NULL);
+///
+/// // Free the replacement dag, register, dag, and register
+/// qk_quantum_register_free(replacement_qr);
+/// qk_dag_free(replacement);
+/// qk_quantum_register_free(qr);
+/// qk_dag_free(dag);
+/// ```
+///
+/// # Safety
+///
+/// Behavior is undefined if ``dag`` and ``replacement`` are not a valid, non-null pointer to a
+/// ``QkDag``. ``error`` must be a valid pointer to a ``char`` pointer or ``NULL``.
+#[unsafe(no_mangle)]
+#[cfg(feature = "cbinding")]
+pub unsafe extern "C" fn qk_dag_substitute_node_with_dag(
+    dag: *mut DAGCircuit,
+    node: u32,
+    replacement: *const DAGCircuit,
+    error: *mut *mut c_char,
+) -> ExitCode {
+    // SAFETY: Per documentation, ``dag`` is non-null and valid.
+    let dag = unsafe { mut_ptr_as_ref(dag) };
+    let replacement = unsafe { const_ptr_as_ref(replacement) };
+
+    match dag.substitute_node_with_dag(NodeIndex::new(node as usize), replacement, None, None, None)
+    {
+        Ok(_) => ExitCode::Success,
+        Err(e) => {
+            if !error.is_null() {
+                let err: Error = e.into();
+                // SAFETY: Per the documentation error is either null or a valid and aligned
+                // pointer to a pointer of a C string which is safe to write a pointer to the
+                // Rust heap into.
+                unsafe {
+                    // Right now we return a backtrace of the error. This at least gives a hint as to
+                    // which pass failed when we have rust errors normalized we can actually have error
+                    // messages which are user facing. But most likely this will be a PyErr and panic
+                    // when trying to extract the string.
+                    *error = CString::new(format!(
+                        "Transpilation failed with this backtrace: {}",
+                        err.backtrace()
+                    ))
+                    .unwrap()
+                    .into_raw();
+                }
+            }
+            ExitCode::DagError
+        }
+    }
+}

crates/cext/src/dag.rs

@@ -60,6 +60,8 @@ pub enum ExitCode {
     TargetInvalidInstKey = 304,
     /// Transpilation failed
     TranspilerError = 400,
+    /// QkDag operation error
+    DagError = 500,
 }
 
 impl From<ArithmeticError> for ExitCode {

crates/cext/src/exit_codes.rs

@@ -29,7 +29,7 @@ qiskit-quantum-info.workspace = true
 thiserror.workspace = true
 bytemuck.workspace = true
 fixedbitset = "0.5.7"
-anyhow = "1.0"
+anyhow.workspace = true
 
 [dependencies.uuid]
 workspace = true

crates/transpiler/Cargo.toml

@@ -508,6 +508,50 @@ static int test_unitary_gates(void) {
     return res;
 }
 
+static int test_substitute_node_with_dag(void) {
+    int res = Ok;
+    QkDag *dag = qk_dag_new();
+    QkQuantumRegister *qr = qk_quantum_register_new(1, "my_register");
+    qk_dag_add_quantum_register(dag, qr);
+
+    uint32_t qubit[1] = {0};
+    uint32_t node_to_replace = qk_dag_apply_gate(dag, QkGate_H, qubit, NULL, false);
+    qk_dag_apply_gate(dag, QkGate_S, qubit, NULL, false);
+
+    // Build replacement dag for H
+    QkDag *replacement = qk_dag_new();
+    QkQuantumRegister *replacement_qr = qk_quantum_register_new(1, "other");
+    qk_dag_add_quantum_register(replacement, replacement_qr);
+    double pi_param[1] = {
+        3.14159,
+    };
+    qk_dag_apply_gate(replacement, QkGate_RZ, qubit, pi_param, false);
+    qk_dag_apply_gate(replacement, QkGate_SX, qubit, NULL, false);
+    qk_dag_apply_gate(replacement, QkGate_RZ, qubit, pi_param, false);
+    char *error = NULL;
+    int ret_code = qk_dag_substitute_node_with_dag(dag, node_to_replace, replacement, &error);
+    if (ret_code != QkExitCode_Success) {
+        res = EqualityError;
+        printf("Substitute call failed: %s\n", error);
+        goto cleanup;
+    }
+
+    if (qk_dag_num_op_nodes(dag) != 4) {
+        res = EqualityError;
+        printf("Number of instructions is %zd but expected 4\n", qk_dag_num_op_nodes(dag));
+        goto cleanup;
+    }
+
+cleanup:
+    // Free the replacement dag, register, dag, and register
+    qk_quantum_register_free(replacement_qr);
+    qk_dag_free(replacement);
+    qk_quantum_register_free(qr);
+    qk_dag_free(dag);
+
+    return res;
+}
+
 int test_dag(void) {
     int num_failed = 0;
     num_failed += RUN_TEST(test_empty);
@@ -520,6 +564,7 @@ int test_dag(void) {
     num_failed += RUN_TEST(test_op_node_bits_explicit);
     num_failed += RUN_TEST(test_dag_topological_op_nodes);
     num_failed += RUN_TEST(test_unitary_gates);
+    num_failed += RUN_TEST(test_substitute_node_with_dag);
 
     fflush(stderr);
     fprintf(stderr, "=== Number of failed subtests: %i\n", num_failed);