OpenQASM 2

qiskit.qasm2

Qiskit prend en charge l'interopérabilité avec les programmes OpenQASM 2.0, tant pour l 'analyse dans les formats Qiskit que pour l'exportation vers OpenQASM 2.

API d'analyse syntaxique

Ce module contient deux fonctions publiques, qui créent toutes deux un programme QuantumCircuit à partir d'un programme OpenQASM 2. load() prend un nom de fichier, tandis que loads() prend le programme lui-même sous la forme d'une chaîne de caractères. Leurs composants internes sont très similaires, de sorte qu'ils offrent pratiquement la même API.

load

loads

Ces deux fonctions de chargement prennent également en argument include_path, qui est une table itérative de noms de répertoires à utiliser lors de la recherche de fichiers dans les instructions include . Les répertoires sont essayés à partir de l'index 0, et la première correspondance est utilisée. L'importation qelib1.inc fait l'objet d'un traitement particulier; elle est toujours trouvée avant de chercher dans le chemin d'inclusion et contient exactement le contenu du document décrivant le langage OpenQASM 2. Les portes de ce fichier d'inclusion sont mappées aux objets de portes de la bibliothèque de circuits définis par Qiskit.

Spécifier des instructions personnalisées

Vous pouvez étendre les composants quantiques du langage OpenQASM 2 en passant un itérable d'informations sur les instructions personnalisées en tant qu'argument custom_instructions. Dans les fichiers qui ont des définitions compatibles pour ces instructions, l'adresse constructor donnée sera utilisée à la place de toute autre manipulation qui aurait été faite qiskit.qasm2 aurait fait. Ces instructions peuvent éventuellement être marquées comme builtin, ce qui fait qu'elles ne nécessitent pas de déclaration opaque ou gate , mais elles ignoreront silencieusement une déclaration compatible. Quoi qu'il en soit, c'est une erreur de fournir une instruction personnalisée dont le nombre de paramètres ou de qubits est différent de celui d'une instruction définie dans un programme analysé. Chaque élément de l'argument itérable doit être une classe de données particulière :

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)

Cela peut s'avérer particulièrement utile lorsqu'il s'agit de résoudre des ambiguïtés dans les conventions de phase globale d'un programme OpenQASM 2. Pour plus de détails, voir OpenQASM 2 Phase Conventions.

Spécification de fonctions classiques personnalisées

Comme pour les extensions quantiques ci-dessus, vous pouvez également étendre le traitement des expressions classiques (arguments des portes) en passant un itérable à l'argument custom_classical de l'un ou l'autre des chargeurs. Elle a besoin de name (un identifiant OpenQASM 2 valide), du nombre num_params de paramètres qu'elle prend et d'un appel Python qui implémente la fonction. L'appelable Python doit être capable d'accepter les arguments flottants positionnels num_params et doit renvoyer un flottant ou un entier (qui sera converti en flottant). Les fonctions intégrées ne peuvent pas être remplacées.

CustomClassical

Mode strict

Les deux fonctions du chargeur disposent d'un mode "strict" optionnel. Par défaut, cet analyseur est un peu plus détendu que la spécification officielle : il autorise les virgules de fin dans les listes de paramètres, les points-virgules inutiles (déclaration vide), l'omission de la déclaration de version OPENQASM 2.0; et quelques autres améliorations de qualité de vie sans émettre d'erreurs. Vous pouvez utiliser le mode "lettre de recommandation" avec strict=True.

API d'exportation

Comme les autres modules de sérialisation de Python, ce module offre deux fonctions publiques : dump() et dumps()qui prennent un QuantumCircuit et écrivent un programme OpenQASM 2 représentatif dans un objet de type fichier ou renvoient une chaîne de caractères, respectivement.

dump

dumps

Erreurs

Ce module définit un type d'erreur générique dérivé de QiskitError qui peut être utilisé comme un piège lorsque l'on s'intéresse à des défaillances émises par la couche d'interopérabilité en particulier.

QASM2Error

Dans les cas où le lexateur ou l'analyseur syntaxique échoue en raison d'un fichier OpenQASM 2 non valide, les fonctions de conversion génèrent une erreur plus spécifique accompagnée d'un message expliquant la nature de l'échec et l'endroit du fichier où il s'est produit.

QASM2ParseError

Lorsque les exportateurs ne parviennent pas à exporter un circuit, probablement parce que sa structure ne peut être représentée par OpenQASM 2.0, ils émettent également une erreur personnalisée.

QASM2ExportError

Exemples

Exemples d'exportation

Exporter un simple QuantumCircuit vers une chaîne OpenQASM 2 :

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];

Écrire la même chose QuantumCircuit dans un fichier donné :

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

De même, il est possible d'utiliser des instances générales os.PathLike comme nom de fichier :

import pathlib

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

Il est également possible de transférer le texte dans un flux déjà ouvert :

import io

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

Exemples d'analyse syntaxique

Utilisation loads() pour importer un programme OpenQASM 2 dans une chaîne de caractères dans un fichier 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

Vous pouvez obtenir la même chose si le programme est stocké dans un fichier en utilisant à la place load() en passant le nom du fichier comme argument :

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

OpenQASM 2 peuvent inclure d'autres fichiers OpenQASM 2 via l'instruction include . Vous pouvez influencer le chemin de recherche utilisé pour trouver ces fichiers à l'aide de l'argument include_path des commandes load() et loads(). Par défaut, seul le répertoire de travail actuel est recherché.

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

Pour load() uniquement, il existe un argument supplémentaire include_input_directory, qui peut être utilisé pour 'append', 'prepend' ou pour ignorer (None) le répertoire du fichier chargé dans le chemin d'inclusion. Par défaut, ce répertoire est ajouté au chemin de recherche, de sorte qu'il est essayé en dernier, mais vous pouvez le modifier.

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
]

Il peut parfois vous arriver de vouloir modifier les Gate objets générés par l'importateur pour certaines instructions nommées. Les portes définies par l'instruction include "qelib1.inc"; seront automatiquement associées à une porte appropriée de la bibliothèque de circuits Qiskit, mais vous pouvez étendre cette fonctionnalité :

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)

De même, vous pouvez ajouter de nouvelles fonctions classiques utilisées lors de la description des arguments des portes, à la fois dans le corps principal du programme (qui sortent avec un pli constant) et dans les corps des portes définies (qui sont calculées à la demande). Nous proposons ici une version Python de atan2(y, x), qui correspond mathématiquement à $\arctan(y/x)$ mais qui traite correctement les quadrants angulaires et les infinis, ainsi qu'une fonction add_one personnalisée :

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 Conventions en deux phases

En tant que langage, OpenQASM 2 ne permet pas de spécifier la phase globale d'un programme complet, ni des définitions de portes particulières. Cela signifie que les analyseurs du langage peuvent interpréter certaines portes avec une phase globale différente de celle à laquelle on pourrait s'attendre. Par exemple, la bibliothèque standard de facto de OpenQASM 2 qelib1.inc contient les définitions suivantes de u1 et rz :

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

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

En d'autres termes, rz semble être un alias direct de u1. Cependant, l'interprétation de u1 est spécifiée dans l' équation (3) du document décrivant la langue comme suit

où le symbole $\sim$ indique une équivalence uniquement jusqu'à une phase globale. Lors de l'analyse de OpenQASM 2, nous devons choisir comment traiter une distinction entre de telles portes; u1 est défini dans la prose comme étant différent par une phase de rz, mais le langage n'est pas conçu pour représenter cela.

Par défaut, Qiskit considère qu’une utilisation de la bibliothèque rz standard correspond à l’utilisation de RZGate, et qu’une utilisation de u1 correspond à l’utilisation de la version à phase distincte U1Gate. Si vous souhaitez utiliser les conventions de phase qui découlent davantage d'une interprétation littérale des gate instructions contenues dans le fichier d'en-tête, vous pouvez utiliser CustomInstruction pour redéfinir la manière dont Qiskit construit le circuit.

Pour l'inclusion standard qelib1.inc , il n'y a qu'un seul point de différence, et la dérogation nécessaire pour changer sa convention de phase est donc la suivante :

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),
]

Cela utilisera la classe de PhaseGate Qiskit pour représenter l'instruction rz , qui est égale (y compris la phase) à U1Gate:

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,))

Compatibilité héritée

QuantumCircuit.from_qasm_str() et from_qasm_file() utilisé pour faire quelques ajouts par rapport à la spécification brute. Qiskit a d'abord essayé d'utiliser OpenQASM 2 comme une sorte de format de sérialisation, et a étendu son comportement au fur et à mesure que Qiskit se développait. Le nouvel analyseur syntaxique, avec toutes ses valeurs par défaut, applique la spécification de manière plus stricte.

En particulier, dans les importateurs traditionnels :

• l'include_path est effectivement :

  1. <qiskit>/qasm/libsoù <qiskit> est la racine du paquet qiskit installé;
  2. Répertoire de travail en cours

• il existe des instructions supplémentaires définies à l'adresse qelib1.inc:

  csx a, b

  Porte d' $\sqrt X$ e contrôlée, correspondant à CSXGate.

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

  La version à quatre paramètres d'une fonction contrôlée- $U$ e, correspondant à CUGate.

  rxx(theta) a, b

  Rotation de deux qubits autour de l'axe d' $XX$, ce qui correspond à RXXGate.

  rzz(theta) a, b

  Rotation de deux qubits autour de l'axe d' $ZZ$, ce qui correspond à RZZGate.

  rccx a, b, c

  La porte d' $X$ e à double commande, mais présentant des différences de phase relatives par rapport à la porte de Toffoli standard. RCCXGateCela devrait correspondre à la porte Qiskit, mais l'ancien convertisseur ne produirait en réalité pas ce type de sortie.

  rc3x a, b, c, d

  La porte « $X$ » à triple contrôle, mais avec des différences de phase relatives par rapport à la définition standard. Cela correspond à RC3XGate.

  c3x a, b, c, d

  La porte « $X$ » à triple commande, correspondant à C3XGate.

  c3sqrtx a, b, c, d

  La porte « $\sqrt X$ » à triple commande, correspondant à C3SXGate.

  c4x a, b, c, d, e

  La porte « $X$ » à quadruple commande., correspondant à C4XGate.

• si une définition opaque ou gate a été donnée pour le nom delay, ils tentent de produire une instruction à chaque appel Delay à chaque appel. Pour fonctionner, il faut une définition compatible avec opaque delay(t) q;, où le temps t est donné en unités de dt. L'importateur soulèvera des erreurs lors de la construction s'il n'y a pas exactement un paramètre et un qubit, ou si le paramètre n'a pas une valeur entière.

• les fonctions supplémentaires de calcul scientifique asin, acos et atan sont disponibles.

• la grammaire analysée est effectivement la même que le mode strict des nouveaux importateurs.

Vous pouvez reproduire ce comportement dans load() et loads() en définissant include_path de manière appropriée (essayez d'inspecter la variable qiskit.__file__ pour trouver l'emplacement installé), et en passant une liste d'instances de CustomInstruction pour chacune des portes personnalisées qui vous intéressent. Pour faciliter les choses, nous mettons à disposition trois tuples, qui contiennent chacun un composant d'une configuration équivalente au comportement de l'ancien convertisseur de Qiskit.

qiskit.qasm2.LEGACY_CUSTOM_INSTRUCTIONS

qiskit.qasm2.LEGACY_CUSTOM_CLASSICAL

qiskit.qasm2.LEGACY_INCLUDE_PATH

Pour toutes les portes définies dans la version héritée de Qiskit de qelib1.inc et l'instruction delay , la façon dont les portes sont définies et utilisées n'a pas d'importance, l'importateur hérité essaiera toujours de produire ses objets personnalisés pour elles. Cela peut entraîner des erreurs lors de la construction du circuit, même après une analyse réussie. Il n'y a aucun moyen d'émuler ce comportement bogué avec qiskit.qasm2; seule une instruction include "qelib1.inc"; ou l'argument custom_instructions peut entraîner l'utilisation d'instructions Qiskit intégrées, et les signatures de ces instructions correspondent les unes aux autres.

Options

Les composants de l'analyseur syntaxique de ce module ont d'abord fait l'objet d'un paquetage distinct à l'adresse PyPI : qiskit-qasm2. Ce paquet, dans sa version 0.5.3, a été vendu à Qiskit Terra 0.24. Toute modification ultérieure entre les deux paquets ne sera pas nécessairement synchronisée.

Il existe une version plus récente de la spécification OpenQASM, la version 3.0, qui est décrite à l'adresse suivante https://openqasm.com. Les possibilités de programmation classique de haut niveau sont beaucoup plus nombreuses. Qiskit a déjà un support rudimentaire pour OpenQASM 3; voir qiskit.qasm3 pour cela.

OpenQASM 2 n'est pas un langage de sérialisation approprié pour le système Qiskit QuantumCircuit. Ce module est fourni à des fins d'interopérabilité et ne constitue pas un format de sérialisation général. Si c'est ce dont vous avez besoin, envisagez d'utiliser qiskit.qpy à la place.