/
computedmap.1
109 lines (109 loc) · 4.27 KB
/
computedmap.1
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
.\" Automatically generated by Pandoc 2.10
.\"
.TH "computedmap" "1" "2020-04-07" "Fortran 95" "SHTOOLS 4.7"
.hy
.SH ComputeDMap
.PP
Compute the space-concentration kernel of an arbitrary mask on the
sphere.
.SH Usage
.PP
call ComputeDMap (\f[C]dij\f[R], \f[C]dh_mask\f[R], \f[C]n\f[R],
\f[C]lmax\f[R], \f[C]sampling\f[R], \f[C]degrees\f[R],
\f[C]exitstatus\f[R])
.SH Parameters
.TP
\f[B]\f[CB]dij\f[B]\f[R] : output, real(dp), dimension ( (\f[B]\f[CB]lmax\f[B]\f[R]+1)**2, (\f[B]\f[CB]lmax\f[B]\f[R]+1)**2 )
The space-concentration kernel corresponding to the mask dh_mask.
.TP
\f[B]\f[CB]dh_mask\f[B]\f[R] : input, integer, dimension (\f[B]\f[CB]n\f[B]\f[R], \f[B]\f[CB]sampling\f[B]\f[R]*\f[B]\f[CB]n\f[B]\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[B]\f[CB]n\f[B]\f[R] : input, integer
The number of latitudinal samples in \f[C]dh_mask\f[R].
The effective spherical harmonic bandwidth of this grid is
\f[C]L=n/2-1\f[R].
.TP
\f[B]\f[CB]lmax\f[B]\f[R] : input, integer
The maximum spherical harmonic degree of the matrix \f[C]dij\f[R].
.TP
\f[B]\f[CB]sampling\f[B]\f[R] : input, optional, integer, default = 1
For 1 (default), \f[C]dh_mask\f[R] has \f[C]n\f[R] x \f[C]n\f[R]
samples.
For 2, \f[C]dh_mask\f[R] has \f[C]n\f[R] x \f[C]2n\f[R] samples.
.TP
\f[B]\f[CB]degrees\f[B]\f[R] : input, integer, optional, dimension (\f[B]\f[CB]lmax\f[B]\f[R]+1)
List of degrees to compute.
If degrees(l+1) is 0, do not compute degree l of the kernel.
.TP
\f[B]\f[CB]exitstatus\f[B]\f[R] : output, optional, integer
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[C]ComputeDMap\f[R] will calculate the space-concentration kernel for
a generic mask defined on the sphere.
The input mask \f[C]dh_mask\f[R] must be sampled according to the
Driscoll and Healy (1994) sampling theorem with \f[C]n\f[R] samples in
latitude, and possess a value of 1 inside the concentration region, and
0 elsewhere.
\f[C]dh_mask\f[R] can either possess \f[C]n\f[R] samples in longitude
(\f[C]sampling=1\f[R]) or \f[C]2n\f[R] samples in longitude
(\f[C]sampling=2\f[R]).
Given the approximate way in which the elements of \f[C]dij\f[R] are
calculated (see below), \f[C]sampling=2\f[R] should be preferred.
\f[C]dij\f[R] is symmetric, and the elements are ordered according to
the scheme described in \f[C]YilmIndexVector\f[R].
See Simons et al.\ (2006) for further details.
If the optional vector \f[C]degrees\f[R] is specified, then the matrix
will be computed only for elements where \f[C]degrees(l+1)\f[R] is not
zero.
.PP
The elements of DIJ are explicitly given by
.PP
\f[C]Dlm,l\[aq]m\[aq] = 1/(4pi) Integral_R Ylm Yl\[aq]m\[aq] dOmega\f[R],
.PP
where \f[C]R\f[R] is the concentration region.
In this routine, all values of \f[C]l\[aq]m\[aq]\f[R] are calculated in
a single spherical harmonic transform for a given value of \f[C]lm\f[R]
according to
.PP
\f[C]Dl\[aq]m\[aq] = 1/(4pi) Integral_Omega F Yl\[aq]m\[aq] dOmega\f[R].
.PP
where
.PP
\f[C]F = Ylm dh_mask\f[R].
.PP
The function \f[C]F\f[R] is in general not a polynomial, and thus the
coefficients \f[C]Dl\[aq]m\[aq]\f[R] should not be expected to be exact.
For this reason, the effective spherical harmonic degree of the input
mask (\f[C]L=n/2-1\f[R]) should be greater than \f[C]lmax\f[R].
The exact value of \f[C]n\f[R] should be chosen such that further
increases in \f[C]n\f[R] do not alter the returned eigenvalues.
The routine prints out the fractional area of the mask computed in the
pixel domain divided by \f[C]D(1,1)\f[R] (the fractional area computed
by the spherical harmonic transforms), and the ratio of the two should
be close to 1.
Experience suggests that \f[C]l\f[R] should be about 5 times
\f[C]lmax\f[R].
.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
shreturntapersmap, yilmindexvector