SHReturnTapersMap (Fortran)

Calculate the eigenfunctions and eigenvalues of the space-concentration problem for an arbitrary region.

Usage

call SHReturnTapersMap (tapers, eigenvalues, dh_mask, n, lmax, sampling, ntapers, degrees, exitstatus)

Parameters

tapers : input, real(dp), dimension ((lmax+1)**2, ntapers)

The spherical harmonic coefficients of the tapers, arranged in columns, from best to worst concentrated. The spherical harmonic coefficients in each column are indexed according to the scheme described in YilmIndexVector.

eigenvalues : input, real(dp), dimension (ntapers)

The concentration factor for each localization window specified in the columns of tapers.

dh_mask : input, integer(int32), dimension (n, n*sampling)

A Driscoll and Healy (1994) sampled grid describing the concentration region R. All elements should either be 1 (for inside the concentration region) or 0 (for outside R).

n : input, integer(int32)

The number of latitudinal samples in dh_mask. The effective spherical harmonic bandwidth of this grid is L=n/2-1.

lmax : input, integer(int32)

The spherical harmonic bandwidth of the localization windows.

sampling : input, integer(int32)

For 1, dh_mask has n x n samples. For 2, dh_mask has n x 2n samples.

ntapers : input, optional, integer(int32), default = (lmax+1)**2

The number of best concentrated eigenvalues and corresponding eigenfunctions to return in tapers and eigenvalues. The default value is to return all tapers.

degrees : input, integer(int32), optional, dimension (lmax+1)

List of degrees to use when computing the eigenfunctions. Only those degrees where degrees(l+1) is non-zero will be employed.

exitstatus : output, optional, integer(int32)

If present, instead of executing a STOP when an error is encountered, the variable exitstatus will be returned describing the error. 0 = No errors; 1 = Improper dimensions of input array; 2 = Improper bounds for input variable; 3 = Error allocating memory; 4 = File IO error.

Description

SHReturnTapersMap will calculate the eigenfunctions of the space-concentration problem for an arbitrary concentration region specified in dh_mask (see Simons et al. (2006) for further details). The input mask dh_mask must be sampled according to the Driscoll and Healy (1994) sampling theorem with n samples in latitude, and possess a value of 1 inside the concentration region, and 0 elsewhere. dh_mask can either possess n samples in longitude (sampling=1) or 2n samples in longitude (sampling=2). Given the approximate way in which the elements of the space-concentration kernel are calculated (see ComputeDMap for details), sampling=2 should be preferred. The effective spherical harmonic bandwidth (L=N/2-1) of the grid dh_mask determines the accuracy of the results, and experience shows that this should be about 3 times larger than lmax.

The spherical harmonic coefficients of each window are given in the columns of tapers, and the corresponding concentration factors are given in eigenvaules. The spherical harmonic coefficients are ordered according to the scheme described in YilmIndexVector, which can be converted to matrix form using SHVectorToCilm, and the columns of tapers are ordered from best to worst concentrated. The localization windows are normalized such that they have unit power. If the optional parameter ntapers is specified, then only the ntapers largest eigenvalues and corresponding eigenfunctions will be calculated and returned. If the optional vector degrees is specified, then the eigenfunctions will be computed using only those degrees where degrees(l+1) is not zero.

References

Driscoll, J. R. and D. M. Healy, Computing Fourier transforms and convolutions on the 2-sphere, Adv. Appl. Math., 15, 202-250, 1994.

Simons, F. J., F. A. Dahlen, and M. A. Wieczorek, Spatiospectral concentration on a sphere, SIAM Review, 48, 504-536, 2006.

See also

computedmap, yilmindexvector, shvectortocilm