PDE models and adapters¶

oracq.applications.qham.pde

Immutable representation and Python construction surface of finite polynomial evolution PDEs.

oracq.applications.qham.pde.derivative_add(derivative, axis, order)[source]¶

Return a new derivative specification with the order accumulated on the given axis.

Orders on the same axis are added, zero-order entries are removed, and the result is sorted by axis name.

Parameters:

derivative – Existing sequence of (axis, order) pairs.
axis – Spatial axis name, must be a valid identifier.
order – Derivative order to append, must be a non-negative integer.

Returns:

Tuple of pairs sorted by axis name without zero-order entries.

Return type:

tuple

Raises:

ValidationError – The axis name is invalid or the order is not a non-negative integer.

class oracq.applications.qham.pde.Atom(name, derivative=())[source]¶

Bases: object

Polynomial atom referencing an unknown field or known coefficient by name, carrying the applied spatial derivative specification.

Variables:

name (str) – Name of the field or known coefficient, must be a valid identifier.
derivative (tuple[tuple[str, int], ...]) – Sequence of (axis, order) pairs, the accumulated spatial derivative orders per axis.

name¶

derivative = ()¶

class oracq.applications.qham.pde.Monomial(coefficient=1.0, fields=(), known=(), outer_derivative=())[source]¶

Bases: object

Polynomial monomial: a coefficient times the product of unknown-field atoms and known-coefficient atoms, optionally under an outer derivative.

Variables:

coefficient (complex) – Complex coefficient.
fields (tuple[oracq.applications.qham.pde.Atom, ...]) – Unknown-field atoms participating in the product.
known (tuple[oracq.applications.qham.pde.Atom, ...]) – Known-coefficient atoms participating in the product, such as forcing data.
outer_derivative (tuple[tuple[str, int], ...]) – Outer spatial derivative specification applied to the complete monomial.

coefficient = 1.0¶

fields = ()¶

known = ()¶

outer_derivative = ()¶

class oracq.applications.qham.pde.Expr(terms)[source]¶

Bases: object

Finite polynomial expression of unknown fields, with terms summed additively.

Supports addition, subtraction, and multiplication with Expr or numeric constants, division by a non-zero numeric constant, non-negative integer powers, and applying spatial derivatives with d.

Variables:: terms (tuple[oracq.applications.qham.pde.Monomial, ...]) – Tuple of monomials.

terms¶

d(axis, order=1)[source]¶

Apply a spatial derivative to every monomial of the expression.

For monomials containing exactly one unknown-field atom or exactly one known-coefficient atom and no outer derivative, the derivative accumulates directly on that atom; all other monomials record the derivative in the outer derivative, preserving operator-action semantics instead of rewriting into a product of field derivatives.

Parameters:

axis – Spatial axis name, must be a valid identifier.
order – Derivative order, must be a non-negative integer; defaults to 1.

Returns:

New expression with the derivative applied; self is unchanged.

Return type:

Expr

Raises:

ValidationError – The axis name is invalid or the order is not a non-negative integer.

normalized()[source]¶

Merge structurally identical monomials and drop zero-coefficient terms, returning the normalized new expression.

Coefficients are accumulated keyed by (fields, known, outer_derivative), sorted by the repr string of the key, and zero-coefficient terms are discarded.

Returns:: The normalized new expression; self is unchanged.
Return type:: Expr

oracq.applications.qham.pde.expression(value)[source]¶

Normalize value to an Expr: numeric constants are wrapped as constant expressions and an Expr is returned unchanged.

The numeric zero maps to the empty expression containing no monomials.

Parameters:: value – An Expr instance or a numeric constant.
Returns:: A constant Expr equivalent to value, or value itself.
Return type:: Expr
Raises:: ValidationError – value is neither an Expr nor a number, or the number is not finite.

oracq.applications.qham.pde.Field(name)[source]¶

Build the unit Expr referencing the given unknown field.

Parameters:: name – Unknown field name, must be a valid identifier.
Returns:: Expression containing only one derivative-free unknown-field atom.
Return type:: Expr
Raises:: ValidationError – The name is invalid.

oracq.applications.qham.pde.Known(name)[source]¶

Build the unit Expr referencing the given known coefficient, such as forcing data.

Parameters:: name – Known coefficient name, must be a valid identifier.
Returns:: Expression containing only one derivative-free known-coefficient atom.
Return type:: Expr
Raises:: ValidationError – The name is invalid.

class oracq.applications.qham.pde.EquationTerm(output, monomial)[source]¶

Bases: object

One term of the PDE system: the contribution of a monomial to a given output component.

Variables:

output (str) – Name of the unknown field this term contributes to.
monomial (oracq.applications.qham.pde.Monomial) – The monomial content.

output¶

monomial¶

class oracq.applications.qham.pde.OperatorPort(name, arity, terms)[source]¶

Bases: object

Linearization port: groups same-class equation terms into one operator awaiting binding.

Variables:

name (str) – Port name; L for the linear port, F for the forcing port, and B_0-style names for nonlinear ports.
arity (int) – Number of port inputs; 1 for linear, 0 for forcing, and for nonlinear the count of unknown-field atoms in the corresponding monomial.
terms (tuple[oracq.applications.qham.pde.EquationTerm, ...]) – Equation terms assigned to this port.

name¶

arity¶

terms¶

class oracq.applications.qham.pde.PolynomialPDE(fields, axes, terms, label='polynomial_pde', version='0.1')[source]¶

Bases: object

Immutable representation of a first-order autonomous time-evolution polynomial PDE system (PDE 0.1).

The right-hand side is split into known linear maps, i.e. u' = f + L u + sum_tau B_tau(u, ..., u). Usually constructed via from_equations, or rebuilt from JSON with loads.

Variables:

fields (tuple[str, ...]) – All unknown field names, non-empty and without duplicates.
axes (tuple[str, ...]) – All spatial axis names, without duplicates.
terms (tuple[oracq.applications.qham.pde.EquationTerm, ...]) – All equation terms; each term’s output must be declared in fields.
label (str) – Label string identifying this PDE.
version (str) – Representation version, currently "0.1".

fields¶

axes¶

terms¶

label = 'polynomial_pde'¶

version = '0.1'¶

classmethod from_equations(equations, *, axes=('x',), label='polynomial_pde')[source]¶

Construct and validate a PDE from a dictionary of equation right-hand sides.

Each right-hand side is converted to an Expr by expression and frozen into the equation-term set after merging like terms with normalized.

Parameters:

equations – Mapping from output component name to right-hand-side expression; a right-hand side may be an Expr or a numeric constant.
axes – Sequence of spatial axis names, defaulting to ("x",).
label – PDE label, defaulting to "polynomial_pde".

Returns:

Immutable instance that has passed validate.

Return type:

PolynomialPDE

Raises:

ValidationError – A name, an expression, or the structure after splitting violates the PDE rules.

validate()[source]¶

Validate the structure, semantics, and immutability of the PDE representation.

Checks the label and version, that the fields are non-empty and duplicate-free, that each equation term’s output component is declared, that coefficients are finite, that all unknown-field atoms are declared, and that every derivative specification is immutable with declared axes and positive integer orders.

Returns:: Returns self for chained construction.
Return type:: PolynomialPDE
Raises:: ValidationError – Any check fails.

property degree¶

Maximum count of unknown-field atoms over all equation terms, i.e. the nonlinear degree used by the derivation.

Forcing terms count 0 and linear terms count 1; returns 0 when there are no terms at all.

property ports¶

Group equation terms into linearization ports.

Terms with exactly one unknown-field atom go to the linear port L; terms with none go to the forcing port F; each term with two or more unknown-field atoms forms its own multilinear port B_i, with i the term’s index in terms.

Returns:: L, F, then each B_i, in order, including only ports with corresponding terms.
Return type:: tuple[OperatorPort, …]

dumps()[source]¶

Run validate first, then serialize the PDE to JSON text following the PDE 0.1 format.

Complex coefficients are written as [real part, imaginary part] arrays; keys are sorted, indentation is two spaces, and the text ends with a newline.

Returns:: JSON text.
Return type:: str
Raises:: ValidationError – The representation fails validate.

classmethod loads(text)[source]¶

Rebuild a PDE from JSON text.

Key sets at the top level and of each item are strictly checked, complex coefficients are read back as [real part, imaginary part], and the rebuilt result passes validate before being returned.

Parameters:: text – JSON text produced by dumps.
Returns:: Rebuilt and validated instance.
Return type:: PolynomialPDE
Raises:: ValidationError – The JSON is invalid, contains unknown fields, or the rebuilt result fails validation.