Skip to content

Commit

Permalink
Merge pull request #1320 from Hallberg-NOAA/framework_arg_doc
Browse files Browse the repository at this point in the history 
Cleaned up framework argument documentation
  • Loading branch information
@marshallward
marshallward authored Feb 10, 2021
2 parents 51e8f5f + 28deefc commit 12a56bb
Show file tree
Hide file tree
Showing 4 changed files with 89 additions and 87 deletions.
121 changes: 62 additions & 59 deletions src/framework/MOM_coms_infra.F90
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,16 +93,16 @@ subroutine set_rootPE(pe)
!! is set to the list of all available PEs on the communicator. Setting the
!! list will trigger a rank synchronization unless the `no_sync` flag is set.
subroutine Set_PEList(pelist, no_sync)
integer, intent(in), optional :: pelist(:) !< List of
logical, intent(in), optional :: no_sync !< Do not sync after list update.
integer, optional, intent(in) :: pelist(:) !< List of PEs to set for communication
logical, optional, intent(in) :: no_sync !< Do not sync after list update.
call mpp_set_current_pelist(pelist, no_sync)
end subroutine Set_PEList

!> Retrieve the current PE list and any metadata if requested.
subroutine Get_PEList(pelist, name, commID)
integer, intent(out) :: pelist(:) !< List of PE IDs of the current PE list
character(len=*), intent(out), optional :: name !< Name of PE list
integer, intent(out), optional :: commID !< Communicator ID of PE list
integer, intent(out) :: pelist(:) !< List of PE IDs of the current PE list
character(len=*), optional, intent(out) :: name !< Name of PE list
integer, optional, intent(out) :: commID !< Communicator ID of PE list

call mpp_get_current_pelist(pelist, name, commiD)
end subroutine Get_PEList
Expand Down Expand Up @@ -311,134 +311,137 @@ end function field_chksum_real_4d

! sum_across_PEs wrappers

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of field across PEs, and return this sum in field.
subroutine sum_across_PEs_int4_0d(field, pelist)
integer(kind=int32), intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list
integer(kind=int32), intent(inout) :: field !< Value on this PE, and the sum across PEs upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, pelist)
end subroutine sum_across_PEs_int4_0d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of the values in corresponding positions of field across PEs, and return these sums in field.
subroutine sum_across_PEs_int4_1d(field, length, pelist)
integer(kind=int32), dimension(:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
integer(kind=int32), dimension(:), intent(inout) :: field !< The values to add, the sums upon return
integer, intent(in) :: length !< Number of elements in field to add
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, length, pelist)
end subroutine sum_across_PEs_int4_1d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of field across PEs, and return this sum in field.
subroutine sum_across_PEs_int8_0d(field, pelist)
integer(kind=int64), intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list
integer(kind=int64), intent(inout) :: field !< Value on this PE, and the sum across PEs upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, pelist)
end subroutine sum_across_PEs_int8_0d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of the values in corresponding positions of field across PEs, and return these sums in field.
subroutine sum_across_PEs_int8_1d(field, length, pelist)
integer(kind=int64), dimension(:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
integer(kind=int64), dimension(:), intent(inout) :: field !< The values to add, the sums upon return
integer, intent(in) :: length !< Number of elements in field to add
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, length, pelist)
end subroutine sum_across_PEs_int8_1d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of the values in corresponding positions of field across PEs, and return these sums in field.
subroutine sum_across_PEs_int8_2d(field, length, pelist)
integer(kind=int64), dimension(:,:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
integer(kind=int64), &
dimension(:,:), intent(inout) :: field !< The values to add, the sums upon return
integer, intent(in) :: length !< The total number of positions to sum, usually
!! the product of the array sizes.
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, length, pelist)
end subroutine sum_across_PEs_int8_2d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of field across PEs, and return this sum in field.
subroutine sum_across_PEs_real_0d(field, pelist)
real, intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list
real, intent(inout) :: field !< Value on this PE, and the sum across PEs upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, pelist)
end subroutine sum_across_PEs_real_0d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of the values in corresponding positions of field across PEs, and return these sums in field.
subroutine sum_across_PEs_real_1d(field, length, pelist)
real, dimension(:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
real, dimension(:), intent(inout) :: field !< The values to add, the sums upon return
integer, intent(in) :: length !< Number of elements in field to add
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, length, pelist)
end subroutine sum_across_PEs_real_1d

!> Find the sum of field across PEs, and update PEs with the sums.
!> Find the sum of the values in corresponding positions of field across PEs, and return these sums in field.
subroutine sum_across_PEs_real_2d(field, length, pelist)
real, dimension(:,:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
real, dimension(:,:), intent(inout) :: field !< The values to add, the sums upon return
integer, intent(in) :: length !< The total number of positions to sum, usually
!! the product of the array sizes.
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_sum(field, length, pelist)
end subroutine sum_across_PEs_real_2d

! max_across_PEs wrappers

!> Find the maximum value of field across PEs, and update PEs with the values.
!> Find the maximum value of field across PEs, and store this maximum in field.
subroutine max_across_PEs_int_0d(field, pelist)
integer, intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list
integer, intent(inout) :: field !< The values to compare, the maximum upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_max(field, pelist)
end subroutine max_across_PEs_int_0d

!> Find the maximum value of field across PEs, and update PEs with the values.
!> Find the maximum value of field across PEs, and store this maximum in field.
subroutine max_across_PEs_real_0d(field, pelist)
real, intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list
real, intent(inout) :: field !< The values to compare, the maximum upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_max(field, pelist)
end subroutine max_across_PEs_real_0d

!> Find the maximum value of field across PEs, and update PEs with the values.
!> Find the maximum values in each position of field across PEs, and store these minima in field.
subroutine max_across_PEs_real_1d(field, length, pelist)
real, dimension(:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
real, dimension(:), intent(inout) :: field !< The list of values being compared, with the
!! maxima in each position upon return
integer, intent(in) :: length !< Number of elements in field to compare
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_max(field, length, pelist)
end subroutine max_across_PEs_real_1d

! min_across_PEs wrappers

!> Find the minimum value of field across PEs, and update PEs with the values.
!> Find the minimum value of field across PEs, and store this minimum in field.
subroutine min_across_PEs_int_0d(field, pelist)
integer, intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list
integer, intent(inout) :: field !< The values to compare, the minimum upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_min(field, pelist)
end subroutine min_across_PEs_int_0d

!> Find the minimum value of field across PEs, and update PEs with the values.
!> Find the minimum value of field across PEs, and store this minimum in field.
subroutine min_across_PEs_real_0d(field, pelist)
real, intent(inout) :: field !< Input field
integer, intent(in), optional :: pelist(:) !< PE list

real, intent(inout) :: field !< The values to compare, the minimum upon return
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with
call mpp_min(field, pelist)
end subroutine min_across_PEs_real_0d

!> Find the minimum value of field across PEs, and update PEs with the values.
!> Find the minimum values in each position of field across PEs, and store these minima in field.
subroutine min_across_PEs_real_1d(field, length, pelist)
real, dimension(:), intent(inout) :: field !< Input field
integer, intent(in) :: length !< Length of field
integer, intent(in), optional :: pelist(:) !< PE list
real, dimension(:), intent(inout) :: field !< The list of values being compared, with the
!! minima in each position upon return
integer, intent(in) :: length !< Number of elements in field to compare
integer, optional, intent(in) :: pelist(:) !< List of PEs to work with

call mpp_min(field, length, pelist)
end subroutine min_across_PEs_real_1d

!> Initialize the model framework, including PE communication over a designated
!! communicator. If no communicator ID is provided, then the framework's
!! default communicator is used.
!> Initialize the model framework, including PE communication over a designated communicator.
!! If no communicator ID is provided, the framework's default communicator is used.
subroutine MOM_infra_init(localcomm)
integer, intent(in), optional :: localcomm !< Communicator ID to initialize
integer, optional, intent(in) :: localcomm !< Communicator ID to initialize
call fms_init(localcomm)
end subroutine

Expand Down
4 changes: 2 additions & 2 deletions src/framework/MOM_cpu_clock_infra.F90
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,13 +73,13 @@ end subroutine cpu_clock_end
!> Returns the integer handle for a named CPU clock.
integer function cpu_clock_id( name, synchro_flag, grain )
character(len=*), intent(in) :: name !< The unique name of the CPU clock
integer, intent(in), optional :: synchro_flag !< An integer flag that controls whether the PEs
integer, optional, intent(in) :: synchro_flag !< An integer flag that controls whether the PEs
!! are synchronized before the cpu clocks start counting.
!! Synchronization occurs before the start of a clock if this
!! is odd, while additional (expensive) statistics can set
!! for other values. If absent, the default is taken from the
!! settings for FMS.
integer, intent(in), optional :: grain !< The timing granularity for this clock, usually set to
integer, optional, intent(in) :: grain !< The timing granularity for this clock, usually set to
!! the values of CLOCK_COMPONENT, CLOCK_ROUTINE, CLOCK_LOOP, etc.

if (present(synchro_flag)) then
Expand Down
33 changes: 16 additions & 17 deletions src/framework/MOM_ensemble_manager_infra.F90
View file
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,13 @@ end subroutine ensemble_manager_init
!! associated with the current ensemble member.
subroutine ensemble_pelist_setup(concurrent, atmos_npes, ocean_npes, land_npes, ice_npes, &
Atm_pelist, Ocean_pelist, Land_pelist, Ice_pelist)
logical, intent(in) :: concurrent !< A logical flag, if True, then
!! ocean fast PEs are run concurrently with
!! slow PEs within the coupler.
integer, intent(in) :: atmos_npes !< The number of atmospheric (fast) PEs
integer, intent(in) :: ocean_npes !< The number of ocean (slow) PEs
integer, intent(in) :: land_npes !< The number of land PEs (fast)
integer, intent(in) :: ice_npes !< The number of ice (fast) PEs
logical, intent(in) :: concurrent !< A logical flag, if True, then ocean fast
!! PEs are run concurrently with
!! slow PEs within the coupler.
integer, intent(in) :: atmos_npes !< The number of atmospheric (fast) PEs
integer, intent(in) :: ocean_npes !< The number of ocean (slow) PEs
integer, intent(in) :: land_npes !< The number of land PEs (fast)
integer, intent(in) :: ice_npes !< The number of ice (fast) PEs
integer, dimension(:), intent(inout) :: Atm_pelist !< A list of Atm PEs
integer, dimension(:), intent(inout) :: Ocean_pelist !< A list of Ocean PEs
integer, dimension(:), intent(inout) :: Land_pelist !< A list of Land PEs
Expand Down Expand Up @@ -71,25 +71,24 @@ function get_ensemble_size()
end function get_ensemble_size

!> Returns the list of PEs associated with all ensemble members
!! Results are stored in the argument array which ust be large
!! Results are stored in the argument array which must be large
!! enough to contain the list. If the optional name argument is present,
!! the returned processor list are for a particular component (atmos, ocean ,land, ice)
subroutine get_ensemble_pelist(pelist, name)
integer, intent(inout) :: pelist(:,:) !< A processor list for all ensemble members
character(len=*), intent(in), optional :: name !< An optional component name (atmos, ocean, land, ice)
integer, intent(inout) :: pelist(:,:) !< A processor list for all ensemble members
character(len=*), optional, intent(in) :: name !< An optional component name (atmos, ocean, land, ice)

call FMS_get_ensemble_pelist(pelist,name)
call FMS_get_ensemble_pelist(pelist, name)

end subroutine get_ensemble_pelist

!> Returns the list of PEs associated with an ensemble filter application.
!! If the optional name argument is present, the returned list is for a
!! particular component (atmos, ocean ,land, ice)
!> Returns the list of PEs associated with the named ensemble filter application.
!! Valid component names include ('atmos', 'ocean', 'land', and 'ice')
subroutine get_ensemble_filter_pelist(pelist, name)
integer, intent(inout) :: pelist(:) !< A processor list for the ensemble filter
character(len=*), intent(in) :: name !< An optional component name (atmos, ocean, land, ice)
integer, intent(inout) :: pelist(:) !< A processor list for the ensemble filter
character(len=*), intent(in) :: name !< The component name (atmos, ocean, land, ice)

call FMS_get_Ensemble_filter_pelist(pelist,name)
call FMS_get_Ensemble_filter_pelist(pelist, name)

end subroutine get_ensemble_filter_pelist

Expand Down
18 changes: 9 additions & 9 deletions src/framework/MOM_time_manager.F90
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,15 @@ module MOM_time_manager

contains

!> This is an alternate implementation of the FMS function real_to_time_type that is accurate over
!! a larger range of input values. With 32 bit signed integers, this version should work over the
!! entire valid range (2^31 days or ~5.8835 million years) of time_types, whereas the standard
!! version in the FMS time_manager stops working for conversions of times greater than 2^31 seconds,
!! or ~68.1 years.
function real_to_time(x, err_msg)
type(time_type) :: real_to_time !< The output time as a time_type
real, intent(in) :: x !< The input time in real seconds.
character(len=*), intent(out), optional :: err_msg !< An optional returned error message.
!> Returns a time_type version of a real time in seconds, using an alternate implementation to the
!! FMS function real_to_time_type that is accurate over a larger range of input values. With 32 bit
!! signed integers, this version should work over the entire valid range (2^31 days or ~5.8835
!! million years) of time_types, whereas the standard version in the FMS time_manager stops working
!! for conversions of times greater than 2^31 seconds, or ~68.1 years.
type(time_type) function real_to_time(x, err_msg)
! type(time_type) :: real_to_time !< The output time as a time_type
real, intent(in) :: x !< The input time in real seconds.
character(len=*), optional, intent(out) :: err_msg !< An optional returned error message.

! Local variables
integer :: seconds, days, ticks
Expand Down

0 comments on commit 12a56bb

Please sign in to comment.