#pragma once /** * \file NETGeographicLib/SphericalHarmonic1.h * \brief Header for NETGeographicLib::SphericalHarmonic1 class * * NETGeographicLib is copyright (c) Scott Heiman (2013) * GeographicLib is Copyright (c) Charles Karney (2010-2012) * and licensed under the MIT/X11 License. * For more information, see * https://geographiclib.sourceforge.io/ **********************************************************************/ namespace NETGeographicLib { ref class SphericalCoefficients; ref class CircularEngine; /** * \brief .NET wrapper for GeographicLib::SphericalHarmonic1. * * This class allows .NET applications to access GeographicLib::SphericalHarmonic1. * * This class is similar to SphericalHarmonic, except that the coefficients * \e C\e nm are replaced by \e C\e nm + \e tau * C'\e nm (and similarly for \e S\e nm). * * C# Example: * \include example-SphericalHarmonic1.cs * Managed C++ Example: * \include example-SphericalHarmonic1.cpp * Visual Basic Example: * \include example-SphericalHarmonic1.vb * * INTERFACE DIFFERENCES:
* This class replaces the () operator with HarmonicSum(). * * Coefficients returns a SphericalCoefficients object. **********************************************************************/ public ref class SphericalHarmonic1 { private: // pointer to the unmanaged GeographicLib::SphericalHarmonic1. const GeographicLib::SphericalHarmonic1* m_pSphericalHarmonic1; // the finalizer destroys the unmanaged memory when the object is destroyed. !SphericalHarmonic1(void); // the number of coefficient vectors. static const int m_numCoeffVectors = 2; // local containers for the cosine and sine coefficients. The // GeographicLib::SphericalEngine::coeffs class uses a // std::vector::iterator to access these vectors. std::vector **m_C, **m_S; public: /** * Supported normalizations for associate Legendre polynomials. **********************************************************************/ enum class Normalization { /** * Fully normalized associated Legendre polynomials. See * SphericalHarmonic::FULL for documentation. * * @hideinitializer **********************************************************************/ FULL = GeographicLib::SphericalEngine::FULL, /** * Schmidt semi-normalized associated Legendre polynomials. See * SphericalHarmonic::SCHMIDT for documentation. * * @hideinitializer **********************************************************************/ SCHMIDT = GeographicLib::SphericalEngine::SCHMIDT, }; /** * Constructor with a full set of coefficients specified. * * @param[in] C the coefficients \e C\e nm. * @param[in] S the coefficients \e S\e nm. * @param[in] N the maximum degree and order of the sum * @param[in] C1 the coefficients \e C'\e nm. * @param[in] S1 the coefficients \e S'\e nm. * @param[in] N1 the maximum degree and order of the correction * coefficients \e C'\e nm and \e S'\e nm. * @param[in] a the reference radius appearing in the definition of the * sum. * @param[in] norm the normalization for the associated Legendre * polynomials, either SphericalHarmonic1::FULL (the default) or * SphericalHarmonic1::SCHMIDT. * @exception GeographicErr if \e N and \e N1 do not satisfy \e N ≥ * \e N1 ≥ −1. * @exception GeographicErr if any of the vectors of coefficients is not * large enough. * * See SphericalHarmonic for the way the coefficients should be stored. * * The class stores pointers to the first elements of \e C, \e S, \e * C', and \e S'. These arrays should not be altered or destroyed during * the lifetime of a SphericalHarmonic object. **********************************************************************/ SphericalHarmonic1(array^ C, array^ S, int N, array^ C1, array^ S1, int N1, double a, Normalization norm ); /** * Constructor with a subset of coefficients specified. * * @param[in] C the coefficients \e C\e nm. * @param[in] S the coefficients \e S\e nm. * @param[in] N the degree used to determine the layout of \e C and \e S. * @param[in] nmx the maximum degree used in the sum. The sum over \e n is * from 0 thru \e nmx. * @param[in] mmx the maximum order used in the sum. The sum over \e m is * from 0 thru min(\e n, \e mmx). * @param[in] C1 the coefficients \e C'\e nm. * @param[in] S1 the coefficients \e S'\e nm. * @param[in] N1 the degree used to determine the layout of \e C' and \e * S'. * @param[in] nmx1 the maximum degree used for \e C' and \e S'. * @param[in] mmx1 the maximum order used for \e C' and \e S'. * @param[in] a the reference radius appearing in the definition of the * sum. * @param[in] norm the normalization for the associated Legendre * polynomials, either SphericalHarmonic1::FULL (the default) or * SphericalHarmonic1::SCHMIDT. * @exception GeographicErr if the parameters do not satisfy \e N ≥ \e * nmx ≥ \e mmx ≥ −1; \e N1 ≥ \e nmx1 ≥ \e mmx1 ≥ * −1; \e N ≥ \e N1; \e nmx ≥ \e nmx1; \e mmx ≥ \e mmx1. * @exception GeographicErr if any of the vectors of coefficients is not * large enough. * * The class stores pointers to the first elements of \e C, \e S, \e * C', and \e S'. These arrays should not be altered or destroyed during * the lifetime of a SphericalHarmonic object. **********************************************************************/ SphericalHarmonic1(array^ C, array^ S, int N, int nmx, int mmx, array^ C1, array^ S1, int N1, int nmx1, int mmx1, double a, Normalization norm ); /** * The destructor calls the finalizer. **********************************************************************/ ~SphericalHarmonic1() { this->!SphericalHarmonic1(); } /** * Compute a spherical harmonic sum with a correction term. * * @param[in] tau multiplier for correction coefficients \e C' and \e S'. * @param[in] x cartesian coordinate. * @param[in] y cartesian coordinate. * @param[in] z cartesian coordinate. * @return \e V the spherical harmonic sum. * * This routine requires constant memory and thus never throws * an exception. **********************************************************************/ double HarmonicSum(double tau, double x, double y, double z); /** * Compute a spherical harmonic sum with a correction term and its * gradient. * * @param[in] tau multiplier for correction coefficients \e C' and \e S'. * @param[in] x cartesian coordinate. * @param[in] y cartesian coordinate. * @param[in] z cartesian coordinate. * @param[out] gradx \e x component of the gradient * @param[out] grady \e y component of the gradient * @param[out] gradz \e z component of the gradient * @return \e V the spherical harmonic sum. * * This is the same as the previous function, except that the components of * the gradients of the sum in the \e x, \e y, and \e z directions are * computed. This routine requires constant memory and thus never throws * an exception. **********************************************************************/ 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); /** * Create a CircularEngine to allow the efficient evaluation of several * points on a circle of latitude at a fixed value of \e tau. * * @param[in] tau the multiplier for the correction coefficients. * @param[in] p the radius of the circle. * @param[in] z the height of the circle above the equatorial plane. * @param[in] gradp if true the returned object will be able to compute the * gradient of the sum. * @exception std::bad_alloc if the memory for the CircularEngine can't be * allocated. * @return the CircularEngine object. * * SphericalHarmonic1::operator()() exchanges the order of the sums in the * definition, i.e., ∑n = 0..N ∑m = 0..n * becomes ∑m = 0..N ∑n = m..N. * SphericalHarmonic1::Circle performs the inner sum over degree \e n * (which entails about N2 operations). Calling * CircularEngine::operator()() on the returned object performs the outer * sum over the order \e m (about \e N operations). * * See SphericalHarmonic::Circle for an example of its use. **********************************************************************/ CircularEngine^ Circle(double tau, double p, double z, bool gradp); /** * @return the zeroth SphericalCoefficients object. **********************************************************************/ SphericalCoefficients^ Coefficients(); /** * @return the first SphericalCoefficients object. **********************************************************************/ SphericalCoefficients^ Coefficients1(); }; } // namespace NETGeographicLib