-
Notifications
You must be signed in to change notification settings - Fork 106
/
shexpandlsq.1
89 lines (89 loc) · 3.87 KB
/
shexpandlsq.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
.\" Automatically generated by Pandoc 2.9.2
.\"
.TH "shexpandlsq" "1" "2019-09-23" "Fortran 95" "SHTOOLS 4.6"
.hy
.SH SHExpandLSQ
.PP
Expand a set of irregularly sampled data points into spherical harmonics
using a (weighted) least squares inversion.
.SH Usage
.PP
call SHExpandLSQ (\f[C]cilm\f[R], \f[C]d\f[R], \f[C]lat\f[R],
\f[C]lon\f[R], \f[C]nmax\f[R], \f[C]lmax\f[R], \f[C]norm\f[R],
\f[C]chi2\f[R], \f[C]csphase\f[R], \f[C]weights\f[R],
\f[C]exitstatus\f[R])
.SH Parameters
.TP
\f[B]\f[CB]cilm\f[B]\f[R] : output, real(dp), dimension (2, \f[B]\f[CB]lmax\f[B]\f[R]+1, \f[B]\f[CB]lmax\f[B]\f[R]+1)
The real spherical harmonic coefficients of the function.
The coefficients \f[C]C1lm\f[R] and \f[C]C2lm\f[R] refer to the cosine
(\f[C]Clm\f[R]) and sine (\f[C]Slm\f[R]) coefficients, respectively,
with \f[C]Clm=cilm(1,l+1,m+1)\f[R] and \f[C]Slm=cilm(2,l+1,m+1)\f[R].
.TP
\f[B]\f[CB]d\f[B]\f[R] : input, real(dp), dimension (\f[B]\f[CB]nmax\f[B]\f[R])
The value of the function at the coordinates (\f[C]lat\f[R],
\f[C]lon\f[R]).
.TP
\f[B]\f[CB]lat\f[B]\f[R] : input, real(dp), dimension (\f[B]\f[CB]nmax\f[B]\f[R])
The latitude in DEGREES corresponding to the value in \f[C]d\f[R].
.TP
\f[B]\f[CB]lon\f[B]\f[R] : input, real(dp), dimension (\f[B]\f[CB]nmax\f[B]\f[R])
The longitude in DEGREES corresponding to the value in \f[C]d\f[R].
.TP
\f[B]\f[CB]nmax\f[B]\f[R] : input, integer
The number of data points.
.TP
\f[B]\f[CB]lmax\f[B]\f[R] : input, integer
The maximum spherical harmonic degree of the output coefficients
\f[C]cilm\f[R].
.TP
\f[B]\f[CB]norm\f[B]\f[R] : input, optional, integer, default = 1
1 (default) = Geodesy 4-pi normalized harmonics; 2 = Schmidt
semi-normalized harmonics; 3 = unnormalized harmonics; 4 = orthonormal
harmonics.
.TP
\f[B]\f[CB]chi2\f[B]\f[R] : output, optional, real(dp)
The residual sum of squares misfit for an overdetermined inversion.
.TP
\f[B]\f[CB]csphase\f[B]\f[R] : input, optional, integer, default = 1
1 (default) = do not apply the Condon-Shortley phase factor to the
associated Legendre functions; -1 = append the Condon-Shortley phase
factor of (-1)\[ha]m to the associated Legendre functions.
.TP
\f[B]\f[CB]weights\f[B]\f[R] : input, real(dp), dimension (\f[B]\f[CB]nmax\f[B]\f[R])
The weights to be applied in a weighted least squares inversion.
.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]SHExpandLSQ\f[R] will expand a set of irregularly sampled data
points into spherical harmonics by a least squares inversion.
When the number of data points is greater or equal to the number of
spherical harmonic coefficients (i.e., \f[C]nmax>=(lmax+1)**2\f[R]), the
solution of the overdetermined system will be determined.
If there are more coefficients than data points, then the solution of
the underdetermined system that minimizes the solution norm will be
determined.
The inversions are performed using the LAPACK routine DGELS.
.PP
A weighted least squares inversion will be performed if the optional
vector \f[C]weights\f[R] is specified.
In this case, the problem must be overdetermined, and it is assumed that
each measurement is statistically independent (i.e., the weighting
matrix is diagonal).
The inversion is performed using the LAPACK routine DGGGLM.
.PP
The employed spherical harmonic normalization and Condon-Shortley phase
convention can be set by the optional arguments \f[C]norm\f[R] and
\f[C]csphase\f[R]; if not set, the default is to use geodesy 4-pi
normalized harmonics that exclude the Condon-Shortley phase of
(-1)\[ha]m.
.SH See also
.PP
makegriddh, shexpanddh, makegriddhc, shexpanddhc, makegridglq,
shexpandglq, makegridglqc, shexpandglqc, dgels(1), dggglm(1)