Static Public Member Functions | Private Types | Private Member Functions | Private Attributes | Static Private Attributes | List of all members
GeographicLib::MagneticModel Class Reference

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

#include <MagneticModel.hpp>

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
 
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 MajorRadius () const
 
Math::real Flattening () const
 

Static Public Member Functions

static std::string DefaultMagneticName ()
 
static std::string DefaultMagneticPath ()
 

Private Types

typedef Math::real real
 

Private Member Functions

void Field (real t, real lat, real lon, real h, bool diffp, real &Bx, real &By, real &Bz, real &Bxt, real &Byt, real &Bzt) const
 
 MagneticModel (const MagneticModel &)
 
MagneticModeloperator= (const MagneticModel &)
 
void ReadMetadata (const std::string &name)
 

Private Attributes

real _a
 
std::string _date
 
std::string _description
 
std::string _dir
 
real _dt0
 
Geocentric _earth
 
std::string _filename
 
std::vector< std::vector< real > > _G
 
std::vector< std::vector< real > > _H
 
std::vector< SphericalHarmonic_harm
 
real _hmax
 
real _hmin
 
std::string _id
 
std::string _name
 
int _Nconstants
 
int _Nmodels
 
SphericalHarmonic::normalization _norm
 
real _t0
 
real _tmax
 
real _tmin
 

Static Private Attributes

static const int idlength_ = 8
 

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
 
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 for details of how to install the magnetic models and the data format.

See

Example of use:

// Example of using the GeographicLib::MagneticModel class
#include <iostream>
#include <exception>
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;
}
}

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

Definition at line 69 of file MagneticModel.hpp.

Member Typedef Documentation

◆ real

Definition at line 71 of file MagneticModel.hpp.

Constructor & Destructor Documentation

◆ MagneticModel() [1/2]

GeographicLib::MagneticModel::MagneticModel ( const MagneticModel )
private

◆ MagneticModel() [2/2]

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().
Exceptions
GeographicErrif the data file cannot be found, is unreadable, or is corrupt.
std::bad_allocif 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.

Definition at line 37 of file src/MagneticModel.cpp.

Member Function Documentation

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

Definition at line 212 of file src/MagneticModel.cpp.

◆ 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 249 of file MagneticModel.hpp.

◆ DefaultMagneticName()

std::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 "wmm2015". 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 261 of file src/MagneticModel.cpp.

◆ DefaultMagneticPath()

std::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 248 of file src/MagneticModel.cpp.

◆ 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 243 of file MagneticModel.hpp.

◆ Field()

void GeographicLib::MagneticModel::Field ( real  t,
real  lat,
real  lon,
real  h,
bool  diffp,
real Bx,
real By,
real Bz,
real Bxt,
real Byt,
real Bzt 
) const
private

Definition at line 173 of file src/MagneticModel.cpp.

◆ FieldComponents() [1/2]

static 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]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 202 of file MagneticModel.hpp.

◆ 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]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 233 of file src/MagneticModel.cpp.

◆ 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 322 of file MagneticModel.hpp.

◆ MagneticFile()

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

Definition at line 254 of file MagneticModel.hpp.

◆ MagneticModelDirectory()

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

Definition at line 265 of file MagneticModel.hpp.

◆ 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 260 of file MagneticModel.hpp.

◆ MajorRadius()

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

◆ 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 287 of file MagneticModel.hpp.

◆ 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 309 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 276 of file MagneticModel.hpp.

◆ 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 298 of file MagneticModel.hpp.

◆ 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]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 140 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]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 163 of file MagneticModel.hpp.

◆ operator=()

MagneticModel& GeographicLib::MagneticModel::operator= ( const MagneticModel )
private

◆ ReadMetadata()

void GeographicLib::MagneticModel::ReadMetadata ( const std::string &  name)
private

Definition at line 86 of file src/MagneticModel.cpp.

Member Data Documentation

◆ _a

real GeographicLib::MagneticModel::_a
private

Definition at line 74 of file MagneticModel.hpp.

◆ _date

std::string GeographicLib::MagneticModel::_date
private

Definition at line 73 of file MagneticModel.hpp.

◆ _description

std::string GeographicLib::MagneticModel::_description
private

Definition at line 73 of file MagneticModel.hpp.

◆ _dir

std::string GeographicLib::MagneticModel::_dir
private

Definition at line 73 of file MagneticModel.hpp.

◆ _dt0

real GeographicLib::MagneticModel::_dt0
private

Definition at line 74 of file MagneticModel.hpp.

◆ _earth

Geocentric GeographicLib::MagneticModel::_earth
private

Definition at line 77 of file MagneticModel.hpp.

◆ _filename

std::string GeographicLib::MagneticModel::_filename
private

Definition at line 73 of file MagneticModel.hpp.

◆ _G

std::vector< std::vector<real> > GeographicLib::MagneticModel::_G
private

Definition at line 78 of file MagneticModel.hpp.

◆ _H

std::vector< std::vector<real> > GeographicLib::MagneticModel::_H
private

Definition at line 79 of file MagneticModel.hpp.

◆ _harm

std::vector<SphericalHarmonic> GeographicLib::MagneticModel::_harm
private

Definition at line 80 of file MagneticModel.hpp.

◆ _hmax

real GeographicLib::MagneticModel::_hmax
private

Definition at line 74 of file MagneticModel.hpp.

◆ _hmin

real GeographicLib::MagneticModel::_hmin
private

Definition at line 74 of file MagneticModel.hpp.

◆ _id

std::string GeographicLib::MagneticModel::_id
private

Definition at line 73 of file MagneticModel.hpp.

◆ _name

std::string GeographicLib::MagneticModel::_name
private

Definition at line 73 of file MagneticModel.hpp.

◆ _Nconstants

int GeographicLib::MagneticModel::_Nconstants
private

Definition at line 75 of file MagneticModel.hpp.

◆ _Nmodels

int GeographicLib::MagneticModel::_Nmodels
private

Definition at line 75 of file MagneticModel.hpp.

◆ _norm

SphericalHarmonic::normalization GeographicLib::MagneticModel::_norm
private

Definition at line 76 of file MagneticModel.hpp.

◆ _t0

real GeographicLib::MagneticModel::_t0
private

Definition at line 74 of file MagneticModel.hpp.

◆ _tmax

real GeographicLib::MagneticModel::_tmax
private

Definition at line 74 of file MagneticModel.hpp.

◆ _tmin

real GeographicLib::MagneticModel::_tmin
private

Definition at line 74 of file MagneticModel.hpp.

◆ idlength_

const int GeographicLib::MagneticModel::idlength_ = 8
staticprivate

Definition at line 72 of file MagneticModel.hpp.


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


gtsam
Author(s):
autogenerated on Tue Jul 4 2023 02:46:12