Strong-Form Analysis
PDEBase.StrongForm analyses the strong form of a PDESystem for discretizers that need the flux structure of each equation, such as finite-element, collocation or discontinuous Galerkin methods. For each equation e = lhs - rhs it finds the mass part, the flux G and the remainder R with e = m⋅u̇ + Σᵢ ∂ᵢGᵢ + R, all written in symbolic quadrature-point slots.
PDEBase.StrongForm — Module
PDEBase.StrongFormSymbolic analysis of a PDE system's strong form, shared by discretizers that need the flux structure of each equation (finite elements, collocation, discontinuous Galerkin). Each equation e = lhs - rhs is checked against an operator whitelist and split into a time-derivative part and a spatial part, ready to be written as e = m⋅u̇ + Σᵢ ∂ᵢGᵢ + R.
PDEBase.StrongForm.analyse — Function
analyse(pdesys, v::VariableMap, boundarymap; ibp = Dict()) -> StrongFormAnalysisStrong-form analysis of pdesys, which must already be in the form symbolic_discretize hands to the discretizer hooks (after make_pdesys_compatible), with v its VariableMap and boundarymap from parse_bcs. Each equation e = lhs - rhs passes the operator whitelist (check_whitelist), is split in time (split_time) and into divergence form (split_divergence), and is written in StateSlots ordered as by SlotContext.
ibp maps an equation, or its index in the flattened equation list (_flatten_eqs(get_eqs(pdesys)), the same order as the outputs), to an IBPPolicy; other keys are an error. Equations are matched by their residual lhs - rhs up to sign, after flattening array variables through replaced_vars(v), so a key written before preprocessing still matches. A key that matches no equation, or keys giving one equation different policies, are errors. The default is ProductRule, which warns once per call when it generates a correction term. Under Weighted(w) the whole analysis is of the weighted equation w⋅e. Equations are not paired with fields here (pair_equations is the discretizer's helper). Spatial boundary conditions in boundarymap are classified by boundary_conditions into essential, natural (matched against the slot-form fluxes) and periodic conditions, keyed by PDEBase.BoxFace for a box discretization's map and by BoundaryPiece for the PieceBoundary entries of a mesh discretization's map; initial conditions are skipped.
PDEBase.StrongForm.StrongFormAnalysis — Type
StrongFormAnalysisThe strong form of a PDE system in slot form (StateSlots). For equation e,
strong[e] = mass[e] + Σᵢ ∂ᵢ flux[e][i] + remainder[e]where mass[e] is the whole time-derivative part Σ_f m_ef⋅Ud_f, not a bare coefficient, so cross-field mass is representable. conormal[e] is ∂(flux[e]⋅N)/∂G, field-major like G. Field f is the f-th declared dependent variable of the system (see declared_fields), whatever order the equations mention them in. Boundary data is keyed by the boundary key type K. essential, natural and periodic list their conditions in the order of the system's boundary conditions; the analysis ranks nothing, so which essential condition wins where faces meet is the discretizer's choice.
mass, flux, remainder and conormal never hold an unevaluated derivative. strong may: the strong residual of ∂ₓ(a(x)⋅∂ₓu) with a registered without a derivative rule holds Differential(X₁)(a(X₁)). Consumers must call check_evaluable on it before build_function, which would compile such a derivative to zero.
PDEBase.StrongForm.StateSlots — Type
StateSlots(nfields, dim, nparams)Symbolic quadrature-point slots that every strong-form output is written in.
Fields
U: state, one slot per field.G: gradient, field-major:G[(f - 1) * dim + d]is∂u_f/∂x_d.Ud: time derivative∂ₜu_f, one slot per field.H: Hessian,H[((f - 1) * dim + d - 1) * dim + e]is∂²u_f/∂x_d∂x_e.X: spatial coordinates,T: time,N: outward unit normal,P: parameters.
PDEBase.StrongForm.SlotContext — Type
SlotContext(pdesys, v::VariableMap; fields = declared_fields(pdesys, v), params = v.ps)How the symbols of pdesys map to slots: field f is fields[f], by default the f-th dependent variable in the declared order of pdesys (see declared_fields), coordinate X[d] is indvars(v)[d], T is the time and P holds the parameters in the order of params, each array parameter contributing its scalar elements in column-major order (a[1], a[2], …). Pair entries p => default stand for p. Boundary traces are located with the classifier (PDEBase.classify_call, PDEBase.location) on v.
PDEBase.StrongForm.declared_fields — Function
declared_fields(pdesys, v::VariableMap)The dependent variables of v in the order pdesys declares them, not the order in which VariableMap discovers them in the equations. pdesys must have been through make_pdesys_compatible, so that array variables are flattened the same way in both.
PDEBase.StrongForm.IBPPolicy — Type
IBPPolicyHow a non-divergence second-order term c⋅∂ᵢw is integrated by parts: ProductRule, Weighted or Reject.
PDEBase.StrongForm.ProductRule — Type
ProductRule()Default IBPPolicy: rewrite c⋅∂ᵢw = ∂ᵢ(c⋅w) - (∂ᵢc)⋅w, adding c⋅w to the flux and -(∂ᵢc)⋅w to the remainder. The correction term makes the stiffness matrix non-symmetric.
PDEBase.StrongForm.Weighted — Type
Weighted(w)IBPPolicy that multiplies the equation by the weight w(x) before integrating by parts, e.g. w = r² for 1/r² ∂ᵣ(r² ∂ᵣu).
PDEBase.StrongForm.Reject — Type
Reject()IBPPolicy that errors on any term that would need the product rule.
PDEBase.StrongForm.EssentialBC — Type
EssentialBC(piece, field, g)Essential condition u_field = g(X, T, P) on the boundary key piece; g is free of state. field is 1-based.
PDEBase.StrongForm.NaturalBC — Type
NaturalBC(piece, eq, Φ)Matched boundary flux Φ of equation eq (1-based) on the boundary key piece, in slot form. It contributes ∮ Φ v to the weak form of eq.
PDEBase.StrongForm.PeriodicBC — Type
PeriodicBC(master, mirror, field, shift)Periodic identification of field (1-based) on the boundary key mirror with master, related by the translation shift.
PDEBase.StrongForm.check_whitelist — Function
check_whitelist(ex, ivs, depvars)Stage 0 of the strong-form analysis: error unless every operation in ex (an expression or an Equation) is supported. Supported are Differential in one of ivs, NormalDerivative applied to a trace, calls of dependent variables and other symbolic functions, ifelse, getindex, and any function Symbolics can differentiate in each of its non-Bool arguments (arithmetic, comparisons and logical operators included). A registered function without a derivative rule, or a symbolic function such as k(..) that is not a dependent variable, is accepted only while no state from depvars reaches it. Returns nothing.
PDEBase.StrongForm.split_time — Function
split_time(eq, depvars, t) -> (mass, spatial)Stage a of the strong-form analysis. Expands the residual e = lhs - rhs of eq (an Equation or a residual expression) and splits it into mass[f], the coefficient of ∂ₜu_f for each u_f in depvars, and spatial, the vector of remaining additive terms (with derivatives distributed over sums, see distribute_derivatives), so that e = Σ_f mass[f]⋅∂ₜu_f + sum(spatial). t is nothing for a steady problem.
Errors on a term that is second order in time, not of the form coefficient × ∂ₜu_f (nonlinear in ∂ₜu or ∂ₜ inside a spatial derivative), or whose coefficient depends on the state.
PDEBase.StrongForm.distribute_derivatives — Function
distribute_derivatives(ex)Rewrite every D(a + b) in ex as D(a) + D(b), expanding derivative arguments first, so that each additive term of the result is a product of factors. Never derivative-expands, so it is safe on expressions holding traces.
PDEBase.StrongForm.split_divergence — Function
split_divergence(spatial, sivs, policy::IBPPolicy = ProductRule(); depvars = ()) -> (G, R, corrected)Stage b of the strong-form analysis. Writes the sum of the spatial terms from split_time as Σᵢ ∂ᵢG[i] + sum(R) over the spatial variables sivs. A term without a second-order factor goes to R unchanged. A term c⋅Dᵢ(w′) with one second-order factor adds c⋅w′ to G[i] and, when c depends on xᵢ, the product-rule correction -(Dᵢc)⋅w′ to R, unless the corrections of all terms simplify to zero together; corrected reports whether corrections were added. Under Reject() a nonzero correction is an error.
Errors on operators of order three or more (naming the highest order present, so that the error does not depend on the term order), on second derivatives outside a divergence-compatible position (inside a nonlinearity, two in one product, or a coefficient depending on ∇u), and on a non-differentiable coefficient that would need the product rule (any of NONSMOOTH_FUNCTIONS), and on a jump (DISCONTINUOUS_FUNCTIONS) under any other derivative that will be expanded (first-order terms, the inner w′): only c⋅w′ in the flux stays undifferentiated, so a jump is accepted there alone. depvars only words the messages.
PDEBase.StrongForm.NONSMOOTH_FUNCTIONS — Constant
NONSMOOTH_FUNCTIONSFunctions that are not differentiable in the symbolic sense. Their Symbolics derivatives are 0 or ifelse(...), so a product-rule correction built from them would vanish silently (spec §5.1, M1). Comparisons and Bool operators are included; they only occur inside ifelse conditions. A derivative that comes out piecewise or NaN is rejected as well, catching functions not listed.
PDEBase.StrongForm.DISCONTINUOUS_FUNCTIONS — Constant
DISCONTINUOUS_FUNCTIONSThe NONSMOOTH_FUNCTIONS that can jump: all of them except the continuous abs, max, min and clamp. A derivative that gets expanded may act on a continuous non-smooth function (the result is correct almost everywhere) but not on a jump, whose delta it would drop.
PDEBase.StrongForm.slot_volume — Function
slot_volume(ctx::SlotContext, ex, slots::StateSlots; derivatives = false) -> Numex from a volume equation in slot form: derivatives are expanded, then interior fields become U, their derivatives Ud, G and H, coordinates X, time T and parameters P. Errors on any symbol left over, such as an unregistered coefficient. A derivative Symbolics cannot evaluate, such as that of a function registered without a derivative rule, is an error too, unless derivatives = true; it is then kept, in slot coordinates (Differential(X₁)(a(X₁))), and the result must pass check_evaluable before code generation. Only for volume equations: a boundary equation must not be derivative-expanded while it holds traces.
PDEBase.StrongForm.check_evaluable — Function
check_evaluable(ex)Error if ex holds an unevaluated Differential, such as the derivative of a coefficient registered without a derivative rule; build_function would silently compile it to zero. Returns nothing. Call it on StrongFormAnalysis.strong before generating code from it.
Boundary conditions
analyse classifies each spatial boundary condition of the parse_bcs boundary map as essential (u_f = g), natural (the facet flux Φ of the one equation whose conormal flux the condition is proven proportional to) or periodic. A box discretization's conditions are keyed by their PDEBase.BoxFace, and the PieceBoundary entries of a mesh discretization's map by their BoundaryPiece. Traces are located with the classifier and put into slots with PDEBase.substitute_traces, never derivative-expanded first: NormalDerivative(Γ)(u_f(t, Γ)) becomes N·G_f, with the numeric normal ±e_iv on a face of the box and the symbolic normal slots N on any other piece, whose normal the backend supplies per quadrature point. A Cartesian derivative such as Dx(u(t, Γ)) is accepted only on a face of the box. pair_equations is the helper a discretizer uses to give each equation its test field.
PDEBase.StrongForm.boundary_conditions — Function
boundary_conditions(boundarymap, ctx::SlotContext, slots, flux; mass = nothing, bcs = nothing)
-> (essential, natural, periodic)Classify every spatial boundary condition of a parse_bcs boundary map: the endpoint faces of a box discretization's map, keyed by their PDEBase.BoxFace, and the PieceBoundary entries of a mesh discretization's map, keyed by their BoundaryPiece; a mixed map gives a union key type. Each output vector lists its conditions in the order of bcs, the system's boundary conditions, duplicates across distinct faces or pieces included and none ranked or dropped; without bcs the order is that of the boundary map. Which essential condition wins where faces or pieces meet is the discretizer's choice. A gradient-free condition is essential for the field parse_bcs filed it under; any other is routed to the equation whose conormal flux it matches, with the normal ±e_iv on a box face (or on a piece that is a face of the box) and the symbolic normal slots N on any other piece. flux[e] is equation e's flux vector and mass[e] its time-derivative part, in slots.
Errors if two conditions fix the same field, or give the same equation's natural condition, on one face. With mass, an equation's own field is the one whose time derivative alone it contains, or the one left over when a single equation and a single field remain unpaired (a steady single-field problem); where the pairing stays ambiguous these checks are skipped. Otherwise it is also an error to give a face both an essential condition on a field and a natural condition for that field's equation, or to give either kind of condition on a face of a field's periodic pair.
PDEBase.StrongForm.slot_condition — Function
slot_condition(eq, face, ctx::SlotContext, slots) -> NumThe residual eq.lhs - eq.rhs of a boundary condition on face, a PDEBase.BoxFace or a BoundaryPiece, in slot form: each trace u_f becomes U[f], Dx_d(u_f) becomes G[(f-1)*dim+d] and NormalDerivative(Γ)(u_f) becomes Σ_d N[d] G[(f-1)*dim+d]. On a box face the normal is the face's ±e_iv and the face coordinate becomes its endpoint value; on a piece the normal stays the symbolic slots N, and a Cartesian derivative of a trace is an error. Traces are replaced with PDEBase.substitute_traces. Errors if a trace or any other unslotted symbol remains. Only trace-free subexpressions are derivative-expanded (spec §3.3 trap).
PDEBase.StrongForm.restrict_to_face — Function
restrict_to_face(ex, face, ctx::SlotContext, slots)ex with a box face's own coordinate slot X[d] set to the face's endpoint, so coefficients are compared on the face rather than in the volume. The identity on a BoundaryPiece, whose coordinates vary over the piece, unless the piece is a face of the box.
PDEBase.StrongForm.match_flux — Function
match_flux(Φ, B, slots) -> Union{Num, Nothing}Match the boundary residual B against the conormal flux Φ = G·N (spec §5.3). Both must be affine in the gradient slots, Φ = a_Φ·g + Φ₀ and B = a_B·g + B₀; if a_B = λ a_Φ for a scalar λ the matched flux Φ₀ - B₀/λ is returned, otherwise nothing. Proportionality must be proven by simplify; a numeric agreement is never accepted (open question O3).
PDEBase.StrongForm.route_natural — Function
route_natural(B, flux, n, slots; label = B) -> (eq::Int, Φ::Num)Route the natural condition B with outward normal n to the one equation whose conormal flux flux[e]·n it matches (spec §5.3), returning that equation and the matched flux. Errors if no equation or more than one matches.
PDEBase.StrongForm.essential_condition — Function
essential_condition(B, slots; field = nothing, label = B) -> (field::Int, g::Num)Solve the gradient-free boundary residual B = 0 for U[field] = g(X, T, P). B must be linear in exactly one field and g free of the others; field, if given, is the field to solve for.
PDEBase.StrongForm.periodic_condition — Function
periodic_condition(b::InterfaceBoundary, ctx::SlotContext) -> PeriodicBC{BoxFace}A condition u(.., x_lo, ..) ~ u(.., x_hi, ..) equating one field on the two faces of one axis, as parse_bcs records it; the shift is the axis length.
PDEBase.StrongForm.pair_equations — Function
pair_equations(mass, slots; pairing = Dict{Int, Int}()) -> Vector{Int}The field each equation is paired with. mass[e] is equation e's time-derivative part Σ_f m_ef Ud[f] in slots. An explicit pairing[e] = f wins; otherwise the equation is paired with the one field whose time derivative it contains. An algebraic row (no time derivative) or a row holding several fields' time derivatives must be named in pairing. Errors if a field is paired twice or pairing names an equation or field that does not exist.