Skip to content
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

Merged
merged 29 commits into from
May 3, 2024

Conversation

crterai
Copy link
Contributor

@crterai crterai commented Mar 29, 2024

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

@crterai crterai added Atmosphere Documentation BFB PR leaves answers BFB labels Mar 29, 2024
Copy link

github-actions bot commented Mar 29, 2024

PR Preview Action v1.4.7
🚀 Deployed preview to https://E3SM-Project.github.io/E3SM/pr-preview/pr-6314/
on branch gh-pages at 2024-05-02 21:17 UTC

@@ -0,0 +1,21 @@
# Five-mode Modal Aerosol Model
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@keziming @crterai I just updated this part.

Copy link
Contributor

@tangq tangq left a 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [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.

Copy link
Contributor

@tangq tangq left a 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.

Comment on lines 13 to 14
| `chlorine_loading_fixed_ymd` | Directory of P3 look-up tables | |
| `chlorine_loading_type` | P3 look-up table Version | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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` | | |

Comment on lines 16 to 17
| `ext_frc_cycle_yr` | Output of P3 microphysical process rates | |
| `ext_frc_type` | Tunable parameter for adjusting rain accretion efficiency | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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` | | |

Comment on lines 19 to 20
| `srf_emis_cycle_yr` | Radius of embryomic raindrops from auto-conversion | |
| `srf_emis_type` | Upper bound of mean raindrop diameter | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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` | | |

Comment on lines 22 to 23
| `linoz_data_cycle_yr` | Nc exponent in droplet auto-conversion | |
| `linoz_data_path` | Qc exponent in rain accretion | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `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 | |
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| `linoz_data_type` | Qc exponeent in droplet autoconversion | |
| `linoz_data_type` | | |


## Aerosol

- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv3.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv3.
- [MAM4](mam4.md): The primary parameterization scheme of aerosols in EAMv2.

Copy link
Contributor

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.

Copy link
Contributor

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

Copy link
Contributor Author

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?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @keziming for pointing this out. As I discussed with @crterai offline, a higher-level, explicit description of MAM5 as the default option of EAMv3 aerosol module is more preferable.

Copy link
Contributor Author

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- [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.
Copy link
Member

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?

Copy link
Contributor Author

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.

Copy link
Member

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.
Copy link
Member

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.

Copy link
Contributor Author

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.

Copy link
Member

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.

Copy link
Contributor

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'

@chengzhuzhang
Copy link
Contributor

@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?

@rljacob
Copy link
Member

rljacob commented Apr 11, 2024

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:

```
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Contributor

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>
Copy link
Contributor Author

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].

Copy link
Contributor

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)

@crterai
Copy link
Contributor Author

crterai commented Apr 26, 2024

@tangq @rljacob - I've updated the PR to address your suggested changes. Would you please review the changes?

@crterai crterai changed the title [WIP] Add documentation to EAM's User and Tech guides Add documentation to EAM's User and Tech guides Apr 26, 2024
@crterai
Copy link
Contributor Author

crterai commented Apr 26, 2024

Removed WIP label, since I believe all reviewer suggestions have been addressed.

@crterai
Copy link
Contributor Author

crterai commented Apr 26, 2024

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'
Copy link
Member

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.

@rljacob
Copy link
Member

rljacob commented Apr 26, 2024

This is some great content!

I don't see the references rendering correctly in the Tech Guide.
I think you should drop the subheadings in the Tech Guide main page. There's not enough content under each subheading (like "Microphysics) to justify it.

@crterai
Copy link
Contributor Author

crterai commented Apr 29, 2024

@rljacob @crterai: I fixed the bib linking (was broken before my commit) and rebased to bring in all features from the main branch.

In my mind there are two items worth improving (but could be delayed to a separate PR):

1. the nav bar should include all these added pages (e.g., see the soft warning below). We can do this either manually or more automatically later (I am working on a general solution)

2. There are fortran code blocks in there (the namelist ones are actually fortran, not text, but that's not important)
INFO    -  The following pages exist in the docs directory, but are not included in the "nav" configuration:
             - EAM/tech-guide/armdiags.md
             - EAM/tech-guide/chemUCIlinozv3.md
             - EAM/tech-guide/clubb.md
             - EAM/tech-guide/cosp.md
             - EAM/tech-guide/dust.md
             - EAM/tech-guide/homme.md
             - EAM/tech-guide/mam4.md
             - EAM/tech-guide/mam5.md
             - EAM/tech-guide/oceanfilms.md
             - EAM/tech-guide/p3.md
             - EAM/tech-guide/rrtmg.md
             - EAM/tech-guide/vbs.md
             - EAM/tech-guide/zm.md
             - EAM/user-guide/aerosol_phys_prop.md
             - EAM/user-guide/emission_oxidant_files.md
             - EAM/user-guide/namelist_parameters.md
             - EAMxx/technical/index.md
             - ELM/dev-guide/testing.md
             - ELM/tech-guide/top_solar_parameterization.md

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.

@mahf708
Copy link
Contributor

mahf708 commented Apr 30, 2024

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)

@crterai crterai requested a review from shaochengx April 30, 2024 18:36
@@ -2,6 +2,6 @@

Some introductory text here
Copy link
Member

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 ...."

Copy link
Contributor Author

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

Copy link
Member

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.

Copy link
Contributor Author

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]
Copy link
Member

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]
Copy link
Member

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.

Copy link
Member

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)

Copy link
Contributor Author

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.

rljacob added 3 commits April 30, 2024 22:21
Clean up users guide removing the in-page TOC and add bigger links
to other files. Link to CIME
@rljacob
Copy link
Member

rljacob commented May 1, 2024

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.
Copy link
Contributor

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

@crterai
Copy link
Contributor Author

crterai commented May 2, 2024

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.

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.

wlin7 added a commit that referenced this pull request May 3, 2024
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
  ...
@wlin7 wlin7 merged commit 2db82b3 into master May 3, 2024
14 checks passed
@wlin7 wlin7 deleted the crterai/eam/add_documentation branch May 3, 2024 00:36
@crterai
Copy link
Contributor Author

crterai commented May 3, 2024

Thanks, @rljacob, @wlin7, and @mahf708 for improving and pushing this PR along.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Development

Successfully merging this pull request may close these issues.

9 participants