Minimum changes to meet JOSS docs criteria

docs/INDEX.md

@@ -1,8 +1,49 @@
-# eCLM Documentation
+# Welcome to eCLM!
 
-```{important}
-**Welcome!** You are viewing the first version of the documentation for eCLM. This is a living document, which means it will be continuously updated and improved. Please check back regularly for the latest information and updates.
+eCLM is based on version 5.0 of the Community Land Model ([CLM5](https://www.cesm.ucar.edu/models/clm)) The Community Land Model is the land model for the Community Earth System Model (CESM). It focuses on modeling the land as the critical interface through which humanity affects, adapts to, and mitigates global environmental change. It includes a comprehensive representation of land biogeophysics, hydrology, plant physiology, biogeochemistry, anthropogenic land use, and ecosystem dynamics across a variety of spatial and temporal scales. The central theme is that terrestrial ecosystems, through their cycling of energy, water, chemical elements, and trace gases, are important determinants of climate.
+The model represents several aspects of the land surface including surface heterogeneity and consists of components or submodels related to land biogeophysics, the hydrologic cycle, biogeochemistry, human dimensions, and ecosystem dynamics. Specific processes that are represented include:
+
+- Vegetation composition, structure, and phenology
+- Absorption, reflection, and transmittance of solar radiation
+- Absorption and emission of longwave radiation
+- Momentum, sensible heat (ground and canopy), and latent heat (ground evaporation, canopy evaporation, transpiration) fluxes
+- Heat transfer in soil and snow including phase change
+- Canopy hydrology (interception, throughfall, and drip)
+- Snow hydrology (snow accumulation and melt, compaction, water transfer between snow layers)
+- Soil hydrology (surface runoff, infiltration, redistribution of water within the column, sub-surface drainage, groundwater)
+- Plant hydrodynamics
+- Stomatal physiology and photosynthesis
+- Lake temperatures and fluxes
+- Dust deposition and fluxes
+- Routing of runoff from rivers to ocean
+- Volatile organic compounds emissions
+- Urban energy balance and climate
+- Carbon-nitrogen cycling
+- Dynamic landcover change
+- Land management including crops and crop management and wood harvest
+- Ecosystem Demography (FATES, optional)
+
+```{figure} users_guide/images/CLM5_processes_Lawrence2019.png
+:height: 400px
+:name: fig1
+
+Overview of land biogeophysical, biogeochemical and landscape processes simulated by CLM5 <a href="http://dx.doi.org/10.1029/2018MS001583" target="_blank">Lawrence et al. (2019)</a>.
 ```
 
-eCLM is based on version 5.0 of the Community Land Model ([CLM5](https://www.cesm.ucar.edu/models/clm)) with simplified infrastructure for build and namelist generation. The build system is handled entirely by Cmake and namelists are generated through a small set of Python scripts. Similar to CLM5, eCLM is forced with meteorological data and uses numerous input streams on soil properties, land cover and land use, as well as complex parameter sets on crop phenology, and plant hydraulics for simulations.
+Each time step the model solves the surface energy balance, water balance, and carbon exchange. Submodels of CLM include biophysics and biogeochemistry. It represents land surface heterogeneity through a subgrid tiling structure and different plant functional types that have unique parameters in terms of optical properties, morphology, photosynthesis. It can be run with prescribed vegetation states using satelllite phenology (SP mode) or prognostic vegetation states and biogeochemistry (BGC mode).
+
+```{figure} users_guide/images/CLM5_subgrid_structure_v1.png
+:height: 400px
+:name: fig2
+
+Configuration of the CLM subgrid hierarchy. Box in upper right shows hypothetical subgrid distribution for a single grid cell. Note that the Crop land unit is only used when the model is run with the crop model active. Abbreviations: TBD – Tall Building District; HD – High Density; MD – Medium Density, G – Glacier, L – Lake, U – Urban, C – Crop, V – Vegetated, PFT – Plant Functional Type, Irr – Irrigated, UIrr – Unirrigated. Red arrows indicate allowed land unit transitions. Purple arrows indicate allowed patch-level transitions. From <a href="https://escomp.github.io/ctsm-docs/versions/release-clm5.0/html/tech_note/Ecosystem/CLM50_Tech_Note_Ecosystem.html#id14" target="_blank">CLM5 Technical Note</a>.
+```
+
+More background information on CLM (and it’s latest release CLM5) including documentation and publications can be found <a href="https://www.cesm.ucar.edu/models/clm" target="_blank">here</a>.
+
+## Difference with CLM5
+
+eCLM has simplified infrastructure for build and namelist generation. The build system is handled entirely by Cmake and namelists are generated through a small set of Python scripts. Similar to CLM5, eCLM is forced with meteorological data and uses numerous input streams on soil properties, land cover and land use, as well as complex parameter sets on crop phenology, and plant hydraulics for simulations.
+
+
 

docs/_toc.yml

@@ -5,39 +5,25 @@ root: INDEX
 parts:
 - caption: Introduction
   chapters:
-  - file: users_guide/installation/README
-    title: Installing eCLM
-  - file: users_guide/introduction/introduction
-    title: Scientific Background
-  - file: users_guide/introduction/perturbation
-    title: Atmospheric forcing noise
-  - file: users_guide/introduction/soil_hydraulic_parameters
-    title: Soil hydraulic properties from surface file
-
+  - file: users_guide/introduction/quick_start
+    title: Quick Start
 - caption: User's Guide
   chapters:
   - file: users_guide/case_examples/README
     title: Running example cases
     sections:
     - file: users_guide/case_examples/Wuestebach
-    - file: users_guide/case_examples/NRW
-    - file: users_guide/case_examples/EURO-CORDEX
-
-  - file: users_guide/running_cases/case_customization
-    title:  Customizing eCLM namelists
 
-  - file: users_guide/analyzing_model_output
-    title: Analyzing model output
-
-  - file: users_guide/case_creation/README
+  - url: https://hpscterrsys.github.io/eCLM_static-file-generator/INDEX.html
     title: Creating a custom case
+
+  - file: users_guide/misc_tutorials/README
+    title: Miscellaneous tutorials
     sections:
-    - file: users_guide/case_creation/1_create_grid_file
-    - file: users_guide/case_creation/2_create_mapping_file
-    - file: users_guide/case_creation/3_create_domain_file
-    - file: users_guide/case_creation/4_create_surface_file
-    - file: users_guide/case_creation/5_modifications_surface_domain_file
-    - file: users_guide/case_creation/6_create_atm_forcings
+    - file: users_guide/misc_tutorials/perturbation
+      title: Atmospheric forcing noise
+    - file: users_guide/misc_tutorials/soil_hydraulic_parameters
+      title: Soil hydraulic properties from surface file
 
 - caption: Developer's Guide
   chapters:
@@ -51,7 +37,3 @@ parts:
   - file: reference/history_fields
   - url: https://escomp.github.io/CTSM/release-clm5.0/tech_note/index.html
     title: CLM5 Technical Note
-  - url: https://github.com/HPSCTerrSys/eCLM_static-file-generator/blob/main/README.md)
-    title: eCLM static file generator
-  - url: https://hpscterrsys.github.io/TSMP2_workflow-engine
-    title: TSMP2 Workflow Engine