Add toy example to docs index.md

docs/Project.toml

@@ -1,5 +1,7 @@
 [deps]
+CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+MDEforM = "25eb15a5-a415-4ff1-88da-9d529a0202cf"
 
 [compat]
 Documenter = "1.6"

docs/build/.documenter-siteinfo.json

@@ -1 +1 @@
-{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-08-30T18:08:54","documenter_version":"1.6.0"}}
+{"documenter":{"julia_version":"1.10.5","generation_timestamp":"2024-09-05T17:23:59","documenter_version":"1.7.0"}}

docs/src/index.md

@@ -18,6 +18,92 @@ julia> using MDEforM
 The functions listed under [Index](@ref Index_index) are exported by the module and thorough documentation of these functions 
 can be found in the following list of [Contents](@ref Contents_index).
 
+## Toy Example
+
+We want to provide a small example to illustrate the main functionality of the module. We start from the following 2-dimensional fast-slow system of stochastic differential equations (SDE)
+```math
+\begin{aligned}
+  dX_ϵ(t) = -α V'(X_ϵ(t)) - \frac{1}{ϵ} p'\left( \frac{X_ϵ(t)}{ϵ} \right) dt  + \sqrt{2 σ} dU(t), \quad &X_ϵ(0) = x_0, \\
+  dY_ϵ(t) = -\frac{α}{ϵ} V'(X_ϵ(t)) - \frac{1}{ϵ^2} p'\left( Y_ϵ(t) \right) dt  + \sqrt{\frac{2 σ}{ϵ^2}} dU(t), \quad &Y_ϵ(0) = y_0.
+\end{aligned}
+```
+Here, ``V`` is a so-called large-scale potential, ``p`` is a ``2\pi``-periodic function, ``U`` is a standard Brownian motion, and the parameters ``\alpha, \sigma, \epsilon`` are strictly positive. An examplatory function constellation for ``V`` and ``p`` is provided by the function [`NLDO`](@ref).
+
+Here is a self-explanatory graphic of ``V`` and ``V + p``:
+
+```@setup potential_graphic
+using CairoMakie
+
+ϵ = 0.1
+V(x) = -x^2 + x^4/12
+p(x) = sin(x/ϵ)
+x_range = range(-4,4,2000)
+
+# create and adjust figure components; using CairoMakie.jl here
+drift_fig = Figure(size=(3840,2160), fontsize = 50)
+drift_ax = Axis(drift_fig[1, 1],
+  # x-axis
+  xlabel = L"x",
+  xticks = LinearTicks(5),
+  # y-axis
+  yticks = LinearTicks(5),
+)
+Makie.xlims!(drift_ax, x_range[1], x_range[end])
+colsize!(drift_fig.layout, 1, Aspect(1, 1.8))
+  
+
+V_line = lines!(drift_ax, x_range, map(V, x_range), linewidth = 10.0, color = (:darkgrey, 1.0), linestyle = :dash)
+Vp_line = lines!(drift_ax, x_range, map(x->V(x)+p(x), x_range), linewidth = 3.0, color = (:black, 1.0))
+
+axislegend(drift_ax,
+[V_line, Vp_line],
+[L"$x^4/12-x^2$", L"$x^4/12 - x^2 + \sin(x/%$ϵ)$"],
+labelsize = 80
+)
+```
+
+```@example potential_graphic
+drift_fig   # hide
+```
+
+When ``\epsilon`` converges to zero, then, by homogenization theory, the process ``X_\epsilon`` converges weakly in ``C([0, T]; \R)`` to the process ``X`` solving the SDE
+```math
+\begin{aligned}
+  dX(t) = -α K V'(X(t)) dt  + \sqrt{2 σ K} dW(t), \quad &X(0) = X_0,
+\end{aligned}
+```
+where ``K>0`` is a corrective constant that comes from the cell problem of the homogenization, see also [`K`](@ref). The task is to estimate the parameter ``\vartheta := \alpha K`` 
+through data that comes in form of a long trajectory of the process ``X_\epsilon`` with "small" ``\epsilon > 0``. We will use the [`MDE`](@ref) for the estimation. First, we generate synthetic
+data with the function [`Langevin_ϵ`](@ref). The plot of a trajectory, created with [`produce_trajectory_1D`](@ref), looks like the following.
+```@example
+# quadratic potential V with sine oscillation p
+using MDEforM   # hide
+T = 10
+trajectory = Langevin_ϵ(5.0, func_config=LDO(), α=2.0, σ=1.0, ϵ=0.1, T=T)
+fig = produce_trajectory_1D(trajectory, T)
+```
+
+We now increase the time horizon ``T`` to obtain accurate estimates for ``\vartheta``.
+```@example toy_example
+using MDEforM   # hide
+import Random   # hide
+Random.seed!(1111)  # hide
+data = Langevin_ϵ(5.0, func_config=LDO(), α=2.0, σ=1.0, ϵ=0.1, T=1000)[1]   # only slow process
+nothing # hide
+```
+Under this configuration the true parameter ``\vartheta`` is given by
+```@example
+using MDEforM   # hide
+ϑ = 2.0*K(LDO()[3], 1.0)
+```
+We can now use the MDE to estimate ``\vartheta``. Due to parameter identification issues we must also provide the limit diffusion parameter ``\Sigma := \sigma K`` as input.
+```@example toy_example
+MDE_value = MDE(data, "Langevin", 1.0*K(LDO()[3], 1.0), 10.0)
+```
+
+As we can see the MDE is capable of retrieving the true parameter with multiscale data.
+
+
 ## [Contents](@id Contents_index)
 
 ```@contents