GeographicLib 2.5
MagneticCircle.hpp
Go to the documentation of this file.
1/**
2 * \file MagneticCircle.hpp
3 * \brief Header for GeographicLib::MagneticCircle class
4 *
5 * Copyright (c) Charles Karney (2011-2022) <karney@alum.mit.edu> and licensed
6 * under the MIT/X11 License. For more information, see
7 * https://geographiclib.sourceforge.io/
8 **********************************************************************/
9
10#if !defined(GEOGRAPHICLIB_MAGNETICCIRCLE_HPP)
11#define GEOGRAPHICLIB_MAGNETICCIRCLE_HPP 1
12
13#include <vector>
14#include <GeographicLib/Constants.hpp>
15#include <GeographicLib/CircularEngine.hpp>
16
17namespace GeographicLib {
18
19 /**
20 * \brief Geomagnetic field on a circle of latitude
21 *
22 * Evaluate the earth's magnetic field on a circle of constant height and
23 * latitude. This uses a CircularEngine to pre-evaluate the inner sum of the
24 * spherical harmonic sum, allowing the values of the field at several
25 * different longitudes to be evaluated rapidly.
26 *
27 * Use MagneticModel::Circle to create a MagneticCircle object. (The
28 * constructor for this class is private.)
29 *
30 * Example of use:
31 * \include example-MagneticCircle.cpp
32 *
33 * <a href="MagneticField.1.html">MagneticField</a> is a command-line utility
34 * providing access to the functionality of MagneticModel and MagneticCircle.
35 **********************************************************************/
36
37 class GEOGRAPHICLIB_EXPORT MagneticCircle {
38 private:
39 typedef Math::real real;
40
41 real _a, _f, _lat, _h, _t, _cphi, _sphi, _t1, _dt0;
42 bool _interpolate, _constterm;
43 CircularEngine _circ0, _circ1, _circ2;
44
45 MagneticCircle(real a, real f, real lat, real h, real t,
46 real cphi, real sphi, real t1, real dt0,
47 bool interpolate,
48 const CircularEngine& circ0, const CircularEngine& circ1)
49 : _a(a)
50 , _f(f)
51 , _lat(Math::LatFix(lat))
52 , _h(h)
53 , _t(t)
54 , _cphi(cphi)
55 , _sphi(sphi)
56 , _t1(t1)
57 , _dt0(dt0)
58 , _interpolate(interpolate)
59 , _constterm(false)
60 , _circ0(circ0)
61 , _circ1(circ1)
62 {}
63
64 MagneticCircle(real a, real f, real lat, real h, real t,
65 real cphi, real sphi, real t1, real dt0,
66 bool interpolate,
67 const CircularEngine& circ0, const CircularEngine& circ1,
68 const CircularEngine& circ2)
69 : _a(a)
70 , _f(f)
71 , _lat(lat)
72 , _h(h)
73 , _t(t)
74 , _cphi(cphi)
75 , _sphi(sphi)
76 , _t1(t1)
77 , _dt0(dt0)
78 , _interpolate(interpolate)
79 , _constterm(true)
80 , _circ0(circ0)
81 , _circ1(circ1)
82 , _circ2(circ2)
83 {}
84
85 void Field(real lon, bool diffp,
86 real& Bx, real& By, real& Bz,
87 real& Bxt, real& Byt, real& Bzt) const;
88
89 void FieldGeocentric(real slam, real clam,
90 real& BX, real& BY, real& BZ,
91 real& BXt, real& BYt, real& BZt) const;
92
93 friend class MagneticModel; // MagneticModel calls the private constructor
94
95 public:
96
97 /**
98 * A default constructor for the normal gravity. This sets up an
99 * uninitialized object which can be later replaced by the
100 * MagneticModel::Circle.
101 **********************************************************************/
102 MagneticCircle() : _a(-1) {}
103
104 /** \name Compute the magnetic field
105 **********************************************************************/
106 ///@{
107 /**
108 * Evaluate the components of the geomagnetic field at a particular
109 * longitude.
110 *
111 * @param[in] lon longitude of the point (degrees).
112 * @param[out] Bx the easterly component of the magnetic field (nanotesla).
113 * @param[out] By the northerly component of the magnetic field
114 * (nanotesla).
115 * @param[out] Bz the vertical (up) component of the magnetic field
116 * (nanotesla).
117 **********************************************************************/
118 void operator()(real lon, real& Bx, real& By, real& Bz) const {
119 real dummy;
120 Field(lon, false, Bx, By, Bz, dummy, dummy, dummy);
121 }
122
123 /**
124 * Evaluate the components of the geomagnetic field and their time
125 * derivatives at a particular longitude.
126 *
127 * @param[in] lon longitude of the point (degrees).
128 * @param[out] Bx the easterly component of the magnetic field (nanotesla).
129 * @param[out] By the northerly component of the magnetic field
130 * (nanotesla).
131 * @param[out] Bz the vertical (up) component of the magnetic field
132 * (nanotesla).
133 * @param[out] Bxt the rate of change of \e Bx (nT/yr).
134 * @param[out] Byt the rate of change of \e By (nT/yr).
135 * @param[out] Bzt the rate of change of \e Bz (nT/yr).
136 **********************************************************************/
137 void operator()(real lon, real& Bx, real& By, real& Bz,
138 real& Bxt, real& Byt, real& Bzt) const {
139 Field(lon, true, Bx, By, Bz, Bxt, Byt, Bzt);
140 }
141
142 /**
143 * Evaluate the components of the geomagnetic field and their time
144 * derivatives at a particular longitude.
145 *
146 * @param[in] lon longitude of the point (degrees).
147 * @param[out] BX the \e X component of the magnetic field (nT).
148 * @param[out] BY the \e Y component of the magnetic field (nT).
149 * @param[out] BZ the \e Z component of the magnetic field (nT).
150 * @param[out] BXt the rate of change of \e BX (nT/yr).
151 * @param[out] BYt the rate of change of \e BY (nT/yr).
152 * @param[out] BZt the rate of change of \e BZ (nT/yr).
153 **********************************************************************/
154 void FieldGeocentric(real lon, real& BX, real& BY, real& BZ,
155 real& BXt, real& BYt, real& BZt) const;
156 ///@}
157
158 /** \name Inspector functions
159 **********************************************************************/
160 ///@{
161 /**
162 * @return true if the object has been initialized.
163 **********************************************************************/
164 bool Init() const { return _a > 0; }
165 /**
166 * @return \e a the equatorial radius of the ellipsoid (meters). This is
167 * the value inherited from the MagneticModel object used in the
168 * constructor.
169 **********************************************************************/
170 Math::real EquatorialRadius() const
171 { return Init() ? _a : Math::NaN(); }
172 /**
173 * @return \e f the flattening of the ellipsoid. This is the value
174 * inherited from the MagneticModel object used in the constructor.
175 **********************************************************************/
176 Math::real Flattening() const
177 { return Init() ? _f : Math::NaN(); }
178 /**
179 * @return the latitude of the circle (degrees).
180 **********************************************************************/
181 Math::real Latitude() const
182 { return Init() ? _lat : Math::NaN(); }
183 /**
184 * @return the height of the circle (meters).
185 **********************************************************************/
186 Math::real Height() const
187 { return Init() ? _h : Math::NaN(); }
188 /**
189 * @return the time (fractional years).
190 **********************************************************************/
191 Math::real Time() const
192 { return Init() ? _t : Math::NaN(); }
193 ///@}
194 };
195
196} // namespace GeographicLib
197
198#endif // GEOGRAPHICLIB_MAGNETICCIRCLE_HPP
CircularEngine.hpp
Header for GeographicLib::CircularEngine class.
Constants.hpp
Header for GeographicLib::Constants class.
GEOGRAPHICLIB_EXPORT
#define GEOGRAPHICLIB_EXPORT
Definition Constants.hpp:67
real
GeographicLib::Math::real real
Definition GeodSolve.cpp:28
GeographicLib::CircularEngine
Spherical harmonic sums for a circle.
Definition CircularEngine.hpp:52
GeographicLib::MagneticCircle
Geomagnetic field on a circle of latitude.
Definition MagneticCircle.hpp:37
GeographicLib::MagneticCircle::operator()
void operator()(real lon, real &Bx, real &By, real &Bz) const
Definition MagneticCircle.hpp:118
GeographicLib::MagneticCircle::EquatorialRadius
Math::real EquatorialRadius() const
Definition MagneticCircle.hpp:170
GeographicLib::MagneticCircle::operator()
void operator()(real lon, real &Bx, real &By, real &Bz, real &Bxt, real &Byt, real &Bzt) const
Definition MagneticCircle.hpp:137
GeographicLib::MagneticModel
Model of the earth's magnetic field.
Definition MagneticModel.hpp:79
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12