mom_spherical_harmonics module reference¶

Laplace’s spherical harmonic transforms (SHT)

Data Types¶

sht_cs

Control structure for spherical harmonic transforms.

Functions/Subroutines¶

`spherical_harmonics_forward()`	Calculates forward spherical harmonics transforms.
`spherical_harmonics_inverse()`	Calculates inverse spherical harmonics transforms.
`spherical_harmonics_init()`	Calculate precomputed coefficients.
`spherical_harmonics_end()`	Deallocate any variables allocated in spherical_harmonics_init.
`calc_lmax()`	Calculates the number of real elements (cosine) of spherical harmonics given maximum degree Nd.
`order2index()`	Calculates the one-dimensional index number at (n=0, m=m), given order m and maximum degree Nd.

Detailed Description¶

Spherical harmonics¶

This module contains the subroutines to calculate spherical harmonic transforms (SHT), namely, forward transform of a two-dimensional field into a given number of spherical harmonic modes and its inverse transform. This module is primarily used to but not limited to calculate self-attraction and loading (SAL) term, which is mostly relevant to high frequency motions such as tides. Should other needs arise in the future, this API can be easily modified. Currently, the transforms are for t-cell fields only.

This module is stemmed from SAL calculation in Model for Prediction Across Scales (MPAS)-Ocean developed by Los Alamos National Laboratory and University of Michigan [[8] and [14]]. The algorithm for forward and inverse transforms loosely follows [70].

In forward transform, a two-dimensional physical field can be projected into a series of spherical harmonics. The spherical harmonic coefficient of degree n and order m for a field \(f(\theta, \phi)\) is calculated as follows:

\[f^m_n = \int^{2\pi}_{0}\int^{\pi}_{0}f(\theta,\phi)Y^m_n(\theta,\phi)\sin\theta d\theta d\phi\]

and

\[Y^m_n(\theta,\phi) = P^m_n(\cos\theta)\exp(im\phi)\]

where \(P^m_n(\cos \theta)\) is the normalized associated Legendre polynomial of degree n and order m. \(\phi\) is the longitude and \(\theta\) is the colatitude. Or, written in the discretized form:

\[f^m_n = \sum^{Nj}_{0}\sum^{Ni}_{0}f(i,j)Y^m_n(i,j)A(i,j)/r_e^2\]

where \(A\) is the area of the cell and \(r_e\) is the radius of the Earth.

In inverse transform, the first N degree spherical harmonic coefficients are used to reconstruct a two-dimensional physical field:

\[f(\theta,\phi) = \sum^N_{n=0}\sum^{n}_{m=-n}f^m_nY^m_n(\theta,\phi)\]

The exponential coefficients are pre-computed and stored in the memory. The associated Legendre polynomials are computed “on-the-fly”, using the recurrence relationships to avoid large memory usage and take the advantage of array vectorization.

The maximum degree of the spherical harmonics is a runtime parameter and the maximum used by all SHT applications. At the moment, it is only decided by SAL_HARMONICS_DEGREE.

The forward transforms involve a global summation. Runtime flag SHT_REPRODUCING_SUM controls whether this is done in a bit-wise reproducing way or not.

References:

Barton, K.N., Pal, N., Brus, S.R., Petersen, M.R., Arbic, B.K., Engwirda, D., Roberts, A.F., Westerink, J.J., Wirasaet, D. and Schindelegger, M., 2022. Global Barotropic Tide Modeling Using Inline Self‐Attraction and Loading in MPAS‐Ocean. Journal of Advances in Modeling Earth Systems, 14(11), p.e2022MS003207. https://doi.org/10.1029/2022MS003207

Brus, S.R., Barton, K.N., Pal, N., Roberts, A.F., Engwirda, D., Petersen, M.R., Arbic, B.K., Wirasaet, D., Westerink, J.J. and Schindelegger, M., 2023. Scalable self attraction and loading calculations for unstructured ocean tide models. Ocean Modelling, p.102160. https://doi.org/10.1016/j.ocemod.2023.102160

Schaeffer, N., 2013. Efficient spherical harmonic transforms aimed at pseudospectral numerical simulations. Geochemistry, Geophysics, Geosystems, 14(3), pp.751-758. https://doi.org/10.1002/ggge.20071

Type Documentation¶

type mom_spherical_harmonics/sht_cs¶

Control structure for spherical harmonic transforms.

Type fields:

% initialized [logical] :: True if this control structure has been initialized.
% ndegree [integer] :: Maximum degree of the spherical harmonics [nondim].
% lmax [integer] :: Number of associated Legendre polynomials of nonnegative m [lmax=(ndegree+1)*(ndegree+2)/2] [nondim].
% cos_clatt [real(:,:),allocatable] :: Precomputed cosine of colatitude at the t-cells [nondim].
% pmm [real(:,:,:),allocatable] :: Precomputed associated Legendre polynomials (m=n) at the t-cells [nondim].
% cos_lont [real(:,:,:),allocatable] :: Precomputed cosine factors at the t-cells [nondim].
% sin_lont [real(:,:,:),allocatable] :: Precomputed sine factors at the t-cells [nondim].
% cos_lont_wtd [real(:,:,:),allocatable] :: Precomputed area-weighted cosine factors at the t-cells [nondim].
% sin_lont_wtd [real(:,:,:),allocatable] :: Precomputed area-weighted sine factors at the t-cells [nondim].
% a_recur [real(:,:),allocatable] :: Precomputed recurrence coefficients a [nondim].
% b_recur [real(:,:),allocatable] :: Precomputed recurrence coefficients b [nondim].
% reprod_sum [logical] :: True if use reproducible global sums.

Function/Subroutine Documentation¶

subroutine mom_spherical_harmonics/spherical_harmonics_forward(G, CS, var, Snm_Re, Snm_Im, Nd, tmp_scale)¶

Calculates forward spherical harmonics transforms.

Parameters:

g :: [in] The ocean’s grid structure.
cs :: [inout] Control structure for SHT
var :: [in] Input 2-D variable in arbitrary mks units [a]
snm_re :: [out] SHT coefficients for the real modes (cosine) in the same arbitrary units as var [a] or [A ~> a]
snm_im :: [out] SHT coefficients for the imaginary modes (sine) in the same arbitrary units as var [a] or [A ~> a]
nd :: [in] Maximum degree of the spherical harmonics overriding ndegree in the CS [nondim]
tmp_scale :: [in] A temporary rescaling factor to convert var to MKS units during the reproducing sums [a A-1 ~> 1]

Call to:

calc_lmax id_clock_sht id_clock_sht_forward id_clock_sht_global_sum mom_error_handler::mom_error order2index

subroutine mom_spherical_harmonics/spherical_harmonics_inverse(G, CS, Snm_Re, Snm_Im, var, Nd)¶

Calculates inverse spherical harmonics transforms.

Parameters:

g :: [in] The ocean’s grid structure.
cs :: [in] Control structure for SHT
snm_re :: [in] SHT coefficients for the real modes (cosine) in arbitrary units [a] or [A ~> a]
snm_im :: [in] SHT coefficients for the imaginary modes (sine) in the same arbitrary units as Snm_Re [a] or [A ~> a]
var :: [out] Output 2-D variable in the same arbitrary units
nd :: [in] Maximum degree of the spherical harmonics overriding ndegree in the CS [nondim]

Call to:

id_clock_sht id_clock_sht_inverse mom_error_handler::mom_error order2index

subroutine mom_spherical_harmonics/spherical_harmonics_init(G, param_file, CS)¶

Calculate precomputed coefficients.

Parameters:

g :: [in] The ocean’s grid structure.
param_file :: [in] A structure indicating
cs :: [inout] Control structure for spherical harmonic transforms

Call to:

calc_lmax id_clock_sht id_clock_sht_forward id_clock_sht_global_sum id_clock_sht_inverse

subroutine mom_spherical_harmonics/spherical_harmonics_end(CS)¶

Deallocate any variables allocated in spherical_harmonics_init.

Parameters:: cs :: [inout] Control structure for spherical harmonic transforms

function mom_spherical_harmonics/calc_lmax(Nd) [integer]¶

Calculates the number of real elements (cosine) of spherical harmonics given maximum degree Nd.

Return:: undefined :: Number of real spherical harmonic modes [nondim]
Parameters:: nd :: [in] Maximum degree [nondim]
Called from:: mom_self_attr_load::sal_init spherical_harmonics_forward spherical_harmonics_init

function mom_spherical_harmonics/order2index(m, Nd) [integer]¶

Calculates the one-dimensional index number at (n=0, m=m), given order m and maximum degree Nd. It is sequenced with degree (n) changing first and order (m) changing second.

Return:

undefined :: One-dimensional index number [nondim]

Parameters:

m :: [in] Current order number [nondim]
nd :: [in] Maximum degree [nondim]

Called from:

mom_self_attr_load::calc_love_scaling mom_self_attr_load::calc_sal spherical_harmonics_forward spherical_harmonics_inverse