diff --git a/README.md b/README.md index 79ab5fe79..cb0bdb99a 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,25 @@ -## Important: Please see Doxygen and Git Commits - ## Table of Contents 1. Model Overview -2. Repository Contents +2. Current version and stable release versions +3. Repository Contents 4. Implementation Notes -5. Further Info - 1. Doxygen and Git Commits - 1. General Doxygen Info - +5. Further Information +6. Code Development, Pull Requests, and Commits + + ## Model Overview The Ecosystem Demography Biosphere Model (ED2) is an integrated terrestrial biosphere model incorporating hydrology, land-surface biophysics, vegetation dynamics, and soil carbon and nitrogen biogeochemistry (Longo et al. 2019;Medvigy et al., 2009). Like its predecessor, ED (Moorcroft et al., 2001), ED2 uses a set of size- and age-structured partial differential equations that track the changing structure and composition of the plant canopy. With the ED2 model, in contrast to conventional biosphere models in which ecosystems with climatological grid cells are represented in a highly aggregated manner, the state of the aboveground ecosystem is described by the density of trees of different sizes and how this varies across horizontal space for a series of plant functional types. This more detailed description of ecosystem composition and structure enables the ED2 model to make realistic projections of both the fast-timescale exchanges of carbon, water and energy between the land and atmosphere, and long-term vegetation dynamics incorporating effects of ecosystem heterogeneity, including disturbance history and recovery. +## Current version and stable release versions + +- This code available on GitHub is the current version of the model, updated frequently. +- The latest stable version of the code (ED-2.2) can be found here. +- For former versions of ED or ED2, check the Moorcroft Lab website. +- A summary of the main changes between stable releases is available here. + ## Repository Contents Copies of the ED2 repository should contain the following directories: - ED: Contains the ED source code (src) and the directory for compilation (build). For further instructions on how to compile and use the model, we strongly suggest accessing the ED Wiki website: https://github.com/EDmodel/ED2/wiki @@ -33,7 +39,7 @@ The primary data structure in ED, which can be found in ed_state_vars.F90, is a - patch: A collection of cohorts sharing a disturbance history and age. - cohort: A collection of plants of identical PFT and height. -Note: height and age, being continuous variables, are "binned". "Identical" in the above refers to bin membership. +Note: height and age, being continuous variables, are "binned". "Identical" in this context means sufficiently similar to be placed in the same bin. These bins are dynamically defined, based on the number of classes sought by the user and the similarity along the age and height axes. ## Further Information @@ -41,48 +47,9 @@ Note: height and age, being continuous variables, are "binned". "Identical" in t - For the technical description of the various ED2 model features, we suggest looking at this reference list (Tip: do not skip the Supporting Information of these papers, they contain relevant details). - For a partial list of studies that have used ED or ED2, check here. -##Stable version - -- The latest stable version of the code (ED-2.2) can be found here. -- For former versions of ED or ED2, check the Moorcroft Lab website. - -### Doxygen and Git Commits: -In order for further pull requests to the mainline to be accepted, modified subroutines will require the following doxygen tags: - - Brief subroutine descriptions using the brief tag - - Detailed subroutine descriptions using the details tag - - Subroutine authorship statements using author tag - - Inline subroutine argument descriptions using "!< comment" - -Please do not commit changes to model code and documentation together if high numbers of documentation files have been modified. Instead ... - - Submit a pull request to the mainline with a comment that docs needs regeneration or - - Seperately pull request code changes and documentation updates +## Code Development, Pull Requests, and Commits -Finally, please note: - - Seperating code and doc changes will make inter-branch comparison much easier when many files are modified. - - Regenerating documentation may produce many spurious line-end encoding differences which git will pick up on. "git add"-ing such files will often return them to the repo standard CRLF, and they will cease to be listed as modified. - -### General Doxygen Info -The following info may be helpful for familiarizing one's self with Doxygen, an auto-documentation program which utilizes a system of tags in source code. To tag a subroutine in the ED model as required above, try taking ed_model.f90 as a template and/or browsing the first few links below. - - NASA Doxygen Quickstart: https://modelingguru.nasa.gov/docs/DOC-1811 - - Doxygen Keywords: https://www.stack.nl/~dimitri/doxygen/manual/commands.html - - Doxygen Documentation: https://www.stack.nl/~dimitri/doxygen/manual/index.html - -More General Info - - http://www.msg.chem.iastate.edu/gamess/DoxygenRules.oct10.pdf - - http://stackoverflow.com/questions/51667/best-tips-for-documenting-code-using-doxygen - - https://www.rosettacommons.org/manuals/rosetta3.2_user_guide/doxygen_tips.html - -Mainpage & custom file construction links: - - http://stackoverflow.com/questions/10136201/mainpage-in-doxygen-documentation?rq=1 - - http://stackoverflow.com/questions/9502426/how-to-make-an-introduction-page-with-doxygen - - http://stackoverflow.com/questions/13368350/use-the-readme-md-file-as-main-page-in-doxygen - - http://stackoverflow.com/questions/3052036/how-to-include-custom-files-in-doxygen/6336368#6336368 - - http://stackoverflow.com/questions/2337307/doxygen-adding-a-custom-link-under-the-related-pages-section - -Using grouping: - - http://www.stack.nl/~dimitri/doxygen/manual/grouping.html +If you plan to develop the code, please refer to the Wiki entries on code organization and design philosophy, to ensure your code developments are consistent with the existing model. Also, make sure that the code is thoroughly tested, and successfully passes the internal GitHub tests. -Configuration: - - http://www.doxygen.nl/config.html +We strongly encourage that code developments are properly documented. Please refer to the Doxygen instructions, and especially the Doxygen and Git commits section, so additional documentation can be automatically generated from the source code comments. -Documentation generated by doxygen can be accessed (locally) on a machine with this repository under Doc/html/index.html