Developer Extension API

PDEBase defines a small, versioned protocol for packages that discretize a ModelingToolkit.PDESystem. The protocol turns symbolic equations and boundary conditions into a symbolic ODE, DAE, or optimization system. It is an extension API for discretizer authors, not an application-level solver API.

Developer API

The functions on this page are public so that discretizer packages can extend them. Ordinary applications should call a discretizer such as MethodOfLines.jl and should not build a solver directly on these hooks. Extension packages should preserve the call order and return contracts below.

Contract

The generic pipeline calls the hooks in this order:

VariableMap(pdesys, discretization) normalizes symbolic variables and domains.
interface_errors rejects unsupported systems before work is allocated.
parse_bcs creates the boundary map, then check_boundarymap validates it.
should_transform optionally enables transform_pde_system!.
construct_disc_state, construct_discrete_space, and construct_var_equation_mapping create the discretizer state.
construct_differential_discretizer precomputes derivative data.
For each PDE, get_eqvar selects its discrete variable and discretize_equation! updates the state in place.
generate_ic_defaults creates discrete initial values.
generate_metadata stores data needed by the generated problem and solution.
generate_system constructs the final symbolic system.

The default methods are intentionally conservative no-ops. A production discretizer must override the hooks that construct its space, map, derivative data, equations, metadata, and final system. A hook should return only the value specified in its docstring; in-place hooks should mutate their supplied state and return nothing.

Input Rules

The PDESystem supplied to the protocol is expected to satisfy these rules:

Every independent variable has one finite domain interval.
Dependent variables use a consistent argument order throughout equations and boundary conditions.
Every spatial boundary required by the discretizer is represented in the boundary conditions.
Time-dependent systems provide initial conditions on the time variable.
Periodic conditions occur as matching lower/upper pairs.
Interface conditions connect variables with compatible argument signatures; only the interface coordinate may differ.

VariableMap excludes time from indvars(v) but retains it in all_ivs(v) and in each dependent variable's argument signature. A discretizer should use the accessors rather than infer dimension order from a field layout.

Abstract Types

Discretizers should subtype one of the output categories and the supporting abstract types as appropriate:

struct MyDiscretization <: PDEBase.AbstractEquationSystemDiscretization
    kwargs::NamedTuple
end

struct MySpace <: PDEBase.AbstractCartesianDiscreteSpace
    grid::Vector{Float64}
end

struct MyMapping <: PDEBase.AbstractVarEqMapping
    equation_variables::Dict
end

struct MyDerivativeData <: PDEBase.AbstractDifferentialDiscretizer
    weights::Dict
end

struct MyState <: PDEBase.AbstractDiscretizationState
    equations::Vector
end

AbstractEquationSystemDiscretization is for ODE/DAE-like symbolic systems; AbstractOptimizationSystemDiscretization is for optimization systems. AbstractDiscreteSpace, AbstractVarEqMapping, AbstractDifferentialDiscretizer, and AbstractDiscretizationState describe the values exchanged by the protocol and are intentionally free of concrete mesh or solver assumptions.

Validation and Transformation

These hooks run before equation generation. Validation hooks should throw a domain-specific error for unsupported input and return nothing for valid input. should_transform must be a pure decision for the supplied system; transform_pde_system! is called only when it returns true and must return the system consumed by later hooks.

PDEBase.interface_errors — Function

interface_errors(sys::PDESystem, v::VariableMap, disc::AbstractDiscretization)

Check whether disc supports the structure of sys represented by v.

Discretization packages should extend this function with checks for features that cannot be handled by their implementation. Return nothing when the system is supported; otherwise throw an informative exception before any boundary parsing or discretization work begins.

Arguments

sys::PDESystem: The PDE system being discretized.
v::VariableMap: The variable map constructed from sys.
disc::AbstractDiscretization: The discretization being applied.

Returns

nothing: The system is supported.

Examples

function PDEBase.interface_errors(sys, v, disc::MyDiscretization)
    isempty(v.x̄) && throw(ArgumentError("MyDiscretization requires a spatial variable"))
    return nothing
end