Move Python utilities from circuit to util (#15910)

jakelishman · web-flow · commit 25a8160c7354 · 2026-04-01T09:11:35.000Z
The base definitions of these objects are unrelated to `qiskit-circuit`
and the core circuit IR concepts, and can easily be moved into the
`qiskit-util` crate to break further spurious dependencies on the IR
definitions.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/crates/circuit/Cargo.toml b/crates/circuit/Cargo.toml
@@ -13,7 +13,7 @@ doctest = false
 workspace = true
 
 [dependencies]
-qiskit-util.workspace = true
+qiskit-util = { workspace = true, features = ["py"] }
 rayon.workspace = true
 ahash.workspace = true
 rustworkx-core.workspace = true
diff --git a/crates/circuit/src/bit.rs b/crates/circuit/src/bit.rs
@@ -29,7 +29,7 @@ use pyo3::{
 
 use crate::circuit_data::CircuitError;
 use crate::dag_circuit::PyBitLocations;
-use crate::slice::{PySequenceIndex, SequenceIndex};
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 /// Describes a relationship between a bit and all the registers it belongs to
 #[derive(Debug, Clone)]
diff --git a/crates/circuit/src/circuit_data.rs b/crates/circuit/src/circuit_data.rs
@@ -37,14 +37,14 @@ use crate::parameter::parameter_expression::{ParameterError, ParameterExpression
 use crate::parameter::symbol_expr::{Symbol, Value};
 use crate::parameter_table::{ParameterTable, ParameterTableError, ParameterUse, ParameterUuid};
 use crate::register_data::RegisterData;
-use crate::slice::{PySequenceIndex, SequenceIndex};
 use crate::var_stretch_container::{
     StretchType, VarStretchContainer, VarStretchContainerError, VarType,
 };
 use crate::{
     Block, BlocksMode, CapacityError, Clbit, ControlFlowBlocks, Qubit, Stretch, Var, VarsMode,
     instruction,
 };
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 use ndarray::ArrayView1;
 use num_complex::Complex64;
diff --git a/crates/circuit/src/dag_circuit.rs b/crates/circuit/src/dag_circuit.rs
@@ -39,13 +39,13 @@ use crate::operations::{
 use crate::packed_instruction::{PackedInstruction, PackedOperation};
 use crate::parameter::parameter_expression::ParameterExpression;
 use crate::register_data::RegisterData;
-use crate::slice::PySequenceIndex;
 use crate::var_stretch_container::{StretchType, VarStretchContainer, VarType};
 use crate::variable_mapper::VariableMapper;
 use crate::{
     Block, BlockMapper, BlocksMode, Clbit, ControlFlowBlocks, Qubit, Stretch, TupleLikeArg, Var,
     VarsMode, imports, instruction, vf2,
 };
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 use hashbrown::{HashMap, HashSet};
 use indexmap::{IndexMap, IndexSet};
@@ -334,7 +334,7 @@ impl PyBitLocations {
         };
         if let Ok(index) = index.with_len(2) {
             match index {
-                crate::slice::SequenceIndex::Int(index) => getter(index),
+                SequenceIndex::Int(index) => getter(index),
                 _ => PyTuple::new(py, index.iter().map(|idx| getter(idx).unwrap()))
                     .map(|obj| obj.into_any().unbind()),
             }
diff --git a/crates/circuit/src/imports.rs b/crates/circuit/src/imports.rs
@@ -18,49 +18,9 @@ use pyo3::prelude::*;
 use pyo3::sync::PyOnceLock;
 
 use crate::operations::{STANDARD_GATE_SIZE, StandardGate};
+use qiskit_util::py::ImportOnceCell;
 
-/// Helper wrapper around `PyOnceLock` instances that are just intended to store a Python object
-/// that is lazily imported.
-pub struct ImportOnceCell {
-    module: &'static str,
-    object: &'static str,
-    cell: PyOnceLock<Py<PyAny>>,
-}
-
-impl ImportOnceCell {
-    pub const fn new(module: &'static str, object: &'static str) -> Self {
-        Self {
-            module,
-            object,
-            cell: PyOnceLock::new(),
-        }
-    }
-
-    /// Get the underlying GIL-independent reference to the contained object, importing if
-    /// required.
-    #[inline]
-    pub fn get(&self, py: Python) -> &Py<PyAny> {
-        self.cell.get_or_init(py, || {
-            py.import(self.module)
-                .unwrap()
-                .getattr(self.object)
-                .unwrap()
-                .unbind()
-        })
-    }
-
-    /// Get a GIL-bound reference to the contained object, importing if required.
-    #[inline]
-    pub fn get_bound<'py>(&self, py: Python<'py>) -> &Bound<'py, PyAny> {
-        self.get(py).bind(py)
-    }
-}
-
-pub static BUILTIN_LIST: ImportOnceCell = ImportOnceCell::new("builtins", "list");
-pub static BUILTIN_SET: ImportOnceCell = ImportOnceCell::new("builtins", "set");
-pub static BUILTIN_RANGE: ImportOnceCell = ImportOnceCell::new("builtins", "range");
-pub static BUILTIN_USER_WARNING: ImportOnceCell = ImportOnceCell::new("builtins", "UserWarning");
-pub static BUILTIN_HASH: ImportOnceCell = ImportOnceCell::new("builtins", "hash");
+pub use qiskit_util::py::imports::*;
 
 pub static OPERATION: ImportOnceCell = ImportOnceCell::new("qiskit.circuit.operation", "Operation");
 pub static INSTRUCTION: ImportOnceCell =
@@ -111,18 +71,15 @@ pub static CASE_DEFAULT: ImportOnceCell = ImportOnceCell::new("qiskit.circuit",
 pub static CLBIT: ImportOnceCell = ImportOnceCell::new("qiskit.circuit", "Clbit");
 pub static CLASSICAL_REGISTER: ImportOnceCell =
     ImportOnceCell::new("qiskit.circuit", "ClassicalRegister");
-pub static DEEPCOPY: ImportOnceCell = ImportOnceCell::new("copy", "deepcopy");
 pub static QI_OPERATOR: ImportOnceCell = ImportOnceCell::new("qiskit.quantum_info", "Operator");
 pub static CLIFFORD: ImportOnceCell =
     ImportOnceCell::new("qiskit.quantum_info.operators.symplectic", "Clifford");
 pub static SPARSE_PAULI_OP: ImportOnceCell =
     ImportOnceCell::new("qiskit.quantum_info.operators", "SparsePauliOp");
-pub static WARNINGS_WARN: ImportOnceCell = ImportOnceCell::new("warnings", "warn");
 pub static CIRCUIT_TO_DAG: ImportOnceCell =
     ImportOnceCell::new("qiskit.converters", "circuit_to_dag");
 pub static DAG_TO_CIRCUIT: ImportOnceCell =
     ImportOnceCell::new("qiskit.converters", "dag_to_circuit");
-pub static UUID: ImportOnceCell = ImportOnceCell::new("uuid", "UUID");
 pub static BARRIER: ImportOnceCell = ImportOnceCell::new("qiskit.circuit", "Barrier");
 pub static DELAY: ImportOnceCell = ImportOnceCell::new("qiskit.circuit", "Delay");
 pub static MEASURE: ImportOnceCell = ImportOnceCell::new("qiskit.circuit", "Measure");
@@ -163,8 +120,6 @@ pub static XX_DECOMPOSER: ImportOnceCell =
     ImportOnceCell::new("qiskit.synthesis.two_qubit.xx_decompose", "XXDecomposer");
 pub static XX_EMBODIMENTS: ImportOnceCell =
     ImportOnceCell::new("qiskit.synthesis.two_qubit.xx_decompose", "XXEmbodiments");
-pub static NUMPY_COPY_ONLY_IF_NEEDED: ImportOnceCell =
-    ImportOnceCell::new("qiskit._numpy_compat", "COPY_ONLY_IF_NEEDED");
 pub static HLS_SYNTHESIZE_OP_USING_PLUGINS: ImportOnceCell = ImportOnceCell::new(
     "qiskit.transpiler.passes.synthesis.high_level_synthesis",
     "_synthesize_op_using_plugins",
@@ -179,7 +134,6 @@ pub static CONTROL_FLOW_BOX_OP: ImportOnceCell =
 pub static TRANSPILER_LAYOUT: ImportOnceCell =
     ImportOnceCell::new("qiskit.transpiler.layout", "TranspileLayout");
 pub static LAYOUT: ImportOnceCell = ImportOnceCell::new("qiskit.transpiler.layout", "Layout");
-pub static NUMPY_ARRAY: ImportOnceCell = ImportOnceCell::new("numpy", "ndarray");
 pub static SYMPIFY_PARAMETER_EXPRESSION: ImportOnceCell =
     ImportOnceCell::new("qiskit.circuit.parameterexpression", "sympify");
 pub static TRANSPILE_LAYOUT: ImportOnceCell =
diff --git a/crates/circuit/src/lib.rs b/crates/circuit/src/lib.rs
@@ -35,7 +35,6 @@ pub mod packed_instruction;
 pub mod parameter;
 pub mod parameter_table;
 pub mod register_data;
-pub mod slice;
 pub mod standard_gate;
 pub mod var_stretch_container;
 mod variable_mapper;
diff --git a/crates/quantum_info/Cargo.toml b/crates/quantum_info/Cargo.toml
@@ -11,7 +11,7 @@ doctest = false
 
 [dependencies]
 qiskit-circuit.workspace = true
-qiskit-util.workspace = true
+qiskit-util = { workspace = true, features = ["py"] }
 numpy.workspace = true
 num-complex.workspace = true
 num-traits.workspace = true
diff --git a/crates/quantum_info/src/lib.rs b/crates/quantum_info/src/lib.rs
@@ -24,7 +24,7 @@ mod test;
 use pyo3::import_exception;
 
 pub(crate) mod imports {
-    use qiskit_circuit::imports::ImportOnceCell;
+    use qiskit_util::py::ImportOnceCell;
 
     pub static PAULI_TYPE: ImportOnceCell = ImportOnceCell::new("qiskit.quantum_info", "Pauli");
     pub static PAULI_LIST_TYPE: ImportOnceCell =
diff --git a/crates/quantum_info/src/pauli_lindblad_map/pauli_lindblad_map_class.rs b/crates/quantum_info/src/pauli_lindblad_map/pauli_lindblad_map_class.rs
@@ -28,7 +28,7 @@ use rand::prelude::*;
 use rand_distr::Bernoulli;
 use rand_pcg::Pcg64Mcg;
 
-use qiskit_circuit::slice::{PySequenceIndex, SequenceIndex};
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 use super::qubit_sparse_pauli::{
     ArithmeticError, CoherenceError, InnerReadError, InnerWriteError, LabelError, Pauli,
diff --git a/crates/quantum_info/src/pauli_lindblad_map/phased_qubit_sparse_pauli.rs b/crates/quantum_info/src/pauli_lindblad_map/phased_qubit_sparse_pauli.rs
@@ -23,7 +23,7 @@ use std::{
     sync::{Arc, RwLock},
 };
 
-use qiskit_circuit::slice::{PySequenceIndex, SequenceIndex};
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 use super::qubit_sparse_pauli::{
     ArithmeticError, CoherenceError, InnerReadError, InnerWriteError, LabelError, Pauli,
diff --git a/crates/quantum_info/src/pauli_lindblad_map/qubit_sparse_pauli.rs b/crates/quantum_info/src/pauli_lindblad_map/qubit_sparse_pauli.rs
@@ -29,7 +29,7 @@ use std::{
 };
 use thiserror::Error;
 
-use qiskit_circuit::slice::{PySequenceIndex, SequenceIndex};
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 use crate::imports;
 
diff --git a/crates/quantum_info/src/sparse_observable/mod.rs b/crates/quantum_info/src/sparse_observable/mod.rs
@@ -39,9 +39,8 @@ use std::{
 };
 use thiserror::Error;
 
-use qiskit_circuit::{
-    imports::{ImportOnceCell, NUMPY_COPY_ONLY_IF_NEEDED},
-    slice::{PySequenceIndex, SequenceIndex},
+use qiskit_util::py::{
+    ImportOnceCell, PySequenceIndex, SequenceIndex, imports::NUMPY_COPY_ONLY_IF_NEEDED,
 };
 
 static PAULI_TYPE: ImportOnceCell = ImportOnceCell::new("qiskit.quantum_info", "Pauli");
diff --git a/crates/synthesis/src/euler_one_qubit_decomposer.rs b/crates/synthesis/src/euler_one_qubit_decomposer.rs
@@ -34,9 +34,9 @@ use pyo3::pybacked::PyBackedStr;
 use qiskit_circuit::circuit_data::{CircuitData, PyCircuitData};
 use qiskit_circuit::dag_node::DAGOpNode;
 use qiskit_circuit::operations::{Operation, Param, StandardGate};
-use qiskit_circuit::slice::{PySequenceIndex, SequenceIndex};
 use qiskit_circuit::{Qubit, impl_intopyobject_for_copy_pyclass};
 use qiskit_util::complex::c64;
+use qiskit_util::py::{PySequenceIndex, SequenceIndex};
 
 pub const ANGLE_ZERO_EPSILON: f64 = 1e-12;
 
diff --git a/crates/synthesis/src/permutation/utils.rs b/crates/synthesis/src/permutation/utils.rs
@@ -16,7 +16,7 @@ use pyo3::exceptions::PyValueError;
 use pyo3::prelude::*;
 use std::vec::Vec;
 
-use qiskit_circuit::slice::PySequenceIndex;
+use qiskit_util::py::PySequenceIndex;
 
 pub fn validate_permutation(pattern: &ArrayView1<i64>) -> PyResult<()> {
     let n = pattern.len();
diff --git a/crates/transpiler/Cargo.toml b/crates/transpiler/Cargo.toml
@@ -26,7 +26,7 @@ rustworkx-core.workspace = true
 qiskit-circuit.workspace = true
 qiskit-synthesis.workspace = true
 qiskit-quantum-info.workspace = true
-qiskit-util.workspace = true
+qiskit-util = { workspace = true, features = ["py"] }
 thiserror.workspace = true
 bytemuck.workspace = true
 fixedbitset.workspace = true
diff --git a/crates/transpiler/src/equivalence.rs b/crates/transpiler/src/equivalence.rs
@@ -40,11 +40,12 @@ use rustworkx_core::petgraph::{
 use qiskit_circuit::NoBlocks;
 use qiskit_circuit::circuit_data::{CircuitData, PyCircuitData};
 use qiskit_circuit::circuit_instruction::OperationFromPython;
-use qiskit_circuit::imports::{ImportOnceCell, QUANTUM_CIRCUIT};
+use qiskit_circuit::imports::QUANTUM_CIRCUIT;
 use qiskit_circuit::instruction::Parameters;
 use qiskit_circuit::operations::Param;
 use qiskit_circuit::operations::{Operation, OperationRef};
 use qiskit_circuit::packed_instruction::PackedOperation;
+use qiskit_util::py::ImportOnceCell;
 
 use crate::standard_equivalence_library::generate_standard_equivalence_library;
 
diff --git a/crates/transpiler/src/passes/disjoint_layout.rs b/crates/transpiler/src/passes/disjoint_layout.rs
@@ -28,12 +28,12 @@ use crate::TranspilerError;
 use crate::target::{Qargs, Target};
 use qiskit_circuit::bit::ShareableQubit;
 use qiskit_circuit::dag_circuit::DAGCircuit;
-use qiskit_circuit::imports::ImportOnceCell;
 use qiskit_circuit::operations::{Operation, OperationRef, StandardInstruction};
 use qiskit_circuit::packed_instruction::PackedOperation;
 use qiskit_circuit::{
     BlockMapper, BlocksMode, Clbit, PhysicalQubit, Qubit, VarsMode, VirtualQubit,
 };
+use qiskit_util::py::ImportOnceCell;
 
 create_exception!(qiskit, MultiQEncountered, pyo3::exceptions::PyException);
 
diff --git a/crates/util/Cargo.toml b/crates/util/Cargo.toml
@@ -9,8 +9,13 @@ license.workspace = true
 name = "qiskit_util"
 doctest = false
 
+[features]
+py = ["dep:pyo3"]
+
 [lints]
 workspace = true
 
 [dependencies]
 num-complex.workspace = true
+pyo3 = { workspace = true, optional = true }
+thiserror.workspace = true
diff --git a/crates/util/src/lib.rs b/crates/util/src/lib.rs
@@ -12,6 +12,9 @@
 
 use std::env;
 
+#[cfg(feature = "py")]
+pub mod py;
+
 pub mod complex {
     use num_complex::Complex64;
 
diff --git a/crates/util/src/py.rs b/crates/util/src/py.rs
@@ -1,6 +1,6 @@
 // This code is part of Qiskit.
 //
-// (C) Copyright IBM 2024
+// (C) Copyright IBM 2026
 //
 // 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
@@ -14,10 +14,65 @@ use thiserror::Error;
 
 use pyo3::exceptions::PyIndexError;
 use pyo3::prelude::*;
+use pyo3::sync::PyOnceLock;
 use pyo3::types::PySlice;
 
 use self::sealed::{Descending, SequenceIndexIter};
 
+/// Helper wrapper around `PyOnceLock` instances that are just intended to store a Python object
+/// that is lazily imported.
+pub struct ImportOnceCell {
+    module: &'static str,
+    object: &'static str,
+    cell: PyOnceLock<Py<PyAny>>,
+}
+
+impl ImportOnceCell {
+    pub const fn new(module: &'static str, object: &'static str) -> Self {
+        Self {
+            module,
+            object,
+            cell: PyOnceLock::new(),
+        }
+    }
+
+    /// Get the underlying GIL-independent reference to the contained object, importing if
+    /// required.
+    #[inline]
+    pub fn get(&self, py: Python) -> &Py<PyAny> {
+        self.cell.get_or_init(py, || {
+            py.import(self.module)
+                .unwrap()
+                .getattr(self.object)
+                .unwrap()
+                .unbind()
+        })
+    }
+
+    /// Get a GIL-bound reference to the contained object, importing if required.
+    #[inline]
+    pub fn get_bound<'py>(&self, py: Python<'py>) -> &Bound<'py, PyAny> {
+        self.get(py).bind(py)
+    }
+}
+
+pub mod imports {
+    use super::ImportOnceCell;
+
+    pub static NUMPY_COPY_ONLY_IF_NEEDED: ImportOnceCell =
+        ImportOnceCell::new("qiskit._numpy_compat", "COPY_ONLY_IF_NEEDED");
+    pub static NUMPY_ARRAY: ImportOnceCell = ImportOnceCell::new("numpy", "ndarray");
+    pub static DEEPCOPY: ImportOnceCell = ImportOnceCell::new("copy", "deepcopy");
+    pub static WARNINGS_WARN: ImportOnceCell = ImportOnceCell::new("warnings", "warn");
+    pub static BUILTIN_LIST: ImportOnceCell = ImportOnceCell::new("builtins", "list");
+    pub static BUILTIN_SET: ImportOnceCell = ImportOnceCell::new("builtins", "set");
+    pub static BUILTIN_RANGE: ImportOnceCell = ImportOnceCell::new("builtins", "range");
+    pub static BUILTIN_USER_WARNING: ImportOnceCell =
+        ImportOnceCell::new("builtins", "UserWarning");
+    pub static BUILTIN_HASH: ImportOnceCell = ImportOnceCell::new("builtins", "hash");
+    pub static UUID: ImportOnceCell = ImportOnceCell::new("uuid", "UUID");
+}
+
 /// A Python-space indexer for the standard `PySequence` type; a single integer or a slice.
 ///
 /// These come in as `isize`s from Python space, since Python typically allows negative indices.
