quaq 0.0.3

A high-performance, qudit-agnostic quantum simulation engine and ML toolkit, optimized with a Rust core for 10-170x faster execution than industry standards.

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

pip install quaq

Optional numerical extras listed in pyproject.toml:

pip install "quaq[numpy]"

Recommended local environment

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

Install from source

If you want to work from the repository:

pip install -U maturin
pip install -e .

For a compiled development install:

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

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

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

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

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

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

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

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