Unified API to import/export circuits in Qiskit

[1ucian0]

Description

There are several way to import and export circuit to and from Qiskit, being OpenQASM2 the most popular one. However, in order to improve interoperability with 3rd parties, we need to organize that a bit. The first stage is to move all the qasm2-related code we have around into a qiskit.qasm2 module. After that, we can take other serializer like https://github.com/jwoehr/nuqasm2 or Qiskit/qiskit#5578.

Mentor/s

@1ucian0

Type of participant

A good python coder. If you have knowledge on design patterns, even better.

Number of participants

1

Deliverable

A Qiskit PR (or several)

[HuangJunye]

@jwoehr Can you comment on this issue so that I can assign you? Please also work with your mentor to refine the project, define scope and deliverables and update the project description in this issue.

[jwoehr]

@1ucian0 and I met on this today.

Our goal in the context of the mentor experience is to separate QASM into its own module and unify its programmatic usage around a functional syntax.

We will implement this with QASM2 and lay the groundwork for QASM3 to inherit this architecture.

Quick notes from our shared document:

• QASM2
  • Putting it in its own module (not package)
  • from qiskit.qasm2 import dump, load
  • dump(QuantumCircuitObject) -> str # i.e., a qasm2 string
  • load either qasm2 source or frozen circuit per QPY Add qpy serialization format Qiskit/qiskit#5578
  • Stop having gate.qasm(). but allow a custom gate._qasm() for special cases
    • move the logic currently handled by gate.qasm() into import/export functional interface
      • said logic will test for existence of a hand-rolled gate._qasm() special case before defaulting to its own methods
    • deprecate but preserve for now the gate.qasm() syntax by delegation to the new functional interface
  • Actual qasm translator(s) should be pluggable.
    • Qiskit native qasm
    • https://github.com/jwoehr/nuqasm2 importer
    • https://github.com/eddieschoute/openqasm-parser/tree/master/openqasm importer
• QASM3
  • TBD if we get this far in the mentor experience

[jwoehr]

We also discussed the following tangential QASM desideratum:

• Control Flow Support
  • support for simple control flow in circuits Qiskit/qiskit#5898
  • IR (DAG) should support this first
  • Export control flow into QASM3

[jwoehr]

• added @1ucian0 as collaborator on my fork of Terra jwoehr /qiskit-terra
• created branch unified_qasm_api

Next I will dig up my work on the functional API as a module of Terra from last year or recreate it from what we left in 1ucian0 /qiskit-openqasm2 (which was qasm2 as a package) and check it into the unified_qasm_api branch.

[jwoehr]

Have recreated the qasm2 module in the unified_qasm_api in the jwoehr /qiskit-terra fork.
It passes tox.

[jwoehr]

Updated the functional interface for export() in the jwoehr/qiskit-terra fork to match the code now found in QuantumCircuit

[jwoehr]

@1ucian0 and @jwoehr met today:

Coding assignment

• Work towards a PR based on the qasm2 module
  • Remove pluggable importer/exporter support from functions.py
  • Make sure imports come from correct module? (qasm2 vs qasm)
  • Remove duplicated code from QuantumCircuit and deprecate the qasm methods in that class in favor of the functional interface

Design of Qasm2 and Qasm3

• We discussed redesigning Qasm2 parse-compile architecture to rationalize/simplify it
  • AST but no DAG (like nuqasm2)
  • The related question of whether load() and export() share core code or are totally separate operations
    • The current status is that they simply move extant code from QuantumCircuit to the new qasm2 module
    • Fully implemented it is worth at least some re-architecture
  • The value of Qasm2 in light of Qasm3
    • The value does exist as an export format
    • Is Qasm2 a pure subset of Qasm3?
• We discussed Qasm3
  • Can we re-engineer Qasm2 in such a way as it merges with the Qasm3 code effort
    • Avoid 2 completely separate code bodies
    • Inform the evolving spec for Qasm3 so that it doesn't exclude such subset treatement
• @jwoehr will start following the Qasm3 discussion more closely and look at the extant Qasm2 architecture with an eye to unification of the efforts, if practical

[jwoehr]

Opened openqasm/openqasm#162

[jwoehr]

In unified_qasm_api branch of jwoehr /qiskit-terra

• Removed duplicated code from QuantumCircuit now that the logic is in qiskit.qasm2.functions
• Recast functions in QuantumCircuit to call qiskit.qasm2.functions
• Moved the Pygments code back into QuantumCircuit from qiskit.qasm2.functions
• Deprecated appropriately in QuantumCircuit for those functions that are simply stubbed to qiskit.qasm2.functions
• Changed imports globally in Terra to load from qiskit.qasm2

[jwoehr]

Added a release note.
@1ucian0 , if we are going to PR before proceeding to change the .qasm() / ._qasm() logic of individual operators, now is the time to do it. Or if you want me to proceed to that further stage of development, please let me know.

[HuangJunye]

Awesome work @jwoehr Thanks for sharing all the updates for the project. Looks really exciting!

[jwoehr]

Thanks for kind words. Just having fun :)

[jwoehr]

Created PR #6053

[jwoehr]

Next idea:

def _circuit_from_qasm(qasm):
    # pylint: disable=cyclic-import
    from qiskit.converters import ast_to_dag
    from qiskit.converters import dag_to_circuit
    ast = qasm.parse()
    dag = ast_to_dag(ast)
    circuit = ast_to_circuit(ast)
    assert circuit == dag_to_circuit(dag)
    return dag_to_circuit(dag)

[jwoehr]

Our discussion today was ideas to tidy up Qasm2 awaiting advent of Qasm3.

• Load Qasm2
  • New parser <- subset of proposed Qasm3 ANTLR grammar?
  • AST -> Circuit, no DAG (see previous comment )
  • Save info on custom gate definitions and parameter bindings to QuantumCircuit metadata
• Export Qasm2
  • QuantumCircuit to AST, then AST to Qasm string?
  • Recognize custom gate definitions and parameter bindings from new QuantumCircuit metadata fields per above

[jwoehr]

Meeting today with Dr. Bello

• Goal still DAG-free direct AST-to-QuantumCircuit assembly of openqasm2
• Use openqasm3 ANTLR grammar as a model for a revised openqasm2 parser
  • grammar subdir of qiskit-terra/qiskit/qasm2 contain grammar and all generated files
  • add antlr4 to pip requirements for qiskit-terra
  • OpenQASM 2.x standard specifies code annotations may appear in comments
    • implement this feature: how?
      • either the parse must retain comments and the compiler hold the grandparent node until done with entire branch, or
      • concept of decorator marker in comment containing annotation must be retroactively introduced
• As far as the unified import/export, may be changed from load() and export() to load() and dump().

[jwoehr]

Branched unified_qasm_api branch to grammar branch

[jwoehr]

Meeting today with Dr. Bello

Qiskit QuantumCircuit objects need to output themselves as OpenQASM 3.

This brings some facets of the implementation to the forefront.

• The qelib1.inc is not actually used by the OpenQASM 2 translator.
• In a new PR standard gates in qiskit in its own inc file #6125 qelib1.inc is returned to its original specification and the accretions are moved to qiskit/qasm/libs/standard_gates.inc
• Is qasm compilation and decompliation [load() and export() [or dump()]] in the future going to:
  • Go directly to QuantumCircuit for the standard gates?
  • Use the include libraries as a reference?
  • Unroll gate invocations using the libraries or jump to the composite operations in QuantumCircuit?
  • In export, unroll or use the high-level names for gates?
    • This can be a user choice, e.g., "sincere" or "insincere" mood.
• Currently, each gate method in QuantumCircuit is responsible to know its own qasm representation. There is some interest in modifying this arrangement to make things simpler for gate authors.
• Is there some restructuring of QuantumCircuit that would make load and export operations more mutually symmetrical?

Progress in the past week

As our mentorship midterm checkpoint presentation will show, we have a grammar branch of qiskit.qasm2 that implements OpenQASM 2 ANTLR parsing using essentially the new OpenQASM 3 grammar. It's not a long journey from that to a translator using this new grammar. At present, the intention is to continue work on Qiskit/qiskit-terra#6089 using the OpenQASM 3 grammar, ignoring or raising if features unsupported by OpenQASM 2 are invoked. If in the future the OpenQASM 3 grammar diverges too much from being a pure superset of OpenQASM 2 we will part ways with that definition.

Plan for coming week

• Continue to work on ANTLR-based implementation of OpenQASM 2
• Assist / coordinate with Dr. Bello on export to OpenQASM 3.

[jwoehr]

Meeting with Dr. Bello 2021-04-09

• Move forward with qasm2 code translator based on ANTLR 4 grammar.
• Examine if possible to what extent gates are actually parsed from qelib1.inc and/or from any other file includeed by the programmer and move to regularize this in the new qasm2 code translator.
  • Keep in mind that changing the way include actually operates could break test cases if formal definitions found in qelib1.inc and/or the new standard_gates.inc have been superseded by inline code in the Qiskit libraries.
• If possible, move towards implementation of pragma-bearing comments, e.g., with a decorator ( // @ ) for instance.

[jwoehr]

Notes before meeting with Dr. Bello scheduled for 2021-04-16:

• Discussion of pragmas in OpenQASM 2 comments
  • In 3.0 grammar, comments are skip
• Include path
  • Is implemented in nuqasm2 and was originally in unified API as first presented in 2020 but later discarded
    • Not sure how "really using" includes in OpenQASM 2 is going to work without this?
• Ongoing implementation of qasm2 ANTLR-parsed AST will be rich in info that could be stored in a metadata dictionary inQuantumCircuit
  • w/r/t going from parse tree to custom AST instead of directly to code generation, that is the design pattern recommended by Terence Parr, the author of ANTLR.

[jwoehr]

Meeting 2021-04-16 with Dr. Bello

• Continue implementing qasm2 parse -> AST
• AST -> code generation may be a direct port from nuqasm2
• Support \\@ metacomments

[omarcostahamido]

oh la la, this is interesting!

(just commenting here so that I can receive the notifications and learn a bit as well ^^)

since you're rewriting the qasm parser can you include a tiny fix update for #6169?

[1ucian0]

Maybe a possible use for PRAGMAs? Something like:

OPENQASM 2.0;
include "qelib1.inc";

//@ QISKIT_DEFINITION initialize(x0, x1, x2, x3) q0, q1;
opaque initialize2(x0, x1, x2, x3) q0, q1;

//@ QISKIT_DEFINITION initialize(x0, x1) q0;
opaque initialize1(x0, x1) q0;

qreg q[3];

initialize2(0,1,0,0) q[0],q[1];
initialize1(0,1) q[2];

where //@ QISKIT_DEFINITION means "take the qiskit definition instead".

[jwoehr]

Meeting 2021-04-16 with Dr. Bello

• Continue implementing qasm2 parse -> AST
• AST -> code generation may be a direct port from nuqasm2
• Support \\@ metacomments

[jwoehr]

Progress up to 2021

The qasm2 file:

// yiqing_5.qasm
// This is a version of yiqing_simple declared as 5 qubits
// so that it will run on the QuantumInspire Starmon-5 QPU
OPENQASM 2.0;
include "qelib1.inc";
qreg q[5];
creg c[5];
h q[0];
h q[1];
h q[2];
// h q[3];
// h q[4];
measure q[0] -> c[0];
measure q[1] -> c[1];
measure q[2] -> c[2];
// measure q[3] -> c[3];
// measure q[4] -> c[4];

... using the new antlr4 stuff yields an AST as follows:

{'CSect': [None,
           None,
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumDeclarationContext object at 0x7f28f1979890>,
            'filenum': 0,
            'index_identifier_list': ['q[5]'],
            'linenum': 6,
            'quantum_type': 'qreg'},
           {'bit_type': 'creg',
            'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.ClassicalDeclarationContext object at 0x7f28f1942970>,
            'filenum': 0,
            'index_identifier_list': ['c[5]'],
            'linenum': 7},
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.SubroutineCallContext object at 0x7f28f1955510>,
            'expression_list': ['q[0]'],
            'filenum': 0,
            'linenum': 8,
            'op': 'h'},
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.SubroutineCallContext object at 0x7f28f1921040>,
            'expression_list': ['q[1]'],
            'filenum': 0,
            'linenum': 9,
            'op': 'h'},
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.SubroutineCallContext object at 0x7f28f19215f0>,
            'expression_list': ['q[2]'],
            'filenum': 0,
            'linenum': 10,
            'op': 'h'},
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumMeasurementAssignmentContext object at 0x7f28f1921c80>,
            'filenum': 0,
            'index_identifier_list': ['q[0]', 'c[0]'],
            'linenum': 13},
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumMeasurementAssignmentContext object at 0x7f28f192e2e0>,
            'filenum': 0,
            'index_identifier_list': ['q[1]', 'c[1]'],
            'linenum': 14},
           {'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumMeasurementAssignmentContext object at 0x7f28f192e900>,
            'filenum': 0,
            'index_identifier_list': ['q[2]', 'c[2]'],
            'linenum': 15}],

... etc ... GSect SSect TSect not shown above.
(The None, None at the head of the CSect is an"unfinished stuff" bug)

Qasm 2 Metacomments

I'm also ready to propose about metacomments. Good example from Slack user requirement:
\\@ parameters #P1 #P2 ...

Qasm3 already uses @ and $ (too much 😄). So I'm going to suggest # for params.

• They have to be declared as above before they appear in the code.
• At load time the values are passed in via a kwarg, e.g., ... parameters={'P1': 1234, 'P2': np.pi}
• Every instance of #P1 or #P2 in the Qasm code gets substituted according to the kwarg.

My task list

1. Finish AST code section.
2. Do AST gate section (then basic AST will be complete).
3. Create class Qasm2Loader which will expose methods employed by the functional interface load().
4. Modify grammar to support metacomments.
5. Implement metacomments in Qasm2Listener and Qasm2Loader.

[jwoehr]

(The None, None at the head of the CSect is an"unfinished stuff" bug)

Fixed

[1ucian0]

\\@ parameters #P1 #P2
OPENQASM 2.1  <-- maybe a good reason to increment this minor?
...
u1(#P1) q[0];   <-- does pytket support #P1 or P1 ?

[1ucian0]

OPENQASM 2.0;
include "qelib1.inc";

qreg q[1];

//@ QISKIT_DEFINITION HGate;
h q[0];

OPENQASM 2.0;
include "qelib1.inc";

qreg q[1];

//@ qelib1.inc;
h q[0];

[1ucian0]

load(include_path=[<custom location>, <default location>])

[jwoehr]

Progress for week ending 2021-04-30

1. Created class Qasm2Loader implementing:
   • Qasm2Loader.ast_qasm_str()
   • Qasm2Loader.ast_qasm_file()
2. Modified grammar to support metacomments.
   • For now using /@ to avoid modifying extant sections of qasm antlr4 grammar
3. Implemented metacomments in Qasm2Listener and Qasm2Loader.
   • They appear in the Code section directly before the code statements they precede.

[jwoehr]

Meeting with Dr. Bello 2021-04-30

Jack's task list

• Change "metacomment" to "annotation".
  • Remember the initialize/initialize2 use case raised by Dr. Bello earlier in this issue.
• Continue with Gate section of AST
• When that is done, start on translator

[jwoehr]

Meeting with Dr. Bello 2021-05-07

• Use qasmlexer method of loading qelib1.inc.
• Raise exception on circular includes.
• Recognize and ignore repeated includes.
• Use black to format code to avoid merge weirdness.
• Translation search gate section reversed so latest definition obtains.
• Add option for use standard library gate vs prefer gate definition in gate section.
• Gate expansion (lazy, on invocation)
  • create a (parameterized) QuantumCircuit
  • instance that circuit as Gate
  • insert gate into translation's QuantumCircuit

[jwoehr]

Progress week ending 2021-05-07

• Gate Section implemented
• Include path search implemented and modified to correctly use core libs path when loading default includes from default path
  • The above includes options to ignore default path and load known default includes from regular include path

[jwoehr]

Progress week ending 2021-05-14

• New Qasm2Translator class
  • translates
    • qubit and clbit declarations
    • standard gates without parameters
    • metacomments
  • profiles on demand
• Modified Code Section
  • deletes expression_list field
  • adds
    • parameter_list field
    • target_list field
• Modified Gate Section holds
  • compiled gate field
  • op field
  • reversed order in Gate Section as we'll want the latest/last definition of a gate which is multiply defined.
    • Qasm2Ast.find_latest_gatedef()
• Other minor changes to AST
• Updated to latest cut of Qasm 3 grammar and backported to our qasm2 grammar
  • Modified Qasm2Listener accordingly
  • Found anomaly in qasm3 grammar and made PR subsumed by openqasm #190 by zachschoenfeld33
• Currently researching
  • How to evaluate mathematical parameter expressions
  • How to translate opaque
• Going forward
  • JIT compile gate definitions

[jwoehr]

Meeting 2021-05-14 with Dr. Bello

• QuantumCircuit op lookup can't be directly from __dict__, need lookup table
• Can fill in gate defs in that lookup table as they are JIT compiled
• Pull into grammar branch from its branch parent unified_qasm_api to avoid merge conflicts.

[jwoehr]

Progress for week ending 2021-05-21

• Updated to latest cut of Qasm 3 grammar and backported to our qasm2 grammar
  • Modified Qasm2Listener accordingly
• Only pass ops which exist in the standard list to QuantumCircuit
  in Qasm2Translator.apply_standard_gate()

[jwoehr]

Meeting 2021-05-21

Examined how to bind parameter expressions at translate time.

Example code:

from qiskit.circuit import Parameter, QuantumCircuit
phi = Parameter("phi")
jax = QuantumCircuit(2, name='jax')
jax.u1(phi/2, 1)

binded_jax = jax.bind_parameters({phi:8})

circuit = QuantumCircuit(3)
circuit.append(binded_jax.to_gate(), [1, 2])

circuit.draw()
circuit.decompose().draw()

import numpy as np
binded_jax = jax.bind_parameters({phi:np.pi})
circuit.append(binded_jax.to_gate(), [1, 2])

[jwoehr]

Progress week ending 2021-06-04

• Updated to latest cut of Qasm 3 grammar and backported to our qasm2 grammar
  • Modified Qasm2Listener accordingly
• Translator now does standard gates with float params (need to work on evaluating expressions and trig)
  • Example:

  >>> qc.draw()
     ┌───────────┐┌────────────────────┐
q_0: ┤ U3(1,2,3) ├┤ U3(2.1,3.2,4.3346) ├
     └───────────┘└────────────────────┘
q_1: ───────────────────────────────────
                                        
c: 2/═══════════════════════════════════
                                        
>>> qc.decompose().draw()
     ┌──────────┐┌───────────────────┐
q_0: ┤ U(1,2,3) ├┤ U(2.1,3.2,4.3346) ├
     └──────────┘└───────────────────┘
q_1: ─────────────────────────────────
                                      
c: 2/═════════════════════════════════

• AST for Gate definitions better formulated, example:

 {'filenum': 1,
  'linenum': 63,
  'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumGateDefinitionContext object at 0x7fd14b778430>,
  'op': 'ch',
  'declaration': ['ch', 'a,b'],
  'parameter_list': [],
  'target_list': ['a', 'b'],
  'definition': [{'op': 'h', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 'sdg', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 'cx', 'parameter_list': [], 'target_list': ['a', 'b']},
                 {'op': 'h', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 't', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 'cx', 'parameter_list': [], 'target_list': ['a', 'b']},
                 {'op': 't', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 'h', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 's', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 'x', 'parameter_list': [], 'target_list': ['b']},
                 {'op': 's', 'parameter_list': [], 'target_list': ['a']}],
  'gate': None},
 {'filenum': 1,
  'linenum': 89,
  'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumGateDefinitionContext object at 0x7fd14b77ff90>,
  'op': 'crx',
  'declaration': ['crx', '(', 'lambda', ')', 'a,b'],
  'parameter_list': ['lambda'],
  'target_list': ['a', 'b'],
  'definition': [{'op': 'u1', 'parameter_list': ['pi/2'], 'target_list': ['b']},
                 {'op': 'cx', 'parameter_list': [], 'target_list': ['a', 'b']},
                 {'op': 'u3',
                  'parameter_list': ['-lambda/2', '0', '0'],
                  'target_list': ['b']},
                 {'op': 'cx', 'parameter_list': [], 'target_list': ['a', 'b']},
                 {'op': 'u3',
                  'parameter_list': ['lambda/2', '-pi/2', '0'],
                  'target_list': ['b']}],
  'gate': None},
 {'filenum': 1,
  'linenum': 7,
  'ctx': <qiskit.qasm2.grammar.qasm2Parser.qasm2Parser.QuantumGateDefinitionContext object at 0x7fd14b7eaeb0>,
  'op': 'u3',
  'declaration': ['u3', '(', 'theta,phi,lambda', ')', 'q'],
  'parameter_list': ['theta', 'phi', 'lambda'],
  'target_list': ['q'],
  'definition': [{'op': 'U',
                  'parameter_list': ['theta', 'phi', 'lambda'],
                  'target_list': ['q']}],
  'gate': None}

• Work on gate_def_for_gate() and gate_def_to_gate()
• Made slide deck and video for mentorship final showcase

[omarcostahamido]

to the point. Looks very nice 😄

[jwoehr]

The new OpenQASM 2 translator based on the OpenQASM 3 grammar works more or less completely now.

OPENQASM 2.0;
include "qelib1.inc";
qreg q[3];
creg c[3];
u3(1,1.5707963267948966,3) q[0];
u3(2.1,3.2,4.33456) q[0];
u3(pi/2, 2+3, pi) q[0];
cx q[0], q[1];
barrier q;
barrier q[0];
barrier q[1];
barrier q[1];
barrier q[0], q[1];
measure q[0] -> c[0];
measure q[1] -> c[1];
measure q[0:2] -> c[0:2];
measure q -> c;
     ┌─────────────┐┌────────────────────┐┌─────────────┐      ░  ░     ░ ┌─┐   ┌─┐   ┌─┐   
q_0: ┤ U3(1,π/2,3) ├┤ U3(2.1,3.2,4.3346) ├┤ U3(π/2,5,π) ├──■───░──░─────░─┤M├───┤M├───┤M├───
     └─────────────┘└────────────────────┘└─────────────┘┌─┴─┐ ░  ░  ░  ░ └╥┘┌─┐└╥┘┌─┐└╥┘┌─┐
q_1: ────────────────────────────────────────────────────┤ X ├─░──░──░──░──╫─┤M├─╫─┤M├─╫─┤M├
                                                         └───┘ ░ ┌─┐ ░  ░  ║ └╥┘ ║ └╥┘ ║ └╥┘
q_2: ──────────────────────────────────────────────────────────░─┤M├───────╫──╫──╫──╫──╫──╫─
                                                               ░ └╥┘       ║  ║  ║  ║  ║  ║ 
c: 3/═════════════════════════════════════════════════════════════╩════════╩══╩══╩══╩══╩══╩═
                                                                  2        0  1  0  1  0  1