MOM_variables.F90

Go to the documentation of this file.

module mom_variables

!***********************************************************************
!*                   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_domains, only : mom_domain_type, get_domain_extent, group_pass_type
use mom_debugging, only : hchksum
use mom_error_handler, only : mom_error, fatal
use mom_grid, only : ocean_grid_type
use mom_io, only : vardesc
use mom_eos, only : eos_type

use coupler_types_mod, only : coupler_2d_bc_type

implicit none ; private

#include <MOM_memory.h>

public mom_thermovar_chksum
public ocean_grid_type, vardesc, alloc_bt_cont_type, dealloc_bt_cont_type

type, public :: p3d
  real, dimension(:,:,:), pointer :: p => null()
end type p3d
type, public :: p2d
  real, dimension(:,:), pointer :: p => null()
end type p2d

!>   The following structure contains pointers to various fields
!! which may be used describe the surface state of MOM, and which
!! will be returned to a the calling program
type, public :: surface
  real, allocatable, dimension(:,:) :: &
    sst, &      !< The sea surface temperature in C.
    sss, &      !< The sea surface salinity in psu.
    sfc_density, & !< The mixed layer density in kg m-3.
    hml, &      !< The mixed layer depth in m.
    u, &        !< The mixed layer zonal velocity in m s-1.
    v, &        !< The mixed layer meridional velocity in m s-1.
    sea_lev, &  !< The sea level in m.  If a reduced surface gravity is
                !! used, that is compensated for in sea_lev.
    ocean_mass, &  !< The total mass of the ocean in kg m-2.
    ocean_heat, &  !< The total heat content of the ocean in C kg m-2.
    ocean_salt, &  !< The total salt content of the ocean in kgSalt m-2.
    salt_deficit   !< The salt needed to maintain the ocean column at a minimum
                   !! salinity of 0.01 PSU over the call to step_MOM, in kgSalt m-2.
  real, pointer, dimension(:,:) :: &
    taux_shelf => null(), &  !< The zonal and meridional stresses on the ocean
    tauy_shelf => null(), &  !< under shelves, in Pa.
    frazil => null(), &  !< The energy needed to heat the ocean column to the
                         !! freezing point over the call to step_MOM, in J m-2.
    tempxpme => null(), &  !< The net inflow of water into the ocean times
                         !! the temperature at which this inflow occurs during
                         !! the call to step_MOM, in deg C kg m-2.
                         !!   This should be prescribed in the forcing fields,
                         !! but as it often is not, this is a useful heat budget
                         !! diagnostic.
    internal_heat => null() !< Any internal or geothermal heat sources that
                         !! are applied to the ocean integrated over the call
                         !! to step_MOM, in deg C kg m-2.
  type(coupler_2d_bc_type), pointer :: &
    tr_fields  => null() ! NOTE: ALL OF THE ARRAYS IN TR_FIELDS USE THE COUPLER'S INDEXING!       CONVENTION AND HAVE NO HALOS!  THIS IS DONE TO CONFORM TO!       THE TREATMENT IN MOM4, BUT I DON'T LIKE IT!!< A structure that may contain an  array of named
                         !! fields describing tracer-related quantities.
       !!
       !!
       !!
  logical :: arrays_allocated = .false.  !< A flag that indicates whether
                         !! the surface type has had its memory allocated.
end type surface

!>   The thermo_var_ptrs structure contains pointers to an assortment of
!! thermodynamic fields that may be available, including potential temperature,
!! salinity, heat capacity, and the equation of state control structure.
type, public :: thermo_var_ptrs
!   If allocated, the following variables have nz layers.
  real, pointer :: t(:,:,:) => null()   !< Potential temperature in C.
  real, pointer :: s(:,:,:) => null()   !< Salnity in psu or ppt.
  type(eos_type), pointer :: eqn_of_state => null() !< Type that indicates the
                                        !! equation of state to use.
  real :: p_ref          !<   The coordinate-density reference pressure in Pa.
                         !! This is the pressure used to calculate Rml from
                         !! T and S when eqn_of_state is associated.
  real :: c_p            !<   The heat capacity of seawater, in J K-1 kg-1.
                         !! When conservative temperature is used, this is
                         !! constant and exactly 3991.86795711963 J K kg-1.
  real, pointer, dimension(:,:) :: &
!  These arrays are accumulated fluxes for communication with other components.
    frazil => null(), &  !<   The energy needed to heat the ocean column to the
                         !! freezing point since calculate_surface_state was
                         !! last called, in units of J m-2.
    salt_deficit => null(), & !<   The salt needed to maintain the ocean column
                         !! at a minumum salinity of 0.01 PSU since the last time
                         !! that calculate_surface_state was called, in units
                         !! of gSalt m-2.
    tempxpme => null(), & !<   The net inflow of water into the ocean times the
                         !! temperature at which this inflow occurs since the
                         !! last call to calculate_surface_state, in units of
                         !! deg C kg m-2. This should be prescribed in the
                         !! forcing fields, but as it often is not, this is a
                         !! useful heat budget diagnostic.
    internal_heat => null() !< Any internal or geothermal heat sources that
                         !! have been applied to the ocean since the last call to
                         !! calculate_surface_state, in units of deg C kg m-2.
end type thermo_var_ptrs

!> The ocean_internal_state structure contains pointers to all of the prognostic
!! variables allocated in MOM_variables.F90 and MOM.F90.  It is useful for
!! sending these variables for diagnostics, and in preparation for ensembles
!! later on.  All variables have the same names as the local (public) variables
!! they refer to in MOM.F90.
type, public :: ocean_internal_state
  real, pointer, dimension(:,:,:) :: &
    u => null(), v => null(), h => null()
  real, pointer, dimension(:,:,:) :: &
    uh => null(), vh => null(), &
    cau => null(), cav => null(), &
    pfu  => null(), pfv => null(), diffu => null(), diffv => null(), &
    t => null(), s => null(), &
    pbce => null(), u_accel_bt => null(), v_accel_bt => null(), &
    u_av => null(), v_av => null(), u_prev => null(), v_prev => null()
end type ocean_internal_state

!> The accel_diag_ptrs structure contains pointers to arrays with accelerations,
!! which can later be used for derived diagnostics, like energy balances.
type, public :: accel_diag_ptrs

! Each of the following fields has nz layers.
  real, pointer :: diffu(:,:,:) => null()    ! Accelerations due to along iso-
  real, pointer :: diffv(:,:,:) => null()    ! pycnal viscosity, in m s-2.
  real, pointer :: cau(:,:,:) => null()      ! Coriolis and momentum advection
  real, pointer :: cav(:,:,:) => null()      ! accelerations, in m s-2.
  real, pointer :: pfu(:,:,:) => null()      ! Accelerations due to pressure
  real, pointer :: pfv(:,:,:) => null()      ! forces, in m s-2.
  real, pointer :: du_dt_visc(:,:,:) => null()! Accelerations due to vertical
  real, pointer :: dv_dt_visc(:,:,:) => null()! viscosity, in m s-2.
  real, pointer :: du_dt_dia(:,:,:) => null()! Accelerations due to diapycnal
  real, pointer :: dv_dt_dia(:,:,:) => null()! mixing, in m s-2.
  real, pointer :: du_other(:,:,:) => null() ! Velocity changes due to any other
  real, pointer :: dv_other(:,:,:) => null() ! processes that are not due to any
                                             ! explicit accelerations, in m s-1.

  ! These accelerations are sub-terms included in the accelerations above.
  real, pointer :: gradkeu(:,:,:) => null()  ! gradKEu = - d/dx(u2), in m s-2.
  real, pointer :: gradkev(:,:,:) => null()  ! gradKEv = - d/dy(u2), in m s-2.
  real, pointer :: rv_x_v(:,:,:) => null()   ! rv_x_v = rv * v at u, in m s-2.
  real, pointer :: rv_x_u(:,:,:) => null()   ! rv_x_u = rv * u at v, in m s-2.

end type accel_diag_ptrs

!> The cont_diag_ptrs structure contains pointers to arrays with transports,
!! which can later be used for derived diagnostics, like energy balances.
type, public :: cont_diag_ptrs

! Each of the following fields has nz layers.
  real, pointer :: uh(:,:,:) => null()    ! Resolved layer thickness fluxes,
  real, pointer :: vh(:,:,:) => null()    ! in m3 s-1 or kg s-1.
  real, pointer :: uhgm(:,:,:) => null()  ! Thickness diffusion induced
  real, pointer :: vhgm(:,:,:) => null()  ! volume fluxes in m3 s-1.

! Each of the following fields is found at nz+1 interfaces.
  real, pointer :: diapyc_vel(:,:,:) => null()! The net diapycnal velocity,

end type cont_diag_ptrs

!>   The vertvisc_type structure contains vertical viscosities, drag
!! coefficients, and related fields.
type, public :: vertvisc_type
  real :: prandtl_turb       !< The Prandtl number for the turbulent diffusion
                             !! that is captured in Kd_turb.
  real, pointer, dimension(:,:) :: &
    bbl_thick_u => null(), & !< The bottom boundary layer thickness at the
                             !! u-points, in m.
    bbl_thick_v => null(), & !< The bottom boundary layer thickness at the
                             !! v-points, in m.
    kv_bbl_u => null(), &    !< The bottom boundary layer viscosity at the
                             !! u-points, in m2 s-1.
    kv_bbl_v => null(), &    !< The bottom boundary layer viscosity at the
                             !! v-points, in m2 s-1.
    ustar_bbl => null(), &   !< The turbulence velocity in the bottom boundary
                             !! layer at h points, in m s-1.
    tke_bbl => null(), &     !< A term related to the bottom boundary layer
                             !! source of turbulent kinetic energy, currently
                             !! in units of m3 s-3, but will later be changed
                             !! to W m-2.
    taux_shelf => null(), &  !< The zonal stresses on the ocean under shelves, in Pa.
    tauy_shelf => null(), &  !< The meridional stresses on the ocean under shelves, in Pa.
    tbl_thick_shelf_u => null(), & !< Thickness of the viscous top boundary
                             !< layer under ice shelves at u-points, in m.
    tbl_thick_shelf_v => null(), & !< Thickness of the viscous top boundary
                             !< layer under ice shelves at v-points, in m.
    kv_tbl_shelf_u => null(), &  !< Viscosity in the viscous top boundary layer
                             !! under ice shelves at u-points, in m2 s-1.
    kv_tbl_shelf_v => null(), &  !< Viscosity in the viscous top boundary layer
                             !! under ice shelves at u-points, in m2 s-1.
    nkml_visc_u => null(), & !< The number of layers in the viscous surface
                             !! mixed layer at u-points (nondimensional).  This
                             !! is not an integer because there may be
                             !! fractional layers, and it is stored
                             !! in terms of layers, not depth, to facilitate
                             !! the movement of the viscous boundary layer with
                             !! the flow.
    nkml_visc_v => null(), & !< The number of layers in the viscous surface
                             !! mixed layer at v-points (nondimensional).
    mld => null()            !< Instantaneous active mixing layer depth (H units).
  real, pointer, dimension(:,:,:) :: &
    ray_u => null(), &  !< The Rayleigh drag velocity to be applied to each layer
                        !! at u-points, in m s-1.
    ray_v => null(), &  !< The Rayleigh drag velocity to be applied to each layer
                        !! at v-points, in m s-1.
    kd_extra_t => null(), & !< The extra diffusivity of temperature due to
                        !! double diffusion relative to the diffusivity of
                        !! density, in m2 s-1.
    kd_extra_s => null(), & !< The extra diffusivity of salinity due to
                        !! double diffusion relative to the diffusivity of
                        !! density, in m2 s-1.
                        !   One of Kd_extra_T and Kd_extra_S is always 0.
                        ! Kd_extra_S is positive for salt fingering; Kd_extra_T
                        ! is positive for double diffusive convection.  These
                        ! are only allocated if DOUBLE_DIFFUSION is true.
    kd_turb => null(), &!< The turbulent diapycnal diffusivity at the interfaces
                        !! between each layer, in m2 s-1.
    kv_turb => null(), &!< The turbulent vertical viscosity at the interfaces
                        !! between each layer, in m2 s-1.
    tke_turb => null()  !< The turbulent kinetic energy per unit mass defined
                        !! at the interfaces between each layer, in m2 s-2.
end type vertvisc_type

!> The BT_cont_type structure contains information about the summed layer
!! transports and how they will vary as the barotropic velocity is changed.
type, public :: bt_cont_type
  real, pointer, dimension(:,:) :: &
    fa_u_ee => null(), &  ! The FA_u_XX variables are the effective open face
    fa_u_e0 => null(), &  ! areas for barotropic transport through the zonal
    fa_u_w0 => null(), &  ! faces, all in H m, with the XX indicating where
    fa_u_ww => null(), &  ! the transport is from, with _EE drawing from points
                          ! far to the east, _E0 from points nearby from the
                          ! east, _W0 nearby from the west, and _WW from far to
                          ! the west.
    ubt_ww => null(), &   ! uBT_WW is the barotropic velocity, in m s-1, beyond
                          ! which the marginal open face area is FA_u_WW.
                          ! uBT_EE must be non-negative.
    ubt_ee => null(), &   ! uBT_EE is the barotropic velocity, in m s-1, beyond
                          ! which the marginal open face area is FA_u_EE.
                          ! uBT_EE must be non-positive.
    fa_v_nn => null(), &  ! The FA_v_XX variables are the effective open face
    fa_v_n0 => null(), &  ! areas for barotropic transport through the meridional
    fa_v_s0 => null(), &  ! faces, all in H m, with the XX indicating where
    fa_v_ss => null(), &  ! the transport is from, with _NN drawing from points
                          ! far to the north, _N0 from points nearby from the
                          ! north, _S0 nearby from the south, and _SS from far
                          ! to the south.
    vbt_ss => null(), &   ! vBT_SS is the barotropic velocity, in m s-1, beyond
                          ! which the marginal open face area is FA_v_SS.
                          ! vBT_SS must be non-negative.
    vbt_nn => null()      ! vBT_NN is the barotropic velocity, in m s-1, beyond
                          ! which the marginal open face area is FA_v_NN.
                          ! vBT_NN must be non-positive.
  real, pointer, dimension(:,:,:) :: &
    h_u => null(), &      ! An effective thickness at zonal faces, in H.
    h_v => null()         ! An effective thickness at meridional faces, in H.
  type(group_pass_type) :: pass_polarity_bt, pass_fa_uv ! For group halo updates
end type bt_cont_type

contains

!> alloc_BT_cont_type allocates the arrays contained within a BT_cont_type and
!! initializes them to 0.
subroutine alloc_bt_cont_type(BT_cont, G, alloc_faces)
  type(bt_cont_type),    pointer    :: BT_cont
  type(ocean_grid_type), intent(in) :: G    !< The ocean's grid structure
  logical,     optional, intent(in) :: alloc_faces

  integer :: isd, ied, jsd, jed, IsdB, IedB, JsdB, JedB
  isd = g%isd ; ied = g%ied ; jsd = g%jsd ; jed = g%jed
  isdb = g%IsdB ; iedb = g%IedB ; jsdb = g%JsdB ; jedb = g%JedB

  if (associated(bt_cont)) call mom_error(fatal, &
    "alloc_BT_cont_type called with an associated BT_cont_type pointer.")

  allocate(bt_cont)
  allocate(bt_cont%FA_u_WW(isdb:iedb,jsd:jed)) ; bt_cont%FA_u_WW(:,:) = 0.0
  allocate(bt_cont%FA_u_W0(isdb:iedb,jsd:jed)) ; bt_cont%FA_u_W0(:,:) = 0.0
  allocate(bt_cont%FA_u_E0(isdb:iedb,jsd:jed)) ; bt_cont%FA_u_E0(:,:) = 0.0
  allocate(bt_cont%FA_u_EE(isdb:iedb,jsd:jed)) ; bt_cont%FA_u_EE(:,:) = 0.0
  allocate(bt_cont%uBT_WW(isdb:iedb,jsd:jed))  ; bt_cont%uBT_WW(:,:) = 0.0
  allocate(bt_cont%uBT_EE(isdb:iedb,jsd:jed))  ; bt_cont%uBT_EE(:,:) = 0.0

  allocate(bt_cont%FA_v_SS(isd:ied,jsdb:jedb)) ; bt_cont%FA_v_SS(:,:) = 0.0
  allocate(bt_cont%FA_v_S0(isd:ied,jsdb:jedb)) ; bt_cont%FA_v_S0(:,:) = 0.0
  allocate(bt_cont%FA_v_N0(isd:ied,jsdb:jedb)) ; bt_cont%FA_v_N0(:,:) = 0.0
  allocate(bt_cont%FA_v_NN(isd:ied,jsdb:jedb)) ; bt_cont%FA_v_NN(:,:) = 0.0
  allocate(bt_cont%vBT_SS(isd:ied,jsdb:jedb))  ; bt_cont%vBT_SS(:,:) = 0.0
  allocate(bt_cont%vBT_NN(isd:ied,jsdb:jedb))  ; bt_cont%vBT_NN(:,:) = 0.0

  if (present(alloc_faces)) then ; if (alloc_faces) then
    allocate(bt_cont%h_u(isdb:iedb,jsd:jed,1:g%ke)) ; bt_cont%h_u(:,:,:) = 0.0
    allocate(bt_cont%h_v(isd:ied,jsdb:jedb,1:g%ke)) ; bt_cont%h_v(:,:,:) = 0.0
  endif ; endif

end subroutine alloc_bt_cont_type

!> dealloc_BT_cont_type deallocates the arrays contained within a BT_cont_type.
subroutine dealloc_bt_cont_type(BT_cont)
  type(bt_cont_type), pointer :: BT_cont

  if (.not.associated(bt_cont)) return

  deallocate(bt_cont%FA_u_WW) ; deallocate(bt_cont%FA_u_W0)
  deallocate(bt_cont%FA_u_E0) ; deallocate(bt_cont%FA_u_EE)
  deallocate(bt_cont%uBT_WW)  ; deallocate(bt_cont%uBT_EE)

  deallocate(bt_cont%FA_v_SS) ; deallocate(bt_cont%FA_v_S0)
  deallocate(bt_cont%FA_v_N0) ; deallocate(bt_cont%FA_v_NN)
  deallocate(bt_cont%vBT_SS)  ; deallocate(bt_cont%vBT_NN)

  if (associated(bt_cont%h_u)) deallocate(bt_cont%h_u)
  if (associated(bt_cont%h_v)) deallocate(bt_cont%h_v)

  deallocate(bt_cont)

end subroutine dealloc_bt_cont_type

!> MOM_thermovar_chksum does diagnostic checksums on various elements of a
!! thermo_var_ptrs type for debugging.
subroutine mom_thermovar_chksum(mesg, tv, G)
  character(len=*),                    intent(in) :: mesg
  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
!   This subroutine writes out chksums for the model's basic state variables.
! Arguments: mesg - A message that appears on the chksum lines.
!  (in)      u - Zonal velocity, in m s-1.
!  (in)      v - Meridional velocity, in m s-1.
!  (in)      h - Layer thickness, in m.
!  (in)      uh - Volume flux through zonal faces = u*h*dy, m3 s-1.
!  (in)      vh - Volume flux through meridional faces = v*h*dx, in m3 s-1.
!  (in)      G - The ocean's grid structure.
  integer :: is, ie, js, je, nz
  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.
  if (associated(tv%T)) &
    call hchksum(tv%T, mesg//" tv%T",g%HI)
  if (associated(tv%S)) &
    call hchksum(tv%S, mesg//" tv%S",g%HI)
  if (associated(tv%frazil)) &
    call hchksum(tv%frazil, mesg//" tv%frazil",g%HI)
  if (associated(tv%salt_deficit)) &
    call hchksum(tv%salt_deficit, mesg//" tv%salt_deficit",g%HI)
  if (associated(tv%TempxPmE)) &
    call hchksum(tv%TempxPmE, mesg//" tv%TempxPmE",g%HI)
end subroutine mom_thermovar_chksum

end module mom_variables