.
+
+### NetCDF
+
+- T1534 gaussian (don't have any more details at this time).
+
+# Initializing with GRIB2 data - some caveats
+
+Keep this 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:
+
+ - C96 - use 0.25, 0.5 or 1.0-degree GRIB2 data
+ - C192 - use 0.25 or 0.5-degree GRIB2 data
+ - C384 - use 0.25-degree GRIB2 data
+ - C768 - try the 0.25-degree GRIB2 data. But it may not work well.
+
+- Sea/lake ice thickness and column temperatures are not
+ available. So, nominal values of 1.5 m and 265 K are used.
+
+- Soil moisture in the GRIB2 files is created using bilinear
+ interpolation and, therefore, may be a mixture of values from
+ different soil types. Could result in poor latent/sensible heat
+ fluxes.
+
+- Ozone is not available at all isobaric levels. Missing levels are
+ set to a nominal value defined in the variable mapping (VARMAP) file
+ (1E-07).
+
+- 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.
+
+When using NEMSIO or NetCDF data to initialize the model, both the
+foundation and surface temperature are available and the atmospheric
+model should be run using the NSST option as this will properly
+account for in the forward run of the model.
+
+In GRIB2 files only the Tsfc is stored and that is set as foundation
+temperature as well. So the diurnal heating / cooling is baked into
+the initial condition for the extent of the run. This can be critical
+if the model is being initialized when the ocean is warm and
+initialization is occuring at the peak of the diurnal warming. That
+warm ocean will be baked in for the extent of the run and may spawn
+off a number of fake hurricanes. The user has two options -- either to
+use a spin up cycle to spin up NSST (set nstf_name =
+[2,1,0,0,0] in input.nml of the model namelist file. This will
+create a diurnal cycle after 24 hours of spin up), or to run the model
+without any NSST option ( set nstf_name = [0,0,0,0,0] in
+input.nml of the model namelist file. The user will also have
+to choose one of the no NSST physics suite options in
+input.nml).
+
+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.
+
+# 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).
+
+When using GRIB2 data as input to chgres_cube, set namelist as
+follows:
+
+ - 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.
+
+ - orog_dir_target_grid - directory containing the tiled FV3 orography
+ and grid files (NetCDF).
+
+ - orog_files_target_grid - names of the six tiled FV3 orography
+ files.
+
+ - vcoord_file_target_grid - path and name of the model vertical
+ coordinate definition file (“global_hyblev.l$LEVS.txt).
+
+ - data_dir_input_grid - directory containing the GRIB2 initial
+ conditions data
+
+ - grib2_file_input_grid - name of the GRIB2 input data file
+
+ - varmap_file - path and name of the variable mapping (VARMAP) table.
+ See below for details on this table.
+
+ - input_type - input data type. Set to ‘grib2’
+
+ - cycle_mon/day/hour - month/day/hour of your model initialization
+
+ - convert_atm - set to ‘true’ to process the atmospheric fields
+
+ - convert_sfc - set to ‘true’ to process the surface fields
+
+When using NEMSIO data as input to chgres_cube, set namelist as follows:
+
+ - 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.
+
+ - orog_dir_target_grid - directory containing the tiled FV3 orography
+ and grid files (NetCDF).
+
+ - orog_files_target_grid - names of the six tiled FV3 orography
+ files.
+
+ - vcoord_file_target_grid - path and name of the model vertical
+ coordinate definition file (“global_hyblev.l$LEVS.txt).
+
+ - data_dir_input_grid - directory containing the NEMSIO input data
+
+ - atm_files_input_grid - name of the NEMSIO input atmospheric data
+ file
+
+ - sfc_files_input_grid - name of the NEMSIO input surface/Near Sea
+ Surface Temperature (NSST) data file
+
+ - input_type - input data type. Set to ‘gaussian_nemsio’.
+
+ - cycle_mon/day/hour - month/day/hour of your model run
+
+ - convert_atm - set to ‘true’ to process the atmospheric fields
+
+ - convert_sfc - set to ‘true’ to process the surface fields
+
+ - convert_nst - set to ‘true’ to process NSST fields
+
+ - 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”.
+
+When using NetCDF data as input to chgres_cube, set namelist as follows:
+
+ - 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.
+
+ - orog_dir_target_grid - directory containing the tiled FV3 orography
+ and grid files (NetCDF).
+
+ - orog_files_target_grid - names of the six tiled FV3 orography
+ files.
+
+ - vcoord_file_target_grid - path and name of the model vertical
+ coordinate definition file (“global_hyblev.l$LEVS.txt).
+
+ - data_dir_input_grid - directory containing the NetCDF input data
+
+ - atm_files_input_grid - name of the NetCDF input atmospheric data
+ file
+
+ - sfc_files_input_grid - name of the NetCDF input surface/Near Sea
+ Surface Temperature (NSST) data file
+
+ - input_type - input data type. Set to ‘gaussian_netcdf’.
+
+ - cycle_mon/day/hour - month/day/hour of your model run
+
+ - convert_atm - set to ‘true’ to process the atmospheric fields
+
+ - convert_sfc - set to ‘true’ to process the surface fields
+
+ - convert_nst - set to ‘true’ to process NSST fields
+
+ - 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”.
+
+# Program inputs and outputs
+
+## Inputs
+
+The following four sets of files are located here:
+https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_fv3_gmted2010.v20191213/
+
+ - FV3 mosaic file - (NetCDF format)
+ - CRES_mosaic.nc
+
+ - FV3 grid files - (NetCDF format)
+ - CRES_grid.tile1.nc
+ - CRES_grid.tile2.nc
+ - CRES_grid.tile3.nc
+ - CRES_grid.tile4.nc
+ - CRES_grid.tile5.nc
+ - CRES_grid.tile6.nc
+
+ - FV3 orography files - (NetCDF format)
+ - CRES_oro_data.tile1.nc
+ - CRES_oro_data.tile2.nc
+ - CRES_oro_data.tile3.nc
+ - CRES_oro_data.tile4.nc
+ - CRES_oro_data.tile5.nc
+ - CRES_oro_data.tile6.nc
+
+ - FV3 surface climatological files - Located under the ./fix_sfc sub-directory. One file for each tile. NetCDF format.
+ - CRES.facsf.tileX.nc (fractional coverage for strong/weak zenith angle dependent albedo)
+ - CRES.maximum_snow_albedo.tileX.nc (maximum snow albedo)
+ - CRES.slope_type.tileX.nc (slope type)
+ - CRES.snowfree_albedo.tileX.nc (snow-free albedo)
+ - CRES.soil_type.tileX.nc (soil type)
+ - CRES.subtrate_temperature.tileX.nc (soil substrate temperature)
+ - CRES.vegetation_greenness.tileX.nc (vegetation greenness)
+ - CRES.vegetation_type.tileX.nc (vegetation type)
+
+ - FV3 vertical coordinate file. Text file. Located here: https://ftp.emc.ncep.noaa.gov/EIB/UFS/global/fix/fix_am.v20191213/
+ - global_hyblev.l$LEVS.txt
+
+ - Input data files. GRIB2, NEMSIO or NetCDF. See above section for how to find this data.
+
+## Outputs
+
+ - Atmospheric “coldstart” files. NetCDF.
+ - out.atm.tile1.nc
+ - out.atm.tile2.nc
+ - out.atm.tile3.nc
+ - out.atm.tile4.nc
+ - out.atm.tile5.nc
+ - out.atm.tile6.nc
+
+ - Surface/Near Sea Surface Temperature (NSST) “coldstart” files. NetCDF
+ - out.sfc.tile1.nc
+ - out.sfc.tile1.nc
+ - out.sfc.tile1.nc
+ - out.sfc.tile1.nc
+ - out.sfc.tile1.nc
+ - out.sfc.tile1.nc
+
+# 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.
+
+ - Link the namelist to Fortran unit number 41:
+ ln -fs your-namelist-file ./fort.41
+
+ - 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.
+
+# 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.)
+
+Column 1: Name the code searches for in the table. Do not change.
+Some definitions:
+
+ - dzdt - vertical velocity
+ - sphum - specific humidity
+ - liq_wat - liquid water mixing ratio
+ - o3mr - ozone mixing ratio
+ - ice_wat - ice water mixing ratio
+ - rainwat - rain water mixing ratio
+ - snowwat - snow water mixing ratio
+ - graupel - graupel mixing ratio
+ - vtype - vegetation type
+ - sotype - soil type
+ - vfrac - plant greenness fraction
+ - fricv - friction velocity
+ - sfcr - roughness length
+ - tprcp - precipitation rate
+ - ffmm - surface exchange coefficient for momentum
+ - ffhh - surface exchange coefficient for heat
+ - f10m - log((sfcr+10)/sfcr)
+ - soilw - total volumetric soil moisture
+ - soill - liquid volumetric soil moisture
+ - soilt - soil column temperature
+ - cnwat - plant canopy water content
+ - hice - sea/lake ice thickness
+ - weasd - snow liquid equivalent
+ - snod - physical snow depth
+
+Column 2: Name of the variable in the output “coldstart”
+files. Unimplemented.
+
+Column 3: Behavior when the code can't find the variable in the input
+file. Options are:
+
+ - "skip": Don't write to the output file.
+ - "set_to_fill": Set to user-specified field value (see column 4).
+ - "stop": Force an exception and stop code execution. Use this if you
+ absolutely require a field to be present.
+
+Column 4: If column 3 = "set_to_fill", then this value is used to fill
+in all points in the input field. These values may be overwritten by
+the code before output depending on the variable (especially for
+surface variables).
+
+Column 5: Variable type descriptor. Variable names designated as
+tracers are used to populate the list of tracers to read from the
+GRIB2 file and write to output, so make sure all tracers you wish to
+read have an entry. Note that if you wish to add a tracer name that is
+not already included in the appropriate VARMAP file, this will require
+modification of the chgres_cube code. Valid choices are:
-This is part of the UFS_UTILS documentation.
+ - “T”: 3-dimensional tracer array
+ - “D”: 3-dimensional non-tracer array
+ - “S”: 2-dimensional surface array
-The chgres_cube code can be found here:
-https://github.com/NOAA-EMC/UFS_UTILS/tree/develop/sorc/chgres_cube.fd.
diff --git a/sorc/chgres_cube.fd/grib2_util.F90 b/sorc/chgres_cube.fd/grib2_util.F90
index 31862636a..c071be7ce 100644
--- a/sorc/chgres_cube.fd/grib2_util.F90
+++ b/sorc/chgres_cube.fd/grib2_util.F90
@@ -3,7 +3,12 @@
!! @author George Gayno NCEP/EMC
!> Utilities for use when reading grib2 data.
-!! @author George Gayno NCEP/EMC
+!!
+!! This module contains routines to:
+!! - convert from RH to specific humidity
+!! - convert from omega to dzdt.
+!!
+!! George Gayno NCEP/EMC
module grib2_util
use esmf
@@ -14,10 +19,11 @@ module grib2_util
contains
-!> Convert relative humidity to specific humidity
-!! @param [inout] rh_sphum rel humidity on input. spec hum on output.
-!! @param [in] p pressure in Pa
-!! @param [in] t temperature
+!> Convert relative humidity to specific humidity.
+!!
+!! @param[inout] rh_sphum rel humidity on input. spec hum on output.
+!! @param[in] p pressure in Pa
+!! @param[in] t temperature
!! @author Larissa Reames
!! @author Jeff Beck
subroutine rh2spfh(rh_sphum,p,t)
@@ -51,13 +57,14 @@ subroutine rh2spfh(rh_sphum,p,t)
end subroutine RH2SPFH
-!> Convert omega to vertical velocity
-!! @param [inout] omega on input, vertical velocity on output
-!! @param [in] p pressure
-!! @param [in] t temperature
-!! @param [in] q specific humidity
-!! @param [in] clb lower bounds of indices processed by this mpi task
-!! @param [in] cub upper bounds of indices processed by this mpi task
+!> Convert omega to vertical velocity.
+!!
+!! @param[inout] omega on input, vertical velocity on output
+!! @param[in] p pressure
+!! @param[in] t temperature
+!! @param[in] q specific humidity
+!! @param[in] clb lower bounds of indices processed by this mpi task
+!! @param[in] cub upper bounds of indices processed by this mpi task
!! @author Larissa Reames
!! @author Jeff Beck
subroutine convert_omega(omega,p,t,q,clb,cub)
diff --git a/sorc/chgres_cube.fd/input_data.F90 b/sorc/chgres_cube.fd/input_data.F90
index 03990fcd5..4bb74b83d 100644
--- a/sorc/chgres_cube.fd/input_data.F90
+++ b/sorc/chgres_cube.fd/input_data.F90
@@ -1,5 +1,5 @@
!> @file
-!! @brief Read input data
+!! @brief Read atmospheric and surface data from GRIB2, NEMSIO and NetCDF files.
!! @author George Gayno NCEP/EMC
!> Read atmospheric, surface and nst data on the input grid.
diff --git a/sorc/chgres_cube.fd/model_grid.F90 b/sorc/chgres_cube.fd/model_grid.F90
index aa1b43fb1..e5820c7c9 100644
--- a/sorc/chgres_cube.fd/model_grid.F90
+++ b/sorc/chgres_cube.fd/model_grid.F90
@@ -2,7 +2,8 @@
!! @brief Specify input and target model grids.
!! @author George Gayno NCEP/EMC
-!> Specify input and target model grids via ESMF grid objects.
+!> Sets up the ESMF grid objects for the input data grid and target
+!! FV3 grid.
!!
!! @author George Gayno NCEP/EMC
module model_grid
diff --git a/sorc/chgres_cube.fd/search_util.F90 b/sorc/chgres_cube.fd/search_util.F90
index c0dd35d3b..1475cade4 100644
--- a/sorc/chgres_cube.fd/search_util.F90
+++ b/sorc/chgres_cube.fd/search_util.F90
@@ -6,6 +6,11 @@
!! happen for an isolated lake or island that is unresolved by
!! the input grid.
!!
+!! 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.
+!!
!! @author George Gayno NCEP/EMC
module search_util
diff --git a/sorc/chgres_cube.fd/static_data.F90 b/sorc/chgres_cube.fd/static_data.F90
index 5ff854b71..ebd02482b 100644
--- a/sorc/chgres_cube.fd/static_data.F90
+++ b/sorc/chgres_cube.fd/static_data.F90
@@ -1,10 +1,13 @@
!> @file
-!! @brief Process static surface data
+!! @brief Process static surface data.
!! @author George Gayno NCEP/EMC
-!> Read pre-computed static/climatological data on the fv3
-!! target grid. Time interpolate if necessary (for example a
-!! monthly climo field).
+!> 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.
!!
!! @author George Gayno NCEP/EMC
module static_data
diff --git a/sorc/chgres_cube.fd/surface.F90 b/sorc/chgres_cube.fd/surface.F90
index 868213289..2b15950c9 100644
--- a/sorc/chgres_cube.fd/surface.F90
+++ b/sorc/chgres_cube.fd/surface.F90
@@ -1,5 +1,6 @@
!> @file
-!! @brief Process surface and nst fields.
+!! @brief Process land, sea/lake ice, open water/Near Sea Surface
+!! Temperature (NSST) fields.
!! @author George Gayno NCEP/EMC
!> Process surface and nst fields. Interpolates fields from the input
@@ -8,6 +9,10 @@
!! type differences between input and target grid. Computes frozen
!! portion of total soil moisture.
!!
+!! 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.
+!!
!! Public variables are defined below. "target" indicates field
!! associated with the target grid. "input" indicates field associated
!! with the input grid.
@@ -295,7 +300,8 @@ subroutine surface_driver(localpet)
end subroutine surface_driver
-!> Horizontally interpolate surface fields using esmf routines.
+!> Horizontally interpolate surface fields from input to target FV3
+!> grid using esmf routines.
!!
!! @param[in] localpet ESMF local persistent execution thread
!!
@@ -3306,8 +3312,9 @@ FUNCTION FRH2O (TKELV,SMC,SH2O,SMCMAX,BEXP,PSIS)
END function frh2o
-!> Adjust soil moisture for changes in soil type between the input and target grids.
-!! Works for Noah land model only.
+!> Adjust soil moisture for changes in soil type between the input and
+!! target grids. Works for Noah land model only. Required to preserve
+!! latent/sensible heat fluxes.
!!
!! @author George Gayno NOAA/EMC
subroutine rescale_soil_moisture
@@ -3665,10 +3672,9 @@ subroutine adjust_soil_levels(localpet)
end subroutine adjust_soil_levels
-!> Set roughness length at land and sea ice.
-!! At land, roughness is set from a lookup table
-!! based on the vegetation type. At sea ice, roughness is
-!! set to 1 cm.
+!> Set roughness length at land and sea ice. At land, roughness is
+!! set from a lookup table based on the vegetation type. At sea ice,
+!! roughness is set to 1 cm.
!!
!! @author George Gayno NOAA/EMC
subroutine roughness
diff --git a/sorc/chgres_cube.fd/write_data.F90 b/sorc/chgres_cube.fd/write_data.F90
index ff142ec23..328a4c107 100644
--- a/sorc/chgres_cube.fd/write_data.F90
+++ b/sorc/chgres_cube.fd/write_data.F90
@@ -1,5 +1,6 @@
!> @file
-!! @brief Write model coldstart files.
+!! @brief Writes the tiled and header files expected by the forecast
+!! model.
!!
!! @author George Gayno NCEP/EMC
!!
diff --git a/sorc/emcsfc_ice_blend.fd/docs/user_guide.md b/sorc/emcsfc_ice_blend.fd/docs/user_guide.md
index b4c2e6c3d..0c4ef0e4d 100644
--- a/sorc/emcsfc_ice_blend.fd/docs/user_guide.md
+++ b/sorc/emcsfc_ice_blend.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# emcsfc_ice_blend
+# Introduction
+
Blends National Ice Center sea ice cover and EMC sea ice concentration
data to create a global sea ice analysis used to update the GFS once
per day.
diff --git a/sorc/emcsfc_snow2mdl.fd/docs/user_guide.md b/sorc/emcsfc_snow2mdl.fd/docs/user_guide.md
index 803698d5a..cf4b3bc59 100644
--- a/sorc/emcsfc_snow2mdl.fd/docs/user_guide.md
+++ b/sorc/emcsfc_snow2mdl.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# emcsfc_snow2mdl
+# Introduction
+
Blends National Ice Center snow cover and Air Force snow depth data to
create a global depth analysis used to update the GFS snow field once
per day.
diff --git a/sorc/fvcom_tools.fd/docs/user_guide.md b/sorc/fvcom_tools.fd/docs/user_guide.md
index 62d1652cf..61fdf3d93 100644
--- a/sorc/fvcom_tools.fd/docs/user_guide.md
+++ b/sorc/fvcom_tools.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# fvcom_tools
+# Introduction
+
Replaces lake surface and lake ice temperature along with aerial ice
concentration generated from the Great Lakes Operational Forecast
System (GLOFS) in an FV3 surface restart file. See [fvcom
diff --git a/sorc/global_cycle.fd/docs/user_guide.md b/sorc/global_cycle.fd/docs/user_guide.md
index 19e60d576..03909444a 100644
--- a/sorc/global_cycle.fd/docs/user_guide.md
+++ b/sorc/global_cycle.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# global_cycle
+# Introduction
+
Updates the GFS surface conditions using external snow and sea ice
analyses. Updates monthly climatological fields such as plant
greenness fraction and albedo. Runs as part of the GFS and GDAS
diff --git a/sorc/grid_tools.fd/docs/user_guide.md b/sorc/grid_tools.fd/docs/user_guide.md
index 83114f059..6d9f5dbeb 100644
--- a/sorc/grid_tools.fd/docs/user_guide.md
+++ b/sorc/grid_tools.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# grid_tools
+# Introduction
+
Utilities to filter topography, to create regional extended Schmidt
gnomonic grids, and to compute the equivalent global resolution of a
regional grid.
diff --git a/sorc/orog_mask_tools.fd/docs/user_guide.md b/sorc/orog_mask_tools.fd/docs/user_guide.md
index 9cba095da..2d605dc97 100644
--- a/sorc/orog_mask_tools.fd/docs/user_guide.md
+++ b/sorc/orog_mask_tools.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# orog_mask_tools
+# Introduction
+
Utilities to create land mask, terrain and gravity wave drag fields;
set lake fraction and depth; creates an inland land mask.
diff --git a/sorc/sfc_climo_gen.fd/docs/user_guide.md b/sorc/sfc_climo_gen.fd/docs/user_guide.md
index 69d7e780c..28d8b6815 100644
--- a/sorc/sfc_climo_gen.fd/docs/user_guide.md
+++ b/sorc/sfc_climo_gen.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# sfc_climo_gen
+# Introduction
+
Creates surface climatological fields, such as vegetation type and
albedo, for an FV3 grid.
diff --git a/sorc/vcoord_gen.fd/docs/user_guide.md b/sorc/vcoord_gen.fd/docs/user_guide.md
index 69aae72a5..42916984c 100644
--- a/sorc/vcoord_gen.fd/docs/user_guide.md
+++ b/sorc/vcoord_gen.fd/docs/user_guide.md
@@ -1,6 +1,8 @@
# vcoord_gen
+# Introduction
+
Generates hybrid coordinate parameters from fields such as surface
pressure, model top and the number of vertical levels. Outputs the
'ak' and 'bk' parameters used by the forecast model to define the