Sparse-access adapters

oracq.algorithms.input_model.sparse

Sparse position and entry access, plus explicit adaptation of numeric words to block encodings.

oracq.algorithms.input_model.sparse.reversible_lookup(inputs, outputs, database, *, name=None)

Adapt the address/data interface of an XorDatabase to named input/output register groups.

The input registers are fused, in declaration order, into an address view and the output registers into a data view; the query semantics remain the XOR database’s data ^= memory[address].

Parameters:

• inputs – Mapping from names to bit widths; the total width must equal database.address_width.

• outputs – Mapping from names to bit widths; the total width must equal database.data_width.

• database – The XOR database being adapted.

• name – Optional module name; generated from content when omitted.

Returns:

Registers are the union of inputs and outputs; the paradigm is reversible_function.

Return type:

Operation

Raises:

ValidationError – The input/output total widths do not match the database, or names conflict between the two sides.

oracq.algorithms.input_model.sparse.word_rotation(value_width, *, scale=None, name=None)

Reversible transduction that converts the integer value of a numeric word linearly into an Ry angle on the amplitude bit.

With per-bit controlled superposition the total rotation angle is scale * value (value taken as an unsigned integer); the default scale = 2*pi / 2**value_width makes the whole value range sweep exactly one full turn.

Parameters:

• value_width – Bit width of the value register.

• scale – Rotation angle per unit of integer value; defaults to 2*pi / 2**value_width.

• name – Optional module name; generated from content when omitted.

Returns:

Registers are value and the single-bit amplitude; the paradigm is reversible_function, with module attribute angle_scale recording the scale used.

Return type:

Operation

oracq.algorithms.input_model.sparse.sparse_block_encoding(access, transducer=None, *, alpha=None)

Historical candidate kept only for the old gallery description; the official sparse adapter is real_symmetric_sparse_encoding.

Parameters:

• access – CKS sparse access bundle.

• transducer – Value-to-amplitude transduction operation; defaults to an open declaration.

• alpha – Explicitly overridden normalization constant; defaults to the sparsity.

Returns:

Legacy transduction construction with an unspecified contract.

Return type:

BlockEncoding

oracq.algorithms.input_model.sparse.batch_lookup(database, count)

Batch circuit issuing multiple concurrent queries to the same XOR database.

Parameters:

• database – The XOR database.

• count – Number of query lanes.

Returns:

Registers are address{i} and data{i} for i from 0 to count-1, with bit widths equal to the database’s address/data widths respectively, invoking the same database operation once per lane.

Return type:

Operation

oracq.algorithms.input_model.sparse.compare_words(width, kind='eq')

Equality or less-than comparison network for two word-width unsigned integers.

Parameters:

• width – Bit width of each input word.

• kind – "eq" builds an equality predicate, "lt" an unsigned less-than predicate.

Returns:

Input registers a and b, output single-bit flag set to 1 when the comparison holds. The Boolean network is compiled into a reversible quantum operation via compute/copy/uncompute, with the private bank zero in and zero out. Results are cached and reused by (width, kind).

Return type:

Operation

oracq.algorithms.input_model.sparse.value_transposition(width)

Swap the two bit patterns a and b within index; a and b are preserved, suitable for quantum addresses.

Parameters:

width – Bit width of each of the index and a, b registers.

Returns:

Operation that exchanges the basis states of index equal to a or b while leaving all other basis states unchanged.

Return type:

Operation

oracq.algorithms.input_model.sparse.prefix_state(width, count)

Prepare a uniform superposition over the first count basis states.

Parameters:

• width – Target register bit width.

• count – Number of basis states covered by the superposition, in 1..2**width.

Returns:

Zero-input preparation on a single target register whose support is |0> through |count-1> with equal amplitudes.

Return type:

Operation

Raises:

ValidationError – count is outside the 1..2**width range.

oracq.algorithms.input_model.sparse.magnitude_rotation(fmt, amax)

Small plain implementation for numeric words; above 12 bits an explicit to-be-bound transducer is kept.

Parameters:

• fmt – Fixed-point format of entry values.

• amax – Upper bound on entry magnitudes, a positive finite real number.

Returns:

Controlled Ry transduction with amplitude sqrt(|value|/amax); for formats wider than 12 bits an open declaration awaiting binding is returned.

Return type:

Operation

oracq.algorithms.input_model.sparse.real_symmetric_sparse_encoding(access, fmt, amax, *, diagonal_nonnegative=False, rotation=None)

CKS-style T†ST: real Hermitian with non-negative diagonal; swaps the coordinates and the failure flag between the two sides.

Parameters:

• access – CKS sparse access bundle.

• fmt – Fixed-point format of entry values; the bit width must match the access bundle’s value width.

• amax – Upper bound on entry magnitudes, a positive finite real number.

• diagonal_nonnegative – Must be True; only matrices with a non-negative diagonal are currently supported.

• rotation – Optional amplitude transduction operation; defaults to one generated by magnitude_rotation.

Returns:

Block encoding of a T†ST-type real symmetric sparse matrix.

Return type:

BlockEncoding

oracq.algorithms.input_model.sparse.chebyshev_block(a, degree)

Chebyshev walk power: the zero-signal block realizes the degree-th Chebyshev polynomial of the scaled matrix.

The degree is kept as a Repeat, each step alternating between a positive reflection about the signal zero state and an invocation of a; the encoded matrix enters the polynomial scaled by a.alpha.

Parameters:

• a – A BlockEncoding whose module attributes explicitly declare self_adjoint_extension.

• degree – Chebyshev degree, a non-negative integer.

Returns:

be_alpha is 1.0, argument_scale records a.alpha, and the zero-signal block is T_degree(A / a.alpha).

Return type:

BlockEncoding

Raises:

ValidationError – The input block encoding lacks the self-adjoint unitary extension declaration, or the degree is negative.