QODE assembly interface

oracq.algorithms.qode.ode

Problem objects, replaceable protocols, and history assembly for linear QODEs.

class oracq.algorithms.qode.ode.QODEProblem(generator, initial, dissipative=None, initial_norm=None, evidence='caller_declared_unverified')[source]

Bases: object

The u’=Gu problem; dissipative is a mathematical declaration, not a language proof.

generator
initial
dissipative = None
initial_norm = None
evidence = 'caller_declared_unverified'
class oracq.algorithms.qode.ode.QODESolver(name, kernel, requires_dissipative=False)[source]

Bases: object

Linear QODE solve-protocol wrapper with contract checking.

Variables:

  • provides – Set of protocols the output is declared to satisfy.

  • name (str) – Protocol name, used in contracts, attributes, and error messages.

  • kernel (collections.abc.Callable[[...], oracq.algorithms.input_model.oracles.StateOracle]) – The actual kernel; a callable of the form (generator, initial, time) -> StateOracle.

  • requires_dissipative (bool) – When True, the problem-level solve must receive a dissipative=True declaration.

provides = (<class 'oracq.algorithms.input_model.interfaces.StateOracleProtocol'>,)
name
kernel
requires_dissipative = False
property contract

Return the operator-state contract of this protocol.

The preconditions include the autonomous homogeneous u'=Gu; when requires_dissipative is True the requirement Hermitian(G)<=0 is appended, and the Schrödingerization protocol additionally appends the validation responsibility for the auxiliary window and the recovery region.

Returns:

The protocol contract; assumptions is the tuple of protocol-specific preconditions.

Return type:

AlgorithmContract

check(generator, initial=None, time=None)[source]

Check whether the inputs satisfy this protocol’s contract, collecting unsatisfied items into a report.

Parameters:

  • generator – Generator block encoding; a QODEProblem may also be passed directly, in which case the generator and initial state inside the problem object are used instead.

  • initial – Initial state preparation; ignored when a QODEProblem is passed.

  • time – Evolution duration; when given, it is also checked to be a finite non-negative real number.

Returns:

The check report; issues collects all unsatisfied items regarding layout, invocation capabilities, and precondition declarations.

Return type:

ContractReport

solve(problem, time)[source]

Problem-level solve entry: check the contract, evolve, and write the declaration provenance into the output attributes.

Parameters:

  • problem – A QODEProblem problem object.

  • time – Evolution duration; must be a finite non-negative real number.

Returns:

The output state oracle; module attributes store evidence, the dissipativity declaration, and the initial norm when provided, without adding a fabricated norm recovery capability.

Return type:

StateOracle

Raises:

  • ContractError – The contract check failed (including an undeclared dissipativity precondition).

  • ValidationError – problem is not a QODEProblem, or time is not a finite non-negative real number.

oracq.algorithms.qode.ode.QODEProtocol

alias of QODESolver

oracq.algorithms.qode.ode.make_euler_history_qode(qlss, *, steps=2)[source]

Wrap a QLSS solver into an implicit-Euler time-discretized QODE generation function.

It assembles, on the history register, a single linear system solving all time steps at once: the matrix is I - dt*(Q⊗G) - S (Q selects all nonzero times, S is the truncated step shift), the right-hand side places the initial state at time zero, then qlss is invoked to solve and the final-time subspace is selected.

Parameters:

  • qlss – A linear-system solve protocol that takes a matrix and a right-hand-side preparation and returns a StateOracle.

  • steps – Number of time steps; must be a positive integer.

Returns:

A generation function of the form (generator, initial, final_time) -> StateOracle whose output is the final-time state.

Return type:

callable

Raises:

ValidationError – steps is not a positive integer; or the input layout or time is invalid at generation time.

oracq.algorithms.qode.ode.linear_qode(method, *, hamiltonian_function=<function taylor_hamiltonian>, **options)[source]

Generic u’=Gu interface that can be injected directly into existing QHAM / make_qpde.

Parameters:

  • method – Solve method; one of schrodingerization, lchs, or cbmd.

  • hamiltonian_function – Hamiltonian simulation implementation of the form (BE, time) returning a BlockEncoding; defaults to truncated Taylor.

  • **options – Method configuration; only plan is accepted, and its type must match the chosen method.

Returns:

The solve protocol wrapping the chosen method’s kernel; the lchs/cbmd paths require a dissipativity declaration.

Return type:

QODESolver