-
Notifications
You must be signed in to change notification settings - Fork 55
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
EAMxx: add documentation for model inputs
- Loading branch information
Showing
1 changed file
with
225 additions
and
3 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,8 +1,230 @@ | ||
| Model input | ||
| Model inputs | ||
| ===================================== | ||
|
|
||
| TODO: explain how defaults XML, atmchange/atmquery, buildml, and input.yaml work. | ||
| This section explains how input parameters are passed to EAMxx, and how the user can | ||
| change their value. The full list of the currently configuraable runtime parameters for | ||
| EAMxx can be found [here](../common/eamxx_params.md). | ||
|
|
||
| [Here](../common/eamxx_params.md) is a list of the currently configurable runtime parameters for EAMxx. | ||
| In the following, we assume that the reader has a familiarity with [CIME case | ||
| control](https://esmci.github.io/cime/versions/master/html/users_guide/index.html). | ||
|
|
||
| The main files/scripts involved in the EAMxx runtime configuration are the following: | ||
|
|
||
| 1. `buildnml`: this script, located in `components/eamxx/cime_config`, is called by CIME's case management | ||
| scripts (`case.setup`, `case.build, `case.submit`), and is responsible for creating EAMxx input files, | ||
| including handling of user-specific modifications for the runtime parameters. Users should not have to | ||
| modify this script, nor should they have to manually call it. | ||
| 2. `scream_input.yaml`: EAMxx will parse this [YAML](https://yaml.org/spec/1.2.2) file at runtime, | ||
| to detect all of its configuration parameters. It is generated automatically by `buildnml` inside the | ||
| RUNDIR/data folder, where `RUNDIR` is the run directory generated by CIME. Since this file is automatically | ||
| generated when `buildnml` runs, users should not manually modify it. Any manual modification will be | ||
| lost the next time `buildnml` runs (e.g., at `case.submit` time). | ||
| 3. 'namelist_scream.xml`: this XML file is generated by `buildnml`, 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`. In particular, `buildnml` generates this file using case information to select the | ||
| proper configuration from the file `namelist_defaults_scream.xml`, located in `components/eamxx/cime_config`. | ||
| As it was the case for `scream_input.yaml`, since this XML file is automatically generated by `buildnml`, | ||
| the user should not manually modify this file. Any manual modification will be lost the next time `buildnml` | ||
| runs (e.g., at `case.submit` time). | ||
| Since the main product of `buildnml` is `scream_input.yaml`, one may wonder why we keep | ||
| this XML file around at all. The main reason is to make it easier for the `atmquery` script (see below) to | ||
| retrieve settings. | ||
| 4. `namelist.nl`: EAMxx will parse this [namelist](https://docs.oracle.com/cd/E19957-01/805-4939/6j4m0vnad/index.html) | ||
| file at runtime, to retrieve all the parameters specific to the [Homme](some_homme_ref) dycore. | ||
| It is generated automatically by `buildnml` inside the RUNDIR/data folder, where `RUNDIR` is the run | ||
| directory generated by CIME. Since this file is automatically generated when `buildnml` runs, | ||
| users should not manually modify it. Any manual modification will be lost the next time `buildnml` runs | ||
| (e.g., at `case.submit` time). | ||
| 5. `atmchange` and `atmquery`: these script, located in `components/eamxx/scripts` and linked in the case folder, | ||
| can be used to query and change any of the runtime configuration parameters of EAMxx. | ||
|
|
||
| Among the files listed above, `atmquery` and `atmchange` are the only ones that the user should interact with, | ||
| and therefore we give here a brief overview of how they can be used, and how their output can be interpreted. | ||
| For both these scripts, a short help can also be obtained using the `-h` flag, highlighting their use cases and options. | ||
|
|
||
| # Querying parameters with `atmquery` | ||
|
|
||
| This script is the simplest way for the user to check the value and properties of EAMxx input parameters. | ||
| A basic usage of the script is | ||
|
|
||
| ```bash | ||
| $ ./atmquery my_param | ||
| ``` | ||
| which will retrieve the value of the parameter called `my_param`, by locating the XML node "my_param" in the | ||
| file `namelist_scream.xml` in the RUNDIR folder. Obviously, an XML file can have multiple nodes with the same tag, | ||
| and the script is implemented to error out if multiple matches are found. In such a scenario, the user needs | ||
| to provide also the parents nodes names, using enough parents to uniquely identify the node (in most cases, | ||
| one parent is enough). To specify a parent, the user can prepend the parent name and `::` to the node name: | ||
|
|
||
| ```bash | ||
| $ ./atmquery foo::my_param | ||
| ``` | ||
|
|
||
| The output will contain the fully scoped parameter name, along with the value. E.g., | ||
| ```bash | ||
| $ ./atmquery foo::my_param | ||
| namelist_defaults::node1::node2::foo::my_param: 10 | ||
| ``` | ||
|
|
||
| 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: | ||
| ```blah | ||
| $ ./atmquery --grep sub | ||
| iop_options::iop_dosubsidence: false | ||
| ctl_nl::hypervis_subcycle: 1 | ||
| ctl_nl::hypervis_subcycle_tom: 1 | ||
| ctl_nl::hypervis_subcycle_q: 6 | ||
| atmosphere_processes::number_of_subcycles: 1 | ||
| sc_import::number_of_subcycles: 1 | ||
| homme::number_of_subcycles: 1 | ||
| physics::number_of_subcycles: 1 | ||
| ``` | ||
| TODO: This difference between basica and `--grep` is not really intuitive (see [this | ||
| issue](https://github.com/E3SM-Project/scream/issues/2413)). | ||
| Using the `--grep` option has another effect: if the match is not a leaf of the XML tree, all its subelements | ||
| are printed: | ||
| ```bash | ||
| $ ./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 | ||
| used to respectively retrieve just the parameter value (useful for bash scripting), the parameter's type, | ||
| a list of valid values for parameter (when applicable), or all of the above: | ||
| ```bash | ||
| $ ./atmquery atm_log_level --value | ||
| info | ||
| $ ./atmquery atm_log_level --type | ||
| namelist_defaults::driver_options::atm_log_level: string | ||
| $ ./atmquery atm_log_level --valid-values | ||
| namelist_defaults::driver_options::atm_log_level: ['trace', 'debug', 'info', 'warn', 'error'] | ||
| $ ./atmquery atm_log_level --full | ||
| namelist_defaults::driver_options::atm_log_level | ||
| value: info | ||
| type: string | ||
| valid values: ['trace', 'debug', 'info', 'warn', 'error'] | ||
| ``` | ||
|
|
||
| Finally, the option `--listall` can be used to list the whole content of the XML file, which will be displayed | ||
| with each node indented in its parent scope: | ||
| ```bash | ||
| $ ./atmquery --listall | ||
| namelist_defaults | ||
| grids_manager | ||
| Type: Homme | ||
| physics_grid_type: PG2 | ||
| physics_grid_rebalance: None | ||
| dynamics_namelist_file_name: ./data/namelist.nl | ||
| vertical_coordinate_filename: /some/path/to/coords/file.nc | ||
| initial_conditions | ||
| Filename: /some/path/to/ic/file.nc | ||
| topography_filename: /some/path/to/topo/file.nc | ||
| ... | ||
| ``` | ||
|
|
||
| # Changing model inputs via `atmchange` | ||
|
|
||
| When `buildnml` runs, the model inputs are deduced from the case configuration settings (e.g., the grid, | ||
| the compset, etc.) and the `namelist_scream_defaults.xml` file, located in the eamxx source tree. | ||
| The user can change any of these parameters using the `atmchange` script. | ||
| A basic usage of the script is | ||
|
|
||
| ```bash | ||
| $ ./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: | ||
| ```bash | ||
| $ ./atmquery homme::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::homme::number_of_subcycles: 1 | ||
| $ ./atmchange number_of_subcycles=10 | ||
| ERROR: number_of_subcycles is ambiguous (use --all to change all matches), matches: | ||
| namelist_defaults::atmosphere_processes::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::sc_import::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::homme::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::physics::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::physics::mac_aero_mic::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::physics::mac_aero_mic::tms::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::physics::mac_aero_mic::shoc::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::physics::mac_aero_mic::cldFraction::number_of_subcycles | ||
| 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 | ||
| Regenerating /path/to/namelist_scream.xml. Manual edits will be lost. | ||
| $ ./atmquery homme::number_of_subcycles | ||
| namelist_defaults::atmosphere_processes::homme::number_of_subcycles: 10 | ||
| ``` | ||
| In some cases, the user may be interested in changing _all_ nodes with a given name. In that case, | ||
| the `--all` flag can be used: | ||
| ```bash | ||
| $ ./atmquery --grep number_of_subcycles | ||
| atmosphere_processes::number_of_subcycles: 1 | ||
| sc_import::number_of_subcycles: 1 | ||
| homme::number_of_subcycles: 1 | ||
| physics::number_of_subcycles: 1 | ||
| mac_aero_mic::number_of_subcycles: 24 | ||
| tms::number_of_subcycles: 1 | ||
| shoc::number_of_subcycles: 1 | ||
| cldFraction::number_of_subcycles: 1 | ||
| spa::number_of_subcycles: 1 | ||
| p3::number_of_subcycles: 1 | ||
| rrtmgp::number_of_subcycles: 1 | ||
| sc_export::number_of_subcycles: 1 | ||
| $ ./atmchange --all number_of_subcycles=3 | ||
| Regenerating /path/to/namelist_scream.xml. Manual edits will be lost. | ||
| $ ./atmquery --grep number_of_subcycles | ||
| atmosphere_processes::number_of_subcycles: 3 | ||
| sc_import::number_of_subcycles: 3 | ||
| homme::number_of_subcycles: 3 | ||
| physics::number_of_subcycles: 3 | ||
| mac_aero_mic::number_of_subcycles: 3 | ||
| tms::number_of_subcycles: 3 | ||
| shoc::number_of_subcycles: 3 | ||
| cldFraction::number_of_subcycles: 3 | ||
| spa::number_of_subcycles: 3 | ||
| p3::number_of_subcycles: 3 | ||
| rrtmgp::number_of_subcycles: 3 | ||
| sc_export::number_of_subcycles: 3 | ||
| ``` | ||
| Since the XML file stores constraints on the parameter value (like its type or valid values), attempting to use the | ||
| wrong type will cause an error: | ||
| ```bash | ||
| $ ./atmquery --type se_ne | ||
| namelist_defaults::ctl_nl::se_ne: integer | ||
| $ ./atmchange se_ne=hello | ||
| ERROR: Could not refine 'hello' as type 'integer': | ||
| ``` | ||
| There are three main types supported: integer, float, string, logical. When passing a string to `atmchange`, | ||
| the script will try to interpret it acoording to the parameter type, and throw an error if that's not possible: | ||
| for "string", anything works; for "integer", only digits are allowed, possibly with a negative sign in front; | ||
| 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 | ||
| a `std::vector<T>`. | ||
|
|
||
| For type "string" and "array(T)", it is also possible to _append_ to the currently stored value | ||
| ```bash | ||
| $ ./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 | ||
| namelist_defaults::atmosphere_processes::homme::compute_tendencies | ||
| value: a, b, c | ||
| type: array(string) | ||
| valid values: [] | ||
| ``` |