Merge pull request #575 from SciML/pdesystem

start PDESystem documentation

Author: ChrisRackauckas

docs/src/basics/FAQ.md

@@ -21,3 +21,20 @@ lowered array? You can use the internal function `varmap_to_vars`. For example:
 ```julia
 pnew = varmap_to_vars([β=>3.0, c=>10.0, γ=>2.0],parameters(sys))
 ```
+
+## Embedding data into a symbolic model
+
+Let's say for example you want to embed data for the timeseries of some
+forcing equations into the right-hand side of and ODE, or data into a PDE. What
+you would do in these cases is use the `@register` function over an interpolator.
+For example, [DataInterpolations.jl](https://github.com/PumasAI/DataInterpolations.jl)
+is a good library for interpolating the data. Then you can do:
+
+```julia
+spline = CubicSpline(data,datat)
+f(t) = spline(t)
+@register f(t)
+```
+
+This will make `f(t)` be a function that Symbolics.jl will not attempt to trace.
+One should also consider defining the derivative to the function, if available.

docs/src/systems/PDESystem.md

@@ -1,3 +1,81 @@
 # PDESystem
 
-`PDESystem` is still a work in progress.
+`PDESystem` is the common symbolic PDE specification for the SciML ecosystem.
+It is currently being built as a component of the ModelingToolkit ecosystem,
+
+## Vision
+
+The vision for the common PDE interface is that a user should only have to specify
+their PDE once, mathematically, and have instant access to everything as simple
+as a finite difference method with constant grid spacing, to something as complex
+as a distributed multi-GPU discrete Galerkin method.
+
+The key to the common PDE interface is a separation of the symbolic handling from
+the numerical world. All of the discretizers should not "solve" the PDE, but
+instead be a conversion of the mathematical specification to a numerical problem.
+Preferably, the transformation should be to another ModelingToolkit.jl `AbstractSystem`,
+but in some cases this cannot be done or will not be performant, so a `SciMLProblem` is
+the other choice.
+
+These elementary problems, such as solving linear systems `Ax=b`, solving nonlinear
+systems `f(x)=0`, ODEs, etc. are all defined by SciMLBase.jl, which then numerical
+solvers can all target these common forms. Thus someone who works on linear solvers
+doesn't necessarily need to be working on a DG or finite element library, but
+instead "linear solvers that are good for matrices A with properties ..." which
+are then accessible by every other discretization method in the common PDE interface.
+
+Similar to the rest of the `AbstractSystem` types, transformation and analyses
+functions will allow for simplifying the PDE before solving it, and constructing
+block symbolic functions like Jacobians.
+
+## Constructors
+
+```@docs
+PDESystem
+```
+
+### Domains (WIP)
+
+Domains are specifying by saying `indepvar in domain`, where `indepvar` is a
+single or a collection of independent variables, and `domain` is the chosen
+domain type. Thus forms for the `indepvar` can be like:
+
+```julia
+t ∈ IntervalDomain(0.0,1.0)
+(t,x) ∈ UnitDisk()
+[v,w,x,y,z] ∈ VectorUnitBall(5)
+```
+
+#### Domain Types (WIP)
+
+- `IntervalDomain(a,b)`: Defines the domain of an interval from `a` to `b`
+
+## `discretize` and `symbolic_discretize`
+
+The only functions which act on a PDESystem are the following:
+
+- `discretize(sys,discretizer)`: produces the outputted `AbstractSystem` or
+  `SciMLProblem`.
+- `symbolic_discretize(sys,discretizer)`: produces a debugging symbolic description
+  of the discretized problem.
+
+## Boundary Conditions (WIP)
+
+## Transformations
+
+## Analyses
+
+## Discretizer Ecosystem
+
+### NeuralPDE.jl: PhysicsInformedNN
+
+[NeuralPDE.jl](https://github.com/SciML/NeuralPDE.jl) defines the `PhysicsInformedNN`
+discretizer which uses a [DiffEqFlux.jl](https://github.com/SciML/DiffEqFlux.jl)
+neural network to solve the differential equation.
+
+### DiffEqOperators.jl: MOLFiniteDifference (WIP)
+
+[DiffEqOperators.jl](https://github.com/SciML/DiffEqOperators.jl) defines the
+`MOLFiniteDifference` discretizer which performs a finite difference discretization
+using the DiffEqOperators.jl stencils. These stencils make use of NNLib.jl for
+fast operations on semi-linear domains.

src/systems/pde/pdesystem.jl

@@ -1,10 +1,53 @@
+"""
+$(TYPEDEF)
+
+A system of partial differential equations.
+
+# Fields
+$(FIELDS)
+
+# Example
+
+```
+using ModelingToolkit
+
+@parameters t, x
+@variables u(..)
+Dxx = Differential(x)^2
+Dtt = Differential(t)^2
+Dt = Differential(t)
+
+#2D PDE
+C=1
+eq  = Dtt(u(t,x)) ~ C^2*Dxx(u(t,x))
+
+# Initial and boundary conditions
+bcs = [u(t,0) ~ 0.,# for all t > 0
+       u(t,1) ~ 0.,# for all t > 0
+       u(0,x) ~ x*(1. - x), #for all 0 < x < 1
+       Dt(u(0,x)) ~ 0. ] #for all  0 < x < 1]
+
+# Space and time domains
+domains = [t ∈ IntervalDomain(0.0,1.0),
+           x ∈ IntervalDomain(0.0,1.0)]
+
+pde_system = PDESystem(eq,bcs,domains,[t,x],[u])
+```
+"""
 struct PDESystem <: ModelingToolkit.AbstractSystem
+  "The equations which define the PDE"
   eqs
+  "The boundary conditions"
   bcs
+  "The domain for the independent variables."
   domain
+  "The independent variables"
   indvars
+  "The dependent variables"
   depvars
+  "The parameters"
   ps
+  "The default values of the parameters"
   default_p
   @add_kwonly function PDESystem(eqs, bcs, domain, indvars, depvars, ps = SciMLBase.NullParameters(), default_p = nothing)
       new(eqs, bcs, domain, indvars, depvars, ps, default_p)