IBM Circuit-Funktion

Hinweis

• Qiskit Functions sind ein experimentelles Feature, das ausschließlich für Nutzer des IBM Quantum® Premium Plan, Flex Plan und On-Prem (über die IBM Quantum Platform API) Plan verfügbar ist. Sie befinden sich im Preview-Status und können sich noch ändern.

Überblick

Die IBM® Circuit function nimmt abstrakte PUBs als Eingabe und gibt geminderte Erwartungswerte als Ausgabe zurück. Diese Circuit function umfasst eine automatisierte und individuell angepasste Pipeline, damit sich Forschende auf die Entdeckung neuer Algorithmen und Anwendungen konzentrieren können.

Beschreibung

Nachdem du deinen PUB eingereicht hast, werden deine abstrakten Circuits und Observablen automatisch transpiliert, auf Hardware ausgeführt und nachbearbeitet, um geminderte Erwartungswerte zurückzugeben. Dafür werden folgende Tools kombiniert:

• Qiskit Transpiler Service, einschließlich automatischer Auswahl von KI-gestützten und heuristischen Transpilierungspässen, um abstrakte Circuits in hardware-optimierte ISA-Circuits umzuwandeln
• Fehlerunterdrückung und -minderung für Berechnungen im Utility-Maßstab, einschließlich Messung und Gate-Twirling, Dynamical Decoupling, Twirled Readout Error eXtinction (TREX), Zero-Noise Extrapolation (ZNE) und Probabilistic Error Amplification (PEA)
• Qiskit Runtime Estimator, zur Ausführung von ISA-PUBs auf Hardware und Rückgabe geminderter Erwartungswerte

Erste Schritte

Authentifiziere dich mit deinem API-Schlüssel und wähle die Qiskit Function wie folgt aus. (Dieser Codeausschnitt setzt voraus, dass du dein Konto bereits in deiner lokalen Umgebung gespeichert hast.)

# Added by doQumentation — required packages for this notebook
!pip install -q qiskit qiskit-ibm-catalog qiskit-ibm-runtime

from qiskit_ibm_catalog import QiskitFunctionsCatalog

catalog = QiskitFunctionsCatalog(channel="ibm_quantum_platform")

function = catalog.load("ibm/circuit-function")

Beispiel

Probiere zunächst dieses einfache Beispiel aus:

from qiskit.circuit.random import random_circuit
from qiskit_ibm_runtime import QiskitRuntimeService

# You can skip this step if you have a target backend, e.g.
# backend_name = "ibm_brisbane"
# You'll need to specify the credentials when initializing QiskitRuntimeService, if they were not previously saved.
service = QiskitRuntimeService()
backend = service.least_busy(operational=True, simulator=False)

circuit = random_circuit(num_qubits=2, depth=2, seed=42)
observable = "Z" * circuit.num_qubits
pubs = [(circuit, observable)]

job = function.run(
    # Use `backend_name=backend_name` if you didn't initialize a backend object
    backend_name=backend.name,
    pubs=pubs,
)

Überprüfe den Status deines Qiskit Function-Workloads oder rufe die Ergebnisse wie folgt ab:

print(job.status())
result = job.result()

QUEUED

Die Ergebnisse haben dasselbe Format wie ein Estimator-Ergebnis:

print(f"The result of the submitted job had {len(result)} PUB\n")
print(
    f"The associated PubResult of this job has the following DataBins:\n {result[0].data}\n"
)
print(f"And this DataBin has attributes: {result[0].data.keys()}")
print(
    f"The expectation values measured from this PUB are: \n{result[0].data.evs}"
)

The result of the submitted job had 1 PUB

The associated PubResult of this job has the following DataBins:
 DataBin(evs=np.ndarray(<shape=(), dtype=float64>), stds=np.ndarray(<shape=(), dtype=float64>), ensemble_standard_error=np.ndarray(<shape=(), dtype=float64>))

And this DataBin has attributes: dict_keys(['evs', 'stds', 'ensemble_standard_error'])
The expectation values measured from this PUB are:
1.02116704805492

Eingaben

Die folgende Tabelle zeigt alle Eingabeparameter, die die IBM Circuit function akzeptiert. Der nachfolgende Abschnitt Optionen geht detaillierter auf die verfügbaren options ein.

Name	Typ	Beschreibung	Erforderlich	Standard	Beispiel
backend_name	str	Name des Backends, auf dem die Anfrage ausgeführt wird.	Ja	N/A	ibm_fez
pubs	Iterable[EstimatorPubLike]	Ein iterierbares Objekt aus abstrakten PUB-ähnlichen (Primitive Unified Bloc) Objekten, etwa Tupel (circuit, observables) oder (circuit, observables, parameter_values). Siehe Überblick über PUBs für weitere Informationen. Die Circuits können abstrakt (nicht-ISA) sein.	Ja	N/A	(circuit, observables, parameter_values)
options	dict	Eingabeoptionen. Weitere Details findest du im Abschnitt Optionen.	Nein	Siehe den Abschnitt Optionen für Details.	{"optimization_level": 3}
instance	str	Der Cloud-Ressourcenname der zu verwendenden Instanz im entsprechenden Format.	Nein	Eine Instanz wird zufällig ausgewählt, wenn dein Konto Zugriff auf mehrere Instanzen hat.	CRN

Optionen

Struktur

Ähnlich wie bei Qiskit Runtime-Primitiven können Optionen für die IBM Circuit function als verschachteltes Dictionary angegeben werden. Häufig verwendete Optionen wie optimization_level und mitigation_level befinden sich auf der ersten Ebene. Weitere, fortgeschrittenere Optionen sind in verschiedene Kategorien gruppiert, z. B. resilience.

Standardwerte

Wenn du keinen Wert für eine Option angibst, wird der vom Service festgelegte Standardwert verwendet.

Minderungsstufe

Die IBM Circuit function unterstützt außerdem mitigation_level. Die Minderungsstufe legt fest, wie viel Fehlerunterdrückung und -minderung auf den Job angewendet wird. Höhere Stufen liefern genauere Ergebnisse, auf Kosten längerer Verarbeitungszeiten. Das Ausmaß der Fehlerreduktion hängt von der angewendeten Methode ab. Die Minderungsstufe abstrahiert die detaillierte Auswahl von Fehlerminderungs- und -unterdrückungsmethoden, damit Nutzer das für ihre Anwendung passende Kosten-/Genauigkeitsverhältnis abwägen können. Die folgende Tabelle zeigt die entsprechenden Methoden für jede Stufe.

hinweis

Obwohl die Namen ähnlich sind, wendet mitigation_level andere Techniken an als die vom resilience_level des Estimators verwendeten.

Ähnlich wie resilience_level im Qiskit Runtime Estimator legt mitigation_level einen Basissatz kuratierter Optionen fest. Alle Optionen, die du zusätzlich zur Minderungsstufe manuell angibst, werden auf den durch die Minderungsstufe definierten Basissatz angewendet. Grundsätzlich könntest du also die Minderungsstufe auf 1 setzen, aber die Messungsminderung deaktivieren – auch wenn dies nicht empfohlen wird.

Minderungsstufe	Technik
1 [Standard]	Dynamical Decoupling + Messung-Twirling + TREX
2	Stufe 1 + Gate-Twirling + ZNE via Gate-Faltung
3	Stufe 1 + Gate-Twirling + ZNE via PEA

Das folgende Beispiel zeigt, wie die Minderungsstufe gesetzt wird:

options = {"mitigation_level": 2}

job = function.run(backend_name=backend.name, pubs=pubs, options=options)

Alle verfügbaren Optionen

Zusätzlich zu mitigation_level bietet die IBM Circuit function eine Auswahl an erweiterten Optionen, mit denen du das Kosten-/Genauigkeitsverhältnis fein abstimmen kannst. Die folgende Tabelle zeigt alle verfügbaren Optionen:

Option	Sub-Option	Sub-Sub-Option	Beschreibung	Auswahlmöglichkeiten	Standard
default_precision			Die Standard-Präzision für jeden PUB oder run()-Aufruf, der keine eigene Präzision angibt. Jeder Eingabe-PUB kann seine eigene Präzision festlegen. Wenn der run()-Methode eine Präzision übergeben wird, gilt dieser Wert für alle PUBs im run()-Aufruf, die keine eigene Präzision angeben.	float > 0	0.015625
max_execution_time			Maximale Ausführungszeit in Sekunden, basierend auf der QPU-Nutzung (nicht auf der Wanduhrzeit). QPU-Nutzung ist die Zeitspanne, in der der QPU ausschließlich für die Verarbeitung deines Jobs genutzt wird. Überschreitet ein Job dieses Zeitlimit, wird er zwangsweise abgebrochen.	Ganzzahl in Sekunden im Bereich [1, 10800]
mitigation_level			Wie viel Fehlerunterdrückung und -minderung angewendet wird. Weitere Informationen zu den auf jeder Stufe verwendeten Methoden findest du im Abschnitt Minderungsstufe.	1 / 2 / 3	1
optimization_level			Wie viel Optimierung an den Circuits durchgeführt wird. Höhere Stufen erzeugen stärker optimierte Circuits, auf Kosten längerer Transpilierungszeit.	1 / 2 / 3	2
dynamical_decoupling	enable		Ob Dynamical Decoupling aktiviert werden soll. Eine Erklärung der Methode findest du unter Fehlerunterdrückung und -minderungstechniken.	True/False	True
	sequence_type		Welche Dynamical-Decoupling-Sequenz verwendet werden soll. * XX: verwendet die Sequenz tau/2 - (+X) - tau - (+X) - tau/2 * XpXm: verwendet die Sequenz tau/2 - (+X) - tau - (-X) - tau/2 * XY4: verwendet die Sequenz tau/2 - (+X) - tau - (+Y) - tau (-X) - tau - (-Y) - tau/2	'XX'/'XpXm'/'XY4'	'XX'
twirling	enable_gates		Ob 2-Qubit-Clifford-Gate-Twirling angewendet werden soll.	True/False	False
	enable_measure		Ob Twirling bei Messungen aktiviert werden soll.	True/False	True
resilience	measure_mitigation		Ob die TREX-Messfehlerminderungsmethode aktiviert werden soll. Eine Erklärung der Methode findest du unter Fehlerunterdrückung und -minderungstechniken.	True/False	True
	zne_mitigation		Ob die Zero-Noise-Extrapolation-Fehlerminderungsmethode aktiviert werden soll. Eine Erklärung der Methode findest du unter Fehlerunterdrückung und -minderungstechniken.	True/False	False
	zne	amplifier	Welche Technik zur Rauschverstärkung verwendet werden soll. Eine der folgenden: - gate_folding (Standard) verwendet 2-Qubit-Gate-Faltung zur Rauschverstärkung. Wenn der Rauschfaktor nur eine Teilmenge der Gates verstärken muss, werden diese zufällig ausgewählt. - gate_folding_front verwendet 2-Qubit-Gate-Faltung zur Rauschverstärkung. Wenn der Rauschfaktor nur eine Teilmenge der Gates verstärken muss, werden diese vom Anfang des topologisch geordneten DAG-Circuits ausgewählt. - gate_folding_back verwendet 2-Qubit-Gate-Faltung zur Rauschverstärkung. Wenn der Rauschfaktor nur eine Teilmenge der Gates verstärken muss, werden diese vom Ende des topologisch geordneten DAG-Circuits ausgewählt. - pea verwendet eine Technik namens Probabilistic Error Amplification (PEA) zur Rauschverstärkung. Eine Erklärung der Methode findest du unter Fehlerunterdrückung und -minderungstechniken.	gate_folding / gate_folding_front / gate_folding_back / pea	gate_folding
		noise_factors	Rauschfaktoren für die Rauschverstärkung.	Liste von Floats; jeder Float >= 1	(1, 1.5, 2) für PEA, und (1, 3, 5) andernfalls.
		extrapolator	Rauschfaktoren, bei denen die Extrapolationsmodelle ausgewertet werden sollen. Diese Option hat keinen Einfluss auf die Ausführung oder das Modell-Fitting; sie bestimmt lediglich die Punkte, an denen die extrapolator-Objekte ausgewertet werden, um in den Datenfeldern evs_extrapolated und stds_extrapolated zurückgegeben zu werden.	eines oder mehrere von exponential, linear, double_exponential, polynomial_degree_(1 <= k <= 7)	(exponential, linear)
	pec_mitigation		Ob die Probabilistic-Error-Cancellation-Fehlerminderungsmethode aktiviert werden soll. Eine Erklärung der Methode findest du unter Fehlerunterdrückung und -minderungstechniken.	True/False	False
	pec	max_overhead	Der maximal zulässige Circuit-Sampling-Overhead, oder None für kein Maximum.	None / Ganzzahl > 1	100

Im folgenden Beispiel deaktiviert das Setzen der Minderungsstufe auf 1 zunächst die ZNE-Minderung, aber das Setzen von zne_mitigation auf True überschreibt die entsprechende Einstellung aus mitigation_level.

options = {"mitigation_level": 1, "resilience": {"zne_mitigation": True}}

Ausgaben

Die Ausgabe einer Circuit function ist ein PrimitiveResult, das zwei Felder enthält:

• Ein oder mehrere PubResult-Objekte. Diese können direkt aus dem PrimitiveResult indiziert werden.

• Metadaten auf Job-Ebene.

Jedes PubResult enthält ein data- und ein metadata-Feld.

• Das data-Feld enthält mindestens ein Array von Erwartungswerten (PubResult.data.evs) und ein Array von Standardfehlern (PubResult.data.stds). Je nach verwendeten Optionen kann es weitere Daten enthalten.

• Das metadata-Feld enthält PUB-Metadaten (PubResult.metadata).

Der folgende Codeausschnitt beschreibt das Format von PrimitiveResult (und dem zugehörigen PubResult).

print(f"The result of the submitted job had {len(result)} PUB")
print(
    f"The expectation values measured from this PUB are: \n{result[0].data.evs}"
)
print(f"And the associated metadata is: \n{result[0].metadata}")

The result of the submitted job had 1 PUB
The expectation values measured from this PUB are:
1.02116704805492
And the associated metadata is:
{'shots': 4096, 'target_precision': 0.015625, 'circuit_metadata': {}, 'resilience': {}, 'num_randomizations': 32}

Fehlermeldungen abrufen

Wenn der Status deines Workloads ERROR ist, kannst du mit job.result() die Fehlermeldung zum Debuggen abrufen:

job = function.run(
    backend_name="bad_backend_name", pubs=pubs, options=options
)

print(job.result())

Support erhalten

Wende dich an den IBM Quantum Support und gib dabei folgende Informationen an:

• Qiskit Function Job-ID (qiskit-ibm-catalog), job.job_id
• Eine detaillierte Beschreibung des Problems
• Alle relevanten Fehlermeldungen oder -codes
• Schritte zur Reproduktion des Problems

Nächste Schritte

Empfehlungen

• Probiere das Tutorial Fehlerminderung mit der IBM Circuit function aus.