Transpiler

Ang function na generate_boxing_pass_manager() ay isang flexible at maginhawang tool para bumuo ng qiskit.transpiler.PassManager na kayang i-group ang mga circuit instruction sa mga annotated na box. Nagbibigay ito ng madaling alternatibo sa mano-manong pag-group at pag-annotate ng mga circuit, at kapaki-pakinabang sa pag-automate ng workflow, pagsubok ng iba't ibang estratehiya sa pag-box ng circuit, at iba pa.

Inilalarawan ng gabay na ito kung paano gamitin ang generate_boxing_pass_manager() at ang mga argument nito. Para i-highlight ang epekto ng bawat argument ng function, pangunahing tinutukoy ng mga sumusunod na seksyon ang circuit sa ibaba.

from qiskit.circuit import Parameter, QuantumCircuit

circuit = QuantumCircuit(4, 7)
circuit.h(1)
circuit.h(2)
circuit.cz(1, 2)
circuit.h(1)
circuit.cx(1, 0)
circuit.cx(2, 3)
circuit.measure(range(1, 4), range(3))
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
for qubit in range(4):
    circuit.rz(Parameter(f"th_{qubit}"), qubit)
    circuit.rx(Parameter(f"phi_{qubit}"), qubit)
    circuit.rz(Parameter(f"lam_{qubit}"), qubit)
circuit.measure(range(4), range(3, 7))

circuit.draw("mpl", scale=0.8)

I-group ang mga operasyon sa mga box

Ang argument na enable_gates ay maaaring itakda sa True o False para tukuyin kung dapat bang i-group sa mga box ang mga two-qubit gate. Gayundin, tinutukoy ng enable_measures kung dapat bang i-group ang mga measurement o hindi. Ipinapakita ng sumusunod na snippet ang isang halimbawa kung saan parehong naka-group ang mga gate at measurement.

from samplomatic.transpiler import generate_boxing_pass_manager

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=True,
)
transpiled_circuit = boxing_pass_manager.run(circuit)
transpiled_circuit.draw("mpl", scale=0.8)

Gaya ng makikita sa figure, gumagawa ang pass manager ng mga box na may dalawang uri: ang mga naglalaman ng iisang layer ng mga two-qubit gate, at ang mga naglalaman ng iisang layer ng mga measurement. Sinasalamin ng paghihiwalay na ito ang mga karaniwang gawi sa mga protocol ng noise learning at mitigation, na karaniwang tumatarget sa mga layer ng homogeneous na operasyon. Ang mga two-qubit gate at measurement ay inilalagay sa pinakakaliwang box na kayang tumanggap sa kanila, at bawat single-qubit gate ay inilalagay sa parehong box ng two-qubit gate o measurement na sinusundan nito.

Ipinapakita ng sumusunod na code ang isang halimbawa kung saan ang enable_gates ay nakatakda sa False. Gaya ng makikita, hindi naka-group sa mga box ang mga two-qubit gate, ni ang mga single-qubit gate na nauuna sa mga ito.

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=False,
    enable_measures=True,
)
transpiled_circuit = boxing_pass_manager.run(circuit)
transpiled_circuit.draw("mpl", scale=0.8)

Piliin kung paano i-annotate ang mga box

Lahat ng two-qubit gate at measurement box sa ibinalik na circuit ay may hawak na mga left-dressed na annotation. Sa partikular, lahat ng box na naglalaman ng mga two-qubit gate ay may annotation na Twirl. Para sa mga measurement box, maaaring pumili ang mga user sa pagitan ng Twirl, BasisTranform (na ang mode ay nakatakda sa "measure"), o pareho. Bumubuo ang sumusunod na code ng circuit kung saan lahat ng box ay naka-twirl, at ang mga measurement box ay dagdag na may annotation na BasisTranform.

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=True,
    measure_annotations="all",
)
transpiled_circuit = boxing_pass_manager.run(circuit)

Ihanda ang circuit para sa noise injection

Pinapayagan ka ng inject_noise_targets na tukuyin kung aling mga box ang dapat makatanggap ng annotation na InjectNoise. Halimbawa, bumubuo ang sumusunod na code ng circuit kung saan ang mga box ng two-qubit gate ay may hawak na annotation na InjectNoise pero ang mga measurement box ay wala.

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=True,
    inject_noise_targets="gates",
)
transpiled_circuit = boxing_pass_manager.run(circuit)

Kung ang isang circuit ay naglalaman ng dalawa o higit pang box na magkatumbas hanggang sa mga single-qubit gate, lahat ng mga ito ay ina-annotate ng annotation na InjectNoise na may parehong ref. Kaya, ang bilang ng mga natatanging ref sa ibinalik na circuit ay katumbas ng bilang ng mga natatanging box.

Ang value ng inject_noise_strategy ay may epekto sa mga annotation na InjectNoise. Posible ang mga sumusunod na value:

• modifier_ref='': Inirerekomenda kapag hindi mo kailangang baguhin ang mga noise map bago mag-sample mula sa mga ito.

• modifier_ref=ref: Inirerekomenda kapag kailangang i-scale nang pantay ang lahat ng noise map sa parehong factor.

• Isang natatanging value ng modifier_ref: Inirerekomenda kapag kailangang i-scale ang bawat noise map sa magkakaibang factor.

Bumubuo ang sumusunod na code ng circuit kung saan ang mga box ng two-qubit gate ay may hawak na annotation na InjectNoise na may mga natatanging value ng modifier_ref.

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=True,
    inject_noise_targets="gates",
    inject_noise_strategy="individual_modification",
)
transpiled_circuit = boxing_pass_manager.run(circuit)

Pumili ng twirling strategy

Nagsisimula ang boxing pass manager sa pagpili kung aling mga entangling gate at measurement instruction ang dapat lumitaw sa parehong mga box. Kapag nagawa na ito, sa pangkalahatan ay hindi full-width ang mga box—malamang na subset lang ng mga qubit na aktibo sa circuit o naroroon sa backend target ang laman ng mga ito. Sa karaniwang configuration ng boxing pass manager, dahil lahat ng qubit na inaaksyunan ng isang box instruction ay ti-nitwirl (kahit ang mga walang instruction sa loob ng box na umaaksyon sa kanila), naaapektuhan ng pagkakaroon ng partial-width na mga box ang mga noise-tailoring na epekto ng twirling. Ang mga idling na qubit ay hindi ti-nitwirl at maaaring, halimbawa, makaipon ng mga coherent error habang ina-apply ang box. Nagbibigay ang twirling_strategy ng mga opsyon para palawigin ang mga qubit na hawak ng bawat box, kaya binabago ang bilang ng mga idling na qubit:

• Ang "active" (default) ay hindi nagpapalawig ng mga box sa anumang idling na qubit.

• Pinapalawig ng "active_accum" ang lahat ng box sa mga qubit na naaksyunan na ng naunang instruction sa circuit. Kapaki-pakinabang ito kung gusto mong iwan ang mga qubit sa simula ng circuit sa kanilang ground state hangga't maaari sa pamamagitan ng hindi pag-twirl sa mga ito hanggang maging aktibo ang mga ito.

• Pinapalawig ng "active_circuit" ang lahat ng box sa mga qubit na inaaksyunan ng anumang instruction sa circuit. Kapaki-pakinabang ito kung mayroon kang structured na circuit na may paulit-ulit na entangling layer at gusto mong bawasan ang bilang ng mga natatanging box dahil kailangang matutunan ang noise ng bawat isa.

• Pinapalawig ng "all" ang lahat ng box sa lahat ng qubit sa lahat ng quantum register ng circuit. Kapaki-pakinabang ito bilang extension ng "active_circuit" kung gusto mong laging ma-twirl ang lahat ng qubit sa QPU.

Sa sumusunod na halimbawa, ina-apply ang bawat estratehiya sa base circuit, pagkatapos ay iginuguhit ang mga resulta.

circuit = QuantumCircuit(5, 2)
circuit.h(range(4))
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
circuit.cx(0, 1)
circuit.cx(1, 2)
circuit.cx(2, 3)
circuit.barrier()
circuit.h(range(4))
circuit.measure([1, 2], [0, 1])

circuit.draw("mpl", scale=0.6)

import matplotlib.pyplot as plt

plt.figure(figsize=(9, 6))
for idx, strategy in enumerate(["active", "active_accum", "active_circuit", "all"]):
    ax = plt.subplot(2, 2, idx + 1)
    pm = generate_boxing_pass_manager(twirling_strategy=strategy, remove_barriers="never")
    transpiled_circuit = pm.run(circuit)
    fig = transpiled_circuit.draw("mpl", scale=0.8, ax=ax)
    ax.set_title(f"twirling_strategy='{strategy}'")

plt.tight_layout()

Tukuyin kung paano tratuhin ang mga barrier

Bilang default, inaalis ang mga barrier sa circuit pagkatapos mai-box ang lahat ng entangling gate at measurement instruction ayon sa tagubilin, kasama ang mga extension ng mga ito dahil sa napiling twirling_strategy, pero bago idagdag ang mga single-qubit gate sa box na agad nasa kanan ng mga ito, kung posible.

Halimbawa, ang sumusunod na circuit ay naglalaman ng isang barrier:

circuit_with_barrier = QuantumCircuit(4)
circuit_with_barrier.h(range(4))
circuit_with_barrier.cz(0, 1)
circuit_with_barrier.barrier()
circuit_with_barrier.cz(2, 3)
circuit_with_barrier.measure_all()

circuit_with_barrier.draw("mpl", scale=0.8)

Pinipigilan ng default na gawi na mapunta sa parehong box ang dalawang entangling gate, bagama't hinahayaan nitong masipsip ang mga single-qubit gate sa susunod na available na box sa kabila ng barrier.

boxing_pass_manager = generate_boxing_pass_manager()
transpiled_circuit = boxing_pass_manager.run(circuit_with_barrier)
transpiled_circuit.draw("mpl", scale=0.8)

Ang pagtatakda ng remove_barriers sa 'never' ay pinapanatili ang mga barrier kaya nalilimitahan ang mga single-qubit gate.

boxing_pass_manager = generate_boxing_pass_manager(remove_barriers="never")

transpiled_circuit = boxing_pass_manager.run(circuit_with_barrier)
transpiled_circuit.draw("mpl", scale=0.8)

Sa wakas, kung agad na aalisin ang mga barrier, hindi na limitado ang mga entangler na mapunta sa magkakahiwalay na box.

boxing_pass_manager = generate_boxing_pass_manager(remove_barriers="immediately")

transpiled_circuit = boxing_pass_manager.run(circuit_with_barrier)
transpiled_circuit.draw("mpl", scale=0.8)

Paano gumagana ang stratification

Nagpapatakbo ang boxing pass manager ng dalawang pangunahing pass nang sunud-sunod:

1. GroupGatesIntoBoxes — Ini-stratify ang mga entangling gate sa mga box. Hindi pinapansin ang mga single-qubit gate sa yugtong ito; mga two-qubit gate lang ang ig-ni-group.

2. AbsorbSingleQubitGates — Sinisipsip ang bawat single-qubit gate sa pinakamalapit na karapat-dapat na box sa kanan nito.

Sa stratification, tinatahak ng GroupGatesIntoBoxes ang circuit DAG sa topological order at inilalagay ang bawat two-qubit gate sa pinakamaagang group na ang mga qubit ay hindi pa okupado. Tatlong uri ng instruction ang kumikilos bilang mga delimiter na nag-fflush ng kasalukuyang group para sa mga qubit nila, na nagtutulak sa mga susunod na gate sa mga qubit na iyon sa bagong group:

• Mga Barrier

• Mga umiiral na box instruction

• Measurements

Ang mga single-qubit gate ay hindi mga delimiter — wala silang epekto sa grouping at iniiwan para hawakan ng AbsorbSingleQubitGates. Sa kasalukuyan, walang commutativity analysis na isinasagawa; sinusunod ng grouping ang topological order ng circuit kung ano ito.

Bakit ang remove_barriers="after_stratification" ang inirerekomendang default

Ang default na mode ay "after_stratification" dahil pinagsasama nito ang dalawang benepisyo:

• Nililimitahan ng mga barrier kung paano ig-ni-group ang mga entangling gate (kumikilos sila bilang mga delimiter habang stratification).

• Inaalis ang mga barrier bago tumakbo ang AbsorbSingleQubitGates, kaya ang mga single-qubit gate ay nakakadaan pa rin sa mga dating posisyon ng barrier at nasisipsip sa pinakamalapit na box.

Sa kabilang banda:

• Pinapanatili ng "never" ang mga barrier sa buong proseso, na nagkukulong sa mga single-qubit gate sa pagitan ng barrier at box, kaya napipigilan ang pagsipsip sa mga ito at naiiwan ang mga untwirled na rotation sa circuit.

• Inaalis ng "immediately" ang mga barrier bago ang stratification, kaya wala silang epekto sa grouping.

• Kapaki-pakinabang ang "finally" kapag gusto mo ng mga barrier sa output circuit (halimbawa, para sa visualization), pero hindi nasisipsip ang mga single-qubit gate sa pagitan ng barrier at box.

I-box ang mga ISA circuit gamit ang mga barrier

Ang mga circuit na may paulit-ulit na istruktura — gaya ng mga Trotterized Hamiltonian simulation, variational ansatze, at error amplification sequence — ay karaniwang binubuo sa pamamagitan ng code at saka ni-transpile sa ISA form. Nakakapagod ang manu-manong pagdaragdag ng mga box sa isang na-transpile na circuit, kaya ang natural na workflow ay ang sumusunod:

1. Buuin ang logical circuit, at maglagay ng mga barrier sa mga hangganan ng layer na gusto mong maging hangganan ng box.

2. I-transpile sa mga ISA circuit. Pinapanatili ng transpiler ng Qiskit ang mga barrier sa routing at optimization.

3. Patakbuhin ang generate_boxing_pass_manager() sa ISA circuit.

Kailangan ang mga barrier kapag hindi sakop ng dulo ng isang layer ang lahat ng qubit. Kung wala ito, ilalagay ng greedy algorithm sa iisang grupo ang mga gate mula sa susunod na layer—sa mga "libreng" qubit na iyon. Bilang konkretong halimbawa, isaalang-alang ang dalawang-hakbang na Heisenberg ZZ simulation sa isang 5-qubit na ring. Bawat Trotter step ay may tatlong bond layer: ang even bond (0,1), (2,3), ang odd bond (1,2), (3,4), at ang wrap bond (4,0). Pagkatapos ng odd-bond layer, parehong libre ang qubit 0 at 4. Kung walang barrier, ang wrap bond (4,0) ay ma-greedy-group kasama ng mga bond mula sa susunod na Trotter step na gumagamit ng mga libreng qubit na iyon, kaya nagkakahalo sa iisang box ang mga gate mula sa magkakaibang step.

from qiskit.circuit import Parameter, QuantumCircuit

n = 5  # 5-qubit ring: bonds (0,1), (1,2), (2,3), (3,4), (4,0)
dt = Parameter("dt")
heisenberg = QuantumCircuit(n)

for step in range(2):
    # Layer 1: even bonds (0,1) and (2,3)
    for idx in range(0, n - 1, 2):
        heisenberg.rzz(dt, idx, idx + 1)
    heisenberg.barrier()
    # Layer 2: odd bonds (1,2) and (3,4) -- qubits 0 and 4 are now free
    for idx in range(1, n - 1, 2):
        heisenberg.rzz(dt, idx, idx + 1)
    heisenberg.barrier()
    # Layer 3: wrap bond (4,0) -- both qubits were free after layer 2
    heisenberg.rzz(dt, n - 1, 0)
    if step < 1:
        heisenberg.barrier()  # separates the two Trotter steps

heisenberg.measure_all()

heisenberg.draw("mpl", scale=0.7)

Ang sumusunod na code ay nagta-transpile ng circuit sa ISA form, sa pag-aakalang CX ang native entangler ng pinagbabatayang device. Pansinin na nananatili ang mga barrier pagkatapos ng transpilation at makikita pa rin sa output circuit.

from qiskit.transpiler import generate_preset_pass_manager

preset_pm = generate_preset_pass_manager(
    basis_gates=["rz", "sx", "cx"],
    coupling_map=[[0, 1], [1, 2], [2, 3], [3, 4], [4, 0]],
    optimization_level=1,
)
isa_circuit = preset_pm.run(heisenberg)
isa_circuit.draw("mpl", scale=0.5, fold=200)

Susunod, ilapat ang boxing pass manager sa ISA circuit. Ang bawat isa sa tatlong bond layer ay nagiging hiwalay na box sa bawat Trotter step.

boxing_pm = generate_boxing_pass_manager()
boxed_isa = boxing_pm.run(isa_circuit)
boxed_isa.draw("mpl", scale=0.5, fold=100)

Isama ang pass manager ng Samplomatic sa mga preset pass manager ng Qiskit

Ipinapakita ng code sa ibaba kung paano isama ang generate_boxing_pass_manager() sa isang preset pass manager ng Qiskit. Ang na-transpile na circuit ay ISA at may mga box.

from qiskit.transpiler import generate_preset_pass_manager

preset_pass_manager = generate_preset_pass_manager(
    basis_gates=["rz", "sx", "cx"],
    coupling_map=[[0, 1], [1, 2]],
    optimization_level=0,
)
boxing_pass_manager = generate_boxing_pass_manager()

# Run the boxing pass manager after the scheduling stage
preset_pass_manager.post_scheduling = boxing_pass_manager

circuit = QuantumCircuit(3)
circuit.h(0)
circuit.cx(0, 1)
circuit.cx(0, 2)
circuit.measure_all()

transpiled_circuit = preset_pass_manager.run(circuit)
transpiled_circuit.draw("mpl", scale=0.8)

Natural ding naisasama ang pattern na ito sa barrier-based na ISA boxing workflow. Tumatakbo ang boxing pass manager bilang post-scheduling step, matapos manatili ang mga barrier mula sa orihinal na logical circuit sa transpilation, kaya ginagabayan nito ang stratification gaya ng inaasahan.

preset_pm = generate_preset_pass_manager(
    basis_gates=["rz", "sx", "cx"],
    coupling_map=[[0, 1], [1, 2], [2, 3], [3, 4], [4, 0]],
    optimization_level=1,
)
preset_pm.post_scheduling = generate_boxing_pass_manager()

boxed_heisenberg = preset_pm.run(heisenberg)
boxed_heisenberg.draw("mpl", scale=0.5, fold=100)

Suriin at baguhin ang mga annotation

Pagkatapos ng auto-boxing, maaaring gusto mong suriin ang mga annotation sa mga partikular na box o ayusin ang mga ito. Halimbawa, para magdagdag ng noise injection, magtanggal ng mga annotation, o magpalit ng twirling group. Nagbibigay ang Samplomatic ng isang set ng mga utility function sa samplomatic.utils para sa layuning ito. Lahat ng mga ito ay nagbabalik ng bagong circuit nang hindi binabago ang orihinal.

Ang extend_annotations() ay nagdaragdag ng isa o higit pang annotation sa bawat box sa circuit.

from samplomatic import InjectNoise, Twirl
from samplomatic.utils import extend_annotations

boxed = generate_boxing_pass_manager().run(circuit_with_barrier)

# Add InjectNoise to every box
with_noise = extend_annotations(boxed, InjectNoise("my_noise_ref"))
with_noise.draw("mpl", scale=0.8)

Ang filter_annotations() ay nag-iiwan lamang ng mga annotation ng mga tinukoy na uri at inaalis ang iba. Ang replace_annotations() ay naglalapat ng isang callable sa bawat annotation; ang callable ay nagbabalik ng listahan ng mga annotation na ipapalit (magbalik ng [] para alisin, isang list na may iisang elemento para palitan, o isang list na may maraming elemento para palawakin).

from samplomatic.utils import filter_annotations, replace_annotations

# Keep only Twirl annotations, drop everything else
twirl_only = filter_annotations(with_noise, Twirl)

# Replace the twirling group on every Twirl annotation
updated = replace_annotations(
    twirl_only, lambda a: [Twirl(group="local_c1")] if isinstance(a, Twirl) else [a]
)

Ang pangkalahatang-gamit na function na map_annotations() ay tumatanggap ng anumang callable na nagmamapa ng listahan ng mga annotation sa bagong listahan, kaya may buo kang kontrol sa mga transformation kada box. Ang strip_annotations() ay isang convenience wrapper na nag-aalis ng lahat ng annotation mula sa bawat box.

Para sa mga bulk na pagbabago tulad ng pagdaragdag ng InjectNoise sa lahat ng gate box, ang parameter na inject_noise_targets ng generate_boxing_pass_manager() ang pinakamaikling opsyon. Kapaki-pakinabang ang mga utility na ito para sa mga piling pag-edit kada box na hindi sakop ng mga parameter ng pass manager.

Bumuo ng circuit

Ang bawat pass manager na nilikha ng generate_boxing_pass_manager() ay nagbabalik ng mga circuit na matagumpay na magagawang template/samplex pair ng build(). Halimbawa, tinatawag ng sumusunod na code ang function na build() sa isang circuit na nilikha ng boxing pass manager.

from samplomatic import build

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=True,
)
transpiled_circuit = boxing_pass_manager.run(circuit)

template, samplex = build(transpiled_circuit)

Upang matiyak na matagumpay na mabubuo ang anumang na-transpile na circuit, alam ng mga pass manager kung paano magsama ng karagdagang mga box kapag kailangan ang mga ito. Halimbawa, isaalang-alang ang circuit sa ibaba, na nagtatapos sa isang hindi na-measure na qubit 0.

circuit_with_unmeasured_qubit = QuantumCircuit(4, 3)
circuit_with_unmeasured_qubit.cz(0, 1)
circuit_with_unmeasured_qubit.cz(2, 3)
for qubit in range(4):
    circuit_with_unmeasured_qubit.rz(Parameter(f"th_{qubit}"), qubit)
    circuit_with_unmeasured_qubit.rx(Parameter(f"phi_{qubit}"), qubit)
    circuit_with_unmeasured_qubit.rz(Parameter(f"lam_{qubit}"), qubit)
circuit_with_unmeasured_qubit.measure(range(1, 4), range(3))

circuit_with_unmeasured_qubit.draw("mpl", scale=0.8)

Ang pagguhit ng mga left-dressed box sa paligid ng mga gate at measurement ay magreresulta sa circuit na may mga hindi nakolektang virtual gate sa qubit 0, at ang pagtawag sa build() sa circuit na ito ay magreresulta sa error. Para maiwasan ito, ang mga pass manager na ibinabalik ng generate_boxing_pass_manager() ay maaaring magdagdag ng mga right-dressed box na magsisilbing collector. Halimbawa, sa sumusunod na code, ang qubit 0 ay tinatapos ng isang right-dressed box na kumukuha ng hindi nakolektang virtual gate. Inilalagay rin sa loob ng box ang mga single-qubit gate na kumikilos sa qubit 0 para mabawasan ang depth ng resultang circuit.

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=True,
)
transpiled_circuit = boxing_pass_manager.run(circuit_with_unmeasured_qubit)
transpiled_circuit.draw("mpl", scale=0.8)

Sa isa pang halimbawa, nagdaragdag ng right-dressed box para kolektahin ang mga virtual gate na maiiwang hindi nakolekta dahil sa mga hindi na-box na measurement.

boxing_pass_manager = generate_boxing_pass_manager(
    enable_gates=True,
    enable_measures=False,
)
transpiled_circuit = boxing_pass_manager.run(circuit_with_unmeasured_qubit)
transpiled_circuit.draw("mpl", scale=0.8)