Quantar 1.0.0__tar.gz → 1.2.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {quantar-1.0.0 → quantar-1.2.0}/.gitignore +3 -0
- {quantar-1.0.0 → quantar-1.2.0}/PKG-INFO +181 -9
- quantar-1.2.0/README.md +370 -0
- {quantar-1.0.0 → quantar-1.2.0}/hatch_build.py +4 -0
- {quantar-1.0.0 → quantar-1.2.0}/pyproject.toml +18 -1
- quantar-1.2.0/rust/.idea/.gitignore +12 -0
- quantar-1.2.0/rust/.idea/modules.xml +8 -0
- quantar-1.2.0/rust/.idea/rust.iml +11 -0
- quantar-1.2.0/rust/.idea/vcs.xml +6 -0
- quantar-1.2.0/rust/.idea/workspace.xml +103 -0
- quantar-1.2.0/rust/Cargo.lock +359 -0
- quantar-1.2.0/rust/Cargo.toml +25 -0
- quantar-1.2.0/rust/src/api.rs +940 -0
- quantar-1.2.0/rust/src/gate.rs +280 -0
- quantar-1.2.0/rust/src/gates.rs +447 -0
- quantar-1.2.0/rust/src/lib.rs +715 -0
- quantar-1.2.0/rust/src/seed.rs +3 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/__init__.py +6 -2
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/ast_builder.py +345 -273
- quantar-1.2.0/src/lang_systems/imports.py +255 -0
- quantar-1.2.0/src/lang_systems/lsp/server.py +691 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar.py +8 -19
- quantar-1.2.0/src/lang_systems/runner.py +151 -0
- quantar-1.2.0/src/lang_systems/symbol_table.py +290 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantar/__init__.py +9 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/__init__.py +48 -3
- quantar-1.2.0/src/quantum/backend.py +511 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/gate_matrix.py +13 -2
- quantar-1.2.0/src/quantum/quantar_kernels.pdb +0 -0
- quantar-1.2.0/src/quantum/quantar_kernels.pyi +108 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/qubit_abs.py +39 -5
- quantar-1.2.0/src/quantum/seed_set.py +24 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/duals_and_coords.py +2 -2
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/fast_factor.py +0 -2
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/quantum_optim_hl.py +3 -9
- quantar-1.0.0/README.md +0 -198
- quantar-1.0.0/src/lang_systems/lsp/server.py +0 -236
- quantar-1.0.0/src/lang_systems/runner.py +0 -53
- {quantar-1.0.0 → quantar-1.2.0}/Grammar/python.gram +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/Grammar/python_clean.gram +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/LICENSE +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/lsp/__init__.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/lsp/__main__.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/operators.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/pegen_gram_gen.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar.gram +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar_parser.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar_tokens.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/runtime.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/visitors.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/basic_funcs.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/composites.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/gate_abs.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/kernels.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/parse_qasm.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/quantum/qasm.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/__init__.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/__init__.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/units.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/vector_fields.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/__init__.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/grovers_alg.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/quantum_optim.py +0 -0
- {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/shors_alg.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.5
|
|
2
2
|
Name: Quantar
|
|
3
|
-
Version: 1.
|
|
3
|
+
Version: 1.2.0
|
|
4
4
|
Summary: A Python superset for easy quantum computing, operator creation and physics simulations.
|
|
5
5
|
License: Apache License
|
|
6
6
|
Version 2.0, January 2004
|
|
@@ -223,6 +223,8 @@ Description-Content-Type: text/markdown
|
|
|
223
223
|
|
|
224
224
|
# Quantar
|
|
225
225
|
|
|
226
|
+
![Quantar Demo]()
|
|
227
|
+
|
|
226
228
|
Quantar is a strict superset of Python for quantum computing and physics
|
|
227
229
|
simulations. It keeps Python syntax and adds custom infix operators such as
|
|
228
230
|
`a <-> b`, plus a library of quantum gates, circuits, algorithms, and physics
|
|
@@ -231,6 +233,7 @@ helpers.
|
|
|
231
233
|
## Requirements
|
|
232
234
|
|
|
233
235
|
- Python 3.12 or newer
|
|
236
|
+
- Rust (to install it, click [here](https://rust-lang.org/tools/install/) and follow the commands)
|
|
234
237
|
- NumPy, Numba, and `openqasm3[parser]` (installed automatically)
|
|
235
238
|
|
|
236
239
|
## Installation
|
|
@@ -372,6 +375,130 @@ from stl.quantum_algs.shors_alg import shors_alg
|
|
|
372
375
|
from stl.physics_algs.units import Quantity, Unit
|
|
373
376
|
```
|
|
374
377
|
|
|
378
|
+
### Selecting a simulator backend
|
|
379
|
+
|
|
380
|
+
`QuantumComputer`, `Qubit`, and `Gate` follow the active backend. The default is
|
|
381
|
+
the pure-Python simulator; switch to the compiled Rust backend at runtime when
|
|
382
|
+
the extension is available:
|
|
383
|
+
|
|
384
|
+
```python
|
|
385
|
+
import quantum
|
|
386
|
+
|
|
387
|
+
print(quantum.get_backend()) # "python"
|
|
388
|
+
quantum.use_backend("rust") # or "python" to switch back
|
|
389
|
+
qc = quantum.QuantumComputer(2) # quantum.quantar_kernels.QuantumComputer
|
|
390
|
+
|
|
391
|
+
quantum.load_rust_backend() # import/validate the extension directly
|
|
392
|
+
quantum.available_backends() # e.g. ("python", "rust")
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
The backend can also be chosen before startup with `QUANTAR_BACKEND=rust`. The
|
|
396
|
+
bundled extension is built with PyO3's `abi3-py312` feature, so the same binary
|
|
397
|
+
works on CPython 3.12+ and wheels are tagged `cp312-abi3-*`. In the source tree
|
|
398
|
+
it is named `src/quantum/quantar_kernels.pyd`, with a copy kept in the root
|
|
399
|
+
`kernels/` directory.
|
|
400
|
+
|
|
401
|
+
If that extension is missing or stale, Quantar automatically builds it locally
|
|
402
|
+
when `cargo` and the `rust/` source tree are available:
|
|
403
|
+
|
|
404
|
+
```python
|
|
405
|
+
import quantum
|
|
406
|
+
|
|
407
|
+
quantum.rust_build_available() # True when cargo + rust/Cargo.toml are found
|
|
408
|
+
quantum.build_rust_backend() # force a fresh release build and load it
|
|
409
|
+
quantum.use_backend("rust") # auto-builds if needed
|
|
410
|
+
```
|
|
411
|
+
|
|
412
|
+
Environment overrides:
|
|
413
|
+
|
|
414
|
+
- `QUANTAR_RUST_AUTO_BUILD=0` disables automatic builds.
|
|
415
|
+
- `QUANTAR_RUST_SOURCE_DIR` points at the repo root or its `rust/` directory.
|
|
416
|
+
- `QUANTAR_CARGO` selects a specific cargo executable.
|
|
417
|
+
- `QUANTAR_RUST_BACKEND_PATH` loads a specific `.pyd`/`.so` instead.
|
|
418
|
+
- `QUANTAR_RUST_BUILD_CACHE` changes the fallback output directory when the
|
|
419
|
+
installed package directory is not writable.
|
|
420
|
+
|
|
421
|
+
### Building the Rust backend manually
|
|
422
|
+
|
|
423
|
+
```powershell
|
|
424
|
+
$env:PYO3_PYTHON = "C:\path\to\your\python.exe"
|
|
425
|
+
cargo build --release --manifest-path rust/Cargo.toml
|
|
426
|
+
|
|
427
|
+
Copy-Item rust\target\release\quantar_kernels.dll `
|
|
428
|
+
src\quantum\quantar_kernels.pyd -Force
|
|
429
|
+
Copy-Item rust\target\release\quantar_kernels.dll `
|
|
430
|
+
kernels\quantar_kernels.pyd -Force
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
For distribution, prefer wheels over copying `.pyd` files by hand. The
|
|
434
|
+
GIL-enabled wheel is tagged `cp312-abi3-*`; free-threaded builds need their own
|
|
435
|
+
wheels as described below.
|
|
436
|
+
|
|
437
|
+
### Free-threaded Python
|
|
438
|
+
|
|
439
|
+
Quantar can build and load the Rust backend on free-threaded CPython. The ABI
|
|
440
|
+
matrix is:
|
|
441
|
+
|
|
442
|
+
| Interpreter | Extension built from source | Prebuilt wheel to publish |
|
|
443
|
+
| --- | --- | --- |
|
|
444
|
+
| CPython 3.12–3.14, GIL enabled | `abi3` (`abi3-py312`) | `cp312-abi3-*` |
|
|
445
|
+
| CPython 3.14t, free-threaded | version-specific `cp314t` | `cp314t-*` |
|
|
446
|
+
| CPython 3.15/3.15t and newer | `abi3t` (`abi3t-py315`) | `abi3t-*` |
|
|
447
|
+
|
|
448
|
+
Important details:
|
|
449
|
+
|
|
450
|
+
- The existing `cp312-abi3-*` wheel **cannot** be installed on a free-threaded
|
|
451
|
+
interpreter; pip rejects it as unsupported. Install a free-threaded wheel or
|
|
452
|
+
install from source with the free-threaded interpreter.
|
|
453
|
+
- `python3.14t -m pip install .` compiles a `cp314t` extension automatically.
|
|
454
|
+
- Python 3.15+ uses PEP 803's `abi3t` stable ABI, so one binary works with both
|
|
455
|
+
GIL-enabled and free-threaded interpreters.
|
|
456
|
+
- PyO3 0.30 no longer supports CPython 3.13t; use 3.14t or newer.
|
|
457
|
+
- The runtime loader detects `Py_GIL_DISABLED`, so local auto-builds never write
|
|
458
|
+
a GIL-only `abi3` extension for a free-threaded interpreter.
|
|
459
|
+
|
|
460
|
+
```powershell
|
|
461
|
+
uv python install 3.14t
|
|
462
|
+
uv venv --python 3.14t .venv-3.14t
|
|
463
|
+
.\.venv-3.14t\Scripts\python.exe -m pip install . --no-deps
|
|
464
|
+
.\.venv-3.14t\Scripts\python.exe -c "import quantum; print(quantum.is_free_threaded()); quantum.use_backend('rust')"
|
|
465
|
+
```
|
|
466
|
+
|
|
467
|
+
The extension declares `gil_used = false`: NumPy access uses borrow guards and
|
|
468
|
+
the heavy kernels run after `py.detach`, so importing it does not force the
|
|
469
|
+
interpreter to re-enable the GIL.
|
|
470
|
+
|
|
471
|
+
### Imports in Quantar programs
|
|
472
|
+
|
|
473
|
+
Regular Python imports work inside `.qtr` files, and Quantar can import other
|
|
474
|
+
`.qtr` modules too:
|
|
475
|
+
|
|
476
|
+
```python
|
|
477
|
+
# gates.qtr
|
|
478
|
+
from lang_systems.operators import operator
|
|
479
|
+
|
|
480
|
+
@operator.binary("<~>")
|
|
481
|
+
def reverse(left, right):
|
|
482
|
+
return right, left
|
|
483
|
+
|
|
484
|
+
VALUE = 42
|
|
485
|
+
```
|
|
486
|
+
|
|
487
|
+
```python
|
|
488
|
+
# main.qtr
|
|
489
|
+
from gates import VALUE
|
|
490
|
+
import gates
|
|
491
|
+
|
|
492
|
+
a, b = 1, 2
|
|
493
|
+
print(a <~> b) # operator is registered before parsing
|
|
494
|
+
print(VALUE)
|
|
495
|
+
```
|
|
496
|
+
|
|
497
|
+
Run it with `qtr main.qtr`. Directory packages with `__init__.qtr` support
|
|
498
|
+
relative imports such as `from .gates import VALUE`. The runner adds the source
|
|
499
|
+
file's directory to `sys.path`, so sibling `.py` and `.qtr` modules are found
|
|
500
|
+
without extra setup. Compiled `.py` output installs the same import hook.
|
|
501
|
+
|
|
375
502
|
See the modules under `src/quantum/` and `src/stl/` for the available gates,
|
|
376
503
|
circuits, algorithms, and physics helpers.
|
|
377
504
|
|
|
@@ -401,21 +528,66 @@ The generated parser is `src/lang_systems/quantar_parser.py`; the build hook in
|
|
|
401
528
|
CPython's `Grammar/python.gram` plus the operator overlay in
|
|
402
529
|
`src/lang_systems/quantar.gram`.
|
|
403
530
|
|
|
404
|
-
##
|
|
405
|
-
|
|
406
|
-
Quantar
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
531
|
+
## Project maturity
|
|
532
|
+
|
|
533
|
+
Quantar is usable today as a Python superset for quantum programs, but it is
|
|
534
|
+
still a maturing project. The core language frontend, simulator, Rust backend,
|
|
535
|
+
and CLI are in place; tooling, platform coverage, and the compiled execution
|
|
536
|
+
pipeline are still being expanded. See [roadmap.md](roadmap.md) for the planned
|
|
537
|
+
work.
|
|
538
|
+
|
|
539
|
+
### What is stable enough to use
|
|
540
|
+
|
|
541
|
+
- **Language frontend:** the parser and AST builder handle Python syntax plus
|
|
542
|
+
Quantar's custom infix operators.
|
|
543
|
+
- **Imports:** `.py` imports and `.qtr` module imports work, including operator
|
|
544
|
+
preloading, sibling modules, and relative imports inside packages.
|
|
545
|
+
- **Simulation:** the pure-Python/NumPy backend is the default and supports the
|
|
546
|
+
main state-vector operations, circuits, QFT helpers, measurement, sampling,
|
|
547
|
+
and QASM export.
|
|
548
|
+
- **Rust backend:** the optional compiled backend mirrors the Python API. It
|
|
549
|
+
uses `abi3-py312` on GIL-enabled CPython and can build for free-threaded
|
|
550
|
+
interpreters (`cp314t` or `abi3t-py315`). If the extension is missing or
|
|
551
|
+
stale, Quantar can build it locally when `cargo` and the Rust source tree are
|
|
552
|
+
available.
|
|
553
|
+
- **CLI:** `qtr` can run or compile `.qtr` files.
|
|
554
|
+
- **LSP basics:** the VS Code extension provides syntax highlighting, operator
|
|
555
|
+
highlighting, and parser diagnostics.
|
|
556
|
+
|
|
557
|
+
### What is still evolving
|
|
558
|
+
|
|
559
|
+
- The Rust backend API is additive and tested for parity, but its surface is
|
|
560
|
+
still growing.
|
|
561
|
+
- Distribution currently produces a Windows `cp312-abi3` wheel from this
|
|
562
|
+
checkout; Linux/macOS wheels and prebuilt free-threaded wheels are planned.
|
|
563
|
+
Free-threaded users can install from source today.
|
|
564
|
+
- The `.qtr` import hook works for common cases, but namespace packages,
|
|
565
|
+
reloads, and circular-import diagnostics are still being refined.
|
|
566
|
+
- Error messages and source locations are being improved across the parser,
|
|
567
|
+
runner, and LSP.
|
|
568
|
+
- Performance work is ongoing, especially for multi-controlled gates, common
|
|
569
|
+
1-qubit/2-qubit kernels, and Python-to-Rust callback reduction.
|
|
570
|
+
|
|
571
|
+
### What is not implemented yet
|
|
572
|
+
|
|
573
|
+
- A dedicated Quantar bytecode interpreter.
|
|
574
|
+
- A debugger with breakpoints, stepping, and state inspection.
|
|
575
|
+
- GPU, distributed, or tensor-network execution backends.
|
|
576
|
+
- Full LSP support for completions, hover documentation, and cross-file
|
|
577
|
+
go-to-definition.
|
|
578
|
+
|
|
579
|
+
In short: Quantar is ready for experimentation, teaching, prototyping, and
|
|
580
|
+
library use on supported platforms. It is not yet a finished production
|
|
581
|
+
toolchain, and the roadmap tracks the work needed to get there.
|
|
410
582
|
|
|
411
583
|
## Feedback
|
|
412
584
|
|
|
413
585
|
Feedback and bug reports are welcome through GitHub issues or by contacting the
|
|
414
586
|
maintainer. The main contributor is
|
|
415
|
-
[Gautham_rgb](https://github.com/
|
|
587
|
+
[Gautham_rgb](https://github.com/systemic-speed/).
|
|
416
588
|
|
|
417
589
|
## Notes on AI
|
|
418
590
|
|
|
419
591
|
Most of the code was written by people. Some AI assistance was used for
|
|
420
592
|
boilerplate and for explaining the mathematics behind topics such as Kronecker
|
|
421
|
-
products and gate matrices.
|
|
593
|
+
products and gate matrices and for understanding Rust.
|
quantar-1.2.0/README.md
ADDED
|
@@ -0,0 +1,370 @@
|
|
|
1
|
+
# Quantar
|
|
2
|
+
|
|
3
|
+
![Quantar Demo]()
|
|
4
|
+
|
|
5
|
+
Quantar is a strict superset of Python for quantum computing and physics
|
|
6
|
+
simulations. It keeps Python syntax and adds custom infix operators such as
|
|
7
|
+
`a <-> b`, plus a library of quantum gates, circuits, algorithms, and physics
|
|
8
|
+
helpers.
|
|
9
|
+
|
|
10
|
+
## Requirements
|
|
11
|
+
|
|
12
|
+
- Python 3.12 or newer
|
|
13
|
+
- Rust (to install it, click [here](https://rust-lang.org/tools/install/) and follow the commands)
|
|
14
|
+
- NumPy, Numba, and `openqasm3[parser]` (installed automatically)
|
|
15
|
+
|
|
16
|
+
## Installation
|
|
17
|
+
|
|
18
|
+
```bash
|
|
19
|
+
pip install quantar
|
|
20
|
+
|
|
21
|
+
# or with uv
|
|
22
|
+
uv pip install quantar
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Optional extras:
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
# alternative quantum backends
|
|
29
|
+
pip install quantar[backends]
|
|
30
|
+
|
|
31
|
+
# SciPy-powered COBYLA optimization
|
|
32
|
+
pip install quantar[optimization]
|
|
33
|
+
|
|
34
|
+
# LSP support
|
|
35
|
+
pip install quantar[lsp]
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
also install the VS code extension [here](https://marketplace.visualstudio.com/items?itemName=Gauthamrgb.quantar-lang) for better coloring and errors or just use the `ext` command as follows:
|
|
39
|
+
```bash
|
|
40
|
+
ext install Gauthamrgb.quantar-lang
|
|
41
|
+
```
|
|
42
|
+
## Running Quantar
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
qtr path/to/program.qtr
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Compile a file to ordinary Python instead of executing it:
|
|
49
|
+
|
|
50
|
+
```bash
|
|
51
|
+
qtr path/to/program.qtr --compile path/to/program.py
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
During development, the same runner is available as a module:
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
python -m lang_systems.runner path/to/program.qtr
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
Small registers use vectorized NumPy so short programs skip Numba's startup and
|
|
61
|
+
compilation cost. Registers with at least 1,048,576 amplitudes use the JIT. Set
|
|
62
|
+
`QUANTAR_NUMBA_MIN_AMPLITUDES` to change that cutoff, or `QUANTAR_NUMBA=0` to
|
|
63
|
+
disable Numba entirely.
|
|
64
|
+
|
|
65
|
+
## VS Code extension
|
|
66
|
+
|
|
67
|
+
The extension lives in `extension/`. It provides Python-based syntax
|
|
68
|
+
highlighting for `.qtr` and `.quantar` files, parser diagnostics, and semantic
|
|
69
|
+
highlighting for registered Quantar operators. Operators use one consistent
|
|
70
|
+
cyan accent; the rest of the syntax follows the active VS Code theme.
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
python -m pip install -e ".[lsp]"
|
|
74
|
+
cd extension
|
|
75
|
+
npm install
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
Open the project root in VS Code and press F5 to launch the `Run Quantar
|
|
79
|
+
Extension` development configuration. The extension uses the Python
|
|
80
|
+
interpreter selected by the VS Code Python extension. Install the LSP extra in
|
|
81
|
+
that interpreter; for a local checkout, run the install command above from the
|
|
82
|
+
project root.
|
|
83
|
+
|
|
84
|
+
## Parsing Quantar
|
|
85
|
+
|
|
86
|
+
`lang_systems.parse()` returns pegen's raw parse tree. This is the low-level
|
|
87
|
+
form used by tooling and tests:
|
|
88
|
+
|
|
89
|
+
```python
|
|
90
|
+
from lang_systems import parse
|
|
91
|
+
|
|
92
|
+
tree = parse("a <-> b\nx = 1 + 2\n")
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`lang_systems.parse_ast()` returns a normal Python AST with custom `QuantumOp`
|
|
96
|
+
nodes:
|
|
97
|
+
|
|
98
|
+
```python
|
|
99
|
+
import ast
|
|
100
|
+
|
|
101
|
+
from lang_systems import OperatorCollector, parse_ast
|
|
102
|
+
|
|
103
|
+
module = parse_ast("x = a <-> b\n")
|
|
104
|
+
print(ast.dump(module, indent=2))
|
|
105
|
+
|
|
106
|
+
collector = OperatorCollector()
|
|
107
|
+
collector.visit(module)
|
|
108
|
+
print(collector.operators) # [("<->", "binary")]
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Custom operators are registered with `lang_systems.operators.operator`:
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
from lang_systems.operators import operator
|
|
115
|
+
|
|
116
|
+
@operator.binary("><")
|
|
117
|
+
def reverse(left, right):
|
|
118
|
+
return right, left
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
If the operators live in another module, import that module before parsing:
|
|
122
|
+
|
|
123
|
+
```python
|
|
124
|
+
from lang_systems import load_operators, parse
|
|
125
|
+
|
|
126
|
+
load_operators("my_package.quantar_ops")
|
|
127
|
+
tree = parse("a >< b\n")
|
|
128
|
+
```
|
|
129
|
+
|
|
130
|
+
## Quantar as a library
|
|
131
|
+
|
|
132
|
+
`quantar` is the umbrella package. It loads the language, quantum, and physics
|
|
133
|
+
packages lazily, so importing it stays lightweight:
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
import quantar
|
|
137
|
+
|
|
138
|
+
q = quantar.QuantumComputer(2)
|
|
139
|
+
tree = quantar.parse_ast("a <-> b\n")
|
|
140
|
+
print(quantar.__version__)
|
|
141
|
+
|
|
142
|
+
quantar.lang_systems
|
|
143
|
+
quantar.quantum
|
|
144
|
+
quantar.stl
|
|
145
|
+
```
|
|
146
|
+
|
|
147
|
+
The underlying packages can still be imported directly:
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
import quantum
|
|
151
|
+
from stl.quantum_algs.shors_alg import shors_alg
|
|
152
|
+
from stl.physics_algs.units import Quantity, Unit
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### Selecting a simulator backend
|
|
156
|
+
|
|
157
|
+
`QuantumComputer`, `Qubit`, and `Gate` follow the active backend. The default is
|
|
158
|
+
the pure-Python simulator; switch to the compiled Rust backend at runtime when
|
|
159
|
+
the extension is available:
|
|
160
|
+
|
|
161
|
+
```python
|
|
162
|
+
import quantum
|
|
163
|
+
|
|
164
|
+
print(quantum.get_backend()) # "python"
|
|
165
|
+
quantum.use_backend("rust") # or "python" to switch back
|
|
166
|
+
qc = quantum.QuantumComputer(2) # quantum.quantar_kernels.QuantumComputer
|
|
167
|
+
|
|
168
|
+
quantum.load_rust_backend() # import/validate the extension directly
|
|
169
|
+
quantum.available_backends() # e.g. ("python", "rust")
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
The backend can also be chosen before startup with `QUANTAR_BACKEND=rust`. The
|
|
173
|
+
bundled extension is built with PyO3's `abi3-py312` feature, so the same binary
|
|
174
|
+
works on CPython 3.12+ and wheels are tagged `cp312-abi3-*`. In the source tree
|
|
175
|
+
it is named `src/quantum/quantar_kernels.pyd`, with a copy kept in the root
|
|
176
|
+
`kernels/` directory.
|
|
177
|
+
|
|
178
|
+
If that extension is missing or stale, Quantar automatically builds it locally
|
|
179
|
+
when `cargo` and the `rust/` source tree are available:
|
|
180
|
+
|
|
181
|
+
```python
|
|
182
|
+
import quantum
|
|
183
|
+
|
|
184
|
+
quantum.rust_build_available() # True when cargo + rust/Cargo.toml are found
|
|
185
|
+
quantum.build_rust_backend() # force a fresh release build and load it
|
|
186
|
+
quantum.use_backend("rust") # auto-builds if needed
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
Environment overrides:
|
|
190
|
+
|
|
191
|
+
- `QUANTAR_RUST_AUTO_BUILD=0` disables automatic builds.
|
|
192
|
+
- `QUANTAR_RUST_SOURCE_DIR` points at the repo root or its `rust/` directory.
|
|
193
|
+
- `QUANTAR_CARGO` selects a specific cargo executable.
|
|
194
|
+
- `QUANTAR_RUST_BACKEND_PATH` loads a specific `.pyd`/`.so` instead.
|
|
195
|
+
- `QUANTAR_RUST_BUILD_CACHE` changes the fallback output directory when the
|
|
196
|
+
installed package directory is not writable.
|
|
197
|
+
|
|
198
|
+
### Building the Rust backend manually
|
|
199
|
+
|
|
200
|
+
```powershell
|
|
201
|
+
$env:PYO3_PYTHON = "C:\path\to\your\python.exe"
|
|
202
|
+
cargo build --release --manifest-path rust/Cargo.toml
|
|
203
|
+
|
|
204
|
+
Copy-Item rust\target\release\quantar_kernels.dll `
|
|
205
|
+
src\quantum\quantar_kernels.pyd -Force
|
|
206
|
+
Copy-Item rust\target\release\quantar_kernels.dll `
|
|
207
|
+
kernels\quantar_kernels.pyd -Force
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
For distribution, prefer wheels over copying `.pyd` files by hand. The
|
|
211
|
+
GIL-enabled wheel is tagged `cp312-abi3-*`; free-threaded builds need their own
|
|
212
|
+
wheels as described below.
|
|
213
|
+
|
|
214
|
+
### Free-threaded Python
|
|
215
|
+
|
|
216
|
+
Quantar can build and load the Rust backend on free-threaded CPython. The ABI
|
|
217
|
+
matrix is:
|
|
218
|
+
|
|
219
|
+
| Interpreter | Extension built from source | Prebuilt wheel to publish |
|
|
220
|
+
| --- | --- | --- |
|
|
221
|
+
| CPython 3.12–3.14, GIL enabled | `abi3` (`abi3-py312`) | `cp312-abi3-*` |
|
|
222
|
+
| CPython 3.14t, free-threaded | version-specific `cp314t` | `cp314t-*` |
|
|
223
|
+
| CPython 3.15/3.15t and newer | `abi3t` (`abi3t-py315`) | `abi3t-*` |
|
|
224
|
+
|
|
225
|
+
Important details:
|
|
226
|
+
|
|
227
|
+
- The existing `cp312-abi3-*` wheel **cannot** be installed on a free-threaded
|
|
228
|
+
interpreter; pip rejects it as unsupported. Install a free-threaded wheel or
|
|
229
|
+
install from source with the free-threaded interpreter.
|
|
230
|
+
- `python3.14t -m pip install .` compiles a `cp314t` extension automatically.
|
|
231
|
+
- Python 3.15+ uses PEP 803's `abi3t` stable ABI, so one binary works with both
|
|
232
|
+
GIL-enabled and free-threaded interpreters.
|
|
233
|
+
- PyO3 0.30 no longer supports CPython 3.13t; use 3.14t or newer.
|
|
234
|
+
- The runtime loader detects `Py_GIL_DISABLED`, so local auto-builds never write
|
|
235
|
+
a GIL-only `abi3` extension for a free-threaded interpreter.
|
|
236
|
+
|
|
237
|
+
```powershell
|
|
238
|
+
uv python install 3.14t
|
|
239
|
+
uv venv --python 3.14t .venv-3.14t
|
|
240
|
+
.\.venv-3.14t\Scripts\python.exe -m pip install . --no-deps
|
|
241
|
+
.\.venv-3.14t\Scripts\python.exe -c "import quantum; print(quantum.is_free_threaded()); quantum.use_backend('rust')"
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
The extension declares `gil_used = false`: NumPy access uses borrow guards and
|
|
245
|
+
the heavy kernels run after `py.detach`, so importing it does not force the
|
|
246
|
+
interpreter to re-enable the GIL.
|
|
247
|
+
|
|
248
|
+
### Imports in Quantar programs
|
|
249
|
+
|
|
250
|
+
Regular Python imports work inside `.qtr` files, and Quantar can import other
|
|
251
|
+
`.qtr` modules too:
|
|
252
|
+
|
|
253
|
+
```python
|
|
254
|
+
# gates.qtr
|
|
255
|
+
from lang_systems.operators import operator
|
|
256
|
+
|
|
257
|
+
@operator.binary("<~>")
|
|
258
|
+
def reverse(left, right):
|
|
259
|
+
return right, left
|
|
260
|
+
|
|
261
|
+
VALUE = 42
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
```python
|
|
265
|
+
# main.qtr
|
|
266
|
+
from gates import VALUE
|
|
267
|
+
import gates
|
|
268
|
+
|
|
269
|
+
a, b = 1, 2
|
|
270
|
+
print(a <~> b) # operator is registered before parsing
|
|
271
|
+
print(VALUE)
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
Run it with `qtr main.qtr`. Directory packages with `__init__.qtr` support
|
|
275
|
+
relative imports such as `from .gates import VALUE`. The runner adds the source
|
|
276
|
+
file's directory to `sys.path`, so sibling `.py` and `.qtr` modules are found
|
|
277
|
+
without extra setup. Compiled `.py` output installs the same import hook.
|
|
278
|
+
|
|
279
|
+
See the modules under `src/quantum/` and `src/stl/` for the available gates,
|
|
280
|
+
circuits, algorithms, and physics helpers.
|
|
281
|
+
|
|
282
|
+
## Development
|
|
283
|
+
|
|
284
|
+
The Python packages live under `src/`. Install the project in editable mode
|
|
285
|
+
before running the CLI or LSP from a checkout:
|
|
286
|
+
|
|
287
|
+
```bash
|
|
288
|
+
pip install -e ".[lsp]"
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Regenerate the parser after changing `src/lang_systems/quantar.gram`:
|
|
292
|
+
|
|
293
|
+
```bash
|
|
294
|
+
python -m lang_systems.pegen_gram_gen
|
|
295
|
+
```
|
|
296
|
+
|
|
297
|
+
Build the wheel and source distribution:
|
|
298
|
+
|
|
299
|
+
```bash
|
|
300
|
+
uv build
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
The generated parser is `src/lang_systems/quantar_parser.py`; the build hook in
|
|
304
|
+
`hatch_build.py` regenerates it automatically. The parser is generated from
|
|
305
|
+
CPython's `Grammar/python.gram` plus the operator overlay in
|
|
306
|
+
`src/lang_systems/quantar.gram`.
|
|
307
|
+
|
|
308
|
+
## Project maturity
|
|
309
|
+
|
|
310
|
+
Quantar is usable today as a Python superset for quantum programs, but it is
|
|
311
|
+
still a maturing project. The core language frontend, simulator, Rust backend,
|
|
312
|
+
and CLI are in place; tooling, platform coverage, and the compiled execution
|
|
313
|
+
pipeline are still being expanded. See [roadmap.md](roadmap.md) for the planned
|
|
314
|
+
work.
|
|
315
|
+
|
|
316
|
+
### What is stable enough to use
|
|
317
|
+
|
|
318
|
+
- **Language frontend:** the parser and AST builder handle Python syntax plus
|
|
319
|
+
Quantar's custom infix operators.
|
|
320
|
+
- **Imports:** `.py` imports and `.qtr` module imports work, including operator
|
|
321
|
+
preloading, sibling modules, and relative imports inside packages.
|
|
322
|
+
- **Simulation:** the pure-Python/NumPy backend is the default and supports the
|
|
323
|
+
main state-vector operations, circuits, QFT helpers, measurement, sampling,
|
|
324
|
+
and QASM export.
|
|
325
|
+
- **Rust backend:** the optional compiled backend mirrors the Python API. It
|
|
326
|
+
uses `abi3-py312` on GIL-enabled CPython and can build for free-threaded
|
|
327
|
+
interpreters (`cp314t` or `abi3t-py315`). If the extension is missing or
|
|
328
|
+
stale, Quantar can build it locally when `cargo` and the Rust source tree are
|
|
329
|
+
available.
|
|
330
|
+
- **CLI:** `qtr` can run or compile `.qtr` files.
|
|
331
|
+
- **LSP basics:** the VS Code extension provides syntax highlighting, operator
|
|
332
|
+
highlighting, and parser diagnostics.
|
|
333
|
+
|
|
334
|
+
### What is still evolving
|
|
335
|
+
|
|
336
|
+
- The Rust backend API is additive and tested for parity, but its surface is
|
|
337
|
+
still growing.
|
|
338
|
+
- Distribution currently produces a Windows `cp312-abi3` wheel from this
|
|
339
|
+
checkout; Linux/macOS wheels and prebuilt free-threaded wheels are planned.
|
|
340
|
+
Free-threaded users can install from source today.
|
|
341
|
+
- The `.qtr` import hook works for common cases, but namespace packages,
|
|
342
|
+
reloads, and circular-import diagnostics are still being refined.
|
|
343
|
+
- Error messages and source locations are being improved across the parser,
|
|
344
|
+
runner, and LSP.
|
|
345
|
+
- Performance work is ongoing, especially for multi-controlled gates, common
|
|
346
|
+
1-qubit/2-qubit kernels, and Python-to-Rust callback reduction.
|
|
347
|
+
|
|
348
|
+
### What is not implemented yet
|
|
349
|
+
|
|
350
|
+
- A dedicated Quantar bytecode interpreter.
|
|
351
|
+
- A debugger with breakpoints, stepping, and state inspection.
|
|
352
|
+
- GPU, distributed, or tensor-network execution backends.
|
|
353
|
+
- Full LSP support for completions, hover documentation, and cross-file
|
|
354
|
+
go-to-definition.
|
|
355
|
+
|
|
356
|
+
In short: Quantar is ready for experimentation, teaching, prototyping, and
|
|
357
|
+
library use on supported platforms. It is not yet a finished production
|
|
358
|
+
toolchain, and the roadmap tracks the work needed to get there.
|
|
359
|
+
|
|
360
|
+
## Feedback
|
|
361
|
+
|
|
362
|
+
Feedback and bug reports are welcome through GitHub issues or by contacting the
|
|
363
|
+
maintainer. The main contributor is
|
|
364
|
+
[Gautham_rgb](https://github.com/systemic-speed/).
|
|
365
|
+
|
|
366
|
+
## Notes on AI
|
|
367
|
+
|
|
368
|
+
Most of the code was written by people. Some AI assistance was used for
|
|
369
|
+
boilerplate and for explaining the mathematics behind topics such as Kronecker
|
|
370
|
+
products and gate matrices and for understanding Rust.
|
|
@@ -22,6 +22,10 @@ class PegenBuildHook(BuildHookInterface):
|
|
|
22
22
|
PLUGIN_NAME = "pegen"
|
|
23
23
|
|
|
24
24
|
def initialize(self, version, build_data):
|
|
25
|
+
# hatch-maturin-build only streams `maturin build` output when Hatch's
|
|
26
|
+
# verbosity is nonzero. Keep Rust/cargo build details visible by default.
|
|
27
|
+
self.app.verbosity = max(getattr(self.app, "verbosity", 0), 1) #type: ignore
|
|
28
|
+
|
|
25
29
|
self._fetch_python_grammar()
|
|
26
30
|
self._generate_parser()
|
|
27
31
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
[build-system]
|
|
2
|
-
requires = ["hatchling", "pegen>=0.3.0"]
|
|
2
|
+
requires = ["hatchling", "pegen>=0.3.0", "hatch-maturin-build", "maturin>=1.7,<2.0"]
|
|
3
3
|
build-backend = "hatchling.build"
|
|
4
4
|
|
|
5
5
|
[project]
|
|
@@ -38,9 +38,11 @@ packages = ["src/quantar", "src/quantum", "src/stl", "src/lang_systems"]
|
|
|
38
38
|
[tool.hatch.build.targets.sdist]
|
|
39
39
|
include = [
|
|
40
40
|
"/README.md",
|
|
41
|
+
"/roadmap.md",
|
|
41
42
|
"/LICENSE",
|
|
42
43
|
"/pyproject.toml",
|
|
43
44
|
"/hatch_build.py",
|
|
45
|
+
"/rust",
|
|
44
46
|
"/src/quantar",
|
|
45
47
|
"/src/quantum",
|
|
46
48
|
"/src/stl",
|
|
@@ -49,6 +51,21 @@ include = [
|
|
|
49
51
|
"/Grammar/python_clean.gram",
|
|
50
52
|
]
|
|
51
53
|
|
|
54
|
+
exclude = [
|
|
55
|
+
"/rust/target",
|
|
56
|
+
]
|
|
57
|
+
|
|
58
|
+
[tool.maturin]
|
|
59
|
+
manifest-path = "rust/Cargo.toml"
|
|
60
|
+
python-source = "src"
|
|
61
|
+
module-name = "quantum.quantar_kernels"
|
|
62
|
+
|
|
52
63
|
[project.scripts]
|
|
53
64
|
qtr = "lang_systems.runner:main"
|
|
54
65
|
quantar-lsp = "lang_systems.lsp.server:main"
|
|
66
|
+
|
|
67
|
+
[tool.hatch.build.targets.wheel.hooks.maturin]
|
|
68
|
+
manifest-path = "rust/Cargo.toml"
|
|
69
|
+
# Passed straight to `maturin build`; -vv shows cargo/build.rs detail.
|
|
70
|
+
args = ["-vv"]
|
|
71
|
+
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
# Default ignored files
|
|
2
|
+
/shelf/
|
|
3
|
+
/workspace.xml
|
|
4
|
+
# Markdown personal settings
|
|
5
|
+
/markdown.xml
|
|
6
|
+
# Editor-based HTTP Client requests
|
|
7
|
+
/httpRequests/
|
|
8
|
+
# Ignored default folder with query files
|
|
9
|
+
/queries/
|
|
10
|
+
# Datasource local storage ignored files
|
|
11
|
+
/dataSources/
|
|
12
|
+
/dataSources.local.xml
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
<?xml version="1.0" encoding="UTF-8"?>
|
|
2
|
+
<module type="EMPTY_MODULE" version="4">
|
|
3
|
+
<component name="NewModuleRootManager">
|
|
4
|
+
<content url="file://$MODULE_DIR$">
|
|
5
|
+
<sourceFolder url="file://$MODULE_DIR$/src" isTestSource="false" />
|
|
6
|
+
<excludeFolder url="file://$MODULE_DIR$/target" />
|
|
7
|
+
</content>
|
|
8
|
+
<orderEntry type="inheritedJdk" />
|
|
9
|
+
<orderEntry type="sourceFolder" forTests="false" />
|
|
10
|
+
</component>
|
|
11
|
+
</module>
|