MOM_hor_index.F90

Go to the documentation of this file.

!> 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
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(=)

!> 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.
end type hor_index_type

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)

  ! 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.")

  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

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%idg_offset = hi2%idg_offset ; hi1%jdg_offset = hi2%jdg_offset
  hi1%symmetric = hi2%symmetric

end subroutine hit_assign

!> \namespace mom_hor_index
!!
!! The hor_index_type provides the decalarations 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