Algorithm contracts and reports

oracq.algorithms.input_model.contracts

Checkable input contracts for the generation stage; structure/capabilities and mathematical truth are handled separately.

class oracq.algorithms.input_model.contracts.OracleCapabilities(adjoint, controlled)[source]

Bases: object

Adjoint and controlled invocation capabilities supported by an oracle; values are derived by conservative conjunction over the dependency graph.

Variables:

  • adjoint (bool) – Whether adjoint invocation is supported.

  • controlled (bool) – Whether controlled invocation is supported.

adjoint
controlled
class oracq.algorithms.input_model.contracts.OracleSpec(type, main_qubit, anc_qubit, capabilities, implementation, registers=(), resources=(), alpha=None, parameters=(), components=())[source]

Bases: object

Snapshot read from the actual operation; CKS is a collection of operations with no unified total anc width.

type
main_qubit
anc_qubit
capabilities
implementation
registers = ()
resources = ()
alpha = None
parameters = ()
components = ()
to_dict()[source]

Convert the snapshot into a JSON-storable plain dictionary.

Returns:

Nested plain dictionary with fields of the same names.

Return type:

dict[str, object]

class oracq.algorithms.input_model.contracts.OracleView[source]

Bases: object

Wrapper classes share read-only queries; widths always follow the RIR register signature.

Host view classes must declare the wrapped operation and the oracle_kind class marker.

operation
oracle_kind
property spec

Current OracleSpec snapshot of this view; re-derived on each access.

describe()[source]

Derive the OracleSpec of this view from the RIR module signature, attributes, and dependency graph.

Returns:

The description snapshot of this view.

Return type:

OracleSpec

property type

Descriptive paradigm role name such as block_encoding; not used as a unique type or dispatch basis.

property main_qubit

Number of bits of the main register (target/address/column); None when it cannot be recognized.

property anc_qubit

Number of bits of the public auxiliary register (signal/work); None when the operation collection has no unified width.

property capabilities

Effective invocation capabilities derived from the whole dependency graph.

class oracq.algorithms.input_model.contracts.ContractIssue(code, path, expected, actual, message)[source]

Bases: object

A concrete issue found by one contract check.

Variables:

  • code (str) – Issue category code, e.g. INPUT_PROTOCOL, INPUT_WIDTH.

  • path (str) – Input path where the issue is located, e.g. protocol.input.field.

  • expected (object) – The value expected by the contract.

  • actual (object) – The value actually received.

  • message (str) – User-facing description of the issue.

code
path
expected
actual
message
exception oracq.algorithms.input_model.contracts.ContractError(issues)[source]

Bases: ValidationError

Exception that raises all discovered contract issues at once; a ValidationError subclass.

Parameters:

issues – Iterable of ContractIssue objects joined as code path: message.

Variables:

issues – Immutable tuple of structured issues.

issues
oracq.algorithms.input_model.contracts.fail(code, path, expected, actual, message)[source]

Raise a ContractError immediately with a single issue.

Parameters:

  • code – Issue category code.

  • path – Input path where the issue is located.

  • expected – The value expected by the contract.

  • actual – The value actually received.

  • message – User-facing description of the issue.

Returns:

Never returns normally, always exits by raising.

Return type:

NoReturn

Raises:

ContractError – Always raised, carrying only this one issue.

oracq.algorithms.input_model.contracts.require_instance(value, cls, path)[source]

Require value to be an instance of cls, otherwise raise ContractError.

Parameters:

  • value – The value to check.

  • cls – The expected type.

  • path – Input path used when reporting the issue.

Returns:

The value itself once the instance check passes, narrowed to cls.

Return type:

_T

Raises:

ContractError – Reported as INPUT_TYPE when the instance check fails.

oracq.algorithms.input_model.contracts.finite_real(value, path, *, minimum=None, strict=False)[source]

Require value to be a finite real number with an optional lower bound; bool is not accepted.

Parameters:

  • value – The numeric value to check.

  • path – Input path used when reporting the issue.

  • minimum – The minimum value allowed; when omitted no lower bound is checked.

  • strict – When True, require strictly greater than minimum; otherwise equality is allowed.

Returns:

The value itself once the check passes, narrowed to a finite real number.

Return type:

int | float

Raises:

ContractError – Reported as CONFIG_VALUE when the value is not a finite real number or is below the bound.

oracq.algorithms.input_model.contracts.positive_integer(value, path, *, minimum=1, maximum=None)[source]

Require value to be an integer within the range; bool is not accepted.

Parameters:

  • value – The integer to check.

  • path – Input path used when reporting the issue.

  • minimum – The minimum value allowed, default 1.

  • maximum – The maximum value allowed; when omitted no upper bound is checked.

Returns:

The value itself once the check passes, narrowed to int.

Return type:

int

Raises:

ContractError – Reported as CONFIG_VALUE when the value is not an integer or is out of range.

oracq.algorithms.input_model.contracts.validate_signature(operation, fields, path)[source]

Validate that the public registers of the operation are exactly the agreed bits register set.

Parameters:

  • operation – The Operation to check.

  • fields – The agreed set of register names.

  • path – Input path used when reporting the issue.

Raises:

  • ContractError – Raised when the input is not an Operation, when the

  • register names disagree with fields, or when a non-bits –

  • register exists. –

  • ValidationError – Passed through when program merging validation fails for operation.

oracq.algorithms.input_model.contracts.describe_oracle(value)[source]

Obtain the OracleSpec description snapshot of an arbitrary input object.

An Operation is derived directly from module attributes and the dependency graph; an object with a callable describe method has that method invoked and must return an OracleSpec; any other host object only reports the type name and optional main_qubit/anc_qubit attributes, without consulting any global type table.

Parameters:

value – An Operation, an object implementing describe, or any host object.

Returns:

The read-only description snapshot of the input.

Return type:

OracleSpec

Raises:

  • ContractError – Reported as INPUT_TYPE when the describe return

  • value is not an OracleSpec. –

  • ValidationError – Passed through when program merging validation fails in the Operation branch.

oracq.algorithms.input_model.contracts.requires(value, protocol, *, path='input')[source]

Algorithm-side structural check; the protocol is defined by the caller, and no global type table is consulted.

Parameters:

  • value – The input value to check.

  • protocol – The protocol class required to be satisfied.

  • path – Input path used when reporting the issue, input by default.

Returns:

The value itself once the protocol check passes.

Return type:

_T

class oracq.algorithms.input_model.contracts.InputRequirement(name, protocols, adapter=None, main_qubit=None, anc_qubit=None, alpha=None, adjoint=False, controlled=False, zero_input=False, clean_work=False)[source]

Bases: object

Declaration of a protocol’s requirement on a single named input.

protocols lists the acceptable protocol classes (satisfying any one is enough); the optional adapter converts the raw value into a concrete view before checking layout, capabilities, and promises.

Variables:

  • name (str) – Input name, unique within the owning AlgorithmContract.

  • protocols (tuple[type, ...]) – Tuple of acceptable protocol classes.

  • adapter (collections.abc.Callable[[...], object] | None) – Optional adapter function such as as_block_encoding; when omitted the raw value is checked directly.

  • main_qubit (int | None) – Expected number of bits of the main register; None means no check.

  • anc_qubit (int | None) – Expected number of bits of the auxiliary register; None means no check.

  • alpha (float | None) – Expected BE normalization constant; None means no check.

  • adjoint (bool) – Require the input to support adjoint invocation.

  • controlled (bool) – Require the input to support controlled invocation.

  • zero_input (bool) – Require the input to explicitly promise zero-input preparation.

  • clean_work (bool) – Require the input to explicitly promise the work space is restored to zero.

Raises:

  • ValidationError – Raised at construction when the name is empty, the

  • protocol tuple is invalid, the adapter is not callable, or a field –

  • value is illegal. –

name
protocols
adapter = None
main_qubit = None
anc_qubit = None
alpha = None
adjoint = False
controlled = False
zero_input = False
clean_work = False
to_dict()[source]

Convert into a JSON-storable dictionary; protocols record class names, the adapter records the function name.

Returns:

Plain dictionary of the requirement fields and constraint values.

Return type:

dict[str, object]

inspect(value, *, prefix='')[source]

Check whether a candidate value satisfies this requirement, returning the description and issues instead of raising.

Parameters:

  • value – The input value to check.

  • prefix – Path prefix for reporting, usually the name of the owning protocol.

Returns:

(spec, issues). spec is None when the protocol

Return type:

tuple

does not match or obtaining the description fails; layout, capability, and promise issues are appended one by one to issues without blocking later checks.

Raises:

Exception – Exceptions other than ValidationError from inside the provider are passed through unchanged, preserving the cause.

resolve(value, *, prefix='')[source]

Adapt and check once, also keeping the actual view for use by the algorithm kernel.

class oracq.algorithms.input_model.contracts.ContractReport(protocol, inputs, issues=(), assumptions=(), adapters=())[source]

Bases: object

Result report of one contract check, covering only structure and declarations, proving no mathematical property.

Variables:

  • protocol (str) – Name of the checked protocol.

  • inputs (tuple[tuple[str, oracq.algorithms.input_model.contracts.OracleSpec], ...]) – (input name, OracleSpec) tuples recording successfully obtained input descriptions.

  • issues (tuple[oracq.algorithms.input_model.contracts.ContractIssue, ...]) – All issues found by the check; empty means passed.

  • assumptions (tuple[str, ...]) – Assumptions declared by the protocol, kept as-is.

  • adapters (tuple[str, ...]) – Adapter names involved in the check; empty by default.

protocol
inputs
issues = ()
assumptions = ()
adapters = ()
property ok

True when no issue was found.

require()[source]

Return self when passed, otherwise raise all issues at once.

Returns:

Self, for chaining.

Return type:

ContractReport

Raises:

ContractError – Raised when any unresolved issue exists.

to_dict()[source]

Convert into a JSON-storable dictionary, adding the top-level ok field.

Returns:

Plain dictionary containing ok and all report fields.

Return type:

dict[str, object]

class oracq.algorithms.input_model.contracts.AlgorithmContract(name, inputs, same_width=(), assumptions=())[source]

Bases: object

The algorithm’s contract declaration over all inputs, checkable as a whole with an aggregated report.

Variables:

  • name (str) – Protocol name.

  • inputs (tuple[oracq.algorithms.input_model.contracts.InputRequirement, ...]) – Tuple of InputRequirement distinguished by name.

  • same_width (tuple[tuple[str, str], ...]) – Pairs of input names required to share the same main_qubit.

  • assumptions (tuple[str, ...]) – Assumption declarations passed through to the report as-is.

Raises:

  • ValidationError – Raised at construction when the name is empty, input

  • names are duplicated, an inputs element is illegal, or a same-width –

  • constraint references a nonexistent input. –

name
inputs
same_width = ()
assumptions = ()
check(**values)[source]

Check the inputs one by one by name and generate an aggregated report.

Only methods of the input objects are invoked to obtain descriptions; no algorithm kernel or quantum simulation is run.

Parameters:

**values – Input values keyed by requirement name; extras and missing values are both recorded as issues.

Returns:

Aggregated check result over all inputs.

Return type:

ContractReport

resolve(**values)[source]

Obtain and check one concrete set of inputs; the report can be saved, and the views are used only in the host generation stage.

to_dict()[source]

Convert into a JSON-storable dictionary; each input recursively uses its own to_dict.

Returns:

Plain dictionary of the contract fields and per-input requirements.

Return type:

dict[str, object]

class oracq.algorithms.input_model.contracts.ResolvedInputs(values, report)[source]

Bases: object

Views and check report of one boundary adaptation; host objects are not cached, and this is not serialized as executable IR.

values
report
get(name, cls)[source]

After the contract passes, obtain the checked concrete view by name.

oracq.algorithms.input_model.contracts.ProtocolContract

alias of AlgorithmContract