From 37db11c71062676b5ecb840e9173e881b1b1d6ad Mon Sep 17 00:00:00 2001 From: Edward Hartnett <38856240+edwardhartnett@users.noreply.github.com> Date: Wed, 10 Mar 2021 08:21:53 -0700 Subject: [PATCH] clearing doxygen warnings for sfc_climo_gen (#402) * clearing doxygen warnings for sfc_climo_gen * fixed names * turned on WARN_AS_ERROR on top level, fixed top-level doxygen warning * added comment --- docs/Doxyfile.in | 2 +- docs/user_guide.md | 3 +- sorc/sfc_climo_gen.fd/docs/Doxyfile.in | 2 +- sorc/sfc_climo_gen.fd/driver.F90 | 9 ++- sorc/sfc_climo_gen.fd/interp.F90 | 26 +++---- sorc/sfc_climo_gen.fd/model_grid.F90 | 71 ++++++++----------- sorc/sfc_climo_gen.fd/output.f90 | 9 ++- sorc/sfc_climo_gen.fd/program_setup.f90 | 93 ++++++++----------------- sorc/sfc_climo_gen.fd/search.f90 | 25 ++++--- sorc/sfc_climo_gen.fd/source_grid.F90 | 80 +++++++++------------ sorc/sfc_climo_gen.fd/utils.f90 | 16 +++++ 11 files changed, 146 insertions(+), 190 deletions(-) diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index c24cf6e38..ea0731b8e 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -733,7 +733,7 @@ WARN_LOGFILE = # WARN_AS_ERROR causes warnings to be treated as errors. -WARN_AS_ERROR = NO +WARN_AS_ERROR = YES #--------------------------------------------------------------------------- # Configuration options related to the input files diff --git a/docs/user_guide.md b/docs/user_guide.md index 75bc52b2d..f759d00c6 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -29,8 +29,7 @@ https://github.com/NOAA-EMC/UFS_UTILS. - fvcom_tools - 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 documentation](@ref - fvcom_readme). + in an FV3 surface restart file. - global_cycle - Updates the GFS surface conditions using external snow and sea ice diff --git a/sorc/sfc_climo_gen.fd/docs/Doxyfile.in b/sorc/sfc_climo_gen.fd/docs/Doxyfile.in index 0ff928ad3..77c39b379 100644 --- a/sorc/sfc_climo_gen.fd/docs/Doxyfile.in +++ b/sorc/sfc_climo_gen.fd/docs/Doxyfile.in @@ -733,7 +733,7 @@ WARN_LOGFILE = # WARN_AS_ERROR causes warnings to be treated as errors. -WARN_AS_ERROR = NO +WARN_AS_ERROR = YES #--------------------------------------------------------------------------- # Configuration options related to the input files diff --git a/sorc/sfc_climo_gen.fd/driver.F90 b/sorc/sfc_climo_gen.fd/driver.F90 index 8d06f1138..4f05d974a 100644 --- a/sorc/sfc_climo_gen.fd/driver.F90 +++ b/sorc/sfc_climo_gen.fd/driver.F90 @@ -1,6 +1,9 @@ !> @file -!! -!! Reads static surface data on a global lat/lon grid, +!! @brief Interpolates static surface data from lat/lon grid, +!! to FV3 model grid. +!! @author George Gayno + +!> Reads static surface data on a global lat/lon grid, !! interpolates the data to the fv3 model grid, and outputs the !! result in netcdf format. !! @@ -16,6 +19,8 @@ !! !! Outputs surface data on the model tiles in netcdf format. !! +!! @return 0 for success, error code otherwise. +!! @author George Gayno program driver use model_grid diff --git a/sorc/sfc_climo_gen.fd/interp.F90 b/sorc/sfc_climo_gen.fd/interp.F90 index 4afe5a0be..8c4b32621 100644 --- a/sorc/sfc_climo_gen.fd/interp.F90 +++ b/sorc/sfc_climo_gen.fd/interp.F90 @@ -1,13 +1,15 @@ !> @file !! @brief Read the input source data and interpolate it to the !! model grid. +!! @author George Gayno @date 2018 + +!> Read the input source data and interpolate it to the +!! model grid. !! -!! @author gayno @date 2018 -!! -!! @param[in] input_flle filename of input source data. !! @param[in] localpet this mpi task !! @param[in] method interpolation method.defined where mask=1 -!! +!! @param[in] input_file filename of input source data. +!! @author George Gayno @date 2018 subroutine interp(localpet, method, input_file) use esmf @@ -259,16 +261,16 @@ subroutine interp(localpet, method, input_file) end subroutine interp -!> Ensure consistent fields at land ice points +!> Ensure consistent fields at land ice points. !! Land ice is vegetation type 15 (variable landice). +!! output is Model field. +!! +!! @param[in] field Model field before adjustments for land ice. +!! @param[in] vegt Vegetation type on the model tile. +!! @param[inout] idim i dimension of model tile. +!! @param[inout] jdim j dimension of model tile. +!! @param[in] field_ch Field name. !! @author George Gayno NCEP/EMC -!! Usage: call adjust_for_landice(field, vegt, idim, jdim, field_ch) -!! output is Model field -!! @param field - Model field before adjustments for land ice. -!! @param field_ch - Field name. -!! @param i/jdim - i/j dimension of model tile. -!! @param vegt - Vegetation type on the model tile. - subroutine adjust_for_landice(field, vegt, idim, jdim, field_ch) use esmf diff --git a/sorc/sfc_climo_gen.fd/model_grid.F90 b/sorc/sfc_climo_gen.fd/model_grid.F90 index fbd611772..74763b1a1 100644 --- a/sorc/sfc_climo_gen.fd/model_grid.F90 +++ b/sorc/sfc_climo_gen.fd/model_grid.F90 @@ -1,34 +1,12 @@ !> @file -!! Defines the model grid. -!! @author gayno @date 2018 -!! -!! ### Public Subroutines: -!! - define_model_grid Defines esmf grid object for the -!! model grid. -!! - model_grid_cleanup Free up memory used in this module. -!! -!! ### Public variables: +!! @brief Defines the model grid. +!! @author George Gayno @date 2018 + +!> This module defines the model grid. !! !! Variables named with 'mdl' refer to the model grid. !! -!! - data_field_mdl ESMF field object that holds the -!! data interpolated to model grid. -!! - grid_mdl ESMF grid object for the model grid. -!! - grid_tiles Array of model grid tile names. -!! - i/j_mdl i/j dimensions of model tile. -!! - latitude_field_mdl ESMF field object that holds the -!! model grid latitude -!! - longitude_field_mdl ESMF field object that holds the -!! model grid longitude -!! - mdl_field_mdl ESMF field object that holds the -!! model land mask. -!! - missing Value assigned to undefined points -!! (i.e., ocean points for a land -!! field). -!! - num_tiles Total number of model grid tiles. -!! - vegt_field_mdl ESMF field object that holds the -!! vegetation type on the model grid. -!! +!! @author George Gayno @date 2018 module model_grid use esmf @@ -37,31 +15,41 @@ module model_grid private - character(len=5), allocatable, public :: grid_tiles(:) + character(len=5), allocatable, public :: grid_tiles(:) !< Array of model grid tile names. - integer, public :: i_mdl, j_mdl, ij_mdl, num_tiles + integer, public :: i_mdl !< i dimension of model tile. + integer, public :: j_mdl !< j dimension of model tile. + integer, public :: ij_mdl !< Total number of points on a model tile. + integer, public :: num_tiles !< Total number of model grid tiles. - real(kind=4), public :: missing = -999. + real(kind=4), public :: missing = -999. ! define model grid -!! @author gayno @date 2018 +!> Define model grid. !! !! Define the model grid from the mosaic and orography -!! files. Create the ESMF grid object for the model grid. +!! files. Create the ESMF grid object for the model grid. !! !! @param[in] localpet this mpi task !! @param[in] npets total number of mpi tasks -!! +!! @author George Gayno @date 2018 subroutine define_model_grid(localpet, npets) use esmf @@ -282,7 +270,6 @@ subroutine define_model_grid(localpet, npets) end subroutine define_model_grid !> Get model information -!! @author gayno @date 2018 !! !! Read model land/sea mask and lat/lon from the orography file. !! @@ -292,7 +279,7 @@ end subroutine define_model_grid !! @param[out] lon2d longitude !! @param[in] idim i dimension of the model tile !! @param[in] jdim j dimension of the model tile -!! +!! @author George Gayno @date 2018 subroutine get_model_info(orog_file, mask, lat2d, lon2d, idim, jdim) use esmf @@ -392,11 +379,11 @@ subroutine get_model_info(orog_file, mask, lat2d, lon2d, idim, jdim) end subroutine get_model_info -!> model grid cleanup -!! @author gayno @date 2018 +!> Model grid cleanup. !! !! Free up memory associated with this module. !! +!! @author George Gayno @date 2018 subroutine model_grid_cleanup implicit none diff --git a/sorc/sfc_climo_gen.fd/output.f90 b/sorc/sfc_climo_gen.fd/output.f90 index bd1e49fd8..7a61c9123 100644 --- a/sorc/sfc_climo_gen.fd/output.f90 +++ b/sorc/sfc_climo_gen.fd/output.f90 @@ -1,9 +1,8 @@ !> @file +!! @brief Output model data for a single tile and a single record. +!! @author George Gayno @date 2018 -!> output -!! @author gayno @date 2018 -!! -!! Output model data for a single tile and a single +!> Output model data for a single tile and a single !! record in netcdf format. !! !! @param[in] data_one_tile Data to be output (single tile). @@ -15,7 +14,7 @@ !! @param[in] record Record number to be output. !! @param[in] tile Tile number. !! @param[in] time Time period to be output. -!! +!! @author George Gayno @date 2018 subroutine output(data_one_tile, lat_one_tile, lon_one_tile, i_mdl, j_mdl, & tile, record, time, field_idx) diff --git a/sorc/sfc_climo_gen.fd/program_setup.f90 b/sorc/sfc_climo_gen.fd/program_setup.f90 index a54e83059..cc35c36f4 100644 --- a/sorc/sfc_climo_gen.fd/program_setup.f90 +++ b/sorc/sfc_climo_gen.fd/program_setup.f90 @@ -1,13 +1,8 @@ !> @file +!! @brief Program setup. +!! @author George Gayno @date 2018 -!> program setup -!! @author gayno @date 2018 -!! -!! Set up program execution -!! -!! Public Subroutines: -!! ------------------- -!! - read_setup_namelist Reads configuration namelist +!> Set up program execution !! !! Public variables: !! ----------------- @@ -19,76 +14,44 @@ !! However, vegetation type must always be processed as it defines !! landice points. !! -!! - halo Number of row/cols defining the lateral -!! boundary halo. Used for regionanl -!! nests. -!! - input_facsf_file File containing input fractional -!! coverage data for strong zenith angle -!! dependent albedo. -!! - input_vegetation_greenness_ File containing input vegetation -!! - file greenness data. -!! - input_leaf_area_index_file File containing input leaf area index -!! data. -!! - input_maximum_snow_albedo_file File containing input maximum snow -!! albedo data. -!! - input_snowfree_albedo_file File containing input snow-free -!! albedo data. -!! - input_soil_type_file File containing input soil type data. -!! - input_slope_type_file File containing input slope type data. -!! - input_substrate_temperature_file File containing input soil substrate -!! temperature data. -!! - input_vegetation_type_file File containing input vegetation type data. -!! - leaf_area_index_method Interpolation method for leaf area index. -!! Conservative or bilinear (default). -!! - maximum snow albedo_method Interpolation method for max snow albedo. -!! Conservative or bilinear (default). -!! - mosaic_file_mdl Model grid mosaic file -!! - orog_dir_mdl Directory containing the model grid -!! orography files. -!! - orog_files_mdl Model grid orography filenames. -!! - snowfree_albedo_method Interpolation method for snowfree albedo. -!! Conservative or bilinear (default). -!! - vegetation_greenness_ Interpolation method for vegetation -!! - method greenness. Conservative or bilinear. -!! Default is bilinear. -!! +!! @author George Gayno @date 2018 module program_setup implicit none private - character(len=500), public :: input_leaf_area_index_file = "NULL" - character(len=500), public :: input_facsf_file = "NULL" - character(len=500), public :: input_substrate_temperature_file = "NULL" - character(len=500), public :: input_maximum_snow_albedo_file = "NULL" - character(len=500), public :: input_snowfree_albedo_file = "NULL" - character(len=500), public :: input_slope_type_file = "NULL" - character(len=500), public :: input_soil_type_file = "NULL" - character(len=500), public :: input_vegetation_type_file = "NULL" - character(len=500), public :: input_vegetation_greenness_file = "NULL" - character(len=500), public :: mosaic_file_mdl = "NULL" - character(len=500), public :: orog_dir_mdl = "NULL" - character(len=500), public :: orog_files_mdl(6) = "NULL" - - character(len=50), public :: leaf_area_index_method='bilinear' - character(len=50), public :: maximum_snow_albedo_method='bilinear' - character(len=50), public :: snowfree_albedo_method='bilinear' - character(len=50), public :: vegetation_greenness_method='bilinear' - - integer, public :: halo = 0 + character(len=500), public :: input_leaf_area_index_file = "NULL" !< File containing input leaf area index data. + character(len=500), public :: input_facsf_file = "NULL" !< File containing input fractional + !! coverage data for strong zenith angle + !! dependent albedo. + character(len=500), public :: input_substrate_temperature_file = "NULL" !< File containing input soil substrate temperature data. + character(len=500), public :: input_maximum_snow_albedo_file = "NULL" !< File containing input maximum snow albedo data. + character(len=500), public :: input_snowfree_albedo_file = "NULL" !< File containing input snow-free albedo data. + character(len=500), public :: input_slope_type_file = "NULL" !< File containing input slope type data. + character(len=500), public :: input_soil_type_file = "NULL" !< File containing input soil type data. + character(len=500), public :: input_vegetation_type_file = "NULL" !< File containing input vegetation type data. + character(len=500), public :: input_vegetation_greenness_file = "NULL" !< File containing input vegetation greenness data. + character(len=500), public :: mosaic_file_mdl = "NULL" !< Model grid mosaic file. + character(len=500), public :: orog_dir_mdl = "NULL" !< Directory containing the model grid orography files. + character(len=500), public :: orog_files_mdl(6) = "NULL" !< Model grid orography filenames. + + character(len=50), public :: leaf_area_index_method='bilinear' !< Interpolation method for leaf area index. Conservative or bilinear (default). + character(len=50), public :: maximum_snow_albedo_method='bilinear' !< Interpolation method for max snow albedo. Conservative or bilinear (default). + character(len=50), public :: snowfree_albedo_method='bilinear' !< Interpolation method for snowfree albedo. Conservative or bilinear (default). + character(len=50), public :: vegetation_greenness_method='bilinear' !< Interpolation method for vegetation greenness. Conservative or bilinear (default). + + integer, public :: halo = 0 !< Number of row/cols defining the lateral + !! boundary halo. Used for regional nests. public :: read_setup_namelist contains -!> read setup namelist -!! @author gayno @date 2018 -!! -!! Read program setup namelist +!> Read program setup namelist !! !! @param[in] localpet mpi task number -!! +!! @author George Gayno @date 2018 subroutine read_setup_namelist(localpet) use mpi diff --git a/sorc/sfc_climo_gen.fd/search.f90 b/sorc/sfc_climo_gen.fd/search.f90 index 6813ab761..ea3faef2a 100644 --- a/sorc/sfc_climo_gen.fd/search.f90 +++ b/sorc/sfc_climo_gen.fd/search.f90 @@ -1,22 +1,25 @@ !> @file -!! @author gayno @date 2018 -! +!! @brief Replace undefined values on the model grid with a valid +!! value at a nearby neighbor. +!! @author George Gayno @date 2018 + !> Replace undefined values on the model grid with a valid -!! value at a nearby neighbor. Undefined values are typically +!! value at a nearby neighbor. Undefined values are typically !! associated with isolated islands where there is no source data. !! Routine searches a neighborhood with a radius of 100 grid points. -!! If no valid value is found, a default value is used. This -!! routine works for one tile of a cubed sphere grid. It does -!! not consider valid values at adjacent faces. That is a future +!! If no valid value is found, a default value is used. This +!! routine works for one tile of a cubed sphere grid. It does +!! not consider valid values at adjacent faces. That is a future !! upgrade. !! -!! @param[in] idim/jdim i/j dimensions of tile -!! @param[in] tile tile number -!! @param[in] mask field bitmap. field defined where mask=1 -!! @param[in] field_name field name !! @param[inout] field - input: field before missing values are replaced !! - output: field after missing values are replaced -!! +!! @param[in] mask field bitmap. Field defined where mask=1 +!! @param[inout] idim i dimension of tile +!! @param[inout] jdim j dimension of tile +!! @param[in] tile tile number +!! @param[in] field_name field name +!! @author George Gayno @date 2018 subroutine search (field, mask, idim, jdim, tile, field_name) use mpi diff --git a/sorc/sfc_climo_gen.fd/source_grid.F90 b/sorc/sfc_climo_gen.fd/source_grid.F90 index 7058aa551..e6c2e6f82 100644 --- a/sorc/sfc_climo_gen.fd/source_grid.F90 +++ b/sorc/sfc_climo_gen.fd/source_grid.F90 @@ -1,34 +1,14 @@ !> @file -!! @author gayno @date 2018 -!! -!! Read grid specs, date information and land/sea mask for +!! @brief Read grid specs, date information and land/sea mask for +!! the source data that will be interpolated to the model grid. +!! @author George Gayno @date 2018 + +!> Read grid specs, date information and land/sea mask for !! the source data that will be interpolated to the model grid. !! Also, sets up the ESMF grid object for the source grid. !! Source grid is assumed to be global lat/lon. !! -!! Public Subroutines: -!! ------------------- -!! - define_source_grid() Defines esmf grid object for source -!! grid. Retrieves date and field -!! information from source file. -!! - source_grid_cleanup() Free up memory used in this module. -!! -!! Public variables: -!! ----------------- -!! -!! - day_of_rec Day of each time record with -!! respect to Jan 1. -!! - field_names Names of fields to be processed. -!! - grid_src ESMF grid object for the source grid. -!! - i_src i/j dimensions of the source grid. -!! - j_src i/j dimensions of the source grid. -!! - num_fields Number of fields in the file. Some -!! files have more than one (ex: -!! the 4-component albedo). -!! - num_records Number of fields times time records. -!! - num_time_recs Number of time records. -!! - source Original source of the data. -!! +!! @author George Gayno @date 2018 module source_grid use esmf @@ -38,31 +18,36 @@ module source_grid private - character(len=50), allocatable, public :: field_names(:) - character(len=75), public :: source + character(len=50), allocatable, public :: field_names(:) !< Names of fields to be processed. + character(len=75), public :: source !< Original source of the data. - integer, public :: i_src, j_src, num_records - integer, public :: num_time_recs - integer, public :: num_fields - integer, allocatable, public :: day_of_rec(:) + integer, public :: i_src !< i dimension of the source grid. + integer, public :: j_src !< j dimension of the source grid. + integer, public :: num_records !< Number of fields times time records. + integer, public :: num_time_recs !< Number of time records. + integer, public :: num_fields !< Number of fields in the file. Some + !! files have more than one (ex: + !! the 4-component albedo). + integer, allocatable, public :: day_of_rec(:) !< Day of each time record with + !! respect to Jan 1. - type(esmf_grid), public :: grid_src + type(esmf_grid), public :: grid_src !< ESMF grid object for the source grid. public :: define_source_grid public :: source_grid_cleanup contains -!> define source grid -!! @author gayno @date 2018 -!! -!! Read date information from input source data file. -!! Create esmf grid object for the source grid. -!! -!! @param[in] localpet mpi task number -!! @param[in] npets total number mpi tasks -!! @param[in] input_file file containing the source grid data. -!! + !> Defines esmf grid object for source grid. Retrieves date and field + !! information from source file. + !! + !! Read date information from input source data file. + !! Create esmf grid object for the source grid. + !! + !! @param[in] localpet mpi task number + !! @param[in] npets total number mpi tasks + !! @param[in] input_file file containing the source grid data. + !! @author George Gayno @date 2018 subroutine define_source_grid(localpet, npets, input_file) use mpi @@ -390,12 +375,9 @@ subroutine define_source_grid(localpet, npets, input_file) end subroutine define_source_grid -!> -!! source grid cleanup -!! @author gayno @date 2018 -!! -!! Free up memory associated with this module. -!! + !> Free up memory associated with this module. + !! + !! @author George Gayno @date 2018 subroutine source_grid_cleanup implicit none diff --git a/sorc/sfc_climo_gen.fd/utils.f90 b/sorc/sfc_climo_gen.fd/utils.f90 index 4c3e8ee7e..3aa24ac48 100644 --- a/sorc/sfc_climo_gen.fd/utils.f90 +++ b/sorc/sfc_climo_gen.fd/utils.f90 @@ -1,4 +1,10 @@ !> @file +!! @brief Utilities. +!! @author George Gayno @date 2018 + +!> Utilities. +!! +!! @author George Gayno @date 2018 module utils private @@ -8,6 +14,11 @@ module utils contains + !> Handle netCDF error codes. + !! + !! @param[in] err NetCDF return code. + !! @param[in] string Error message. + !! @author George Gayno @date 2018 subroutine netcdf_err( err, string ) use mpi @@ -29,6 +40,11 @@ subroutine netcdf_err( err, string ) return end subroutine netcdf_err + !> Handle errors. + !! + !! @param[in] string Error message. + !! @param[in] rc Error code. + !! @author George Gayno @date 2018 subroutine error_handler(string, rc) use mpi