final first commit

qibojit-benchmarks/scripts/quimb/README.md

@@ -0,0 +1,214 @@
+# Quimb Benchmark Suite
+
+Local (single-process) tensor network simulation benchmarking using quimb backend.
+
+## Files
+
+- **quimb_local.sh** — Main benchmark sweep script (no MPI)
+- **expectation_mps.json** — Expectation mode with MPS (default for expectation)
+- **expectation_dense.json** — Expectation mode, dense tensor network
+- **dense_vector_mps.json** — State extraction with MPS (default for state)
+- **dense_vector_dense.json** — State extraction, dense tensor network
+
+## Configuration Files
+
+### Expectation Modes (computing Hamiltonian expectation values)
+- **expectation_mps.json**: Uses Matrix Product State (MPS) tensor network ansatz; good for larger systems with limited bond dimension
+- **expectation_dense.json**: Uses dense tensor network; full contraction without MPS truncation
+
+### State Modes (full state vector computation)
+- **dense_vector_mps.json**: Extracts full state using MPS contraction (faster, bounded memory)
+- **dense_vector_dense.json**: Extracts full state using dense tensor (maximum memory usage)
+
+## Usage
+
+```bash
+cd /ssd_data/tankya2/code/ASC_2026_prism/ASC-2026/qibojit-benchmarks/scripts/quimb
+
+# Run with defaults (all matching dense_vector*.json and expectation*.json configs)
+./quimb_local.sh
+
+# Test only expectation mode, custom qubit sizes
+modes="expectation" nqubits_list="8 10 12" ./quimb_local.sh
+
+# Test dense vector only with one explicit config
+state_cfg=dense_vector_dense.json modes="dense_vector" ./quimb_local.sh
+
+# Restrict the sweep to a chosen subset of configs
+EXPECTATION_CONFIGS="expectation_mps.json expectation_dense.json" ./quimb_local.sh
+
+# Test variational and BV circuits
+circuits="variational bv" nqubits_list="6 8 10" nreps=3 ./quimb_local.sh
+```
+
+## Supported Circuits
+
+### ✓ Fully Supported (Numerically Validated)
+
+| Circuit | Alias | Parameters | Status | Notes |
+|---------|-------|------------|--------|-------|
+| **qft** | — | none | ✓ Works | Quantum Fourier Transform; aligned with qibojit |
+| **supremacy** | — | depth, seed | ✓ Works | Verified locally after environment repair; requires Cirq import path to be healthy |
+| **variational** | — | nlayers | ✓ Works | Parameterized circuit; aligned with qibojit |
+| **bv** | bernstein-vazirani | none | ✓ Works | Bernstein-Vazirani algorithm; aligned with qibojit |
+| **hs** | hidden-shift | none | ✓ Works | Hidden-shift problem; aligned with qibojit |
+| **qaoa** | — | nlayers | ✓ Works | QAOA with RZZ gate support; aligned with qibojit |
+
+### ❌ Not Supported
+
+| Circuit | Issue | Notes |
+|---------|-------|-------|
+| **qv** | Qiskit API compatibility | quantum-volume uses deprecated qiskit `.qasm()` method (v3.0+); not specific to quimb |
+
+### Implementation Notes
+- **RZZ Gate:** Full support for QAOA and algorithms using two-qubit Ising rotations
+- **cu1 Gate:** Fully supported in expectation value mode (QFT compatible)
+- **Numerical Alignment:** All benchmarks automatically include qibojit (numba) reference with identical observable for validation
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `nqubits_list` | `6 8 10` | Space-separated qubit counts to benchmark |
+| `circuits` | `supremacy qft variational bv qaoa` | Space-separated circuit names |
+| `modes` | `dense_vector expectation` | Benchmark modes (dense_vector, expectation) |
+| `nlayers` | `2` | Layers for layered circuits (variational, qaoa) |
+| `nreps` | `1` | Repetitions per benchmark |
+| `filename` | `quimb_benchmark_local.dat` | Output log file |
+| `precision` | `complex128` | NumPy dtype (complex128 or complex64) |
+| `exp_cfg` | unset | Optional single expectation config; when unset, all `expectation*.json` files are swept |
+| `state_cfg` | unset | Optional single dense-vector config; when unset, all `dense_vector*.json` files are swept |
+| `EXPECTATION_CONFIGS` | unset | Optional space-separated subset of expectation configs to run |
+| `STATE_CONFIGS` | unset | Optional space-separated subset of dense-vector configs to run |
+
+## Results
+
+Results are logged to `/qibojit-benchmarks/benchmarks/results/` with filename `quimb_benchmark_local.dat` (configurable).
+
+Each benchmark includes:
+- **import_time** — Backend initialization time
+- **creation_time** — Circuit creation time
+- **dry_run_time** — First execution time (warm-up)
+- **simulation_times** — Execution times for nreps runs
+- **expectation_result** — Observable expectation values (for expectation mode)
+
+## Observable
+
+By default, expectation uses:
+- **X on qubit 0**, identity on remaining qubits
+- Configurable via `pauli_pattern` in JSON config (e.g., `"XIIII"` for 5 qubits)
+
+## Reference Validation
+
+Each benchmark run automatically includes a **qibojit (numba) reference** with the same observable configuration, enabling direct numerical comparison for validation.
+
+Example:
+```
+[expectation MPI] quimb + qft @ 6q:     0.2019...
+[qibojit ref]     numba + qft @ 6q:     0.2019...  ✓ aligned
+```
+
+## MPI Support
+
+For MPI-enabled benchmarking (multiple processes), see the parallel suite in `/scripts/quimb_mpi/`:
+
+```bash
+cd /ssd_data/tankya2/code/ASC_2026_prism/ASC-2026/qibojit-benchmarks/scripts/quimb_mpi
+./quimb_mpi.sh  # runs with mpirun -np 2
+```
+
+## Tensor Network Options
+
+Quimb supports both MPS (Matrix Product State) and dense tensor network contractions. By default the script sweeps every matching JSON file in this folder, or you can target individual configs:
+
+```bash
+# Compare MPS vs dense at same nqubits
+exp_cfg=expectation_mps.json nqubits_list="12" ./quimb_local.sh
+exp_cfg=expectation_dense.json nqubits_list="12" ./quimb_local.sh
+```
+
+MPS is typically faster and uses bounded memory, while dense provides full accuracy without truncation.
+
+## Installation
+
+Preferred path: create a fresh environment from the benchmark spec.
+
+```bash
+cd /ssd_data/tankya2/code/ASC_2026_prism/ASC-2026/qibojit-benchmarks
+conda env create -f environment.yml
+conda activate benchmarks
+```
+
+If you are using an existing environment instead of recreating it, check that it is aligned with the benchmark stack:
+
+```bash
+python -c "import numpy, qibo, qibojit; print('numpy', numpy.__version__); print('qibo', qibo.__version__); print('qibojit', qibojit.__version__)"
+```
+
+## Dependency Recovery
+
+```bash
+pip install cirq==0.8.2
+```
+This is the recovery path that eventually made `./quimb_local.sh` work for `supremacy` in the existing `qibotn-py311-test` environment.
+
+### Symptom 1: `cirq` failed with `ModuleNotFoundError: No module named 'pkg_resources'`
+
+Cause:
+- the existing environment had `setuptools 82.0.1`
+- that install did not expose `pkg_resources`
+- the installed `cirq` package still imported `pkg_resources` during startup
+
+Fix:
+
+```bash
+/home/tankya2/miniforge3/envs/qibotn-py311-test/bin/python -m pip install "setuptools<81"
+```
+
+Working result:
+- `setuptools` was changed to `80.10.2`
+- `import pkg_resources` worked again
+- the Quimb `supremacy` path could construct the Cirq-generated circuit
+
+### Symptom 2: `qibojit` reference crashed with `TypeError: asarray() got an unexpected keyword argument 'copy'`
+
+Cause:
+- the same environment had `numpy 1.26.4`
+- but `qibo 0.3.1` requires `numpy >= 2.0.0`
+- the `qibojit` reference backend was therefore running against an incompatible NumPy version
+
+Fix:
+
+```bash
+/home/tankya2/miniforge3/envs/qibotn-py311-test/bin/python -m pip install numpy==2.2.6
+```
+
+Working result:
+- `numpy` was changed to `2.2.6`
+- the `qibojit` reference backend started working again
+- both the Quimb and qibojit sides of the `supremacy` benchmark completed successfully
+
+### Final verified state
+
+The existing repaired environment was verified with:
+
+```bash
+cd /ssd_data/tankya2/code/ASC_2026_prism/ASC-2026/qibojit-benchmarks/scripts/quimb
+nqubits_list="6" circuits="supremacy" nreps=1 modes="dense_vector expectation" ./quimb_local.sh
+```
+
+That smoke test completed all three stages:
+- Quimb `dense_vector`
+- Quimb `expectation`
+- qibojit reference
+
+Notes:
+- `environment.yml` remains the preferred source of truth for a clean install
+- the repaired environment may still emit a `pkg_resources` deprecation warning from the older Cirq stack, but the benchmark run succeeds
+- if an environment has drifted far from `environment.yml`, recreating it is usually safer than incremental repair
+
+## Notes
+
+- **Intel MPI Fabric:** On Prism cluster, shared-memory fabric (`I_MPI_FABRICS=shm`) is automatically enabled for single-node runs
+- **QFT Support:** Fixed cu1 gate compatibility in quimb backend; no platform-specific gate limitations
+- **Bond Dimension:** MPS modes use max_bond_dimension=20 by default; adjust in JSON for memory/accuracy tradeoff

qibojit-benchmarks/scripts/quimb/dense_vector_dense.json

@@ -0,0 +1 @@
+{"expectation_enabled": false, "use_mps": false}

qibojit-benchmarks/scripts/quimb/dense_vector_mps.json

@@ -0,0 +1 @@
+{"expectation_enabled": false, "use_mps": true, "max_bond_dimension": 20, "svd_cutoff": 1e-10}

qibojit-benchmarks/scripts/quimb/expectation_dense.json

@@ -0,0 +1 @@
+{"expectation_enabled": true, "use_mps": false, "pauli_pattern": "XIIII"}

qibojit-benchmarks/scripts/quimb/expectation_dense_auto.json

@@ -0,0 +1,6 @@
+{
+  "expectation_enabled": true,
+  "use_mps": false,
+  "pauli_pattern_auto": true,
+  "pauli_pattern_style": "mixed"
+}

qibojit-benchmarks/scripts/quimb/expectation_mps.json

@@ -0,0 +1 @@
+{"expectation_enabled": true, "use_mps": true, "max_bond_dimension": 20, "svd_cutoff": 1e-10, "pauli_pattern": "XIIII"}

qibojit-benchmarks/scripts/quimb/quimb_local.sh

@@ -0,0 +1,215 @@
+#!/usr/bin/env bash
+# Local quimb benchmark sweep.
+# Tests both dense vector (non-expectation) and expectation across multiple
+# qubit sizes and circuit types.
+#
+# Usage examples:
+#   ./quimb_local.sh
+#   nqubits_list="6 8 10" circuits="variational bv" ./quimb_local.sh
+#   modes="expectation" nreps=3 ./quimb_local.sh
+#   state_cfg=dense_vector_dense.json modes="dense_vector" ./quimb_local.sh
+set -euo pipefail
+
+: "${precision:=complex128}"
+: "${nreps:=3}"
+: "${filename:=quimb_benchmark_local.dat}"
+: "${nlayers:=2}"
+: "${nqubits_list:=6 8 10}"
+: "${circuits:=supremacy qft variational qaoa}"
+: "${modes:=dense_vector expectation}"
+: "${exp_cfg:=}"
+: "${state_cfg:=}"
+: "${EXPECTATION_CONFIGS:=}"
+: "${STATE_CONFIGS:=}"
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+repo_root="$(cd "${script_dir}/../.." && pwd)"
+cd "${repo_root}"
+
+config_list_from_prefix() {
+    local prefix="$1"
+    local single_cfg="$2"
+    local override_list="$3"
+
+    if [[ -n "${override_list}" ]]; then
+        for cfg in ${override_list}; do
+            printf '%s\n' "${cfg}"
+        done
+        return
+    fi
+
+    if [[ -n "${single_cfg}" ]]; then
+        printf '%s\n' "${single_cfg}"
+        return
+    fi
+
+    shopt -s nullglob
+    local matches=( "${script_dir}/${prefix}"*.json )
+    shopt -u nullglob
+
+    for path in "${matches[@]}"; do
+        basename "${path}"
+    done
+}
+
+require_existing_configs() {
+    local mode="$1"
+    shift
+
+    for cfg in "$@"; do
+        if [[ ! -f "${script_dir}/${cfg}" ]]; then
+            echo "Missing ${mode} config: ${script_dir}/${cfg}" >&2
+            exit 1
+        fi
+    done
+}
+
+read_pauli_pattern() {
+    local cfg_path="$1"
+
+    python - "${cfg_path}" <<'PY'
+import json
+import sys
+
+try:
+    with open(sys.argv[1], "r") as f:
+        data = json.load(f)
+    print(data.get("pauli_pattern", ""))
+except Exception:
+    print("")
+PY
+}
+
+build_ref_pattern() {
+    local base_pauli_pattern="$1"
+    local nqubits="$2"
+
+    python - "${base_pauli_pattern}" "${nqubits}" <<'PY'
+import sys
+
+p = sys.argv[1].upper()
+n = int(sys.argv[2])
+
+if not p:
+    p = "X" + "I" * max(n - 1, 0)
+if len(p) < n:
+    p = p + ("I" * (n - len(p)))
+else:
+    p = p[:n]
+print(p)
+PY
+}
+
+run_qibojit_reference() {
+    local nqubits="$1"
+    local circuit="$2"
+    local circuit_opts="$3"
+    local exp_cfg_name="$4"
+    local exp_cfg_path="${script_dir}/${exp_cfg_name}"
+    local base_pauli_pattern
+    local ref_pattern
+
+    base_pauli_pattern="$(read_pauli_pattern "${exp_cfg_path}")"
+    ref_pattern="$(build_ref_pattern "${base_pauli_pattern}" "${nqubits}")"
+
+    echo "  [qibojit reference] cfg=${exp_cfg_name}"
+    python compare.py \
+        --circuit "${circuit}" \
+        ${circuit_opts:+--circuit-options "${circuit_opts}"} \
+        --nqubits "${nqubits}" \
+        --filename "${filename}" \
+        --library-options backend=qibojit,platform=numba,expectation=${ref_pattern} \
+        --nreps "${nreps}" \
+        --precision "${precision}"
+}
+
+mapfile -t expectation_cfgs < <(
+    config_list_from_prefix "expectation" "${exp_cfg}" "${EXPECTATION_CONFIGS}"
+)
+mapfile -t state_cfgs < <(
+    config_list_from_prefix "dense_vector" "${state_cfg}" "${STATE_CONFIGS}"
+)
+
+run_dense_mode=false
+run_expectation_mode=false
+
+if echo "${modes}" | grep -Eqw "dense_vector|statevector"; then
+    run_dense_mode=true
+fi
+
+if echo "${modes}" | grep -qw "expectation"; then
+    run_expectation_mode=true
+fi
+
+if [[ "${run_dense_mode}" == true && ${#state_cfgs[@]} -eq 0 ]]; then
+    echo "No dense-vector JSON configs found in ${script_dir}" >&2
+    exit 1
+fi
+
+if [[ "${run_expectation_mode}" == true && ${#expectation_cfgs[@]} -eq 0 ]]; then
+    echo "No expectation JSON configs found in ${script_dir}" >&2
+    exit 1
+fi
+
+require_existing_configs "dense-vector" "${state_cfgs[@]}"
+require_existing_configs "expectation" "${expectation_cfgs[@]}"
+
+# On Prism, Intel MPI needs shared-memory fabric for single-node runs.
+if [[ -z "${I_MPI_FABRICS:-}" ]]; then
+    export I_MPI_FABRICS=shm
+fi
+
+echo "Dense-vector configs : ${state_cfgs[*]:-none}"
+echo "Expectation configs  : ${expectation_cfgs[*]:-none}"
+
+for nqubits in ${nqubits_list}; do
+    for circuit in ${circuits}; do
+        circuit_opts="nlayers=${nlayers}"
+        # These circuits do not use nlayers — omit it to avoid unknown-option errors.
+        if [[ "${circuit}" == "qft" || "${circuit}" == "QFT" || \
+              "${circuit}" == "supremacy" || "${circuit}" == "Supremacy" || \
+              "${circuit}" == "bv" || "${circuit}" == "bernstein-vazirani" || \
+              "${circuit}" == "hs" || "${circuit}" == "hidden-shift" || \
+              "${circuit}" == "qaoa" || "${circuit}" == "qv" || \
+              "${circuit}" == "quantum-volume" ]]; then
+            circuit_opts=""
+        fi
+
+        echo "===== nqubits=${nqubits}  circuit=${circuit} ====="
+
+        # dense_vector is the preferred name; statevector is kept as a legacy alias.
+        if [[ "${run_dense_mode}" == true ]]; then
+            for cfg_name in "${state_cfgs[@]}"; do
+                state_cfg_path="${script_dir}/${cfg_name}"
+                echo "  [dense_vector] cfg=${cfg_name}"
+                python compare.py \
+                    --circuit "${circuit}" \
+                    ${circuit_opts:+--circuit-options "${circuit_opts}"} \
+                    --nqubits "${nqubits}" \
+                    --filename "${filename}" \
+                    --library-options backend=qibotn,platform=quimb,computation_settings=${state_cfg_path} \
+                    --nreps "${nreps}" \
+                    --precision "${precision}"
+            done
+        fi
+
+        if [[ "${run_expectation_mode}" == true ]]; then
+            for cfg_name in "${expectation_cfgs[@]}"; do
+                exp_cfg_path="${script_dir}/${cfg_name}"
+                echo "  [expectation] cfg=${cfg_name}"
+                python compare.py \
+                    --circuit "${circuit}" \
+                    ${circuit_opts:+--circuit-options "${circuit_opts}"} \
+                    --nqubits "${nqubits}" \
+                    --filename "${filename}" \
+                    --library-options backend=qibotn,platform=quimb,computation_settings=${exp_cfg_path} \
+                    --nreps "${nreps}" \
+                    --precision "${precision}"
+
+                run_qibojit_reference "${nqubits}" "${circuit}" "${circuit_opts}" "${cfg_name}"
+            done
+        fi
+
+        echo
+    done
+done