From b25a0e18836e1807c78cf9753b0a715bdfbd12b0 Mon Sep 17 00:00:00 2001 From: mahf708 Date: Wed, 24 Apr 2024 10:47:39 -0500 Subject: [PATCH 01/10] move rad calls from tech to user, update nudging and aerocom docs --- .../eamxx/docs/technical/aerocom_cldtop.md | 9 +- .../eamxx/docs/technical/clean_clear_sky.md | 10 --- components/eamxx/docs/user/clean_clear_sky.md | 83 +++++++++++++++++++ components/eamxx/docs/user/coarse_nudging.md | 26 +++--- components/eamxx/mkdocs.yml | 4 +- .../rrtmgp/eamxx_rrtmgp_process_interface.cpp | 6 +- .../rrtmgp/scream_rrtmgp_interface.cpp | 2 +- .../rrtmgp/scream_rrtmgp_interface.hpp | 2 +- .../homme_shoc_cld_p3_rrtmgp_pg2/output.yaml | 2 +- .../tests/single-process/rrtmgp/output.yaml | 2 +- 10 files changed, 112 insertions(+), 34 deletions(-) delete mode 100644 components/eamxx/docs/technical/clean_clear_sky.md create mode 100644 components/eamxx/docs/user/clean_clear_sky.md diff --git a/components/eamxx/docs/technical/aerocom_cldtop.md b/components/eamxx/docs/technical/aerocom_cldtop.md index 18fea456cf6..cda0c46c3b8 100644 --- a/components/eamxx/docs/technical/aerocom_cldtop.md +++ b/components/eamxx/docs/technical/aerocom_cldtop.md @@ -1,6 +1,6 @@ -# The AeroCOM algorithm +# The AeroCom algorithm -The goal of the AeroCOM algorithm is to calculate properties at cloud top based on the AeroCOM recommendation. There are two main parts of the algorithm: probabilistically determining "cloud top" and then "calculating properties" at said cloud top. +The goal of the AeroCom algorithm is to calculate properties at cloud top based on the AeroCom recommendation. There are two main parts of the algorithm: probabilistically determining "cloud top" and then "calculating properties" at said cloud top. We treat model columns independently, so we loop over all columns in parallel. We then loop over all layers in serial (due to needing an accumulative product), starting at 2 (second highest) layer because the highest is assumed to have no clouds. Let's take a photonic approach from above the model top. Let's say that $p_{k}$ is the probability of a photon passing through the layer $k$. We follow the maximum-random overlap assumption. In all cases, we assume the cloudiness (or cloudy fraction) is completely opaque. @@ -24,4 +24,7 @@ $$c\Phi_{i,k} = \frac{cQ_{i,k}}{iQ_{i,k} + cQ_{i,k}}$$ The thermodynamic phase is used only for cloud properties (e.g., cloud-top cloud droplet number concentration) or cloud content (e.g., cloud liquid content). Further, $X_{i,k}$ is the three-dimensional cloud property of interest which is needed if we are converting a property from three-dimensional ($X$) to its two-dimensional counterpart ($x$). "Other" properties here include temperature and pressure which are not dependent on the thermodynamic phase. -A helpful references: Räisänen, P., Barker, H. W., Khairoutdinov, M. F., Li, J., & Randall, D. A. (2004). Stochastic generation of subgrid‐scale cloudy columns for large‐scale models. Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography, 130(601), 2047-2067. +Helpful pointers: + +- Räisänen, P., Barker, H. W., Khairoutdinov, M. F., Li, J., & Randall, D. A. (2004). Stochastic generation of subgrid‐scale cloudy columns for large‐scale models. Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography, 130(601), 2047-2067. +- References in this ECMWF report: Tiedtke, M., Geleyn, J.-F., Hollingsworth, A., and Louis, J.-F.: ECMWF model parameterisation of sub-grid scale processes, Technical Report, ECMWF, Shinfield Park, Reading, 10, 1979. diff --git a/components/eamxx/docs/technical/clean_clear_sky.md b/components/eamxx/docs/technical/clean_clear_sky.md deleted file mode 100644 index 82380f90315..00000000000 --- a/components/eamxx/docs/technical/clean_clear_sky.md +++ /dev/null @@ -1,10 +0,0 @@ -# Clean- and clean-clear-sky diagnostics - -In order to decompose the aerosol effective radiative forcing, additional diagnostic radiation calls are needed. -These extra diagnostics are optionally added to the main radiation call. The extra diagnostics are: - -- Clean-clear-sky fluxes: the fluxes that would be present if there were neither aerosols nor clouds, and are calculated by adding an additional radiation call at the very beginning of the logic before the optics class is endowed with aerosol and cloud properties. -- Clean-sky fluxes: the fluxes that would be present if there were no aerosols, and are calculated by adding an additional radiation call after substantiating an additional optics class, but not endowing it with aerosol properties. - -It was necessary to add an additional optics class because the original optics class is endowed with aerosols before clouds (in order to calculate the clear-sky fluxes). -The extra calls are controlled by runtime flags `extra_clnclrsky_diag` and `extra_clnsky_diag` (they take either `true` or `false` as their values). diff --git a/components/eamxx/docs/user/clean_clear_sky.md b/components/eamxx/docs/user/clean_clear_sky.md new file mode 100644 index 00000000000..56ae29bf933 --- /dev/null +++ b/components/eamxx/docs/user/clean_clear_sky.md @@ -0,0 +1,83 @@ +# Clean- and clean-clear-sky diagnostics + +In order to decompose the aerosol effective radiative forcing, additional diagnostic radiation calls are needed. +These extra diagnostics are optionally added to the main radiation call. The extra diagnostics are: + +- Clean-clear-sky fluxes: the fluxes that would be present if there were neither aerosols nor clouds, and are calculated by adding an additional radiation call at the very beginning of the logic before the optics class is endowed with aerosol and cloud properties. +- Clean-sky fluxes: the fluxes that would be present if there were no aerosols, and are calculated by adding an additional radiation call after substantiating an additional optics class, but not endowing it with aerosol properties. + +It was necessary to add an additional optics class because the original optics class is endowed with aerosols before clouds (in order to calculate the clear-sky fluxes). + +## Example setup (current as of April 2024) + +The extra calls are controlled by runtime flags `extra_clnclrsky_diag` and `extra_clnsky_diag` (they take either `true` or `false` as their values). + +```shell + ./atmchange extra_clnclrsky_diag=true + ./atmchange extra_clnsky_diag=true +``` + +An example output file with the additional radiation diagnostics requested. + +```yaml +%YAML 1.1 +--- +filename_prefix: monthly.outputs +Averaging Type: Average +Max Snapshots Per File: 1 +Fields: + Physics PG2: + Field Names: + #2D vars + - SW_flux_up_at_model_top + - SW_flux_dn_at_model_top + - LW_flux_up_at_model_top + - SW_clnclrsky_flux_up_at_model_top + - LW_clnclrsky_flux_up_at_model_top + - SW_clrsky_flux_up_at_model_top + - LW_clrsky_flux_up_at_model_top + - SW_clnsky_flux_up_at_model_top + - LW_clnsky_flux_up_at_model_top + - SW_flux_dn_at_model_bot + - SW_clnclrsky_flux_dn_at_model_bot + - SW_clrsky_flux_dn_at_model_bot + - SW_clnsky_flux_dn_at_model_bot + - SW_flux_up_at_model_bot + - SW_clnclrsky_flux_up_at_model_bot + - SW_clrsky_flux_up_at_model_bot + - SW_clnsky_flux_up_at_model_bot + - LW_flux_dn_at_model_bot + - LW_clnclrsky_flux_dn_at_model_bot + - LW_clrsky_flux_dn_at_model_bot + - LW_clnsky_flux_dn_at_model_bot + - LW_flux_up_at_model_bot + - LongwaveCloudForcing + - ShortwaveCloudForcing + - ps + - SeaLevelPressure + - T_2m + - qv_2m + - surf_radiative_T + - VapWaterPath + - IceWaterPath + - LiqWaterPath + - RainWaterPath + - ZonalVapFlux + - MeridionalVapFlux + - surf_evap + - surf_sens_flux + - surface_upward_latent_heat_flux + - precip_liq_surf_mass_flux + - precip_ice_surf_mass_flux + - landfrac + - ocnfrac + - PotentialTemperature_at_700hPa + - PotentialTemperature_at_1000hPa + - omega_at_500hPa + - RelativeHumidity_at_700hPa +output_control: + Frequency: 1 + frequency_units: nmonths + MPI Ranks in Filename: false + +``` diff --git a/components/eamxx/docs/user/coarse_nudging.md b/components/eamxx/docs/user/coarse_nudging.md index 3d7309c42aa..6dbf4d7eeb4 100644 --- a/components/eamxx/docs/user/coarse_nudging.md +++ b/components/eamxx/docs/user/coarse_nudging.md @@ -5,21 +5,23 @@ Instead, in EAMxx, it is possible to nudge from coarse data. This is done by remapping the coarse data provided by the user to the runtime physics grid of EAMxx. In order to enable nudging from coarse data, the user must provide nudging data at the coarse resolution desired and an appropriate ncremap-compatible mapping file. -## Example setup +## Example setup (current as of April 2024) A user can produce coarse nudging data from running EAMxx or EAM at a ne30pg2 or any other applicable resolution. -Additionally, several users in the E3SM projects have produced nudging data at the ne30pg2 resolution from the MERRA2 and ERA5 datasets. -A limitation for now is that the nudging data must be provided explicitly, either as one file or as a list of files. -This can be problematic for long list of files, but we are working on a solution to this problem. +Additionally, several users in the E3SM projects have produced nudging data at the ne30pg2 resolution from the MERRA2 and ERA5 datasets. Then, to enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter. -Let's say that the nudging data is provided as one file in the following path: `/path/to/nudging_data_ne4pg2_L72.nc`. -Then, a mapping file is provided as `/another/path/to/mapping_file_ne4pg2_to_ne120pg2.nc`. -Then if the physics grid is ne120pg2, the user must enable the nudging process, specify the nudging files, and provide the specifies the nudging data and a remap file. -In other words, the following options are needed: +```shell + ./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging" +``` + +The following options are needed to specify the nudging. ```shell -./atmchange atm_procs_list=(sc_import,nudging,homme,physics,sc_export) -./atmchange nudging_fields=U,V -./atmchange nudging_filenames_patterns=/path/to/nudging_data_ne4pg2_L72.nc -./atmchange nudging_refine_remap_mapfile=/another/path/to/mapping_file_ne4pg2_to_ne120pg2.nc + ./atmchange nudging::nudging_filenames_patterns="${PSCRATCH}/mo_ne45pg2_nudg_trim_merra/*.nc" + ./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE + ./atmchange nudging::nudging_fields=U,V + ./atmchange nudging::nudging_timescale=21600 # 6-hr + ./atmchange nudging::nudging_refine_remap_mapfile="${PSCRATCH}/map_ne45pg2_to_ne256pg2.trbilin.20240410.nc" ``` + +To gain a deeper understanding of these parameters and options, please refer to the overarching nudging documentation. diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index dde0970a4ed..6cc8fdeae0a 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -9,6 +9,7 @@ nav: - 'Model input': 'user/model_input.md' - 'Runtime parameters': 'common/eamxx_params.md' - 'Coarse nudging': 'user/coarse_nudging.md' + - 'Extra radiation calls': 'user/clean_clear_sky.md' - 'Developer Guide': - 'Overview': 'developer/index.md' - 'Installation': 'common/installation.md' @@ -26,8 +27,7 @@ nav: - 'Full model': 'developer/cime_testing.md' - 'CI and Nightly Testing': 'developer/ci_nightly.md' - 'Technical Guide': - - 'AeroCOM cloud top': 'technical/aerocom_cldtop.md' - - 'Extra radiation calls': 'technical/clean_clear_sky.md' + - 'AeroCom cloud top': 'technical/aerocom_cldtop.md' edit_uri: "" diff --git a/components/eamxx/src/physics/rrtmgp/eamxx_rrtmgp_process_interface.cpp b/components/eamxx/src/physics/rrtmgp/eamxx_rrtmgp_process_interface.cpp index 16811885a3b..a228267f12f 100644 --- a/components/eamxx/src/physics/rrtmgp/eamxx_rrtmgp_process_interface.cpp +++ b/components/eamxx/src/physics/rrtmgp/eamxx_rrtmgp_process_interface.cpp @@ -160,7 +160,7 @@ void RRTMGPRadiation::set_grids(const std::shared_ptr grids_ add_field("dtau105" , scalar3d_layout_mid, nondim, grid_name); add_field("sunlit" , scalar2d_layout , nondim, grid_name); add_field("cldfrac_rad" , scalar3d_layout_mid, nondim, grid_name); - // Cloud-top diagnostics following AeroCOM recommendation + // Cloud-top diagnostics following AeroCom recommendation add_field("T_mid_at_cldtop", scalar2d_layout, K, grid_name); add_field("p_mid_at_cldtop", scalar2d_layout, Pa, grid_name); add_field("cldfrac_ice_at_cldtop", scalar2d_layout, nondim, grid_name); @@ -521,7 +521,7 @@ void RRTMGPRadiation::run_impl (const double dt) { Kokkos::deep_copy(d_dtau067,0.0); Kokkos::deep_copy(d_dtau105,0.0); - // Outputs for AeroCOM cloud-top diagnostics + // Outputs for AeroCom cloud-top diagnostics auto d_T_mid_at_cldtop = get_field_out("T_mid_at_cldtop").get_view(); auto d_p_mid_at_cldtop = get_field_out("p_mid_at_cldtop").get_view(); auto d_cldfrac_ice_at_cldtop = @@ -998,7 +998,7 @@ void RRTMGPRadiation::run_impl (const double dt) { // Get IR 10.5 micron band for COSP auto idx_105 = rrtmgp::get_wavelength_index_lw(10.5e-6); - // Compute cloud-top diagnostics following AeroCOM recommendation + // Compute cloud-top diagnostics following AeroCom recommendation real1d T_mid_at_cldtop ("T_mid_at_cldtop", d_T_mid_at_cldtop.data() + m_col_chunk_beg[ic], ncol); real1d p_mid_at_cldtop ("p_mid_at_cldtop", d_p_mid_at_cldtop.data() + m_col_chunk_beg[ic], ncol); real1d cldfrac_ice_at_cldtop ("cldfrac_ice_at_cldtop", d_cldfrac_ice_at_cldtop.data() + m_col_chunk_beg[ic], ncol); diff --git a/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.cpp b/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.cpp index ec346029395..04aef4fd003 100644 --- a/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.cpp +++ b/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.cpp @@ -1047,7 +1047,7 @@ namespace scream { real1d &cldfrac_tot_at_cldtop, real1d &cdnc_at_cldtop, real1d &eff_radius_qc_at_cldtop, real1d &eff_radius_qi_at_cldtop) { /* The goal of this routine is to calculate properties at cloud top - * based on the AeroCOM recommendation. See reference for routine + * based on the AeroCom recommendation. See reference for routine * get_subcolumn_mask above, where equation 14 is used for the * maximum-random overlap assumption for subcolumn generation. We use * equation 13, the column counterpart. diff --git a/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.hpp b/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.hpp index 65e16542286..71904aef886 100644 --- a/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.hpp +++ b/components/eamxx/src/physics/rrtmgp/scream_rrtmgp_interface.hpp @@ -122,7 +122,7 @@ namespace scream { int ncol, int nlay, int ngpt, Real pmin, Real pmax, const real2d& pmid, const real3d& cld_tau_gpt, real1d& cld_area); /* - * Return select cloud-top diagnostics following AeroCOM recommendation + * Return select cloud-top diagnostics following AeroCom recommendation */ void compute_aerocom_cloudtop( int ncol, int nlay, const real2d &tmid, const real2d &pmid, diff --git a/components/eamxx/tests/multi-process/dynamics_physics/homme_shoc_cld_p3_rrtmgp_pg2/output.yaml b/components/eamxx/tests/multi-process/dynamics_physics/homme_shoc_cld_p3_rrtmgp_pg2/output.yaml index d07cdf5a4d0..c492f864ff9 100644 --- a/components/eamxx/tests/multi-process/dynamics_physics/homme_shoc_cld_p3_rrtmgp_pg2/output.yaml +++ b/components/eamxx/tests/multi-process/dynamics_physics/homme_shoc_cld_p3_rrtmgp_pg2/output.yaml @@ -64,7 +64,7 @@ Fields: - rad_heating_pdel - sfc_flux_lw_dn - sfc_flux_sw_net - # AeroCOM in RRTMGP + # AeroCom in RRTMGP - cdnc_at_cldtop - cldfrac_tot_at_cldtop - cldfrac_liq_at_cldtop diff --git a/components/eamxx/tests/single-process/rrtmgp/output.yaml b/components/eamxx/tests/single-process/rrtmgp/output.yaml index b067d1412bc..94a7dc94eba 100644 --- a/components/eamxx/tests/single-process/rrtmgp/output.yaml +++ b/components/eamxx/tests/single-process/rrtmgp/output.yaml @@ -17,7 +17,7 @@ Field Names: - sfc_flux_lw_dn - sfc_flux_sw_net - rad_heating_pdel - # AeroCOM in RRTMGP + # AeroCom in RRTMGP - cdnc_at_cldtop - cldfrac_tot_at_cldtop - cldfrac_liq_at_cldtop From d1d8e3f63975665697291aac0eec4deb58c01500 Mon Sep 17 00:00:00 2001 From: mahf708 Date: Wed, 24 Apr 2024 12:59:06 -0500 Subject: [PATCH 02/10] refine and refocus the rad diags text --- components/eamxx/docs/user/clean_clear_sky.md | 47 +------------------ 1 file changed, 1 insertion(+), 46 deletions(-) diff --git a/components/eamxx/docs/user/clean_clear_sky.md b/components/eamxx/docs/user/clean_clear_sky.md index 56ae29bf933..0cde752028a 100644 --- a/components/eamxx/docs/user/clean_clear_sky.md +++ b/components/eamxx/docs/user/clean_clear_sky.md @@ -6,8 +6,6 @@ These extra diagnostics are optionally added to the main radiation call. The ext - Clean-clear-sky fluxes: the fluxes that would be present if there were neither aerosols nor clouds, and are calculated by adding an additional radiation call at the very beginning of the logic before the optics class is endowed with aerosol and cloud properties. - Clean-sky fluxes: the fluxes that would be present if there were no aerosols, and are calculated by adding an additional radiation call after substantiating an additional optics class, but not endowing it with aerosol properties. -It was necessary to add an additional optics class because the original optics class is endowed with aerosols before clouds (in order to calculate the clear-sky fluxes). - ## Example setup (current as of April 2024) The extra calls are controlled by runtime flags `extra_clnclrsky_diag` and `extra_clnsky_diag` (they take either `true` or `false` as their values). @@ -17,7 +15,7 @@ The extra calls are controlled by runtime flags `extra_clnclrsky_diag` and `extr ./atmchange extra_clnsky_diag=true ``` -An example output file with the additional radiation diagnostics requested. +Below is an example output file to output the extra (clean and clean-clear-sky) radiation diagnostics atop the atmosphere. ```yaml %YAML 1.1 @@ -28,53 +26,10 @@ Max Snapshots Per File: 1 Fields: Physics PG2: Field Names: - #2D vars - - SW_flux_up_at_model_top - - SW_flux_dn_at_model_top - - LW_flux_up_at_model_top - SW_clnclrsky_flux_up_at_model_top - LW_clnclrsky_flux_up_at_model_top - - SW_clrsky_flux_up_at_model_top - - LW_clrsky_flux_up_at_model_top - SW_clnsky_flux_up_at_model_top - LW_clnsky_flux_up_at_model_top - - SW_flux_dn_at_model_bot - - SW_clnclrsky_flux_dn_at_model_bot - - SW_clrsky_flux_dn_at_model_bot - - SW_clnsky_flux_dn_at_model_bot - - SW_flux_up_at_model_bot - - SW_clnclrsky_flux_up_at_model_bot - - SW_clrsky_flux_up_at_model_bot - - SW_clnsky_flux_up_at_model_bot - - LW_flux_dn_at_model_bot - - LW_clnclrsky_flux_dn_at_model_bot - - LW_clrsky_flux_dn_at_model_bot - - LW_clnsky_flux_dn_at_model_bot - - LW_flux_up_at_model_bot - - LongwaveCloudForcing - - ShortwaveCloudForcing - - ps - - SeaLevelPressure - - T_2m - - qv_2m - - surf_radiative_T - - VapWaterPath - - IceWaterPath - - LiqWaterPath - - RainWaterPath - - ZonalVapFlux - - MeridionalVapFlux - - surf_evap - - surf_sens_flux - - surface_upward_latent_heat_flux - - precip_liq_surf_mass_flux - - precip_ice_surf_mass_flux - - landfrac - - ocnfrac - - PotentialTemperature_at_700hPa - - PotentialTemperature_at_1000hPa - - omega_at_500hPa - - RelativeHumidity_at_700hPa output_control: Frequency: 1 frequency_units: nmonths From 0b6d21c142f2eb46643137655826ba8a7ebfa0fa Mon Sep 17 00:00:00 2001 From: mahf708 Date: Wed, 24 Apr 2024 13:01:22 -0500 Subject: [PATCH 03/10] more descriptive text for these nudging docs --- .../{coarse_nudging.md => nudging_from_coarse_reanalysis.md} | 0 components/eamxx/mkdocs.yml | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename components/eamxx/docs/user/{coarse_nudging.md => nudging_from_coarse_reanalysis.md} (100%) diff --git a/components/eamxx/docs/user/coarse_nudging.md b/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md similarity index 100% rename from components/eamxx/docs/user/coarse_nudging.md rename to components/eamxx/docs/user/nudging_from_coarse_reanalysis.md diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index 6cc8fdeae0a..85e8e54dfe9 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -8,7 +8,7 @@ nav: - 'Model output': 'user/model_output.md' - 'Model input': 'user/model_input.md' - 'Runtime parameters': 'common/eamxx_params.md' - - 'Coarse nudging': 'user/coarse_nudging.md' + - 'Nudging from coarse reanalysis': 'user/nudging_from_coarse_reanalysis.md' - 'Extra radiation calls': 'user/clean_clear_sky.md' - 'Developer Guide': - 'Overview': 'developer/index.md' From 3dfee227546b3045523a4f716fc15e127cda352b Mon Sep 17 00:00:00 2001 From: mahf708 Date: Wed, 24 Apr 2024 13:13:41 -0500 Subject: [PATCH 04/10] point to the code, not yet-to-exist docs --- components/eamxx/docs/user/nudging_from_coarse_reanalysis.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md b/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md index 6dbf4d7eeb4..3b876855435 100644 --- a/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md +++ b/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md @@ -24,4 +24,4 @@ The following options are needed to specify the nudging. ./atmchange nudging::nudging_refine_remap_mapfile="${PSCRATCH}/map_ne45pg2_to_ne256pg2.trbilin.20240410.nc" ``` -To gain a deeper understanding of these parameters and options, please refer to the overarching nudging documentation. +To gain a deeper understanding of these parameters and options, please refer to code implementation of the nudging process. From 0a756b615e572e3eed22c16e156918b5c982dc07 Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Fri, 26 Apr 2024 20:11:59 -0400 Subject: [PATCH 05/10] add citations, generalize nudging --- components/eamxx/docs/refs.bib | 24 +++++++++++++++++ .../eamxx/docs/technical/aerocom_cldtop.md | 5 +--- components/eamxx/docs/user/nudging.md | 25 +++++++++++++++++ .../user/nudging_from_coarse_reanalysis.md | 27 ------------------- 4 files changed, 50 insertions(+), 31 deletions(-) create mode 100644 components/eamxx/docs/user/nudging.md delete mode 100644 components/eamxx/docs/user/nudging_from_coarse_reanalysis.md diff --git a/components/eamxx/docs/refs.bib b/components/eamxx/docs/refs.bib index 6ab4e21c917..7a8745e0709 100644 --- a/components/eamxx/docs/refs.bib +++ b/components/eamxx/docs/refs.bib @@ -123,3 +123,27 @@ @article{Taylor_et20 note = {e2019MS001783 10.1029/2019MS001783}, year = {2020} } + +@techreport{tiedtke_ecmwf_1979, + address = {Shinfield Park, Reading}, + type = {Technical {Report}}, + title = {{ECMWF} model parameterisation of sub-grid scale processes}, + language = {en}, + institution = {ECMWF}, + author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.}, + month = jan, + year = {1979}, + note = {10}, + pages = {146}, +} + +@article{raisanen2004stochastic, + title={Stochastic generation of subgrid-scale cloudy columns for large-scale models}, + author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A}, + journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography}, + volume={130}, + number={601}, + pages={2047--2067}, + year={2004}, + publisher={Wiley Online Library} +} diff --git a/components/eamxx/docs/technical/aerocom_cldtop.md b/components/eamxx/docs/technical/aerocom_cldtop.md index cda0c46c3b8..2dfbfbab0d8 100644 --- a/components/eamxx/docs/technical/aerocom_cldtop.md +++ b/components/eamxx/docs/technical/aerocom_cldtop.md @@ -24,7 +24,4 @@ $$c\Phi_{i,k} = \frac{cQ_{i,k}}{iQ_{i,k} + cQ_{i,k}}$$ The thermodynamic phase is used only for cloud properties (e.g., cloud-top cloud droplet number concentration) or cloud content (e.g., cloud liquid content). Further, $X_{i,k}$ is the three-dimensional cloud property of interest which is needed if we are converting a property from three-dimensional ($X$) to its two-dimensional counterpart ($x$). "Other" properties here include temperature and pressure which are not dependent on the thermodynamic phase. -Helpful pointers: - -- Räisänen, P., Barker, H. W., Khairoutdinov, M. F., Li, J., & Randall, D. A. (2004). Stochastic generation of subgrid‐scale cloudy columns for large‐scale models. Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography, 130(601), 2047-2067. -- References in this ECMWF report: Tiedtke, M., Geleyn, J.-F., Hollingsworth, A., and Louis, J.-F.: ECMWF model parameterisation of sub-grid scale processes, Technical Report, ECMWF, Shinfield Park, Reading, 10, 1979. +Most studies in this topic refer a technical report by Tiedtke et al. (1979)[@tiedtke_ecmwf_1979]. Another more recent general reference that may be of interest is that of Räisänen et al. (2004)[@raisanen2004stochastic]. diff --git a/components/eamxx/docs/user/nudging.md b/components/eamxx/docs/user/nudging.md new file mode 100644 index 00000000000..b102cedd26c --- /dev/null +++ b/components/eamxx/docs/user/nudging.md @@ -0,0 +1,25 @@ +# Nudging in EAMxx + +Nudging is supported in EAMxx. +Currently, it is possible to nudge EAMxx to reference meterological fields at the run resolution or a coarser one. + +## Example setup (current as of April 2024) + +A user can produce nudging data for EAMxx using a model run or by using reanalysis data. +To enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter. + +```shell + ./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging" +``` + +The following options are needed to specify the nudging. + +```shell +./atmchange nudging::nudging_filenames_patterns="/pathto/nudging_files/*.nc" +./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE +./atmchange nudging::nudging_fields=U,V +./atmchange nudging::nudging_timescale=21600 +``` + +To gain a deeper understanding of these parameters and options, please refer to code implementation of the nudging process. +In particular, depending on the specific needs, one may utilize weighted nudging (for regionally refined model runs) or nudging from coarse data via specifying a map in the `atmchange` calls above. diff --git a/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md b/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md deleted file mode 100644 index 3b876855435..00000000000 --- a/components/eamxx/docs/user/nudging_from_coarse_reanalysis.md +++ /dev/null @@ -1,27 +0,0 @@ -# Nudging from coarse data - -Because EAMxx is designed to support ultra-high resolutions (in fact, that was the initial reason for its inception), it is not feasible to produce nudging data at the same resolution. -Instead, in EAMxx, it is possible to nudge from coarse data. -This is done by remapping the coarse data provided by the user to the runtime physics grid of EAMxx. -In order to enable nudging from coarse data, the user must provide nudging data at the coarse resolution desired and an appropriate ncremap-compatible mapping file. - -## Example setup (current as of April 2024) - -A user can produce coarse nudging data from running EAMxx or EAM at a ne30pg2 or any other applicable resolution. -Additionally, several users in the E3SM projects have produced nudging data at the ne30pg2 resolution from the MERRA2 and ERA5 datasets. Then, to enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter. - -```shell - ./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging" -``` - -The following options are needed to specify the nudging. - -```shell - ./atmchange nudging::nudging_filenames_patterns="${PSCRATCH}/mo_ne45pg2_nudg_trim_merra/*.nc" - ./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE - ./atmchange nudging::nudging_fields=U,V - ./atmchange nudging::nudging_timescale=21600 # 6-hr - ./atmchange nudging::nudging_refine_remap_mapfile="${PSCRATCH}/map_ne45pg2_to_ne256pg2.trbilin.20240410.nc" -``` - -To gain a deeper understanding of these parameters and options, please refer to code implementation of the nudging process. From 7fe672e6ef1f8291cd1e231603edcbbcc67bb106 Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Fri, 26 Apr 2024 20:14:23 -0400 Subject: [PATCH 06/10] refer to nudging, not old name --- components/eamxx/mkdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index 85e8e54dfe9..d86bc23f63a 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -8,7 +8,7 @@ nav: - 'Model output': 'user/model_output.md' - 'Model input': 'user/model_input.md' - 'Runtime parameters': 'common/eamxx_params.md' - - 'Nudging from coarse reanalysis': 'user/nudging_from_coarse_reanalysis.md' + - 'Nudging': 'user/nudging.md' - 'Extra radiation calls': 'user/clean_clear_sky.md' - 'Developer Guide': - 'Overview': 'developer/index.md' From 9c7d36f8b6291bf8d2848741ab3031d568a8cc3a Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Fri, 26 Apr 2024 20:21:36 -0400 Subject: [PATCH 07/10] fix technical overview --- components/eamxx/docs/technical/index.md | 2 +- components/eamxx/mkdocs.yml | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/components/eamxx/docs/technical/index.md b/components/eamxx/docs/technical/index.md index 2df88d5cee9..0bfd2e5add0 100644 --- a/components/eamxx/docs/technical/index.md +++ b/components/eamxx/docs/technical/index.md @@ -1,6 +1,6 @@ # EAMxx Technical Guide -The goal of this document is to describe the specific equations, parameterizations, and numerical methods used in the current version of EAMxx. Because our master-branch implementation changes every time we make a new commit, this documentation will also evolve continuously. As such, documentation for master should always be considered to be preliminary and under construction. If you want trustworthy documentation, pull it from an official model release. +The goal of this document is to describe the specific equations, parameterizations, and numerical methods used in the current version of EAMxx. Because our master-branch implementation changes every time we make a new commit, this documentation will also evolve continuously. As such, documentation for master should always be considered to be preliminary and under construction. If you want trustworthy documentation, pull it from an official model release. ## Overview diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index d86bc23f63a..770362671d3 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -27,6 +27,7 @@ nav: - 'Full model': 'developer/cime_testing.md' - 'CI and Nightly Testing': 'developer/ci_nightly.md' - 'Technical Guide': + - 'Overview': 'technical/index.md' - 'AeroCom cloud top': 'technical/aerocom_cldtop.md' edit_uri: "" From ed8859adf1d0efd0005c2ad7c18d9a746fc45e3e Mon Sep 17 00:00:00 2001 From: Peter Caldwell Date: Mon, 29 Apr 2024 09:53:13 -0700 Subject: [PATCH 08/10] cleaned up nudging.md text --- components/eamxx/docs/user/nudging.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/components/eamxx/docs/user/nudging.md b/components/eamxx/docs/user/nudging.md index b102cedd26c..acb72468d97 100644 --- a/components/eamxx/docs/user/nudging.md +++ b/components/eamxx/docs/user/nudging.md @@ -1,11 +1,10 @@ # Nudging in EAMxx Nudging is supported in EAMxx. -Currently, it is possible to nudge EAMxx to reference meterological fields at the run resolution or a coarser one. +Currently, it is possible to nudge EAMxx to the output from a different EAMxx run or to reanalysis. Nudging data can be on your model grid or an arbitrary coarser grid. Inline interpolating of finer-grid nudging data to a coarser model resolution isn't implemented yet but may be in the future. ## Example setup (current as of April 2024) -A user can produce nudging data for EAMxx using a model run or by using reanalysis data. To enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter. ```shell From a3d251d76176e471bf9d1cd61ce4a9a3498a56c9 Mon Sep 17 00:00:00 2001 From: Naser Mahfouz Date: Wed, 1 May 2024 01:29:30 -0400 Subject: [PATCH 09/10] update nudging docs + fix bibtex --- .github/workflows/eamxx-gh-pages.yml | 2 +- components/eamxx/docs/refs/aerocom_cldtop.bib | 24 ++++++++++++++ .../eamxx/docs/{refs.bib => refs/general.bib} | 24 -------------- components/eamxx/docs/user/nudging.md | 32 +++++++++++++++---- components/eamxx/mkdocs.yml | 4 +++ 5 files changed, 54 insertions(+), 32 deletions(-) create mode 100644 components/eamxx/docs/refs/aerocom_cldtop.bib rename components/eamxx/docs/{refs.bib => refs/general.bib} (87%) diff --git a/.github/workflows/eamxx-gh-pages.yml b/.github/workflows/eamxx-gh-pages.yml index 91f591a32ba..a78f76c9c07 100644 --- a/.github/workflows/eamxx-gh-pages.yml +++ b/.github/workflows/eamxx-gh-pages.yml @@ -60,7 +60,7 @@ jobs: - name: Install Python deps run: | - pip install mkdocs pymdown-extensions mkdocs-material mdutils + pip install mkdocs pymdown-extensions mkdocs-material mdutils mkdocs-bibtex - name: Generate EAMxx params docs working-directory: components/eamxx/scripts diff --git a/components/eamxx/docs/refs/aerocom_cldtop.bib b/components/eamxx/docs/refs/aerocom_cldtop.bib new file mode 100644 index 00000000000..45ed5808860 --- /dev/null +++ b/components/eamxx/docs/refs/aerocom_cldtop.bib @@ -0,0 +1,24 @@ + +@techreport{tiedtke_ecmwf_1979, + address = {Shinfield Park, Reading}, + type = {Technical {Report}}, + title = {{ECMWF} model parameterisation of sub-grid scale processes}, + language = {en}, + institution = {ECMWF}, + author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.}, + month = jan, + year = {1979}, + note = {10}, + pages = {146}, +} + +@article{raisanen2004stochastic, + title={Stochastic generation of subgrid-scale cloudy columns for large-scale models}, + author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A}, + journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography}, + volume={130}, + number={601}, + pages={2047--2067}, + year={2004}, + publisher={Wiley Online Library} +} diff --git a/components/eamxx/docs/refs.bib b/components/eamxx/docs/refs/general.bib similarity index 87% rename from components/eamxx/docs/refs.bib rename to components/eamxx/docs/refs/general.bib index 7a8745e0709..6ab4e21c917 100644 --- a/components/eamxx/docs/refs.bib +++ b/components/eamxx/docs/refs/general.bib @@ -123,27 +123,3 @@ @article{Taylor_et20 note = {e2019MS001783 10.1029/2019MS001783}, year = {2020} } - -@techreport{tiedtke_ecmwf_1979, - address = {Shinfield Park, Reading}, - type = {Technical {Report}}, - title = {{ECMWF} model parameterisation of sub-grid scale processes}, - language = {en}, - institution = {ECMWF}, - author = {Tiedtke, M. and Geleyn, J.-F. and Hollingsworth, A. and Louis, J.-F.}, - month = jan, - year = {1979}, - note = {10}, - pages = {146}, -} - -@article{raisanen2004stochastic, - title={Stochastic generation of subgrid-scale cloudy columns for large-scale models}, - author={R{\"a}is{\"a}nen, Petri and Barker, Howard W and Khairoutdinov, Marat F and Li, Jiangnan and Randall, David A}, - journal={Quarterly Journal of the Royal Meteorological Society: A journal of the atmospheric sciences, applied meteorology and physical oceanography}, - volume={130}, - number={601}, - pages={2047--2067}, - year={2004}, - publisher={Wiley Online Library} -} diff --git a/components/eamxx/docs/user/nudging.md b/components/eamxx/docs/user/nudging.md index acb72468d97..e6137e666be 100644 --- a/components/eamxx/docs/user/nudging.md +++ b/components/eamxx/docs/user/nudging.md @@ -1,24 +1,42 @@ # Nudging in EAMxx Nudging is supported in EAMxx. -Currently, it is possible to nudge EAMxx to the output from a different EAMxx run or to reanalysis. Nudging data can be on your model grid or an arbitrary coarser grid. Inline interpolating of finer-grid nudging data to a coarser model resolution isn't implemented yet but may be in the future. +Currently, it is possible to nudge EAMxx to the output from a different EAMxx run or to reanalysis. Nudging data can be on your model grid or an arbitrary coarser grid. Inline interpolating of finer-grid nudging data to a coarser model resolution isn't implemented yet but may be in the future. + +## Data to nudge towards + +The user is expected to prepapre (and then use `atmchange` to point to) nudging data files that are compliant with EAMxx specification. +In practice, this means that the data files must contain variable names known to EAMxx (only U, V, T_mid, and qv are supported now). +The files can be specified with an explicit list or via pattern matching. +The files must contain an arbitary global attribute `case_t0`, and it is recommended to be the same as the time dimension unit (the files must be time-dimensioned). +Finally, the dimension order must be such that `lev` is the last dimension, so most likely, the user must transpose the dimensions. + +## Pressure in the nudging data + +Pressure can be explicitly provided in the nudging data as time-varying `p_mid` corresponding to the option `TIME_DEPENDENT_3D_PROFILE` for `source_pressure_type`. +Alternatively, the data can contain a time-invariant pressure variable `p_lev` corresponding to the option `TIME_DEPENDENT_3D_PROFILE` for `source_pressure_type`. + +## Weighted nudging for RRM applications + +In regionally refined model applications, it is possible to use weighted nudging, for example, to avoid nudging the refined region. +To achieve that, the user can use `atmchange` to set `use_nudging_weights` (boolean) and provide `nudging_weights_file` that has the weight to apply for nudging (for example, zeros in the refined region). +Currently, weighted nudging is only supported if the user provides the nudging data at the target grid. ## Example setup (current as of April 2024) To enable nudging as a process, one must declare it in the `atm_procs_list` runtime parameter. ```shell - ./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging" +./atmchange physics::atm_procs_list="mac_aero_mic,rrtmgp,cosp,nudging" ``` The following options are needed to specify the nudging. ```shell -./atmchange nudging::nudging_filenames_patterns="/pathto/nudging_files/*.nc" -./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE -./atmchange nudging::nudging_fields=U,V -./atmchange nudging::nudging_timescale=21600 +./atmchange nudging::nudging_filenames_patterns="/pathto/nudging_files/*.nc" # can provide file name explicitly here instead (or multiple patterns) +./atmchange nudging::source_pressure_type=TIME_DEPENDENT_3D_PROFILE # see section on pressure +./atmchange nudging::nudging_fields=U,V # can include qv, T_mid as well +./atmchange nudging::nudging_timescale=21600 # in seconds ``` To gain a deeper understanding of these parameters and options, please refer to code implementation of the nudging process. -In particular, depending on the specific needs, one may utilize weighted nudging (for regionally refined model runs) or nudging from coarse data via specifying a map in the `atmchange` calls above. diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index 770362671d3..609bd346bf4 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -66,3 +66,7 @@ extra_javascript: - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js repo_url: https://github.com/E3SM-Project/scream + +plugins: + - bibtex: + bib_dir: refs \ No newline at end of file From 7a53ecc42ab48c38f75e62c13316ef0a80b6e36b Mon Sep 17 00:00:00 2001 From: mahf708 Date: Wed, 1 May 2024 01:43:03 -0400 Subject: [PATCH 10/10] updates to get bibtex working correctly --- .github/workflows/eamxx-gh-pages.yml | 4 ++-- components/eamxx/mkdocs.yml | 4 +++- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/.github/workflows/eamxx-gh-pages.yml b/.github/workflows/eamxx-gh-pages.yml index a78f76c9c07..abd8b92e4f6 100644 --- a/.github/workflows/eamxx-gh-pages.yml +++ b/.github/workflows/eamxx-gh-pages.yml @@ -53,10 +53,10 @@ jobs: run: | echo "= The job was automatically triggered by a ${{github.event_name}} event." - - name: Set up Python 3.10 + - name: Set up Python 3.11 uses: actions/setup-python@v5.1.0 with: - python-version: "3.10" + python-version: "3.11" - name: Install Python deps run: | diff --git a/components/eamxx/mkdocs.yml b/components/eamxx/mkdocs.yml index 609bd346bf4..ccf72c08039 100644 --- a/components/eamxx/mkdocs.yml +++ b/components/eamxx/mkdocs.yml @@ -59,6 +59,7 @@ markdown_extensions: alternate_style: true - pymdownx.arithmatex: generic: true + - footnotes extra_javascript: # - javascript/mathjax.js @@ -68,5 +69,6 @@ extra_javascript: repo_url: https://github.com/E3SM-Project/scream plugins: + - search - bibtex: - bib_dir: refs \ No newline at end of file + bib_dir: docs/refs