MOM_hor_index.F90

!> Defines the horizontal index type (hor_index_type) used for providing index ranges
module mom_hor_index

! This file is part of MOM6. See LICENSE.md for the license.

use mom_domains, only : mom_domain_type, get_domain_extent, get_global_shape
use mom_error_handler, only : mom_error, mom_mesg, fatal
use mom_file_parser, only : get_param, log_param, log_version, param_file_type

implicit none ; private

public :: hor_index_init, assignment(=)
public :: rotate_hor_index

!> Container for horizontal index ranges for data, computational and global domains
type, public :: hor_index_type
  integer :: isc !< The start i-index of cell centers within the computational domain
  integer :: iec !< The end i-index of cell centers within the computational domain
  integer :: jsc !< The start j-index of cell centers within the computational domain
  integer :: jec !< The end j-index of cell centers within the computational domain

  integer :: isd !< The start i-index of cell centers within the data domain
  integer :: ied !< The end i-index of cell centers within the data domain
  integer :: jsd !< The start j-index of cell centers within the data domain
  integer :: jed !< The end j-index of cell centers within the data domain

  integer :: isg !< The start i-index of cell centers within the global domain
  integer :: ieg !< The end i-index of cell centers within the global domain
  integer :: jsg !< The start j-index of cell centers within the global domain
  integer :: jeg !< The end j-index of cell centers within the global domain

  integer :: iscb !< The start i-index of cell vertices within the computational domain
  integer :: iecb !< The end i-index of cell vertices within the computational domain
  integer :: jscb !< The start j-index of cell vertices within the computational domain
  integer :: jecb !< The end j-index of cell vertices within the computational domain

  integer :: isdb !< The start i-index of cell vertices within the data domain
  integer :: iedb !< The end i-index of cell vertices within the data domain
  integer :: jsdb !< The start j-index of cell vertices within the data domain
  integer :: jedb !< The end j-index of cell vertices within the data domain

  integer :: isgb !< The start i-index of cell vertices within the global domain
  integer :: iegb !< The end i-index of cell vertices within the global domain
  integer :: jsgb !< The start j-index of cell vertices within the global domain
  integer :: jegb !< The end j-index of cell vertices within the global domain

  integer :: idg_offset !< The offset between the corresponding global and local i-indices.
  integer :: jdg_offset !< The offset between the corresponding global and local j-indices.
  logical :: symmetric  !< True if symmetric memory is used.

  integer :: niglobal !< The global number of h-cells in the i-direction
  integer :: njglobal !< The global number of h-cells in the j-direction

  integer :: turns      !< Number of quarter-turn rotations from input to model
end type hor_index_type

!> Copy the contents of one horizontal index type into another
interface assignment(=); module procedure HIT_assign ; end interface

contains

!> Sets various index values in a hor_index_type.
subroutine hor_index_init(Domain, HI, param_file, local_indexing, index_offset)
  type(mom_domain_type),  intent(in)    :: domain     !< The MOM domain from which to extract information.
  type(hor_index_type),   intent(inout) :: hi         !< A horizontal index type to populate with data
  type(param_file_type),  intent(in)    :: param_file !< Parameter file handle
  logical, optional,      intent(in)    :: local_indexing !< If true, all tracer data domains start at 1
  integer, optional,      intent(in)    :: index_offset   !< A fixed additional offset to all indices

! This include declares and sets the variable "version".
#include "version_variable.h"

  ! get_domain_extent ensures that domains start at 1 for compatibility between
  ! static and dynamically allocated arrays.
  call get_domain_extent(domain, hi%isc, hi%iec, hi%jsc, hi%jec, &
                         hi%isd, hi%ied, hi%jsd, hi%jed, &
                         hi%isg, hi%ieg, hi%jsg, hi%jeg, &
                         hi%idg_offset, hi%jdg_offset, hi%symmetric, &
                         local_indexing=local_indexing)
  call get_global_shape(domain, hi%niglobal, hi%njglobal)

  ! Read all relevant parameters and write them to the model log.
  call log_version(param_file, "MOM_hor_index", version, &
                   "Sets the horizontal array index types.", all_default=.true.)

  hi%IscB = hi%isc ; hi%JscB = hi%jsc
  hi%IsdB = hi%isd ; hi%JsdB = hi%jsd
  hi%IsgB = hi%isg ; hi%JsgB = hi%jsg
  if (hi%symmetric) then
    hi%IscB = hi%isc-1 ; hi%JscB = hi%jsc-1
    hi%IsdB = hi%isd-1 ; hi%JsdB = hi%jsd-1
    hi%IsgB = hi%isg-1 ; hi%JsgB = hi%jsg-1
  endif
  hi%IecB = hi%iec ; hi%JecB = hi%jec
  hi%IedB = hi%ied ; hi%JedB = hi%jed
  hi%IegB = hi%ieg ; hi%JegB = hi%jeg

  hi%turns = 0
end subroutine hor_index_init

!> HIT_assign copies one hor_index_type into another.  It is accessed via an
!! assignment (=) operator.
subroutine hit_assign(HI1, HI2)
  type(hor_index_type), intent(out) :: HI1 !< Horizontal index type to copy to
  type(hor_index_type), intent(in)  :: HI2 !< Horizontal index type to copy from
  ! This subroutine copies all components of the horizontal array index type
  ! variable on the RHS (HI2) to the variable on the LHS (HI1).

  hi1%isc = hi2%isc ; hi1%iec = hi2%iec ; hi1%jsc = hi2%jsc ; hi1%jec = hi2%jec
  hi1%isd = hi2%isd ; hi1%ied = hi2%ied ; hi1%jsd = hi2%jsd ; hi1%jed = hi2%jed
  hi1%isg = hi2%isg ; hi1%ieg = hi2%ieg ; hi1%jsg = hi2%jsg ; hi1%jeg = hi2%jeg

  hi1%IscB = hi2%IscB ; hi1%IecB = hi2%IecB ; hi1%JscB = hi2%JscB ; hi1%JecB = hi2%JecB
  hi1%IsdB = hi2%IsdB ; hi1%IedB = hi2%IedB ; hi1%JsdB = hi2%JsdB ; hi1%JedB = hi2%JedB
  hi1%IsgB = hi2%IsgB ; hi1%IegB = hi2%IegB ; hi1%JsgB = hi2%JsgB ; hi1%JegB = hi2%JegB

  hi1%niglobal = hi2%niglobal ; hi1%njglobal = hi2%njglobal
  hi1%idg_offset = hi2%idg_offset ; hi1%jdg_offset = hi2%jdg_offset
  hi1%symmetric = hi2%symmetric
  hi1%turns = hi2%turns
end subroutine hit_assign

!> Rotate the horizontal index ranges from the input to the output map.
subroutine rotate_hor_index(HI_in, turns, HI)
  type(hor_index_type), intent(in) :: hi_in   !< Unrotated horizontal indices
  integer, intent(in) :: turns                !< Number of quarter turns
  type(hor_index_type), intent(inout) :: hi   !< Rotated horizontal indices

  if (modulo(turns, 2) /= 0) then
    hi%isc = hi_in%jsc
    hi%iec = hi_in%jec
    hi%jsc = hi_in%isc
    hi%jec = hi_in%iec
    hi%isd = hi_in%jsd
    hi%ied = hi_in%jed
    hi%jsd = hi_in%isd
    hi%jed = hi_in%ied
    hi%isg = hi_in%jsg
    hi%ieg = hi_in%jeg
    hi%jsg = hi_in%isg
    hi%jeg = hi_in%ieg

    hi%IscB = hi_in%JscB
    hi%IecB = hi_in%JecB
    hi%JscB = hi_in%IscB
    hi%JecB = hi_in%IecB
    hi%IsdB = hi_in%JsdB
    hi%IedB = hi_in%JedB
    hi%JsdB = hi_in%IsdB
    hi%JedB = hi_in%IedB
    hi%IsgB = hi_in%JsgB
    hi%IegB = hi_in%JegB
    hi%JsgB = hi_in%IsgB
    hi%JegB = hi_in%IegB

    hi%niglobal = hi_in%njglobal
    hi%njglobal = hi_in%niglobal
    hi%idg_offset = hi_in%jdg_offset
    hi%jdg_offset = hi_in%idg_offset

    hi%symmetric = hi_in%symmetric
  else
    hi = hi_in
  endif
  hi%turns = hi_in%turns + turns
end subroutine rotate_hor_index

!> \namespace mom_hor_index
!!
!! The hor_index_type provides the declarations and loop ranges for almost all data with horizontal extent.
!!
!! Declarations and loop ranges should always be coded with the symmetric memory model in mind.
!! The non-symmetric memory mode will then also work, albeit with a different (less efficient) communication pattern.
!!
!! Using the hor_index_type HI:
!! - declaration of h-point data is of the form `h(HI%%isd:HI%%ied,HI%%jsd:HI%%jed)`
!! - declaration of q-point data is of the form `q(HI%%IsdB:HI%%IedB,HI%%JsdB:HI%%JedB)`
!! - declaration of u-point data is of the form `u(HI%%IsdB:HI%%IedB,HI%%jsd:HI%%jed)`
!! - declaration of v-point data is of the form `v(HI%%isd:HI%%ied,HI%%JsdB:HI%%JedB)`.
!!
!! For more detail explanation of horizontal indexing see \ref Horizontal_Indexing.


end module mom_hor_index