.. _wfnamelistref-label: ================================================== Workflow Namelist (wfnamelist) Reference Document ================================================== This is a copy of the file **packages/ehratmworkflow/src/ehratmworkflow/wfnamelist_reference.nml**, which serves as the official definition document of options within a wfnamelist. The file constitutes a correctly formatted wfnamelist and contains ALL options that one might find in such a namelist, even those that might conflict with each other. The programs that process a wfnamelist will look at each option and ensure that such an option is defined in the reference namelist. This helps to catch typos, and ensures that users define only valid options. At the same time, with the extensive documentation within the file, it serves as a "living document" for a format that may change. What follows is a recent copy, more for orientiation purposes, but those interested in the specifics should make sure that they look at the current document in the source code. ---- Copy of wfnamelist_reference.nml - 2023-11-26 ============================================= .. code-block:: bash !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! ! This is a "reference" worfklow namelist with two primary purposes ! ! 1) Serve as a definitive reference of all possible sections and their ! fields. It's important to note that since we are trying to include ! all possible options, there will be some in here that are mutually ! exclusive with respect to others. Hence, this can never be an ! example of a valid wfnamelist. ! ! 2) Serve as a source of validation for user wfnamelists - as we read in ! a user wfnamelist, we can have the option of checking that all of ! its sections and fields are present in this reference version, ! helping to reduce errors caused by typos, etc. ! ! The values assigned to many of these fields will be, to some degree, ! nonsensical, and just meant to illustrate the types of values they ! might take. However, every effort is made to make these fake values ! look realistic, conforming to expected types, etc. !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! !------------------------------------------------------------------ ! This section defines the basic control parameters of the workflow ! ! Valid components include UNGRIB, GEOGRID, METGRID, REAL, WRF and FLEXWRF. ! Defined in module ehratm.wf_config ! ! In the future I will add "meta-components" to designate particular ! groupings of valid components ! ! "workflow_list" is a list of valid components, in the order ! that we will execute them within a workflow ! ! "workflow_rootdir" is an existing user-writable dir in which an indidivual ! workflow dir will be created and maintained. This is optional, and ! will be assigned a default (likely a world writable dir) if not specified. ! Users may typically want to specify something in their own directory space ! and not use the default. ! ! "workflow_name" is the name that will used for this specific workflow. ! This is optional, and a default name will be assigned if not specified. ! In general, users will probably want to go ahead and use the default. ! This name will be used as a subdirectory name under the workflow root dir ! (regardless of whether it's user-specified or default). ! ! log_level defines the Python logging level for generating messages. ! If not defined, a default value is used. ! ! I may also add an optional "workdir_root_path" to this section !------------------------------------------------------------------ &control workflow_list = 'UNGRIB', 'GEOGRID' workflow_rootdir = '/a/location/in/my/home/dir' workflow_name = 'MyCustomWorkflowName' log_level = 'info' / !------------------------------------------------------------------ ! This section defines the timing parameters for the specified workflow. ! The times are expressed from the perspective of the Flexpart WRF run. ! In many cases, users want to run WRF for a few "spinup" hours before ! the actual Flexpart WRF startup time, in order to get more reasonable ! initial values from WRF. So, an optional wrf_spinup_hours allows us ! to indicate an earlier start time for all of the WRF components. !------------------------------------------------------------------ &time start_time = '2014012400' ! YYYYMMDDHH[mmss] string end_time = '2014012406' ! YYYYMMDDHH[mmss] string wrf_spinup_hours = 0 ! (optional) default specified in ! defaults.Defaults / !------------------------------------------------------------------ ! There may be one or more grib_input sections, numbered starting at 1 ! (Max is defined in defaults.Defaults) ! ! Current implementation assumes that we only need one grib_input section ! for GFS GRIB inputs, and two grib_input sections (one for model levels, ! one for surface) for ERA GRIB inputs. ! ! The current supported type values are gfs_ctbto, ecmwf_ml, and ! ecmwf_sfc (supported types defined in ehratm.wf_config.py). ! ! gfs_ctbto files are assumed to be in a CTBTO-like directory hierarchy ! ! YYYY/MM/DD/ ! ! Valid subtypes for 'gfs_ctbto' are '1.0', '0.5' and '0.5.fv3' ! ! The 'ecmwf_ml' and 'ecmwf_sfc' are assumed to be arranged in a "flat" ! address space ! ! ! The subtype is not used for the ecmwf_* types. ! ! subtype: (condionally optional) Some types require these, others don't ! ! hours_intvl: (required) is the hours interval to extract from the GRIB ! files located at designated path. In some cases, for example, with a ! list of hourly files, we may choose to extract from only a subset ! (e.g. 3-hourly) ! ! rootdir: (required) is a full path to a directory that contains the expected ! met files. Currently, in the case of type gfs_ctbto, we expect an ! underlying dir hierarchy of YYYY/MM/DD/. In the case of the ERA ! type, we expect the GRIB files to be located in the flat dir space ! underneath rootdir. ! ! custom_vtable_path: (optional) ! !------------------------------------------------------------------ &grib_input1 type = 'ecmwf_ml' ! Valid GRIB data types as defined in ! subtype = '' ! Each type has its own valid subtypes, ! sometimes None hours_intvl = 3 ! integer rootdir = '/scratch/ctbtosa/metdata/era' ! str custom_vtable_path = '/my/path/to/custom/vtable/Vtable.ECMWF.ml' ! str / &grib_input2 type = 'ecmwf_sfc' hours_intvl = 3 rootdir = '/scratch/ctbtosa/metdata/era' custom_vtable_path = '/home/ctbtuser/git/hratm-experimentation/packagedev/nwpservice/tests/testcase_data/ecmwf_anne_2014_eu/WPS/Vtable.ECMWF.sfc' / !------------------------------------------------------------------ ! This section defines the basic domain definition parameters ! ! The domain definition has been defined to be performed outside of the ! ehratm framework, due to its complexity. In normal usage, a properly ! constructed domain definition namelist would be created by another ! application, and this section would have a single variable, ! "domain_defn_path" that specifies the file location. ! ! Alternatively, the same parameters could be inserted into this section ! of this workflow namelist. THIS IS NOT YET IMPLEMENTED AND IS NOT A HIGH ! PRIORITY. NEVERTHELESS, I AM LEAVING THIS POSSIBILITY OPEN FOR FUTURE ! DEVELOPMENT. ! ! If the "domain_defn_path" is present in this section, then anything else ! will be ignored, and it will be assumed that all relevant domain defn ! variables are in the specified file. ! ! Even though the domain defn variables might not be defined directly in ! the workflow namelist, they are listed here a) for a single place of ! reference, and b) so that if desired, a routine that ingests the domain ! definition namelist can perform the standard reference tests "as if" the ! values were located in the workflow namelist (one can think of the domain ! definition variables being contained in the workflow namelist "indirectly," ! even if we use the domain_defn_path option) ! ! The following examples (the parameters after "domain_defn_path") ! depict a 2-nest domain ! ! The only projections supported by Flexpart WRF are lambert, polar, and ! mercator. The projection parameters will be defined differently for each. ! ! Currently, the fpwrf variables are not well-defined and really shouldn't ! even be used at this point. We need more planning and development to ! determine how we want to handle these outgrid parameters. ! They are useful, however, when using the domaincheck utility, as they ! allow the user to see where a Flexpart OUTGRID or OUTGRID_NEST might fit ! into the overall WPS domain. In this case, we use only the LL and UR ! latlon coordinates ! !------------------------------------------------------------------ &domain_defn domain_defn_path = '/my/path/to/domain/defn/namelist', parent_id = 1, 1, parent_grid_ratio = 1, 3, i_parent_start = 1, 20, j_parent_start = 1, 20, e_we = 140, 301, e_sn = 125, 256, geog_data_res = '10m', '5m', dx = 30000, dy = 30000, map_proj = 'lambert', ref_lat = 50.00, ref_lon = 5.00, truelat1 = 60.0, truelat2 = 30.0, stand_lon = 5.0, fpwrf_outgrid_dx = 0.1, 0.05, ! deprecated - use fpwrf_outgrid_dx_lon fpwrf_outgrid_dy = 0.1, 0.05, ! deprecated - use fpwrf_outgrid_dx_lat fpwrf_outgrid_ll_lat = 35.0, 41.3, fpwrf_outgrid_ll_lon = -11.7, 1.2 fpwrf_outgrid_ur_lat = -31.0, -35.0 fpwrf_outgrid_ur_lon = -165.0, -170.0, / !------------------------------------------------------------------ ! This section defines the basic geogrid parameters ! ! Currently, the only parameter, which is optional, is the number of MPI ! tasks to use for running geogrid. The default value (typically 0) would ! imply serial execution. ! ! NOTE - NEED TO ADD AND TEST A geogrid_output_path GROUP for standalone ! geogrid execution. !------------------------------------------------------------------ &geogrid num_mpi_tasks = 4 / !------------------------------------------------------------------ ! This section defines the basic metgrid parameters ! ! There are up to three different sets of ungribbed data, each with its ! own prefix, and own path (though the paths may be identical). These ! are optional, and if not used, default paths will be used. ! ! Likewise,there is an optional specification for path to the geogrid files. ! And, an optional spec for num_nests, in case this is run standalone, ! we need to know how many geogrid files to expect and how many nests of ! metgrid files to produce ! ! hours_intvl is required, specifying the number of hours expected between ! ungrib files (this is used because, for example, we may have a directory ! with hourly ungrib files, but may want to use only 3-hourly for metgrid) ! ! metgrid_output_dir is also optional. This is a staging directory, ! outside of the normal run directory. If not specified, a default ! (which may be None) will be used, depending on the workflow. ! !------------------------------------------------------------------ &metgrid ug_prefix_01 = 'ECMWF_ML' ug_path_01 = '/path/to/ECMWF_ML:*' ug_prefix_02 = 'ECMWF_SFC' ug_path_02 = '/path/to/ECMWF_SFC:*' ug_prefix_03 = 'PRES' ug_path_03 = '/path/to/PRES:*' geogrid_path = '/path/to/geo_em*' num_nests = 2 hours_intvl = 3 num_mpi_tasks = 4 metgrid_output_dir = '/path/to/metgrid/output/files' / !------------------------------------------------------------------ ! This section defines the basic real parameters ! ! There is an optional specification for path to the metgrid files. ! And, an optional spec for num_nests, in case this is run standalone, ! we need to know how many metgrid files to expect and how many nests of ! wrfinput files to produce ! ! hours_intvl is required, specifying the number of hours expected between ! metgrid files (this is used because, for example, we may have a directory ! with hourly metgrid files, but may want to use only 3-hourly for real) ! ! num_mpi_tasks is optional. If not specified, will take on a default value ! (defined in defaults.py, typically 0) ! ! real_output_dir is also optional. This is a staging directory, ! outside of the normal run directory. If not specified, a default ! (which may be None) will be used, depending on the workflow. ! ! Finally anne_bypass_namelist_input is a path to a fully-correct ! namelist.input for real. For general workflow operations, namelist.input ! would normally be created within this software stack, but this ! variable is available for experimental and testing purposes. If ! defined, items like hours_intvl and num_nests will still be ingested ! and possibly used, so it will be up to the user of this bypass namelist.input ! to ensure that everything is consistent. ! ! !------------------------------------------------------------------ &real metgrid_path = '/path/to/met_em*' num_nests = 2 hours_intvl = 3 num_mpi_tasks = 4 real_output_dir = '/path/to/real/output/files' anne_bypass_namelist_input = '/path/to/correct/namelist.input' / !------------------------------------------------------------------ ! This section defines the basic wrf parameters ! ! There is an optional specification for path to the real files. ! And, an optional spec for num_nests, in case this is run standalone, ! we need to know how many real files to expect and how many nests of ! wrfout files to produce ! ! hours_intvl is required, specifying the number of hours expected between ! met files (this is used because, for example, we may have a directory ! with hourly metgrid files, but may want to use only 3-hourly for real). ! I'm not sure this is absolutely required for wrf at this point, but we ! do need to note that this information is embedded in the NetCDF real files ! and maybe it makes sense to keep this required, just to help us keep from ! getting messed up. ! ! num_mpi_tasks is optional. If not specified, will take on a default value ! (defined in defaults.py, typically 0) ! ! wrf_output_dir is also optional. This is a staging directory, ! outside of the normal run directory. If not specified, a default ! (which may be None) will be used, depending on the workflow. ! ! Finally anne_bypass_namelist_input is a path to a fully-correct ! namelist.input for wrf. For general workflow operations, namelist.input ! would normally be created within this software stack, but this ! variable is available for experimental and testing purposes. If ! defined, items like hours_intvl and num_nests will still be ingested ! and possibly used, so it will be up to the user of this bypass namelist.input ! to ensure that everything is consistent. ! !------------------------------------------------------------------ &wrf real_path = '/path/to/real/outputs' num_nests = 2 hours_intvl = 3 num_mpi_tasks = 4 wrf_output_dir = '/path/to/wrf/output/files' anne_bypass_namelist_input = '/path/to/correct/namelist.input' / ------------------------------------------------------------------ ! This section defines the basic flexwrf parameters ! ! There is an optional specification for path to the wrfout files. ! And, a required spec for wrfout_num_nests. We need to know how many ! wrfout files to expect and how many input nests to look for. ! ! wrfout_hours_intvl is required, specifying the number of hours expected between ! met files (this is used because, for example, we may have a directory ! with hourly wrfout files, but may want to use only 3-hourly for flexwrf). ! I'm not sure this is absolutely required for wrf at this point, but we ! do need to note that this information is embedded in the NetCDF wrfout files ! and maybe it makes sense to keep this required, just to help us keep from ! getting messed up. ! ! num_mpi_tasks is optional. If not specified, will take on a default value ! (defined in defaults.py, typically 0) ! ! num_omp_threads is optional. If not specified, will take on a default value ! (defined in defaults.py, typically 0) ! ! flexwrf_output_dir is also optional. This is a staging directory, ! outside of the normal run directory. If not specified, a default ! (which may be None) will be used, depending on the workflow. ! ! Finally bypass_user_input is a path to a fully-correct ! flexp_input.txt for flexwrf. For general workflow operations, ! flexp_input.txt would normally be created within this software stack, ! but this variable is available for experimental and testing purposes. ! It is currently the only option supported right now, and the user will ! need to ensure that that input file parameters are consistent with any ! parameters defined in the wfnamelist. In the long run, this bypass ! input file should NOT be used, but is here for development purposes ! right now. ! !------------------------------------------------------------------ &flexwrf wrfout_path = '/path/to/wrf/outputs' wrfout_num_nests = 2 wrfout_hours_intvl = 3 num_mpi_tasks = 4 num_omp_threads = 64 flexwrf_output_dir = '/path/to/flexwrf/output/files' bypass_user_input = '/path/to/correct/flexp_input.txt' / ------------------------------------------------------------------ ! This section defines the basic srm parameters ! ! Current (30 May 2023) assumptions are that ! ! - The standard ATM pipeline flexpart2ctbt is being used ! - That only the primary FlexWRF OUTGRID nest is being processed ! - That this group is not required in a wfnamelist, even if we ! - have chosen SRM as one of the workflow components. The options ! here are not always needed, and some have defaults ! ! levels_list is optional, and is the list of OUTGRID levels that we want ! to process. If not specified, we'll revert to a default value in code ! that uses this - typically level 1, but this is not guaranteed. Indexing ! is from Level 1 to n ! ! srm_exec_path - full path to the flexpart2ctbt executable. If not specified, ! default values are assumed ! ! flexwrfout_path - optional path to location of flexwrf binary output, ! including the header and dates files. At this point, nests are not ! explicitly handled. This option would be used in SRM standalone mode ! ! srm_output_dir - full path to where srm files should be staged. This is ! optional. ! ! multiplier - Factor by which to multiply the concentrations. If not ! specified, default value is used ! ! compress - Whether to compress the SRM files nor not. 0: no compression ! 1 : compress. If not specified, default values are used ! ! This may be modified at some future date to support processing of OUTGRID ! nests ! !------------------------------------------------------------------ &srm levels_list = 1, 2, 4 srm_exec_path = '/path/to/flexpart2ctbt/executable' flexwrfout_path = '/path/to/flexwrf/outputs' srm_output_dir = '/path/to/srm/output/files' multiplier = 1.0, compress = 0 / .. toctree::