PDE 模型与适配

oracq.applications.qham.pde

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

oracq.applications.qham.pde.derivative_add(derivative, axis, order)

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.

参数:

• 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.

返回:

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

返回类型:

tuple

抛出:

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

class oracq.applications.qham.pde.Atom(name, derivative=())

基类：object

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

变量:

• 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=())

基类：object

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

变量:

• 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)

基类：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.

变量:

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

terms

d(axis, order=1)

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.

参数:

• axis -- Spatial axis name, must be a valid identifier.

• order -- Derivative order, must be a non-negative integer; defaults to 1.

返回:

New expression with the derivative applied; self is unchanged.

返回类型:

Expr

抛出:

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

normalized()

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.

返回:

The normalized new expression; self is unchanged.

返回类型:

Expr

oracq.applications.qham.pde.expression(value)

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.

参数:

value -- An Expr instance or a numeric constant.

返回:

A constant Expr equivalent to value, or value itself.

返回类型:

Expr

抛出:

ValidationError -- value is neither an Expr nor a number, or the number is not finite.

oracq.applications.qham.pde.Field(name)

Build the unit Expr referencing the given unknown field.

参数:

name -- Unknown field name, must be a valid identifier.

返回:

Expression containing only one derivative-free unknown-field atom.

返回类型:

Expr

抛出:

ValidationError -- The name is invalid.

oracq.applications.qham.pde.Known(name)

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

参数:

name -- Known coefficient name, must be a valid identifier.

返回:

Expression containing only one derivative-free known-coefficient atom.

返回类型:

Expr

抛出:

ValidationError -- The name is invalid.

class oracq.applications.qham.pde.EquationTerm(output, monomial)

基类：object

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

变量:

• 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)

基类：object

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

变量:

• 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')

基类：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.

变量:

• 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')

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.

参数:

• 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".

返回:

Immutable instance that has passed validate.

返回类型:

PolynomialPDE

抛出:

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

validate()

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 self for chained construction.

返回类型:

PolynomialPDE

抛出:

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.

返回:

L, F, then each B_i, in order, including only ports with corresponding terms.

返回类型:

tuple[OperatorPort, ...]

dumps()

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.

返回:

JSON text.

返回类型:

str

抛出:

ValidationError -- The representation fails validate.

classmethod loads(text)

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.

参数:

text -- JSON text produced by dumps.

返回:

Rebuilt and validated instance.

返回类型:

PolynomialPDE

抛出:

ValidationError -- The JSON is invalid, contains unknown fields, or the rebuilt result fails validation.