RFC1: Fix dt-unit Delay handling in the C API (minimal patch)

crates/cext/src/circuit.rs

@@ -1909,6 +1909,8 @@ pub enum CDelayUnit {
     NS = 3,
     /// Picoseconds.
     PS = 4,
+    /// QPU clock cycles.
+    DT = 5,
 }
 
 impl From<CDelayUnit> for DelayUnit {
@@ -1919,6 +1921,7 @@ impl From<CDelayUnit> for DelayUnit {
             CDelayUnit::US => DelayUnit::US,
             CDelayUnit::NS => DelayUnit::NS,
             CDelayUnit::PS => DelayUnit::PS,
+            CDelayUnit::DT => DelayUnit::DT,
         }
     }
 }
@@ -1970,6 +1973,46 @@ pub unsafe extern "C" fn qk_circuit_delay(
     ExitCode::Success
 }
 
+/// @ingroup QkCircuit
+/// Append a delay instruction with unit ``dt`` to the circuit.
+///
+/// The duration is stored internally as a floating-point value; values larger
+/// than ``2^53`` lose precision.
+///
+/// @param circuit A pointer to the circuit to add the delay to.
+/// @param qubit The ``uint32_t`` index of the qubit to apply the delay to.
+/// @param duration The duration of the delay in clock cycles.
+///
+/// @return An exit code.
+///
+/// # Safety
+///
+/// Behavior is undefined if ``circuit`` is not a valid, non-null pointer to a ``QkCircuit``.
+#[unsafe(no_mangle)]
+pub unsafe extern "C" fn qk_circuit_delay_dt(
+    circuit: *mut CircuitData,
+    qubit: u32,
+    duration: u64,
+) -> ExitCode {
+    // SAFETY: Per documentation, the pointer is non-null and aligned.
+    let circuit = unsafe { mut_ptr_as_ref(circuit) };
+
+    let duration_param: Param = (duration as f64).into();
+    let delay_instruction = StandardInstruction::Delay(DelayUnit::DT);
+
+    let params = Parameters::Params(smallvec![duration_param]);
+    circuit
+        .push_packed_operation(
+            PackedOperation::from_standard_instruction(delay_instruction),
+            Some(params),
+            &[Qubit(qubit)],
+            &[],
+        )
+        .unwrap();
+
+    ExitCode::Success
+}
+
 /// The configuration options for the ``qk_circuit_draw`` function.
 #[repr(C)]
 pub struct CircuitDrawerConfig {

crates/circuit/src/circuit_instruction.rs

@@ -1023,14 +1023,11 @@ pub fn extract_params<T: CircuitBlock>(
             match &i {
                 StandardInstruction::Barrier(_) => None,
                 StandardInstruction::Delay(_) => {
-                    // If the delay's duration is a Python int, we preserve it rather than
-                    // coercing it to a float (e.g. when unit is 'dt').
-                    Some(Parameters::Params(
-                        params
-                            .try_iter()?
-                            .map(|p| Param::extract_no_coerce(p?.as_borrowed()))
-                            .collect::<PyResult<_>>()?,
-                    ))
+                    // Coerce the duration to `Param::Float`. Python `int` durations (used for
+                    // the 'dt' unit) round-trip back to `int` on the Python side via
+                    // `Delay.validate_parameter`.
+                    let params: SmallVec<[Param; 3]> = params.extract()?;
+                    Some(Parameters::Params(params))
                 }
                 StandardInstruction::Measure => None,
                 StandardInstruction::Reset => None,

crates/circuit/src/operations.rs

@@ -181,8 +181,7 @@ impl Param {
                     if coerce_to_float {
                         Ok(Self::Float(i as f64)) // coerce integer to float
                     } else {
-                        // Int is not a param type and only comes from Python so dump it in
-                        // there until we support DT unit delay from C
+                        // Int is not a `Param` variant; store as a Python object.
                         Python::attach(|py| Ok(Self::Obj(i.into_py_any(py)?)))
                     }
                 }

releasenotes/notes/c-api-dt-delay-2d0bc1fcf6b7214c.yaml

@@ -0,0 +1,13 @@
+---
+features_c:
+  - |
+    Added support for ``dt``-unit delays to the C API. The ``QkDelayUnit`` enum
+    now includes ``QkDelayUnit_DT``, and a new function
+    ``qk_circuit_delay_dt(circuit, qubit, duration)`` constructs a delay whose
+    duration is given in integer clock cycles (``uint64_t``).
+fixes:
+  - |
+    Fixed a crash where reading a ``QkCircuit`` containing a ``Delay`` with
+    unit ``"dt"`` (built from Python) via the C API would panic. The integer
+    duration is now stored as a floating-point value internally, so the
+    instruction is readable by the C-API instruction-readback path.

test/c/test_circuit.c

@@ -1153,6 +1153,28 @@ static int test_delay_instruction(void) {
         goto cleanup;
     }
 
+    QkExitCode delay_dt_code = qk_circuit_delay_dt(qc, 1, 100);
+    if (delay_dt_code != QkExitCode_Success) {
+        result = RuntimeError;
+        goto cleanup;
+    }
+
+    // Read back the dt-delay and verify the duration.
+    QkCircuitInstruction inst;
+    qk_circuit_get_instruction(qc, 1, &inst);
+    if (inst.num_params != 1) {
+        printf("Expected 1 parameter in dt-delay, got %u\n", inst.num_params);
+        result = EqualityError;
+        qk_circuit_instruction_clear(&inst);
+        goto cleanup;
+    }
+    double duration = qk_param_as_real(inst.params[0]);
+    if (fabs(duration - 100.0) > 1e-10) {
+        printf("Unexpected dt-delay duration: %f\n", duration);
+        result = EqualityError;
+    }
+    qk_circuit_instruction_clear(&inst);
+
 cleanup:
     qk_circuit_free(qc);
     return result;

test/python/circuit/test_delay.py

@@ -12,6 +12,7 @@
 
 
 """Test delay instruction for quantum circuits."""
+
 import copy
 import pickle
 
@@ -40,6 +41,13 @@ def test_keep_units_after_adding_delays_to_circuit(self):
         self.assertEqual(qc.data[3].operation.unit, "ns")
         self.assertEqual(qc.data[4].operation.unit, "dt")
 
+    def test_dt_duration_stays_int_after_circuit_roundtrip(self):
+        qc = QuantumCircuit(1)
+        qc.delay(100, 0, unit="dt")
+        duration = qc.data[0].operation.duration
+        self.assertIsInstance(duration, int)
+        self.assertEqual(duration, 100)
+
     def test_fail_if_non_integer_duration_with_dt_unit_is_supplied(self):
         qc = QuantumCircuit(1)
         with self.assertRaises(CircuitError):