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

Abstract

Quantum algorithms require encoding classical vectors as quantum states, a step known as amplitude encoding. General-purpose routines produce circuits with O(2^m) gates for vectors of length N = 2^m, for an m-qubit register. 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 PyEncode, an open-source Python library that implements this body of theory in a unified framework. It covers ten exact pattern families: sparse, step, square, Walsh, Fourier, geometric, Hamming, staircase, Dicke, and polynomial. A function encode maps each pattern to a verified Qiskit circuit, with no vector materialization and no approximation; for example, encode(SPARSE([(19, 1.0)]), N=64) encodes the vector e_19 of length N = 64. Sparse, step, Walsh, Hamming, and staircase patterns require O(m) gates; square and Fourier patterns require O(m^2); Dicke states D^m_k require O(k(m-k)), that denotes uniform superpositions over indices of Hamming weight k; degree-d polynomials require O(m^(d+1)). A companion predict_gates function estimates transpiled gate counts without synthesis, and a reverse-lookup utility match_vector identifies which family best fits a given numerical vector. Three composition primitives are supported: SUM for weighted superpositions, PARTITION for ancilla-free composition of disjoint-support patterns, and TENSOR for separable states over disjoint subregisters. For amplitude vectors outside these exact families, PyEncode also provides a matrix product state (MPS) loader, encode_mps for approximate vector encoding. The library is available at https://github.com/UW-ERSL/PyEncode.