RelabelModes

class RelabelModes(permutation=None, *, solver=None, **kwargs)

Bases: GenericPass[DAGCircuit, DAGCircuit]

A transpilation pass to relabel the fermionic modes.

This pass reorders the fermionic modes of a circuit. The reordering is described by a permutation list, read as a mapping from original to new mode index: original mode i is placed at new index permutation[i] in the relabeled circuit. For example, permutation = [0, 2, 4, 1, 3, 5] places original mode 1 at new index 2, original mode 2 at new index 4, and so on. Being a permutation, each index must appear exactly once.

Post-processing

The relabeling reorders the fermionic modes, which in turn influences the fermion-to-qubit mapping chosen by a later synthesis stage (and thus the achievable circuit depth). How much work that costs you when interpreting sampled bitstrings depends on where you add the measurements.

The simplest option is to measure on the FermionicCircuit, with FermionicCircuit.measure_all(), before transpiling. Each measurement then names the mode it reads and the classical bit it writes into, and both travel through this pass together: the mode is relabeled, the classical bit is not. The sampled bitstring is therefore indexed by the original mode and needs no post-processing at all:

>>> from qiskit.passmanager import MultiStagePassManager
>>> from qiskit.providers.basic_provider import BasicSimulator
>>> from qiskit_fermions.circuit import FermionicCircuit
>>> from qiskit_fermions.circuit.library import InitializeModes
>>> from qiskit_fermions.transpiler import FermionicCircuitToDAG, QuantumDAGToCircuit
>>> from qiskit_fermions.transpiler.passes import (
...     F2QSynthesis, F2QSynthesisPluginManager, RelabelModes, TrivialF2QLayout,
... )
>>>
>>> # blocked occupation: spin-up orbitals 0 and 1 and spin-down orbital 0 are occupied
>>> circ = FermionicCircuit(6)
>>> circ.append(InitializeModes([1, 1, 0, 1, 0, 0]), circ.modes)
>>> circ.barrier()
>>> circ.measure_all()  # measure the *fermionic* circuit
>>>
>>> synth_plugins = F2QSynthesisPluginManager()
>>> synth = F2QSynthesis()
>>> synth.methods["InitializeModes"] = synth_plugins.method("InitializeModes", "TrivialOccupation")()
>>> synth.methods["FermionicMeasure"] = synth_plugins.method("FermionicMeasure", "TrivialOccupation")()
>>>
>>> pm = MultiStagePassManager(
...     init=FermionicCircuitToDAG(),
...     optimization=RelabelModes(permutation=[0, 2, 4, 1, 3, 5]),
...     layout=TrivialF2QLayout(),
...     synthesis=synth,
...     output=QuantumDAGToCircuit(),
... )
>>>
>>> qcirc = pm.run(circ)
>>>
>>> counts = BasicSimulator().run(qcirc, shots=1).result().get_counts()
>>> print(counts)  # already in the original blocked ordering
{'001011': 1}

Drawing the two circuits side by side shows what travelled and what did not. The fermionic measurements read modes 0..5 in order; after synthesis they sit on permuted qubits, yet each one still writes into the classical bit of the mode it measures, so the meas labels remain in the original order:

Measuring the transpiled QuantumCircuit instead leaves you to undo the relabeling yourself, because those measurements were never part of the fermionic circuit and so know nothing about it. The relabeling that was actually applied is recorded in a permutation field of the returned FermionicDAGCircuit’s metadata.

Conceptually, undoing the relabeling assigns to each original mode m the value that was measured for new mode permutation[m]. In practice this is complicated by the fact that FermionicRegister modes and Qiskit’s classical bits run in opposite (little-endian) order, so the mode-space gather turns into an index negation (~idx) followed by a final reversal ([::-1]) on the counts bitstrings.

The example below repeats the six-mode relabeling above, from a blocked spin ordering ([u0, u1, u2, d0, d1, d2]) to an interleaved one ([u0, d0, u1, d1, u2, d2]) as a common trick to reduce the implementation depth, but measures after transpilation, and so has to undo the relabeling on the sampled counts:

>>> from qiskit.passmanager import MultiStagePassManager
>>> from qiskit.providers.basic_provider import BasicSimulator
>>> from qiskit_fermions.circuit import FermionicCircuit
>>> from qiskit_fermions.circuit.library import InitializeModes
>>> from qiskit_fermions.transpiler import FermionicCircuitToDAG, QuantumDAGToCircuit
>>> from qiskit_fermions.transpiler.passes import (
...     F2QSynthesis, F2QSynthesisPluginManager, RelabelModes, TrivialF2QLayout,
... )
>>>
>>> # blocked occupation: spin-up orbitals 0 and 1 and spin-down orbital 0 are occupied
>>> circ = FermionicCircuit(6)
>>> circ.append(InitializeModes([1, 1, 0, 1, 0, 0]), circ.modes)
>>>
>>> synth_plugins = F2QSynthesisPluginManager()
>>> synth = F2QSynthesis()
>>> synth.methods["InitializeModes"] = synth_plugins.method("InitializeModes", "TrivialOccupation")()
>>>
>>> # map blocked mode order onto the interleaved one
>>> relabel = RelabelModes(permutation=[0, 2, 4, 1, 3, 5])
>>>
>>> pm = MultiStagePassManager(
...     init=FermionicCircuitToDAG(),
...     optimization=relabel,
...     layout=TrivialF2QLayout(),
...     synthesis=synth,
...     output=QuantumDAGToCircuit(),
... )
>>>
>>> qcirc = pm.run(circ)
>>> qcirc.measure_all()
>>>
>>> bit_permutation = qcirc.metadata.get("permutation")
>>> print(bit_permutation)
[0, 2, 4, 1, 3, 5]
>>>
>>> res = BasicSimulator().run(qcirc, shots=1).result()
>>> counts = res.get_counts()
>>> print(counts)  # measured in the interleaved ordering
{'000111': 1}
>>>
>>> # undo the relabeling to recover the counts in the original blocked ordering
>>> post_processed = {
...     "".join(bitstring[~idx] for idx in bit_permutation)[::-1]: count
...     for bitstring, count in counts.items()
... }
>>> print(post_processed)  # recovered in the original blocked ordering
{'001011': 1}

Initializing this transpiler pass can be done with the arguments listed below.

Parameters

• permutation (list[int] | None) – the index permutation used to relabel the fermionic mode indices. When this is None, a permutation will be determined automatically based on build_excitation_span_minimization_model(). See also permutation for more details.
• solver (pyomo.opt.SolverFactory | None) – the optimization problem solver instance used to solve the build_excitation_span_minimization_model() problem. When this is None, no permutation can be determined automatically. See also solver for more details.
• kwargs – any additional keyword arguments will be forward to build_excitation_span_minimization_model().

Attributes

permutation

solver

Methods

find_permutation

run

Inherited Methods

execute

name

update_status