charm_leg

charm_leg#

Module to work with the fully-normalized associated Legendre functions of the first kind:

  • defines the charm_pnmj structure to store Fourier coefficients of the Legendre functions,

  • allocates, initializes and frees charm_pnmj,

  • computes Fourier coefficients of Legendre functions after Fukushima (2018).

References:

  • Fukushima, T. (2018) Fast computation of sine/cosine series coefficients of associated Legendre functions of arbitrary high degree and order

  • Fukushima T (2014) Numerical computation of spherical harmonics of arbitrary degree and order by extending exponent of floating point numbers. Computers and Geosciences 63, 17-21, doi: 10.1016/j.cageo.2013.10.010

Note

This documentation is written for double precision version of CHarm.

Allocate and free the charm_pnmj structure

Functions to allocate and free charm_pnmj.

charm_pnmj *charm_leg_pnmj_malloc(unsigned long nmax, int ordering)#

Allocates Fourier coefficients of the fully-normalized associated Legendre functions up to harmonic degree nmax using the ordering scheme ordering. The Fourier coefficients are uninitialized, so their values are undefined.

ordering can be set either to CHARM_LEG_PMNJ or CHARM_LEG_PMJN.

Warning

The charm_pnmj structure created by this function must be deallocated by calling charm_leg_pnmj_free(). The usual deallocation free will not deallocate the memory and will lead to memory leaks.

Returns:

On success, returned is a pointer to the charm_pnmj structure. On error, NULL is returned.

charm_pnmj *charm_leg_pnmj_calloc(unsigned long nmax, int ordering)#

The same as charm_leg_pnmj_malloc() but all Fourier coefficients are initialized to zero.

void charm_leg_pnmj_free(charm_pnmj *pnmj)#

Frees the memory associated with pnmj. No operation is performed if pnmj is NULL.

Fourier coefficients of Legendre functions

Functions to compute the Fourier coefficients of Legendre functions and some associated useful functions.

void charm_leg_pnmj_coeffs(charm_pnmj *pnmj, unsigned long nmax, charm_err *err)#

Computes Fourier coefficients of fully normalized associated Legendre functions up to degree nmax and saves them to pnmj. The structure of pnmj->pnmj depends on pnmj->ordering. If nmax < pnmj->nmax, all Fourier coefficients in pnmj->pnmj beyond nmax are set to zero. In case of failure, the error is written to err.

The algorithm of Fukushima (2018) is employed.

References:

  • Fukushima, T. (2018) Fast computation of sine/cosine series coefficients of associated Legendre functions of arbitrary high degree and order.

unsigned long charm_leg_pnmj_j2k(unsigned long n, unsigned long j)#

Transforms a wave-number-related variable j to the wave-number k of a Fourier coefficient of fully-normalized associated Legendre function of degree n (see Section C.1 of Fukushima, 2018),.

\[k = \left[ 1 - (-1)^n \right] / 2 + 2 j{.}\]

Parameters:

  • n – [in] Harmonic degree of the Legendre function.

  • j – [in] Variable related to the wave-number k.

Returns:

Wave-number k of the Fourier coefficient of a Legendre function.

unsigned long charm_leg_pnmj_k2j(unsigned long k)#

Transforms a wave-number k of a Fourier coefficient of fully-normalized associated Legendre function to the wave-number-related variable j (see Section C.1 of Fukushima, 2018),.

\[j = \left[ k / 2 \right]_{\mathrm{floor}}{.}\]

Parameters:

k – [in] Wave-number of a Fourier coefficients of Legendre function.

Returns:

Wave-number-related variable j of the Fourier coefficient of a Legendre function.

Enums

enum [anonymous]#

Ordering scheme of charm_pnmj.pnmj (a 3D array).

Values:

enumerator CHARM_LEG_PMNJ#

Order m, degree n, wave-number-related variable j. Note that j is not a wave-number k, but is related to it (see charm_leg_pnmj_j2k() and charm_leg_pnmj_k2j()).

enumerator CHARM_LEG_PMJN#

Order m, wave-number-related variable j, degree n.

struct charm_pnmj#

Structure to store Fourier coefficients of the fully-normalized associated Legendre functions.

Public Members

unsigned long nmax#

Maximum harmonic degree of the Fourier coefficients.

int ordering#

Ordering scheme of the Fourier coefficients in charm_pnmj.pnmj: either CHARM_LEG_PMNJ or CHARM_LEG_PMJN.

size_t npnmj#

Total number of Fourier coefficients \(P_{nmj}\) in charm_pnmj.pnmj.

double ***pnmj#

Fourier coefficients.

The structure of charm_pnmj.pnmj depends on charm_pnmj.ordering, which takes one of two constants: CHARM_LEG_PMNJ or CHARM_LEG_PMJN.

If charm_pnmj.ordering is CHARM_LEG_PMNJ, the following loop order is recommended for fast sequential access to the \(P_{nmj}\) coefficients: harmonic order m, harmonic degree n and wave-number-related variable j; e.g.:

charm_pnmj *pnmj = charm_leg_pnmj_calloc(nmax, CHARM_LEG_PMNJ)
for (unsigned long m = 0; m <= nmax; m++)
    for (unsigned long n = m; n <= nmax; n++)
        for (unsigned long j = 0; j <= (n / 2); j++)
            pnmj->pnmj[m][n - m][j];

If charm_pnmj.ordering is CHARM_LEG_PMJN, the recommended loop order is:

charm_pnmj *pnmj = charm_leg_pnmj_calloc(nmax, CHARM_LEG_PMJN)
for (unsigned long m = 0; m <= nmax; m++)
    for (unsigned long j = 0; j <= (nmax / 2); j++)
        for (unsigned long n = CHARM_MAX(m, 2 * j); n <= nmax; n++)
            pnmj->pnmj[m][j][n - CHARM_MAX(m, 2 * j)];

The coefficients (elements) in charm_pnmj.pnmj are stored in a single contiguous block of memory.

Warning

j does not represent the wave-number k, but it is closely related to it (see charm_leg_pnmj_j2k() and charm_leg_pnmj_k2j()).