Sitelet https://github.com/Sciumo/GeographicLib/commit/4ead7ebc31f435b45f6b291c2a9623e98c779c60
Skip to content

Commit 4ead7eb

Browse files
author
Charles Karney
committed
Fix VS compiler warnings. Add documentation.
1 parent 5ab92b1 commit 4ead7eb

7 files changed

Lines changed: 140 additions & 40 deletions

File tree

‎include/GeographicLib/CircularEngine.hpp‎

Lines changed: 116 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,21 @@
1717
namespace GeographicLib {
1818

1919
/**
20-
* \brief Circular Harmonic series
20+
* \brief Spherical Harmonic sums for a circle.
2121
*
22-
* Sum a circular harmonic series.
22+
* The class is a companion to SphericalEngine. If the results of a
23+
* spherical harmonic sum are needed for several points on a circle of
24+
* constant latitude \e lat and height \e h, then SphericalEngine::Circle can
25+
* compute the inner sum, which is independent of longitude \e lon, and
26+
* produce a CircularEngine object. CircularEngine::operator()(real) can
27+
* then be used to perform the outer sum for particular vales of \e lon.
28+
* This can lead to substantial improvements in computational speed for high
29+
* degree sum (approximately by a factor of \e N / 2 where \e N is the
30+
* maximum degree).
31+
*
32+
* The constructor for this class is private. Use SphericalHarmonic::Circle,
33+
* SphericalHarmonic1::Circle, and SphericalHarmonic2::Circle to create
34+
* instances of this class.
2335
**********************************************************************/
2436

2537
class GEOGRAPHIC_EXPORT CircularEngine {
@@ -36,7 +48,7 @@ namespace GeographicLib {
3648
std::vector<real> _wc, _ws, _wrc, _wrs, _wtc, _wts;
3749
real _q, _uq, _uq2;
3850

39-
Math::real Value(bool gradp, real coslam, real sinlam,
51+
Math::real Value(bool gradp, real cl, real sl,
4052
real& gradx, real& grady, real& gradz) const;
4153

4254
static inline void cossin(real x, real& cosx, real& sinx) {
@@ -46,8 +58,28 @@ namespace GeographicLib {
4658
sinx = x == -180 ? 0 : sin(xi);
4759
}
4860

49-
public:
50-
61+
friend class SphericalEngine;
62+
/**
63+
* Constructor for CircularEngine with
64+
*
65+
* @param[in] M the maximum order of the spherical harmonic sum.
66+
* @param[in] gradp whether to include the coefficients of the series for
67+
* the gradient of the sum.
68+
* @param[in] norm the normalization of the Legrendre functions (either
69+
* full or schmidt).
70+
* @param[in] scale a scaling that is given to the coefficients to avoid
71+
* overflow.
72+
* @param[in] a the reference radius for the sum.
73+
* @param[in] r the (spherical) radius of points.
74+
* @param[in] u the sine of the (spherical) colatiude.
75+
* @param[in] t the cosine of the (spherical) colatiude.
76+
*
77+
* Thus the CircularEngine evaluates the harmonic sum (and its gradient)
78+
* for points on the circle of radius \e u \e r which lies a distance \e t \e
79+
* r above the equatorial plane. The constructor allocates memory for the
80+
* arrays used to store the coefficients and stores zero in them. These
81+
* coefficients are set with calls to CircularEngine::SetCoeff.
82+
**********************************************************************/
5183
CircularEngine(int M, bool gradp, SphericalEngine::normalization norm,
5284
real scale, real a, real r, real u, real t)
5385
: _M(M)
@@ -69,8 +101,36 @@ namespace GeographicLib {
69101
_uq = _u * _q;
70102
_uq2 = Math::sq(_uq);
71103
}
104+
105+
/**
106+
* Store coefficients for the sum for the order \e m term.
107+
*
108+
* @param[in] m the order of the term.
109+
* @param[in] wc the coefficient for the cos(\e m \e lam) term.
110+
* @param[in] ws the coefficient for the sin(\e m \e lam) term.
111+
*
112+
* \e m must lie in [0, \e M].
113+
**********************************************************************/
72114
void SetCoeff(int m, real wc, real ws)
73115
{ _wc[m] = wc; _ws[m] = ws; }
116+
117+
/**
118+
* Store coefficients for the sum and its gradient for the order \e m term.
119+
*
120+
* @param[in] m the order of the term
121+
* @param[in] wc the coefficient for the cos(\e m \e lam) term.
122+
* @param[in] ws the coefficient for the sin(\e m \e lam) term.
123+
* @param[in] wrc the coefficient for the radial derivative of the cosine
124+
* term.
125+
* @param[in] wrs the coefficient for the radial derivative of the sine
126+
* term.
127+
* @param[in] wtc the coefficient for the \e theta derivative of the cosine
128+
* term.
129+
* @param[in] wts the coefficient for the \e theta derivative of the sine
130+
* term.
131+
*
132+
* \e m must lie in [0, \e M]. Here \e theta is the spherical colatitude.
133+
**********************************************************************/
74134
void SetCoeff(int m, real wc, real ws,
75135
real wrc, real wrs, real wtc, real wts) {
76136
_wc[m] = wc; _ws[m] = ws;
@@ -79,24 +139,63 @@ namespace GeographicLib {
79139
_wtc[m] = wtc; _wts[m] = wts;
80140
}
81141
}
82-
Math::real operator()(real lam) const {
83-
real coslam, sinlam;
84-
cossin(lam, coslam, sinlam);
85-
return (*this)(coslam, sinlam);
142+
143+
public:
144+
/**
145+
* Evaluate the sum for a particular longitude.
146+
*
147+
* @param[in] lon the longitude (degrees).
148+
* @return[in] \e V the value of the sum.
149+
**********************************************************************/
150+
Math::real operator()(real lon) const {
151+
real coslon, sinlon;
152+
cossin(lon, coslon, sinlon);
153+
return (*this)(coslon, sinlon);
86154
}
87-
Math::real operator()(real coslam, real sinlam) const {
155+
156+
/**
157+
* Evaluate the sum for a particular longitude given in terms of its
158+
* cosine and sine.
159+
*
160+
* @param[in] coslon the cosine of the longitude.
161+
* @param[in] sinlon the sine of the longitude.
162+
* @return[in] \e V the value of the sum.
163+
**********************************************************************/
164+
Math::real operator()(real coslon, real sinlon) const {
88165
real dummy;
89-
return Value(false, coslam, sinlam, dummy, dummy, dummy);
166+
return Value(false, coslon, sinlon, dummy, dummy, dummy);
90167
}
91-
Math::real operator()(real lam,
168+
169+
/**
170+
* Evaluate the sum and its gradient for a particular longitude.
171+
*
172+
* @param[in] lon the longitude (degrees).
173+
* @param[out] gradx \e x component of the gradient
174+
* @param[out] grady \e y component of the gradient
175+
* @param[out] gradz \e z component of the gradient
176+
* @return[in] \e V the value of the sum.
177+
**********************************************************************/
178+
Math::real operator()(real lon,
92179
real& gradx, real& grady, real& gradz) const {
93-
real coslam, sinlam;
94-
cossin(lam, coslam, sinlam);
95-
return (*this)(coslam, sinlam, gradx, grady, gradz);
180+
real coslon, sinlon;
181+
cossin(lon, coslon, sinlon);
182+
return (*this)(coslon, sinlon, gradx, grady, gradz);
96183
}
97-
Math::real operator()(real coslam, real sinlam,
184+
185+
/**
186+
* Evaluate the sum and its gradient for a particular longitude given in
187+
* terms of its cosine and sine.
188+
*
189+
* @param[in] coslon the cosine of the longitude.
190+
* @param[in] sinlon the sine of the longitude.
191+
* @param[out] gradx \e x component of the gradient
192+
* @param[out] grady \e y component of the gradient
193+
* @param[out] gradz \e z component of the gradient
194+
* @return[in] \e V the value of the sum.
195+
**********************************************************************/
196+
Math::real operator()(real coslon, real sinlon,
98197
real& gradx, real& grady, real& gradz) const {
99-
return Value(true, coslam, sinlam, gradx, grady, gradz);
198+
return Value(true, coslon, sinlon, gradx, grady, gradz);
100199
}
101200
};
102201

‎include/GeographicLib/SphericalEngine.hpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -105,12 +105,12 @@ namespace GeographicLib {
105105
};
106106

107107
template<bool gradp, normalization norm, int L>
108-
static Math::real Value(const coeff c[L], const real f[L],
108+
static Math::real Value(const coeff c[], const real f[],
109109
real x, real y, real z, real a,
110110
real& gradx, real& grady, real& gradz);
111111

112112
template<bool gradp, SphericalEngine::normalization norm, int L>
113-
static CircularEngine Circle(const coeff c[L], const real f[L],
113+
static CircularEngine Circle(const coeff c[], const real f[],
114114
real p, real z, real a);
115115
};
116116

‎include/GeographicLib/SphericalHarmonic.hpp‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -155,19 +155,19 @@ namespace GeographicLib {
155155
}
156156

157157
CircularEngine Circle(real p, real z, bool gradp) const {
158-
real f[] = {};
158+
real f[] = {1};
159159
switch (_norm) {
160160
case full:
161161
return gradp ?
162-
SphericalEngine::Circle<true, SphericalEngine::full, 1>
162+
SphericalEngine::Circle<true, SphericalEngine::full, 1>
163163
(_c, f, p, z, _a) :
164164
SphericalEngine::Circle<false, SphericalEngine::full, 1>
165165
(_c, f, p, z, _a);
166166
break;
167167
case schmidt:
168168
default: // To avoid compiler warnings
169169
return gradp ?
170-
SphericalEngine::Circle<true, SphericalEngine::schmidt, 1>
170+
SphericalEngine::Circle<true, SphericalEngine::schmidt, 1>
171171
(_c, f, p, z, _a) :
172172
SphericalEngine::Circle<false, SphericalEngine::schmidt, 1>
173173
(_c, f, p, z, _a);

‎include/GeographicLib/SphericalHarmonic1.hpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -142,15 +142,15 @@ namespace GeographicLib {
142142
switch (_norm) {
143143
case full:
144144
return gradp ?
145-
SphericalEngine::Circle<true, SphericalEngine::full, 2>
145+
SphericalEngine::Circle<true, SphericalEngine::full, 2>
146146
(_c, f, p, z, _a) :
147147
SphericalEngine::Circle<false, SphericalEngine::full, 2>
148148
(_c, f, p, z, _a);
149149
break;
150150
case schmidt:
151151
default: // To avoid compiler warnings
152152
return gradp ?
153-
SphericalEngine::Circle<true, SphericalEngine::schmidt, 2>
153+
SphericalEngine::Circle<true, SphericalEngine::schmidt, 2>
154154
(_c, f, p, z, _a) :
155155
SphericalEngine::Circle<false, SphericalEngine::schmidt, 2>
156156
(_c, f, p, z, _a);

‎include/GeographicLib/SphericalHarmonic2.hpp‎

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ namespace GeographicLib {
7272
}
7373

7474
/**
75-
* Compute a spherical harmonic sum with a correction term.
75+
* Compute a spherical harmonic sum with two correction terms.
7676
*
7777
* @param[in] tau1 multiplier for correction coefficients.
7878
* @param[in] tau2 multiplier for correction coefficients.
@@ -114,7 +114,8 @@ namespace GeographicLib {
114114
}
115115

116116
/**
117-
* Compute a spherical harmonic sum with a correction and its gradient.
117+
* Compute a spherical harmonic sum with two correction terms and its
118+
* gradient.
118119
*
119120
* @param[in] tau1 multiplier for correction coefficients.
120121
* @param[in] tau2 multiplier for correction coefficients.
@@ -152,15 +153,15 @@ namespace GeographicLib {
152153
switch (_norm) {
153154
case full:
154155
return gradp ?
155-
SphericalEngine::Circle<true, SphericalEngine::full, 3>
156+
SphericalEngine::Circle<true, SphericalEngine::full, 3>
156157
(_c, f, p, z, _a) :
157158
SphericalEngine::Circle<false, SphericalEngine::full, 3>
158159
(_c, f, p, z, _a);
159160
break;
160161
case schmidt:
161162
default: // To avoid compiler warnings
162163
return gradp ?
163-
SphericalEngine::Circle<true, SphericalEngine::schmidt, 3>
164+
SphericalEngine::Circle<true, SphericalEngine::schmidt, 3>
164165
(_c, f, p, z, _a) :
165166
SphericalEngine::Circle<false, SphericalEngine::schmidt, 3>
166167
(_c, f, p, z, _a);

‎src/CircularEngine.cpp‎

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ namespace GeographicLib {
2020

2121
using namespace std;
2222

23-
Math::real CircularEngine::Value(bool gradp, real coslam, real sinlam,
23+
Math::real CircularEngine::Value(bool gradp, real cl, real sl,
2424
real& gradx, real& grady, real& gradz) const
2525
{
2626
gradp = _gradp && gradp;
@@ -40,12 +40,12 @@ namespace GeographicLib {
4040
switch (_norm) {
4141
case full:
4242
v = 2 * real(2 * m + 3) / (m + 1);
43-
A = coslam * sqrt(v) * _uq;
43+
A = cl * sqrt(v) * _uq;
4444
B = - sqrt((v * (2 * m + 5)) / (8 * (m + 2))) * _uq2;
4545
break;
4646
case schmidt:
4747
v = 2 * real(2 * m + 1) / (m + 1);
48-
A = coslam * sqrt(v) * _uq;
48+
A = cl * sqrt(v) * _uq;
4949
B = - sqrt((v * (2 * m + 3)) / (8 * (m + 2))) * _uq2;
5050
break;
5151
default:
@@ -65,7 +65,7 @@ namespace GeographicLib {
6565
real A, B, qs;
6666
switch (_norm) {
6767
case full:
68-
A = sqrt(real(3)) * _uq; // F[1]/(q*coslam) or F[1]/(q*sinlam)
68+
A = sqrt(real(3)) * _uq; // F[1]/(q*cl) or F[1]/(q*sl)
6969
B = - sqrt(real(15)/4) * _uq2; // beta[1]/q
7070
break;
7171
case schmidt:
@@ -76,24 +76,24 @@ namespace GeographicLib {
7676
A = B = 0;
7777
}
7878
qs = _q / _scale;
79-
vc = qs * (_wc[m] + A * (coslam * vc + sinlam * vs ) + B * vc2);
79+
vc = qs * (_wc[m] + A * (cl * vc + sl * vs ) + B * vc2);
8080
if (gradp) {
8181
qs /= _r;
8282
// The components of the gradient in circular coordinates are
8383
// r: dV/dr
8484
// theta: 1/r * dV/dtheta
8585
// lambda: 1/(r*u) * dV/dlambda
86-
vrc = -qs*(_wrc[m] + A * (coslam * vrc + sinlam * vrs) + B * vrc2);
87-
vtc = -_u*qs*(_wtc[m] + A * (coslam * vtc + sinlam * vts) + B * vtc2);
88-
vlc = qs/_u*( A * (coslam * vlc + sinlam * vls) + B * vlc2);
86+
vrc = - qs * (_wrc[m] + A * (cl * vrc + sl * vrs) + B * vrc2);
87+
vtc = - _u * qs * (_wtc[m] + A * (cl * vtc + sl * vts) + B * vtc2);
88+
vlc = qs / _u * ( A * (cl * vlc + sl * vls) + B * vlc2);
8989
}
9090
}
9191
}
9292

9393
if (gradp) {
9494
// Rotate into cartesian (geocentric) coordinates
95-
gradx = coslam * (_u * vrc + _t * vtc) - sinlam * vlc;
96-
grady = sinlam * (_u * vrc + _t * vtc) + coslam * vlc;
95+
gradx = cl * (_u * vrc + _t * vtc) - sl * vlc;
96+
grady = sl * (_u * vrc + _t * vtc) + cl * vlc;
9797
gradz = _t * vrc - _u * vtc ;
9898
}
9999
return vc;

‎src/SphericalEngine.cpp‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ namespace GeographicLib {
3030
const std::vector<Math::real> SphericalEngine::Z_(0);
3131

3232
template<bool gradp, SphericalEngine::normalization norm, int L>
33-
Math::real SphericalEngine::Value(const coeff c[L], const real f[L],
33+
Math::real SphericalEngine::Value(const coeff c[], const real f[],
3434
real x, real y, real z, real a,
3535
real& gradx, real& grady, real& gradz) {
3636
// General sum
@@ -281,7 +281,7 @@ namespace GeographicLib {
281281
}
282282

283283
template<bool gradp, SphericalEngine::normalization norm, int L>
284-
CircularEngine SphericalEngine::Circle(const coeff c[L], const real f[L],
284+
CircularEngine SphericalEngine::Circle(const coeff c[], const real f[],
285285
real p, real z, real a) {
286286

287287
STATIC_ASSERT(L > 0, "L must be positive");

0 commit comments

Comments
 (0)