diff --git a/docs/source/_static/supergrid.png b/docs/source/_static/supergrid.png new file mode 100644 index 000000000..91076a5c0 Binary files /dev/null and b/docs/source/_static/supergrid.png differ diff --git a/docs/source/chgres_cube.rst b/docs/source/chgres_cube.rst index ac00d4eef..4ae86e202 100644 --- a/docs/source/chgres_cube.rst +++ b/docs/source/chgres_cube.rst @@ -1,22 +1,23 @@ .. _chgres_cube: -************** Introduction -************** +------------ The chgres_cube program creates initial condition files to “coldstart” the forecast model. The initial conditions are created from either Finite-Volume Sphere (FV3) Global Forecast System (GFS), North American Mesoscale Forecast System (NAM), Rapid Refresh (RAP), or High Resolution Rapid Refresh (HRRR) gridded binary version 2 (GRIB2) data. -************************ Code structure -************************ +-------------- Note on variable names: “input” refers to the data input to the program (i.e., GRIB2, NEMSIO, NetCDF). “Target” refers to the target or FV3 model grid. See routine doc blocks for more details. +The program assumes Noah/Noah-MP LSM coefficients for certain soil thresholds. In the future, an option will be added to use RUC LSM thresholds. + * chgres.F90 - This is the main driver routine. * program_setup.F90 - Sets up the program execution. - * Reads program namelist - * Computes required soil parameters - * Reads the variable mapping (VARMAP) table. + + * Reads program namelist + * Computes required soil parameters + * Reads the variable mapping (VARMAP) table. * model_grid.F90 - Sets up the ESMF grid objects for the input data grid and target FV3 grid. * static_data.F90 - Reads static surface climatological data for the target FV3 grid (such as soil type and vegetation type). Time interpolates time-varying fields, such as monthly plant greenness, to the model run time. Data for each target FV3 resolution resides in the ‘fixed’ directory. Set path via the fix_dir_target_grid namelist variable. * write_data.F90 - Writes the tiled and header files expected by the forecast model. @@ -24,50 +25,28 @@ Note on variable names: “input” refers to the data input to the program (i.e * utils.f90 - Contains utility routines, such as error handling. * grib2_util.F90 - Routines to (1) convert from RH to specific humidity; (2) convert from omega to dzdt. Required for GRIB2 input data. * atmosphere.F90 - Process atmospheric fields. Horizontally interpolate from input to target FV3 grid using ESMF regridding. Adjust surface pressure according to terrain differences between input and target grid. Vertically interpolate to target FV3 grid vertical levels. Description of main routines: - * read_vcoord_info - Reads model vertical coordinate definition file (as specified by namelist variable vcoord_file_target_grid). - * newps - computes adjusted surface pressure given a new terrain height. - * newpr1 - computes 3-D pressure given an adjusted surface pressure. - * vintg - vertically interpolate atmospheric fields to target FV3 grid. - * surface.F90 - process land, sea/lake ice, open water/Near Sea Surface Temperature (NSST) fields. Assumes the input land data are Noah LSM-based, and the fv3 run will use the Noah LSM. NSST fields are not available when using GRIB2 input data. Description of main routines: - * interp - horizontally interpolate fields from input to target FV3 grid. - * calc_liq_soil_moisture - compute liquid portion of total soil moisture. - * adjust_soilt_for_terrain - adjust soil temperature for large differences between input and target FV3 grids. - * rescale_soil_moisture - adjust total soil moisture for differences between soil type on input and target FV3 grids. Required to preserve latent/sensible heat fluxes. Assumes Noah LSM. - * roughness - set roughness length at land and sea/lake ice. At land, a vegetation type-based lookup table is used. - * qc_check - some consistency checks. - * search_util.f90 - searches for the nearest valid land/non-land data where the input and target fv3 land-mask differ. Example: when the target FV3 grid depicts an island that is not resolved by the input data. If nearby valid data is not found, a default value is used. - -************************ -Compiling the program -************************ - -chgres_cube requires cmake 3.12 or higher. It can be built as part of the NCEPLIBS unified build system that includes two separate build systems -- one for the third party libraries that are needed and the other for the libraries and utilities themselves. See https://github.com/NOAA-EMC/NCEPLIBS-external/wiki for more detailed information. - -If the NCEPLIBS have been installed and the user wants to compile chgres_cube again - - * make sure paths are set to hdf5, compiler, mpi and cmake - * In a bash environment run - - * cd /path/to/nceplibs/installed - * source bin/setenv_nceplibs.sh (this will set all necessary environments) - * set cmake compiler - export FC=ifort (if ifort is the compiler chosen) - * cd to where you checked out the UFS_Utils - * mkdir build and cd build - * cmake .. -DCMAKE_INSTALL_PREFIX=/path/where/you/want/the/code/installed -DCMAKE_PREFIX_PATH=/path/to/nceplibs/installed - * make -j x (where x is a number that can be chosen to speed up the make, usually 8) - * make install - * if you do get errors that cmake cannot find "FindNETCDF" or "FindESMF", run: git submodule update --init --recursive + * read_vcoord_info - Reads model vertical coordinate definition file (as specified by namelist variable vcoord_file_target_grid). + * newps - computes adjusted surface pressure given a new terrain height. + * newpr1 - computes 3-D pressure given an adjusted surface pressure. + * vintg - vertically interpolate atmospheric fields to target FV3 grid. + * surface.F90 - process land, sea/lake ice, open water/Near Sea Surface Temperature (NSST) fields. NSST fields are not available when using GRIB2 input data. Description of main routines: + + * interp - horizontally interpolate fields from input to target FV3 grid. + * calc_liq_soil_moisture - compute liquid portion of total soil moisture. + * adjust_soilt_for_terrain - adjust soil temperature for large differences between input and target FV3 grids. + * rescale_soil_moisture - adjust total soil moisture for differences between soil type on input and target FV3 grids. Required to preserve latent/sensible heat fluxes. + * roughness - set roughness length at land and sea/lake ice. At land, a vegetation type-based lookup table is used. + * qc_check - some consistency checks. + * search_util.f90 - searches for the nearest valid land/non-land data where the input and target fv3 land-mask differ. Example: when the target FV3 grid depicts an island that is not resolved by the input data. If nearby valid data is not found, a default value is used. -*************************************************************** Configuring and using chgres_cube for global applications -*************************************************************** +--------------------------------------------------------- Program inputs and outputs for global applications --------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Inputs -~~~~~~ +**Inputs** The following four sets of files are located here: https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_fv3_gmted2010.v20191213/ @@ -105,8 +84,7 @@ The following four sets of files are located here: https://ftp.emc.ncep.noaa.gov * Input data files. GRIB2, NEMSIO or NetCDF. See the next section for how to find this data. -Outputs -~~~~~~~ +**Outputs** * Atmospheric “coldstart” files. NetCDF. * out.atm.tile1.nc @@ -126,10 +104,9 @@ Outputs Where to find GFS GRIB2, NEMSIO and NetCDF data for global applications --------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -GRIB2 -~~~~~ +**GRIB2** * 0.25-degree data (last 10 days only) - Use the **gfs.tHHz.pgrb2.0p25.f000** files in subdirectory gfs.YYYYMMDD/HH `here `_.` @@ -137,21 +114,18 @@ GRIB2 * 1.0-degree data - Use the **gfs_3_YYYYMMDD_00HH_000.grb2 file**, under **GFS Forecasts 003 (1-deg)** here: `NCDC - Global Forecast System `__. Note: *Tests were not done with the AVN, MRF or analysis data*. -NEMSIO -~~~~~~ +**NEMSIO** * T1534 gaussian (last 10 days only) - Use the **gfs.tHHz.atmanl.nemsio** (atmospheric fields) and **gfs.tHHz.sfcanl.nemsio** (surface fields) files in subdirectory gfs.YYYYMMDD/HH `here `_. -NetCDF -~~~~~~ +**NetCDF** * T1534 gaussian (don't have any more details at this time). Initializing global domains with GRIB2 data - some caveats ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Keep these things in mind when using GFS GRIB2 data for model initialization -~~~~~~~~~~~~~~~~ +**Keep these things in mind when using GFS GRIB2 data for model initialization.** * GRIB2 data does not contain the fields needed for the Near Sea Surface Temperature (NSST) scheme. See the next section for options on running the forecast model in this situation. * Data is coarse (in vertical and horizontal) compared to the NCEP operational GFS . May not provide a good initialization (especially for the surface). Recommendations: @@ -166,7 +140,7 @@ Keep these things in mind when using GFS GRIB2 data for model initialization * Only tested with GRIB2 data from GFS v14 and v15 (from 12z July 19, 2017 to current). May not work with older GFS data. Will not work with GRIB2 data from other models. Near Sea Surface Temperature (NSST) data and GRIB2 initialization -~~~~~~~ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The issue with not having NSST data is important. In GFS we use the foundation temperature (Tref) and add a diurnal warming/cooling layer using NSST. This is the surface temperature that is passed to the atmospheric boundary layer. This is a critical feature, especially when we are doing Data Assimilation. @@ -177,12 +151,11 @@ In GRIB2 files only the Tsfc is stored and that is set as foundation temperature Note, that neither of these two options will get rid of the underlying baked in heating/cooling in the surface temperature fields. For most cases this may not be an issue, but where it is then the user will either have to initialize the model with NEMSIO or NetCDF data, or replace the surface temperature in the GRIB2 fields with independently obtained foundation temperature. Global chgres_cube namelist options ------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Namelist variables with “input” in their name refer to data input to chgres_cube. Namelist variables with “target” in their name refer to the FV3 horizontal and vertical grid (i.e., the target grid chgres_cube is mapping to). Namelist settings for using **GRIB2** data as input in global chgres_cube applications -~~~~~~~~~~~~~~~~~~~~~~ * fix_dir_target_grid - Path to the tiled FV3 surface climatological files (such as albedo). * mosaic_file_target_grid - Path and name of the FV3 mosaic file. @@ -198,7 +171,6 @@ Namelist settings for using **GRIB2** data as input in global chgres_cube applic * convert_sfc - set to ‘true’ to process the surface fields Namelist settings for using **NEMSIO** data as input in global chgres_cube applications -~~~~~~~~~~~~~~~~~~~~~ * fix_dir_target_grid - Path to the tiled FV3 surface climatological files (such as albedo). * mosaic_file_target_grid - Path and name of the FV3 mosaic file. @@ -217,7 +189,6 @@ Namelist settings for using **NEMSIO** data as input in global chgres_cube appli * tracers - names of tracer records in output file expected by model. For GFDL microphysics, set to “sphum”,”liq_wat”,”o3mr”,”ice_wat”,”rainwat”,”snowwat”,”graupel”. Namelist settings for using **NetCDF** data as input in global chgres_cube applications -~~~~~~~~~~~~~~~~~~~~~~ * fix_dir_target_grid - Path to the tiled FV3 surface climatological files (such as albedo). * mosaic_file_target_grid - Path and name of the FV3 mosaic file. @@ -235,15 +206,13 @@ Namelist settings for using **NetCDF** data as input in global chgres_cube appli * tracers_input - names of tracer records in input file. For GFDL microphysics, set to “spfh”,”clwmr”,”o3mr”,”icmr”,”rwmr”,”snmr”,”grle”. * tracers - names of tracer records in output file expected by model. For GFDL microphysics, set to “sphum”,”liq_wat”,”o3mr”,”ice_wat”,”rainwat”,”snowwat”,”graupel”. -*************************************************************** Configuring and using chgres_cube for regional applications -*************************************************************** +---------------------------------------------------------------- Regional program inputs and outputs ---------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Inputs -~~~~~~ +**Inputs** The following four sets of files/directories should all be located in the same directory (orog_dir_target_grid in the namelist): @@ -271,8 +240,7 @@ The following four sets of files/directories should all be located in the same d * Input data files. GRIB2 only. See the next section for how to find this data. -Outputs -~~~~~~~~ +**Outputs** * Atmospheric “coldstart” file. NetCDF. * out.atm.tile7.nc @@ -281,10 +249,9 @@ Outputs * out.sfc.tile7.nc Where to find FV3GFS, NAM, HRRR, and RAP GRIB2 data for regional applications ---------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -FV3GFS -~~~~~~~~ +**FV3GFS** * 0.25-degree data (last 10 days only) - Use the **gfs.tHHz.pgrb2.0p25.f000** files in subdirectory gfs.YYYYMMDD/HH `here `_. @@ -292,16 +259,15 @@ FV3GFS * 1.0-degree data - Use the **gfs_3_YYYYMMDD_00HH_000.grb2 file**, under **GFS Forecasts 003 (1-deg)** here: `NCDC - Global Forecast System `__. Note: *Tests were not done with the AVN, MRF or analysis data*. -NAM -~~~~~ +**NAM** + * 12-km data from last few days (NOMADS) - Use the **nam.tHHz.conusnest.hiresfFH.tmHH.grib2** files in subdirectory nam.YYYYMMDD `here `__. * 12-km data from previous 6 months - Use the **nam_218_YYYYMMDD_00HH_000.grb2 file**, under **NAM Forecasts NAM-NMM 218 (12km) Domain** here: `NCDC - North American Mesoscale Forecast System `__. * 12-km archived data older than 6 months can be requested through the Archive Information Request System `here `__. -HRRR -~~~~ +**HRRR** * 3-km operational data from previous few days (NOMADS) - Use the **hrrr.tHHz.wrfnatfFH.grib2** files in the subdirectory hrrr.YYYYMMDD/conus `here `__. @@ -311,8 +277,8 @@ HRRR * 3-km operational data from 2016 to present (University of Utah): `Click here `__. -RAP -~~~~~ +**RAP** + * 13-km operational data for the previous few days (NOMADS): Use the **rap.tHHz.wrfnatfFH.grib2** files in the subdirectory rap.YYYYMMDD `here `__. @@ -323,7 +289,7 @@ RAP Initializing regional domains with GRIB2 data - some caveats ------------------------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Keep these things in mind when using FV3GFS GRIB2 data for model initialization: @@ -339,12 +305,11 @@ Keep these things in mind when using FV3GFS GRIB2 data for model initialization: * Only tested with GRIB2 data from FV3GFS, RAP, NAM, and HRRR data. May not work with GRIB2 data from other models. Use these at your own risk. Regional chgres_cube namelist options -------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Namelist variables with “input” in their name refer to data input to chgres_cube. Namelist variables with “target” in their name refer to the FV3-LAM horizontal and vertical grid (i.e., the target grid chgres_cube is mapping to). -Required Entries -~~~~~~~~~~~~~~~~ +**Required Entries** * fix_dir_target_grid - Path to the FV3-LAM surface climatological files (such as albedo). * fix_dir_input_grid - Directory containing RAP lat/lon file. On NOAA HPC machines, typically the “fix/fix_am” directory of the UFS_UTILS directory. @@ -368,8 +333,7 @@ Required Entries * halo_bndy - Integer number of rows/columns that exist within the halo, where pure lateral boundary conditions are applied. * external_model - Name of source model for input data. Valid options: 'GFS', 'NAM', 'RAP', 'HRRR'. (Default: 'GFS') -Optional Entries -~~~~~~~~~~~~~~~ +**Optional Entries** * geogrid_file_input_grid - Full path to the RAP or HRRR geogrid file corresponding to the external model input data. Only used with external_model = ‘HRRR’ or ‘RAP’. * nsoill_out - Number of soil levels to produce in the sfc_data.nc file (Default: 4). @@ -381,9 +345,8 @@ Optional Entries * tg3_from_soil - Use tg3 from input soil. Valid options: .true. or .false. . Default: .false. * thomp_mp_climo_file - Location of Thompson aerosol climatology file. Provide only if you wish to use these aerosol variables. -************************************************ Variable Mapping (VARMAP) table -************************************************ +------------------------------- The VARMAP table, set in the chgres_cube namelist (variable varmap_file), controls how chgres_cube handles variables that might be missing from the GRIB2 files. Since there are so many different versions of GRIB2 files, it's often uncertain what fields are available even if you know what source model the data is coming from. Each file contains the following: (Note, only the GFS physics suite is currently supported.) @@ -430,9 +393,8 @@ Column 5: Variable type descriptor. Variable names designated as tracers are use * “D”: 3-dimensional non-tracer array * “S”: 2-dimensional surface array -************************************************ Running the program stand alone -************************************************ +------------------------------- * Locate your input files. See above for a list. * Set the namelist for your experiment. See above for an explanation of the namelist entries. @@ -441,9 +403,8 @@ Running the program stand alone * Load any required runtime libraries. For example, you may need to load libraries for NetCDF and/or your Fortran compiler. * Run the program with an MPI task count that is a multiple of six. This is an ESMF library requirement when processing a six-tiled global grid. -************************************************ Making changes to the chgres_cube program -************************************************ +----------------------------------------- chgres_cube is part of the UFS_UTILS repository (https://github.com/NOAA-EMC/UFS_UTILS). When wanting to contribute to this repository developers shall follow the Gitflow software development process diff --git a/docs/source/conf.py b/docs/source/conf.py index e265c4dc4..f9f16fbf9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,7 +19,7 @@ # -- Project information ----------------------------------------------------- -project = 'chgres' +project = 'ufs_utils' copyright = '2020 ' author = 'George Gayno and others' @@ -54,6 +54,8 @@ 'sphinxcontrib.bibtex' ] +bibtex_bibfiles = ['references.bib'] + # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -118,7 +120,7 @@ def setup(app): # -- Options for HTMLHelp output --------------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'chgres' +htmlhelp_basename = 'ufs_utils' # -- Options for LaTeX output ------------------------------------------------ @@ -147,7 +149,7 @@ def setup(app): # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'chgres.tex', 'chgres Documentation', + (master_doc, 'ufs_utils.tex', 'ufs_utils Documentation', author,'manual'), ] @@ -157,7 +159,7 @@ def setup(app): # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'chgres', 'chgres Documentation', + (master_doc, 'ufs_utils', 'ufs_utils Documentation', [author], 1) ] @@ -168,8 +170,8 @@ def setup(app): # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'chgres', 'chgres Documentation', - 'author, chgres', 'One line description of project.', + (master_doc, 'ufs_utils', 'ufs_utils Documentation', + 'author, ufs_utils', 'One line description of project.', 'Miscellaneous'), ] diff --git a/docs/source/index.rst b/docs/source/index.rst index 2e7513ee2..dd756b6d6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,13 +1,13 @@ -.. chgres_cube documentation master file, created by +.. ufs_utils documentation master file, created by sphinx-quickstart on Tue Feb 12 08:48:32 2019. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -chgres_cube Documentation +UFS_UTILS Documentation ============================ .. toctree:: :numbered: :maxdepth: 3 - chgres_cube + ufs_utils diff --git a/docs/source/ufs_utils.rst b/docs/source/ufs_utils.rst new file mode 100644 index 000000000..6e1193e57 --- /dev/null +++ b/docs/source/ufs_utils.rst @@ -0,0 +1,423 @@ +.. _ufs_utils: + + +**************************** +Introduction +**************************** + +The Unified Forecast Systems (UFS) Utilities repository contains pre-processing programs for the UFS weather model. These programs set up the model grid and create coldstart initial conditions. The repository is hosted on `Github `_. Information on checking out the code and making changes to it is available on the repository `wiki page `_. + +*********************************** +Grid Generation +*********************************** + +The following programs are used to create a grid. + + * make_hgrid + * regional_grid_esg + * make_solo_mosaic + * orog + * global_equiv_resol + * shave + * filter_topo + * sfc_climo_gen + +The grid generation process is run by these scripts (located under ./ush) + + * fv3gfs_grid_driver.sh (driver script) + * fv3gfs_make_grid.sh (creates the geo-referencing for the grid) + * fv3gfs_make_orog.sh (creates the land-sea mask and terrain) + * fv3gfs_filter_topo.sh (filters the orography) + * sfc_climo_gen.sh (creates climatological surface fields, such as soil type) + +*************************************************** +Description of each program +*************************************************** + +chgres_cube +=========== + +.. include:: chgres_cube.rst + +make_hgrid +========== + +Introduction +------------ + +The make_hgrid program computes geo-referencing parameters for global uniform grids. (Extended Schmidt gnomonic regional grids are created by the regional_esg_grid program.) The parameters include geographic latitude and longitude, and grid cell area. See the output data section for a full list of parameters. Grids are gnomonic such that all great circles are straight lines. The parameters are computed on the staggered or "supergrid" - which has twice the resolution of the model grid. The chgres_cube initialization program maps mass fields - such as temperature - at the supergrid centroids, and u/v winds at the face mid-points. The supergrid is shown here: + +.. _figure_reference: + +.. figure:: _static/supergrid.png + +Code Structure +-------------- + +Location of source code: ./sorc/fre-nctools.fd/tools/make_hgrid. Relevant routines: + + * make_hgrid.c - main driver routine + * create_gnomonic_cubic_grid.c - contains routines for creating a gnomonic grid + +Namelist Options +---------------- + +The program is controlled by these script variables: + + * Global uniform grid + * res - x/y dimension of one tile. The "CRES" resolution. Example: a 96x96 tile would be classified as C96. It may be converted to physical resolution as follows: resol = (360 degrees / 4*CRES) * 111 km. + +Program inputs and outputs +-------------------------- + +**Input data:** + +None + +**Output data:** + +Tiled "grid" files (NetCDF) containing geo-referencing records. File naming convention: CRES_grid.tile#.nc. File records include: + + * x - geographic longitude (degrees) + * y - geographic latitude (degrees) + * dx - grid edge 'x' distance (m) + * dy - grid edge 'y' distance (m) + * area - grid cell area (m^2) + * angle_dx - grid vertex 'x' angle with respect to geographic east (degrees) + * angle_dy - grid vertex 'y' angle with respect to geographic north (degrees) + +regional_esg_grid +================= + +Introduction +------------ + +The regional_esg_grid program computes geo-referencing parameters for the Extended Schmidt Gnomonic (ESG) regional grid. The parameters include geographic latitude and longitude, and grid cell area. See the output data section for a full list of parameters. The ESG grid is designed to have nearly homogenous grid spacing. Like the make_hgrid program, the parameters are computed on the staggered or "supergrid". For more information on the Extended Schmidt Gnomonic, see: `Purser, et. al `_. + +Code Structure +-------------- + +Location of source code: ./sorc/grid_tools.fd/regional_esg_grid.fd. Relevant routines: + + * regional_esg_grid.f90 - Main driver routine. Reads program namelist. Writes output file. + * pseg.f90 - Suite of routines to perform the ESG regional grid mapping. + +Namelist Options +---------------- + +The program is controlled by these script variables: + + * target_lon - center longitude of grid - degrees + * target_lat - center latitude of grid - degrees + * idim - dimension of grid in 'i' direction + * jdim - dimension of grid in 'j' direction + * delx - grid spacing in degrees in the 'i' direction on the supergrid. The physical grid spacing is related to delx as follows: 2*delx(circumf_earth / 360 deg). + * dely - grid spacing in degrees in the 'j' direction on the supergrid. + * halo - number of rows/cols of the lateral boundary halo + +Program Inputs and Outputs +-------------------------- + +**Input data:** + +None + +**Output data:** + +A tiled "grid" file (NetCDF) containing geo-referencing records for the supergrid. File naming convention: CRES_grid.tile7.nc. Here, CRES is the global equivalent resolution as computed by the global_equiv_resol program. Note: the forecast model assumes regional grids are tile 1. File records include: + + * x - geographic longitude (degrees) + * y - geographic latitude (degrees) + * dx - grid edge 'x' distance (m) + * dy - grid edge 'y' distance (m) + * area - grid cell area (m^2) + * angle_dx - grid vertex 'x' angle with respect to geographic east (degrees) + * angle_dy - grid vertex 'y' angle with respect to geographic north (degrees) + + +make_solo_mosaic +================ + +Introduction +------------ + +This program creates the "mosaic" file, which contains information about the tiled "grid" files (such as name and tile number). For global grids, it also defines the orientation of the six tiles. All output records are listed below under "output data". There are no runtime-selectable options for this program. + +Code structure +-------------- + +Location of source code ./sorc/fre-nctools.fd/tools/make_solo_mosaic. Relevant routines: + + * make_solo_mosaic.c - main driver routine. + * get_contact.c - computes the number of aligned contacts between two tiles. + + +Program inputs and outputs +-------------------------- + +**Input data:** + +The tiled "grid" files (CRES_grid.tile#.nc) created by the make_hgrid or regional_esg_grid programs - (NetCDF) + +**Output data:** + +The mosaic file - CRES_mosaic.nc (NetCDF). Contains these records + + * Mosaic - name of mosaic (character) + * Gridlocation - directory containing the "grid" files (character) + * Gridfiles - names of each "grid" file (character array) + * Gridtiles - list of each tile number (character array) + * Contacts - list of tile contact regions - global grids only (character array) + * Contact_index - list of contact regions as specified by i/j index - global grids only (character array). + +global_equiv_resol +================== + +Introduction +------------ + +This program computes the global equivalent resolution for regional grids. For example, a global grid with x/y dimensions of 96 would have a global resolution (CRES) of C96. And the approximate physical resolution would be: + + * Res in km = (360 degrees / 4*CRES) * 111 km = 104 km + +Using the average cell size (in m^2) of the regional grid, the equivalent global resolution is computed according to: + + * CRES = nint( (2*pi*rad_earth)/(4*avg_cell_size) ) + +There are no runtime-selectable options for this program. + +Code structure +-------------- + +Location of source code: ./sorc/grid_tools.fd/global_equiv_resol.fd. Relevant routine: + + * global_equiv_resol.f90 - Contains the entire program. + +Program inputs and outputs +-------------------------- + +**Input data:** + +The regional "grid" file (CRES_grid.tile#.nc) created by the regional_esg_grid program - (NetCDF). Uses the grid cell area record. + +**Output data:** + +Adds the equivalent resolution as an attribute to the "grid" file - CRES_grid.tile#.nc (NetCDF). + +orog +==== + +Introduction +------------ + +This program computes the land mask, land fraction, orography and gravity wave drag (GWD) fields on the model grid. See the output data section for a complete list of fields. + +Land-sea mask and land fraction are created from a global 30-arc second University of Maryland land cover (land/non-land flag) dataset. Land fraction is determined by averaging all 30-second land cover points located within the model grid box. Points with a land fraction of 50% or more are given a land-sea mask of "land". Orography and GWD fields are created from two datasets: 1) 30-arc-second `USGS GMTED2010 `_ orography data; 2) for Antarctica, 30-arc-second `RAMP `_ terrain data (Radarsat Antarctic Mapping Project). Fields are determined from all 30-arc second data located within the model grid box. The orography is simply the average of the 30-arc second values. It is later filtered by the filter_topo program. For details on the GWD fields, see: + + * Kim, Y-J and A. Arakawa, 1995: Improvement of orographic gravity wave parameterization using a mesoscale gravity wave model. J. Atmos. Sci. 52, pp 1875-1902. + * Lott, F. and M. J. Miller: 1977: A new sub-grid scale orographic drag parameterization: Its formulation and testing, QJRMS, 123, pp 101-127. + +Code structure +-------------- + +The source code is located - ./sorc/orog_mask_tools.fd/orog.fd. Some important subroutines: + + * MAKEMT2 - computes land fraction, land-sea mask, orography, standard deviation of orography, and convexity. + * MAKEPC2 - computes anisotropy (gamma), slope of orography (sigma) and mountain range angle (theta). + * MAKEOA2 - computes maximum height (elvmax), orographic asymmetry (oa) and length scale (ol). + +Program inputs and outputs +-------------------------- + +**Input data:** + + * The "grid" files (CRES_grid.tile#.nc) containing the geo-reference records for the grid - (NetCDF). Created by the make_hgrid or regional_esg_grid programs. + * Global 30-arc-second University of Maryland land cover data. Used to create the land-sea mask. + * ./fix/fix_orog/landcover30.fixed (unformatted binary) + * Global 30-arc-second USGS GMTED2010 orography data. + * ./fix/fix_orog/gmted2010.30sec.int (unformatted binary) + * 30-arc-second RAMP Antarctic terrain data (Radarsat Antarctic Mapping Project) + * ./fix/fix_orog/thirty.second.antarctic.new.bin (unformatted binary) + +**Output data:** + +Orography files - one for each tile - oro.CRES.tile#.nc (NetCDF). Contains these records: + + * geolon - longitude (degrees east) + * geolat - latitude (degrees north) + * slmsk - land-sea mask (0 - nonland; 1 - land) + * land_frac - land fraction (percent) + * orog_raw - orography (meters) + * orog_filt - same as orog_raw + * stddev - standard deviation of orography (meters) + * convexity - orographic convexity (unitless) + * oa[1-4] - orographic asymmetry - four directional components - W/S/SW/NW + * ol[1-4] - orographic length scale - four directional components - W/S/SW/NW + * theta - angle of mountain range with respect to east (degrees) + * gamma - anisotropy (unitless) + * sigma - slope of orography (unitless) + * elvmax - maximum height above mean (meters) + +filter_topo +=========== + +Introduction +------------ + +The FV3 terrain filtering algorithm has several unique properties compared to conventional topography filters. The resulting topography filtered by this algorithm has conserved globally integrated elevations. More importantly, this filter has the following island-preserving properties: 1) No Gibbs ringing at the coastlines where discontinuities occur; 2) the filtered terrain's coastlines strictly match the source terrain's. The detailed implementation of this terrain filtering algorithm will be described in a forthcoming publication by Dr. Shian-Jiann Lin and his group. + +Code structure +-------------- + +Location of source code: ./sorc/grid_tools.fd/filter_topo.fd. The entire program is contained in filter_topo.F90. + +Namelist options +---------------- + +Program execution is controlled via a namelist. The namelist variables are: + + * topo_file - Name of the orography file (See input data) (character) + * topo_field - Name of the filtered orography record in the orography file ("orog_filt") (character) + * mask_field - Name of the land-sea mask record in the orography file ("land_frac") (character) + * grid_file - The mosaic file (See input data) (character) + * zero_ocean - Flag to turn on the "island-preserving" property. Default is true (logical) + * stretch_fac - Stretching factor. Equal to "1" for global uniform grids. Not applicable for ESG regional grids (floating point) + * res - The "CRES" resolution (floating point) + * grid_type - 0 for a gnomonic grid (integer) + * regional - True for an ESG regional grid (logical) + +Program inputs and outputs +-------------------------- + +**Input data:** + + * mosaic file - the mosaic file from the make_solo_mosaic program - CRES_mosaic.nc (NetCDF) + * grid file - the "grid" file from the make_hgrid or regional_esg programs - CRES_grid.tile#.nc - (NetCDF) + * orography file - the orography file from the orog program - oro.CRES.tile#.nc (NetCDF) + +**Output data:** + + * The filtered orography is written to the "orog_filt" record of the input orography file - oro.CRES.tile#.nc (NetCDF). + +Filtering parameters +-------------------- + + * n_del2 - Second-order strong filtering coefficient. + * n_del2_weak - Second-order weak filtering coefficient - used to more finely smooth the topography compared to the strong filter. + * cd4 - dimensionless coefficient for delta-4 diffusion. + * peak_fac - overshoot factor for the mountain peak + * max_slope - maximum allowable terrain slope + +shave +===== + +Introduction +------------ + +The "grid" and "orography" files for regional grids are first created with rows and columns extending beyond the halo. This is required for the topography filtering code to work correctly in the halo region. After filtering, the shave program removes these extra points from the files. + +Code structure +-------------- + +Location of the source code: ./sorc/grid_tools.fd/shave.fd. The entire program is contained in shave_nc.F90. + +Program control options +----------------------- + +The program is controlled by these parameters read from standard input: + + * The i/j dimensions of the compute domain (not including halo) (integer) + * The number of halo rows/columns (integer) + * The file name with the extra points (character string) + * The name of the output file with the extra points removed (character string) + +Program inputs and outputs +-------------------------- + +**Input data:** + + * Model "grid" files (CRES_grid.tile#.nc) created by the make_hgrid or regional_esg_grid programs - (NetCDF) + * Model orography files (oro.CRES.tile#.nc) after topography filtering - (NetCDF) + +**Output data:** + +With and without the halo. + + * Model "grid" files - CRES.grid.tile#.halo#.nc (NetCDF) + * Model orography files - CRES.oro_data.tile#.halo#.nc (NetCDF) + + +sfc_climo_gen +============= + +Introduction +------------ + +The sfc_climo_gen (surface climatological field generation) program creates surface climatological fields such as soil type, vegetation type and albedo. Some fields may be time-varying: for example, snow-free albedo is monthly. But they are static - i.e., they only need to be generated when the grid is created. The program uses the ESMF library to horizontally interpolate the source data to the model grid. For regional grids, the program will output files with and without the halo region when the "halo" namelist variable is set. + +Code structure +-------------- + +Location of the source code: ./sorc/sfc_climo_gen.fd. Brief description of each module: + + * driver.F90 - The main driver routine. + * interp.F90 - The interpolation driver routine. Reads the input source data and interpolates it to the model grid. + * model_grid.F90 - Defines the ESMF grid object for the model grid. + * output.f90 - Writes the output surface data to a NetCDF file. For regional grids, will output separate files with and without the halo. + * program_setup.f90 - Reads the namelist and sets up program execution. + * search.f90 - Replace undefined values on the model grid with a valid value at a nearby neighbor. Undefined values are typically associated with isolated islands where there is no source data. + * source_grid.F90 - Reads the grid specifications and land/sea mask for the source data. Sets up the ESMF grid object for the source grid. + * utils.f90 - Contains error handling utility routines. + +Namelist options +---------------- + +Program execution is controlled via a namelist. The namelist variables are: + + * input_facsf_file - path/name of input fractional strong/weak zenith angle albedo data + * input_substrate_file - path/name of input soil substrate temperature data + * input_maximum_snow_albedo_file - path/name of input maximum snow albedo data + * input_snowfree_albedo_file - path/name of input snow-free albedo data + * input_slope_type_file - path/name of input global slope type data + * input_soil_type_file - path/name of input soil type data + * input_vegetation_type_file - path/name of vegetation type data + * input_vegetation_greenness_file - path/name of monthly vegetation greenness data + * mosaic_file_mdl - path/name of the model mosaic file + * orog_dir_mdl - directory containing the model orography files + * orog_files_mdl - list of model orography files. For global uniform grids, all six files are listed. + * halo - number of rows/cols of the lateral boundary halo (regional grids only). When selected, the program will output files with and without the halo region. + * maximum_snow_albedo_method - interpolation method for this field. Bilinear or conservative. Default is bilinear. + * snowfree_albedo_method - interpolation method for this field. Bilinear or conservative. Default is bilinear. + * vegetation_greenness_method - interpolation method for this field. Bilinear or conservative. Default is bilinear. + +Program inputs and outputs +-------------------------- + +**Input data:** + +The global surface climatological data is located in ./fix/fix_sfc_climo. All NetCDF. + + * Global 1-degree fractional coverage strong/weak zenith angle albedo - facsf.1.0.nc + * Global 0.05-degree maximum snow albedo - maximum_snow_albedo.0.05.nc + * Global 2.6 x 1.5-degree soil substrate temperature - substrate_temperature.2.6x1.5.nc + * Global 0.05-degree four component monthly snow-free albedo - snowfree_albedo.4comp.0.05.nc + * Global 1.0-degree categorical slope type - slope_type.1.0.nc + * Global 0.05-degree categorical STATSGO soil type - soil_type.statsgo.0.05.nc + * Global 0.05-degree categorical IGBP vegetation type - vegetation_type.igbp.0.05.nc + * Global 0.144-degree monthly vegetation greenness in percent - vegetation_greenness.0.144.nc + * Model mosaic file - CRES_mosaic.nc (NetCDF) + * Model orography files including halo - CRES_oro_data.tile#.halo#.nc (NetCDF) + * Model grid files including halo - CRES_grid.tile#.halo#.nc (NetCDF) + +**Output files:** + +All files with and without halo (all NetCDF). + + * Fractional coverage strong/weak zenith angle albedo - CRES_facsf.tile#.halo#.nc + * Maximum snow albedo - CRES_maximum_snow_albedo.tile#.halo#nc + * Soil substrate temperature - CRES_substrate_temperature.tile#.halo#.nc + * Snow free albedo - CRES_snowfree_albedo.tile#.halo#.nc + * Slope type - CRES_slope_type.tile#.halo#.nc + * Soil type - CRES_soil_type.tile#.halo#.nc + * Vegetation type - CRES_vegetation_type.tile#.halo#.nc + * Vegetation greenness - CRES_vegetation_greenness.tile#.halo#.nc