add FitzHugh SDE example (#244)

* add FitzHugh SDE example

* add stocahstieq to doc deps

* also show attractors

* Update Project.toml

Project.toml

@@ -1,7 +1,7 @@
 name = "DynamicalSystems"
 uuid = "61744808-ddfa-5f27-97ff-6e42cc95d634"
 repo = "https://github.com/JuliaDynamics/DynamicalSystems.jl.git"
-version = "3.3.21"
+version = "3.3.22"
 
 [deps]
 Attractors = "f3fd9213-ca85-4dba-9dfd-7fc91308fec7"
@@ -30,7 +30,7 @@ ChaosTools = "3"
 ComplexityMeasures = "2, 3"
 DataStructures = "0.18"
 DelayEmbeddings = "2.7"
-DynamicalSystemsBase = "3.8.3"
+DynamicalSystemsBase = "3.11.0"
 FractalDimensions = "1"
 Makie = "≥ 0.19"
 PredefinedDynamicalSystems = "1"

docs/Project.toml

@@ -16,3 +16,4 @@ StateSpaceSets = "40b095a5-5852-4c12-98c7-d43bf788e795"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
 FractalDimensions = "4665ce21-e117-4649-aed8-08bbe5ccbead"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
+StochasticDiffEq = "789caeaf-c7a9-5a7d-9973-96adeb23e2a0"

docs/src/tutorial.jl

@@ -290,7 +290,60 @@ basins, attractors = basins_of_attraction(mapper; show_progress = false)
 
 heatmap_basins_attractors((xg, yg), basins, attractors)
 
-# One last thing to highlight in this short overview are the interactive GUI apps one
+# ## Stochastic systems
+
+# DynamicalSystems.jl has some support for stochastic systems
+# in the form of Stochastic Differential Equations (SDEs).
+# Just like `CoupledODEs`, one can make `CoupledSDEs`!
+# For example here is a stochastic version of a FitzHugh-Nagumo model
+
+using StochasticDiffEq # load extention for `CoupledSDEs`
+
+function fitzhugh_nagumo(u, p, t)
+    x, y = u
+    ϵ, β, α, γ, κ, I = p
+    dx = (-α * x^3 + γ * x - κ * y + I) / ϵ
+    dy = -β * y + x
+    return SVector(dx, dy)
+end
+p = [1.,3.,1.,1.,1.,0.]
+sde = CoupledSDEs(fitzhugh_nagumo, zeros(2), p; noise_strength = 0.05)
+
+# In this particular example the SDE noise is white noise (Wiener process)
+# with strength (σ) of 0.05. See the documentation of `CoupledSDEs` for alternatives.
+
+# In any case, in DynamicalSystems.jl all dynamical systems are part of the same
+# interace, stochastic or not. As long as the algorithm is not influenced by stochasticity,
+# we can apply it to `CoupledSDEs` just as well. For example, we can study multistability
+# in a stochastic system. In contrast to the previous example of the Henon map,
+# we have to use an alternative algorithm, because `AttractorsViaRecurrences`
+# only works for deterministic systems. So instead we'll use `AttractorsViaFeaturizing`:
+
+featurizer(X, t) = X[end]
+
+mapper = AttractorsViaFeaturizing(sde, featurizer; Ttr = 200, T = 10)
+
+xg = yg = range(-1, 1; length = 101)
+
+sampler, _ = statespace_sampler((xg, yg))
+
+fs = basins_fractions(mapper, sampler)
+
+# and we can see the stored "attractors"
+
+attractors = extract_attractors(mapper)
+fig, ax = scatter(attractors[1])
+scatter!(attractors[2])
+fig
+
+# The mathematical concept of attractors
+# doesn't translate trivially to stochastic systems but thankfully
+# this system has two fixed point attractors that are only mildly perturbed
+# by the noise.
+
+# ## Interactive GUIs
+
+# A particularly useful feature are interactive GUI apps one
 # can launch to examine a `DynamicalSystem`. The simplest is [`interactive_trajectory_timeseries`](@ref).
 # To actually make it interactive one needs to enable GLMakie.jl as a backend: