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_coms, only : min_across_pes, max_across_pes, reproducing_sum
use mom_debugging, only : hchksum, uvchksum
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, US, haloshift, symmetric, vel_scale)
  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 [L T-1 ~> m s-1] or other units.
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                           intent(in) :: v    !< The meridional velocity [L T-1 ~> m s-1] or other units.
  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 L2 T-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 L2 T-1 ~> m3 s-1 or kg s-1].
  type(unit_scale_type),   intent(in) :: US   !< A dimensional unit scaling type
  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
                                                   !! computational domain.
  real,          optional, intent(in) :: vel_scale !< The scaling factor to convert velocities to [m s-1]

  real :: scale_vel ! The scaling factor to convert velocities to [m s-1]
  logical :: sym
  integer :: is, ie, js, je, nz, hs
  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
  scale_vel = us%L_T_to_m_s ; if (present(vel_scale)) scale_vel = vel_scale

  call uvchksum(mesg//" [uv]", u, v, g%HI, haloshift=hs, symmetric=sym, scale=scale_vel)
  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*us%L_to_m**2*us%s_to_T)
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, US, 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 [L T-1 ~> m s-1] or [m s-1].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                                   intent(in) :: v  !< Meridional velocity [L T-1 ~> m s-1] or [m s-1]..
  real, dimension(SZI_(G),SZJ_(G),SZK_(G)),  &
                                   intent(in) :: h  !< Layer thicknesses [H ~> m or kg m-2].
  type(unit_scale_type), optional, intent(in) :: US !< A dimensional unit scaling type, which is
                                                    !! used to rescale u and v if present.
  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 computational domain.
  real :: L_T_to_m_s ! A rescaling factor for velocities [m T s-1 L-1 ~> nondim] or [nondim]
  integer :: is, ie, js, je, nz, hs
  logical :: sym

  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
  l_t_to_m_s = 1.0 ; if (present(us)) l_t_to_m_s = us%L_T_to_m_s

  ! 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, scale=l_t_to_m_s)
  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, US, 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.
  type(unit_scale_type),    intent(in) :: US   !< A dimensional unit scaling type
  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, &
                                          scale=us%Q_to_J_kg*us%R_to_kg_m3*us%Z_to_m)
  if (associated(tv%salt_deficit)) &
    call hchksum(tv%salt_deficit, mesg//" salt deficit", g%HI, haloshift=hs, scale=us%RZ_to_kg_m2)

end subroutine mom_thermo_chksum

! =============================================================================

!> Write out chksums for the ocean surface variables.
subroutine mom_surface_chksum(mesg, sfc_state, G, US, haloshift, symmetric)
  character(len=*),      intent(in)    :: mesg !< A message that appears on the chksum lines.
  type(surface),         intent(inout) :: sfc_state !< 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.
  type(unit_scale_type), intent(in)    :: US    !< A dimensional unit scaling type
  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
                                               !! computational domain.

  integer :: hs
  logical :: sym

  sym = .false. ; if (present(symmetric)) sym = symmetric
  hs = 1 ; if (present(haloshift)) hs = haloshift

  if (allocated(sfc_state%SST)) call hchksum(sfc_state%SST, mesg//" SST", g%HI, haloshift=hs)
  if (allocated(sfc_state%SSS)) call hchksum(sfc_state%SSS, mesg//" SSS", g%HI, haloshift=hs)
  if (allocated(sfc_state%sea_lev)) call hchksum(sfc_state%sea_lev, mesg//" sea_lev", g%HI, &
                                                 haloshift=hs, scale=us%Z_to_m)
  if (allocated(sfc_state%Hml)) call hchksum(sfc_state%Hml, mesg//" Hml", g%HI, haloshift=hs, &
                                             scale=us%Z_to_m)
  if (allocated(sfc_state%u) .and. allocated(sfc_state%v)) &
    call uvchksum(mesg//" SSU", sfc_state%u, sfc_state%v, g%HI, haloshift=hs, symmetric=sym, &
                  scale=us%L_T_to_m_s)
!  if (allocated(sfc_state%salt_deficit)) &
!    call hchksum(sfc_state%salt_deficit, mesg//" salt deficit", G%HI, haloshift=hs, scale=US%RZ_to_kg_m2)
  if (allocated(sfc_state%frazil)) call hchksum(sfc_state%frazil, mesg//" frazil", g%HI, &
                                                haloshift=hs, scale=us%Q_to_J_kg*us%RZ_to_kg_m2)

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 [L T-2 ~> m s-2].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                            intent(in) :: CAv  !< Meridional acceleration due to Coriolis
                                               !! and momentum advection terms [L T-2 ~> m s-2].
  real, dimension(SZIB_(G),SZJ_(G),SZK_(G)), &
                            intent(in) :: PFu  !< Zonal acceleration due to pressure gradients
                                               !! (equal to -dM/dx) [L T-2 ~> m s-2].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                            intent(in) :: PFv  !< Meridional acceleration due to pressure gradients
                                               !! (equal to -dM/dy) [L T-2 ~> 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 [L T-2 ~> 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 [L T-2 ~> 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
                                               !! [L2 T-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 [L T-2 ~> 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 [L T-2 ~> m s-2].
  logical,        optional, intent(in) :: symmetric !< If true, do checksums on the fully symmetric
                                                    !! computational 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, scale=us%L_T2_to_m_s2)
  call uvchksum(mesg//" PF[uv]", pfu, pfv, g%HI, haloshift=0, symmetric=sym, scale=us%L_T2_to_m_s2)
  call uvchksum(mesg//" diffu", diffu, diffv, g%HI,haloshift=0, symmetric=sym, scale=us%L_T2_to_m_s2)
  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, &
                  scale=us%L_T2_to_m_s2)
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, GV, US, allowChange, permitDiminishing)
  type(ocean_grid_type),   intent(in) :: G    !< The ocean's grid structure.
  type(verticalgrid_type), intent(in) :: GV   !< The ocean's vertical 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 [L T-1 ~> m s-1].
  real, dimension(SZI_(G),SZJB_(G),SZK_(G)), &
                           intent(in) :: v    !< The meridional velocity [L T-1 ~> 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].
  type(unit_scale_type),   intent(in) :: US    !< A dimensional unit scaling type
  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
  real, dimension(G%isc:G%iec, G%jsc:G%jec) :: &
    tmp_A, &  ! The area per cell [m2] (unscaled to permit reproducing sum).
    tmp_V, &  ! The column-integrated volume [m3] (unscaled to permit reproducing sum)
    tmp_T, &  ! The column-integrated temperature [degC m3]
    tmp_S     ! The column-integrated salinity [ppt m3]
  real :: Vol, dV    ! The total ocean volume and its change [m3] (unscaled to permit reproducing sum).
  real :: Area       ! The total ocean surface area [m2] (unscaled to permit reproducing sum).
  real :: h_minimum  ! The minimum layer thicknesses [H ~> m or kg m-2]
  logical :: do_TS   ! If true, evaluate statistics for temperature and salinity
  type(stats) :: T, S, delT, delS

  ! NOTE: save data is not normally allowed but we use it for debugging purposes here on the
  !       assumption we will not turn this on with threads
  type(stats), save :: oldT, oldS
  logical, save :: firstCall = .true.
  real, save :: oldVol ! The previous total ocean volume [m3]

  character(len=80) :: lMsg
  integer :: is, ie, js, je, nz, i, j, k

  is = g%isc ; ie = g%iec ; js = g%jsc ; je = g%jec ; nz = g%ke
  do_ts = associated(temp) .and. associated(salt)

  tmp_a(:,:) = 0.0
  tmp_v(:,:) = 0.0
  tmp_t(:,:) = 0.0
  tmp_s(:,:) = 0.0

  ! First collect local stats
  do j=js,je ; do i=is,ie
    tmp_a(i,j) = tmp_a(i,j) + us%L_to_m**2*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*gv%m_to_H
  do k=1,nz ; do j=js,je ; do i=is,ie
    if (g%mask2dT(i,j)>0.) then
      dv = us%L_to_m**2*g%areaT(i,j)*gv%H_to_m*h(i,j,k)
      tmp_v(i,j) = tmp_v(i,j) + 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
  area = reproducing_sum( tmp_a ) ; vol = reproducing_sum( tmp_v )
  if (do_ts) then
    call min_across_pes( t%minimum ) ; call max_across_pes( t%maximum )
    call min_across_pes( s%minimum ) ; call max_across_pes( s%maximum )
    t%average = reproducing_sum( tmp_t ) ; s%average = reproducing_sum( tmp_s )
    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