00001 #pragma once 00002 /** 00003 * \file NETGeographicLib/SphericalHarmonic2.h 00004 * \brief Header for NETGeographicLib::SphericalHarmonic2 class 00005 * 00006 * NETGeographicLib is copyright (c) Scott Heiman (2013) 00007 * GeographicLib is Copyright (c) Charles Karney (2010-2012) 00008 * <charles@karney.com> and licensed under the MIT/X11 License. 00009 * For more information, see 00010 * http://geographiclib.sourceforge.net/ 00011 **********************************************************************/ 00012 00013 namespace NETGeographicLib 00014 { 00015 ref class CircularEngine; 00016 ref class SphericalCoefficients; 00017 /** 00018 * \brief .NET wrapper for GeographicLib::SphericalHarmonic2. 00019 * 00020 * This class allows .NET applications to access GeographicLib::SphericalHarmonic2. 00021 * 00022 * This class is similar to SphericalHarmonic, except that the coefficients 00023 * \e C<sub>\e nm</sub> are replaced by \e C<sub>\e nm</sub> + \e tau' 00024 * C'<sub>\e nm</sub> + \e tau'' C''<sub>\e nm</sub> (and similarly for \e 00025 * S<sub>\e nm</sub>). 00026 * 00027 * C# Example: 00028 * \include example-SphericalHarmonic2.cs 00029 * Managed C++ Example: 00030 * \include example-SphericalHarmonic2.cpp 00031 * Visual Basic Example: 00032 * \include example-SphericalHarmonic2.vb 00033 * 00034 * <B>INTERFACE DIFFERENCES:</B><BR> 00035 * This class replaces the () operator with HarmonicSum(). 00036 * 00037 * Coefficients, Coefficients1, and Coefficients2 return a SphericalCoefficients 00038 * object. 00039 **********************************************************************/ 00040 public ref class SphericalHarmonic2 00041 { 00042 private: 00043 // pointer to the unmanaged GeographicLib::SphericalHarmonic2 00044 const GeographicLib::SphericalHarmonic2* m_pSphericalHarmonic2; 00045 // the finalizer destroys the unmanaged memory when the object is destroyed. 00046 !SphericalHarmonic2(void); 00047 // the number of coefficient vectors. 00048 static const int m_numCoeffVectors = 3; 00049 // local containers for the cosine and sine coefficients. The 00050 // GeographicLib::SphericalEngine::coeffs class uses a 00051 // std::vector::iterator to access these vectors. 00052 std::vector<double> **m_C, **m_S; 00053 public: 00054 /** 00055 * Supported normalizations for associate Legendre polynomials. 00056 **********************************************************************/ 00057 enum class Normalization { 00058 /** 00059 * Fully normalized associated Legendre polynomials. See 00060 * SphericalHarmonic::FULL for documentation. 00061 * 00062 * @hideinitializer 00063 **********************************************************************/ 00064 FULL = GeographicLib::SphericalEngine::FULL, 00065 /** 00066 * Schmidt semi-normalized associated Legendre polynomials. See 00067 * SphericalHarmonic::SCHMIDT for documentation. 00068 * 00069 * @hideinitializer 00070 **********************************************************************/ 00071 SCHMIDT = GeographicLib::SphericalEngine::SCHMIDT 00072 }; 00073 00074 /** 00075 * Constructor with a full set of coefficients specified. 00076 * 00077 * @param[in] C the coefficients \e C<sub>\e nm</sub>. 00078 * @param[in] S the coefficients \e S<sub>\e nm</sub>. 00079 * @param[in] N the maximum degree and order of the sum 00080 * @param[in] C1 the coefficients \e C'<sub>\e nm</sub>. 00081 * @param[in] S1 the coefficients \e S'<sub>\e nm</sub>. 00082 * @param[in] N1 the maximum degree and order of the first correction 00083 * coefficients \e C'<sub>\e nm</sub> and \e S'<sub>\e nm</sub>. 00084 * @param[in] C2 the coefficients \e C''<sub>\e nm</sub>. 00085 * @param[in] S2 the coefficients \e S''<sub>\e nm</sub>. 00086 * @param[in] N2 the maximum degree and order of the second correction 00087 * coefficients \e C'<sub>\e nm</sub> and \e S'<sub>\e nm</sub>. 00088 * @param[in] a the reference radius appearing in the definition of the 00089 * sum. 00090 * @param[in] norm the normalization for the associated Legendre 00091 * polynomials, either SphericalHarmonic2::FULL (the default) or 00092 * SphericalHarmonic2::SCHMIDT. 00093 * @exception GeographicErr if \e N and \e N1 do not satisfy \e N ≥ 00094 * \e N1 ≥ −1, and similarly for \e N2. 00095 * @exception GeographicErr if any of the vectors of coefficients is not 00096 * large enough. 00097 * 00098 * See SphericalHarmonic for the way the coefficients should be stored. \e 00099 * N1 and \e N2 should satisfy \e N1 ≤ \e N and \e N2 ≤ \e N. 00100 * 00101 * The class stores <i>pointers</i> to the first elements of \e C, \e S, \e 00102 * C', \e S', \e C'', and \e S''. These arrays should not be altered or 00103 * destroyed during the lifetime of a SphericalHarmonic object. 00104 **********************************************************************/ 00105 SphericalHarmonic2(array<double>^ C, 00106 array<double>^ S, 00107 int N, 00108 array<double>^ C1, 00109 array<double>^ S1, 00110 int N1, 00111 array<double>^ C2, 00112 array<double>^ S2, 00113 int N2, 00114 double a, 00115 Normalization norm ); 00116 00117 /** 00118 * Constructor with a subset of coefficients specified. 00119 * 00120 * @param[in] C the coefficients \e C<sub>\e nm</sub>. 00121 * @param[in] S the coefficients \e S<sub>\e nm</sub>. 00122 * @param[in] N the degree used to determine the layout of \e C and \e S. 00123 * @param[in] nmx the maximum degree used in the sum. The sum over \e n is 00124 * from 0 thru \e nmx. 00125 * @param[in] mmx the maximum order used in the sum. The sum over \e m is 00126 * from 0 thru min(\e n, \e mmx). 00127 * @param[in] C1 the coefficients \e C'<sub>\e nm</sub>. 00128 * @param[in] S1 the coefficients \e S'<sub>\e nm</sub>. 00129 * @param[in] N1 the degree used to determine the layout of \e C' and \e 00130 * S'. 00131 * @param[in] nmx1 the maximum degree used for \e C' and \e S'. 00132 * @param[in] mmx1 the maximum order used for \e C' and \e S'. 00133 * @param[in] C2 the coefficients \e C''<sub>\e nm</sub>. 00134 * @param[in] S2 the coefficients \e S''<sub>\e nm</sub>. 00135 * @param[in] N2 the degree used to determine the layout of \e C'' and \e 00136 * S''. 00137 * @param[in] nmx2 the maximum degree used for \e C'' and \e S''. 00138 * @param[in] mmx2 the maximum order used for \e C'' and \e S''. 00139 * @param[in] a the reference radius appearing in the definition of the 00140 * sum. 00141 * @param[in] norm the normalization for the associated Legendre 00142 * polynomials, either SphericalHarmonic2::FULL (the default) or 00143 * SphericalHarmonic2::SCHMIDT. 00144 * @exception GeographicErr if the parameters do not satisfy \e N ≥ \e 00145 * nmx ≥ \e mmx ≥ −1; \e N1 ≥ \e nmx1 ≥ \e mmx1 ≥ 00146 * −1; \e N ≥ \e N1; \e nmx ≥ \e nmx1; \e mmx ≥ \e mmx1; 00147 * and similarly for \e N2, \e nmx2, and \e mmx2. 00148 * @exception GeographicErr if any of the vectors of coefficients is not 00149 * large enough. 00150 * 00151 * The class stores <i>pointers</i> to the first elements of \e C, \e S, \e 00152 * C', \e S', \e C'', and \e S''. These arrays should not be altered or 00153 * destroyed during the lifetime of a SphericalHarmonic object. 00154 **********************************************************************/ 00155 SphericalHarmonic2(array<double>^ C, 00156 array<double>^ S, 00157 int N, int nmx, int mmx, 00158 array<double>^ C1, 00159 array<double>^ S1, 00160 int N1, int nmx1, int mmx1, 00161 array<double>^ C2, 00162 array<double>^ S2, 00163 int N2, int nmx2, int mmx2, 00164 double a, 00165 Normalization norm ); 00166 00167 /** 00168 * The destructor calls the finalizer. 00169 **********************************************************************/ 00170 ~SphericalHarmonic2() 00171 { this->!SphericalHarmonic2(); } 00172 00173 /** 00174 * Compute a spherical harmonic sum with two correction terms. 00175 * 00176 * @param[in] tau1 multiplier for correction coefficients \e C' and \e S'. 00177 * @param[in] tau2 multiplier for correction coefficients \e C'' and \e S''. 00178 * @param[in] x cartesian coordinate. 00179 * @param[in] y cartesian coordinate. 00180 * @param[in] z cartesian coordinate. 00181 * @return \e V the spherical harmonic sum. 00182 * 00183 * This routine requires constant memory and thus never throws an 00184 * exception. 00185 **********************************************************************/ 00186 double HarmonicSum(double tau1, double tau2, double x, double y, double z); 00187 00188 /** 00189 * Compute a spherical harmonic sum with two correction terms and its 00190 * gradient. 00191 * 00192 * @param[in] tau1 multiplier for correction coefficients \e C' and \e S'. 00193 * @param[in] tau2 multiplier for correction coefficients \e C'' and \e S''. 00194 * @param[in] x cartesian coordinate. 00195 * @param[in] y cartesian coordinate. 00196 * @param[in] z cartesian coordinate. 00197 * @param[out] gradx \e x component of the gradient 00198 * @param[out] grady \e y component of the gradient 00199 * @param[out] gradz \e z component of the gradient 00200 * @return \e V the spherical harmonic sum. 00201 * 00202 * This is the same as the previous function, except that the components of 00203 * the gradients of the sum in the \e x, \e y, and \e z directions are 00204 * computed. This routine requires constant memory and thus never throws 00205 * an exception. 00206 **********************************************************************/ 00207 double HarmonicSum(double tau1, double tau2, double x, double y, double z, 00208 [System::Runtime::InteropServices::Out] double% gradx, 00209 [System::Runtime::InteropServices::Out] double% grady, 00210 [System::Runtime::InteropServices::Out] double% gradz); 00211 00212 /** 00213 * Create a CircularEngine to allow the efficient evaluation of several 00214 * points on a circle of latitude at fixed values of \e tau1 and \e tau2. 00215 * 00216 * @param[in] tau1 multiplier for correction coefficients \e C' and \e S'. 00217 * @param[in] tau2 multiplier for correction coefficients \e C'' and \e S''. 00218 * @param[in] p the radius of the circle. 00219 * @param[in] z the height of the circle above the equatorial plane. 00220 * @param[in] gradp if true the returned object will be able to compute the 00221 * gradient of the sum. 00222 * @exception std::bad_alloc if the memory for the CircularEngine can't be 00223 * allocated. 00224 * @return the CircularEngine object. 00225 * 00226 * SphericalHarmonic2::operator()() exchanges the order of the sums in the 00227 * definition, i.e., ∑<sub>n = 0..N</sub> ∑<sub>m = 0..n</sub> 00228 * becomes ∑<sub>m = 0..N</sub> ∑<sub>n = m..N</sub>.. 00229 * SphericalHarmonic2::Circle performs the inner sum over degree \e n 00230 * (which entails about <i>N</i><sup>2</sup> operations). Calling 00231 * CircularEngine::operator()() on the returned object performs the outer 00232 * sum over the order \e m (about \e N operations). 00233 * 00234 * See SphericalHarmonic::Circle for an example of its use. 00235 **********************************************************************/ 00236 CircularEngine^ Circle(double tau1, double tau2, double p, double z, bool gradp); 00237 00238 /** 00239 * @return the zeroth SphericalCoefficients object. 00240 **********************************************************************/ 00241 SphericalCoefficients^ Coefficients(); 00242 /** 00243 * @return the first SphericalCoefficients object. 00244 **********************************************************************/ 00245 SphericalCoefficients^ Coefficients1(); 00246 /** 00247 * @return the second SphericalCoefficients object. 00248 **********************************************************************/ 00249 SphericalCoefficients^ Coefficients2(); 00250 }; 00251 } // namespace NETGeographicLib