geoMag.TSAGeoMag

public class TSAGeoMag extends Object

Last updated on May 26, 2015

NOTE: Comment out the logger references, and put back in the System.out.println statements if not using log4j in your application. Checks are not made on the method inputs to ensure they are within a valid range.

Verified by a JUnit test using the test values distributed with the 2015 update.

This is a class to generate the magnetic declination, magnetic field strength and inclination for any point on the earth. The true bearing = magnetic bearing + declination. This class is adapted from an Applet from the NOAA National Data Center at http://www.ngdc.noaa.gov/seg/segd.shtml. None of the calculations were changed. This class requires an input file named WMM.COF, which must be in the same directory that the application is run from.
NOTE: If the WMM.COF file is missing, the internal fit coefficients for 2015 will be used. Using the correct date, the declination is accurate to about 0.5 degrees.

This is the LANL D-3 version of the GeoMagnetic calculator from the NOAA National Data Center at http://www.ngdc.noaa.gov/seg/segd.shtml.

Adapted by John St. Ledger, Los Alamos National Laboratory June 25, 1999

Version 2 Comments: The world magnetic model is updated every 5 years. The data for 2000 uses the same algorithm to calculate the magnetic field variables. The only change is in the spherical harmonic coefficients in the input file. The input file has been renamed to WMM.COF. Once again, the date was fixed. This time to January 1, 2001. Also, a deprecated constructor for StreamTokenizer was replaced, and the error messages in the catch clause were changed. Methods to get the field strength and inclination were added.

Found out some interesting information about the altitude. The altitude entered for the calculations is the height above the WGS84 spheroid, not height MSL. Using MSL height means that the altitude could be in error by as much as 200 meters. This should not be significant for our applications.

NOTE: This class is not thread safe.

Version:

3.0 January 19, 2000

Updated for 2000 data.

, 4.0 March 1, 2002

Changed so that if data file doesn't exist, it uses an internal version of the coefficients from the 2000 update.

, 5.0 June 1, 2005

Changed so that if data file doesn't exist, it uses an internal version of the coefficients from the 2005 update. Previously, only calculated the declination at sea level for one date. Now can return all of the variables as a function of date and altitude. Original version used float variables. All changed to type double. Does not check if the input date is within the valid block.

, 5.1 June 20, 2005

Fixed a bug discovered by Alvin Liem. In my zeal to clean up compiler comments I deleted some double casts for integers that resulted in an integer division being made when double division was needed.

, 5.2 June 1, 2006

Took out the input error variable, which was no longer being used. Now verified with a JUnit test. Deleted the main() method which printed a table of test values.

, 5.3 January 28, 2009

Fixed JavaDoc comments, and replaced the StringTokenizer uses with String.split()., 5.4 January 5, 2010

Updated for 2010 data. The new 2010 WMM.COF values are now used. Also, added log4j support.

, 5.5 October 10, 2012

Made minor changes. The default date used when the caller does not input a date is now the epoch + 2.5 years, rather than being a fixed value. This means that the default date is automatically updated if a new WMM.COF file is used. Also, now have a method to return the date as a decimal year, given the Gregorian Calendar date.

, 5.6 January 15, 2015

Updated the internal coefficients to the 2015 values. Passes the new JUnit tests.

, 5.7 May 26, 2015

Martin Frassl discovered a major bug in the code. I thought that X was in the East direction. It is not. The X axis is in the North direction. This is now fixed so that getNorthIntensity and getEastIntensity return the correct values. Thank you Martin!. The X, Y, and Z axes are defined in table 1 of the reference:

Chulliat, A., S. Macmillan, P. Alken, C. Beggan, M. Nair, B. Hamilton, A. Woods, V. Ridley, S. Maus and A. Thomson, 2015, The US/UK World Magnetic Model for 2015-2020: Technical Report, National Geophysical Data Center, NOAA. doi: 10.7289/V5TB14V7

JOHN M. QUINN, DAVID J. KERRIDGE AND DAVID R. BARRACLOUGH, WORLD MAGNETIC CHARTS FOR 1985 - SPHERICAL HARMONIC MODELS OF THE GEOMAGNETIC FIELD AND ITS SECULAR VARIATION, GEOPHYS. J. R. ASTR. SOC. (1986) 87, PP 1143-1157
DEFENSE MAPPING AGENCY TECHNICAL REPORT, TR 8350.2: DEPARTMENT OF DEFENSE WORLD GEODETIC SYSTEM 1984, SEPT. 30 (1987)
JOSEPH C. CAIN, ET AL.; A PROPOSED MODEL FOR THE INTERNATIONAL GEOMAGNETIC REFERENCE FIELD - 1965, J. GEOMAG. AND GEOELECT. VOL. 19, NO. 4, PP 335-355 (1967) (SEE APPENDIX)
ALFRED J. ZMUDA, WORLD MAGNETIC SURVEY 1957-1969, INTERNATIONAL ASSOCIATION OF GEOMAGNETISM AND AERONOMY (IAGA) BULLETIN #28, PP 186-188 (1971)
JOHN M. QUINN, RACHEL J. COLEMAN, MICHAEL R. PECK, AND STEPHEN E. LAUBER; THE JOINT US/UK 1990 EPOCH WORLD MAGNETIC MODEL, TECHNICAL REPORT NO. 304, NAVAL OCEANOGRAPHIC OFFICE (1991)
JOHN M. QUINN, RACHEL J. COLEMAN, DONALD L. SHIEL, AND JOHN M. NIGRO; THE JOINT US/UK 1995 EPOCH WORLD MAGNETIC MODEL, TECHNICAL REPORT NO. 314, NAVAL OCEANOGRAPHIC OFFICE (1995)

WMM-2000 is a National Imagery and Mapping Agency (NIMA) standard product. It is covered under NIMA Military Specification: MIL-W-89500 (1993). For information on the use and applicability of this product contact

DIRECTOR
NATIONAL IMAGERY AND MAPPING AGENCY/HEADQUARTERS
ATTN: CODE P33
12310 SUNRISE VALLEY DRIVE
RESTON, VA 20191-3449
(703) 264-3002

The FORTRAN version of GEOMAG PROGRAMMED BY:

JOHN M. QUINN 7/19/90
FLEET PRODUCTS DIVISION, CODE N342
NAVAL OCEANOGRAPHIC OFFICE (NAVOCEANO)
STENNIS SPACE CENTER (SSC), MS 39522-5001
USA
PHONE: COM: (601) 688-5828
AV: 485-5828
FAX: (601) 688-5521

NOW AT:

GEOMAGNETICS GROUP
U. S. GEOLOGICAL SURVEY MS 966
FEDERAL CENTER
DENVER, CO 80225-0046
USA
PHONE: COM: (303) 273-8475
FAX: (303) 273-8600
EMAIL: quinn@ghtmail.cr.usgs.gov

Constructor Summary

Constructors

Constructor

Description

TSAGeoMag()

Instantiates object by calling initModel().
Method Summary

Modifier and Type

Method

Description

double

decimalYear(GregorianCalendar cal)

Given a Gregorian Calendar object, this returns the decimal year value for the calendar, accurate to the day of the input calendar.

double

getDeclination(double dlat, double dlong)

Returns the declination from the Department of Defense geomagnetic model and data, in degrees.

double

getDeclination(double dlat, double dlong, double year, double altitude)

Returns the declination from the Department of Defense geomagnetic model and data, in degrees.

double

getDipAngle(double dlat, double dlong)

Returns the magnetic field dip angle from the Department of Defense geomagnetic model and data, in degrees.

double

getDipAngle(double dlat, double dlong, double year, double altitude)

Returns the magnetic field dip angle from the Department of Defense geomagnetic model and data, in degrees.

double

getEastIntensity(double dlat, double dlong)

Returns the easterly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getEastIntensity(double dlat, double dlong, double year, double altitude)

Returns the easterly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getHorizontalIntensity(double dlat, double dlong)

Returns the horizontal magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getHorizontalIntensity(double dlat, double dlong, double year, double altitude)

Returns the horizontal magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getIntensity(double dlat, double dlong)

Returns the magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getIntensity(double dlat, double dlong, double year, double altitude)

Returns the magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getNorthIntensity(double dlat, double dlong)

Returns the northerly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getNorthIntensity(double dlat, double dlong, double year, double altitude)

Returns the northerly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getVerticalIntensity(double dlat, double dlong)

Returns the vertical magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

double

getVerticalIntensity(double dlat, double dlong, double year, double altitude)

Returns the vertical magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.

Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details
- TSAGeoMag
  
  public TSAGeoMag()
  
  Instantiates object by calling initModel().
Method Details
- getDeclination
  
  public double getDeclination(double dlat, double dlong)
  
  Returns the declination from the Department of Defense geomagnetic model and data, in degrees. The magnetic heading + declination = true heading. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation. (True heading + variation = magnetic heading.)
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  The declination in degrees.
- getDeclination
  
  public double getDeclination(double dlat, double dlong, double year, double altitude)
  
  Returns the declination from the Department of Defense geomagnetic model and data, in degrees. The magnetic heading + declination = true heading. (True heading + variation = magnetic heading.)
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - The date as a decimial year.
  
  altitude - The altitude in kilometers.
  
  Returns:
  
  The declination in degrees.
- getIntensity
  
  public double getIntensity(double dlat, double dlong)
  
  Returns the magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  Magnetic field strength in nano Tesla.
- getIntensity
  
  public double getIntensity(double dlat, double dlong, double year, double altitude)
  
  Returns the magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - Date of the calculation in decimal years.
  
  altitude - Altitude of the calculation in kilometers.
  
  Returns:
  
  Magnetic field strength in nano Tesla.
- getHorizontalIntensity
  
  public double getHorizontalIntensity(double dlat, double dlong)
  
  Returns the horizontal magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  The horizontal magnetic field strength in nano Tesla.
- getHorizontalIntensity
  
  public double getHorizontalIntensity(double dlat, double dlong, double year, double altitude)
  
  Returns the horizontal magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - Date of the calculation in decimal years.
  
  altitude - Altitude of the calculation in kilometers.
  
  Returns:
  
  The horizontal magnetic field strength in nano Tesla.
- getVerticalIntensity
  
  public double getVerticalIntensity(double dlat, double dlong)
  
  Returns the vertical magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  The vertical magnetic field strength in nano Tesla.
- getVerticalIntensity
  
  public double getVerticalIntensity(double dlat, double dlong, double year, double altitude)
  
  Returns the vertical magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - Date of the calculation in decimal years.
  
  altitude - Altitude of the calculation in kilometers.
  
  Returns:
  
  The vertical magnetic field strength in nano Tesla.
- getNorthIntensity
  
  public double getNorthIntensity(double dlat, double dlong)
  
  Returns the northerly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  The northerly component of the magnetic field strength in nano Tesla.
- getNorthIntensity
  
  public double getNorthIntensity(double dlat, double dlong, double year, double altitude)
  
  Returns the northerly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - Date of the calculation in decimal years.
  
  altitude - Altitude of the calculation in kilometers.
  
  Returns:
  
  The northerly component of the magnetic field strength in nano Tesla.
- getEastIntensity
  
  public double getEastIntensity(double dlat, double dlong)
  
  Returns the easterly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  The easterly component of the magnetic field strength in nano Tesla.
- getEastIntensity
  
  public double getEastIntensity(double dlat, double dlong, double year, double altitude)
  
  Returns the easterly magnetic field intensity from the Department of Defense geomagnetic model and data in nano Tesla.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - Date of the calculation in decimal years.
  
  altitude - Altitude of the calculation in kilometers.
  
  Returns:
  
  The easterly component of the magnetic field strength in nano Tesla.
- getDipAngle
  
  public double getDipAngle(double dlat, double dlong)
  
  Returns the magnetic field dip angle from the Department of Defense geomagnetic model and data, in degrees. The date and altitude are the defaults, of half way through the valid 5 year period, and 0 elevation.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  Returns:
  
  The magnetic field dip angle, in degrees.
- getDipAngle
  
  public double getDipAngle(double dlat, double dlong, double year, double altitude)
  
  Returns the magnetic field dip angle from the Department of Defense geomagnetic model and data, in degrees.
  
  Parameters:
  
  dlat - Latitude in decimal degrees.
  
  dlong - Longitude in decimal degrees.
  
  year - Date of the calculation in decimal years.
  
  altitude - Altitude of the calculation in kilometers.
  
  Returns:
  
  The magnetic field dip angle, in degrees.
- decimalYear
  
  public double decimalYear(GregorianCalendar cal)
  
  Given a Gregorian Calendar object, this returns the decimal year value for the calendar, accurate to the day of the input calendar. The hours, minutes, and seconds of the date are ignored.
  If the input Gregorian Calendar is new GregorianCalendar(2012, 6, 1), all of the first of July is counted, and this returns 2012.5. (183 days out of 366)
  If the input Gregorian Calendar is new GregorianCalendar(2010, 0, 0), the first of January is not counted, and this returns 2010.0
  
  Parameters:
  
  cal - Has the date (year, month, and day of the month)
  
  Returns:
  
  The date in decimal years

Class TSAGeoMag

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Details

TSAGeoMag

Method Details

getDeclination

getDeclination

getIntensity

getIntensity

getHorizontalIntensity

getHorizontalIntensity

getVerticalIntensity

getVerticalIntensity

getNorthIntensity

getNorthIntensity

getEastIntensity

getEastIntensity

getDipAngle

getDipAngle

decimalYear