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