GeographicLib  2.1.1
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) <charles@karney.com> 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>
16 
17 namespace 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 
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  **********************************************************************/
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  **********************************************************************/
177  { return Init() ? _f : Math::NaN(); }
178  /**
179  * @return the latitude of the circle (degrees).
180  **********************************************************************/
182  { return Init() ? _lat : Math::NaN(); }
183  /**
184  * @return the height of the circle (meters).
185  **********************************************************************/
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
Header for GeographicLib::CircularEngine class.
Header for GeographicLib::Constants class.
#define GEOGRAPHICLIB_EXPORT
Definition: Constants.hpp:67
GeographicLib::Math::real real
Definition: GeodSolve.cpp:31
Spherical harmonic sums for a circle.
Geomagnetic field on a circle of latitude.
void operator()(real lon, real &Bx, real &By, real &Bz) const
Math::real EquatorialRadius() const
void operator()(real lon, real &Bx, real &By, real &Bz, real &Bxt, real &Byt, real &Bzt) const
Model of the earth's magnetic field.
static T LatFix(T x)
Definition: Math.hpp:300
static T NaN()
Definition: Math.cpp:250
Namespace for GeographicLib.
Definition: Accumulator.cpp:12