FV3 Example Notebooks and cleanup of docs directory (NOAA-EMC#117)

* Create examples README.md * Reorganizing files in docs/ directory * Added advection notebook * Fixed subplot spacing * New 3D case notebooks * Added notebooks * Update README.md
LarissaReames-NOAA · Jul 21, 2021 · ef5028f · ef5028f
1 parent ae14c6e
commit ef5028f
Show file tree

Hide file tree

Showing 24 changed files with 5,055 additions and 7 deletions.
diff --git a/README.md b/README.md
@@ -14,6 +14,12 @@ Cite _Putman and Lin (2007)_ and _Harris and Lin (2013)_ when describing a model
 
 Cite _Chen et al (2013)_ and _Zhou et al (2019)_ when using the GFDL Microphysics.
 
+# Documentation
+
+The up-to-date FV3 Scientific reference guide is included in LaTex and PDF formats in the ```docs/``` directory. There are also some notebooks in docs/examples demonstrating basic FV3 capabilities and analysis techniques.
+
+A [DOI referenceable version](https://doi.org/10.25923/6nhs-5897) is available in the [_NOAA Institutional Repository_](https://repository.library.noaa.gov/view/noaa/30725)
+
 # What files are what
 
 The top level directory structure groups source code and input files as follow:
@@ -27,13 +33,7 @@ The top level directory structure groups source code and input files as follow:
 | ```driver/```        | contains drivers used by different models/modeling systems |
 | ```tools/```         | contains source code of tools used within the core |
 | ```GFDL_tools/```    | contains source code of tools specific to GFDL models |
-| ```docs/```          | contains documentation for the FV3 dynamical core |
-
-# Documentation
-
-The up-to-date FV3 Scientific reference guide is included in LaTex and PDF formats in the ```docs/``` directory.
-
-A DOI referenceable version will soon be available in the [_NOAA Institutional Repository_](https://repository.library.noaa.gov/)
+| ```docs/```          | contains documentation for the FV3 dynamical core, and Python notebooks demonstrating basic capabilities. |
 
 # Disclaimer
 

diff --git a/docs/CDgrid.pdf → docs/doc_source/CDgrid.pdf b/docs/CDgrid.pdf → docs/doc_source/CDgrid.pdf
diff --git a/docs/FV3flowchart.pdf → docs/doc_source/FV3flowchart.pdf b/docs/FV3flowchart.pdf → docs/doc_source/FV3flowchart.pdf
diff --git a/docs/GFDLLogo.png → docs/doc_source/GFDLLogo.png b/docs/GFDLLogo.png → docs/doc_source/GFDLLogo.png
diff --git a/docs/KESpectra.pdf → docs/doc_source/KESpectra.pdf b/docs/KESpectra.pdf → docs/doc_source/KESpectra.pdf
diff --git a/docs/PGF.pdf → docs/doc_source/PGF.pdf b/docs/PGF.pdf → docs/doc_source/PGF.pdf
diff --git a/docs/doc_source/README b/docs/doc_source/README
@@ -0,0 +1 @@
+These are LaTeX and BibTeX source files and associated graphics files. They should not require any special LaTeX packages not present in current TeX distributions.
diff --git a/docs/fv3_technical_2021.tex → docs/doc_source/fv3_technical_2021.tex b/docs/fv3_technical_2021.tex → docs/doc_source/fv3_technical_2021.tex
diff --git a/docs/fv3logo.png → docs/doc_source/fv3logo.png b/docs/fv3logo.png → docs/doc_source/fv3logo.png
diff --git a/docs/fv3references.bib → docs/doc_source/fv3references.bib b/docs/fv3references.bib → docs/doc_source/fv3references.bib
diff --git a/docs/gridmetrics1D.pdf → docs/doc_source/gridmetrics1D.pdf b/docs/gridmetrics1D.pdf → docs/doc_source/gridmetrics1D.pdf
diff --git a/docs/gridmetricsCoordinates.pdf → docs/doc_source/gridmetricsCoordinates.pdf b/docs/gridmetricsCoordinates.pdf → docs/doc_source/gridmetricsCoordinates.pdf
diff --git a/docs/gridmetricsReconstructions.pdf → ...doc_source/gridmetricsReconstructions.pdf b/docs/gridmetricsReconstructions.pdf → ...doc_source/gridmetricsReconstructions.pdf
diff --git a/docs/phasespeedbad.pdf → docs/doc_source/phasespeedbad.pdf b/docs/phasespeedbad.pdf → docs/doc_source/phasespeedbad.pdf
diff --git a/docs/phasespeedgood.pdf → docs/doc_source/phasespeedgood.pdf b/docs/phasespeedgood.pdf → docs/doc_source/phasespeedgood.pdf
diff --git a/docs/twowayschematic.pdf → docs/doc_source/twowayschematic.pdf b/docs/twowayschematic.pdf → docs/doc_source/twowayschematic.pdf
diff --git a/docs/examples/BCMoist.ipynb b/docs/examples/BCMoist.ipynb
diff --git a/docs/examples/BLvortex.ipynb b/docs/examples/BLvortex.ipynb
diff --git a/docs/examples/BTwave.ipynb b/docs/examples/BTwave.ipynb
diff --git a/docs/examples/DPSupercell.ipynb b/docs/examples/DPSupercell.ipynb
diff --git a/docs/examples/README.md b/docs/examples/README.md
@@ -0,0 +1,28 @@
+# FV3 Examples
+
+This directory contains Python (Jupyter) notebooks demonstrating basic FV3 capabilities, including characteristics of the solver, physics-dynamics coupling, output using FMS diag_manager, and basic analyses of the model output. The notebooks should all be viewable in any browser; you can also download any of them and use them in an up-to-date Python/Jupyter environment.
+
+## 1D Notebooks
+tp_core
+: 1D advection operators in FV3. This is designed to be an *interactive* notebook for downloading and playing with the options, initial conditions, zooms, and so on.
+
+## 2D Shallow-water Notebooks
+RHwave
+: Rossby-Haurwitz wave, a test of height-vorticity consistency
+
+BTwave
+: Barotropic instability, demonstrating wave breaking (cf. Galewsky et al. 2004; Scott, Harris, and Polvani 2016)
+
+BLvortex
+: Bates-Li forced polar vortex
+
+## 3D Notebooks
+
+BCwave
+: Hydrostatic baroclinic wave, with and without moisture
+
+TC
+: Reed-Jablonowski TC tests, demonstrating the effect of advection schemes and numerical diffusion
+
+DPsupercell
+: Supercell on a doubly-periodic using Weisman (WK82) sounding and a straight-line hodograph. Demonstrates pressure partitioning between moist, dry, and nonhydrostatic contributions.
diff --git a/docs/examples/RHwave.ipynb b/docs/examples/RHwave.ipynb
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1 @@
		These are LaTeX and BibTeX source files and associated graphics files. They should not require any special LaTeX packages not present in current TeX distributions.