From 46a696397b0725aeead813f606a4298e722b62e8 Mon Sep 17 00:00:00 2001
From: Datseris <datseris.george@gmail.com>
Date: Tue, 20 Feb 2024 13:15:55 +0000
Subject: [PATCH] finish docs: variables and integrations

---
 docs/src/index.md | 40 +++++++++++++++++++++++++++++++++++++---
 src/statespace.jl | 15 +++++++++++++++
 src/variables.jl  | 12 ++++++++----
 3 files changed, 60 insertions(+), 7 deletions(-)

diff --git a/docs/src/index.md b/docs/src/index.md
index 8865202..51b188c 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -1,20 +1,54 @@
 # EnergyBalanceModels.jl
 
-## Global symbolic variables
+## [Premade symbolic variable instances](@id global_vars)
 
-For convenience, EnergyBalanceModels.jl defines and exports these global variables:
+For convenience, EnergyBalanceModels.jl defines and exports some symbolic variables. These are used throughout the library as the default variables in [implemented processes](@id processes).
+When going through documentation strings of processes, such as [`BasicRadiationBalance`](@ref),
+you will notice that the function call signature is like:
+
+```julia
+BasicRadiationBalance(; T=T, kwargs...)
+```
+
+This `T=T` means that the keyword argument `T`, which represents the "temperature variable", takes the value of `EnergyBalanceModels.T`, which itself is a premade symbolic variable instance that is exported by EnergyBalanceModels.jl. You can pass in your own variables instead, by doing
+```julia
+@variables T1_tropics = 310.0
+BasicRadiationBalance(; T=T1_tropics, kwargs...)
+```
+
+The exported symbolic variables are:
 
 ```@example MAIN
 using EnergyBalanceModels
-GLOBAL_EBM_VARIABLES
+PREDEFINED_EBM_VARIABLES
 ```
 
 ## Default values, limits, etc.
 
+All [exported symbolic variable instances](@ref) are defiled with a default value and have plausible physical limits that can be obtained with the following function:
+
+```@docs
+physically_plausible_limits(::String)
+```
+
+e.g.,
+
+```@example MAIN
+physically_plausible_limits(T)
+```
+
+
 ## Integration with DynamicalSystems.jl
 
 EnergyBalanceModels.jl integrates with [DynamicalSystems.jl](https://juliadynamics.github.io/DynamicalSystemsDocs.jl/dynamicalsystems/dev/) in many ways.
 
+
+```@docs
+physically_plausible_limits(::DynamicalSystem)
+physically_plausible_ic_sampler
+physically_plausible_grid
+```
+
 # ## Utilities
 
 ```@docs
diff --git a/src/statespace.jl b/src/statespace.jl
index e3a5cf0..6362ab9 100644
--- a/src/statespace.jl
+++ b/src/statespace.jl
@@ -13,7 +13,14 @@ function physically_plausible_limits(ds::DynamicalSystem)
     return minmax
 end
 
+"""
+    physically_plausible_ic_sampler(ds::DynamicalSystem)
 
+Return a `sampler` that can be called as a 0-argument function `sampler()`, which
+yields random initial conditions within the hyperrectangle defined by the
+[`physically_plausible_limits`](@ref) of `ds`.
+The `sampler` is useful to give to e.g., `DynamicalSystems.basins_fractions`.
+"""
 function physically_plausible_ic_sampler(ds::DynamicalSystem)
     minmax = physically_plausible_limits(ds)
     mini = getindex.(minmax, 1)
@@ -22,6 +29,14 @@ function physically_plausible_ic_sampler(ds::DynamicalSystem)
     return sampler
 end
 
+"""
+    physically_plausible_grid(ds::DynamicalSystem, n = 101)
+
+Return a `grid` that is a tuple of `range` objects that each spans the
+[`physically_plausible_limits`](@ref) of `ds`.
+`n` can be an integer or a vector of integers (for each dimension).
+The resulting `grid` is useful to give to `DynamicalSystems.AttractorsViaRecurrences`.
+"""
 function physically_plausible_grid(ds::DynamicalSystem, n = 101)
     minmax = physically_plausible_limits(ds)
     if n isa Integer
diff --git a/src/variables.jl b/src/variables.jl
index 94580cc..3c59268 100644
--- a/src/variables.jl
+++ b/src/variables.jl
@@ -4,7 +4,7 @@
 # In the final generated energy balance model it is not necessary that all of these
 # will exist in the equations.
 
-const GLOBAL_EBM_VARIABLES = @variables begin
+const PREDEFINED_EBM_VARIABLES = @variables begin
     T(t) = 290.0       # [description = "temperature, in Kelvin"]
     S(t) = 1.0         # [description = "insolation in units relative to solar constant"]
     f(t) = 0.0         # [description = "external forcing, normalized to units of the solar constant"]
@@ -34,13 +34,17 @@ function physically_plausible_limits(var::String)::Tuple{Float64, Float64}
     if var[1] == 'T'
         return (200, 350)
     elseif var == "α_ice" || var == "α_clouds"
-        return (0, 0.75)
-    elseif var[1] == 'α' || var[1] == 'ε' || var[1] == 'C'
+        return (0, 0.5)
+    elseif var[1] == 'α' || var[1] == 'ε' || var[1] == 'C' || var[1] == 'ℓ'
         return (0, 1)
     elseif var == "ΔT"
         return (5.0, 60.0)
+    elseif var == "CO2"
+        return (200.0, 1600.0)
+    elseif !isnothing(default_value(var))
+        return (0.8default_value(var), 1.2default_value(var))
     else
-        error("Unpsecified plausible physical limits for $(var). "*
+        error("Unpsecified plausible physical limits for $(var) or no default value. "*
         "Please edit function `physically_plausible_limits` and add one.")
     end
 end