Özel pass — transpiler zincirine kendi dönüşüm veya analiz adımınızı eklemek

Preset transpile yolu çoğu uygulamayı karşılar; özel pass ihtiyacı genelde şu durumlarda doğar: hedefe özgü bir henüz kütüphanede olmayan sadeleştirme, yayın öncesi zorunlu bir doğrulama veya metrik toplama, A/B deneyinde yalnızca tek bir geçişi değiştirme veya üniversite araştırması için yeni bir derleme fikrini deneme. Özel pass, transpiler'ı genişletmenin en güçlü ve en riskli yoludur: doğru yazıldığında verim kazandırır; hatalı yazıldığında sessizce yanlış devre üretir.

Bu sayfanın sınırı

Dahili IBM pass isimleri veya sürüme özgü dahili sınıflar burada kataloglanmaz; resmi belge ve kaynak kod tek doğru liste olarak kalır. Yürütücü ve zincir disiplini pass manager başlığında; evre sırası transpiler pipeline sayfasında özetlenir.

Önce preset mi, önce özel mi?

Çoğu ekip önce preset ile sonuç alır, ardından ihtiyaç duyulan dar düzeltmeyi özel pass ile ekler. Sıfırdan pass listesi yazmak, aynı preset'i yeniden keşfetme riskini taşır; bu yüzden ekleme deseni önerilir.

Dönüşüm pass'i, çıktı devresinin matematiksel olarak (veya hedefin kabul ettiği anlamda) girdiyle eşdeğer kalmasını sağlamalıdır; aksi hâlde derleyici hatalıdır. Pratikte bu, DAG üzerinde izin verilen yerel dönüşümlerin birleşiminin tüm devre için güvenli olduğunun ispatına indirgenir. Ayrıca pass, yalnızca DAG'ın tutarlılık kurallarına uygun biçimde düğüm ekleyip çıkarmalı; yarım bırakılmış bir düzenleme sonraki pass'leri kilitler veya çökertir.

Bariyer ve klasik kontrol

Özel pass, bariyer veya ölçüm düğümlerini kaydırmadan önce semantiği bariyer ve akış kontrolü ile ölçüm mantığı üzerinden düşünmelidir; aksi hâlde doğru sayılan bir yerel eşdeğerlik, global akışta hatalı olur.

İnceleme listesi

Yayın öncesi: küçük devrelerde birim test, orta boyda altın çıktı kıyası, büyük devrede rastgele farklılık testi ve en az bir donanım veya fake hedef üzerinde uçtan uca koşu.

Analiz pass DAG'ı değiştirmeden okur ve sonuçları paylaşılan duruma yazar; dönüşüm pass ise DAG'ı değiştirir. Özel pass yazarken hangi aileye ait olduğunuzu açıkça seçin; aksi hâlde pass manager yanlış optimizasyon varsayımları uygulayabilir. Çoğu öğretici örnek dönüşüm sınıfından türetilir; analiz pass'leri ise telemetri ve karar verme için kullanılır.

PropertySet alanları

Analiz çıktıları ve bazı ara durumlar property_set üzerinden taşınır; anahtar adları sürüme göre değişebilir. Özel pass'leriniz mümkünse kendi ad alanınızı (örneğin myproj_*) kullanarak çakışmayı azaltır. İletişim modeli pass manager · PropertySet bölümüyle uyumludur.

Performans

DAG üzerinde naif tarama büyük devrelerde maliyetli olur; mümkünse yerel pencerede çalışın veya mevcut analiz pass'lerinin sonuçlarını yeniden kullanın.

Özel pass'ler çoğu zaman PassManager örneğine append ile eklenir; sıra, önce hangi analizin doldurulacağını ve sonra hangi dönüşümün uygulanacağını belirler. Zincirin sonunda devre tekrar QuantumCircuit'e dönüştürülür. Sıra hatası, önceki bölümde anlatılan property eksikliği veya denklik bozulması olarak geri döner.

Koşullu dallanma

Bazı projelerde “eğer şu metrik eşiği aşıldıysa şu pass'i çalıştır” deseni kullanılır; bu, FlowController benzeri yapılarla kurulur. Ayrıntı sürüme bağlıdır; resmi örnekleri referans alın.

Yineleme ve sabit nokta

Özel pass'iniz birden çok tur gerektiriyorsa, üst sınır koyun ve sonsuz döngüyü ölçün; aksi hâlde CI'da takılı kalır.

İki yaygın desen vardır: (A) preset pass manager oluşturulup bazı sürümlerde sonuna özel pass eklenir; (B) önce transpile veya preset run ile standart çıktı alınır, ardından ikinci bir PassManager yalnızca özel adımları uygular. Staged veya iç içe yapılar sürüme göre append davranışını kısıtlayabilir; bu yüzden (B) deseni taşınabilirlik açısından sıkça seçilir.

optimization_level ile etkileşim

Preset seviyesi değiştikçe özel pass'inizin önünde veya arkasında çalışan pass'ler değişir; bu yüzden özel pass'i tek bir seviyeye kilitlerseniz yükseltmede sürpriz yaşanır. Seviye matrisi optimization seviyeleri sayfasında özetlenir.

Zamanlama ve süre alanları

Özel pass DAG'ı değiştirdikten sonra süre etiketleri geçersiz kalabilir; gerekirse sonraki aşamada zamanlama pass'lerinin yeniden çalışmasını planlayın. Zamanlama semantiği zamanlama sayfasında işlenir.

Özel pass için en az üç katmanlı test önerilir: (1) birim düzeyinde küçük DAG'lerde beklenen özellikler, (2) birkaç gerçekçi devrede önceki transpile çıktısıyla sayım ve derinlik kıyası, (3) rastgele küçük devrelerde unitary simülasyonu veya fidelity (kuantum doğruluğu) kontrolü mümkünse. Altın dosyaları sürüm yükseltmesinde güncellenmeli; aksi hâlde doğru değişiklikler testte hata gibi görünür.

Regresyon sinyali

SWAP sayısı, iki-qubit sayısı ve toplam süre (dt) birlikte izlenmelidir; tek metrik yanıltır. Bu ölçütler SWAP ekleme ve yönlendirme sayfalarıyla örtüşür.

Kod incelemesi

Özel pass değişiklikleri mutlaka kuantum bilgisi olan bir gözden geçirici gerektirir; yalnızca yazılım incelemesi yetmez.

Qiskit sürüm yükseltmeleri DAG API'si, pass taban sınıfları ve import yollarını değiştirebilir. Üretim projelerinde özel pass modülü, kütüphane sürümü ile birlikte kilitlenmeli; yükseltme planı “önce test suite, sonra sahaya” sırasıyla yürütülmelidir. Açık kaynak kütüphaneye katkı düşünülüyorsa, genel kullanıcı için stabil bir arayüz tasarlamak gerekir.

İçe aktarma yolları

qiskit.transpiler altındaki alt modül taşınmaları sık görülür; import'ları tek dosyada toplayıp sürüm dalı açmak taşınabilirliği artırır.

Dokümantasyon

Her özel pass için kısa bir tasarım notu: amaç, önkoşul pass'ler, üretilen veya okunan property anahtarları, bilinen sınırlar.

Aşağıdaki örnekler sürümler arasında ince fark gösterebilir; TransformationPass taban sınıfı ve import yolunu resmi belgeyle doğrulayın. İlk blok yalnızca property_set işaretleyen minimal dönüşüm; ikinci blok preset sonrası ikinci aşamalı yöneticidir; üçüncü blok aynı işaretin okunmasını gösterir.

from qiskit import QuantumCircuit
from qiskit.transpiler import PassManager
from qiskit.transpiler.basepasses import TransformationPass

class MarkPass(TransformationPass):
    """DAG'ı değiştirmeden property_set'e işaret yazar (örnek)."""

    def run(self, dag):
        self.property_set["myproj_mark"] = True
        return dag

qc = QuantumCircuit(1)
qc.h(0)

pm = PassManager()
pm.append(MarkPass())
out = pm.run(qc)

ps = getattr(pm, "property_set", {})
print("işaretlendi mi:", ps.get("myproj_mark"))
print(out)

from qiskit import QuantumCircuit, transpile
from qiskit.transpiler import PassManager
from qiskit.transpiler.basepasses import TransformationPass
from qiskit_ibm_runtime.fake_provider import FakeManilaV2

class MarkPass(TransformationPass):
    def run(self, dag):
        self.property_set["myproj_mark"] = True
        return dag

qc = QuantumCircuit(2)
qc.h(0)
qc.cx(0, 1)

backend = FakeManilaV2()
base = transpile(qc, backend=backend, optimization_level=2, seed_transpiler=0)

pm2 = PassManager()
pm2.append(MarkPass())
final = pm2.run(base)

ps = getattr(pm2, "property_set", {})
print("preset sonrası depth:", base.depth(), "özel pass sonrası:", final.depth())
print("işaret:", ps.get("myproj_mark"))

from qiskit import QuantumCircuit
from qiskit.transpiler.preset_passmanagers import generate_preset_pass_manager
from qiskit.transpiler.basepasses import TransformationPass
from qiskit_ibm_runtime.fake_provider import FakeManilaV2

class MarkPass(TransformationPass):
    def run(self, dag):
        self.property_set["myproj_mark"] = True
        return dag

qc = QuantumCircuit(1)
qc.h(0)
backend = FakeManilaV2()
pm = generate_preset_pass_manager(optimization_level=1, backend=backend)

# Bazı sürümlerde doğrudan append desteklenir; desteklenmiyorsa üstteki iki aşamalı deseni kullanın.
if hasattr(pm, "append"):
    pm.append(MarkPass())
    tqc = pm.run(qc)
    print("append destekli, depth:", tqc.depth())
else:
    print("append yok: iki aşamalı örnek dosyaya bakın (two_stage_custom.py)")

Özel pass, transpiler'ı genişletmenin en keskin aracıdır: DAG üzerinde çalışır, pass manager ile orkestre edilir ve preset ile birleştirilirken sürüm ve sıra riskleri taşır. Güvenli yol, küçük ve denklik kanıtı net pass'ler yazmak, test ve sürüm kilidiyle korumak ve gerektiğinde iki aşamalı desene dönmektir.

• Pass manager — zincir ve PropertySet.
• Transpiler pipeline — evre çerçevesi.
• Optimization seviyeleri — preset politikası.
• Taban kapıları, kapı ayrıştırması — dönüşüm içeriği.
• Zamanlama — süre alanları ve özel pass sonrası yeniden çizim.
• Donanım topolojisi — hedefe özgü kuralların zemini.