qasm-ts 2.0.0 → 2.1.0

package/paper/main.bib

@@ -0,0 +1,191 @@
+@misc{di_matteo_abstraction_2024,
+	title = {An Abstraction Hierarchy Toward Productive Quantum Programming},
+	url = {https://ieeexplore.ieee.org/document/10821267},
+	abstract = {Experience from seven decades of classical computing suggests that a sustainable computer industry depends on a community of software engineers writing programs to address a wide variety of specific end-user needs, achieving both performance and utility in the process. Quantum computing is an emerging technology, and we do not yet have the insight to understand what quantum software tools and practices will best support researchers, software engineers, or applications specialists. Developers for today's quantum computers are grappling with the low-level details of the hardware, and progress towards scalable devices does not yet suggest what higher-level abstractions may look like. In this paper, we analyze and reframe the current state of the quantum software stack using the language of programming models. We propose an abstraction hierarchy to support quantum software engineering and discuss the consequences of overlaps across the programming, execution, and hardware models found in current technologies. We exercise this hierarchy for solving the eigenvalue estimation problem in two ways (a variational algorithm with error mitigation, and phase estimation with error correction) and pinpoint key differences in these approaches in terms of these layered models and their overlaps. While our work points to concrete conceptual challenges and gaps in quantum programming and proposes some specific steps forward, our primary thesis is that progress hinges on thinking about the abstraction hierarchy holistically, and not just about its components.},
+	language = {en},
+	urldate = {2025-08-13},
+	journal = {IEEE International Conference on Quantum Computing and Engineering (QCE) 2024},
+	author = {Di Matteo, Olivia and Nunez-Corrales, Santiago and Stechly, Michal and Reinhardt, Steven P. and Mattson, Tim},
+	month = september,
+	year = {2024},
+	DOI = {10.1109/qce60285.2024.00117},
+}
+
+@article{Cross_2022,
+   title={OpenQASM 3: A Broader and Deeper Quantum Assembly Language},
+   volume={3},
+   ISSN={2643-6817},
+   url={http://dx.doi.org/10.1145/3505636},
+   DOI={10.1145/3505636},
+   number={3},
+   journal={ACM Transactions on Quantum Computing},
+   publisher={Association for Computing Machinery (ACM)},
+   author={Cross, Andrew and Javadi-Abhari, Ali and Alexander, Thomas and De Beaudrap, Niel and Bishop, Lev S. and Heidel, Steven and Ryan, Colm A. and Sivarajah, Prasahnt and Smolin, John and Gambetta, Jay M. and Johnson, Blake R.},
+   year={2022},
+   month=sep, pages={1–50} 
+}
+
+
+@misc{seidel2024qrispframeworkcompilablehighlevel,
+      title={Qrisp: A Framework for Compilable High-Level Programming of Gate-Based Quantum Computers}, 
+      author={Raphael Seidel and Sebastian Bock and René Zander and Matic Petrič and Niklas Steinmann and Nikolay Tcholtchev and Manfred Hauswirth},
+      year={2024},
+      eprint={2406.14792},
+      archivePrefix={arXiv},
+      primaryClass={quant-ph},
+      url={https://arxiv.org/abs/2406.14792}, 
+}
+
+@article{shammah_open_2024,
+	title = {Open Hardware Solutions in Quantum Technology},
+	volume = {1},
+	issn = {2835-0103},
+	url = {http://arxiv.org/abs/2309.17233},
+	doi = {10.1063/5.0180987},
+	abstract = {Quantum technologies such as communications, computing, and sensing offer vast opportunities for advanced research and development. While an open-source ethos currently exists within some quantum technologies, especially in quantum computer programming, we argue that there are additional advantages in developing open quantum hardware (OQH). Open quantum hardware encompasses open-source software for the control of quantum devices in labs, blueprints and open-source toolkits for chip design and other hardware components, as well as openly-accessible testbeds and facilities that allow cloud-access to a wider scientific community. We provide an overview of current projects in the OQH ecosystem, identify gaps, and make recommendations on how to close them today. More open quantum hardware would accelerate technology transfer to and growth of the quantum industry and increase accessibility in science.},
+	number = {1},
+	urldate = {2024-09-09},
+	journal = {APL Quantum},
+	author = {Shammah, Nathan and Roy, Anurag Saha and Almudever, Carmen G. and Bourdeauducq, Sébastien and Butko, Anastasiia and Cancelo, Gustavo and Clark, Susan M. and Heinsoo, Johannes and Henriet, Loïc and Huang, Gang and Jurczak, Christophe and Kotilahti, Janne and Landra, Alessandro and LaRose, Ryan and Mari, Andrea and Nowrouzi, Kasra and Ockeloen-Korppi, Caspar and Prawiroatmodjo, Guen and Siddiqi, Irfan and Zeng, William J.},
+	month = mar,
+	year = {2024},
+	note = {arXiv:2309.17233 [physics]},
+	keywords = {Physics - Applied Physics},
+	pages = {011501},
+	annote = {Comment: 22 pages, 5 figures},
+	file = {arXiv Fulltext PDF:/Users/marcusedwards/Zotero/storage/ANMVI27I/Shammah et al. - 2024 - Open Hardware Solutions in Quantum Technology.pdf:application/pdf;arXiv.org Snapshot:/Users/marcusedwards/Zotero/storage/BVXLYT5I/2309.html:text/html},
+}
+
+@misc{edwards_three_2023,
+	title = {Three Quantum Programming Language Parser Implementations for the Web},
+	url = {http://arxiv.org/abs/2310.10802},
+	doi = {10.48550/arXiv.2310.10802},
+	abstract = {IBM has developed a quantum assembly (QASM) language particular to gate model quantum computing since 2017 [CBSG17]. Version 3.0 which adds timing, pulse control, and gate modifiers is currently undergoing finalization in 2023 [CJA+21]. In a similar vein, Pakin of Los Alamos National Laboratory published a quantum macro assembler (QMASM) for D-Wave quantum annealers in 2016 [Pak16]. This assembler specifically targets quantum annealers like D-Wave's. A comparable technology that targets continuous-variable (CV) quantum computing is the Blackbird language developed by Xanadu since 2018 [KIQ+19]. We implement parsers for each of these languages in TypeScript with a singular approach. In the cases of Blackbird and QMASM these are the first parser implementations that are web compatible and so bring these languages to a new audience and to new runtimes. This makes the parsing and execution of QMASM, QASM and Blackbird possible in web and mobile environments that don't have access to heavy compile toolchains, enabling adoption and scientific research.},
+	urldate = {2024-11-20},
+	publisher = {arXiv},
+	author = {Edwards, Marcus},
+	month = oct,
+	year = {2023},
+	note = {arXiv:2310.10802},
+	keywords = {Computer Science - Programming Languages, Quantum Physics},
+	file = {Preprint PDF:/Users/marcusedwards/Zotero/storage/68WTYTLM/Edwards - 2023 - Three Quantum Programming Language Parser Implemen.pdf:application/pdf;Snapshot:/Users/marcusedwards/Zotero/storage/ITANF7WM/2310.html:text/html},
+}
+
+@misc{noauthor_qasm_grammar_nodate,
+	title = {{OpenQASM} {3.0} {Grammar}},
+	url = {https://openqasm.com/grammar/index.html},
+	urldate = {2024-11-24},
+        note = {https://openqasm.com/grammar/index.html},
+}
+
+@misc{noauthor_qec_nodate,
+	title = {{QEC} {Decoder} {Toolkit} - {H}-{Series}},
+	url = {https://www.quantinuum.com/blog/making-fault-tolerance-a-reality-introducing-our-qec-decoder-toolkit},
+	urldate = {2024-11-20},
+	file = {QEC Decoder Toolkit - H-Series:/Users/marcusedwards/Zotero/storage/DEG3AT5Z/Quantinuum_hseries_qec_decoder_toolkit.html:text/html},
+    note = {https://www.quantinuum.com/blog/making-fault-tolerance-a-reality-introducing-our-qec-decoder-toolkit},
+}
+
+@inproceedings{qdmi,
+    title = {QDMI -- {Q}uantum {D}evice {M}anagement {I}nterface: A Standardized Interface for Quantum Computing Platforms},
+    shorttitle = {{QDMI -- Quantum Device Management Interface}},
+    booktitle = {IEEE International Conference on Quantum Computing and Engineering (QCE)},
+    author = {Wille, Robert and Schmid, Ludwig and Stade, Yannick and Echavarria, Jorge and Schulz, Martin and Schulz, Laura and Burgholzer, Lukas},
+    date = {2024},
+}
+
+@misc{noauthor_qiskit_openqasm2_nodate,
+	title = {{OpenQasm2} - {Qiskit} {SDK}},
+	url = {https://docs.quantum.ibm.com/api/qiskit/qasm2},
+	urldate = {2024-11-21},
+    note = {https://docs.quantum.ibm.com/api/qiskit/qasm2},
+}
+
+@incollection{exman_verification_2024,
+	address = {Cham},
+	title = {Verification and Validation of Quantum Software},
+	isbn = {978-3-031-64135-0 978-3-031-64136-7},
+	url = {https://link.springer.com/10.1007/978-3-031-64136-7_5},
+	abstract = {Abstract
+            Quantum software—like classic software—needs to be designed, specified, developed, and, most importantly, tested by developers. Writing tests is a complex, error-prone, and time-consuming task. Due to the particular properties of quantum physics (e.g., superposition), quantum software is inherently more complex to develop and effectively test than classical software. Nevertheless, some preliminary works have tried to bring commonly used classical testing practices for quantum computing to assess and improve the quality of quantum programs. In this chapter, we first gather 16 quantum software testing techniques that have been proposed for the IBM quantum framework, Qiskit. Then, whenever possible, we illustrate the usage of each technique (through the proposed tool that implements it, if available) on a given running example. We showcase that although several works have been proposed to ease the burn of testing quantum software, we are still in the early stages of testing in the quantum world. Researchers should focus on delivering artifacts that are usable without much hindrance to the rest of the community, and the development of quantum benchmarks should be a priority to facilitate reproducibility, replicability, and comparison between different testing techniques.},
+	language = {en},
+	urldate = {2024-11-21},
+	booktitle = {Quantum {Software}},
+	publisher = {Springer Nature Switzerland},
+	author = {Fortunato, Daniel and Jiménez-Navajas, Luis and Campos, José and Abreu, Rui},
+	editor = {Exman, Iaakov and Pérez-Castillo, Ricardo and Piattini, Mario and Felderer, Michael},
+	year = {2024},
+	doi = {10.1007/978-3-031-64136-7_5},
+	pages = {93--123},
+	file = {Full Text:/Users/marcusedwards/Zotero/storage/54MM6VMX/Fortunato et al. - 2024 - Verification and Validation of Quantum Software.pdf:application/pdf},
+}
+
+@article{zeng_first_2017,
+	title = {First quantum computers need smart software},
+	volume = {549},
+	copyright = {2017 Springer Nature Limited},
+	issn = {1476-4687},
+	url = {https://www.nature.com/articles/549149a},
+	doi = {10.1038/549149a},
+	abstract = {Early devices must solve real-world problems, urge Will Zeng and colleagues.},
+	language = {en},
+	number = {7671},
+	urldate = {2024-08-11},
+	journal = {Nature},
+	author = {Zeng, Will and Johnson, Blake and Smith, Robert and Rubin, Nick and Reagor, Matt and Ryan, Colm and Rigetti, Chad},
+	month = sep,
+	year = {2017},
+	note = {Publisher: Nature Publishing Group},
+	keywords = {Applied physics, Mathematics and computing, Quantum information, Quantum physics},
+	pages = {149--151},
+	file = {Full Text:/Users/marcusedwards/Zotero/storage/J8BV8J98/Zeng et al. - 2017 - First quantum computers need smart software.pdf:application/pdf},
+}
+
+@article{ying_floyd--hoare_2012,
+	title = {Floyd--hoare logic for quantum programs},
+	volume = {33},
+	issn = {0164-0925},
+	url = {https://dl.acm.org/doi/10.1145/2049706.2049708},
+	doi = {10.1145/2049706.2049708},
+	abstract = {Floyd--Hoare logic is a foundation of axiomatic semantics of classical programs, and it provides effective proof techniques for reasoning about correctness of classical programs. To offer similar techniques for quantum program verification and to build a logical foundation of programming methodology for quantum computers, we develop a full-fledged Floyd--Hoare logic for both partial and total correctness of quantum programs. It is proved that this logic is (relatively) complete by exploiting the power of weakest preconditions and weakest liberal preconditions for quantum programs.},
+	number = {6},
+	urldate = {2024-11-22},
+	journal = {ACM Trans. Program. Lang. Syst.},
+	author = {Ying, Mingsheng},
+	month = jan,
+	year = {2012},
+	pages = {19:1--19:49},
+	file = {Full Text PDF:/Users/marcusedwards/Zotero/storage/CUQGJ2EH/Ying - 2012 - Floyd--hoare logic for quantum programs.pdf:application/pdf},
+}
+
+@misc{noauthor_types_nodate,
+	title = {Types and {Casting} — {OpenQASM} {Live} {Specification} documentation},
+	url = {https://openqasm.com/language/types.html},
+	urldate = {2024-11-22},
+	file = {Types and Casting — OpenQASM Live Specification documentation:/Users/marcusedwards/Zotero/storage/C7FTLQJZ/types.html:text/html},
+    note = {https://openqasm.com/language/types.html},
+}
+
+@misc{zhao_qchecker_2023,
+	title = {{QChecker}: Detecting Bugs in Quantum Programs via Static Analysis},
+	shorttitle = {{QChecker}},
+	url = {http://arxiv.org/abs/2304.04387},
+	doi = {10.48550/arXiv.2304.04387},
+	abstract = {Static analysis is the process of analyzing software code without executing the software. It can help find bugs and potential problems in software that may only appear at runtime. Although many static analysis tools have been developed for classical software, due to the nature of quantum programs, these existing tools are unsuitable for analyzing quantum programs. This paper presents QChecker, a static analysis tool that supports finding bugs in quantum programs in Qiskit. QChecker consists of two main modules: a module for extracting program information based on abstract syntax tree (AST), and a module for detecting bugs based on patterns. We evaluate the performance of QChecker using the Bugs4Q benchmark. The evaluation results show that QChecker can effectively detect various bugs in quantum programs.},
+	urldate = {2024-11-25},
+	publisher = {arXiv},
+	author = {Zhao, Pengzhan and Wu, Xiongfei and Li, Zhuo and Zhao, Jianjun},
+	month = apr,
+	year = {2023},
+	note = {arXiv:2304.04387},
+	keywords = {Computer Science - Programming Languages, Computer Science - Software Engineering},
+	file = {Preprint PDF:/Users/marcusedwards/Zotero/storage/D29EPA49/Zhao et al. - 2023 - QChecker Detecting Bugs in Quantum Programs via S.pdf:application/pdf;Snapshot:/Users/marcusedwards/Zotero/storage/QNX2SHXM/2304.html:text/html},
+}
+
+@misc{osaka_2025,
+	author = {Aso, Noriyasu and Feluś, Karolina and Gaj, Adrian and Gokita, Shun and Góralczyk, Sławomir and Kakuko, Norihiro and Masumoto, Naoyuki and Miyaji, Kosuke and Miyanaga, Takafumi and Mori, Toshio and Noda, Kunihiro and Tsukano, Satoyuki and Ymaguchi, Masaomi and Żybort, Dobrosław},
+	month = {9},
+	title = {OQTOPUS Cloud},
+	url = {https://github.com/oqtopus-team/oqtopus-cloud},
+	year = {2024}
+}

package/paper/paper.md

@@ -0,0 +1,166 @@
+---
+authors:
+  - name: Sean Kim[^1]
+    affiliation: "1"
+    orcid: 0009-0006-1223-1895
+  - name: Marcus Edwards[^2]
+    affiliation: "2"
+    orcid: 0000-0001-6591-9585
+tags:
+  - TypeScript
+  - Quantum computing
+  - Compiling
+bibliography: main.bib
+date: 30 July 2025
+title: Enabling the Verification and Formalization of Hybrid
+  Quantum-Classical Computing with OpenQASM 3.0 compatible QASM-TS 2.0
+affiliations:
+ - name: George Washington University, United States of America
+   index: 1
+ - name: University of British Columbia, Canada
+   index: 2
+---
+
+# Summary
+
+The unique features of the hybrid quantum-classical computing model
+implied by the specification of OpenQASM 3.0 motivate new approaches to
+quantum program verification. We implement and thoroughly test a QASM 3.0 
+parser in TypeScript to enable implementations of verification and validation
+software, compilers, and more. We aim to
+help the community to formalize the logic of hybrid quantum-classical
+computing by providing tools that may help with such efforts.
+
+### Top Level Abstractions
+
+The parser implements recursive descent parsing with support for
+expression precedence and type checking. At a high
+level, the parsing can be split into three logical sections: expression
+parsing, quantum-specific parsing, and classical parsing.
+
+Expression parsing forms the foundation for both quantum and classical
+parsing by breaking down expressions into their constituent parts and
+rebuilding them according to the mathematical and operator syntax
+defined in the OpenQASM 3.0 official grammar
+[@noauthor_qasm_grammar_nodate]. Starting with basic elements like
+numbers, variables, and operators, the parser constructs an abstract
+syntax tree that reflects proper operator precedence and nesting. This process handles not only mathematical
+operations but also array accesses, function calls, and parameter lists,
+creating a structured representation that maintains the logical
+relationships between all parts of the expression.
+
+Quantum operation parsing manages the core quantum computing elements of
+QASM, ensuring that quantum operations are syntactically correct. The
+parser maintains strict tracking of quantum resources through its
+*gates*, *standardGates*, and *customGates* sets, validating that each
+quantum operation references only properly defined gates and qubits. It
+processes quantum register declarations, custom gate definitions, gate
+applications (including gate modifiers), measurement operations, and
+timing-critical operations like barriers and delays. Each quantum
+operation is validated in its context.
+
+The classical parsing processes classical variable declarations with
+strict type checking, function definitions with parameter and return
+type validation, control flow structures like conditional statements and
+loops, and array operations. The parser maintains separate tracking for
+classical and quantum resources while ensuring they can interact in
+well-defined ways. This enables
+QASM programs to express complex quantum algorithms that require
+classical processing while maintaining type safety and operational
+validity.
+
+Our parser produces a strongly-typed AST that captures the full
+structure of QASM programs and is designed to enable subsequent semantic
+analysis.
+
+# Statement of Need
+
+The OpenQASM 3.0 type system supports classical and
+quantum types as well as functions which can be used to specify hybrid
+quantum-classical programs. 
+
+There is need for formal analysis and verification of hybrid quantum
+classical programs and we argue that mathematical frameworks and
+software frameworks are needed to address this gap.
+
+Hand-in-hand with formalization efforts are the development of community
+standards for quantum programming. The standardization of quantum computer programming is ongoing
+[@di_matteo_abstraction_2024; @Cross_2022] and relies significantly on
+open source software and frameworks including some released only last
+year [@seidel2024qrispframeworkcompilablehighlevel; @qdmi]. Some
+community standards such as the 2022 Open Quantum Assembly (OpenQASM)
+3.0 specification boast typing as well as interoperability and
+portability between quantum systems of different types. However, others such as the QUASAR
+instruction set architecture assume some backend details such as a
+classical co-processor to complement the Quantum Processing Unit (QPU)
+[@shammah_open_2024]. To what extent the classical surrounds of a
+quantum processing unit should be assumed or specified and at what part
+of the stack is an open question. This "piping" can leverage many
+classical programming paradigms including web technology. What we refer
+to here is distinct from cloud quantum computing which simply offers a
+web-accessible front-end to users of quantum computers. Instead, we are
+interested in parts of the programming model itself, such as pieces of
+the compile toolchain (compilers, transpilers, assemblers, noise
+profilers, schedulers) that are implemented using web technology. An
+example of this is Quantinuum's QEC decoder toolkit, which uses a
+WebAssembly (WASM) virtual machine (WAVM) as a real-time classical
+compute environment for QEC decoding [@noauthor_qec_nodate]. Other examples include our
+ports of Quantum Assembly (QASM), Quantum Macro Assembler (QMASM), and
+Blackbrid to TypeScript [@edwards_three_2023].
+
+An important part of standardization is verification. Our typed OpenQASM 3.0 parser implements a system that infers types from QASM syntax. This opens the
+door to the type-based formal verification of QASM code. A body of work
+exists regarding the verification of quantum software, and it is
+summarized in @exman_verification_2024.
+
+The primary future direction that we see is the development of
+verification tools such as static analysis tools based on QASM-TS in the
+vein of QChecker [@zhao_qchecker_2023]. This could be complemented by a
+formal type theory of OpenQASM 3.0.
+
+Virtually every quantum computing company has provided access through a hybrid cloud. This
+demands that parts of the stack be implemented in web
+technology, and we argue that it is optimal in a sense to use technology
+that is designed for this environment when we find ourselves working in
+a hybrid quantum / classical cloud. We
+suggest that a closer marriage of open source efforts to the
+inherently web-based stack supporting existing quantum computing
+offerings is desirable.
+
+We note that Osaka University's open-source quantum computer operating system project "Oqtopus"
+already depends on and makes use of Qasm-ts [@osaka_2025] and thank the Oqtopus team for their interest 
+in our work.
+
+# Outcomes
+
+Our comparative analysis focused on two promiment OpenQASM 3.0 parsers:
+Qiskit's Python ANLTR-based reference implementation and Qiskit's
+experimental Rust parser.
+
+## Performance Benchmarking
+
+Benchmark Results                                             
+------------------- -------------------- -------------------- --------------------
+Result              ANTLR Parser         Rust Parser          Qasm-ts
+Success Rate        100% (11/11 files)   18.2% (2/11 files)   100% (11/11 files)
+Average Time        8.53 ms              0.59 ms              0.90 ms
+Min Time            1.93 ms              0.55 ms              0.36 ms
+Max Time            30.54 ms             0.62 ms              3.68 ms
+
+The benchmarking reveals that when just taking into account the AST
+generation, the Rust implementation generally offers superior raw
+performance, but suffers from only currently supporting a subset of the
+full OpenQASM 3.0 specification. The QASM-TS parser provides competitive
+performance for web deployment scenarios, while the ANTLR parser offers
+a balance of features and performance suitable for development and
+testing.
+
+# Acknowledgements
+
+We would like to thank Dr. Shohini Ghose for support and helpful discussions regarding the previous version of this software package, QASM-TS 1.0, which has had use in the community by hundreds (counted by npm downloads).
+
+[^1]: skim658\@gwu.edu
+
+[^2]: msedward\@student.ubc.ca
+
+# References

package/readme.md

@@ -1,12 +1,19 @@
 # QASM TypeScript
 
+![NPM Downloads](https://img.shields.io/npm/dy/qasm-ts)
+
+
 OpenQASM, the low-level programming language for quantum circuit specification, implemented in TypeScript.
 
-Language documentation is provided by IBM [here](https://github.com/Qiskit/openqasm/blob/master/spec/qasm2.rst).
+QASM-TS 2.0 is an implementation of a compiler frontend for OpenQASM 2.0 and 3.0. It includes a lexer and a parser of the OpenQASM language. The source is parsed into an Intermediate Representation (IR): an Abstract Syntax Tree (AST) that captures program structure including control flow and data flow.
+
+The package is aimed at enabling implementations of verification and validation software (such as semantic and static analyzers), compilers and more. These tools may be instrumental in the formalization of hybrid quantum-classical computing.
+
+Language documentation is provided by IBM [here](https://openqasm.com).
 
 ## New in Version 2.0.0
 
-- Support for the OpenQASM 3.0 spec while retaining OpenQASM 2.0 backwards compatability.
+- Support for the OpenQASM 3.0 spec while retaining OpenQASM 2.0 backwards compatibility.
 
 ## Usage
 
@@ -16,21 +23,29 @@ Import the parse function or parseString function from the package.
 import { parseFile, parseString } from 'qasm-ts';
 ```
 
-`parseFile` can be called with a file path to a `.qasm` file. It will parse the file and return the abstract syntax tree representation. `parseFile` can also take 3 optional parameters: 
-1. `version`: A `number`, `OpenQASMVersion`, or `OpenQASMMajorVersion` to specify whether to use the Qasm 2 or 3 lexer/parser (defaults to version 3).
-2. `verbose`: Whether to return verbose objects that includes an extra key for each node's class name (defaults to `false`).
-3. `stringify`: Whether to stringify and format the return object (defaults to `false`).
+`parseFile` can be called with a `String` file path to a `.qasm` file. It will parse the file and return the abstract syntax tree representation. `parseFile` can also take 3 optional parameters: 
+1. `version`: A `number`, `OpenQASMVersion`, or `OpenQASMMajorVersion`. Specifies whether to use the Qasm 2 or 3 lexer/parser (defaults to version 3).
+2. `verbose`: A `Boolean`. Whether to return verbose objects that includes an extra key for each node's class name (defaults to `false`).
+3. `stringify`: A `Boolean`. Whether to stringify and format the return object (defaults to `false`).
 
 ```ts
 let ast = parseFile("<file-path>");
 ```
 
-`parseString` should be called with a string of QASM code. It will parse the code and return the abstract syntax tree representation. `parseString` also takes the same optional arguments as `parseFile`.
+`parseString` should be called with a `String` of QASM code. It will parse the code and return the abstract syntax tree representation. `parseString` also takes the same optional arguments as `parseFile`.
 
 ```ts
 let ast = parseString("<qasm-string>");
 ```
 
+The return type for both `parseFile` and `parseString` is `Array<AstNode>`, unless the `stringify` parameter is `true`, in which case the return is a `String`.
+
+The parser is able to recognize and handle 19 distinct types of syntax errors, which are defined and
+exported in `errors.ts`. While this is not an advanced semantic or static analysis, it should enable 
+users to basically validate their OpenQASM 2.0 or 3.0 code.
+
+Comprehensive API docs can be found in the `docs/` directory.
+
 ## Example I/O
 
 ### Input: `alignment.qasm` ([source](https://github.com/openqasm/openqasm/blob/main/examples/alignment.qasm))
@@ -52,8 +67,6 @@ barrier q;
 
 ### Output: Abstract Syntax Tree
 
-Run with: `const ast = parseFile("./alignment.qasm", 3);`.
-
 ```
 [
   Include { filename: '"stdgates.inc"' },
@@ -92,10 +105,31 @@ Run with: `const ast = parseFile("./alignment.qasm", 3);`.
 ]
 ```
 
+To reproduce this output, you could run the following script in the directory where `alignment.qasm` is located.
+
+```
+import { parseFile } from 'qasm-ts';
+
+const ast = parseFile("./alignment.qasm", 3);
+
+console.log(ast);
+```
+
+To run TypeScript files, you can use any number of compilers, but we recommend `ts-node`. For more information on `ts-node`, refer to [the docs](https://www.npmjs.com/package/ts-node).
+
+```
+ts-node script.ts
+```
+
 ## Source code
 
 Feel free to clone, fork, comment or contribute on [GitHub](https://github.com/comp-phys-marc/qasm-ts)!
 
+## Contributing
+
+To get started contributing to QASM-TS, please see the open issues for a place to start.
+Alternatively, you are welcome to create any issues which you feel may capture changes, improvements or additions to the package that would be useful. These may be bug reports or enhancement requests. These will be reviewed in a timely manner by a maintainer. If you are able to implement any desired functionality or bug fixes yourself, we also welcome and promise to review any pull requests. Please simply fork the repository and create a branch in your fork with the changes in question. When you create your pull request, make sure to target our repo.
+
 ## Transpiling
 
 ```
@@ -114,6 +148,10 @@ npm install
 npm test
 ```
 
+## Run benchmarks
+
+To run benchmarks that compare this package's performance against pre-existing ANTLR and Rust based parsers, see the [benchmarking repo](https://github.com/seankim658/qasm-parser-testing) and its instructions.
+
 ## References
 
 The original OpenQASM authors:
@@ -136,3 +174,19 @@ http://www.apache.org/licenses/LICENSE-2.0
 ```
 
 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+
+## How to Cite
+
+If you are using QASM-TS for research we appreciate any citations. Please read and cite our pre-print at https://arxiv.org/abs/2412.12578.
+
+```
+@misc{kim2024enablingverificationformalizationhybrid,
+      title={Enabling the Verification and Formalization of Hybrid Quantum-Classical Computing with OpenQASM 3.0 compatible QASM-TS 2.0}, 
+      author={Sean Kim and Marcus Edwards},
+      year={2024},
+      eprint={2412.12578},
+      archivePrefix={arXiv},
+      primaryClass={cs.PL},
+      url={https://arxiv.org/abs/2412.12578}, 
+}
+```