diff --git a/components/elm/docs/user-guide/fates.md b/components/elm/docs/user-guide/fates.md new file mode 100644 index 000000000000..390f714ee0c2 --- /dev/null +++ b/components/elm/docs/user-guide/fates.md @@ -0,0 +1,21 @@ +# FATES + +FATES (Functionally Assembled Terrestrial Ecosystem Simulator) is a numerical terrestrial ecosystem model +hat can be utilized as a component with various host land models such as ELM. It is incorporated as an +external module, the development of which is primarily supported by the Department of Energy’s Office of +Science, through the [Next Generation Ecosystem Experiment - Tropics (NGEE-T) project](https://ngee-tropics.lbl.gov/). + +The FATES code is hosted online through a github repository at [https://github.com/NGEET/fates](https://github.com/NGEET/fates). + +## Technical Document + +The full FATES documentation detailing the scientific underpinnings of the model can be found in the +[FATES Technical Document](https://fates-users-guide.readthedocs.io/projects/tech-doc/en/stable/) +hosted on ReadTheDocs. + +## User's and Developer's Guide + +The FATES team also provides a [User's guide](https://fates-users-guide.readthedocs.io/en/latest/user/users-guide.html) +and a [Developer's guide](https://fates-users-guide.readthedocs.io/en/latest/developer/developer-guide.html) +also hosted on ReadTheDocs. Both guides and the technical documentation can be reached from the top level +[User's Guide](https://fates-users-guide.readthedocs.io/en/latest/index.html) diff --git a/components/elm/docs/user-guide/index.md b/components/elm/docs/user-guide/index.md index 0ec3b413c3fb..7995e54acb36 100644 --- a/components/elm/docs/user-guide/index.md +++ b/components/elm/docs/user-guide/index.md @@ -1 +1,78 @@ -start of the ELM User's Guide +# ELM User's Guide + +This User's Guide describes how to set up and run ELM. + +## Steps to build and run ELM + +A step-by-step instruction on how to run fully coupled E3SM can be found [here](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/2309226536). Here we describe running ELM driven by atmospheric forcings provided via the data atmosphere (DATM) model for configurations that are used in the E3SM water cycle v3 campaign. + +The water cycle campaigns of E3SM v1 and v2 used ELM's satellite phenology mode (SP-mode) in which a prescribed leaf area index is used in ELM. However, the E3SM v3 water cycle campaign uses an interactive phenology by including an active biogeochemistry (BGC) cycle in ELM. Additionally, a parameterization of sub-grid topographical effects on solar radiation is included within ELM. + +### Scientifically supported compsets + +The land-only compsets are referred to as "I"-compset and are supported for the following time periods: pre-industrial (1850) and historical transient (20TR). Additionally, multiple atmospheric forcing datasets can be used to drive the ELM simulations. The supported compsets are: + +1. `I1850GSWCNPRDCTCBCTOP`: Pre-industrial ELM simulation using atmospheric forcings from GSWP3 reanalysis dataset +2. `I20TRGSWCNPRDCTCBCTOP`: Historical ELM simulation using GSWP atmospheric forcings with time varying greenhouse gas forcing and land use, land cover dataset (year 1850-2014). + +The E3SM coupler output forcings are most commonly used as an offline land model spinup step, in preparation for a fully-coupled E3SM experiment. + +### Supported grid + +The `r05_r05` is the supported grid resolution for performing offline ELM simulation. + +## Customizing runs + +Few useful changes to `user_nl_elm` + +### Changing monthly output file + +ELM by default outputs monthly history file in `*elm.h0.**.nc` files +that include many variables (>200). At times, many of the default output +variables may not be of interest, thus one could remove all default variables +(via `hist_empty_htapes`) and only include select variables (via `hist_fincl1`) +to the monthly history files by + +```fortran + &elm_inparm + hist_empty_htapes = .true. + hist_fincl1 = 'TG', 'TV', 'FSA' + / +``` + +#### Saving additional output files + +ELM can output additional history files (such as `*elm.h1.*.nc`, `*elm.h2.*.nc`) +that have different temporal averaging (e.g. daily, hourly, every model timestep) via +`hist_nhtfrq` where + +- `-24` corresponds to daily average +- `-1` corresponds to hourly average +- `0` corresponds to monthly average +- `1` corresponds to each model time step + +The number of time slices in these additional files can be controlled +vai `hist_mfilt`. + +```fortran + &elm_inparm + hist_fincl2 = 'TG' + hist_fincl3 = 'TV' + hist_fincl4 = 'TG', 'TV', 'FSA' + hist_nhtfrq = 0, -24, -1, 1 + hist_mfilt = 12, 30, 24, 48 + / +``` + +Using the above-mentioned settings: + +- Each `*.elm.h1.*.nc` will include 30 daily average values of `TG` +- Each `*.elm.h2.*.nc` will include 24 hourly average values of `TV` +- Each `*.elm.h3.*.nc` will include 48 values of `TG`, `TV`, and `FSA` at + each model time step, which is typically is 30 min. + +## Running with FATES + +[FATES](fates.md) can be run in various modes with ELM through the use of namelist settings. +The [FATES User's Guide section on namelist options](https://fates-users-guide.readthedocs.io/en/latest/user/Namelist-Options-and-Run-Time-Modes.html) +provides guidance on enabling these different FATES run modes.