docs/getting-started.md

Getting Started

Install

pip install dense-evolution  # JAX is a core dependency, installed by default

# full stack: GPU · dashboard · Qiskit/PennyLane interop
pip install dense-evolution[full]

# just the interop bridge
pip install dense-evolution[qiskit]
pip install dense-evolution[pennylane]

# development (includes pytest + pytest-cov)
git clone https://github.com/tatopenn-cell/Dense-Evolution.git
cd Dense-Evolution && pip install -e .[full,dev]

Google Colab (3 lines):

!git clone https://github.com/tatopenn-cell/Dense-Evolution.git
%cd Dense-Evolution
!pip install -e .

Quick start

from dense_evolution import DenseSVSimulator, QASMParser

# parse any OpenQASM 2.0 / 3.0 string
qasm = """
OPENQASM 2.0;
include "qelib1.inc";
qreg q[3];
h q[0];
cx q[0], q[1];
cx q[1], q[2];
"""

parser = QASMParser()
circuit = parser.parse(qasm)

sim = DenseSVSimulator(n_qubits=3)
sim.run_circuit_jit_beast_mode(circuit.to_tuples())

probs = sim.get_probabilities()
sv    = sim.get_statevector()

Anti-OOM for large circuits

from dense_evolution import Chunk

sim = Chunk(27)                                    # logical 27 qubits
circuit_ops = [['h', i] for i in range(27)]
sim.run_chunk(circuit_ops, chunk_size_gates=500)   # SafeMemoryGuard active

Zero-Noise Extrapolation

Self-contained: builds its own noisy density matrices via Monte Carlo, so it runs as-is. rho_ideal is used only to grade the result at the end, never fed into the correction itself (see the full writeup in Examples).

import numpy as np
import jax.numpy as jnp
import dense_evolution as de
from dense_evolution.registry import NoiseModel
from dense_evolution.mitigation import zne_density_matrix, uhlmann_fidelity

N_QUBITS, SCALES, K = 2, (1.0, 2.0, 3.0), 200
rng = np.random.default_rng(0)

sim = de.DenseSVSimulator(N_QUBITS)
sim.run_circuit([("h", 0), ("cx", 0, 1)])
ideal_sv = np.asarray(sim.get_statevector())
rho_ideal = jnp.asarray(np.outer(ideal_sv, ideal_sv.conj()), dtype=jnp.complex128)

def noisy_density_matrix(p):
    dim = len(ideal_sv)
    rho = np.zeros((dim, dim), dtype=np.complex128)
    for _ in range(K):
        sv_noisy = NoiseModel.apply_to_sv(ideal_sv.copy(), N_QUBITS, 'depolarizing', p, rng=rng)
        rho += np.outer(sv_noisy, sv_noisy.conj())
    return jnp.asarray(rho / K, dtype=jnp.complex128)

rho_at_scales = jnp.stack([noisy_density_matrix(0.05 * scale) for scale in SCALES])

raw_fidelity = uhlmann_fidelity(rho_at_scales[0], rho_ideal)
corrected = zne_density_matrix(rho_at_scales, SCALES)
corrected_fidelity = uhlmann_fidelity(corrected, rho_ideal)

See dense_evolution.mitigation for the full API, including the _jit variants for use inside a larger jax.jit-compiled pipeline, and Examples for this walkthrough plus MPS and differentiable-VQE examples.

Dashboard (local, Streamlit)

app_dashboard.py lives at the root of the cloned repository -- it is not part of the pip-installed package, so this needs the git clone from the Install section above, not just pip install.

pip install "dense-evolution[dashboard]"  # JAX already included by default
cd Dense-Evolution
streamlit run app_dashboard.py

Running the test suite

pip install -e .[dev]
pytest test_dense_evolution.py test_mitigation.py test_mps.py -v

# with coverage
pytest --cov=dense_evolution --cov-report=term-missing