Devre üst verisi — talimatların gölgesinde kalan ikinci katman

Üst veri, devrenin anlamını değiştirmeyen ek bilgidir: kapıların sırasını, açılarını veya ölçüm eşlemesini doğrudan değiştirmez; fakat aynı talimat listesini taşıyan iki nesneyi insan veya makine için ayırt etmeyi kolaylaştırır. Bu ayrım önemlidir çünkü yeni başlayanlar, “devreyi tanımlayan her şey aynı yerde olmalı” dürtüsüyle üst veriye hesap sonucu yazmaya meyleder — bu da sonra serileştirme ve önbellek katmanlarında sürpriz üretir.

Kısa cümle: üst veri etikettir; talimat ise iş emridir.

.data içindeki öğeler kuantum yürütümünün atomlarıdır; üst veri ise bu atomların fabrika etiketi gibidir. Özellikler ( num_qubits vb.) çoğu zaman devreden türetilir; üst veri ise dış dünyadan atanır. Bu ikinci fark, “sayıyı metadata’ya yazayım” alışkanlığını sorgulatır: türetilebilen şeyi etikete gömmek, iki kaynağı senkron tutma borcunu doğurur.

Ne üst veri değildir

Parametre nesneleri, bindirme haritaları veya geçiş çıktısının kendisi üst verinin yerine geçmez; bunlar ayrı API yüzeyleridir. Parametre cebri parametrik devreler sayfasında; talimat sırası QuantumCircuit yapısı sayfasında işlenir.

Üst veri, köken (hangi depo, hangi commit, hangi not defteri), deney (job kimliği, parti adı, tekrar numarası), üretim (hangi sürümle üretildi, hangi hedef aile için derlendi) ve belgeleme (makale referansı, kısaltılmış protokol adı) için kullanılır. Bunların hiçbiri kuantum durumını değiştirmez; fakat bilimsel tekrarlanabilirlik ve operasyonel hata ayıklama için sıklıkla gereklidir.

İyi metadata, altı ay sonra “bu devre nereden çıktı?” sorusuna tek satırla cevap verir.

Varyasyonel veya hibrit iş akışlarında, üst veri bazen hiperparametre özeti taşır. Bu kullanışlıdır; fakat büyük tensörleri veya tam veri kümelerini buraya gömmek yerine dış depoda tutup yalnızca işaretçi (dosya yolu, URI, içerik özeti) yazmak daha sürdürülebilirdir.

Ekip sözleşmesi

Üst verinin değeri, ekip içi sözleşmeyle ölçülür: hangi anahtarlar zorunlu, hangileri isteğe bağlı, hangi tipler kabul edilir? Bu sözleşme yazılmadan metadata “çöplük”e döner; yazıldıktan sonra ise CI ve gözden geçirme süreçlerine bağlanır.

Kübit sayısı, derinlik tahminleri, kapı sayımları gibi nicelikler çoğu zaman devre grafiğinden okunabilir. Bunları üst veriye kopyalamak caziptir çünkü “raporlamayı kolaylaştırır”; fakat devre değişince etiket eskir. İki kaynaklı gerçeklik oluşur: biri grafiğin kendisi, diğeri unutulmuş sayı.

Türetilebileni etikete yazacaksanız, ya otomatik yenileyin ya da hiç yazmayın.

İstisna: dış sistemlerin “anında fotoğraf” istemesi. O zaman bile anahtar adını açıkça snapshot_* gibi bir dilimle işaretlemek, kalıcı iddialardan ayırır.

Düz anahtar adları çabuk çakışır: "version" hem sizin ekibinizde hem kullandığınız kütüphanede anlam kazanabilir. Bu yüzden üretim kodlarında önekli anahtarlar ( "acme_lab/experiment_id" gibi) veya iç içe sözlükler ( "provenance": {"git": ...}) tercih edilir. Çakışma çözülmeyince, bir araç zinciri sessizce üzerine yazar — hata bile vermez.

İsim alanı yoksa, metadata savaş alanına döner.

JSON uyumlu tipler (dize, sayı, mantıksal, liste, iç içe sözlük) dışa aktarımı kolaylaştırır. Özel Python nesneleri koymak kısa vadede rahattır; uzun vadede serileştirme kırılır.

Python’da sözlükler referansla taşınır. Bir devreyi klonlarken veya alt modüller arasında paylaşırken, aynı sözlük nesnesinin yanlışlıkla ortak kalması mümkündür: bir taraf günceller, diğeri habersiz değişir. Üst veriyi güvenle taşımak için bilinçli kopya (sığ veya derin, ihtiyaca göre) disiplini gerekir.

Paylaşılan sözlük, paylaşılan gizli durumdur.

“Boş metadata” ile “metadata yok” arasında da ince fark vardır: biri boş kutu, diğeri özellik tanımsızlığı. Ekip sözleşmesinde hangi durumun ne anlama geldiğini netleştirin.

İki modül devreyi compose ile birleştirdiğinizde, üst verinin nasıl birleşeceği tek bir “doğru” cevaba sahip olmayabilir: birleştirme öncesi her iki tarafta farklı köken etiketleri vardır. Bazı akışlarda birleşik devrede yalnızca bir tarafın etiketleri kalır; bazılarında birleşik bir sözlük üretilir; bazılarında ise üst veri bilinçli olarak boşaltılır. Bu yüzden birleştirme sonrası etiketleri yeniden atamak sık görülen bir adımdır.

Birleştirme matematiği net; metadata birleşimi ekip kararıdır.

Ters devre alırken üst verinin anlamı tartışmalıdır: “aynı deneyin tersi” mi, yoksa “yeni bir aşama” mı? Pratikte, ters çağrısından sonra üst veriyi gözden geçirmek ve gerekirse stage benzeri bir anahtarla güncellemek hatayı azaltır. Ayrıntılı birleştirme ve ters desenleri birleştirme ve ters devre sayfasında anlatılır; burada yalnızca etiket etkisine dikkat çekilir.

Geçiş (transpile) sonrası devre, kaynak devreyle aynı anlamsal hedefe yaklaşırken farklı talimat listesine dönüşebilir. Üst veri bu süreçte korunabilir, zenginleşebilir veya kısmen düşebilir; bu davranış sürüm ve araç zincirine bağlıdır. Bu yüzden “transpile öncesi” ve “transpile sonrası” için ayrı köken blokları tutmak, bilimsel iz sürmeyi kolaylaştırır.

Dışa aktarma formatı değiştikçe, hangi anahtarların taşındığını belgeleyin — varsaymayın.

Dosya tabanlı süreçlerde (örnek akışı: üret → dosyaya yaz → başka ortamda oku), üst verinin dosya gövdesinin dışında mı içinde mi duracağı ayrı bir tasarım kararıdır. İkisi de geçerli; karıştırmak ise hata üretir.

Talimat listesi okuması

Geçiş sonrası doğrulama için çoğu zaman .data üzerinden yürünür; modern sürümlerde işlem adı için inst.operation.name kullanımı yaygındır. Bu okuma, üst veriden bağımsızdır; ikisini birlikte raporlamak iyi bir deney defteri alışkanlığıdır.

Üst veri, kişisel veri veya gizli anahtar taşımak için uygun görünür çünkü “sadece etiket”tir. Bu yanıltıcıdır: loglara düşer, dosyalara yazılır, paylaşılan depolara kopyalanır. Üretimde hassas bilgileri metadata’ya koymaktan kaçının; yerine güvenli kimlik ve harici kasa kullanın.

Metadata loglanırsa, gizli değil demektir.

Boyut açısından, dev iç içe yapılar bellek ve serileştirme maliyetini artırır. Üst veriyi “mini veri tabanı” gibi kullanmak kısa vadede hızlıdır; uzun vadede performans ve diff okunabilirliği acıtır.

Sürekli entegrasyonda, beklenen üst veri anahtarlarının varlığını doğrulayan küçük testler, “sessiz üzerine yazma” hatalarını erken yakalar. Örneğin geçiş sonrası devrede belirli bir target_family etiketinin bulunması veya parametre şemasının korunması gibi iddialar, regresyon koruması sağlar.

Metadata assertion küçük görünür; büyük kayıpları önler.

Bu yaklaşım, optimizasyon geçişlerinin davranışını değiştirdiği senaryolarda özellikle değerlidir: talimat sayısı aynı kalsa bile üst veri farklılaşmış olabilir.

Aşağıdaki örnekler, üst veri atama ve JSON uyumlu dışa aktarım için küçük bir şablon sunar. Sürümler arasında metadata özniteliğinin tam adı veya ek kısıtlar değişebilir; resmi belgenizi doğrulayın.

from qiskit import QuantumCircuit

qc = QuantumCircuit(2, name="demo-ghz-prep")
qc.h(0)
qc.cx(0, 1)

qc.metadata = {
    "qubyt/provenance": {
        "notebook": "exp-2026-05-12",
        "stage": "pre-transpile",
    },
    "qubyt/tags": ["education", "static-page-example"],
}

print(qc.name)
print(qc.metadata)

import copy
import json
from qiskit import QuantumCircuit

src = QuantumCircuit(1)
src.x(0)
src.metadata = {"qubyt/run": {"id": 7, "label": "dry-run"}}

# Paylaşılan sözlük riskine karşı derin kopya ile yeni bir üst veri tabakası.
dst = src.copy()
dst.metadata = copy.deepcopy(src.metadata)
dst.metadata["qubyt/run"]["stage"] = "post-edit"

print(json.dumps(dst.metadata, ensure_ascii=False))

Devre üst verisi, kuantum programının kimlik kartı katmanıdır: talimatları değiştirmez; fakat köken, aşama ve ekip sözleşmesini taşır. Özelliklerden farklı olarak çoğu zaman dışsal atama ile gelir; paylaşılan referans riski taşır; birleştirme ve geçiş sonrası yeniden düzenlenmesi gerekebilir.

• QuantumCircuit yapısı — talimat kuyruğu ve okuma disiplini.
• Birleştirme ve ters devre — modül sınırında etiket etkisi.
• Devre optimizasyon mantığı — geçiş ve talimat dönüşümü.
• Parametrik devreler — sayısal parametreler ve üst veri ayrımı.