change coupledsde documentation page

Project.toml

@@ -1,5 +1,6 @@
 name = "CriticalTransitions"
 uuid = "251e6cd3-3112-48a5-99dd-66efcfd18334"
+authors = ["Reyk Börner, Ryan Deeley, Raphael Römer, Orjan Ameye"]
 repo = "https://github.com/juliadynamics/CriticalTransitions.jl.git"
 version = "0.3.0"
 

docs/Project.toml

@@ -5,7 +5,9 @@ ChaosTools = "608a59af-f2a3-5ad4-90b4-758bdf3122a7"
 CriticalTransitions = "251e6cd3-3112-48a5-99dd-66efcfd18334"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
 
+
 [compat]
 Documenter = "1"

docs/make.jl

@@ -1,32 +1,51 @@
-push!(LOAD_PATH, "../src/")
-
 using Documenter
 using DocumenterCitations
+using DocumenterInterLinks
+using Pkg
 
 using CriticalTransitions, ChaosTools, Attractors
 using CairoMakie
 
+project_toml = Pkg.TOML.parsefile(joinpath(@__DIR__, "..", "Project.toml"))
+package_version = project_toml["version"]
+name = project_toml["name"]
+authors = join(project_toml["authors"], ", ") * " and contributors"
+github = "https://github.com/juliadynamics/CriticalTransitions.jl"
+
+links = InterLinks(
+    "DiffEqNoiseProcess" => "https://docs.sciml.ai/DiffEqNoiseProcess/stable/",
+    "DifferentialEquations" => "https://docs.sciml.ai/DiffEqDocs/stable/",
+    "StochasticDiffEq" => "https://docs.sciml.ai/DiffEqDocs/stable/",
+)
+
 bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"); style=:numeric)
+
 include("pages.jl")
 
+html_options = Dict(
+    :prettyurls => true,
+    :canonical => "https://juliadynamics.github.io/CriticalTransitions.jl/",
+    :mathengine => Documenter.MathJax2(),
+)
+
+if Documenter.DOCUMENTER_VERSION >= v"1.3.0"
+    html_options[:inventory_version] = package_version
+end
+
 makedocs(;
+    authors=authors,
     sitename="CriticalTransitions.jl",
-    repo=Documenter.Remotes.GitHub("JuliaDynamics", "CriticalTransitions.jl"),
+    linkcheck=true,
     modules=[
         CriticalTransitions,
         Base.get_extension(CriticalTransitions, :ChaosToolsExt),
         Base.get_extension(CriticalTransitions, :CoupledSDEsBaisin),
     ],
     doctest=false,
-    format=Documenter.HTML(;
-        canonical  = "https://juliadynamics.github.io/CriticalTransitions.jl/",
-        prettyurls = true,
-        mathengine = Documenter.MathJax2(),
-    ),
-    linkcheck=true,
+    format=Documenter.HTML(; html_options...),
     warnonly=[:doctest, :missing_docs, :cross_references, :linkcheck],
     pages=pages,
-    plugins=[bib],
+    plugins=[bib, links],
 )
 
 deploydocs(; repo="github.com/JuliaDynamics/CriticalTransitions.jl.git", push_preview=false)

docs/pages.jl

@@ -9,7 +9,6 @@ pages = [
         "Simulating the system" => "man/simulation.md",
         "Sampling transitions" => "man/sampling.md",
         "Large deviation theory" => "man/largedeviations.md",
-        "Noise processes" => "man/noise.md",
         "Utilities" => "man/utils.md",
     ],
     "Predefined systems" => "man/systems.md",

docs/src/man/CoupledSDEs.md

@@ -1,27 +1,51 @@
 # Define a CoupledSDE
-<!--
+
 A `CoupledSDEs` defines a stochastic dynamical system of the form
 
-``\text{d}\vec x = f(\vec x(t); \ p_f)  \text{d}t + \sigma g(\vec x(t);  \ p_g)  \Gamma \cdot \text{d}\mathcal{N} \ ,``
+``\text{d}\vec x = f(\vec x(t); \ p)  \text{d}t + g(\vec x(t);  \ p) \text{d}\mathcal{W} \ ,``
+where $\text{d}\mathcal{W}=\Gamma \cdot \text{d}\mathcal{N}$, $\vec x \in \mathbb{R}^\text{dim}$ and $\mathcal N$ denotes a stochastic process. The (positive definite) noise covariance matrix is $\Sigma = \Gamma \Gamma^\top \in \mathbb R^{N\times N}$.
 
-where $\vec x \in \mathbb{R}^\text{dim}$, $\Sigma = \Gamma \Gamma^\top \in \mathbb R^{N\times N}$ is the (positive definite) noise covariance matrix and $\mathcal N$ denotes a stochastic process.
+The function $f$ is the deterministic part of the system and is assumed to be of similar form as is accepted in [DynamicalSystems.jl](https://juliadynamics.github.io/DynamicalSystems.jl/latest/tutorial/), i.e., `f(u, p, t)` for out-of-place (oop) and `f(du, u, p, t)` for in-place (iip).
 
-An instance of StochSystem is created via `StochSystem(f, pf, u [, σ [, g, pg, Σ , process]])`,
-taking the following arguments:
-* `f` (Function): Dynamical ODE rule describing the drift term of the system, corresponding to `f` in the ODEProblem of `DifferentialEquations`. Can be defined in-place (`f!(du, u, p, t)`) or out-of-place (`f(u,p,t)`).
-* `pf` (Vector or Nothing): Parameter vector for the drift term.
-* `u` (State): Initial state. E.g. `zeros(dim)`, where `dim` is the system's dimensionality. 
-* `σ` (Float64): Noise intensity. Defaults to `1.0`.
-* `g` (Function): Dynamical ODE rule describing the noise term of the system. Same format as `f`. Defaults to `idfunc`.
-* `pg` (Vector or Nothing): Parameter vector of the noise term.
-* `Σ` (Matrix): Noise covariance matrix. Defaults to `I` (identity matrix).
-* `process` (String): Noise process. Defaults to `white-gauss` (independent n-dimensional Brownian motion).
+The function $g$ represent the stochastics dynamics of the system and should be the of the same type (iip or oop) as $f$. The keyword `noise` defines the system [noise process](#noise-process). In combination with `g` one can define different type of stochastic systems. Examples of different type of stochastics systems can be found on the [StochasticDiffEq.jl tutorial page](https://docs.sciml.ai/DiffEqDocs/stable/tutorials/sde_example/). A quick overview of the different types of stochastic systems can be found [here](#Type-of-stochastic-system).
 
-### Shortcut methods
-* `StochSystem(f, pf, u)`
-* `StochSystem(f, pf, u, σ)`
-* `StochSystem(f, pf, u, σ, Σ)` -->
 
 ```@docs
 CoupledSDEs
-```
+```
+## Type of stochastic system
+
+```@example type
+using CriticalTransitions
+
+function meier_stein!(du, u, p, t) # out-of-place
+    x, y = u
+    du[1] = x - x^3 - 10 * x * y^2
+    dv[2] = -(1 + x^2) * y
+    return
+end
+σ = 0.1
+```
+
+### Diagonal noise
+that is a vector of random numbers dW whose size matches the output of g where the noise is applied element-wise,
+### scalar noise
+ scalar noise where a single random variable is applied to all dependent variables
+### Non-diagonal noise
+ more general type of noise allows for the terms to linearly mixed via g being a matrix.
+
+ In our `g` we define the functions for computing the values of the matrix.
+We can now think of the SDE that this solves as the system of equations
+
+```math
+du_1 = f_1(u,p,t)dt + g_{11}(u,p,t)dW_1 + g_{12}(u,p,t)dW_2 \\
+du_2 = f_2(u,p,t)dt + g_{21}(u,p,t)dW_1 + g_{22}(u,p,t)dW_2
+```
+
+
+!!! info
+    Note that nonlinear mixings are not Stochasitic Differential Equations but are a different class of differential equations of random ordinary differential equations (RODEs) which have a separate set of solvers. See this example of [DiffernetialEquations.jl](@exref rode_example).
+### Corelated noise
+
+## Noise process
+We provide the noise processes $text{d}\mathcal{W}$ that can be used in the stochastic simulations through the [DiffEqNoiseProcess.jl](https://docs.sciml.ai/DiffEqNoiseProcess/stable) package. A complete list of the available processes can be found [here](https://docs.sciml.ai/DiffEqNoiseProcess/stable/noise_processes/). We list some of the most common ones below:

src/CoupledSDEs.jl

@@ -35,7 +35,33 @@ coupled ordinary differential equations as follows:
 ```math
 d\\vec{u} = \\vec{f}(\\vec{u}, p, t) dt + \\vec{g}(\\vec{u}, p, t) dW_t
 ```
-An alias for `CoupledSDEs` is `ContinuousDynamicalSystem`.
+
+Optionally provide the parameter container `p` and initial time as keyword `t0`.
+
+For construction instructions regarding `f, u0` see the [DynamicalSystems.jl tutorial](https://juliadynamics.github.io/DynamicalSystems.jl/latest/tutorial/#DynamicalSystemsBase.CoupledODEs).
+
+The stochastic part of the differential equation is defined by the function `g` and the keyword arguments `noise_rate_prototype` and `noise`. `noise` indicates the noise process applied during generation and defaults to Gaussian white noise. For details on defining various noise processes, refer to the noise process documentation page. `noise_rate_prototype` indicates the prototype type instance for the noise rates, i.e., the output of `g`. It can be any type which overloads `A_mul_B!` with itself being the middle argument. Commonly, this is a matrix or sparse matrix. If this is not given, it defaults to `nothing`, which means the problem should be interpreted as having diagonal noise.
+
+## DifferentialEquations.jl interfacing
+
+The ODEs are evolved via the solvers of DifferentialEquations.jl.
+When initializing a `CoupledODEs`, you can specify the solver that will integrate
+`f` in time, along with any other integration options, using the `diffeq` keyword.
+For example you could use `diffeq = (abstol = 1e-9, reltol = 1e-9)`.
+If you want to specify a solver, do so by using the keyword `alg`, e.g.:
+`diffeq = (alg = Tsit5(), reltol = 1e-6)`. This requires you to have been first
+`using OrdinaryDiffEq` to access the solvers. The default `diffeq` is:
+
+$(DynamicalSystemsBase.DEFAULT_DIFFEQ)
+
+`diffeq` keywords can also include `callback` for [event handling
+](http://docs.juliadiffeq.org/latest/features/callback_functions.html).
+
+Dev note: `CoupledSDEs` is a light wrapper of  `StochasticDiffEq.SDEIntegrator` from DifferentialEquations.jl.
+The integrator is available as the field `integ`, and the `SDEProblem` is `integ.sol.prob`.
+The convenience syntax `SDEProblem(ds::CoupledSDEs, tspan = (t0, Inf))` is available
+to extract the problem.
+```
 """
 struct CoupledSDEs{IIP,D,I,P} <: ContinuousTimeDynamicalSystem
     # D parametrised by length of u0

test/CoupledSDEs.jl

@@ -11,7 +11,7 @@
     @testset "diagonal additive noise" begin
         # diagonal additive noise: σ*N(0,dt)
         # a vector of random numbers dW whose size matches the output of g where the noise is applied element-wise
-        prob = SDEProblem(meier_stein, diag_noise_function(σ), zeros(2), (0.0, Inf))
+        prob = SDEProblem(meier_stein, diag_noise_function(σ), zeros(2), (0.0, 1.0))
         sde = CoupledSDEs(meier_stein, diag_noise_function(σ), zeros(2))
 
         @test sde.integ.sol.prob.f == prob.f