GeographicLib  1.21
Static Public Member Functions
GeographicLib::MagneticModel Class Reference

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

#include <GeographicLib/MagneticModel.hpp>

List of all members.

Public Member Functions

Setting up the magnetic model
 MagneticModel (const std::string &name, const std::string &path="", const Geocentric &earth=Geocentric::WGS84)
Inspector functions
const std::string & Description () const throw ()
const std::string & DateTime () const throw ()
const std::string & MagneticFile () const throw ()
const std::string & MagneticModelName () const throw ()
const std::string & MagneticModelDirectory () const throw ()
Math::real MinHeight () const throw ()
Math::real MaxHeight () const throw ()
Math::real MinTime () const throw ()
Math::real MaxTime () const throw ()
Math::real MajorRadius () const throw ()
Math::real Flattening () const throw ()

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 throw ()
void operator() (real t, real lat, real lon, real h, real &Bx, real &By, real &Bz, real &Bxt, real &Byt, real &Bzt) const throw ()
MagneticCircle Circle (real t, real lat, real h) const
static void FieldComponents (real Bx, real By, real Bz, real &H, real &F, real &D, real &I) throw ()
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) throw ()

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 model and the data format.

See

Example of use:

// Example of using the GeographicLib::MagneticModel class
// $Id: ab27b155755e540d29e5e6bf550df8cdb00c74ba $

#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;
  }
  return 0;
}

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


Constructor & Destructor Documentation

GeographicLib::MagneticModel::MagneticModel ( const std::string &  name,
const std::string &  path = "",
const Geocentric earth = Geocentric::WGS84 
) [explicit]

Construct a magnetic model.

Parameters:
[in]namethe name of the model.
[in]path(optional) directory for data file.
[in]earth(optional) Geocentric object for converting coordinates; default Geocentric::WGS84.

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 may throw an exception because the file does not exist, is unreadable, or is corrupt.

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 specify an ellipsoid to allow geodetic coordinates to the transformed into the spherical coordinates used in the spherical harmonic sum.

Definition at line 44 of file MagneticModel.cpp.

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


Member Function Documentation

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

Evaluate the components of the geomagnetic field.

Parameters:
[in]tthe time (years).
[in]latlatitude of the point (degrees).
[in]lonlongitude of the point (degrees).
[in]hthe height of the point above the ellipsoid (meters).
[out]Bxthe easterly component of the magnetic field (nanotesla).
[out]Bythe northerly component of the magnetic field (nanotesla).
[out]Bzthe vertical (up) component of the magnetic field (nanotesla).

Definition at line 131 of file MagneticModel.hpp.

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 throw () [inline]

Evaluate the components of the geomagnetic field and their time derivatives

Parameters:
[in]tthe time (years).
[in]latlatitude of the point (degrees).
[in]lonlongitude of the point (degrees).
[in]hthe height of the point above the ellipsoid (meters).
[out]Bxthe easterly component of the magnetic field (nanotesla).
[out]Bythe northerly component of the magnetic field (nanotesla).
[out]Bzthe vertical (up) component of the magnetic field (nanotesla).
[out]Bxtthe rate of change of Bx (nT/yr).
[out]Bytthe rate of change of By (nT/yr).
[out]Bztthe rate of change of Bz (nT/yr).

Definition at line 153 of file MagneticModel.hpp.

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]tthe time (years).
[in]latlatitude of the point (degrees).
[in]hthe height of the point above the ellipsoid (meters).
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.

Definition at line 207 of file MagneticModel.cpp.

Referenced by main().

static void GeographicLib::MagneticModel::FieldComponents ( real  Bx,
real  By,
real  Bz,
real &  H,
real &  F,
real &  D,
real &  I 
) throw () [inline, static]

Compute various quantities dependent on the magnetic field.

Parameters:
[in]Bxthe x (easterly) component of the magnetic field (nT).
[in]Bythe y (northerly) component of the magnetic field (nT).
[in]Bzthe z (vertical, up positive) component of the magnetic field (nT).
[out]Hthe horizontal magnetic field (nT).
[out]Fthe total magnetic field (nT).
[out]Dthe declination of the field (degrees east of north).
[out]Ithe inclination of the field (degrees down from horizontal).

Definition at line 190 of file MagneticModel.hpp.

Referenced by main().

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 
) throw () [static]

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

Parameters:
[in]Bxthe x (easterly) component of the magnetic field (nT).
[in]Bythe y (northerly) component of the magnetic field (nT).
[in]Bzthe z (vertical, up positive) component of the magnetic field (nT).
[in]Bxtthe rate of change of Bx (nT/yr).
[in]Bytthe rate of change of By (nT/yr).
[in]Bztthe rate of change of Bz (nT/yr).
[out]Hthe horizontal magnetic field (nT).
[out]Fthe total magnetic field (nT).
[out]Dthe declination of the field (degrees east of north).
[out]Ithe inclination of the field (degrees down from horizontal).
[out]Htthe rate of change of H (nT/yr).
[out]Ftthe rate of change of F (nT/yr).
[out]Dtthe rate of change of D (degrees/yr).
[out]Itthe rate of change of I (degrees/yr).

Definition at line 222 of file MagneticModel.cpp.

References GeographicLib::Math::hypot(), and GeographicLib::Math::sq().

const std::string& GeographicLib::MagneticModel::Description ( ) const throw () [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 231 of file MagneticModel.hpp.

Referenced by main().

const std::string& GeographicLib::MagneticModel::DateTime ( ) const throw () [inline]
Returns:
date of the model, if available, from the ReleaseDate field in the data file; if absent, return "UNKNOWN".

Definition at line 237 of file MagneticModel.hpp.

Referenced by main().

const std::string& GeographicLib::MagneticModel::MagneticFile ( ) const throw () [inline]
Returns:
full file name used to load the magnetic model.

Definition at line 242 of file MagneticModel.hpp.

Referenced by main().

const std::string& GeographicLib::MagneticModel::MagneticModelName ( ) const throw () [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 248 of file MagneticModel.hpp.

Referenced by main().

const std::string& GeographicLib::MagneticModel::MagneticModelDirectory ( ) const throw () [inline]
Returns:
directory used to load the magnetic model.

Definition at line 253 of file MagneticModel.hpp.

Math::real GeographicLib::MagneticModel::MinHeight ( ) const throw () [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 264 of file MagneticModel.hpp.

Referenced by main().

Math::real GeographicLib::MagneticModel::MaxHeight ( ) const throw () [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 275 of file MagneticModel.hpp.

Referenced by main().

Math::real GeographicLib::MagneticModel::MinTime ( ) const throw () [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 286 of file MagneticModel.hpp.

Referenced by main().

Math::real GeographicLib::MagneticModel::MaxTime ( ) const throw () [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 297 of file MagneticModel.hpp.

Referenced by main().

Math::real GeographicLib::MagneticModel::MajorRadius ( ) const throw () [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 304 of file MagneticModel.hpp.

Math::real GeographicLib::MagneticModel::Flattening ( ) const throw () [inline]
Returns:
f the flattening of the ellipsoid. This is the value inherited from the Geocentric object used in the constructor.

Definition at line 310 of file MagneticModel.hpp.

std::string GeographicLib::MagneticModel::DefaultMagneticPath ( ) [static]
Returns:
the default path for magnetic model data files.

This is the value of the environment variable 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:/Documents and Settings/All Users/Application Data/GeographicLib/magnetic on Windows systems).

Definition at line 237 of file MagneticModel.cpp.

References GEOGRAPHICLIB_DATA.

Referenced by main(), and MagneticModel().

std::string GeographicLib::MagneticModel::DefaultMagneticName ( ) [static]
Returns:
the default name for the magnetic model.

This is the value of the environment variable MAGNETIC_NAME, if set, otherwise, it is "wmm2010". 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 250 of file MagneticModel.cpp.

References MAGNETIC_DEFAULT_NAME.

Referenced by main().


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