Breaking change (two_qubit_decompose.trace_to_fid)

[frankharkins]

Environment

• Qiskit version: 1.3.0
• Python version: 3.11
• Operating system: Ubuntu

What is happening?

It appears two_qubit_decompose.trace_to_fid was removed in #13093. I discovered this in when running our docs notebooks with 1.3.0: https://github.com/Qiskit/documentation/actions/runs/12119882758/job/33788219418

ImportError                               Traceback (most recent call last)
Cell In[7], line 2
      1 import numpy as np
----> 2 from qiskit.synthesis.two_qubit.two_qubit_decompose import trace_to_fid
      4 # Reduce circuits down to 2 qubits so they are easy to simulate
      5 qc_t3_exact_small = QuantumCircuit.from_instructions(qc_t3_exact)
ImportError: cannot import name 'trace_to_fid' from 'qiskit.synthesis.two_qubit.two_qubit_decompose'

How can we reproduce the issue?

Run the following line:

from qiskit.synthesis.two_qubit.two_qubit_decompose import trace_to_fid

What should happen?

Function should import

Any suggestions?

The function is small enough you could probably just add it back with a deprecation notice.

[jakelishman]

That import path certainly doesn't look like it would have been part of the public interface - what notebook is this that's using that import?

[jakelishman]

I don't see that function documented anywhere, so it wasn't public. I think whatever notebook it is is likely mistaken for having used some internal detail of a 2q-specific synthesis algorithm, but it should be an easy fix, and it might not be a big deal for the notebook to include the actual code of that function rather than hide it - it's just

def fidelity_from_trace_2q(trace: float) -> float:
    return (4.0 + trace * trace.conjugate()) / 20.0

and it's specific to 2q gates, so the name trace_to_fid is a bit misleading out of context.

I think the general form is

def fidelity_from_trace(num_qubits: int, trace: float) -> float:
    dim = 2 ** num_qubits
    return (dim + trace * trace.conjugate()) / (dim * (dim + 1))

---

Fwiw, it probably wouldn't hurt for us to have neater exposure of some useful synthesis utilities and have a proper API around re-usable synthesis components, so people can build up their own, rather than only getting fully packaged syntheses from us, but (especially as the fully packaged things move to Rust) that's something that should probably be handled a bit more top-down than exposing random little things four packages deep in the file organisation.

[mtreinish]

Right, that function was never documented and not considered part of the public API. It was internal utility function designed specifically for use in the the two qubit weyl decomposition and its derivatives in that module. When we rewrote the synthesis path in rust nothing was using that private python function anymore so we removed it. The way that notebook in question is using it the better public API alternative you should probably be using is: qiskit.quantum_info.average_gate_fidelity https://docs.quantum.ibm.com/api/qiskit/quantum_info#average_gate_fidelity

[frankharkins]

Ok that's good to know, thanks both.