Reorganize into submodules; finish docs (#10)

* move all ebm stuff to dedicated submodule

* add a todo folder

* rename limits function

* breaking change

* define default processes outside submodule

* finish (?) new docs centered on submodules

* need to do the default process thingy outside module scope

* allow start for sigmoid process

* better Tanh docstring

* mass rename SigmoidProcess

* improve sigmoid process

* great, using `init` works!

* finish first 3 subsections of tutorial

* finish tutorial

* finish globalmeanebm page

* show default variables in docs

* delete .gitub; use org wide

* fix incorrect function called in ice

* add back the .github repo

* fix tests

* fix examples

* fix all docs problems

* add submodule to doc build

.github/ISSUE_TEMPLATE/bug_report.md

@@ -1,27 +1,30 @@
 ---
-name: Bug report
-about: Create a report to help us improve
+name: Problem/bug report
+about: Create a report for incorrect/unexpected/erroring behavior
 title: ''
 labels: ''
 assignees: ''
 
 ---
 
-**Describe the bug**
-A clear and concise description of what the bug is.
+**Describe the problem**
+
+A clear and concise description of what the problem is, and what you were expecting to happen instead.
 
 **Minimal Working Example**
+
 Please provide a piece of code that leads to the bug you encounter.
 
-If the code is **runnable**, it will help us identify the problem faster.
+This code should be **runnable**, **self-contained**, and minimal. Remove all irrelevant dependencies
+and actively try to reduce the code to its smallest possible version.
+This will help us identify and fix the problem faster.
 
 **Package versions**
 
 Please provide the versions you use. To do this, run the code:
 ```julia
-using Pkg
-Pkg.status([
-    "Package1", "Package2"]; # etc.
+import Pkg
+Pkg.status(["Package1", "Package2"]; # etc.
     mode = PKGMODE_MANIFEST
 )
 ```

.github/ISSUE_TEMPLATE/feature_request.md

@@ -1,6 +1,6 @@
 ---
 name: Feature request
-about: Suggest an idea for this project
+about: Suggest a new feature for this project
 title: ''
 labels: ''
 assignees: ''

.github/workflows/CompatHelper.yml

@@ -1,24 +1,44 @@
 name: CompatHelper
-
 on:
   schedule:
-    - cron: '00 * * * *'
-
+    - cron: 0 0 * * *
+  workflow_dispatch:
+permissions:
+  contents: write
+  pull-requests: write
 jobs:
   CompatHelper:
-    runs-on: ${{ matrix.os }}
-    strategy:
-      matrix:
-        julia-version: [1]
-        julia-arch: [x86]
-        os: [ubuntu-latest]
+    runs-on: ubuntu-latest
     steps:
-      - uses: julia-actions/setup-julia@latest
+      - name: Check if Julia is already available in the PATH
+        id: julia_in_path
+        run: which julia
+        continue-on-error: true
+      - name: Install Julia, but only if it is not already available in the PATH
+        uses: julia-actions/setup-julia@v1
         with:
-          version: ${{ matrix.julia-version }}
-      - name: Pkg.add("CompatHelper")
-        run: julia -e 'using Pkg; Pkg.add("CompatHelper")'
-      - name: CompatHelper.main()
+          version: '1'
+          arch: ${{ runner.arch }}
+        if: steps.julia_in_path.outcome != 'success'
+      - name: "Add the General registry via Git"
+        run: |
+          import Pkg
+          ENV["JULIA_PKG_SERVER"] = ""
+          Pkg.Registry.add("General")
+        shell: julia --color=yes {0}
+      - name: "Install CompatHelper"
+        run: |
+          import Pkg
+          name = "CompatHelper"
+          uuid = "aa819f21-2bde-4658-8897-bab36330d9b7"
+          version = "3"
+          Pkg.add(; name, uuid, version)
+        shell: julia --color=yes {0}
+      - name: "Run CompatHelper"
+        run: |
+          import CompatHelper
+          CompatHelper.main()
+        shell: julia --color=yes {0}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: julia -e 'using CompatHelper; CompatHelper.main()'
+          COMPATHELPER_PRIV: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/TagBot.yml

@@ -12,4 +12,4 @@ jobs:
       - uses: JuliaRegistries/TagBot@v1
         with:
           token: ${{ secrets.GITHUB_TOKEN }}
-          ssh: ${{ secrets.DOCUMENTER_KEY }}
+          ssh: ${{ secrets.DOCUMENTER_KEY }}

.github/workflows/doccleanup.yml

@@ -23,4 +23,4 @@ jobs:
               git push --force origin gh-pages-new:gh-pages
             fi
         env:
-            PRNUM: ${{ github.event.number }}
+            PRNUM: ${{ github.event.number }}

.github/workflows/documentation.yml

@@ -22,5 +22,5 @@ jobs:
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # If authenticating with GitHub Actions token
-          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key
-        run: julia --project=docs/ docs/make.jl
+          DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # If authenticating with SSH deploy key for using TagBot
+        run: julia --project=docs/ docs/make.jl

.github/workflows/ci.yml → .github/workflows/test_coverage.yml

@@ -1,4 +1,4 @@
-name: CI
+name: CI - test & coverage
 on:
   pull_request:
     branches:

Project.toml

@@ -1,7 +1,7 @@
 name = "ConceptualClimateModels"
 uuid = "3e640dcb-3446-4ed7-aadb-0366b77312ec"
 authors = ["Datseris <[email protected]>"]
-version = "0.1.3"
+version = "0.2.0"
 
 [deps]
 DynamicalSystemsBase = "6e36e845-645a-534a-86f2-f5d4aa5a06b4"

docs/make.jl

@@ -1,6 +1,7 @@
 cd(@__DIR__)
 
 using ConceptualClimateModels
+using ConceptualClimateModels.GlobalMeanEBM
 
 import Downloads
 Downloads.download(
@@ -12,7 +13,9 @@ include("build_docs_with_style.jl")
 pages =  [
     "Introduction" => "index.md",
     "Tutorial" => "tutorial.md",
-    "Predefined processes" => "processes.md",
+    "Submodules" => [
+        "Global mean EBM" => "submodules/globalmeanebm.md",
+    ],
     "Examples" => "examples.md",
     "References" => "references.md",
 ]
@@ -24,7 +27,7 @@ bib = CitationBibliography(
     style=:authoryear
 )
 
-build_docs_with_style(pages, ConceptualClimateModels, ProcessBasedModelling;
+build_docs_with_style(pages, ConceptualClimateModels, GlobalMeanEBM, ProcessBasedModelling;
     authors = "George Datseris <[email protected]>",
     bib, warnonly = [:doctest, :missing_docs, :cross_references],
     repo = Remotes.GitHub("JuliaDynamics", "ConceptualClimateModels.jl")

docs/src/examples.md

@@ -18,7 +18,7 @@ We will combine the processes:
 
 ```@example MAIN
 using ConceptualClimateModels
-using ConceptualClimateModels.CCMV
+using ConceptualClimateModels.GlobalMeanEBM
 
 budyko_processes = [
     BasicRadiationBalance(),
@@ -30,7 +30,7 @@ budyko_processes = [
     # absorbed solar radiation has a default process
 ]
 
-budyko = processes_to_coupledodes(budyko_processes)
+budyko = processes_to_coupledodes(budyko_processes, GlobalMeanEBM)
 println(dynamical_system_summary(budyko))
 ```
 
@@ -44,10 +44,10 @@ For setting up the continuation we leverage the integration with DynamicalSystem
 ```@example MAIN
 using DynamicalSystems
 
-grid = physically_plausible_grid(budyko)
+grid = plausible_grid(budyko)
 mapper = AttractorsViaRecurrences(budyko, grid)
 rfam = RecurrencesFindAndMatch(mapper)
-sampler = physically_plausible_ic_sampler(budyko)
+sampler = plausible_ic_sampler(budyko)
 sampler() # randomly sample initial conditions
 ```
 
@@ -61,7 +61,7 @@ index = :ε_0
 Now we perform the continuation versus the effective emissivity, to approximate increasing or decreasing the strength of the greenhouse effect:
 ```@example MAIN
 εrange = 0.3:0.01:0.8
-fractions_curves, attractors_info = continuation(
+fractions_curves, attractors_info = global_continuation(
     rfam, εrange, index, sampler;
     samples_per_parameter = 1000,
     show_progress = false,
@@ -85,7 +85,7 @@ dependent variable instead, like so:
 
 ```@example MAIN
 using ConceptualClimateModels
-using ConceptualClimateModels.CCMV
+using ConceptualClimateModels.GlobalMeanEBM
 
 @variables η1(t)
 @parameters η1_0 = 2.0 # starting value for η1 parameter
@@ -96,7 +96,7 @@ processes = [
     η1 ~ η1_0 + r_η*t, # this symbolic variable has its own equation!
 ]
 
-stommel = processes_to_coupledodes(processes)
+stommel = processes_to_coupledodes(processes, GlobalMeanEBM)
 println(dynamical_system_summary(stommel))
 ```
 
@@ -106,15 +106,15 @@ estimate its bifurcation diagram using the same steps as the above example.
 ```@example MAIN
 using DynamicalSystems
 
-grid = physically_plausible_grid(stommel)
+grid = plausible_grid(stommel)
 mapper = AttractorsViaRecurrences(stommel, grid;
     consecutive_recurrences = 1000, attractor_locate_steps = 10,
 )
 rfam = RecurrencesFindAndMatch(mapper)
-sampler = physically_plausible_ic_sampler(stommel)
+sampler = plausible_ic_sampler(stommel)
 
 ηrange = 2.0:0.01:4.0
-fractions_curves, attractors_info = continuation(
+fractions_curves, attractors_info = global_continuation(
     rfam, ηrange, η1_0, sampler;
     samples_per_parameter = 1000,
     show_progress = false,
@@ -159,14 +159,3 @@ fig
 As you can see from the figure, depending on the rate the system either "tracks"
 the fixed point of high ΔΤ or it collapses down to the small ΔT branch.
 This happens because the system crosses the unstable manifold of the lower branch [Datseris2022; Chap. 12](@cite).
-To visualize the unstable manifold we could use BifurcationKit.jl, however,
-it is very inconvenient to do so, because BifurcationKit.jl does not provide most of the conveniences
-that DynamicalSystems.jl does. For example, it does not integrate well enough with
-DifferentialEquations.jl (to allow passing `ODEProblem` which is created by `DynamicalSystem`).
-It also does not allow indexing parameters by their symbolic bindings.
-Lastly, it does not work with models generated with ModelingToolkit.jl so we would
-have to re-write all the equations that the chosen `processes` made for us.
-
-## Glacial oscillations
-
-Coming soon!

docs/src/index.md

@@ -5,29 +5,14 @@ ConceptualClimateModels
 ```
 
 To get started with ConceptualClimateModels.jl see the [tutorial](@ref tutorial).
-Predefined processes that can be part of a model are in the
-[predefined processes](@ref predefined_processes) page.
+Predefined processes that can be part of a model are in individual module pages
+(see "predefined processes" on the side bar).
 See the [examples](@id examples) for a couple of applications.
 
 ## [Asking questions](@id ask_questions)
 
-There are three options for asking questions:
-
-1. As a new post in the official [Julia discourse](https://discourse.julialang.org/) and ask a question under the category Specific Domains > Modelling & Simulations, also using `dynamical-systems` as a tag.
-2. As a message in our channel `#dynamics-bridged` in the [Julia Slack](https://julialang.org/slack/) workplace.
-3. By opening an issue directly on the GitHub page of DynamicalSystems.jl while providing a Minimal Working Example. This is the most useful approach when you encounter unexpected behaviour.
+See <https://github.com/JuliaDynamics/.github/blob/main/SUPPORT.md>.
 
 ## Contributing
 
-There are many ways to contribute to ConceptualClimateModels.jl:
-
-1. Just *use it*! Share it with your colleagues if it was useful for you, and report
-   unexpected behaviour if you find any.
-2. Suggest processes that you think should be included in our library. This should be
-   done by opening a new GitHub issue that describes the process and gives references to papers using the method.
-3. Contribute code by adding new documentation examples.
-4. Contribute code by implementing new processes! That is by far the most impactful
-   way to contribute to the library.
-
-Contributed code must be documented per the standards of
-[DynamicalSystems.jl](https://juliadynamics.github.io/DynamicalSystemsDocs.jl/dynamicalsystems/dev/contributors_guide/#Documentation-string-style).
+See <https://github.com/JuliaDynamics/.github/blob/main/CONTRIBUTING.md>.