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', 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. 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): Minimum trace distance in RE. RLIM(optional): Maximum trace distance in RE (default 60 RE) 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. 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: 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: egrimes $ $LastChangedDate: 2014-03-31 08:53:44 -0700 (Mon, 31 Mar 2014) $ $LastChangedRevision: 14708 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/external/IDL_GEOPACK/trace/trace2equator.pro $