-
Notifications
You must be signed in to change notification settings - Fork 383
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add documentation to EAM's User and Tech guides #6314
Conversation
|
@@ -0,0 +1,21 @@ | |||
# Five-mode Modal Aerosol Model |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See the suggested changes below.
|
||
## Chemistry | ||
|
||
- [chemUCI + Linoz v3](chemUCIlinozv3.md): The parameterization of interactive atmospheric chemistry in EAMv3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- [chemUCI + Linoz v3](chemUCIlinozv3.md): The parameterization of interactive atmospheric chemistry in EAMv3. | |
- [chemUCI + Linoz v3](chemUCIlinozv3.md): The interactive atmospheric chemistry packages in EAMv3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Hi @crterai , thanks for drafting this PR. I noticed some mismatched descriptions of input variables. Since these variables are self-explanatory, they can be left as blanks.
| `chlorine_loading_fixed_ymd` | Directory of P3 look-up tables | | | ||
| `chlorine_loading_type` | P3 look-up table Version | | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| `chlorine_loading_fixed_ymd` | Directory of P3 look-up tables | | | |
| `chlorine_loading_type` | P3 look-up table Version | | | |
| `chlorine_loading_fixed_ymd` | | | | |
| `chlorine_loading_type` | | | |
| `ext_frc_cycle_yr` | Output of P3 microphysical process rates | | | ||
| `ext_frc_type` | Tunable parameter for adjusting rain accretion efficiency | | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| `ext_frc_cycle_yr` | Output of P3 microphysical process rates | | | |
| `ext_frc_type` | Tunable parameter for adjusting rain accretion efficiency | | | |
| `ext_frc_cycle_yr` | | | | |
| `ext_frc_type` | | | |
| `srf_emis_cycle_yr` | Radius of embryomic raindrops from auto-conversion | | | ||
| `srf_emis_type` | Upper bound of mean raindrop diameter | | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| `srf_emis_cycle_yr` | Radius of embryomic raindrops from auto-conversion | | | |
| `srf_emis_type` | Upper bound of mean raindrop diameter | | | |
| `srf_emis_cycle_yr` | | | | |
| `srf_emis_type` | | | |
| `linoz_data_cycle_yr` | Nc exponent in droplet auto-conversion | | | ||
| `linoz_data_path` | Qc exponent in rain accretion | | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| `linoz_data_cycle_yr` | Nc exponent in droplet auto-conversion | | | |
| `linoz_data_path` | Qc exponent in rain accretion | | | |
| `linoz_data_cycle_yr` | | | | |
| `linoz_data_path` | | | |
| `linoz_data_file` | Linoz data file | | | ||
| `linoz_data_cycle_yr` | Nc exponent in droplet auto-conversion | | | ||
| `linoz_data_path` | Qc exponent in rain accretion | | | ||
| `linoz_data_type` | Qc exponeent in droplet autoconversion | | |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| `linoz_data_type` | Qc exponeent in droplet autoconversion | | | |
| `linoz_data_type` | | | |
|
||
## Aerosol | ||
|
||
- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv3. | |
- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv2. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All our simulations used MAM5 not MAM4, as suggested by configuration 'superfast_mam5_resus_mom_soag'. MAM5 has been developed upon MAM4 and kept all the four modes in MAM4. However, MAM5 is a whole package to replace MAM4.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
MAM4 is an option of aerosol scheme in E3SMv3
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @keziming. I had intended MAM5 to describe the addition of the fifth mode for the stratospheric coarse mode and the MAM4 to describe all of the aerosol processes that we have inherited from EAMv0. Since MAM4 that we inherited covers most of the processes that we run in EAMv3, I had noted it as the primary parameterization scheme.
Maybe there is a better way to describe what is under MAM4 and MAM5. @hwangacme - do you have any thoughts?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks @hwangacme. I'll make that change.
|
||
- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv3. | ||
|
||
- [MAM5](mam5.md): The parameterization scheme to represent stratospheric sulfate aerosols in EAMv3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
- [MAM5](mam5.md): The parameterization scheme to represent stratospheric sulfate aerosols in EAMv3. | |
- [MAM5](mam5.md): The primary parameterization scheme to represent aerosols in EAMv3. The fifth mode is the stratospheric aerosols mode, which added upon previous MAM4 to represent sulfate aerosols in the stratosphere. |
|
||
### Namelist changes | ||
|
||
Namelist parameters can be specified in the `user_nl_eam` file. While most can be added at run time, some need to be added before `./case.setup` to have the changes applied in the simulation. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What paramateres in user_nl_eam need to be specified before case.setup?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Talking to @wlin7, they appear to be specifically in the chemistry and RRTMG, so I've rephrased this and will note them alongside the specific parameters.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@wlin7 I still don't understand how that works. You're saying that if I change something in user_nl_eam and then run "case.build", different code will be compiled? I'm pretty sure CIME doesn't work that way. The user namelist is strictly for run-time changes.
|
||
Namelist parameters can be specified in the `user_nl_eam` file. While most can be added at run time, some need to be added before `./case.setup` to have the changes applied in the simulation. | ||
|
||
Refer to the individual schemes in the [tech-guide](../tech-guide/index.md) for a list of namelist parameters associated with each scheme in the atmosphere. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think all the namelist paramaters should be covered in the user's guide since they are fundamental to using the model.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a good point. Under the User's Guide section, I've created a new markdown document with all of the namelist parameters and linked it in the top level User's guide.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I like what I see in https://docs.e3sm.org/E3SM/pr-preview/pr-6314/EAM/user-guide/namelist_parameters/ but why doesn't that appear in the table of contents for the users-guide?
## Overview | ||
|
||
The ARM data-oriented metrics and diagnostics package (ARM Diags) was developed to facilitate the use of ARM data in climate model evaluation and model intercomparison (Zhang et al. 2020). It includes ARM data sets, compiled from multiple ARM data products, and a Python-based analysis toolkit for computation ad visualization. It also includes simulation data from models participating the CMIP, which allows climate-modeling groups to compare a new, candidate version of their model to existing CMIP models. The ARM Diags has been applied in several model evaluation studies to help address a range of issues in climate models (Zheng et al. 2023; Emmenegger et al. 2022; Zhang et al. 2018). The Majority of ARM Diags sets are ported into E3SM Diags (Zhabg et al. 2022) for routine evaluation of the model. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
A typo above in 'Zhabg et al. 2022'
@rljacob we discussed about version control yesterday. Take this PR for example, where should we note that this doc is made for version3? Should we have EAMv3 (instead of EAM) under components? |
All documentation is "for master" until we have complete documentation. We decided long ago that the way to get older versions is on a maint branch. |
|
||
#### Example output specification: | ||
|
||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This code block didn't get rendered correctly at https://e3sm-project.github.io/E3SM/pr-preview/pr-6314/EAM/user-guide/#example-output-specification
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@crterai, looks much better. One minor note: These #
s should be !
s (just in case someone copy-pasted this into their user_nl_eam)
|
||
#### Land-use / land cover change | ||
|
||
- <span style="color:red">Info needed on land-use land cover change / land surface data</span> |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@bishtgautam - Could I get some help with a short description of the land-use land-cover change that we would use in the F2010, F1850, and F20TR simulations?
- Original physical properties of aerosols are documented in Liu et al. (2012) [@liu_toward_2012]. Detailed information is included in the supplement. | ||
|
||
- Physical properties of aerosols used in E3SMv1 are documented in Wang et al. (2020) [@wang_aerosols_2020]. | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Physical properties of the fifth mode aerosols are documented by Ke et al. (2024, in preparation)
Removed WIP label, since I believe all reviewer suggestions have been addressed. |
Pinging @susburrows and @chengzhuzhang since I believe you'd also want to review this before it is merged. |
|
||
## To enable the use of ARM Diags | ||
|
||
To enable using ARM Diags for a simulation, often, a new tape that output at high-frequency over limited-area (nearest grid box to supported ARM site) needs to be included in the namelist file, an example as follows: | ||
|
||
``` | ||
```text | ||
fincl7 = 'PS','Q','T','Z3','CLOUD','CONCLD','CLDICE','CLDLIQ','FREQR','REI','REL','PRECT','TMQ','PRECC','TREFHT','QREFHT','OMEGA','CLDTOT','LHFLX','SHFLX','FLDS','FSDS','FLNS','FSNS','FLNSC','FSDSC','FSNSC','AODVIS','AODABS','LS_FLXPRC','LS_FLXSNW','LS_REFFRAIN','ZMFLXPRC','ZMFLXSNW','CCN1','CCN2','CCN3','CCN4','CCN5','num_a1','num_a2','num_a3','num_a4','so4_a1','so4_a2','so4_a3','AREL','TGCLDLWP','AQRAIN','ANRAIN','FREQR','PRECL','RELHUM' |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Please break this line up. Its not rendering correctly.
This is some great content! I don't see the references rendering correctly in the Tech Guide. |
Thanks for rebasing and bringing in the fixes, @mahf708. It'd be easy for me to fix the text to fortran. I don't know where to make those changes to the navbar though. |
I can take care of this once we get a chance to discuss it (and test a prototype solution; see E3SM-Project/E3SM-Project.github.io#2 (comment) for an example) |
components/eam/docs/index.md
Outdated
@@ -2,6 +2,6 @@ | |||
|
|||
Some introductory text here |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This should be replaced with actual introductory text. Something like "EAM is a state-of-the-art general circulation model of the atmosphere that ...."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for catching this @rljacob. After consulting with Shaocheng, I've added a couple sentences with a quick overview of EAM.
EAM using the a dynamical core (dycore) from the High Order Method Modeling Environment (HOMME). The EAM dycore solves the atmospheric primitive equations governing the evolution of velocity, density, pressure and temperature, as well as the transport of water species and related hydrometers, aerosols and other atmospheric constituents. The governing equations are written in a vertically lagrangian terrain following mass coordinate. They are discretized with second order finite differences in the radial direction and spectral finite elements in the horizontal (surface of the sphere) directions, and advanced in time with a 3rd order accurate 5 stage Runge-Kutta method. Dissipation is added through the use of monotoncity contraints on some advectiion terms, explicitly added hyperviscosity, and a Laplacian-based sponge layer in the first few layers at the model top. The transported species makes use of an efficient interpolatory semi-Lagrangian method. EAMv3 uses 80 layers in the vertical. The use of the spectral finite element method allows EAMv3 to run on fully unstructured grids, including the cubed-sphere grid ([SE Atmosphere Grid Overview (EAM & CAM)](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/34113147)) which provides quasi-uniform resolution over the globe, and regionally refined meshes (RRM) which enhance horizontal resolution in regions of interest ([Library of Regionally-Refined Model (RRM) Grids](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/3690397775)). | ||
|
||
### References | ||
|
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't break out the references separately. Keep them inline as done in other sections like P3 and MAM. The bib function makes a better version of this.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've added the references in the overview text as suggested.
|
||
### References | ||
|
||
- Larson (2022) [@larson_clubb-silhs_2022] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't break out the references separately. Keep them inline as done in other sections like P3 and MAM. You can put all of these after the first sentence.
|
||
### References | ||
|
||
- Zhang et al. (2024) [@zhang_understanding_2024] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Don't break out the references separately. Keep the footnote references inline as done in other sections like P3 and MAM.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm concerned that the material here is duplicated in each of the markdown files in the tech-guide. It should live in one place and I think it should be here. You could link to each section here from the tech guide. For example, in clubb.md, add
[Namelist Paramters](../user-guide/namelist_parameters.md#cloud-layers-unified-by-binormals)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It makes sense to just have one copy so that any subsequent changes don't need to be made in two places. I've added the link, as you'd suggested.
Clean up users guide removing the in-page TOC and add bigger links to other files. Link to CIME
I pushed some changes that mostly improve navigation. This is almost ready to merge but I'd like to see the duplicate entries of namelist params removed and the references inlined in 3 of the tech guide pieces. |
Move the history file example up with other namelist mentions. Make input data its own section instead of part of customization.
|
||
`mfilt` - List that sets the number of timesteps to write in a single file before starting a new file. | ||
|
||
`avgflag_pertape` - List that sets the type of output to write. Choices are `'A'` for time-averaged output, `'A'` for instantaneous output, `'MIN'` for time-minimum output, and `'MAX'` for time-maximum output. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Need to replace MIN
with M
, and MAX
with X
for the avgflag above.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Done.
due to its need by the bib extention
I've pushed some changes that remove the duplicate entries of namelist parameters, add the references inline, add the top-level EAM description, and fixes the issue @wlin7 caught above. |
Add documentation to EAM's User and Tech guides This PR adds documentation related to the EAM, with specific emphasis on the schemes and input datasets used in EAMv3. [BFB] * origin/crterai/eam/add_documentation: (29 commits) don't bother linting reversed links Fix output labels in EAM docs Add top level description of EAM in docs Update the citation format in EAM docs Link all namelist parameters to single source in EAM docs Fix the citations format in EAM docs Additional re-org of eam user guide content Clean up users guide Add more eam docs to navigation Remove v3 refs from tech guide. Fix code block formatting in EAM docs Combine MAM4 and MAM5 description in EAM docs fix linting errors unify how we say developer/user/technical guide make reference lists into lists and fix typos fix misplaced search entry in plugins fixing bib linking Fix top-level description of MAM4 and MAM5 in EAM docs Fix reference to ELM docs in EAM docs Add MAM5 aerosol properties citation in EAM docs ...
This PR adds documentation related to the EAM, with specific emphasis on the schemes and input datasets used in EAMv3.
Contributions from @susburrows, Jack Chen, @brhillman, @DJFJJA, Guang Zhang, @hwangacme, @mingxuanwupnnl, @wlin7, @vlarson, @Jiwengithub, @jinboxie, @tangq, @yfenganl, Manish Shrivastava, @mt5555, @kaizhangpnl, @zyuying, @chengzhuzhang, Cheng Tao, @keziming