Feat/unitary definitions

[Katie1harrison]

Add Matrix Definitions for the Unitary Data Type

Summary

This PR extends the unitary data type so that a unitary can be defined using a matrix initializer.

Previously, unitary declarations supported:

unitary u;

This PR adds support for:

unitary u = {
    {1, 0},
    {0, 1}
};

Changes

ASTUnitaryNode

Updated ASTUnitaryNode to optionally store an ASTInitializerList representing the matrix used to define the unitary.

Added:

const ASTInitializerList *INL;

along with a constructor for initialized unitaries and methods for accessing the initializer list.

The existing constructors for uninitialized unitary declarations and unitary gate calls are preserved.

ASTBuilder

Added an overloaded CreateASTUnitaryNode that accepts an ASTInitializerList.

This allows the builder to construct both:

unitary u;

and:

unitary u = {
    {1, 0},
    {0, 1}
};

ASTProductionFactory

Added a production rule for constructing a unitary declaration containing an initializer list. The new production rule passes the parsed initializer list to ASTBuilder.

Parser Grammar

Added grammar support for:

unitary Identifier = {
    { ... },
    { ... }
};

The implementation reuses the existing InitializerList grammar rather than introducing a separate matrix AST type.

AST Representation

For example:

unitary u = {
    {1, 0},
    {0, 1}
};

is represented as:

ASTUnitaryNode
├── Identifier: u
└── ASTInitializerList
    ├── ASTExpressionNodeList: 1, 0
    └── ASTExpressionNodeList: 0, 1

Testing

Added/tested parsing of an initialized unitary using:

tests/src/unitary/unitary_creation.qasm

The parser successfully produces an ASTTypeUnitary declaration containing the expected InitializerList and matrix entries.

Not Included

This PR adds the syntax and AST representation for matrix-defined unitaries. It does not yet validate that the provided matrix is mathematically unitary.

Matrix shape, element type, and unitarity validation can be handled later during semantic analysis/compiler validation.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
0 out of 2 committers have signed the CLA.

❌ joshmtlau
❌ Katie1harrison
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[blakejohnson]

Hi @Katie1harrison: a quick heads up that this project is no longer actively maintained by the original authors. You are welcome to fork this for your own use, or if you want to become a maintainer of the repo in its currently location, we would consider that.

I'm curious if this unitary type is defined somewhere? It is not formally part of the OpenQASM spec. There was some discussion a few years ago about adding Unitary subroutines, but the related spec change has been waiting a strong use case to push it over the finish line.