00001 /** 00002 * \file MagneticCircle.hpp 00003 * \brief Header for GeographicLib::MagneticCircle class 00004 * 00005 * Copyright (c) Charles Karney (2011) <charles@karney.com> and licensed under 00006 * the MIT/X11 License. For more information, see 00007 * http://geographiclib.sourceforge.net/ 00008 **********************************************************************/ 00009 00010 #if !defined(GEOGRAPHICLIB_MAGNETICCIRCLE_HPP) 00011 #define GEOGRAPHICLIB_MAGNETICCIRCLE_HPP 1 00012 00013 #include <vector> 00014 #include <GeographicLib/Constants.hpp> 00015 #include <GeographicLib/CircularEngine.hpp> 00016 00017 namespace GeographicLib { 00018 00019 /** 00020 * \brief Geomagnetic field on a circle of latitude 00021 * 00022 * Evaluate the earth's magnetic field on a circle of constant height and 00023 * latitude. This uses a CircularEngine to pre-evaluate the inner sum of the 00024 * spherical harmonic sum, allowing the values of the field at several 00025 * different longitudes to be evaluated rapidly. 00026 * 00027 * Use MagneticModel::Circle to create a MagneticCircle object. (The 00028 * constructor for this class is private.) 00029 * 00030 * Example of use: 00031 * \include example-MagneticCircle.cpp 00032 * 00033 * <a href="MagneticField.1.html">MagneticField</a> is a command-line utility 00034 * providing access to the functionality of MagneticModel and MagneticCircle. 00035 **********************************************************************/ 00036 00037 class GEOGRAPHICLIB_EXPORT MagneticCircle { 00038 private: 00039 typedef Math::real real; 00040 00041 real _a, _f, _lat, _h, _t, _cphi, _sphi, _t1, _dt0; 00042 bool _interpolate; 00043 CircularEngine _circ0, _circ1; 00044 00045 MagneticCircle(real a, real f, real lat, real h, real t, 00046 real cphi, real sphi, real t1, real dt0, 00047 bool interpolate, 00048 const CircularEngine& circ0, const CircularEngine& circ1) 00049 : _a(a) 00050 , _f(f) 00051 , _lat(lat) 00052 , _h(h) 00053 , _t(t) 00054 , _cphi(cphi) 00055 , _sphi(sphi) 00056 , _t1(t1) 00057 , _dt0(dt0) 00058 , _interpolate(interpolate) 00059 , _circ0(circ0) 00060 , _circ1(circ1) 00061 {} 00062 00063 void Field(real lon, bool diffp, 00064 real& Bx, real& By, real& Bz, 00065 real& Bxt, real& Byt, real& Bzt) const; 00066 00067 friend class MagneticModel; // MagneticModel calls the private constructor 00068 00069 public: 00070 00071 /** 00072 * A default constructor for the normal gravity. This sets up an 00073 * uninitialized object which can be later replaced by the 00074 * MagneticModel::Circle. 00075 **********************************************************************/ 00076 MagneticCircle() : _a(-1) {} 00077 00078 /** \name Compute the magnetic field 00079 **********************************************************************/ 00080 ///@{ 00081 /** 00082 * Evaluate the components of the geomagnetic field at a particular 00083 * longitude. 00084 * 00085 * @param[in] lon longitude of the point (degrees). 00086 * @param[out] Bx the easterly component of the magnetic field (nanotesla). 00087 * @param[out] By the northerly component of the magnetic field (nanotesla). 00088 * @param[out] Bz the vertical (up) component of the magnetic field 00089 * (nanotesla). 00090 **********************************************************************/ 00091 void operator()(real lon, real& Bx, real& By, real& Bz) const { 00092 real dummy; 00093 Field(lon, false, Bx, By, Bz, dummy, dummy, dummy); 00094 } 00095 00096 /** 00097 * Evaluate the components of the geomagnetic field and their time 00098 * derivatives at a particular longitude. 00099 * 00100 * @param[in] lon longitude of the point (degrees). 00101 * @param[out] Bx the easterly component of the magnetic field (nanotesla). 00102 * @param[out] By the northerly component of the magnetic field (nanotesla). 00103 * @param[out] Bz the vertical (up) component of the magnetic field 00104 * (nanotesla). 00105 * @param[out] Bxt the rate of change of \e Bx (nT/yr). 00106 * @param[out] Byt the rate of change of \e By (nT/yr). 00107 * @param[out] Bzt the rate of change of \e Bz (nT/yr). 00108 **********************************************************************/ 00109 void operator()(real lon, real& Bx, real& By, real& Bz, 00110 real& Bxt, real& Byt, real& Bzt) const { 00111 Field(lon, true, Bx, By, Bz, Bxt, Byt, Bzt); 00112 } 00113 ///@} 00114 00115 /** \name Inspector functions 00116 **********************************************************************/ 00117 ///@{ 00118 /** 00119 * @return true if the object has been initialized. 00120 **********************************************************************/ 00121 bool Init() const { return _a > 0; } 00122 /** 00123 * @return \e a the equatorial radius of the ellipsoid (meters). This is 00124 * the value inherited from the MagneticModel object used in the 00125 * constructor. 00126 **********************************************************************/ 00127 Math::real MajorRadius() const 00128 { return Init() ? _a : Math::NaN(); } 00129 /** 00130 * @return \e f the flattening of the ellipsoid. This is the value 00131 * inherited from the MagneticModel object used in the constructor. 00132 **********************************************************************/ 00133 Math::real Flattening() const 00134 { return Init() ? _f : Math::NaN(); } 00135 /** 00136 * @return the latitude of the circle (degrees). 00137 **********************************************************************/ 00138 Math::real Latitude() const 00139 { return Init() ? _lat : Math::NaN(); } 00140 /** 00141 * @return the height of the circle (meters). 00142 **********************************************************************/ 00143 Math::real Height() const 00144 { return Init() ? _h : Math::NaN(); } 00145 /** 00146 * @return the time (fractional years). 00147 **********************************************************************/ 00148 Math::real Time() const 00149 { return Init() ? _t : Math::NaN(); } 00150 00151 ///@} 00152 }; 00153 00154 } // namespace GeographicLib 00155 00156 #endif // GEOGRAPHICLIB_MAGNETICCIRCLE_HPP