qaravan 0.2.2__tar.gz → 0.2.3__tar.gz

{qaravan-0.2.2/src/qaravan.egg-info → qaravan-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qaravan
-Version: 0.2.2
+Version: 0.2.3
 Summary: Unified classical simulation of noiseless and noisy quantum circuits
 Author-email: Faisal Alam <faisal@phasecraft.io>
 Requires-Python: >=3.11

qaravan-0.2.3/README.md

@@ -0,0 +1,103 @@
+# Qaravan
+
+[![PyPI version](https://img.shields.io/pypi/v/qaravan.svg)](https://pypi.org/project/qaravan/)
+[![codecov](https://codecov.io/gh/alam-faisal/qaravan/branch/master/graph/badge.svg)](https://codecov.io/gh/alam-faisal/qaravan/branch/master)
+
+**Qaravan** is a Python library for classical simulation of quantum circuits. It is designed for rapid prototyping of near-term quantum algorithms, error mitigation techniques, and mid-circuit measurement applications.
+
+> **v0.2 is under active development.** Backends marked "In legacy" below still live under `qaravan.legacy` and are being ported to the new abstractions.
+
+## Design
+
+Qaravan is built around four core abstractions:
+
+- **`Gate`** — an operation with a name, site indices, and a matrix representation. 
+- **`Circuit`** — an ordered sequence of gates. Supports `+` (concatenation), `*` (repetition), `.dagger()`.
+- **`State`** — the evolving data structure (statevector, density matrix, MPS, ...). Has `.expectation()`, `.sample()`, `.sample_and_collapse()`.
+- **`Simulator`** — takes an initial `State`, a `Circuit`, and an optional `NoiseModel`. Compiles and evolves; returns the final `State`.
+
+## Installation
+
+Install from PyPI:
+
+```bash
+uv add qaravan
+```
+
+For development (clone the repo first):
+
+```bash
+uv sync --group dev
+```
+
+## Usage
+
+### Noiseless simulation
+
+```python
+from qaravan.core import Circuit, PauliString
+from qaravan.core.gates import H, CNOT
+from qaravan.backends import Statevector
+
+circ = Circuit([H(0), CNOT([0, 1])])
+final_sv = Statevector(bitstring="00").apply(circ)
+print("⟨ZZ⟩:", final_sv.expectation(PauliString("ZZ")))   # → 1.0
+```
+
+`state.apply(circ)` is shorthand for `StatevectorSimulator(circ, state).run()`.
+
+### Noisy simulation
+
+A single noisy `Statevector` run samples one error realization and returns one pure state. `Walkers` evolves an ensemble of independent trajectories, which represents the mixed state statistically (see [GOTCHAS](docs/GOTCHAS.md)).
+
+```python
+from qaravan.backends import Walkers
+from qaravan.core.noise import DepolarizingNoise
+
+noise = DepolarizingNoise(num_sites=2, error_rate=0.1)
+walkers = Walkers(Statevector(bitstring="00"), num_walkers=2000)
+noisy = walkers.apply(circ, noise_model=noise, noise_rng=0)
+print("⟨ZZ⟩:", noisy.expectation(PauliString("ZZ")))
+```
+
+### Dynamic circuits (mid-circuit measurement + feed-forward)
+
+```python
+from qaravan.core import DynamicCircuit, DynamicRound
+
+def decoder(outcome: str) -> Circuit:
+    return Circuit([]) if outcome == "0" else Circuit([H(1)])
+
+dynamic = DynamicCircuit([DynamicRound(meas_sites=[0], decoder=decoder)])
+final_state, record = dynamic.execute(final_sv, measurement_rng=1)
+```
+
+### Trotter time evolution
+
+```python
+from qaravan.core import TFI, Magnetization
+from qaravan.applications import trotter_circuit
+
+ham = TFI(n=8, J=1.0, h=0.75)
+step = trotter_circuit(ham, dt=0.1)
+obs = Magnetization(n=8)
+
+state = Statevector(bitstring="0" * 8)
+mags = []
+for _ in range(50):
+    mags.append(state.expectation(obs))
+    state = state.apply(step)
+```
+
+## Backends planned
+
+| Backend | State type | Notes |
+|---|---|---|
+| `StatevectorSimulator` | `Statevector` | ![Complete](https://img.shields.io/badge/Complete-brightgreen) |
+| `DensityMatrixSimulator` | `DensityMatrix` | ![In legacy](https://img.shields.io/badge/In_legacy-blue) |
+| `MPSSimulator` | `MPS` | ![In legacy](https://img.shields.io/badge/In_legacy-blue) |
+| `MPDOSimulator` | `MPDO` | ![In legacy](https://img.shields.io/badge/In_legacy-blue) |
+| `MonteCarloSimulator` | `Walkers` | ![In development](https://img.shields.io/badge/In_development-orange) |
+| `CliffordSimulator` | `StabilizerTableau` | ![In development](https://img.shields.io/badge/In_development-orange) |
+| `MatchgateSimulator` | `GaussianState` | ![In legacy](https://img.shields.io/badge/In_legacy-blue) |
+| `PauliPropagationSimulator` | `PauliSum` | ![In development](https://img.shields.io/badge/In_development-orange) |

{qaravan-0.2.2 → qaravan-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qaravan"
-version = "0.2.2"
+version = "0.2.3"
 description = "Unified classical simulation of noiseless and noisy quantum circuits"
 authors = [{ name = "Faisal Alam", email = "faisal@phasecraft.io" }]
 requires-python = ">=3.11"

qaravan-0.2.3/src/qaravan/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.2.3"

{qaravan-0.2.2 → qaravan-0.2.3}/src/qaravan/backends/monte_carlo.py

@@ -149,7 +149,7 @@ class MonteCarloSimulator(Simulator):
             circuit, initial_state, noise_model, decompose, noise_rng=noise_rng
         )
         representative = initial_state[0]
-        member_simulator_type = initial_state.default_simulator
+        member_simulator_type = representative.default_simulator
         self.member_simulator = member_simulator_type(
             circuit,
             representative,

{qaravan-0.2.2 → qaravan-0.2.3/src/qaravan.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: qaravan
-Version: 0.2.2
+Version: 0.2.3
 Summary: Unified classical simulation of noiseless and noisy quantum circuits
 Author-email: Faisal Alam <faisal@phasecraft.io>
 Requires-Python: >=3.11

qaravan-0.2.2/README.md

@@ -1,139 +0,0 @@
-# Qaravan
-
-[![PyPI version](https://img.shields.io/pypi/v/qaravan.svg)](https://pypi.org/project/qaravan/)
-[![codecov](https://codecov.io/gh/alam-faisal/qaravan/branch/rewrite%2Fv0.2/graph/badge.svg)](https://codecov.io/gh/alam-faisal/qaravan/branch/rewrite%2Fv0.2)
-
-**Qaravan** is a Python library for classical simulation of quantum circuits. It is designed for rapid prototyping of near-term quantum algorithms, error mitigation techniques, and mid-circuit measurement applications.
-
-> **v0.2 is under active development.** The API described here reflects the target design. Legacy v0.1 code is preserved under `qaravan.legacy` for reference.
-
-## Design
-
-Qaravan is built around four core abstractions:
-
-- **`Gate`** — an operation with a name, site indices, and a matrix representation. Backend-agnostic.
-- **`Circuit`** — an ordered sequence of gates. Supports `+` (concatenation), `*` (repetition), `.dagger()`.
-- **`State`** — the evolving data structure (statevector, density matrix, MPS, ...). Owns `.expectation()`, `.sample()`, `.sample_and_collapse()`.
-- **`Simulator`** — takes an initial `State`, a `Circuit`, and an optional `NoiseModel`. Compiles and evolves; returns the final `State`.
-
-The `State`/`Simulator` split is the key design choice: the returned `State` is independent of the simulator, which makes dynamic-circuit and feed-forward workflows natural.
-
-## Installation
-
-Install from PyPI:
-
-```bash
-uv add qaravan
-```
-
-For development (clone the repo first):
-
-```bash
-uv sync --group dev
-```
-
-## Usage
-
-### Noiseless simulation
-
-```python
-from qaravan.core.gates import H, CNOT
-from qaravan.core.circuits import Circuit
-from qaravan.core.observables import PauliString
-from qaravan.backends.statevector import Statevector, StatevectorSimulator
-
-circ = Circuit([H(0), CNOT([0, 1])])
-obs = PauliString("ZZ")
-
-sv = Statevector(bitstring="00")
-final_sv = StatevectorSimulator(circ, sv).run()
-print("⟨ZZ⟩:", final_sv.expectation(obs))   # → 1.0
-```
-
-### Noisy simulation
-
-```python
-from qaravan.core.noise import ThermalNoise
-from qaravan.backends.density_matrix import DensityMatrix, DensityMatrixSimulator
-
-nm = ThermalNoise(t1=100, t2=75, t_q1=0.04, t_q2=0.5)
-dm = DensityMatrix(bitstring="00")
-final_dm = DensityMatrixSimulator(circ, dm, nm).run()
-print("⟨ZZ⟩:", final_dm.expectation(obs))
-```
-
-### Dynamic circuits (mid-circuit measurement + feed-forward)
-
-```python
-from qaravan.backends.statevector import Statevector, StatevectorSimulator
-
-sv = Statevector(bitstring="0" * n)
-for round in range(n_rounds):
-    outcome, sv = sv.sample_and_collapse(meas_sites)
-    correction = decoder(outcome, round)
-    sv = StatevectorSimulator(correction, sv).run()
-```
-
-### Trotter time evolution
-
-```python
-from qaravan.core.hamiltonians import TFI
-from qaravan.core.observables import Magnetization
-from qaravan.backends.density_matrix import DensityMatrix, DensityMatrixSimulator
-
-ham = TFI(n=8, j=1.0, h=0.75)
-nm = ThermalNoise(t1=100, t2=75, t_q1=0.04, t_q2=0.5)
-obs = Magnetization(n=8)
-
-circ = ham.trotter_circuit(step_size=0.1)
-dm = DensityMatrix(bitstring="0" * 8)
-exp_list = []
-for _ in range(500):
-    exp_list.append(dm.expectation(obs))
-    dm = DensityMatrixSimulator(circ, dm, nm).run()
-```
-
-## Backends
-
-| Backend | State type | Noise | Notes |
-|---|---|---|---|
-| `StatevectorSimulator` | `Statevector` | ✗ | Reference backend |
-| `DensityMatrixSimulator` | `DensityMatrix` | ✓ | Full $d^{2n}$ density matrix |
-| `MPSSimulator` | `MPS` | ✗ | Bond-dimension truncation |
-| `MPDOSimulator` | `MPDO` | ✓ | Mixed-state MPS |
-| `MonteCarloSimulator` | `Walkers` | ✓ | Trajectory sampling |
-| `CliffordSimulator` | `StabilizerTableau` | ✓ | Wraps Stim |
-| `MatchgateSimulator` | `GaussianState` | — | Fermionic Gaussian circuits |
-| `PauliPropagationSimulator` | `PauliSum` | — | Heisenberg-picture propagation |
-
-## Gotchas
-
-**`Circuit.copy()` resets layers but preserves decomposition.**
-`copy()` returns a new circuit with the same gate list but `layers = None`.
-`construct_layers()` must be called again on the copy before iterating over layers.
-Decomposition is *not* undone: `decompose()` mutates `self.gates` in place, so a copy of a decomposed circuit still has the decomposed gates.
-
-**Qubit ordering is big-endian: qubit 0 is the most significant bit.**
-Applying `H(0)` to a 2-qubit system embeds as `H ⊗ I`, not `I ⊗ H`.
-In general, gate `G` on qubit `k` of an `n`-qubit system embeds as:
-
-```
-I^{⊗k} ⊗ G ⊗ I^{⊗(n−k−1)}
-```
-
-Basis state index `i` corresponds to bitstring `q0 q1 … q_{n−1}` where `i = q0·2^{n−1} + q1·2^{n−2} + … + q_{n−1}·2^0`. Qubit 0 is the leftmost qubit in ket notation. This is the opposite of Qiskit's little-endian convention, where qubit 0 is the least significant bit and `H(0)` embeds as `I ⊗ H`.
-
-## Roadmap
-
-- ✅ **v0.2 scaffold** — directory structure, legacy preservation, `uv` packaging
-- ✅ **Core ABCs** — `Gate`, `Circuit`, `State`, `Simulator`, `Observable`, `NoiseModel`
-- 🔧 **Concrete gates** — `H`, `X`, `Y`, `Z`, `CNOT`, `RX/Y/Z`, `RXX/YY/ZZ`, `Reset`, `Measure`
-- ⬜ **Statevector backend** — reference implementation
-- ⬜ **Density matrix backend** — first noisy backend
-- ⬜ **TFI Hamiltonian** — first end-to-end Trotter workflow
-- ⬜ **MPS / MPDO backends**
-- ⬜ **Mid-circuit measurements** — `Measure` gate, classical registers, feed-forward
-- ⬜ **Monte Carlo backend**
-- ⬜ **Clifford backend** (wraps Stim)
-- ⬜ **Matchgate backend**
-- ⬜ **Pauli propagation backend**

qaravan-0.2.2/src/qaravan/__init__.py

@@ -1 +0,0 @@
-__version__ = "0.2.0"