PyQASM CLI

To provide a more interactive experience for developers, PyQASM offers a command-line interface (CLI) tool. The CLI tool can be installed as an extra dependency by running the following command:

pip install 'pyqasm[cli]'

This feature is still in active development and may not be stable for production use

Users can then verify their installation by running the following command:

Verify installation

pyqasm --help

Output

Usage: pyqasm [OPTIONS] COMMAND [ARGS]...

The PyQASM CLI.

╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --version             -v        Show the version and exit.                                                     │
│ --install-completion            Install completion for the current shell.                                      │
│ --show-completion               Show completion for the current shell, to copy it or customize the             │
│                                 installation.                                                                  │
│ --help                -h        Show this message and exit.                                                    │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ validate   Validate OpenQASM files.                                                                            |
| unroll     Unroll OpenQASM files.                                                                                                               │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Validate

The validate functionality can be used to check QASM files. You can provide the path to the QASM file or a directory as an argument to the validate command. The tool will then check the semantic validity of the file(s) and return the results.

help command

pyqasm validate --help

Output

Usage: pyqasm validate [OPTIONS] SRC_PATHS...

 Validate OpenQASM files.

╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    src_paths      SRC_PATHS...  Source file or directory paths to validate.                                   │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --skip       -s      TEXT  Files to skip during validation.                                                    │
│ --help       -h            Show this message and exit.                                                         │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Valid QASM file

$ pyqasm validate tests/cli/resources/valid1.qasm

Success: no issues found in 1 source file

Invalid QASM file inside a dir

$ pyqasm validate tests/cli/resources/

tests/cli/resources/invalid1.qasm: error: Index 2 out of range for register of size 1 in qubit [validation]
Found errors in 1 file (checked 3 source files)

Unroll

The unroll functionality is used to expand all macros and modular structures in OpenQASM files into flat, low-level instructions that are directly executable by quantum devices or emulators. You can provide either the path to a specific QASM file or a directory containing multiple QASM files as an argument to the unroll command. By default, the unrolled file is saved with the following naming convention: <original_qasm_filename>_unrolled

help command

pyqasm unroll --help

Output

Usage: pyqasm unroll [OPTIONS] SRC_PATHS...

 Unroll OpenQASM files.

╭─ Arguments ─────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ *    src_paths      SRC_PATHS...  Source file or directory paths to unroll.                                     │
╰─────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ──────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --skip       -s      TEXT  Files to skip during unrolling.                                                     │
│ --overwrite                Overwrite original files instead of creating new ones.                              │
│ --output     -o      TEXT  Output file path (can only be used with a single input file).                       │
│ --help       -h            Show this message and exit.                                                         │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Unroll single QASM file

$ pyqasm unroll tests/cli/resources/valid1.qasm

Successfully unrolled 1 file
Checked 1 source file

Unroll multiple QASM file inside a dir

$ pyqasm unroll tests/cli/resources/

Successfully unrolled 2 files
----------------------------------------------------------------------------------------------------
Failed to unroll: tests/cli/resources/invalid1.qasm

[validation-error] -> Index 2 out of range for register of size 1 in qubit

Error at line 8, column 0 in QASM file

 >>>>>> h q[2];
----------------------------------------------------------------------------------------------------
Failed to unroll 1 file
Checked 3 source files