Algorithm structure protocols¶

oracq.algorithms.input_model.interfaces

Python structural protocols shared by the algorithm library; applications may keep defining protocols in their own modules.

class oracq.algorithms.input_model.interfaces.StatePreparationProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Requires a state_preparation() method; anything satisfying it can serve as an algorithm’s initial-state input.

state_preparation()[source]¶

Return the StatePreparation access view corresponding to this input.

Returns:: View that prepares the target state on this input’s zero-input registers.
Return type:: StatePreparation

class oracq.algorithms.input_model.interfaces.UnitaryProtocol(*args, **kwargs)[source]¶

Bases: StatePreparationProtocol, Protocol

Adds the full unitary interface unitary() on top of the state-preparation protocol.

unitary()[source]¶

Return the unitary Operation on the full register space.

Returns:: Unitary operation acting on all registers of this input.
Return type:: Operation

class oracq.algorithms.input_model.interfaces.BlockEncodingProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Requires a block_encoding() method; anything satisfying it can serve as a block-encoding input.

block_encoding()[source]¶

Return the BlockEncoding access view corresponding to this input.

Returns:: Access view encoding this input as a normalized sub-block of a unitary.
Return type:: BlockEncoding

class oracq.algorithms.input_model.interfaces.CKSSparseProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Requires a sparse_access() method; anything satisfying it can serve as a CKS sparse-matrix input.

sparse_access()[source]¶

Return the SparseAccess composed of the CKS location and entry operations.

Returns:: Sparse access view composed of a location oracle and an entry oracle.
Return type:: SparseAccess

class oracq.algorithms.input_model.interfaces.XorDatabaseProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Requires a xor_database() method; anything satisfying it can serve as an XOR database input.

xor_database()[source]¶

Return the XorDatabase access view corresponding to this input.

Returns:: Database access view that answers queries by XOR.
Return type:: XorDatabase

class oracq.algorithms.input_model.interfaces.StateOracleProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Requires a state_oracle() method; anything satisfying it can serve as an output-state oracle.

state_oracle()[source]¶

Return the StateOracle carrying a success signal.

Returns:: Oracle that marks the success subspace within the output state.
Return type:: StateOracle

oracq.algorithms.input_model.interfaces.as_state_preparation(value)[source]¶

Convert a protocol-satisfying input into a StatePreparation.

Parameters:: value – Object satisfying StatePreparationProtocol.
Returns:: The concrete view obtained by calling state_preparation().
Return type:: StatePreparation
Raises:: ContractError – Reported as INPUT_PROTOCOL when the interface is missing; as INPUT_TYPE when the return value is not a StatePreparation.

oracq.algorithms.input_model.interfaces.checked_state_preparation(value, *, adjoint=False, controlled=False, path='preparation')[source]¶

Obtain a zero-input, clean-work preparation; the calling algorithm selects the transformation capabilities it needs.

Parameters:

value – Input object satisfying StatePreparationProtocol.
adjoint – Whether the preparation must offer a Hermitian-adjoint version.
controlled – Whether the preparation must support a controlled version.
path – Path name of this input in the contract report.

Returns:

Preparation view that passed the zero-input and clean-work checks.

Return type:

StatePreparation

oracq.algorithms.input_model.interfaces.as_block_encoding(value)[source]¶

Convert a protocol-satisfying input into a BlockEncoding.

Parameters:: value – Object satisfying BlockEncodingProtocol.
Returns:: The concrete view obtained by calling block_encoding().
Return type:: BlockEncoding
Raises:: ContractError – Reported as INPUT_PROTOCOL when the interface is missing; as INPUT_TYPE when the return value is not a BlockEncoding.

oracq.algorithms.input_model.interfaces.as_sparse_access(value)[source]¶

Convert a protocol-satisfying input into a SparseAccess.

Parameters:: value – Object satisfying CKSSparseProtocol.
Returns:: The concrete view obtained by calling sparse_access().
Return type:: SparseAccess
Raises:: ContractError – Reported as INPUT_PROTOCOL when the interface is missing; as INPUT_TYPE when the return value is not a SparseAccess.

oracq.algorithms.input_model.interfaces.as_qlss_matrix(value)[source]¶

Convert a matrix input into a BlockEncoding or SparseAccess according to the available interface.

When BlockEncodingProtocol is satisfied the block-encoding view is returned preferentially; otherwise the sparse access view is taken per CKSSparseProtocol.

Parameters:: value – Matrix input object.
Returns:: A BlockEncoding when the block-encoding protocol is satisfied, otherwise a SparseAccess.
Raises:: ContractError – Neither protocol is satisfied, or the obtained return value has the wrong type.

oracq.algorithms.input_model.interfaces.operator_state_contract(name, *, matrix='generator', state='initial', composable=True)[source]¶

Requirements of the current BE-type evolution algorithms; other algorithms may define entirely different contracts.

Parameters:

name – Contract name, used in reports and diagnostics.
matrix – Path name of the block-encoding matrix input in the contract.
state – Path name of the initial-state preparation input in the contract.
composable – Whether the initial state requires adjoint and controlled capabilities for use by composable algorithms.

Returns:

Contract requiring the matrix to be a block encoding with adjoint and controlled capabilities, the initial state to be a zero-input and clean-work preparation, and constraining both to equal register widths.

Return type:

AlgorithmContract