MOM_checksum_packages.F90

!> Provides routines that do checksums of groups of MOM variables
module mom_checksum_packages
 
! This file is part of MOM6. See LICENSE.md for the license.
 
!   This module provides several routines that do check-sums of groups
! of variables in the various dynamic solver routines.
 
use mom_debugging, only : hchksum, uvchksum
use mom_domains, only : sum_across_pes, min_across_pes, max_across_pes
use mom_error_handler, only : mom_mesg, is_root_pe
use mom_grid, only : ocean_grid_type
use mom_unit_scaling, only : unit_scale_type
use mom_variables, only : thermo_var_ptrs, surface
use mom_verticalgrid, only : verticalgrid_type
 
implicit none ; private
 
public mom_state_chksum, mom_thermo_chksum, mom_accel_chksum
public mom_state_stats, mom_surface_chksum
 
!> Write out checksums of the MOM6 state variables
interface mom_state_chksum
  module procedure mom_state_chksum_5arg
  module procedure mom_state_chksum_3arg
end interface
 
#include <MOM_memory.h>
 
!> A type for storing statistica about a variable
type :: stats ; private
  real :: minimum = 1.e34  !< The minimum value
  real :: maximum = -1.e34 !< The maximum value
  real :: average = 0.     !< The average value
end type stats
 
contains
 
! =============================================================================
 
!> Write out chksums for the model's basic state variables, including transports.
subroutine mom_state_chksum_5arg(mesg, u, v, h, uh, vh, G, GV, haloshift, symmetric)
  character(len=*),                          &
                           intent(in) :: mesg !< A message that appears on the chksum lines.
  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(SZIB_(G),SZJ_(G),SZK_(G)), &
                           intent(in) :: u    !< The zonal velocity [m s-1].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                           intent(in) :: v    !< The meridional velocity [m s-1].
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)),  &
                           intent(in) :: h    !< Layer thicknesses [H ~> m or kg m-2].
  real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), &
                           intent(in) :: uh   !< Volume flux through zonal faces = u*h*dy
                                              !! [H m2 s-1 ~> m3 s-1 or kg s-1].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                           intent(in) :: vh   !< Volume flux through meridional faces = v*h*dx
                                              !! [H m2 s-1 ~> m3 s-1 or kg s-1].
  integer,       optional, intent(in) :: haloshift !< The width of halos to check (default 0).
  logical,       optional, intent(in) :: symmetric !< If true, do checksums on the fully symmetric
                                                   !! computationoal domain.
 
  integer :: is, ie, js, je, nz, hs
  logical :: sym
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
 
  ! Note that for the chksum calls to be useful for reproducing across PE
  ! counts, there must be no redundant points, so all variables use is..ie
  ! and js...je as their extent.
  hs=1; if (present(haloshift)) hs=haloshift
  sym=.false.; if (present(symmetric)) sym=symmetric
  call uvchksum(mesg//" [uv]", u, v, g%HI, haloshift=hs, symmetric=sym)
  call hchksum(h, mesg//" h", g%HI, haloshift=hs, scale=gv%H_to_m)
  call uvchksum(mesg//" [uv]h", uh, vh, g%HI, haloshift=hs, &
                symmetric=sym, scale=gv%H_to_m)
end subroutine mom_state_chksum_5arg
 
! =============================================================================
 
!> Write out chksums for the model's basic state variables.
subroutine mom_state_chksum_3arg(mesg, u, v, h, G, GV, haloshift, symmetric)
  character(len=*),        intent(in) :: mesg !< A message that appears on the chksum lines.
  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(SZIB_(G),SZJ_(G),SZK_(G)), &
                           intent(in) :: u    !< Zonal velocity [m s-1].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                           intent(in) :: v    !< Meridional velocity [m s-1].
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)),  &
                           intent(in) :: h    !< Layer thicknesses [H ~> m or kg m-2].
  integer,       optional, intent(in) :: haloshift !< The width of halos to check (default 0).
  logical,       optional, intent(in) :: symmetric !< If true, do checksums on the fully symmetric
                                                   !! computationoal domain.
 
  integer :: is, ie, js, je, nz, hs
  logical :: sym
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
 
  ! Note that for the chksum calls to be useful for reproducing across PE
  ! counts, there must be no redundant points, so all variables use is..ie
  ! and js...je as their extent.
  hs=1; if (present(haloshift)) hs=haloshift
  sym=.false.; if (present(symmetric)) sym=symmetric
  call uvchksum(mesg//" u", u, v, g%HI,haloshift=hs, symmetric=sym)
  call hchksum(h, mesg//" h",g%HI, haloshift=hs, scale=gv%H_to_m)
end subroutine mom_state_chksum_3arg
 
! =============================================================================
 
!> Write out chksums for the model's thermodynamic state variables.
subroutine mom_thermo_chksum(mesg, tv, G, haloshift)
  character(len=*),         intent(in) :: mesg !< A message that appears on the chksum lines.
  type(thermo_var_ptrs),    intent(in) :: tv   !< A structure pointing to various
                                               !! thermodynamic variables.
  type(ocean_grid_type),    intent(in) :: g    !< The ocean's grid structure.
  integer,        optional, intent(in) :: haloshift !< The width of halos to check (default 0).
 
  integer :: is, ie, js, je, nz, hs
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
  hs=1; if (present(haloshift)) hs=haloshift
 
  if (associated(tv%T)) call hchksum(tv%T, mesg//" T",g%HI,haloshift=hs)
  if (associated(tv%S)) call hchksum(tv%S, mesg//" S",g%HI,haloshift=hs)
  if (associated(tv%frazil)) call hchksum(tv%frazil, mesg//" frazil",g%HI,haloshift=hs)
  if (associated(tv%salt_deficit)) call hchksum(tv%salt_deficit, mesg//" salt deficit",g%HI,haloshift=hs)
 
end subroutine mom_thermo_chksum
 
! =============================================================================
 
!> Write out chksums for the ocean surface variables.
subroutine mom_surface_chksum(mesg, sfc, G, haloshift, symmetric)
  character(len=*),      intent(in) :: mesg !< A message that appears on the chksum lines.
  type(surface),         intent(inout) :: sfc !< transparent ocean surface state
                                              !! structure shared with the calling routine
                                              !! data in this structure is intent out.
  type(ocean_grid_type), intent(in) :: g    !< The ocean's grid structure.
  integer,     optional, intent(in) :: haloshift !< The width of halos to check (default 0).
  logical,     optional, intent(in) :: symmetric !< If true, do checksums on the fully symmetric
                                                 !! computationoal domain.
 
  integer :: hs
  logical :: sym
 
  sym = .false. ; if (present(symmetric)) sym = symmetric
  hs = 1 ; if (present(haloshift)) hs = haloshift
 
  if (allocated(sfc%SST)) call hchksum(sfc%SST, mesg//" SST",g%HI,haloshift=hs)
  if (allocated(sfc%SSS)) call hchksum(sfc%SSS, mesg//" SSS",g%HI,haloshift=hs)
  if (allocated(sfc%sea_lev)) call hchksum(sfc%sea_lev, mesg//" sea_lev",g%HI,haloshift=hs)
  if (allocated(sfc%Hml)) call hchksum(sfc%Hml, mesg//" Hml",g%HI,haloshift=hs)
  if (allocated(sfc%u) .and. allocated(sfc%v)) &
    call uvchksum(mesg//" SSU", sfc%u, sfc%v, g%HI, haloshift=hs, symmetric=sym)
!  if (allocated(sfc%salt_deficit)) call hchksum(sfc%salt_deficit, mesg//" salt deficit",G%HI,haloshift=hs)
  if (associated(sfc%frazil)) call hchksum(sfc%frazil, mesg//" frazil",g%HI,haloshift=hs)
 
end subroutine mom_surface_chksum
 
! =============================================================================
 
!> Write out chksums for the model's accelerations
subroutine mom_accel_chksum(mesg, CAu, CAv, PFu, PFv, diffu, diffv, G, GV, US, pbce, &
                            u_accel_bt, v_accel_bt, symmetric)
  character(len=*),         intent(in) :: mesg !< A message that appears on the chksum lines.
  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(SZIB_(G),SZJ_(G),SZK_(G)), &
                            intent(in) :: cau  !< Zonal acceleration due to Coriolis
                                               !! and momentum advection terms [m s-2].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                            intent(in) :: cav  !< Meridional acceleration due to Coriolis
                                               !! and momentum advection terms [m s-2].
  real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), &
                            intent(in) :: pfu  !< Zonal acceleration due to pressure gradients
                                               !! (equal to -dM/dx) [m s-2].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                            intent(in) :: pfv  !< Meridional acceleration due to pressure gradients
                                               !! (equal to -dM/dy) [m s-2].
  real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), &
                            intent(in) :: diffu !< Zonal acceleration due to convergence of the
                                                !! along-isopycnal stress tensor [m s-1 T-1 ~> m s-2].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                            intent(in) :: diffv !< Meridional acceleration due to convergence of
                                                !! the along-isopycnal stress tensor [m s-1 T-1 ~> m s-2].
  type(unit_scale_type),    intent(in) :: us    !< A dimensional unit scaling type
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)),  &
                  optional, intent(in) :: pbce !< The baroclinic pressure anomaly in each layer
                                               !! due to free surface height anomalies
                                               !! [m2 s-2 H-1 ~> m s-2 or m4 s-2 kg-1].
  real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), &
                  optional, intent(in) :: u_accel_bt !< The zonal acceleration from terms in the
                                                     !! barotropic solver [m s-2].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                  optional, intent(in) :: v_accel_bt !< The meridional acceleration from terms in
                                                     !! the barotropic solver [m s-2].
  logical,        optional, intent(in) :: symmetric !< If true, do checksums on the fully symmetric
                                                    !! computationoal domain.
 
  integer :: is, ie, js, je, nz
  logical :: sym
 
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
  sym=.false.; if (present(symmetric)) sym=symmetric
 
  ! Note that for the chksum calls to be useful for reproducing across PE
  ! counts, there must be no redundant points, so all variables use is..ie
  ! and js...je as their extent.
  call uvchksum(mesg//" CA[uv]", cau, cav, g%HI, haloshift=0, symmetric=sym)
  call uvchksum(mesg//" PF[uv]", pfu, pfv, g%HI, haloshift=0, symmetric=sym)
  call uvchksum(mesg//" diffu", diffu, diffv, g%HI,haloshift=0, symmetric=sym, scale=us%s_to_T)
  if (present(pbce)) &
    call hchksum(pbce, mesg//" pbce",g%HI,haloshift=0, scale=gv%m_to_H*us%L_T_to_m_s**2)
  if (present(u_accel_bt) .and. present(v_accel_bt)) &
    call uvchksum(mesg//" [uv]_accel_bt", u_accel_bt, v_accel_bt, g%HI,haloshift=0, symmetric=sym)
end subroutine mom_accel_chksum
 
! =============================================================================
 
!> Monitor and write out statistics for the model's state variables.
subroutine mom_state_stats(mesg, u, v, h, Temp, Salt, G, allowChange, permitDiminishing)
  type(ocean_grid_type),   intent(in) :: g    !< The ocean's grid structure.
  character(len=*),        intent(in) :: mesg !< A message that appears on the chksum lines.
  real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), &
                           intent(in) :: u    !< The zonal velocity [m s-1].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                           intent(in) :: v    !< The meridional velocity [m s-1].
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)),  &
                           intent(in) :: h    !< Layer thicknesses [H ~> m or kg m-2].
  real, pointer, dimension(:,:,:),           &
                           intent(in) :: temp !< Temperature [degC].
  real, pointer, dimension(:,:,:),           &
                           intent(in) :: salt !< Salinity [ppt].
  logical,       optional, intent(in) :: allowchange !< do not flag an error
                                                     !! if the statistics change.
  logical,       optional, intent(in) :: permitdiminishing !< do not flag error
                                                           !!if the extrema are diminishing.
  ! Local variables
  integer :: is, ie, js, je, nz, i, j, k
  real :: vol, dv, area, h_minimum
  type(stats) :: t, s, delt, dels
  type(stats), save :: oldt, olds     ! NOTE: save data is not normally allowed but
  logical, save :: firstcall = .true. ! we use it for debugging purposes here on the
  logical :: do_ts
  real, save :: oldvol                ! assumption we will not turn this on with threads
  character(len=80) :: lmsg
  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
 
  do_ts = associated(temp) .and. associated(salt)
 
  ! First collect local stats
  area = 0. ; vol = 0.
  do j = js, je ; do i = is, ie
    area = area + g%areaT(i,j)
  enddo ; enddo
  t%minimum = 1.e34 ; t%maximum = -1.e34 ; t%average = 0.
  s%minimum = 1.e34 ; s%maximum = -1.e34 ; s%average = 0.
  h_minimum = 1.e34
  do k = 1, nz ; do j = js, je ; do i = is, ie
    if (g%mask2dT(i,j)>0.) then
      dv = g%areaT(i,j)*h(i,j,k) ; vol = vol + dv
      if (do_ts .and. h(i,j,k)>0.) then
        t%minimum = min( t%minimum, temp(i,j,k) ) ; t%maximum = max( t%maximum, temp(i,j,k) )
        t%average = t%average + dv*temp(i,j,k)
        s%minimum = min( s%minimum, salt(i,j,k) ) ; s%maximum = max( s%maximum, salt(i,j,k) )
        s%average = s%average + dv*salt(i,j,k)
      endif
      if (h_minimum > h(i,j,k)) h_minimum = h(i,j,k)
    endif
  enddo ; enddo ; enddo
  call sum_across_pes( area ) ; call sum_across_pes( vol )
  if (do_ts) then
    call min_across_pes( t%minimum ) ; call max_across_pes( t%maximum ) ; call sum_across_pes( t%average )
    call min_across_pes( s%minimum ) ; call max_across_pes( s%maximum ) ; call sum_across_pes( s%average )
    t%average = t%average / vol ; s%average = s%average / vol
  endif
  if (is_root_pe()) then
    if (.not.firstcall) then
      dv = vol - oldvol
      delt%minimum = t%minimum - oldt%minimum ; delt%maximum = t%maximum - oldt%maximum
      delt%average = t%average - oldt%average
      dels%minimum = s%minimum - olds%minimum ; dels%maximum = s%maximum - olds%maximum
      dels%average = s%average - olds%average
      write(lmsg(1:80),'(2(a,es12.4))') 'Mean thickness =',vol/area,' frac. delta=',dv/vol
      call mom_mesg(lmsg//trim(mesg))
      if (do_ts) then
        write(lmsg(1:80),'(a,3es12.4)') 'Temp min/mean/max =',t%minimum,t%average,t%maximum
        call mom_mesg(lmsg//trim(mesg))
        write(lmsg(1:80),'(a,3es12.4)') 'delT min/mean/max =',delt%minimum,delt%average,delt%maximum
        call mom_mesg(lmsg//trim(mesg))
        write(lmsg(1:80),'(a,3es12.4)') 'Salt min/mean/max =',s%minimum,s%average,s%maximum
        call mom_mesg(lmsg//trim(mesg))
        write(lmsg(1:80),'(a,3es12.4)') 'delS min/mean/max =',dels%minimum,dels%average,dels%maximum
        call mom_mesg(lmsg//trim(mesg))
      endif
    else
      write(lmsg(1:80),'(a,es12.4)') 'Mean thickness =',vol/area
      call mom_mesg(lmsg//trim(mesg))
      if (do_ts) then
        write(lmsg(1:80),'(a,3es12.4)') 'Temp min/mean/max =',t%minimum,t%average,t%maximum
        call mom_mesg(lmsg//trim(mesg))
        write(lmsg(1:80),'(a,3es12.4)') 'Salt min/mean/max =',s%minimum,s%average,s%maximum
        call mom_mesg(lmsg//trim(mesg))
      endif
    endif
  endif
  firstcall = .false. ; oldvol = vol
  oldt%minimum = t%minimum ; oldt%maximum = t%maximum ; oldt%average = t%average
  olds%minimum = s%minimum ; olds%maximum = s%maximum ; olds%average = s%average
 
  if (do_ts .and. t%minimum<-5.0) then
    do j = js, je ; do i = is, ie
      if (minval(temp(i,j,:)) == t%minimum) then
        write(0,'(a,2f12.5)') 'x,y=',g%geoLonT(i,j),g%geoLatT(i,j)
        write(0,'(a3,3a12)') 'k','h','Temp','Salt'
        do k = 1, nz
          write(0,'(i3,3es12.4)') k,h(i,j,k),temp(i,j,k),salt(i,j,k)
        enddo
        stop 'Extremum detected'
      endif
    enddo ; enddo
  endif
 
  if (h_minimum<0.0) then
    do j = js, je ; do i = is, ie
      if (minval(h(i,j,:)) == h_minimum) then
        write(0,'(a,2f12.5)') 'x,y=',g%geoLonT(i,j),g%geoLatT(i,j)
        write(0,'(a3,3a12)') 'k','h','Temp','Salt'
        do k = 1, nz
          write(0,'(i3,3es12.4)') k,h(i,j,k),temp(i,j,k),salt(i,j,k)
        enddo
        stop 'Negative thickness detected'
      endif
    enddo ; enddo
  endif
 
end subroutine mom_state_stats
 
end module mom_checksum_packages