Update docs

docs_src/sphinx/source/conf.py

@@ -31,6 +31,9 @@
 
 # -- General configuration ---------------------------------------------------
 
+numfig = True # auto-numbering for figures, reference by name
+
+
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
@@ -45,8 +48,11 @@
   #'numpydoc',
   'sphinx.ext.napoleon',
   'sphinxarg.ext',
+  'sphinxcontrib.bibtex',
 ]
 
+bibtex_bibfiles = ["bibliography.bib"]
+bibtex_reference_style = "author_year"
 
 # -- Config for some extensions ----------------------------------------------
 autosectionlabel_prefix_document = True

docs_src/sphinx/source/references.rst

@@ -9,219 +9,6 @@
 References
 ################
 
-.. Formatting follows the Ecological Applications style
-
-Balshi, M. S., A. D. McGuire, Q. Zhuang, J. Melillo, D. W. Kicklighter, E.
-Kasischke, C. Wirth, M. Flannigan, J. Harden, J. S. Clein, T. J. Burnside, J.
-McAllister, W. A. Kurz, M. Apps, and A. Shvidenko. 2007. The role of
-historical fire disturbance in the carbon dynamics of the pan-boreal region:
-A process-based analysis. Journal of Geophysical Research: Biogeosciences
-112.
-https://doi.org/10.1029/2006JG000380
-
-Balshi, M. S., A. D. Mcguire, P. Duffy, M. Flannigan, D. W. Kicklighter, and
-J. Melillo. 2009. Vulnerability of carbon storage in North American boreal
-forests to wildfires during the 21st century. Global Change Biology 15.
-https://doi.org/10.1111/j.1365-2486.2009.01877.x
-
-Balshi, M. S., A. D. McGuire, P. Duffy, M. Flannigan, J. Walsh, and J.
-Melillo. 2009. Assessing the response of area burned to changing climate in
-western boreal North America using a Multivariate Adaptive Regression Splines
-(MARS) approach. Global Change Biology 15.
-https://doi.org/10.1111/j.1365-2486.2008.01679.x
-
-Beringer, J., A. H. Lynch, F. S. I. Chapin, M. Mack, and G. B. Bonan. 2001.
-The representation of arctic soils in the land surface model: The importance
-of mosses. Journal of Climate 14.
-`https://doi.org/10.1175/1520-0442(2001)014<3324:TROASI>2.0.CO;2
-<https://doi.org/10.1175/1520-0442(2001)014\<3324:TROASI\>2.0.CO;2>`_
-
-Decker, M., and X. Zeng. 2009. Impact of Modified Richards Equation on Global
-Soil Moisture Simulation in the Community Land Model (CLM3.5). Journal of
-Advances in Modeling Earth Systems 1.
-https://doi.org/10.3894/james.2009.1.5
-
-Euskirchen, E. S., C. W. Edgar, M. R. Turetsky, M. P. Waldrop, and J. W.
-Harden. 2014. Differential response of carbon fluxes to climate in three
-peatland ecosystems that vary in the presence and stability of permafrost.
-Journal of Geophysical Research: Biogeosciences 119.
-https://doi.org/10.1002/2014JG002683
-
-Euskirchen, E. S., A. D. Mcguire, F. S. Chapin, S. Yi, and C. C. Thompson.
-2009. Changes in vegetation in northern Alaska under scenarios of climate
-change, 2003-2100: implications for climate feedbacks. Ecological
-Applications 19.
-https://doi.org/10.1890/08-0806.1
-
-Euskirchen, E. S., A. D. McGuire, D. W. Kicklighter, Q. Zhuang, J. S. Clein,
-R. J. Dargaville, D. G. Dye, J. S. Kimball, K. C. McDonald, J. M. Melillo, V.
-E. Romanovsky, and N. V. Smith. 2006. Importance of recent shifts in soil
-thermal dynamics on growing season length, productivity, and carbon
-sequestration in terrestrial high-latitude ecosystems. Global Change Biology
-12.
-https://doi.org/10.1111/j.1365-2486.2006.01113.x
-
-Euskirchen, E. S., T. B. Carman, and A. D. Mcguire. 2014. Changes in the
-structure and function of northern Alaskan ecosystems when considering
-variable leaf-out times across groupings of species in a dynamic vegetation
-model. Global Change Biology 20.
-https://doi.org/10.1111/gcb.12392
-
-Euskirchen, E. S., S. P. Serbin, T. B. Carman, J. M. Fraterrigo, H. Genet, C.
-M. Iversen, V. Salmon, and A. D. McGuire. 2022. Assessing dynamic vegetation
-model parameter uncertainty across Alaskan arctic tundra plant communities.
-Ecological Applications 32.
-https://doi.org/10.1002/eap.2499
-
-Fan, Z., A. David Mcguire, M. R. Turetsky, J. W. Harden, J. Michael
-Waddington, and E. S. Kane. 2013. The response of soil organic carbon of a
-rich fen peatland in interior Alaska to projected climate change. Global
-Change Biology 19.
-https://doi.org/10.1111/gcb.12041
-
-Genet, H., A. D. McGuire, K. Barrett, A. Breen, E. S. Euskirchen, J. F.
-Johnstone, E. S. Kasischke, A. M. Melvin, A. Bennett, M. C. Mack, T. S. Rupp,
-A. E. G. Schuur, M. R. Turetsky, and F. Yuan. 2013. Modeling the effects of
-fire severity and climate warming on active layer thickness and soil carbon
-storage of black spruce forests across the landscape in interior Alaska.
-Environmental Research Letters 8.
-https://doi.org/10.1088/1748-9326/8/4/045016
-
-Genet, H., Y. He, Z. Lyu, A. D. McGuire, Q. Zhuang, J. Clein, D. D’Amore, A.
-Bennett, A. Breen, F. Biles, E. S. Euskirchen, K. Johnson, T. Kurkowski, S.
-Kushch Schroder, N. Pastick, T. S. Rupp, B. Wylie, Y. Zhang, X. Zhou, and Z.
-Zhu. 2018. The role of driving factors in historical and projected carbon
-dynamics of upland ecosystems in Alaska: Ecological Applications 28.
-https://doi.org/10.1002/eap.1641
-
-Hayes, D. J., A. D. McGuire, D. W. Kicklighter, K. R. Gurney, T. J. Burnside,
-and J. M. Melillo. 2011. Is the northern high-latitude land-based CO 2 sink
-weakening? Global Biogeochemical Cycles 25.
-https://doi.org/10.1029/2010GB003813
-
-Hayes, D. J., A. D. McGuire, D. W. Kicklighter, T. J. Burnside, and J. M.
-Melillo. 2011. The effects of land cover and land use change on the
-contemporary carbon balance of the arctic and boreal terrestrial ecosystems
-of Northern Eurasia. Page Eurasian Arctic Land Cover and Land Use in a
-Changing Climate.
-https://doi.org/10.1007/978-90-481-9118-5_6
-
-Jordan, R. 1991. A One-Dimensional Temperature Model for a Snow Cover:
-Technical Documentation for SNTHERM.89. Page U.S.Army Corps of Engineers,
-Cold Regions Research & Engineering Laboratory.
-http://hdl.handle.net/11681/11677
-
-Kelly, R., H. Genet, A. D. McGuire, and F. S. Hu. 2016. Palaeodata-informed
-modelling of large carbon losses from recent burning of boreal forests.
-Nature Climate Change 6.
-https://doi.org/10.1038/nclimate2832
-
-Lara, M. J., A. D. Mcguire, E. S. Euskirchen, C. E. Tweedie, K. M. Hinkel, A.
-N. Skurikhin, V. E. Romanovsky, G. Grosse, W. R. Bolton, and H. Genet. 2015.
-Polygonal tundra geomorphological change in response to warming alters future
-CO2 and CH4 flux on the Barrow Peninsula. Global Change Biology 21.
-https://doi.org/10.1111/gcb.12757
-
-Lundin, L. C. 1990. Hydraulic properties in an operational model of frozen
-soil. Journal of Hydrology 118.
-https://doi.org/10.1016/0022-1694(90)90264-X
-
-Lyu, Z., H. Genet, Y. He, Q. Zhuang, A. D. McGuire, A. Bennett, A. Breen, J.
-Clein, E. S. Euskirchen, K. Johnson, T. Kurkowski, N. J. Pastick, T. S. Rupp,
-B. K. Wylie, and Z. Zhu. 2018. The role of environmental driving factors in
-historical and projected carbon dynamics of wetland ecosystems in Alaska.
-Ecological Applications 28.
-https://doi.org/10.1002/eap.1755
-
-McGuire, A. D., J. M. Melillo, L. A. Joyce, D. W. Kicklighter, A. L. Grace,
-B. Moore, and C. J. Vorosmarty. 1992. Interactions between carbon and
-nitrogen dynamics in estimating net primary productivity for potential
-vegetation in North America. Global Biogeochemical Cycles 6.
-https://doi.org/10.1029/92GB00219
-
-McGuire, A. D., H. Genet, Z. Lyu, N. Pastick, S. Stackpoole, R. Birdsey, D.
-D’Amore, Y. He, T. S. Rupp, R. Striegl, B. K. Wylie, X. Zhou, Q. Zhuang, and
-Z. Zhu. 2018. Assessing historical and projected carbon balance of Alaska: A
-synthesis of results and policy/management implications. Ecological
-Applications 28.
-https://doi.org/10.1002/eap.1768
-
-Niu, G. Y., Z. L. Yang, R. E. Dickinson, and L. E. Gulden. 2005. A simple
-TOPMODEL-based runoff parameterization (SIMTOP) for use in global climate
-models. Journal of Geophysical Research Atmospheres 110.
-https://doi.org/10.1029/2005JD006111
-
-Raich, J. W., E. B. Rastetter, J. M. Melillo, D. W. Kicklighter, P. A.
-Steudler, B. J. Peterson, A. L. Grace, B. Moore, and C. J. Vorosmarty. 1991.
-Potential net primary productivity in south-america - application of a
-global-model. Ecological Applications 1:399–429.
-https://doi.org/10.2307/1941899
-
-Raleigh, M. S., C. C. Landry, M. Hayashi, W. L. Quinton, and J. D. Lundquist.
-2013. Approximating snow surface temperature from standard temperature and
-humidity data: New possibilities for snow model and remote sensing
-evaluation. Water Resources Research 49.
-https://doi.org/10.1002/2013WR013958
-
-Swenson, S. C., D. M. Lawrence, and H. Lee. 2012. Improved simulation of the
-terrestrial hydrological cycle in permafrost regions by the Community Land
-Model. Journal of Advances in Modeling Earth Systems 4.
-https://doi.org/10.1029/2012MS000165
-
-Tian, H., J. M. Melillo, D. W. Kicklighter, A. D. McGuire, and J. Helfrich.
-1999. The sensitivity of terrestrial carbon storage to historical climate
-variability and atmospheric CO2 in the United States. Tellus Series
-B-Chemical and Physical Meteorology 51:414–452.
-from mendeley: 10.3402/tellusb.v51i2.16318
-https://doi.org/10.1034/j.1600-0889.1999.00021.x
-
-Walter, B. P., and M. Heimann. 2000. A process-based, climate-sensitive model
-to derive methane emissions from natural wetlands: Application to five
-wetland sites, sensitivity to model parameters, and climate. Global
-Biogeochemical Cycles 14:745–765.
-https://doi.org/10.1029/1999gb001204
-
-Woo, M. K., M. A. Arain, M. Mollinga, and S. Yi. 2004. A two-directional
-freeze and thaw algorithm for hydrologic and land surface modelling.
-Geophysical Research Letters 31:L12501.
-https://doi.org/10.1029/2004gl019475
-
-Yi, S., A. D. McGuire, J. Harden, E. Kasischke, K. Manies, L. Hinzman, A.
-Liljedahl, J. Randerson, H. Liu, V. Romanovsky, S. Marchenko, and Y. Kim.
-2009. Interactions between soil thermal and hydrological dynamics in the
-response of Alaska ecosystems to fire disturbance. Journal of Geophysical
-Research-Biogeosciences 114:G02015.
-https://doi.org/10.1029/2008jg000841
-
-Yi, S., A. D. McGuire, E. Kasischke, J. Harden, K. Manies, M. Mack, and M.
-Turetsky. 2010. A dynamic organic soil biogeochemical model for simulating
-the effects of wildfire on soil environmental conditions and carbon dynamics
-of black spruce forests. Journal of Geophysical Research-Biogeosciences 115.
-https://doi.org/10.1029/2010jg001302
-
-Yuan, F. M., S. H. Yi, A. D. McGuire, K. D. Johnson, J. Liang, J. W. Harden,
-E. S. Kasischke, and W. A. Kurz. 2012. Assessment of boreal forest historical
-C dynamics in the Yukon River Basin: relative roles of warming and fire
-regime change. Ecological Applications 22:2091–2109.
-https://doi.org/10.1890/11-1957.1
-
-Zhuang, Q., A. D. McGuire, J. M. Melillo, J. S. Clein, R. J. Dargaville, D.
-W. Kicklighter, R. B. Myneni, J. Dong, V. E. Romanovsky, J. Harden, and J. E.
-Hobbie. 2003. Carbon cycling in extratropical terrestrial ecosystems of the
-Northern Hemisphere during the 20th century: a modeling analysis of the
-influences of soil thermal dynamics. Tellus Series B-Chemical and Physical
-Meteorology 55:751–776.
-https://doi.org/10.3402/tellusb.v55i3.16368
-
-Zhuang, Q., A. D. McGuire, K. P. O’Neill, J. W. Harden, V. E. Romanovsky, and
-J. Yarie. 2003. Modeling soil thermal and carbon dynamics of a fire
-chronosequence in interior Alaska. Journal of Geophysical Research:
-Atmospheres 108.
-https://doi.org/10.1029/2001jd001244
-
-Zhuang, Q., J. M. Melillo, D. W. Kicklighter, R. G. Prinn, A. D. McGuire, P.
-A. Steudler, B. S. Felzer, and S. Hu. 2004. Methane fluxes between
-terrestrial ecosystems and the atmosphere at northern high latitudes during
-the past century: A retrospective analysis with a process-based
-biogeochemistry model. Global Biogeochemical Cycles 18.
-https://doi.org/10.1029/2004GB002239
+.. bibliography::
+  :all:
+  :style: plain

docs_src/sphinx/source/running_dvmdostem.rst

@@ -412,8 +412,68 @@ Parallel Options
 ==================================
 Processing Outputs
 ==================================
+
+    WRITE THIS....
+
+------------------
+Output Selection
+------------------
+    WRITE THIS...
+
+.. note:: draft thoughts: 
+    NetCDF outputs are specified in a csv file named in config/config.js. The 
+    csv file specifies a variable name (for identification only - it does not 
+    correspond to the variable name in the code), a short description, units, 
+    and what level of detail to output on (timestep and variable part).
+    [Link to default file after PR merge] Variable name, Description, 
+    Units, Yearly, Monthly, Daily, PFT, Compartment, Layer,
+    Example entry: VEGC,Total veg. biomass C,gC/m2,y,m,,p,c,,
+    This will output VegC every month, and provide both PFT and PFT 
+    compartment values.
+    The file is more user-friendly when viewed in a spreadsheet.
+    [example]
+    A complete list of output combinations is below
+    The initial list of outputs can be found at Issue #252
+    LAYERDEPTH, LAYERDZ, and LAYERTYPE should be automatically output if 
+    the user specifies any by-layer output. They are not currently, so ensure
+    that they are specified on the same timestep as the desired output.
+    HKLAYER, LAYERDEPTH, LAYERDZ, LAYERTYPE, TCLAYER, TLAYER, and VWCLAYER 
+    must have the layer option specified or they will generate NetCDF 
+    dimension bound errors.
+
+
+-------------
+Process
+-------------
+    WRITE THIS...
+
+.. note:: draft thoughts:
+    A single output file will be produced for each entry in the specifying file, 
+    based on variable name, timestep, and run stage.
+    VEGC_monthly_eq.nc
+    At the beginning of the model run, an output file will be constructed for each 
+    variable specified, for each run stage where NetCDF output is indicated and that 
+    has more than 0 years of run time.
+    Currently the model tracks the variables specified for each timestep as separate 
+    sets (i.e. monthly separate from yearly, etc). This reduces the number of map 
+    lookups every time the output function is called, but increases the number of 
+    monthly vs. yearly string comparisons.
+
+------------------------------
+Variable Output Combinations
+------------------------------
     WRITE THIS...
 
+.. note:: draft thoughts:
+    '-' indicates that the combination is not an option 'x' indicates that the
+    combination has been implemented in the code '?' indicates that it is undecided 
+    if the combination should be made available, or that structure in the code needs 
+    to be modified to make data available for output.
+    Three variables should be automatically written out if any by-layer variable is 
+    specified: Layer type Layer depth Layer thickness Currently they are written out 
+    like standard variables. Automation will need to be added in the future.
+
+
 ==================================
 Processing Inputs
 ==================================

docs_src/sphinx/source/software_development_info.rst

@@ -115,7 +115,8 @@ To build the Sphinx documentation (this document) locally, then do the following
     .. code:: shell
 
       $ make clean
-      $ PYTHONPATH="/work:/work/calibration:$PYTHONPATH" make html
+      $ export PYTHONPATH="/work:/work/scripts:/work/scripts/util:/work/calibration:$PYTHONPATH" 
+      $ make html
 
 
 The resulting files are in the ``docs_src/sphinx/build/html`` directory and can
@@ -256,8 +257,8 @@ image to render, directly from Google Docs when someone loads the page:
 
 .. code:: html
 
-   <!-- From Tobey Carman's google drawing "dvmdostem-general-idea-science"-->
-   <img src="https://docs.google.com/drawings/d/17AWgyjGv3fWRLhEPX7ayJKSZt3AXcBILXN2S-FGQHeY/pub?w=960&amp;h=720">
+   <!-- From Shared Drive > "Documentation Embed Images, dvmdostem-general-idea-science"-->
+   <img src="https://docs.google.com/drawings/d/e/2PACX-1vT8BiV8S8_oCTOghlwsSkdyoxY7bm1sArD6y_JVx8PEBQF5OF3KYEonCH1v5T0bDbqsGw8zMDaZvoSh/pub?w=966&amp;h=519">
 
 If the original Google Drawing is updated, then the drawing seen in the wiki 
 will be updated too. Take caution with the permissions granted for editing 
@@ -267,14 +268,14 @@ on the original drawing!
 
    When you are editing an image that is embedded, the edits are automatically
    live on the published website! This is fine for quick edits such as fixing a
-   typo, but for anything more substantial, it is reccomended that you make a
+   typo, but for anything more substantial, it is recommended that you make a
    duplicate of the Google Drawing, edit the duplicate and then copy it back
    over the original. This will keep your edits from showing up on the live site
    until you are done with them!
 
 .. warning:: 
 
-   Soure drawings for this document should probably be stored in the 
+   Soucre drawings for this document should probably be stored in the 
    Shared Google Drive so that they are not tied to an individual's account.
 
 In Google Docs, there is a way to insert a Google Drawing from a menu: 

requirements_general_dev.txt

@@ -6,14 +6,18 @@ netCDF4==1.5.8
 commentjson==0.9.0
 ipython==8.10.0
 jupyter==1.0.0
-jupyter-sphinx==0.4.0
 lhsmdu==1.1
-Sphinx==5.1.1
-sphinx-rtd-theme==1.1.0
-sphinx-toolbox==3.4.0
-sphinx-argparse==0.4.0
 xarray==2023.1.*
 pypdf==5.1.*
 
 # for SA - maybe merits its own file??
 scikit-learn
+
+# For building documentation
+Sphinx==5.1.1
+sphinx-rtd-theme==1.1.0
+sphinx-toolbox==3.4.0
+sphinx-argparse==0.4.0
+sphinxcontrib-bibtex
+jupyter-sphinx==0.4.0
+