-
Notifications
You must be signed in to change notification settings - Fork 104
/
shreturntapersmap.3
128 lines (128 loc) · 4.83 KB
/
shreturntapersmap.3
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
.\" Automatically generated by Pandoc 3.1.3
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "shreturntapersmap" "1" "2021-02-15" "Fortran 95" "SHTOOLS 4.11"
.hy
.SH SHReturnTapersMap
.PP
Calculate the eigenfunctions and eigenvalues of the space-concentration
problem for an arbitrary region.
.SH Usage
.PP
call SHReturnTapersMap (\f[V]tapers\f[R], \f[V]eigenvalues\f[R],
\f[V]dh_mask\f[R], \f[V]n\f[R], \f[V]lmax\f[R], \f[V]sampling\f[R],
\f[V]ntapers\f[R], \f[V]degrees\f[R], \f[V]exitstatus\f[R])
.SH Parameters
.TP
\f[V]tapers\f[R] : input, real(dp), dimension ((\f[V]lmax\f[R]+1)**2, \f[V]ntapers\f[R])
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 \f[V]YilmIndexVector\f[R].
.TP
\f[V]eigenvalues\f[R] : input, real(dp), dimension (\f[V]ntapers\f[R])
The concentration factor for each localization window specified in the
columns of \f[V]tapers\f[R].
.TP
\f[V]dh_mask\f[R] : input, integer(int32), dimension (\f[V]n\f[R], \f[V]n\f[R]*\f[V]sampling\f[R])
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).
.TP
\f[V]n\f[R] : input, integer(int32)
The number of latitudinal samples in \f[V]dh_mask\f[R].
The effective spherical harmonic bandwidth of this grid is
\f[V]L=n/2-1\f[R].
.TP
\f[V]lmax\f[R] : input, integer(int32)
The spherical harmonic bandwidth of the localization windows.
.TP
\f[V]sampling\f[R] : input, integer(int32)
For 1, \f[V]dh_mask\f[R] has \f[V]n x n\f[R] samples.
For 2, \f[V]dh_mask\f[R] has \f[V]n x 2n\f[R] samples.
.TP
\f[V]ntapers\f[R] : input, optional, integer(int32), default = (\f[V]lmax\f[R]+1)**2
The number of best concentrated eigenvalues and corresponding
eigenfunctions to return in \f[V]tapers\f[R] and \f[V]eigenvalues\f[R].
The default value is to return all tapers.
.TP
\f[V]degrees\f[R] : input, integer(int32), optional, dimension (\f[V]lmax\f[R]+1)
List of degrees to use when computing the eigenfunctions.
Only those degrees where \f[V]degrees(l+1)\f[R] is non-zero will be
employed.
.TP
\f[V]exitstatus\f[R] : 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.
.SH Description
.PP
\f[V]SHReturnTapersMap\f[R] will calculate the eigenfunctions of the
space-concentration problem for an arbitrary concentration region
specified in \f[V]dh_mask\f[R] (see Simons et al.\ (2006) for further
details).
The input mask \f[V]dh_mask\f[R] must be sampled according to the
Driscoll and Healy (1994) sampling theorem with \f[V]n\f[R] samples in
latitude, and possess a value of 1 inside the concentration region, and
0 elsewhere.
\f[V]dh_mask\f[R] can either possess \f[V]n\f[R] samples in longitude
(\f[V]sampling=1\f[R]) or \f[V]2n\f[R] samples in longitude
(\f[V]sampling=2\f[R]).
Given the approximate way in which the elements of the
space-concentration kernel are calculated (see \f[V]ComputeDMap\f[R] for
details), \f[V]sampling=2\f[R] should be preferred.
The effective spherical harmonic bandwidth (L=N/2-1) of the grid
\f[V]dh_mask\f[R] determines the accuracy of the results, and experience
shows that this should be about 3 times larger than \f[V]lmax\f[R].
.PP
The spherical harmonic coefficients of each window are given in the
columns of \f[V]tapers\f[R], and the corresponding concentration factors
are given in \f[V]eigenvaules\f[R].
The spherical harmonic coefficients are ordered according to the scheme
described in \f[V]YilmIndexVector\f[R], which can be converted to matrix
form using \f[V]SHVectorToCilm\f[R], and the columns of \f[V]tapers\f[R]
are ordered from best to worst concentrated.
The localization windows are normalized such that they have unit power.
If the optional parameter \f[V]ntapers\f[R] is specified, then only the
\f[V]ntapers\f[R] largest eigenvalues and corresponding eigenfunctions
will be calculated and returned.
If the optional vector \f[V]degrees\f[R] is specified, then the
eigenfunctions will be computed using only those degrees where
\f[V]degrees(l+1)\f[R] is not zero.
.SH References
.PP
Driscoll, J.
R.
and D.
M.
Healy, Computing Fourier transforms and convolutions on the 2-sphere,
Adv.
Appl.
Math., 15, 202-250, 1994.
.PP
Simons, F.
J., F.
A.
Dahlen, and M.
A.
Wieczorek, Spatiospectral concentration on a sphere, SIAM Review, 48,
504-536, 2006.
.SH See also
.PP
computedmap, yilmindexvector, shvectortocilm