Begin documenting the common interface at a high level

.github/workflows/Documentation.yml

@@ -0,0 +1,24 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@latest
+        with:
+          version: '1'
+      - name: Install dependencies
+        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+      - name: Build and deploy
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
+        run: julia --project=docs/ docs/make.jl

docs/.gitignore

@@ -0,0 +1,2 @@
+build/
+site/

docs/Project.toml

@@ -0,0 +1,6 @@
+[deps]
+SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
+Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+
+[compat]
+Documenter = "0.27"

docs/make.jl

@@ -0,0 +1,26 @@
+using Documenter, SciMLBase
+
+makedocs(
+    sitename="SciMLBase.jl",
+    authors="Chris Rackauckas",
+    modules=[SciMLBase],
+    clean=true,doctest=false,
+    format = Documenter.HTML(#analytics = "UA-90474609-3",
+                             assets = ["assets/favicon.ico"],
+                             canonical="https://scimlbase.sciml.ai/stable/"),
+    pages=[
+        "Home" => "index.md",
+        "Fundamentals" => Any[
+            "fundamentals/Problems.md",
+            "fundamentals/PDE.md",
+            "fundamentals/SciMLFunctions.md",
+            "fundamentals/Differentiation.md",
+            "fundamentals/FAQ.md"
+        ]
+    ]
+)
+
+deploydocs(
+   repo = "github.com/SciML/SciMLBase.jl.git";
+   push_preview = true
+)

docs/src/fundamentals/Differentiation.md

@@ -0,0 +1,4 @@
+# Controls for Automatic Differentiation
+
+Describe the general `sensealg` system and how it pertains to all problems
+(beyond differential equations!)

docs/src/fundamentals/FAQ.md

@@ -0,0 +1,3 @@
+# Frequently Asked Questions
+
+Ask more questions.

docs/src/fundamentals/PDE.md

@@ -0,0 +1,85 @@
+# The PDE Definition Interface
+
+While ODEs ``u' = f(u,p,t)`` can be defined by a user-function `f`, for PDEs the
+function form can be different for every PDE. How many functions, and how many
+inputs? This can always change. The SciML ecosystem solves this problem by
+using [ModelingToolkit.jl](https://mtk.sciml.ai/dev/) to define `PDESystem`,
+a high-level symbolic description of the PDE to be consumed by other packages.
+
+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 Discontinuous Galerkin 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. A 2-tuple can be used to indicate an `Interval`.
+Thus forms for the `indepvar` can be like:
+
+```julia
+t ∈ (0.0,1.0)
+(t,x) ∈ UnitDisk()
+[v,w,x,y,z] ∈ VectorUnitBall(5)
+```
+
+#### Domain Types (WIP)
+
+- `Interval(a,b)`: Defines the domain of an interval from `a` to `b` (requires explicit
+import from `DomainSets.jl`, but a 2-tuple can be used instead)
+
+## `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.

docs/src/fundamentals/Problems.md

@@ -0,0 +1,4 @@
+# Problem Types
+
+This should become an API page generated from the docstrings of the various
+problem types, and show a picture of the abstract problem type hierarchies.

docs/src/fundamentals/SciMLFunctions.md

@@ -0,0 +1,113 @@
+# SciMLFunctions (Jacobians, Sparsity, Etc.)
+
+The SciML ecosystem provides an extensive interface for declaring extra functions
+associated with the differential equation's data. In traditional libraries there
+is usually only one option: the Jacobian. However, we allow for a large array
+of pre-computed functions to speed up the calculations. This is offered via the
+`SciMLFunction` types which can be passed to the problems.
+
+## Function Type Definitions
+
+### Common Function Choice Definitions
+
+The full interface available to the solvers is as follows:
+
+- `jac`: The Jacobian of the differential equation with respect to the state
+  variable `u` at a time `t` with parameters `p`.
+- `paramjac`: The Jacobian of the differential equation with respect to `p` at
+  state `u` at time `t`.
+- `analytic`: Defines an analytical solution using `u0` at time `t` with `p`
+  which will cause the solvers to return errors. Used for testing.
+- `syms`: Allows you to name your variables for automatic names in plots and
+  other output.
+- `jac_prototype`: Defines the type to be used for any internal Jacobians
+  within the solvers.
+- `sparsity`: Defines the sparsity pattern to be used for the sparse differentiation
+  schemes. By default this is equal to `jac_prototype`. See the sparsity handling
+  portion of this page for more information.
+- `colorvec`: The coloring pattern used by the sparse differentiator. See the
+  sparsity handling portion of this page for more information.
+- `observed`: A function which allows for generating other observables from a
+  solution.
+
+Each function type additionally has some specific arguments, refer to their
+documentation for details.
+
+## In-place Specification and No-Recompile Mode
+
+Each SciMLFunction type can be called with an "is inplace" (iip) choice.
+
+```julia
+ODEFunction(f)
+ODEFunction{iip}(f)
+```
+
+which is a boolean for whether the function is in the inplace form (mutating to
+change the first value). This is automatically determined using the methods table
+but note that for full type-inferrability of the `SciMLProblem` this iip-ness should
+be specified.
+
+Additionally, the functions are fully specialized to reduce the runtimes. If one
+would instead like to not specialize on the functions to reduce compile time,
+then one can set `recompile` to false.
+
+```julia
+ODEFunction{iip,false}(f)
+```
+
+This makes the ODE solver compilation independent of the function and so changing
+the function will not cause recompilation. One can change the default value
+by changing the `const RECOMPILE_BY_DEFAULT = true` to false in the SciMLBase.jl
+source code.
+
+## Specifying Jacobian Types
+
+The `jac` field of an inplace style `SciMLFunction` has the signature `jac(J,u,p,t)`,
+which updates the jacobian `J` in-place. The intended type for `J` can sometimes be
+inferred (e.g. when it is just a dense `Matrix`), but not in general. To supply the
+type information, you can provide a `jac_prototype` in the function's constructor.
+
+The following example creates an inplace `ODEFunction` whose jacobian is a `Diagonal`:
+
+```julia
+using LinearAlgebra
+f = (du,u,p,t) -> du .= t .* u
+jac = (J,u,p,t) -> (J[1,1] = t; J[2,2] = t; J)
+jp = Diagonal(zeros(2))
+fun = ODEFunction(f; jac=jac, jac_prototype=jp)
+```
+
+Note that the integrators will always make a deep copy of `fun.jac_prototype`, so
+there's no worry of aliasing.
+
+In general the jacobian prototype can be anything that has `mul!` defined, in
+particular sparse matrices or custom lazy types that support `mul!`. A special case
+is when the `jac_prototype` is a `AbstractDiffEqLinearOperator`, in which case you
+do not need to supply `jac` as it is automatically set to `update_coefficients!`.
+Refer to the [DiffEqOperators](@ref) section for more information
+on setting up time/parameter dependent operators.
+
+## Sparsity Handling
+
+The solver libraries internally use packages such as [FiniteDiff.jl](https://github.com/JuliaDiff/FiniteDiff.jl)
+and [SparseDiffTools.jl](https://github.com/JuliaDiff/SparseDiffTools.jl) for
+high performance calculation of sparse Jacobians and Hessians, along with matrix-free
+calculations of Jacobian-Vector products (J*v), vector-Jacobian products (v'*J),
+and Hessian-vector products (H*v). The SciML interface gives users the ability
+to control these connections in order to allow for top notch performance.
+
+The key arguments in the SciMLFunction is the `prototype`, which is an object
+that will be used as the underlying Jacobian/Hessian. Thus if one wants to use
+a sparse Jacobian, one should specify `jac_prototype` to be a sparse matrix.
+The sparsity pattern used in the differentiation scheme is defined by `sparsity`.
+By default, `sparsity=jac_prototype`, meaning that the sparse automatic differentiation
+scheme should specialize on the sparsity pattern given by the actual sparsity
+pattern. This can be overridden to say perform partial matrix coloring approximations.
+Additionally, the color vector for the sparse differentiation directions can
+be specified directly via `colorvec`. For more information on how these arguments
+control the differentiation process, see the aforementioned differentiation
+library documentations.
+
+## SciMLFunctions API
+
+Should be generated from docstrings!