Spatial discretization and classical reference¶

oracq.applications.qham.reference

Small-scale mathematical witnesses: finite-difference ports and independent HAM/chain-rule evaluation, not quantum simulation.

class oracq.applications.qham.reference.SpatialGrid(*args, **kwargs)[source]¶

Bases: Protocol

Grid access needed by polynomial PDE discretization.

A grid defines discrete derivative rows; coordinates alone do not specify a discretization. Quantum implementations may supply their own encodings.

property axes¶: Names of the spatial axes, in index order.

property size¶: Total number of grid samples across all axes.

property spatial_width¶: Address width in qubits of the padded spatial coordinate.

derivative_row(derivative, row)[source]¶: Return the sparse finite-difference row of one derivative at one sample.

oracq.applications.qham.reference.centered_weights(order)[source]¶

Compute the weights of a unit-step one-dimensional centered difference stencil.

The derivative interpolation conditions are solved by exact rational elimination on integer lattice points centered at the origin; the result is exact for polynomials of degree below the point count. Zero weights are dropped.

Parameters:: order – Derivative order, a non-negative integer.
Returns:: (lattice offset, weight) pairs where the weight is a float for unit step size; usage still requires division by spacing**order. The result is cached per order.
Return type:: tuple

class oracq.applications.qham.reference.Grid(axes, shape, spacing, boundary='periodic')[source]¶

Bases: object

Spatial discretization grid: axes, shape, spacing, and boundary type, with indexing and difference stencils.

Linear grid indices use a mixed-radix layout with axis 0 in the least significant position; coordinates and address are inverse mappings of each other.

Variables:

axes (tuple[str, ...]) – Tuple of spatial axis names, must match the PDE axes.
shape (tuple[int, ...]) – Number of grid points per axis, all positive integers.
spacing (tuple[float, ...]) – Grid point spacing per axis, all positive finite values.
boundary (str) – Boundary type: periodic wraps out-of-range coordinates by the axis length; dirichlet_zero drops out-of-range stencil points by zero extension.

Raises:

ValidationError – Axis counts disagree, the shape or spacing is invalid, or the boundary type is unsupported.

axes¶

shape¶

spacing¶

boundary = 'periodic'¶

property size¶: Total number of grid points, i.e. the product of all shape entries.

property spatial_width¶

Bit width required to index a spatial coordinate, at least 1.

Spatial storage is aligned to 1 << spatial_width, which may exceed size.

coordinates(index)[source]¶

Decompose a linear grid index into per-axis coordinates; inverse of address.

Parameters:: index – Linear grid index.
Returns:: Per-axis coordinates, axis 0 in the least significant position, with the same length as shape.
Return type:: list[int]

address(coords)[source]¶

Combine per-axis coordinates into a linear grid index.

Parameters:: coords – Sequence of per-axis coordinates; its length must match shape.
Returns:: Linear grid index under the mixed-radix layout.
Return type:: int

derivative_row(derivative, row)[source]¶

Compute the sparse difference row of a mixed spatial derivative at a given grid point.

One-dimensional centered difference stencils are composed axis by axis, with weights already divided by the matching power of spacing; the periodic boundary wraps out-of-range points while dirichlet_zero drops them.

Parameters:

derivative – Derivative specification built from (axis name, order) pairs.
row – Linear grid index.

Returns:

(column address, weight) pairs sorted by column address, zero weights dropped; an empty tuple when row is out of range. The result is cached by (derivative, row).

Return type:

tuple

Raises:

ValueError – derivative references an axis not present in axes.

oracq.applications.qham.reference.tensor_values(vectors)[source]¶

Compute the tensor product of several vectors flattened into a one-dimensional complex list.

Factor 0 occupies the least significant position: the index stride of the k-th factor is the product of the lengths of the preceding factors; with no factors a single-element [1+0j] is returned.

Parameters:: vectors – Sequence of factor vectors.
Returns:: Flattened tensor product, with length equal to the product of the factor lengths.
Return type:: list[complex]

oracq.applications.qham.reference.digits(value, dimension, count)[source]¶

Decompose a non-negative integer into count digits in a fixed radix, least significant digit first.

Inverse of pack; the part of value above count digits is discarded.

Parameters:

value – Non-negative integer to decompose.
dimension – Radix base.
count – Number of output digits.

Returns:

Tuple of digits with length count.

Return type:

tuple[int, …]

oracq.applications.qham.reference.pack(values, dimension)[source]¶

Combine a least-significant-first digit sequence into an integer in a fixed radix; inverse of digits.

Parameters:

values – Digit sequence; the i-th entry carries weight dimension**i.
dimension – Radix base.

Returns:

Weighted sum of the digits.

Return type:

int

class oracq.applications.qham.reference.Discretization(pde, grid, known=None)[source]¶

Bases: object

Classical spatial discretization reference for a polynomial PDE on a grid.

The single-component state is addressed with width bits: the low grid.spatial_width bits are the padded spatial coordinates and the high component_width bits select the field component; the row rules for port matrix elements and closure generators are both evaluated from difference stencils and cached.

Parameters:

pde – The PolynomialPDE to discretize; validated again at construction.
grid – Grid whose spatial axes match the PDE.
known – Known coefficient and forcing data, keyed by known field name with numeric sequences of length equal to the grid point count as values; must cover every known field referenced by the PDE.

Variables:

component_width – Bit width of the field component index.
width – Total bit width of a single-component state.
dimension – Dimension of a single-component state, 2**width.
spatial_storage – Storage length occupied by each field component, 2**spatial_width.
ports – Mapping from port name to OperatorPort.

Raises:

ValidationError – The PDE fails validation, the PDE and grid spatial axes differ, known data is missing, or a known data length differs from the grid point count.

pde¶

grid¶

component_width¶

width¶

dimension¶

spatial_storage¶

known¶

ports¶

known_value(atom, row)[source]¶

Evaluate a known-field atom at a physical grid point.

The difference stencil of atom.derivative is applied to the known data for atom.name and summed with weights.

Parameters:

atom – Known-field atom, possibly carrying a spatial derivative specification.
row – Physical grid point index.

Returns:

Value of the known field or its derivative at the grid point, cached by (atom, row).

Return type:

complex

known_product(monomial, row)[source]¶

Evaluate the product of the known part of a monomial at a physical grid point.

Parameters:

monomial – PDE monomial.
row – Physical grid point index.

Returns:

Running product of monomial.coefficient and the values of the known-field atoms, each carrying its own difference.

Return type:

complex

entry(key, row, column)[source]¶

Evaluate a single matrix element of a multilinear port.

The row is a single-component state index (component and spatial coordinates) and the column packs arity input state indices in a least-significant-first mixed radix; after matching output and input components term by term, the contributions of the outer derivative, known coefficients, and each field derivative are computed with difference stencils.

Parameters:

key – Port name, e.g. L, F, or B_i.
row – Output row index.
column – Packed input column index.

Returns:

The matrix element; 0 when the row or column is out of range. The result is cached by (key, row, column).

Return type:

complex

row_entries(key, row)[source]¶

Enumerate a row from the base difference stencils without scanning N^arity input coordinates.

Parameters:

key – Port name, e.g. L, F, or B_i.
row – Output row index.

Returns:

(packed column index, weight) pairs sorted by column, zero weights dropped; an empty tuple when row is out of range. The result is cached by (key, row).

Return type:

tuple

qcl_row(plan, eta, row)[source]¶

Enumerate one row of the QCL closure generator under global lifted indices.

plan.locate first locates the owning block of the row and its local index, then each linear edge embeds the port row_entries into the source block coordinates and multiplies the homotopy weight evaluated at eta.

Parameters:

plan – QHAMPlan closure plan.
eta – Homotopy parameter.
row – Global row index within the closure system.

Returns:

(global column index, weight) pairs sorted by column, zero weights dropped; an empty tuple when row is out of range.

Return type:

tuple

qcl_entry(plan, eta, row, column)[source]¶

Classical entry reference usable for review; does not masquerade as a reversible quantum oracle.

Parameters:

plan – QHAMPlan closure plan.
eta – Homotopy parameter.
row – Global row index within the closure system.
column – Global column index within the closure system.

Returns:

Matrix element of the closure generator at the given row and column; 0 when either index is out of range.

Return type:

complex

apply_port(key, vectors)[source]¶

Differentiate and multiply the fields directly, for independent validation of the port and closure rules.

Parameters:

key – Port name, e.g. L, F, or B_i.
vectors – Sequence of input state vectors; its length must equal the port arity and each vector must have length dimension.

Returns:

Multilinear evaluation of the port with length dimension.

Return type:

list[complex]

ham_rhs(values, eta)[source]¶

Compute the classical right-hand sides of the order components Ui' by the HAM recursion.

U0' = L U0 + f; Ui' = L Ui - eta*sum_l (1+eta)^(i-1-l) C_l, where C_l is the multilinear evaluation of the nonlinear ports on the order split l.

Parameters:

values – Order components [U0, ..., Um], each a vector of length dimension.
eta – Homotopy parameter.

Returns:

List of vectors with the same length as values; the i-th entry is Ui'.

Return type:

list

Raises:

ValidationError – Some vector length differs from dimension.

lift(plan, values)[source]¶

Lift the order components into the block layout of the closure system.

The physical block holds the sum of the order components; tensor blocks hold the tensor products of their factors via tensor_values; the empty-word constant block is identically 1.

Parameters:

plan – QHAMPlan closure plan.
values – Order-component vectors [U0, ..., Um].

Returns:

Lifted vector with length plan.raw_dimension(dimension).

Return type:

list[complex]

chain_rule(plan, values, eta)[source]¶

Compute the time derivative of the lifted vector directly with the product rule.

Each tensor-factor position of the lift output is differentiated and the order-wise Ui' from ham_rhs substituted; the result should agree component by component with the generator matrix acting on the lifted vector, forming an independent mathematical witness.

Parameters:

plan – QHAMPlan closure plan.
values – Order-component vectors [U0, ..., Um].
eta – Homotopy parameter.

Returns:

Derivative vector with length plan.raw_dimension(dimension).

Return type:

list[complex]

Raises:

ValidationError – Some vector length differs from dimension.

linear_action(plan, eta, values)[source]¶

Act block row by block row, avoiding storage of raw_dimension^2 matrix elements.

Parameters:

plan – QHAMPlan closure plan.
eta – Homotopy parameter.
values – Lifted vector of length plan.raw_dimension(dimension).

Returns:

Vector after the closure generator acts, with the same length as the input vector.

Return type:

list[complex]

matrix(plan, eta, *, max_dimension=512)[source]¶

Materialize the full square matrix of the closure generator.

Parameters:

plan – QHAMPlan closure plan.
eta – Homotopy parameter.
max_dimension – Maximum total dimension allowed for materialization.

Returns:

Square complex matrix of order plan.raw_dimension(dimension), organized by row.

Return type:

list

Raises:

ValidationError – The total dimension exceeds max_dimension.

encode_fields(values)[source]¶

Pack initial data given per field component into a single-component state vector.

Parameters:: values – Mapping keyed by field component name with data sequences of length equal to the grid point count as values; must cover all components.
Returns:: Vector of length dimension whose c-th component occupies the coordinates [c*spatial_storage, c*spatial_storage+size).
Return type:: tuple[complex]
Raises:: ValidationError – The component set is incomplete or a data length mismatches.