Added Advanced SDE example and a table of SRKs

Author: andyElking

docs/api/solvers/sde_solvers.md

@@ -1,6 +1,9 @@
 # SDE solvers
 
-See also [How to choose a solver](../../usage/how-to-choose-a-solver.md#stochastic-differential-equations).
+See also [How to choose a solver](../../usage/how-to-choose-a-solver.md#stochastic-differential-equations)
+and [Advanced SDE example](../../examples/sde_example.ipynb) which gives a walkthrough of how to simulate SDEs
+and how to perform optimisation with respect to SDE parameters.
+For a table of all SDE solvers and their properties see [SDE solver table](../../devdocs/SDE_solver_table.md).
 
 !!! info "Term structure"
 

docs/devdocs/SDE_solver_table.md

@@ -0,0 +1,46 @@
+# SDE solver table
+
+For an explanation of the terms in the table, see [how to choose a solver](../usage/how-to-choose-a-solver.md#stochastic-differential-equations).
+
+This table is included as a reference that we think *should* be correct, but if you're going to use any of this information in a load-bearing way (for example a publication) then please double-check the information! It's a big table, we might have gotten something wrong.
+
+```
++----------------+-------+------------+------------------------------------+-------------------+----------------+------------------------------------------+
+|                | SDE   | Lévy       | Strong/weak order (per noise type) | VF evaluations    | Embedded error | Recommended for                          |
+|                | type  | area       +----------+--------------+----------+-------+-----------+ estimation     | (and other notes)                        |
+|                |       |            | General  | Commutative  | Additive | Drift | Diffusion |                |                                          |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| Euler          | Itô   | BM only    | 0.5/1.0  | 0.5/1.0      | 1.0/1.0  | 1     | 1         | No             | Itô SDEs when a cheap solver is needed.  |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| Heun           | Strat | BM only    | 0.5/1.0  | 1.0/1.0      | 1.0/1.0  | 2     | 2         | Yes            | Standard solver for Stratonovich SDEs.   |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| EulerHeun      | Strat | BM only    | 0.5/1.0  | 0.5/1.0      | 1.0/1.0  | 1     | 2         | No             | Stratonovich SDEs with expensive drift.  |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| ItoMilstein    | Itô   | BM only    | 0.5/1.0  | 1.0/1.0      | 1.0/1.0  | 1     | 1         | No             | Better than Euler for Itô SDEs, but      |
+|                |       |            |          |              |          |       |           |                | comuptes the derivative of diffusion VF. |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| Stratonovich   | Strat | BM only    | 0.5/1.0  | 1.0/1.0      | 1.0/1.0  | 1     | 1         | No             | For commutative Stratonovich SDEs when   |
+| Milstein       |       |            |          |              |          |       |           |                | space-time Lévy area is not available.   |
+|                |       |            |          |              |          |       |           |                | Computes derivative of diffusion VF.     |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| ReversibleHeun | Strat | BM only    | 0.5/1.0  | 1.0/1.0      | 1.0/1.0  | 2     | 2         | Yes            | When a reversible solver is needed.      |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| Midpoint       | Strat | BM only    | 0.5/1.0  | 1.0/1.0      | 1.0/1.0  | 2     | 2         | Yes            | Usually Heun should be preferred.        |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| Ralston        | Strat | BM only    | 0.5/1.0  | 1.0/1.0      | 1.0/1.0  | 2     | 2         | Yes            | Usually Heun should be preferred.        |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| ShARK          | Strat | space-time | /        | /            | 1.5/2.0  | 2     | 2         | Yes            | Additive noise SDEs.                     |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| SRA1           | Strat | space-time | /        | /            | 1.5/2.0  | 2     | 2         | Yes            | Only slightly worse than ShARK.          |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| SEA            | Strat | space-time | /        | /            | 1.0/1.0  | 1     | 1         | No             | Cheap solver for additive noise SDEs.    |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| SPaRK          | Strat | space-time | 0.5/1.0  | 1.0/1.0      | 1.5/2.0  | 3     | 3         | Yes            | General SDEs when embedded error         |
+|                |       |            |          |              |          |       |           |                | estimation is needed.                    |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| GeneralShARK   | Strat | space-time | 0.5/1.0  | 1.0/1.0      | 1.5/2.0  | 2     | 3         | No             | General SDEs when embedded error         |
+|                |       |            |          |              |          |       |           |                | estimaiton is not needed.                |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+| SlowRK         | Strat | space-time | 0.5/1.0  | 1.5/2.0      | 1.5/2.0  | 2     | 5         | No             | Commutative noise SDEs.                  |
++----------------+-------+------------+----------+--------------+----------+-------+-----------+----------------+------------------------------------------+
+```

docs/examples/sde_example.ipynb

@@ -123,6 +123,7 @@ nav:
         - Second-order sensitivities: 'examples/hessian.ipynb'
         - Nonlinear heat PDE: 'examples/nonlinear_heat_pde.ipynb'
         - Underdamped Langevin diffusion: 'examples/underdamped_langevin_example.ipynb'
+        - Advanced SDE simulation example: 'examples/sde_example.ipynb'
     - Basic API:
         - 'api/diffeqsolve.md'
         - Solvers:
@@ -150,3 +151,4 @@ nav:
             - 'devdocs/predictor_dirk.md'
             - 'devdocs/adjoint_commutative_noise.md'
             - Stochastic Runge-Kutta methods: 'devdocs/srk_example.ipynb'
+            - Table of SDE solvers: 'devdocs/SDE_solver_table.md'