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