Merge pull request #8 from PALEOtoolkit/doc_update

Doc update
PALEOtoolkit · Apr 23, 2023 · 52284e9 · 52284e9
2 parents 2be289d + 348c5ec
commit 52284e9
Show file tree

Hide file tree

Showing 22 changed files with 2,187 additions and 126 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,4 +1,6 @@
 Manifest.toml
 LocalPreferences.toml
 /docs/build/
+/docs/src/collated_examples/
 .vscode
+*.jld2
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -2,6 +2,7 @@
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 PALEOboxes = "804b410e-d900-4b2a-9ecd-f5a06d4c1fd4"
+PALEOmodel = "bf7b4fbe-ccb1-42c5-83c2-e6e9378b660c"
 PALEOocean = "41de04b1-2efd-44ae-92ae-39d71a4fd99b"
 Revise = "295af30f-e4ad-537b-8983-00126c2a3abe"
 
@@ -10,6 +11,3 @@ Documenter = "0.27"
 DocumenterCitations = "0.2"
 Revise = "3.1"
 julia = "1.6"
-
-[extras]
-
diff --git a/docs/make.jl b/docs/make.jl
@@ -25,14 +25,13 @@ makedocs(bib, sitename="PALEOocean Documentation",
     pages = [
         "index.md",
         "Examples and Tutorials" => examples_pages,
-        # no Design docs yet
-        # "Design" => [
-        #     "COPSE_Domains.md",
-        # ],
+        "Design" => [
+             "PALEOocean_Domains.md",
+        ],
         # no HOWTO docs yes
         "Reference" => [
-            "PALEOocean Reactions.md",
-            "PALEOocean functions.md",
+            "PALEOocean_Reactions.md",
+            "PALEOocean_functions.md",
         ],
         "References.md",
         "indexpage.md",

diff --git a/docs/src/PALEOocean_Domains.md b/docs/src/PALEOocean_Domains.md
@@ -0,0 +1,46 @@
+# PALEOocean Domains, fluxes, and standard Variables
+
+![Domains image](images/ocean_domains.svg)
+###### Figure 1
+*Ocean Domains, subDomains, and fluxes. Compare to full Earth system Domains <https://paleotoolkit.github.io/PALEOcopse.jl/dev/COPSE_Domains>*
+
+## Domains
+
+The standard Domain configuration for an atmosphere-ocean model is shown in Figure 1.
+- **global** This is used for model-wide quantities, typically global budgets and global forcings
+
+- **atmosphere** A scalar (0-D) Domain with atmospheric variables and Reactions
+
+- **ocean** The `ocean` Domain represents a 3-D ocean as a vector of cells, with geometry and internal transport defined by an OceanTransport Reaction. 
+
+- **oceansurface, oceanfloor** `oceansurface` and `oceanfloor` represent 2-D boundaries as a vector of cells, with geometry defined by the OceanTransport Reaction. There is a 1-to-1 correspondence between the cells in the 2-D `oceansurface` Domain, the adjacent `ocean` surface cells defined by the `ocean.oceansurface` subdomain. Similarly, there is a 1-to-1 correspondence between the cells in the 2-D `oceanfloor` Domain, the adjacent `ocean` floor cells defined by the `ocean.oceanfloor` subdomain.
+
+
+## Fluxes
+ Flux Domains are used to hold exchange fluxes in Variables defined by `FluxTarget` Reactions, see <https://paleotoolkit.github.io/PALEOboxes.jl/stable/DesignOverview/#Coupling-Spatial-Domains>
+
+- **fluxAtmtoOceansurface** Air-sea exchange fluxes are defined in the 2-D `fluxAtmtoOceansurface` Domain, which contains cells with a 1-to-1 correspondence to the `oceansurface` Domain.
+
+- **fluxOceanfloor** Particulate fluxes from ocean to oceanfloor, and solute exchange fluxes between ocean and oceanfloor, are defined in the 2-D `fluxOceanfloor` Domain. This contains cells with a 1-to-1 correspondence to cells in the `oceanfloor` Domain.
+
+- **fluxOceanBurial** Ocean burial fluxes are defined in the 2-D `fluxOceanburial` Domain. This contains cells with a 1-to-1 correspondence to cells in the `oceanfloor` Domain.
+
+## Standard Variables
+
+(see [Skeleton ocean-atmosphere configuration](@ref))
+
+    julia> include("PALEO_examples_oceanskeleton.jl")
+
+```@setup oceanskeleton
+include("../../examples/skeleton_configuration/PALEO_examples_oceanskeleton.jl") # hide
+```
+```@example oceanskeleton
+show(PB.show_variables(model); allrows=true, allcols=true, eltypes=false, show_row_number=false)
+```
+
+ocean, oceansurface, and oceanfloor Variables are standard grid variables, provided by the ocean transport Reaction
+(a `ReactionOceanTransport3box` in this case).
+
+Flux target Variables to accumulate exchange fluxes are provided by `ReactionFluxTarget` Reactions, the illustrative
+configuration here defines fluxes for a C, O, P model with atmospheric state variables CO2, O2, and ocean state
+variables including DIC, TAlk, O2 and P.
diff --git a/docs/src/PALEOocean Reactions.md → docs/src/PALEOocean_Reactions.md b/docs/src/PALEOocean Reactions.md → docs/src/PALEOocean_Reactions.md
diff --git a/docs/src/PALEOocean functions.md → docs/src/PALEOocean_functions.md b/docs/src/PALEOocean functions.md → docs/src/PALEOocean_functions.md
diff --git a/docs/src/collated_examples/PTBClarkson2014/README.md b/docs/src/collated_examples/PTBClarkson2014/README.md
diff --git a/docs/src/collated_examples/mitgcm/README.md b/docs/src/collated_examples/mitgcm/README.md
diff --git a/docs/src/collated_examples/ocean3box/README.md b/docs/src/collated_examples/ocean3box/README.md
diff --git a/docs/src/collated_examples/transport_examples/README.md b/docs/src/collated_examples/transport_examples/README.md
diff --git a/docs/src/collated_examples/transport_examples/images/examples_transport_advect.png b/docs/src/collated_examples/transport_examples/images/examples_transport_advect.png
diff --git a/.../src/collated_examples/transport_examples/images/examples_transport_diffuse.png b/.../src/collated_examples/transport_examples/images/examples_transport_diffuse.png