A A C G M
User's Guide

• Converting from geographic to AACGM and vice versa
• Using the 1990 model instead of 1995
• Calculating MLT
• Using AACGM in IDL

How do I convert a geographic position to AACGM (or vice versa)?

[in FORTRAN]
       CALL SFC$$CONVERT_GEO_COORD(x_in_lat, x_in_long, x_height,
                            x_out_lat, x_out_long, i_flag, i_err)
where:
   x_in_lat  =  input latitude (in degrees)(real single precision)
   x_in_long =  input longitude (in degrees) (real single precision)
   x_height  =  input altitude (in km) (real single precision)
   x_out_lat =  returned magnetic latitude (real single precision)
   x_out_long = returned magnetic longitude (real single precision)
   i_flag    =  1 (32-bit integer) [flag indicating geo->AACGM conversion]
   i_err     =  returned integer error code (0 = OK)

latitude must be in the range -90 to +90.
longitude must be in the range 0 to 360
height must be in the range 0 to 2000
out_lat is returned in the range -90 to + 90
out_long is returned in the range 0 to 360
i_flag must be 1 (geo->AACGM) or 2 (AACGM->geo)
i_err (see below) 

[in C use]:
  sfc$$convert_geo_coord(&in_lat, &in_long, &height, &out_lat,
                       &out_long, &i_flag, &i_err);

Alternatively you can use the old call to cnv$coord (one of the original
PGM routines) which will in turn make the call to sfc$$convert_geo_coord.
The call to cnv$coord is:

       CALL CNV$COORD(x_in_lat, x_in_long, x_height, i_order,
                      x_out_lat, x_out_long, x_out_r, i_flag, i_err)

Where:
   The variables are the same as above except that there are two
additional variables, i_order, and x_out_r.  i_order is required
only for backwards compatibility with the old PGM software.  It
is ignored by the new software.  x_out_r is a returned quality
flag and will be 1 if the conversion was successful.  It provides
no additional information that is not in i_err.

   The input range of the longitude may be either -180 to + 180 or
0 to 360.  The output ragne of the longitude is -180 to + 180 instead
of 0 to 360.


Error Codes:
  The value of i_err indicates the following error conditions:

value        condition
------------------------
0           No Error
-2          height value outside of allowed range
-4          I_flag is invalid (must be 1 or 2)
-8          input latitude is outside the range -90 to + 90
-16         input longitude is outside the range
-32         magnitude of the unit vecotr of the result deviates
            significantly (more than 10%) from 1.
-64         For conversions from AACGM to geo there is a range
            of latitudes for which the transformation
            is invalid.  

How do I do the coordinate conversion for epoch 1990?

aacgm_coeffs1990.asc contains the coefficients for the 1990 epoch model
aacgm_coeffs1995.asc contains the coefficients for the 1995 epoch model

To change the coefficients you must call the routine aacgm_init as follows.

[in FORTRAN]
       CALL aacgm_init(filename, .TRUE.)

where:
	filename is a character string containing the full path to the
	required data file.  The second argument indicates that the
	file is in ASCII.

[in C]
       aacgm_init(filename, &ascii_flag);

where:
	filename is a char pointer to the string containing the file
	name.
	ascii_flag is a char containing the value 1. NOTE it must be
	passed by reference (i.e. use &).

The initialization routine will read in the appropriate data file. Once the coefficients have been initialized, simply call the conversion routines as usual. You can switch back and forth between models as often as you want, but this will significantly slow up your program.

How do I calculate MLT?

[ in FORTRAN]
       REAL*4 HR_MLT, MLT
       hr_mlt = MLT( iyr, n_yr_sec, x_mlong, x_mslong)

[ in C]
       hr_mlt = mlt( &iyr, &n_yr_sec, &x_mlong, &x_mslong);

where:
	You must declare mlt to be a REAL*4 function.
	iyr is the year (example: 1996) and is an integer*2 value.
	n_yr_sec is the time in seconds from the beginning of the year
                 and is an integer*4 value.
        x_mlong is the magnetic longitude of the point in question and 
                 is real*4.
        x_mslong is returned to you by the function.  It gives
                 the magnetic longitude of the sub-solar point
                 and is a real*4 value.  You don't generally need
                 to make any use of this value, but since it has
                 to be determined, there was no reason not to
                 return it to you. 

How do I use these routines from IDL?

	cnvcoord_idl.c
	mlt_idl.c

	
        SD_LIB_PGM	full path to the shareable AACGM library
	AACGM90_DAT	full path to the data file for the 1990 coefficients
	AACGM95_DAT	full path to the data file for the 1995 coefficients