MOM_spatial_means.F90

Go to the documentation of this file.

module mom_spatial_means

!***********************************************************************
!*                   GNU General Public License                        *
!* This file is a part of MOM.                                         *
!*                                                                     *
!* MOM is free software; you can redistribute it and/or modify it and  *
!* are expected to follow the terms of the GNU General Public License  *
!* as published by the Free Software Foundation; either version 2 of   *
!* the License, or (at your option) any later version.                 *
!*                                                                     *
!* MOM is distributed in the hope that it will be useful, but WITHOUT  *
!* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY  *
!* or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public    *
!* License for more details.                                           *
!*                                                                     *
!* For the full text of the GNU General Public License,                *
!* write to: Free Software Foundation, Inc.,                           *
!*           675 Mass Ave, Cambridge, MA 02139, USA.                   *
!* or see:   http://www.gnu.org/licenses/gpl.html                      *
!***********************************************************************

use mom_coms, only : efp_type, operator(+), operator(-), assignment(=)
use mom_coms, only : efp_to_real, real_to_efp, efp_list_sum_across_pes
use mom_coms, only : reproducing_sum
use mom_coms, only : query_efp_overflow_error, reset_efp_overflow_error
use mom_error_handler, only : mom_error, note, warning, fatal, is_root_pe
use mom_file_parser, only : get_param, log_version, param_file_type
use mom_grid, only : ocean_grid_type
use mom_verticalgrid, only : verticalgrid_type

implicit none ; private

#include <MOM_memory.h>

public :: global_i_mean, global_j_mean
public :: global_area_mean, global_layer_mean
public :: global_area_integral
public :: global_volume_mean
public :: adjust_area_mean_to_zero

contains

function global_area_mean(var,G)
  type(ocean_grid_type),             intent(in)  :: G    !< The ocean's grid structure
  real, dimension(SZI_(G), SZJ_(G)), intent(in)  :: var
  real, dimension(SZI_(G), SZJ_(G))              :: tmpForSumming
  real :: global_area_mean

  integer :: i, j, is, ie, js, je
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec

  tmpforsumming(:,:) = 0.
  do j=js,je ; do i=is, ie
    tmpforsumming(i,j) = ( var(i,j) * (g%areaT(i,j) * g%mask2dT(i,j)) )
  enddo ; enddo
  global_area_mean = reproducing_sum( tmpforsumming ) * g%IareaT_global

end function global_area_mean

function global_area_integral(var,G)
  type(ocean_grid_type),             intent(in)  :: G    !< The ocean's grid structure
  real, dimension(SZI_(G), SZJ_(G)), intent(in)  :: var
  real, dimension(SZI_(G), SZJ_(G))              :: tmpForSumming
  real :: global_area_integral

  integer :: i, j, is, ie, js, je
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec

  tmpforsumming(:,:) = 0.
  do j=js,je ; do i=is, ie
    tmpforsumming(i,j) = ( var(i,j) * (g%areaT(i,j) * g%mask2dT(i,j)) )
  enddo ; enddo
  global_area_integral = reproducing_sum( tmpforsumming )

end function global_area_integral

function global_layer_mean(var, h, G, GV)
  type(ocean_grid_type),                     intent(in)  :: G    !< The ocean's grid structure
  type(verticalgrid_type),                   intent(in)  :: GV   !< The ocean's vertical grid structure
  real, dimension(SZI_(G),SZJ_(G),SZK_(GV)), intent(in)  :: var
  real, dimension(SZI_(G),SZJ_(G),SZK_(GV)), intent(in)  :: h    !< Layer thicknesses, in H (usually m or kg m-2)
  real, dimension(SZK_(GV))                   :: global_layer_mean

  real, dimension(SZI_(G), SZJ_(G), SZK_(GV)) :: tmpForSumming, weight
  real, dimension(SZK_(GV)) :: scalarij, weightij
  real, dimension(SZK_(GV)) :: global_temp_scalar, global_weight_scalar
  integer :: i, j, k, is, ie, js, je, nz
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = gv%ke

  tmpforsumming(:,:,:) = 0. ; weight(:,:,:) = 0.

  do k=1,nz ; do j=js,je ; do i=is,ie
    weight(i,j,k)  =  h(i,j,k) * (g%areaT(i,j) * g%mask2dT(i,j))
    tmpforsumming(i,j,k) =  var(i,j,k) * weight(i,j,k)
  enddo ; enddo ; enddo

  global_temp_scalar   = reproducing_sum(tmpforsumming,sums=scalarij)
  global_weight_scalar = reproducing_sum(weight,sums=weightij)

  do k=1, nz
    global_layer_mean(k) = scalarij(k) / weightij(k)
  enddo

end function global_layer_mean

function global_volume_mean(var, h, G, GV)
  type(ocean_grid_type),                     intent(in)  :: G    !< The ocean's grid structure
  type(verticalgrid_type),                   intent(in)  :: GV   !< The ocean's vertical grid structure
  real, dimension(SZI_(G),SZJ_(G),SZK_(GV)), intent(in)  :: var
  real, dimension(SZI_(G),SZJ_(G),SZK_(GV)), intent(in)  :: h    !< Layer thicknesses, in H (usually m or kg m-2)
  real :: global_volume_mean

  real :: weight_here
  real, dimension(SZI_(G), SZJ_(G)) :: tmpForSumming, sum_weight
  integer :: i, j, k, is, ie, js, je, nz
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = gv%ke

  tmpforsumming(:,:) = 0. ; sum_weight(:,:) = 0.

  do k=1,nz ; do j=js,je ; do i=is,ie
    weight_here  =  h(i,j,k) * (g%areaT(i,j) * g%mask2dT(i,j))
    tmpforsumming(i,j) = tmpforsumming(i,j) + var(i,j,k) * weight_here
    sum_weight(i,j) = sum_weight(i,j) + weight_here
  enddo ; enddo ; enddo
  global_volume_mean = (reproducing_sum(tmpforsumming)) / &
                       (reproducing_sum(sum_weight))

end function global_volume_mean


subroutine global_i_mean(array, i_mean, G, mask)
  type(ocean_grid_type),            intent(inout) :: G    !< The ocean's grid structure
  real, dimension(SZI_(G),SZJ_(G)), intent(in)    :: array
  real, dimension(SZJ_(G)),         intent(out)   :: i_mean
  real, dimension(SZI_(G),SZJ_(G)), optional, intent(in) :: mask

!    This subroutine determines the global mean of a field along rows of
!  constant i, returning it in a 1-d array using the local indexing.

! Arguments: array - The 2-d array whose i-mean is to be taken.
!  (out)     i_mean - Global mean of array along its i-axis.
!  (in)      G - The ocean's grid structure.
!  (in)      mask - An array used for weighting the i-mean.

  type(efp_type), allocatable, dimension(:) :: asum, mask_sum
  real :: mask_sum_r
  integer :: is, ie, js, je, idg_off, jdg_off
  integer :: i, j

  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec
  idg_off = g%idg_offset ; jdg_off = g%jdg_offset

  call reset_efp_overflow_error()

  allocate(asum(g%jsg:g%jeg))
  if (present(mask)) then
    allocate(mask_sum(g%jsg:g%jeg))

    do j=g%jsg,g%jeg
      asum(j) = real_to_efp(0.0) ; mask_sum(j) = real_to_efp(0.0)
    enddo

    do i=is,ie ; do j=js,je
      asum(j+jdg_off) = asum(j+jdg_off) + real_to_efp(array(i,j)*mask(i,j))
      mask_sum(j+jdg_off) = mask_sum(j+jdg_off) + real_to_efp(mask(i,j))
    enddo ; enddo

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_i_mean overflow error occurred before sums across PEs.")

    call efp_list_sum_across_pes(asum(g%jsg:g%jeg), g%jeg-g%jsg+1)
    call efp_list_sum_across_pes(mask_sum(g%jsg:g%jeg), g%jeg-g%jsg+1)

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_i_mean overflow error occurred during sums across PEs.")

    do j=js,je
      mask_sum_r = efp_to_real(mask_sum(j+jdg_off))
      if (mask_sum_r == 0.0 ) then ; i_mean(j) = 0.0 ; else
        i_mean(j) = efp_to_real(asum(j+jdg_off)) / mask_sum_r
      endif
    enddo

    deallocate(mask_sum)
  else
    do j=g%jsg,g%jeg ; asum(j) = real_to_efp(0.0) ; enddo

    do i=is,ie ; do j=js,je
      asum(j+jdg_off) = asum(j+jdg_off) + real_to_efp(array(i,j))
    enddo ; enddo

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_i_mean overflow error occurred before sum across PEs.")

    call efp_list_sum_across_pes(asum(g%jsg:g%jeg), g%jeg-g%jsg+1)

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_i_mean overflow error occurred during sum across PEs.")

    do j=js,je
      i_mean(j) = efp_to_real(asum(j+jdg_off)) / real(g%ieg-g%isg+1)
    enddo
  endif

  deallocate(asum)

end subroutine global_i_mean

subroutine global_j_mean(array, j_mean, G, mask)
  type(ocean_grid_type),            intent(inout) :: G    !< The ocean's grid structure
  real, dimension(SZI_(G),SZJ_(G)), intent(in)    :: array
  real, dimension(SZI_(G)),         intent(out)   :: j_mean
  real, dimension(SZI_(G),SZJ_(G)), optional, intent(in) :: mask

!    This subroutine determines the global mean of a field along rows of
!  constant j, returning it in a 1-d array using the local indexing.

! Arguments: array - The 2-d array whose j-mean is to be taken.
!  (out)     j_mean - Global mean of array along its j-axis.
!  (in)      G - The ocean's grid structure.
!  (in)      mask - An array used for weighting the j-mean.

  type(efp_type), allocatable, dimension(:) :: asum, mask_sum
  real :: mask_sum_r
  integer :: is, ie, js, je, idg_off, jdg_off
  integer :: i, j

  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec
  idg_off = g%idg_offset ; jdg_off = g%jdg_offset

  call reset_efp_overflow_error()

  allocate(asum(g%isg:g%ieg))
  if (present(mask)) then
    allocate (mask_sum(g%isg:g%ieg))

    do i=g%isg,g%ieg
      asum(i) = real_to_efp(0.0) ; mask_sum(i) = real_to_efp(0.0)
    enddo

    do i=is,ie ; do j=js,je
      asum(i+idg_off) = asum(i+idg_off) + real_to_efp(array(i,j)*mask(i,j))
      mask_sum(i+idg_off) = mask_sum(i+idg_off) + real_to_efp(mask(i,j))
    enddo ; enddo

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_j_mean overflow error occurred before sums across PEs.")

    call efp_list_sum_across_pes(asum(g%isg:g%ieg), g%ieg-g%isg+1)
    call efp_list_sum_across_pes(mask_sum(g%isg:g%ieg), g%ieg-g%isg+1)

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_j_mean overflow error occurred during sums across PEs.")

    do i=is,ie
      mask_sum_r = efp_to_real(mask_sum(i+idg_off))
      if (mask_sum_r == 0.0 ) then ; j_mean(i) = 0.0 ; else
        j_mean(i) = efp_to_real(asum(i+idg_off)) / mask_sum_r
      endif
    enddo

    deallocate(mask_sum)
  else
    do i=g%isg,g%ieg ; asum(i) = real_to_efp(0.0) ; enddo

    do i=is,ie ; do j=js,je
      asum(i+idg_off) = asum(i+idg_off) + real_to_efp(array(i,j))
    enddo ; enddo

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_j_mean overflow error occurred before sum across PEs.")

    call efp_list_sum_across_pes(asum(g%isg:g%ieg), g%ieg-g%isg+1)

    if (query_efp_overflow_error()) call mom_error(fatal, &
      "global_j_mean overflow error occurred during sum across PEs.")

    do i=is,ie
      j_mean(i) = efp_to_real(asum(i+idg_off)) / real(g%jeg-g%jsg+1)
    enddo
  endif

  deallocate(asum)

end subroutine global_j_mean

!> Adjust 2d array such that area mean is zero without moving the zero contour
subroutine adjust_area_mean_to_zero(array, G, scaling)
  type(ocean_grid_type),            intent(inout) :: G       !< Grid structure
  real, dimension(SZI_(G),SZJ_(G)), intent(inout) :: array   !< 2D array to be adjusted
  real, optional,                   intent(out)   :: scaling !< The scaling factor used
  ! Local variables
  real, dimension(SZI_(G), SZJ_(G)) :: posVals, negVals, areaXposVals, areaXnegVals
  integer :: i,j
  real :: areaIntPosVals, areaIntNegVals, posScale, negScale

  areaxposvals(:,:) = 0.
  areaxnegvals(:,:) = 0.

  do j=g%jsc,g%jec ; do i=g%isc,g%iec
    posvals(i,j) = max(0., array(i,j))
    areaxposvals(i,j) = g%areaT(i,j) * posvals(i,j)
    negvals(i,j) = min(0., array(i,j))
    areaxnegvals(i,j) = g%areaT(i,j) * negvals(i,j)
  enddo ; enddo

  areaintposvals = reproducing_sum( areaxposvals )
  areaintnegvals = reproducing_sum( areaxnegvals )

  posscale = 0.0 ; negscale = 0.0
  if ((areaintposvals>0.).and.(areaintnegvals<0.)) then ! Only adjust if possible
    if (areaintposvals>-areaintnegvals) then ! Scale down positive values
      posscale = - areaintnegvals / areaintposvals
      do j=g%jsc,g%jec ; do i=g%isc,g%iec
        array(i,j) = (posscale * posvals(i,j)) + negvals(i,j)
      enddo ; enddo
    elseif (areaintposvals<-areaintnegvals) then ! Scale down negative values
      negscale = - areaintposvals / areaintnegvals
      do j=g%jsc,g%jec ; do i=g%isc,g%iec
        array(i,j) = posvals(i,j) + (negscale * negvals(i,j))
      enddo ; enddo
    endif
  endif
  if (present(scaling)) scaling = posscale - negscale

end subroutine adjust_area_mean_to_zero

end module mom_spatial_means