Add OpenQASM 3 import for GateCircuit

[Kitsunp]

Closes #14

Summary

This PR adds a minimal OpenQASM 3 importer for Stretto circuits.

It introduces from_qasm(qasm::String) -> GateCircuit, which parses a small static OpenQASM 3 subset into Stretto's existing GateCircuit / GateOp representation.

Changes

• Adds src/qasm.jl with from_qasm.
• Maps supported OpenQASM gate names to Stretto gate symbols:
  • h -> :H
  • cx -> :CX
  • cz -> :CZ
  • x -> :X
  • y -> :Y
  • z -> :Z
  • s -> :S
  • t -> :T
  • ccx -> :CCX
• Converts OpenQASM 0-based qubit indices to Stretto 1-based qubit indices.
• Supports optional include "..." statements and compact one-line QASM statements.
• Rejects unsupported/out-of-scope input, including:
  • missing or non-OpenQASM 3 headers
  • OpenQASM 2 input
  • parametric gates
  • unsupported statements such as measure
  • multiple qubit registers
  • out-of-range or repeated qubit operands
• Exports from_qasm from Stretto.
• Adds qasm.jl to the API documentation.
• Adds tests for successful parsing, unitary equivalence, compact statements, comments, and invalid input.

Scope

This intentionally implements only the static OpenQASM 3 subset requested in the issue. It does not add parametric gates, OpenQASM 2 support, to_qasm, Python interop, or new compilation behavior.

Verification

julia --project=. test/runtests.jl

Result:

123 passed

julia --project=docs docs/make.jl

Result:

Docs build passed.

The docs build still reports existing warnings for unrelated links/docstrings.

AI Transparency

I used OpenAI Codex to help inspect the repository patterns, compare the implementation against issue #14, draft tests, and run local verification. I manually reviewed the parser behavior, supported scope, error handling, tests, documentation changes, and command outputs before preparing this PR.

[jack-champagne]

Hi @Kitsunp, thanks for your submission to #14 for unitaryHACK! 👋 We've done an initial read-through and it looks like a real, well-formed contribution. We're pulling it down to run the test suite locally tonight and will follow up with detailed feedback in the morning. Appreciate your patience!

[jack-champagne]

Thanks @Kitsunp, we're going with this one for #14. It's clean, dependency-free, and the best-validated of the parsers here (strict OPENQASM 3; header, arity and duplicate-qubit checks, parametric rejection, and round-trip circuit_unitary tests), which fits our goal of keeping Stretto's core lean for the public release. Verified locally: 123/123 passing.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️