This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
NAME:
CORRECT_DELTA_PHI_TENSOR.PRO
PURPOSE:
Apply eclipse delta_phi corrections to L1 MOM tensor quantities.
CATEGORY:
TDAS
CALLING SEQUENCE:
correct_delta_phi_tensor, tens=mflux, delta_phi=delta_phi
INPUTS:
OUTPUTS:
KEYWORDS:
tens: An Nx6 input array representing the xx,yy,zz,xy,xz,yz
components of a 3x3 matrix. (The other three elements
are implied by symmetry.) The data is modified in place.
delta_phi: An array of delta_phi correction values, in degrees.
The sample counts of tens and delta_phi must match.
PROCEDURE:
For each sample: construct a 3-d rotation matrix corresponding
to a delta_phi degree counterclockwise rotation about the
DSL-Z axis. Construct a 3x3 matrix from the 6-element tensor
sample. Apply the rotation by performing matrix multiplication:
transpose(rotation) # tensor # rotation
Then strip the redundant terms of the result, yielding a
modified 6-element representation of the original tensor.
EXAMPLE:
(See projects/themis/spin/correct_delta_phi_tensor.pro)
NAME:
CORRECT_DELTA_PHI_VECTOR.PRO
PURPOSE:
CATEGORY:
TDAS
CALLING SEQUENCE:
correct_delta_phi_vector,tvar=thb_fgs_dsl,delta_phi=delta_phi
INPUTS:
OUTPUTS:
KEYWORDS:
tvar: name of an input tplot variable containing 3-d vectors in DSL.
The data will be altered in place.
x_in, y_in: Input data with X and Y in separate arrays. Output
goes to variables specified with the x_out and y_out keywords.
xyz_in: Input data with x,y,z in a single array. Data will be
altered in place.
delta_phi: Array of delta_phi values, in degrees. The sample
count must match the sample count of the data being transformed.
PROCEDURE:
Given a tplot variable name or array(s) of data values (in DSL coordinates),
and an array of delta_phi values, apply a counter-clockwise rotation of
delta_phi degrees. This is used to apply the eclipse delta_phi corrections
obtained from the spin model, and is intended for correcting spin fits (efs
and fgs), and (3-vector) particle moments. Waveform data
does not require this correction. Some of the quantities
from L1 MOM are tensors, and should not be corrected with this
routine -- see correct_delta_phi_tensor.
(See projects/themis/spin/correct_delta_phi_vector.pro)
NAME:
SEGMENT_INTERP_T
PURPOSE:
Performs interpolation on individual elements. (Now a vectorized implementation, accepts multiple inputs)
CATEGORY:
TDAS
CALLING SEQUENCE:
segment_interp_t,segments,t,spincount,t_last,spinphase,spinper,segflag,eclipse_delta_phi
INPUTS:
segments: Segment struct from spinmodel
t: target time array for interpolation(number of elements must match segments)
OUTPUTS:
spincount,t_last,spinphase,segflag,eclipse_delta_phi
KEYWORDS:
mask=Set to mask value or array of mask value(with same number of elements as segments)
PROCEDURE:
EXAMPLE:
$LastChangedBy: bsadeghi $
$LastChangedDate: 2012-05-22 10:48:29 -0700 (Tue, 22 May 2012) $
$LastChangedRevision: 10447 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spin/segment_interp_t.pro $
(See projects/themis/spin/segment_interp_t.pro)
NAME:
SEGMENT_TEST.PRO
PURPOSE:
Check a spinmodel segment structure to ensure that the model parameters
b and c are consistent with the start and end times and
spin counts
CATEGORY:
TDAS
CALLING SEQUENCE:
segment_test,probe,segment,result
INPUTS:
probe: A single character probe letter (only used in output messages).
segment: A spinmodel_segment structure.
OUTPUTS:
result: 0 for failure, 1 for success
KEYWORDS:
None.
PROCEDURE:
Calls segment_interp_t to get spin count and spin phase at
segment start/end times.
Calls segment_interp_n to get sun pulse times of segment
start/end counts.
Cross check results of segment_interp_t and segment_interp_n,
verifying that interp_t and interp_n results are consistent
within modest tolerances (100 usec for times, 0.1 deg for
phase angles).
Check maxgap field against 4-hour threshold; large gaps are
likely a result of missing data.
EXAMPLE:
mptr=spinmodel_get_ptr('a')
sptr=(*mptr).segs_ptr
segment_test,'a',(*sptr)[0],result
Written by: Jim Lewis (jwl@ssl.berkeley.edu)
Change Date: 2007-10-08
(See projects/themis/spin/segment_test.pro)
NAME:
SPINMODEL_FINDSEG_T
PURPOSE:
Finds indexes of spin model segments matching each time.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel_findseg_t,mptr,t
INPUTS:
mptr: pointer to spin model
t: array of times to which model segments will be matched
RETURNS:
an array of matching indexes. Throws error using 'message' routine on failure.
PROCEDURE:
EXAMPLE:
$LastChangedBy: pcruce $
$LastChangedDate: 2010-10-25 13:18:23 -0700 (Mon, 25 Oct 2010) $
$LastChangedRevision: 7885 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spin/spinmodel_findseg_t.pro $
(See projects/themis/spin/spinmodel_findseg_t.pro)
NAME:
SPINMODEL_FINDSEG_T
PURPOSE:
Finds indexes of spin model segments matching each time.
CATEGORY:
TDAS
CALLING SEQUENCE:
model->spinmodel_findseg_t,t
INPUTS:
model: spin model, reference to object of type 'thm_spinmodel'
t: array of times to which model segments will be matched
RETURNS:
an array of matching indexes. Throws error using 'message' routine on failure.
PROCEDURE:
EXAMPLE:
$LastChangedBy: jwl $
$LastChangedDate: 2011-05-09 11:16:41 -0700 (Mon, 09 May 2011) $
$LastChangedRevision: 8651 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spin/thm_spinmodel__findseg_t.pro $
(See projects/themis/spin/thm_spinmodel__findseg_t.pro)
NAME:
SPINMODEL_GET_INFO.PRO
PURPOSE:
Given a probe string or spinmodel pointer, return information
about the valid time range or shadow times.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel_get_info,model=modelptr,min_shadow_duration=min_shadow_duration,$
shadow_count=shadow_count, $
shadow_start=shadow_start,shadow_end=shadow_end,$
start_time=start_time, end_time=end_time
INPUTS:
Model: pointer to s spinmodel structure
Probe: a string identifying the probe.
The caller must specify either a model pointer or probe string.
min_shadow_duration: Optional parameter specifying the minimum
gap between BAU sun sensor crossing times to be considered a shadow
interval. Defaults to 60.0 sec.
OUTPUTS: (all optional)
shadow_count: Number of shadow intervals found.
shadow_start: Double precision array of shadow start times.
shadow_end: Double precision array of shadow end times.
start_time: Double precision scalar indicating start time
of loaded spinmodel data
end_time: Double precision scalar indicating end time of
loaded spinmodel data
PROCEDURE:
Shadow intervals consist of spinmodel segments where the
"maxgap" parameter exceeds the min_shadow_duration threshold.
Start time is the start time of the first segment.
End time is the end time of the last segment.
If no spinmodel data is loaded for the requested probe,
start_time = end_time = 0.0D.
If no shadows are found, shadow_count is set to zero and
no start/end times are returned.
EXAMPLE:
timespan,'2007-03-23',1,/days
thm_load_state,probe='a',/get_support_data
spinmodel_get_info,probe='a',shadow_count=shadow_count,$
shadow_start=shadow_start, shadow_end=shadow_end,$
start_time=start_time,end_time=end_time
(See projects/themis/spin/spinmodel_get_info.pro)
NAME:
SPINMODEL_GET_PTR.PRO
PURPOSE:
Returns a pointer to the spin model, specified by a single
letter probe designation ('a' through 'f'). This is to avoid
having to define the spinmodel common block all over the place.
CATEGORY:
TDAS
CALLING SEQUENCE:
model_ptr=spinmodel_get_ptr('a')
INPUTS:
probe: A scalar character, one of 'a' through 'f', specifying which model
pointer to return.
OUTPUTS:
model_ptr: The return value is a pointer to the specified spin model,
suitable for passing to the other spinmodel manipulation routines.
KEYWORDS:
None.
PROCEDURE:
Test probe argument for validity; return appropriate value from
the spinmodel_common block.
EXAMPLE:
model_ptr=spinmodel_get_ptr('a')
spinmodel_test,model_ptr
Written by: Jim Lewis (jwl@ssl.berkeley.edu)
Change Date: 2007-10-08
(See projects/themis/spin/spinmodel_get_ptr.pro)
NAME:
SPINMODEL_INTERP_N.PRO
PURPOSE:
Given a spin model and spin count (or array of counts), calculate
the sun pulse time and spin period at each input count.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel_interp_n,model=modelptr,count=input_counts,$
time=output_times, spinper=output_spinper
INPUTS:
Model: pointer to a spinmodel structure
Count: A long integer (or long integer array) specifying the spin
count to use. If the input is a scalar, all outputs
will be scalars; otherwise, all outputs are arrays having
the same size as the input counts.
OUTPUTS:
spinper: Optional keyword parameter to receive spin period values.
time: Optional keyword parameter to receive sun pulse time
of each input count.
KEYWORDS:
/MODEL: Required input keyword argument, specifying a pointer to a
spinmodel structure.
/COUNT: Required input keyword argument specifying a time or array of times.
/SPINPER: Optional keyword argument to receive spin period values.
/TIME: Optional keyword argument to receive sun pulse times.
PROCEDURE:
Find the spinmodel segment containing the input spin count.
Invert phi(t) function to find time corresponding to this count.
Use b and c segment parameters to determine the spin period
at the sunpulse time.
EXAMPLE:
; Retrieve first 100 sun pulse times included in model for THA:
modelptr=spinmodel_get_ptr('a')
spinmodel_interp_n,model=modelptr,count=lindgen(100),time=output_times
(See projects/themis/spin/spinmodel_interp_n.pro)
NAME:
SPINMODEL_INTERP_N.PRO
PURPOSE:
Given a spin model and spin count (or array of counts), calculate
the sun pulse time and spin period at each input count.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel->interp_n,count=input_counts,$
time=output_times, spinper=output_spinper
INPUTS:
Count: A long integer (or long integer array) specifying the spin
count to use. If the input is a scalar, all outputs
will be scalars; otherwise, all outputs are arrays having
the same size as the input counts.
OUTPUTS:
spinper: Optional keyword parameter to receive spin period values.
time: Optional keyword parameter to receive sun pulse time
of each input count.
KEYWORDS:
/COUNT: Required input keyword argument specifying a time or array of times.
/SPINPER: Optional keyword argument to receive spin period values.
/TIME: Optional keyword argument to receive sun pulse times.
PROCEDURE:
Find the spinmodel segment containing the input spin count.
Invert phi(t) function to find time corresponding to this count.
Use b and c segment parameters to determine the spin period
at the sunpulse time.
EXAMPLE:
; Retrieve first 100 sun pulse times included in model for THA:
modelptr=spinmodel_get_ptr('a')
spinmodel_interp_n,model=modelptr,count=lindgen(100),time=output_times
(See projects/themis/spin/thm_spinmodel__interp_n.pro)
NAME:
SPINMODEL_INTERP_T.PRO
PURPOSE:
Given a spin model and time (or array of times), calculate
the spin count, spin phase, spin period, and time of last sun pulse
for each input time.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel_interp_t,model=modelptr,time=input_times,$
spincount=output_spincount, spinper=output_spinper,$
t_last=output_sun_pulse_times, eclipse_delta_phi=delta_phi
INPUTS:
Model: pointer to s spinmodel structure
Time: A double precision scalar or array specifying the input times.
If the input is a scalar, all outputs will be scalars; otherwise,
all outputs are arrays having the same size as the input times.
OUTPUTS:
spinper: Optional keyword parameter to receive spin period values.
tlast: Optional keyword parameter to receive sun pulse time
immediately preceding each input time.
spincount: Optional keyword parameter to receive count of spins
since the start of the model.
spinphase: Optional keyword parameter to receive the spin phase
(ranging from 0.0 to 360.0 degrees) at each input time.
eclipse_delta_phi: Optional keyword parameter to receive
deviation (degrees) between the IDPU's spin model and
the sunpulse+fgm spin model. Zero in sunlight, non-zero
if in eclipse AND FGM "synthetic" sunpulses were used
when the spinmodel was created during L0->L1 processing.
KEYWORDS:
/MODEL: Required input keyword argument, specifying a pointer to a
spinmodel structure.
/TIME: Required input keyword argument specifying a time or array of times.
/SPINPER: Optional keyword argument to receive spin period values.
/T_LAST: Optional keyword argument to receive sun pulse times
/SPINCOUNT: Optional keyword argument to receive spin counts
/SPINPHASE: Optional keyword argument to receive spin phase
PROCEDURE:
Find the spinmodel segment containing the input time.
Use b and c segment parameters to determine the spin period,
spin phase, and spin count at each input time
Invert phi(t) function to find sun pulse time immediately preceding
each input time.
EXAMPLE:
; Assume 'input_times' and 'input_spinphase' already exist as a
; IDL variables -- perhaps obtained from thm_load_state.
;
; Get a pointer to the spin model for probe A
modelptr=spinmodel_get_ptr('a')
; Calculate spin phase at each time from spin model
spinmodel_interp_t,model=modelptr,time=input_times,spinphase=output_spinphase
; Calculate spinphase differences between spin model and state
phi_diff=output_spinphase-input_spinphase
; Fix wraparounds
i=where(phi_diff GT 180.0D)
i2=where(phi_diff LT -180.0D)
phi_diff[i] = phi_diff[i] - 360.0D
phi_diff[i2] = phi_diff[i2] + 360.0D
Plot results
plot,input_times,phi_diff
(See projects/themis/spin/spinmodel_interp_t.pro)
NAME:
SPINMODEL_INTERP_T.PRO
PURPOSE:
Given a spin model and time (or array of times), calculate
the spin count, spin phase, spin period, and time of last sun pulse
for each input time.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel->interp_t,time=input_times,$
spincount=output_spincount, spinper=output_spinper,$
t_last=output_sun_pulse_times, segflag=output_segflag, eclipse_delta_phi=delta_phi
INPUTS:
Time: A double precision scalar or array specifying the input times.
If the input is a scalar, all outputs will be scalars; otherwise,
all outputs are arrays having the same size as the input times.
OUTPUTS:
spinper: Optional keyword parameter to receive spin period values.
tlast: Optional keyword parameter to receive sun pulse time
immediately preceding each input time.
spincount: Optional keyword parameter to receive count of spins
since the start of the model.
spinphase: Optional keyword parameter to receive the spin phase
(ranging from 0.0 to 360.0 degrees) at each input time.
eclipse_delta_phi: Optional keyword parameter to receive
deviation (degrees) between the IDPU's spin model and
the sunpulse+fgm spin model. Zero in sunlight, non-zero
if in eclipse AND FGM "synthetic" sunpulses were used
when the spinmodel was created during L0->L1 processing.
KEYWORDS:
/TIME: Required input keyword argument specifying a time or array of times.
/SPINPER: Optional keyword argument to receive spin period values.
/T_LAST: Optional keyword argument to receive sun pulse times
/SPINCOUNT: Optional keyword argument to receive spin counts
/SPINPHASE: Optional keyword argument to receive spin phase
PROCEDURE:
Find the spinmodel segment containing the input time.
Use b and c segment parameters to determine the spin period,
spin phase, and spin count at each input time
Invert phi(t) function to find sun pulse time immediately preceding
each input time.
EXAMPLE:
; Assume 'input_times' and 'input_spinphase' already exist as a
; IDL variables -- perhaps obtained from thm_load_state.
;
; Get a pointer to the spin model for probe A
modelptr=spinmodel_get_ptr('a')
; Calculate spin phase at each time from spin model
model->interp_t,time=input_times,spinphase=output_spinphase
; Calculate spinphase differences between spin model and state
phi_diff=output_spinphase-input_spinphase
; Fix wraparounds
i=where(phi_diff GT 180.0D)
i2=where(phi_diff LT -180.0D)
phi_diff[i] = phi_diff[i] - 360.0D
phi_diff[i2] = phi_diff[i2] + 360.0D
Plot results
plot,input_times,phi_diff
(See projects/themis/spin/thm_spinmodel__interp_t.pro)
Function: spinmodel_post_process
Purpose: Performs post-load corrections on spinmodel data.
Notes: Somewhat finicky about data requirements. Will throw an error that
causes interpreter to halt unless the error is explicitly caught. Error's
will be returned in the SPINMODEL_POST_PROCESS message block.
If you find execution halted here and you aren't sure why, it is probably
because the state support data was not loaded.
This occurs most commonly because
1. there is no data available on this day, or
2. because of internet connection issues,
3. because the !themis.no_download flag is on.
$LastChangedBy: bsadeghi $
$LastChangedDate: 2012-05-22 10:48:29 -0700 (Tue, 22 May 2012) $
$LastChangedRevision: 10447 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spin/spinmodel_post_process.pro $
(See projects/themis/spin/spinmodel_post_process.pro)
NAME:
SPINMODEL_RESET.PRO
PURPOSE:
Free any data structures associated with the spin model for a
given probe or set of probes, and null out the spin model
pointer to prevent stale, previously loaded data from being
used erroneously.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel_reset,probe='a'
spinmodel_reset,probe='a b c'
spinmodel_reset,probe=['a','b','c']
spinmodel_reset,probe='*'
spinmodel_reset,probe='all'
INPUTS:
None.
OUTPUTS:
None.
KEYWORDS:
PROBE Specifies which probe or probes to reset.
PROCEDURE:
Parse value of PROBE keyword to see which models to reset;
for any specified model with existing data, free the data
and set the spinmodel pointer in the common block to null.
EXAMPLE:
Written by: Jim Lewis (jwl@ssl.berkeley.edu)
(See projects/themis/spin/spinmodel_reset.pro)
NAME:
SPINMODEL_TEST.PRO
PURPOSE:
Perform consistency checks on a spin model.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel_test,model_ptr
INPUTS:
model_ptr: A pointer to a spinmodel structure, obtained from the
spinmodel_common block or the spinmodel_get_ptr() function.
This input must be a scalar.
OUTPUTS:
Prints "PASS"/"FAIL" messages depending on outcome of tests.
KEYWORDS:
None.
PROCEDURE:
Validate model_ptr input argument.
Compare spin model capacity to actual number of segments.
Validate pointer to model segments.
Call segment_test on each model segment, check for any failures.
Examine boundaries of adjacent segments, making sure time and
spin_number endpoints are identical across each pair.
Exercise spinmodel_interp_n by retrieving modeled sun pulse
times by spin number.
Exercise spinmodel_interp_t by recalculating the spin count
and spin phase at each modeled sun pulse time.
Cross check results of spinmodel_interp_n and spinmodel_interp_t
to verify that the expected values are produced within
modest tolerances (allowable phase error .01 deg at each
modeled sun pulse time).
EXAMPLE:
model_ptr=spinmodel_get_ptr('a')
spinmodel_test,model_ptr
Written by: Jim Lewis (jwl@ssl.berkeley.edu)
Change Date: 2007-10-08
(See projects/themis/spin/spinmodel_test.pro)
Procedure: THM_LOAD_SPIN
Purpose: Loads THEMIS spin model parameters, performs some post-processing
of data loaded from the SPIN CDFs, and stashes the resulting spin model
in a common block.
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'
Flatsat data (probe 'f') is not returned unless explicitly
mentioned.
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
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_spin,probe=['a','b']
Written by: Jim Lewis (jwl@ssl.berkeley.edu)
Change Date: 2007-10-08
(See projects/themis/spin/thm_load_spin.pro)
NAME:
THM_SPINMODEL::GET_INFO.PRO
PURPOSE:
Return information about the valid time range or shadow times given
a spinmodel object reference.
CATEGORY:
TDAS
CALLING SEQUENCE:
spinmodel->get_info,min_shadow_duration=min_shadow_duration,$
shadow_count=shadow_count, $
shadow_start=shadow_start,shadow_end=shadow_end,$
start_time=start_time, end_time=end_time
INPUTS:
min_shadow_duration: Optional parameter specifying the minimum
gap between BAU sun sensor crossing times to be considered a shadow
interval. Defaults to 60.0 sec.
OUTPUTS: (all optional)
shadow_count: Number of shadow intervals found.
shadow_start: Double precision array of shadow start times.
shadow_end: Double precision array of shadow end times.
start_time: Double precision scalar indicating start time
of loaded spinmodel data
end_time: Double precision scalar indicating end time of
loaded spinmodel data
PROCEDURE:
Shadow intervals consist of spinmodel segments where the
"maxgap" parameter exceeds the min_shadow_duration threshold.
Start time is the start time of the first segment.
End time is the end time of the last segment.
If no spinmodel data is loaded for the requested probe,
start_time = end_time = 0.0D.
If no shadows are found, shadow_count is set to zero and
no start/end times are returned.
EXAMPLE:
timespan,'2007-03-23',1,/days
thm_load_state,probe='a',/get_support_data
spinmodel_get_info,probe='a',shadow_count=shadow_count,$
shadow_start=shadow_start, shadow_end=shadow_end,$
start_time=start_time,end_time=end_time
(See projects/themis/spin/thm_spinmodel__get_info.pro)
NAME: thm_spinmodel__define PURPOSE: define, construct, and destroy spinmodel objects
(See projects/themis/spin/thm_spinmodel__define.pro)