NETGeographicLib  1.38
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Friends Pages
CircularEngine.h
Go to the documentation of this file.
1 /**
2  * \file NETGeographicLib/CircularEngine.h
3  * \brief Header for NETGeographicLib::CircularEngine class
4  *
5  * NETGeographicLib is copyright (c) Scott Heiman (2013)
6  * GeographicLib is Copyright (c) Charles Karney (2010-2012)
7  * <charles@karney.com> and licensed under the MIT/X11 License.
8  * For more information, see
9  * http://geographiclib.sourceforge.net/
10  **********************************************************************/
11 #pragma once
12 
13 namespace NETGeographicLib
14 {
15  /**
16  * \brief .NET wrapper for GeographicLib::CircularEngine.
17  *
18  * This class allows .NET applications to access GeographicLib::CircularEngine.
19  *
20  * The class is a companion to SphericalEngine. If the results of a
21  * spherical harmonic sum are needed for several points on a circle of
22  * constant latitude \e lat and height \e h, then SphericalEngine::Circle can
23  * compute the inner sum, which is independent of longitude \e lon, and
24  * produce a CircularEngine object. CircularEngine::LongitudeSum() can
25  * then be used to perform the outer sum for particular values of \e lon.
26  * This can lead to substantial improvements in computational speed for high
27  * degree sum (approximately by a factor of \e N / 2 where \e N is the
28  * maximum degree).
29  *
30  * CircularEngine is tightly linked to the internals of SphericalEngine. For
31  * that reason, the constructor for this class is for internal use only. Use
32  * SphericalHarmonic::Circle, SphericalHarmonic1::Circle, and
33  * SphericalHarmonic2::Circle to create instances of this class.
34  *
35  * CircularEngine stores the coefficients needed to allow the summation over
36  * order to be performed in 2 or 6 vectors of length \e M + 1 (depending on
37  * whether gradients are to be calculated). For this reason the constructor
38  * may throw a GeographicErr exception.
39  *
40  * C# Example:
41  * \include example-CircularEngine.cs
42  * Managed C++ Example:
43  * \include example-CircularEngine.cpp
44  * Visual Basic Example:
45  * \include example-CircularEngine.vb
46  *
47  * <B>INTERFACE DIFFERENCES:</B><BR>
48  * The () operator has been replaced with with LongitudeSum.
49  *
50  * This class does not have a constructor that can be used in a .NET
51  * application. Use SphericalHarmonic::Circle, SphericalHarmonic1::Circle or
52  * SphericalHarmonic2::Circle to create instances of this class.
53  **********************************************************************/
54  public ref class CircularEngine
55  {
56  private:
57  // pointer to the unmanaged GeographicLib::CircularEngine
58  const GeographicLib::CircularEngine* m_pCircularEngine;
59 
60  // The finalizer frees the unmanaged memory when the object is destroyed.
61  !CircularEngine();
62  public:
63  /**
64  * The constructor.
65  *
66  * This constructor should not be used in .NET applications.
67  * Use SphericalHarmonic::Circle, SphericalHarmonic1::Circle or
68  * SphericalHarmonic2::Circle to create instances of this class.
69  *
70  * @param[in] c The unmanaged CircularEngine to be copied.
71  **********************************************************************/
73 
74  /**
75  * The destructor calls the finalizer
76  **********************************************************************/
78  { this->!CircularEngine(); }
79 
80  /**
81  * Evaluate the sum for a particular longitude given in terms of its
82  * cosine and sine.
83  *
84  * @param[in] coslon the cosine of the longitude.
85  * @param[in] sinlon the sine of the longitude.
86  * @return \e V the value of the sum.
87  *
88  * The arguments must satisfy <i>coslon</i><sup>2</sup> +
89  * <i>sinlon</i><sup>2</sup> = 1.
90  **********************************************************************/
91  double LongitudeSum(double coslon, double sinlon);
92 
93  /**
94  * Evaluate the sum for a particular longitude.
95  *
96  * @param[in] lon the longitude (degrees).
97  * @return \e V the value of the sum.
98  **********************************************************************/
99  double LongitudeSum(double lon);
100 
101  /**
102  * Evaluate the sum and its gradient for a particular longitude given in
103  * terms of its cosine and sine.
104  *
105  * @param[in] coslon the cosine of the longitude.
106  * @param[in] sinlon the sine of the longitude.
107  * @param[out] gradx \e x component of the gradient.
108  * @param[out] grady \e y component of the gradient.
109  * @param[out] gradz \e z component of the gradient.
110  * @return \e V the value of the sum.
111  *
112  * The gradients will only be computed if the CircularEngine object was
113  * created with this capability (e.g., via \e gradp = true in
114  * SphericalHarmonic::Circle). If not, \e gradx, etc., will not be
115  * touched. The arguments must satisfy <i>coslon</i><sup>2</sup> +
116  * <i>sinlon</i><sup>2</sup> = 1.
117  **********************************************************************/
118  double LongitudeSum(double coslon, double sinlon,
119  [System::Runtime::InteropServices::Out] double% gradx,
120  [System::Runtime::InteropServices::Out] double% grady,
121  [System::Runtime::InteropServices::Out] double% gradz);
122 
123  /**
124  * Evaluate the sum and its gradient for a particular longitude.
125  *
126  * @param[in] lon the longitude (degrees).
127  * @param[out] gradx \e x component of the gradient.
128  * @param[out] grady \e y component of the gradient.
129  * @param[out] gradz \e z component of the gradient.
130  * @return \e V the value of the sum.
131  *
132  * The gradients will only be computed if the CircularEngine object was
133  * created with this capability (e.g., via \e gradp = true in
134  * SphericalHarmonic::Circle). If not, \e gradx, etc., will not be
135  * touched.
136  **********************************************************************/
137  double LongitudeSum(double lon,
138  [System::Runtime::InteropServices::Out] double% gradx,
139  [System::Runtime::InteropServices::Out] double% grady,
140  [System::Runtime::InteropServices::Out] double% gradz);
141  };
142 } //namespace NETGeographicLib
CircularEngine(const GeographicLib::CircularEngine &c)
double LongitudeSum(double coslon, double sinlon)
.NET wrapper for GeographicLib::CircularEngine.