igrfmagm

Calculate Earth magnetic field and secular variation using International Geomagnetic Reference Field

Syntax

[XYZ,H,D,I,F,DXDYDZ,DH,DD,DI,DF] = igrfmagm(height,latitude,longitude,decimalYear)

[XYZ,H,D,I,F,DXDYDZ,DH,DD,DI,DF] = igrfmagm(height,latitude,longitude,decimalYear,generation)

Description

[XYZ,H,D,I,F,DXDYDZ,DH,DD,DI,DF] = igrfmagm(height,latitude,longitude,decimalYear) calculates the Earth magnetic field and the secular variation at a specific location and time using the International Geomagnetic Reference Field generation 13 (IGRF-13).

[XYZ,H,D,I,F,DXDYDZ,DH,DD,DI,DF] = igrfmagm(height,latitude,longitude,decimalYear,generation) optionally uses different generations of the International Geomagnetic Reference Field (IGRF-13, IGRF-12, and IGRF-11).

Examples

Calculate the Magnetic Model

Calculate the magnetic model 1000 meters over Natick, Massachusetts on July 4, 2015 using IGRF-13.

[XYZ,H,D,I,F] ...
= igrfmagm(1000,42.283,-71.35,decyear(2015,7,4),13)

XYZ =
   1.0e+04 *

    1.9471   -0.5086    4.8177

H =
   2.0124e+04

D =
  -14.6381

I =
   67.3295

F =
   5.2212e+04

Calculate the Magnetic Model with Matrix inputs

Calculate the magnetic model at 0 and 10000 km over Lawrence, Kansas on May 15, 2018 using IGRF-13.

h = [0,10000000]
lat = [38.957114,38.957114]
lon = [-95.253997,-95.253997]
dyear = [decyear(2018,5,14), decyear(2018,5,14)]
[XYZ,H,D,I,F] = igrfmagm(h,lat,lon,dyear,13)

h =
           0    10000000

lat =
   38.9571   38.9571

lon =
  -95.2540  -95.2540

dyear =
   1.0e+03 *
    2.0184    2.0184

XYZ =
   1.0e+04 *

    2.0655    0.0783    4.7990
    0.1192    0.0046    0.2571

H =
   1.0e+04 *

    2.0670
    0.1193

D =
    2.1714
    2.1968

I =
   66.6981
   65.1016

F =
   1.0e+04 *

    5.2252
    0.2834

Input Arguments

height — Distance

matrix | scalar | vector

Distance from the surface of the Earth, specified as a matrix, scalar, or vector, in meters.

Data Types: double

latitude — Geodetic latitude

scalar | vector | matrix

Geodetic latitude, specified as a matrix, scalar, or vector, in degrees. North latitude is positive and south latitude is negative.

This function accepts latitude values greater than 90 and less than -90.

Data Types: double

longitude — Geodetic longitude

matrix | scalar | vector

Geodetic longitude specified as a matrix, scalar, or vector, in degrees. East longitude is positive and west longitude is negative. This function accepts ranges greater than 180 and less than -180.

Data Types: double

decimalYear — Year

matrix | scalar | vector

Year, in decimal format, specified as a matrix. This value can have any fraction of the year that has already passed.

Data Types: double

generation — Generation version of International Geomagnetic Reference Field

13 (default) | 12 | 11 | scalar numeric

Generation version of the International Geomagnetic Reference Field, specified as 13, 12, or 11.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | char | string

Output Arguments

XYZ — Magnetic field vector

vector | matrix

Magnetic field vector, in nanotesla (nT), returned as a vector or matrix the same size as the input matrix with an additional dimension, the last dimension. The last dimension of the matrix is of size 3, specifying the X, Y, and Z components of the magnetic field. Z is the vertical component (+ve down).

Data Types: double

H — Horizontal intensity

scalar | vector | matrix

Horizontal intensity, returned as a scalar, vector, or matrix, in nanotesla (nT), the same size as the input matrix.

Data Types: double

D — Declination

scalar | vector | matrix

Declination, returned as a scalar, in degrees (+ve east), the same size as the input matrix.

Data Types: double

I — Inclination

scalar | vector | matrix

Inclination, returned as a scalar, in degrees (+ve down), the same size as the input matrix.

Data Types: double

F — Total intensity

scalar | vector | matrix

Total intensity, returned as a scalar, in nanotesla (nT), the same size as the input matrix.

Data Types: double

DXDYDZ — Secular variation in magnetic field vector

vector | matrix

Secular variation in magnetic field vector, returned as a vector or matrix, in nT/year, the same size ans the input matrix with an additional dimension, the last dimension. The last dimension of the matrix is of size 3, specifying the X, Y, and Z components of the magnetic field. Z is the vertical component (+ve down).

Data Types: double

DH — Secular variation in horizontal intensity

scalar | vector | matrix

Secular variation in horizontal intensity, in nT/year, returned as a scalar, the same size as the input matrix.

Data Types: double

DD — Secular variation in declination

scalar | vector | matrix

Secular variation in declination, in minutes/year (+ve east), returned as a scalar, the same size as the input matrix.

Data Types: double

DI — Secular variation in inclination

scalar | vector | matrix

Secular variation in inclination, in minutes/year (+ve down), returned as a scalar, the same size as the input matrix.

Data Types: double

DF — Secular variation in total intensity

scalar | vector | matrix

Secular variation in total intensity, in nT/year, returned as a scalar, the same size as the input matrix.

Data Types: double

Limitation

• This function is valid for these year ranges:

  • IGRF-13 model — 1900 and 2025

  • IGRF-12 model — 1900 and 2020

  • IGRF-11 model — 1900 and 2015

• This function is valid between the heights of -1000 m and 5.6 Earth radii (35,​717,​567.​2 m).

• The height, latitude, longitude, and decimalYear arguments must all be the same size (matrix, scalar, and so forth).

This function has the limitations of the International Geomagnetic Reference Field (IGRF). For more information, see the IGRF website, https://www.ngdc.noaa.gov/IAGA/vmod/igrfhw.html.

References

[1] Blakely, R. J. Potential Theory in Gravity & Magnetic Applications. Cambridge, UK: Cambridge University Press, 1996.

[2] Lowes, F. J. “The International Geomagnetic Reference Field: A 'Health' Warning.” January, 2010. https://www.ngdc.noaa.gov/IAGA/vmod/igrfhw.html.