GeographicLib: Magnetic models (original) (raw)

Back to Normal gravity. Forward to Geodesics on an ellipsoid of revolution. Up to Contents.

GeographicLib can compute the earth's magnetic field by a magnetic model using the MagneticModel and MagneticCircle classes and with the MagneticField utility. These models expand the internal magnetic potential of the earth as sum of spherical harmonics. They neglect magnetic fields due to the ionosphere, the magnetosphere, nearby magnetized materials, electric machinery, etc. Users of MagneticModel are advised to read the "Health Warning" this is provided with igrf. Although the advice is specific to the igrf models, many of the comments apply to all magnetic field models.

The supported models are

• wmm2010, the World Magnetic Model 2010, which approximates the main magnetic field for the period 2010–2015.
• wmm2015v2, the World Magnetic Model 2015, which approximates the main magnetic field for the period 2015–2020.
• wmm2015, a deprecated version of wmm2015v2.
• wmm2020, the World Magnetic Model 2020, which approximates the main magnetic field for the period 2020–2025.
• wmm2025, the World Magnetic Model 2025, which approximates the main magnetic field for the period 2025–2030.
• wmmhr2025, the World Magnetic Model High Resolution 2025, a high resolution version of wmm2025.
• igrf11, the International Geomagnetic Reference Field (11th generation), which approximates the main magnetic field for the period 1900–2015.
• igrf12, the International Geomagnetic Reference Field (12th generation), which approximates the main magnetic field for the period 1900–2020.
• igrf13, the International Geomagnetic Reference Field (13th generation), which approximates the main magnetic field for the period 1900–2025.
• igrf14, the International Geomagnetic Reference Field (14th generation), which approximates the main magnetic field for the period 1900–2030.
• emm2010, the Enhanced Magnetic Model 2010, which approximates the main and crustal magnetic fields for the period 2010–2015.
• emm2015, the Enhanced Magnetic Model 2015, which approximates the main and crustal magnetic fields for the period 2000–2020.
• emm2017, the Enhanced Magnetic Model 2017, which approximates the main and crustal magnetic fields for the period 2000–2022.

Go to

• Installing the magnetic field models
• The format of the magnetic model files

Installing the magnetic field models

These magnetic models are available for download from this directoy https://sourceforge.net/projects/geographiclib/files/magnetic-distrib

Available magnetic models

The "size" column is the size of the uncompressed data. N.B., the wmm2015 model is deprecated; use wmm2015v2 instead.

For Linux and Unix systems, GeographicLib provides a shell script geographiclib-get-magnetic (typically installed in /usr/local/sbin) which automates the process of downloading and installing the magnetic models. For example

geographiclib-get-magnetic all # install all available models geographiclib-get-magnetic -h # for help

This script should be run as a user with write access to the installation directory, which is typically /usr/local/share/GeographicLib (this can be overridden with the -p flag), and the data will then be placed in the "magnetic" subdirectory.

Windows users should download and run the Windows installers. These will prompt for an installation directory with the default being

C:/ProgramData/GeographicLib

(which you probably should not change) and the data is installed in the "magnetic" sub-directory. (The second directory name is an alternate name that Windows 7 uses for the "Application Data" directory.)

Otherwise download either the tar.bz2 file or the zip file (they have the same contents). To unpack these, run, for example

mkdir -p /usr/local/share/GeographicLib tar xofjC wmm2025.tar.bz2 /usr/local/share/GeographicLib tar xofjC emm2010.tar.bz2 /usr/local/share/GeographicLib etc.

and, again, the data will be placed in the "magnetic" subdirectory.

However you install the magnetic models, all the datasets should be installed in the same directory. MagneticModel and MagneticField uses a compile time default to locate the datasets. This is

• /usr/local/share/GeographicLib/magnetic, for non-Windows systems
• C:/ProgramData/GeographicLib/magnetic, for Windows systems

consistent with the examples above. This may be overridden at run-time by defining the GEOGRAPHICLIB_MAGNETIC_PATH or the GEOGRAPHIC_DATA environment variables; see MagneticModel::DefaultMagneticPath() for details. Finally, the path may be set using the optional second argument to the MagneticModel constructor or with the "-d" flag to MagneticField. Supplying the "-h" flag to MagneticField reports the default path for magnetic models for that utility. The "-v" flag causes MagneticField to report the full path name of the data file it uses.

The format of the magnetic model files

The constructor for MagneticModel reads a file called NAME.wmm which specifies various properties for the magnetic model. It then opens a binary file NAME.wmm.cof to obtain the coefficients of the spherical harmonic sum.

The first line of the .wmm file must consist of "WMMF-v" where WMMF stands for "World Magnetic Model Format" and v is the version number of the format (currently "2").

The rest of the file is read a line at a time. A # character and everything after it are discarded. If the result is just white space it is discarded. The remaining lines are of the form "KEY WHITESPACE VALUE". In general, the KEY and the VALUE are case-sensitive.

MagneticModel only pays attention to the following keywords

• keywords that affect the field calculation, namely:
  • Radius (required), the normalizing radius of the model in meters.
  • NumModels (default 1), the number of models. WMM2020 consists of a single model giving the magnetic field and its time variation at 2020. IGRF12 consists of 24 models for 1900 thru 2015 at 5 year intervals. The time variation is given only for the last model to allow extrapolation beyond 2015. For dates prior to 2015, linear interpolation is used.
  • NumConstants (default 0), the number of time-independent terms; this can be 0 or 1. This keyword was introduced in format version 2 (GeographicLib version 1.43) to support the EMM2015 and later models. This model includes long wavelength time-varying components of degree 15. This is supplemented by a short wavelength time-independent component with much higher degree.
  • Epoch (required), the time origin (in fractional years) for the first model.
  • DeltaEpoch (default 1), the interval between models in years (only relevant for NumModels > 1).
  • Normalization (default schmidt), the normalization used for the associated Legendre functions (schmidt or full).
  • ID (required), 8 printable characters which serve as a signature for the .wmm.cof file (they must appear as the first 8 bytes of this file).
• keywords that store data that the user can query:
  • Name, the name of the model.
  • Description, a more descriptive name of the model.
  • ReleaseDate, when the model was created.
  • MinTime, the minimum date at which the model should be used.
  • MaxTime, the maximum date at which the model should be used.
  • MinHeight, the minimum height above the ellipsoid for which the model should be used.
  • MaxHeight, the maximum height above the ellipsoid for which the model should be used.
    MagneticModel does not enforce the restrictions implied by last four quantities. However, MagneticField issues a warning if these limits are exceeded.
• keywords that are examined to verify that their values are valid:
  • Type (default linear), the type of the model. "linear" means that the time variation is piece-wise linear (either using interpolation between the field at two dates or using the field and its first derivative with respect to time). This is the only type of model supported at present.
  • ByteOrder (default little), the order of bytes in the .wmm.cof file. Only little endian is supported at present.

Other keywords are ignored.

The coefficient file NAME.wmm.cof is a binary file in little endian order. The first 8 bytes of this file must match the ID given in

NAME.wmm. This is followed by NumModels + 1 + NumConstants sets of spherical harmonic coefficients. The first NumModels of these model the magnetic field at Epoch + i * DeltaEpoch for 0 ≤ i < NumModels. The next set of coefficients model the rate of change of the magnetic field at Epoch + (NumModels − 1) * DeltaEpoch. If NumConstants > 0, the last set of coefficients model the constant short wavelength contributions to the magnetic field.

The format for each set of coefficients is:

• N, the maximum degree of the sum stored as a 4-byte signed integer. This must satisfy N ≥ −1.
• M, the maximum order of the sum stored as a 4-byte signed integer. This must satisfy N ≥ M ≥ −1.
• C nm, the coefficients of the cosine coefficients of the sum in column (i.e., m) major order. There are (M + 1) (2_N_ − M + 2) / 2 elements which are stored as IEEE doubles (8 bytes). For example for N = M = 3, there are 10 coefficients arranged as _C_00, _C_10, _C_20, _C_30, _C_11, _C_21, _C_31, _C_22, _C_32, _C_33.
• S nm, the coefficients of the sine coefficients of the sum in column (i.e., m) major order starting at m = 1. There are M (2_N_ − M + 1) / 2 elements which are stored as IEEE doubles (8 bytes). For example for N = M = 3, there are 6 coefficients arranged as _S_11, _S_21, _S_31, _S_22, _S_32, _S_33.

Although the coefficient file is in little endian order, GeographicLib can read it on big endian machines. It can only be read on machines which store doubles in IEEE format.

As an illustration, here is igrf11.wmm:

WMMF-1

A World Magnetic Model (Format 1) file. For documentation on the

format of this file see

https://geographiclib.sourceforge.io/C++/doc/magnetic.html#magneticformat

Name igrf11 Description International Geomagnetic Reference Field 11th Generation URL https://ngdc.noaa.gov/IAGA/vmod/igrf.html Publisher National Oceanic and Atmospheric Administration ReleaseDate 2009-12-15 DataCutOff 2009-10-01 ConversionDate 2011-11-04 DataVersion 1 Radius 6371200 NumModels 23 Epoch 1900 DeltaEpoch 5 MinTime 1900 MaxTime 2015 MinHeight -1000 MaxHeight 600000

The coefficients are stored in a file obtained by appending ".cof" to

the name of this file. The coefficients were obtained from IGRF11.COF

in the geomag70 distribution.

ID IGRF11-A

Back to Normal gravity. Forward to Geodesics on an ellipsoid of revolution. Up to Contents.