[Previous]
[Next]
NAME:
t3d_oblique
PURPOSE:
Implements 3D transformation matrix for oblique projections
CATEGORY:
gen/idl/math
CALLING SEQUENCE:
t3d_oblique, Array, /reset, oblique=oblique
INPUTS:
Array array[4,4]; type: any
Matrix used as the starting transformation.
If omitted !P.T is used; not used if /reset is set.
OPTIONAL INPUTS:
/reset if set start out with the identity matrix
matrix=matrix
if set to a named variable, the result is returned in this
parameter and !P.T is not modified.
oblique=oblique
A two-element vector of oblique projection parameters.
Points are projected onto the XY plane at Z=0 as follows:
x' = x + z(d COS(a)), and y' = y + z(d SIN(a)).
where oblique[0] = d, and oblique[1] = a.
OUTPUTS:
!P.T unless the keyword MATRIX is supplied, in which case the result
is returned in MATRIX and !P.T is not affected.
CALLED BY:
setup3d
SIDE EFFECTS:
!P.T is changed if the keyword MATRIX is not set.
PROCEDURE:
Modidifies the oblique projection in IDL t3d.pro by settinr
r[2,2] = 1.0 instead of 0.0
This preserves the z-component in an oblique projection.
MODIFICATION HISTORY:
JUN-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TagArray
PURPOSE:
(First check whether the IDL functions strjoin and/or
STRSPLIT can do what you need)
Combine string arrays into single string separated by
separator character, or v.v.
CATEGORY:
Toolbox: generic
CALLING SEQUENCE:
R = TagArray(tag, sep [,/nonull, /split])
INPUTS:
tag scalar, array; type: string
if scalar, or /split keyword set:
the string is decomposed into elements separated by the
'sep' character(s). The result is returned as a string array
with one dimension more than the input array: the leading
dimension is the number of tags found (see RESTRICTIONS).
if array: the elements in the array are
concatenated, separated by the 'sep' character
OPTIONAL INPUT PARAMETERS:
sep scalar, or array; type: 1-char string: default is a scalar and depends on OS
if /split is used then 'sep' can be an array of 1-char separator strings
/nonull if extracting tags, discard null-string tags
/split if 'tag' is an array that needs to be decomposed then
split needs to be set (by default, arrays are
concatenated; a scalar is always decomposed, even
if /split is not set).
OUTPUTS:
R either a string array of tags, or a scalar string
of concatenated tags.
CALLS: ***
InitVar, IsType
CALLED BY:
TimeSplit
RESTRICTIONS:
If keyword /split is set than the first elements in the 'tag' array is analyzed
for the presence of separators. The result is applied to all strings. So all
strings in 'tag' must have the same structure: same length and separators in the
same positions.
SIDE EFFECTS:
Note that an array[1] is treated differently from a scalar.
An array[1] is returned unmodified as a scalar
it is NOT decomposed if it contains 'sep' characters.
EXAMPLE:
t = tagarray('1998:337:23:53.000',[':','.']
results in:
t =['1998','337','23','53','000']
PROCEDURE:
The default separator is a comma on 'Win32', a colon on 'linux'
On other OS it is a colon (as on linux).
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
thomson_common
PURPOSE:
Contains common block definition used by
Thomson scattering functions
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
@thomson_common.pro
INCLUDED BY:
ThomsonLOSDensity, ThomsonSetupLOS
PROCEDURE:
MODIFICATION HISTORY:
JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
Thomson_doc
PURPOSE:
Documentation only. Collects all links to the Thomson scattering
package and a link to a pdf with additional information.
CATEGORY:
Documentation
SEE ALSO:
ThomsonBase, ThomsonBrightness, ThomsonElectron, ThomsonElectronFar
ThomsonLOSDensity, ThomsonLOSFar, ThomsonLOSRomb, ThomsonLOSStep
ThomsonMidpoint, ThomsonMidpointFar, ThomsonMidpointFnc, ThomsonPDistance
ThomsonPDistanceFar, ThomsonRadialFilter, ThomsonS10, ThomsonSetupLOS
ThomsonSetupRomb, ThomsonSolarFlux, ThomsonSoup, ThomsonTang, ThomsonTangMRad
thomson_common
PROCEDURE:
See http://supercat.ucsd.edu/reports/thomson.pdf
MODIFICATION HISTORY:
JUL-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonBase
PURPOSE:
(Used internally only)
Determines the intensity scattered from single coronal electron by Thomson scattering
CALLING SEQUENCE:
Result = ThomsonBase(ElSun,SinChi,U, P,It,Itr)
INPUTS:
ElSun array distance Sun-observer (in solar radii)
SinChi array sine of angle Sun-Electron-Observer
U array limb darkening coefficient
OUTPUTS:
ThomsonBase array scattered intensity
P array polarization; P=Itr/ThomsonBase (-1<=P<=1)
Itr array tangential minus radial intensity; same units as ThomsonBase.
It array radial intensity; same units as ThomsonBase
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
ThomsonSoup
CALLED BY:
ThomsonElectron, ThomsonLOSStep, ThomsonTang, ThomsonTangMRad
PROCEDURE:
> Based on Chapter 6, Section B of Billings' "A guide to the solar corona" (p. 150)
Sigma = Thomson cross section=7.96x10^-26 cm^2/sterad
Omega = angular size of Sun from electron
Chi = angle Sun-Electron-Observer
I0 = intensity at disk center
RSun = solar radius = 7x10^10 cm
Billings specifies the scattered intensity in the form
I=0.5*Pi*Sigma*I0*Func(Omega,Chi) (erg/s/sterad)
This subroutine only deals with Func(Omega,Chi):
From Eq. 18: It = (1-u)*CC+u*DD
From Eq. 19: Itr = sin^2(Chi)*[(1-u)AA+u*DD]
> The last two arguments (It, Itr) are returned for use by function ThomsonIntegral.
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonBrightness
PURPOSE:
Calculates weights for integrating Thomson scattering signal
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
FUNCTION ThomsonBrightness, REarth, R, F, f3darg, $
ut_earth = ut_earth , $
pa_earth = pa_earth , $
elo_earth = elo_earth , $
elo_sun = elo_sun , $
degrees = degrees
INPUTS:
REarth array[3] NOT USED; for 'plain' sky map
array[3,N] NOT USED; for 'transit' sky map
NOT USED; heliographic coordinates of Earth for lines of sight
R array[3,N,L,M] heliographic coordinates of points in a 2D grid
of NxL lines of sight with M segments along each
R[0,*,*,*] : heliographic longitude
R[1,*,*,*] : heliographic latitude
R[2,*,*,*] : heliocentric distance (AU)
F array[N,L,M] normalized densities n*(r/r0)^2 at los segments (electrons/cm^-3)
f3darg array[4] f3darg[0] Line of sight step size (AU)
f3darg[1] Limb darkening constant
f3darg[2] Apparent magnitude Sun at 1 AU
f3darg[3] 0=Intensity; 1: Tangential; 2: Tang-Rad
OPTIONAL INPUT PARAMETERS:
/degrees if set all input angles should be in degrees (default: radians)
ut_earth array[1] not used
pa_earth array[N,L,M] not used
elo_earth array[N,L,M] angle Sun-Earth-LOS segment (i.e. conventional elongation angle)
elo_sun array[N,L,M] angle Earth-Sun-LOS segment
OUTPUTS:
R array[N,L,M] weight factors W(s) at location s along line of sight in S10
Intensity B = Sum( W(s) ) = Sum( I(s)n(s)ds )
INCLUDE:
@compile_opt.pro ; On error, return to caller
EXTERNAL BY:
RemoteView_Display2D, vu_earthskymap
CALLS: ***
SubArray, ThomsonElectron, ToRadians
PROCEDURE:
ThomsonElectron returns 10^-26 S10. Multiply by the step size along the line
of sight in cm (f3darg[0]*!sun.au*10^13) and multiply with the remaining
10^-13. The value returned is a brightness in S10 for each line of sight segment.
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Removed restriction on dimensions of R,F,elo_earth,elo_sun.
F, elo_earth, elo_sun should all by of the same structure, while
R should have an additional leading dimension of size 3.
[Previous]
[Next]
NAME:
ThomsonElectron
PURPOSE:
Determines the Thomson scattering intensity from single coronal electron.
If /S10 is set then return brightness of one electron per square degree
of sky in S10 units
CALLING SEQUENCE:
I = ThomsonElectron(SinChi, P, rsun=RSun, au=au, udark=udark, apm=APM, /s10)
INPUTS:
SinChi array; type: float
sine of angle Sun-Electron-Observer
OPTIONAL INPUT PARAMETERS:
rsun=RSun array; type: float; default: 1 AU
distance Sun-Electron
udark=idark array; type: float; default: 0
limb darkening coefficient
/au if set all distances are in AU (default: solar radii)
/s10 if set then return brightness is in S10
apm=APM apparent magnitude of Sun (only needed if /S10 is set)
/tangonly return tangential intensity, It
/tangmrad return tangential - radial intensity, Itr
OUTPUTS:
I array; type: float
scattered intensity; units depend on setting of /S10
/S10 NOT set: 10^-26 times the flux from the solar disk incident
on the electron (effectively the units are 10^-26 cm^2/sterad)
/S10 set; 10^-26 S10 units
P array: type: float
polarization (-1<=P<=1)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, ThomsonBase, ThomsonS10, ThomsonSolarFlux, ToSolarRadii
CALLED BY:
ThomsonBrightness
PROCEDURE:
Based on Chapter 6, Section B of Billings' "A guide to the solar corona" (p. 150)
Sigma = Thomson cross section=7.96x10^-26 cm^2/sterad
Omega = angular size of Sun from electron
Chi = angle Sun-Electron-Observer
I0 = intensity at disk center
Rs = solar radius = 7x10^10 cm
Billings specifies the scattered intensity in the form
I=0.5*Pi*Sigma*I0*Func(Omega,Chi) (erg/s/sterad)
The average intensity coming from the solar disk is
i=(Pi*Rs^2)*I0*(1-U/3) (erg/s/sterad)
The flux incident on the electron at distance Rsun is
F=i/RSun^2=Pi*I0*(1-U/3)*(Rs/RSun)^2 (erg/s/cm^2)
If /S10 NOT set then the ratio
I/F = 0.5*Sigma*Func(Omega,Chi)/( (Rs/RSun)^2*(1-U/3) )
is returned here, except for a factor 10^-26 (from Sigma).
> The flux received from the solar disk by an observer at distance RObs
(rather than the electron) is i/RObs^2 = F*(RSun/RObs)^2 (erg/s/cm^2).
The scattered flux from the electron incident on the observer is
I/S^2 (erg/s/cm^2). The ratio (I/F)*(RObs/(RSun*S))^2 gives
the flux received from the electron in units of the flux received by
the observer from the solar disk.
> The conversion to S10 is done by multiplying with the conversion
factor returned by ThomsonS10
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonElectronFar
PURPOSE:
Determines the intensity scattered from single coronal electron
by Thomson scattering in the limit of large electron-Sun distance
(limit Omega->0; ElSun->Infinity)
Get Thomson scattering brightness of one electron per square degree
of sky in S10 units in limit of large electron-Sun distance
CALLING SEQUENCE:
I = ThomsonElectronFar(SinChi, P, rsun=RSun, /au, apm=APM, /s10)
INPUTS:
SinChi array; type: float
sine of angle Sun-Electron-Observer
OPTIONAL INPUT PARAMETERS:
APM array; type: float
apparent magnitude of the Sun
rsun=RSun array; type: float
distance Sun-Electron (in solar radii)
OUTPUTS:
I array; type: float
scattered intensity; units depend on /S10 setting
S10 NOT set: 10^-26 times the flux from the solar disk incident on the electron
S10 set : 10^-26 S10
P array polarization (-1<=P<=1)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, ThomsonS10, ToSolarRadii
PROCEDURE:
> Based on Chapter 6, Section B of Billings' "A guide to the solar
corona" (p. 150)
Sigma = Thomson cross section=7.96x10^-26 cm^2/sterad
Omega = angular size of Sun from electron
Chi = angle Sun-Electron-Observer
I0 = intensity at disk center
RSun = solar radius = 7x10^10 cm
Billings specifies the scattered intensity in the form
I=0.5*Pi*Sigma*I0*Func(Omega,Chi) (erg/s/sterad)
The average intensity coming from the solar disk is
i=(Pi*RSun^2)*I0*(1-U/3) (erg/s/sterad)
The flux incident on the electron is F=i/ElSun^2 (erg/s/cm^2)
The ratio
I/F = 0.5*Sigma*Func(Omega,Chi)/( (RSun/ElSun)^2*(1-U/3) )
is returned here, except for a factor 10^-26 (from Sigma).
> The flux received from the solar disk by the observer (rather than the
electron) is i/ScSun^2 = F*(ElSun/ScSun)^2 (erg/s/cm^2).
The scattered flux from the electron incident on the observer is
I/ScEl^2 (erg/s/cm^2). The ratio (I/F)*(ScSun/(ElSun*ScEl))^2 gives
the flux received from the electron in units of the flux received by
the observer from the solar disk.
> An S10 unit is `the brightness of one 10th magnitude star per square
degree of sky'. Replace the star by an electron at the same location
in the sky, and at distance ScEl away from the observer. The electron
is radiating by Thomson scattering of sunlight.
> STEP 1: Calculate the intensity (erg/s/sterad) -emitted- by the electron
in units of the flux -incident- at 1 AU from the solar
disk (erg/s/cm^2) (compare ThomsonElectron; the only difference
is that ElSun is replaced by r0=1 AU in the unit determination)
> STEP 2: Convert to units of the flux -incident- at 1 AU from a 10th
magnitude star: multiply by 10^((10-M)/2.5). (Apparent
magnitude, M=-2.5*log(Flux)).
!!! M is an apparent magnitude as observed at 1 AU. This is why
1 AU was used in step 2, rather than the observer-Sun
distance ScSun.
> 10^-48 = 10^-26*10^-26*10^4:
10^-26 from Sigma; 10^-26 from 1/ScEl^2; 10^4 from 10^(10/2.5)
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonLOSDensity
PURPOSE:
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
F = ThomsonLOSDensity(S)
INPUTS:
S array; type: float
topocentric distance electron-observer (in solar radii)
OPTIONAL INPUT PARAMETERS:
/grid if set every line-of-sight distance in S is combined with every
line of sight stored with ThomsonSetupLOS.
OUTPUTS:
F array; type: float
density at electron location (in electrons/cm^-3)
INCLUDE:
@compile_opt.pro ; On error, return to caller
@thomson_common.pro ; Dummy comment
CALLS: ***
CvPointOnLos, InitVar, IsType, SubArray, SuperArray, SyncArgs
CALLED BY:
ThomsonLOSStep, ThomsonTang, ThomsonTangMRad
PROCEDURE:
> The observer locations and directions of the lines of sight are
first setup in a common block by ThomsonSetupLOS.
> The distance along the lines of sight 'S', in combination with
the common block variables are used to get the heliocentric coordinates
of all line-of-sight locations.
> The function 'density' is a user-defined function, which returns the
density for a given heliocentric location.
The function is called using the IDL call_function routine.
> If no density function is specified than a 1/r^2 density with a
1 electrons/cm^3 density at 1 AU is used.
MODIFICATION HISTORY:
JAN-1998, Paul Hick (UCSD)
JUN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu; added /grid keyword
[Previous]
[Next]
NAME:
ThomsonLOSFar
PURPOSE:
Determines the integrated intensity along a line of sight for electron
Thomson scattering in a 1/r^2 density distribution in the limit of
small angular size of the Sun (with density at 1 AU of 1 electron/cm^-3)
CALLING SEQUENCE:
F = ThomsonLOSFar(RSun, Elo, P, lower=Lower, upper=Upper, /degrees, /au, apm=APM, /s10)
INPUTS:
RSun array; type: float
distance of observer from Sun
Elo array; type: float
elongation of line of sight (l.o.s.)
(Elo=0 is the direction to the Sun)
OPTIONAL INPUT PARAMETERS:
lower=Lower
array; type: float; default: 0
lower lmit of integration along line of sight
upper=Upper
array; type: float: default: !values.f_inifinity
upper limit of integration along line of sight
(negative value integrates up to infinity)
/degrees if set all angles are in degrees (default:radians)
/au if set all distance are in AU (default: solar radii)
/S10 return brightness in S10 units
apm=APM apparent magnitude of Sun at 1 AU
(needed only if /S10 is set)
OUTPUTS:
F array; type: float
Integrated Thomson scattering intensity;
units depend on setting of /S10:
/S10 NOT set: per sterad in units of 10^-16 times the flux received
from the solar disk (at the observer location
/S10 set: S10 units
P array; type: float
polarization
CALLS: ***
InitVar, IsType, SyncArgs, THOMSONFARY, ThomsonS10, ToRadians, ToSolarRadii
SEE ALSO:
ThomsonLOSRomb, ThomsonLOSStep
PROCEDURE:
> Calculates an analytical expression for the integral along the
entire line of sight in the limit of small angular size of the Sun.
> The integrated intensity incident on the observer has cgs units of
erg/s/cm^2/sterad. The flux from the Sun incident on the observer has
cgs units of erg/s/cm^2, so the ratio will have units 1/sterad.
> The electron density in the solar wind at 1 AU (cm^-3) is set to 1 cm^-3.
> Coronal density n(s) = n0*(r0/r(s))^2 (r0=a AU)
Intensity/electron I(s) = 0.5*Pi*Sigma*I0*Func(Omega,Chi)
The integral has the form
B = Integral[0,inf]{n(s)I(s)ds}
= 0.5*Pi*Sigma*I0*Integral[0,inf]{n(s) Func(Omega,Chi) ds}
> The result is expressed in units of the flux received from the solar
disk by the observer:
F = (Pi*Rs^2)*I0*(1-U/3) / RSun^2 (erg/s/cm^2)
= Pi*I0*(1-U/3)* (Rs/RSun)^2
> 10^-13 = 10^-26*10^13
Factor 10^-26 is from the Thomson cross section, Sigma
Factor 10^13 is from the integration step size
MODIFICATION HISTORY:
1990, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonLOSRomb
PURPOSE:
Calculates integrated line-of-sight intensity for Thomson scattering using Romberg integration
Can only handle one line of sight at at time.
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
I = ThomsonLOSRomb(Pos, Dir, P, lower=Lower, upper=Upper, /degrees, /au, $
density=density, udark=udark, apm=APM, /s10)
INPUTS:
Pos array[3]; type: float
heliocentric location of observer:
(ecliptic) longitude and latitude; and heliocentric distance
(a scalar 'pos' is interpreted as [0,0,pos])
Dir array[2]; type: float
topocentric (ecliptic) longitude and latitude of line of sight
relative to Sun-observer direction
(a scalar 'dir' is interpreted as [dir,0])
OPTIONAL INPUT PARAMETERS:
/s10 if set intensities are returned in S10 units
In this case the apparent magnitude APM MUST BE SPECIFIED
udark=udark scalar; type: float; default: 0
limb darkening constant
apm=APM scalar; type: float
apparent magnitude of Sun
density=density
scalar; type: string; default: undefined
name of function used to calculate the electron density.
Keyword is passed to ThomsonSetupLOS.
lower=Lower
scalar; type: float; default: 0
Lower limit of los integration (solar radii)
If Lower <=0 then Lower = 0 is used.
upper=Upper
scalar; type: float; default: 9000 solar radii
Upper limit of los integration (solar radii)
If Lower <=0 then Upper = 9000.0 solar radii (~40 AU) is used.
/degrees if set all angles are in degrees (default: radians)
/au if set all distances are in AU (default: solar radii)
OUTPUTS:
I scalar; type: float
Integrated Thomson scattering intensity;
units depend on setting of /S10:
/S10 NOT set: per sterad in units of 10^-16 times the flux received
from the solar disk (at the observer location
/S10 set: S10 units
P scalar; type: float
polarization
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
Elongation, InitVar, SyncArgs, ThomsonS10, ThomsonSetupLOS, ThomsonSetupRomb
ThomsonSolarFlux, ToRadians, ToSolarRadii
EXTERNAL:
ThomsonTang, ThomsonTangMRad
CALLED BY:
ThomsonMidpoint, ThomsonMidpointFnc
SEE ALSO:
ThomsonLOSStep
PROCEDURE:
> The lower and upper limits can actually be 1-dim arrays, but that is
probably not useful.
> If no 'density' function is specified then a 1/r^2 density is used with
density of 1 at 1 AU.
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonLOSStep
PURPOSE:
Calculates integrated line-of-sight intensity for Thomson scattering.
Integration is implemented as a sum over steps of equal size.
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
I = ThomsonLOSStep(Pos, Dir, P, lower=Lower, upper=Upper, nstep=nStep, $
/degrees, /au, density=density, udark=udark, apm=APM, /s10)
INPUTS:
Pos array[3]; type: float
heliocentric location of observer:
(ecliptic) longitude and latitude; and heliocentric distance
Dir array[2,..]; type: float
topocentric (ecliptic) longitude and latitude of line of sight
relative to Sun-observer direction
OPTIONAL INPUT PARAMETERS:
/s10 if set intensities are returned in S10 units
In this case the apparent magnitude APM MUST BE SPECIFIED
udark=udark scalar; type: float; default: 0
limb darkening constant
apm=APM scalar; type: float
apparent magnitude of Sun
density=density
scalar; type: string; default: undefined
name of function used to calculate the electron density.
Keyword is passed to ThomsonSetupLOS.
lower=Lower
scalar; type: float; default: 0
Lower limit of los integration (solar radii)
If Lower <=0 then Lower = 0 is used.
upper=Upper
scalar; type: float; default: 9000 solar radii
Upper limit of los integration (solar radii)
If Lower <=0 then Upper = 9000.0 solar radii (~40 AU) is used.
nstep=nStep
scalar; type: integer; default: 100
number of elements in which to divide the range [Lower, Upper]
/degrees if set all angles are in degrees (default: radians)
/au if set all distances are in AU (default: solar radii)
OUTPUTS:
I array of same size as Dir[0,...]; type: float
Integrated Thomson scattering intensity;
units depend on setting of /S10:
/S10 NOT set: per sterad in units of 10^-16 times the flux received
from the solar disk (at the observer location
/S10 set: S10 units
P array of same size as Dir[0,..]; type: float
Polarization
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
Distance2Sun, Elongation, InitVar, IsType, ThomsonBase, ThomsonLOSDensity
ThomsonS10, ThomsonSetupLOS, ThomsonSolarFlux, ToRadians, ToSolarRadii, gridgen
SEE ALSO:
ThomsonLOSFar, ThomsonLOSRomb
PROCEDURE:
Densities are calculated by ThomsonLOSDensity.
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonMidpoint
PURPOSE:
Calculate position along line of sight where the integrated intensity
is half of the intensity integrated along the entire line of sight
CALLING SEQUENCE:
S = ThomsonMidpoint(ScSun,Elo,U,/degrees)
INPUTS:
ScSun scalar distance of spacecraft from Sun
Elo scalar elongation of s/c line of sight (l.o.s.) in degrees.
Elo=0 is the direction to the Sun
OPTIONAL INPUT PARAMETERS:
udark=udark scalar; type: float; default: 0
limb darkening constant
/degrees if set all angles are in degrees (default is radians)
/au if set all distances are in AU (default: solar radii)
OUTPUTS:
ThomsonMidPoint
scalar point on l.o.s. where intensity is half the total
integrated intensity
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, ThomsonLOSRomb, ToRadians, ToSolarRadii, nrZBrent, nrZbrac
EXTERNAL:
ThomsonMidpointFnc
PROCEDURE:
First nrZbrac is used to bracket the zero of function ThomsonMidpointFnc.
Then nrZBrent is used to locate the zero.
MODIFICATION HISTORY:
JAN-1997, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonMidpointFar
PURPOSE:
Calculate position along line of sight where the integrated
intensity is half of the intensity integrated along the
entire line of sight (treating the Sun as a point source
CALLING SEQUENCE:
S = ThomsonMidpoint(ScSun,Elo,U,/degrees)
INPUTS:
ScSun array distance of spacecraft from Sun in AU
Elo array elongation of s/c line of sight (l.o.s.) in degrees.
Elo=0 is the direction to the Sun
OUTPUTS:
ThomsonMidPointFar
array point on l.o.s. where intensity is half the total
integrated intensity
CALLS: ***
BadValue, SyncArgs, THOMSONMIDFAR, ToRadians, nrZBrent, nrZbrac
EXTERNAL:
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
JAN-1997, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonMidpointFnc
PURPOSE:
Internal use by ThomsonMidpoint.
CALLING SEQUENCE:
R = ThomsonMidpointFnc, S, arg
INPUTS:
S scalar; type: float
distance along line of sight in solar radii
arg array(4}; type: float
[R,E,udark,halfint]
R = heliocentric distance observer in solar radii
E = elongation in radians
udark = limb darkening constant
halfint = half the intensity from 0 to infinity
OUTPUTS:
R scalar; type: float
integrated intensity upto distance S - halfint
INCLUDE:
@compile_opt.pro ; On error, return to caller
EXTERNAL BY:
ThomsonMidpoint
CALLS: ***
ThomsonLOSRomb
PROCEDURE:
Returns the difference between line-of-sight integrated intensity
up to specified distance S and half the integrated intensity over the
entire line of sight. I.e. the distance S which makes this function zero is
what ThomsonMidpoint is looking for.
No density function is passed to ThomsonLOSRomb, so a 1/r^2 density is assumed.
MODIFICATION HISTORY:
JAN-1997, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonPDistance
PURPOSE:
Find the distance to the plane of the sky where a single electron
would have a given polarization.
CALLING SEQUENCE:
FUNCTION ThomsonPDistance, ElSun, U, P
INPUTS:
ElSun array distance Sun-Electron (in solar radii)
U array limb darkening coefficient
P array polarization (-1<=P<=1)
OUTPUTS:
ThomsonPDistance
array distance to the plane of the sky (solar radii) (>=0)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
BadValue, SyncArgs, ThomsonSoup
PROCEDURE:
> The distance to the plane of the sky is given as a positive number.
There are two locations on either side of the plane of the sky
which match the polarization.
> An electron can only produce a positive polarization. If a negative
polarization is specified, then D=-1. is returned
> An electron can only produce a polarization below a certain maximum
(less than one). If a polarization above the maximum value is specified
the D=-1. is returned.
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonPDistanceFar
PURPOSE:
Find the distance to the plane of the sky where a single electron
would have a given polarization in the limit of large electron-Sun
distance
CALLING SEQUENCE:
FUNCTION ThomsonPDistanceFar, ElSun, P
INPUTS:
ElSun array distance Sun-Electron (in solar radii)
P array polarization (-1<=P<=1)
OUTPUTS:
ThomsonPDistance
array distance to the plane of the sky (in solar radii) (>=0)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
BadValue, SyncArgs
PROCEDURE:
> The distance to the plane of the sky is given as a positive number.
There are two locations on either side of the plane of the sky
which match the polarization.
> An electron can only produce a positive polarization. If a negative
polarization is specified, then D=-1. is returned
> An electron can only produce a polarization below a certain maximum
(less than one). If a polarization above the maximum value is specified
the D=-1. is returned.
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonRadialFilter
PURPOSE:
CATEGORY:
sat/idl/toolbox/thomson
CALLING SEQUENCE:
F = ThomsonRadialFilter(elo_sun [,/degrees])
INPUTS:
elo_sun array; type: float
elongations (angle between line of sight and
direction to Sun).
OPTIONAL INPUT PARAMETERS:
elo_one=elo_one
scalar; type: float: default: 90 degrees
elongation at which radial filter has value of unity.
i.e. the filter scales to equivalent brightness at
this elongation
/degrees if set, then elo_sun should be in degrees
OUTPUTS:
F array of same type as 'elo_sun'; type: float
radial filter; dividing by F should remove the steep dropoff
in the Thomson scattering brightness.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsType, ToRadians
CALLED BY:
RemoteView_Display2D, vu_earthskymap
PROCEDURE:
Currently the radial filter is the dropoff with elongation in a 1/r^2
density in the limit of small angular size of the Sun.
MODIFICATION HISTORY:
FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonS10
PURPOSE:
(Internal use only) Convert to S10 units
CALLING SEQUENCE:
R = ThomsonS10(DSun,APM)
INPUTS:
DSun array; type: float
distance to Sun (in solar radii)
APM array; type: float
apparent magnitude Sun at 1 AU
OUTPUTS:
R array; type: float
Conversion factor to S10 units. If F is a flux in units of the
flux incident from the solar disk at heliocentric distance DSun
then R*F is the same flux in S10 units.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
ThomsonElectron, ThomsonElectronFar, ThomsonLOSFar, ThomsonLOSRomb
ThomsonLOSStep
PROCEDURE:
An S10 unit is `the brightness of one 10th magnitude star per square
degree of sky'. Replace the star by an electron at the same location
in the sky, and at distance S away from the observer. The electron
is radiating by Thomson scattering of sunlight.
The conversion is done in two steps:
> STEP 1: Convert to units of the flux -incident- at r0 = 1 AU from the
solar disk: multiply by (r0/DSun)^2
(M is an apparent magnitude as observed at 1 AU. This is why
1 AU is used, rather than the observer-Sun distance RObs).
> STEP 2: Convert to units of the flux -incident- at 1 AU from a 10th
magnitude star: multiply by 10^((10-M)/2.5). (Apparent
magnitude, M=-2.5*log(Flux)).
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonSetupLOS
PURPOSE:
Sets up common block used by ThomsonLOSDensity to
calculate electron density at specified locations
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
ThomsonSetupLOS, Pos, Dir, density=density
INPUTS:
Pos array[3] or array[3,n]; type: float
heliocentric location of observer:
(longitude and latitude in radians;
and heliocentric distance in solar radii)
Dir array[2,n]; type: float
topocentric longitude and latitude of lines of sight
relative to Sun-observer direction (in radians)
OPTIONAL INPUT PARAMETERS:
density=density
scalar; type: string; default: undefined
name of function to be called to called to calculate the electron
density (see PROCEDURE). This function takes a single argument:
R array[3,n]; type: float
heliocentric locations where density is to be evaluated
ecliptic longitude and latitude (radians)
and heliocentric distance (solar radii)
OUTPUTS:
(stored in common block)
INCLUDE:
@compile_opt.pro ; On error, return to caller
@thomson_common.pro ; Dummy comment
CALLS: ***
IsType, boost, destroyvar
CALLED BY:
ThomsonLOSRomb, ThomsonLOSStep
SEE ALSO:
ThomsonLOSDensity
PROCEDURE:
The input variables are stored in common block
MODIFICATION HISTORY:
JAN-1998, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonSetupRomb
PURPOSE:
Controls Romberg integration in ThomsonLOSRomb
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
ThomsonSetupRomb, RSun, Elo, U
INPUTS:
RSun scalar: type: float
Observer-Sun distance (solar radii)
Elo scalar; type: float
Elongation (radians)
U scalar; type: float
Limb darkening constant
OUTPUTS:
(stored in common block)
CALLED BY:
ThomsonLOSRomb
COMMON BLOCKS:
common ThomsonIntegrand, RSun, Elo, U
PROCEDURE:
ThomsonSetupIntegrand sets up the common block accessed by
ThomsonTang and ThomsonTangMRad (these two functions
are used as arguments to the IDL QRomb and QRomo functions.
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonSolarFlux
PURPOSE:
Calculates the flux from the solar disk incident on
an observer at given distance from Sun
CATEGORY:
Thomson scattering
CALLING SEQUENCE:
Flux = ThomsonSolarFlux(R,U)
INPUTS:
R array; type: float; default: 1 AU
distance from Sun (in solar radii)
U array; type: float; default: zero
limb darkening constant
OUTPUTS:
Flux array; type: float
flux from the solar disk in units of pi*I0
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar
CALLED BY:
ThomsonElectron, ThomsonLOSRomb, ThomsonLOSStep
PROCEDURE:
The flux from the solar disk expressed in the intensity at
the center of the disk, I0, is pi*I0*(1-u/3)*(Rsun/R)^2.
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonSoup
PURPOSE:
(Used internally only).
Calculates constant needed for calculating Thomson scattering intensities
CALLING SEQUENCE:
ThomsonSoup, ElSun, U, It, Itr
INPUTS:
ElSun array[*] Electron-Sun distance in solar radii (=1./sine(Omega))
U array[*],scalar limb darkening constant
OUTPUTS:
rIt,rItr real constants
CALLED BY:
ThomsonBase, ThomsonPDistance
RESTRICTIONS:
Distance ElSun must be greater than one solar radii
(if its smaller then ElSun=1 is used)
PROCEDURE:
> See Billings, Guide to the solar corona (Chapter 6, p. 150) Academic Press (1966)
> The constants are functions of the angular size, Omega, of the Sun as seen from the
electron, and the limb darkening constant U. Sin(Omega)=RSun[cm]/dElectronSun[cm].
MODIFICATION HISTORY:
JUL-1996, Paul Hick (UCSD)
[Previous]
[Next]
NAME:
ThomsonTang
PURPOSE:
Controls Romberg integration in ThomsonLOSRomb (internal use only)
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
ThomsonTang, S
INPUTS:
S
OUTPUTS:
INCLUDE:
@compile_opt.pro ; On error, return to caller
EXTERNAL BY:
ThomsonLOSRomb
COMMON BLOCKS:
common ThomsonIntegrand, RSun, Elo, U
CALLS: ***
Distance2Sun, ThomsonBase, ThomsonLOSDensity
PROCEDURE:
ThomsonSetupRomb sets up the common block accessed by ThomsonTang
and ThomsonTangMRad (these two functions are used as arguments to the
IDL QRomb and QRomo functions).
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ThomsonTangMRad
PURPOSE:
Controls Romberg integration in ThomsonLOSRomb
CATEGORY:
Physics: Thomson scattering
CALLING SEQUENCE:
ThomsonTangMRad, S
INPUTS:
S
OUTPUTS:
INCLUDE:
@compile_opt.pro ; On error, return to caller
EXTERNAL BY:
ThomsonLOSRomb
COMMON BLOCKS:
common ThomsonIntegrand, RSun, Elo, U
CALLS: ***
Distance2Sun, ThomsonBase, ThomsonLOSDensity
PROCEDURE:
ThomsonSetupRomb sets up the common block accessed by
ThomsonTang and ThomsonTangMRad (these two functions are
used as arguments to the IDL QRomb and QRomo functions).
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeArray
PURPOSE:
Converts time structure to array and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeArray(t [,/linear])
INPUTS:
t array; type: time structure array, or non-structure
array[2,*], array[*]
time to be converted from array to structure or v.v.
OPTIONAL INPUT PARAMETERS:
/linear returns scalar integer instead of 2-element integer
OUTPUTS:
u array; type: array[2,*] or time structure
converted time
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SubArray, SuperArray, TimePieces, TimeStandardize
CALLED BY:
CarringtonT, CarringtonT0, IsBadTime, TimeOrigin
PROCEDURE:
> If the input time is a structure array[*] then it is returned as an
integer array[2,*] (with days and fract-day units) If /linear is set
then an integer array[*] is returned in fract-day units
> If an non-structure array is input then it should be an array[2,*]
(leading dimension of 2) if /linear NOT set, or an array[1,*] if
/linear is set. This is returned as a structure array.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeDay
PURPOSE:
Converts numerical day value to time structure and v.v
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
v = TimeDay(t)
INPUTS:
t array; type: time structure or any numerical type
OUTPUTS:
t array; type: nummerical or time structure
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
IsTime, TimePieces, TimeStandardize
CALLED BY:
TimeGet, TimeSet
RESTRICTIONS:
This function is for use in TimeGet and TimeSet only.
Other code should make calls to TimeGet or TimeSet:
u = TimeSet(day=t,/diff)
u = TimeGet(day=t,/diff)
SIDE EFFECTS:
Accesses !TimeUnits.in_day
PROCEDURE:
> If the input is a type structure than is an integer array
if all the fractions of a day are zero, or else a double array
is returned
> If the input is a numerical array then it is converted to
a time structure with the integer part as the number of days,
and the fraction as time of day.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeFixYear
PURPOSE:
Complete year specified in 2 digits
CATEGORY:
Tricks
CALLING SEQUENCE:
Y = TimeFixYear(Yr)
INPUTS:
Yr array; type: integer
OUTPUTS:
Y array; type integer
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
GetNagoyaSources, InsituTimeSeries, TimeSplit, nagoya_glevel, sgp4_eph, sgp4_tlm
PROCEDURE:
Where 0<=Yr<=50, Yr is changed to 2000+Yr
Where 50<Yr<100, Yr is changed to 1900+Yr
Everywhere else Yr is unmodified
MODIFICATION HISTORY:
AUG-1999, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeGet
PURPOSE:
Get information from time structure
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeGet(t ,[unit,...])
INPUTS:
t array[*]; type: time structure
input times
unit scalar; type: integer; default: none
integer identifying one of the time units year,
day, hour, minute, sec or msec. Should be a return
value of the fnc TimeUnit.
Alternatively, setting one of the keywords /year, /day, /hour,
/minute, /sec or /msec accomplishes the same.
/yr is the same as /year
/hr is the same as /hour.
'unit' must be set for keywords /full, /botime, /roundt.
If 'unit' is set without any of these keywords present then
the associated time unit is extracted from 't'.
OPTIONAL INPUT PARAMETERS:
/difference by default the input time is treated as an absolute
time, i.e. a time relative to the time origin !TimeZero.
If /difference is set then the input time is treated
as a time difference, i.e. the returned values will be
be independent of !TimeZero.
The distinction is significant if !TimeZero is set to an
irregular time, e.g. if the time origin is 2000 Jan 1,
00:00:03, and t = 0, then
TimeGet(/sec ) returns 3 while
TimeGet(/sec, /diff) returns 0.
Internally the difference is that by default the time
!TimeZero+t is processed, while with /diff set only the
input time t is processed Note that !TimeZero+t is the
number of days elapsed since 2000 Jan 1, 0 UT.
For keywords extracting calendar date information
setting /difference is somewhat tricky because the calculation
assumes that time is specified relative to 2000 Jan 1, 0 UT
(i.e. !TimeZero+t). Setting /difference would produce wrong
results unless the input t itself already has !TimeZero added to it.
/full used only if 'unit' is set
converts to units of 'unit'
/botime used only if 'unit' is set
truncates to 'unit'
/roundt used only if 'unit' is set
rounds to 'unit'
/jd extract Julian date
/mjd extract modified Julian date
/njd extract days since 2000 Jan 1.5
/jepoch extract Julian epoch
/bepoch extract Besselian epoch
/dow extract day of week
/month extract month (integer between 1 and 12)
to convert to 3-char strings, see TimeMonth
/dom extract day of month (with fraction for time of day)
/doy extract day of year (with fraction for time of day)
/scalar if set and only one time is specified (i.e. T is array[1])
then the result is output as a scalar (by default the
output will also be an array[1] (note: this only applies if
the output is not a time structure, since structures are
always arrays).
OUTPUTS:
u = TimeGet( t, /dhms [, /difference])
u array[5,*]; type: integer
input time split into days, hours, minutes, sec and msec
u[0,*] days
u[1,*] hours
u[2,*] minutes
u[3,*] seconds
u[4,*] milli-seconds
u = TimeGet( t, /full [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: numerical type, usually double
input time in units of 'unit'
/year time converted to Julian years
/day time converted to days
/hour time converted to hours
/minute time converted to minutes
/sec time converted to seconds
/msec time converted to milli-seconds
Internally a recursive call to TimeGet is made with /difference
and /dhms set.
u = TimeGet( t, /botime [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: time structure
input time truncate to 'unit'
/year time truncated to start of year (doy=1.0)
(though technically legal you probably don't want
to specify /difference with this keyword).
/day time truncated to beginning of day
/hour time truncated to beginning of hour
/minute time truncated to beginning of minute
/sec time truncated to beginning of second
/msec time truncated to beginning of milli-second
If /difference is NOT set then 'u' is returned relative to
the internal time origin !TimeZero (i.e. !TimeZero is subtracted
after the truncation has been done).
u = TimeGet( t, /fotime [, /difference, /full, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: time structure (/full NOT set) or numerical
(/full SET).
fraction of time left after subtracting the result
of TimeGet(t,/botime).
/year fraction of year left
/day fraction of day left
/hour fraction of hour left
/minute fraction of minute left
/sec fraction of second left
/msec fraction of milli-second left
If /full is SET then the remaining fraction is converted
into time units 'unit'. This is a shortcut for two TimeGet calls:
u = TimeGet(t, /fotime, /day, /full)
is the same as:
u = TimeGet(t, /fotime, /day)
u = TimeGet(u, /diff, /full, /day)
u = TimeGet( t, unit, roundt=roundt [, /difference])
u = TimeGet( t, /roundt [, /difference, $
[year=year, day=day, hour=hour, minute=minute, sec=sec, msec=msec]])
u array[*]; type: time structure
rounded input time
year = year time rounded to 'year' Julian years
(same as setting day=365.25d0)
day = day time rounded to 'day' days
hour = hour time rounded to 'hour' hours
minute = minute time rounded to 'minute' minutes
sec = sec time rounded to 'sec' seconds
msec = msec time rounded to 'msec' milli-second
Setting e.g. /day is the same as day=1, i.e. rounding occurs
to the nearest unit of time specified.
If /difference is NOT set then 'u' is returned relative to
the internal time origin !TimeZero (i.e. !TimeZero is subtracted
after the rounding has been done).
u = TimeGet( t [, /difference, $
[unit, /year, /day, /hour, /minute, /sec, /msec]])
u array[*]; type: integer
specified time-component extracted from 'u'
year = year year (integer array)
day = day day of year (integer array)
The calendar keywords /julian and jul2greg affect
the result (see TimeYDoy).
(though technically legal you probably don't want
to specify /difference with these two keywords).
hour = hour hours
minute = minute minutes
sec = sec seconds
msec = msec milli-seconds
These four are implemented as recursive calls to
TimeGet with /difference and /dhms set.
u = TimeGet( t, /d2000 [ , /difference] ) # days since 2000 Jan 1, 0 UT
u = TimeGet( t, /jd [ , /difference] ) Julian days
u = TimeGet( t, /mjd [ , /difference] ) Modified Julian days, JD-2400000
u = TimeGet( t, /njd [ , /difference] ) New Julian days = days since 2000 Jan 1, 12 UT
u = TimeGet( t, /jepoch [ , /difference] ) Julian epoch
u = TimeGet( t, /bepoch [ , /difference] ) Besselian epoch
u array[*]; type; numerical
calendar date 't' converted to indicated format
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
u = TimeGet( t, /dow [ , /difference] )
u array[*]; type: string
day of week as 2-char string, 'SUN','MON', etc.
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
u = TimeGet( t, /month [ , /difference] )
u array[*]; type: integer
month as integer 1-12. To convert to 3-char strings, 'JAN','FEB', etc.
see TimeMonth).
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result (see TimeYDoy).
u = TimeGet( t, /dom [ , /difference] )
u = TimeGet( t, /doy [ , /difference] )
array[*]; type: numerical
day of the month or year with fraction for time of day.
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result (see TimeYDoy).
u = TimeGet( t, /yrmd [ , /difference] )
array[3,*]; type: numerical
year, month and day of the month (with fraction for time of day).
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result (see TimeYDoy).
u = TimeGet( t, /ydoy [ , /difference] )
array[*]; type: numerical
year and day of the year (with fraction for time of day).
If /difference is used, make sure that t reflects elapsed times since
2000 Jan 1, 0 UT.
The calendar keywords /julian and jul2greg affect the result (see TimeYDoy).
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
CarringtonT0, CvMag, CvSky_Equatorial, CvSky_GSM, CvSky_Geographic
CvSky_Heliographic, CvSky_Precess, GeographicInfo, GetNagoyaSources, HOSOrbit
InsituTimeSeries, KeplerOrbit, NewcombSun, PA_Pole, RemoteView_BodyLoc, TimeGST
TimeOp, TimeSet, TimeSplit, TimeString, TimeXAxis, TimeYDate, TimeYDoy, UlyssesOrbit
clock, jpl_eph, lsqLinearFit, mpc_eph, nagoya_glevel, qLine_Curve, smei_coriolis
smei_frm_cp, smei_frm_cvhdr, smei_frm_findpoint, smei_frm_get, smei_frm_info
smei_frm_path, smei_frm_summary, smei_getfile, smei_hdr_get, smei_hdr_make
smei_hdr_plot, smei_hdr_update, smei_orbits_stat, smeidb_mounted, usno_eph
vu_insitu, vu_insitu_raw, vu_movie, vu_select, vu_update_hours
RESTRICTIONS:
If the return value is a one-element non-structure it is returned as a 1-element array,
unless /scalar is set.
CALLS: ***
InitVar, IsType, SubArray, SuperArray, TimeDay, TimeOp, TimePieces, TimeSet, TimeShift
TimeStandardize, TimeString, TimeUnit, TimeYDate, TimeYDoy
PROCEDURE:
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
NOV-2003, Paul Hick (UCSD/CASS)
Fixed bug in use of /botime keyword
JAN-2004, Paul Hick (UCSD/CASS)
Fairly substantial rewrite, converting from the old time structure
with year,doy,h,m,s,msec fields to the new structure with two integer fields.
APR-2004, Paul Hick (UCSD/CASS)
Fixed bug with /roundt for rounding to hours, minutes, seconds or milliseconds
JUL-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added /eotime keyword
[Previous]
[Next]
NAME:
TimeGST
PURPOSE:
Calculate Greenwich Sidereal Time from UT
Good for years 1901 through 2099. Accuracy is 0.006 degree.
CATEGORY:
Celestial mechanics
CALLING SEQUENCE:
gst = TimeGST(T, /degrees)
INPUTS:
T array; type: time structure
universal time (UT)
OPTIONAL INPUT PARAMETERS:
/degrees if set output is in degrees (default: radians)
OUTPUTS:
gst array; type: double
Greenwich sidereal time
INCLUDE:
@compile_opt.pro ; Return to caller
CALLS: ***
TimeGet, TimeOp, TimeSet, TimeUnit, ToDegrees
CALLED BY:
EarthTransit3DLoc, GeographicInfo
RESTRICTIONS:
Only valid for years 1901 through 2099
PROCEDURE:
Local Sidereal Time (LST) is defined as the Hour Angle of the
vernal equinox. GST is RA of local meridian at Greenwich
MODIFICATION HISTORY:
See: C.T. Russell, Geophysical Coordinate Transformations,
in: Cosmic Electrodynamics 2 (1971) 184-196
[Previous]
[Next]
NAME:
TimeInterpol
PURPOSE:
Interpolation of a function of time.
CATEGORY:
Tell time
CALLING SEQUENCE:
F = TimeInterpol(FF, TT, T, Unit, _extra=_extra)
INPUTS:
FF array[n]; type: any numerical array
list of function values
TT array[n]; type: time structure
list of times where function values FF are supplied
T array[m]; type: time structure
list of times where interpolates are needed
OPTIONAL INPUT PARAMETERS:
Unit scalar; type: integer; default: TimeUnit(/days)
time units used for the interpolation (see PROCEDURE)
_extra=_extra
extra keyword passed to IDL function 'interpol'
OUTPUTS:
F array[n]; type: same as FF
list of interpolated values at times T
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
INTERPOL, InitVar, IsType, SyncDims, TimeOp, TimeUnit
CALLED BY:
mpc_eph, vu_RemoteView, vu_atlocation, vu_gettime, vu_insitu_raw, vu_mean
vu_timeseries
PROCEDURE:
Input arrays TT and T are converted to time differences relative to
TT[0] in units specified by the Unit argument. Interpolation is done
with the IDL interpol function using these time difference arrays.
MODIFICATION HISTORY:
MAR-2001, Paul Hick (UCSD/CASS)
SEP-2001, Paul Hick (UCSD/CASS)
Added interpolation on multidimensional arrays
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added check for new time of time structure
[Previous]
[Next]
NAME:
TimeLimits
PURPOSE:
Extract information about a array of times
CATEGORY:
Tell time
CALLING SEQUENCE:
R = TimeLimits(T, /tmin [, unit])
R = TimeLimits(T, /tmax [, unit])
R = TimeLimits(T, /tmid [, unit])
R = TimeLimits(T, /tbounds [, unit])
R = TimeLimits(T, /trange [, unit])
INPUTS:
T array; type: time structure
times to be processed
OPTIONAL INPUT PARAMETERS:
unit scalar; type: integer
If'unit' is not specified all times are returned
as a time structure
If 'unit' ist specified then times are returned
as a difference from T[0] in units of 'unit'.
/tmin return earliest time
/tmax return latest time
/tmid return center time
/tbounds return earliest and latest time
(earliest time = R[0], latest time = R[1])
This is the default if no keyword is specified.
/trange (use only with chronological or reverse
chronological arrays, SEE RESTRICTIONS)
return earliest and latest time,
The pair of times is returned in the
same order as they occur in the input array T,
e.g. if the array is in reverse chronological order
than R[0] is the latest, and R[1] the earliest time.
(this keyword is primarily use in plotting routines
to reverse the time axis).
OUTPUTS:
R array[1], array[2]; type: time structure of float
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, MEAN, TimeOp, TimeUnit
CALLED BY:
InsituTimeSeries, TimeLInterpol, TimeXAxis, lsqLinearFit, mpc_eph, qLine_Curve
qView_GetData, sgp4_eph, sgp4_tlm, smei_buf_getframe, smei_buf_prep, smei_buf_read
smei_frm_eclipse, smei_frm_findpoint, smei_frm_get, smei_frm_summary
smei_getfile, smei_hdr_get, smei_hdr_plot, smei_hdr_update, smei_sky
smei_star_fit, vu_insitucurve
RESTRICTIONS:
If the min and max time is required for an input array T that is
not (reverse) chronological the /trange keyword can produce unexpected
results (the minimum time may end up in R[1], not R[0]).
Use trange = TimeLimits(T,/tbounds) if you need to be sure
that the minimum time is R[0] and the maximum time R[1].
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS)
SEP-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added /tbounds keyword
[Previous]
[Next]
NAME:
TimeLInterpol
PURPOSE:
Linear interpolation on a function of time
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
fnc = TimeLInterpol(ff, tt, t, unit)
INPUTS:
ff array[n]; type: any
function values
if ff does not exist then the array index
lindgen(n) is used
tt array[n]; type: time structure
UT times
t array[m]; type: time structure
times were interpolated values are needed
OPTIONAL INPUTS:
/scalar if n=1 then return values will be scalars instead
of array[1]
OUTPUTS:
inear=inear
dtnear=dtnear
ilow=ilow
dtlow=dtlow
ihigh=ihigh
dthigh=dthigh
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
ArrayLocation, InitVar, IsType, TimeLimits, TimeOp, TimeUnit
CALLED BY:
smei_coriolis
PROCEDURE:
MODIFICATION HISTORY:
DEC-2005, Paul Hick (UCSD/CASS)
[Previous]
[Next]
NAME:
TimeMonth
PURPOSE:
Converts integer month to 3-char month and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
mon = TimeMonth(month)
INPUTS:
month scalar or array; type: integer or string
if integer then values must be between 1 and 12
if char then values must be one of
JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC
(case insensitive).
OPTIONAL INPUT PARAMETERS:
/check if set then no conversion is done, but the input
array is checked to make sure all entries are valid.
OUTPUTS:
mon same array type as input; type; string or integer
converted month array
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncArgs
CALLED BY:
TimeSet, TimeString, TimeYDate
PROCEDURE:
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeOp
PURPOSE:
Simple operations on times
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
v = TimeOp(t,u, /add)
v = TimeOp(t,u, /subtract)
v = TimeOp(t,u, /meant, wt=wt, wu=wu)
u = TimeOp(t, /units, old_units=old_units, new_units=new_units)
INPUTS:
t array; type: time structure
u array; type: time structure
OPTIONAL INPUT PARAMETERS:
wt=wt scalar or array; type: double; default: 1d0-wu or 0.5d0
weight for first time array (t)
wu=wu scalar or array; type: double; default: 1d0-wt or 0.5d0
weight for second time array (u)
Input is converted to double if necessary
old_units=old_units
scalar; type: integer; default: !TimeUnits.in_day
# times per day currently stored in t
new_units=new_units
scalar; type: integer; default: !TimeUnits.tiny
new units
OUTPUTS:
u array; type: time structure
added times
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, TimeGet, TimePieces, TimeSet, TimeStandardize, TimeUnit
CALLED BY:
CarringtonT, CarringtonT0, CarringtonVar, EarthTransit3DLoc, GeographicInfo
GetNagoyaSources, InsituTimeSeries, IsBadTime, PlotCurve, RemoteView_BodyLoc
RemoteView_CMEDensity, RemoteView_Init_FOV, TimeGST, TimeGet, TimeInterpol
TimeLInterpol, TimeLimits, TimeOrigin, TimeScale, TimeSet, TimeShift, TimeSplit
TimeSystem, TimeXAxis, big_orbit, even_light, jpl_eph, jpl_test, mpc_eph, nso_fe_plot
qImage_cw_DrawEphem, qLine_Curve, qView_UpdateTime, sgp4_eph, sgp4_tlm
smei_base_testcase, smei_buf, smei_buf_getframe, smei_buf_prep, smei_buf_read
smei_camera_gain, smei_coriolis, smei_frm_cp, smei_frm_cvhdr, smei_frm_findpoint
smei_frm_get, smei_frm_info, smei_frm_path, smei_frm_read, smei_frm_summary
smei_getfile, smei_hdr_get, smei_hdr_make, smei_hdr_plot, smei_hdr_update
smei_orbits_stat, smei_sgp4_orbits, smei_star_fit, smei_time, stopwatch
vu_NagoyaSourcemap, vu_atlocation, vu_getdata, vu_gettime, vu_header, vu_insitu
vu_insitu_raw, vu_insitucurve, vu_is_sequence, vu_mean, vu_movie, vu_nagoyaskymap
vu_new_time, vu_select, vu_timeseries, vu_update_hours, vu_update_marker
vu_vox_draworbit, vu_vox_write, vu_weight, vu_whatis, www_help_tree
PROCEDURE:
If neither wu nor wt are specified then the unweighted mean time
(t+u)/2 is returned.
If only one weight is defined then the other weight is set to
1-(specified) weight, i.e. a weighted mean is calculated:
wt*t+(1-wt(u)) or (1-wu)*t+wu*t
If both weights are specified the wt*t+wu*u is returned.
Uses !TimeUnits
Note that the units in the returned time are not necessarily consistent
anymore with !TimeUnits.in_day. It is the users responsibility to make
sure that this does not lead to mayhem.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS)
APR-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Fixed bug in calculation of signdiff
Added keyword /scalar to TimeGet call used to get signdiff.
Signdiff is now a returned as a scalar if both t and u are
1-element time structure arrays.
[Previous]
[Next]
NAME:
TimeOrigin
PURPOSE:
Converts time structure to array and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeOrigin(t)
INPUTS:
t0 /get NOT set:
array[1]; type: time structure
time origin additional offset to the origin
defined in keywords /d2000, /jd, /mjd, /njd
OPTIONAL INPUT PARAMETERS:
/get if set then the current settings are returned in t0
/time do not change the origin, only change time units
/d2000 if set then the origin is set to 2000 Jan 1, 0 UT
(plus t0 if specified).
/jd if set then the origin is set to JD=0
(plus t0 if specified)
/mjd if set then the origin is set to JD=2400000
(plus t0 if specified)
/njd if set then the origin is set to 2000 Jan 1, 12 UT
(plus t0 if specified)
units_in_day=units_in_day
scalar; type: integer; default: !TimeUnits.in_day
# times per day
OUTPUTS:
u array; type: array[2,*] or time structure
converted time
OPTIONAL OUTPUT PARAMETERS:
t0 /get SET: current settings of time origin and time units
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, TimeArray, TimeOp
CALLED BY:
CarringtonT, TimeShift
PROCEDURE:
Uses structure definition in !TheTime
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimePieces
PURPOSE:
Manipulate time structures
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
v = TimePieces(t, [p ,/days, /tiny, /units])
INPUTS:
t array; type: time structure; default: !TheTime
times
p array; type: integer
time component to be entered into 't'
OPTIONAL INPUT PARAMETERS:
/days return # whole days in t
/units return fraction of day in current units
/tiny return fractions of day in smallest permitted
time units (as set in !TimeU.tiny)
OUTPUTS:
v array; type: integer
returns a part of the input time.
If /days and /tiny NOT set:
fraction of day in current units
(as set by !TimeUnits.in_day)
If /day SET:
# whole days in t
If /tiny SET:
fraction of day in smallest permitted units
(as set by !TimeUnits.tiny)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType
CALLED BY:
TimeArray, TimeDay, TimeGet, TimeOp, TimeSet, TimeStandardize
RESTRICTIONS:
The assumption is made that !TimeUnits.tiny is an
integer multiple of TimeUnits.in_day. If this is not the case
integer truncation occurs, with probably pretty nasty side effects.
PROCEDURE:
As much as possible all access to the fields in the time
structure should be channelled through this function.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimePosn
PURPOSE:
Finds location of time in string
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
p = TimePosn(names, time=time [,cbreak=cbreak,front=front,back=back,format=format]
INPUTS:
names array; type: string
strings containing times
OPTIONAL INPUT PARAMETERS:
cbreak=cbreak scalar; type: string; default: '_' (underscore)
separator between time fields
OUTPUTS:
p array; type: long
position in 'names' where the time starts
-1 if no time was found
OPTIONAL OUTPUT PARAMETERS:
times=time array; type: time structure
times extracted from 'names'.
Set to !TheTime if no time was found
front=front array; type: string
part of 'names' preceeding the time
back=back array; type: string
part of 'names' trailing the time
format=format array; type: string
format string used to extract the time with TimeSplit
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncArgs, TIMEPOSN_ADD, TIMEPOSN_BACKCHECK, TimePosn_test
TimeSplit, UNIQ [1], UNIQ [2], UNIQ [3], boost, strposn
CALLED BY:
TimePosn_test, smei_TimePosn
PROCEDURE:
Currently YMD and YDOY type formats are accepted:
YYYY[_DOY_HHMMSS] and YYYY[_MN_DD_HHMMSS]
where the parts between brackets are optional.
MODIFICATION HISTORY:
JUL-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimePosn_test
PURPOSE:
(Internal use by timeposn only)
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
p = TimePosn(ctest,ntest,cbreak,trailingback,complement=complement)
INPUTS:
ctest
ntest
cbreak
OPTIONAL INPUT PARAMETERS:
OUTPUTS:
trail
OPTIONAL OUTPUT PARAMETERS:
complement=complement
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncArgs, TIMEPOSN_ADD, TIMEPOSN_BACKCHECK, TimePosn, TimeSplit
UNIQ [1], UNIQ [2], UNIQ [3], boost, strposn
CALLED BY:
TimePosn
MODIFICATION HISTORY:
JUL-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeReadMe
PURPOSE:
Help file for time variables in SMEI IDL software
CATEGORY:
gen/idl/toolbox/time
SEE ALSO:
TimePieces, defsysv_smei
PROCEDURE:
Three system variables are defined at startup (in defsysv_smei.pro)
to control the handling of time variables:
IDL> help, /structure, !timeunits
** Structure TIMEUNITS, 2 tags, length=8, data length=8:
IN_DAY LONG 86400000
TINY LONG 86400000
IDL> help, /structure, !thetime
** Structure THETIME, 2 tags, length=8, data length=8:
DAYS LONG 0
UNITS LONG 0
IDL> help, /structure, !timezero
** Structure THETIME, 2 tags, length=8, data length=8:
DAYS LONG 0
UNITS LONG 0
!TimeUnits has two integer fields:
!TimeUnits.in_days defines the unit used to keep track of the time of day
in !TheTime.units. It is the number of these time units in one whole day.
Currently this unit is milli-second, i.e. !TimeUnits.in_day = 86,400,000
Other allowed values are 24 (time-of-day units are hours), 1440 (units are
minutes) or 86400 (units are seconds).
!TimeUnits.tiny defines the smallest allowed time units allowed for the
time of day. Currently this also is milli-second, i.e.
!TimeUnits.tiny=!TimeUnits.in_day.
!TimeUnits.tiny is used primarily in rounding operations
(see the /roundt keyword on TimeGet).
All time variables are defined as arrays of !TheTime structures.
!TheTime has two long integer fields that together define the time elapsed since
some reference time (time origin).
!TheTime.days keeps track of integer days.
!TheTime.units keeps track of the time of day in units defined by !TimeUnits.in_day.
i.e. the time (in days) elapsed since the reference time is
!TheTime.days+!TheTime.units/!TimeUnits.in_day.
By default the reference time is set in !TimeZero.
!TimeZero itself is a !TheTime structure, and defines the time elapsed since
the 'absolute time origin' 2000, Jan 1, 0 UT. The default for !TimeZero is {0,0}
i.e. the current origin is set by default to the absolute origin.
TimeOrigin:
The function TimeOrigin is used to manipulate !TimeZero, and the setting
of !TimeUnits.in_day (!TimeUnits.tiny is never changed).
TimeShift:
A change of origin usually means that time variables need to be modified to
reflect the new origin. This is done with TimeShift.
TimeSet:
Most common real-life times can be converted to a !TheTime structure using
TimeSet. Examples are yr,mon,day triplets, yr,doy pair, (Modified) Julian Days,
Julian epochs, etc.
TimeGet:
This function is used to extract real-life data from a !TheTime structure.
Examples are year, day of year, day of week, day of month, Julian day, etc.
It also provides additional services, such as rounding of times.
Usage:
In principle, every routine that takes a time structure as input, should assume that
the time specifies time elapsed since the origin !TimeZero.
MODIFICATION HISTORY:
FEB-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeRound
PURPOSE:
Find rounded values bracketing the specified time range
CATEGORY:
Tell time
CALLING SEQUENCE:
R = TimeRound(dT,Unit)
INPUTS:
dT array; type: integer or float
times (in unit of 'Unit')
Unit array; type: integer
determines the time units of dT
(set by TimeUnit)
OUTPUTS:
R array[2]; type: float
two times bracketing dT (in units of 'Unit')
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
TimeXAxis
PROCEDURE:
Tricky and imperfect
MODIFICATION HISTORY:
???-????, Paul Hick (pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeScale
PURPOSE:
Returns range of time axis to data units established by
a previous call to TimeXAxis
CATEGORY:
Telling time
CALLING SEQUENCE:
R = TimeScale(t)
INPUTS:
t array; type: time structure
time array to be converted to data units
OPTIONAL INPUT PARAMETERS:
OUTPUTS:
R array; type: float
times converted to data units
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
TimeOp
CALLED BY:
qLine_FitPlot, smei_frm_summary, smei_hdr_plot
COMMON BLOCKS:
common TimeScale, torigin, trange, tunit, texact
PROCEDURE:
> The common block is set by a call to TimeXAxis.
MODIFICATION HISTORY:
JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeSet
PURPOSE:
Convert real-world time units to time structure.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
T = TimeSet(Tunit,unit)
T = TimeSet(/diff, year=year, day=day
[, hour=hour, minute=minute, sec=sec, msec=msec])
T = TimeSet(year=year, doy=doy
[, hour=hour, minute=minute, sec=sec, msec=msec])
T = TimeSet(year=year, month=month, day=day
[, hour=hour, minute=minute, sec=sec, msec=msec])
T = TimeSet(Tunit, T0, format=format
See TimeSplit
INPUTS:
For time differences:
--------------------
The calculation does not involve the internal time origin !TimeZero,
although the time can still be interpreted as the time elapsed
since !TimeZero)
T = TimeSet(Tunit, unit)
Tunit array; type: any numerical type
times specified in units of 'unit'
unit scalar; type: integer; default: none
integer indicating the time units of 'Tunit'
Should be a return value of fnc TimeUnit.
The input 'Tunit' in units of 'unit' are converted
to a standard time structure.
T = TimeSet(/diff, year=year, day=day, hour=hour, $
minute=minute, sec=sec, msec=msec)
The arguments can be a combination of scalars and arrays
of any numerical type (incl. float or double).
Input units are combined into standard time structure.
Years are interpreted as Julian years of 365.25 days.
The /diff keyword is optional, but more robust. If omitted a list
of checks for 'calendar keywords' (see below) is done; if none is
found then a recursive call with /difference SET follows.
For specific dates ('calendar times'):
--------------------------------------
Calendar times can be set in a number of different 'calendar keywords'.
In addition to the keywords specified below, the time-of-day keywords hour,
minute, sec and msec are permitted. The associated elapsed time (i.e. a time
difference calculated internally by a recursive call to TimeSet with /diff set)
is added to the time calculated from the main keywords.
The resulting time is returned relative to the current origin !TimeZero,
i.e. the returned value T depends on the setting of !TimeZero with
!TimeZero+T the time elapsed since 2000 Jan 1, 0 UT.
T = TimeSet(year=year, doy=doy)
Specify Year and Day Of Year.
The year is an integer; if omitted it is set using the system time;
doy (day of year) MUST be specified and can include a fraction for
the time of day. Calendar related keywords /julian and /jul2greg are
permitted (see TimeYDoy)
T = TimeSet(year=year, month=month, day=day)
Specify Year, Month, Day Of Month.
The year is an integer; if omitted it is set using the system time;
the month MUST be present either as an integer (1-12) or as a 3-char string
('jan', 'feb', etc.; case insensitive); the day of the month, if not defined,
is set to 1, and it can include a fraction for the time of day.
Calendar related keywords /julian and /jul2greg are permitted
(see TimeYDoy, TimeYDate).
T = TimeSet(jd =jd )
T = TimeSet(mjd=mjd)
T = TimeSet(njd=njd)
Specify a Julian day (number of days elapsed since noon of a specific date)
'jd' is the conventional Julian day (e.g. jd=2451545 is 2000 Jan 1, 12 UT)
'mjd' is the modified Julian day, JD-2400000, i.e.the first two digits of
the Julian day are dropped; e.g. mjd=51545 is 2000 Jan 1, 12 UT)
'njd' is the new Julian day, JD-2451545, (e.g. njd=0 is 2000 Jan 1, 12 UT)
Specify an epoch:
T = TimeSet(jepoch=jepoch [, /diff])
T = TimeSet(bepoch=bepoch [, /diff])
Specify time as Julian epoch and Besselian epoch. These are typically
specified as double arrays.
String times for specific dates:
T = TimeSet(TT, [T0 , format=format, $
year=year, day=day, hour=hour,minute=minute, sec=sec, msec=msec])
With TT a time in string time representation and T0 a time origin
(see TimeSplit). The string time is converted to a time structure
by a call to TimeSplit (using T0 and 'format'). The additional
keywords are added to the resulting time.
OPTIONAL INPUT PARAMETERS:
/difference if set, initialize a time difference
/stringt if set, a call to TimeString is made, resulting in
the return of a time in string representation.
OUTPUTS:
T array; type: standard time structure or string
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncArgs, TimeDay, TimeGet, TimeMonth, TimeOp, TimePieces, TimeShift
TimeSplit, TimeStandardize, TimeString, TimeSystem, TimeUnit, TimeYDate, TimeYDoy
CALLED BY:
CarringtonT, CarringtonT0, CarringtonVar, CvSky_Galactic, EarthTransit3DLoc
GeographicInfo, GetNagoyaSources, InsituTimeSeries, RemoteView_BodyLoc, TimeGST
TimeGet, TimeOp, TimeSplit, TimeSystem, TimeXAxis, TimeYDate, TimeYDoy, UlyssesOrbit
big_eph, big_orbit, jpl_eph, jpl_test, makemovie, mpc_eph, nagoya_glevel, nso_fe_plot
nso_fe_start, qEphem_State, qLine_Curve, qView_Save2File, sgp4_eph, sgp4_tlm
smei_base_testcase, smei_buf_get, smei_buf_getframe, smei_camera_gain
smei_coriolis, smei_frm_cp, smei_frm_cvhdr, smei_frm_drive, smei_frm_eclipse
smei_frm_findpoint, smei_frm_get, smei_frm_path, smei_frm_summary, smei_getfile
smei_hdr_get, smei_hdr_make, smei_hdr_plot, smei_hdr_update, smei_mksidereal
smei_orbits_stat, smei_sgp4_orbits, smei_sky, smei_star_fit, smeidb_mounted
usno_eph, vu_NagoyaSourcemap, vu_insitu, vu_insitu_raw, vu_insitucurve, vu_movie
vu_nagoyaskymap, vu_new_time, vu_update_hours, vu_vox_draworbit, vu_vox_write
vu_weight
PROCEDURE:
Messy, but it works
MODIFICATION HISTORY:
SEP-1999, Paul Hick (UCSD/CASS)
AUG-2000, Paul Hick (UCSD/CASS)
Introduced keyword Month, which accepts both integer and character
specifications. This makes keywords iMon (for integer input) and
cMon (for character input) obsolete.
JUL-2003, Paul Hick (UCSD/CASS)
If Doy of Day is specified without a year then the current year is used.
DEC-2003, Paul Hick (UCSD/CASS)
Fixed problem with keyword month. Only types string and integer were
acceptable. Anything else would cause an error. Now if is neither string
nor integer, it is converted to integer by rounding.
JAN-2004, Paul Hick (UCSD/CASS)
Fairly substantial rewrite, converting from the old time structure
with year,doy,h,m,s,msec fields to the new structure with two integer fields.
JUN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added processing of string times. Hopefully this elimates the necessity to
call TimeSplit and TimeString directly.
[Previous]
[Next]
NAME:
TimeShift
PURPOSE:
Converts between various possible origins
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeShift(from_time=from_time, from_d2000=from_d2000, from_jd=from_jd, $
from_mjd=from_mjd, from_njd=from_njd, /to_time, /to_d2000, /to_jd, /to_mjd, /to_njd
INPUTS:
from_time=from_time current origin
from_y200=from_d2000 2000 Jan 1, 0 UT
from_jd=from_jd JD = 0
from_mjd=from_mjd JD = 2400000
from_njd=from_njd 2000 Jan 1, 12 UT
array; type: time structure
times relative to implied origin
/to_time if set return time relative to 2000 Jan 1, 0 UT
/to_d2000
/to_jd
/to_mjd
/to_njd
OUTPUTS:
u array; type: time structure
converted times
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, TimeOp, TimeOrigin
CALLED BY:
TimeGet, TimeSet
PROCEDURE:
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeSplit
PURPOSE:
Convert times from string to numerical
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
T = TimeSplit(TS, T0, format=format)
INPUTS:
TS array; type: string
times in string form
T0 array[1]; type: time structure
time origin
OPTIONAL INPUTS:
format=format
scalar; type: sting; default: none
string template specifying the time format, e.g. 'YEAR/MN/DD hh:mm:ss.mss'
Valid components are:
YEAR for 4-digit year
YY for 2-digit year (converted using TimeFixYear)
DOY for the day of year
MON for 3-char month ('jan')
MN for 2-digit month (01-12)
DD for the day of the month
hh for the hour of the day
mm for the minutes
ss for the seconds
mss for the milliseconds
OUTPUTS:
T array; type: time structure
output times with numerical values for the
seperate components of the time array
If an error occurs then T = -1 is returned.
The function IsTime(T) can be used to check for an
error condition.
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncDims, TagArray, TimeFixYear, TimeGet, TimeOp, TimeSet, TimeUnit
CALLED BY:
TimePosn, TimePosn_test, TimeSet, TimeSystem, clock, htmd_cat, qImage_cw_DrawEphem
qImage_cw_Ephem, qNagoya_PointSources, qNagoya_Skymap, qView_ApplyGain
qView_GetData, qView_PlotSeries, qView_PlotTrack, qView_UpdateTime, smei_buf_get
smei_coriolis, smei_sky_get, smei_sky_read, smei_star_remove, smei_time, vu_header
vu_set_time_entry, vu_vox_read, wso_read
RESTRICTIONS:
The first element of the TS array is used to analyze the exact string format.
This format is used to decompose all string elements in their constituent parts.
Hence, if TS is a string array, all entries must have exactly the same format!!!
PROCEDURE:
The string times in TS do not have to be complete.
Missing parts are taken from the time origin T0
Four types of strings can be entered:
'1999:300:00:00:00.000'
'1999/11/20 00:00:00.000' (YMD format)
'SAT JAN 10 00:00:00 1991' (SYS format)
'19-NOV-1999 23:48:11.00' (VMS format)
'03-23-2000 23:48:11 (SMEI format)
'2003_023_234811000 (L1A format)
MODIFICATION HISTORY:
AUG-1998, Paul Hick (UCSD/CASS)
NOV-1999, Paul Hick (UCSD/CASS)
Added VMS format, fairly substantial rewrite
APR-2000, Paul Hick (UCSD/CASS)
Added SMEI format '03-23-2000 23:48:11'
MAR-2003, Paul Hick (UCSD/CASS)
Added processing of strings like 2003_175_123456789
OCT-2003, Paul Hick (UCSD/CASS)
Added processing of strings like 2003_10_02_123456789
NOV-2003, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added keyword 'template'
JUN-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Rename keyword 'template' to 'format'.
[Previous]
[Next]
NAME:
TimeStandardize
PURPOSE:
Standardize times
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
u = TimeStandardize(t)
INPUTS:
t array; type: time structure
times
OUTPUTS:
t array; type: time structure
standardized times
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
TimePieces
CALLED BY:
TimeArray, TimeDay, TimeGet, TimeOp, TimeSet
SIDE EFFECTS:
Uses !TimeUnits.in_day
PROCEDURE:
Makes sure that the fraction of days stored in t.units
is a positive fraction and less than one day.
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeString
PURPOSE:
Converts times intro string form
CATEGORY:
Tell time
CALLING SEQUENCE:
R = TimeString(T, [/ymd, /sys, /vms])
INPUTS:
T array; type: time structure
times to be converted to string form
OPTIONAL INPUTS:
/ydoy returns string in form '1999:201:00:00:00.000'
/ymd returns string in form '1999/11/22 00:00:00.000'
/sys if set, a PC-style system string is returned (in uppercase)
/vms if set, a VMS-style system string is returned (in uppercase)
/_ydoy returns string in form 1999_201_000000000'
/_ymd returns string in form 1999_11_22_000000'
part scalar; type: integer
same as specifying 'from' and 'upto' with the same argument
from scalar; type: integer
should be set using the return value of TimeUnit.
If 'format' is NOT set then the time string will start
at the indicated time unit.
If 'format' is SET then 'from' is ignored.
upto scalar; type: integer
should be set using the return value of TimeUnit.
If 'format' is NOT set then the time string will end
indicated time unit. If in addition /roundt is set then
TT is rounded to unit 'upto' before being turned into a string.
If 'format' is SET, and in addition /roundt is set, then
'upto' is used for roundoff only.
format=format
scalar; type: string; default: none
string format specifying the time format, e.g. 'YEAR/MN/DD hh:mm:ss.mss'
The format can combine any of the following sections in any order:
YEAR insert 4-digit year
YY insert 2-digit year
DOY insert day of year
MON insert month as 3-char string ('jan')
MN insert month as 2-digit integer (1-12)
DD insert day of month as 2-digit integer
DOW insert day of week as 3-char string ('sat')
hh insert hour of day
mm insert minutes
ss insert seconds
mss,fff insert milliseconds
OUTPUTS:
R array; type: string
times in string form
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType, SyncDims, TimeGet, TimeMonth, TimeUnit
CALLED BY:
GetNagoyaSources, InsituTimeSeries, PlotEarthSkymap, PlotPlanarCut
PlotPolarSkymap, PlotSolarDisk, RemoteView_CMEDensity, RemoteView_Display2D
RemoteView_Display3D, RemoteView_FOV, TimeGet, TimeSet, TimeXAxis, htmd_cat
img_read, jpl_eph, nagoya_glevel, qEphem, qImage_cw_Property, qLine_FitPlot, qNagoya
qNagoya_PointSources, qsmei_sky_Pick, smei_base_testcase, smei_buf, smei_buf_get
smei_buf_getframe, smei_buf_prep, smei_buf_read, smei_frm_base, smei_frm_cvhdr
smei_frm_eclipse, smei_frm_findpoint, smei_frm_get, smei_frm_info, smei_frm_name
smei_frm_path, smei_frm_read, smei_frm_summary, smei_frm_track, smei_frm_where
smei_getfile, smei_hdr_get, smei_hdr_make, smei_hdr_plot, smei_hdr_update
smei_mksidereal, smei_orbits_stat, smei_sgp4_orbits, smei_sky_file
smei_star_fit, smei_star_writepnt, stopwatch, vu_NagoyaSourcemap, vu_RemoteView
vu_earthskymap, vu_get_page, vu_getdata, vu_image, vu_insitu_raw, vu_insitucurve
vu_mean, vu_movie, vu_nagoyaskymap, vu_new_time, vu_planarcut, vu_read, vu_select
vu_solardisk, vu_synopticmap, vu_update_marker, vu_vox_write, vu_whatis, vu_write
wso_read, www_help_tree
SEE ALSO:
TimeSplit
SIDE EFFECTS:
An earlier version of TimeString did not have the 'roundt' keyword.
It would always round when upto was set to units of hours or smaller,
and not round for units of years or days.
PROCEDURE:
If 'format' is NOT set the following formats are supported:
YDOY format: '0000:000:00:00:00.000' (default)
YMD format: '0000/00/00 00:00:00.000'
SYS format: 'SAT JAN 10 00:00:00 1991'
VMS format: '19-NOV-1999 23:48:11.00'
_YDOY format: '0000_000_000000000'
_YMD format: '0000_00_00_000000000'
The 'format' keyword obviously is a more transparent way of setting
a specific time format. The only reason to use one of the specific
formats above is the 'from' keyword, which is not implemented (yet??)
for the 'format' keyword (other than explicitly mutilating the
'format' itself).
MODIFICATION HISTORY:
AUG-1998, Paul Hick (UCSD/CASS)
NOV-1999, Paul Hick (UCSD/CASS)
Added VMS keyword
MAR-2003, Paul Hick (UCSD/CASS)
Added /fsys keyword
OCT-2003, Paul Hick (UCSD/CASS)
Renamed /fsys to /_ydoy. Added /_ymd.
NOV-2003, Paul Hick (UCSD/CASS)
Added keyword 'template'.
JAN-2003, Paul Hick (UCSD/CASS)
Removed /fsys keyword.
Added keyword /roundt. Rounding was automatic for 'upto' units
of hours or smaller. Rounding needs to be specified explicitly
for all units now.
OCT-2004, Paul Hick (UCSD/CASS)
Fixed bug in processing of seconds and msec. If the template
contained 'hhmmss' to represent hour, minute, seconds then the
trailing 'mss' would be interpreted as millisecond. This is fixed
by clearing portion of the template after they have been used.
JUN-2005, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Changed 'template' keyword to 'format'. 'template' is still supported
(for now).
[Previous]
[Next]
NAME:
TimeSystem
PURPOSE:
Convert system time to UT
CATEGORY:
Time
CALLING SEQUENCE:
ut = TimeSystem(local2ut)
INPUTS:
local2ut scalar; type:integer; default: 0
offset between local time and UT
OPTIONAL INPUT PARAMETERS:
/utc (this keyword was introduced in IDL 5.4)
passed to the IDL function systime
If this keyword is set then systime already
returns UT. If /utc is used then local2ut should
be set to zero.
OUTPUTS:
ut scalar; type: time structure
current universal time
INCLUDE:
@compile_opt.pro ; Return to caller
CALLS: ***
InitVar, IsType, TimeOp, TimeSet, TimeSplit
CALLED BY:
RemoteView_FOV, RemoteView_Init_Matrix, RemoteView_Init_View, TimeSet, arg_time
big_eph, even_light, qEphem, qNagoya, smei_buf, smei_frm_get, smei_frm_summary
smei_getfile, smei_hdr_plot, smei_hdr_update, smei_orbits_stat
smei_star_writepnt, smei_zodiac_fit, stopwatch, vu_write, www_help_tree
PROCEDURE:
The system time is retrieved using the IDL systime function,
and is assumed to set to the local time.
UT is calculated by adding 'local2ut' hours to the system time.
Note that this means that local2ut=0 simply returns the system time.
MODIFICATION HISTORY:
NOV-1999, Paul Hick (UCSD/CASS)
JUL-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Fixed version problem reported by Dick Altrock.
Embedded the 'systime' call containing the /utc keyword inside
a 'call_function' call to avoid compilation problems on
pre-5.4 versions of IDL.
[Previous]
[Next]
NAME:
TimeUnit
PURPOSE:
Provides information about time units used in time structures
CATEGORY:
Tell time
CALLING SEQUENCE:
T = TimeUnit( [/all,/years,/days,/hours,/minutes,/seconds,/mseconds])
T = TimeUnit(/NextUp,[/all,/years,/days,/hours,/minutes,/seconds,/mseconds])
T = TimeUnit(/msec ,[/all,/years,/days,/hours,/minutes,/seconds,/mseconds])
INPUTS:
tunit scalar; type: integer
if tunit exist the corresponding name for the unit of time
is returned (tag name of time structure, i.e. Y,M,D,H,M,S,MS)
OPTIONAL INPUT PARAMETERS:
/years,/days,/hours,/minutes,/seconds,/mseconds
sets time unit for which information is needed (set only one at a time)
/all returns information for all time units
If /all is not set and no time unit keyword is set, then /day is assumed
/nextup return the number of units in the next larger time unit
e.g. if /hours is set the value is 24 (24 hours in a day)
/mmsec returns number of mseconds (smallest time unit) in time unit
e.g. if /hours is set the value is 60*60*100=3600000
If neither /nextup nor /mmsec is set the position of the time unit tag in the
structure is returned.
OUTPUTS:
T scalar, if one of the time unit keywords is set.
array[7] if /all is set
The array is a long integer array if tag numbers are returned;
or double precision if /nextup or /mmsec are used
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsType
CALLED BY:
CarringtonT0, CarringtonVar, CvMag, CvSky_Heliographic, EarthTransit3DLoc
GeographicInfo, GetNagoyaSources, InSitu, InsituTimeSeries, IsBadTime, PA_Pole
PlotEarthSkymap, PlotPolarSkymap, PlotSynopticMap, RemoteView_CMEDensity
RemoteView_Display2D, RemoteView_Display3D, RemoteView_FOV
RemoteView_Init_FOV, TimeGST, TimeGet, TimeInterpol, TimeLInterpol, TimeLimits
TimeOp, TimeSet, TimeSplit, TimeString, TimeXAxis, even_light, htmd_cat, img_read
jpl_eph, jpl_test, lsqLinearFit, makemovie, mpc_eph, nagoya_glevel, qEphem
qImage_cw_DrawEphem, qLine_Curve, qLine_FitPlot, qNagoya, qNagoya_PointSources
qView_Save2File, qView_UpdateTime, sgp4_eph, sgp4_tlm, smei_base_testcase
smei_buf, smei_buf_get, smei_buf_getframe, smei_buf_prep, smei_buf_read
smei_camera_gain, smei_frm_base, smei_frm_cp, smei_frm_cvhdr, smei_frm_eclipse
smei_frm_findpoint, smei_frm_get, smei_frm_hbar, smei_frm_hbar_inside
smei_frm_info, smei_frm_name, smei_frm_path, smei_frm_read, smei_frm_summary
smei_frm_track, smei_getfile, smei_hdr_get, smei_hdr_make, smei_hdr_plot
smei_hdr_update, smei_mksidereal, smei_orbits_stat, smei_sgp4_orbits
smei_sky_file, smei_star_fit, smei_star_writepnt, smei_zodiac_fit, stopwatch
vu_RemoteView, vu_atlocation, vu_earthskymap, vu_get_page, vu_getdata, vu_gettime
vu_header, vu_image, vu_insitu, vu_insitu_raw, vu_insitucurve, vu_is_sequence
vu_mean, vu_movie, vu_nagoyaskymap, vu_new_time, vu_planarcut, vu_select
vu_solardisk, vu_synopticmap, vu_timeseries, vu_update_hours, vu_update_marker
vu_vox_write, vu_weight, vu_whatis, vu_write, wso_read, www_help_tree
PROCEDURE:
MODIFICATION HISTORY:
SEP-1998, Paul Hick (UCSD/CASS)
OCT-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added tunit argument
[Previous]
[Next]
NAME:
TimeXAxis
PURPOSE:
Plot horizontal time axis
CATEGORY:
Plotting
CALLING SEQUENCE:
TimeXAxis, TR, Unit, t0=T0
INPUT PARAMETERS:
TR array; type: float or time structure
(must have at least two elements)
Defines range of times to be plotted
If TR is a float array then TR is a time relative to the
time origin T0 in units of 'Unit'.
If T0 is not specified then TR MUST be an array
of time structures (T0 will be set internally using TR)
Only min(TR) and max(TR) are used.
Unit scalar; type: integer; default: TimeUnit(/days)
Determines the units of TR (if TR is a float array)
Use function TimeUnit to specify unit
Graphics keywords to the PLOT command are used using the _extra mechanism.
OPTIONAL INPUT PARAMETERS:
t0=T0 scalar; type: time structure
Time origin. MUST be set if TR is specified as a float array
/same_T0
if set then the time origin from a previous call to TimeXAxis
is used. If there is no origin available then the keyword is
ignored. If there is an origin available then this keyword
overrides the t0 keyword.
/exact forces time axis to cover exactly min(TR) to max(TR)
/noxtitle
suppress title for time axis
title=title NOT TRUE
title for time axis. If omitted and /noxtitle is not set then
the title is time at the start of the time axis is used as title.
from, upto
if set these keywords determine which time units are used in
the axis labels.
/axis_only
by default, the IDL plot procedure with the /nodata keyword
is used to plot the axis. If /axis_only is used then the
IDL axis procedure is used.
nmajor=nmajor
# of major tickmarks on time axis.
OPTIONAL OUTPUT PARAMETERS:
starttime=starttime
scalar; type: string
time at beginning of time axis.
tick_get=tick_get
array; type: float
tickmark labels used (i.e. value of keyword xtickv
on IDL plot or axis procedures)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
InSitu, PlotCurve, PlotSynopticMap, jpl_test, qLine_Curve, smei_frm_summary
smei_hdr_plot, vu_insitucurve
COMMON BLOCKS:
common TimeScale, torigin, trange, tunit, texact
CALLS: ***
InitVar, IsTime, IsType, REVERSE, TimeGet, TimeLimits, TimeOp, TimeRound, TimeSet
TimeString, TimeUnit, UNIQ [1], UNIQ [2], UNIQ [3], gridgen
PROCEDURE:
The common block stores the time origin (as a time structure) and the
time units used to generate the time axis. These are used by PlotCurve
to plot data points if the first argument to PlotCurve is a time
structure.
MODIFICATION HISTORY:
MAY-1991, Paul Hick (ARC)
Cribbed from the UTPLOT package
SEP-1998, Paul Hick (UCSD/CASS)
Introduced time structures
JAN-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Renamed from TimeAxis to TimeXAxis to avoid conflict in SSW
[Previous]
[Next]
NAME:
TimeYDate
PURPOSE:
Gets day of year from year, month day, or gets month and
day from year and day of year
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
TimeYDate, yr, month, day, doy [, /get_date]
INPUTS:
yr scalar or array; type: integer
year
/get_date NOT set:
month scalar or array; type: integer or string
month as integer in 1-12 or strings of type
'JAN','FEB', etc. (case-insensitive)
day scalar or array; type: any
day of month, possibly including a fraction for
the time of day.
/get_date SET:
doy scalar or array; type: any
day of year, possibly including a fraction for
the time of day.
OPTIONAL INPUT PARAMETERS:
/get_date by default, yr, month and day are assumed to be input
and the doy is returned. If /get_date is set then
yr and doy are input and month and day are output.
/julian interpret yr,doy and yr,mon,day as dates in Julian calendar
/jul2greg
jul2greg=jul2greg
array[1]; type: time structure
time at which the transition from Julian to Gregorian
calendar is made.
/jul2greg is the same as jul2greg=TimeSet(yr=1582, mon='oct', day=15)
OUTPUTS:
/get_date set:
month scalar or array; type: integer or string
month as integer in 1-12
(use TimeMonth to get 3-char strings)
day scalar or array; type: same as input doy
day of month, with the fraction from the input
doy added (if present)
/get_date NOT set:
doy scalar or array; type: same as input day
day of year, with the fraction from the input
day added (if present).
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
TimeGet, TimeSet
SIDE EFFECTS:
yr is converted to integer if it isn't already. None of the
other input variables are modified.
CALLS: ***
InitVar, IsTime, IsType, SyncArgs, TimeGet, TimeMonth, TimeSet, TimeYDoy
PROCEDURE:
For the input arguments combinations of scalars and arrays are permitted.
If integer day and doy are used the conversion is exact. For floating input
the fraction is moved from day to doy or v.v., i.e. it is not exact.
The relation between yr,month,day and yr,doy depends only on
whether yr is a leap year or not.
Two calendar schemes are implemented. In the Julian calendar
(/julian SET) every multiple of 4 is a leap year. In the Gregrorian
calendar (/julian NOT set) every multiple of 4 is a leap year, except
when the year is a centennial year that is not a multiple of 400
(i.e. 1700, 1800, 1900 are not leap years, but 1600 and 2000 are),.
See also documentation of TimeYDoy
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TimeYDoy
PURPOSE:
Converts date in yr, doy to number of days elapsed
since 2000 Jan 1, 0 UT and v.v.
CATEGORY:
gen/idl/toolbox/time
CALLING SEQUENCE:
TimeYDoy, yr, doy, day [, /get_date]
INPUTS:
/get_date NOT set:
yr scalar or array; type: integer
year
doy scalar or array; type: any
day of year, possibly including a fraction for
the time of day.
/get_date SET:
day scalar or array: type: any
number of days elapsed since 200 Jan 1, UT (Gregorian)
possibly including a fraction for the time of day.
Use TimeShift(d2000=TimeSet(day=day), /to_time) to convert
to a time structure (relative to current origin).
OPTIONAL INPUT PARAMETERS:
/get_date by default the number of days elapsed is calculated from
the date. If /get_date is set than the date is obtained
from the number of days elapsed since 2000 Jan 1, 0 UT.
(Gregorian).
/julian interpret yr, doy as date in Julian calendar
/jul2greg
/jul2greg=jul2greg
array[1]; type: time structure
time at which the transition from Julian to Gregorian
calendar is made.
/jul2greg is the same as jul2greg=TimeSet(yr=1582, mon='oct', day=15)
OUTPUTS:
/get_date NOT set:
day scalar or array: type: double
number of days elapsed since 200 Jan 1, UT (Gregorian).
the fraction of day is copied from the input day of year
(if present)
/get_date SET:
yr scalar or array; type: integer
year
doy scalar or array; type: same as input 'day'
day of year, the fraction of day is copied from the
input day (if present)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar, IsTime, IsType, TimeGet, TimeSet
CALLED BY:
TimeGet, TimeSet, TimeYDate
SIDE EFFECTS:
If /get_date NOT set then yr is converted to integer if it isn't already.
PROCEDURE:
The date yr,doy is a Julian date (if /julian SET) or a Gregorian date
(/julian NOT set). 'day' always is # days since 2000 Jan 1.0 (Gregorian)
i.e. Julian days minus 2451544.5
JD = 2451557.5 = 2000 Jan 14.0 (Gregorian) = 2000 Jan 1.0 (Julian)
JD = 2451544.5 = 2000 Jan 1.0 (Gregorian)
JD = 2299160.5 = 1582 Oct 15.0 (Gregorian) = 1582 Oct 5.0 (Julian)
(= -152384.0 days from 2000 Jan 1.0, Gregorian)
JD = 2361221.5 = 1752 Sep 14.0 (Gregorian) = 1752 Sep 3.0 (Julian)
The keyword jul2greg can be used to automatically switch from
Julian to Gregorian calendar. In general jul2greg is defined as
a UT standard time structure. If specified as keyword /jul2greg
then the time 1582 Oct 15.0 (Gregorian is used). The gap between
calendars at that time was 10 days.
Another useful transition would be 1752 Sep 14.0 (Gregorian).
The Britisch empire switched from 1752, Sep 2 to 1752 Sep 14
(11 day gap; the extra day comes from the year 1700 which is a leap
year in the Julian calendar but not in the Gregorian calendar).
MODIFICATION HISTORY:
JAN-2004, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TMO_skymotion
PURPOSE:
Corrects positions on CCD for skymotion during transit
CATEGORY:
SMEI prototype camera: TMO
CALLING SEQUENCE:
rr_out = TMO_skymotion(rr [, p_axis, frame, /degrees, to_zenith=to_zenith, $
fov=fov, vv=vv, plotx=plotx
INPUTS:
rr array[2,n]; type: float
positions on ccd as pairs off azimuthal angle (along long
dimension of fov), and radius
p_axis array[2]; type: float; default: [0,0]
position of optical axis on ccd: azimuthal angle and radius
Currently only p_axis[0] is used.
frame array[m]; type: any; default: 1
list of frame numbers (see PROCEDURE)
OPTIONAL INPUT PARAMETERS:
/south if set, the south position (19.5 south of zenith) is assumed
/north if set, the north position (10.0 north of zenith) is assumed
/degrees if set, all angles are in degrees (default: radians)
/plotx plot results
OUTPUTS:
rr_out array[2,n,m]; type: float
positions rr, corrected for motion across the sky
OPTIONAL OUTPUT PARAMETERS:
fov=fov array[*]; CCD azimuth angle (-30,..,+30) of points along
long dimension of fov
vv=vv array[*]; type: float
skymotion at positions 'fov' in pixels/minute
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
TMO_tracksky
RESTRICTIONS:
No check is made whether the locations rr are actually inside the fov
CALLS: ***
BadValue, INTERPOL, InitVar, MEAN, SubArray, SuperArray, SyncDims, ToRadians, gridgen
PROCEDURE:
> The SMEI fov is assumed to be along the local meridian
> The motion of stars during transit are calculated in pixels/minute
under the assumption that the 3 degree fov is covered by 27.16 pixels, and
that the geographic latitude of TMO is 34.382 degree.
> The 'frame' array is used to define the time axis in units of minutes.
(TMO data were taken at a 1 minute cadence). Usually 'frame' will be an
integer array of frame numbers, but the effective cadence time can be adjusted
by multiplication of the 'frame' array with the cadence time in minutes.
> For each location 'rr' on the CCD inside the fov, the corrected position is
the position of 'rr' after a time 'frame' minutes has elapsed.
> Only the radial component r[1,*] is corrected, i.e. stars are assumed to
transit on the CCD in the radial direction.
MODIFICATION HISTORY:
JUL-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
TMO_tracksky
PURPOSE:
CATEGORY:
SMEI prototype camera: TMO
CALLING SEQUENCE:
INPUTS:
box array[2,2]; type: integer; default: defined in smei_camera
defines two corners of box in the form [ [x1,y1], [x2,y2] ]
relative to the lowerleft corner of a full image
The box contains nx by ny pixels (nx=x2-x1+1, ny=y2-y1+1)
OPTIONAL INPUT PARAMETERS:
center=center array[2]; type: float; default: defined in smei_camera
'center' must be defined relative to the same origin as 'box'
p_axis=p_axis array[2]; type: float; default: defined in smei_camera
frame=frame array[m]; type: integer; default: 1
/plotx
OUTPUTS:
rfov array[2,nx,ny,m]; type: float
rectangular coordinates of all pixels in box corrected for skymotion
relative to the same origin as 'box' and 'center'
OPTIONAL OUTPUT PARAMETERS:
pfov array[2,nx,ny,m]; type: float
polar coordinates of all pixels in box corrected for skymotion
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
BadValue, CV_COORD, Inside_Wedge, SuperArray, TMO_skymotion, View, gridgen
smei_camera
CALLED BY:
qView_TMO_tracksky
PROCEDURE:
For each of the pixels in 'box' the position in each frame is calculated after
correcting it for skymotion.
MODIFICATION HISTORY:
JULY-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ToDegrees
PURPOSE:
Get conversion factor needed to convert angles to degrees,
depending on setting of keyword Degrees
CATEGORY:
Number strangling
CALLING SEQUENCE:
degrees_per_mystery_unit = ToRadians(degrees=Degrees)
OPTIONAL INPUT PARAMETERS:
/degrees indicates whether input angles are in
radians (not set) or degrees (set)
OUTPUTS:
degrees_per_mystery_unit
= !radeg if Degrees not set
= 1.0 if Degrees set
Result is returned in double precision
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
AngleUnits, ColorPolarBox, ColorSkybox, CvMag, CvSky_Equatorial, CvSky_GSM
CvSky_Geographic, CvSky_Heliographic, CvSky_Precess, GetNagoyaSources, HOSOrbit
PlotEarthSkymap, PlotPolarSkymap, PlotSynopticMap, TimeGST, eclipsed_area
jpl_test, smei_camera, smei_ccd2sky, smei_cv, smei_frm_where, smei_sky, smei_sky2ccd
smei_sky_read, smei_star_fit, smei_star_standard, smei_star_stdmaps
smei_zodiac_fit, vu_get, vu_planarcut, vu_point_source, vu_set
SEE ALSO:
ToRadians
PROCEDURE:
Many procedures which process angles allow the keyword /Degrees
to indicate that the input and/or output angles are in degrees,
rather than the default radians. This function returns the
conversion factor required to convert to radians. Usually
this function is used at the beginning of the procedure to convert
all angles from the input units to radians, and at the end to convert
back from radians to the input units.
MODIFICATION HISTORY:
SEP-2001, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ToRadians
PURPOSE:
Get conversion factor needed to convert angles to radians,
depending on setting of keyword Degrees
CATEGORY:
Number strangling
CALLING SEQUENCE:
radians_per_mystery_unit = ToRadians(degrees=Degrees)
OPTIONAL INPUT PARAMETERS:
/degrees indicates whether input angles are in
radians (not set) or degrees (set)
OUTPUTS:
radians_per_mystery_unit
= 1.0 if Degrees not set
= 1.0/!radeg if Degrees set
Results is double precision
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLED BY:
AngleRange, CarringtonLng, CarringtonNear, CarringtonNr, ColorPolarBox
ColorSkybox, CvMag, CvPointOnLos, CvRotation, CvSky_GSM, CvT3d, Distance2Sun
EarthSky3DLoc, EarthTransit3DLoc, Elongation, EulerRotate, FishEye, GeographicInfo
HammerAitoff, IPS_velocity, InterpolateHeliosphere, KeplerOrbit, NewcombSun
PA_Pole, PlotEarthSkymap, PlotPolarSkymap, PlotSynopticMap, RemoteView_BodySize
RemoteView_CMEDensity, RemoteView_FovTilt, RemoteView_Init_Matrix
RemoteView_Init_View, RemoteView_StereoStates, RemoteView_ZEclipticPlane
RotationMeasure, ScEarth, TMO_skymotion, ThomsonBrightness, ThomsonLOSFar
ThomsonLOSRomb, ThomsonLOSStep, ThomsonMidpoint, ThomsonMidpointFar
ThomsonRadialFilter, UlyssesOrbit, eclipsed_area, flat_centerofmass, jpl_mag
jpl_phase, plot3darc, refine_pointing, smei_cam2angle, smei_camera, smei_ccd2sky
smei_cv, smei_frm_where, smei_sky, smei_sky2cam, smei_sky2ccd, smei_sky_read
smei_star_fit, smei_star_standard, smei_star_stdmaps, smei_zodiac_fit
vu_RemoteView, vu_solardisk, vu_synopticmap, wedge_bounding_box
SEE ALSO:
ToDegrees
PROCEDURE:
Many procedures which process angles allow the keyword /Degrees
to indicate that the input and/or output angles are in degrees,
rather than the default radians. This function returns the
conversion factor required to convert to radians. Usually
this function is used at the beginning of the procedure to convert
all angles from the input units to radians, and at the end to convert
back from radians to the input units.
MODIFICATION HISTORY:
JAN-1998, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
[Previous]
[Next]
NAME:
ToSolarRadii
PURPOSE:
Returns factor needed to convert distance to solar radii
CATEGORY:
Thomson scattering
CALLING SEQUENCE:
rpau = ToSolarRadii(au=au)
OPTIONAL INPUT PARAMETERS:
au=au if not set then rpau=1 is returned
if set then the number of au per solar radii is returned
OUTPUTS:
rpau multiplicative factor to convert to solar radii
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
InitVar
CALLED BY:
ThomsonElectron, ThomsonElectronFar, ThomsonLOSFar, ThomsonLOSRomb
ThomsonLOSStep, ThomsonMidpoint
PROCEDURE:
Many of the Thomson scattering procedures have a keyword /au to indicate
that in- and output distances are in AU rather than the default units of
solar radii. This function provides the conversion factor needed to
convert to solar radii irrespective of the setting of keyword /au.
MODIFICATION HISTORY:
FEB-2002, Paul Hick (UCSD/CASS; pphick@ucsd.edu
[Previous]
[Next]
NAME:
twin
PURPOSE:
'TEK': Switch between alphanumeric and graphics screen
'X': Hide or show graphics window
'REGIS': Nothing
CALLING SEQUENCE:
PRO twin, mode, $
hide = hidewin, $
show = showwin, $
reset = reset, $
tl = topleft, $
tr = topright, $
br = bottomright, $
bl = bottomleft, $
center = center, $
cl = centerleft, $
tc = topcenter, $
cr = centerright, $
bc = bottomcenter, $
winnr = winnr, $
newwin = newwin, $
delete = delete, $
allwin = allwin, $
copywin = copywin, $
stackwin = stackwin, $
title = win_title, $
quarterscreen = QuarterScreen, $
onethirdscreen = OneThirdScreen,$
xsize = win_xsize, $
ysize = win_ysize, $
xysize = win_xysize, $
aspectratio = aspectratio, $
infowin = infowin, $
winmodes = winmodes, $
windex = windex, $
winwall = winwall, $
nocoordinates = nocoordinates,$
wallpaper = WallPaper, $
scream = scream
OPTIONAL INPUT:
mode 1 = restore graphics screen
2 = restore alphanumeric screen
if omitted the procedure works as a switch between both screens
In X-windows only:
The following keywords are used only when a window is created (in the
first call to Twin for the window):
/hide show window (equivalent of mode=2)
/show hide window (equivalent of mode=1)
title=title
if set and non-zero, used as title for window
xsize=xsize
horizontal window size
ysize=ysize
vertical window size
/quarter_screen
defines a window size of one quarterscreen (half screen
high/wide) (i.e. /tl,/tr,/bl,/br windows would fill up screen)
/onethird_screen
defines a window size of one-third screen high/wide
(i.e. all nine windows together would fill up screen)
/nocoordinates
by default, every time a 'show' is executed, the data
coordinates are set equal to device coordinates for the new
active window (!x.s and !y.s are modified directly).
If the /nocoordinates keyword !x and !y remain unchanged.
Keywords for selection of windows (if keyword WallPaper is NOT set):
/tl manipulates window in top-left corner
/tr manipulates window in top-right corner
/br manipulates window in bottom-right corner
/bl manipulates window in botton-left corner
/c manipulates window in center of screen
/cl manipulates window at center-left of screen
/tc manipulates window at top-center of screen
/cr manipulates window at center-right of screen
/bc manipulates window at bottom-center of screen
/newwin the next unused window is opened (ignored if /stackwin is used)
the position of the new window is topleft for /tl, etc.
/stackwin
same as newwin, but tries to stack the windows side by side
(left to right and top to bottom)
winnr=winnr
array of integers in the range [0,8], corresponding to the
windows /tl,/tr,..,etc.
The above window selection keywords work accumulative. E.g. the command
twin,/new,/tl,winnr=winnr
will manipulate the topleft window, plus the `winnr' windows, and it
will create the next available unused window.
/allwin selects all existing windows; or, if no windows exist yet,
selects all nine windows. /allwin is ignored if one of the
above keywords for window selection is used.
If none of the above keywords is used for selection, then the active
window is used (if it is one of the nine TWIN windows).
If there is no active window, then the first window is used.
/delete the specified window(s) is deleted
if both xsize and ysize are specified the window is deleted
only if the specified values differ from the window dimensions;
To find out whether or not the window has been deleted,
check the return value of DELETE (=0 if the window was not
deleted; =1 if the window was deleted)
Keywords for WallPaper option:
/wallpaper
fill up screen with small windows side by side until screen
is full
/wallpaper,/delete
delete all windows created with previous /wallpaper call
/wallpaper,show=number
makes panel `number' the active window and establishes
data coordinates which are identical to device coordinates.
OPTIONAL OUTPUT: (only if keyword DELETE is used)
delete = 0: No window deleted, =1: window deleted
windex
winmodes
CALLS: ***
InitVar, IsDisplay, IsType, IsWindowSystem, wvalid
CALLED BY:
Get_Page, RemoteView_Display2D, RemoteView_Display3D, RemoteView_PlotVertices
Set_Page, View, even_light, even_light_corrections, even_light_figures
even_light_info, even_light_photometry, even_light_plot
even_light_registration, jpl_test, nagoya_glevel, qView_Wall, smei_star_fit
PROCEDURE:
> 'TEK': Print escape sequences ("<ESC>[0/w" and "<ESC)[2/w") as given
on page 20.2 of the HDS programmers manual
> 'X': Calls to wset and wshow
> Windows are created with backing store enabled.
> The number in the window title is the TWIN number (0,..,8; which can
be used in the 'winnr' keyword), or, if the wallpaper option is used,
it's the panel number (0,..; which can be used in the /show keyword
to set the active panel window).
INCLUDE:
@compile_opt.pro ; On error, return to caller
COMMON BLOCKS:
common save_twin, old_mode,nr_window,xs_window,ys_window,nwall,xwall,ywall,nr_wall,ti_window
WARNING:
> The title of the window contains a number which is NOT THE IDL WINDOW ID
(!D.WINDOW). Every time a `wset' is executed the new !D.WINDOW value
is printed in the text window.
> In the first call to TWIN or during a /reset all existing windows are
nuked (including windows not created by TWIN).
> If TWIN encounters an active window not created by TWIN, the active
window is assimilated (and is treated as a TWIN window in following
calls to TWIN).
RESTRICTIONS:
> If called without the 'mode' argument, it may be necessary to call the
procedure twice to effect the desired change
> If TWIN is called without the /wallpaper keyword, then existing
wallpaper is removed before continuing (the reverse is not true:
wallpaper can be created, while TWIN windows are present.
MODIFICATION HISTORY:
DEC-1993, Paul Hick (UCSD)
JUL-2000, Paul Hick (UCSD); added call to 'wvalid' to make sure that the
requested window still exists before calling wshow or wset
[Previous]
[Next]
NAME:
txt_read
PURPOSE:
Read entire ascii file into character array
CATEGORY:
I/O
CALLING SEQUENCE:
status = txt_read(file, data, approx_recl)
INPUTS:
file scalar; type: string
fully qualified file name
OPTIONAL INPUT PARAMETERS:
approx_recl=approx_recl
scalar; type: integer
approximate record length in bytes
(passed to GuessRecs)
range_recl=range_recl
scalar: type: integer: default: 1
range of recordlength tested is approx_recl +/- range
(passed to GuessRecs)
OUTPUTS:
status scalar: type: byte
0: file not read
1: file read, data returned in 'data' array
data array[n]; type: string
array containing all records in file
(only if status=1)
OPTIONAL OUTPUT PARAMETERS:
recl=recl scalar: type: integer
guess at record length in bytes (= file size/# records)
(-1 if not succesful; output from GuessRecs)
nrec=nrec scalar: type: integer
# records on file
(nrec=-1 if opening of the file fails)
INCLUDE:
@compile_opt.pro ; On error, return to caller
CALLS: ***
GuessRecs, InitVar, IsType, destroyvar, do_file, gunzip_file, hide_env
CALLED BY:
GetNagoyaSources, env_slashes, htmd_cat, nagoya_glevel, sgp4_eph, sgp4_tlm
smei_base_testcase, smei_buf, smei_buf_get, smei_coriolis, smei_cv_catalogue
smei_orbits_stat, smei_setup_roi, smei_sgp4_orbits, smei_star_list
PROCEDURE:
If the approximate record length is specified then GuessRecs is called
to determine the record length. This will give only correct results for
fixed record length files.
If the approximate record length is not specified then the file is
pre-read to determine the record length. This will also work for
files with a variable record length.
MODIFICATION HISTORY:
JUL-2000, Paul Hick (UCSD/CASS)
JUL-2000, Paul Hick (UCSD/CASS; pphick@ucsd.edu)
Added capability to read gzipped files