This page was created by the IDL library routine `mk_html_help2`.

Last modified: Sat Aug 2 18:17:35 2025.

# Directory Listing of Routines

# external/IDL_GEOPACK/trace

- TRACE2EQUATOR
- TRACE2IONO
- TTRACE2EQUATOR
- TTRACE2IONO

# Routine Descriptions

## TRACE2EQUATOR

[Next Routine] [List of Routines]

    Procedure: trace2equator

    Purpose: Generates a model field line footprint from an array of given
             positions and times, will also trace field lines at the user's request
             This program will always use the refined foot point mappings (a
             modification made by Vassilis Angelopoulos to provide more accurate
             mappings of foot points) as there is no Tsyganenko code to
             perform equatorial traces.

    Input:
             tarray: N length array storing the position times in seconds utc since 1970

             in_pos_array: Nx3 array representing the position series (in
                 km gsm by default)

             out_foot_array: named variable in which to store the footprints
                 calculated by this function(will be an Nx3 array) will be returned
                 (in RE gsm by default)

    Keywords:
             out_trace_array(optional): named variable in which to store the traces of
                 field lines leading to footprints. Because traces are of variable
                 length, the returned array will be of dimensions NxDx3
                 D is the maximum number of vectors in any of the traces.
                 Shorter traces will have NaNs filling the space at the end
                 of the array

             in_coord(optional): set this keyword to a string indicating the
                 coordinate system input position data is in.
                 (can be 'gei','gse','geo','gsm',or 'sm' default: gsm)

             out_coord(optional): set this keyword to a string indicating the
                 coordinate system output data should be in.
                 (can be 'gei','gse','geo','gsm',or 'sm' default: gsm)

             internal_model(optional): set this keyword to a string
                 indicating the internal model that should be used in tracing
                 (can be 'dip' or 'igrf' default:igrf)

             external_model(optional): set this keyword to a string
                 indicating the external model that should be used in tracing
                 (can be 'none', 't89', 't96', 't01', 't04s','ts07', 'ta15b', 'ta15n', 'ta16'
                  default: none)

             SOUTH(optional): set this keyword to indicate that fields
                 should be traced towards the southern hemisphere. By default
                 they trace north.

             KM(optional): set this keyword to indicate that input
                 and output will be in KM not RE

             par(optional): parameter input for the external field model
                 if using t89 then it should be an N element array containing
                 kp values or a single kp value, if using t96,t01,t04s it
                 should be an N x 10 element array of parmod values or a 10
                 element array or a 1x10 element array. At the moment if an
                 external model is set and this is not set an error will be
                 thrown.

             period(optional): the amount of time between recalculations of
                 geodipole tilt and input of new model parameters in
                 seconds (default: 60) increase this value to decrease
                 run time
                 if field line traces are requested this parameter is
                 ignored and new model parameters are input on each
                 iteration

             error(optional): named variable in which to return the error state
                 of the procedure.  1 for success, 0 for failure

             R0(optional):  radius of a sphere (in re), defining the inner boundary of the tracing region
             (usually, earth's surface or the ionosphere, where r0~1.0)
             if the field line reaches that sphere from outside, its inbound tracing is
             terminated and the crossing point coordinates xf,yf,zf  are calculated.
             (units are km if /km is set)

             RLIM(optional) - radius of a sphere (in re), defining the outer boundary of the tracing region;
             if the field line reaches that boundary from inside, its outbound tracing is
             terminated and the crossing point coordinates xf,yf,zf are calculated.(default 60 RE)
             (units are km if /km is set)

             NOBOUNDARY(optional): Override boundary limits.

             STORM(optional): Specify storm-time version of T01 external
                 magnetic field model use together with /T01.

             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: Alternative 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.
                 set_tilt will cause add_tilt to be ignored.

             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.

              ts07_param_dir (optional): Location of TS07 parameter directory

              ts07_param_file (optional): Location of TS07 parameter file

              skip_ts07_load (optional): Do not reset TS07 parameter directory or reload parameter file

    Example:
            trace2equator,in_time,in_pos,out_foot

    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. 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.
      3. If the trace_array variable is set
          the period variable will be ignored.  The program will
          recalculate for each value, this will cause the program to
          run very slowly.
      4. All calculations are done internally in double precision

     $LastChangedBy: nikos $
     $LastChangedDate: 2025-06-22 10:49:35 -0700 (Sun, 22 Jun 2025) $
     $LastChangedRevision: 33400 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/trace/trace2equator.pro $

(See external/IDL_GEOPACK/trace/trace2equator.pro)

## TRACE2IONO

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

    Procedure: trace2iono

    Purpose: Generates a model field line footprint from an array of given
             positions and times,will also trace field lines at the user's request
             This program will always use the refined foot point mappings(a
             modification made by Vassilis Angelopoulos to provide more accurate
             mappings of foot points) unless you request the standard mapping;

    Input:
             tarray: N length array storing the position times in seconds utc since 1970

             in_pos_array: Nx3 array representing the position series (in
             km gsm by default)

             out_foot_array: named variable in which to store the footprints
             calculated by this function(will be an Nx3 array) will be returned
             (in RE gsm by default)

    Keywords:
             out_trace_array(optional): named variable in which to store the traces of
                 field lines leading to footprints. Because traces are of variable
                 length, the returned array will be of dimensions NxDx3
                 D is the maximum number of vectors in any of the traces.
                 Shorter traces will have NaNs filling the space at the end
                 of the array

             in_coord(optional): set this keyword to a string indicating the
                 coordinate system input position data is in.
                 (can be 'gei','geo','gse','gsm',or 'sm' default: gsm)

             out_coord(optional): set this keyword to a string indicating the
                 coordinate system output data should be in.
                 (can be 'gei','geo','gse','gsm',or 'sm' default: gsm)

             internal_model(optional): set this keyword to a string
                 indicating the internal model that should be used in tracing
                 (can be 'dip' or 'igrf' default:igrf)

             external_model(optional): set this keyword to a string
                 indicating the external model that should be used in tracing
                 (can be 'none', 't89', 't96', 't01', 't04s','ts07', 'ta15b', 'ta15n', 'ta16'
                  default: none)

             SOUTH(optional): set this keyword to indicate that fields
                 should be traced towards the southern hemisphere. By default
                 they trace north.

             KM(optional): set this keyword to indicate that input
                 and output will be in KM not RE

             par(optional): parameter input for the external field model
                 if using t89 then it should be an N element array containing
                 kp values or a single kp value, if using t96,t01,t04s it
                 should be an N x 10 element array of parmod values or a 10
                 element array or a 1x10 element array. At the moment if an
                 external model is set and this is not set an error will be thrown.

             period(optional): the amount of time between recalculations of
                 geodipole tilt and input of new model parameters in
                 seconds (default: 60)  increase this value to decrease run time
                 if field line traces are requested this parameter is
                 ignored and new model parameters are input on each
                 iteration

             error(optional): named variable in which to return the error state
                 of the procedure.  1 for success, 0 for failure

             standard_mapping(optional): Set to use Tsyganenko's
                 unmodified version instead of the Angelopoulos's
                 refined version

             R0(optional):  radius of a sphere (in re), defining the inner boundary of the tracing region
             (usually, earth's surface or the ionosphere, where r0~1.0)
             if the field line reaches that sphere from outside, its inbound tracing is
             terminated and the crossing point coordinates xf,yf,zf  are calculated.
             (units are km if /km is set)

             RLIM(optional) - radius of a sphere (in re), defining the outer boundary of the tracing region;
             if the field line reaches that boundary from inside, its outbound tracing is
             terminated and the crossing point coordinates xf,yf,zf are calculated.(default 60 RE)
             (units are km if /km is set)

             NOBOUNDARY(optional): Override boundary limits.

             STORM(optional): Specify storm-time version of T01 external
                 magnetic field model use together with /T01.

             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: Alternative 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.
                 set_tilt will cause add_tilt to be ignored.

             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.

    Example: trace2iono,in_time,in_pos,out_foot

    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. 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.
      3. If the trace_array variable is set
          the period variable will be ignored.  The program will
          recalculate for each value, this will cause the program to
          run very slowly.
      4. All calculations are done internally in double precision

     $LastChangedBy: nikos $
     $LastChangedDate: 2025-06-22 10:49:35 -0700 (Sun, 22 Jun 2025) $
     $LastChangedRevision: 33400 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/trace/trace2iono.pro $

(See external/IDL_GEOPACK/trace/trace2iono.pro)

## TTRACE2EQUATOR

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

    Procedure : ttrace2equator

    Purpose: tplot wrapper for field line footprint and tracing routines
             This program will always use the refined foot point mappings
             (a modification made by Vassilis Angelopoulos to provide more accurate
             mappings of foot points) as there is no Tsyganenko code to
             perform equatorial traces.Model parameters can be provided
             in the par array or individually, using the
             parameter's name.  If a model parameter is provided
             by name, it will overwrite a part of any par value
             provided.  If a named parameter is provided, but is
             unneeded by the model, it will be ignored.

    Input:
             in_pos_tvar: name of the tplot variable storing the
                 position information for tracing, input values should be in
                 'gse','gei','gsm',or 'sm'

    Keywords:
             newname(optional): name of the tplot variable in which output
                 footprints should be stored(default: in_pos_tvar+'_foot')

             trace_var_name(optional): name of the tplot variable in
                 which to store the traces of field lines leading to footprints.
                 Because traces are of variable length, the returned array
                 will be of dimensions NxDx3
                 D is the maximum number of vectors in any of the traces.
                 Shorter traces will have NaNs filling the space at the end
                 of the array

             in_coord(optional): set this keyword to the coordinate
                 system of the input, defaults to 'gsm', must match tplot
                 meta data

             out_coord(optional): set this keyword to a string indicating
                 the coordinate system output data should be in, defaults to 'gsm'
                 (can be 'geo','gei','gse','gsm',or 'sm' default: the same as
                  the input)

             internal_model(optional): set this keyword to a string
                 indicating the internal model that should be used in tracing
                 (can be 'dip' or 'igrf' default:igrf)

             external_model(optional): set this keyword to a string
                 indicating the external model that should be used in tracing
                 (can be 'none','t89','t96','t01', or 't04s' default: none)

             SOUTH(optional): set this keyword to indicate that fields
                 should be traced towards the southern hemisphere. By default
                 they trace north.

             KM(optional): set this keyword to indicate that input
                 and output will be in KM not RE

             par(optional): parameter input for the external field model
                 if using t89 then it should be an N element array containing
                 kp values or a single kp value, if using t96,t01,t04s it
                 should be an N x 10 element array of parmod values or a 10
                 element array. At the moment if an external model is set and
                 this is not set an error will be thrown. This value can also
                 be tplot variable name. If it is a tplot variable name it
                 will be interpolated to match the positions in pos_tvar

             period(optional): the amount of time between recalculations of
                 geodipole tilt and input of new model parameters in
                 seconds (default: 60) increase this value to decrease
                 run time
                 if field line traces are requested this parameter is
                 ignored and new model parameters are input on each
                 iteration

             error(optional): named variable in which to return the error
                 state of the procedure.  1 for success, 0 for failure

             R0(optional):  radius of a sphere (in re), defining the inner boundary of the tracing region
             (usually, earth's surface or the ionosphere, where r0~1.0)
             if the field line reaches that sphere from outside, its inbound tracing is
             terminated and the crossing point coordinates xf,yf,zf  are calculated.
             (units are km if /km is set)

             RLIM(optional) - radius of a sphere (in re), defining the outer boundary of the tracing region;
             if the field line reaches that boundary from inside, its outbound tracing is
             terminated and the crossing point coordinates xf,yf,zf are calculated.(default 60 RE)
             (units are km if /km is set)

             NOBOUNDARY(optional): Override boundary limits.

             STORM(optional): Specify storm-time version of T01 external
                 magnetic field model use together with /T01.

             kp (optional): Kp index value for T89 model should either be a
                  string naming a tplot variable or an array or a single
                  value. 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

             pdyn(optional): Solar wind pressure(nanoPascals) should either be a
                  string naming a tplot variable or an array or a single
                  value. 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

             dsti(optional): DST index(nanoTeslas)  should either be a
                  string naming a tplot variable or an array or a single
                  value.  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

             yimf(optional): y component of the interplanetary magnetic field
                 should either be a string naming a tplot variable or an
                 array or a single value.  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

             zimf(optional): z component of the interplanetary magnetic field
                 should either be a string naming a tplot variable or an
                 array or a single value.  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

             symc(optional, for TA16 only): sliding average of Sym-H over 30-min interval,
                 centered on the current time moment.
                 symc can be computed from symh using symh2symc

             g1(optional):  index describes solar wind conditions in the
                 previous hour, should either be a string naming a tplot variable or an
                 array or a single value.   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

             g2(optional): index describes solar wind conditions in the
                 previous hour should either be a string naming a tplot variable or an
                 array or a single value.   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

             w1(optional):  time integral from the beginning of a storm
                 can be an array or a tplot variable(see paper reference
                 below for definitions of w1-w6) or a single value.
                 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

             w2(optional): time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w3(optional):  time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w4(optional): time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w5(optional):  time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w6(optional): time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             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

             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

             get_nperiod(optional): Return the number of periods used in the time interval

             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.

             ts07_param_dir (optional): Specify location of TS07 parameter directory

             ts07_param_file (optional): Specify TS07 parameter file to load

             skip_ts07_load (optional):  Do not reset the TS07 parameter directory or reload the parameter file

    Example: ttrace2equator,'tha_state_pos',newname='tha_out_foot'

    See: crib_ttrace for more examples

    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. 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.
      3. If the trace_array variable is set
          the period variable will be ignored.  The program will
          recalculate for each value, this will cause the program to
          run very slowly.
      4. All calculations are done internally in double precision

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-09-16 16:30:39 -0700 (Fri, 16 Sep 2022) $
     $LastChangedRevision: 31098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/trace/ttrace2equator.pro $

(See external/IDL_GEOPACK/trace/ttrace2equator.pro)

## TTRACE2IONO

[Previous Routine] [List of Routines]

    Procedure : ttrace2iono

    Purpose: tplot wrapper for field line footprint and tracing routines
             This program will always use the refined foot point mappings
             (a modification made by Vassilis Angelopoulos to provide more
             accurate mappings of foot points) unless you request the standard
             mapping. Model parameters can be provided in the par array
             or individually, using the parameter's name.  If a model parameter
             is provided by name, it will overwrite an par value
             provided.  If a named parameter is provided, but is
             unneeded by the model, it will be ignored.

    Input:
             in_pos_tvar: name of the tplot variable storing the
                 position information for tracing, input values should be in
                 'gse','gei','gsm',or 'sm'

    Keywords:
             newname(optional): name of the tplot variable in which output
                 footprints should be stored(default: in_pos_tvar+'_foot')

             trace_var_name(optional): name of the tplot variable in
                 which to store the traces of field lines leading to footprints.
                 Because traces are of variable length, the returned array
                 will be of dimensions NxDx3
                 D is the maximum number of vectors in any of the traces.
                 Shorter traces will have NaNs filling the space at the end
                 of the array

             in_coord(optional): set this keyword to the coordinate
                 system of the input, defaults to 'gsm', must match tplot
                 meta data

             out_coord(optional): set this keyword to a string indicating
                 the coordinate system output data should be in, defaults to 'gsm'
                 (can be 'geo','gei','gse','gsm',or 'sm' default: the same as
                  the input)

             internal_model(optional): set this keyword to a string
                 indicating the internal model that should be used in tracing
                 (can be 'dip' or 'igrf' default:igrf)

             external_model(optional): set this keyword to a string
                 indicating the external model that should be used in tracing
                 (can be 'none','t89','t96','t01', or 't04s' default: none)

             SOUTH(optional): set this keyword to indicate that fields
                 should be traced towards the southern hemisphere. By default
                 they trace north.

             KM(optional): set this keyword to indicate that input
                 and output will be in KM not RE

             par(optional): parameter input for the external field model
                 if using t89 then it should be an N element array containing
                 kp values or a single kp value, if using t96,t01,t04s it
                 should be an N x 10 element array of parmod values or a 10
                 element array or a 1x10 element array. At the moment if an
                 external model is set and this is not set an error will be
                 thrown. This can also contain a string naming a tplot
                 variable storing the par values. If a tplot variable is
                 named it will also be interpolated to match the position
                 data.

             period(optional): the amount of time between recalculations of
                 geodipole tilt and input of new model parameters in
                 seconds (default: 60) increase this value to decrease
                 run time
                 if field line traces are requested this parameter is
                 ignored and new model parameters are input on each
                 iteration

             error(optional): named variable in which to return the error
                 state of the procedure.  1 for success, 0 for failure

             standard_mapping(optional): Set to use Tsyganenko's
                 unmodified version instead of the Angelopoulos's
                 refined version

             R0(optional):  radius of a sphere (in re), defining the inner boundary of the tracing region
             (usually, earth's surface or the ionosphere, where r0~1.0)
             if the field line reaches that sphere from outside, its inbound tracing is
             terminated and the crossing point coordinates xf,yf,zf  are calculated.
             (units are km if /km is set)

             RLIM(optional) - radius of a sphere (in re), defining the outer boundary of the tracing region;
             if the field line reaches that boundary from inside, its outbound tracing is
             terminated and the crossing point coordinates xf,yf,zf are calculated.(default 60 RE)
             (units are km if /km is set)

             NOBOUNDARY(optional): Override boundary limits.

             STORM(optional): Specify storm-time version of T01 external
                 magnetic field model use together with /T01.

             kp (optional): Kp index value for T89 model should either be a
                  string naming a tplot variable or an array or a single
                  value. 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.

             pdyn(optional): Solar wind pressure(nanoPascals) should either be a
                  string naming a tplot variable or an array or a single
                  value. 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

             dsti(optional): DST index(nanoTeslas)  should either be a
                  string naming a tplot variable or an array or a single
                  value.  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

             yimf(optional): y component of the interplanetary magnetic field
                 should either be a string naming a tplot variable or an
                 array or a single value.  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

             zimf(optional): z component of the interplanetary magnetic field
                 should either be a string naming a tplot variable or an
                 array or a single value.  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

             symc(optional, for TA16 only): sliding average of Sym-H over 30-min interval,
                 centered on the current time moment.
                 symc can be computed from symh using symh2symc

             g1(optional):  index describes solar wind conditions in the
                 previous hour, should either be a string naming a tplot variable or an
                 array or a single value.   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

             g2(optional): index describes solar wind conditions in the
                 previous hour should either be a string naming a tplot variable or an
                 array or a single value.   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

             w1(optional):  time integral from the beginning of a storm
                 can be an array or a tplot variable(see paper reference
                 below for definitions of w1-w6) or a single value.
                 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

             w2(optional): time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w3(optional):  time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w4(optional): time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w5(optional):  time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             w6(optional): time integral from the beginning of a storm
                 can be an array or a tplot variable or a single value
                 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

             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

             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

             get_nperiod(optional): Return the number of periods used in the time interval

             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.

             ts07_param_dir (optional): Specify location of TS07 parameter directory

             ts07_param_file (optional): Specify TS07 parameter file to load

             skip_ts07_load (optional):  Do not reset the TS07 parameter directory or reload the parameter file

    Example: ttrace2iono,'tha_state_pos',newname='tha_out_foot'

    See: crib_ttrace for more examples

    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. 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.
      3. If the trace_array variable is set
          the period variable will be ignored.  The program will
          recalculate for each value, this will cause the program to
          run very slowly.
      4. All calculations are done internally in double precision

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-09-16 16:30:39 -0700 (Fri, 16 Sep 2022) $
     $LastChangedRevision: 31098 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/trace/ttrace2iono.pro $

(See external/IDL_GEOPACK/trace/ttrace2iono.pro)