Document content of the standard library #517

jakelishman · 2024-03-15T00:09:26Z

Summary

This describes the effects of the stdgates.inc include file as part of the language specification. I deliberately did not include the examples/stdgates.inc version of it in the specification to avoid implications that it must be implemented with that manner, but attempted to explain how implementations must behave as if if were defined like this, so that implementations are free to interpret the file in terms of defcal statements or the like (if they were to so choose).

~~This commit also includes a brief Sphinx extension, to make it possible to document OpenQASM gates in the full Sphinx structure.~~ edit: now split off into https://github.com/openqasm/openqasm-sphinx and the openqasm-sphinx Python distribution.

Details and comments

Close #516.

The text here is largely just a first draft - happy for any suggestions to the requirements, or different ways of presenting things.

It probably makes sense for me to split of the Sphinx extension into a separately installable Python package, but just for the purposes of demoing this PR, I've included it inline here. If we want it, I'll sort out the legal stuff for my work on it on the IBM side (since here, it's just folded into the licensing for this repo) and move it into a separate repo. The current implementation is bare bones and just enough to document what I needed to. edit: Done as of 2024-04-09.

This describes the effects of the `stdgates.inc` include file as part of the language specification. I deliberately did not include the `examples/stdgates.inc` version of it in the specification to avoid implications that it *must* be implemented with that manner, but attempted to explain how implementations must behave *as if* if were defined like this, so that implementations are free to interpret the file in terms of `defcal` statements or the like (if they were to so choose). This commit also includes a brief Sphinx extension, to make it possible to document OpenQASM gates in the full Sphinx structure.

source/_extensions/oq_domain.py

hodgestar

Overall this looks good to me.

source/language/standard_library.rst

jlapeyre · 2024-03-20T15:19:23Z

source/language/standard_library.rst

+the rest of the program under.
+
+Implementations must not define gates that are not present in chosen OpenQASM 3 version, where
+doing so could cause a user program to be ill formed (for example due to a user attempting to define


Wouldn't any other gate definition potentially (silently) conflict with a user's gate definition?

The intention was to allow "implementation magic" to make extension gates available iff a user didn't later define them, such as to make later gates from later library versions available in an older program as a convenience mode - since the language syntax and library version are linked, it's plausible that somebody might want to write a program for older syntax but use a later library version, and accept that they're tied to a particular implementation. That can't be spelled in OpenQASM 3 in user programs, but implementations can / often do magic in the standard library.

I'm not precious about this proviso - I'm fine to drop it, since it would rely on implementation extensions anyway.

source/language/standard_library.rst

The biggest change in openqasm3_parser is in handling stdgates.inc. Upon encountering `include "stdgates.inc" openqasm3_parser reads no file, but rather adds symbols to the symbol table for gates in the standard library. The function `convert_asg` in the importer calls oq3_semantics::symbols::SymbolTable.gates which returns a `Vec` of information about each "declared" gate. The information is the gate's name and signature and SymbolID, which is sufficient to do everything the importer could do before this commit. Encountering `Stmt::GateDefinition` now is a no-op rather than an error. (This was previously called `Stmt::GateDeclaration`, but importantly it is really a definition.) How the standard library, and gates in general, are handled will continue to evolve. A behavioral difference between this commit and its parent: Before if the importer encountered a gate call before the corresponding definition an error would be raised. With the current commit, the importer behaves as if all gate definitions were moved to the top of the OQ3 program. However, the error will still be found by the parser so that the importer never will begin processing statements. The importer depends on a particular branch of a copy of openqasm3_parser. When the commit is ready to merge, we will release a version of openqasm3_parser and depend instead on that release. See openqasm/openqasm#517

This commit adds no new features or capabilities to the importer. But it brings the importer up to date with the latest version of openqasm3_parser as a preliminary step in improving the importer. The biggest change in openqasm3_parser is in handling stdgates.inc. Upon encountering `include "stdgates.inc" openqasm3_parser reads no file, but rather adds symbols to the symbol table for gates in the standard library. The function `convert_asg` in the importer calls oq3_semantics::symbols::SymbolTable.gates which returns a `Vec` of information about each "declared" gate. The information is the gate's name and signature and SymbolID, which is sufficient to do everything the importer could do before this commit. Encountering `Stmt::GateDefinition` now is a no-op rather than an error. (This was previously called `Stmt::GateDeclaration`, but importantly it is really a definition.) How the standard library, and gates in general, are handled will continue to evolve. A behavioral difference between this commit and its parent: Before if the importer encountered a gate call before the corresponding definition an error would be raised. With the current commit, the importer behaves as if all gate definitions were moved to the top of the OQ3 program. However, the error will still be found by the parser so that the importer never will begin processing statements. The importer depends on a particular branch of a copy of openqasm3_parser. When the commit is ready to merge, we will release a version of openqasm3_parser and depend instead on that release. See openqasm/openqasm#517

source/language/standard_library.rst

Co-authored-by: John Lapeyre <jlapeyre@users.noreply.github.com>

source/language/standard_library.rst

hodgestar · 2024-04-10T08:06:59Z

@jakelishman I'm done with my re-review. Apologies for the delay

Co-authored-by: Simon Cross <hodgestar+github@gmail.com>

jakelishman · 2024-04-10T13:56:38Z

Simon: I've pushed up 42fd895 that includes formal mathematics (deliberately avoiding the complications arising from a matrix representation) and symbol definitions for all the maps, so it's unambiguous what the mathematical symbols mean. Let me know if there's more you want.

hodgestar

Looks good to me.

levbishop · 2024-04-17T15:22:38Z

source/language/standard_library.rst

+      \texttt{crz(θ) a, b;} \mathit{CRZ}_{ba}(\theta)\colon\ \left\{\begin{alignedat}[c]2
+         {\lvert00\rangle}_{ba} &{}\to{}& &{\lvert00\rangle}_{ba}\\
+         {\lvert01\rangle}_{ba} &{}\to{}& e^{-i\theta/2} &{\lvert01\rangle}_{ba}\\
+         {\lvert10\rangle}_{ba} &{}\to{}& &{\lvert10\rangle}_{ba} \vphantom{e^{i\theta/2}}\\


The \vphantom confuses github's rst viewer. But I'm ok with it so long as it looks right in the rendered file

MathJax handles it fine. I was just being silly about the line spacings all coming out looking the same...

Sample rendering

... and that picture just made me realise there's a typo in the inlined version of the CRX action. Fixed in 0b74092.

…12087) * Adapt crates/qasm3 to work with recent versions of openqasm3_parser This commit adds no new features or capabilities to the importer. But it brings the importer up to date with the latest version of openqasm3_parser as a preliminary step in improving the importer. The biggest change in openqasm3_parser is in handling stdgates.inc. Upon encountering `include "stdgates.inc" openqasm3_parser reads no file, but rather adds symbols to the symbol table for gates in the standard library. The function `convert_asg` in the importer calls oq3_semantics::symbols::SymbolTable.gates which returns a `Vec` of information about each "declared" gate. The information is the gate's name and signature and SymbolID, which is sufficient to do everything the importer could do before this commit. Encountering `Stmt::GateDefinition` now is a no-op rather than an error. (This was previously called `Stmt::GateDeclaration`, but importantly it is really a definition.) How the standard library, and gates in general, are handled will continue to evolve. A behavioral difference between this commit and its parent: Before if the importer encountered a gate call before the corresponding definition an error would be raised. With the current commit, the importer behaves as if all gate definitions were moved to the top of the OQ3 program. However, the error will still be found by the parser so that the importer never will begin processing statements. The importer depends on a particular branch of a copy of openqasm3_parser. When the commit is ready to merge, we will release a version of openqasm3_parser and depend instead on that release. See openqasm/openqasm#517 * Remove unnecessary conversion `name.to_string()` Response to reviewer comment https://github.com/Qiskit/qiskit/pull/12087/files#r1586949717 * Remove check for U gate in map_gate_ids * This requires modifying the external parser crate. * Depend temporarily on the branch of the parser with this modification. * Make another change required by other upstream improvments. * Cargo config files are changed because of above changes. * Return error returned by map_gate_ids in convert_asg Previously this error was ignored. This would almost certainly cause an error later. But better to do it at the correct place. * Remove superfluous call to `iter()` * Depend on published oq3_semantics 0.6.0 * Fix cargo lock file --------- Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

…iskit#12087) * Adapt crates/qasm3 to work with recent versions of openqasm3_parser This commit adds no new features or capabilities to the importer. But it brings the importer up to date with the latest version of openqasm3_parser as a preliminary step in improving the importer. The biggest change in openqasm3_parser is in handling stdgates.inc. Upon encountering `include "stdgates.inc" openqasm3_parser reads no file, but rather adds symbols to the symbol table for gates in the standard library. The function `convert_asg` in the importer calls oq3_semantics::symbols::SymbolTable.gates which returns a `Vec` of information about each "declared" gate. The information is the gate's name and signature and SymbolID, which is sufficient to do everything the importer could do before this commit. Encountering `Stmt::GateDefinition` now is a no-op rather than an error. (This was previously called `Stmt::GateDeclaration`, but importantly it is really a definition.) How the standard library, and gates in general, are handled will continue to evolve. A behavioral difference between this commit and its parent: Before if the importer encountered a gate call before the corresponding definition an error would be raised. With the current commit, the importer behaves as if all gate definitions were moved to the top of the OQ3 program. However, the error will still be found by the parser so that the importer never will begin processing statements. The importer depends on a particular branch of a copy of openqasm3_parser. When the commit is ready to merge, we will release a version of openqasm3_parser and depend instead on that release. See openqasm/openqasm#517 * Remove unnecessary conversion `name.to_string()` Response to reviewer comment https://github.com/Qiskit/qiskit/pull/12087/files#r1586949717 * Remove check for U gate in map_gate_ids * This requires modifying the external parser crate. * Depend temporarily on the branch of the parser with this modification. * Make another change required by other upstream improvments. * Cargo config files are changed because of above changes. * Return error returned by map_gate_ids in convert_asg Previously this error was ignored. This would almost certainly cause an error later. But better to do it at the correct place. * Remove superfluous call to `iter()` * Depend on published oq3_semantics 0.6.0 * Fix cargo lock file --------- Co-authored-by: Matthew Treinish <mtreinish@kortar.org>

jakelishman commented Mar 15, 2024

View reviewed changes

source/_extensions/oq_domain.py Outdated Show resolved Hide resolved

hodgestar reviewed Mar 19, 2024

View reviewed changes

source/language/standard_library.rst Outdated Show resolved Hide resolved

jlapeyre reviewed Mar 20, 2024

View reviewed changes

source/language/standard_library.rst Outdated Show resolved Hide resolved

jlapeyre reviewed Mar 20, 2024

View reviewed changes

source/language/standard_library.rst Show resolved Hide resolved

This was referenced Mar 22, 2024

Support extern gate declarations #507

Open

Replace an occurrence of stdgates.qasm with stdgates.inc #523

Merged

jlapeyre mentioned this pull request Mar 26, 2024

Adapt crates/qasm3 to work with recent versions of openqasm3_parser Qiskit/qiskit#12087

Merged

braised-babbage reviewed Apr 3, 2024

View reviewed changes

source/language/standard_library.rst Show resolved Hide resolved

braised-babbage reviewed Apr 3, 2024

View reviewed changes

source/language/standard_library.rst Show resolved Hide resolved

jakelishman and others added 6 commits April 3, 2024 17:19

Fix typo

6bf6f90

Co-authored-by: John Lapeyre <jlapeyre@users.noreply.github.com>

Depend on separate openqasm_sphinx

85cbd33

Cross-reference other files

885ab15

Merge remote-tracking branch 'qasm/main' into stdlib

5c544bb

Fix incorrect dependency

2a2c813

Include cross-reference in release note

75932b7

hodgestar reviewed Apr 10, 2024

View reviewed changes

source/language/standard_library.rst Outdated Show resolved Hide resolved

jakelishman and others added 2 commits April 10, 2024 11:06

Clarify wording around implementation choices

1fd53b0

Co-authored-by: Simon Cross <hodgestar+github@gmail.com>

Include formal mathematics

42fd895

hodgestar previously approved these changes Apr 10, 2024

View reviewed changes

levbishop previously approved these changes Apr 17, 2024

View reviewed changes

Correct inline descriptions of controlled rotation gates

0b74092

jakelishman dismissed stale reviews from levbishop and hodgestar via 0b74092 April 17, 2024 15:27

hodgestar approved these changes Apr 17, 2024

View reviewed changes

levbishop approved these changes Apr 17, 2024

View reviewed changes

blakejohnson approved these changes Apr 17, 2024

View reviewed changes

braised-babbage approved these changes Apr 17, 2024

View reviewed changes

levbishop merged commit 2c33cdd into openqasm:main Apr 17, 2024
11 checks passed

jakelishman deleted the stdlib branch April 17, 2024 15:50

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document content of the standard library #517

Document content of the standard library #517

jakelishman commented Mar 15, 2024 •

edited

Loading

hodgestar left a comment

jlapeyre Mar 20, 2024

jakelishman Mar 20, 2024

hodgestar commented Apr 10, 2024

jakelishman commented Apr 10, 2024

hodgestar left a comment

levbishop Apr 17, 2024

jakelishman Apr 17, 2024 •

edited

Loading

jakelishman Apr 17, 2024

jakelishman Apr 17, 2024 •

edited

Loading

Document content of the standard library #517

Document content of the standard library #517

Conversation

jakelishman commented Mar 15, 2024 • edited Loading

Summary

Details and comments

hodgestar left a comment

Choose a reason for hiding this comment

jlapeyre Mar 20, 2024

Choose a reason for hiding this comment

jakelishman Mar 20, 2024

Choose a reason for hiding this comment

hodgestar commented Apr 10, 2024

jakelishman commented Apr 10, 2024

hodgestar left a comment

Choose a reason for hiding this comment

levbishop Apr 17, 2024

Choose a reason for hiding this comment

jakelishman Apr 17, 2024 • edited Loading

Choose a reason for hiding this comment

jakelishman Apr 17, 2024

Choose a reason for hiding this comment

jakelishman Apr 17, 2024 • edited Loading

Choose a reason for hiding this comment

jakelishman commented Mar 15, 2024 •

edited

Loading

jakelishman Apr 17, 2024 •

edited

Loading

jakelishman Apr 17, 2024 •

edited

Loading