NETGeographicLib 1.52
Loading...
Searching...
No Matches
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
13namespace 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 **********************************************************************/
63 FULL = GeographicLib::SphericalEngine::FULL,
64 /**
65 * Schmidt semi-normalized associated Legendre polynomials. See
66 * SphericalHarmonic::SCHMIDT for documentation.
67 *
68 * @hideinitializer
69 **********************************************************************/
70 SCHMIDT = GeographicLib::SphericalEngine::SCHMIDT,
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()