SansqritPy Complete Reference

COMPLETE_ARCHITECTURE_AND_DSL_REFERENCE.md

Sansqrit Quantum DSL

Author / maintainer: Karthik V Version: 0.3.3 Package: sansqrit Purpose: a simplified quantum-computing DSL and Python runtime for scientists, AI/ML training datasets, educational quantum-programming examples, sparse/sharded simulation, lookup-accelerated execution, hierarchical tensor shards, QEC, and hardware export workflows.

Sansqrit is designed to make quantum circuits readable:

simulate(120, engine="hierarchical", block_size=10) {
    q = quantum_register(120)
    shard node_0 [0..9]
    shard node_1 [10..19]

    apply H on node_0
    X(q[119])
    apply CNOT on q[9], q[10] bridge_mode=sparse

    print(hierarchical_report())
    print(lookup_profile())
}

It is not a claim that arbitrary dense 120-qubit state-vector simulation is possible on local hardware. Sansqrit supports 120+ logical qubit programs when the circuit remains sparse, Clifford-structured, low-entanglement, or decomposable into independent tensor blocks.

---

Table of contents

1. Installation
2. Quick start
3. Execution architecture
4. 120-qubit dense simulation reality
5. Sparse, sharded, hierarchical and MPS modes
6. Precomputed lookup files
7. Distributed computing model
8. GPU backend
9. Stabilizer backend
10. Density/noise backend
11. Quantum error correction framework
12. Hardware export: Qiskit, Cirq, Braket, Azure, PennyLane, QASM
13. Complete DSL syntax
14. Gate/function reference
15. Algorithms and high-level helpers
16. Logging, diagnostics and troubleshooting
17. AI/ML training usage
18. Real-world 120+ qubit examples
19. PyPI upload/release notes
20. Limitations and safe claims

---

1. Installation

pip install sansqrit

Optional integrations:

pip install "sansqrit[qiskit]"
pip install "sansqrit[cirq]"
pip install "sansqrit[braket]"
pip install "sansqrit[pennylane]"
pip install "sansqrit[gpu]"
pip install "sansqrit[all]"

Development install:

git clone <your-repo-url>
cd sansqrit
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[all,dev]"

---

2. Quick start

Create bell.sq:

simulate(2, engine="sparse") {
    q = quantum_register(2)
    H(q[0])
    CNOT(q[0], q[1])
    print(probabilities())
    print(measure_all(shots=10))
}

Run:

sansqrit run bell.sq

Export QASM:

sansqrit qasm bell.sq --version 3 -o bell.qasm

Inspect environment:

sansqrit doctor
sansqrit backends
sansqrit estimate 120
sansqrit architecture
sansqrit troubleshoot lookup
sansqrit hardware

---

3. Execution architecture

Sansqrit uses a layered runtime:

flowchart TD
    A[Sansqrit .sq DSL] --> B[Translator / Parser]
    B --> C[Circuit History + Runtime Engine]
    C --> D[Optimizer Passes]
    D --> E[Adaptive Planner]
    E -->|Sparse / few amplitudes| F[Sparse State Map]
    E -->|Large sparse| G[Sharded Sparse State]
    E -->|Independent <=10q blocks| H[Hierarchical Tensor Shards]
    E -->|Cross-block low entanglement| I[MPS Bridge]
    E -->|Clifford circuit| J[Stabilizer Tableau]
    E -->|Noisy small circuit| K[Density Matrix]
    E -->|GPU available and dense small| L[CuPy / GPU Statevector]
    E -->|Cluster configured| M[TCP Distributed Sparse Workers]
    F --> N[Lookup Matrices + Sparse Updates]
    G --> N
    H --> O[Packaged 1..10q Embedded Lookups]
    I --> P[Tensor SVD / Bond Update]
    J --> Q[Tableau Update]
    K --> R[Kraus / Noise Channels]
    L --> S[GPU Vector Operations]
    M --> T[Shard Exchange / Coordinator]
    N --> U[Measurement / QASM / Hardware Export]
    O --> U
    P --> U
    Q --> U
    R --> U
    S --> U
    T --> U

Layers

---

4. 120-qubit dense simulation reality

A dense n-qubit state vector contains 2^n amplitudes. A 120-qubit dense vector has:

2^120 ≈ 1.329e36 amplitudes

At complex128 precision, even one full vector is astronomically too large for ordinary hardware. Precomputed lookup, sharding and distributed execution reduce overhead and organize data, but they do not remove exponential dense-state growth.

Sansqrit therefore uses this decision strategy:

---

5. Sparse, sharded, hierarchical and MPS modes

Sparse mode

simulate(120, engine="sparse") {
    q = quantum_register(120)
    X(q[119])
    H(q[0])
    CNOT(q[0], q[1])
    print(engine_nnz())
}

Sparse mode stores only active amplitudes. It is efficient when the number of nonzero amplitudes stays small.

Sharded sparse mode

simulate(120, engine="sharded", n_shards=16, workers=8) {
    q = quantum_register(120)
    X(q[5])
    X(q[87])
    H(q[0])
    CNOT(q[0], q[1])
    print(shards())
}

Sharding partitions active basis keys. It helps memory locality and distributed layout. It does not blindly split entangled systems into independent sub-simulators.

Hierarchical tensor shards

simulate(120, engine="hierarchical", block_size=10) {
    q = quantum_register(120)
    shard block_0 [0..9]
    shard block_1 [10..19]
    apply H on block_0
    apply X on block_1
    print(hierarchical_report())
}

A 120-qubit register becomes 12 local blocks of 10 qubits. Each local block can be represented by 1024 amplitudes, and precomputed embedded lookup tables can accelerate local static gates.

Bridge entanglement

simulate(120, engine="hierarchical", block_size=10, cutoff=0.0, max_bond_dim=null) {
    q = quantum_register(120)
    H(q[9])
    apply CNOT on q[9], q[10] bridge_mode=sparse
    print(hierarchical_report())
}

A cross-block gate such as CNOT(q[9], q[10]) is not mathematically local to a single 10-qubit block. Sansqrit promotes the model to an MPS bridge so correlations are represented accurately when cutoff=0.0 and max_bond_dim=null.

---

6. Precomputed lookup files

The package includes real lookup data files:

sansqrit/data/lookup_static_gates.json
sansqrit/data/lookup_two_qubit_static_gates.json
sansqrit/data/lookup_embedded_single_upto_10.json.gz
sansqrit/data/lookup_metadata.json

Runtime lookup policy:

1. If n <= 10 and the gate is a static single-qubit gate, use embedded full-register transition tables.
2. Else if the gate is a static single-qubit gate, use the packaged 2x2 matrix.
3. Else if the gate is a static two-qubit gate, use the packaged 4x4 matrix.
4. Else compute at runtime and optionally rely on higher-level block/cache optimizations.

Check usage:

simulate(10, engine="sparse", use_lookup=true) {
    q = quantum_register(10)
    H(q[0])
    SX(q[3])
    CNOT(q[0], q[1])
    print(lookup_profile())
}

---

7. Distributed computing model

Start workers:

sansqrit worker --host 0.0.0.0 --port 8765
sansqrit worker --host 0.0.0.0 --port 8766

Use from Python:

from sansqrit import QuantumEngine
engine = QuantumEngine.create(120, backend="distributed", addresses=[("10.0.0.1", 8765), ("10.0.0.2", 8766)])

The built-in distributed backend is correctness-first. It is useful for sparse shard orchestration and testing. For production HPC, a future backend should add MPI/Ray/Dask, compressed amplitude transfer, worker-local gate kernels and topology-aware shard exchange.

---

8. GPU backend

pip install "sansqrit[gpu]"

simulate(24, engine="gpu") {
    q = quantum_register(24)
    H(q[0])
    CNOT(q[0], q[1])
    print(measure_all(shots=100))
}

GPU acceleration helps small/medium dense state vectors. It does not make arbitrary dense 120-qubit simulation feasible.

---

9. Stabilizer backend

simulate(1000, engine="stabilizer") {
    q = quantum_register(1000)
    for i in range(0, 999) {
        H(q[i])
        CNOT(q[i], q[i + 1])
    }
    print(measure_all(shots=5))
}

The stabilizer backend is for Clifford circuits using gates such as H, S, X, Y, Z, CNOT, CZ, and SWAP. It does not support arbitrary non-Clifford rotations as exact tableau operations.

---

10. Density and noise backend

simulate(3, engine="density") {
    q = quantum_register(3)
    H(q[0])
    CNOT(q[0], q[1])
    noise_bit_flip(q[1], 0.01)
    noise_phase_flip(q[0], 0.01)
    print(probabilities())
}

Noise helpers:

noise_bit_flip(q, p)
noise_phase_flip(q, p)
noise_depolarize(q, p)
noise_amplitude_damping(q, gamma)

Density matrices scale as 4^n, so use this backend for small noisy circuits.

---

11. Quantum error correction framework

Sansqrit includes a dedicated QEC module.

Supported codes:

bit_flip
phase_flip
repetition3
repetition distance-d
shor9
steane7
five_qubit
surface3
surface distance-d helpers

Core DSL functions:

qec_codes()
qec_code(name, distance=null)
qec_logical(code="bit_flip", base=0, name="logical", distance=null)
qec_encode(logical)
qec_decode(logical)
qec_syndrome(logical, ancilla_base=null)
qec_correct(logical, syndrome)
qec_syndrome_and_correct(logical, ancilla_base=null)
qec_inject_error(logical, pauli, physical_offset)
logical_x(logical)
logical_z(logical)
logical_h(logical)
logical_s(logical)
logical_cx(control, target)
qec_surface_lattice(distance=3)
qec_syndrome_circuit(logical, ancilla_base=null)
qec_optional_features()
qec_stim_syndrome_text(logical, ancilla_base=null)

Bit-flip example:

simulate(6, engine="sparse") {
    q = quantum_register(6)
    logical = qec_logical("bit_flip", base=0)
    qec_encode(logical)
    qec_inject_error(logical, "X", 1)
    result = qec_syndrome_and_correct(logical, ancilla_base=3)
    print(result)
}

Surface-code helper:

simulate(20, engine="sparse") {
    q = quantum_register(20)
    logical = qec_logical("surface", base=0, distance=3)
    print(logical.stabilizers())
    print(qec_surface_lattice(3).stabilizers())
    print(qec_optional_features())
}

The built-in surface-code decoder is educational/greedy. If pymatching is installed, Sansqrit exposes an integration point for MWPM-style decoding. If stim is installed, the package can emit syndrome-extraction text that can be adapted into Stim workflows.

---

12. Hardware export

OpenQASM 3

simulate(3, engine="sparse") {
    q = quantum_register(3)
    H(q[0])
    CNOT(q[0], q[1])
    print(export_qasm3())
}

Hardware target summary

simulate(4, engine="sparse") {
    q = quantum_register(4)
    H(q[0])
    CNOT(q[0], q[1])
    print(hardware_targets())
    print(hardware_payload_summary())
    print(export_hardware("azure"))
}

Supported export modes:

Sansqrit does not store cloud credentials. Submission to cloud hardware remains controlled by the provider SDK and user account.

---

13. Complete DSL syntax

Variables

x = 10
y = 3.14
name = "sansqrit"
flag = true
nothing = null

Lists, dictionaries and math

values = [1, 2, 3, 4]
config = {"backend": "sparse", "shots": 1000}
print(sum(values))
print(mean(values))

Functions

fn square(x) {
    return x * x
}

print(square(7))

Lambdas and pipelines

values = [1, 2, 3, 4]
result = values |> map(fn(x) => x * x) |> filter(fn(x) => x > 4)
print(result)

Loops and conditionals

for i in range(0, 10) {
    if i % 2 == 0 {
        print(i)
    } else {
        print("odd")
    }
}

Simulation blocks

simulate(5, engine="sparse") {
    q = quantum_register(5)
    H(q[0])
}

Arguments:

simulate(n_qubits, engine="sparse", n_shards=1, workers=1, seed=null, use_lookup=true, max_bond_dim=null, cutoff=0.0, addresses=null, block_size=10)

Shard declarations

shard block_A [0..9]
apply H on block_A

Bridge gate syntax

apply CNOT on q[9], q[10] bridge_mode=sparse

The translator routes this to the engine while retaining the bridge-mode intention for hierarchical backends.

---

14. Gate/function reference

Single-qubit gates

I(q)
X(q)
Y(q)
Z(q)
H(q)
S(q)
Sdg(q)
T(q)
Tdg(q)
SX(q)
SXdg(q)
Rx(q, theta)
Ry(q, theta)
Rz(q, theta)
Phase(q, theta)
U1(q, theta)
U2(q, phi, lambda)
U3(q, theta, phi, lambda)

Two-qubit gates

CNOT(c, t)
CX(c, t)
CZ(c, t)
CY(c, t)
CH(c, t)
CSX(c, t)
SWAP(a, b)
iSWAP(a, b)
SqrtSWAP(a, b)
fSWAP(a, b)
DCX(a, b)
CRx(c, t, theta)
CRy(c, t, theta)
CRz(c, t, theta)
CP(c, t, theta)
CU(c, t, theta, phi, lambda)
RXX(a, b, theta)
RYY(a, b, theta)
RZZ(a, b, theta)
RZX(a, b, theta)
ECR(a, b)
MS(a, b)

Three/multi-qubit gates

Toffoli(a, b, c)
CCX(a, b, c)
Fredkin(c, a, b)
CSWAP(c, a, b)
CCZ(a, b, c)
MCX(q0, q1, ..., target)
MCZ(q0, q1, ...)
C3X(a, b, c, target)
C4X(a, b, c, d, target)

Whole-register helpers

H_all(qubits=null)
Rx_all(theta, qubits=null)
Ry_all(theta, qubits=null)
Rz_all(theta, qubits=null)
qft(q=null)
iqft(q=null)
measure(q)
measure_all(q=null, shots=1)
probabilities(q=null)
expectation_z(q)
expectation_zz(a, b)
engine_nnz()
shards()
lookup_profile()
hierarchical_report()

File/data helpers

read_file(path)
write_file(path, text)
read_json(path)
write_json(path, obj)
read_csv(path)
write_csv(path, rows)

Diagnostics and architecture helpers

sansqrit_doctor()
sansqrit_backends()
estimate_qubits(n_qubits)
execution_flow()
architecture_layers()
lookup_architecture()
explain_120_qubits_dense()
troubleshooting(topic=null)
research_gaps()
enable_logging(level="INFO", path=null)
log_sansqrit_event(event, fields={})

---

15. Algorithms and high-level helpers

grover_search
grover_search_multi
shor_factor
vqe_h2
qaoa_maxcut
quantum_phase_estimation
hhl_solve
bernstein_vazirani
simon_algorithm
deutsch_jozsa
quantum_counting
swap_test
teleport
superdense_coding
bb84_qkd
amplitude_estimation
variational_classifier

---

16. Logging, diagnostics and troubleshooting

enable_logging("INFO", "sansqrit.log")
log_sansqrit_event("start", {"program": "sparse_120"})
print(sansqrit_doctor())
print(sansqrit_backends())
print(troubleshooting("lookup"))

CLI:

sansqrit doctor
sansqrit backends
sansqrit estimate 120
sansqrit troubleshoot distributed
sansqrit architecture
sansqrit hardware

---

17. AI/ML training usage

Sansqrit ships examples and docs inside the wheel so AI tools can inspect them after installation.

from sansqrit.dataset import builtin_training_records, generate_jsonl
records = builtin_training_records()
generate_jsonl("sansqrit_training.jsonl", records)

Training task types:

---

18. Real-world 120+ qubit example themes

The package includes 300+ examples. New high-qubit examples cover:

• Climate sensor anomaly encoding
• Supply-chain route optimization
• Finance portfolio risk flags
• Cybersecurity graph threat propagation
• Telecom network routing
• Drug-discovery feature maps
• QEC satellite link protection
• Smart-grid sparse fault localization
• Port logistics
• Aerospace sensor fusion
• 1000-qubit Clifford/stabilizer workflows

Run:

sansqrit run examples/278_climate_128q_sparse_sensors.sq
sansqrit run examples/283_hierarchical_120q_bridge_iot.sq
sansqrit run examples/300_city_1000q_stabilizer_graph.sq

---

19. PyPI release notes

Build:

python -m pip install --upgrade build twine
rm -rf build dist *.egg-info src/*.egg-info
python -m build --sdist --wheel
python -m twine check dist/*
python -m twine upload dist/*

If version 0.3.3 is already uploaded to PyPI, PyPI will reject another upload with the same version. In that case, bump to 0.3.6 or later.

---

20. Limitations and safe claims

Safe claim:

> Sansqrit supports 120+ logical qubit programs using sparse, sharded, lookup-accelerated, stabilizer, MPS, hierarchical tensor, density-matrix, GPU and distributed backends when the circuit has exploitable structure.

Unsafe claim:

> Sansqrit can simulate any arbitrary dense 120-qubit quantum state on local hardware.

That is not physically realistic.

---

License

MIT.

DSL_REFERENCE.md

Sansqrit DSL Reference

Sansqrit source files use the .sq extension. The Python implementation translates Sansqrit into Python and runs it with Sansqrit quantum builtins. It is intended for trusted local programs.

Program shape

simulate(2) {
    let q = quantum_register(2)
    H(q[0])
    CNOT(q[0], q[1])
    print(measure_all(q, shots=1000))
}

Engine selection

simulate(8, engine="sparse") { }
simulate(8, engine="sharded", n_shards=4, workers=2) { }
simulate(8, engine="threaded", workers=4) { }

Variables

let x = 1
const EPS = 1e-9
x += 1
x -= 1
x *= 2
x /= 2

Literals

true
false
None
1
1.5
"text"
[1, 2, 3]
{"key": "value"}
(1, 2)

Functions

fn square(x) {
    return x * x
}

let cube = fn(x) => x * x * x

Pipelines

let xs = [1, 2, 3, 4]
let ys = xs |> map(fn(x) => x * x)
let zs = ys |> filter(fn(x) => x > 4)
let total = zs |> sum
let folded = xs |> reduce(fn(a, b) => a + b)

Control flow

if x > 0 {
    print("positive")
} else if x == 0 {
    print("zero")
} else {
    print("negative")
}

for i in range(10) {
    print(i)
}

while error > 1e-6 {
    error = error / 2
}

Quantum register

let q = quantum_register(5)
q[0]
q[4]

Qubits are little-endian internally: q[0] is the least-significant bit. Displayed bitstrings are conventional most-significant-bit first.

Gates

Single-qubit

I(q[0]); X(q[0]); Y(q[0]); Z(q[0]); H(q[0])
S(q[0]); Sdg(q[0]); T(q[0]); Tdg(q[0])
SX(q[0]); SXdg(q[0])
Rx(q[0], PI / 2); Ry(q[0], PI / 2); Rz(q[0], PI / 2)
Phase(q[0], PI / 4); U1(q[0], PI / 4)
U2(q[0], 0.1, 0.2); U3(q[0], 0.1, 0.2, 0.3)

Two-qubit

CNOT(q[0], q[1]); CX(q[0], q[1])
CZ(q[0], q[1]); CY(q[0], q[1]); CH(q[0], q[1])
CSX(q[0], q[1]); SWAP(q[0], q[1]); iSWAP(q[0], q[1])
SqrtSWAP(q[0], q[1]); fSWAP(q[0], q[1]); DCX(q[0], q[1])
CRx(q[0], q[1], PI/3); CRy(q[0], q[1], PI/3); CRz(q[0], q[1], PI/3)
CP(q[0], q[1], PI/3); CU(q[0], q[1], 0.1, 0.2, 0.3)
RXX(q[0], q[1], PI/4); RYY(q[0], q[1], PI/4); RZZ(q[0], q[1], PI/4)
RZX(q[0], q[1], PI/4); ECR(q[0], q[1]); MS(q[0], q[1])

Three and multi-qubit

Toffoli(q[0], q[1], q[2]); CCX(q[0], q[1], q[2])
Fredkin(q[0], q[1], q[2]); CSWAP(q[0], q[1], q[2])
CCZ(q[0], q[1], q[2])
MCX(q[0], q[1], q[2], q[3])
MCZ(q[0], q[1], q[2])
C3X(q[0], q[1], q[2], q[3])
C4X(q[0], q[1], q[2], q[3], q[4])

Circuit helpers

H_all()
Rx_all(PI / 4)
Ry_all(PI / 4)
Rz_all(PI / 4)
qft(q)
iqft(q)

Measurement

measure(q[0])
measure_all(q, shots=1000)
probabilities(q)
expectation_z(q[0])
expectation_zz(q[0], q[1])
engine_nnz()
shards()

Algorithms

grover_search(3, 5, shots=512)
grover_search_multi(4, [3, 12], shots=512)
shor_factor(15)
vqe_h2(0.735, max_iter=32)
qaoa_maxcut(4, [(0,1), (1,2), (2,3), (3,0)], p=1, shots=256)
quantum_phase_estimation(0.3125, 5, shots=256)
hhl_solve([[2, 0], [0, 4]], [2, 8])
bernstein_vazirani("101101")
simon_algorithm("101")
deutsch_jozsa(4, "balanced")
quantum_counting(6, 7, 5)
teleport(1)
superdense_coding(1, 0)
bb84_qkd(24, eavesdropper=false)
amplitude_estimation(0.37, 5)
variational_classifier([0.1, 0.5, 1.2], layers=3)

I/O

write_file("out.txt", "hello")
let text = read_file("out.txt")
write_json("data.json", {"shots": 1000})
let obj = read_json("data.json")
write_csv("data.csv", [{"gate": "H", "q": 0}])
let rows = read_csv("data.csv")

Advanced backend syntax

simulate(1000, engine="stabilizer") { H(0); CNOT(0, 999) }
simulate(64, engine="mps", max_bond_dim=128, cutoff=1e-12) { H(0) }
simulate(3, engine="density") { H(0); noise_depolarize(0, 0.01) }
simulate(20, engine="gpu") { H(0); CNOT(0, 1) }

Additional functions:

• noise_depolarize(q, p)
• noise_bit_flip(q, p)
• noise_phase_flip(q, p)
• noise_amplitude_damping(q, gamma)
• engine_nnz() for sparse nonzero count; stabilizer/MPS may return -1 because they do not store computational-basis sparse amplitudes.

Use Python API for hybrid and cluster orchestration:

Circuit(150).H(0).CNOT(0, 149).run(backend="hybrid")
DistributedSparseEngine.from_addresses(150, ["host1:8765", "host2:8765"])

API_REFERENCE.md

Python API Reference

QuantumEngine

from sansqrit import QuantumEngine
engine = QuantumEngine.create(n_qubits=5, backend="sparse")

Options:

• backend: "sparse", "sharded", or "threaded".
• n_shards: local partition count for sharded mode.
• workers: worker thread count for large single-qubit transforms.
• use_lookup: use precomputed static-gate matrices.
• seed: deterministic sampling seed.

Core methods:

engine.H(0)
engine.CNOT(0, 1)
engine.RZZ(1, 2, 0.5)
engine.H_all()
engine.qft([0, 1, 2])
engine.measure(0)
engine.measure_all(1000)
engine.probabilities()
engine.expectation_z(0)
engine.expectation_zz(0, 1)
engine.export_qasm2()
engine.export_qasm3()
engine.shard_info()

Circuit

from sansqrit import Circuit
c = Circuit(2).H(0).CNOT(0, 1)
engine = c.run()
counts = c.run(shots=1000)
print(c.qasm3())

DSL runner

from sansqrit import run_code, run_file, translate
run_file("program.sq")
print(translate(open("program.sq").read()))

Algorithms module

from sansqrit.algorithms import grover_search, qaoa_maxcut, vqe_h2

The algorithms module contains readable reference implementations and toy hybrid algorithms for examples, education and model training.

Advanced Python APIs

from sansqrit import Circuit, QuantumEngine, StabilizerEngine, DensityMatrixEngine
from sansqrit.mps import MPSEngine
from sansqrit.hybrid import HybridEngine
from sansqrit.cluster import DistributedSparseEngine
from sansqrit.optimizer import optimize_operations
from sansqrit.interop import to_qiskit, to_cirq, to_braket, apply_to_pennylane
from sansqrit.verification import verify_all_available

Backends

• QuantumEngine.create(n, backend="sparse")
• QuantumEngine.create(n, backend="sharded", n_shards=8)
• QuantumEngine.create(n, backend="threaded", workers=8)
• QuantumEngine.create(n, backend="stabilizer")
• QuantumEngine.create(n, backend="mps", max_bond_dim=128)
• QuantumEngine.create(n, backend="density")
• QuantumEngine.create(n, backend="gpu")
• QuantumEngine.create(n, backend="distributed", addresses=["host:8765"])

Optimizer

optimized_ops, report = optimize_operations(circuit.operations)

The report includes before, after, removed, and the set of passes used.

Verification

verify_all_available(circuit) attempts Qiskit and Cirq comparisons if installed.

ADVANCED_BACKENDS.md

Sansqrit Advanced Backends

Sansqrit 0.2 adds advanced backends for large and specialized simulations. These backends are not magic: a fully dense, highly entangled 150-qubit state is still infeasible on local hardware. The goal is to avoid expanding the state whenever the circuit structure allows it.

Backend selection summary

Stabilizer backend

Use it for Clifford circuits:

simulate(1000, engine="stabilizer", seed=7) {
    H(0)
    for i in range(0, 999) {
        CNOT(i, i + 1)
    }
    print(measure_all(shots=8))
}

Supported stabilizer gates: I, X, Y, Z, H, S, Sdg, CNOT/CX, CZ, SWAP.

The backend raises an error for non-Clifford gates. This is intentional: silently switching to dense simulation would defeat the purpose.

MPS / tensor-network backend

Use it when the circuit has limited entanglement:

simulate(64, engine="mps", max_bond_dim=64, cutoff=1e-10) {
    for i in range(0, 64) { Ry(i, 0.05) }
    for i in range(0, 63) { CNOT(i, i + 1) }
    print(measure_all(shots=32))
}

Install dependencies:

pip install sansqrit[tensor]

Noise and density matrices

simulate(2, engine="density", seed=1) {
    H(0)
    CNOT(0, 1)
    noise_depolarize(0, 0.01)
    noise_amplitude_damping(1, 0.05)
    print(probabilities())
}

Noise functions:

• noise_depolarize(q, p)
• noise_bit_flip(q, p)
• noise_phase_flip(q, p)
• noise_amplitude_damping(q, gamma)

GPU backend

pip install sansqrit[gpu]

simulate(20, engine="gpu") {
    H(0)
    CNOT(0, 1)
    print(measure_all(shots=100))
}

The GPU backend is dense. It accelerates moderate state vectors but cannot store arbitrary 150-qubit dense states.

Distributed cluster backend

Start workers on machines reachable by TCP:

sansqrit worker --host 0.0.0.0 --port 8765
sansqrit worker --host 0.0.0.0 --port 8766

Use from Python:

from sansqrit.cluster import DistributedSparseEngine

engine = DistributedSparseEngine.from_addresses(150, ["worker-a:8765", "worker-b:8766"])
engine.apply("H", 0)
engine.apply("CNOT", 0, 149)
print(engine.measure_all(100))

This mode is a real multi-node protocol, but it prioritizes correctness. It gathers/repartitions state around each operation, so it is not yet a high-performance MPI simulator.

Interop

Install extras as needed:

pip install sansqrit[qiskit]
pip install sansqrit[cirq]
pip install sansqrit[braket]
pip install sansqrit[pennylane]

Python API:

from sansqrit import Circuit
from sansqrit.interop import to_qiskit, to_cirq, to_braket, apply_to_pennylane

circuit = Circuit(2).H(0).CNOT(0, 1)
qc = to_qiskit(circuit)
cc = to_cirq(circuit)
braket_circuit = to_braket(circuit)
qml_function = apply_to_pennylane(circuit)

Formal verification helpers

from sansqrit import Circuit
from sansqrit.verification import verify_all_available

circuit = Circuit(2).H(0).CNOT(0, 1)
for result in verify_all_available(circuit):
    print(result)

The helpers compare Sansqrit probabilities against installed SDK simulators. They are regression checks, not mathematical proof certificates.

HIERARCHICAL_TENSOR_SHARDS.md

Sansqrit Hierarchical Tensor Shards

Version 0.3.3 adds a safe implementation of the common idea: simulate a large logical register as many small dense blocks, then promote to a tensor network when blocks become entangled.

Why this exists

A 120-qubit dense state vector has 2^120 amplitudes, which is not physically practical on local hardware. However, many useful programs do not immediately create global dense entanglement. They contain local dynamics, independent blocks, sparse activity, or low-entanglement bridge operations.

The hierarchical backend exploits that structure.

120 logical qubits
    ↓
12 local dense blocks of 10 qubits each
    ↓
local gates use dense 1024-amplitude vectors and packaged lookup matrices
    ↓
first cross-block entangling bridge promotes to MPS
    ↓
MPS tracks correlations with bond dimensions instead of one 2^120 vector

Important correctness rule

Sansqrit does not blindly treat twelve 10-qubit blocks as independent after a cross-block gate. That would be wrong.

For example:

cx q[9], q[10]

creates a bridge between block 0 and block 1. After this, the backend promotes into MPS mode so the correlation is represented accurately.

Memory example

For block_size=10, one local block has:

2^10 = 1024 complex amplitudes
1024 × 16 bytes ≈ 16 KiB with complex128

A 120-qubit separable block state has 12 blocks:

12 × 16 KiB ≈ 192 KiB for raw block vectors

This is only valid while the global state factors across those blocks.

DSL usage

simulate(120, engine="hierarchical", block_size=10, max_bond_dim=null, cutoff=0.0) {
    q = quantum_register(120)

    shard block_A [0..9]
    shard block_B [10..19]

    apply H on block_A
    apply X on block_B

    # Cross-block bridge. This promotes the backend to MPS safely.
    apply CNOT on q[9], q[10] bridge_mode=sparse

    info = hierarchical_report()
    print(info)
}

Equivalent Python:

from sansqrit import QuantumEngine

engine = QuantumEngine.create(120, backend="hierarchical", block_size=10, max_bond_dim=None, cutoff=0.0)
q = engine.quantum_register()
for i in range(10):
    engine.H(q[i])
for i in range(10, 20):
    engine.X(q[i])
engine.CNOT(q[9], q[10])
print(engine.hierarchical_report())

Runtime modes

mode="blocks" means the state is still a product of dense local blocks.

mode="mps" means a bridge gate has created cross-block entanglement and the state was promoted to the MPS backend.

Accuracy

Block mode is exact.

MPS bridge mode is exact if:

max_bond_dim = None
cutoff = 0.0

If you set a finite bond dimension or nonzero cutoff, Sansqrit may truncate small singular values to save memory/time. That can be useful for approximation but is no longer exact.

Lookup usage

Inside each 10-qubit block, static primitive gates use packaged lookup matrices:

H, X, Y, Z, S, Sdg, T, Tdg, SX, SXdg
CNOT, CZ, CY, CH, CSX, SWAP, iSWAP, SqrtSWAP, fSWAP, DCX, ECR, MS

The backend reports lookup counters via:

lookup_profile()
hierarchical_report()

Recommended use cases

Good fits:

• 120+ qubit programs with local block dynamics.
• Independent 10-qubit components.
• Low-entanglement bridges between neighboring blocks.
• Real-time sparse/logical applications that should not materialize a global dense vector.
• Workloads where the programmer wants explicit block mapping.

Poor fits:

• Random all-to-all dense circuits.
• h_all followed by many nonlocal entanglers.
• Circuits with rapidly growing MPS bond dimension.

Use engine="stabilizer" for large Clifford-only circuits and engine="sparse" or engine="sharded" for oracle-style sparse state maps.

PRECOMPUTED_LOOKUPS.md

Sansqrit Precomputed Lookup Tables

Sansqrit v0.4.0 ships precomputed lookup files inside the Python wheel under sansqrit/data/.

Included files:

• lookup_metadata.json — table schema, version, and limits.
• lookup_static_gates.json — precomputed 2x2 matrices for all static single-qubit gates.
• lookup_two_qubit_static_gates.json — precomputed 4x4 matrices for all static two-qubit gates that do not need parameters.
• lookup_embedded_single_upto_10.json.gz — embedded basis-transition tables for every register size from 1 to 10 qubits, every target qubit position, and every static single-qubit gate.

Why not every possible circuit product?

A phrase like "all possible matrix multiplications up to 10 qubits" can mean an infinite or combinatorially explosive set. Parametric gates such as Rx(theta) have continuous parameters, and even a finite static gate alphabet has an astronomical number of possible circuit products as sequence length grows.

Sansqrit therefore packages the practical exhaustive tables:

1. Every static primitive matrix.
2. Every static primitive embedded single-qubit transition for n=1..10.
3. Static two-qubit primitive matrices.

Runtime then performs sequence fusion/caching and arithmetic fallback where the state space or parameters make prepackaging impractical.

Runtime lookup path

For QuantumEngine.create(n, use_lookup=True):

• if n <= 10 and the gate is static single-qubit, Sansqrit uses the packaged

full-register transition table;

• if the gate is static two-qubit, Sansqrit uses the packaged 4x4 matrix;
• otherwise it computes the needed matrix at runtime.

For n > 10, Sansqrit still uses packaged primitive matrices but not full embedded transition tables, because embedded full-register tables scale as 2^n.

Inspect installed lookup data

python - <<'PY'
from importlib.resources import files
import sansqrit
root = files('sansqrit').joinpath('data')
for path in root.iterdir():
    print(path.name)
PY

python - <<'PY'
from sansqrit.lookup import packaged_metadata, DEFAULT_LOOKUP
print(packaged_metadata())
print(DEFAULT_LOOKUP.has_embedded_single(10, 7, 'H'))
PY

QEC_FRAMEWORK.md

Sansqrit Quantum Error Correction Framework

Sansqrit v0.3.6 adds a dedicated QEC layer for teaching, prototyping, AI training corpora, and small simulator validation. It includes code definitions, logical qubit objects, syndrome extraction circuits, decoder interfaces, logical gate helpers, and noise/correction examples.

Included codes

Python API

from sansqrit import QuantumEngine
from sansqrit.qec import logical_qubit, encode, inject_error, syndrome_and_correct, decode

engine = QuantumEngine.create(5, backend="sparse")
logical = logical_qubit("bit_flip", base=0)
encode(engine, logical)
inject_error(engine, logical, "X", 1)
result = syndrome_and_correct(engine, logical, ancilla_base=3)
decode(engine, logical)
print(result.syndrome, result.corrections)

Sansqrit DSL syntax

simulate(5) {
  let q = quantum_register(5)
  let l = qec_logical("bit_flip", base=0)
  qec_encode(l)
  qec_inject_error(l, "X", 1)
  let result = qec_syndrome_and_correct(l, ancilla_base=3)
  qec_decode(l)
  let counts = measure_all(q)
}

QEC functions exposed to the DSL

qec_codes()
qec_code(name, distance=null)
qec_logical(code="bit_flip", base=0, name="logical", distance=null)
qec_encode(logical)
qec_decode(logical)
qec_syndrome(logical, ancilla_base=null)
qec_correct(logical, syndrome)
qec_syndrome_and_correct(logical, ancilla_base=null)
qec_inject_error(logical, pauli, physical_offset)
logical_x(logical)
logical_z(logical)
logical_h(logical)
logical_s(logical)
logical_cx(control_logical, target_logical)
qec_surface_lattice(distance=3)
qec_syndrome_circuit(logical, ancilla_base=null)

Decoder interface

A decoder implements:

class Decoder:
    def decode(self, code, syndrome):
        return [("X", 1), ("Z", 4)]

Sansqrit includes:

• RepetitionDecoder
• LookupDecoder
• SurfaceCodeDecoder

The included surface-code decoder is a greedy educational decoder. It is intentionally replaceable; production surface-code threshold research should plug in a specialized MWPM or union-find decoder through the same interface.

Stabilizer syndrome extraction

syndrome_circuit(logical) returns gate tuples that extract each stabilizer onto an ancilla. Z checks use data-to-ancilla CNOTs. X checks use ancilla preparation/measurement in the X basis. This lets AI tools inspect how stabilizer checks are converted into circuits.

Logical gate helpers

Sansqrit exposes logical Pauli and transversal helper gates:

logical_x, logical_z, logical_h, logical_s, logical_cx

Where transversal gates are not universally valid for all codes, these helpers are educational primitives; code-specific fault-tolerant compilation should be added as later specialized passes.

HARDWARE_EXPORTS_AND_CLOUD.md

Hardware exports and cloud-provider workflows

Sansqrit can export circuit payloads but does not manage cloud credentials.

Built-in export paths

• export_qasm2()
• export_qasm3()
• export_hardware("qiskit")
• export_hardware("ibm")
• export_hardware("cirq")
• export_hardware("braket")
• export_hardware("azure")
• export_hardware("pennylane")
• hardware_targets()
• hardware_payload_summary()

Qiskit / IBM

Install:

pip install "sansqrit[qiskit]"

Use export_hardware("qiskit") for a QuantumCircuit when Qiskit is installed. Otherwise Sansqrit returns an OpenQASM 3 fallback payload.

Amazon Braket

Install:

pip install "sansqrit[braket]"

Use export_hardware("braket") for a Braket Circuit when the SDK is installed.

Azure Quantum

Sansqrit emits an OpenQASM 3/Azure-style payload. Submit it using your QDK, Qiskit or Cirq Azure workflow.

PennyLane

Install:

pip install "sansqrit[pennylane]"

Use export_hardware("pennylane") to get a callable quantum function that can be wrapped by a PennyLane QNode.

INDUSTRY_PARITY_V036.md

Sansqrit v0.3.6 Industry-Parity Upgrade Notes

Author/Maintainer: Karthik V

This release adds a stronger adaptive execution planner, production-oriented distributed sparse execution APIs, optional Stim/PyMatching QEC bridges, GPU/cuQuantum capability adapters, richer OpenQASM 3 builders, and expanded conformance verification hooks.

Why these features were added

Modern quantum platforms do not use one simulator for every circuit. They choose among dense state vectors, density matrices, stabilizer/tableau methods, matrix-product-state/tensor-network methods, GPU acceleration, hardware exports, and resource-estimation workflows. Sansqrit now exposes a comparable planning layer while keeping its simple DSL.

Adaptive planner

Use:

sansqrit plan program.sq --json

or in DSL:

print(plan_backend(120, [("H", [0], []), ("CNOT", [0, 1], [])]))
print(explain_backend(120, [("H", [0], []), ("CNOT", [0, 1], [])]))

The planner extracts:

• qubit count
• gate count
• Clifford/non-Clifford count
• estimated depth
• connected-component sizes
• cross-block bridge edges
• dense memory estimate
• density-matrix memory estimate
• sparse-amplitude estimate
• safe backend recommendation

Backend choices include:

• sparse
• sharded
• sparse_sharded
• hierarchical
• mps
• stabilizer
• extended_stabilizer
• density
• gpu
• distributed

Distributed execution

Built-in TCP sparse workers support:

• compressed payloads
• batched gate application
• checkpoint/restore
• capability discovery
• optional Ray/Dask/MPI metadata hooks

Start workers:

sansqrit worker --host 0.0.0.0 --port 8765

Use from Python:

from sansqrit.cluster import DistributedSparseEngine
eng = DistributedSparseEngine.from_addresses(120, [("worker1", 8765), ("worker2", 8765)])
eng.apply_batch([
    ("H", (0,), ()),
    ("CNOT", (0, 1), ()),
])
eng.checkpoint("./checkpoint")

This remains mathematically correct by keeping an authoritative sparse state. Large production clusters should add worker-local kernels and pairwise shard exchange for gate families whose partner amplitudes are colocated.

GPU and cuQuantum layer

Use:

sansqrit gpu --qubits 28 --type dense

DSL:

print(gpu_capabilities())
print(cuquantum_recommendation(28, "dense"))

The package does not hard-depend on CUDA. It detects:

• CuPy
• cuQuantum
• cuStateVec target
• cuTensorNet target
• cuDensityMat target

OpenQASM 3 advanced support

Sansqrit now includes a text builder for:

• mid-circuit measurements
• classical bit control
• delays/timing
• barriers
• pragmas
• extern declarations
• calibration blocks

DSL:

print(qasm3_mid_circuit_template(2))

Python:

from sansqrit.qasm import Qasm3Builder
print(Qasm3Builder(2).gate("h", [0]).measure(0, 0).if_bit(0, 1, "x q[1];").text())

QEC production bridges

Sansqrit adds optional integrations and planning utilities:

print(qec_stim_surface_task(3, 3, 0.001))
print(qec_threshold_sweep())
print(qec_logical_resource_estimate(100, 1000, 5, 10))

It supports built-in educational codes and external production pathways:

• bit-flip
• phase-flip
• repetition codes
• Shor 9-qubit
• Steane 7-qubit
• 5-qubit perfect code
• surface-code lattice helpers
• Stim generated surface-code memory experiments when Stim is installed
• PyMatching-compatible MWPM adapter when a matching graph is supplied

Formal verification

The verification layer now attempts:

• Qiskit probability comparison
• Cirq probability comparison
• Braket local simulator/export check
• Stim Clifford parse check

CLI:

sansqrit verify program.sq

DSL:

simulate(2) {
    q = quantum_register(2)
    H(q[0])
    CNOT(q[0], q[1])
    print(conformance_report())
}

Large 120+ qubit design rule

For 120+ qubits, Sansqrit avoids false dense claims. It chooses:

• stabilizer for Clifford-only circuits
• extended-stabilizer for mostly Clifford circuits
• hierarchical tensor shards when components are <=10 qubits
• MPS when cross-block entanglement is limited
• sparse/sharded/distributed when active amplitudes stay sparse
• hardware export when classical simulation is not appropriate

Dense 120-qubit state-vector simulation remains physically infeasible because it requires 2^120 amplitudes.

TROUBLESHOOTING_AND_LOGGING.md

Troubleshooting and logging

CLI

sansqrit doctor
sansqrit backends
sansqrit estimate 120
sansqrit troubleshoot lookup
sansqrit hardware

DSL logging

enable_logging("INFO", "sansqrit.log")
log_sansqrit_event("program_start", {"name": "sparse_150"})

Common issues

• Slow 120-qubit run: use estimate_qubits, plan_backend, stabilizer, mps, or hierarchical.
• Missing lookup files: verify sansqrit/data/ exists in the installed package.
• Cloud export fails: install the provider extra or use OpenQASM fallback.
• Density backend memory issue: density matrices scale as 4^n.
• GPU missing: install CuPy matching your CUDA runtime.

DESIGN_AND_BUG_AUDIT.md

Sansqrit v0.3.6/v0.3.6 Design and Bug Audit

Author/maintainer metadata: Karthik V

Audit date: 2026-04-26

Executive summary

I tested the latest Sansqrit package and found that the overall architecture is directionally good: sparse + sharded + lookup + hierarchical tensor shards + MPS + stabilizer + QEC + hardware export is the right high-level design for a large-logical-qubit DSL.

However, the v0.3.6 package should not be treated as production-complete. I found three concrete correctness/release issues and fixed them in the rebuilt v0.3.6 package:

1. MPS non-adjacent two-qubit gates were wrong when the first qubit index was greater than the second, e.g. CNOT(3, 0).
2. export_hardware("pennylane") raised an exception when PennyLane was not installed, while other providers returned a QASM fallback.
3. Distributed TCP worker request threads could keep waiting for more input, making some subprocess-style tests hang after use.

I also updated metadata/dependency policy in v0.3.6:

• version bumped to 0.3.6;
• author/maintainer kept as Karthik V;
• core dependency changed to include numpy>=1.26, because MPS/hierarchical functionality is advertised as a primary feature;
• placeholder example.com project URLs replaced with PyPI links;
• wheel metadata retains optional extras for Qiskit, Cirq, Braket, PennyLane, GPU, Stim, and PyMatching.

Test results

v0.3.6 baseline tests

• Included test suite: 23 tests passed, 0 failed.
• Python source compilation: passed.
• Example translation/compilation: 800 examples compiled, 0 failed.
• Example execution: 797 examples passed, 3 failed.

The 3 failing examples were:

• 745_scenario_hardware_calibration_05.sq
• 751_scenario_hardware_calibration_11.sq
• 757_scenario_hardware_calibration_17.sq

Cause: each example called export_hardware("pennylane"); without PennyLane installed, the package raised QuantumError instead of returning a fallback payload.

Extra audit tests beyond bundled tests

I added targeted checks not covered by the original test suite:

• Sparse vs sharded equivalence on a mixed 6-qubit circuit.
• MPS vs sparse equivalence for non-adjacent CNOT(3, 0).
• MPS vs sparse equivalence on a mixed circuit with non-adjacent CNOT, SWAP, RZZ, Ry.
• Hierarchical bridge promotion sanity.
• 150-qubit sparse/sharded state sanity.
• Wheel content inspection.
• Training/scenario dataset manifest and count checks.

v0.3.6 fixed package validation

• Included test suite: 23 tests passed, 0 failed.
• Example translation/compilation: 800 examples compiled, 0 failed.
• Former PennyLane-failing examples: all passed with fallback payloads.
• MPS reversed non-adjacent CNOT test: passed.
• Mixed MPS vs sparse test: passed.
• Wheel contains:
• 34 Python modules
• 800 packaged .sq examples
• 19 packaged markdown docs
• 10 packaged data/training/lookup files
• no __pycache__ or .pyc files

twine check was not run because twine is not installed in this container.

Bugs fixed in v0.3.6

1. MPS non-adjacent reversed two-qubit gates

Problem:

q = quantum_register(4)
H(q[3])
CNOT(q[3], q[0])

The MPS backend produced the wrong target correlation when q0 > q1 and the two sites were non-adjacent.

Fix:

• transform the 4x4 matrix into swapped site order with SWAP @ U @ SWAP;
• then reuse the left-to-right MPS two-site path.

2. PennyLane export fallback

Problem:

print(export_hardware("pennylane"))

raised an exception when PennyLane was missing.

Fix:

• PennyLane now matches Qiskit/Cirq/Braket behavior:
• use native adapter when installed;
• otherwise return an OpenQASM 3 fallback payload plus install hint.

3. Distributed worker subprocess hang risk

Problem:

The TCP worker request handler could continue waiting for additional input on the same request connection.

Fix:

• worker server now has daemon_threads = True;
• client calls sock.shutdown(socket.SHUT_WR) after sending one JSON request.

Design analysis

What is strong

Sparse + sharded is the right foundation

Sansqrit correctly avoids claiming arbitrary dense 120-qubit simulation. Sparse state maps plus sharding are appropriate for large logical registers when the active amplitude count remains small.

Hierarchical 10-qubit blocks are valid with a bridge rule

The hierarchical tensor-shard strategy is mathematically valid when:

• local operations stay inside independent 10-qubit blocks; and
• cross-block gates promote the representation to MPS/tensor-network form instead of pretending the blocks remain independent.

The package follows this direction.

Lookup files are useful but should be treated as a middle-layer accelerator

The packaged lookup files are appropriate for:

• static single-qubit matrices;
• static two-qubit matrices;
• embedded <=10-qubit transition tables;
• small block accelerators.

They cannot make arbitrary dense 120-qubit simulation feasible.

QEC module is useful for education and AI training

The QEC module includes logical qubits, code registries, syndrome extraction helpers, and decoder interfaces. This is useful, but the built-in surface-code decoder should remain labelled educational unless a full MWPM graph is implemented.

What is still missing for industry-grade parity

1. True adaptive backend planner

Current planning is useful but should become mandatory for engine("auto").

Add:

• estimated active amplitudes;
• Clifford/non-Clifford count;
• T-count/magic-state cost;
• entanglement graph;
• MPS bond-dimension estimate;
• memory estimate;
• backend decision explanation;
• safe refusal for impossible dense runs.

2. Real distributed execution plan

Current distributed mode is correctness-first and coordinator-driven. For real cluster performance, add:

• worker-local single-qubit gate execution;
• pairwise shard exchange for cross-shard two-qubit gates;
• batched gate execution;
• compressed amplitude transfer;
• checkpoint/restart;
• optional Ray/Dask/MPI transport.

3. Production QEC decoder

Add real surface-code decoding:

• construct detector graph from syndrome circuits;
• integrate PyMatching MWPM directly;
• support repeated syndrome rounds;
• support circuit-level noise;
• support logical error-rate estimation;
• export Stim detector-error models.

4. Formal cross-simulator verification

Add optional validation suites:

• compare small circuits against Qiskit Aer;
• compare Clifford/QEC circuits against Stim;
• compare MPS low-entanglement circuits against dense sparse/statevector for <=20 qubits;
• compare QASM export/import round trips.

5. Stronger OpenQASM 3 support

The exporter should eventually support:

• mid-circuit measurement;
• classical control;
• timing/delay/duration;
• calibration blocks;
• extern declarations;
• hardware-native gate set decomposition.

6. Benchmark suite

Add repeatable benchmarks:

• sparse 150q oracle;
• 1000q stabilizer Clifford graph;
• MPS 500q chain;
• QEC surface-code d=3/d=5;
• 20–30q dense statevector;
• lookup-hit benchmark;
• distributed sparse benchmark.

7. Lookup block compiler

The next improvement for lookup speed is not packaging every possible circuit. It is:

• detect static <=10-qubit blocks;
• fuse gates;
• hash the block;
• generate/cache the fused unitary or transition map;
• reuse across runs.

8. Data-quality tooling for AI training

The synthetic dataset should add quality gates:

• JSON schema validation;
• duplicates/near-duplicates report;
• code execution result attached to records;
• backend label verification;
• rejected-output taxonomy;
• eval set with hidden answers;
• citation/license metadata.

Recommendation before PyPI upload

Upload the fixed package as 0.3.6, not 0.3.6, if 0.3.6 has already been uploaded.

Run locally before upload:

python -m pip install --upgrade build twine
python -m twine check dist/*
python -m twine upload dist/*

Then verify:

python -m venv /tmp/sansqrit-check
source /tmp/sansqrit-check/bin/activate
pip install sansqrit==0.3.6
sansqrit doctor
sansqrit dataset info
sansqrit scenarios info
python - <<'PY'
from sansqrit import QuantumEngine
e = QuantumEngine.create(2)
e.H(0)
e.CNOT(0, 1)
print(e.probabilities())
PY

Final status

The v0.3.6 package is safer to upload than the v0.3.6 package because it fixes the concrete MPS, hardware-export, and distributed-worker issues found during the audit.

The design is promising, but for claims like "on par with Qiskit/Azure/AWS," the package should be described as an alpha/research DSL with multiple execution strategies, not yet a production cloud runtime or calibrated hardware compiler.