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.
Files changed (64) hide show
  1. {quantar-1.0.0 → quantar-1.2.0}/.gitignore +3 -0
  2. {quantar-1.0.0 → quantar-1.2.0}/PKG-INFO +181 -9
  3. quantar-1.2.0/README.md +370 -0
  4. {quantar-1.0.0 → quantar-1.2.0}/hatch_build.py +4 -0
  5. {quantar-1.0.0 → quantar-1.2.0}/pyproject.toml +18 -1
  6. quantar-1.2.0/rust/.idea/.gitignore +12 -0
  7. quantar-1.2.0/rust/.idea/modules.xml +8 -0
  8. quantar-1.2.0/rust/.idea/rust.iml +11 -0
  9. quantar-1.2.0/rust/.idea/vcs.xml +6 -0
  10. quantar-1.2.0/rust/.idea/workspace.xml +103 -0
  11. quantar-1.2.0/rust/Cargo.lock +359 -0
  12. quantar-1.2.0/rust/Cargo.toml +25 -0
  13. quantar-1.2.0/rust/src/api.rs +940 -0
  14. quantar-1.2.0/rust/src/gate.rs +280 -0
  15. quantar-1.2.0/rust/src/gates.rs +447 -0
  16. quantar-1.2.0/rust/src/lib.rs +715 -0
  17. quantar-1.2.0/rust/src/seed.rs +3 -0
  18. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/__init__.py +6 -2
  19. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/ast_builder.py +345 -273
  20. quantar-1.2.0/src/lang_systems/imports.py +255 -0
  21. quantar-1.2.0/src/lang_systems/lsp/server.py +691 -0
  22. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar.py +8 -19
  23. quantar-1.2.0/src/lang_systems/runner.py +151 -0
  24. quantar-1.2.0/src/lang_systems/symbol_table.py +290 -0
  25. {quantar-1.0.0 → quantar-1.2.0}/src/quantar/__init__.py +9 -0
  26. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/__init__.py +48 -3
  27. quantar-1.2.0/src/quantum/backend.py +511 -0
  28. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/gate_matrix.py +13 -2
  29. quantar-1.2.0/src/quantum/quantar_kernels.pdb +0 -0
  30. quantar-1.2.0/src/quantum/quantar_kernels.pyi +108 -0
  31. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/qubit_abs.py +39 -5
  32. quantar-1.2.0/src/quantum/seed_set.py +24 -0
  33. {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/duals_and_coords.py +2 -2
  34. {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/fast_factor.py +0 -2
  35. {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/quantum_optim_hl.py +3 -9
  36. quantar-1.0.0/README.md +0 -198
  37. quantar-1.0.0/src/lang_systems/lsp/server.py +0 -236
  38. quantar-1.0.0/src/lang_systems/runner.py +0 -53
  39. {quantar-1.0.0 → quantar-1.2.0}/Grammar/python.gram +0 -0
  40. {quantar-1.0.0 → quantar-1.2.0}/Grammar/python_clean.gram +0 -0
  41. {quantar-1.0.0 → quantar-1.2.0}/LICENSE +0 -0
  42. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/lsp/__init__.py +0 -0
  43. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/lsp/__main__.py +0 -0
  44. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/operators.py +0 -0
  45. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/pegen_gram_gen.py +0 -0
  46. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar.gram +0 -0
  47. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar_parser.py +0 -0
  48. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/quantar_tokens.py +0 -0
  49. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/runtime.py +0 -0
  50. {quantar-1.0.0 → quantar-1.2.0}/src/lang_systems/visitors.py +0 -0
  51. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/basic_funcs.py +0 -0
  52. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/composites.py +0 -0
  53. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/gate_abs.py +0 -0
  54. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/kernels.py +0 -0
  55. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/parse_qasm.py +0 -0
  56. {quantar-1.0.0 → quantar-1.2.0}/src/quantum/qasm.py +0 -0
  57. {quantar-1.0.0 → quantar-1.2.0}/src/stl/__init__.py +0 -0
  58. {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/__init__.py +0 -0
  59. {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/units.py +0 -0
  60. {quantar-1.0.0 → quantar-1.2.0}/src/stl/physics_algs/vector_fields.py +0 -0
  61. {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/__init__.py +0 -0
  62. {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/grovers_alg.py +0 -0
  63. {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/quantum_optim.py +0 -0
  64. {quantar-1.0.0 → quantar-1.2.0}/src/stl/quantum_algs/shors_alg.py +0 -0
@@ -223,3 +223,6 @@ __marimo__/
223
223
 
224
224
  # Streamlit
225
225
  .streamlit/secrets.toml
226
+
227
+ # Temporary Python documents used by Quantar/Pylance integration
228
+ **/.quantar-pylance-mirrors/
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: Quantar
3
- Version: 1.0.0
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
- ## Status
405
-
406
- Quantar currently provides the parser, AST, quantum library, physics library, a
407
- CLI runner/compiler, and a VS Code extension with syntax highlighting,
408
- operator highlighting, and parser diagnostics. A bytecode interpreter and
409
- debugger are not implemented yet.
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/Gautham-rgb/).
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.
@@ -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,8 @@
1
+ <?xml version="1.0" encoding="UTF-8"?>
2
+ <project version="4">
3
+ <component name="ProjectModuleManager">
4
+ <modules>
5
+ <module fileurl="file://$PROJECT_DIR$/.idea/rust.iml" filepath="$PROJECT_DIR$/.idea/rust.iml" />
6
+ </modules>
7
+ </component>
8
+ </project>
@@ -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>