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

Last modified: Thu Sep 11 18:17:40 2025.

# Directory Listing of Routines

# projects/themis/state

- THM_AUTOLOAD_SUPPORT
  given a THEMIS tplot variable name, check to see if spin period and
- THM_INTERPOLATE_STATE
- THM_LOAD_SLP
- THM_LOAD_SSC
- THM_LOAD_STATE
- THM_LOAD_STATE2
- THM_LOAD_STATE3
- THM_LOAD_STATE_RELPATH
  Alternate relpathname routine for L1 state data, allows for different
- THM_SPIN_PHASE
- THM_SUNPULSE

# Routine Descriptions

## THM_AUTOLOAD_SUPPORT

[Next Routine] [List of Routines]

    NAME:
     thm_autoload_support
    PURPOSE:
     given a THEMIS tplot variable name, check to see if spin period and
     phase exist, for coordinate transformations, If they do not, load
     the state data for the appropriate time period
    CALLING SEQUENCE:
     thm_autoload_support, vname=vname, spinmodel=spinmodel, spinaxis=spinaxis, slp=slp, probe_in=probe,
         trange=[tmin, tmax], history_out=hist_string
    INPUT:
    OUTPUT:
    KEYWORDS:
     vname = tplot variable name
     probe_in: Specifies the probe name to load support data for (required
               for /spinmodel and /spinaxis)
     spinmodel: if set to 1, ensure spinmodel data is loaded and covers the
               requested time interval
     spinaxis: if set to 1, ensure state (spinras, spindec) data is loaded and
               covers the requested time interval
     slp:  if set, ensure sun & moon data are loaded and cover the requested
           time interval
     trange: Specify a time range for which support data should be loaded
            (required if vname is not supplied)
     history_out = a history string, if data needs loading
    HISTORY:
     2013-12-19: Adapted from thm_ui_check4spin by jwl

     NOTES:

    $LastChangedBy: jwl $
    $LastChangedDate: 2021-06-29 16:13:26 -0700 (Tue, 29 Jun 2021) $
    $LastChangedRevision: 30093 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_autoload_support.pro $

(See projects/themis/state/thm_autoload_support.pro)

## THM_INTERPOLATE_STATE

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

    function: thm_interpolate_state

    Purpose: interpolates the low res STATE file

             all variables are structures as produced by get_data

    keywords:

    Examples:
          tha_spinper_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_spinper=thx_spinper) --> linear interpolation
          tha_spinphase_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_spinper=thx_spinper,thx_spinphase=thx_spinphase) --> phase constructed according to the nearest neighbor spin phase, spin period
          tha_spinras_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_spinras=thx_spinras) --> linear interpolation
          tha_spindec_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_spindec=thx_spindec) --> linear interpolation
          tha_spinalpha_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_spinalpha=thx_spinalpha) --> linear interpolation
          tha_spinbeta_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_spinbeta=thx_spinbeta) --> linear interpolation
          tha_pos_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_pos=thx_pos) --> spline interpolation
          tha_vel_highres=thm_interpolate_state(thx_xxx_in=thx_xxx_in,thx_vel=thx_vel) --> spline interpolation

    Notes: under construction!!

    Written by Hannes Schwarzl
     $LastChangedBy: pcruce $
     $LastChangedDate: 2013-06-13 17:51:42 -0700 (Thu, 13 Jun 2013) $
     $LastChangedRevision: 12531 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_interpolate_state.pro $

(See projects/themis/state/thm_interpolate_state.pro)

## THM_LOAD_SLP

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

    Procedure: THM_LOAD_SLP,
     thm_load_slp, datatype = datatype, trange = trange, $
                    verbose = verbose, $
                    varname_out = varname_out, $
                    downloadonly = downloadonly, $
                    no_download=no_download,
                    relpathnames_all=relpathnames_all,$
                    files=files,$
                    valid_names = valid_names,$
                    suffix=suffix

    Purpose:
      Loads Solar and Lunar Ephemeris data from a CDF.

      1. Data is generated using the JPL SPICE/ICY library.  Extensive documentation
      can be found on the SPICE/ICY website:
      http://naif.jpl.nasa.gov/pub/naif/toolkit_docs/IDL/req/index.html

      2. All quantities are in GEI coordinates. GEI Epoch is True of Date(this
      is the THEMIS standard).

      3. All data have abberational corrections for light time and stellar abberation.
      Thus the data represent the state of the Moon and the Sun as they would be
      observed on earth at a particular time. A more detailed discussion of this topic
      can be found in the SPICE/ICY 'SPK' required reading document. The SPICE/ICY
      abberation used is called 'LT+S'.

      4. GEI True of Date are not built into SPICE/ICY.  A custom kernel is used when
      generating these data that accounts for earth precession using the IAU_1976
      precessional model and accounts for earth nutation using the IAU_1980 nutational
      model which are built into SPICE/ICY.

      The quantities returned and their descriptions follow.

      1. slp_sun_pos:    Sun position X,Y,Z in km.

      2. slp_sun_vel:    Sun velocity X,Y,Z in km/sec.

      3. slp_sun_att_x:  IAU_SUN coordinate system X-axis(X,Y,Z).  (unitless/normalized)
                         A. This axis lies in the Solar equatorial plane and the plane containing the Solar prime meridian
                         B. This axis points towards a fixed point on the solar surface and rotates with the sun.
                         C. This axis rotates with sidereal rotation period of the sun.~24.47 days.
                         D. This quantity created by rotation the basis vector [1,0,0] from IAU_SUN
                         into GEI coordinate orientation.
                         E.  While this quantity is oriented relative to the GEI coordinate system, it is not technically earth centered.  Only
                         the rotational component of the transformation is performed, not the translation into earth-center.
                         F.  slp_sun_att_z and slp_sun_att_x are orthognal axes, thus
                         slp_sun_att_y = slp_sun_att_z x slp_sun_att_x, and this set of axes can be used to
                         transform between GEI and IAU_SUN coordinates

      4. slp_sun_att_z:  IAU_SUN coordinate system Z-axis(X,Y,Z). (unitless/normalized)
                         A.  This axis points in the direction of the mean rotational axis of the sun.
                         B. This quantity created by rotation the basis vector [0,0,1] from IAU_SUN
                         into GEI coordinate orientation.
                         C. While this quantity is oriented relative to the GEI coordinate system, it is not technically earth centered.  Only
                         the rotational component of the transformation is performed, not the translation into earth-center.
                         D.  slp_sun_att_z and slp_sun_att_x are orthognal axes, thus
                         slp_sun_att_y = slp_sun_att_z x slp_sun_att_x, and this set of axes can be used to
                         transform between GEI and IAU_SUN coordinates

      5. slp_sun_ltime:  The time, in seconds, it takes for light to travel from the sun to the earth at the time of observation..
                         To translate data from light corrected to uncorrected data subtract these corrections from the data times.

      6. slp_lun_pos:    Lunar position X,Y,Z in km.

      7. slp_lun_pos:    Lunar velocity X,Y,Z in km/s.

      8. slp_lun_att_x:  IAU_MOON coordinate system X-axis (X,Y,Z)
                         A.  This axis lies in the Lunar equatorial plane and the plane containing the Lunar prime meridian
                         B.  This axis points towards a fixed point on the moon's surface and rotates with the moon.
                         C.  This quantity created by rotation the basis vector [0,0,1] from IAU_MOON
                         into GEI coordinate orientation..
                         D.  While this quantity is oriented relative to the GEI coordinate system, it is not technically earth centered.  Only
                         the rotational component of the transformation is performed, not the translation into earth-center.
                         E.  slp_lun_att_z and slp_lun_att_x are orthognal axes, thus
                         slp_lun_att_y = slp_lun_att_z x slp_lun_att_x, and this set of axes can be used to
                         transform between GEI and IAU_SUN coordinates
      9. slp_lun_att_z:  IAU_MOON coordinate system Z-axis(X,Y,Z). (unitless/normalized)
                         A.  This axis points in the direction of the mean rotational axis of the moon.
                         B.  This quantity created by rotation the basis vector [0,0,1] from IAU_MOON
                         into GEI coordinates.
                         C. While This quantity is in GEI coordinates, it is not technically earth centered.  Only
                         the rotational component of the transformation is performed, not the translation into earth-center.
                         D.  slp_lun_att_z and slp_;un_att_x are orthognal axes, thus
                         slp_lun_att_y = slp_lun_att_z x slp_lun_att_x, and this set of axes can be used to
                         transform between GEI and IAU_MOON coordinates.
     10. slp_lun_ltime:  The time, in seconds, it takes for light to travel from the moon to the earth at the time of observation.
                         To translate data from light corrected to uncorrected data subtract these corrections from the data times.

    keywords:
      datatype = The type of data to be loaded.  Allowed values are:
               'sun_pos','sun_vel','sun_att_x','sun_att_z','sun_ltime',
               'lun_pos','lun_vel','lun_att_x','lun_att_z','lun_ltime'
      TRANGE= (Optional) Time range of interest  (2 element array), if
              this is not set, the default is to prompt the user. Note
              that if the input time range is not a full day, a full
              day's data is loaded
       level = ignored, only one level for this datatype: L1
      /VERBOSE : set to output some useful info
      varname_out= a string array containing the tplot variable names for
                   the loaded data
      /downloadonly, if set, then only download the data, do not load it
                     into variables.
      /no_download: use only files which are online locally.
      relpathnames_all: named variable in which to return all files that are
              required for specified timespan, probe, datatype, and level.
              If present, no files will be downloaded, and no data will be loaded.
      files   named varible for output of pathnames of local files.
      /valid_names, if set, then this will return the valid site, datatype
                    and/or level options in named variables, for example,
                    thm_load_gmag, site = xxx, /valid_names
                    will return the array of valid sites in the
                    variable xxx
      suffix= suffix to add to output data quantity (not added to support data)

    Examples:
       timespan,'2007-03-23'
       thm_load_slp
       thm_load_slp,datatype='sun_pos',trange=['2007-01-22/00:00:00','2007-01-24/00:00:00']

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-12-21 11:50:27 -0800 (Fri, 21 Dec 2018) $
     $LastChangedRevision: 26397 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_load_slp.pro $

(See projects/themis/state/thm_load_slp.pro)

## THM_LOAD_SSC

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

     Procedure: thm_load_ssc

     Purpose:
       Load THEMIS current/past orbit data, and predicted data, from CDAWeb/SSCWeb (Satellite Situation Center).

     Keywords:
                 trange:       Standard time range of interest.
                 probes:       Probe names. This can be an array of strings, e.g., ['a', 'b']
                 predicted:    If set, it loads predicted data.
                 varformat:    Only load these variable names. If not set, load all.
                 downloadonly: Only download files, do not load them into tplot.
                 prefix:       Give this prefix to tplot variable names
                 suffix:       Give this suffix to tplot variable names
                 no_time_clip: Do not time clip tplot variables (not recommended because some files contain a year of data)
                 ssc_server:   (optional) URL of CDAWeb server.

     Returns:
                 tplotnames:   List of variables loaded into tplot

     Examples:
       thm_load_ssc, trange = ['2026-01-01', '2026-01-10'], probes=['a','b','c'], /predicted
       thm_load_ssc, trange = ['2016-01-01', '2016-01-10'], probes='e'

     $LastChangedBy: nikos $
     $LastChangedDate: 2024-09-27 15:53:46 -0700 (Fri, 27 Sep 2024) $
     $LastChangedRevision: 32864 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_load_ssc.pro $

(See projects/themis/state/thm_load_ssc.pro)

## THM_LOAD_STATE

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

    Procedure: THM_LOAD_STATE

    Purpose:  Loads THEMIS STATE (orbit and attitude) data

    ;keywords:
      probe = Probe name. The default is 'all', i.e., load all available probes.
              This can be an array of strings, e.g., ['a', 'b'] or a
              single string delimited by spaces, e.g., 'a b'
      datatype = The type of data to be loaded, can be an array of strings
              or single string separate by spaces.  The default is 'pos vel'
      TRANGE= (Optional) Time range of interest  (2 element array), if
              this is not set, the default is to prompt the user. Note
              that if the input time range is not a full day, a full
              day's data is loaded
      version = the version of the state file, one of 'v00', 'v01', 'v02', 'v03'.
                defaults to 'v01'
      level = the level of the data, the default is 'l1', or level-1
              data. A string (e.g., 'l2') or an integer can be used. 'all'
              can be passed in also, to get all levels.
      suffix= suffix to add to tplot variable names.  Note: this will get added
              support_data variables as well as regular data variables.
      CDF_DATA: named variable in which to return cdf data structure: only works
              for a single spacecraft and datafile name.
      VARNAMES: names of variables to load from cdf: default is all.
      /GET_SUPPORT_DATA: load support_data variables as well as data variables
                          into tplot variables.
      /DOWNLOADONLY: download file but don't read it.
      /no_download: use only files which are online locally.
      /NO_UPDATE: prevent contact to server if local file already exists.
      relpathnames_all: named variable in which to return all files that are
              required for specified timespan, probe, datatype, and level.
              If present, no files will be downloaded, and no data will be loaded.
      /valid_names, if set, then this routine will return the valid probe, datatype
              level, and version options in named variables supplied as
              arguments to the corresponding keywords.
      files   named varible for output of pathnames of local files.
      /VERBOSE  set to output some useful info
      coord: Can specify the coordinate system you would like data
      returned in.
      no_spin: if set, do not call thm_load_spin to load spinmodel data.

    Example:
       thm_load_state
    Notes:

    Modifications:
      If /GET_SUPPORT_DATA and ~/NO_SPIN, then call THM_LOAD_SPIN, W.M.Feuerstein,
        4/10/2008.
      Delete th?_spin* TPLOT variables after calling THM_LOAD_SPIN (as long as
        ~/KEEP_SPIN_DATA), add KEEP_SPIN_DATA kw, include a couple of (normally
        commented) lines to chck consistency of spinmodel, WMF, 4/10/08.

     coordinate systems of returned variables:
     *_pos : gei
     *_vel : gei
     *_ras : gei
     *_dec : gei
     *_alpha : spg
     *_beta : spg
     *_spinper : none(listed in dlimits as unknown)
     *_spinphase : none(listed in dlimits as unknown)
     *_roi : none(listed in dlimits as unknown)
     *_man : none(listed in dlimits as unknown)

     If you modify the d_names constant make sure to make the
     corresponding changes to the c_names constant

     $LastChangedBy: jwl $
     $LastChangedDate: 2023-04-03 12:28:04 -0700 (Mon, 03 Apr 2023) $
     $LastChangedRevision: 31701 $
     $URL $

(See projects/themis/state/thm_load_state.pro)

## THM_LOAD_STATE2

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

    Procedure: THM_LOAD_STATE2

    Purpose:  Loads THEMIS STATE (orbit and attitude) data

    ;keywords:
      probe = Probe name. The default is 'all', i.e., load all available probes.
              This can be an array of strings, e.g., ['a', 'b'] or a
              single string delimited by spaces, e.g., 'a b'
      datatype = The type of data to be loaded, can be an array of strings
              or single string separate by spaces.  The default is 'all'
      TRANGE= (Optional) Time range of interest  (2 element array), if
              this is not set, the default is to prompt the user. Note
              that if the input time range is not a full day, a full
              day's data is loaded
      version = the version of the state file, one of 'v01', 'v02', 'v03', 'v04'.
                defaults to 'v01'
      level = the level of the data, the default is 'l1', or level-1
              data. A string (e.g., 'l2') or an integer can be used. 'all'
              can be passed in also, to get all levels.
      CDF_DATA: named variable in which to return cdf data structure: only works
              for a single spacecraft and datafile name.
      VARNAMES: names of variables to load from cdf: default is all.
      /GET_SUPPORT_DATA: load support_data variables as well as data variables
                          into tplot variables.
      /DOWNLOADONLY: download file but don't read it.
      /valid_names, if set, then this routine will return the valid probe, datatype
              and/or level options in named variables supplied as
              arguments to the corresponding keywords.
      files   named varible for output of pathnames of local files.
      /VERBOSE  set to output some useful info
    Example:
       thm_load_state
    Notes:

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-12-21 11:50:27 -0800 (Fri, 21 Dec 2018) $
     $LastChangedRevision: 26397 $
     $URL $

(See projects/themis/state/thm_load_state2.pro)

## THM_LOAD_STATE3

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

    Procedure: THM_LOAD_STATE2

    Purpose:  Loads THEMIS STATE (orbit and attitude) data

    ;keywords:
      probe = Probe name. The default is 'all', i.e., load all available probes.
              This can be an array of strings, e.g., ['a', 'b'] or a
              single string delimited by spaces, e.g., 'a b'
      datatype = The type of data to be loaded, can be an array of strings
              or single string separate by spaces.  The default is 'all'
      TRANGE= (Optional) Time range of interest  (2 element array), if
              this is not set, the default is to prompt the user. Note
              that if the input time range is not a full day, a full
              day's data is loaded
      version = the version of the state file, one of 'v01', 'v02', 'v03', 'v04'.
                defaults to 'v01'
      level = the level of the data, the default is 'l1', or level-1
              data. A string (e.g., 'l2') or an integer can be used. 'all'
              can be passed in also, to get all levels.
      CDF_DATA: named variable in which to return cdf data structure: only works
              for a single spacecraft and datafile name.
      VARNAMES: names of variables to load from cdf: default is all.
      /GET_SUPPORT_DATA: load support_data variables as well as data variables
                          into tplot variables.
      /DOWNLOADONLY: download file but don't read it.
      /valid_names, if set, then this routine will return the valid probe, datatype
              and/or level options in named variables supplied as
              arguments to the corresponding keywords.
      files   named varible for output of pathnames of local files.
      /VERBOSE  set to output some useful info
    Example:
       thm_load_state
    Notes:

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-12-21 11:50:27 -0800 (Fri, 21 Dec 2018) $
     $LastChangedRevision: 26397 $
     $URL $

(See projects/themis/state/thm_load_state3.pro)

## THM_LOAD_STATE_RELPATH

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

    NAME:
    thm_load_state_relpath
    PURPOSE:
    Alternate relpathname routine for L1 state data, allows for different
    relpath from SPDF directory with v0? in the final relpathname
    CALLING SEQUENCE:
    relpathnames = thm_load_state_relpath(sname = sname, filetype =
                                          filetype, level = level, $
                                          version = version, $
                                          trange = trange, $
                                          addmaster = addmaster)
    INPUT:
     sname = probe, one of ['a','b','c','d','e']
     filetype = 'state' -> this keyword is only defined here due to the
                interface to thm_load_xxx
     level = 'l1'  -> this keyword is only defined here due to the
                interface to thm_load_xxx
     version = '0','1','2','3' or '?' The default is to not have a
               version number, and this keyword is not used
     trange = the timerange
     relpathnames_local = the fullpath of the file as it will be saved
                          locally, this is an output keyword
    OUTPUT:
     relpathnames = the full path of the files relative to the local
                    and remote data directories.
    HISTORY:
     April 1, 2010, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jwl $
     $LastChangedDate: 2025-03-29 21:54:31 -0700 (Sat, 29 Mar 2025) $
     $LastChangedRevision: 33212 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_load_state_relpath.pro $

(See projects/themis/state/thm_load_state_relpath.pro)

## THM_SPIN_PHASE

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

    NAME:
      thm_spin_phase
    Purpose:
      Use sunpulse data produced by thm_sunpulse to get spinphase at abitrary times
    Input Parameters:
          time_dat: double precision array: times of data points at which
                    interpolates are desired.
    Output Parameters:
       spinpha_int: interpolated spin phase
    Keywords:
             Probe: a single probe name. e.g. 'a'
            suffix: suffix on tplot variable (thx_state_sunpulse[_suffix])

    Optional Input Parameters (If not present, then state data will be
       loaded from standard state tplot variables, using probe keyword)
          sunpulse: double precision array: times of sunpulses
      sunp_spinper: spin period at each sunpulse time

    K. Bromund, SPSystems/NASA/GSFC, May 2007
    $LastChangedBy: aaflores $
    $LastChangedDate: 2012-02-13 14:41:42 -0800 (Mon, 13 Feb 2012) $
    $LastChangedRevision: 9728 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_spin_phase.pro $

(See projects/themis/state/thm_spin_phase.pro)

## THM_SUNPULSE

[Previous Routine] [List of Routines]

    NAME:
      thm_sunpulse
    Purpose:
      Interpolate spin phase to have same time resolution as time_dat
    Keyword:
             probe: string indicating probe.  Array of strings, or a string
                    like 'a b'.  Not used if positional parameters are present.
            suffix: suffix to add to default tplot name in which to store sunpulse
                    data: thx_state_sunpulse (x = probe letter designation)
                    This suffix is expected on the names of the state data inputs.
    Optional Inputs/Output parameters:
    (if not present, then standard state tplot variable names will be used for i/o)
      Input Parameters:
        time_state: double precision array: times of data from state file
           spinpha: spin phase from state file
           spinper: spin period from state file
      Output Parameters:
          sunpulse: sunpulse times (times of zero spin phase)
      sunp_spinper: spin period at time of each sunpulse.

    Keywords:
     sunpulse_name: string.  If present, store sunpulse/spinperiod in tplot
                    variable with this name.  Has no effect if probe keyword
                    is provided.

    Notes:

     Written by K. Bromund, SPSystems/NASA/GSFC, May 2007
    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-04-30 15:28:49 -0700 (Thu, 30 Apr 2015) $
    $LastChangedRevision: 17458 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/state/thm_sunpulse.pro $

(See projects/themis/state/thm_sunpulse.pro)