Argument Classification
PDEBase recognises where a call of a dependent variable lies by classifying each of its arguments. u(t, x, y), the endpoint form u(t, 0, y) and the trace u(t, Γ) go through the same code: an argument is the declared variable (Free), an interval endpoint (BoxFace), or a boundary piece standing for all the spatial arguments (Piece). A piece that is a face of the box normalises to the BoxFace of its endpoint form, so on (x, y) ∈ Rectangle(0 .. 1, 0 .. 1) the calls u(t, 0, y) and u(t, boundarypiece(Ω, :left)) have the same location.
v = VariableMap(pdesys, disc)
u_op, classes = classify_call(v, u(t, 0, y)) # [Free(t), BoxFace(x, :lo), Free(y)]
PDEBase.location(v, classes) # BoxFace(x, :lo)
classify_condition(v, u(t, 1, y) ~ u(t, 0, y)).kind # :periodicA trace keeps the time argument: on a time-dependent u(t, x, y) it is u(t, Γ), and u(Γ) is an error.
Substitution through operators
Plain substitute does not descend into Differential or NormalDerivative applications, so it leaves the trace in Dx(u(t, Γ)) and Dn(u(t, Γ)) unchanged. Rewrite traces with substitute_traces, then check with assert_no_traces before any expand_derivatives, which turns a remaining Dx(u(t, Γ)) into 0.
Box lowering
to_box_bcs turns every trace condition on the faces of an interval or box into the endpoint form box discretizations parse: u(t, Γ_left) ~ g becomes u(t, 0.0, y) ~ g, Dn_Γ(u(t, Γ)) becomes -Dx(...) on a lower face and +Dx(...) on an upper face, and conditions already in endpoint form pass through. symbolic_discretize applies it automatically for every AbstractBoxDiscretization through lower_boundaries. An interval is the one-dimensional box, with pieces :x1_lo and :x1_hi.
Ω = Rectangle(0.0 .. 1.0, 0.0 .. 1.0)
Γ = boundarypiece(Ω, :right)
bcs = [u(0, x, y) ~ 0, u(t, 0, y) ~ sin(t), NormalDerivative(Γ)(u(t, Γ)) ~ 0]
@named pdesys = PDESystem(eqs, bcs, [(x, y) ∈ Ω, t ∈ Interval(0.0, 1.0)], [t, x, y], [u(t, x, y)])
get_bcs(to_box_bcs(pdesys)) # [u(0, x, y) ~ 0, u(t, 0, y) ~ sin(t), Dx(u(t, 1.0, y)) ~ 0]PDEBase.to_box_bcs — Function
to_box_bcs(pdesys::PDESystem; time = <inferred>) -> PDESystemRewrite every trace condition of pdesys on the faces of an interval or box into the endpoint form that box discretizations such as MethodOfLines parse, and leave everything else untouched. For the face of axis x at its lower end x_lo (from boundarypieces, for example :left of a Rectangle or :x1_lo of an interval):
| Trace form | Lowered form |
|---|---|
u(t, Γ) ~ g | u(t, x_lo, y) ~ g |
Dn_Γ(u(t, Γ)) ~ h | -Dx(u(t, x_lo, y)) ~ h, and +Dx(...) on an upper face |
k * Dn_Γ(u(t, Γ)) + α * u(t, Γ) ~ β | -k * Dx(u(t, x_lo, y)) + α * u(t, x_lo, y) ~ β |
u(t, Γ_lo) ~ u(t, Γ_hi) | u(t, x_lo, y) ~ u(t, x_hi, y) |
Dx(u(t, Γ)) ~ h | Dx(u(t, x_lo, y)) ~ h |
The endpoint value is the interval's own endpoint, DomainSets.infimum or supremum, so 0.0 on Interval(0.0, 1.0); it is isequal to the 0 a user writes. Conditions that hold no trace, including existing endpoint-form conditions, are passed through as they are, so the two styles may be mixed. A system without traces is returned as the same object. Every other field of the system is kept. Each lowered condition is checked with classify_condition and assert_no_traces and is never derivative-expanded.
time is the time variable. When it is not given, it is the independent variable (or nothing, for a steady system) that leaves the parent domain of the traced pieces as the spatial domain; when two fit, as t and x both on Interval(0, 1), the one under which every trace classifies is taken, then the one declared by a pairing of its own, and otherwise time must be passed. A given time is used as is. lower_boundaries calls to_box_bcs with the discretization's time for every AbstractBoxDiscretization. Conditions may be Equations or Pairs.
Throws an ArgumentError when a domain of pdesys is a MeshDomain or another domain that is not an interval or interval product, such as a ball ("MethodOfLines needs an interval or box domain; this system uses a MeshDomain, use FEMDiscretization"), and with the classifier's message for a trace missing its time argument, a periodic pair that is not the two opposite faces of one axis, or a normal derivative applied to a trace on another piece. Traces of array or complex dependent variables are not supported yet and are an ArgumentError asking for the endpoint form, as is a trace on a face whose coordinate the variable does not depend on.
Classifier
PDEBase.classify_argument — Function
classify_argument(v::VariableMap, u_op, position::Int, arg) -> ArgumentClassClassify argument arg of a call of the dependent variable u_op, given in the place of the position-th argument of its declared argument list v.args[u_op].
- A
BoundaryPiecewhose parent is the spatial domain (isequaltospatial_domain(v)) is aPiece. - A number or numeric constant is converted to the float type of the interval of the declared variable
iv. It is aBoxFacewhen it lies within8eps·max(width, |endpoint|)of an endpoint, whereepsis that of the coarser of the interval's and the number's float types, sou(t, π)andu(t, Float32(π))onInterval(0.0, π)andu(t, 0.1 + 0.2)onInterval(0.0, 0.3)are on the upper face. An infinite endpoint matches only an infinite number of the same sign. An exact endpoint always wins; when a number is within the tolerance of both endpoints of a narrow interval, the nearer endpoint wins, and a number equally close to both is an error. Any other number is an error naming the nearest endpoint and the distance to it. - The declared variable
ivitself isFree. - Anything else is an error that shows the declared argument list.
PDEBase.classify_call — Function
classify_call(v::VariableMap, call) -> (u_op, Vector{ArgumentClass})Classify every argument of call, a call of a dependent variable of v, with classify_argument, and return the operation of the call with the classes in argument order.
A call without a BoundaryPiece must have the declared number of arguments, with each declared variable in its own position or replaced by a number. A call with a piece must be the declared argument list with every spatial argument replaced by the one piece and nothing else changed: on u(t, x, y) the trace is u(t, Γ), on Brusselator's u(x, y, t) it is u(Γ, t), and on a steady u(x, y) it is u(Γ). A trace u(Γ) of a time-dependent variable is an error, "trace is missing the time argument". A trace has one class fewer than the declaration has arguments for each spatial argument beyond the first.
PDEBase.classify_condition — Function
classify_condition(v::VariableMap, eq) -> ConditionClassClassify the condition eq (an Equation or a Pair) by the set of locations of its dependent-variable calls, and return a ConditionClass:
| Locations of the calls | Result |
|---|---|
all on the lower time face, as u(0, x) | :initial |
| any on the upper time face | error, not an initial condition |
| one spatial face or one piece | :boundary |
| the two opposite faces of one spatial axis | :periodic |
| two pieces that are not opposite faces of a box | error, not supported yet |
| interior calls mixed with traces | error |
| two faces in one call (an edge or a corner) | error |
A trace written with a piece that is a face of the box classifies like its endpoint form. A call of a variable with no spatial arguments, such as w(t), has no location, so u(t, 0) ~ w(t) is a boundary condition; w(0) is on the lower time face. Likewise an interior call of a variable that does not have the variables its condition's faces fix, as q(t, y) in u(t, 0, y) ~ q(t, y), adds no location, while u(t, 0, y) ~ u(t, x, y) mixes an interior call with a trace. A NormalDerivative(Γa) applied to an expression whose traces are not all on Γa is an error.
PDEBase.location — Function
location(classes)
location(v::VariableMap, classes)Return where a call with argument classes classes (from classify_call) lies: Interior() when every class is Free, the one BoxFace, or the one Piece. Two faces in one call (an edge or a corner) or a face with a piece are an error.
With v, a piece that is a face of the box spatial_domain(v) is normalised to its BoxFace with boxface, so u(t, 0, y) and the trace u(t, Γ) on the left face of (x, y) ∈ Rectangle(...) have equal locations.
PDEBase.boxface — Function
boxface(v::VariableMap, piece::BoundaryPiece) -> Union{BoxFace, Nothing}Return the BoxFace that piece is, when it is a face of the box spatial_domain(v) (a DomainSets.HyperRectangle, or an interval in one dimension, with pieces from boundarypieces), and nothing otherwise. The axes of the box follow the domain declaration, as in spatial_domain: the spatial coordinates of a tuple pairing in tuple order, or the spatial interval pairings in the order of the domain list, never the order of indvars(v).
A piece is matched to a face by its name, as boundarypieces names the faces, so a user-built piece with a face's name and a custom geometry, such as part of that face, normalises to the whole face. A face name beyond the dimension of the box, as :x5_lo on a 3D box, is an ArgumentError that lists the valid names.
PDEBase.normal — Function
normal(face::BoxFace) -> (iv, sign)
normal(piece::Piece, x)Return the outward normal of a location. For a BoxFace it is ±e_iv, returned as the pair (iv, -1) on the lower face and (iv, 1) on the upper face. For a Piece it is DomainSets.normal(parent, x) at the point x when DomainSets knows the normal of the parent domain; otherwise the discretization backend supplies it, and this is an error.
PDEBase.substitute_traces — Function
substitute_traces(ex, rules)substitute(ex, rules) that also substitutes inside Differential and NormalDerivative applications, which plain substitute leaves alone. ex may be an expression or an Equation. Use it wherever traces are rewritten, so that Dx(u(t, Γ)), Dn(u(t, Γ)) and k * Dn(u(t, Γ)) + α * u(t, Γ) all have their trace replaced, and check the result with assert_no_traces.
PDEBase.assert_no_traces — Function
assert_no_traces(ex)Throw an ArgumentError if ex, an expression or an Equation, still holds a trace (a call with a BoundaryPiece argument) or a NormalDerivative, and return ex otherwise. Run it after replacing traces and before expand_derivatives, which silently turns Dx(u(t, Γ)) into 0.
Classes
PDEBase.ArgumentClass — Type
ArgumentClassSupertype of the classes classify_argument assigns to one argument of a call of a dependent variable: Free, BoxFace or Piece.
PDEBase.Free — Type
Free(iv) <: ArgumentClassThe argument is the declared independent variable iv in its own position, as x in u(t, x, y).
PDEBase.BoxFace — Type
BoxFace(iv, side::Symbol) <: ArgumentClassThe argument is an endpoint of the interval of iv, the lower one when side is :lo and the upper one when it is :hi, as 0 in u(t, 0, y) on x ∈ Interval(0, 1). As a location, it is the face of the box on which iv is fixed at that endpoint. A Piece that is a face of the box normalises to the same BoxFace (see location).
PDEBase.Piece — Type
Piece(piece::BoundaryPiece) <: ArgumentClassThe argument is a BoundaryPiece standing for all the spatial arguments, as Γ in the trace u(t, Γ).
PDEBase.Interior — Type
Interior()The location of a call whose arguments are all Free: the call is in the interior of the domain.