GeographicLib: GeographicLib::MagneticModel Class Reference

GeographicLib 2.7

Loading...
Searching...
No Matches
GeographicLib::MagneticModel Class Reference

Model of the earth's magnetic field. More...

`#include <GeographicLib/MagneticModel.hpp>`

## Public Member Functions
| MagneticModel (MagneticModel &&)=default
MagneticModel & | operator= (MagneticModel &&)=default
Setting up the magnetic model
| MagneticModel (const std::string &name, const std::string &path="", const Geocentric &earth=Geocentric::WGS84(), int Nmax=-1, int Mmax=-1)
Inspector functions
const std::string & | Description () const
const std::string & | DateTime () const
const std::string & | MagneticFile () const
const std::string & | MagneticModelName () const
const std::string & | MagneticModelDirectory () const
Math::real | MinHeight () const
Math::real | MaxHeight () const
Math::real | MinTime () const
Math::real | MaxTime () const
Math::real | EquatorialRadius () const
Math::real | Flattening () const
int | Degree () const
int | Order () const

## Static Public Member Functions
static std::string | DefaultMagneticPath ()
static std::string | DefaultMagneticName ()

## Compute the magnetic field
void | operator() (real t, real lat, real lon, real h, real &Bx, real &By, real &Bz) const
void | operator() (real t, real lat, real lon, real h, real &Bx, real &By, real &Bz, real &Bxt, real &Byt, real &Bzt) const
MagneticCircle | Circle (real t, real lat, real h) const
void | FieldGeocentric (real t, real X, real Y, real Z, real &BX, real &BY, real &BZ, real &BXt, real &BYt, real &BZt) const
static void | FieldComponents (real Bx, real By, real Bz, real &H, real &F, real &D, real &I)
static void | FieldComponents (real Bx, real By, real Bz, real Bxt, real Byt, real Bzt, real &H, real &F, real &D, real &I, real &Ht, real &Ft, real &Dt, real &It)

## Detailed Description

Model of the earth's magnetic field.

Evaluate the earth's magnetic field according to a model. At present only internal magnetic fields are handled. These are due to the earth's code and crust; these vary slowly (over many years). Excluded are the effects of currents in the ionosphere and magnetosphere which have daily and annual variations.

See Magnetic models for details of how to install the magnetic models and the data format.

See

- General information:
  - http://geomag.org/models/index.html
- WMM2010:
  - https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
  - https://ngdc.noaa.gov/geomag/WMM/data/WMM2010/WMM2010COF.zip
- WMM2015 (deprecated):
  - https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
  - https://ngdc.noaa.gov/geomag/WMM/data/WMM2015/WMM2015COF.zip
- WMM2015V2:
  - https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
  - https://ngdc.noaa.gov/geomag/WMM/data/WMM2015/WMM2015v2COF.zip
- WMM2020:
  - https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml
  - https://ngdc.noaa.gov/geomag/WMM/data/WMM2020/WMM2020COF.zip
- WMM2025:
  - https://www.ncei.noaa.gov/products/world-magnetic-model
- WMMHR2025:
  - https://www.ncei.noaa.gov/products/world-magnetic-model-high-resolution
- IGRF11:
  - https://ngdc.noaa.gov/IAGA/vmod/igrf.html
  - https://ngdc.noaa.gov/IAGA/vmod/igrf11coeffs.txt
  - https://ngdc.noaa.gov/IAGA/vmod/geomag70_linux.tar.gz
- EMM2010:
  - https://ngdc.noaa.gov/geomag/EMM/index.html
  - https://ngdc.noaa.gov/geomag/EMM/data/geomag/EMM2010_Sph_Windows_Linux.zip
- EMM2015:
  - https://ngdc.noaa.gov/geomag/EMM/index.html
  - https://www.ngdc.noaa.gov/geomag/EMM/data/geomag/EMM2015_Sph_Linux.zip
- EMM2017:
  - https://ngdc.noaa.gov/geomag/EMM/index.html
  - https://www.ngdc.noaa.gov/geomag/EMM/data/geomag/EMM2017_Sph_Linux.zip

Example of use:

// Example of using the GeographicLib::MagneticModel class
// This requires that the wmm2010 magnetic model be installed; see
// https://geographiclib.sourceforge.io/C++/doc/magnetic.html#magneticinst
#include <iostream>
#include <exception>
#include <GeographicLib/MagneticModel.hpp>
using namespace std;
using namespace GeographicLib;
int main() {
try {
MagneticModel mag("wmm2010");
double lat = 27.99, lon = 86.93, h = 8820, t = 2012; // Mt Everest
double Bx, By, Bz;
mag(t, lat,lon, h, Bx, By, Bz);
double H, F, D, I;
MagneticModel::FieldComponents(Bx, By, Bz, H, F, D, I);
cout << H << " " << F << " " << D << " " << I << "\n";
}
catch (const exception& e) {
cerr << "Caught exception: " << e.what() << "\n";
return 1;
}
}
main
int main(int argc, const char *const argv[])
Definition Cart3Convert.cpp:52
MagneticModel.hpp
Header for GeographicLib::MagneticModel class.
GeographicLib::MagneticModel::FieldComponents
static void FieldComponents(real Bx, real By, real Bz, real &H, real &F, real &D, real &I)
Definition MagneticModel.hpp:263
GeographicLib
Namespace for GeographicLib.
Definition Accumulator.cpp:12
std
Definition NearestNeighbor.hpp:806

MagneticField is a command-line utility providing access to the functionality of MagneticModel and MagneticCircle.

Definition at line 79 of file MagneticModel.hpp.

## Constructor & Destructor Documentation

## ◆ MagneticModel() [1/2]

GeographicLib::MagneticModel::MagneticModel | ( | MagneticModel && |  | ) |
| default

Move constructs a magnetic model.

## ◆ MagneticModel() [2/2]

GeographicLib::MagneticModel::MagneticModel | ( | const std::string & | name,
|  | const std::string & | path = "",
|  | const Geocentric & | earth = Geocentric::WGS84(),
|  | int | Nmax = -1,
|  | int | Mmax = -1 )
| explicit

Construct a magnetic model.

Parameters

  [in] | name | the name of the model.
  [in] | path | (optional) directory for data file.
  [in] | earth | (optional) Geocentric object for converting coordinates; default Geocentric::WGS84().
  [in] | Nmax | (optional) if nonnegative, truncate the degree of the model this value.
  [in] | Mmax | (optional) if nonnegative, truncate the order of the model this value.

Exceptions

  GeographicErr | if the data file cannot be found, is unreadable, or is corrupt, or if Mmax > Nmax.
  std::bad_alloc | if the memory necessary for storing the model can't be allocated.

A filename is formed by appending ".wmm" (World Magnetic Model) to the name. If path is specified (and is non-empty), then the file is loaded from directory, path. Otherwise the path is given by the DefaultMagneticPath().

This file contains the metadata which specifies the properties of the model. The coefficients for the spherical harmonic sums are obtained from a file obtained by appending ".cof" to metadata file (so the filename ends in ".wwm.cof").

The model is not tied to a particular ellipsoidal model of the earth. The final earth argument to the constructor specifies an ellipsoid to allow geodetic coordinates to the transformed into the spherical coordinates used in the spherical harmonic sum.

If Nmax ≥ 0 and Mmax < 0, then Mmax is set to Nmax. After the model is loaded, the maximum degree and order of the model can be found by the Degree() and Order() methods.

Definition at line 37 of file MagneticModel.cpp.

References DefaultMagneticPath(), and GeographicLib::SphericalEngine::coeff::readcoeffs().

## Member Function Documentation

## ◆ operator=()

MagneticModel & GeographicLib::MagneticModel::operator= | ( | MagneticModel && |  | ) |
| default

Move assigns a magnetic model.

References GeographicLib::Geocentric::WGS84().

## ◆ operator()() [1/2]

void GeographicLib::MagneticModel::operator() | ( | real | t,
|  | real | lat,
|  | real | lon,
|  | real | h,
|  | real & | Bx,
|  | real & | By,
|  | real & | Bz ) const
| inline

Evaluate the components of the geomagnetic field.

Parameters

  [in] | t | the time (fractional years).
  [in] | lat | latitude of the point (degrees).
  [in] | lon | longitude of the point (degrees).
  [in] | h | the height of the point above the ellipsoid (meters).
  [out] | Bx | the easterly component of the magnetic field (nanotesla).
  [out] | By | the northerly component of the magnetic field (nanotesla).
  [out] | Bz | the vertical (up) component of the magnetic field (nanotesla).

Use Utility::fractionalyear to convert a date of the form yyyy-mm or yyyy-mm-dd into a fractional year.

Definition at line 174 of file MagneticModel.hpp.

## ◆ operator()() [2/2]

void GeographicLib::MagneticModel::operator() | ( | real | t,
|  | real | lat,
|  | real | lon,
|  | real | h,
|  | real & | Bx,
|  | real & | By,
|  | real & | Bz,
|  | real & | Bxt,
|  | real & | Byt,
|  | real & | Bzt ) const
| inline

Evaluate the components of the geomagnetic field and their time derivatives

Parameters

  [in] | t | the time (fractional years).
  [in] | lat | latitude of the point (degrees).
  [in] | lon | longitude of the point (degrees).
  [in] | h | the height of the point above the ellipsoid (meters).
  [out] | Bx | the easterly component of the magnetic field (nanotesla).
  [out] | By | the northerly component of the magnetic field (nanotesla).
  [out] | Bz | the vertical (up) component of the magnetic field (nanotesla).
  [out] | Bxt | the rate of change of Bx (nT/yr).
  [out] | Byt | the rate of change of By (nT/yr).
  [out] | Bzt | the rate of change of Bz (nT/yr).

Use Utility::fractionalyear to convert a date of the form yyyy-mm or yyyy-mm-dd into a fractional year.

Definition at line 200 of file MagneticModel.hpp.

## ◆ Circle()

MagneticCircle GeographicLib::MagneticModel::Circle | ( | real | t,
|  | real | lat,
|  | real | h ) const

Create a MagneticCircle object to allow the geomagnetic field at many points with constant lat, h, and t and varying lon to be computed efficiently.

Parameters

  [in] | t | the time (fractional years).
  [in] | lat | latitude of the point (degrees).
  [in] | h | the height of the point above the ellipsoid (meters).

Exceptions

  std::bad_alloc | if the memory necessary for creating a MagneticCircle can't be allocated.

Returns
  a MagneticCircle object whose MagneticCircle::operator()(real lon) member function computes the field at particular values of lon.

If the field at several points on a circle of latitude need to be calculated then creating a MagneticCircle and using its member functions will be substantially faster, especially for high-degree models.

Use Utility::fractionalyear to convert a date of the form yyyy-mm or yyyy-mm-dd into a fractional year.

Definition at line 238 of file MagneticModel.cpp.

Referenced by main().

## ◆ FieldGeocentric()

void GeographicLib::MagneticModel::FieldGeocentric | ( | real | t,
|  | real | X,
|  | real | Y,
|  | real | Z,
|  | real & | BX,
|  | real & | BY,
|  | real & | BZ,
|  | real & | BXt,
|  | real & | BYt,
|  | real & | BZt ) const

Compute the magnetic field in geocentric coordinate.

Parameters

  [in] | t | the time (fractional years).
  [in] | X | geocentric coordinate (meters).
  [in] | Y | geocentric coordinate (meters).
  [in] | Z | geocentric coordinate (meters).
  [out] | BX | the X component of the magnetic field (nT).
  [out] | BY | the Y component of the magnetic field (nT).
  [out] | BZ | the Z component of the magnetic field (nT).
  [out] | BXt | the rate of change of BX (nT/yr).
  [out] | BYt | the rate of change of BY (nT/yr).
  [out] | BZt | the rate of change of BZ (nT/yr).

Use Utility::fractionalyear to convert a date of the form yyyy-mm or yyyy-mm-dd into a fractional year.

Definition at line 190 of file MagneticModel.cpp.

## ◆ FieldComponents() [1/2]

void GeographicLib::MagneticModel::FieldComponents | ( | real | Bx,
|  | real | By,
|  | real | Bz,
|  | real & | H,
|  | real & | F,
|  | real & | D,
|  | real & | I )
| inlinestatic

Compute various quantities dependent on the magnetic field.

Parameters

  [in] | Bx | the x (easterly) component of the magnetic field (nT).
  [in] | By | the y (northerly) component of the magnetic field (nT).
  [in] | Bz | the z (vertical, up positive) component of the magnetic field (nT).
  [out] | H | the horizontal magnetic field (nT).
  [out] | F | the total magnetic field (nT).
  [out] | D | the declination of the field (degrees east of north).
  [out] | I | the inclination of the field (degrees down from horizontal).

Definition at line 263 of file MagneticModel.hpp.

References FieldComponents().

Referenced by FieldComponents(), and main().

## ◆ FieldComponents() [2/2]

void GeographicLib::MagneticModel::FieldComponents | ( | real | Bx,
|  | real | By,
|  | real | Bz,
|  | real | Bxt,
|  | real | Byt,
|  | real | Bzt,
|  | real & | H,
|  | real & | F,
|  | real & | D,
|  | real & | I,
|  | real & | Ht,
|  | real & | Ft,
|  | real & | Dt,
|  | real & | It )
| static

Compute various quantities dependent on the magnetic field and its rate of change.

Parameters

  [in] | Bx | the x (easterly) component of the magnetic field (nT).
  [in] | By | the y (northerly) component of the magnetic field (nT).
  [in] | Bz | the z (vertical, up positive) component of the magnetic field (nT).
  [in] | Bxt | the rate of change of Bx (nT/yr).
  [in] | Byt | the rate of change of By (nT/yr).
  [in] | Bzt | the rate of change of Bz (nT/yr).
  [out] | H | the horizontal magnetic field (nT).
  [out] | F | the total magnetic field (nT).
  [out] | D | the declination of the field (degrees east of north).
  [out] | I | the inclination of the field (degrees down from horizontal).
  [out] | Ht | the rate of change of H (nT/yr).
  [out] | Ft | the rate of change of F (nT/yr).
  [out] | Dt | the rate of change of D (degrees/yr).
  [out] | It | the rate of change of I (degrees/yr).

Definition at line 259 of file MagneticModel.cpp.

References GeographicLib::Math::atan2d(), GeographicLib::Math::degree(), and GeographicLib::Math::sq().

## ◆ Description()

const std::string & GeographicLib::MagneticModel::Description | ( |  | ) | const
| inline

Returns
  the description of the magnetic model, if available, from the Description file in the data file; if absent, return "NONE".

Definition at line 304 of file MagneticModel.hpp.

Referenced by main().

## ◆ DateTime()

const std::string & GeographicLib::MagneticModel::DateTime | ( |  | ) | const
| inline

Returns
  date of the model, if available, from the ReleaseDate field in the data file; if absent, return "UNKNOWN".

Definition at line 310 of file MagneticModel.hpp.

Referenced by main().

## ◆ MagneticFile()

const std::string & GeographicLib::MagneticModel::MagneticFile | ( |  | ) | const
| inline

Returns
  full file name used to load the magnetic model.

Definition at line 315 of file MagneticModel.hpp.

Referenced by main().

## ◆ MagneticModelName()

const std::string & GeographicLib::MagneticModel::MagneticModelName | ( |  | ) | const
| inline

Returns
  "name" used to load the magnetic model (from the first argument of the constructor, but this may be overridden by the model file).

Definition at line 321 of file MagneticModel.hpp.

Referenced by main().

## ◆ MagneticModelDirectory()

const std::string & GeographicLib::MagneticModel::MagneticModelDirectory | ( |  | ) | const
| inline

Returns
  directory used to load the magnetic model.

Definition at line 326 of file MagneticModel.hpp.

## ◆ MinHeight()

Math::real GeographicLib::MagneticModel::MinHeight | ( |  | ) | const
| inline

Returns
  the minimum height above the ellipsoid (in meters) for which this MagneticModel should be used.

Because the model will typically provide useful results slightly outside the range of allowed heights, no check of t argument is made by MagneticModel::operator()() or MagneticModel::Circle.

Definition at line 337 of file MagneticModel.hpp.

Referenced by main().

## ◆ MaxHeight()

Math::real GeographicLib::MagneticModel::MaxHeight | ( |  | ) | const
| inline

Returns
  the maximum height above the ellipsoid (in meters) for which this MagneticModel should be used.

Because the model will typically provide useful results slightly outside the range of allowed heights, no check of t argument is made by MagneticModel::operator()() or MagneticModel::Circle.

Definition at line 348 of file MagneticModel.hpp.

Referenced by main().

## ◆ MinTime()

Math::real GeographicLib::MagneticModel::MinTime | ( |  | ) | const
| inline

Returns
  the minimum time (in years) for which this MagneticModel should be used.

Because the model will typically provide useful results slightly outside the range of allowed times, no check of t argument is made by MagneticModel::operator()() or MagneticModel::Circle.

Definition at line 359 of file MagneticModel.hpp.

Referenced by main().

## ◆ MaxTime()

Math::real GeographicLib::MagneticModel::MaxTime | ( |  | ) | const
| inline

Returns
  the maximum time (in years) for which this MagneticModel should be used.

Because the model will typically provide useful results slightly outside the range of allowed times, no check of t argument is made by MagneticModel::operator()() or MagneticModel::Circle.

Definition at line 370 of file MagneticModel.hpp.

Referenced by main().

## ◆ EquatorialRadius()

Math::real GeographicLib::MagneticModel::EquatorialRadius | ( |  | ) | const
| inline

Returns
  a the equatorial radius of the ellipsoid (meters). This is the value of a inherited from the Geocentric object used in the constructor.

Definition at line 377 of file MagneticModel.hpp.

## ◆ Flattening()

Math::real GeographicLib::MagneticModel::Flattening | ( |  | ) | const
| inline

Returns
  f the flattening of the ellipsoid. This is the value inherited from the Geocentric object used in the constructor.

Definition at line 383 of file MagneticModel.hpp.

## ◆ Degree()

int GeographicLib::MagneticModel::Degree | ( |  | ) | const
| inline

Returns
  Nmax the maximum degree of the components of the model.

Definition at line 388 of file MagneticModel.hpp.

## ◆ Order()

int GeographicLib::MagneticModel::Order | ( |  | ) | const
| inline

Returns
  Mmax the maximum order of the components of the model.

Definition at line 393 of file MagneticModel.hpp.

## ◆ DefaultMagneticPath()

string GeographicLib::MagneticModel::DefaultMagneticPath | ( |  | ) |
| static

Returns
  the default path for magnetic model data files.

This is the value of the environment variable GEOGRAPHICLIB_MAGNETIC_PATH, if set; otherwise, it is $GEOGRAPHICLIB_DATA/magnetic if the environment variable GEOGRAPHICLIB_DATA is set; otherwise, it is a compile-time default (/usr/local/share/GeographicLib/magnetic on non-Windows systems and C:/ProgramData/GeographicLib/magnetic on Windows systems).

Definition at line 274 of file MagneticModel.cpp.

References GEOGRAPHICLIB_DATA.

Referenced by MagneticModel(), and main().

## ◆ DefaultMagneticName()

string GeographicLib::MagneticModel::DefaultMagneticName | ( |  | ) |
| static

Returns
  the default name for the magnetic model.

This is the value of the environment variable GEOGRAPHICLIB_MAGNETIC_NAME, if set; otherwise, it is "wmm2025". The MagneticModel class does not use this function; it is just provided as a convenience for a calling program when constructing a MagneticModel object.

Definition at line 287 of file MagneticModel.cpp.

References GEOGRAPHICLIB_MAGNETIC_DEFAULT_NAME.

Referenced by main().

The documentation for this class was generated from the following files:

- MagneticModel.hpp
- MagneticModel.cpp