diff --git a/.github/workflows/Documentation.yml b/.github/workflows/Documentation.yml new file mode 100644 index 000000000..e47f93896 --- /dev/null +++ b/.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 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 000000000..a303fff20 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,2 @@ +build/ +site/ diff --git a/docs/Project.toml b/docs/Project.toml new file mode 100644 index 000000000..76ec69dd7 --- /dev/null +++ b/docs/Project.toml @@ -0,0 +1,6 @@ +[deps] +SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462" +Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" + +[compat] +Documenter = "0.27" diff --git a/docs/make.jl b/docs/make.jl new file mode 100644 index 000000000..62bca9a89 --- /dev/null +++ b/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 +) diff --git a/docs/src/assets/favicon.ico b/docs/src/assets/favicon.ico new file mode 100644 index 000000000..3c6bd4703 Binary files /dev/null and b/docs/src/assets/favicon.ico differ diff --git a/docs/src/assets/logo.png b/docs/src/assets/logo.png new file mode 100644 index 000000000..6f4c3e261 Binary files /dev/null and b/docs/src/assets/logo.png differ diff --git a/docs/src/fundamentals/Differentiation.md b/docs/src/fundamentals/Differentiation.md new file mode 100644 index 000000000..a5ba4c9fe --- /dev/null +++ b/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!) diff --git a/docs/src/fundamentals/FAQ.md b/docs/src/fundamentals/FAQ.md new file mode 100644 index 000000000..c996e4b90 --- /dev/null +++ b/docs/src/fundamentals/FAQ.md @@ -0,0 +1,3 @@ +# Frequently Asked Questions + +Ask more questions. diff --git a/docs/src/fundamentals/PDE.md b/docs/src/fundamentals/PDE.md new file mode 100644 index 000000000..f50ee828d --- /dev/null +++ b/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. diff --git a/docs/src/fundamentals/Problems.md b/docs/src/fundamentals/Problems.md new file mode 100644 index 000000000..9918ea4b6 --- /dev/null +++ b/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. diff --git a/docs/src/fundamentals/SciMLFunctions.md b/docs/src/fundamentals/SciMLFunctions.md new file mode 100644 index 000000000..9e74d70ce --- /dev/null +++ b/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! diff --git a/docs/src/index.md b/docs/src/index.md new file mode 100644 index 000000000..892a6ce41 --- /dev/null +++ b/docs/src/index.md @@ -0,0 +1,138 @@ +# The SciML Common Interface for Julia Equation Solvers + +The SciML common interface ties together the numerical solvers of the Julia +package ecosystem into a single unified interface. It is designed for maximal +efficiency and parallelism, while incorporating essential features for large-scale +scientific machine learning such as differentiability, composability, and sparsity. + +This documentation is made to pool together the docs of the various SciML libraries +to paint the overarching picture, establish development norms, and document the +shared/common functionality. + +## Domains of SciML + +The SciML common interface covers the following domains: + +- Linear systems (`LinearProblem`) + - Direct methods for dense and sparse + - Iterative solvers with preconditioning +- Nonlinear Systems (`NonlinearProblem`) + - Systems of nonlinear equations + - Scalar bracketing systems +- Differential Equations + - Discrete equations (function maps, discrete stochastic (Gillespie/Markov) + simulations) (`DiscreteProblem`) + - Ordinary differential equations (ODEs) (`ODEProblem`) + - Split and Partitioned ODEs (Symplectic integrators, IMEX Methods) (`SplitODEProblem`) + - Stochastic ordinary differential equations (SODEs or SDEs) (`SDEProblem`) + - Stochastic differential-algebraic equations (SDAEs) (`SDEProblem` with mass matrices) + - Random differential equations (RODEs or RDEs) (`RODEProblem`) + - Differential algebraic equations (DAEs) (`DAEProblem` and `ODEProblem` with mass matrices) + - Delay differential equations (DDEs) (`DDEProblem`) + - Neutral, retarded, and algebraic delay differential equations (NDDEs, RDDEs, and DDAEs) + - Stochastic delay differential equations (SDDEs) (`SDDEProblem`) + - Experimental support for stochastic neutral, retarded, and algebraic delay differential equations (SNDDEs, SRDDEs, and SDDAEs) + - Mixed discrete and continuous equations (Hybrid Equations, Jump Diffusions) (`DEProblem`s with callbacks) +- Optimization (`OptimizationProblem`) + - Nonlinear (constrained) optimization +- (Stochastic/Delay/Differential-Algebraic) Partial Differential Equations (`PDESystem`) + - Finite difference and finite volume methods + - Interfaces to finite element methods + - Physics-Informed Neural Networks (PINNs) + - Integro-Differential Equations + - Fractional Differential Equations + +The SciML common interface also includes +[ModelingToolkit.jl](https://github.com/SciML/ModelingToolkit.jl) +for defining such systems symbolically, allowing for optimizations like automated +generation of parallel code, symbolic simplification, and generation of sparsity +patterns. + +## Common Interface High Level + +The SciML interface is common as the usage of arguments is standardized across +all of the problem domains. Underlying high level ideas include: + +- All domains use the same interface of defining a `SciMLProblem` which is then + solved via `solve(prob,alg;kwargs)`, where `alg` is a `SciMLAlgorithm`. The + keyword argument namings are standardized across the organization. +- `SciMLProblem`s are generally defined by a `SciMLFunction` which can define + extra details about a model function, such as its analytical Jacobian, its + sparsity patterns and so on. +- There is an organization-wide method for defining linear and nonlinear solvers + used within other solvers, giving maximum control of performance to the user. +- Types used within the packages are defined by the input types. For example, + packages attempt to internally use the type of the initial condition as the + type for the state within differential equation solvers. +- `solve` calls should be thread-safe and parallel-safe. +- `init(prob,alg;kwargs)` returns an iterator which allows for directly iterating + over the solution process +- High performance is key. Any performance that is not at the top level is considered + a bug and should be reported as such. +- All functions have an in-place and out-of-place form, where the in-place form + is made to utilize mutation for high performance on large-scale problems and + the out-of-place form is for compatibility with tooling like static arrays and + some reverse-mode automatic differentiation systems. + +## User-Facing Solver Libraries + +- [DifferentialEquations.jl](https://diffeq.sciml.ai/stable/) + - Multi-package interface of high performance numerical solvers of + differential equations +- [ModelingToolkit.jl](https://mtk.sciml.ai/stable/) + - The symbolic modeling package which implements the SciML symbolic common + interface. +- [NonlinearSolve.jl](https://github.com/JuliaComputing/NonlinearSolve.jl) + - High performance numerical solving of nonlinear systems. +- [GalacticOptim.jl](https://github.com/SciML/GalacticOptim.jl) + - Multi-package interface for numerical solving of optimization problems. +- [NeuralPDE.jl](https://github.com/SciML/NeuralPDE.jl) + - Physics-Informed Neural Network (PINN) package for transforming partial + differential equations into optimization problems. +- [DiffEqOperators.jl](https://github.com/SciML/DiffEqOperators.jl) + - Automated finite difference method (FDM) package for transforming partial + differential equations into nonlinear problems and ordinary differential + equations. +- [DiffEqFlux.jl](https://github.com/SciML/DiffEqFlux.jl) + - High level package for scientific machine learning applications, such as + neural and universal differential equations, solving of inverse problems, + parameter estimation, nonlinear optimal control, and more. + +## Interface Implementation Libraries + +- [SciMLBase.jl](https://github.com/SciML/SciMLBase.jl) + - The core package defining the interface which is consumed by the modeling + and solver packages. +- [DiffEqSensitivity.jl](https://github.com/SciML/DiffEqSensitivity.jl) + - A package which pools together the definition of derivative overloads to + define the common `sensealg` automatic differentiation interface. +- [DiffEqNoiseProcess.jl](https://github.com/SciML/DiffEqNoiseProcess.jl) + - A package which defines the stochastic `AbstractNoiseProcess` interface + for the SciML ecosystem. +- [RecursiveArrayTools.jl](https://github.com/SciML/RecursiveArrayTools.jl) + - A package which defines the underlying `AbstractVectorOfArray` structure + used as the output for all time series results. +- [ArrayInterface.jl](https://github.com/JuliaArrays/ArrayInterface.jl) + - The package which defines the extended `AbstractArray` interface employed + throughout the SciML ecosystem. + +## Using-Facing Modeling Libraries + +There are too many to name here and this will be populated when there is time! + +## Solver Libraries + +There are too many to name here. Check out the +[SciML Organization Github Page](https://github.com/SciML) for details. + +## Contributing + +- Please refer to the + [SciML ColPrac: Contributor's Guide on Collaborative Practices for Community Packages](https://github.com/SciML/ColPrac/blob/master/README.md) + for guidance on PRs, issues, and other matters relating to contributing to SciML. +- There are a few community forums: + - The #diffeq-bridged and #sciml-bridged channels in the + [Julia Slack](https://julialang.org/slack/) + - [JuliaDiffEq](https://gitter.im/JuliaDiffEq/Lobby) on Gitter + - On the Julia Discourse forums (look for the [modelingtoolkit tag](https://discourse.julialang.org/tag/modelingtoolkit) + - See also [SciML Community page](https://sciml.ai/community/)