/usr/share/doc/geographiclib/html/magnetic.html is in geographiclib-doc 1.49-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.13"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>GeographicLib: Magnetic models</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/x-mathjax-config">
MathJax.Hub.Config({
extensions: ["tex2jax.js"],
jax: ["input/TeX","output/HTML-CSS"],
});
</script><script type="text/javascript" src="/usr/share/javascript/mathjax/MathJax.js/MathJax.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">GeographicLib
 <span id="projectnumber">1.49</span>
</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.13 -->
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
$(function() {
initMenu('',false,false,'search.php','Search');
});
</script>
<div id="main-nav"></div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Magnetic models </div> </div>
</div><!--header-->
<div class="contents">
<div class="textblock"><center> Back to <a class="el" href="normalgravity.html">Normal gravity</a>. Forward to <a class="el" href="geodesic.html">Geodesics on an ellipsoid of revolution</a>. Up to <a class="el" href="index.html#contents">Contents</a>. </center><p><a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> can compute the earth's magnetic field by a magnetic model using the <a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> and <a class="el" href="classGeographicLib_1_1MagneticCircle.html" title="Geomagnetic field on a circle of latitude. ">MagneticCircle</a> classes and with the <a href="MagneticField.1.html">MagneticField</a> 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 <a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> are advised to read the <a href="https://www.ngdc.noaa.gov/IAGA/vmod/igrfhw.html">"Health
Warning"</a> this is provided with igrf11. Although the advice is specific to igrf11, many of the comments apply to all magnetic field models.</p>
<p>The supported models are</p><ul>
<li><b>wmm2010</b>, the <a href="https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml">World Magnetic Model 2010</a>, which approximates the main magnetic field for the period 2010–2015.</li>
<li><b>wmm2015</b>, the <a href="https://ngdc.noaa.gov/geomag/WMM/DoDWMM.shtml">World Magnetic Model 2015</a>, which approximates the main magnetic field for the period 2015–2020.</li>
<li><b>igrf11</b>, the <a href="https://ngdc.noaa.gov/IAGA/vmod/igrf.html">International Geomagnetic Reference Field (11th generation)</a>, which approximates the main magnetic field for the period 1900–2015.</li>
<li><b>igrf12</b>, the <a href="https://ngdc.noaa.gov/IAGA/vmod/igrf.html">International Geomagnetic Reference Field (12th generation)</a>, which approximates the main magnetic field for the period 1900–2020.</li>
<li><b>emm2010</b>, the <a href="https://ngdc.noaa.gov/geomag/EMM/index.html">Enhanced Magnetic Model 2010</a>, which approximates the main and crustal magnetic fields for the period 2010–2015.</li>
<li><b>emm2015</b>, the <a href="https://ngdc.noaa.gov/geomag/EMM/index.html">Enhanced Magnetic Model 2015</a>, which approximates the main and crustal magnetic fields for the period 2000–2020.</li>
<li><b>emm2017</b>, the <a href="https://ngdc.noaa.gov/geomag/EMM/index.html">Enhanced Magnetic Model 2017</a>, which approximates the main and crustal magnetic fields for the period 2000–2022.</li>
</ul>
<p>Go to</p><ul>
<li><a class="el" href="magnetic.html#magneticinst">Installing the magnetic field models</a></li>
<li><a class="el" href="magnetic.html#magneticformat">The format of the magnetic model files</a></li>
</ul>
<h1><a class="anchor" id="magneticinst"></a>
Installing the magnetic field models</h1>
<p>These magnetic models are available for download: </p><center> <a class="anchor" id=""></a>
<table class="doxtable">
<caption>Available magnetic models</caption>
<tr>
<th rowspan="2">name </th><th rowspan="2">max<br />
degree </th><th rowspan="2">time<br />
interval </th><th rowspan="2">size<br />
(kB) </th><th colspan="3"><center>Download Links (size, kB)</center> </th></tr>
<tr>
<th>tar file </th><th>Windows<br />
installer </th><th>zip file </th></tr>
<tr>
<td>wmm2010 </td><td><center>12</center> </td><td><center>2010–2015</center> </td><td><center>3</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2010.tar.bz2">link</a> (2)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2010.exe">link</a> (300)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2010.zip">link</a> (2)</center> </td></tr>
<tr>
<td>wmm2015 </td><td><center>12</center> </td><td><center>2015–2020</center> </td><td><center>3</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015.tar.bz2">link</a> (2)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015.exe">link</a> (300)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/wmm2015.zip">link</a> (2)</center> </td></tr>
<tr>
<td>igrf11 </td><td><center>13</center> </td><td><center>1900–2015</center> </td><td><center>25</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf11.tar.bz2">link</a> (7)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf11.exe">link</a> (310)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf11.zip">link</a> (8)</center> </td></tr>
<tr>
<td>igrf12 </td><td><center>13</center> </td><td><center>1900–2020</center> </td><td><center>26</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf12.tar.bz2">link</a> (7)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf12.exe">link</a> (310)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/igrf12.zip">link</a> (8)</center> </td></tr>
<tr>
<td>emm2010 </td><td><center>739</center> </td><td><center>2010–2015</center> </td><td><center>4400</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2010.tar.bz2">link</a> (3700)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2010.exe">link</a> (3000)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2010.zip">link</a> (4100)</center> </td></tr>
<tr>
<td>emm2015 </td><td><center>729</center> </td><td><center>2000–2020</center> </td><td><center>4300</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2015.tar.bz2">link</a> (660)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2015.exe">link</a> (990)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2015.zip">link</a> (1030)</center> </td></tr>
<tr>
<td>emm2017 </td><td><center>790</center> </td><td><center>2000–2022</center> </td><td><center>5050</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2017.tar.bz2">link</a> (1740)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2017.exe">link</a> (1700)</center> </td><td><center> <a href="https://sourceforge.net/projects/geographiclib/files/magnetic-distrib/emm2017.zip">link</a> (2750)</center> </td></tr>
</table>
</center><p> The "size" column is the size of the uncompressed data.</p>
<p>For Linux and Unix systems, <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> 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 </p><pre class="fragment"> geographiclib-get-magnetic all # install wmm2010, wmm2015, igrf11, igrf12, emm2010, emm2015, emm2017
geographiclib-get-magnetic -h # for help
</pre><p> 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.</p>
<p>Windows users should download and run the Windows installers. These will prompt for an installation directory with the default being </p><pre class="fragment"> C:/ProgramData/GeographicLib
</pre><p> (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.)</p>
<p>Otherwise download <em>either</em> the tar.bz2 file <em>or</em> the zip file (they have the same contents). To unpack these, run, for example </p><pre class="fragment"> mkdir -p /usr/local/share/GeographicLib
tar xofjC wmm2015.tar.bz2 /usr/local/share/GeographicLib
tar xofjC emm2010.tar.bz2 /usr/local/share/GeographicLib
etc.
</pre><p> and, again, the data will be placed in the "magnetic" subdirectory.</p>
<p>However you install the magnetic models, all the datasets should be installed in the same directory. <a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> and <a href="MagneticField.1.html">MagneticField</a> uses a compile time default to locate the datasets. This is</p><ul>
<li>/usr/local/share/GeographicLib/magnetic, for non-Windows systems</li>
<li>C:/ProgramData/GeographicLib/magnetic, for Windows systems</li>
</ul>
<p>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 <a class="el" href="classGeographicLib_1_1MagneticModel.html#a469db97d257876c1abafa3da3c5f0f7e">MagneticModel::DefaultMagneticPath()</a> for details. Finally, the path may be set using the optional second argument to the <a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> constructor or with the "-d" flag to <a href="MagneticField.1.html">MagneticField</a>. Supplying the "-h" flag to <a href="MagneticField.1.html">MagneticField</a> 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.</p>
<h1><a class="anchor" id="magneticformat"></a>
The format of the magnetic model files</h1>
<p>The constructor for <a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> 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.</p>
<p>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").</p>
<p>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.</p>
<p><a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> only pays attention to the following keywords</p><ul>
<li>keywords that affect the field calculation, namely:<ul>
<li><b>Radius</b> (required), the normalizing radius of the model in meters.</li>
<li><b>NumModels</b> (default 1), the number of models. WMM2015 consists of a single model giving the magnetic field and its time variation at 2015. 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.</li>
<li><b>NumConstants</b> (default 0), the number of time-independent terms; this can be 0 or 1. This keyword was introduced in format version 2 (<a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> 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.</li>
<li><b>Epoch</b> (required), the time origin (in fractional years) for the first model.</li>
<li><b>DeltaEpoch</b> (default 1), the interval between models in years (only relevant for NumModels > 1).</li>
<li><b>Normalization</b> (default schmidt), the normalization used for the associated Legendre functions (schmidt or full).</li>
<li><b>ID</b> (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).</li>
</ul>
</li>
<li>keywords that store data that the user can query:<ul>
<li><b>Name</b>, the name of the model.</li>
<li><b>Description</b>, a more descriptive name of the model.</li>
<li><b>ReleaseDate</b>, when the model was created.</li>
<li><b>MinTime</b>, the minimum date at which the model should be used.</li>
<li><b>MaxTime</b>, the maximum date at which the model should be used.</li>
<li><b>MinHeight</b>, the minimum height above the ellipsoid for which the model should be used.</li>
<li><b>MaxHeight</b>, the maximum height above the ellipsoid for which the model should be used.</li>
</ul>
<a class="el" href="classGeographicLib_1_1MagneticModel.html" title="Model of the earth's magnetic field. ">MagneticModel</a> does not enforce the restrictions implied by last four quantities. However, <a href="MagneticField.1.html">MagneticField</a> issues a warning if these limits are exceeded.</li>
<li>keywords that are examined to verify that their values are valid:<ul>
<li><b>Type</b> (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.</li>
<li><b>ByteOrder</b> (default little), the order of bytes in the .wmm.cof file. Only little endian is supported at present.</li>
</ul>
</li>
</ul>
<p>Other keywords are ignored.</p>
<p>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 + <em>i</em> * DeltaEpoch for 0 ≤ <em>i</em> < 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:</p><ul>
<li><em>N</em>, the maximum degree of the sum stored as a 4-byte signed integer. This must satisfy <em>N</em> ≥ −1.</li>
<li><em>M</em>, the maximum order of the sum stored as a 4-byte signed integer. This must satisfy <em>N</em> ≥ <em>M</em> ≥ −1.</li>
<li><em>C</em><sub><em>nm</em></sub>, the coefficients of the cosine coefficients of the sum in column (i.e., <em>m</em>) major order. There are (<em>M</em> + 1) (2<em>N</em> − <em>M</em> + 2) / 2 elements which are stored as IEEE doubles (8 bytes). For example for <em>N</em> = <em>M</em> = 3, there are 10 coefficients arranged as <em>C</em><sub>00</sub>, <em>C</em><sub>10</sub>, <em>C</em><sub>20</sub>, <em>C</em><sub>30</sub>, <em>C</em><sub>11</sub>, <em>C</em><sub>21</sub>, <em>C</em><sub>31</sub>, <em>C</em><sub>22</sub>, <em>C</em><sub>32</sub>, <em>C</em><sub>33</sub>.</li>
<li><em>S</em><sub><em>nm</em></sub>, the coefficients of the sine coefficients of the sum in column (i.e., <em>m</em>) major order starting at <em>m</em> = 1. There are <em>M</em> (2<em>N</em> − <em>M</em> + 1) / 2 elements which are stored as IEEE doubles (8 bytes). For example for <em>N</em> = <em>M</em> = 3, there are 6 coefficients arranged as <em>S</em><sub>11</sub>, <em>S</em><sub>21</sub>, <em>S</em><sub>31</sub>, <em>S</em><sub>22</sub>, <em>S</em><sub>32</sub>, <em>S</em><sub>33</sub>.</li>
</ul>
<p>Although the coefficient file is in little endian order, <a class="el" href="namespaceGeographicLib.html" title="Namespace for GeographicLib. ">GeographicLib</a> can read it on big endian machines. It can only be read on machines which store doubles in IEEE format.</p>
<p>As an illustration, here is igrf11.wmm: </p><pre class="fragment">WMMF-1
# A World Magnetic Model (Format 1) file. For documentation on the
# format of this file see
# https://geographiclib.sourceforge.io/html/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
</pre><center> Back to <a class="el" href="normalgravity.html">Normal gravity</a>. Forward to <a class="el" href="geodesic.html">Geodesics on an ellipsoid of revolution</a>. Up to <a class="el" href="index.html#contents">Contents</a>. </center> </div></div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated by  <a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/>
</a> 1.8.13
</small></address>
</body>
</html>
|