Quantum building blocks of QCNNs

oracq.algorithms.qml.qcnn_layer

Quantum building blocks of the QCNN (arXiv:1911.01117 §5.1).

qcnn_vector_prep implements the QRAM row/column loading of Eq. (13)-(15): the index register p selects a row and the target register prepares the normalized row vector state |A_p⟩. Rotation angles and signs are stored as runtime QRAM banks — an angle tree (RY half-angle convention, addressing (1<<depth)-1+prefix) plus sign kickback, a mechanism consistent with the QFVM sign residual tree; swapping data only swaps the memory tables and leaves the circuit unchanged.

qcnn_inner_product implements Eq. (16)-(19): p and q are put into uniform superposition and a Hadamard test on flag encodes the inner product into an amplitude. The probability of measuring (p, q, flag) satisfies P0(p,q) = (1+<A_p|F_q>)/(2 H’W’D’) (Eq. 20).

The semantic validation of both building blocks against a classical mirror with quantized angles lives in tests/core/test_qcnn.py.

oracq.algorithms.qml.qcnn_layer.vector_angle_tables(rows, angle_width)

Compile a group of equal-length row vectors into an angle-tree bank and a sign bank (runtime memory tables).

Angles are derived from the squared partial sums under the RY half-angle convention: the RY parameter is 2*atan2(sqrt(S_right), sqrt(S_left)); tree nodes are addressed (1<<depth)-1+prefix (matching the addressing of qram_state_prep). Returns (angles, signs): angles is keyed by fuse(index, node) and signs by fuse(index, leaf).

Parameters:

• rows – Sequence of equal-length nonzero-norm row vectors; each vector length must be a power of two.

• angle_width – Quantization bit width of an angle word; angles are quantized in units of 2π/2^angle_width radians.

Returns:

Runtime memory tables of the angle-tree bank and the sign bank.

Return type:

tuple[dict[int, int], dict[int, int]]

oracq.algorithms.qml.qcnn_layer.qcnn_vector_prep(count, vector_width, angle_width, *, name=None)

Eq. (15): write the normalized vector state into the target register according to the index (QRAM data driven).

Registers: index (log2 count bits), target (vector_width bits), and work (angle_width bits). Resources: angles (address fuse(index, node), data width angle_width) and signs (address fuse(index, leaf), data width 1). Angle words are synthesized bit by bit into controlled RY rotations: 2*pi*2^k/2^angle_width. Signs are written via Z kickback and only a branch phase remains after the query is uncomputed. Behavior for index >= count is undefined; the caller must ensure the superposition only covers valid rows.

Parameters:

• count – Number of vectors, must be a power of two; determines the index register width.

• vector_width – Quantum bit width of a single vector (the vector length is a power of two).

• angle_width – Word width of the angle bank; rotations are synthesized from it by bit-weighted summation.

• name – Name of the generated module; generated from the parameters by default.

Returns:

A preparation operation that selects a row by index and writes the normalized vector state into target.

Return type:

Operation

oracq.algorithms.qml.qcnn_layer.qcnn_inner_product(row_count, column_count, vector_width, angle_width, *, name=None)

Eq. (16)-(19): Hadamard-type inner product circuit.

Registers: p and q (row/column indices), flag (1 bit), vec (vector_width bits), and work (angle_width + 1 bits). After p and q are put into uniform superposition, the flag=0 branch loads a row vector and the flag=1 branch loads a column vector; the final Hadamard encodes (1+<A_p|F_q>)/2 into the flag=0 amplitude. Resources: one angle and sign bank set each for rows and columns (resource name prefixes row and col).

Parameters:

• row_count – Number of row vectors, must be a power of two.

• column_count – Number of column vectors, must be a power of two.

• vector_width – Quantum bit width of the row/column vectors.

• angle_width – Word width of the angle bank, matching the preparation operation.

• name – Name of the generated module; generated from the parameters by default.

Returns:

An inner product estimation operation that encodes (1+<A_p|F_q>)/2 into the flag amplitude.

Return type:

Operation

oracq.algorithms.qml.qcnn_layer.quantized_prepared_state(vector, angle_width)

Angle-quantization mirror: the (quantized) normalized vector prepared from a row/column.

Consistent with the circuit semantics: layer-by-layer rotation, each layer’s angle synthesized bit by bit from the quantized angle word in the bank; signs applied per the sign bank. Returns a list of reals.

Parameters:

• vector – Real vector to prepare, of power-of-two length and nonzero norm.

• angle_width – Quantization bit width of an angle word, matching the circuit bank.

Returns:

The quantized normalized vector matching the circuit output.

Return type:

list[float]

oracq.algorithms.qml.qcnn_layer.qcnn_sampled_layer(x, kernel, spec, *, samples, eta, seed=0)

Sampling driver for Algorithm 1 of the paper (small scale, end to end).

The quantum semantics split into two layers: row/column preparation and the Hadamard inner product are already validated by circuits (qcnn_inner_product, Eq. 16-20); conditional rotation, amplitude amplification, and l_inf tomography (Eq. 28-38) are modeled here by their exact distributions — the sampling probability is f(Y_pq)^2/sum f^2 (Eq. 34), each sample yields the triple (p, q, f(Y_pq)), and pixels below eta are treated as unsampled and set to zero (Eq. 36). Sampled values are mapped into pooling regions per Eq. 39 and turned into the output tensor through the QRAM online overwrite rule (max keeps the high value / average spreads it). Returns (pooled_rows, stats).

Parameters:

• x – Input tensor data stored flat in row-major order.

• kernel – Flat sequence of convolution kernel coefficients.

• spec – Convolution layer specification, determining the unrolling, the activation cap, and the pooling kind.

• samples – Number of samples, a positive integer.

• eta – Pixel retention threshold; sampled values below it are treated as unsampled and set to zero.

• seed – Random number generator seed.

Returns:

The pooled output matrix and sampling statistics (sampled/kept counts).

Return type:

tuple[list[list[float]], dict[str, int]]