LightCone pass gives index errors unexpectedly

[caleb-johnson]

Environment

• Qiskit version: 2.1.2
• Python version: 3.12.9
• Operating system: macOS

What is happening?

I am trying to run the LightCone pass but am getting index errors once the initial lightcone grows to a certain size. Full traceback below:

PanicException                            Traceback (most recent call last)
Cell In[24], line 15
      6 indices = [0, 1, 2, 3, 4, 9, 10, 12, 13]
      7 pm = PassManager(
      8     [
      9         LightCone(
   (...)
     13     ]
     14 )
---> 15 reduced_circ = pm.run(qc)

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/passmanager.py:482](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/passmanager.py#line=481), in _replace_error.<locals>.wrapper(*meth_args, **meth_kwargs)
    479 @wraps(meth)
    480 def wrapper(*meth_args, **meth_kwargs):
    481     try:
--> 482         return meth(*meth_args, **meth_kwargs)
    483     except TranspilerError:
    484         # If it's already a `TranspilerError` subclass, don't erase the extra information.
    485         raise

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/passmanager.py:241](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/passmanager.py#line=240), in PassManager.run(self, circuits, output_name, callback, num_processes, property_set)
    238 if callback is not None:
    239     callback = _legacy_style_callback(callback)
--> 241 return super().run(
    242     in_programs=circuits,
    243     callback=callback,
    244     output_name=output_name,
    245     num_processes=num_processes,
    246     property_set=property_set,
    247 )

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/passmanager.py:238](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/passmanager.py#line=237), in BasePassManager.run(self, in_programs, callback, num_processes, property_set, **kwargs)
    234 # If we're not going to run in parallel, we want to avoid spending time `dill` serializing
    235 # ourselves, since that can be quite expensive.
    236 if len(in_programs) == 1 or not should_run_in_parallel(num_processes):
    237     out = [
--> 238         _run_workflow(
    239             program=program,
    240             pass_manager=self,
    241             callback=callback,
    242             initial_property_set=property_set,
    243             **kwargs,
    244         )
    245         for program in in_programs
    246     ]
    247     if len(in_programs) == 1 and not is_list:
    248         return out[0]

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/passmanager.py:310](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/passmanager.py#line=309), in _run_workflow(program, pass_manager, initial_property_set, **kwargs)
    303 passmanager_ir = pass_manager._passmanager_frontend(
    304     input_program=program,
    305     **kwargs,
    306 )
    307 property_set = (
    308     PropertySet() if initial_property_set is None else PropertySet(initial_property_set)
    309 )
--> 310 passmanager_ir, final_state = flow_controller.execute(
    311     passmanager_ir=passmanager_ir,
    312     state=PassManagerState(workflow_status=initial_status, property_set=property_set),
    313     callback=kwargs.get("callback", None),
    314 )
    315 # The `property_set` has historically been returned as a mutable attribute on `PassManager`
    316 # This makes us non-reentrant (though `PassManager` would be dependent on its internal tasks to
    317 # be re-entrant if that was required), but is consistent with previous interfaces.  We're still
    318 # safe to be called in a serial loop, again assuming internal tasks are re-runnable.  The
    319 # conversion to the backend language is also allowed to use the property set, so it must be set
    320 # before calling it.
    321 pass_manager.property_set = final_state.property_set

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/base_tasks.py:218](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/base_tasks.py#line=217), in BaseController.execute(self, passmanager_ir, state, callback)
    216     return passmanager_ir, state
    217 while True:
--> 218     passmanager_ir, state = next_task.execute(
    219         passmanager_ir=passmanager_ir,
    220         state=state,
    221         callback=callback,
    222     )
    223     try:
    224         # Sending the object through the generator implies the custom controllers
    225         # can always rely on the latest data to choose the next task to run.
    226         next_task = task_generator.send(state)

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/basepasses.py:167](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/basepasses.py#line=166), in TransformationPass.execute(self, passmanager_ir, state, callback)
    161 def execute(
    162     self,
    163     passmanager_ir: PassManagerIR,
    164     state: PassManagerState,
    165     callback: Callable = None,
    166 ) -> tuple[PassManagerIR, PassManagerState]:
--> 167     new_dag, state = super().execute(
    168         passmanager_ir=passmanager_ir,
    169         state=state,
    170         callback=callback,
    171     )
    173     if state.workflow_status.previous_run == RunState.SUCCESS:
    174         if not isinstance(new_dag, DAGCircuit):

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/base_tasks.py:98](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/passmanager/base_tasks.py#line=97), in GenericPass.execute(self, passmanager_ir, state, callback)
     96 try:
     97     if self not in state.workflow_status.completed_passes:
---> 98         ret = self.run(passmanager_ir)
     99         run_state = RunState.SUCCESS
    100     else:

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/passes/optimization/light_cone.py:121](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/transpiler/passes/optimization/light_cone.py#line=120), in LightCone.run(self, dag)
    114 if max_num_qubits > 10:
    115     warnings.warn(
    116         "LightCone pass is checking commutation of"
    117         f"operators of size {max_num_qubits}."
    118         "This operation can be slow.",
    119         category=RuntimeWarning,
    120     )
--> 121 commute_bool = scc.commute(
    122     op[0], op[1], [], node.op, node.qargs, [], max_num_qubits=max_num_qubits
    123 )
    124 if not commute_bool:
    125     # If the current node does not commute, update the light-cone
    126     lightcone_qubits.update(node.qargs)

File [~/venvs/blox/lib/python3.12/site-packages/qiskit/circuit/commutation_checker.py:101](http://localhost:8888/lab/workspaces/~/venvs/blox/lib/python3.12/site-packages/qiskit/circuit/commutation_checker.py#line=100), in CommutationChecker.commute(self, op1, qargs1, cargs1, op2, qargs2, cargs2, max_num_qubits, approximation_degree)
     69 def commute(
     70     self,
     71     op1: Operation,
   (...)
     78     approximation_degree: float = 1.0,
     79 ) -> bool:
     80     """
     81     Checks if two Operations commute. The return value of `True` means that the operations
     82     truly commute, and the return value of `False` means that either the operations do not
   (...)
     99         bool: whether two operations commute.
    100     """
--> 101     return self.cc.commute(
    102         op1, qargs1, cargs1, op2, qargs2, cargs2, max_num_qubits, approximation_degree
    103     )

PanicException: index out of bounds: the len is 26 but the index is 26

How can we reproduce the issue?

import numpy as np
from qiskit import QuantumCircuit
from qiskit.transpiler.passmanager import PassManager
from qiskit.transpiler.passes.optimization.light_cone import LightCone

qc = QuantumCircuit(18)
qc.rx(np.pi / 3, range(0, qc.num_qubits))
bit_terms = "ZZZZZZZZ"
indices = [0, 1, 2, 3, 4, 9, 10, 12]
pm = PassManager(
    [
        LightCone(
            bit_terms=bit_terms,
            indices=indices,
        )
    ]
)
reduced_circ = pm.run(qc)

The above runs succesfully. Adding an extra qubit (13), as in the snippet below, causes a failure.

import numpy as np
from qiskit import QuantumCircuit
from qiskit.transpiler.passmanager import PassManager
from qiskit.transpiler.passes.optimization.light_cone import LightCone

qc = QuantumCircuit(18)
qc.rx(np.pi / 3, range(0, qc.num_qubits))
bit_terms = "ZZZZZZZZZ"
indices = [0, 1, 2, 3, 4, 9, 10, 12, 13]
pm = PassManager(
    [
        LightCone(
            bit_terms=bit_terms,
            indices=indices,
        )
    ]
)
reduced_circ = pm.run(qc)

What should happen?

The pass should run without failure in both of the above cases

Any suggestions?

This happens on a larger qubit number for a non-trivial circuit, but it breaks given these same qubit id's in both the minimal snippet above and the non-trivial case in my workflow

[Cryoris]

Ugh that's again a limitation of the commutation checker which doesn't know how to handle the PauliGate graciously and tries to compute commutations via matrix multiplication. We have the same problem for PauliEvolutionGate, where the commutation could be checked efficiently but is not. We have ongoing work to re-write the commutation checker, but if that doesn't make 2.3 then we should at least hotfix this by treating these gates specially in the commutation checker.

[littlebullGit]

Analysis: Index out-of-bounds in unitary_compose.rs (issue #15021)

Summary

• The Rust einsum label generation in crates/quantum_info/src/unitary_compose.rs maps numeric axis IDs to ASCII letters using a 26-letter LOWERCASE array. For 9+ qubit compositions, the computed label ID exceeds 25, causing an index out-of-bounds panic.
• A second, dormant issue exists: _einsum_matmul_index contains an inverted assert and is not used on the failing path, so it doesn’t trigger today.

Reproduction

• The provided test creates two scenarios:
  • 8-qubit case: succeeds.
  • 9-qubit case: raises a panic/"index out of bounds".

This drives the path:

• compose(...) → _einsum_matmul(...) (not _einsum_matmul_index).

Root cause

Within _einsum_matmul, einsum labels are constructed like this:

let tensor_einsum = unsafe {
    String::from_utf8_unchecked(indices_tensor.iter().map(|c| LOWERCASE[*c]).collect())
};
let mat_einsum = unsafe {
    String::from_utf8_unchecked(indices_mat.iter().map(|c| LOWERCASE[*c]).collect())
};

Key facts:

• The per-qubit shaped “gate” tensor has rank rank = 2q for a q-qubit gate.
• For each contracted axis, the code remaps a position in indices_tensor to a fresh ID starting at rank:

for (j, index) in indices.iter().enumerate() {
    indices_tensor[index + shift] = rank + j;
}

• The largest label ID used is therefore max_id = rank + indices.len() - 1.
• In the failing test, q = 9 and indices.len() = 9 (one index per qubit), so:

rank = 2q = 18
max_id = 18 + 9 - 1 = 26

• The code then indexes LOWERCASE[max_id] where LOWERCASE has length 26 (a..z). Valid indices are 0..=25. Accessing index 26 panics.

Why 8 works, 9 fails:

• For q = 8, rank = 16, max_id = 16 + 8 - 1 = 23 → within 0..=25 → ok.
• For q = 9, max_id = 26 → out of bounds.

Note: from_utf8_unchecked is not the direct cause here (no invalid UTF-8), but the prior array indexing with LOWERCASE[*c] panics when *c >= 26.

Secondary (dormant) issue

There are helper functions that appear to intend a two-alphabet scheme:

• _einsum_matmul_helper and _einsum_matmul_index (which uses _UPPERCASE).
• _einsum_matmul_index starts with:

assert!(num_qubits > 26, "Can't compute unitary of > 26 qubits");

This condition is inverted. It would immediately panic for any num_qubits <= 26. However, these helpers are not referenced by the executed path—_einsum_matmul builds strings directly—so this bug is currently unused and does not cause the reported failure.

Possible solutions

1. Dual-alphabet mapping (minimal change)

• Map 0..=25 → a..z and 26..=51 → A..Z. Return a user-friendly error if an ID ≥ 52 is requested.
• Replace direct LOWERCASE[*c] indexing with a helper:

fn label_byte(i: usize) -> Result<u8, &'static str> {
    if i < 26 {
        Ok(LOWERCASE[i])
    } else if i < 52 {
        Ok(_UPPERCASE[i - 26])
    } else {
        Err("Too many einsum indices (exceeds 52 labels)")
    }
}

let tensor_einsum: String = indices_tensor
    .iter()
    .map(|&c| label_byte(c))
    .collect::<Result<Vec<u8>, _>>()?
    .into_iter()
    .map(|b| b as char)
    .collect();

let mat_einsum: String = indices_mat
    .iter()
    .map(|&c| label_byte(c))
    .collect::<Result<Vec<u8>, _>>()?
    .into_iter()
    .map(|b| b as char)
    .collect();

• Pros: Small fix, resolves the 9-qubit crash, supports up to 26 qubits of contraction (52 labels total).
• Cons: Still limited by alphabet size (fails > 52 distinct labels).

2. Fix the assert

• Fix _einsum_matmul_index assert to assert!(num_qubits <= 26, "Can't compute unitary of > 26 qubits")

3. Remove label limits entirely (long term fix - to be designed.)

4. Add graceful bounds checks

• Regardless of approach, validate the maximum label ID before mapping and return a descriptive Err(...) instead of panicking.

Proposal

• Short term: implement Dual-alphabet mapping to stop panics. This is the least intrusive fix for the current production path.
• Add graceful bounds checks
• Clean up: either remove _einsum_matmul_index/_einsum_matmul_helper as dead code or fix the assert if we intend to use them. They seems dead codes to me.

@Cryoris @caleb-johnson I plan to apply the above changes as a fix for this. Let me know what you think.

[Cryoris]

The suggestions just postpones the problem and doesn't fix it; we'll run into the same problem once the gate gets larger. The right way to fix this is to implement commutation checking for the PauliGate that is based on the Pauli representation of the gate.

[littlebullGit]

The suggestions just postpones the problem and doesn't fix it; we'll run into the same problem once the gate gets larger. The right way to fix this is to implement commutation checking for the PauliGate that is based on the Pauli representation of the gate.

Agree with your point. The fix I proposed is a temporary works around and will fail once the gate gets larger. I tried to use commutation but I cannot get it working. So if you still need the temporary work, let me know.

[debasmita2102]

Is someone working in this? otherwise can take it up and try to extend CommutationChecker after #15359 to support Pauli vs standard gates (RX to X-generator)

[Cryoris]

Sure go ahead @debasmita2102, note though that we probably only want to do the standard gate to generator (aka RX to X) mapping if checking commutation with a Pauli-based gate, not generally 🙂 In a follow up it would be interesting to investigate if we can generally use generators instead of the big lookup table we use now.