MOM_unit_scaling.F90

!> Provides a transparent unit rescaling type to facilitate dimensional consistency testing
module mom_unit_scaling
 
! This file is part of MOM6. See LICENSE.md for the license.
 
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 unit_scaling_init, unit_scaling_end, fix_restart_unit_scaling
 
!> Describes various unit conversion factors
type, public :: unit_scale_type
  real :: m_to_z !< A constant that translates distances in meters to the units of depth.
  real :: z_to_m !< A constant that translates distances in the units of depth to meters.
  real :: m_to_l !< A constant that translates lengths in meters to the units of horizontal lengths.
  real :: l_to_m !< A constant that translates lengths in the units of horizontal lengths to meters.
  real :: s_to_t !< A constant that translates time intervals in seconds to the units of time.
  real :: t_to_s !< A constant that translates the units of time to seconds.
  real :: r_to_kg_m3 !< A constant that translates the units of density to kilograms per meter cubed.
  real :: kg_m3_to_r !< A constant that translates kilograms per meter cubed to the units of density.
  real :: q_to_j_kg  !< A constant that translates the units of enthalpy to Joules per kilogram.
  real :: j_kg_to_q  !< A constant that translates Joules per kilogram to the units of enthalpy.
 
  ! These are useful combinations of the fundamental scale conversion factors above.
  real :: z_to_l          !< Convert vertical distances to lateral lengths
  real :: l_to_z          !< Convert lateral lengths to vertical distances
  real :: l_t_to_m_s      !< Convert lateral velocities from L T-1 to m s-1.
  real :: m_s_to_l_t      !< Convert lateral velocities from m s-1 to L T-1.
  real :: l_t2_to_m_s2    !< Convert lateral accelerations from L T-2 to m s-2.
  real :: z2_t_to_m2_s    !< Convert vertical diffusivities from Z2 T-1 to m2 s-1.
  real :: m2_s_to_z2_t    !< Convert vertical diffusivities from m2 s-1 to Z2 T-1.
  real :: w_m2_to_qrz_t   !< Convert heat fluxes from W m-2 to Q R Z T-1.
  real :: qrz_t_to_w_m2   !< Convert heat fluxes from Q R Z T-1 to W m-2.
  ! Not used enough:  real :: kg_m2_to_RZ   !< Convert mass loads from kg m-2 to R Z.
  real :: rz_to_kg_m2     !< Convert mass loads from R Z to kg m-2.
  real :: kg_m2s_to_rz_t  !< Convert mass fluxes from kg m-2 s-1 to R Z T-1.
  real :: rz_t_to_kg_m2s  !< Convert mass fluxes from R Z T-1 to kg m-2 s-1.
  real :: rz3_t3_to_w_m2  !< Convert turbulent kinetic energy fluxes from R Z3 T-3 to W m-2.
  real :: w_m2_to_rz3_t3  !< Convert turbulent kinetic energy fluxes from W m-2 to R Z3 T-3.
  real :: rl2_t2_to_pa    !< Convert pressures from R L2 T-2 to Pa.
  ! Not used enough:  real :: Pa_to_RL2_T2    !< Convert pressures from Pa to R L2 T-2.
 
  ! These are used for changing scaling across restarts.
  real :: m_to_z_restart = 0.0 !< A copy of the m_to_Z that is used in restart files.
  real :: m_to_l_restart = 0.0 !< A copy of the m_to_L that is used in restart files.
  real :: s_to_t_restart = 0.0 !< A copy of the s_to_T that is used in restart files.
  real :: kg_m3_to_r_restart = 0.0 !< A copy of the kg_m3_to_R that is used in restart files.
  real :: j_kg_to_q_restart = 0.0 !< A copy of the J_kg_to_Q that is used in restart files.
end type unit_scale_type
 
contains
 
!> Allocates and initializes the ocean model unit scaling type
subroutine unit_scaling_init( param_file, US )
  type(param_file_type), optional, intent(in) :: param_file !< Parameter file handle/type
  type(unit_scale_type), optional, pointer    :: us         !< A dimensional unit scaling type
 
  ! This routine initializes a unit_scale_type structure (US).
 
  ! Local variables
  integer :: z_power, l_power, t_power, r_power, q_power
  real    :: z_rescale_factor, l_rescale_factor, t_rescale_factor, r_rescale_factor, q_rescale_factor
  ! This include declares and sets the variable "version".
# include "version_variable.h"
  character(len=16) :: mdl = "MOM_unit_scaling"
 
  if (.not.present(us)) return
 
  if (associated(us)) call mom_error(fatal, &
     'unit_scaling_init: called with an associated US pointer.')
  allocate(us)
 
  if (present(param_file)) then
    ! Read all relevant parameters and write them to the model log.
    call log_version(param_file, mdl, version, &
                 "Parameters for doing unit scaling of variables.", debugging=.true.)
    call get_param(param_file, mdl, "Z_RESCALE_POWER", z_power, &
                 "An integer power of 2 that is used to rescale the model's "//&
                 "internal units of depths and heights.  Valid values range from -300 to 300.", &
                 units="nondim", default=0, debuggingparam=.true.)
    call get_param(param_file, mdl, "L_RESCALE_POWER", l_power, &
                 "An integer power of 2 that is used to rescale the model's "//&
                 "internal units of lateral distances.  Valid values range from -300 to 300.", &
                 units="nondim", default=0, debuggingparam=.true.)
    call get_param(param_file, mdl, "T_RESCALE_POWER", t_power, &
                 "An integer power of 2 that is used to rescale the model's "//&
                 "internal units of time.  Valid values range from -300 to 300.", &
                 units="nondim", default=0, debuggingparam=.true.)
    call get_param(param_file, mdl, "R_RESCALE_POWER", r_power, &
                 "An integer power of 2 that is used to rescale the model's "//&
                 "internal units of density.  Valid values range from -300 to 300.", &
                 units="nondim", default=0, debuggingparam=.true.)
    call get_param(param_file, mdl, "Q_RESCALE_POWER", q_power, &
                 "An integer power of 2 that is used to rescale the model's "//&
                   "internal units of heat content.  Valid values range from -300 to 300.", &
                   units="nondim", default=0, debuggingparam=.true.)
  else
    z_power = 0 ; l_power = 0 ; t_power = 0 ; r_power = 0 ; q_power = 0
  endif
 
  if (abs(z_power) > 300) call mom_error(fatal, "unit_scaling_init: "//&
                 "Z_RESCALE_POWER is outside of the valid range of -300 to 300.")
  if (abs(l_power) > 300) call mom_error(fatal, "unit_scaling_init: "//&
                 "L_RESCALE_POWER is outside of the valid range of -300 to 300.")
  if (abs(t_power) > 300) call mom_error(fatal, "unit_scaling_init: "//&
                 "T_RESCALE_POWER is outside of the valid range of -300 to 300.")
  if (abs(r_power) > 300) call mom_error(fatal, "unit_scaling_init: "//&
                 "R_RESCALE_POWER is outside of the valid range of -300 to 300.")
  if (abs(q_power) > 300) call mom_error(fatal, "unit_scaling_init: "//&
                 "Q_RESCALE_POWER is outside of the valid range of -300 to 300.")
 
  z_rescale_factor = 1.0
  if (z_power /= 0) z_rescale_factor = 2.0**z_power
  us%Z_to_m = 1.0 * z_rescale_factor
  us%m_to_Z = 1.0 / z_rescale_factor
 
  l_rescale_factor = 1.0
  if (l_power /= 0) l_rescale_factor = 2.0**l_power
  us%L_to_m = 1.0 * l_rescale_factor
  us%m_to_L = 1.0 / l_rescale_factor
 
  t_rescale_factor = 1.0
  if (t_power /= 0) t_rescale_factor = 2.0**t_power
  us%T_to_s = 1.0 * t_rescale_factor
  us%s_to_T = 1.0 / t_rescale_factor
 
  r_rescale_factor = 1.0
  if (r_power /= 0) r_rescale_factor = 2.0**r_power
  us%R_to_kg_m3 = 1.0 * r_rescale_factor
  us%kg_m3_to_R = 1.0 / r_rescale_factor
 
  q_rescale_factor = 1.0
  if (q_power /= 0) q_rescale_factor = 2.0**q_power
  us%Q_to_J_kg = 1.0 * q_rescale_factor
  us%J_kg_to_Q = 1.0 / q_rescale_factor
 
  ! These are useful combinations of the fundamental scale conversion factors set above.
  us%Z_to_L = us%Z_to_m * us%m_to_L
  us%L_to_Z = us%L_to_m * us%m_to_Z
  ! Horizontal velocities:
  us%L_T_to_m_s = us%L_to_m * us%s_to_T
  us%m_s_to_L_T = us%m_to_L * us%T_to_s
  ! Horizontal accelerations:
  us%L_T2_to_m_s2 = us%L_to_m * us%s_to_T**2
    ! It does not look like US%m_s2_to_L_T2 would be used, so it does not exist.
  ! Vertical diffusivities and viscosities:
  us%Z2_T_to_m2_s = us%Z_to_m**2 * us%s_to_T
  us%m2_s_to_Z2_T = us%m_to_Z**2 * us%T_to_s
  ! Column mass loads:
  us%RZ_to_kg_m2  = us%R_to_kg_m3 * us%Z_to_m
    ! It does not seem like US%kg_m2_to_RZ would be used enough in MOM6 to justify its existence.
  ! Vertical mass fluxes:
  us%kg_m2s_to_RZ_T = us%kg_m3_to_R * us%m_to_Z * us%T_to_s
  us%RZ_T_to_kg_m2s = us%R_to_kg_m3 * us%Z_to_m * us%s_to_T
  ! Turbulent kinetic energy vertical fluxes:
  us%RZ3_T3_to_W_m2 = us%R_to_kg_m3 * us%Z_to_m**3 * us%s_to_T**3
  us%W_m2_to_RZ3_T3 = us%kg_m3_to_R * us%m_to_Z**3 * us%T_to_s**3
  ! Vertical heat fluxes:
  us%W_m2_to_QRZ_T = us%J_kg_to_Q * us%kg_m3_to_R * us%m_to_Z * us%T_to_s
  us%QRZ_T_to_W_m2 = us%Q_to_J_kg * us%R_to_kg_m3 * us%Z_to_m * us%s_to_T
  ! Pressures:
  us%RL2_T2_to_Pa = us%R_to_kg_m3 * us%L_T_to_m_s**2
    ! It does not seem like US%Pa_to_RL2_T2 would be used enough in MOM6 to justify its existence.
  ! US%Pa_to_RL2_T2 = US%kg_m3_to_R * US%m_s_to_L_T**2
 
end subroutine unit_scaling_init
 
!> Set the unit scaling factors for output to restart files to the unit scaling
!! factors for this run.
subroutine fix_restart_unit_scaling(US)
  type(unit_scale_type), intent(inout) :: us !< A dimensional unit scaling type
 
  us%m_to_Z_restart = us%m_to_Z
  us%m_to_L_restart = us%m_to_L
  us%s_to_T_restart = us%s_to_T
  us%kg_m3_to_R_restart = us%kg_m3_to_R
  us%J_kg_to_Q_restart = us%J_kg_to_Q
 
end subroutine fix_restart_unit_scaling
 
!> Deallocates a unit scaling structure.
subroutine unit_scaling_end( US )
  type(unit_scale_type), pointer :: us !< A dimensional unit scaling type
 
  deallocate( us )
 
end subroutine unit_scaling_end
 
end module mom_unit_scaling