;+
;Function: t01
;
;Purpose:  generates an array of model magnetic field vectors from
;          a monotonic time series and an array of 3-d position
;          vectors
;
;Keywords:
;         tarray: N array representing the time series in seconds utc
;         rgsm_array: Nx3 array representing the position series in earth radii GSM
;         pdyn_array: Solar wind pressure (nanoPascals) 
;         dsti_array: DST index(nanoTeslas)
;         yimf_array: y component of the interplanetary magnetic field
;         zimf_array: z component of the interplanetary magnetic field
;         g1_array:  index describes solar wind conditions in the
;         previous hour
;         g2_array: index describes solar wind conditions in the
;         previous hour
;
;         period(optional): the amount of time between recalculations of
;             geodipole tilt in seconds(default: 60)  increase this
;             value to decrease run time
;         
;
;Returns: an Nx3 length array or -1L on failure
;
;Example:
;   mag_array = t01(time_array,pos_array,pdyn_array,dsti_array,yimf_array,zimf_array,g1_array,g2_array)
;   mag_array = t01(time_array,pos_array,pdyn_array,dsti_array,yimf_array,zimf_array,g1_array,g2_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 6374 km to convert them.
;  5.Find more documentation on the inner workings of the model,
;    any gotchas, and the meaning of the arguments at:
;    http://modelweb.gsfc.nasa.gov/magnetos/data-based/modeling.html
;    -or-
;    http://dysprosium.jhuapl.edu/idl_geopack/
;
;  6. Definition of G1 and G2 can be found at: 
;  http://modelweb.gsfc.nasa.gov/magnetos/data-based/Paper220.pdf
;  http://modelweb.gsfc.nasa.gov/magnetos/data-based/Paper219.pdf
;
; $LastChangedBy: pcruce $
; $LastChangedDate: 2008-01-15 16:13:22 -0800 (Tue, 15 Jan 2008) $
; $LastChangedRevision: 2266 $
; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/idl_socware/tags/tdas_5_00/external/IDL_GEOPACK/t01/t01.pro $
;-

function t01, tarray, rgsm_array,pdyn,dsti,yimf,zimf,g1,g2, period = period

  ;sanity tests, setting defaults

  if igp_test() eq 0 then return, -1L

  if not keyword_set(tarray) then begin 
    message, /continue, 'tarray must be set'
    return, -1L
  endif

  if not keyword_set(rgsm_array) then begin
    message, /continue, 'rgsm_array must be set'
    return, -1L
  endif
 
  if not keyword_set(pdyn) then begin
    message, /continue, 'pdyn must be set'
    return, -1L
  endif
  
  if not keyword_set(dsti) then begin
    message, /continue, 'dsti must be set'
    return, -1L
  endif

  if not keyword_set(yimf) then begin
    message, /continue, 'yimf must be set'
    return, -1L
  endif

  if not keyword_set(zimf) then begin
    message, /continue, 'zimf must be set'
    return, -1L
  endif

  if not keyword_set(g1) then begin
    message, /continue, 'g1 must be set'
    return, -1L
  endif

  if not keyword_set(g2) then begin
    message, /continue, 'g2 must be set'
    return, -1L
  endif

  if not keyword_set(period) then period = 60

  if period le 0. then begin
    message, /contiune, 'period must be positive'
    return, -1L
  endif

  t_size = size(tarray, /dimensions)

  pdyn_size = size(pdyn, /dimensions)

  dsti_size = size(dsti, /dimensions)

  yimf_size = size(yimf, /dimensions)

  zimf_size = size(zimf, /dimensions)

  g1_size = size(g1,/dimensions)

  g2_size = size(g2,/dimensions)

  r_size = size(rgsm_array, /dimensions)

  if n_elements(t_size) ne 1 then begin
    message, /continue, 'tarray has incorrect dimensions'
    return, -1L
  endif

  if n_elements(pdyn_size) ne 1 then begin
    message, /continue, 'pdyn_array has incorrect dimensions'
    return, -1L
  endif

  if n_elements(dsti_size) ne 1 then begin
    message, /continue, 'dsti_array has incorrect dimensions'
    return, -1L
  endif

  if n_elements(yimf_size) ne 1 then begin
    message, /continue, 'yimf_array has incorrect dimensions'
    return, -1L
  endif

  if n_elements(zimf_size) ne 1 then begin
    message, /continue, 'zimf_array has incorrect dimensions'
    return, -1L
  endif

  if n_elements(g1_size) ne 1 then begin
    message, /continue, 'g1_array has incorrect dimensions'
    return, -1L
  endif

  if n_elements(g2_size) ne 1 then begin
    message, /continue, 'g2_array has incorrect dimensions'
    return, -1L
  endif
  
  if n_elements(r_size) ne 2 || r_size[1] ne 3 then begin
    message, /continue, 'rgsm_array has incorrect dimensions'
    return, -1L
  endif

  if t_size[0] ne r_size[0] then begin
    message, /continue, 'number of times in tarray does not match number of positions in rgsm_array'
    return, -1L
  endif

  if pdyn_size[0] eq 0 then begin
      pdyn_array = replicate(pdyn,t_size)
  endif else if t_size[0] ne pdyn_size[0] then begin
      message, /continue, 'number of times in tarray does not match number of elements in pdyn_array'
      return, -1L
  endif else pdyn_array = pdyn

  if dsti_size[0] eq 0 then begin
      dsti_array = replicate(dsti,t_size)
  endif else if t_size[0] ne dsti_size[0] then begin
      message, /continue, 'number of times in tarray does not match number of elements in dsti_array'
      return, -1L
  endif else dsti_array = dsti

  if yimf_size[0] eq 0 then begin
      yimf_array = replicate(yimf,t_size)
  endif else if t_size[0] ne yimf_size[0] then begin
      message, /continue, 'number of times in tarray does not match number of elements in yimf_array'
      return, -1L
  endif else yimf_array = yimf

  if zimf_size[0] eq 0 then begin
      zimf_array = replicate(zimf,t_size)
  endif else if t_size[0] ne zimf_size[0] then begin
      message, /continue, 'number of times in tarray does not match number of elements in zimf_array'
      return, -1L
  endif else zimf_array = zimf

  if g1_size[0] eq 0 then begin
      g1_array = replicate(g1,t_size)
  endif else if t_size[0] ne g1_size[0] then begin
       message, /continue, 'number of times in tarray does not match number of elements in g1_array'
      return, -1L
  endif else g1_array = g1

  if g2_size[0] eq 0 then begin
      g2_array = replicate(g2,t_size)
  endif else if t_size[0] ne g2_size[0] then begin
       message, /continue, 'number of times in tarray does not match number of elements in g2_array'
      return, -1L
  endif else g2_array = g2

  ;defaults to NaN so it will plot properly in tplot and to prevent
  ;insertion of spurious default dindgen values
  out_array = make_array(r_size, /DOUBLE, VALUE = !VALUES.D_NAN)

  tstart = tarray[0]

  tend = tarray[t_size - 1L]

  i = 0L

  ts = time_struct(tarray)

  ct = (tend-tstart)/period

  period = long(period)

  parmod = dblarr(t_size, 10)

  parmod[*, 0] = pdyn_array
  
  parmod[*, 1] = dsti_array

  parmod[*, 2] = yimf_array

  parmod[*, 3] = zimf_array

  parmod[*, 4] = g1_array

  parmod[*, 5] = g2_array

  while i le ceil(ct) do begin

    ;find indices of points to be input this iteration
    idx1 = where(tarray ge tstart + i*period)
    idx2 = where(tarray le tstart + (i+1)*period)

    idx = ssl_set_intersection(idx1, idx2)

    if idx[0] ne -1L then begin 

      id = idx[0]

      ;recalculate geomagnetic dipole
      geopack_recalc, ts[id].year,ts[id].doy, ts[id].hour, ts[id].min, ts[id].sec, tilt = tilt

      rgsm_x = rgsm_array[idx, 0]
      rgsm_y = rgsm_array[idx, 1]
      rgsm_z = rgsm_array[idx, 2]

      ;calculate internal contribution
      geopack_igrf_gsm,rgsm_x, rgsm_y, rgsm_z, igrf_bx, igrf_by,igrf_bz 

      ;calculate external contribution
      ;iopt = kp+1
      geopack_t01, parmod[id, *], rgsm_x, rgsm_y, rgsm_z, t01_bx, t01_by, t01_bz, tilt = tilt

      ;total field
      out_array[idx, 0] = igrf_bx + t01_bx
      out_array[idx, 1] = igrf_by + t01_by
      out_array[idx, 2] = igrf_bz + t01_bz

    endif

    i++

  endwhile

return, out_array

end