/
shrotatetapers.1
121 lines (121 loc) · 4.64 KB
/
shrotatetapers.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
110
111
112
113
114
115
116
117
118
119
120
121
.\" Automatically generated by Pandoc 2.7.3
.\"
.TH "shrotatetapers" "1" "2019-09-17" "Fortran 95" "SHTOOLS 4.5"
.hy
.SH SHRotateTapers
.PP
Rotate orthogonal spherical-cap Slepian functions centered at the North
pole to a different location.
.SH Usage
.PP
call SHRotateTapers(\f[C]tapersrot\f[R], \f[C]tapers\f[R],
\f[C]taper_order\f[R], \f[C]lmax\f[R], \f[C]nrot\f[R], \f[C]x\f[R],
\f[C]dj\f[R], \f[C]exitstatus\f[R])
.SH Parameters
.TP
.B \f[C]tapersrot\f[R] : output, real(dp), dimension ((\f[C]lmax\f[R]+1)**2, \f[C]nrot\f[R])
An array containing the spherical harmonic coefficients of the rotated
spherical-cap functions.
Each column corresponds to a single function of which the spherical
harmonic coefficients can be unpacked with \f[C]SHVectorToCilm\f[R].
.TP
.B \f[C]tapers\f[R] : input, real(dp), dimension (\f[C]lmax\f[R]+1, \f[C]nrot\f[R])
An array containing the eigenfunctions of the spherical-cap
concentration problem obtained from \f[C]SHReturnTapers\f[R].
The functions are listed by columns, ordered from best to worst
concentrated.
.TP
.B \f[C]taper_order\f[R] : input, integer, dimension (\f[C]nrot\f[R])
The angular order of the non-zero spherical harmonic coefficients in
each column of \f[C]tapers\f[R].
.TP
.B \f[C]lmax\f[R] : input, integer
The spherical harmonic bandwidth of the functions.
.TP
.B \f[C]nrot\f[R] : input, integer
The number of functions to rotate, which must be less than or equal to
(\f[C]lmax\f[R]+1)**2.
.TP
.B \f[C]x\f[R] : input, real(dp), dimension(3)
The three Euler angles, alpha, beta, and gamma, in radians.
.TP
.B \f[C]dj\f[R] : input, real(dp), dimension (\f[C]lmax\f[R]+1, \f[C]lmax\f[R]+1, \f[C]lmax\f[R]+1)
The rotation matrix \f[C]dj(pi/2)\f[R], obtained from a call to
\f[C]djpi2\f[R].
.TP
.B \f[C]exitstatus\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]SHRotateTapers\f[R] will rotate a set of orthogonal spherical-cap
Slepian functions originally centered at the North pole to a different
location according to the three Euler angles in the vector \f[C]x\f[R].
The original matrix \f[C]tapers\f[R] is computed by a call to
\f[C]SHReturnTapers\f[R].
Only the first \f[C]nrot\f[R] tapers are rotated, each of which is
returned in a column of the output matrix \f[C]tapersrot\f[R].
The spherical harmonic coefficients are geodesy 4pi normalized, and each
column of \f[C]tapersrot\f[R] can be unpacked using
\f[C]SHVectorCilm\f[R].
The input rotation matrix \f[C]dj\f[R] is computed by a call to
\f[C]djpi2\f[R].
.PP
The rotation of a coordinate system or body can be viewed in two
complementary ways involving three successive rotations.
Both methods have the same initial and final configurations, and the
angles listed in both schemes are the same.
.PP
\f[C]Scheme A:\f[R]
.IP " (I)" 6
Rotation about the z axis by alpha.
.IP " (II)" 6
Rotation about the new y axis by beta.
.IP "(III)" 6
Rotation about the new z axis by gamma.
.PP
\f[C]Scheme B:\f[R]
.IP " (I)" 6
Rotation about the z axis by gamma.
.IP " (II)" 6
Rotation about the initial y axis by beta.
.IP "(III)" 6
Rotation about the initial z axis by alpha.
.PP
The rotations can further be viewed either as a rotation of the
coordinate system or the physical body.
For a rotation of the coordinate system without rotation of the physical
body, use
.PP
\f[C]x(alpha, beta, gamma)\f[R].
.PP
For a rotation of the physical body without rotation of the coordinate
system, use
.PP
\f[C]x(-gamma, -beta, -alpha)\f[R].
.PP
To perform the inverse transform of \f[C]x(alpha, beta, gamma)\f[R], use
\f[C]x(-gamma, -beta, -alpha)\f[R].
.PP
Note that this routine uses the \[lq]y convention\[rq], where the second
rotation is with respect to the new y axis.
If alpha, beta, and gamma were originally defined in terms of the \[lq]x
convention\[rq], where the second rotation was with respect to the new x
axis, the Euler angles according to the y convention would be
\f[C]alpha_y=alpha_x-pi/2\f[R], \f[C]beta_x=beta_y\f[R], and
\f[C]gamma_y=gamma_x+pi/2\f[R].
.PP
This routine first converts the real coefficients to complex form using
\f[C]SHrtoc\f[R].
Then the coefficients are converted to indexed form using
\f[C]SHCilmToCindex\f[R], these are sent to \f[C]SHRotateCoef\f[R], the
result if converted back to \f[C]cilm\f[R] complex form using
\f[C]SHCindexToCilm\f[R], and these are finally converted back to real
form using \f[C]SHctor\f[R].
.SH See also
.PP
djpi2, shreturntapers, shctor, shrtoc, shcilmtocindex, shcindextocilm,
shvectortocilm