Block Encoding (BlockEncoding/)

Tridiagonal Matrix Block Encoding (SparQ_Algorithm/include/BlockEncoding/block_encoding_tridiagonal.h)

Quantum block encoding of tridiagonal matrices.

Implements the block encoding of the symmetric tridiagonal matrix A = αI + βT (T is the shift matrix whose sub- and super-diagonals are all 1). Based on the LCU (linear combination of unitaries) decomposition A = αI + βU₊ + βU₋: after the ancilla register prepares the LCU amplitudes, the conditional shift gates (PlusOneAndOverflow) execute the +1/-1 shift branches, and the final unitary U satisfies (⟨0|_{anc}⊗I) U (|0|_{anc}⊗I) = (αI + βU₊ + βU₋)/‖A‖_F. This block encoding is a core submodule of the tridiagonal version (qda_tridiagonal.h) of the QDA discrete adiabatic solver

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

namespace block_encoding

namespace block_encoding_tridiagonal

Functions

inline DenseMatrix<double> get_block_encoding_tridiagonal(size_t qubit_num, double alpha, double beta)

Extract the encoded block matrix of the tridiagonal block encoding (numerical verification helper)

Parameters:

• qubit_num – Number of qubits n of the main register

• alpha – Diagonal-entry coefficient α

• beta – Off-diagonal-entry coefficient β

Returns:

Real matrix of the encoded block (⟨0|_{anc}⊗I) U (|0|_{anc}⊗I) with dimension 2^n × 2^n; its theoretical value is (αI + βT)/‖αI + βT‖_F

inline DenseMatrix<double> get_tridiagonal_matrix(double alpha, double beta, size_t dim)

Construct the classical tridiagonal matrix αI + βT.

Parameters:

• alpha – Diagonal-entry coefficient α

• beta – Off-diagonal-entry coefficient β

• dim – Matrix dimension

Returns:

dim × dim tridiagonal matrix with α on the main diagonal and β on the off-diagonals

template<typename Ty>
DenseMatrix<Ty> Get_U_plus(size_t size)

Construct the down-shift matrix U₊ (U₊[i, i-1] = 1, i.e., the sub-diagonal is 1)

Template Parameters:

Ty – Matrix element type

Parameters:

size – Matrix dimension

Returns:

size × size down-shift matrix

template<typename Ty>
DenseMatrix<Ty> Get_U_minus(size_t size)

Construct the up-shift matrix U₋ (U₋[i, i+1] = 1, i.e., the super-diagonal is 1)

Template Parameters:

Ty – Matrix element type

Parameters:

size – Matrix dimension

Returns:

size × size up-shift matrix

struct Block_Encoding_Tridiagonal : public qram_simulator::BaseOperator

#include <block_encoding_tridiagonal.h>

Block encoding operator for the tridiagonal matrix A = αI + βT.

Decomposes A = αI + βU₊ + βU₋ as an LCU: on the 4-qubit ancilla register anc_UA it prepares the amplitude vector prep_state = {√|α|/s, √|β|/s, √|β|/s, √(1-(|α|+2|β|)/s)}, where s = ‖A‖_F = sqrt(N|α|² + 2(N-1)|β|²) is the Frobenius norm (N = 2^n is the main register dimension). The branches respectively perform the identity / +1 shift / -1 shift / annihilation operations, so that the unitary U satisfies the block encoding definition (⟨0|_{anc}⊗I) U (|0|_{anc}⊗I) = (αI + βU₊ + βU₋)/s, i.e., the encoding scale factor is s. When β < 0 an additional conditional reflection is inserted to correct the sign of the shift branches. Supports conditional control (ClassControllable)

Public Functions

ClassControllable Block_Encoding_Tridiagonal(std::string_view main_reg_, std::string_view anc_UA_, double alpha_, double beta_)

Constructor (computes the LCU state preparation amplitudes)

Note

The concrete implementation of the amplitude computation is in block_encoding_tridiagonal.cpp

Parameters:

• main_reg_ – Main register name

• anc_UA_ – Block encoding ancilla register name (4 qubits)

• alpha_ – Diagonal-entry coefficient α

• beta_ – Off-diagonal-entry coefficient β

template<typename Ty>
inline void impl(Ty &state) const

Block encoding circuit implementation (forward)

Flow: split the ancilla register → LCU state preparation → conditional ±1 shift (with an additional reflection to correct the sign when β < 0) → annihilation branch → inverse state preparation and register merging

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

Block encoding circuit implementation (dagger, reverse)

Same circuit composition as impl, but with the execution order of the shift branches and the order of the reflections reversed

Parameters:

state – System state vector

Public Members

double alpha

Diagonal-entry coefficient α

double beta

Off-diagonal-entry coefficient β

std::string main_reg

Main register name.

std::string anc_UA

Block encoding ancilla register name (4 qubits)

std::vector<complex_t> prep_state

LCU state preparation amplitude vector (square roots of the branch coefficients)

struct PlusOneAndOverflow : public qram_simulator::BaseOperator

#include <block_encoding_tridiagonal.h>

Modular shift gate that increments by one and records overflow.

Performs a +1 operation on the main register: when the main register reaches the maximum value 2^n - 1 it wraps around to 0 and flips the overflow bit. This gate corresponds to the action of the shift matrices U₊/U₋ and is the basic building block for constructing the conditional shift branches in the tridiagonal block encoding. Supports conditional control (ClassControllable)

Public Functions

inline PlusOneAndOverflow(std::string_view main_reg_, std::string_view overflow_)

Constructor.

Parameters:

• main_reg_ – Main register name

• overflow_ – Overflow-bit register name

virtual void operator()(std::vector<System> &state) const

Apply the increment-by-one shift operation.

Parameters:

state – System state vector

virtual void dag(std::vector<System> &state) const

Apply the dagger operation (decrement-by-one shift)

Parameters:

state – System state vector

inline virtual void dag(std::vector<System> &state) const

Apply the conjugate transpose (dagger) operation.

Parameters:

state – System state vector

Throws:

Throws – a not-implemented exception by default

inline virtual void dag(SparseState &state) const

Apply dagger to a SparseState.

Parameters:

state – Sparse state

Public Members

ClassControllable std::string main_reg

Name of the main register to be shifted.

std::string overflow

Overflow-bit register name (flipped when wrap-around occurs)

QRAM-Based Block Encoding (SparQ_Algorithm/include/BlockEncoding/block_encoding_via_QRAM.h)

QRAM-based block encoding of arbitrary matrices.

Constructs the block encoding of a matrix A via the U_L / U_R quantum walk decomposition: U_L|col⟩|0⟩ = |col⟩|a_col⟩ prepares the normalized column vector indexed by the column index, U_R|0⟩ = |A⟩ = Σ_i ‖a_i‖|i⟩ prepares the column-norm distribution, and their combination U_A = SWAP(row, col) · U_R†(col) · U_L(row, col) satisfies ⟨i|_col⟨0|_row U_A |j⟩_col|0⟩_row = A_ij, with the data provided by the QRAM hierarchy tree nodes. Used together with make_qram.h (data quantization and tree construction)

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

namespace block_encoding

namespace block_encoding_via_QRAM

struct Block_Encoding_via_QRAM : public qram_simulator::BaseOperator

#include <block_encoding_via_QRAM.h>

QRAM-based matrix block encoding operator U_A.

Combines U_A = SWAP(row, col) · U_R†(col) · U_L(row, col), which satisfies the block encoding definition U_A|φ⟩_col|0⟩_row = A|φ⟩_col|0⟩_row + |ψ⊥⟩, i.e., ⟨i|_col⟨0|_row U_A |j⟩_col|0⟩_row = A_ij (the encoding scale is determined by the normalization factor stored at the QRAM tree root). Supports conditional control (ClassControllable)

Public Functions

inline ClassControllable Block_Encoding_via_QRAM(qram_qutrit::QRAMCircuit *qram_, std::string_view column_index_, std::string_view row_index_, size_t dsz, size_t rsz)

Constructor.

Parameters:

• qram_ – QRAM circuit pointer

• column_index_ – Column index register name

• row_index_ – Row index register name

• dsz – Data register width

• rsz – Rational register width

template<typename Ty>
inline void impl(Ty &state) const

Block encoding circuit implementation (forward): U_L → U_R† → SWAP.

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

Block encoding circuit implementation (dagger): SWAP → U_R → U_L†

Parameters:

state – System state vector

Public Members

std::string column_index

Column index register name.

std::string row_index

Row index register name.

size_t addr_size

One-sided address register width.

size_t data_size

Data register width (fixed-point quantization bit count)

size_t rational_size

Rational (rotation angle) register width.

qram_qutrit::QRAMCircuit *qram

QRAM circuit pointer (stores the tree structure of matrix A)

struct U_L : public qram_simulator::BaseOperator

#include <block_encoding_via_QRAM.h>

Left-multiplication operator U_L (prepares the normalized column vector indexed by the column index)

Implements U_L|col⟩|0⟩ = |col⟩|a_col⟩ (|a_col⟩ is the normalized quantum state corresponding to column col): iterate over the top addr_size bits of the row address register; each step concatenates the row/column indices into the parent/child addresses of the QRAM tree nodes (addr_child = 2·addr_parent + 1), loads the node values, computes the rotation angle and rotates conditionally while descending layer by layer; the last layer (the leaf layer) instead uses GetRotateAngle_Int_Int with an atan2-type angle to handle signs. Supports conditional control (ClassControllable)

Public Functions

inline ClassControllable U_L(qram_qutrit::QRAMCircuit *qram_, std::string_view row_index_, std::string_view column_index_, size_t dsz, size_t rsz)

Constructor.

Parameters:

• qram_ – QRAM circuit pointer

• row_index_ – Row index register name

• column_index_ – Column index register name

• dsz – Data register width

• rsz – Rational register width

template<typename Ty>
inline void impl(Ty &state) const

U_L circuit implementation (forward)

Bit-by-bit iteration: split off the rotation bit → concatenate the parent/child addresses → QRAM load → conditional rotation → uncompute to restore the addresses; non-final layers use Div_Sqrt_Arccos, the final layer uses GetRotateAngle

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

U_L circuit implementation (dagger, reverse)

Executes the inverse conditional rotations and uncomputations in the address-bit order opposite to impl

Parameters:

state – System state vector

Public Members

std::string row_index

Row index register name.

std::string column_index

Column index register name.

size_t addr_size

One-sided address register width.

size_t data_size

Data register width (fixed-point quantization bit count)

size_t rational_size

Rational (rotation angle) register width.

qram_qutrit::QRAMCircuit *qram

QRAM circuit pointer (stores the tree structure of matrix A)

struct U_R : public qram_simulator::BaseOperator

#include <block_encoding_via_QRAM.h>

Right-multiplication operator U_R (column-norm state preparation)

Implements U_R|0⟩ = |A⟩ = Σ_i ‖a_i‖|i⟩ (a_i is the i-th column of A): iterate over the column address register bit by bit from the most significant to the least significant bit, use the parent/child node values of the QRAM loading tree, compute the rotation angle arccos(√(child/parent)) with Div_Sqrt_Arccos_UInt_UInt and perform a conditional rotation (CondRot_Fixed_Bool), preparing the normalized column-norm superposition state from the tree root downward; after each step the ancilla registers are cleaned up by uncomputing step by step. Supports conditional control (ClassControllable)

Public Functions

inline ClassControllable U_R(qram_qutrit::QRAMCircuit *qram_, std::string_view column_index_, size_t dsz, size_t rsz)

Constructor.

Parameters:

• qram_ – QRAM circuit pointer

• column_index_ – Column index register name

• dsz – Data register width

• rsz – Rational register width

template<typename Ty>
inline void impl(Ty &state) const

U_R circuit implementation (forward)

One iteration per address bit: split off the rotation bit → concatenate the parent/child addresses → QRAM-load the node values → compute the rotation angle and rotate conditionally → uncompute to restore the address and data registers

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

U_R circuit implementation (dagger, reverse)

Executes the inverse conditional rotations and uncomputations in the address-bit order opposite to impl

Parameters:

state – System state vector

Public Members

std::string column_index

Column index register name.

size_t addr_size

Column address register width.

size_t data_size

Data register width (fixed-point quantization bit count)

size_t rational_size

Rational (rotation angle) register width.

qram_qutrit::QRAMCircuit *qram

QRAM circuit pointer (stores the column-norm tree)

QRAM Construction Utilities (SparQ_Algorithm/include/BlockEncoding/make_qram.h)

QRAM data preparation utilities (classical side)

Provides the conversion from floating-point matrices/vectors to QRAM fixed-point two’s-complement data (the scaleAndConvertVector family) as well as the construction of the QRAM hierarchy tree (make_vector_tree): parents of the leaf layer store the sum of squares of their two children’s two’s-complement values, and the remaining internal nodes store the direct sum of their children. The generated tree is used by QRAMCircuit_qutrit for state preparation and block encoding conditional rotations (Div_Sqrt_Arccos / CondRot_Fixed_Bool, see block_encoding_via_QRAM.h)

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

Functions

inline std::vector<double> get_column_flatten(const std::vector<double> &row_vec)

Convert a row-major flattened matrix to column-major flattened form (i.e. transpose the matrix)

Parameters:

row_vec – Data of an n×n square matrix flattened in row-major order

Throws:

Throws – an exception if the input length is not a perfect square

Returns:

The same data flattened in column-major order

inline std::vector<uint64_t> scaleAndConvertVector(const std::vector<double> &input_vec, int exponent, size_t data_size, bool from_matrix = true)

Scale and quantize to fixed-point two’s complement (std::vector version)

Parameters:

• input_vec – Input floating-point data (a flattened matrix or a plain vector)

• exponent – Scaling exponent (each element is first multiplied by 2^exponent)

• data_size – Target fixed-point bit width

• from_matrix – When true the input is treated as a row-major flattened matrix and transposed to column-major first; when false it is treated as a plain vector and quantized directly

Returns:

Unsigned integer vector with the quantized values encoded as data_size-bit two’s complement

inline std::vector<uint64_t> scaleAndConvertVector(const DenseVector<double> &input_vec, int exponent, size_t data_size)

Scale and quantize to fixed-point two’s complement (DenseVector version, no transpose)

Parameters:

• input_vec – Input floating-point vector

• exponent – Scaling exponent (each element is first multiplied by 2^exponent)

• data_size – Target fixed-point bit width

Returns:

Unsigned integer vector with the quantized values encoded as data_size-bit two’s complement

inline std::vector<uint64_t> scaleAndConvertVector(const DenseMatrix<double> &input_vec, int exponent, size_t data_size)

Scale and quantize to fixed-point two’s complement (DenseMatrix version, transposed to column-major first)

Parameters:

• input_vec – Input floating-point square matrix

• exponent – Scaling exponent (each element is first multiplied by 2^exponent)

• data_size – Target fixed-point bit width

Returns:

Unsigned integer vector of two’s-complement-encoded quantized values after column-major flattening

inline std::vector<uint64_t> make_vector_tree(const std::vector<uint64_t> &dist, size_t data_size)

Build the QRAM hierarchy tree bottom-up from the leaf data.

Parameters:

• dist – Leaf-layer data (two’s-complement integers output by scaleAndConvertVector)

• data_size – Fixed-point bit width (the leaf layer uses get_complement to restore the true values)

Returns:

Tree node array flattened in level (breadth-first) order: [top internal nodes, …, leaves, 0], where the parents of the leaf layer store the sum of squares of their two children’s two’s-complement true values (squared norms), the remaining internal nodes store the sum of their children, and a trailing 0 is appended as a placeholder slot

---

中文版 ===

块编码（BlockEncoding/）

三对角矩阵块编码（SparQ_Algorithm/include/BlockEncoding/block_encoding_tridiagonal.h）

Quantum block encoding of tridiagonal matrices.

Implements the block encoding of the symmetric tridiagonal matrix A = αI + βT (T is the shift matrix whose sub- and super-diagonals are all 1). Based on the LCU (linear combination of unitaries) decomposition A = αI + βU₊ + βU₋: after the ancilla register prepares the LCU amplitudes, the conditional shift gates (PlusOneAndOverflow) execute the +1/-1 shift branches, and the final unitary U satisfies (⟨0|_{anc}⊗I) U (|0|_{anc}⊗I) = (αI + βU₊ + βU₋)/‖A‖_F. This block encoding is a core submodule of the tridiagonal version (qda_tridiagonal.h) of the QDA discrete adiabatic solver

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

namespace block_encoding

namespace block_encoding_tridiagonal

Functions

inline DenseMatrix<double> get_block_encoding_tridiagonal(size_t qubit_num, double alpha, double beta)

Extract the encoded block matrix of the tridiagonal block encoding (numerical verification helper)

Parameters:

• qubit_num – Number of qubits n of the main register

• alpha – Diagonal-entry coefficient α

• beta – Off-diagonal-entry coefficient β

Returns:

Real matrix of the encoded block (⟨0|_{anc}⊗I) U (|0|_{anc}⊗I) with dimension 2^n × 2^n; its theoretical value is (αI + βT)/‖αI + βT‖_F

inline DenseMatrix<double> get_tridiagonal_matrix(double alpha, double beta, size_t dim)

Construct the classical tridiagonal matrix αI + βT.

Parameters:

• alpha – Diagonal-entry coefficient α

• beta – Off-diagonal-entry coefficient β

• dim – Matrix dimension

Returns:

dim × dim tridiagonal matrix with α on the main diagonal and β on the off-diagonals

template<typename Ty>
DenseMatrix<Ty> Get_U_plus(size_t size)

Construct the down-shift matrix U₊ (U₊[i, i-1] = 1, i.e., the sub-diagonal is 1)

Template Parameters:

Ty – Matrix element type

Parameters:

size – Matrix dimension

Returns:

size × size down-shift matrix

template<typename Ty>
DenseMatrix<Ty> Get_U_minus(size_t size)

Construct the up-shift matrix U₋ (U₋[i, i+1] = 1, i.e., the super-diagonal is 1)

Template Parameters:

Ty – Matrix element type

Parameters:

size – Matrix dimension

Returns:

size × size up-shift matrix

struct Block_Encoding_Tridiagonal : public qram_simulator::BaseOperator

#include <block_encoding_tridiagonal.h>

Block encoding operator for the tridiagonal matrix A = αI + βT.

Decomposes A = αI + βU₊ + βU₋ as an LCU: on the 4-qubit ancilla register anc_UA it prepares the amplitude vector prep_state = {√|α|/s, √|β|/s, √|β|/s, √(1-(|α|+2|β|)/s)}, where s = ‖A‖_F = sqrt(N|α|² + 2(N-1)|β|²) is the Frobenius norm (N = 2^n is the main register dimension). The branches respectively perform the identity / +1 shift / -1 shift / annihilation operations, so that the unitary U satisfies the block encoding definition (⟨0|_{anc}⊗I) U (|0|_{anc}⊗I) = (αI + βU₊ + βU₋)/s, i.e., the encoding scale factor is s. When β < 0 an additional conditional reflection is inserted to correct the sign of the shift branches. Supports conditional control (ClassControllable)

Public Functions

ClassControllable Block_Encoding_Tridiagonal(std::string_view main_reg_, std::string_view anc_UA_, double alpha_, double beta_)

Constructor (computes the LCU state preparation amplitudes)

Note

The concrete implementation of the amplitude computation is in block_encoding_tridiagonal.cpp

Parameters:

• main_reg_ – Main register name

• anc_UA_ – Block encoding ancilla register name (4 qubits)

• alpha_ – Diagonal-entry coefficient α

• beta_ – Off-diagonal-entry coefficient β

template<typename Ty>
inline void impl(Ty &state) const

Block encoding circuit implementation (forward)

Flow: split the ancilla register → LCU state preparation → conditional ±1 shift (with an additional reflection to correct the sign when β < 0) → annihilation branch → inverse state preparation and register merging

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

Block encoding circuit implementation (dagger, reverse)

Same circuit composition as impl, but with the execution order of the shift branches and the order of the reflections reversed

Parameters:

state – System state vector

Public Members

double alpha

Diagonal-entry coefficient α

double beta

Off-diagonal-entry coefficient β

std::string main_reg

Main register name.

std::string anc_UA

Block encoding ancilla register name (4 qubits)

std::vector<complex_t> prep_state

LCU state preparation amplitude vector (square roots of the branch coefficients)

struct PlusOneAndOverflow : public qram_simulator::BaseOperator

#include <block_encoding_tridiagonal.h>

Modular shift gate that increments by one and records overflow.

Performs a +1 operation on the main register: when the main register reaches the maximum value 2^n - 1 it wraps around to 0 and flips the overflow bit. This gate corresponds to the action of the shift matrices U₊/U₋ and is the basic building block for constructing the conditional shift branches in the tridiagonal block encoding. Supports conditional control (ClassControllable)

Public Functions

inline PlusOneAndOverflow(std::string_view main_reg_, std::string_view overflow_)

Constructor.

Parameters:

• main_reg_ – Main register name

• overflow_ – Overflow-bit register name

virtual void operator()(std::vector<System> &state) const

Apply the increment-by-one shift operation.

Parameters:

state – System state vector

virtual void dag(std::vector<System> &state) const

Apply the dagger operation (decrement-by-one shift)

Parameters:

state – System state vector

inline virtual void dag(std::vector<System> &state) const

Apply the conjugate transpose (dagger) operation.

Parameters:

state – System state vector

Throws:

Throws – a not-implemented exception by default

inline virtual void dag(SparseState &state) const

Apply dagger to a SparseState.

Parameters:

state – Sparse state

Public Members

ClassControllable std::string main_reg

Name of the main register to be shifted.

std::string overflow

Overflow-bit register name (flipped when wrap-around occurs)

基于 QRAM 的块编码（SparQ_Algorithm/include/BlockEncoding/block_encoding_via_QRAM.h）

QRAM-based block encoding of arbitrary matrices.

Constructs the block encoding of a matrix A via the U_L / U_R quantum walk decomposition: U_L|col⟩|0⟩ = |col⟩|a_col⟩ prepares the normalized column vector indexed by the column index, U_R|0⟩ = |A⟩ = Σ_i ‖a_i‖|i⟩ prepares the column-norm distribution, and their combination U_A = SWAP(row, col) · U_R†(col) · U_L(row, col) satisfies ⟨i|_col⟨0|_row U_A |j⟩_col|0⟩_row = A_ij, with the data provided by the QRAM hierarchy tree nodes. Used together with make_qram.h (data quantization and tree construction)

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

namespace block_encoding

namespace block_encoding_via_QRAM

struct Block_Encoding_via_QRAM : public qram_simulator::BaseOperator

#include <block_encoding_via_QRAM.h>

QRAM-based matrix block encoding operator U_A.

Combines U_A = SWAP(row, col) · U_R†(col) · U_L(row, col), which satisfies the block encoding definition U_A|φ⟩_col|0⟩_row = A|φ⟩_col|0⟩_row + |ψ⊥⟩, i.e., ⟨i|_col⟨0|_row U_A |j⟩_col|0⟩_row = A_ij (the encoding scale is determined by the normalization factor stored at the QRAM tree root). Supports conditional control (ClassControllable)

Public Functions

inline ClassControllable Block_Encoding_via_QRAM(qram_qutrit::QRAMCircuit *qram_, std::string_view column_index_, std::string_view row_index_, size_t dsz, size_t rsz)

Constructor.

Parameters:

• qram_ – QRAM circuit pointer

• column_index_ – Column index register name

• row_index_ – Row index register name

• dsz – Data register width

• rsz – Rational register width

template<typename Ty>
inline void impl(Ty &state) const

Block encoding circuit implementation (forward): U_L → U_R† → SWAP.

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

Block encoding circuit implementation (dagger): SWAP → U_R → U_L†

Parameters:

state – System state vector

Public Members

std::string column_index

Column index register name.

std::string row_index

Row index register name.

size_t addr_size

One-sided address register width.

size_t data_size

Data register width (fixed-point quantization bit count)

size_t rational_size

Rational (rotation angle) register width.

qram_qutrit::QRAMCircuit *qram

QRAM circuit pointer (stores the tree structure of matrix A)

struct U_L : public qram_simulator::BaseOperator

#include <block_encoding_via_QRAM.h>

Left-multiplication operator U_L (prepares the normalized column vector indexed by the column index)

Implements U_L|col⟩|0⟩ = |col⟩|a_col⟩ (|a_col⟩ is the normalized quantum state corresponding to column col): iterate over the top addr_size bits of the row address register; each step concatenates the row/column indices into the parent/child addresses of the QRAM tree nodes (addr_child = 2·addr_parent + 1), loads the node values, computes the rotation angle and rotates conditionally while descending layer by layer; the last layer (the leaf layer) instead uses GetRotateAngle_Int_Int with an atan2-type angle to handle signs. Supports conditional control (ClassControllable)

Public Functions

inline ClassControllable U_L(qram_qutrit::QRAMCircuit *qram_, std::string_view row_index_, std::string_view column_index_, size_t dsz, size_t rsz)

Constructor.

Parameters:

• qram_ – QRAM circuit pointer

• row_index_ – Row index register name

• column_index_ – Column index register name

• dsz – Data register width

• rsz – Rational register width

template<typename Ty>
inline void impl(Ty &state) const

U_L circuit implementation (forward)

Bit-by-bit iteration: split off the rotation bit → concatenate the parent/child addresses → QRAM load → conditional rotation → uncompute to restore the addresses; non-final layers use Div_Sqrt_Arccos, the final layer uses GetRotateAngle

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

U_L circuit implementation (dagger, reverse)

Executes the inverse conditional rotations and uncomputations in the address-bit order opposite to impl

Parameters:

state – System state vector

Public Members

std::string row_index

Row index register name.

std::string column_index

Column index register name.

size_t addr_size

One-sided address register width.

size_t data_size

Data register width (fixed-point quantization bit count)

size_t rational_size

Rational (rotation angle) register width.

qram_qutrit::QRAMCircuit *qram

QRAM circuit pointer (stores the tree structure of matrix A)

struct U_R : public qram_simulator::BaseOperator

#include <block_encoding_via_QRAM.h>

Right-multiplication operator U_R (column-norm state preparation)

Implements U_R|0⟩ = |A⟩ = Σ_i ‖a_i‖|i⟩ (a_i is the i-th column of A): iterate over the column address register bit by bit from the most significant to the least significant bit, use the parent/child node values of the QRAM loading tree, compute the rotation angle arccos(√(child/parent)) with Div_Sqrt_Arccos_UInt_UInt and perform a conditional rotation (CondRot_Fixed_Bool), preparing the normalized column-norm superposition state from the tree root downward; after each step the ancilla registers are cleaned up by uncomputing step by step. Supports conditional control (ClassControllable)

Public Functions

inline ClassControllable U_R(qram_qutrit::QRAMCircuit *qram_, std::string_view column_index_, size_t dsz, size_t rsz)

Constructor.

Parameters:

• qram_ – QRAM circuit pointer

• column_index_ – Column index register name

• dsz – Data register width

• rsz – Rational register width

template<typename Ty>
inline void impl(Ty &state) const

U_R circuit implementation (forward)

One iteration per address bit: split off the rotation bit → concatenate the parent/child addresses → QRAM-load the node values → compute the rotation angle and rotate conditionally → uncompute to restore the address and data registers

Parameters:

state – System state vector

template<typename Ty>
inline void impl_dag(Ty &state) const

U_R circuit implementation (dagger, reverse)

Executes the inverse conditional rotations and uncomputations in the address-bit order opposite to impl

Parameters:

state – System state vector

Public Members

std::string column_index

Column index register name.

size_t addr_size

Column address register width.

size_t data_size

Data register width (fixed-point quantization bit count)

size_t rational_size

Rational (rotation angle) register width.

qram_qutrit::QRAMCircuit *qram

QRAM circuit pointer (stores the column-norm tree)

QRAM 构造工具（SparQ_Algorithm/include/BlockEncoding/make_qram.h）

QRAM data preparation utilities (classical side)

Provides the conversion from floating-point matrices/vectors to QRAM fixed-point two’s-complement data (the scaleAndConvertVector family) as well as the construction of the QRAM hierarchy tree (make_vector_tree): parents of the leaf layer store the sum of squares of their two children’s two’s-complement values, and the remaining internal nodes store the direct sum of their children. The generated tree is used by QRAMCircuit_qutrit for state preparation and block encoding conditional rotations (Div_Sqrt_Arccos / CondRot_Fixed_Bool, see block_encoding_via_QRAM.h)

namespace qram_simulator

QRAM sparse state simulator namespace.

Contains all classes, functions, and data structures related to quantum computing simulation

Functions

inline std::vector<double> get_column_flatten(const std::vector<double> &row_vec)

Convert a row-major flattened matrix to column-major flattened form (i.e. transpose the matrix)

Parameters:

row_vec – Data of an n×n square matrix flattened in row-major order

Throws:

Throws – an exception if the input length is not a perfect square

Returns:

The same data flattened in column-major order

inline std::vector<uint64_t> scaleAndConvertVector(const std::vector<double> &input_vec, int exponent, size_t data_size, bool from_matrix = true)

Scale and quantize to fixed-point two’s complement (std::vector version)

Parameters:

• input_vec – Input floating-point data (a flattened matrix or a plain vector)

• exponent – Scaling exponent (each element is first multiplied by 2^exponent)

• data_size – Target fixed-point bit width

• from_matrix – When true the input is treated as a row-major flattened matrix and transposed to column-major first; when false it is treated as a plain vector and quantized directly

Returns:

Unsigned integer vector with the quantized values encoded as data_size-bit two’s complement

inline std::vector<uint64_t> scaleAndConvertVector(const DenseVector<double> &input_vec, int exponent, size_t data_size)

Scale and quantize to fixed-point two’s complement (DenseVector version, no transpose)

Parameters:

• input_vec – Input floating-point vector

• exponent – Scaling exponent (each element is first multiplied by 2^exponent)

• data_size – Target fixed-point bit width

Returns:

Unsigned integer vector with the quantized values encoded as data_size-bit two’s complement

inline std::vector<uint64_t> scaleAndConvertVector(const DenseMatrix<double> &input_vec, int exponent, size_t data_size)

Scale and quantize to fixed-point two’s complement (DenseMatrix version, transposed to column-major first)

Parameters:

• input_vec – Input floating-point square matrix

• exponent – Scaling exponent (each element is first multiplied by 2^exponent)

• data_size – Target fixed-point bit width

Returns:

Unsigned integer vector of two’s-complement-encoded quantized values after column-major flattening

inline std::vector<uint64_t> make_vector_tree(const std::vector<uint64_t> &dist, size_t data_size)

Build the QRAM hierarchy tree bottom-up from the leaf data.

Parameters:

• dist – Leaf-layer data (two’s-complement integers output by scaleAndConvertVector)

• data_size – Fixed-point bit width (the leaf layer uses get_complement to restore the true values)

Returns:

Tree node array flattened in level (breadth-first) order: [top internal nodes, …, leaves, 0], where the parents of the leaf layer store the sum of squares of their two children’s two’s-complement true values (squared norms), the remaining internal nodes store the sum of their children, and a trailing 0 is appended as a placeholder slot