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  # :periodic

A 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>) -> PDESystem

Rewrite 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 formLowered form
u(t, Γ) ~ gu(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, Γ)) ~ hDx(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.

source

Classifier

PDEBase.classify_argument — Function
classify_argument(v::VariableMap, u_op, position::Int, arg) -> ArgumentClass

Classify 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 BoundaryPiece whose parent is the spatial domain (isequal to spatial_domain(v)) is a Piece.
  • A number or numeric constant is converted to the float type of the interval of the declared variable iv. It is a BoxFace when it lies within 8eps·max(width, |endpoint|) of an endpoint, where eps is that of the coarser of the interval's and the number's float types, so u(t, π) and u(t, Float32(π)) on Interval(0.0, π) and u(t, 0.1 + 0.2) on Interval(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 iv itself is Free.
  • Anything else is an error that shows the declared argument list.
source
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.

source
PDEBase.classify_condition — Function
classify_condition(v::VariableMap, eq) -> ConditionClass

Classify 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 callsResult
all on the lower time face, as u(0, x):initial
any on the upper time faceerror, 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 boxerror, not supported yet
interior calls mixed with traceserror
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.

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

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

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

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

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

source

Classes

PDEBase.Free — Type
Free(iv) <: ArgumentClass

The argument is the declared independent variable iv in its own position, as x in u(t, x, y).

source
PDEBase.BoxFace — Type
BoxFace(iv, side::Symbol) <: ArgumentClass

The 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).

source
PDEBase.Piece — Type
Piece(piece::BoundaryPiece) <: ArgumentClass

The argument is a BoundaryPiece standing for all the spatial arguments, as Γ in the trace u(t, Γ).

source
PDEBase.ConditionClass — Type
ConditionClass

What classify_condition found a condition to be.

Fields

  • kind: :initial, :boundary or :periodic.
  • locations: The distinct locations of the condition's calls. One BoxFace(t, :lo) for an initial condition, one BoxFace or Piece for a boundary condition, and the lower then the upper face of one axis for a periodic condition.
source