OpenQASM 2

qiskit.qasm2

O Qiskit tem suporte para interoperação com os programas OpenQASM 2.0, tanto para análise em formatos Qiskit quanto para exportação de volta para OpenQASM 2.

API de análise

Esse módulo contém duas funções públicas, ambas as quais criam um programa QuantumCircuit a partir de um programa OpenQASM 2. load() recebe um nome de arquivo, enquanto loads() recebe o próprio programa como uma cadeia de caracteres. Seus componentes internos são muito semelhantes, portanto, ambos oferecem praticamente a mesma API.

load

loads

Ambas as funções de carregamento também recebem um argumento include_path, que é um iterável de nomes de diretório a ser usado na busca de arquivos nos comandos include . Os diretórios são testados a partir do índice 0, e a primeira correspondência é usada. A importação qelib1.inc é tratada de forma especial; ela é sempre encontrada antes de procurar no caminho de inclusão e contém exatamente o conteúdo do documento que descreve a linguagem OpenQASM 2. As portas nesse arquivo de inclusão são mapeadas para objetos de porta de biblioteca de circuitos definidos pelo Qiskit.

Especificando instruções personalizadas

Você pode estender os componentes quânticos da linguagem OpenQASM 2 passando um iterável de informações sobre instruções personalizadas como o argumento custom_instructions. Em arquivos que tenham definições compatíveis para essas instruções, o constructor fornecido será usado no lugar de qualquer outra manipulação que qiskit.qasm2 teria sido feito. Essas instruções podem, opcionalmente, ser marcadas como builtin, o que faz com que elas não exijam uma declaração opaque ou gate , mas ignoram silenciosamente uma declaração compatível. De qualquer forma, é um erro fornecer uma instrução personalizada que tenha um número diferente de parâmetros ou qubits como uma instrução definida em um programa analisado. Cada elemento do argumento iterável deve ser uma classe de dados específica:

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)

Isso pode ser particularmente útil ao tentar resolver ambiguidades nas convenções de fase global de um programa OpenQASM 2. Consulte OpenQASM 2 Convenções de fase para obter mais detalhes.

Especificando funções clássicas personalizadas

De forma semelhante às extensões quânticas acima, você também pode estender o processamento feito para expressões clássicas (argumentos para gates) passando um iterável para o argumento custom_classical para qualquer um dos carregadores. Isso requer o name (um identificador OpenQASM 2 válido), o número num_params de parâmetros necessários e um Python chamável que implemente a função. O chamável Python deve ser capaz de aceitar num_params argumentos de ponto flutuante posicional e deve retornar um ponto flutuante ou um número inteiro (que será convertido em um ponto flutuante). As funções incorporadas não podem ser substituídas.

CustomClassical

Modo estrito

Ambas as funções do carregador têm um modo "estrito" opcional. Por padrão, esse analisador é um pouco mais relaxado do que a especificação oficial: ele permite vírgulas finais em listas de parâmetros; pontos e vírgulas desnecessários (declaração vazia); a declaração da versão OPENQASM 2.0; a ser omitida; e algumas outras melhorias de qualidade de vida sem emitir nenhum erro. Você pode usar o modo de letra de especificação com strict=True.

API de exportação

Semelhante a outros módulos de serialização em Python, esse módulo oferece duas funções públicas: dump() e dumps()que recebem um QuantumCircuit e escrevem um programa OpenQASM 2 representativo em um objeto do tipo arquivo ou retornam uma string, respectivamente.

dump

dumps

Erros

Este módulo define um tipo de erro genérico que deriva de QiskitError que pode ser usado como uma captura quando você se preocupa especificamente com as falhas emitidas pela camada de interoperação.

QASM2Error

Nos casos em que o lexer ou o analisador falhar devido a um arquivo OpenQASM 2 inválido, as funções de conversão gerarão um erro mais específico com uma mensagem explicando qual é a falha e em que parte do arquivo ela ocorreu.

QASM2ParseError

Quando os exportadores não conseguirem exportar um circuito, provavelmente porque ele tem uma estrutura que não pode ser representada por OpenQASM 2.0, eles também emitirão um erro personalizado.

QASM2ExportError

Exemplos

Exportando exemplos

Exportar um simples QuantumCircuit para uma cadeia de caracteres 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];

Escreve o mesmo QuantumCircuit em um determinado nome de arquivo:

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

Da mesma forma, é possível usar instâncias gerais os.PathLike como nome de arquivo:

import pathlib

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

Também é possível despejar o texto em um fluxo já aberto:

import io

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

Exemplos de análise sintática

Usar loads() para importar um programa OpenQASM 2 em uma cadeia de caracteres para um arquivo 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

É possível fazer a mesma coisa se o programa estiver armazenado em um arquivo usando load() em vez disso, passando o nome do arquivo como um argumento:

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

OpenQASM 2 podem incluir outros arquivos OpenQASM 2 por meio da instrução include . Você pode influenciar o caminho de pesquisa usado para localizar esses arquivos com o argumento include_path em ambos os comandos load() e loads(). Por padrão, somente o diretório de trabalho atual é pesquisado.

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

Somente para load() há um argumento extra include_input_directory, que pode ser usado para 'append', 'prepend' ou ignorar (None) o diretório do arquivo carregado no caminho de inclusão. Por padrão, esse diretório é anexado ao caminho de pesquisa, portanto, é tentado por último, mas você pode alterar isso.

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
]

Às vezes, você pode querer influenciar os objetos Gate que o importador emite para determinadas instruções nomeadas. As portas definidas pela instrução include "qelib1.inc"; serão automaticamente associadas a uma porta adequada da biblioteca de circuitos Qiskit, mas você pode estender isso:

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)

Da mesma forma, você pode adicionar novas funções clássicas usadas durante a descrição dos argumentos para as portas, tanto no corpo principal do programa (que são dobradas de forma constante) quanto nos corpos das portas definidas (que são computadas sob demanda). Aqui, fornecemos uma versão Python de atan2(y, x), que matematicamente é $\arctan(y/x)$, mas que lida corretamente com quadrantes angulares e infinitos, e uma função personalizada add_one :

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 Convenções de 2 fases

Como linguagem, o OpenQASM 2 não tem uma maneira de especificar a fase global de um programa completo, nem de definições de portas específicas. Isso significa que os analisadores da linguagem podem interpretar determinadas portas com uma fase global diferente da esperada. Por exemplo, a biblioteca padrão de fato de OpenQASM 2 qelib1.inc contém definições de u1 e rz da seguinte forma:

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

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

Em outras palavras, rz parece ser um alias direto de u1. No entanto, a interpretação de u1 é especificada na equação (3) do documento que descreve a linguagem como

onde o símbolo $\sim$ denota equivalência somente até uma fase global. Ao analisar OpenQASM 2, precisamos escolher como lidar com uma distinção entre esses portões; u1 é definido na prosa como sendo diferente por uma fase de rz, mas a linguagem não foi projetada para representar isso.

A posição padrão do Qiskit é interpretar um uso da biblioteca padrão rz usando RZGatee um uso de u1 como usando a distinção de fase U1Gate. Se desejar usar as convenções de fase mais implícitas por uma interpretação direta das instruções gate no arquivo de cabeçalho, você poderá usar CustomInstruction para substituir a forma como o Qiskit constrói o circuito.

Para o padrão qelib1.inc include, há apenas um ponto de diferença e, portanto, a substituição necessária para mudar sua convenção de fase é:

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

Isso usará a classe PhaseGate para representar a instrução rz , que é igual (incluindo a fase) a 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,))

Compatibilidade com versões anteriores

QuantumCircuit.from_qasm_str() e from_qasm_file() usado para fazer alguns acréscimos sobre a especificação bruta. Originalmente, o Qiskit tentou usar o OpenQASM 2 como um tipo de formato de serialização e expandiu seu comportamento à medida que o Qiskit se expandia. O novo analisador, com todos os seus padrões, implementa a especificação de forma mais rigorosa.

Em particular, nos importadores de legado:

• o include_path é eficaz:

  1. <qiskit>/qasm/libs, em que <qiskit> é a raiz do pacote qiskit instalado;
  2. O diretório atualmente em funcionamento.

• há instruções adicionais definidas em qelib1.inc:

  csx a, b

  Controlado $\sqrt X$ gate, correspondente a CSXGate.

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

  A versão de quatro parâmetros de um controle- $U$, correspondente a CUGate.

  rxx(theta) a, b

  Rotação de dois qubits em torno do eixo $XX$, correspondente a RXXGate.

  rzz(theta) a, b

  Rotação de dois qubits em torno do eixo $ZZ$, correspondente a RZZGate.

  rccx a, b, c

  A porta $X$ com controle duplo, mas com diferenças de fase relativas em relação à porta Toffoli padrão. Isso deve corresponder ao Qiskit gate RCCXGatemas o conversor legado não produziria de fato esse tipo.

  rc3x a, b, c, d

  A porta $X$ com controle triplo, mas com diferenças de fase relativas em relação à definição padrão. Corresponde a RC3XGate.

  c3x a, b, c, d

  A porta $X$ com controle triplo, correspondente a C3XGate.

  c3sqrtx a, b, c, d

  A porta $\sqrt X$ com controle triplo, correspondente a C3SXGate.

  c4x a, b, c, d, e

  O portão de controle quádruplo $X$.., correspondente a C4XGate.

• se alguma definição de opaque ou gate foi dada para o nome delay, eles tentam emitir uma Delay em cada chamada. Para funcionar, espera-se uma definição compatível com opaque delay(t) q;, em que o tempo t é dado em unidades de dt. O importador gerará erros na construção se não houver exatamente um parâmetro e um qubit, ou se o parâmetro não tiver valor inteiro.

• as funções adicionais de calculadora científica asin, acos e atan estão disponíveis.

• a gramática analisada é efetivamente a mesma que o modo estrito dos novos importadores.

Você pode emular esse comportamento em load() e loads() configurando include_path adequadamente (tente inspecionar a variável qiskit.__file__ para encontrar o local instalado) e passando uma lista de instâncias de CustomInstruction para cada uma das portas personalizadas que lhe interessam. Para facilitar as coisas, disponibilizamos três tuplas, cada uma contendo um componente de uma configuração que é equivalente ao comportamento do conversor legado do Qiskit.

qiskit.qasm2.LEGACY_CUSTOM_INSTRUCTIONS

qiskit.qasm2.LEGACY_CUSTOM_CLASSICAL

qiskit.qasm2.LEGACY_INCLUDE_PATH

Em todas as portas definidas na versão legada do Qiskit do qelib1.inc e na instrução delay , não importa como as portas são de fato definidas e usadas, o importador legado sempre tentará gerar seus objetos personalizados para elas. Isso pode resultar em erros durante a construção do circuito, mesmo após uma análise bem-sucedida. Não há como emular esse comportamento problemático com o qiskit.qasm2somente uma instrução include "qelib1.inc"; ou o argumento custom_instructions pode fazer com que as instruções integradas do Qiskit sejam usadas, e as assinaturas dessas instruções são iguais.

Alternativas

Os componentes do analisador deste módulo começaram como um pacote PyPI separado: qiskit-qasm2. Esse pacote na versão 0.5.3 foi vendido para o Qiskit Terra 0.24. Quaisquer alterações subsequentes entre os dois pacotes podem não ser necessariamente mantidas em sincronia.

Há uma versão mais recente da especificação OpenQASM, a versão 3.0, que é descrita em https://openqasm.com. Isso inclui muito mais recursos para programação clássica de alto nível. O Qiskit já tem algum suporte rudimentar para OpenQASM 3; consulte qiskit.qasm3 para isso.

OpenQASM 2 não é uma linguagem de serialização adequada para o Qiskit QuantumCircuit. Esse módulo é fornecido para fins de interoperabilidade, não como um formato de serialização geral. Se for isso que você precisa, considere usar qiskit.qpy em vez disso.