NETGeographicLib  1.49
SphericalHarmonic2.h
Go to the documentation of this file.
1 #pragma once
2 /**
3  * \file NETGeographicLib/SphericalHarmonic2.h
4  * \brief Header for NETGeographicLib::SphericalHarmonic2 class
5  *
6  * NETGeographicLib is copyright (c) Scott Heiman (2013)
7  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
8  * <charles@karney.com> and licensed under the MIT/X11 License.
9  * For more information, see
10  * https://geographiclib.sourceforge.io/
11  **********************************************************************/
12 
13 namespace NETGeographicLib
14 {
15  ref class CircularEngine;
16  ref class SphericalCoefficients;
17  /**
18  * \brief .NET wrapper for GeographicLib::SphericalHarmonic2.
19  *
20  * This class allows .NET applications to access GeographicLib::SphericalHarmonic2.
21  *
22  * This class is similar to SphericalHarmonic, except that the coefficients
23  * \e C<sub>\e nm</sub> are replaced by \e C<sub>\e nm</sub> + \e tau'
24  * C'<sub>\e nm</sub> + \e tau'' C''<sub>\e nm</sub> (and similarly for \e
25  * S<sub>\e nm</sub>).
26  *
27  * C# Example:
28  * \include example-SphericalHarmonic2.cs
29  * Managed C++ Example:
30  * \include example-SphericalHarmonic2.cpp
31  * Visual Basic Example:
32  * \include example-SphericalHarmonic2.vb
33  *
34  * <B>INTERFACE DIFFERENCES:</B><BR>
35  * This class replaces the () operator with HarmonicSum().
36  *
37  * Coefficients, Coefficients1, and Coefficients2 return a SphericalCoefficients
38  * object.
39  **********************************************************************/
40  public ref class SphericalHarmonic2
41  {
42  private:
43  // pointer to the unmanaged GeographicLib::SphericalHarmonic2
44  const GeographicLib::SphericalHarmonic2* m_pSphericalHarmonic2;
45  // the finalizer destroys the unmanaged memory when the object is destroyed.
46  !SphericalHarmonic2(void);
47  // the number of coefficient vectors.
48  static const int m_numCoeffVectors = 3;
49  // local containers for the cosine and sine coefficients. The
50  // GeographicLib::SphericalEngine::coeffs class uses a
51  // std::vector::iterator to access these vectors.
52  std::vector<double> **m_C, **m_S;
53  public:
54  /**
55  * Supported normalizations for associate Legendre polynomials.
56  **********************************************************************/
57  enum class Normalization {
58  /**
59  * Fully normalized associated Legendre polynomials. See
60  * SphericalHarmonic::FULL for documentation.
61  *
62  * @hideinitializer
63  **********************************************************************/
65  /**
66  * Schmidt semi-normalized associated Legendre polynomials. See
67  * SphericalHarmonic::SCHMIDT for documentation.
68  *
69  * @hideinitializer
70  **********************************************************************/
72  };
73 
74  /**
75  * Constructor with a full set of coefficients specified.
76  *
77  * @param[in] C the coefficients \e C<sub>\e nm</sub>.
78  * @param[in] S the coefficients \e S<sub>\e nm</sub>.
79  * @param[in] N the maximum degree and order of the sum
80  * @param[in] C1 the coefficients \e C'<sub>\e nm</sub>.
81  * @param[in] S1 the coefficients \e S'<sub>\e nm</sub>.
82  * @param[in] N1 the maximum degree and order of the first correction
83  * coefficients \e C'<sub>\e nm</sub> and \e S'<sub>\e nm</sub>.
84  * @param[in] C2 the coefficients \e C''<sub>\e nm</sub>.
85  * @param[in] S2 the coefficients \e S''<sub>\e nm</sub>.
86  * @param[in] N2 the maximum degree and order of the second correction
87  * coefficients \e C'<sub>\e nm</sub> and \e S'<sub>\e nm</sub>.
88  * @param[in] a the reference radius appearing in the definition of the
89  * sum.
90  * @param[in] norm the normalization for the associated Legendre
91  * polynomials, either SphericalHarmonic2::FULL (the default) or
92  * SphericalHarmonic2::SCHMIDT.
93  * @exception GeographicErr if \e N and \e N1 do not satisfy \e N &ge;
94  * \e N1 &ge; &minus;1, and similarly for \e N2.
95  * @exception GeographicErr if any of the vectors of coefficients is not
96  * large enough.
97  *
98  * See SphericalHarmonic for the way the coefficients should be stored. \e
99  * N1 and \e N2 should satisfy \e N1 &le; \e N and \e N2 &le; \e N.
100  *
101  * The class stores <i>pointers</i> to the first elements of \e C, \e S, \e
102  * C', \e S', \e C'', and \e S''. These arrays should not be altered or
103  * destroyed during the lifetime of a SphericalHarmonic object.
104  **********************************************************************/
105  SphericalHarmonic2(array<double>^ C,
106  array<double>^ S,
107  int N,
108  array<double>^ C1,
109  array<double>^ S1,
110  int N1,
111  array<double>^ C2,
112  array<double>^ S2,
113  int N2,
114  double a,
115  Normalization norm );
116 
117  /**
118  * Constructor with a subset of coefficients specified.
119  *
120  * @param[in] C the coefficients \e C<sub>\e nm</sub>.
121  * @param[in] S the coefficients \e S<sub>\e nm</sub>.
122  * @param[in] N the degree used to determine the layout of \e C and \e S.
123  * @param[in] nmx the maximum degree used in the sum. The sum over \e n is
124  * from 0 thru \e nmx.
125  * @param[in] mmx the maximum order used in the sum. The sum over \e m is
126  * from 0 thru min(\e n, \e mmx).
127  * @param[in] C1 the coefficients \e C'<sub>\e nm</sub>.
128  * @param[in] S1 the coefficients \e S'<sub>\e nm</sub>.
129  * @param[in] N1 the degree used to determine the layout of \e C' and \e
130  * S'.
131  * @param[in] nmx1 the maximum degree used for \e C' and \e S'.
132  * @param[in] mmx1 the maximum order used for \e C' and \e S'.
133  * @param[in] C2 the coefficients \e C''<sub>\e nm</sub>.
134  * @param[in] S2 the coefficients \e S''<sub>\e nm</sub>.
135  * @param[in] N2 the degree used to determine the layout of \e C'' and \e
136  * S''.
137  * @param[in] nmx2 the maximum degree used for \e C'' and \e S''.
138  * @param[in] mmx2 the maximum order used for \e C'' and \e S''.
139  * @param[in] a the reference radius appearing in the definition of the
140  * sum.
141  * @param[in] norm the normalization for the associated Legendre
142  * polynomials, either SphericalHarmonic2::FULL (the default) or
143  * SphericalHarmonic2::SCHMIDT.
144  * @exception GeographicErr if the parameters do not satisfy \e N &ge; \e
145  * nmx &ge; \e mmx &ge; &minus;1; \e N1 &ge; \e nmx1 &ge; \e mmx1 &ge;
146  * &minus;1; \e N &ge; \e N1; \e nmx &ge; \e nmx1; \e mmx &ge; \e mmx1;
147  * and similarly for \e N2, \e nmx2, and \e mmx2.
148  * @exception GeographicErr if any of the vectors of coefficients is not
149  * large enough.
150  *
151  * The class stores <i>pointers</i> to the first elements of \e C, \e S, \e
152  * C', \e S', \e C'', and \e S''. These arrays should not be altered or
153  * destroyed during the lifetime of a SphericalHarmonic object.
154  **********************************************************************/
155  SphericalHarmonic2(array<double>^ C,
156  array<double>^ S,
157  int N, int nmx, int mmx,
158  array<double>^ C1,
159  array<double>^ S1,
160  int N1, int nmx1, int mmx1,
161  array<double>^ C2,
162  array<double>^ S2,
163  int N2, int nmx2, int mmx2,
164  double a,
165  Normalization norm );
166 
167  /**
168  * The destructor calls the finalizer.
169  **********************************************************************/
171  { this->!SphericalHarmonic2(); }
172 
173  /**
174  * Compute a spherical harmonic sum with two correction terms.
175  *
176  * @param[in] tau1 multiplier for correction coefficients \e C' and \e S'.
177  * @param[in] tau2 multiplier for correction coefficients \e C'' and \e S''.
178  * @param[in] x cartesian coordinate.
179  * @param[in] y cartesian coordinate.
180  * @param[in] z cartesian coordinate.
181  * @return \e V the spherical harmonic sum.
182  *
183  * This routine requires constant memory and thus never throws an
184  * exception.
185  **********************************************************************/
186  double HarmonicSum(double tau1, double tau2, double x, double y, double z);
187 
188  /**
189  * Compute a spherical harmonic sum with two correction terms and its
190  * gradient.
191  *
192  * @param[in] tau1 multiplier for correction coefficients \e C' and \e S'.
193  * @param[in] tau2 multiplier for correction coefficients \e C'' and \e S''.
194  * @param[in] x cartesian coordinate.
195  * @param[in] y cartesian coordinate.
196  * @param[in] z cartesian coordinate.
197  * @param[out] gradx \e x component of the gradient
198  * @param[out] grady \e y component of the gradient
199  * @param[out] gradz \e z component of the gradient
200  * @return \e V the spherical harmonic sum.
201  *
202  * This is the same as the previous function, except that the components of
203  * the gradients of the sum in the \e x, \e y, and \e z directions are
204  * computed. This routine requires constant memory and thus never throws
205  * an exception.
206  **********************************************************************/
207  double HarmonicSum(double tau1, double tau2, double x, double y, double z,
208  [System::Runtime::InteropServices::Out] double% gradx,
209  [System::Runtime::InteropServices::Out] double% grady,
210  [System::Runtime::InteropServices::Out] double% gradz);
211 
212  /**
213  * Create a CircularEngine to allow the efficient evaluation of several
214  * points on a circle of latitude at fixed values of \e tau1 and \e tau2.
215  *
216  * @param[in] tau1 multiplier for correction coefficients \e C' and \e S'.
217  * @param[in] tau2 multiplier for correction coefficients \e C'' and \e S''.
218  * @param[in] p the radius of the circle.
219  * @param[in] z the height of the circle above the equatorial plane.
220  * @param[in] gradp if true the returned object will be able to compute the
221  * gradient of the sum.
222  * @exception std::bad_alloc if the memory for the CircularEngine can't be
223  * allocated.
224  * @return the CircularEngine object.
225  *
226  * SphericalHarmonic2::operator()() exchanges the order of the sums in the
227  * definition, i.e., &sum;<sub>n = 0..N</sub> &sum;<sub>m = 0..n</sub>
228  * becomes &sum;<sub>m = 0..N</sub> &sum;<sub>n = m..N</sub>..
229  * SphericalHarmonic2::Circle performs the inner sum over degree \e n
230  * (which entails about <i>N</i><sup>2</sup> operations). Calling
231  * CircularEngine::operator()() on the returned object performs the outer
232  * sum over the order \e m (about \e N operations).
233  *
234  * See SphericalHarmonic::Circle for an example of its use.
235  **********************************************************************/
236  CircularEngine^ Circle(double tau1, double tau2, double p, double z, bool gradp);
237 
238  /**
239  * @return the zeroth SphericalCoefficients object.
240  **********************************************************************/
242  /**
243  * @return the first SphericalCoefficients object.
244  **********************************************************************/
246  /**
247  * @return the second SphericalCoefficients object.
248  **********************************************************************/
250  };
251 } // namespace NETGeographicLib
.NET wrapper for GeographicLib::SphericalHarmonic2.
CircularEngine ^ Circle(double tau1, double tau2, double p, double z, bool gradp)
double HarmonicSum(double tau1, double tau2, double x, double y, double z)
.NET wrapper for GeographicLib::SphericalEngine::coeff.
SphericalCoefficients ^ Coefficients2()
SphericalCoefficients ^ Coefficients()
SphericalCoefficients ^ Coefficients1()
SphericalHarmonic2(array< double >^ C, array< double >^ S, int N, array< double >^ C1, array< double >^ S1, int N1, array< double >^ C2, array< double >^ S2, int N2, double a, Normalization norm)
.NET wrapper for GeographicLib::CircularEngine.