Skip to content

Commit

Permalink
Fix and tidy Wright_EOS API documentation
Browse files Browse the repository at this point in the history 
  Cleaned up the comments describing the routines and added a proper doxygen
namespace block at the end of the MOM_EOS_Wright and MOM_EOS_Wright_full
modules, based on changes that A. Adcroft had on a detached branch of MOM6.
Only comments are changed, and all answers are bitwise identical.
  • Loading branch information
@Hallberg-NOAA
Hallberg-NOAA committed Apr 22, 2023
1 parent 7a04018 commit 010b4dc
Show file tree
Hide file tree
Showing 2 changed files with 135 additions and 127 deletions.
134 changes: 69 additions & 65 deletions src/equation_of_state/MOM_EOS_Wright.F90
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,6 @@ module MOM_EOS_Wright

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

!***********************************************************************
!* The subroutines in this file implement the equation of state for *
!* sea water using the formulae given by Wright, 1997, J. Atmos. *
!* Ocean. Tech., 14, 735-740. Coded by R. Hallberg, 7/00. *
!***********************************************************************

use MOM_hor_index, only : hor_index_type

implicit none ; private
Expand All @@ -20,40 +14,34 @@ module MOM_EOS_Wright
public calculate_density_second_derivs_wright
public int_density_dz_wright, int_spec_vol_dp_wright

! A note on unit descriptions in comments: MOM6 uses units that can be rescaled for dimensional
! consistency testing. These are noted in comments with units like Z, H, L, and T, along with
! their mks counterparts with notation like "a velocity [Z T-1 ~> m s-1]". If the units
! vary with the Boussinesq approximation, the Boussinesq variant is given first.


!> Compute the in situ density of sea water (in [kg m-3]), or its anomaly with respect to
!! a reference density, from salinity in practical salinity units ([PSU]), potential
!! temperature (in degrees Celsius [degC]), and pressure [Pa], using the expressions from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740 with the reduced range fit coefficients.
interface calculate_density_wright
module procedure calculate_density_scalar_wright, calculate_density_array_wright
end interface calculate_density_wright

!> Compute the in situ specific volume of sea water (in [m3 kg-1]), or an anomaly with respect
!! to a reference specific volume, from salinity in practical salinity units ([PSU]), potential
!! temperature (in degrees Celsius [degC]), and pressure [Pa], using the expressions from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740 with the reduced range fit coefficients.
interface calculate_spec_vol_wright
module procedure calculate_spec_vol_scalar_wright, calculate_spec_vol_array_wright
end interface calculate_spec_vol_wright

!> For a given thermodynamic state, return the derivatives of density with temperature and salinity
!> Compute the derivatives of density with temperature and salinity
interface calculate_density_derivs_wright
module procedure calculate_density_derivs_scalar_wright, calculate_density_derivs_array_wright
end interface calculate_density_derivs_wright

!> For a given thermodynamic state, return the second derivatives of density with various combinations
!> Compute the second derivatives of density with various combinations
!! of temperature, salinity, and pressure
interface calculate_density_second_derivs_wright
module procedure calculate_density_second_derivs_scalar_wright, calculate_density_second_derivs_array_wright
end interface calculate_density_second_derivs_wright

!>@{ Parameters in the Wright equation of state using the restricted range formula, which is a fit to the UNESCO
!>@{ Parameters in the Wright equation of state using the reduced range formula, which is a fit to the UNESCO
! equation of state for the restricted range: -2 < theta < 30 [degC], 28 < S < 38 [PSU], 0 < p < 5e7 [Pa].

! Note that a0/a1 ~= 2028 [degC] ; a0/a2 ~= -6343 [PSU]
Expand All @@ -78,25 +66,19 @@ module MOM_EOS_Wright

contains

!> This subroutine computes the in situ density of sea water (rho in
!! [kg m-3]) from salinity (S [PSU]), potential temperature
!! (T [degC]), and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!> Computes the in situ density of sea water for scalar inputs and outputs.
!!
!! Returns the in situ density of sea water (rho in [kg m-3]) from salinity (S [PSU]),
!! potential temperature (T [degC]), and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740 with the reduced range fit coefficients.
subroutine calculate_density_scalar_wright(T, S, pressure, rho, rho_ref)
real, intent(in) :: T !< Potential temperature relative to the surface [degC].
real, intent(in) :: S !< Salinity [PSU].
real, intent(in) :: pressure !< pressure [Pa].
real, intent(out) :: rho !< In situ density [kg m-3].
real, optional, intent(in) :: rho_ref !< A reference density [kg m-3].

! *====================================================================*
! * This subroutine computes the in situ density of sea water (rho in *
! * [kg m-3]) from salinity (S [PSU]), potential temperature *
! * (T [degC]), and pressure [Pa]. It uses the expression from *
! * Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740. *
! * Coded by R. Hallberg, 7/00 *
! *====================================================================*

! Local variables
real, dimension(1) :: T0 ! A 1-d array with a copy of the potential temperature [degC]
real, dimension(1) :: S0 ! A 1-d array with a copy of the salinity [PSU]
real, dimension(1) :: pressure0 ! A 1-d array with a copy of the pressure [Pa]
Expand All @@ -111,10 +93,11 @@ subroutine calculate_density_scalar_wright(T, S, pressure, rho, rho_ref)

end subroutine calculate_density_scalar_wright

!> This subroutine computes the in situ density of sea water (rho in
!! [kg m-3]) from salinity (S [PSU]), potential temperature
!! (T [degC]), and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!> Computes the in situ density of sea water for 1-d array inputs and outputs.
!!
!! Returns the in situ density of sea water (rho in [kg m-3]) from salinity (S [PSU]),
!! potential temperature (T [degC]), and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740 with the reduced range fit coefficients.
subroutine calculate_density_array_wright(T, S, pressure, rho, start, npts, rho_ref)
real, dimension(:), intent(in) :: T !< potential temperature relative to the surface [degC].
real, dimension(:), intent(in) :: S !< salinity [PSU].
Expand All @@ -124,7 +107,6 @@ subroutine calculate_density_array_wright(T, S, pressure, rho, start, npts, rho_
integer, intent(in) :: npts !< the number of values to calculate.
real, optional, intent(in) :: rho_ref !< A reference density [kg m-3].

! Original coded by R. Hallberg, 7/00, anomaly coded in 3/18.
! Local variables
real :: al0 ! The specific volume at 0 lambda in the Wright EOS [m3 kg-1]
real :: p0 ! The pressure offset in the Wright EOS [Pa]
Expand Down Expand Up @@ -155,10 +137,11 @@ subroutine calculate_density_array_wright(T, S, pressure, rho, start, npts, rho_

end subroutine calculate_density_array_wright

!> This subroutine computes the in situ specific volume of sea water (specvol in
!! [m3 kg-1]) from salinity (S [PSU]), potential temperature (T [degC])
!! and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!> Computes the Wright in situ specific volume of sea water for scalar inputs and outputs.
!!
!! Returns the in situ specific volume of sea water (specvol in [m3 kg-1]) from salinity (S [PSU]),
!! potential temperature (T [degC]) and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740 with the reduced range fit coefficients.
!! If spv_ref is present, specvol is an anomaly from spv_ref.
subroutine calculate_spec_vol_scalar_wright(T, S, pressure, specvol, spv_ref)
real, intent(in) :: T !< potential temperature relative to the surface [degC].
Expand All @@ -179,10 +162,11 @@ subroutine calculate_spec_vol_scalar_wright(T, S, pressure, specvol, spv_ref)
specvol = spv0(1)
end subroutine calculate_spec_vol_scalar_wright

!> This subroutine computes the in situ specific volume of sea water (specvol in
!! [m3 kg-1]) from salinity (S [PSU]), potential temperature (T [degC])
!! and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!> Computes the Wright in situ specific volume of sea water for 1-d array inputs and outputs.
!!
!! Returns the in situ specific volume of sea water (specvol in [m3 kg-1]) from salinity (S [PSU]),
!! potential temperature (T [degC]) and pressure [Pa]. It uses the expression from
!! Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740 with the reduced range fit coefficients.
!! If spv_ref is present, specvol is an anomaly from spv_ref.
subroutine calculate_spec_vol_array_wright(T, S, pressure, specvol, start, npts, spv_ref)
real, dimension(:), intent(in) :: T !< potential temperature relative to the
Expand Down Expand Up @@ -213,7 +197,7 @@ subroutine calculate_spec_vol_array_wright(T, S, pressure, specvol, start, npts,
enddo
end subroutine calculate_spec_vol_array_wright

!> For a given thermodynamic state, return the thermal/haline expansion coefficients
!> Return the thermal/haline expansion coefficients for 1-d array inputs and outputs
subroutine calculate_density_derivs_array_wright(T, S, pressure, drho_dT, drho_dS, start, npts)
real, intent(in), dimension(:) :: T !< Potential temperature relative to the
!! surface [degC].
Expand Down Expand Up @@ -250,8 +234,10 @@ subroutine calculate_density_derivs_array_wright(T, S, pressure, drho_dT, drho_d

end subroutine calculate_density_derivs_array_wright

!> The scalar version of calculate_density_derivs which promotes scalar inputs to a 1-element array and then
!! demotes the output back to a scalar
!> Return the thermal/haline expansion coefficients for scalar inputs and outputs
!!
!! The scalar version of calculate_density_derivs promotes scalar inputs to 1-element array
!! and then demotes the output back to a scalar
subroutine calculate_density_derivs_scalar_wright(T, S, pressure, drho_dT, drho_dS)
real, intent(in) :: T !< Potential temperature relative to the surface [degC].
real, intent(in) :: S !< Salinity [PSU].
Expand All @@ -277,7 +263,7 @@ subroutine calculate_density_derivs_scalar_wright(T, S, pressure, drho_dT, drho_

end subroutine calculate_density_derivs_scalar_wright

!> Second derivatives of density with respect to temperature, salinity, and pressure
!> Second derivatives of density with respect to temperature, salinity, and pressure for 1-d array inputs and outputs.
subroutine calculate_density_second_derivs_array_wright(T, S, P, drho_ds_ds, drho_ds_dt, drho_dt_dt, &
drho_ds_dp, drho_dt_dp, start, npts)
real, dimension(:), intent(in ) :: T !< Potential temperature referenced to 0 dbar [degC]
Expand Down Expand Up @@ -337,8 +323,10 @@ subroutine calculate_density_second_derivs_array_wright(T, S, P, drho_ds_ds, drh

end subroutine calculate_density_second_derivs_array_wright

!> Second derivatives of density with respect to temperature, salinity, and pressure for scalar inputs. Inputs
!! promoted to 1-element array and output demoted to scalar
!> Second derivatives of density with respect to temperature, salinity, and pressure for scalar inputs.
!!
!! The scalar version of calculate_density_second_derivs promotes scalar inputs to 1-element array
!! and then demotes the output back to a scalar
subroutine calculate_density_second_derivs_scalar_wright(T, S, P, drho_ds_ds, drho_ds_dt, drho_dt_dt, &
drho_ds_dp, drho_dt_dp)
real, intent(in ) :: T !< Potential temperature referenced to 0 dbar
Expand Down Expand Up @@ -379,8 +367,8 @@ subroutine calculate_density_second_derivs_scalar_wright(T, S, P, drho_ds_ds, dr

end subroutine calculate_density_second_derivs_scalar_wright

!> For a given thermodynamic state, return the partial derivatives of specific volume
!! with temperature and salinity
!> Return the partial derivatives of specific volume with temperature and salinity
!! for 1-d array inputs and outputs
subroutine calculate_specvol_derivs_wright(T, S, pressure, dSV_dT, dSV_dS, start, npts)
real, intent(in), dimension(:) :: T !< Potential temperature relative to the surface [degC].
real, intent(in), dimension(:) :: S !< Salinity [PSU].
Expand Down Expand Up @@ -414,11 +402,7 @@ subroutine calculate_specvol_derivs_wright(T, S, pressure, dSV_dT, dSV_dS, start

end subroutine calculate_specvol_derivs_wright

!> This subroutine computes the in situ density of sea water (rho in [kg m-3])
!! and the compressibility (drho/dp = C_sound^-2) (drho_dp [s2 m-2]) from
!! salinity (sal [PSU]), potential temperature (T [degC]), and pressure [Pa].
!! It uses the expressions from Wright, 1997, J. Atmos. Ocean. Tech., 14, 735-740.
!! Coded by R. Hallberg, 1/01
!> Computes the compressibility of seawater for 1-d array inputs and outputs
subroutine calculate_compress_wright(T, S, pressure, rho, drho_dp, start, npts)
real, intent(in), dimension(:) :: T !< Potential temperature relative to the surface [degC].
real, intent(in), dimension(:) :: S !< Salinity [PSU].
Expand All @@ -430,7 +414,6 @@ subroutine calculate_compress_wright(T, S, pressure, rho, drho_dp, start, npts)
integer, intent(in) :: start !< The starting point in the arrays.
integer, intent(in) :: npts !< The number of values to calculate.

! Coded by R. Hallberg, 1/01
! Local variables
real :: al0 ! The specific volume at 0 lambda in the Wright EOS [m3 kg-1]
real :: p0 ! The pressure offset in the Wright EOS [Pa]
Expand All @@ -449,9 +432,11 @@ subroutine calculate_compress_wright(T, S, pressure, rho, drho_dp, start, npts)
enddo
end subroutine calculate_compress_wright

!> This subroutine calculates analytical and nearly-analytical integrals of
!! pressure anomalies across layers, which are required for calculating the
!! finite-volume form pressure accelerations in a Boussinesq model.
!> Calculates analytical and nearly-analytical integrals, in geopotential across layers, of pressure
!! anomalies, which are required for calculating the finite-volume form pressure accelerations in a
!! Boussinesq model. There are essentially no free assumptions, apart from the use of Boole's rule
!! rule to do the horizontal integrals, and from a truncation in the series for log(1-eps/1+eps)
!! that assumes that |eps| < 0.34.
subroutine int_density_dz_wright(T, S, z_t, z_b, rho_ref, rho_0, G_e, HI, &
dpa, intz_dpa, intx_dpa, inty_dpa, bathyT, dz_neglect, &
useMassWghtInterp, rho_scale, pres_scale, temp_scale, saln_scale, Z_0p)
Expand Down Expand Up @@ -707,12 +692,11 @@ subroutine int_density_dz_wright(T, S, z_t, z_b, rho_ref, rho_0, G_e, HI, &

end subroutine int_density_dz_wright

!> This subroutine calculates analytical and nearly-analytical integrals in
!! pressure across layers of geopotential anomalies, which are required for
!! calculating the finite-volume form pressure accelerations in a non-Boussinesq
!! model. There are essentially no free assumptions, apart from the use of
!! Boole's rule to do the horizontal integrals, and from a truncation in the
!! series for log(1-eps/1+eps) that assumes that |eps| < 0.34.
!> Calculates analytical and nearly-analytical integrals, in pressure across layers, of geopotential
!! anomalies, which are required for calculating the finite-volume form pressure accelerations in a
!! non-Boussinesq model. There are essentially no free assumptions, apart from the use of Boole's
!! rule to do the horizontal integrals, and from a truncation in the series for log(1-eps/1+eps)
!! that assumes that |eps| < 0.34.
subroutine int_spec_vol_dp_wright(T, S, p_t, p_b, spv_ref, HI, dza, &
intp_dza, intx_dza, inty_dza, halo_size, bathyP, dP_neglect, &
useMassWghtInterp, SV_scale, pres_scale, temp_scale, saln_scale)
Expand Down Expand Up @@ -947,4 +931,24 @@ subroutine int_spec_vol_dp_wright(T, S, p_t, p_b, spv_ref, HI, dza, &
enddo ; enddo ; endif
end subroutine int_spec_vol_dp_wright

!> \namespace mom_eos_wright
!!
!! \section section_EOS_Wright Wright equation of state
!!
!! Wright, 1997, provide an approximation for the in situ density as a function of
!! potential temperature, salinity, and pressure. The formula follow the Tumlirz
!! equation of state which are easier to evaluate and make efficient.
!!
!! Two ranges are provided by Wright: a "full" range and "reduced" range. The version in this
!! module uses the reduced range.
!!
!! Originally coded in 2000 by R. Hallberg.
!! Anomaly form coded in 3/18.
!!
!! \subsection section_EOS_Wright_references References
!!
!! Wright, D., 1997: An Equation of State for Use in Ocean Models: Eckart's Formula Revisited.
!! J. Ocean. Atmosph. Tech., 14 (3), 735-740.
!! https://journals.ametsoc.org/doi/abs/10.1175/1520-0426%281997%29014%3C0735%3AAEOSFU%3E2.0.CO%3B2

end module MOM_EOS_Wright
Loading

0 comments on commit 010b4dc

Please sign in to comment.