NETGeographicLib  1.52
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::CircularEngine.
.NET wrapper for GeographicLib::SphericalEngine::coeff.
.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)
double HarmonicSum(double tau1, double tau2, double x, double y, double z, [System::Runtime::InteropServices::Out] double% gradx, [System::Runtime::InteropServices::Out] double% grady, [System::Runtime::InteropServices::Out] double% gradz)
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)
SphericalCoefficients ^ Coefficients()
SphericalHarmonic2(array< double >^ C, array< double >^ S, int N, int nmx, int mmx, array< double >^ C1, array< double >^ S1, int N1, int nmx1, int mmx1, array< double >^ C2, array< double >^ S2, int N2, int nmx2, int mmx2, double a, Normalization norm)
SphericalCoefficients ^ Coefficients2()
SphericalCoefficients ^ Coefficients1()