Metadata-Version: 2.4
Name: qupac
Version: 0.1.0
Summary: Qupac (Quantum Python Abstraction Compiler): lightweight language for quantum circuits transpiled to Qiskit 2.x
Author: Amol Yadav
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: lark==1.3.0
Requires-Dist: qiskit==2.2.1
Requires-Dist: qiskit-aer==0.17.2
Provides-Extra: dev
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"

`# Qupac (Quantum Python Abstraction Compiler)

A lightweight language to design quantum circuits and transpile them to Python code using Qiskit 2.x. Write simple gate instructions; Qupac parses, transpiles, and can run the generated Python for simulation.

Highlights
- Minimal syntax for qubit/classical declarations, gate application, measurement, and simulate.
- CLI runs generated Python in the background by default on Windows.
- Optionally emit the generated Python without running it.

Project layout
- `qupac/grammar.lark` — Lark grammar for the language
- `qupac/parser.py` — Parser and transformer to an IR
- `qupac/transpiler.py` — IR -> Python (Qiskit 2.x) code generator
- `qupac/executor.py` — Runs generated Python (bg/fg)
- `qupac/cli.py` — CLI entrypoint (background by default)
- `main.qu` — Example program

Language quick reference
- Use statement: `use qiskit`
- Qubits: `qubits: <int>`
- Classical bits (optional): `classical: <int>`
- Apply gate: `apply H to 0` or `apply CX from 0 to 1`
 - Entangle two qubits: `entangle 0,1` (shorthand for `apply CX from 0 to 1`)
 - Put a qubit in superposition: `superpose 0` (shorthand for `apply H to 0`)
- Measure all: `measure all`
- Measure one: `measure 0 -> 0`
- Execute: `simulate`
 - Shots (number of measurement samples): `shots: 1024` (default 1024 if not provided)
 - Optimization level for transpile: `optimize: 0|1|2|3` (maps to Qiskit's optimization_level)
 - Draw the generated circuit: `draw` or `draw mpl` (text drawing is default; `mpl` attempts a matplotlib rendering)
- Simulator backend method: `simulator: default|statevector|unitary`
- Simple noise model (depolarizing): `noise depol p=0.01` (requires qiskit-aer noise modules)
- Comments: lines starting with `#` or `//`

Example `main.qu`

use qiskit

qubits: 3
classical: 3

apply H to 0
apply CX from 0 to 1
apply CX from 1 to 2

measure all

simulate

Other shorthand examples

```
use qiskit
qubits: 2
entangle 0,1
measure all
simulate
```

Or using superpose:

```
use qiskit
qubits: 1
superpose 0
measure all
simulate
```

Draw and simulation options

```
use qiskit
qubits: 2
entangle 0,1
draw
shots: 2048
optimize: 1
simulate
```

This will print a textual drawing of the circuit, transpile with optimization level 1, and run the simulator with 2048 shots.

Parameterized gates and statevector

```
use qiskit
qubits: 1
apply RY(1.5708) to 0
draw
simulator: statevector
shots: 1
simulate
```

Noise (depolarizing) example

```
use qiskit
qubits: 2
entangle 0,1
noise depol p=0.02
shots: 2048
simulate
```

Setup
1) Create and activate a Python 3.9+ environment.
2) Install dependencies (Qiskit is large; installing only Lark lets you test parsing/transpiling):
   - Minimal (parser/transpiler only):
     pip install lark
   - Full (to actually run/simulate):
     pip install -r requirements.txt

Developer setup (lint, type-check, tests)
- Install dev tools:
  - Using pip:
    pip install -e .[dev]
  - Or install individually:
    pip install ruff mypy pytest

- Lint (Ruff):
  ruff check .

- Type check (mypy):
  mypy qupac

- Run tests (pytest):
  pytest -q

How to run
- Dev, without installing the package:
  - Emit generated Python (no Qiskit needed):
    python -m qupac.cli --emit main.qu
  - Run generated Python in the background (requires Qiskit installed):
    python -m qupac.cli main.qu
  - Run in foreground/blocking (requires Qiskit installed):
    python -m qupac.cli --fg main.qu

- Install CLI (optional) to get the `qupac` command:
  pip install -e .
  qupac --emit main.qu
  qupac main.qu

Background execution and logs
- By default, Qupac runs the generated Python script in the background.
- Logs are written to `.qupac_build/` in your Qupac source folder. If you provide `--log`, output goes to that file.

Notes and limitations
- Rotation gates RX/RY/RZ need an angle; supported as numeric or expressions (e.g., `pi/2`).
- Measuring a specific qubit (e.g., `measure 0 -> 0`) requires an explicit `classical: N` declaration.
- Targeted for Qiskit 2.x APIs via `qiskit` and `qiskit-aer` packages.

Troubleshooting
- If your IDE shows "Invalid Python interpreter" or unresolved imports, make sure you’ve selected the correct Python environment and installed dependencies.
- If background runs don’t produce output, check `.qupac_build/*.log` files for error messages (e.g., missing Qiskit).

License
- MIT (add your license as appropriate)

