Directory Listing of Routines

external/IDL_GEOPACK/t89

KP2IOPT
T89
T89_TEST
TT89

Routine Descriptions

KP2IOPT

Function: kp2iopt

Purpose: Convert a tplot or array Kp index variable to iopt values suitable for passing to the T89 field
modeling or tracing routines.

Input Kp values will be in the range of 0 to 6, and may have a fractional part indicating an increasing or decreasing index.
For example, 2.33333 represents 2+, 2.66666 represents 3-. iopt output values will be in the range 1 to 7.

Input: Kp values (e.g. from noaa_load_kp)

Return value: IOPT values suitable for passing to the GEOPACK T89 tracing and modeling routines. Represented as double precision floating
point for compatibility with GEOPACK library calling sequences, but may or may not be rounded to integer values depending
on whether the kp_plus1 keyword is specified.

Keywords:
kp: (input) A scalar or array of Kp values, or name of a tplot variable giving the Kp index values

varname (Required if kp is a tplot variable): A string specifying a tplot position variable. Output iopt values will be interpolated to the 'varname' times
using nearest-neighbor interpolation.

plus1: (optional) If specified, overrides the default behavior of rounding iopt to the nearest integer, and
instead sets iopt to kp+1, preserving any fractional part.

Example:

$LastChangedBy: jwl $
$LastChangedDate: 2021-07-28 18:16:15 -0700 (Wed, 28 Jul 2021) $
$LastChangedRevision: 30156 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta15/tomni2bindex.pro $

(See external/IDL_GEOPACK/t89/kp2iopt.pro)

T89

[Previous Routine] [Next Routine] [List of Routines]

Function: t89

Purpose: generates an array of model magnetic field vectors from
a monotonic time series and an array of 3-d position
vectors

Input:
tarray: N array representing the time series in seconds utc since 1970
rgsm_array: Nx3 array representing the position series in earth radii (required to be in GSM coordinates)

Keywords:
kp(optional): the requested value of the kp parameter(default: 2)
kp can also be an array, if it is an array it should be an
N length array(you should interpolate your values onto the tarray)
Also kp values passed in can only be integers. any pluses
or minuses will be ignored, because the Tsyganenko model
ignores plus and minuses on kp values

period(optional): the amount of time between recalculations of
geodipole tilt and application of a new kp value
in seconds,increase this value to decrease run time(default: 600)
The center (not the start) of the first period is now aligned with the start time.

igrf_only(optional): Set this keyword to turn off the t89 component of
the model and return only the igrf component

add_tilt: Increment the default dipole tilt used by the model with
a user provided tilt in degrees. Result will be produced with TSY_DEFAULT_TILT+ADD_TILT
Value can be set to an N length array an M length array or a single element array.
N is the number of time elements for the data. M is the number of periods in the time interval.(determined by the period keyword)
If single element is provided the same correction will be applied to all periods.
If an N length array is provided, the data will be re-sampled to an M length array. Consequently, if
the values change quickly, the period may need to be shortened.

get_tilt: Returns the dipole_tilt parameter used for each period.
Returned value has a number of elements equal to the value returned by get_nperiod

set_tilt: Use alternative dipole_tilt value rather than the geopack tilt.
This input can be an M length array, and N length array or a single elemnt.
Value can be set to an N length array an M length array or a single element array.
N is the number of time elements for the data. M is the number of periods in the time interval.(determined by the period keyword)
If an N length array is provided, the data will be re-sampled to an M length array. Consequently, if
the values change quickly, the period may need to be shortened.
Notes:
1) set_tilt will cause add_tilt to be ignored
2) Due to this routine adding IGRF to the returned field, you cannot use set_tilt = 0 and give input
position values in SM coordinates; input position values are required to be in GSM coordinates due to the
IGRF calculation

exact_tilt_times (optional): Set this keyword to avoid grouping similar times (default 10 minutes) and instead
recalculate the dipole tilt at each input time

get_nperiod: Returns the number of periods used for the time interval= ceil((end_time-start_time)/period)

geopack_2008 (optional): Set this keyword to use the latest version (2008) of the Geopack
library. Version 9.2 of the IDL Geopack DLM is required for this keyword to work.

Returns:
an Nx3 length array of field model data (T89 + IGRF) or -1L on failure

Example:
mag_array = t89(time_array,pos_array)
mag_array = t89(time_array,pos_array,kp=5,rlength=10)

Notes:
1. Relies on the IDL/Geopack Module provided by Haje Korth JHU/APL
and N.A. Tsyganenko NASA/GSFC, if the module is not installed
this function will fail.
2. Sums the contribution from the internal field model (IGRF) and the
external field model (t89).
3. Has a loop with number of iterations = (tarray[n_elements(t_array)]-tarray[0])/period
This means that as period becomes smaller the amount time of this
function should take will grow quickly.
4. Position units are earth radii, be sure to divide your normal
units by 6371.2 km to convert them.
6371.2 = the value used in the GEOPACK FORTRAN code for Re

$LastChangedBy: jwl $
$LastChangedDate: 2021-12-08 14:28:31 -0800 (Wed, 08 Dec 2021) $
$LastChangedRevision: 30452 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/external/IDL_GEOPACK/t89/t89.pro $

(See external/IDL_GEOPACK/t89/t89.pro)

T89_TEST

[Previous Routine] [Next Routine] [List of Routines]

 tt89_test

 Purpose: A few tests to verify that the model and the wrapper
 procedures work correctly

 $LastChangedBy: lphilpott $
 $LastChangedDate: 2012-06-14 11:15:50 -0700 (Thu, 14 Jun 2012) $
 $LastChangedRevision: 10561 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/external/IDL_GEOPACK/t89/t89_test.pro $

(See external/IDL_GEOPACK/t89/t89_test.pro)

TT89

[Previous Routine] [List of Routines]

Procedure: tt89

Purpose:  tplot wrapper for the functional interface to the IDL Geopack
          implementation of the Tsyganenko 89 and IGRF model.

Input:
          pos_gsm_tvar: the tplot variable storing the position in
               gsm coordinates(can use standard globbing)

Keywords: 
          kp(optional): the requested value of the kp parameter(default: 2) 
               can also be a tplot variable name if it is a tplot variable name 
               the kp values stored in the variable will be interpolated to match 
               the time grid of the position input values

          period(optional): the amount of time between recalculations of
               geodipole tilt in seconds(default: 600)  increase this
               value to decrease run time
             
          get_nperiod(optional): Return the number of periods used in the time interval

          newname(optional):the name of the output variable. 
               (default: pos_gsm_tvar+'_bt89') This option is ignored if
               globbing is used.

          error(optional): named variable in which to return the
               error state of this procedure call. 1 = success, 0 = failure
        
          igrf_only(optional): Set this keyword to turn off the t89 component of
               the model and return only the igrf component
        
          get_tilt(optional):  Set this value to a tplot variable name in which the geodipole tilt for each period will be returned
               One sample will be returned for each period with time at the center of the period.
          
          set_tilt(optional): Set this to a tplot variable name or an array of values containing the dipole tilt that should be used.
               If a tplot input is used it will be interpolated to match the time inputs from the position
               var. Non-tplot array values must match the number of times in the tplot input for pos_gsm_tvar
               Notes:
                    1) set_tilt will cause add_tilt to be ignored
                    2) Due to this routine adding IGRF to the returned field, you cannot use set_tilt = 0 and give input 
                         position values in SM coordinates; input position values are required to be in GSM coordinates due to the
                         IGRF calculation

          add_tilt(optional): Set this to a tplot variable name or an array of values containing the values to be added to the dipole tilt
               that should be used for each period. If a tplot input is used it will be interpolated to match the time inputs from the position
               var. Non-tplot array values must match the number of times in the tplot input for pos_gsm_tvar

         exact_tilt_times (optional):  Set this keyword to avoid grouping similar times (default 10 minutes) and instead
              recalculate the dipole tilt at each input time

          geopack_2008 (optional): Set this keyword to use the latest version (2008) of the Geopack
              library. Version 9.2 of the IDL Geopack DLM is required for this keyword to work.
              
 Output: Stores the result of the field model calculations in tplot variables
          
 Notes: 
        1. Converts from normal gsm to rgsm by dividing vectors by earth's
            radius(6371.2 km) ie inputs should be in km
            6371.2 = the value used in the GEOPACK FORTRAN code for Re
        2. Input must be in GSM coordinates
        3. Haje Korth's IDL/Geopack DLM must be installed for this
        procedure to work

 $LastChangedBy: nikos $
 $LastChangedDate: 2022-08-18 09:29:42 -0700 (Thu, 18 Aug 2022) $
 $LastChangedRevision: 31020 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_6_1/external/IDL_GEOPACK/t89/tt89.pro $

(See external/IDL_GEOPACK/t89/tt89.pro)