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

Last modified: Fri Aug 29 03:18:49 2025.

# Directory Listing of Routines

# external/IDL_GEOPACK/ta16

- GET_TA16_PARAMS
- SYMH2SYMC
- TA15N_TA16_CRIB
- TA16
- TA16_CRIB
- TA16_SETPATH
- TA16_SUPPORTED
- TA16_TEST
- TTA16

# Routine Descriptions

## GET_TA16_PARAMS

[Next Routine] [List of Routines]

    TODO
     PROCEDURE: get_ta16_params

     PURPOSE: this procedure will interpolate inputs, generate
              tsyganenko model parameters and store them in a tplot
              variable that can be passed directly to the model
              procedure

     KEYWORDS:
               imf_tvar: tplot variable name with IMF data.  Can be just the Y and Z components as a composite tplot variable,
                         or 3-vectors.

               /imf_yz:  Set this keyword if using just the T abd Z components, otherwise 3-vectors assumed

               Np_tvar: tplot variable name storing the solar wind
                       ion density(rho) cm^-3

               Vp_tvar: tplot variable name storing the proton velocity.  Can be a scalar (speed only), or 3-vectors

               /speed: Set this keyword if Vp_tvar contains scalar speeds

               symh(optional): Sym-H index (nT),
                 longitudinal symmetric component of the ring current;
                 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): sliding average of Sym-H over 30-min interval,
                 centered on the current time moment.
                 Either symh or symc must be provided.
                 symc can be computed from symh using GEOPACK_GETSYMHC
                 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

               newname(optional): the name of the output tplot variable
                   (default: ta16_par)

               trange(optional): the time range over which the parameters
                   should range, if not set, this program will check the
                   timespan variable or prompt the user for a range

               speed(optional): set this if Vp_tvar is stored as a speed

     Notes:
       Modified from get_ta15_params.
       TA16: Ten-element array parmod: (1) Pdyn [nPa], (2) SymHc, (3) XIND, (4) IMF By [nT].

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-09-22 15:29:33 -0700 (Thu, 22 Sep 2022) $
     $LastChangedRevision: 31124 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/get_ta16_params.pro $

(See external/IDL_GEOPACK/ta16/get_ta16_params.pro)

## SYMH2SYMC

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

    Procedure: symh2symc

    Purpose: Create a tplot variable with sliding average of SYM-H over 30-min interval,
                 centered on the current time moment

    Input:
             symh:  (input) Name of a tplot variable that contains Sym-H index (nT) in 5-minute intervals, e.g, OMNI_HRO_5min_SYM_H

             pdyn:  (input) Name of a tplot variable that contains Solar wind dynamic pressure [nPa] in 5-minute intervals), e.g. OMNI_HRO_5min_Pressure

    Output:

             newname: (optional) Name of the tplot variable to use for the output. If not provided, symh + '_c' will be used.

    Notes:
           Requires GEOPACK 10.9 or higher

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-09-15 18:51:58 -0700 (Thu, 15 Sep 2022) $
     $LastChangedRevision: 31088 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/symh2symc.pro $

(See external/IDL_GEOPACK/ta16/symh2symc.pro)

## TA15N_TA16_CRIB

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

    Procedure: ta15n_ta16_crib

    Purpose:  Compare TA15n model to TA16 model

     $LastChangedBy: nikos $
     $LastChangedDate: 2022-10-06 09:42:40 -0700 (Thu, 06 Oct 2022) $
     $LastChangedRevision: 31156 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/ta15n_ta16_crib.pro $

(See external/IDL_GEOPACK/ta16/ta15n_ta16_crib.pro)

## TA16

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

    Function: ta16

    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)
             The following arguments can either be N length arrays or
             single values
             pdyn_array: Solar wind pressure (nanoPascals)
             yimf_array: y component of the interplanetary magnetic field
             symc_array: sliding average of Sym-H over 30-min interval,
                 centered on the current time moment
             xind_array: N-index parameter (see Newell et al., 2007)

    Keywords:
             period(optional): the amount of time between recalculations of
                 geodipole tilt in seconds(default: 60)
                 increase this value to decrease run time
                 By default, the center (not the start) of the first period is now aligned with the start time.

             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 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 (TA16 + IGRF) or -1L on failure

    Example:
       mag_array = ta16(time_array,pos_array,pdyn_array,dsti_array,yimf_array,symc_array,w1_array,w2_array,w3_array,w4_array,w5_array,w6_array)
       mag_array = ta16(time_array,pos_array,pdyn_array,dsti_array,yimf_array,symc_array,w1_array,w2_array,w3_array,w4_array,w5_array,w6_array,period=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 and the
          external field model.
      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 in 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

      See Newell 2007 for details:
      https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2006JA012015

      TA16 model description:
      https://geo.phys.spbu.ru/~tsyganenko/empirical-models/magnetic_field/ta16
      https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2016JA023217

      The N-index calculation is implemented in omni2nindex.pro

     $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/ta16/ta16.pro $

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

## TA16_CRIB

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

    Procedure: ta16_crib

    Purpose: A crib for the TA16 geopack model.
             Similar to ta15n_crib.pro.

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-09-22 15:30:50 -0700 (Thu, 22 Sep 2022) $
     $LastChangedRevision: 31125 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/ta16_crib.pro $

(See external/IDL_GEOPACK/ta16/ta16_crib.pro)

## TA16_SETPATH

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

     ta16_setpath

     Purpose: Set the GEOPACK internal path for the TA16_RBF.par file required by TA16 model.

     Notes:
       2022-05-23: Geopack DLM v10.9 is a beta version:
                   https://www.korthhaus.com/index.php/idl-software/idl-geopack-dlm/

     $LastChangedBy: nikos $
     $LastChangedDate: 2022-05-29 14:31:21 -0700 (Sun, 29 May 2022) $
     $LastChangedRevision: 30837 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/ta16_supported.pro $

(See external/IDL_GEOPACK/ta16/ta16_setpath.pro)

## TA16_SUPPORTED

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

     ta16_supported

     Purpose: returns 1 if TA16 is supported (geopack version is 10.9 or higher)

     Notes:
       2022-05-23: Geopack DLM v10.9 is a beta version:
                   https://www.korthhaus.com/index.php/idl-software/idl-geopack-dlm/

     $LastChangedBy: jwl $
     $LastChangedDate: 2022-09-16 16:24:34 -0700 (Fri, 16 Sep 2022) $
     $LastChangedRevision: 31096 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/ta16_supported.pro $

(See external/IDL_GEOPACK/ta16/ta16_supported.pro)

## TA16_TEST

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

     ta16_test

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

     $LastChangedBy: nikos $
     $LastChangedDate: 2022-06-24 09:11:47 -0700 (Fri, 24 Jun 2022) $
     $LastChangedRevision: 30880 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/ta16/ta16_test.pro $

(See external/IDL_GEOPACK/ta16/ta16_test.pro)

## TTA16

[Previous Routine] [List of Routines]

    Procedure: tt16

    Purpose:  tplot wrapper for the functional interface to the IDL Geopack
              implementation of the TA16 field model.

    Input:
              pos_gsm_tvar: the tplot variable storing the position in
                  gsm coordinates

    Keywords:
             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

             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

             symh(optional): Sym-H index (nT),
                 longitudinal symmetric component of the ring current;
                 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): sliding average of Sym-H over 30-min interval,
                 centered on the current time moment.
                 Either symh or symc must be provided.
                 symc can be computed from symh using GEOPACK_GETSYMHC
                 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

             xind(optional)

             parmod(optional): can input the Nx10 parmod array used by the
                 fortran Tsyganenko model instead of inputing parameters as
                 separate arrays. If passed as a raw array it will not be
                 modified or interpolated so be sure its has the correct
                 number of entries. It can also be passed as a tplot variable
                 name in which case it will be interpolated. If values are
                 passed individually and as par, the par values will be overwritten.

             period(optional): the amount of time between recalculations of
                 geodipole tilt in seconds(default: 60)  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+'_bta16') 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

             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
            4. either the variables setting parmod or the variables
                setting the individual parameter arrays should be set because
                the defaults aren't scientifically accurate
            5. model parameters that are input as tplot variables they
                will be interpolated to match the time values on the input
                position

      See Newell 2007 for details:
      https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2006JA012015

      TA16 model description:
      https://geo.phys.spbu.ru/~tsyganenko/empirical-models/magnetic_field/ta16
      https://agupubs.onlinelibrary.wiley.com/doi/full/10.1002/2016JA023217

      The N-index calculation is implemented in omni2nindex.pro

     $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/ta16/tta16.pro $

(See external/IDL_GEOPACK/ta16/tta16.pro)