From f149cf2bf16eda9654561ffdd3799b834a1fee97 Mon Sep 17 00:00:00 2001 From: Luca Bertagna Date: Wed, 22 Jan 2025 09:18:38 -0700 Subject: [PATCH 1/5] EAMxx: fixes to atmquery/atmchange docs --- components/eamxx/docs/user/model_input.md | 39 +++++++++++------------ 1 file changed, 18 insertions(+), 21 deletions(-) diff --git a/components/eamxx/docs/user/model_input.md b/components/eamxx/docs/user/model_input.md index def86e25c80f..78fefb57b99d 100644 --- a/components/eamxx/docs/user/model_input.md +++ b/components/eamxx/docs/user/model_input.md @@ -60,6 +60,22 @@ $ ./atmquery foo::my_param namelist_defaults::node1::node2::foo::my_param: 10 ``` +If the input parameter is not a leaf but a node with sub-elements, the output will recursively print all +sub-elements, properly indented: + +```shell +$ ./atmquery homme + homme + Moisture: moist + BfbHash: 18 + number_of_subcycles: 1 + enable_precondition_checks: true + enable_postcondition_checks: true + repair_log_level: trace + internal_diagnostics_level: 0 + compute_tendencies: None +``` + It is sometimes desirable to query _all_ the nodes that have a particular name, or that contain a particular string. We can do that by using the `--grep` flag: @@ -75,28 +91,9 @@ $ ./atmquery --grep sub physics::number_of_subcycles: 1 ``` -TODO: This difference between basic and `--grep` is not really intuitive: as pointed out in [this -issue](https://github.com/E3SM-Project/scream/issues/2413), we should change this. If we do, don't forget -to update this following part of the docs. -Using the `--grep` option has another effect: if the match is not a leaf of the XML tree, all its subelements -are printed: - -```shell -$ ./atmquery --grep homme - homme - Moisture: moist - BfbHash: 18 - number_of_subcycles: 1 - enable_precondition_checks: true - enable_postcondition_checks: true - repair_log_level: trace - internal_diagnostics_level: 0 - compute_tendencies: None -``` - -Similarly to the CIME utility `xmlchange`, the options `--value`, `--type`, `--valid-values`, and `--full` can be +Similarly to the CIME utility `xmlquery`, the options `--value`, `--type`, `--valid-values`, and `--full` can be used to respectively retrieve just the parameter value (useful for shell scripting), the parameter's type, -a list of valid values for parameter (when applicable), or all of the above: +a list of valid values for the parameter (when applicable), or all of the above: ```shell $ ./atmquery atm_log_level --value From 9814f13ba9fe8065850e4d7b253bbfba6128f477 Mon Sep 17 00:00:00 2001 From: Luca Bertagna Date: Wed, 22 Jan 2025 09:19:07 -0700 Subject: [PATCH 2/5] EAMxx: small upgrades to model output docs Start adding formulas for diags --- components/eamxx/docs/user/model_output.md | 61 +++++++++++++--------- 1 file changed, 37 insertions(+), 24 deletions(-) diff --git a/components/eamxx/docs/user/model_output.md b/components/eamxx/docs/user/model_output.md index 65b8c9e7d940..6ee39480ce7b 100644 --- a/components/eamxx/docs/user/model_output.md +++ b/components/eamxx/docs/user/model_output.md @@ -1,16 +1,17 @@ # Model output EAMxx allows the user to configure the desired model output via [YAML](https://yaml.org/) files, -with each YAML file associated to a different output file. In order to add an output stream, +with each YAML file associated to a different output stream (i.e. a file). In order to add an output stream, one needs to run `atmchange output_yaml_files+=/path/to/my/output/yaml` (more information on how to use `atmchange` can be found [here](./model_input.md#changing-model-inputs-atmchange)). -During the `buildnml` phase of the case management system, a copy of these YAML files will be copied +During the `buildnml` phase of the case management system, these YAML files will be copied into the RUNDIR/data folder. During this process, the files will be parsed, and any CIME-related -variable will be resolved accordingly. Therefore, it is not advised to put the original YAML files in RUNDIR/data, -since upon `buildnml` execution, all the CIME vars will no longer be available in the YAML file, -making it harder to tweak it, and even harder to share with other users/cases. Another consequence -of this is that the user should not modify the YAML files in RUNDIR/data, since any modification will -be lost on the next run of `buildnml`. +variable will be resolved accordingly. Therefore, it is not advised to put the original YAML files +in RUNDIR/data, since upon `buildnml` execution, all the CIME vars will no longer be present in the +YAML file (replaced by their values), making it harder to tweak it, and even harder to share with +other users/cases. Another consequence of this is that, much like `scream_input.yaml', the user should +not modify the generated YAML files in RUNDIR/data, since any modification will be lost on the next +run of `buildnml` (e.g., during `case.submit'). ## Basic output @@ -37,7 +38,8 @@ output_control: ``` Notice that lists can be equivalently specified in YAML as `Field Names: [f1, f2, f3]`. -The user can specify fields to be outputted from any of the grids used in the simulation. +The user can specify fields to be outputted from any of the grids on which they are available +(although most fields are only available on ONE grid). In the example above, we requested fields from both the Physics and Dynamics grid. The meaning of the other parameters is as follows: @@ -47,15 +49,18 @@ The meaning of the other parameters is as follows: - Instant: no integration, each time frame saved corresponds to instantaneous values of the fields - Average/Max/Min: the fields undergo the corresponding operation over the time - interval specified in the `output_control` section. In the case above, each snapshot - saved to file corresponds to an average of the output fields over 6h windows. + interval since the last output step (as specified in the `output_control` section). + In the case above, each snapshot saved to file corresponds to an average of the output + fields over 6h windows. - `filename_prefix`: the prefix of the output file, which will be created in the run directory. The full filename will be `$prefix.$avgtype.$frequnits_x$freq.$timestamp.nc`, - where $timestamp corresponds to the first snapshot saved in the file for Instant output, - or the beginning of the first averaging window for the other averaging types + where `$timestamp` corresponds to the first snapshot saved in the file for Instant output, + or the beginning of the first averaging window for the other averaging types. If not set, + it defaults to `$casename.scream.h`. - `Max Snapshots Per File`: specifies how many time snapshots can be put in a file. Once - this number is reached, EAMxx will close the file and open a new one. + this number is reached, EAMxx will close the file and open a new one. If not set, + it defaults to `-1`, signaling "unlimited storage". - `Frequency`: how many units of time are between two consecutive writes to file. For Instant output the fields are "sampled" at this frequency, while for other averaging types the fields are "integrated" in time over this window @@ -73,16 +78,17 @@ I/O interface of EAMxx. There are two types of diagnostic outputs: that EAMxx does not keep in persistent storage. As of May 2024, the available derived quantities are (case sensitive): - - `PotentialTemperature` - - `AtmosphereDensity` - - `Exner` - - `VirtualTemperature` - - `z_int` - - `z_mid` - - `geopotential_int` - - `geopotential_mid` - - `dz` - - `DryStaticEnergy` + - `Exner`: $\Pi = \left( \dfrac{p}{p_0} \right) ^\dfrac{R_d}{c_p}$ + - `PotentialTemperature`: $\Theta = T / \Pi$ + - `LiqPotentialTemperature`: $\Theta_\ell = \Theta - \dfrac{\Theta}{T} \dfrac{L_v}{c_p}q_c$ + - `dz`: $dz = \dfrac{rd}{g}\dfrac{\rho_s T_v}{p}$ + - `z_int`: vertical sum of `dz` from surface (b.c. at surface: 0 or $\phi_s/g$, depending if from surface or sealevel) + - `z_mid`: midpoint average of `z_int` + - `geopotential_int`: vertical sum of `g dz` from surface (b.c. at surface: $\phi_s$) + - `geopotential_mid`: midpoint average of `geopotential_int` + - `AtmosphereDensity`: $\rho = \dfrac{\rho_s}{dz*g} + - `VirtualTemperature`: $T_v = T\left(1+c_1 q_v\right)$ + - `DryStaticEnergy`: $DSE = c_p T + gz + \phi_s$ - `SeaLevelPressure` - `LiqWaterPath` - `IceWaterPath` @@ -103,7 +109,14 @@ I/O interface of EAMxx. There are two types of diagnostic outputs: - `NumberPath` - `AeroComCld` - TODO: add some information about what each diagnostic is, perhaps a formula + Where the other symbols above are: + + - $p_0$: reference pressure (100kPa in EAMxx) + - $R_d$: gas constant for dry air + - $\rho_s$: pseudo density + - $c_1=-1+\frac{1}{\epsilon}$ + - $\epsilon=\frac{M_w}{M_d}$ + - $M_w$,$M_d$: molecular masses of water and dry air respectively - lower-dimensional slices of a field. These are hyperslices of an existing field or of another diagnostic output. As of August 2023, given a field X, the available options From a15bf66b89be27c36ccec4a04619dc9e023032f4 Mon Sep 17 00:00:00 2001 From: Luca Bertagna Date: Wed, 22 Jan 2025 16:58:48 -0700 Subject: [PATCH 3/5] EAMxx: fix mdlinter issues in the docs --- components/eamxx/docs/user/model_input.md | 91 ++++++++--------- components/eamxx/docs/user/model_output.md | 110 ++++++++++----------- 2 files changed, 102 insertions(+), 99 deletions(-) diff --git a/components/eamxx/docs/user/model_input.md b/components/eamxx/docs/user/model_input.md index 78fefb57b99d..f76b204e84f4 100644 --- a/components/eamxx/docs/user/model_input.md +++ b/components/eamxx/docs/user/model_input.md @@ -17,19 +17,19 @@ The infrastructure for reading inputs into EAMxx involves a few scripts/files: the input files that EAMxx will read to load its runtime parameters. Users should not have to modify this script, nor should they have to manually call it, but it is useful to know what it does. When `buildnml` runs, it creates a few files, containing EAMxx input parameters: - - `scream_input.yaml`: this [YAML](https://yaml.org/spec/1.2.2) file is located in the `RUNDIR/data` folder, - and will be read by EAMxx at runtime to load all of its configuration parameters. More precisely, - this file contains parameters that need to be used inside the EAMxx interfaces. - - `namelist.nl`: this [namelist](https://docs.oracle.com/cd/E19957-01/805-4939/6j4m0vnad/index.html) file is - located in the `RUNDIR/data` folder, and will be parsed at runtime to get all the parameters for the - HOMME dycore (ADD REF). This file only contains dycore-specific parameters that are only recognized - inside HOMME, and does not contain any parameter pertaining EAMxx infrastructure. - - `namelist_scream.xml`: this XML file is located in the case directory, and contains all the runtime parameters that EAMxx - will read in at runtime. `buildnml` uses this XML file as an intermediate file during the generation of - `scream_input.yaml` and `namelist.nl`. More specifically, `buildnml` generates this file using case information to select the - proper configurations from the file `namelist_defaults_scream.xml`, located in `SRCDIR/components/eamxx/cime_config`. - Despite the fact that the only files that are needed at runtime are `scream_input.yaml` and `namelist.nl`, - we generate and keep this XML file around to make the implementation of `atmquery` easier. + - `scream_input.yaml`: this [YAML](https://yaml.org/spec/1.2.2) file is located in the `RUNDIR/data` folder, + and will be read by EAMxx at runtime to load all of its configuration parameters. More precisely, + this file contains parameters that need to be used inside the EAMxx interfaces. + - `namelist.nl`: this [namelist](https://docs.oracle.com/cd/E19957-01/805-4939/6j4m0vnad/index.html) file is + located in the `RUNDIR/data` folder, and will be parsed at runtime to get all the parameters for the + HOMME dycore (ADD REF). This file only contains dycore-specific parameters that are only recognized + inside HOMME, and does not contain any parameter pertaining EAMxx infrastructure. + - `namelist_scream.xml`: this XML file is located in the case directory, and contains all the runtime parameters that EAMxx + will read in at runtime. `buildnml` uses this XML file as an intermediate file during the generation of + `scream_input.yaml` and `namelist.nl`. More specifically, `buildnml` generates this file using case information to select the + proper configurations from the file `namelist_defaults_scream.xml`, located in `SRCDIR/components/eamxx/cime_config`. + Despite the fact that the only files that are needed at runtime are `scream_input.yaml` and `namelist.nl`, + we generate and keep this XML file around to make the implementation of `atmquery` easier. Since these files are automatically generated when `buildnml` runs, users should not manually modify them. Any manual modification will be lost the next time `buildnml` runs (e.g., at `case.submit` time). @@ -40,7 +40,7 @@ This script is the simplest way for the user to check the value and properties o A basic usage of the script is ```shell -$ ./atmquery my_param +> ./atmquery my_param ``` which will retrieve the value of the parameter called `my_param`, by locating the XML node "my_param" in the @@ -50,13 +50,13 @@ to provide also the parents nodes names, using enough parents to uniquely identi one parent is enough). To specify a parent, the user can prepend the parent name and `::` to the node name: ```shell -$ ./atmquery foo::my_param +> ./atmquery foo::my_param ``` The output will contain the fully scoped parameter name, along with the value. E.g., ```shell -$ ./atmquery foo::my_param +> ./atmquery foo::my_param namelist_defaults::node1::node2::foo::my_param: 10 ``` @@ -64,7 +64,7 @@ If the input parameter is not a leaf but a node with sub-elements, the output wi sub-elements, properly indented: ```shell -$ ./atmquery homme +> ./atmquery homme homme Moisture: moist BfbHash: 18 @@ -80,7 +80,7 @@ It is sometimes desirable to query _all_ the nodes that have a particular name, string. We can do that by using the `--grep` flag: ```shell -$ ./atmquery --grep sub +> ./atmquery --grep sub iop_options::iop_dosubsidence: false ctl_nl::hypervis_subcycle: 1 ctl_nl::hypervis_subcycle_tom: 1 @@ -96,13 +96,13 @@ used to respectively retrieve just the parameter value (useful for shell scripti a list of valid values for the parameter (when applicable), or all of the above: ```shell -$ ./atmquery atm_log_level --value +> ./atmquery atm_log_level --value info -$ ./atmquery atm_log_level --type +> ./atmquery atm_log_level --type namelist_defaults::driver_options::atm_log_level: string -$ ./atmquery atm_log_level --valid-values +> ./atmquery atm_log_level --valid-values namelist_defaults::driver_options::atm_log_level: ['trace', 'debug', 'info', 'warn', 'error'] -$ ./atmquery atm_log_level --full +> ./atmquery atm_log_level --full namelist_defaults::driver_options::atm_log_level value: info type: string @@ -113,7 +113,7 @@ Finally, the option `--listall` can be used to list the whole content of the XML with each node indented in its parent scope: ```shell -$ ./atmquery --listall +> ./atmquery --listall namelist_defaults grids_manager Type: Homme @@ -135,16 +135,16 @@ The user can change any of these parameters using the `atmchange` script. A basic usage of the script is ```shell -$ ./atmchange my_param=10 +> ./atmchange my_param=10 ``` As for `atmquery`, if there are multiple matches for a given parameter name, the user must specify a unique scoped name, which allows `atmchange` to uniquely identify the XML node to modify: ```shell -$ ./atmquery homme::number_of_subcycles +> ./atmquery homme::number_of_subcycles namelist_defaults::atmosphere_processes::homme::number_of_subcycles: 1 -$ ./atmchange number_of_subcycles=10 +> ./atmchange number_of_subcycles=10 ERROR: internal_diagnostics_level is ambiguous. Use ANY in the node path to allow multiple matches. Matches: namelist_defaults::atmosphere_processes::number_of_subcycles namelist_defaults::atmosphere_processes::sc_import::number_of_subcycles @@ -158,9 +158,9 @@ ERROR: internal_diagnostics_level is ambiguous. Use ANY in the node path to allo namelist_defaults::atmosphere_processes::physics::mac_aero_mic::p3::number_of_subcycles namelist_defaults::atmosphere_processes::physics::rrtmgp::number_of_subcycles namelist_defaults::atmosphere_processes::sc_export::number_of_subcycles -$ ./atmchange homme::number_of_subcycles=10 +> ./atmchange homme::number_of_subcycles=10 Regenerating /path/to/namelist_scream.xml. Manual edits will be lost. -$ ./atmquery homme::number_of_subcycles +> ./atmquery homme::number_of_subcycles namelist_defaults::atmosphere_processes::homme::number_of_subcycles: 10 ``` @@ -168,7 +168,7 @@ In some cases, the user may be interested in changing _all_ nodes with a given n you can use 'ANY' as a node name: ```shell -$ ./atmquery --grep number_of_subcycles +> ./atmquery --grep number_of_subcycles atmosphere_processes::number_of_subcycles: 1 sc_import::number_of_subcycles: 1 homme::number_of_subcycles: 1 @@ -181,9 +181,9 @@ $ ./atmquery --grep number_of_subcycles p3::number_of_subcycles: 1 rrtmgp::number_of_subcycles: 1 sc_export::number_of_subcycles: 1 -$ ./atmchange ANY::number_of_subcycles=3 +> ./atmchange ANY::number_of_subcycles=3 Regenerating /path/to/namelist_scream.xml. Manual edits will be lost. -$ ./atmquery --grep number_of_subcycles +> ./atmquery --grep number_of_subcycles atmosphere_processes::number_of_subcycles: 3 sc_import::number_of_subcycles: 3 homme::number_of_subcycles: 3 @@ -197,11 +197,13 @@ $ ./atmquery --grep number_of_subcycles rrtmgp::number_of_subcycles: 3 sc_export::number_of_subcycles: 3 ``` + In addition, "ANY" can be used in a "scoped" string, to limit the set of matches: + ```shell -$ ./atmchange mac_aero_mic::ANY::number_of_subcycles=1 +> ./atmchange mac_aero_mic::ANY::number_of_subcycles=1 Regenerating /path/to/namelist_scream.xml. Manual edits will be lost. -$ ./atmquery --grep number_of_subcycles +> ./atmquery --grep number_of_subcycles atmosphere_processes::number_of_subcycles: 3 sc_import::number_of_subcycles: 3 homme::number_of_subcycles: 3 @@ -220,9 +222,9 @@ Since the XML file stores constraints on the parameter value (like its type or v wrong type will cause an error: ```shell -$ ./atmquery --type se_ne +> ./atmquery --type se_ne namelist_defaults::ctl_nl::se_ne: integer -$ ./atmchange se_ne=hello +> ./atmchange se_ne=hello ERROR: Could not refine 'hello' as type 'integer': ``` @@ -232,6 +234,7 @@ for "string", anything works; for "integer", only digits are allowed, possibly w for "float", only digits are allowed, possibly with a negative sign in front and a decimal point; for "logical", only the strings "true" and "false" are allowed (case insensitive). There are two additional types supported: "file" and "array(T)", where "T" is any of the other supported types (but not another array): + - "file" is used to inform CIME of the input files that have to be download from E3SM data servers, like initial conditions files, or certain lookup tables. - "array(T)" allows to specify a list of items (of the same type), which will be parsed inside EAMxx as @@ -240,13 +243,13 @@ or certain lookup tables. For type "string" and "array(T)", it is also possible to _append_ to the currently stored value ```shell -$ ./atmquery homme::compute_tendencies +> ./atmquery homme::compute_tendencies namelist_defaults::atmosphere_processes::homme::compute_tendencies: value: a, b type: array(string) valid values: [] -$ ./atmchange homme::compute_tendencies+=c -$ ./atmquery homme::compute_tendencies --full +> ./atmchange homme::compute_tendencies+=c +> ./atmquery homme::compute_tendencies --full namelist_defaults::atmosphere_processes::homme::compute_tendencies value: a, b, c type: array(string) @@ -261,7 +264,7 @@ make sure that the defaults for that process are present in `namelist_defaults_s the default settings for the "physics" atmosphere process group include the following: ```shell -$ ./atmquery physics::atm_procs_list +> ./atmquery physics::atm_procs_list namelist_defaults::atmosphere_processes::physics::atm_procs_list: mac_aero_mic,rrtmgp ``` @@ -270,8 +273,8 @@ processes. If one wanted to add the "cosp" atmosphere process to this list, and subcycles, it could do so via ```shell -$ ./atmchange physics::atm_procs_list+=cosp -$ ./atmchange cosp::number_of_subcycles=3 +> ./atmchange physics::atm_procs_list+=cosp +> ./atmchange cosp::number_of_subcycles=3 ``` Notice that if we swapped the two commands, we would get an error, since the node "cosp" is not present in @@ -282,14 +285,14 @@ atmosphere processes via subsequent calls to `atmchange`. The syntax to trigger in specifying a process name that begins and ends with an underscore: ```shell -$ ./atmchange physics::atm_procs_list+=_my_group_ +> ./atmchange physics::atm_procs_list+=_my_group_ ``` This adds a new process to the list of processes in "physics", called "\_my_group\_", and which is itself an atmosphere process group. Hence, we can then do ```shell -$ ./atmchange _my_group_::atm_procs_list+=A,B +> ./atmchange _my_group_::atm_procs_list+=A,B ``` where A and B must be valid atmosphere process names (i.e., present in `namelist_defaults_scream.xml`) @@ -298,7 +301,7 @@ or be themselves new atmosphere process groups (i.e., beginning/ending with an u `atmchange` can also be used to completely change a list of atmosphere processes: ```shell -$ ./atmchange physics::atm_procs_list=A,B,C +> ./atmchange physics::atm_procs_list=A,B,C ``` Notice that we used "=" instead of "+=", which means we will be overwriting the value, rather than appending. diff --git a/components/eamxx/docs/user/model_output.md b/components/eamxx/docs/user/model_output.md index 6ee39480ce7b..3db354260a5d 100644 --- a/components/eamxx/docs/user/model_output.md +++ b/components/eamxx/docs/user/model_output.md @@ -11,7 +11,7 @@ in RUNDIR/data, since upon `buildnml` execution, all the CIME vars will no longe YAML file (replaced by their values), making it harder to tweak it, and even harder to share with other users/cases. Another consequence of this is that, much like `scream_input.yaml', the user should not modify the generated YAML files in RUNDIR/data, since any modification will be lost on the next -run of `buildnml` (e.g., during `case.submit'). +run of `buildnml` (e.g., during `case.submit`). ## Basic output @@ -46,12 +46,12 @@ The meaning of the other parameters is as follows: - `Averaging Type`: how the fields are integrated in time before being saved. Valid options are - - Instant: no integration, each time frame saved corresponds to instantaneous values - of the fields - - Average/Max/Min: the fields undergo the corresponding operation over the time - interval since the last output step (as specified in the `output_control` section). - In the case above, each snapshot saved to file corresponds to an average of the output - fields over 6h windows. + - Instant: no integration, each time frame saved corresponds to instantaneous values + of the fields + - Average/Max/Min: the fields undergo the corresponding operation over the time + interval since the last output step (as specified in the `output_control` section). + In the case above, each snapshot saved to file corresponds to an average of the output + fields over 6h windows. - `filename_prefix`: the prefix of the output file, which will be created in the run directory. The full filename will be `$prefix.$avgtype.$frequnits_x$freq.$timestamp.nc`, @@ -78,57 +78,57 @@ I/O interface of EAMxx. There are two types of diagnostic outputs: that EAMxx does not keep in persistent storage. As of May 2024, the available derived quantities are (case sensitive): - - `Exner`: $\Pi = \left( \dfrac{p}{p_0} \right) ^\dfrac{R_d}{c_p}$ - - `PotentialTemperature`: $\Theta = T / \Pi$ - - `LiqPotentialTemperature`: $\Theta_\ell = \Theta - \dfrac{\Theta}{T} \dfrac{L_v}{c_p}q_c$ - - `dz`: $dz = \dfrac{rd}{g}\dfrac{\rho_s T_v}{p}$ - - `z_int`: vertical sum of `dz` from surface (b.c. at surface: 0 or $\phi_s/g$, depending if from surface or sealevel) - - `z_mid`: midpoint average of `z_int` - - `geopotential_int`: vertical sum of `g dz` from surface (b.c. at surface: $\phi_s$) - - `geopotential_mid`: midpoint average of `geopotential_int` - - `AtmosphereDensity`: $\rho = \dfrac{\rho_s}{dz*g} - - `VirtualTemperature`: $T_v = T\left(1+c_1 q_v\right)$ - - `DryStaticEnergy`: $DSE = c_p T + gz + \phi_s$ - - `SeaLevelPressure` - - `LiqWaterPath` - - `IceWaterPath` - - `VapWaterPath` - - `RainWaterPath` - - `RimeWaterPath` - - `ShortwaveCloudForcing` - - `LongwaveCloudForcing` - - `RelativeHumidity` - - `ZonalVapFlux` - - `MeridionalVapFlux` - - `precip_liq_surf_mass_flux` - - `precip_ice_surf_mass_flux` - - `precip_total_surf_mass_flux` - - `surface_upward_latent_heat_flux` - - `wind_speed` - - `AerosolOpticalDepth550nm` - - `NumberPath` - - `AeroComCld` - - Where the other symbols above are: - - - $p_0$: reference pressure (100kPa in EAMxx) - - $R_d$: gas constant for dry air - - $\rho_s$: pseudo density - - $c_1=-1+\frac{1}{\epsilon}$ - - $\epsilon=\frac{M_w}{M_d}$ - - $M_w$,$M_d$: molecular masses of water and dry air respectively + - `Exner`: $\Pi = \left( \dfrac{p}{p_0} \right) ^\dfrac{R_d}{c_p}$ + - `PotentialTemperature`: $\Theta = T / \Pi$ + - `LiqPotentialTemperature`: $\Theta_\ell = \Theta - \dfrac{\Theta}{T} \dfrac{L_v}{c_p}q_c$ + - `dz`: $dz = \dfrac{rd}{g}\dfrac{\rho_s T_v}{p}$ + - `z_int`: vertical sum of `dz` from surface (b.c. at surface: 0 or $\phi_s/g$, depending if from surface or sealevel) + - `z_mid`: midpoint average of `z_int` + - `geopotential_int`: vertical sum of `g dz` from surface (b.c. at surface: $\phi_s$) + - `geopotential_mid`: midpoint average of `geopotential_int` + - `AtmosphereDensity`: $\rho = \dfrac{\rho_s}{dz*g} + - `VirtualTemperature`: $T_v = T\left(1+c_1 q_v\right)$ + - `DryStaticEnergy`: $DSE = c_p T + gz + \phi_s$ + - `SeaLevelPressure` + - `LiqWaterPath` + - `IceWaterPath` + - `VapWaterPath` + - `RainWaterPath` + - `RimeWaterPath` + - `ShortwaveCloudForcing` + - `LongwaveCloudForcing` + - `RelativeHumidity` + - `ZonalVapFlux` + - `MeridionalVapFlux` + - `precip_liq_surf_mass_flux` + - `precip_ice_surf_mass_flux` + - `precip_total_surf_mass_flux` + - `surface_upward_latent_heat_flux` + - `wind_speed` + - `AerosolOpticalDepth550nm` + - `NumberPath` + - `AeroComCld` + + Where the other symbols above are: + + - $p_0$: reference pressure (100kPa in EAMxx) + - $R_d$: gas constant for dry air + - $\rho_s$: pseudo density + - $c_1=-1+\frac{1}{\epsilon}$ + - $\epsilon=\frac{M_w}{M_d}$ + - $M_w$,$M_d$: molecular masses of water and dry air respectively - lower-dimensional slices of a field. These are hyperslices of an existing field or of another diagnostic output. As of August 2023, given a field X, the available options are: - - `X_at_lev_N`: slice the field `X` at the N-th vertical level index. Recall that - in EAMxx N=0 corresponds to the model top. - - `X_at_model_bot`, `X_at_model_top`: special case for top and bottom of the model. - - `X_at_Ymb`, `X_at_YPa`, `X_at_YhPa`: interpolates the field `X` at a vertical position - specified by the give pressure `Y`. Available units are `mb` (millibar), `Pa`, and `hPa`. - - `X_at_Ym_above_Z`: interpolates the field `X` at a vertical height of `Y` meters above - `Z`, with `Z=surface` or `Z=sealevel`. + - `X_at_lev_N`: slice the field `X` at the N-th vertical level index. Recall that + in EAMxx N=0 corresponds to the model top. + - `X_at_model_bot`, `X_at_model_top`: special case for top and bottom of the model. + - `X_at_Ymb`, `X_at_YPa`, `X_at_YhPa`: interpolates the field `X` at a vertical position + specified by the give pressure `Y`. Available units are `mb` (millibar), `Pa`, and `hPa`. + - `X_at_Ym_above_Z`: interpolates the field `X` at a vertical height of `Y` meters above + `Z`, with `Z=surface` or `Z=sealevel`. ## Remapped output @@ -146,7 +146,7 @@ they are computed on. before being saved to file. This feature is really only used to save fields on the dynamics grid without saving twice the DOFs at the interface of two spectral elements. E.g., for a scalar quantity defined only in the horizontal direction, native output - from the Dynamics grid would produce arrays of length `nelems*ngp*ngp`, where `ngp` + from the Dynamics grid would produce arrays of length `nelems*ngp*ngp`, where `ngp` is the number of Gauss points along each axis in the 2d spectral element, and `nelems` is the number of horizontal elements. However, due to continuity, the values on the Gauss points on the element boundary must match the values on the neighboring element, @@ -198,7 +198,7 @@ file and the type of the parameter value). - `save_grid_data` (`output_control` sublist, boolean): this option allows to specify whether grid data (such as `lat`/`lon`) should be added to the output stream. By default, it is `true`. - `iotype` (toplevel list, string): this option allows the user to request a particular format for the output - file. The possible values are `default`, `netcdf`, `pnetcdf, `adios`, `hdf5`, where `default` means + file. The possible values are 'default', 'netcdf', 'pnetcdf' 'adios', 'hdf5', where 'default' means "whatever is the PIO type from the case settings". - `skip_t0_output` (`output_control` sublist, boolean): this option is relevant only for `Instant` output, where fields are also outputed at the case start time (i.e., after initialization but before the beginning From 37fc66ccb4f23bc42632049a56e499c85b25e0b2 Mon Sep 17 00:00:00 2001 From: Luca Bertagna Date: Wed, 22 Jan 2025 17:39:17 -0700 Subject: [PATCH 4/5] EAMxx: give up on formulas of diagnostics in the docs It gets too complicated for a user guide. They belong in the tech docs --- components/eamxx/docs/user/model_output.md | 31 ++++++++-------------- 1 file changed, 11 insertions(+), 20 deletions(-) diff --git a/components/eamxx/docs/user/model_output.md b/components/eamxx/docs/user/model_output.md index 3db354260a5d..a41f8d7f43c5 100644 --- a/components/eamxx/docs/user/model_output.md +++ b/components/eamxx/docs/user/model_output.md @@ -78,17 +78,17 @@ I/O interface of EAMxx. There are two types of diagnostic outputs: that EAMxx does not keep in persistent storage. As of May 2024, the available derived quantities are (case sensitive): - - `Exner`: $\Pi = \left( \dfrac{p}{p_0} \right) ^\dfrac{R_d}{c_p}$ - - `PotentialTemperature`: $\Theta = T / \Pi$ - - `LiqPotentialTemperature`: $\Theta_\ell = \Theta - \dfrac{\Theta}{T} \dfrac{L_v}{c_p}q_c$ - - `dz`: $dz = \dfrac{rd}{g}\dfrac{\rho_s T_v}{p}$ - - `z_int`: vertical sum of `dz` from surface (b.c. at surface: 0 or $\phi_s/g$, depending if from surface or sealevel) - - `z_mid`: midpoint average of `z_int` - - `geopotential_int`: vertical sum of `g dz` from surface (b.c. at surface: $\phi_s$) - - `geopotential_mid`: midpoint average of `geopotential_int` - - `AtmosphereDensity`: $\rho = \dfrac{\rho_s}{dz*g} - - `VirtualTemperature`: $T_v = T\left(1+c_1 q_v\right)$ - - `DryStaticEnergy`: $DSE = c_p T + gz + \phi_s$ + - `Exner` + - `PotentialTemperature` + - `LiqPotentialTemperature` + - `dz` + - `z_int` + - `z_mid` + - `geopotential_int` + - `geopotential_mid` + - `AtmosphereDensity` + - `VirtualTemperature` + - `DryStaticEnergy` - `SeaLevelPressure` - `LiqWaterPath` - `IceWaterPath` @@ -109,15 +109,6 @@ I/O interface of EAMxx. There are two types of diagnostic outputs: - `NumberPath` - `AeroComCld` - Where the other symbols above are: - - - $p_0$: reference pressure (100kPa in EAMxx) - - $R_d$: gas constant for dry air - - $\rho_s$: pseudo density - - $c_1=-1+\frac{1}{\epsilon}$ - - $\epsilon=\frac{M_w}{M_d}$ - - $M_w$,$M_d$: molecular masses of water and dry air respectively - - lower-dimensional slices of a field. These are hyperslices of an existing field or of another diagnostic output. As of August 2023, given a field X, the available options are: From c057ef7c2954ae60fefffa346c0988fed4706756 Mon Sep 17 00:00:00 2001 From: Luca Bertagna Date: Wed, 22 Jan 2025 17:50:11 -0700 Subject: [PATCH 5/5] EAMxx: more md linting fixes to the docs --- components/eamxx/docs/user/model_input.md | 6 +++--- components/eamxx/docs/user/model_output.md | 5 +---- 2 files changed, 4 insertions(+), 7 deletions(-) diff --git a/components/eamxx/docs/user/model_input.md b/components/eamxx/docs/user/model_input.md index f76b204e84f4..384cb312938b 100644 --- a/components/eamxx/docs/user/model_input.md +++ b/components/eamxx/docs/user/model_input.md @@ -235,10 +235,10 @@ for "float", only digits are allowed, possibly with a negative sign in front and only the strings "true" and "false" are allowed (case insensitive). There are two additional types supported: "file" and "array(T)", where "T" is any of the other supported types (but not another array): - - "file" is used to inform CIME of the input files that have to be download from E3SM data servers, like initial conditions files, +- "file" is used to inform CIME of the input files that have to be download from E3SM data servers, like initial conditions files, or certain lookup tables. - - "array(T)" allows to specify a list of items (of the same type), which will be parsed inside EAMxx as - a `std::vector`. +- "array(T)" allows to specify a list of items (of the same type), which will be parsed inside EAMxx as + a `std::vector`. For type "string" and "array(T)", it is also possible to _append_ to the currently stored value diff --git a/components/eamxx/docs/user/model_output.md b/components/eamxx/docs/user/model_output.md index a41f8d7f43c5..f00d85e4d86f 100644 --- a/components/eamxx/docs/user/model_output.md +++ b/components/eamxx/docs/user/model_output.md @@ -9,7 +9,7 @@ into the RUNDIR/data folder. During this process, the files will be parsed, and variable will be resolved accordingly. Therefore, it is not advised to put the original YAML files in RUNDIR/data, since upon `buildnml` execution, all the CIME vars will no longer be present in the YAML file (replaced by their values), making it harder to tweak it, and even harder to share with -other users/cases. Another consequence of this is that, much like `scream_input.yaml', the user should +other users/cases. Another consequence of this is that, much like `scream_input.yaml`, the user should not modify the generated YAML files in RUNDIR/data, since any modification will be lost on the next run of `buildnml` (e.g., during `case.submit`). @@ -206,6 +206,3 @@ file and the type of the parameter value). - `force_new_file` (`Restart` sublist, boolean): this parameter allows to start a fresh new output file upon restarts. By default, is is set to `false`, so that EAMxx will attempt to resume filling the last produced output file (if any, and if it can accommodate more snapshots). - - -