C API: Burn ConsolidateBlocks (Qiskit#14751)

* Add: C FFI for `ConsolidateBlocks`
- Add `qk_transpiler_pass_standalone_consolidate_blocks` to expose a version of the `ConsolidateBlocks` pass to C. The pass runs on an instance of `CircuitData` and an optional `Target`.

* Chore: Add tests and fix formatting.

* Fix: C test deallocates

* Fix: Add missing void in function signature for c tests,

* Fix: Free circuit instruction instance afterwards.

* FIx: Add missing `qk_count_ops_free` to Ctests

* Fix: Modify the Circuit in place.

* Docs: Add release note

* Chore: Add test with target

* Fix: Incorrect formatting on c tests.

* Fix: Address review comments.
- Quit using malloc in favor of stack allocations.
- Remove dependency on synthesis module from `cext`.
- Add mention of `NaN` on docstring.

* Fix: Pivot to freeing the allocated space.

* Fix: Adapt to Qiskit#14930

* Fix: Redo stack approach correctly

Author: raynelfss

crates/cext/src/transpiler/passes/consolidate_blocks.rs

@@ -0,0 +1,73 @@
+// This code is part of Qiskit.
+//
+// (C) Copyright IBM 2025
+//
+// This code is licensed under the Apache License, Version 2.0. You may
+// obtain a copy of this license in the LICENSE.txt file in the root directory
+// of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
+//
+// Any modifications or derivative works of this code must retain this
+// copyright notice, and modified files need to carry a notice indicating
+// that they have been altered from the originals.
+
+use qiskit_circuit::{
+    circuit_data::CircuitData, converters::dag_to_circuit, dag_circuit::DAGCircuit,
+};
+use qiskit_transpiler::{passes::run_consolidate_blocks, target::Target};
+
+use crate::pointers::{const_ptr_as_ref, mut_ptr_as_ref};
+
+/// @ingroup QkTranspilerPasses
+/// Run the ConsolidateBlocks pass on a circuit.
+///
+/// ConsolidateBlocks is a transpiler pass that consolidates consecutive blocks of
+/// gates operating on the same qubits into a Unitary gate, to later on be
+/// resynthesized, which leads to a more optimal subcircuit.
+///
+/// @param circuit A pointer to the circuit to run ConsolidateBlocks on.
+/// @param target A pointer to the target to run ConsolidateBlocks on.
+/// @param approximation_degree A float between `[0.0, 1.0]` or a `NaN` which
+/// defaults to `1.0`. Lower approximates more.
+/// @param force_consolidate: Force block consolidation.
+///
+/// # Safety
+///
+/// Behavior is undefined if ``circuit`` is not a valid, non-null pointer to a ``QkCircuit`` and
+/// if ``target`` is not a valid pointer to a ``QkTarget``.
+#[no_mangle]
+#[cfg(feature = "cbinding")]
+pub unsafe extern "C" fn qk_transpiler_pass_standalone_consolidate_blocks(
+    circuit: *mut CircuitData,
+    target: *const Target,
+    approximation_degree: f64,
+    force_consolidate: bool,
+) {
+    let circuit = unsafe { mut_ptr_as_ref(circuit) };
+    let target = unsafe {
+        if target.is_null() {
+            None
+        } else {
+            Some(const_ptr_as_ref(target))
+        }
+    };
+    let approximation_degree = if approximation_degree.is_nan() {
+        1.0
+    } else {
+        approximation_degree
+    };
+    let mut circ_as_dag = DAGCircuit::from_circuit_data(circuit, true, None, None, None, None)
+        .expect("Error while converting from CircuitData to DAGCircuit.");
+
+    // Call the pass
+    run_consolidate_blocks(
+        &mut circ_as_dag,
+        force_consolidate,
+        Some(approximation_degree),
+        target,
+    )
+    .expect("Error running the consolidate blocks pass.");
+
+    let result_circuit = dag_to_circuit(&circ_as_dag, true)
+        .expect("Error while converting from DAGCircuit to CircuitData.");
+    *circuit = result_circuit;
+}

crates/cext/src/transpiler/passes/mod.rs

@@ -11,6 +11,7 @@
 // that they have been altered from the originals.
 
 pub mod commutative_cancellation;
+pub mod consolidate_blocks;
 pub mod elide_permutations;
 pub mod gate_direction;
 pub mod inverse_cancellation;

releasenotes/notes/c-api-consolidate-blocks-a1248e1f01cf1736.yaml

@@ -0,0 +1,24 @@
+---
+features_c:
+  - |
+    Add support for the :class:`.ConsolidateBlocks` transpiler pass to the C
+    API via the method :cpp:func:`qk_transpiler_pass_standalone_consolidate_blocks`.
+
+    Here's an example:
+
+    .. code-block:: C
+      
+      #include <qiskit.h>
+      
+      // Build circuit
+      QkCircuit *circuit = qk_circuit_new(2, 0);
+      uint32_t cx_qargs[2] = {1, 0};
+
+      qk_circuit_gate(circuit, QkGate_H, (uint32_t[1]){0}, NULL);
+      qk_circuit_gate(circuit, QkGate_CX, cx_qargs, NULL);
+
+      // Run pass, without Target
+      qk_transpiler_pass_standalone_consolidate_blocks(circuit, NULL, 1.0, true);
+
+      // Free the circuit once you're done
+      qk_circuit_free(circuit);