Update xgrid.F90

exchange/xgrid.F90

@@ -3107,6 +3107,28 @@ end subroutine regen
 !#######################################################################
 
 !> @brief Changes sub-grid portion areas and/or number.
+!! @details (re)sets the fraction area of the side 2 component grid cell. 
+!!  The input is a 3d array of numbers between 0 and 1. It signifies the 
+!!  fraction of the component grid cell area which has a model-specific property.
+!!  This property is used for some sub-grid scale parametrization in the component model.
+!!  E.g., for the seaice component model, the quantity of seaice in each grid cell (i,j) 
+!!  is distibuted into N=grid%km partitions (ice categories) each parametrized with a weight (part_size) that add to 1. 
+!!  E.g., for 6+2 thickness (h) categories used in GFDL seaice models we have
+!!  given  hlim(1, ..., 8) = [1.0e-10, 0.1, 0.3, 0.7, 1.1, 1.5, 2.0, 2.5] (meters)
+!!  Caterory n=1     : h <= hlim(1), essentially no ice
+!!  Caterory n=2...7 : hlim(n-1) < h <= hlim(n) 
+!!  Caterory n=8     : hlim(n-1) < h   , unlimimitted ice thickness  
+!!  E.g., if seaice in grid cell (i,j) is parameterized as 10% open water, 0% category 1, 40% category 2 , 50% category 3 then we have
+!!  f(i,j,1:km) = part_size(i,j,1:8) = [0.1, 0.0, 0.4, 0.5, 0.0, 0.0, 0.0, 0.0]
+!!
+!! @param[in] f real(r8_kind) 3D array
+!! @param[in] grid_id 3 character grid ID
+!! @param[inout] xmap exchange grid
+!! 
+!! <br>Example usage:
+!! @code{.F90}
+!! call fms_xgrid_set_frac_area (Ice%part_size(isc:iec,jsc:jec,:) , 'OCN', xmap_sfc) (https://github.com/NOAA-GFDL/FMScoupler/blob/main/full/atm_land_ice_flux_exchange.F90#L1239)
+!! @endcode
 subroutine set_frac_area_sg(f, grid_id, xmap)
 real(r8_kind), dimension(:,:,:), intent(in)    :: f !< fraction area to be set
 character(len=3),                intent(in)    :: grid_id !< 3 character grid ID