Structured finite-difference ports

oracq.applications.qham.stencils

Structured PDE ports on periodic grids: shifted LCU, component selection, and same-point contraction.

oracq.applications.qham.stencils.derivative_encoding(grid, derivative)

Build a shifted-LCU block encoding of a spatial derivative on a periodic grid.

The derivative on each axis is decomposed into cyclic shift terms by the centered difference stencil, with term coefficients equal to the stencil weights divided by spacing**order; the per-axis operators compose onto the whole spatial address register, each acting only on its own axis’s address bits. An axis without a derivative contributes the identity, and an axis whose stencil coefficients cancel entirely contributes the zero operator.

Parameters:

• grid – A Grid with periodic boundary and axis lengths that are powers of 2.

• derivative – Derivative specification of the form ((axis, order), ...).

Returns:

Block encoding of the difference operator whose target is the spatial register of width grid.spatial_width.

Return type:

BlockEncoding

Raises:

ValidationError – The grid boundary is not periodic, or some axis length is not a power of 2.

oracq.applications.qham.stencils.coefficient_encoding(discretization, monomial, *, max_words=4096)

Build a gate-implemented block encoding of the known-coefficient diagonal multiplier.

The product of the known fields, including their spatial derivatives, and the monomial coefficient is evaluated address by address; a single signal qubit is rotated under address control with the complex phase compensated so that projecting the signal back to zero applies the diagonal value divided by alpha; values range over the whole spatial address register, with padded addresses outside the grid equal to 0.

Parameters:

• discretization – The Discretization providing the grid and known field data.

• monomial – The monomial to encode; degenerates to a constant scaling when there are no known fields and the grid has no padding bits.

• max_words – Maximum number of addresses allowed for the gate coefficient table.

Returns:

Block encoding whose target is the spatial register and whose alpha is the largest modulus of the diagonal values; returns the zero operator when all diagonal values are zero.

Return type:

BlockEncoding

Raises:

ValidationError – The coefficient table exceeds the max_words budget.

oracq.applications.qham.stencils.qram_coefficient_encoding(discretization, monomial, *, angle_width=8, max_words=4096)

Open angle-database encoding of the known-coefficient diagonal; the same program can bind either a gate or a QRAM database.

The contract matches coefficient_encoding (target on the spatial bits and the same alpha), but the coefficient data is not burned into gates: the angle words for diagonal values alpha*cos(theta_a/2) stay in open XOR database slots, and the runtime table is computed separately by qram_coefficient_memory. Only real coefficient data is accepted; angle quantization introduces an amplitude error of at most alpha*pi/2**angle_width.

Parameters:

• discretization – The Discretization providing the grid and known field data.

• monomial – The monomial to encode; degenerates to a constant scaling when there are no known fields and the grid has no padding bits.

• angle_width – Bit width of an angle word, determining the quantization precision of diagonal values.

• max_words – Maximum number of addresses allowed for the angle database.

Returns:

Block encoding with diagonal values left in open XOR database slots, alpha equal to the largest modulus of the diagonal values; returns the zero operator when all diagonal values are zero.

Return type:

BlockEncoding

oracq.applications.qham.stencils.qram_coefficient_memory(discretization, monomial, *, angle_width=8)

Runtime angle table matching qram_coefficient_encoding (address -> angle word).

Parameters:

• discretization – The Discretization providing the grid and known field data.

• monomial – The same monomial used at encoding time; must agree with the encoding call.

• angle_width – Bit width of an angle word; must agree with the encoding call.

Returns:

Mapping from spatial address to angle word; an empty table when the encoding degenerates to a constant scaling or all diagonal values are zero.

Return type:

dict[int, int]

oracq.applications.qham.stencils.term_encoding(discretization, term, *, max_coefficient_words=4096, coefficient_encoder=<function coefficient_encoding>, derivative_encoder=None)

Build the multilinear block encoding of the structured difference port for a single PDE equation term.

The port is assembled from the centered-difference derivatives of each factor field, the known-coefficient diagonal multiplier, component selection, and the outer derivative: each factor is differentiated on its own spatial bits, and in the multi-factor case the factors are contracted to the same point before the diagonal merge; the two reject bits in the signal flag input coordinates whose components mismatch and, for multiple factors, factors not at the same point, while order-zero terms flag nonzero addresses and prepare a uniform superposition on the spatial bits. The port matrix is never materialized.

Parameters:

• discretization – The Discretization providing the grid, component layout, and known data.

• term – An EquationTerm carrying the output component and one monomial.

• max_coefficient_words – Address budget passed to the coefficient encoder.

• coefficient_encoder – Encoding function for the coefficient diagonal multiplier, with the same contract as coefficient_encoding (e.g. qram_coefficient_encoding).

• derivative_encoder – Optional spatial derivative adapter, allowing a custom grid representation instead of periodic structured shifts.

Returns:

Rectangular block encoding whose target width is max(1, arity)*discretization.width, with the arity recorded in the rectangular_arity attribute; alpha is the product of the alphas of the coefficient, the outer derivative, and each factor derivative, with an extra factor sqrt(2**spatial_width) for order-zero terms.

Return type:

BlockEncoding

Raises:

ValidationError – The port target width exceeds 64, or the coefficient encoder reports an exceeded budget.

oracq.applications.qham.stencils.structured_fd_bindings(discretization, initial, *, max_coefficient_words=4096, coefficient_encoder=<function coefficient_encoding>, derivative_encoder=None, initial_norm=None)

Base matrices are generated from shifts and contractions, without materializing N^r x N^r port matrices.

Parameters:

• discretization – The Discretization providing the grid, component layout, and known data.

• initial – Initial vector of length discretization.dimension or an existing physical preparation oracle. A zero vector uses the first basis vector as its normalized preparation.

• max_coefficient_words – Address budget passed to the coefficient encoder.

• coefficient_encoder – Encoding function for the coefficient diagonal multiplier, with the same contract as coefficient_encoding (e.g. qram_coefficient_encoding).

• derivative_encoder – Optional quantum spatial derivative adapter for the chosen grid representation.

• initial_norm – Explicit physical norm required with an oracle initial input; sample arrays retain their computed norm.

Returns:

QHAM binding set with each port bound to a shifted-LCU block encoding, including the initial-state preparation and norm.

Return type:

QHAMBindings