Files generated by PkgTemplates

PkgTemplates version: 0.7.52

.github/dependabot.yml

@@ -0,0 +1,7 @@
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+version: 2
+updates:
+ - package-ecosystem: "github-actions"
+ directory: "/" # Location of package manifests
+ schedule:
+ interval: "weekly"

.github/workflows/CI.yml

@@ -0,0 +1,78 @@
+name: CI
+on:
+ push:
+ branches:
+ - main
+ tags: ['*']
+ pull_request:
+ workflow_dispatch:
+concurrency:
+ # Skip intermediate builds: always.
+ # Cancel intermediate builds: only if it is a pull request build.
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: ${{ startsWith(github.ref, 'refs/pull/') }}
+jobs:
+ test:
+ name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 10
+ permissions: # needed to allow julia-actions/cache to proactively delete old caches that it has created
+ actions: write
+ contents: read
+ strategy:
+ fail-fast: false
+ matrix:
+ version:
+ - '1'
+ - 'lts'
+ - 'pre'
+ os:
+ - ubuntu-latest
+ arch:
+ - x64
+ steps:
+ - uses: actions/checkout@v4
+ - uses: julia-actions/setup-julia@v2
+ with:
+ version: ${{ matrix.version }}
+ arch: ${{ matrix.arch }}
+ - uses: julia-actions/cache@v2
+ - uses: julia-actions/julia-buildpkg@v1
+ - uses: julia-actions/julia-runtest@v1
+ - uses: julia-actions/julia-processcoverage@v1
+ - uses: codecov/codecov-action@v3
+ with:
+ token: ${{ secrets.CODECOV_TOKEN }}
+ files: lcov.info
+ docs:
+ name: Documentation
+ runs-on: ubuntu-latest
+ permissions:
+ actions: write # needed to allow julia-actions/cache to proactively delete old caches that it has created
+ contents: write
+ statuses: write
+ steps:
+ - uses: actions/checkout@v4
+ - uses: julia-actions/setup-julia@v2
+ with:
+ version: '1'
+ - uses: julia-actions/cache@v2
+ - uses: julia-actions/julia-buildpkg@v1 # forces PkgServer refresh
+ - name: Configure doc environment
+ shell: julia --project=docs --color=yes {0}
+ run: |
+ using Pkg
+ Pkg.Registry.update()
+ Pkg.develop(PackageSpec(path=pwd()))
+ Pkg.instantiate()
+ - uses: julia-actions/julia-buildpkg@v1
+ - uses: julia-actions/julia-docdeploy@v1
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ - name: Run doctests
+ shell: julia --project=docs --color=yes {0}
+ run: |
+ using Documenter: DocMeta, doctest
+ using Quasar 
+ DocMeta.setdocmeta!(Quasar, :DocTestSetup, :(using Quasar); recursive=true)
+ doctest(Quasar)

.github/workflows/CompatHelper.yml

@@ -0,0 +1,16 @@
+name: CompatHelper
+on:
+ schedule:
+ - cron: 0 0 * * *
+ workflow_dispatch:
+jobs:
+ CompatHelper:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Pkg.add("CompatHelper")
+ run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
+ - name: CompatHelper.main()
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}
+ run: julia -e 'using CompatHelper; CompatHelper.main()'

.github/workflows/Documentation.yml

@@ -0,0 +1,26 @@
+name: Documentation
+
+on:
+ push:
+ branches:
+ - main # update to match your development branch (master, main, dev, trunk, ...)
+ tags: '*'
+
+jobs:
+ build:
+ permissions:
+ contents: write
+ statuses: write
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v2
+ - uses: julia-actions/setup-julia@v2
+ with:
+ version: '1'
+ - name: Install dependencies
+ run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+ - name: Build and deploy
+ env:
+ GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+ run: julia --project=docs/ docs/make.jl
+

.github/workflows/TagBot.yml

@@ -0,0 +1,31 @@
+name: TagBot
+on:
+ issue_comment:
+ types:
+ - created
+ workflow_dispatch:
+ inputs:
+ lookback:
+ default: "3"
+permissions:
+ actions: read
+ checks: read
+ contents: write
+ deployments: read
+ issues: read
+ discussions: read
+ packages: read
+ pages: read
+ pull-requests: read
+ repository-projects: read
+ security-events: read
+ statuses: read
+jobs:
+ TagBot:
+ if: github.event_name == 'workflow_dispatch' || github.actor == 'JuliaTagBot'
+ runs-on: ubuntu-latest
+ steps:
+ - uses: JuliaRegistries/TagBot@v1
+ with:
+ token: ${{ secrets.GITHUB_TOKEN }}
+ ssh: ${{ secrets.DOCUMENTER_KEY }}

.gitignore

@@ -0,0 +1,2 @@
+*Manifest.toml
+lcov.info

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Katharine Hyatt <[email protected]> and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Project.toml

@@ -0,0 +1,29 @@
+name = "Quasar"
+uuid = "86e06105-936e-439e-acf0-7687560b0bd9"
+authors = ["Katharine Hyatt <[email protected]> and contributors"]
+version = "1.0.0-DEV"
+
+[deps]
+AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
+Automa = "67c07d97-cdcb-5c2c-af73-a7f9c32a568b"
+DataStructures = "864edb3b-99cc-5e75-8d2d-829cb0a9cfe8"
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+PrecompileTools = "aea7be01-6a6a-4083-8856-8a6e6704d82a"
+
+[compat]
+AbstractTrees = "0.4.5"
+Automa = "1.0.4"
+DataStructures = "0.18.20"
+Dates = "1"
+PrecompileTools = "1.2.1"
+julia = "1.6"
+
+[extras]
+Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
+Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
+
+[targets]
+test = ["Test", "Dates", "LinearAlgebra", "Statistics"]

README.md

@@ -0,0 +1,3 @@
+# Quasar
+
+[![Build Status](https://github.com/kshyatt-aws/Quasar.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/kshyatt-aws/Quasar.jl/actions/workflows/CI.yml?query=branch%3Amain)

docs/Project.toml

@@ -0,0 +1,3 @@
+[deps]
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Quasar = "86e06105-936e-439e-acf0-7687560b0bd9"

docs/make.jl

@@ -0,0 +1,23 @@
+using Quasar 
+using Documenter
+
+DocMeta.setdocmeta!(Quasar, :DocTestSetup, :(using Quasar; recursive=true))
+
+makedocs(;
+ modules=[Quasar],
+ sitename="Quasar.jl",
+ repo="github.com/kshyatt-aws/Quasar.jl",
+ format=Documenter.HTML(;
+ canonical="github.com/kshyatt-aws/Quasar.jl",
+ edit_link="main",
+ assets=String[],
+ ),
+ pages=[
+ "Home" => "index.md",
+ ],
+)
+
+deploydocs(;
+ repo="github.com/kshyatt-aws/Quasar.jl",
+ devbranch="main",
+)

docs/src/index.md

@@ -0,0 +1,94 @@
+```@meta
+DocTestSetup = quote using Quasar end
+CurrentModule = Quasar
+```
+
+# Quasar
+
+`Quasar.jl`, the Qu(antum) as(sembly) (lex/pars)er, is a package for lexing and parsing the [OpenQASM quantum assembly IR](https://openqasm.com/).
+
+`Quasar` works in a two-step fashion: first, it uses a tokenizer to generate an [abstract syntax tree (AST)](https://en.wikipedia.org/wiki/Abstract_syntax_tree) representing the
+quantum program, which is a nested structure of `QasmExpression`s.
+Then, it walks (visits) the AST to evaluate all loops, conditionals, gate calls, and variable declarations.
+
+`Quasar` has support for:
+
+- Basic builtin OpenQASM 3 gates `gphase` and `U`
+- Custom gate definitions
+- `for` and `while` loops
+- `if`, `else`, and `switch` conditional statements
+- Builtin OpenQASM3 functions
+- Function definitions and calls
+- Casting classical types
+- Timing statements `barrier` and `delay`
+- Pragmas (see below)
+
+What is *not* yet supported:
+- `angle` types
+- Annotations
+- OpenPulse
+
+If you need any of these features, feel free to open an issue requesting support for them!
+
+## Quick Start
+
+For more extensive examples, see the tests in `test/`. Here, we can parse and visit a simple OpenQASM 3.0 program to generate a Bell circuit:
+
+```jldoctest
+julia> qasm = """OPENQASM 3.0;\ngate h a { U(π/2, 0, π) a; gphase(-π/4);};\ngate x a { U(π, 0, π) a; gphase(-π/2);};\ngate cx a, b { ctrl @ x a, b; };\ndef bell(qubit q0, qubit q1) {\n h q0;\n cx q0, q1;\n}\nqubit[2] q;\nbell(q[0], q[1]);\nbit[2] b = "00";\nb[0] = measure q[0];\nb[1] = measure q[1];\n""";
+
+julia> parsed = Quasar.parse_qasm(qasm);
+
+julia> visitor = Quasar.QasmProgramVisitor();
+
+julia> visitor(parsed);
+```
+
+You can supply [inputs](https://openqasm.com/language/directives.html#input-output) to your program
+by creating the `QasmProgramVisitor` with a `Dict{String, Any}` containing the names of the input variables
+as the keys and their values as the `Dict`'s values. This allows you to re-use the same AST multiple times
+for different inputs.
+
+Once the visitor has walked the AST, its `instructions` field contains `CircuitInstruction` `NamedTuple`s you can
+use to construct your own circuit instruction types. These tuples have fields:
+
+- `type::String` - the name of the instruction, e.g. `"measure"` or `"cx"`
+- `arguments` - any arguments the instruction accepts, such as an angle for an `rx` gate or a `Period` for a `duration` 
+- `targets::Vector{Int}` - the qubits targeted by this instruction. This should include any control qubits. 
+- `controls::Vector{Pair{Int,Int}}` - any controls (including `negctrl`) applied to the instruction. The first item in the pair is the qubit, the second is the value controlled upon, so that `2=>0` represents a `negctrl` on qubit 2.
+- `exponent::Float64` - the `pow` modifier applied to the instruction, if any
+
+You can use a package such as [`StructTypes.jl`](https://github.com/JuliaData/StructTypes.jl) to build your circuits and programs from these named tuples.
+
+In the above example, the `h`, `x`, and `cx` were defined in terms of the built-in gates `U` and `gphase`. In many cases, you may have an implementation of these
+gates that is simpler or more efficient. In that case, you can supply your own gate definition file using the [`include` instruction](https://openqasm.com/language/comments.html#included-files), or provide a *function* to generate a dictionary of builtin gates to `Quasar.jl`:
+
+```julia
+using Quasar
+
+function my_builtin_generator()
+ ...
+end
+
+Quasar.builtin_gates[] = my_builtin_generator 
+```
+
+A generator function is used here in order to allow visitors to overwrite builtin functions in certain scopes without corrupting the reference definition.
+
+## Working with `pragma`s
+
+[OpenQASM `pragma`s](https://openqasm.com/language/directives.html#pragmas) allow specific platforms to provide custom instructions.
+`Quasar.jl` provides a bare `parse_pragma` function you can override and extend to support parsing your pragma constructs. This will
+teach `Quasar.jl` how to incorporate your `pragma` instructions into the AST. You will also need to write a `visit_pragma` function
+for the AST walking step. You may want to use `pragma`s to support custom circuit operations (like noise channels) or results. 
+
+Your `parse_pragma` should take four arguments:
+- `tokens` -- some vector of tokens generated by the tokenizer which represents the `pragma` line, with the leading `#pragma` removed
+- `stack` -- the current stack of `QasmExpressions`, used for error reporting
+- `start` -- the location in the QASM source string of the start of the `#pragma` line, used for error reporting
+- `qasm` -- the QASM source string, used for error reporting
+
+Your `visit_pragma` should take two arguments:
+- `visitor` -- any subtype of `AbstractVisitor`, e.g. a `QasmProgramVisitor`, `QasmForLoopVisitor`, etc.
+- `expr` -- the `QasmExpression` containing your full `pragma` invocation, generated by the above `parse_pragma` function
+