Edit on GitHub

DifferentialEquations.jl: Scientific Machine Learning (SciML) Enabled Simulation and Estimation

This is a suite for numerically solving differential equations written in Julia and available for use in Julia, Python, and R. The purpose of this package is to supply efficient Julia implementations of solvers for various differential equations. Equations within the realm of this package include:

  • Discrete equations (function maps, discrete stochastic (Gillespie/Markov) simulations)
  • Ordinary differential equations (ODEs)
  • Split and Partitioned ODEs (Symplectic integrators, IMEX Methods)
  • Stochastic ordinary differential equations (SODEs or SDEs)
  • Stochastic differential-algebraic equations (SDAEs)
  • Random differential equations (RODEs or RDEs)
  • Differential algebraic equations (DAEs)
  • Delay differential equations (DDEs)
  • Neutral, retarded, and algebraic delay differential equations (NDDEs, RDDEs, and DDAEs)
  • Stochastic delay differential equations (SDDEs)
  • Experimental support for stochastic neutral, retarded, and algebraic delay differential equations (SNDDEs, SRDDEs, and SDDAEs)
  • Mixed discrete and continuous equations (Hybrid Equations, Jump Diffusions)
  • (Stochastic) partial differential equations ((S)PDEs) (with both finite difference and finite element methods)

The well-optimized DifferentialEquations solvers benchmark as some of the fastest implementations, using classic algorithms and ones from recent research which routinely outperform the "standard" C/Fortran methods, and include algorithms optimized for high-precision and HPC applications. At the same time, it wraps the classic C/Fortran methods, making it easy to switch over to them whenever necessary. Solving differential equations with different methods from different languages and packages can be done by changing one line of code, allowing for easy benchmarking to ensure you are using the fastest method possible.

DifferentialEquations.jl integrates with the Julia package sphere with:

  • GPU acceleration through CUDA.jl[https://cuda.juliagpu.org/stable/] and DiffEqGPU.jl
  • Automated sparsity detection with [Symbolics.jl][(https://github.com/JuliaSymbolics/SparsityDetection.jl)
  • Automatic Jacobian coloring with SparseDiffTools.jl, allowing for fast solutions to problems with sparse or structured (Tridiagonal, Banded, BlockBanded, etc.) Jacobians
  • Allowing the specification of linear solvers for maximal efficiency with LinearSolve.jl
  • Progress meter integration with the Visual Studio Code IDE for estimated time to solution
  • Automatic plotting of time series and phase plots
  • Built-in interpolations
  • Wraps for common C/Fortran methods like Sundials and Hairer's radau
  • Arbitrary precision with BigFloats and Arbfloats
  • Arbitrary array types, allowing the definition of differential equations on matrices and distributed arrays
  • Unit checked arithmetic with Unitful

Additionally, DifferentialEquations.jl comes with built-in analysis features, including:

Contributing

Supporting and Citing

The software in this ecosystem was developed as part of academic research. If you would like to help support it, please star the repository as such metrics may help us secure funding in the future. If you use SciML software as part of your research, teaching, or other activities, we would be grateful if you could cite our work.

@article{rackauckas2017differentialequations,
  title={Differentialequations.jl--a performant and feature-rich ecosystem for solving differential equations in julia},
  author={Rackauckas, Christopher and Nie, Qing},
  journal={Journal of Open Research Software},
  volume={5},
  number={1},
  year={2017},
  publisher={Ubiquity Press}
}

is necessary for any use of DifferentialEquations.jl or the packages that are maintained as part of its suite (OrdinaryDiffEq.jl, Sundials.jl, DiffEqDevTools.jl, etc.). Additionally, many of the solvers utilize novel algorithms, and if these algorithms are used we asked that you cite the methods. Please see our citation page for guidelines.

Getting Started: Installation And First Steps

Installing from Julia

To install the package, use the following command inside the Julia REPL:

using Pkg
Pkg.add("DifferentialEquations")

To load the package, use the command:

using DifferentialEquations

This will add solvers and dependencies for all kinds of Differential Equations (e.g. ODEs or SDEs etc., see the Supported Equations section below). If you are interested in only one type of equation solvers of DifferentialEquations.jl or simply want a more lightweight version, see the Reduced Compile Time and Low Dependency Usage page.

To understand the package in more detail, check out the following tutorials in this manual. It is highly recommended that new users start with the ODE tutorial. Example IJulia notebooks can also be found in DiffEqTutorials.jl. If you find any example where there seems to be an error, please open an issue.

For the most up to date information on using the package, please join the Gitter channel.

Using the bleeding edge for the latest features and development is only recommended for power users. Information on how to get to the bleeding edge is found in the developer documentation.

Installing from Python

Use of DifferentialEquations.jl from the Python programming language is available through the diffeqpy module. To install diffeqpy, use pip:

pip install diffeqpy

Using diffeqpy requires that Julia is installed and in the path, along with DifferentialEquations.jl and PyCall.jl. To install Julia, download a generic binary from the JuliaLang site and add it to your path. To install Julia packages required for diffeqpy, open up Python interpreter then run:

>>> import diffeqpy
>>> diffeqpy.install()

and you're good! In addition, to improve the performance of your code it is recommended that you use Numba to JIT compile your derivative functions. To install Numba, use:

pip install numba

diffeqpy supports the majority of DifferentialEquations.jl with very similar syntax, see the diffeqpy README for more details. One important point to note is that Numba is generally an order of magnitude slower than Julia in terms of the generated differential equation solver code, and thus it is recommended to use julia.Main.eval for Julia-side derivative function implementations for maximal efficiency. See this blog post for more information.

Installing from R

Use of DifferentialEquations.jl from the R programming language is available through the diffeqr module. diffeqr is registered into CRAN. Thus to add the package, use:

install.packages("diffeqr")

To install the master branch of the package (for developers), use:

devtools::install_github('SciML/diffeqr', build_vignettes=T)

You will need a working installation of Julia in your path. To install Julia, download a generic binary from the JuliaLang site and add it to your path. The download and installation of DifferentialEquations.jl will happen on the first invocation of diffeqr::diffeq_setup().

Currently, use from R supported a subset of DifferentialEquations.jl which is documented through CRAN.

IJulia Notebook Tutorials

You can access extra tutorials supplied in the DiffEqTutorials.jl repository via the commands:

using Pkg
pkg"add https://github.com/SciML/SciMLTutorials.jl"
using SciMLTutorials
SciMLTutorials.open_notebooks()

Or you can view the webpages for the rendered tutorials at the links found in the repository.

Video Tutorial

Video Tutorial

Tutorials

The following tutorials will introduce you to the functionality of DifferentialEquations.jl. More examples can be found by checking out the IJulia notebooks in the examples folder.

Removing and Reducing Compile Times

In some situations one may wish to decrease the compile time associated with DifferentialEquations.jl usage. If that's the case, there's two strategies to employ. One strategy is to use the low dependency usage. DifferentialEquations.jl is a metapackage composed of many smaller packages, and thus one could directly use a single component, such as OrdinaryDiffEq.jl for the pure Julia ODE solvers, and decrease the compile times by ignoring the rest (note: the interface is exactly the same, except using a solver other than those in OrdinaryDiffEq.jl will error). We recommend that downstream packages only rely on exactly the packages they need.

The other strategy is to use PackageCompiler.jl to create a system image that precompiles the whole package. To do this, one simply does:

using PackageCompiler
PackageCompiler.create_sysimage([:DifferentialEquations,:Plots];replace_default=true)

Note that there are some drawbacks to adding a package in your system image, for example the package will never update until you manually rebuild the system image again. For more information on the consequences, see this portion of the PackageCompiler manual

Basics

These pages introduce you to the core of DifferentialEquations.jl and the common interface. It explains the general workflow, options which are generally available, and the general tools for analysis.

Problem Types

These pages describe building the problem types to define differential equations for the solvers, and the special features of the different solution types.

Solver Algorithms

These pages describe the solvers and available algorithms in detail.

Additional Features

These sections discuss extra performance enhancements, event handling, and other in-depth features.

Extra Details

These are just assorted extra explanations for the curious.

Acknowledgements

Core Contributors

JuliaDiffEq and DifferentialEquations.jl has been a collaborative effort by many individuals. Significant contributions have been made by the following individuals:

  • Chris Rackauckas (@ChrisRackauckas) (lead developer)
  • Yingbo Ma (@YingboMa)
  • David Widmann (@devmotion)
  • Hendrik Ranocha (@ranocha)
  • Ethan Levien (@elevien)
  • Tom Short (@tshort)
  • @dextorious
  • Samuel Isaacson (@isaacsas)

Google Summer of Code Alumni

  • Yingbo Ma (@YingboMa)
  • Shivin Srivastava (@shivin9)
  • Ayush Pandey (@Ayush-iitkgp)
  • Xingjian Guo (@MSeeker1340)
  • Shubham Maddhashiya (@sipah00)
  • Vaibhav Kumar Dixit (@Vaibhavdixit02)

Reproducibility

The documentation of this SciML package was built using these direct dependencies,
Status `~/work/DiffEqDocs.jl/DiffEqDocs.jl/docs/Project.toml`
  [fbb218c0] BSON v0.3.6
  [336ed68f] CSV v0.10.7
  [dfb8ca35] DAEProblemLibrary v0.1.0
  [f42792ee] DDEProblemLibrary v0.1.2
  [a93c6f00] DataFrames v1.4.3
  [2b5f629d] DiffEqBase v6.108.0
  [459566f4] DiffEqCallbacks v2.24.3
  [d91efeb5] DiffEqDocs v7.6.0 `~/work/DiffEqDocs.jl/DiffEqDocs.jl`
  [0c46a032] DifferentialEquations v7.6.0
  [e30172f5] Documenter v0.27.23
  [033835bb] JLD2 v0.4.29
  [faf0f6d7] JumpProblemLibrary v0.1.3
  [fdc4e326] ODEProblemLibrary v0.1.4
  [1dea7af3] OrdinaryDiffEq v6.34.1
  [c72e72a9] SDEProblemLibrary v0.1.3
  [0bca4576] SciMLBase v1.77.0
and using this machine and Julia version.
Julia Version 1.8.3
Commit 0434deb161e (2022-11-14 20:14 UTC)
Platform Info:
  OS: Linux (x86_64-linux-gnu)
  CPU: 2 × Intel(R) Xeon(R) CPU E5-2673 v4 @ 2.30GHz
  WORD_SIZE: 64
  LIBM: libopenlibm
  LLVM: libLLVM-13.0.1 (ORCJIT, broadwell)
  Threads: 1 on 2 virtual cores
A more complete overview of all dependencies and their versions is also provided.
Status `~/work/DiffEqDocs.jl/DiffEqDocs.jl/docs/Manifest.toml`
  [a4c015fc] ANSIColoredPrinters v0.0.1
  [c3fe647b] AbstractAlgebra v0.27.7
  [1520ce14] AbstractTrees v0.4.3
  [79e6a3ab] Adapt v3.4.0
  [dce04be8] ArgCheck v2.3.0
  [ec485272] ArnoldiMethod v0.2.0
  [4fba245c] ArrayInterface v6.0.24
  [30b0a656] ArrayInterfaceCore v0.1.26
  [6ba088a2] ArrayInterfaceGPUArrays v0.2.2
  [015c0d05] ArrayInterfaceOffsetArrays v0.1.7
  [b0d46f97] ArrayInterfaceStaticArrays v0.1.5
  [dd5226c6] ArrayInterfaceStaticArraysCore v0.1.3
  [4c555306] ArrayLayouts v0.8.15
  [15f4f7f2] AutoHashEquals v0.2.0
  [fbb218c0] BSON v0.3.6
  [aae01518] BandedMatrices v0.17.9
  [198e06fe] BangBang v0.3.37
  [9718e550] Baselet v0.1.1
  [e2ed5e7c] Bijections v0.1.4
  [62783981] BitTwiddlingConvenienceFunctions v0.1.5
  [8e7c35d0] BlockArrays v0.16.21
  [ffab5731] BlockBandedMatrices v0.11.9
  [764a87c0] BoundaryValueDiffEq v2.10.0
  [fa961155] CEnum v0.4.2
  [2a0fbf3d] CPUSummary v0.1.30
  [00ebfdb7] CSTParser v3.3.6
  [336ed68f] CSV v0.10.7
  [49dc2e85] Calculus v0.5.1
  [479239e8] Catalyst v12.3.1
  [d360d2e6] ChainRulesCore v1.15.6
  [9e997f8a] ChangesOfVariables v0.1.4
  [fb6a15b2] CloseOpenIntervals v0.1.11
  [944b1d66] CodecZlib v0.7.0
  [861a8166] Combinatorics v1.0.2
  [a80b9123] CommonMark v0.8.7
  [38540f10] CommonSolve v0.2.3
  [bbf7d656] CommonSubexpressions v0.3.0
  [34da2185] Compat v4.5.0
  [b152e2b5] CompositeTypes v0.1.3
  [a33af91c] CompositionsBase v0.1.1
  [187b0558] ConstructionBase v1.4.1
  [adafc99b] CpuId v0.3.1
  [a8cc5b0e] Crayons v4.1.1
  [dfb8ca35] DAEProblemLibrary v0.1.0
  [f42792ee] DDEProblemLibrary v0.1.2
  [9a962f9c] DataAPI v1.13.0
  [a93c6f00] DataFrames v1.4.3
  [864edb3b] DataStructures v0.18.13
  [e2d170a0] DataValueInterfaces v1.0.0
  [244e2a9f] DefineSingletons v0.1.2
  [bcd4f6db] DelayDiffEq v5.40.3
  [b429d917] DensityInterface v0.4.0
  [2b5f629d] DiffEqBase v6.108.0
  [459566f4] DiffEqCallbacks v2.24.3
  [d91efeb5] DiffEqDocs v7.6.0 `~/work/DiffEqDocs.jl/DiffEqDocs.jl`
  [77a26b50] DiffEqNoiseProcess v5.14.2
  [9fdde737] DiffEqOperators v4.44.0
  [163ba53b] DiffResults v1.1.0
  [b552c78f] DiffRules v1.12.2
  [0c46a032] DifferentialEquations v7.6.0
  [b4f34e82] Distances v0.10.7
  [31c24e10] Distributions v0.25.79
  [ffbed154] DocStringExtensions v0.9.2
  [e30172f5] Documenter v0.27.23
  [5b8099bc] DomainSets v0.5.14
  [fa6b7ba4] DualNumbers v0.6.8
  [7c1d4256] DynamicPolynomials v0.4.5
  [4e289a0a] EnumX v1.0.3
  [d4d017d3] ExponentialUtilities v1.22.0
  [e2ba6199] ExprTools v0.1.8
  [7034ab61] FastBroadcast v0.2.3
  [9aa1b823] FastClosures v0.3.2
  [29a986be] FastLapackInterface v1.2.7
  [5789e2e9] FileIO v1.16.0
  [48062228] FilePathsBase v0.9.20
  [1a297f60] FillArrays v0.13.5
  [6a86dc24] FiniteDiff v2.17.0
  [59287772] Formatting v0.4.2
  [f6369f11] ForwardDiff v0.10.33
  [069b7b12] FunctionWrappers v1.1.3
  [77dc65aa] FunctionWrappersWrappers v0.1.1
  [46192b85] GPUArraysCore v0.1.2
  [c145ed77] GenericSchur v0.5.3
  [c27321d9] Glob v1.3.0
  [86223c79] Graphs v1.7.4
  [0b43b601] Groebner v0.2.11
  [d5909c97] GroupsCore v0.4.0
  [3e5b6fbb] HostCPUFeatures v0.1.13
  [34004b35] HypergeometricFunctions v0.3.11
  [b5f81e59] IOCapture v0.2.2
  [615f187c] IfElse v0.1.1
  [d25df0c9] Inflate v0.1.3
  [22cec73e] InitialValues v0.3.1
  [842dd82b] InlineStrings v1.3.2
  [18e54dd8] IntegerMathUtils v0.1.0
  [8197267c] IntervalSets v0.7.4
  [3587e190] InverseFunctions v0.1.8
  [41ab1584] InvertedIndices v1.2.0
  [92d709cd] IrrationalConstants v0.1.1
  [42fd0dbc] IterativeSolvers v0.9.2
  [82899510] IteratorInterfaceExtensions v1.0.0
  [033835bb] JLD2 v0.4.29
  [692b3bcd] JLLWrappers v1.4.1
  [682c06a0] JSON v0.21.3
  [98e50ef6] JuliaFormatter v1.0.16
  [faf0f6d7] JumpProblemLibrary v0.1.3
  [ccbc3e58] JumpProcesses v9.2.3
  [ef3ab10e] KLU v0.4.0
  [ba0b0d4f] Krylov v0.9.0
  [0b1a1467] KrylovKit v0.6.0
  [b964fa9f] LaTeXStrings v1.3.0
  [2ee39098] LabelledArrays v1.12.5
  [984bce1d] LambertW v0.4.5
  [23fbe1c1] Latexify v0.15.17
  [10f19ff3] LayoutPointers v0.1.12
  [5078a376] LazyArrays v0.22.12
⌅ [d7e5e226] LazyBandedMatrices v0.7.17
  [2d8b4e74] LevyArea v1.0.0
  [d3d80556] LineSearches v7.2.0
  [7ed4a6bd] LinearSolve v1.31.0
  [2ab3a3ac] LogExpFunctions v0.3.19
  [bdcacae8] LoopVectorization v0.12.141
  [1914dd2f] MacroTools v0.5.10
  [d125e4d3] ManualMemory v0.1.8
  [a3b82374] MatrixFactorizations v0.9.3
  [e9d8d322] Metatheory v1.3.5
  [128add7d] MicroCollections v0.1.3
  [e1d29d7a] Missings v1.0.2
  [961ee093] ModelingToolkit v8.36.0
  [46d2c3a1] MuladdMacro v0.2.4
  [102ac46a] MultivariatePolynomials v0.4.6
  [d8a4904e] MutableArithmetics v1.1.0
  [d41bc354] NLSolversBase v7.8.3
  [2774e3e8] NLsolve v4.5.1
  [872c559c] NNlib v0.8.11
  [77ba4419] NaNMath v1.0.1
  [fdc4e326] ODEProblemLibrary v0.1.4
  [6fe1bfb0] OffsetArrays v1.12.8
  [429524aa] Optim v1.7.4
  [bac558e1] OrderedCollections v1.4.1
  [1dea7af3] OrdinaryDiffEq v6.34.1
  [90014a1f] PDMats v0.11.16
  [d96e819e] Parameters v0.12.3
  [69de0a69] Parsers v2.5.1
  [e409e4f3] PoissonRandom v0.4.3
  [f517fe37] Polyester v0.6.18
  [1d0040c9] PolyesterWeave v0.1.11
  [2dfb63ee] PooledArrays v1.4.2
  [85a6dd25] PositiveFactorizations v0.2.4
  [d236fae5] PreallocationTools v0.4.4
  [21216c6a] Preferences v1.3.0
  [08abe8d2] PrettyTables v2.2.2
  [27ebfcd6] Primes v0.5.3
  [1fd47b50] QuadGK v2.6.0
  [74087812] Random123 v1.6.0
  [fb686558] RandomExtensions v0.4.3
  [e6cf234a] RandomNumbers v1.5.3
  [3cdcf5f2] RecipesBase v1.3.2
  [731186ca] RecursiveArrayTools v2.32.3
  [f2c3362d] RecursiveFactorization v0.2.12
  [189a3867] Reexport v1.2.2
  [42d2dcc6] Referenceables v0.1.2
  [ae029012] Requires v1.3.0
  [ae5879a3] ResettableStacks v1.1.1
  [79098fc4] Rmath v0.7.0
  [7e49a35a] RuntimeGeneratedFunctions v0.5.5
  [c72e72a9] SDEProblemLibrary v0.1.3
  [3cdde19b] SIMDDualNumbers v0.1.1
  [94e857df] SIMDTypes v0.1.0
  [476501e8] SLEEFPirates v0.6.37
  [0bca4576] SciMLBase v1.77.0
  [91c51154] SentinelArrays v1.3.16
  [efcf1570] Setfield v1.1.1
  [727e6d20] SimpleNonlinearSolve v0.1.2
  [699a6c99] SimpleTraits v0.9.4
  [66db9d55] SnoopPrecompile v1.0.1
  [a2af1166] SortingAlgorithms v1.1.0
  [47a9eef4] SparseDiffTools v1.29.0
  [276daf66] SpecialFunctions v2.1.7
  [171d559e] SplittablesBase v0.1.15
  [aedffcd0] Static v0.8.2
  [90137ffa] StaticArrays v1.5.11
  [1e83bf80] StaticArraysCore v1.4.0
  [82ae8749] StatsAPI v1.5.0
  [2913bbd2] StatsBase v0.33.21
  [4c63d2b9] StatsFuns v1.1.0
  [9672c7b4] SteadyStateDiffEq v1.9.1
  [789caeaf] StochasticDiffEq v6.57.3
⌅ [7792a7ef] StrideArraysCore v0.3.17
  [892a3eda] StringManipulation v0.3.0
  [c3572dad] Sundials v4.11.1
  [d1185830] SymbolicUtils v0.19.11
  [0c5d862f] Symbolics v4.13.0
  [3783bdb8] TableTraits v1.0.1
  [bd369af6] Tables v1.10.0
⌅ [8ea1fca8] TermInterface v0.2.3
  [8290d209] ThreadingUtilities v0.5.0
  [ac1d9e8a] ThreadsX v0.1.11
  [a759f4b9] TimerOutputs v0.5.22
  [0796e94c] Tokenize v0.5.24
  [3bb67fe8] TranscodingStreams v0.9.9
  [28d57a85] Transducers v0.4.75
  [a2a6695c] TreeViews v0.3.0
  [d5829a12] TriangularSolve v0.1.15
  [410a4b4d] Tricks v0.1.6
  [5c2747f8] URIs v1.4.1
  [3a884ed6] UnPack v1.0.2
  [1986cc42] Unitful v1.12.2
  [3d5dd08c] VectorizationBase v0.21.56
  [19fa3120] VertexSafeGraphs v0.2.0
  [ea10d353] WeakRefStrings v1.4.2
  [700de1a5] ZygoteRules v0.2.2
  [efe28fd5] OpenSpecFun_jll v0.5.5+0
  [f50d1b31] Rmath_jll v0.3.0+0
  [fb77eaff] Sundials_jll v5.2.1+0
  [0dad84c5] ArgTools v1.1.1
  [56f22d72] Artifacts
  [2a0f44e3] Base64
  [ade2ca70] Dates
  [8ba89e20] Distributed
  [f43a241f] Downloads v1.6.0
  [7b1f6079] FileWatching
  [9fa8497b] Future
  [b77e0a4c] InteractiveUtils
  [b27032c2] LibCURL v0.6.3
  [76f85450] LibGit2
  [8f399da3] Libdl
  [37e2e46d] LinearAlgebra
  [56ddb016] Logging
  [d6f4376e] Markdown
  [a63ad114] Mmap
  [ca575930] NetworkOptions v1.2.0
  [44cfe95a] Pkg v1.8.0
  [de0858da] Printf
  [3fa0cd96] REPL
  [9a3f8284] Random
  [ea8e919c] SHA v0.7.0
  [9e88b42a] Serialization
  [1a1011a3] SharedArrays
  [6462fe0b] Sockets
  [2f01184e] SparseArrays
  [10745b16] Statistics
  [4607b0f0] SuiteSparse
  [fa267f1f] TOML v1.0.0
  [a4e569a6] Tar v1.10.1
  [8dfed614] Test
  [cf7118a7] UUIDs
  [4ec0a83e] Unicode
  [e66e0078] CompilerSupportLibraries_jll v0.5.2+0
  [deac9b47] LibCURL_jll v7.84.0+0
  [29816b5a] LibSSH2_jll v1.10.2+0
  [c8ffd9c3] MbedTLS_jll v2.28.0+0
  [14a3606d] MozillaCACerts_jll v2022.2.1
  [4536629a] OpenBLAS_jll v0.3.20+0
  [05823500] OpenLibm_jll v0.8.1+0
  [bea87d4a] SuiteSparse_jll v5.10.1+0
  [83775a58] Zlib_jll v1.2.12+3
  [8e850b90] libblastrampoline_jll v5.1.1+0
  [8e850ede] nghttp2_jll v1.48.0+0
  [3f19e933] p7zip_jll v17.4.0+0
Info Packages marked with ⌅ have new versions available but compatibility constraints restrict them from upgrading. To see why use `status --outdated -m`
You can also download the manifest file and the project file.