Merge #59

59: Improve convergence plots r=charleskawczynski a=charleskawczynski

This PR was pulled from [ClimateMachine.jl's 1885](CliMA/ClimateMachine.jl#1885), which improves the convergence plots for values outside of the tested profiles.

`@trontrytel,` we could add these same plots for the other thermo constructors to get an idea of the convergence manifold.

Co-authored-by: Charles Kawczynski <kawczynski.charles@gmail.com>

.github/workflows/DocCleanUp.yml

@@ -0,0 +1,28 @@
+name: Doc Preview Cleanup
+
+on:
+  pull_request:
+    types: [closed]
+
+jobs:
+  doc-preview-cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout gh-pages branch
+        uses: actions/checkout@v2
+        with:
+          ref: gh-pages
+
+      - name: Delete preview and history
+        run: |
+            git config user.name "Documenter.jl"
+            git config user.email "documenter@juliadocs.github.io"
+            git rm -rf "previews/PR$PRNUM"
+            git commit -m "delete preview"
+            git branch gh-pages-new $(echo "delete history" | git commit-tree HEAD^{tree})
+        env:
+            PRNUM: ${{ github.event.number }}
+
+      - name: Push changes
+        run: |
+            git push --force origin gh-pages-new:gh-pages

docs/Project.toml

@@ -5,5 +5,6 @@ DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 ExprTools = "e2ba6199-217a-4e67-a87a-7c52f15ade04"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
+RootSolvers = "7181ea78-2dcb-4de3-ab41-2b8ab5a31e74"
 Thermodynamics = "b60c26fb-14c3-4610-9d3e-2d17fe7ff00c"
 UnPack = "3a884ed6-31ef-47d7-9d2a-63182c4928ed"

docs/src/DevDocs.md

@@ -1,4 +1,7 @@
-# Input space exploration
+# Saturation adjustment input space convergence maps
+
+The saturation adjustment procedure requires solving a non-linear
+equation.
 
 In the [Tested Profiles](@ref) section, we plotted the tested thermodynamic
 states. In this section, we explore the convergence of the
@@ -11,18 +14,35 @@ or likely to be observed in climate simulations, but showing
 the convergence space helps illustrate the buffer between our
 tested profiles and the nearest space where convergence fails.
 
+This section is dedicated to monitoring the status and improvement
+of the performance and robustness of various numerical methods
+in solving the saturation adjustment equations for various thermodynamic
+formulations.
+
+!!! note
+
+    `dims` in `docs/src/saturation_adjustment.jl` is currently set to
+    ``dims = (6, 6, 6);`` to avoid heavy computations in the doc build, but you
+    may want to increase it to, e.g., ``dims = (10, 10, 10);`` when running locally
+    to see a higher resolution map.
+
 ```@example
-include(joinpath(@__DIR__, "..", "ThreeDimensionalInput.jl"))
+include("saturation_adjustment.jl")
 ```
 
-## Converged cases (3D view)
-![](Scatter3DConverged.svg)
-
-## Non-converged cases (3D view)
-![](Scatter3DNonConverged.svg)
+## 3D space
+| Numerical method  | Converged  |  Non-converged |
+:-----------------:|:-----------------:|:---------------------:
+SecantMethod | ![](3DSpace_converged_SecantMethod.svg)       |  ![](3DSpace_non_converged_SecantMethod.svg)
+NewtonsMethod | ![](3DSpace_converged_NewtonsMethod.svg)      |  ![](3DSpace_non_converged_NewtonsMethod.svg)
+NewtonsMethodAD | ![](3DSpace_converged_NewtonsMethodAD.svg)    |  ![](3DSpace_non_converged_NewtonsMethodAD.svg)
+RegulaFalsiMethod | ![](3DSpace_converged_RegulaFalsiMethod.svg)  |  ![](3DSpace_non_converged_RegulaFalsiMethod.svg)
 
-## Converged cases (2D view), binned by total specific humidity
-![](Slices2DConverged.svg)
+## 2D slices, binned by total specific humidity
 
-## Non-converged cases (2D view), binned by total specific humidity
-![](Slices2DNonConverged.svg)
+| Numerical method  | Converged  |  Non-converged |
+:-----------------:|:-----------------:|:---------------------:
+SecantMethod | ![](2DSlice_converged_SecantMethod.svg)  |  ![](2DSlice_non_converged_SecantMethod.svg)
+NewtonsMethod | ![](2DSlice_converged_NewtonsMethod.svg)  |  ![](2DSlice_non_converged_NewtonsMethod.svg)
+NewtonsMethodAD | ![](2DSlice_converged_NewtonsMethodAD.svg)  |  ![](2DSlice_non_converged_NewtonsMethodAD.svg)
+RegulaFalsiMethod | ![](2DSlice_converged_RegulaFalsiMethod.svg)  |  ![](2DSlice_non_converged_RegulaFalsiMethod.svg)