PREPARE-SELECT decomposition¶

oracq.algorithms.common.prepare_select

Standard PREPARE–SELECT decomposition of an LCU (Low & Chuang 2019; Babbush et al. 2018 alias sampling).

oracq.algorithms.common.prepare_select.abstract_prepare(coefficients, *, work_width=0, name=None)[source]¶

Open declaration of PREPARE: the coefficients go into declaration attributes, the body is empty, and bind defers the implementation.

work_width must match the work width of the implementation bound later, 0 for the gate variant and the selector bit width plus the angle bit width for the QRAM variant, consistently with the usage of abstract_state_prep in the catalog.

Parameters:

coefficients – LCU complex coefficient sequence, with at least two finite values, not all zero.
work_width – Bit width of the work register, in 0..64; must match the work width of the implementation bound later.
name – Declaration module name; generated automatically from the coefficients and width when omitted.

Returns:

State preparation handle wrapping the open PREPARE declaration module.

Return type:

StatePreparation

oracq.algorithms.common.prepare_select.gate_prepare(coefficients, *, name=None)[source]¶

Gate-level PREPARE: a multiplexed Ry with amplitudes proportional to √|c_i|; coefficient phases enter SELECT following the repository convention.

Parameters:

coefficients – LCU complex coefficient sequence, with at least two finite values, not all zero.
name – Name of the generated state preparation module; generated automatically from the coefficients when omitted.

Returns:

Handle of the gate-level state preparation operation.

Return type:

StatePreparation

class oracq.algorithms.common.prepare_select.QramPreparation(preparation, memory)[source]¶

Bases: object

QRAM-variant PREPARE handle; the angle table is provided in memory and never enters the IR.

preparation¶

memory¶

state_preparation()[source]¶

Return the StatePreparation operation wrapped inside the handle.

Returns:: The state preparation operation wrapped inside the handle.
Return type:: StatePreparation

oracq.algorithms.common.prepare_select.qram_prepare(coefficients, *, angle_width=8)[source]¶

QRAM-resource PREPARE: the rotation angle table is bound by the caller as QRAM data.

Parameters:

coefficients – LCU complex coefficient sequence, with at least two finite values, not all zero.
angle_width – Quantization bit width of the rotation angles, in 2..32.

Returns:

Handle holding the PREPARE operation and the default angle table QRAM data.

Return type:

QramPreparation

class oracq.algorithms.common.prepare_select.AliasTable(probabilities, keep, alt, quantized, precision, table)[source]¶

Bases: object

Classical preprocessing result of Babbush et al. alias sampling; words are packed as keep | (alt << precision).

probabilities¶

keep¶

alt¶

quantized¶

precision¶

table¶

distribution()[source]¶

Classical sampling distribution under quantized keep and uniform drawing.

Returns:: Sampling probability of each slot, with length equal to the slot count and total sum one.
Return type:: tuple[float, …]

oracq.algorithms.common.prepare_select.alias_table(coefficients, *, precision=8)[source]¶

Vose alias preprocessing: padded to 2^selector, then split into keep and alt by the mean; zero-probability slots also work.

Parameters:

coefficients – LCU complex coefficient sequence, with at least two finite values, not all zero.
precision – Quantization bit width of the keep probabilities, in 2..32; its sum with the selector bit width must not exceed 64.

Returns:

Preprocessing result holding the probabilities, the keep and alt tables, the quantized words and the packed data table.

Return type:

AliasTable

class oracq.algorithms.common.prepare_select.AliasPreparation(preparation, table, memory)[source]¶

Bases: object

Alias-sampling PREPARE handle; table is the classical table and memory is the data of the default QRAM binding.

preparation¶

table¶

memory¶

state_preparation()[source]¶

Return the StatePreparation operation wrapped inside the handle.

Returns:: The state preparation operation wrapped inside the handle.
Return type:: StatePreparation

oracq.algorithms.common.prepare_select.alias_prepare(coefficients, *, precision=8, database=None)[source]¶

Babbush et al. alias-sampling PREPARE: uniform state plus keep and alt loading, a comparator and a controlled swap.

The data table is injected through the XorDatabase interface, by default the QRAM resource but a gate_database also works, and is not embedded in the IR. The data and comparison bits in work entangle with the selector, forming the purification junk of Σ√p_i|i>|junk_i>; the (0,0) block of the block encoding is unaffected by inner products over the junk, and the junk is cleaned by the adjoint of PREPARE. keep is quantized by rounding down to precision bits, with total variation from the exact distribution at most 2^selector·2^-precision.

Parameters:

coefficients – LCU complex coefficient sequence, with at least two finite values, not all zero.
precision – Quantization bit width of the keep probabilities, in 2..32.
database – XorDatabase handle carrying the keep alt packed data table; defaults to the QRAM resource, whose address bit width must equal the selector bit width and whose data bit width equals precision plus the selector bit width.

Returns:

Handle holding the PREPARE operation, the classical alias table and the default QRAM data.

Return type:

AliasPreparation

oracq.algorithms.common.prepare_select.select_pauli(terms)[source]¶

SELECT: when selector equals i, apply the i-th Pauli word to target, and also apply the coefficient phase.

The control condition is expressed with the RIR Control primitive on the binary value of the selector; when unary iteration is needed, the backend lowers the multi-bit control, and the generation stage does not expand it.

Parameters:: terms – Sequence of, coefficient and Pauli word, pairs or a PauliHamiltonian; at least two terms, whose Pauli words contain only I/X/Y/Z and have equal widths.
Returns:: SELECT operation applying the Pauli word and coefficient phase corresponding to the selector value.
Return type:: Operation

oracq.algorithms.common.prepare_select.lcu_prepare_select(terms, *, prepare=None)[source]¶

Standard PREPARE–SELECT block encoding: (PREPARE†⊗I)·SELECT·(PREPARE⊗I).

The low selector_width bits of signal are the selector and the high bits are the work of PREPARE, the purification junk for the alias variant; prepare defaults to gate_prepare, and an abstract, qram or alias handle also works. A single term degenerates to scale. The result can be fed directly to transforms.qubitization_walk.

Parameters:

terms – Sequence of, coefficient and Pauli word, pairs or a PauliHamiltonian; the Pauli words contain only I/X/Y/Z and have equal widths.
prepare – PREPARE handle, defaulting to gate_prepare; it must satisfy the zero_input contract and its target width must equal the selector bit width.

Returns:

(PREPARE†⊗I)·SELECT·(PREPARE⊗I) block encoding with scale equal to the l1 norm of the coefficients.

Return type:

BlockEncoding