OpenQASM 2

qiskit.qasm2

Qiskit unterstützt die Zusammenarbeit mit OpenQASM 2.0 Programmen, sowohl beim Parsen in Qiskit-Formate als auch beim Exportieren zurück nach OpenQASM 2.

API-Parsing

Dieses Modul enthält zwei öffentliche Funktionen, die beide ein QuantumCircuit aus einem OpenQASM 2 Programm erstellen. load() nimmt einen Dateinamen, während loads() das Programm selbst als Zeichenkette annimmt. Ihre Interna sind sehr ähnlich, so dass beide fast die gleiche API bieten.

load

loads

Beide Ladefunktionen nehmen auch ein Argument include_path entgegen, bei dem es sich um eine Iterable von Verzeichnisnamen handelt, die bei der Suche nach Dateien in include Anweisungen verwendet werden. Die Verzeichnisse werden ab Index 0 durchsucht, und der erste Treffer wird verwendet. Der Import qelib1.inc wird besonders behandelt; er wird immer gefunden, bevor im Include-Pfad gesucht wird, und enthält genau den Inhalt des Papiers, das die Sprache OpenQASM 2 beschreibt. Die Gatter in dieser Include-Datei werden auf von Qiskit definierte Gatterobjekte der Schaltkreisbibliothek abgebildet.

Angabe benutzerdefinierter Anweisungen

Sie können die Quantenkomponenten der Sprache OpenQASM 2 erweitern, indem Sie eine Iterable mit Informationen über benutzerdefinierte Anweisungen als Argument custom_instructions übergeben. In Dateien, die kompatible Definitionen für diese Befehle haben, wird die angegebene constructor anstelle einer anderen Handhabung verwendet qiskit.qasm2 getan hätte. Diese Befehle können optional als builtin markiert werden, was dazu führt, dass sie keine opaque oder gate Deklaration benötigen, aber eine kompatible Deklaration wird stillschweigend ignoriert. In jedem Fall ist es ein Fehler, eine benutzerdefinierte Anweisung mit einer anderen Anzahl von Parametern oder Qubits als eine definierte Anweisung in einem geparsten Programm anzugeben. Jedes Element des Arguments iterable sollte eine bestimmte Datenklasse sein:

CustomInstruction

from qiskit import qasm2
from qiskit.circuit import QuantumCircuit, library

qc = QuantumCircuit(2)
qc.ecr(0, 1)
qc.rzx(0.3, 0, 1)
qc.rzx(0.7, 1, 0)
qc.rzx(1.5, 0, 1)
qc.ecr(1, 0)

# This output string includes `gate ecr q0, q1 { ... }` and `gate rzx(p) q0, q1 { ... }`
# statements, since `ecr` and `rzx` are neither built-in gates nor in ``qelib1.inc``.
dumped = qasm2.dumps(qc)

# Tell the importer how to interpret the `gate` statements, which we know are safe
# because we controlled the input OpenQASM 2 source.
custom = [
    qasm2.CustomInstruction("ecr", 0, 2, library.ECRGate),
    qasm2.CustomInstruction("rzx", 1, 2, library.RZXGate),
]

loaded = qasm2.loads(dumped, custom_instructions=custom)

Dies kann besonders nützlich sein, wenn es darum geht, Unklarheiten in den Global-Phase-Konventionen eines OpenQASM 2-Programms zu beseitigen. Weitere Einzelheiten finden Sie unter OpenQASM 2 Phase Conventions.

Festlegen benutzerdefinierter klassischer Funktionen

Ähnlich wie bei den obigen Quantenerweiterungen können Sie auch die Verarbeitung klassischer Ausdrücke (Argumente an Gates) erweitern, indem Sie eine Iterable an das Argument custom_classical an einen der Lader übergeben. Diese benötigt die name (eine gültige OpenQASM 2 Kennung), die Anzahl num_params der Parameter, die sie benötigt, und ein Python callable, das die Funktion implementiert. Der Aufruf Python muss num_params positionale Fließkomma-Argumente akzeptieren und einen Float oder Integer zurückgeben (der in einen Float konvertiert wird). Eingebaute Funktionen können nicht außer Kraft gesetzt werden.

CustomClassical

Strikter Modus

Beide Loader-Funktionen verfügen über einen optionalen "strict"-Modus. Standardmäßig ist dieser Parser etwas entspannter als die offizielle Spezifikation: Er erlaubt abschließende Kommas in Parameterlisten, unnötige (leere Anweisung) Semikolons, das Weglassen der OPENQASM 2.0; Versionsanweisung und einige andere Verbesserungen der Lebensqualität, ohne Fehler auszugeben. Sie können den Kennbuchstabenmodus mit strict=True verwenden.

API exportieren

Ähnlich wie andere Serialisierungsmodule in Python bietet dieses Modul zwei öffentliche Funktionen: dump() und dumps(), die ein QuantumCircuit nehmen und ein repräsentatives OpenQASM 2 Programm in ein dateiähnliches Objekt schreiben bzw. einen String zurückgeben.

dump

dumps

Fehler

Dieses Modul definiert einen generischen Fehlertyp, der sich von QiskitError abgeleitet ist, der als Abfangtyp verwendet werden kann, wenn Sie sich speziell um Fehler kümmern, die von der Interoperationsschicht ausgegeben werden.

QASM2Error

In Fällen, in denen der Lexer oder Parser aufgrund einer ungültigen OpenQASM 2 Datei fehlschlägt, geben die Konvertierungsfunktionen eine spezifischere Fehlermeldung aus, in der erklärt wird, worin der Fehler besteht und wo in der Datei er aufgetreten ist.

QASM2ParseError

Wenn die Exporteure einen Schaltkreis nicht exportieren können, wahrscheinlich weil er eine Struktur hat, die nicht durch OpenQASM 2.0 dargestellt werden kann, geben sie auch einen benutzerdefinierten Fehler aus.

QASM2ExportError

Beispiele

Beispiele exportieren

Exportieren Sie eine einfache QuantumCircuit in eine OpenQASM 2 Zeichenfolge:

import qiskit.qasm2
from qiskit.circuit import QuantumCircuit

qc = QuantumCircuit(2, 2)
qc.h(0)
qc.cx(0, 1)
qc.measure([0, 1], [0, 1])
print(qiskit.qasm2.dumps(qc))

OPENQASM 2.0;
include "qelib1.inc";
qreg q[2];
creg c[2];
h q[0];
cx q[0],q[1];
measure q[0] -> c[0];
measure q[1] -> c[1];

Schreiben Sie das gleiche QuantumCircuit unter einem bestimmten Dateinamen:

qiskit.qasm2.dump(qc, "myfile.qasm")

In ähnlicher Weise kann man allgemeine os.PathLike instanzen als Dateinamen verwenden:

import pathlib

qiskit.qasm2.dump(qc, pathlib.Path.home() / "myfile.qasm")

Man kann den Text auch in einen bereits geöffneten Stream ausgeben:

import io

with io.StringIO() as stream:
    qiskit.qasm2.dump(qc, stream)

Beispiele für die Analyse

Verwenden Sie loads() importieren Sie ein OpenQASM 2 Programm in einem String in eine QuantumCircuit:

import qiskit.qasm2
program = """
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[2];
    creg c[2];

    h q[0];
    cx q[0], q[1];

    measure q -> c;
"""
circuit = qiskit.qasm2.loads(program)
circuit.draw()

     ┌───┐     ┌─┐
q_0: ┤ H ├──■──┤M├───
     └───┘┌─┴─┐└╥┘┌─┐
q_1: ─────┤ X ├─╫─┤M├
          └───┘ ║ └╥┘
c: 2/═══════════╩══╩═
                0  1

Sie können dasselbe erreichen, wenn das Programm in einer Datei gespeichert ist, indem Sie load() verwenden und den Dateinamen als Argument übergeben:

import qiskit.qasm2
circuit = qiskit.qasm2.load("myfile.qasm")

OpenQASM 2-Dateien können andere OpenQASM 2-Dateien über die Anweisung include einschließen. Sie können den Suchpfad, der zum Auffinden dieser Dateien verwendet wird, mit dem Argument include_path sowohl bei load() und loads(). Standardmäßig wird nur das aktuelle Arbeitsverzeichnis durchsucht.

import qiskit.qasm2
program = """
    include "other.qasm";
    // ... and so on
"""
circuit = qiskit.qasm2.loads(program, include_path=("/path/to/a", "/path/to/b", "."))

Nur für load() gibt es ein zusätzliches Argument include_input_directory, mit dem man entweder 'append', 'prepend' oder das Verzeichnis der geladenen Datei im Include-Pfad ignorieren (None) kann. Standardmäßig wird dieses Verzeichnis an den Suchpfad angehängt, so dass es als letztes durchsucht wird, aber Sie können dies ändern.

import qiskit.qasm2
filenames = ["./subdirectory/a.qasm", "/path/to/b.qasm", "~/my.qasm"]
# Search the directory of each file before other parts of the include path.
circuits = [
    qiskit.qasm2.load(filename, include_input_directory="prepend") for filename in filenames
]
# Override the include path, and don't search the directory of each file unless it's in the
# absolute path list.
circuits = [
    qiskit.qasm2.load(
        filename,
        include_path=("/usr/include/qasm", "~/qasm/include"),
        include_input_directory=None,
    )
    for filename in filenames
]

Manchmal möchte man vielleicht die Gate Objekte beeinflussen, die der Importer für bestimmte benannte Anweisungen ausgibt. Gatter, die durch die Anweisung include "qelib1.inc"; definiert sind, werden automatisch einem passenden Gatter aus der Qiskit-Schaltkreisbibliothek zugeordnet, aber Sie können dies erweitern:

from qiskit.circuit import Gate
from qiskit.qasm2 import loads, CustomInstruction

class MyGate(Gate):
    def __init__(self, theta):
        super().__init__("my", 2, [theta])

class Builtin(Gate):
    def __init__(self):
        super().__init__("builtin", 1, [])

program = """
    opaque my(theta) q1, q2;
    qreg q[2];
    my(0.5) q[0], q[1];
    builtin q[0];
"""
customs = [
    CustomInstruction(name="my", num_params=1, num_qubits=2, constructor=MyGate),
    # Setting 'builtin=True' means the instruction doesn't require a declaration to be usable.
    CustomInstruction("builtin", 0, 1, Builtin, builtin=True),
]
circuit = loads(program, custom_instructions=customs)

In ähnlicher Weise können Sie neue klassische Funktionen hinzufügen, die bei der Beschreibung von Argumenten für Gatter verwendet werden, sowohl im Hauptteil des Programms (die konstant gefaltet erscheinen) als auch in den Körpern definierter Gatter (die bei Bedarf berechnet werden). Hier stellen wir eine Python Version von atan2(y, x) zur Verfügung, die mathematisch $\arctan(y/x)$ entspricht, aber korrekt mit Winkelquadranten und Unendlichkeiten umgeht, sowie eine benutzerdefinierte add_one Funktion:

import math
from qiskit.qasm2 import loads, CustomClassical

program = """
    include "qelib1.inc";
    qreg q[2];
    rx(atan2(pi, 3 + add_one(0.2))) q[0];
    cx q[0], q[1];
"""

def add_one(x):
    return x + 1

customs = [
    # `atan2` takes two parameters, and `math.atan2` implements it.
    CustomClassical("atan2", 2, math.atan2),
    # Our `add_one` takes only one parameter.
    CustomClassical("add_one", 1, add_one),
]
circuit = loads(program, custom_classical=customs)

OpenQASM 2-Phasen-Konventionen

Als Sprache bietet OpenQASM 2 keine Möglichkeit, die globale Phase eines vollständigen Programms oder bestimmte Gatterdefinitionen zu spezifizieren. Das bedeutet, dass die Parser der Sprache bestimmte Gatter mit einer anderen globalen Phase interpretieren können, als man es erwarten würde. Die De-facto-Standardbibliothek OpenQASM 2 qelib1.inc enthält beispielsweise folgende Definitionen von u1 und rz :

gate u1(lambda) q {
    U(0, 0, lambda) q;
}

gate rz(phi) a {
    u1(phi) a;
}

Mit anderen Worten: rz scheint ein direkter Alias für u1 zu sein. Die Interpretation von u1 wird jedoch in Gleichung (3) des Papiers, das die Sprache beschreibt, wie folgt spezifiziert

wobei das Symbol $\sim$ die Gleichwertigkeit nur bis zu einer globalen Phase angibt. Beim Parsen von OpenQASM 2 müssen wir entscheiden, wie wir mit der Unterscheidung zwischen solchen Gattern umgehen; u1 ist in der Prosa so definiert, dass sie sich um eine Phase von rz unterscheidet, aber die Sprache ist nicht darauf ausgelegt, dies darzustellen.

U1GateRZGateQiskit geht standardmäßig davon aus, dass die Verwendung der Standardbibliothek rz mit bedeutet und die Verwendung von u1 bedeutet, dass die phasenunterschiedliche verwendet wird. Wenn Sie die Phasenkonventionen verwenden möchten, die sich eher aus einer direkten Auslegung der gate Anweisungen in der Header-Datei ergeben, können Sie verwenden CustomInstruction , um die Art und Weise zu überschreiben, wie Qiskit die Schaltung aufbaut.

Für das Standard-Include qelib1.inc gibt es nur einen Differenzpunkt, so dass die für die Umschaltung der Phasenkonvention erforderliche Übersteuerung gleich ist:

from qiskit import qasm2
from qiskit.circuit.library import PhaseGate
from qiskit.quantum_info import Operator

program = """
    OPENQASM 2.0;
    include "qelib1.inc";
    qreg q[1];
    rz(pi / 2) q[0];
"""

custom = [
    qasm2.CustomInstruction("rz", 1, 1, PhaseGate),
]

U1GateHierbei wird die Klasse von PhaseGate Qiskit verwendet, um die rz Anweisung darzustellen, die (einschließlich der Phase) gleich ist mit:

Operator(qasm2.loads(program, custom_instructions=custom))

Operator([[1.000000e+00+0.j, 0.000000e+00+0.j],
          [0.000000e+00+0.j, 6.123234e-17+1.j]],
         input_dims=(2,), output_dims=(2,))

Abwärtskompatibilität

QuantumCircuit.from_qasm_str() und from_qasm_file() verwendet, um einige Ergänzungen zu den Rohdaten vorzunehmen. Qiskit hat ursprünglich versucht, OpenQASM 2 als eine Art Serialisierungsformat zu verwenden, und hat sein Verhalten erweitert, als Qiskit expandierte. Der neue Parser setzt die Spezifikation mit all seinen Voreinstellungen strenger um.

Dies gilt insbesondere für die alten Importeure:

• der Include-Pfad ist effektiv:

  1. <qiskit>/qasm/libswobei <qiskit> das Stammverzeichnis des installierten Pakets qiskit ist;
  2. Das aktuelle Arbeitsverzeichnis.

• gibt es zusätzliche Anweisungen, die in qelib1.inc definiert sind:

  csx a, b

  Gesteuertes „ $\sqrt X$ “-Gate, entsprechend CSXGate.

  cu(theta, phi, lambda, gamma) c, t

  CUGateDie Vier-Parameter-Version eines kontrollierten „ $U$ “, entsprechend.

  rxx(theta) a, b

  RXXGateDrehung zweier Qubits um die Achse „ $XX$ “, was dem Wert entspricht.

  rzz(theta) a, b

  RZZGateDrehung zweier Qubits um die Achse „ $ZZ$ “, was dem Wert entspricht.

  rccx a, b, c

  Das doppelt gesteuerte „ $X$ “-Gatter, jedoch mit relativen Phasendifferenzen gegenüber dem Standard-Toffoli-Gatter. RCCXGateDies sollte dem Qiskit-Gatter entsprechen, aber der Legacy-Konverter würde diesen Typ eigentlich nicht ausgeben.

  rc3x a, b, c, d

  Das dreifach gesteuerte „ $X$ “-Gatter, jedoch mit relativen Phasendifferenzen gegenüber der Standarddefinition. RC3XGateEntspricht.

  c3x a, b, c, d

  C3XGateDas dreifach gesteuerte „ $X$ “-Tor, das dem entspricht.

  c3sqrtx a, b, c, d

  C3SXGateDas dreifach gesteuerte „ $\sqrt X$ “-Tor, das dem entspricht.

  c4x a, b, c, d, e

  Das vierfach gesteuerte „ $X$ “-Tor., C4XGateentsprechend.

• wenn eine opaque oder gate Definition für den Namen delay gegeben wurde, versuchen sie, bei jedem Aufruf eine Delay anweisung bei jedem Aufruf auszugeben. Damit dies funktioniert, wird eine Definition erwartet, die mit opaque delay(t) q; kompatibel ist, wobei die Zeit t in Einheiten von dt angegeben wird. Der Importer löst bei der Konstruktion Fehler aus, wenn nicht genau ein Parameter und ein Qubit vorhanden sind oder wenn der Parameter nicht ganzzahlig ist.

• stehen die zusätzlichen wissenschaftlichen Rechenfunktionen asin, acos und atan zur Verfügung.

• die geparste Grammatik entspricht im Wesentlichen dem strengen Modus der neuen Importeure.

Sie können dieses Verhalten in load() und loads() emulieren, indem Sie include_path entsprechend setzen (versuchen Sie, die Variable qiskit.__file__ zu untersuchen, um den installierten Speicherort zu finden), und indem Sie eine Liste von CustomInstruction instanzen für jedes der benutzerdefinierten Gates, für die Sie sich interessieren, übergeben. Zur Vereinfachung stellen wir drei Tupel zur Verfügung, die jeweils eine Komponente einer Konfiguration enthalten, die dem bisherigen Konverterverhalten von Qiskit entspricht.

qiskit.qasm2.LEGACY_CUSTOM_INSTRUCTIONS

qiskit.qasm2.LEGACY_CUSTOM_CLASSICAL

qiskit.qasm2.LEGACY_INCLUDE_PATH

Bei allen Gattern, die in Qiskits Legacy-Version von qelib1.inc und der Anweisung delay definiert sind, spielt es keine Rolle, wie die Gatter tatsächlich definiert und verwendet werden, der Legacy-Importer wird immer versuchen, seine benutzerdefinierten Objekte für sie auszugeben. Dies kann zu Fehlern beim Aufbau des Stromkreises führen, selbst nach einer erfolgreichen Analyse. Es gibt keine Möglichkeit, dieses fehlerhafte Verhalten zu emulieren mit qiskit.qasm2zu emulieren; nur eine include "qelib1.inc"; -Anweisung oder das Argument custom_instructions kann bewirken, dass eingebaute Qiskit-Anweisungen verwendet werden, und die Signaturen dieser Anweisungen stimmen überein.

Alternativen

Die Parser-Komponenten dieses Moduls waren ursprünglich ein separates PyPI -Paket: qiskit-qasm2. Dieses Paket in der Version 0.5.3 wurde in Qiskit Terra 0.24 verkauft. Spätere Änderungen zwischen den beiden Paketen müssen nicht unbedingt synchronisiert werden.

Es gibt eine neuere Version der Spezifikation OpenQASM, Version 3.0, die unter folgender Adresse beschrieben wird https://openqasm.com. Dazu gehören weitaus mehr Möglichkeiten zur klassischen Programmierung auf hohem Niveau. Qiskit hat bereits eine rudimentäre Unterstützung für OpenQASM 3; siehe qiskit.qasm3 für diese.

OpenQASM 2 ist keine geeignete Serialisierungssprache für Qiskit's QuantumCircuit. Dieses Modul dient der Interoperabilität und nicht als allgemeines Serialisierungsformat. Wenn Sie genau das brauchen, sollten Sie qiskit.qpy stattdessen.