Quantum compilation framework for data loading (QCFDL)

QCFDL is a lightweight toolkit for estimating quantum resources required to load classical vectors into quantum states. It evaluates multiple algorithms for two common tasks:

• State preparation of a target amplitude vector
• Block-encoding approximations of a target vector

It leverages PennyLane's experimental resource estimation API to report gate counts and qubit usage for different approaches under a shared interface.

---

Features

• Evaluate several algorithms with a single call
• Two problem types: state_prep and block_encoding
• Tunable error budget split into precision and approximation components
• Respect a hardware budget via max_wires (extra wires used as work qubits)
• Optional splitting parameter (max_splits) for algorithms that support controlled subroutines

---

Installation

QCFDL required PennyLane as a key dependency, which can be installed as follows (Python ≥ 3.10 recommended):

pip install pennylane

---

Quickstart

import numpy as np
from qcfdl.main import compute_resources

# Create and normalize a target amplitude vector (length must be a power of 2)
state = np.random.normal(size=1024)
state = state / np.linalg.norm(state)

# Estimate resources for state preparation methods
results = compute_resources(
    amplitudes=state,
    error=1e-3,              # or (precision_error, approximation_error)
    max_wires=12,            # total available qubits; extra beyond log2(len(state)) are work qubits
    prob_type="state_prep", # or "block_encoding"
    verbose=True             # print per-method details
)

# `results` is a list of gate count objects, one per method evaluated

---

API

qcfdl.main.compute_resources

• amplitudes (np.ndarray): Target vector to load/approximate.
• error (float | tuple[float, float]): If a float is provided, it is split evenly into (precision_error, approximation_error). Some methods primarily use one of these.
• max_wires (int): Total qubits available. Must be ≥ ceil(log2(len(amplitudes))). Extra wires are used as work qubits where applicable.
• max_splits (int): Optional splitting for algorithms that support controlled compositions.
• prob_type (str): One of "state_prep" or "block_encoding".
• verbose (bool): Print method names and detailed resource info.

Returns: list of per-method resource summaries (gate counts). When verbose is False, a concise per-method summary is printed.

Behavioral notes:

• If max_wires == num_wires (no work qubits), QROM-based state preparation is skipped.
• Methods are evaluated in a fixed order (see below), and the returned list aligns with that order.

---

Supported methods

State preparation (qcfdl/state_prep)

• Fourier Series Loader (FSL) (fsl.py): Fourier-based synthesis of amplitudes.
• Matrix Product State (MPS) (mps.py): Approximates the target using an MPS with adaptive bond dimension chosen to meet the approximation error; resources are derived from qml.MPSPrep.
• Sum of Slaters (SoS) (sparse.py): Sparse/structured approximation using a sum of Slater determinants; uses QROM-based rotations for the selected support.
• Möttönen State Preparation (mottonen.py): Standard uniformly controlled rotations for exact state preparation.
• QROM State Preparation (qrom.py): Angle loading via QROM with precision wires and optional parallelization controls.

Imported as:

from qcfdl.state_prep import (
    fourier_loader_resource, mps_resource, sos_resource,
    mottonen_resource, qrom_prep_resource,
)

Block-encoding (qcfdl/block_encoding)

• QSP Block Encoding (qsp.py): Chebyshev/QSP-based approximation; finds a polynomial degree meeting the approximation error and estimates controlled rotations.
• Walsh Block Encoding (walsh.py): Approximates in the Walsh-Hadamard basis and estimates controlled-phase resources.
• Möttönen Block Encoding (mottonen.py): Uses uniformly controlled rotations as a block-encoding primitive; parameterized by per-rotation precision.
• QROM Block Encoding (qrom.py): QROM-driven construction with precision and optional work wires for select/swap parallelization.

Imported as:

from qcfdl.block_encoding import (
    qsp_block_encoding_resource, walsh_block_encoding_resource,
    mottonen_block_encoding_resource, qrom_block_encoding_resource,
)

---

Error model and parameters

• error = (precision_error, approximation_error)
  • Precision error typically controls the fidelity/angle precision of continuous rotations (e.g., CRZ/RY discretization).
  • Approximation error controls truncation/approximation quality (e.g., MPS bond dimension, Walsh truncation, polynomial degree).
• max_wires: Total hardware qubits available. For QROM-based methods, additional work wires can reduce T or CNOT depth via select/swap parallelization.

Each method documents its own internal choices (e.g., precision wire counts, bond dimension search) in its respective module.

---

Repository layout

QCFDL/
  ├─ qcfdl/
  │  ├─ main.py                # Entry point with compute_resources
  │  ├─ state_prep/            # State preparation algorithms
  │  ├─ block_encoding/        # Block-encoding algorithms
  │  ├─ split.py               # Utilities for problem splitting
  │  └─ wf_utils.py            # Wavefunction helpers
  └─ README.md                 # This file