GeographicLib 2.1.2
Magnetic models
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 igrf11. Although the advice is specific to igrf11, many of the comments apply to all magnetic field models.

The supported models are

Go to

Installing the magnetic field models

These magnetic models are available for download:

Available magnetic models
name max
degree 		time
interval 		size
(kB)
Download Links (size, kB)
tar file Windows
installer 		zip file
wmm2010
12
2010–2015
3
link (2)
link (300)
link (2)
wmm2015
12
2015–2020
3
link (2)
link (300)
link (2)
wmm2015v2
12
2015–2020
3
link (2)
link (300)
link (2)
wmm2020
12
2020–2025
3
link (2)
link (1390)
link (2)
igrf11
13
1900–2015
25
link (7)
link (310)
link (8)
igrf12
13
1900–2020
26
link (7)
link (310)
link (8)
igrf13
13
1900–2025
28
link (7)
link (1420)
link (8)
emm2010
739
2010–2015
4400
link (3700)
link (3000)
link (4100)
emm2015
729
2000–2020
4300
link (660)
link (990)
link (1030)
emm2017
790
2000–2022
5050
link (1740)
link (1700)
link (2750)

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 wmm2020.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 sets of spherical harmonic coefficients. The first NumModels of these model the magnetic field at Epoch + i * DeltaEpoch for 0 ≤ i < NumModels. The last set of coefficients model the rate of change of the magnetic field at Epoch + (NumModels − 1) * DeltaEpoch. 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.
  • Cnm, the coefficients of the cosine coefficients of the sum in column (i.e., m) major order. There are (M + 1) (2N − M + 2) / 2 elements which are stored as IEEE doubles (8 bytes). For example for N = M = 3, there are 10 coefficients arranged as C00, C10, C20, C30, C11, C21, C31, C22, C32, C33.
  • Snm, the coefficients of the sine coefficients of the sum in column (i.e., m) major order starting at m = 1. There are M (2N − M + 1) / 2 elements which are stored as IEEE doubles (8 bytes). For example for N = M = 3, there are 6 coefficients arranged as S11, S21, S31, S22, S32, S33.

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.