Merge pull request #725 from uaf-arctic-eco-modeling/general-documentation

Update docs:
 - add QuickStart section to Sphinx docs and Readme
 - improve plotting script to match documentation
 - fix attribution in MADS section

Author: tobeycarman

README.md

@@ -8,20 +8,52 @@ The dvm-dos-tem (`dvmdostem`) model is a process based bio-geo-chemical
 ecosystem model that focuses on C and N dynamics as well as soil thermal
 dynamics in high latitude ecosystems.
 
-[Complete Documentation](https://uaf-arctic-eco-modeling.github.io/dvm-dos-tem/index.html)
+For more information see the [User Guide](https://uaf-arctic-eco-modeling.github.io/dvm-dos-tem/index.html).
 
-> **Whats with the name?**
-> 
-> `dvm-dos-tem` is short for "Dynamic Vegetation \[Model\] Dynamic Organic Soil
-> Terrestrial Ecosystem Model". Orignally the model
-> was simply "TEM", and as more logic and capabilities have been added, the name
-> has grown. We still frequently use simply "TEM" because it is less cumbersome
-> for writing and typing.
+For questions and to get involved please see the [Github Issues](https://uaf-arctic-eco-modeling.github.io/dvm-dos-tem/issues) and [Github Discussions](https://uaf-arctic-eco-modeling.github.io/dvm-dos-tem/discussions).
 
+> [!NOTE]
+> **Whats with the name?** `dvm-dos-tem` is short for "**D**ynamic
+> **V**egetation \[**M**odel\] **D**ynamic **O**rganic **S**oil **T**errestrial
+> **E**cosystem **M**odel". Orignally the model was simply "TEM", and as more
+> logic and capabilities have been added, the name has grown. We still
+> frequently use simply "TEM" because it is less cumbersome for writing and
+> typing. In most context TEM, dvmdostem, dvm-dos-tem, DVM-DOS-TEM and DMVDOSTEM
+> are synonomous and can be used interchangably.
 
-> **Sept 2022**
->
-> We are in the process of updating the entire documentation
+
+## Quickstart
+
+For users who have Docker and Git installed. 
+
+More details are available in the [User Guide - Basic Model Setup and Run](https://uaf-arctic-eco-modeling.github.io/dvm-dos-tem/examples_and_tutorials/basic_model_run.html#basic-model-setup-and-run).
+
+The default settings will run the model in the source code directory, using the
+sample data that is included with the repository in the ``demo-data/`` directory.
+The run will output a single variable (GPP), and will run for 2 pixels.
+
+- Clone the repository (``git clone https://github.com/uaf-arctic-eco-modeling/dvm-dos-tem.git``).
+- Change into directory (``cd dvm-dos-tem``).
+- Get some input data (optional).
+- Build Docker images (``./docker-build-wrapper.sh cpp-dev && ./docker-build-wrapper.sh dev``).
+- Setup your environment variables in ``.env`` file for ``V_TAG``, ``DDT_INPUT_CATALOG``, and ``DDT_WORKFLOWS`` (optional).
+- Start Docker containers (``V_TAG=$(git describe) docker compose up -d dvmdostem-dev``).
+- Obtain shell in container (``docker compose exec dvmdostem-dev bash``)
+- Compile code (``develop@56ef79004e31:/work$ make``)
+- Setup working directory (optional).
+- Change into working directory (optional) .
+- Adjust as needed (optional):
+   - Your run mask (``run-mask.nc``)
+   - The outputs you would like to generate (``output_spec.csv``)
+   - Any other configuration items (``config.js``)
+   - Any custom parameters (``parameters/``)
+   - Any custom target data (``calibration/calibration_targets.py``).
+- Start the model run (``develop@56ef79004e31:/work$ ./dvmdostem --log-level monitor -p 100 -e 1000 -s 250 -t 115 -n 85``).
+- Analyze run (``develop@56ef79004e31:/work ./scripts/plot_output_var.py --yx 0 0 --file output/GPP_yearly_tr.nc``).
+ 
+
+> [!WARNING]
+> Sept 2022 - We are in the process of updating the entire documentation
 > system. There is still info scattered across this README, the wiki, a Google
 > Doc and the Sphinx system but we are working on consolidating the info into 
-> primarily the Sphinx system.
+> primarily the Sphinx system (the User Guide).

docs_src/sphinx/source/examples_and_tutorials/basic_model_run.rst

@@ -15,6 +15,35 @@ bunch of the supporting tools, including Docker, and Git. For post processing
 and visualization, see the :ref:`Plotting Example
 <examples_and_tutorials/plotting_discussion:Plotting>`. 
 
+.. hint:: Quickstart Summary
+
+  For users who have Docker and Git installed. 
+
+  The default settings will run the model in the source code directory, using the
+  sample data that is included with the repository in the ``demo-data/`` directory.
+  The run will output a single variable (GPP), and will run for 2 pixels.
+
+  - Clone the repository (``git clone https://github.com/uaf-arctic-eco-modeling/dvm-dos-tem.git``).
+  - Change into directory (``cd dvm-dos-tem``).
+  - Get some input data (optional).
+  - Build Docker images (``./docker-build-wrapper.sh cpp-dev && ./docker-build-wrapper.sh dev``).
+  - Setup your environment variables in ``.env`` file for ``V_TAG``, ``DDT_INPUT_CATALOG``, and ``DDT_WORKFLOWS`` (optional).
+  - Start Docker containers (``V_TAG=$(git describe) docker compose up -d dvmdostem-dev``).
+  - Obtain shell in container (``docker compose exec dvmdostem-dev bash``)
+  - Compile code (``develop@56ef79004e31:/work$ make``)
+  - Setup working directory (optional).
+  - Change into working directory (optional) .
+  - Adjust as needed (optional):
+
+     - Your run mask (``run-mask.nc``)
+     - The outputs you would like to generate (``output_spec.csv``)
+     - Any other configuration items (``config.js``)
+     - Any custom parameters (``parameters/``)
+     - Any custom target data (``calibration/calibration_targets.py``).
+
+  - Start the model run (``develop@56ef79004e31:/work$ ./dvmdostem --log-level monitor -p 100 -e 1000 -s 250 -t 115 -n 85``).
+  - Analyze run (``develop@56ef79004e31:/work ./scripts/plot_output_var.py --yx 0 0 --file output/GPP_yearly_tr.nc``).
+ 
 .. note::
 
   This lab is more or less a duplicate of an existing wiki page:

docs_src/sphinx/source/examples_and_tutorials/mads_assisted_calibration.rst

@@ -16,13 +16,12 @@ portions being done iteratively and or in an automated fashion.
 
 .. note:: 
 
-   The MADS Assisted Calibration process has been a group effort led by `Elchin
-   Jafarov <WCRCEJ_>`_ with contributions and testing from the team at
-   `Woodwell Climate Research Center <WCRC_>`_ as well as the UAF Arctic
-   Ecosystem Modeling group, including:
+   The MADS Assisted Calibration process has been a group effort led by `Helene
+   Genet <UAFHG_>`_  and `Elchin Jafarov <WCRCEJ_>`_ with contributions and
+   testing from the team at `Woodwell Climate Research Center <WCRC_>`_ as well
+   as the `UAF Arctic Ecosystem Modeling Group <UAFAEMG_>`_, including:
 
     - Tobey Carman
-    - Helene Genet
     - Ruth Rutter
     - Aiza Kabeer
     - Andrew Mullen
@@ -137,4 +136,6 @@ the optimization.
 .. _MADS: https://www.madsjulia.github.io
 .. _WCRC: https://www.woodwellclimate.org/
 .. _WCRCEJ: https://www.woodwellclimate.org/staff/elchin-jafarov/ 
+.. _UAFHG: https://www.uaf.edu/iab/people/faculty.php?who=Genet_Helene
+.. _UAFAEMG: https://github.com/uaf-arctic-eco-modeling
 

scripts/plot_output_var.py

@@ -124,6 +124,8 @@
         data = nc_data[:,Y,X]
         fig, axes = plt.subplots(1,1, sharex=args.sharex, sharey=args.sharey)
         axes.plot(time_range, data)
+        axes.set_ylabel(f"{ncFile.variables[plotting_var].units}")
+        fig.suptitle(f"{args.file}")
 
 
       # Variables by PFT, Compartment, or Layer
@@ -248,7 +250,10 @@
       manager = plt.get_current_fig_manager()
       manager.set_window_title(plotting_var)
       plt.xlabel("time")
-      plt.savefig("SAMPLE_plot_output_var.png")
+
+      savename = f"{plotting_var}_plot_output_var.png"
+      print(f"Saving file: {savename} ...")
+      plt.savefig(savename)
       plt.show()