# 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

example

``````[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

collapse all

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 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

collapse all

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

Data Types: `double`

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`

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

Data Types: `double`

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 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

collapse all

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). The components of this vector are in the north-east-down (NED) reference frame.

Data Types: `double`

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

Data Types: `double`

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

Data Types: `double`

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

Data Types: `double`

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

Data Types: `double`

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`

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

Data Types: `double`

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

Data Types: `double`

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

Data Types: `double`

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, IGRF Health Warning, Errors, and Limitations.

## 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. IGRF Health Warning, Errors, and Limitations.

## Version History

Introduced in R2015b