Metadata-Version: 2.4
Name: quaq
Version: 0.0.3
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: numpy>=1.24 ; extra == 'numpy'
Provides-Extra: numpy
Summary: A high-performance, qudit-agnostic quantum simulation engine and ML toolkit, optimized with a Rust core for 10-170x faster execution than industry standards.
Keywords: quantum,simulation,machine-learning,reservoir-computing
Home-Page: https://github.com/EnriqueAnguianoVara/quac
Author: Enrique Anguiano Vara
Requires-Python: >=3.10
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/EnriqueAnguianoVara/quac
Project-URL: Issues, https://github.com/EnriqueAnguianoVara/quac/issues
Project-URL: Repository, https://github.com/EnriqueAnguianoVara/quac

# quaq: A duck over crabs
## A quantum simulator engine 10–170x faster than Qiskit Aer.

> Researchers should not have to choose between expressive models and efficient execution.
> Their quantum simulator must be shaped for them, to any experiment,
> and be deeply efficient inside.

To solve this issue, quaq is shaped by three main pillars:

1. **Quantum-unit agnostic simulation**: quaq is centered on qudits with
   configurable dimension d rather than assuming qubits everywhere. That
   makes it a natural foundation for working with qubits (d = 2), higher
   dimensional qudits, and continuous-variable-inspired discretizations within
   a single conceptual model. 

2. **Performance-first engineering**: quantum simulation gets expensive very
   quickly.
   quaq pushes all execution into Rust and is designed around low-level
   performance concerns. In some algorithms like VQE, quaq can reach ~180x speedup versus Qiskit Aer.
   
3. **Minimal surface, powerful internals**: performance should not come at the
   cost of usability. quaq aims to stay compact at the API level while
   gradually providing the core building blocks and algorithms researchers need
   for real workflows, from circuit simulation to machine-learning-oriented
   quantum pipelines. Our goal is to grow the library with strong community
   submissions so useful ideas can become directly available to everyone. 

## Performance
 
quaq is **10–170x faster than Qiskit Aer** depending on the algorithm and circuit size.
 
| Algorithm          | Median speedup | Range         |
|--------------------|---------------|---------------|
| VQE                | **169x**      | —             |
| QRC                | **33x**       | 7x – 90x      |
| GHZ                | **31x**       | 10x – 48x     |
| MPS random circuit | **16x**       | 2x – 42x      |
| Random circuit     | **16x**       | 2x – 59x      |
 
Benchmarks run with 200 samples. QRC range measured across 1–10 qubits and 1–10 reservoir layers.
Speedup = Aer sustained runtime / quaq sustained runtime.

## Installation

### From PyPI

```bash
pip install quaq
```

Optional numerical extras listed in `pyproject.toml`:

```bash
pip install "quaq[numpy]"
```

### Recommended local environment

```bash
python3 -m venv venv
source venv/bin/activate
pip install -U pip
```

### Install from source

If you want to work from the repository:

```bash
pip install -U maturin
pip install -e .
```

For a compiled development install:

```bash
maturin develop --release
```

## Quickstart

This section will be removed after version 0.1.0, when the
documentation will be available to everyone. 

### 1. Build and run a Bell-state-style circuit

```python
from quaq import SystemSpec, Circuit

spec = SystemSpec.from_qubits(2)
circ = Circuit(spec)

circ.h(0).cnot(0, 1)
circ.measure_z("z0", 0)
circ.measure_z("z1", 1)
circ.measure_zz("corr", 0, 1)

result = circ.run([])
print(result)
```

`run(...)` returns a dictionary keyed by your measurement labels.

### 2. Use parametric gates

```python
from quaq import SystemSpec, Circuit

spec = SystemSpec.from_qubits(2)
circ = Circuit(spec)

circ.ry(0, 0).rz(1, 1).rzz(0, 1, 2)
circ.measure_z("left", 0).measure_z("right", 1)

print(circ.run([0.7, 1.2, 0.3]))
```

Parametric gates store parameter indices in the circuit. The actual values are supplied later through `run(...)`.

### 3. Evaluate a circuit in batches

```python
outputs = circ.run_batch([
    [0.1, 0.2, 0.3],
    [0.4, 0.5, 0.6],
    [0.7, 0.8, 0.9],
])

print(outputs)
```

### 4. Define mixed-dimension systems

```python
from quaq import SystemSpec

spec = SystemSpec([2, 2, 3]) #2 qubtis, 1 qutrit
print(spec.dims())
print(spec.n_subsystems())
print(spec.total_dim())
```

The system description is based on subsystem dimensions rather than assuming everything is a qubit.

## Quantum Reservoir Computing

```python
from quaq import QuantumReservoir

model = QuantumReservoir(
    n_qubits=6,
    reservoir_layers=2,
    input_window=10,
    entanglement="brick",
    algorithm="qrc",
    two_body_readout=True,
)

model.fit(train_inputs, train_targets, method="ridge", lambda_=1e-4)
predictions = model.predict(test_inputs)

print(model.n_features())
print(predictions[:5])
```

Helper functions in `quaq.reservoir`:

- `fit_predict(...)`
- `score(...)`

Current reservoir configuration parameters exposed by the bindings include:

- `n_qubits`
- `input_window`
- `reservoir_layers`
- `input_scale`
- `seed`
- `algorithm`
- `warmup_steps`
- `entanglement`
- `two_body_readout`
- `include_raw_input`
- `include_x_readout`
- `include_y_readout`
- `use_zz_entangler`
- `forecast_horizon`
- `feature_leak`

## Advanced Public Bindings

These are part of the top-level package today, but they feel more advanced than the main `SystemSpec` + `Circuit` workflow.

### MPS simulator

```python
from quaq import MpsSimulator

sim = MpsSimulator.from_qubits(6, chi_max=64, singular_value_eps=1e-10)
sim.h(0)
sim.cnot(0, 1)

print(sim.norm_sq())
print(sim.max_bond_dim())
```

Current limitation exposed in the binding: `MpsSimulator.cnot(control, target)` only supports nearest-neighbor CNOT with `target = control + 1`.

### Gaussian-state continuous-variable API

```python
from quaq import GaussianState

state = GaussianState.vacuum(2)
state.displace(0, 0.2, -0.1)
state.squeeze(1, 0.4)
state.beamsplitter(0, 1, 0.3)

print(state.n_modes())
print(state.phase_space_dim())
print(state.homodyne(0, "x"))
```

The Gaussian-state binding currently exposes:

- `vacuum(n_modes)`
- `displace(mode, alpha_x, alpha_p)`
- `squeeze(mode, r)`
- `beamsplitter(mode_a, mode_b, theta)`
- `homodyne(mode, "x" | "p")`
- `heterodyne(mode)`
- accessors for displacement and covariance

