Quantar

Quantar is a strict superset of Python for quantum computing and physics simulations. It keeps Python syntax and adds custom infix operators such as a <-> b, plus a library of quantum gates, circuits, algorithms, and physics helpers.

Requirements

• Python 3.12 or newer
• NumPy, Numba, and openqasm3[parser] (installed automatically)

Installation

pip install quantar

# or with uv
uv pip install quantar

Optional extras:

# alternative quantum backends
pip install quantar[backends]

# SciPy-powered COBYLA optimization
pip install quantar[optimization]

# LSP support
pip install quantar[lsp]

Running Quantar

qtr path/to/program.qtr

Compile a file to ordinary Python instead of executing it:

qtr path/to/program.qtr --compile path/to/program.py

During development, the same runner is available as a module:

python -m lang_systems.runner path/to/program.qtr

Small registers use vectorized NumPy so short programs skip Numba's startup and compilation cost. Registers with at least 1,048,576 amplitudes use the JIT. Set QUANTAR_NUMBA_MIN_AMPLITUDES to change that cutoff, or QUANTAR_NUMBA=0 to disable Numba entirely.

VS Code extension

The extension lives in editors/vscode. It provides .qtr syntax highlighting, parser diagnostics, and registry-driven operator highlighting through a pygls language server.

pip install -e ".[lsp]"
cd editors/vscode
npm install
npm run compile

Open editors/vscode in VS Code and run the Run Quantar Extension launch configuration. The extension also adds Quantar: Run File and Quantar: Compile File to Python commands.

Parsing Quantar

lang_systems.parse() returns pegen's raw parse tree. This is the low-level form used by tooling and tests:

from lang_systems import parse

tree = parse("a <-> b\nx = 1 + 2\n")

lang_systems.parse_ast() returns a normal Python AST with custom QuantumOp nodes:

import ast

from lang_systems import OperatorCollector, parse_ast

module = parse_ast("x = a <-> b\n")
print(ast.dump(module, indent=2))

collector = OperatorCollector()
collector.visit(module)
print(collector.operators)  # [("<->", "binary")]

Custom operators are registered with lang_systems.operators.operator:

from lang_systems.operators import operator

@operator.binary("><")
def reverse(left, right):
    return right, left

If the operators live in another module, import that module before parsing:

from lang_systems import load_operators, parse

load_operators("my_package.quantar_ops")
tree = parse("a >< b\n")

Quantar as a library

quantar is the umbrella package. It loads the language, quantum, and physics packages lazily, so importing it stays lightweight:

import quantar

q = quantar.QuantumComputer(2)
tree = quantar.parse_ast("a <-> b\n")
print(quantar.__version__)

quantar.lang_systems
quantar.quantum
quantar.stl

The underlying packages can still be imported directly:

import quantum
from stl.quantum_algs.shors_alg import shors_alg
from stl.physics_algs.units import Quantity, Unit

See the modules under src/quantum/ and src/stl/ for the available gates, circuits, algorithms, and physics helpers.

Development

The Python packages live under src/. Install the project in editable mode before running the CLI or LSP from a checkout:

pip install -e ".[lsp]"

Regenerate the parser after changing src/lang_systems/quantar.gram:

python -m lang_systems.pegen_gram_gen

Build the wheel and source distribution:

uv build

The generated parser is src/lang_systems/quantar_parser.py; the build hook in hatch_build.py regenerates it automatically. The parser is generated from CPython's Grammar/python.gram plus the operator overlay in src/lang_systems/quantar.gram.

Status

Quantar currently provides the parser, AST, quantum library, physics library, a CLI runner/compiler, and a VS Code extension scaffold. A bytecode interpreter and debugger are not implemented yet.

Feedback

Feedback and bug reports are welcome through GitHub issues or by contacting the maintainer. The main contributor is Gautham_rgb.

Notes on AI

Most of the code was written by people. Some AI assistance was used for boilerplate and for explaining the mathematics behind topics such as Kronecker products and gate matrices.