API Reference

AbstractEquationSystemDiscretization <: AbstractDiscretization

Supertype for discretizations that lower a PDESystem into an equation-based SciML system, typically an ODESystem or DAESystem.

Discretizer packages subtype this type and implement the developer extension hooks documented in the Developer Extension API.

AbstractOptimizationSystemDiscretization <: AbstractDiscretization

Supertype for discretizations that lower a PDESystem into an optimization system.

Use this type when the generated system is consumed by an optimization problem rather than by an ODE or DAE solver.

AbstractDiscreteSpace

Supertype for discretized spatial domain representations produced from a PDESystem and a discretization.

Concrete spaces are returned by construct_discrete_space and are passed to the remaining discretization hooks.

AbstractCartesianDiscreteSpace <: AbstractDiscreteSpace

Supertype for discrete space representations whose coordinates form a Cartesian product grid.

Subtype this type when x2i and Cartesian indexing describe the spatial coordinates without a general mesh connectivity object.

AbstractVarEqMapping

Supertype for mappings that assign dependent variables and boundary conditions to the equations used to discretize them.

Concrete mappings are returned by construct_var_equation_mapping; their get_eqvar method must identify the discrete variable for every PDE.

AbstractDifferentialDiscretizer

Supertype for objects that hold the data needed to discretize differential operators on a discrete space.

Concrete derivative data is returned by construct_differential_discretizer and consumed by discretize_equation!.

AbstractDiscretizationState

Supertype for mutable state accumulated while PDE equations and boundary conditions are discretized.

Concrete state is returned by construct_disc_state and is updated in place by discretize_equation! before generate_system consumes it.

AbstractBoundary

Abstract base type for all boundary condition representations.

AbstractTruncatingBoundary <: AbstractBoundary

Abstract type for boundary conditions at domain boundaries that truncate the domain.

AbstractInterfaceBoundary <: AbstractTruncatingBoundary

Abstract type for boundary conditions at interfaces between different regions or subdomains.

LowerBoundary <: AbstractTruncatingBoundary

Represents a boundary condition at the lower boundary of a domain.

The public fields describe the boundary after PDEBase has matched the input condition to a dependent variable and spatial coordinate. Construct instances through LowerBoundary(u, t, x, order, eq, v) while parsing a PDESystem.

Fields

• u: The dependent variable
• x: The independent variable at this boundary
• depvars: All dependent variables involved in the boundary condition
• indvars: All independent variables involved in the boundary condition
• eq: The boundary condition equation
• order: The order of the derivative in the boundary condition

Arguments

• u: The dependent-variable expression at the boundary.
• t: The time variable, or nothing for a steady-state system.
• x: The independent variable whose lower endpoint is represented.
• order: The derivative order associated with the boundary condition.
• eq: The symbolic boundary equation.
• v::VariableMap: The variable map used to reconstruct dependent variables.

Returns

• LowerBoundary: A normalized boundary representation.

Examples

boundary = LowerBoundary(u(t, 0), t, x, 0, u(t, 0) ~ 0, v)
boundary.x == x

UpperBoundary <: AbstractTruncatingBoundary

Represents a boundary condition at the upper boundary of a domain.

Construct instances through UpperBoundary(u, t, x, order, eq, v) while parsing a PDESystem.

Fields

• u: The dependent variable
• x: The independent variable at this boundary
• depvars: All dependent variables involved in the boundary condition
• indvars: All independent variables involved in the boundary condition
• eq: The boundary condition equation
• order: The order of the derivative in the boundary condition

Arguments

• u: The dependent-variable expression at the boundary.
• t: The time variable, or nothing for a steady-state system.
• x: The independent variable whose upper endpoint is represented.
• order: The derivative order associated with the boundary condition.
• eq: The symbolic boundary equation.
• v::VariableMap: The variable map used to reconstruct dependent variables.

Returns

• UpperBoundary: A normalized boundary representation.

Examples

boundary = UpperBoundary(u(t, 1), t, x, 0, u(t, 1) ~ 0, v)
boundary.x == x

InterfaceBoundary{IsUpper_u, IsUpper_u2} <: AbstractInterfaceBoundary

Represents a boundary condition at an interface between two regions or subdomains.

Use the ordinary five-field constructor after the two sides have been classified. The type parameters record whether each side is at its upper endpoint; they are Val types so dispatch can use the orientation.

Type Parameters

• IsUpper_u: Val{true} if the first variable is at the upper boundary, Val{false} otherwise
• IsUpper_u2: Val{true} if the second variable is at the upper boundary, Val{false} otherwise

Fields

• u: The first dependent variable at the interface
• u2: The second dependent variable at the interface
• x: The independent variable for the first variable
• x2: The independent variable for the second variable
• eq: The interface boundary condition equation

Note

It is assumed that the variables in an interface boundary condition have the same argument signature, differing in only one variable which defines the interface. This assumption is not validated but will cause errors if violated.

Arguments

• u, u2: Dependent-variable expressions on the two sides.
• x, x2: The interface coordinates on the two sides.
• eq: The symbolic interface equation.

Returns

• InterfaceBoundary: An orientation-aware interface condition.

Examples

boundary = InterfaceBoundary{Val(true), Val(false)}(u, u2, x, x2, u ~ u2)
isinterface(boundary) == Val(true)

HigherOrderInterfaceBoundary <: AbstractInterfaceBoundary

Represents a higher-order boundary condition at an interface between regions.

Higher-order interface boundary conditions involve derivatives and are handled differently from simple interface conditions. These are typically flux conditions or derivative matching conditions at interfaces.

Construct instances through HigherOrderInterfaceBoundary(u, u2, x, x2, t, order, eq, v) so the dependent and independent variable fields are normalized from eq.

Fields

• u: The first dependent variable at the interface
• u2: The second dependent variable at the interface
• x: The independent variable for the first variable
• x2: The independent variable for the second variable
• depvars: All dependent variables involved in the boundary condition
• indvars: All independent variables involved in the boundary condition
• eq: The interface boundary condition equation
• order: The maximum order of derivatives in the boundary condition

Arguments

• u, u2: Dependent-variable expressions on the two sides.
• x, x2: The interface coordinates on the two sides.
• t: The time variable, or nothing for a steady-state system.
• order: The maximum derivative order represented by eq.
• eq: The symbolic interface equation.
• v::VariableMap: The variable map used to reconstruct dependent variables.

Returns

• HigherOrderInterfaceBoundary: A normalized higher-order interface.

VariableMap

A container that maps dependent and independent variables from a PDESystem along with their properties.

VariableMap is created during SciMLBase.symbolic_discretize and is passed to discretizer hooks. VariableMap(pdesys) is useful when a package needs to inspect the symbolic variables without selecting a discretization.

Fields

• ū: Collection of all dependent variables (filtered to exclude boundary values)
• x̄: Collection of spatial independent variables (excludes time)
• ps: Parameters of the system
• time: The time variable (if the system is time-dependent)
• intervals: Dictionary mapping each independent variable to its domain bounds (min, max)
• args: Dictionary mapping each dependent variable operation to its arguments
• depvar_ops: Operations (function symbols) of the dependent variables
• x2i: Dictionary mapping independent variables to their dimension indices
• i2x: Dictionary mapping dimension indices to independent variables
• replaced_vars: Dictionary of variable substitutions/replacements

Constructors

• VariableMap(pdesys): Build a map without a discretization.
• VariableMap(pdesys, disc; replaced_vars = Dict()): Build a map for disc.

Returns

• VariableMap: The normalized variable and domain information used by PDEBase.

Examples

v = VariableMap(pdesys)
depvars(v)
indvars(v)

PeriodicMap{hasperiodic}

A structure that tracks periodic boundary conditions for variables in a PDE system.

Type Parameters

• hasperiodic: A Val type parameter indicating whether any periodic conditions exist

Fields

• map: A nested dictionary structure mapping dependent variable operations to their independent variables and whether each boundary is periodic

Arguments

• hasperiodic: A Val type parameter indicating whether the map contains a periodic pair.
• map: A nested dictionary from dependent-variable operations to independent variables and Val periodicity markers.

Constructor

• PeriodicMap(bmap, v::VariableMap): Build the map from a parsed boundary map and variable map.

Constructs a PeriodicMap from a boundary map and variable map, automatically detecting which boundaries have periodic conditions.

Returns

• PeriodicMap{Val{true}} or PeriodicMap{Val{false}}, depending on the map.

Examples

periodic = PeriodicMap(boundarymap, v)
periodic.map

count_differentials(term, x)

Counts the number of Differential operators with respect to variable x in a term. This is used to determine the order of a PDE.

Arguments

• term: A symbolic expression to analyze
• x: The symbolic variable to count differentials for

Returns

The total count of differential operators with respect to x in the term.

differential_order(eq, x)

Returns a set of all differential orders present in the equation with respect to variable x.

Arguments

• eq: A symbolic equation or expression to analyze
• x: The symbolic variable to compute differential orders for

Returns

A set of integers representing all differential orders found in the equation (excluding zero).

Examples

differential_order(Dx(Dx(u)) ~ 0, x) == Set([2])

has_derivatives(term)

Determines whether a term contains any Differential operators.

Arguments

• term: A symbolic expression to check

Returns

true if the term contains any derivatives, false otherwise.

find_derivative(term, depvar_op)

Finds the first Differential operator or dependent variable matching depvar_op within a term.

Arguments

• term: A symbolic expression to search
• depvar_op: The operation (function symbol) of the dependent variable to find

Returns

The first matching derivative or dependent variable found, or nothing if none exists.

Examples

find_derivative(Dx(u) + 1, operation(u)) == Dx(u)

d_orders(x, pdeeqs)

Return derivative orders with respect to independent variable x that appear in the PDE equations or boundary conditions pdeeqs.

Arguments

• x: The independent variable to inspect.
• pdeeqs: An iterable of Equation or Pair values.

Returns

• A descending vector of unique derivative orders.

Examples

d_orders(x, [Dx(Dx(u)) ~ 0]) == [2]

subs_alleqs!(eqs, bcs, rules)

Applies substitution rules to all equations and boundary conditions in place.

Arguments

• eqs: Vector of equations to modify
• bcs: Vector of boundary conditions to modify
• rules: Substitution rules to apply

Returns

• eqs: The mutated equation vector.

Examples

eqs = [u ~ x]
subs_alleqs!(eqs, [x => 1])

get_depvars(eq, depvar_ops)

Finds all dependent variables matching the given operations in an expression.

Arguments

• eq: A symbolic expression to search
• depvar_ops: Collection of dependent variable operations to match

Returns

A set of all dependent variables found in the expression that match the given operations.

Examples

get_depvars(Dx(u) ~ u, [operation(u)])

getvars(b::AbstractBoundary)

Return the dependent variable and independent boundary variable represented by boundary object b.

Arguments

• b::AbstractBoundary: A lower, upper, or interface boundary.

Returns

• Tuple: (b.u, b.x).

Examples

u_at_boundary, x = getvars(boundary)

pde_substitute(expr, dict)

Custom substitute function for PDE discretization that properly handles Differential operators. In Symbolics v7, Differential(constant) throws an error, and the standard SymbolicUtils Substituter doesn't respect filter functions when processing Differential operators.

This implementation manually traverses the expression tree and:

• Substitutes variables according to the dict
• Does NOT substitute inside Differential(x) operators (the differential variable stays symbolic)
• DOES substitute inside the arguments of derivative calls like Dx(u(t,x))

This allows expressions like Dx(u(t, boundary_value)) to work correctly.

Arguments

• expr: The symbolic expression to transform.
• dict: An iterable of substitution pairs.

Returns

• A symbolic expression with the requested substitutions applied.

Examples

pde_substitute(u(t, x), Dict(x => 0))

get_all_depvars(pdeeqs, depvar_ops)
get_all_depvars(pdesys::PDESystem, depvar_ops)

Return all dependent variables with operations in depvar_ops that appear in the equations or boundary conditions.

Arguments

• pdeeqs or pdesys::PDESystem: Equations, or a PDE system containing them.
• depvar_ops: Operations identifying dependent variables.

Returns

• A vector of matching dependent-variable expressions.

split_terms(eq)
split_terms(eq, x̄)

Split an equation or boundary condition into symbolic terms used by PDE discretization rules.

Arguments

• eq: An Equation or initial-condition Pair.
• x̄: Optional spatial-variable collection used by the derivative-aware method.

Returns

• A vector of symbolic terms extracted from both sides of eq.

Examples

split_terms(u + Dx(u) ~ 0)

split_additive_terms(eq)

Return the left- and right-hand additive terms of equation eq.

Arguments

• eq: A symbolic equation with lhs and rhs fields.

Returns

• A vector containing additive terms from the left-hand side followed by additive terms from the right-hand side.

Examples

split_additive_terms(u + x ~ 2u) == [u, x, 2u]

subsmatch(expr, rule)

Return true when rule.first appears anywhere in expression expr.

Arguments

• expr: An equation or symbolic expression to search.
• rule: A pair whose first element is the expression to match.

Returns

• Bool: Whether the expression occurs in expr.

ex2term(x::Term) -> Symbolic
ex2term(x) -> x

Convert a Term to a variable Term. Note that it only takes a Term not a Num.

Arguments

• term: The symbolic term to replace.
• v::VariableMap: The variable map used to identify dependent variables.

Returns

• A new symbolic variable with the same argument signature as the selected dependent variable, or term if it is not a call expression.

Examples

ex2term(Dx(u), v)

safe_unwrap(x)

Return the wrapped symbolic value for Num inputs and leave all other values unchanged.

recursive_unwrap(ex)

Recursively unwrap Num values inside a symbolic expression.

Arguments

• ex: A symbolic expression, possibly containing nested Num wrappers.

Returns

• The expression with wrappers removed recursively.

Examples

recursive_unwrap(u(x))

flatten_vardict(bmps)

Flatten a nested boundary map into a vector of boundary objects.

Arguments

• bmps: A nested boundary map indexed by dependent variable and independent variable.

Returns

• Vector: All boundary objects in the map, preserving map traversal order.

Examples

boundaries = flatten_vardict(boundarymap)

filter_interfaces(bs)

Return the interface boundaries contained in the collection bs.

Arguments

• bs: An iterable of boundary representations.

Returns

• A vector containing only InterfaceBoundary values.

isperiodic(b1::InterfaceBoundary, b2::InterfaceBoundary)

Return true when interface boundaries b1 and b2 form matching periodic boundary conditions.

Arguments

• b1, b2: Interface boundaries to compare.

Returns

• Bool: Whether the variable operations and interface coordinates are paired.

isinterface(b)

Return Val(true) when b is an InterfaceBoundary, otherwise Val(false).

Arguments

• b: A boundary representation.

Returns

• Val{true} for InterfaceBoundary and Val{false} otherwise.

haslowerupper(bs, x)

Return booleans indicating whether interface boundaries in bs include lower and upper boundaries for independent variable x.

Arguments

• bs: An iterable of boundary representations.
• x: The independent variable to inspect.

Returns

• Tuple{Bool, Bool}: (has_lower, has_upper).

has_interfaces(bmps)

Return true when a nested boundary map contains at least one InterfaceBoundary.

Arguments

• bmps: A nested boundary map indexed by dependent variable and independent variable.

Returns

• Bool: Whether at least one interface boundary is present.

isupper(b)

Return true when boundary object b corresponds to the upper side of a domain or interface.

Arguments

• b: A boundary representation.

Returns

• Bool: Whether b is oriented to the upper side.

ivs(u, v::VariableMap)

Return the independent variables of dependent variable u, excluding the time variable stored in v.

all_ivs(v::VariableMap)
all_ivs(u, v::VariableMap)

Return all independent variables tracked by v, including time when present. With a dependent variable u, return the full argument list for u.

depvar(u, v::VariableMap)

Reconstruct dependent variable u with the argument ordering stored in v.

depvars(v::VariableMap)

Return the dependent variables tracked by v.

indvars(v::VariableMap)

Return the spatial independent variables tracked by v, excluding time.

replaced_vars(v::VariableMap)

Return the variable replacements made while normalizing array-valued dependent variables. The dictionary maps each flattened scalar variable to its original indexed variable, allowing discretizers to translate solution queries between the normalized and user-facing forms. The map is empty when no array-valued dependent variables are present.

x2i(v::VariableMap, u, x)

Return the spatial dimension index of independent variable x in the arguments of dependent variable u.