Add documentation to EAM's User and Tech guides

components/eam/docs/dev-guide/index.md

@@ -1 +1,3 @@
-start of the EAM Developer's Guide
+# EAM Developer Guide
+
+coming soon.

components/eam/docs/index.md

@@ -1,7 +1,7 @@
 # The E3SM Atmosphere Model (EAM)
 
-Some introductory text here
+EAM is the state-of-the-art atmospheric component of the E3SM model that uses a Spectral Element Dynamical Core and a suite of parameterizations to represent a range of atmospheric processes, which are described in the Technical Guide (see below). Its nominal resolution is roughly 100km in the horizontal, with a model time step of 1800 seconds, and runs with 80 layers in the vertical (model top of 60km).
 
-* The [EAM User's Guide](user-guide/index.md) explains how to control EAM when its running within E3SM.
-* The [EAM Developer's Guide](dev-guide/index.md) explains EAM data structures and how to write new code.
-* The [EAM Techincal Guide](tech-guide/index.md) explains the science behind EAM's code
+* The [EAM User Guide](user-guide/index.md) explains how to control EAM when its running within E3SM.
+* The [EAM Developer Guide](dev-guide/index.md) explains EAM data structures and how to write new code.
+* The [EAM Technical Guide](tech-guide/index.md) explains the science behind EAM's code

components/eam/docs/tech-guide/armdiags.md

@@ -0,0 +1,56 @@
+# ARM diagnostics
+
+## 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)[@zhang_arm_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;[@zheng_assessment_2023] Emmenegger et al., 2022;[@emmenegger_evaluating_2022] Zhang et al., 2018[@zhang_causes_2018]). The Majority of ARM Diags sets are ported into E3SM Diags (Zhang et al., 2022)[@zhang_e3sm_2022] for routine evaluation of the model.
+
+## 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:
+
+```fortran
+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'
+fincl7lonlat='262.5e_36.6n','203.4e_71.3n','147.4e_2.0s',
+   '166.9e_0.5s','130.9e_12.4s','331.97e_39.09n'
+```
+
+Note that in this example fincl7 should set to write output at hourly (`nhtfrq = -1`). And here additional variables are included for ARM simulator analysis. The ARM site information is shown below:
+
+```fortran
+    "sgpc1": ["97.5W 36.4N Oklahoma ARM"],
+
+    "nsac1": ["156.6W 71.3N Barrow ARM"],
+
+    "twpc1": ["147.4E 2.1S Manus ARM"],
+
+    "twpc2": ["166.9E 0.5S Nauru ARM"],
+
+    "twpc3": ["130.9E 12.4S Darwin ARM"],
+
+    "enac1": ["28.0E 39.1N Graciosa Island ARM"], 
+```
+
+## Diagnostics and metrics currently implemented in the ARM Diags
+
+| Statistical Metrics       | Variables                                                       |  Time sampling     |
+| ------------------------- | --------------------------------------------------------------- | -----------------  |
+| Line plots and Taylor diagrams for annual cycle variability of each variable | Precipitation, column water vapor, surface energy budget components, near-surface temperature and specific humidity, surface pressure, total cloud fraction, and aerosol optical depth. | Monthly mean       |
+| Contour and vertical profiles of annual cycle and diurnal cycle of cloud fraction | Vertical profiles of cloud fraction | Hourly mean       |
+| Line and harmonic dial plots of diurnal cycle of precipitation | Surface precipitation rate | Hourly mean       |
+| Probability density function (PDF) plots of precipitation rate | Surface precipitation rate | Hourly mean       |
+| CCN Annual Cycles  | CCN number concentrations at 0.1%, 0.2%, 0.5% and 1.0% supersaturation levels | Hourly mean       |
+| Aerosol Annual Cycles | Total aerosol number concentration | Hourly mean       |
+| Aerosol Chemical Annual Cycles | Organic, sulfate, nitrate, ammonium, chloride mass concentration | Hourly mean       |
+
+| Process-oriented metrics  | Variables                                                     |  Time sampling     |
+| ------------------------- | ------------------------------------------------------------- | -----------------  |
+| Convection Onset | 1. Surface precipitation rate <!-- markdownlint-disable MD033 --><br>  2. Column Precipitable Water Vapor | Hourly mean       |
+| Aerosol-CCN Activation | 1. Total aerosol number concentration <br>  2. CCN number concentrations at different supersaturation levels (0.1%, 0.2%, 0.5% and 1.0) | Hourly mean       |

components/eam/docs/tech-guide/chemUCIlinozv3.md

@@ -0,0 +1,9 @@
+# chemUCI and Linoz
+
+## Overview
+
+Atmospheric interactive chemistry is handled by chemUCI (in the troposphere) and Linoz v3 (in the stratosphere). chemUCI consists of 28 advected tracers for the O3-CH4-HOx-NOx-NMVOCs chemistry. Compared to E3SMv2, the E3SMv3 linearized stratospheric chemistry scheme (Linoz v3) expends the interactive species to include O3, N2O, NOy, and CH4. The boundary between stratosphere and troposphere adopts the e90 tropopause algorithm.
+
+## Namelist parameters
+
+[chemUCI and Linoz Namelist Parameters](../user-guide/namelist_parameters.md#chemuci-and-linoz-v3)

components/eam/docs/tech-guide/clubb.md

@@ -0,0 +1,9 @@
+# Cloud Layers Unified By Binormals
+
+## Overview
+
+The Cloud Layers Unified By Binormals (CLUBB) parameterization is a parameterization of subgrid-scale turbulence and clouds.[@larson_clubb-silhs_2022,@bogenschutz_path_2018,@larson_using_2005,@golaz_pdf-based_2002] It prognoses turbulent fluxes of heat, moisture, and momentum, and it diagnoses the liquid cloud fraction and liquid water mixing ratio.  To do so, it prognoses higher-order turbulence moments and closes those prognostic equations by use of an assumed double-Gaussian shape of the subgrid probability density function.  CLUBB operates throughout the troposphere, but it contributes especially to the planetary boundary layer and low-cloud regimes, including stratocumulus and shallow cumulus regimes.  
+
+## Namelist parameters
+
+[CLUBB Namelist Parameters](../user-guide/namelist_parameters.md#cloud-layers-unified-by-binormals)

components/eam/docs/tech-guide/cosp.md

@@ -0,0 +1,27 @@
+# Cloud Feedback Model Intercomparison Project (CFMIP) Observation Simulator Package
+
+## Overview
+
+The Cloud Feedback Model Intercomparison Project (CFMIP) Observation Simulator Package (COSP; Bodas-Salcedo et al., 2011;[@bodas-salcedo_cosp_2011] Swales et al., 2018;[@swales_cloud_2018] Zhang et al., 2019;[@zhang_evaluation_2019] Zhang et al., 2024[@zhang_understanding_2024]) was developed to improve the consistency between model clouds and satellite observations. COSP contains several independent satellite simulators for better comparing model clouds with satellite measurements collected by the International Satellite Cloud Climatology Project (ISCCP), the Moderate Resolution Imaging Spectroradiometer (MODIS), the Multi-angle Imaging SpectroRadiometer (MISR), Cloud-Aerosol Lidar and Infrared Pathfinder Satellite Observation (CALIPSO), and CloudSat. The use of satellite simulators will not only make a fairer comparison between model clouds and satellite data but also allow a more in-depth analysis of clouds. For example, clouds can be assessed in terms of their optical properties and vertical location, which dictate their radiative effects.
+
+## Namelist parameters
+
+[COSP Namelist Parameters](../user-guide/namelist_parameters.md#cloud-feedback-model-intercomparison-project-cfmip-observation-simulator-package)
+
+## To turn on COSP outputs
+
+Run (add to the run script) the following command before running `./case.setup`
+
+`./xmlchange --id CAM_CONFIG_OPTS --append --val='-cosp'`
+
+| Related Outputs           | Description                                                       |
+| ------------------------- | ----------------------------------------------------------------- |
+| `FISCCP1_COSP`            | Grid-box fraction covered by each ISCCP D level cloud type        |
+| `CLMODIS`                 | MODIS Cloud Area Fraction                                         |
+| `CLD_MISR`                | Cloud Fraction from MISR Simulator                                |
+| `CLDTOT_CAL`              | Calipso Total Cloud Fraction                                      |
+| `CLDHGH_CAL`              | Calipso High-level Cloud Fraction                                 |
+| `CLDMED_CAL`              | Calipso Mid-level Cloud Fraction                                  |
+| `CLDLOW_CAL`              | Calipso Low-level Cloud Fraction                                  |
+| `CLD_CAL_TMPLIQ`          | Calipso Liquid Cloud Fraction as a function of temperature        |
+| `CLD_CAL_TMPICE`          | Calipso Ice Cloud Fraction as a function of temperature           |

components/eam/docs/tech-guide/dust.md

@@ -0,0 +1,9 @@
+# Dust aerosol
+
+## Overview
+
+Dust-related processes are represented in the E3SM atmosphere and land model components. In E3SMv3, dust deposition will also be coupled with the sea ice and ocean biogeochemistry in the ocean model. Total emission fluxes of dust particles are calculated at each model time step. A new dust emission scheme following Kok et al. (2014)[@kok_improved_2014] is implemented to E3SMv3, replacing the Zender scheme (Zender et al., 2003)[@zender_mineral_2003] in E3SMv1 and v2 as the default option. The new dust emission scheme includes a time-varying soil erodibility factor for dust mobilization, and includes dust sources in high latitudes (e.g., >60 degree N). A manuscript by Feng et al. is in prep to document the performance of the new emission scheme on dust life cycle and radiative effects in E3SMv3. Dust aerosol is represented in the accumulation and coarse aerosol modes of the MAM4 module following emission. Other dust properties such as optical properties and size distribution at emission are documented in Feng et al. (2022).[@feng_global_2022]
+
+## Namelist parameters
+
+[Dust Namelist Parameters](../user-guide/namelist_parameters.md#dust-aerosol)

components/eam/docs/tech-guide/homme.md

@@ -0,0 +1,11 @@
+# High-Order Methods Modeling Environment
+
+## Overview
+
+EAM uses the a dynamical core (dycore) from the High Order Method Modeling Environment (HOMME).[@taylor_compatible_2010,@guba_spectral_2014,@taylor_energy_2020] 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)).
+
+## Namelist parameters
+
+Many dynamical core parameters can not be changed independently.  For example, increasing the hyperviscosity coefficient may require reducing the hyperviscosity timestep.   Dycore timesteps are tuned for each resolution and the defaults are close to the CFL stability limit. For complete details, as well as their interactions, see [EAM's HOMME dycore](https://acme-climate.atlassian.net/wiki/spaces/DOC/pages/1044644202/EAM+s+HOMME+dycore).
+
+[HOMME Namelist Parameters](../user-guide/namelist_parameters.md#homme)

components/eam/docs/tech-guide/index.md

@@ -1 +1,31 @@
-start of the EAM Technical Guide
+# EAM Technical Guide
+
+This Technical Guide describes the physics of version 3 of the E3SM Atmospheric Model
+
+## Dynamics and Physics
+
+- [HOMME](homme.md): Dynamical core.
+
+- [P3](p3.md): Stratiform cloud microphysics scheme.
+
+- [CLUBB](clubb.md): Parameterization of subgrid-scale turbulence and clouds.
+
+- [Zhang-McFarlane](zm.md): Deep convection parameterization.
+
+- [RRTMG](rrtmg.md): Parameterization of radiation.
+
+- [MAM](mam.md): Primary parameterization schemes used to represent aerosols.
+
+- [VBS](vbs.md): Parameterization of secondary organic aerosols.
+
+- [Dust](dust.md): Parameterization of dust emissions.
+
+- [OCEANFILMS](oceanfilms.md): Parameterization of sea soray irganic aerosol emissions.
+
+- [chemUCI + Linoz v3](chemUCIlinozv3.md): Interactive atmospheric chemistry packages.
+
+## Diagnostic outputs
+
+- [COSP](cosp.md): Scheme that allows the model to output satellite simulator output.
+
+- [ARM Diags](armdiags.md): Diagnostic package that allows the model output to be compared against ARM measurements.

components/eam/docs/tech-guide/mam.md

@@ -0,0 +1,17 @@
+# Modal Aerosol Module
+
+## MAM5 Overview
+
+The Five-mode Modal Aerosol Model (MAM5) supersedes the MAM4 utilized in previous iterations of E3SM (E3SM-V1 and -V2). MAM5 introduces a fifth mode, specifically designed to represent stratospheric coarse mode aerosols, primarily originating from volcanic eruptions and DMS decomposition. This mode exclusively comprises sulfate aerosols, characterized by a smaller standard deviation (STD) value of 1.2. The STD value denotes the width of the aerosol mode, where a higher STD implies a greater gravitational settling effect (Wang et al., 2020;[@wang_aerosols_2020] Liu et al., 2012[@liu_toward_2012]). By setting the STD to 1.2, the simulated properties of volcanic aerosols align closely with observational findings (Mills et al., 2016).[@mills_global_2016] MAM5 represents a pioneering aerosol model, effectively segregating tropospheric and stratospheric aerosols (Ke et al., in preparation), thereby mitigating the risk of overestimating dust and sea salt aerosols within the stratosphere in previous MAM4 (Visioni et al., 2021).[@visioni_limitations_2022] Volcanic eruptions derived from Neely and Schmidt (2016).[@neely_iii_volcaneesm_2016]
+
+## MAM4 Overview
+
+The representation of atmospheric aerosols and their roles in the Earth system by EAMv1/v2/v3 was inherited from the global aerosol-climate model EAMv0 and its four-mode modal aerosol module (MAM4), including Aitken, primary-carbon, accumulation, and coarse modes (Liu et al., 2016).[@liu_description_2016] It treats a combination of processes, controlling the evolution of aerosols that are either directly emitted or converted from precursor gases from a variety of natural and anthropogenic sources. The processes include transport (by grid-scale wind, subgrid turbulence, convection, and sedimentation), aerosol microphysics (i.e., particle nucleation, condensation/evaporation of trace gases, aging, and coagulation), cloud processing (i.e., aqueous chemistry, scavenging by hydrometeors, resuspension from evaporating hydrometeors, and wet deposition), and dry deposition. Aerosol species in the original MAM4 (Liu et al., 2016)[@liu_description_2016] include sulfate, primary organic aerosol (POA) or particulate organic matter (POM), secondary organic aerosol (SOA), black carbon (BC), sea salt, and mineral dust. As described by Wang et al. (2020),[@wang_aerosols_2020] the enhanced MAM4 in EAMv1/v2 added marine organic aerosol (MOA) to all four modes (Burrows et al., 2022).[@burrows_oceanfilms_2022] In MAM4 of EAMv3, the Aitken mode has sulfate, sea salt, SOA and MOA; the primary-carbon mode has BC, POA and MOA; the accumulation and coarse modes include all seven species. Ammonium (NH4) and nitrate (NO3) aerosols are also explicitly treated in EAMv3 (Wu et al., 2022),[@wu_development_2022] as an optional feature for research, in which new species (NH4, NO3, Ca, CO3, Na, Cl) are introduced to the Aitken, accumulation and coarse modes. All aerosol species within each of the four individual modes the MAM4 is assumed to be internally mixed and represented by a single number concentration, while particles are externally mixed among the different modes.
+
+### Sea salt
+
+In MAM4, sea salt aerosol is represented in the Aitken, accumulation, and coarse mode with particle emission size (diameter) ranges of 0.02-0.08, 0.08-1.0, and 1.0-10.0 μm, respectively. The emission flux of natural sea salt is first divided into 31 size bins, following the parameterization of Mårtensson et al. (2003)[@martensson_laboratory_2003] and Monahan et al. (1986),[@monahan_model_1986] and then redistributed to the three MAM4 size modes.
+
+## Namelist parameters
+
+[MAM Namelist Parameters](../user-guide/namelist_parameters.md#modal-aerosol-module)

components/eam/docs/tech-guide/oceanfilms.md

@@ -0,0 +1,9 @@
+# OCEANFILMS
+
+## Overview
+
+E3SM (v1-v3) uses the OCEANFILMS (Organic Compounds from Ecosystems to Aerosols: Natural Films and Interfaces via Langmuir Molecular Surfactants) parameterization to represent sea spray organic aerosol emissions.  OCEANFILMS is a physically based model that links sea spray chemistry with ocean biogeochemistry using a Langmuir partitioning approach.  The underlying physical assumptions and parameterization are described in Burrows et al. (2014);[@burrows_physically_2014] the implementation in E3SM and impact on clouds and climate are documented in Burrows et al. (2022).[@burrows_oceanfilms_2022]
+
+## Namelist parameters
+
+[OCEANFILMS Namelist Parameters](../user-guide/namelist_parameters.md#oceanfilms)

components/eam/docs/tech-guide/p3.md

@@ -0,0 +1,9 @@
+# Predicted Particle Properties
+
+## Overview
+
+The stratiform cloud microphysics scheme in v3 is Predicted Particle Properties (P3; Morrison & Milbrandt, 2015;[@morrison_parameterization_2015] Milbrandt & Morrison, 2016[@milbrandt_parameterization_2016]). P3 offers a new approach to representing the evolution of ice particles that is more physical than the traditional approach of using predefined ice categories. It has been implemented in E3SM (Wang et al., 2021)[@wang_impact_2021] to address the limitations in the original microphysics scheme- the lack of riming particles and the artificial conversion between ice crystals and snow particles. The current version in E3SM is a two-moment scheme with a single ice category (Morrison & Milbrandt, 2015).[@morrison_parameterization_2015] In addition to the total ice number and mass mixing ratios, P3 prognoses the rimed mass and rimed volume mixing ratios, which allows for the prediction of the continuous evolution of the rime fraction and particle density. It is worth noting that the ice nucleation parameterizations are changed to be aerosol-dependent in this study, with the heterogenous ice nucleation parameterizations from the Classical Nucleation Theory (Liu et al., 2012)[@liu_toward_2012] and the homogenous in-situ cirrus formation based on Liu and Penner (2005).[@liu_ice_2005] This differs from the P3 used in WRF and that used in the E3SM v1 in Wang et al. (2021)[@wang_impact_2021] where the heterogeneous ice nucleation parameterizations are temperature dependent only.
+
+## Namelist parameters
+
+[P3 Namelist Parameters](../user-guide/namelist_parameters.md#predicted-particle-properties)