PyEncode: An Open-Source Library for Structured Quantum State Preparation

Quantum algorithms require encoding classical vectors as quantum states, a step known as amplitude encoding. General-purpose routines produce circuits with $\bigO{2^m}$ gates for vectors of length $N = 2^m$. However, vectors arising in scientific and engineering applications often exhibit mathematical structure that admits far more efficient encoding. Theoretical work over the last decade has established efficient circuits for several structured vector classes, but without open-source implementations. We present \textbf{PyEncode}, an open-source Python library that implements this body of theory in a unified framework. It covers ten exact pattern families: \emph{sparse, step, square, Walsh, Fourier, geometric, Hamming, staircase, Dicke}, and \emph{polynomial}. A function \texttt{encode} maps each pattern to a verified Qiskit circuit, with no vector materialization and no approximation; for example, \texttt{encode(SPARSE([(19, 1.0)]), N=64)} encodes the vector $\mathbf{e}_{19}$ of length $N = 64$. Sparse, step, Walsh, Hamming, and staircase patterns require $\bigO{m}$ gates; square and Fourier patterns require $\bigO{m^2}$; Dicke states $|D^m_k\rangle$ require $\bigO{k(m-k)}$; degree-$d$ polynomials require $\bigO{m^{d+1}}$. A companion \texttt{predict\_gates} function estimates transpiled gate counts without synthesis. Three composition primitives are supported: \texttt{SUM} for weighted superpositions, \texttt{PARTITION} for ancilla-free composition of disjoint-support patterns, and \texttt{TENSOR} for separable states over disjoint subregisters. For amplitude vectors outside these exact families, PyEncode also provides a matrix product state (MPS) loader, \texttt{encode\_mps}. The library is available at https://github.com/UW-ERSL/PyEncode.