QHAM finite closure¶

oracq.applications.qham.linearization

Lazily generate the QCL by HAM order and ordered tensor words; spatial matrices are not materialized.

oracq.applications.qham.linearization.compositions(total, length)[source]¶

Lazily enumerate all ordered splits of length non-negative integers summing to total, in increasing first-component order.

Parameters:

total – Target sum, a non-negative integer.
length – Number of components in each split.

Returns:

Lazy generator yielding one split at a time without materializing all splits.

Return type:

Iterator[tuple[int, …]]

Yields:

tuple[int, …] –

Ordered tuples of length length whose elements: sum to total; when length is 0 the empty tuple is yielded only if total is 0.

class oracq.applications.qham.linearization.HomotopyWeight(kind='one', power=0)[source]¶

Bases: object

Coefficient on a QCL linear edge that varies with the homotopy parameter eta.

Variables:

kind (str) – Weight kind: one (identically 1), correction, or physical.
power (int) – Exponent used by the correction and physical kinds.

kind = 'one'¶

power = 0¶

evaluate(eta)[source]¶

Evaluate the weight at the homotopy parameter eta.

Parameters:: eta – Homotopy parameter value.
Returns:: one is identically 1, correction is -eta*(1+eta)**power, and physical is 1-(1+eta)**power.
Raises:: ValidationError – kind is not a supported weight kind.

formula()[source]¶

Return the formula text of the weight, with the homotopy parameter written eta.

Returns:: Infix expression matching evaluate, e.g. -eta*(1+eta)^3.
Return type:: str

class oracq.applications.qham.linearization.Block(kind, orders=())[source]¶

Bases: object

One block variable of the QCL finite closure.

Variables:

kind (str) – Block kind; physical is the physical output block, the sum of the HAM order components, and tensor is a tensor block on independent coordinates.
orders (tuple[int, ...]) – Tensor word, i.e. the ordered tuple of HAM orders of the factors; always the empty tuple for physical blocks, and the empty tuple with tensor denotes the constant block introduced by forcing homogenization.

kind¶

orders = ()¶

property rank¶: Number of tensor factors of the block; 1 for physical blocks and 0 for the empty-word constant block.

property label¶

Return the human-readable label of the block.

Physical blocks are u_sum, the empty-word constant block is one, and other tensor blocks are Y_ followed by the underscore-joined orders.

class oracq.applications.qham.linearization.Coupling(row, column, operator, position, arity, weight=HomotopyWeight(kind='one', power=0))[source]¶

Bases: object

One linear edge of the QCL closure, delivering a column block’s contribution into the row block’s equation.

Variables:

row (oracq.applications.qham.linearization.Block) – Target block of the edge (the owning equation row).
column (oracq.applications.qham.linearization.Block) – Source block of the edge (the input variable).
operator (str) – Name of the applied multilinear port, e.g. L, F, or B_i.
position (int) – Which tensor factor of the row block the port acts on, replacing it; counted from 0.
arity (int) – Number of port inputs.
weight (oracq.applications.qham.linearization.HomotopyWeight) – Homotopy weight of this edge, identically 1 by default.

row¶

column¶

operator¶

position¶

arity¶

weight = HomotopyWeight(kind='one', power=0)¶

class oracq.applications.qham.linearization.QHAMPlan(pde, order, version='0.1')[source]¶

Bases: object

QCL finite closure plan of a polynomial PDE at a HAM truncation order.

The closure is bounded by the weight criterion p*sum(orders)+len(orders) <= p*m+1, where p = max(1, D-1), D is the PDE polynomial degree, and m is the truncation order. The block set and each row rule are enumerated lazily; the closure matrix is never materialized.

Variables:

pde (oracq.applications.qham.pde.PolynomialPDE) – The PolynomialPDE, validated at construction.
order (int) – HAM truncation order m, must be a non-negative integer.
version (str) – Serialization format version, currently 0.1.

Raises:

ValidationError – pde fails validation, or order is not a non-negative integer, or version is not 0.1.

pde¶

order¶

version = '0.1'¶

property grade¶: Degree scaling of the closure weight criterion, p = max(1, D-1), with D the PDE polynomial degree.

property max_rank¶: Closure weight bound p*m+1, the maximum tensor rank allowed for tensor blocks.

property has_forcing¶: Whether the PDE has a constant forcing term, i.e. port F exists and the closure needs the empty-word constant block.

weight(word)[source]¶

Compute the closure weight p*sum(word)+len(word) of a tensor word.

Parameters:: word – Tuple of the HAM orders of the factors.
Returns:: The closure weight of this tensor word.
Return type:: int

contains(block)[source]¶

Test whether a block belongs to this plan’s finite closure.

Physical blocks must carry no orders; the empty-word tensor block belongs only when forcing exists; other tensor blocks require every order to be a non-negative integer with closure weight within the bound; block kinds other than these never belong to the closure.

Parameters:: block – The block to check.
Returns:: True when the block belongs to the closure.
Return type:: bool

rank_count(rank)[source]¶

Count the closure tensor blocks of a given tensor rank.

Parameters:: rank – Number of tensor factors, counted from 1.
Returns:: Number of tensor words of this rank satisfying the weight constraint; 0 when the rank is below 1 or above the bound.
Return type:: int

property block_count¶

the physical block, the optional empty-word constant block, plus the tensor blocks of each rank.

Type:: Total closure block count

blocks(*, max_blocks=None)[source]¶

Lazily enumerate all blocks of the closure in canonical order.

The physical block comes first, tensor blocks follow by ascending rank and, within a rank, by ascending word sum (ties follow the compositions enumeration order), and the empty-word constant block, when forcing exists, comes last.

Parameters:: max_blocks – Budget for explicitly enumerated blocks; when the total block count exceeds it an error is raised immediately, pointing to lazy queries instead.
Returns:: Lazy generator yielding closure blocks one at a time without materializing the full block list.
Return type:: Iterator[Block]
Yields:: Block – A block of the closure.
Raises:: ValidationError – max_blocks is given and the closure block count exceeds the budget.

row_terms(row)[source]¶

Enumerate all linear edges of a row block within the closure.

Three edge classes are covered: the same-word linear edge L; forcing insertion edges F (physical rows take the empty-word constant block, tensor rows take the word with that zero-order factor removed); and edges replacing a higher-order factor with a lower-order tuple and applying a nonlinear port, carrying a physical or correction homotopy weight. The row of the empty-word constant block has no edges.

Parameters:

row – Row block, must belong to the closure.

Returns:

All edges of this row; each edge’s row field equals the input.

Return type:

tuple[Coupling, …]

Raises:

ValidationError – The row block is outside the finite closure.
AssertionError – A generated column block escapes the closure, i.e. the closure construction invariant is broken.

raw_dimension(dimension)[source]¶

Compute the total dimension of the closure linear system.

Parameters:: dimension – Dimension of a single block’s local state space.
Returns:: Sum of the local dimensions of the physical block and each rank’s tensor blocks (dimension**rank), plus the single coordinate of the empty-word constant block when forcing exists.
Return type:: int

offset(block, dimension)[source]¶

Return the global start index of local coordinate 0 of a block within the closure system.

Blocks are laid out in the canonical order of blocks: the physical block first, each rank’s tensor blocks occupying dimension**rank consecutive coordinates, and the empty-word constant block last with a single coordinate.

Parameters:

block – A block within the closure.
dimension – Dimension of a single block’s local state space.

Returns:

The starting global index of this block.

Return type:

int

Raises:

ValidationError – The block is outside the closure.

locate(index, dimension)[source]¶

Decompose a global index into its owning block and local index within the block; inverse of offset.

Parameters:

index – Global index within the closure system.
dimension – Dimension of a single block’s local state space.

Returns:

The block containing the index and the local index within it.

Return type:

tuple[Block, int]

Raises:

ValidationError – The index is outside the closure system’s total dimension.

summary()[source]¶

Summarize the plan’s key quantities for reports and diagnostics.

Returns:: Dictionary with the version, truncation order, PDE degree, maximum tensor rank, total block count, whether forcing exists, a description of the closure criterion, and each port’s arity.
Return type:: dict

dumps()[source]¶

Serialize the plan to canonical JSON text.

Returns:: JSON text with version, order, and pde fields, keys sorted, indentation 2, ending with a newline.
Return type:: str

classmethod loads(text)[source]¶

Rebuild a plan from the JSON text produced by dumps.

Parameters:: text – JSON text.
Returns:: The rebuilt plan; validation runs again at construction.
Return type:: QHAMPlan
Raises:: ValidationError – The JSON structure, field set, or data is invalid.