From effa47170ecbac240fa7c16754d4c744810ded3d Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Fri, 12 Feb 2021 10:33:47 -0700 Subject: [PATCH 1/3] doxygen for model_grid.F90 --- sorc/chgres_cube.fd/model_grid.F90 | 103 ++++++++++++++++++++--------- 1 file changed, 72 insertions(+), 31 deletions(-) diff --git a/sorc/chgres_cube.fd/model_grid.F90 b/sorc/chgres_cube.fd/model_grid.F90 index 0e4221e03..bd34c1224 100644 --- a/sorc/chgres_cube.fd/model_grid.F90 +++ b/sorc/chgres_cube.fd/model_grid.F90 @@ -102,7 +102,7 @@ module model_grid contains -!> @brief Setup the esmf grid object for the input grid. +!> Setup the esmf grid object for the input grid. !! !! If the input source is tiled fv3 restart or history data, the grid is !! created by reading the mosaic and grid files. If the input source is @@ -110,6 +110,9 @@ module model_grid !! spectral gfs global gaussian sigio/sfcio, the grid is setup by !! computing lat/lons using the sp library. !! +!! @param localpet +!! @param npets +!! @author George Gayno NCEP/EMC subroutine define_input_grid(localpet, npets) use program_setup, only : input_type, external_model @@ -133,16 +136,17 @@ subroutine define_input_grid(localpet, npets) end subroutine define_input_grid -!-------------------------------------------------------------------------- -! Define grid object for input data on global gaussian grids. -! Recognized file formats: -! -! - fv3gfs nemsio -! - spectral gfs nemsio (starting July 19, 2017) -! - spectral gfs sigio (prior to July 19, 2017) -! - spectral gfs sfcio (prior to July 19, 2017) -!-------------------------------------------------------------------------- - +!> Define grid object for input data on global gaussian grids. +!! +!! Recognized file formats: +!! - fv3gfs nemsio +!! - spectral gfs nemsio (starting July 19, 2017) +!! - spectral gfs sigio (prior to July 19, 2017) +!! - spectral gfs sfcio (prior to July 19, 2017) +!! +!! @param localpet +!! @param npets +!! @author George Gayno NCEP/EMC subroutine define_input_grid_gaussian(localpet, npets) use nemsio_module @@ -391,6 +395,11 @@ subroutine define_input_grid_gaussian(localpet, npets) end subroutine define_input_grid_gaussian +!> Define input grid. +!! +!! @param localpet +!! @param npets +!! @author George Gayno NCEP/EMC subroutine define_input_grid_mosaic(localpet, npets) use netcdf @@ -598,11 +607,12 @@ subroutine define_input_grid_mosaic(localpet, npets) end subroutine define_input_grid_mosaic -!-------------------------------------------------------------------------- -! Define grid object for GFS grib2 data. Only works for data on -! global lat/lon or gaussian grids. -!-------------------------------------------------------------------------- - +!> Define grid object for GFS grib2 data. Only works for data on +!! global lat/lon or gaussian grids. +!! +!! @param localpet +!! @param npets +!! @author George Gayno NCEP/EMC subroutine define_input_grid_gfs_grib2(localpet, npets) use wgrib2api @@ -786,6 +796,11 @@ subroutine define_input_grid_gfs_grib2(localpet, npets) end subroutine define_input_grid_gfs_grib2 +!> Define input grid. +!! +!! @param localpet +!! @param npets +!! @author George Gayno NCEP/EMC subroutine define_input_grid_grib2(localpet, npets) use mpi @@ -1079,9 +1094,11 @@ subroutine define_input_grid_grib2(localpet, npets) end subroutine define_input_grid_grib2 -!> @brief -!! Setup the esmf grid object for the target grid. +!> Setup the esmf grid object for the target grid. !! +!! @param localpet +!! @param npets +!! @author George Gayno NCEP/EMC subroutine define_target_grid(localpet, npets) use netcdf @@ -1352,10 +1369,23 @@ subroutine define_target_grid(localpet, npets) end subroutine define_target_grid -!----------------------------------------------------------------------- -! Read model lat/lons for a single tile from the "grid" file. -!----------------------------------------------------------------------- - +!> Read model lat/lons for a single tile from the "grid" file. +!! +!! @param mosaic_file +!! @param orog_dir +!! @param num_tiles +!! @param tile +!! @param i_tile +!! @param j_tile +!! @param ip1_tile +!! @param jp1_tile +!! @param latitude +!! @param latitude_s +!! @param latitude_w +!! @param longitude +!! @param longitude_s +!! @param longitude_w +!! @author George Gayno NCEP/EMC subroutine get_model_latlons(mosaic_file, orog_dir, num_tiles, tile, & i_tile, j_tile, ip1_tile, jp1_tile, & latitude, latitude_s, latitude_w, & @@ -1498,11 +1528,16 @@ subroutine get_model_latlons(mosaic_file, orog_dir, num_tiles, tile, & end subroutine get_model_latlons - !---------------------------------------------------------------------------------------- -! For grids with equal cell sizes (e.g., lambert conformal), get lat and on of the grid -! cell corners -!---------------------------------------------------------------------------------------- - +!> For grids with equal cell sizes (e.g., lambert conformal), get lat +!! and on of the grid cell corners +!! @param latitude +!! @param longitude +!! @param latitude_sw +!! @param longitude_sw +!! @param dx +!! @param clb +!! @param cub +!! @author George Gayno NCEP/EMC subroutine get_cell_corners( latitude, longitude, latitude_sw, longitude_sw, dx,clb,cub) implicit none @@ -1576,10 +1611,15 @@ subroutine get_cell_corners( latitude, longitude, latitude_sw, longitude_sw, dx, end subroutine get_cell_corners -!----------------------------------------------------------------------- -! Read the model land mask and terrain for a single tile. -!----------------------------------------------------------------------- +!> Read the model land mask and terrain for a single tile. +!! +!! @param orog_file +!! @param idim +!! @param jdim +!! @param mask +!! @param terrain +!! @author George Gayno NCEP/EMC subroutine get_model_mask_terrain(orog_file, idim, jdim, mask, terrain) use netcdf @@ -1644,8 +1684,9 @@ subroutine get_model_mask_terrain(orog_file, idim, jdim, mask, terrain) end subroutine get_model_mask_terrain -!> @brief Deallocate all esmf grid objects. +!> Deallocate all esmf grid objects. !! +!! @author George Gayno NCEP/EMC subroutine cleanup_input_target_grid_data implicit none From 884ed85c09a2fb802f9e9b853298b8179d5ba336 Mon Sep 17 00:00:00 2001 From: Edward Hartnett Date: Thu, 18 Feb 2021 06:07:19 -0700 Subject: [PATCH 2/3] doxygen updates --- sorc/chgres_cube.fd/model_grid.F90 | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/sorc/chgres_cube.fd/model_grid.F90 b/sorc/chgres_cube.fd/model_grid.F90 index bd34c1224..4e2151c8c 100644 --- a/sorc/chgres_cube.fd/model_grid.F90 +++ b/sorc/chgres_cube.fd/model_grid.F90 @@ -1,10 +1,9 @@ !> @file -!! @brief Specify input and target model grids -!! -!! @author gayno NCEP/EMC +!! @brief Specify input and target model grids. !! !! Specify input and target model grids via ESMF grid objects. !! +!! @author gayno NCEP/EMC module model_grid use esmf @@ -104,13 +103,13 @@ module model_grid !> Setup the esmf grid object for the input grid. !! -!! If the input source is tiled fv3 restart or history data, the grid is -!! created by reading the mosaic and grid files. If the input source is -!! fv3 global gaussian nemsio, spectral gfs global gaussian nemsio, or -!! spectral gfs global gaussian sigio/sfcio, the grid is setup by -!! computing lat/lons using the sp library. +!! If the input source is tiled fv3 restart or history data, the grid +!! is created by reading the mosaic and grid files. If the input +!! source is fv3 global gaussian nemsio, spectral gfs global gaussian +!! nemsio, or spectral gfs global gaussian sigio/sfcio, the grid is +!! setup by computing lat/lons using the sp library. !! -!! @param localpet +!! @param localpet ESMF local persistent execution thread !! @param npets !! @author George Gayno NCEP/EMC subroutine define_input_grid(localpet, npets) @@ -144,7 +143,7 @@ end subroutine define_input_grid !! - spectral gfs sigio (prior to July 19, 2017) !! - spectral gfs sfcio (prior to July 19, 2017) !! -!! @param localpet +!! @param localpet ESMF local persistent execution thread !! @param npets !! @author George Gayno NCEP/EMC subroutine define_input_grid_gaussian(localpet, npets) @@ -397,7 +396,7 @@ end subroutine define_input_grid_gaussian !> Define input grid. !! -!! @param localpet +!! @param localpet ESMF local persistent execution thread !! @param npets !! @author George Gayno NCEP/EMC subroutine define_input_grid_mosaic(localpet, npets) @@ -610,7 +609,7 @@ end subroutine define_input_grid_mosaic !> Define grid object for GFS grib2 data. Only works for data on !! global lat/lon or gaussian grids. !! -!! @param localpet +!! @param localpet ESMF local persistent execution thread !! @param npets !! @author George Gayno NCEP/EMC subroutine define_input_grid_gfs_grib2(localpet, npets) @@ -798,7 +797,7 @@ end subroutine define_input_grid_gfs_grib2 !> Define input grid. !! -!! @param localpet +!! @param localpet ESMF local persistent execution thread !! @param npets !! @author George Gayno NCEP/EMC subroutine define_input_grid_grib2(localpet, npets) @@ -1096,7 +1095,7 @@ end subroutine define_input_grid_grib2 !> Setup the esmf grid object for the target grid. !! -!! @param localpet +!! @param localpet ESMF local persistent execution thread !! @param npets !! @author George Gayno NCEP/EMC subroutine define_target_grid(localpet, npets) @@ -1529,7 +1528,8 @@ subroutine get_model_latlons(mosaic_file, orog_dir, num_tiles, tile, & end subroutine get_model_latlons !> For grids with equal cell sizes (e.g., lambert conformal), get lat -!! and on of the grid cell corners +!! and on of the grid cell corners. +!! !! @param latitude !! @param longitude !! @param latitude_sw From b9b28490d7e32e219ce0a3b38b7a9b069141628c Mon Sep 17 00:00:00 2001 From: George Gayno Date: Thu, 18 Feb 2021 17:02:52 +0000 Subject: [PATCH 3/3] Update doxygen for each routine in module chgres_cube/model_grid.F90 --- sorc/chgres_cube.fd/model_grid.F90 | 104 +++++++++++++++-------------- 1 file changed, 54 insertions(+), 50 deletions(-) diff --git a/sorc/chgres_cube.fd/model_grid.F90 b/sorc/chgres_cube.fd/model_grid.F90 index 4e2151c8c..c245ca5cb 100644 --- a/sorc/chgres_cube.fd/model_grid.F90 +++ b/sorc/chgres_cube.fd/model_grid.F90 @@ -3,7 +3,7 @@ !! !! Specify input and target model grids via ESMF grid objects. !! -!! @author gayno NCEP/EMC +!! @author George Gayno NCEP/EMC module model_grid use esmf @@ -101,7 +101,7 @@ module model_grid contains -!> Setup the esmf grid object for the input grid. +!> Driver routine to setup the esmf grid object for the input grid. !! !! If the input source is tiled fv3 restart or history data, the grid !! is created by reading the mosaic and grid files. If the input @@ -109,8 +109,8 @@ module model_grid !! nemsio, or spectral gfs global gaussian sigio/sfcio, the grid is !! setup by computing lat/lons using the sp library. !! -!! @param localpet ESMF local persistent execution thread -!! @param npets +!! @param [in] localpet ESMF local persistent execution thread +!! @param [in] npets Number of persistent execution threads !! @author George Gayno NCEP/EMC subroutine define_input_grid(localpet, npets) @@ -143,8 +143,8 @@ end subroutine define_input_grid !! - spectral gfs sigio (prior to July 19, 2017) !! - spectral gfs sfcio (prior to July 19, 2017) !! -!! @param localpet ESMF local persistent execution thread -!! @param npets +!! @param [in] localpet ESMF local persistent execution thread +!! @param [in] npets Number of persistent execution threads. !! @author George Gayno NCEP/EMC subroutine define_input_grid_gaussian(localpet, npets) @@ -394,10 +394,11 @@ subroutine define_input_grid_gaussian(localpet, npets) end subroutine define_input_grid_gaussian -!> Define input grid. +!> Define input grid for tiled data using the 'mosaic', +!! 'grid' and orography files. !! !! @param localpet ESMF local persistent execution thread -!! @param npets +!! @param npets Total number of persistent execution threads !! @author George Gayno NCEP/EMC subroutine define_input_grid_mosaic(localpet, npets) @@ -606,11 +607,11 @@ subroutine define_input_grid_mosaic(localpet, npets) end subroutine define_input_grid_mosaic -!> Define grid object for GFS grib2 data. Only works for data on +!> Define input grid object for GFS grib2 data. Only works for data on !! global lat/lon or gaussian grids. !! -!! @param localpet ESMF local persistent execution thread -!! @param npets +!! @param [in] localpet ESMF local persistent execution thread +!! @param [in] npets Number of persistent execution threads !! @author George Gayno NCEP/EMC subroutine define_input_grid_gfs_grib2(localpet, npets) @@ -795,11 +796,12 @@ subroutine define_input_grid_gfs_grib2(localpet, npets) end subroutine define_input_grid_gfs_grib2 -!> Define input grid. +!> Define input grid object for non-GFS grib2 data. !! -!! @param localpet ESMF local persistent execution thread -!! @param npets -!! @author George Gayno NCEP/EMC +!! @param [in] localpet ESMF local persistent execution thread +!! @param [in] npets Number of persistent execution threads +!! @author Larissa Reames +!! @author Jeff Beck subroutine define_input_grid_grib2(localpet, npets) use mpi @@ -1095,8 +1097,8 @@ end subroutine define_input_grid_grib2 !> Setup the esmf grid object for the target grid. !! -!! @param localpet ESMF local persistent execution thread -!! @param npets +!! @param [in] localpet ESMF local persistent execution thread +!! @param [in] npets Number of persistent execution threads !! @author George Gayno NCEP/EMC subroutine define_target_grid(localpet, npets) @@ -1368,22 +1370,23 @@ subroutine define_target_grid(localpet, npets) end subroutine define_target_grid -!> Read model lat/lons for a single tile from the "grid" file. +!> Read model lat/lons for a single tile from the "grid" +!! specificaton file. !! -!! @param mosaic_file -!! @param orog_dir -!! @param num_tiles -!! @param tile -!! @param i_tile -!! @param j_tile -!! @param ip1_tile -!! @param jp1_tile -!! @param latitude -!! @param latitude_s -!! @param latitude_w -!! @param longitude -!! @param longitude_s -!! @param longitude_w +!! @param [in] mosaic_file The mosaic file associated with the 'grid' files. +!! @param [in] orog_dir Directory containing the 'grid' and orography files. +!! @param [in] num_tiles Total number of tiles +!! @param [in] tile Tile number to be read +!! @param [in] i_tile "i" dimension of the tile +!! @param [in] j_tile "j" dimension of the tile +!! @param [in] ip1_tile "i" dimension of the tile plus 1 +!! @param [in] jp1_tile "j" dimension of the tile plus 1 +!! @param [out] latitude grid box center latitude +!! @param [out] latitude_s latitude of 'south' edge of grid box +!! @param [out] latitude_w latitude of 'west' edge of grid box +!! @param [out] longitude grid box center longitude +!! @param [out] longitude_s longitude of 'south' edge of grid box +!! @param [out] longitude_w longitude of 'west' edge of grid box !! @author George Gayno NCEP/EMC subroutine get_model_latlons(mosaic_file, orog_dir, num_tiles, tile, & i_tile, j_tile, ip1_tile, jp1_tile, & @@ -1527,17 +1530,18 @@ subroutine get_model_latlons(mosaic_file, orog_dir, num_tiles, tile, & end subroutine get_model_latlons -!> For grids with equal cell sizes (e.g., lambert conformal), get lat -!! and on of the grid cell corners. +!> For grids with equal cell sizes (e.g., lambert conformal), get +!! latitude and longitude of the grid cell corners. !! -!! @param latitude -!! @param longitude -!! @param latitude_sw -!! @param longitude_sw -!! @param dx -!! @param clb -!! @param cub -!! @author George Gayno NCEP/EMC +!! @param [in] latitude grid box center latitude +!! @param [in] longitude grid box center longitude +!! @param [inout] latitude_sw latitude of the 'southwest' corner of grid box +!! @param [inout] longitude_sw longitude of the 'southwest' corner of grid box +!! @param [in] dx grid cell side size in meters +!! @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 get_cell_corners( latitude, longitude, latitude_sw, longitude_sw, dx,clb,cub) implicit none @@ -1545,7 +1549,7 @@ subroutine get_cell_corners( latitude, longitude, latitude_sw, longitude_sw, dx, real(esmf_kind_r8), intent(inout), pointer :: latitude_sw(:,:) real(esmf_kind_r8), intent(in) :: longitude(i_input, j_input) real(esmf_kind_r8), intent(inout), pointer :: longitude_sw(:,:) - real(esmf_kind_r8), intent(in) :: dx !grid cell side size (m) + real(esmf_kind_r8), intent(in) :: dx integer, intent(in) :: clb(2), cub(2) @@ -1611,14 +1615,14 @@ subroutine get_cell_corners( latitude, longitude, latitude_sw, longitude_sw, dx, end subroutine get_cell_corners - -!> Read the model land mask and terrain for a single tile. +!> Read the model land mask and terrain for a single tile +!! from the orography file. !! -!! @param orog_file -!! @param idim -!! @param jdim -!! @param mask -!! @param terrain +!! @param [in] orog_file Path/name of orography file +!! @param [in] idim "i" dimension of tile +!! @param [in] jdim "j" dimension of tile +!! @param [out] mask land mask of tile +!! @param [out] terrain terrain height of tile !! @author George Gayno NCEP/EMC subroutine get_model_mask_terrain(orog_file, idim, jdim, mask, terrain)