From 2b371e371b984930dd72dba9839bdcb4fdee2911 Mon Sep 17 00:00:00 2001 From: Julie Schramm Date: Thu, 16 Jan 2020 11:02:53 -0700 Subject: [PATCH] - Change project name in conf.py to "UFS Weather Model Users Guide" - Add chapter InputsOutputs.rst - Add chapter SDFandNamelistExamplePractices.rst Both html and latex builds succeed. Table format looks good in pdf file. --- doc/UsersGuide/source/InputsOutputs.rst | 730 +++++++++++++++++- .../source/SDFandNamelistExamplePractices.rst | 243 +++++- doc/UsersGuide/source/conf.py | 2 +- 3 files changed, 965 insertions(+), 10 deletions(-) diff --git a/doc/UsersGuide/source/InputsOutputs.rst b/doc/UsersGuide/source/InputsOutputs.rst index 7af8732389..dea485a64e 100644 --- a/doc/UsersGuide/source/InputsOutputs.rst +++ b/doc/UsersGuide/source/InputsOutputs.rst @@ -4,14 +4,732 @@ Inputs and Outputs ************************* -* List of the inputs and outputs of the executable, including SDF, namelists, diag/field, tables, fix files, ICs/BCs, stdout +This chapter describes the input and output files needed for executing the model in the various supported configurations. -* Detailed description of +============= +Input files +============= -* SDF +There are three types of files needed to execute a run: static datasets (*fix* files containing climatological +information), files that depend on grid resolution and initial conditions, and model configuration files (such as namelists). -* Namelists (can have links to namelist description elsewhere) +------------------------------------ +Static datasets (i.e., *fix files*) +------------------------------------ +The static input files are listed and described in :numref:`Table %s `. -* Field table +.. _FixFiles: + +.. list-table:: *Fix files containing climatological information* + :widths: 40 50 + :header-rows: 1 + + * - Filename + - Description + * - aerosol.dat + - External aerosols data file + * - CFSR.SEAICE.1982.2012.monthly.clim.grb + - CFS reanalysis of monthly sea ice climatology + * - co2historicaldata_YYYY.txt + - Monthly CO2 in PPMV data for year YYYY + * - global_albedo4.1x1.grb + - Four albedo fields for seasonal mean climatology: 2 for strong zenith angle dependent (visible and near IR) + and 2 for weak zenith angle dependent + * - global_glacier.2x2.grb + - Glacier points, permanent/extreme features + * - global_h2oprdlos.f77 + - Coefficients for the parameterization of photochemical production and loss of water (H2O) + * - global_maxice.2x2.grb + - Maximum ice extent, permanent/extreme features + * - global_mxsnoalb.uariz.t126.384.190.rg.grb + - Climatological maximum snow albedo + * - global_o3prdlos.f77 + - Monthly mean ozone coefficients + * - global_shdmax.0.144x0.144.grb + - Climatological maximum vegetation cover + * - global_shdmin.0.144x0.144.grb + - Climatological minimum vegetation cover + * - global_slope.1x1.grb + - Climatological slope type + * - global_snoclim.1.875.grb + - Climatological snow depth + * - global_snowfree_albedo.bosu.t126.384.190.rg.grb + - Climatological snowfree albedo + * - global_soilmgldas.t126.384.190.grb + - Climatological soil moisture + * - global_soiltype.statsgo.t126.384.190.rg.grb + - Soil type from the STATSGO dataset + * - global_tg3clim.2.6x1.5.grb + - Climatological deep soil temperature + * - global_vegfrac.0.144.decpercent.grb + - Climatological vegetation fraction + * - global_vegtype.igbp.t126.384.190.rg.grb + - Climatological vegetation type + * - global_zorclim.1x1.grb + - Climatological surface roughness + * - RTGSST.1982.2012.monthly.clim.grb + - Monthly, climatological, real-time global sea surface temperature + * - seaice_newland.grb + - High resolution land mask + * - sfc_emissivity_idx.txt + - External surface emissivity data table + * - solarconstant_noaa_an.txt + - External solar constant data table + +--------------------------------------------- +Grid description and initial condition files +--------------------------------------------- +The input files containing grid information and the initial conditions are listed and described in :numref:`Table %s `. + +.. _GridICFiles: + +.. list-table:: *Input files containing grid information and initial conditions* + :widths: 35 50 15 + :header-rows: 1 + + * - Filename + - Description + - Date-dependent + * - C96_grid.tile[1-6].nc + - C96 grid information for tiles 1-6 + - + * - gfs_ctrl.nc + - NCEP NGGPS tracers, ak, and bk + - ✔ + * - gfs_data.tile[1-6].nc + - Initial condition fields (ps, u, v, u, z, t, q, O3). May include spfo3, spfo, spf02 if multiple gases are used + - ✔ + * - oro_data.tile[1-6].nc + - Model terrain (topographic/orographic information) for grid tiles 1-6 + - + * - sfc_ctrl.nc + - Control parameters for surface input: forecast hour, date, number of soil levels + - + * - sfc_data.tile[1-6].nc + - Surface properties for grid tiles 1-6 + - ✔ + +------------------------------------ +Model configuration files +------------------------------------ +The configuration files used by the UFS Weather Model are listed here and described below: + +- *diag_table* +- *field_table* +- *input.nml* +- *model_configure* +- *nems.configure* +- *suite_[suite_name].xml* (used only at build time) + + +*diag_table* file +------------------------------------ +There are three sections in file *diag_table*: Header (Global), File, and Field. These are described below. + +**Header Description** + +The Header section must reside in the first two lines of the *diag_table* file and contain the title and date +of the experiment (see example below). The title must be a Fortran character string. The base date is the +reference time used for the time units, and must be greater than or equal to the model start time. The base date +consists of six space-separated integers in the following format: ``year month day hour minute second``. Here is an example: + +.. code-block:: console + + 20161003.00Z.C96.64bit.non-mono + 2016 10 03 00 0 0 + +**File Description** + +The File Description lines are used to specify the name of the file(s) to which the output will be written. They +contain one or more sets of six required and five optional fields (optional fields are denoted by square brackets +``[ ]``). The lines containing File Descriptions can be intermixed with the lines containing Field Descriptions as +long as files are defined before fields that are to be written them. File entries have the following format: + +.. code-block:: console + + "file_name", output_freq, "output_freq_units", file_format, "time_axis_units", "time_axis_name" + [, new_file_freq, "new_file_freq_units"[, "start_time"[, file_duration, "file_duration_units"]]] + +These file line entries are described in :numref:`Table %s `. + +.. _FileDescription: + +.. list-table:: *Description of the six required and five optional fields used to define output file sampling rates.* + :widths: 20 25 55 + :header-rows: 1 + + * - File Entry + - Variable Type + - Description + * - file_name + - CHARACTER(len=128) + - Output file name without the trailing ".nc" + * - output_freq + - INTEGER + - | The period between records in the file_name: + | > 0 output frequency in output_freq_units. + | = 0 output frequency every time step (output_freq_units is ignored) + | =-1 output at end of run only (output_freq_units is ignored) + * - output_freq_units + - CHARACTER(len=10) + - The units in which output_freq is given. Valid values are “years”, “months”, “days”, “minutes”, “hours”, or “seconds”. + * - file_format + - INTEGER + - Currently only the netCDF file format is supported. = 1 netCDF + * - time_axis_units + - CHARACTER(len=10) + - The units to use for the time-axis in the file. Valid values are “years”, “months”, “days”, “minutes”, “hours”, + or “seconds”. + * - time_axis_name + - CHARACTER(len=128) + - Axis name for the output file time axis. The character string must contain the string 'time'. + (mixed upper and lowercase allowed.) + * - new_file_freq + - INTEGER, OPTIONAL + - Frequency for closing the existing file, and creating a new file in new_file_freq_units. + * - new_file_freq_units + - CHARACTER(len=10), OPTIONAL + - Time units for creating a new file: either years, months, days, minutes, hours, or seconds. + NOTE: If the new_file_freq field is present, then this field must also be present. + * - start_time + - CHARACTER(len=25), OPTIONAL + - Time to start the file for the first time. The format of this string is the same as the global date. + NOTE: The new_file_freq and the new_file_freq_units fields must be present to use this field. + * - file_duration + - INTEGER, OPTIONAL + - How long file should receive data after start time in file_duration_units. This optional field can only be + used if the start_time field is present. If this field is absent, then the file duration will be equal to the + frequency for creating new files. NOTE: The file_duration_units field must also be present if this field is present. + * - file_duration_units + - CHARACTER(len=10), OPTIONAL + - File duration units. Can be either years, months, days, minutes, hours, or seconds. NOTE: If the file_duration field + is present, then this field must also be present. + +**Field Description** + +The field section of the diag_table specifies the fields to be output at run time. Only fields registered +with ``register_diag_field()``, which is an API in the FMS ``diag_manager`` routine, can be used in the *diag_table*. + +Registration of diagnostic fields is done using the following syntax + +.. code-block:: console + + diag_id = register_diag_field(module_name, diag_name, axes, ...) + +in file ``FV3/atmos_cubed_sphere/tools/fv_diagnostics.F90``. As an example, the sea level pressure is registered as: + +.. code-block:: console + + id_slp = register_diag_field (trim(field), 'slp', axes(1:2), & Time, 'sea-level pressure', 'mb', missing_value=missing_value, range=slprange ) + +All data written out by ``diag_manager`` is controlled via the *diag_table*. A line in the field section of the +*diag_table* file contains eight variables with the following format: + +.. code-block:: console + + "module_name", "field_name", "output_name", "file_name", "time_sampling", "reduction_method", "regional_section", packing + +These field section entries are described in :numref:`Table %s `. + +.. _FieldDescription: + +.. list-table:: *Description of the eight variables used to define the fields written to the output files.* + :widths: 16 24 55 + :header-rows: 1 + + * - Field Entry + - Variable Type + - Description + * - module_name + - CHARACTER(len=128) + - Module that contains the field_name variable. (e.g. dynamic, gfs_phys, gfs_sfc) + * - field_name + - CHARACTER(len=128) + - The name of the variable as registered in the model. + * - output_name + - CHARACTER(len=128) + - Name of the field as written in file_name. + * - file_name + - CHARACTER(len=128) + - Name of the file where the field is to be written. + * - time_sampling + - CHARACTER(len=50) + - Currently not used. Please use the string "all". + * - reduction_method + - CHARACTER(len=50) + - The data reduction method to perform prior to writing data to disk. Current supported option is .false.. See ``FMS/diag_manager/diag_table.F90`` for more information. + * - regional_section + - CHARACTER(len=50) + - Bounds of the regional section to capture. Current supported option is “none”. See ``FMS/diag_manager/diag_table.F90`` for more information. + * - packing + - INTEGER + - Fortran number KIND of the data written. Valid values: 1=double precision, 2=float, 4=packed 16-bit integers, 8=packed 1-byte (not tested). + +Comments can be added to the diag_table using the hash symbol (``#``). + +A brief example of the diag_table is shown below. ``“...”`` denote where lines have been removed. + +.. code-block:: console + + 20161003.00Z.C96.64bit.non-mono + 2016 10 03 00 0 0 + + "grid_spec", -1, "months", 1, "days", "time" + "atmos_4xdaily", 6, "hours", 1, "days", "time" + "atmos_static" -1, "hours", 1, "hours", "time" + "fv3_history", 0, "hours", 1, "hours", "time" + "fv3_history2d", 0, "hours", 1, "hours", "time" + + # + #======================= + # ATMOSPHERE DIAGNOSTICS + #======================= + ### + # grid_spec + ### + "dynamics", "grid_lon", "grid_lon", "grid_spec", "all", .false., "none", 2, + "dynamics", "grid_lat", "grid_lat", "grid_spec", "all", .false., "none", 2, + "dynamics", "grid_lont", "grid_lont", "grid_spec", "all", .false., "none", 2, + "dynamics", "grid_latt", "grid_latt", "grid_spec", "all", .false., "none", 2, + "dynamics", "area", "area", "grid_spec", "all", .false., "none", 2, + ### + # 4x daily output + ### + "dynamics", "slp", "slp", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "vort850", "vort850", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "vort200", "vort200", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "us", "us", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u1000", "u1000", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u850", "u850", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u700", "u700", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u500", "u500", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u200", "u200", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u100", "u100", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u50", "u50", "atmos_4xdaily", "all", .false., "none", 2 + "dynamics", "u10", "u10", "atmos_4xdaily", "all", .false., "none", 2 + + ... + ### + # gfs static data + ### + "dynamics", "pk", "pk", "atmos_static", "all", .false., "none", 2 + "dynamics", "bk", "bk", "atmos_static", "all", .false., "none", 2 + "dynamics", "hyam", "hyam", "atmos_static", "all", .false., "none", 2 + "dynamics", "hybm", "hybm", "atmos_static", "all", .false., "none", 2 + "dynamics", "zsurf", "zsurf", "atmos_static", "all", .false., "none", 2 + ### + # FV3 variables needed for NGGPS evaluation + ### + "gfs_dyn", "ucomp", "ugrd", "fv3_history", "all", .false., "none", 2 + "gfs_dyn", "vcomp", "vgrd", "fv3_history", "all", .false., "none", 2 + "gfs_dyn", "sphum", "spfh", "fv3_history", "all", .false., "none", 2 + "gfs_dyn", "temp", "tmp", "fv3_history", "all", .false., "none", 2 + ... + "gfs_phys", "ALBDO_ave", "albdo_ave", "fv3_history2d", "all", .false., "none", 2 + "gfs_phys", "cnvprcp_ave", "cprat_ave", "fv3_history2d", "all", .false., "none", 2 + "gfs_phys", "cnvprcpb_ave", "cpratb_ave","fv3_history2d", "all", .false., "none", 2 + "gfs_phys", "totprcp_ave", "prate_ave", "fv3_history2d", "all", .false., "none", 2 + ... + "gfs_sfc", "crain", "crain", "fv3_history2d", "all", .false., "none", 2 + "gfs_sfc", "tprcp", "tprcp", "fv3_history2d", "all", .false., "none", 2 + "gfs_sfc", "hgtsfc", "orog", "fv3_history2d", "all", .false., "none", 2 + "gfs_sfc", "weasd", "weasd", "fv3_history2d", "all", .false., "none", 2 + "gfs_sfc", "f10m", "f10m", "fv3_history2d", "all", .false., "none", 2 + ... + +More information on the content of this file can be found in ``FMS/diag_manager/diag_table.F90``. + +.. note:: None of the lines in the *diag_table* can span multiple lines. + +*field_table* file +------------------------------------ +The FMS field and tracer managers are used to manage tracers and specify tracer options. All tracers +advected by the model must be registered in an ASCII table called *field_table*. The field table consists +of entries in the following format: + +The first line of an entry should consist of three quoted strings: + - The first quoted string will tell the field manager what type of field it is. The string ``“TRACER”`` is used to + declare a field entry. + - The second quoted string will tell the field manager which model the field is being applied to. The supported + type at present is ``“atmos_mod”`` for the atmosphere model. + - The third quoted string should be a unique tracer name that the model will recognize. + +The second and following lines are called ``methods``. These lines can consist of two or three quoted strings. +The first string will be an identifier that the querying module will ask for. The second string will be a name +that the querying module can use to set up values for the module. The third string, if present, can supply +parameters to the calling module that can be parsed and used to further modify values. + +An entry is ended with a forward slash (/) as the final character in a row. Comments can be inserted in the field table by having a hash symbol (#) as the first character in the line. + +Below is an example of a field table entry for the tracer called ``“sphum”``: + +.. code-block:: console + + # added by FRE: sphum must be present in atmos + # specific humidity for moist runs + "TRACER", "atmos_mod", "sphum" + "longname", "specific humidity" + "units", "kg/kg" + "profile_type", "fixed", "surface_value=3.e-6" / + +In this case, methods applied to this tracer include setting the long name to "specific humidity", the units +to "kg/kg". Finally a field named "profile_type" will be given a child field called "fixed", and that field +will be given a field called "surface_value" with a real value of 3.E-6. The “profile_type” options are listed +in :numref:`Table %s `. If the profile type is “fixed” then the tracer field values are set equal +to the surface value. If the profile type is “profile” then the top/bottom of model and surface values are read +and an exponential profile is calculated, with the profile being dependent on the number of levels in the component model. + +.. _TracerTable: + +.. list-table:: *Tracer profile setup from FMS/tracer_manager/tracer_manager.F90.* + :widths: 20 25 55 + :header-rows: 1 + + * - Method Type + - Method Name + - Method Control + * - profile_type + - fixed + - surface_value = X + * - profile_type + - profile + - surface_value = X, top_value = Y (atmosphere) + +For the case of + +.. code-block:: console + + "profile_type","profile","surface_value = 1e-12, top_value = 1e-15" + +in a 15 layer model this would return values of surf_value = 1e-12 and multiplier = 0.6309573, i.e 1e-15 = 1e-12*(0.6309573^15). + +A ``method`` is a way to allow a component module to alter the parameters it needs for various tracers. In essence, +this is a way to modify a default value. A namelist can supply default parameters for all tracers and a method, as +supplied through the field table, will allow the user to modify the default parameters on an individual tracer basis. +The lines in this file can be coded quite flexibly. Due to this flexibility, a number of restrictions are required. +See ``FMS/field_manager/field_manager.F90`` for more information. + +*input.nml* file +------------------------------------ + +The atmosphere model reads many parameters from a Fortran namelist file, named *input.nml*. This file contains +several Fortran namelist records, some of which are always required, others of which are only used when selected +physics options are chosen. + +The following link describes the various physics-related namelist records: +https://dtcenter.org/GMTB/v3.0/sci_doc/GFSsuite_nml.html + +The following link describes the stochastic physics namelist records +https://stochastic-physics.readthedocs.io/en/ufs_public_release/namelist_options.html + +The following link describes some of the other namelist records (dynamics, grid, etc): +https://www.gfdl.noaa.gov/wp-content/uploads/2017/09/fv3_namelist_Feb2017.pdf + +The namelist section relating to the FMS diagnostic manager is described in the last section of this chapter. + +*model_configure* file +------------------------------------ + +This file contains settings and configurations for the NUOPC/ESMF main component, including the simulation +start time, the processor layout/configuration, and the I/O selections. :numref:`Table %s ` +shows the following parameters that can be set in *model_configure* at run-time. + +.. _ModelConfigParams: + +.. list-table:: *Parameters that can be set in model_configure at run-time.* + :widths: 20 30 15 20 + :header-rows: 1 + + * - Parameter + - Meaning + - Type + - Default Value + * - print_esmf + - flag for ESMF PET files + - logical + - .true. + * - PE_MEMBER01 + - total number of tasks for ensemble number 1 + - integer + - 150 (for c96 with quilt) + * - start_year + - start year of model integration + - integer + - 2019 + * - start_month + - start month of model integration + - integer + - 09 + * - start_day + - start day of model integration + - integer + - 12 + * - start_hour + - start hour of model integration + - integer + - 00 + * - start_minute + - start minute of model integration + - integer + - 0 + * - start_second + - start second of model integration + - integer + - 0 + * - fhrot + - forecast hour at restart for nems/earth grid component clock in coupled model + - integer + - 0 + * - nhours_fcst + - total forecast length + - integer + - 48 + * - dt_atmos + - atmosphere time step in second + - integer + - 1800 (for C96) + * - output_1st_tstep_rst + - output first time step history file after restart + - logical + - .false. + * - memuse_verbose + - flag for printing out memory usage + - logical + - .false. + * - atmos_nthreads + - number of threads for atmosphere + - integer + - 4 + * - use_hyper_thread + - flag to use hyper threads + - logical + - .false. + * - ncores_per_node + - number of cores per node + - integer + - 24 + * - restart_interval + - frequency to output restart file + - integer + - 0 (write restart file at the end of integration) + * - quilting + - flag to turn on quilt + - logical + - .true. + * - write_groups + - total number of groups + - integer + - 2 + * - write_tasks_per_group + - total number of write tasks in each write group + - integer + - 6 + * - output_history + - flag to output history files + - logical + - .true. + * - num_files + - number of output files + - integer + - 2 + * - filename_base + - file name base for the output files + - character(255) + - 'atm' 'sfc' + * - output_grid + - output grid + - character(255) + - gaussian_grid + * - output_file + - output file format + - character(255) + - nemsio + * - imo + - i-dimension for output grid + - integer + - 384 + * - jmo + - j-dimension for output grid + - integer + - 190 + * - nfhout + - history file output frequency + - integer + - 3 + * - nfhmax_hf + - forecast length of high history file + - integer + - 0 (0:no high frequency output) + * - nfhout_hf + - high history file output frequency + - integer + - 1 + * - nsout + - output frequency of number of time step + - integer + - -1 (negative: turn off the option, 1: output history file at every time step) + +:numref:`Table %s ` shows the following parameters in *model_configure* that +are not usually changed. + +.. _ModelConfigParamsNotChanged: + +.. list-table:: *Parameters that are not usually changed in model_configure at run-time.* + :widths: 20 30 15 20 + :header-rows: 1 + + * - Parameter + - Meaning + - Type + - Default Value + * - total_member + - total number of ensemble member + - integer + - 1 + * - RUN_CONTINUE + - Flag for more than one NEMS run + - logical + - .false. + * - ENS_SPS + - flag for the ensemble stochastic coupling flag + - logical + - .false. + * - calendar + - type of calendar year + - character(*) + - 'julian' + * - cpl + - flag for coupling with MOM6/CICE5 + - logical + - .false. + * - write_dopost + - flag to do post on write grid component + - logical + - .false. + * - ideflate + - lossless compression level + - integer + - 1 (0:no compression, range 1-9) + * - nbits + - lossy compression level + - integer + - 14 (0: lossless, range 1-32) + * - write_nemsioflip + - flag to flip the vertical level for nemsio file + - logical + - .true. + * - write_fsyncflag + - flag to check if a file is synced to disk + - logical + - .true. + * - iau_offset + - IAU offset lengdth + - integer + - 0 + +*nems.configure* file +------------------------------------ +This file contains information about the various NEMS components and their run sequence. In the current release, +this is an atmosphere-only model, so this file is simple and does not need to be changed. A sample of the file contents is below: + +.. code-block:: console + + EARTH_component_list: ATM + ATM_model: fv3 + runSeq:: + ATM + :: + +*The SDF (Suite Definition File) file* +--------------------------------------- +There are two SDFs currently supported: *suite_FV3_GFS_v15p2.xml* and *suite_FV3_GFS_v16beta.xml*. + +============= +Output files +============= + +The following files are output when running *fv3.exe* in the default configuration (six files of each kind, +corresponding to the six tiles of the model grid): + +- *atmos_4xdaily.tile[1-6].nc* +- *atmos_static.tile[1-6].nc* +- *phyfHHH.tile[1-6].nc* +- *dynfHHH.tile[1-6].nc* +- *grid_spec.tile[1-6].nc* + +The specifications of the output files (type, projection, etc) may be overridden in the *model_configure* input file. + +Standard output files are *logf???*, and out and err as specified by the job submission. ESMF may also produce log +files (controlled by variable print_esmf in the *model_configure* file), called *PET???.ESMF_LogFile*. + +============================================================== +Additional Information about the FMS Diagnostic Manager +============================================================== + +The UFS Weather Model output is managed through the FMS (Flexible Modeling System) diagnostic manager (``FMS/diag_manager``) +and is configured using the *diag_table* file. Data can be written at any number of sampling and/or averaging intervals +specified at run-time. More information about the FMS diagnostic manager can be found at: +https://data1.gfdl.noaa.gov/summer-school/Lectures/July16/03_Seth1_DiagManager.pdf + +------------------------------ +Diagnostic Manager namelist +------------------------------ +The ``diag_manager_nml`` namelist contains values to control the behavior of the diagnostic manager. Some +of the more common namelist options are described in :numref:`Table %s `. See +``FMS/diag_manager/diag_manager.F90`` for the complete list. + +.. _DiagManager: + +.. list-table:: *Namelist variables used to control the behavior of the diagnostic manager.* + :widths: 15 10 30 10 + :header-rows: 1 + + * - Namelist variable + - Type + - Description + - Default value + * - max_files + - INTEGER + - Maximum number of files allowed in diag_table + - 31 + * - max_output_fields + - INTEGER + - Maximum number of output fields allowed in diag_table + - 300 + * - max_input_fields + - INTEGER + - Maximum number of registered fields allowed + - 300 + * - prepend_date + - LOGICAL + - Prepend the file start date to the output file. .TRUE. is only supported if the diag_manager_init routine is called with the optional time_init parameter. + - .TRUE. + * - do_diag_field_log + - LOGICAL + - Write out all registered fields to a log file + - .FALSE. + * - use_cmor + - LOGICAL + - Override the missing_value to the CMOR value of -1.0e20 + - .FALSE. + * - issue_oor_warnings + - LOGICAL + - Issue a warning if a value passed to diag_manager is outside the given range + - .TRUE. + * - oor_warnings_fatal + - LOGICAL + - Treat out-of-range errors as FATAL + - .FALSE. + * - debug_diag_manager + - LOGICAL + - Check if the diag table is set up correctly + - .FALSE. + +This release of the UFS Weather Model uses the following namelist: + +.. code-block:: console + + &diag_manager_nml + prepend_date = .false. + / -* Diag table diff --git a/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst b/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst index 08855cd52a..902e14b991 100644 --- a/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst +++ b/doc/UsersGuide/source/SDFandNamelistExamplePractices.rst @@ -1,10 +1,247 @@ .. _SDFandNamelistExamplePractices: ******************************************** -SDF and Namelist Best Practices and Examples +SDF and Namelist Samples and Best Practices ******************************************** -* GFS v15 configuration for four supported resolutions +The public release of the medium-range weather app includes two supported physics suites: +GFSv15p2 and GFSv16beta. You will find the Suite Definition Files (SDFs) for these suites +in -* GFS v16 beta configuration for four supported resolutions +https://github.com/NOAA-EMC/fv3atm/tree/ufs_public_release/ccpp/suites + +(no other SDFs are available with this release). You will find the namelists for the C96 configuration here: + +https://github.com/ufs-community/ufs-weather-model/blob/ufs_public_release/parm/ccpp_v15p2_c96.nml.IN + +and + +https://github.com/ufs-community/ufs-weather-model/blob/ufs_public_release/parm/ccpp_v16beta_c96.nml.IN + +The two CCPP suites for the medium-range weather app release are supported in four grid resolutions: +C96, C192, C384, and C768, with 64 vertical levels. + +An in depth description of the namelist settings, SDFs, and parameterizations used in the GFSv15p2 +and GFSv16beta suites can be found in the CCPP Scientific Documentation (TODO add link). Note both suites do not +use stochastic physics by default, but the stochastic physics can be activated following the +instructions described here (TODO add link). + +Both the SDF and the *input.nml* contain information about how to specify the physics suite. +Some of this information is redundant, and the user must make sure they are compatible. The +safest practice is to use the SDF and namelist provided for each suite, since those are +supported configurations. + +Changes to the SDF must be accompanied by corresponding changes to the namelist. While there +is not a one-to-one correspondence between the namelist and the SDF, :numref:`Table %s ` +shows some variables in the namelist that must match the SDF. + +.. _PBLVarOptions: + +.. list-table:: *Variables related to PBL options* + :widths: 15 30 10 10 20 30 + :header-rows: 1 + + * - Namelist option + - Meaning + - Possible Values + - Default + - Used with CCPP scheme + - Recommentation + * - + - **PBL-related variables** + - + - + - + - + * - do_myjpbl + - Flag to activate the MYJ PBL scheme + - T + - F + - mypbl_wrapper + - Set to F for GFSv15p2 and GFSv16beta + * - do_myjsfc + - Flag to activate the MYJ PBL surface layer scheme + - T, F + - F + - myjsfc_wrapper + - Set to F for GFSv15p2 and GFSv16beta + * - do_mynnedmf + - Flag to activate the MYNN-EDMF scheme + - T, F + - F + - mynnedmf_wrapper + - Set to F for GFSv15p2 and GFSv16beta + * - do_ysu + - Flag to activate the YSU PBL scheme + - T, F + - F + - ysudif + - Set to F for GFSv15p2 and GFSv16beta + * - hybedmf + - Flag to activate the K-based PBL scheme + - T, F + - F + - hedmf + - Set to T for GFSv15p2 and F for GFSv16beta + * - isatedmf + - Flag for version of scale-aware TKE-based EDMF scheme + - 0, 1 + - 0 + - 0=satmedmfvdif, 1=satmedmfvdifq + - Set to 0 for GFSv15p2 and 1 for GFSv16beta + * - ism + - Flag to choose a land surface model to use + - 0, 1, 2 + - 1 + - 1=lsm_noah, 2=lsm_ruc + - Set to 1 for GFSv15p2 and GFSv16beta + * - satedmf + - Flag to activate the scale-aware TKE-based EDMF scheme + - T, F + - F + - satmedmfvdif or satmedmfvdifq + - Set to T for GFSv15p2 and GFSv16beta + * - shinhong + - Flag to activate the Shin-Hong PBL parameterization + - T, F + - F + - shinhongdif + - Set to F for GFSv15p2 and GFSv16beta + * - + - **Convection-releated flags** + - + - + - + - + * - cscnv + - Flag to activate the Chikira-Sugiyama deep convection scheme + - T, F + - F + - cs_conv + - Set to F for GFSv15p2 and GFSv16beta + * - do_aw + - Flag to activate the Arakawa-Wu extension to the Chikira-Sugiyama deep convection scheme + - T, F + - F + - cs_conv_aw_adj + - Set to F for GFSv15p2 and GFSv16beta + * - imfdeepcnv + - Flag to choose a mass flux deep convective scheme + - -1, 2, 3, 4 + - -1 + - -1=no deep convection*, 2=samfshalcnv, 3=cu_gf_driver, 4=cu_ntiedtke + - Set to 2 for GFSv15p2 and GFSv16beta + * - imfshalcvn + - Flag to choose a mass flux shallow convective scheme + - -1, 2, 3, 4 + - -1 + - -1=no deep convection*, 2=samfshalcnv, 3=cu_gf_driver, 4=cu_ntiedtke + - Set to 2 for GFSv15p2 and GFSv16beta + +\*Even when imfdeepcvn=-1, the Chikira-Sugiyama deep convection scheme may be specified using cscnv=T. + +Other miscellaneous changes to the SDF that must be accompanied by corresponding changes in +the namelist are listed in :numref:`Table %s `. + +.. _MiscVarOptions: + +.. list-table:: *Miscellaneous namelist variables and their relation to the SDF* + :widths: 15 30 10 10 20 30 + :header-rows: 1 + + * - Namelist option + - Meaning + - Possible Values + - Default + - Used with CCPP scheme + - Recommentation + * - + - **Miscellaneous variables** + - + - + - + - + * - do_myjsfc + - Flag to activate the MYJ PBL surface scheme + - T, F + - F + - mynnsfc_wrapper + - Set to F for GFSv15p2 and GFSv16beta + * - do_shoc + - Flag to activate the Simplified Higher-Order Closure (SHOC) parameterization + - T, F + - F + - shoc + - Set to F for GFSv15p2 and GFSv16beta + * - do_ugwp** + - Flag to activate the unified Gravity Wave Physics parameterization + - T, F + - F + - cires_ugwp + - Set to F for GFSv15p2 and GFSv16beta + * - imp_physics + - Flag to choose a microphysics scheme + - 8, 10, 11 + - 99 + - 8=mp_thompson, 10=m_micro, 11=gfdl_could_microphys + - Set to 11 for GFSv15p2 and GFSv16beta + * - lsm + - Flag to choose a land surface model to use + - 0, 1, 2 + - 1 + - 1=lsm_noah, 2=lsm_ruc + - Set to 1 for GFSv15p2 and GFSv16beta + * - lsoil + - Number of soil layers + - 4, 9 + - 4 + - 4 for lsm_noah, 9 for lsm_ruc + - Set to 4 for GFSv15p2 and GFSv16beta + * - h2o_phys + - Flag for stratosphere h2o scheme + - T, F + - + - h2ophys + - Set to T for GFSv15p2 and GFSv16beta + * - oz_phys_2015 + - Flag for new (2015) ozone physics + - T, F + - + - ozphys_2015 + - Set to T for GFSv15p2 and GFSv16beta + +\*\*The CIRES Unified Gravity Wave Physics (cires_ugwp) scheme is used in GFSv15p2 and GFSv16beta SDFs with do_ugwp=F in the namelist. In this setting, the cires_ugwp calls the operational GFS v15.2 orographic gravity wave drag (gwdps) scheme. When do_ugwp=T, the cires_ugwp scheme calls an experimental orographic gravity wave (gwdps_v0). + +**Note that some namelist variables are not available for use with CCPP.** + + * **do_deep**. In order to disable deep convection, it is necessary to remove the deep convection scheme from the SDF. + * **shal_cnv**. In order to disable shallow convection, it is necessary to remove the deep convection scheme from the SDF. + * **ldiag3d** and **ldiag_ugwp**. Must be F for CCPP runs. + * **gwd_opt**. Ignored in CCPP-supported suites. + +**When certain parameterizations are turned on, additional namelist options can be used (they are ignored otherwise). +Some examples are shown in** :numref:`Table %s `. + +.. _EnabledNMLOptions: + +.. list-table:: *Enabled namelist variables* + :widths: 10 50 + :header-rows: 1 + + * - Namelist setting + - Enabled namelist variables + * - do_ugwp=T + - All variables in namelist record &cires_ugwp_nml plus do_tofd. Additionally, if namelist variable cnvgwd=T and + the third and fourth position of namelist array cdmbgwd are both 1, then the convective gravity wave drag that + is part of cires_ugwp will be called. (Not supported with the UFS) + * - do_mynnedmf=T + - bl_mynn_tkeadvect, bl_mynn_edmf, bl_mynn_edmf_mom (Not supported with the UFS) + * - imp_physics=99 + - psautco and prautco (Not supported with the UFS) + * - imp_physics=10 + - mg_* (Not supported with UFS) + * - imp_physics=11 + - All variables in namelist record gfdl_cloud_microphysics_nml and lgfdlmprad + * - satedmf=T + - isatedmf diff --git a/doc/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py index acb99585c4..aaa1ab70d9 100644 --- a/doc/UsersGuide/source/conf.py +++ b/doc/UsersGuide/source/conf.py @@ -19,7 +19,7 @@ # -- Project information ----------------------------------------------------- -project = 'UFS Weather Model Developers Guide' +project = 'UFS Weather Model Users Guide' copyright = '2020' author = ' '