QFVM application

oracq.applications.qfvm

Build QFVM sparse inputs and a replaceable QLSS problem from a QRAM flow field and Roe arithmetic.

class oracq.applications.qfvm.RoeQfvmInputs(cell_width, fmt, angle_width, rho, momentum, energy, geometry, theta, rhs, residual)[source]

Bases: object

The set of abstract slots declared by the QFVM input model: raw field values, geometry, residual values and residual state preparation.

The slots themselves carry no data; implementations are bound by bind_qfvm and runtime memory tables are materialized by qfvm_memories. Matrix elements are not pre-stored in any slot but are computed on the fly at query time by reversible Roe arithmetic.

Variables:
cell_width
fmt
angle_width
rho
momentum
energy
geometry
theta
rhs
residual
property width

2 component bits + cell_width cell bits + 1 dilation half-block flag bit.

Type:

Bit width of full matrix coordinates

property geometry_width

seven packed segments for partner coordinate, symmetric slot, source cell, row and column components, source band and the valid bit.

Type:

Bit width of geometry table words

oracq.applications.qfvm.roe_qfvm_inputs(*, cell_width=2, fmt=None, angle_width=8, prefix='RoeQfvm')[source]

Declare the full set of abstract QFVM input slots: six databases plus one RHS state preparation.

Everything returned is an open slot without data; data only appears at binding time (bind_qfvm) and execution time (qfvm_memories).

Parameters:

  • cell_width – Bit width of cell indices, in the range 2..25.

  • fmt – Fixed-point format of conserved variables; defaults to FixedFormat(6, 2).

  • angle_width – Bit width of rotation angle words, in the range 1..64.

  • prefix – Prefix of the module names of the abstract slots.

Returns:

The declared set, containing the three conserved-variable databases, the geometry table, the theta table, the residual value database and the abstract RHS preparation.

Return type:

RoeQfvmInputs

Raises:

ValidationError – cell_width or angle_width out of range.

oracq.applications.qfvm.geometry_cells(inputs)[source]

Encode only sparse positions and raw data indices; contains no flow field matrix values.

Parameters:

inputs – The slot set declared by roe_qfvm_inputs, determining coordinate widths and the geometry table layout.

Returns:

The geometry table contents; the address is a matrix coordinate concatenated with a 4-bit slot number, and the value is the seven-segment packed word of partner coordinate, reverse slot, source cell, row and column components, source band and valid bit.

Return type:

dict[int, int]

oracq.applications.qfvm.ptheta_cells(fmt, angle_width, amax)[source]

Generate the theta table: conversion from residual fixed-point words to rotation angle words 2*acos(min(1, |v|/amax)).

Parameters:

  • fmt – The fixed-point format; addresses cover all 2**fmt.width raw words of the format.

  • angle_width – Bit width of output angle words.

  • amax – Magnitude upper bound of elements, used to clamp the acos argument.

Returns:

Mapping from raw fixed-point words to quantized angle words; angle words wrap modulo 2**angle_width.

Return type:

dict

Raises:

ValueError – amax non-positive.

oracq.applications.qfvm.roe_entry(inputs, *, gamma=1.4, entropy_delta=0.125, mass=1.0, dx=1.0)[source]

Build the reversible arithmetic circuit for a single Roe matrix element (without sparse addressing).

The three conserved-variable databases are queried for source and its left and right neighbor cells (with periodic boundary wraparound), roe_face computes the flux characteristic components of the two faces, and the west, center and east candidate values are assembled by band; the mass term is added to the center block diagonal only when the row and column components coincide.

Parameters:

  • inputs – The slot set declared by roe_qfvm_inputs, providing the conserved-variable databases and fixed-point format.

  • gamma – Ratio of specific heats.

  • entropy_delta – Roe entropy fix coefficient.

  • mass – The mass term, applied only to the component diagonal of the center block.

  • dx – Grid step size.

Returns:

Registers are source, row, col, band, value, status; value writes out the selected matrix element, and status aggregates the failure flags of the arithmetic nodes (non-zero means overflow or division by zero).

Return type:

Operation

oracq.applications.qfvm.roe_qfvm_block_encoding(inputs, *, amax=8.0, padding_value=1.0, **entry_options)[source]

Explicit conversion from sparse inputs to a block encoding; QFVM itself no longer forces exposing only a block encoding.

Parameters:

  • inputs – The slot set declared by roe_qfvm_inputs.

  • amax – Magnitude upper bound of sparse elements, used as the scaling factor of the block encoding.

  • padding_value – The padding diagonal value; must be positive and no greater than amax.

  • **entry_options – Arithmetic options forwarded to roe_entry (gamma, mass and so on).

Returns:

The real symmetric sparse block encoding of the Hermitian dilation of the Roe matrix.

Return type:

BlockEncoding

oracq.applications.qfvm.rhs_qram_preparation(inputs)[source]

Build the QRAM preparation of the normalized residual state: amplitudes come from the squared-norm tree, signs are written by phase kickback.

Amplitudes are obtained by qram_state_prep querying the rhs_angles angle word bank layer by layer; signs use the one-bit rhs_sign bank, turning negative residual components into a pi phase through Load, Z and un-Load. The input is the zero state and work returns clean.

Parameters:

inputs – The slot set declared by roe_qfvm_inputs, from which coordinate and angle word widths are taken.

Returns:

target holds the full matrix coordinate (cell_width+3 bits); amplitudes are written only on the first cell_width+2 bits, and the dilation half-block flag stays zero.

Return type:

StatePreparation

oracq.applications.qfvm.qram_bindings(inputs)[source]

Provide the complete binding map from abstract QFVM slots to QRAM implementations.

The three conserved-variable databases, the geometry table and the theta table bind to actual qram_database libraries (the table resource maps to the like-named classical bank); the residual value slot binds to the RoeResidualValues database (rhs_values); the RHS preparation slot binds to the rhs_qram_preparation circuit (angle word and sign resources map to rhs_angles and rhs_sign respectively).

Parameters:

inputs – The slot set declared by roe_qfvm_inputs, providing all abstract slots to bind.

Returns:

Mapping from abstract slot module names to Binding objects, ready to hand to bind.

Return type:

dict

oracq.applications.qfvm.bind_qfvm(program, inputs)[source]

Bind the still-unresolved abstract QFVM slots in a program to QRAM implementations and the signed residual tree preparation.

Parameters:

  • program – The program containing calls to abstract QFVM slots.

  • inputs – The slot set declared by roe_qfvm_inputs.

Returns:

The program with only unresolved slots replaced; open slots unrelated to QFVM are left untouched.

Return type:

Program

oracq.applications.qfvm.qfvm_memories(inputs, flow, *, amax=8.0)[source]

Materialize the runtime memory tables of the QFVM path: a flow field snapshot plus the static geometry table and theta table.

Parameters:

  • inputs – The slot set declared by roe_qfvm_inputs.

  • flow – Classical-side flow field data providing the snapshot of the six banks.

  • amax – Magnitude upper bound of elements used by the theta table.

Returns:

Memory tables handed to the execution backend by name: rho, momentum, energy, rhs_values, rhs_sign, rhs_angles, geometry and theta.

Return type:

dict

Raises:

ValidationError – The flow field mismatches the declared cell count, fixed-point format or angle format.

oracq.applications.qfvm.roe_qfvm_problem(inputs, *, spectrum, rhs_norm=None, amax=8.0, padding_value=1.0, **entry_options)[source]

D=([[0,M],[M.T,0]] on physical coordinates) + padding_value*I_pad.

Parameters:

  • inputs – The slot set declared by roe_qfvm_inputs.

  • spectrum – A SpectralPromise covering the spectral bounds of the quantized Roe matrix; required.

  • rhs_norm – Classical right-hand-side norm; the physical magnitude of the solution can be recovered only when provided.

  • amax – Magnitude upper bound of sparse elements.

  • padding_value – The padding diagonal value; must be positive and no greater than amax.

  • **entry_options – Arithmetic options forwarded to roe_entry (gamma, mass and so on).

Returns:

The QLSS linear system composed of the sparse access, the residual preparation and the extended spectral bounds with the padding value merged in.

Return type:

LinearSystem

oracq.applications.qfvm.roe_qfvm_step(inputs, qlss, *, spectrum=None, rhs_norm=None, **options)[source]

Hand the QFVM problem to a replaceable QLSS protocol for solving.

Parameters:

  • inputs – The slot set declared by roe_qfvm_inputs.

  • qlss – A QLSSProtocol that declares input_model.

  • spectrum – A SpectralPromise covering the actually quantized matrix; required.

  • rhs_norm – Classical right-hand-side norm; only when provided can the solution magnitude be recovered via SolveResult.recover_norm.

  • **options – Remaining keyword arguments forwarded to roe_qfvm_problem, including amax, padding_value and matrix element arithmetic options.

Returns:

The solution state, norm probe and adaptation records produced by the protocol.

Return type:

SolveResult

Raises:

ValidationError – qlss is not a QLSSProtocol declaring input_model, or spectrum is not provided.

oracq.applications.qfvm.qfvm_sparse_access(inputs, *, padding_value=1.0, **entry_options)[source]

Build the CKS sparse access for QFVM: two oracles, an in-place position permutation and an arbitrary-coordinate matrix element XOR.

The location oracle queries the nine structural slots of each column and completes them into a full permutation via nine coherent value transpositions; the padded component has no neighbor structure, and its partner coordinate is rewritten as column + rank to yield the padding diagonal. The entry oracle selects the source cell and component with the geometry table and calls roe_entry to compute the element on the fly: entries outside the structural domain are zero, entries with failed arithmetic are zeroed, and the diagonal of padded coordinates writes padding_value.

Parameters:

  • inputs – The slot set declared by roe_qfvm_inputs.

  • padding_value – The padding diagonal value; must be a positive number exactly representable in the fixed-point format.

  • **entry_options – Arithmetic options forwarded to roe_entry (gamma, mass and so on).

Returns:

Coordinate width inputs.width, value width inputs.fmt.width, sparsity 9.

Return type:

SparseAccess

Raises:

ValidationError – padding_value is non-positive or not exactly representable in the fixed-point format.