Table of contents
CSPICE_PHASEQ computes the apparent phase angle for a target, observer,
illuminator set of ephemeris objects.
Given:
et double precision scalar the time in ephemeris seconds past J2000
TDB at which to compute the phase angle.
help, et
DOUBLE = Scalar
target scalar string naming the target body.
help, target
STRING = Scalar
Optionally, you may supply a string containing the integer ID
code for the object. For example both "MOON" and "301" are
legitimate strings that indicate the Moon is the target body.
Case and leading or trailing blanks are not significant
in the string `target'.
illmn scalar string naming the illuminating body.
help, illmn
STRING = Scalar
Optionally, you may supply a string containing the integer ID
code for the object. For example both "SUN" and "10" are
legitimate strings that indicate the sun is the illuminating
body.
Case and leading or trailing blanks are not significant
in the string `illmn'.
In most cases, `illmn' is the sun.
obsrvr scalar string naming the observer body.
help, obsrvr
STRING = Scalar
Optionally, you may supply a string containing the integer ID
code for the object. For example both "MOON" and "301" are
legitimate strings that indicate the Moon is the observer body.
Case and leading or trailing blanks are not significant
in the string `obsrvr'.
abcorr scalar string indicating the aberration corrections to apply to
the state evaluations to account for one-way light time and
stellar aberration.
help, abcorr
STRING = Scalar
This routine accepts only reception mode aberration
corrections. See the Aberration Correction Required
Reading (abcorr.req) for a detailed description of
the aberration correction options. For convenience,
the appropriate aberration options are listed below:
'NONE' Apply no correction. Returns the "true"
geometric state.
'LT' "Reception" case: correct for
one-way light time using a Newtonian
formulation.
'LT+S' "Reception" case: correct for
one-way light time and stellar
aberration using a Newtonian
formulation.
'CN' "Reception" case: converged
Newtonian light time correction.
'CN+S' "Reception" case: converged
Newtonian light time and stellar
aberration corrections.
Case and leading or trailing blanks are not significant
in the string `abcorr'.
the call:
phaseq = cspice_phaseq( et, target, illmn, obsrvr, abcorr )
returns:
phaseq scalar double precision, optionally light-time corrected phase
angle between `target' and `illmn' as observed from `obsrvr'.
help, phaseq
DOUBLE = Scalar
The range of the phase angle is [0, pi].
None.
Any numerical results shown for this example may differ between
platforms as the results depend on the SPICE kernels used as input
and the machine specific arithmetic implementation.
1) Determine the time intervals from December 1, 2006 UTC to
January 31, 2007 UTC for which the sun-moon-earth configuration
phase angle satisfies the relation conditions with respect to a
reference value of 0.57598845 radians (the phase angle at
January 1, 2007 00:00:00.000 UTC, 33.001707 degrees). Also
determine the time windows corresponding to the local maximum and
minimum phase angles, and the absolute maximum and minimum phase
angles during the search interval. The configuration defines the
sun as the illuminator, the moon as the target, and the earth as
the observer.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: phaseq_ex1.tm
This meta-kernel is intended to support operation of SPICE
example programs. The kernels shown here should not be
assumed to contain adequate or correct versions of data
required by SPICE-based user applications.
In order for an application to use this meta-kernel, the
kernels referenced here must be present in the user's
current working directory.
The names and contents of the kernels referenced
by this meta-kernel are as follows:
File name Contents
--------- --------
de421.bsp Planetary ephemeris
pck00009.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00009.tpc',
'naif0009.tls' )
\begintext
End of meta-kernel
Example code begins here.
PRO phaseq_ex1
MAXWIN = 5000L
TIMFMT = 'YYYY-MON-DD HR:MN:SC.###'
TIMLEN = 41
relate = [ '=', '<', '>', $
'LOCMIN', 'ABSMIN', 'LOCMAX', 'ABSMAX' ]
;;
;; Load kernels.
;;
cspice_furnsh, 'phaseq_ex1.tm'
;;
;; Store the time bounds of our search interval in
;; the cnfine confinement window.
;;
cspice_str2et, [ '2006 DEC 01', '2007 JAN 31'], et
;;
;; Search using a step size of 1 day (in units of seconds).
;; The reference value is 0.57598845 radians. We're not using the
;; adjustment feature, so we set `adjust' to zero.
;;
target = 'MOON'
illmn = 'SUN'
abcorr = 'LT+S'
obsrvr = 'EARTH'
refval = 0.57598845D
adjust = 0.D
step = cspice_spd()
nintvls = MAXWIN
cnfine = cspice_celld( 2 )
cspice_wninsd, et[0], et[1], cnfine
result = cspice_celld( MAXWIN*2)
for j=0, 6 do begin
print, 'Relation condition: ', relate[j]
;;
;; Perform the search. The SPICE window `result' contains
;; the set of times when the condition is met.
;;
cspice_gfpa, target, illmn, abcorr, $
obsrvr, relate[j], refval, $
adjust, step, nintvls,$
cnfine, result
;;
;; List the beginning and ending times in each interval
;; if `result' contains data.
;;
count = cspice_wncard( result )
if ( count eq 0 ) then begin
print, 'Result window is empty.'
endif else begin
for i= 0L, (count - 1L ) do begin
;;
;; Fetch the endpoints of the Ith interval
;; of the result window.
;;
cspice_wnfetd, result, i, left, right
cspice_timout, [left, right], TIMFMT, TIMLEN, timstr
phaseq = cspice_phaseq( left, target, illmn, $
obsrvr, abcorr )
print, 'Start time = ', timstr[0], phaseq
phaseq = cspice_phaseq( right, target, illmn, $
obsrvr, abcorr )
print, 'Stop time = ', timstr[1], phaseq
endfor
endelse
print, ' '
endfor
;;
;; It's always good form to unload kernels after use,
;; particularly in IDL due to data persistence.
;;
cspice_kclear
END
When this program was executed on a Mac/Intel/IDL8.x/64-bit
platform, the output was:
Relation condition: =
Start time = 2006-DEC-02 13:31:34.414 0.57598845
Stop time = 2006-DEC-02 13:31:34.414 0.57598845
Start time = 2006-DEC-07 14:07:55.470 0.57598845
Stop time = 2006-DEC-07 14:07:55.470 0.57598845
Start time = 2006-DEC-31 23:59:59.997 0.57598845
Stop time = 2006-DEC-31 23:59:59.997 0.57598845
Start time = 2007-JAN-06 08:16:25.512 0.57598845
Stop time = 2007-JAN-06 08:16:25.512 0.57598845
Start time = 2007-JAN-30 11:41:32.557 0.57598845
Stop time = 2007-JAN-30 11:41:32.557 0.57598845
Relation condition: <
Start time = 2006-DEC-02 13:31:34.414 0.57598845
Stop time = 2006-DEC-07 14:07:55.470 0.57598845
Start time = 2006-DEC-31 23:59:59.997 0.57598845
Stop time = 2007-JAN-06 08:16:25.512 0.57598845
Start time = 2007-JAN-30 11:41:32.557 0.57598845
Stop time = 2007-JAN-31 00:00:00.000 0.46827909
Relation condition: >
Start time = 2006-DEC-01 00:00:00.000 0.94071497
Stop time = 2006-DEC-02 13:31:34.414 0.57598845
Start time = 2006-DEC-07 14:07:55.470 0.57598845
Stop time = 2006-DEC-31 23:59:59.997 0.57598845
Start time = 2007-JAN-06 08:16:25.512 0.57598845
Stop time = 2007-JAN-30 11:41:32.557 0.57598845
Relation condition: LOCMIN
Start time = 2006-DEC-05 00:16:50.317 0.086121423
Stop time = 2006-DEC-05 00:16:50.317 0.086121423
Start time = 2007-JAN-03 14:18:31.977 0.079899769
Stop time = 2007-JAN-03 14:18:31.977 0.079899769
Relation condition: ABSMIN
Start time = 2007-JAN-03 14:18:31.977 0.079899769
Stop time = 2007-JAN-03 14:18:31.977 0.079899769
Relation condition: LOCMAX
Start time = 2006-DEC-20 14:09:10.392 3.0550629
Stop time = 2006-DEC-20 14:09:10.392 3.0550629
Start time = 2007-JAN-19 04:27:54.600 3.0746039
Stop time = 2007-JAN-19 04:27:54.600 3.0746039
Relation condition: ABSMAX
Start time = 2007-JAN-19 04:27:54.600 3.0746039
Stop time = 2007-JAN-19 04:27:54.600 3.0746039
This routine returns the phase angle using the location of the
bodies (if point objects) or the centers of the bodies (if finite
bodies).
illmn obsrvr
illmn as seen ^ /
from target at | /
et - LT. | /
>|..../< phase angle
| /
. | /
. | /
. |v target as seen from obsrvr
sep . target at et
. /
/
v
pi = sep + phase
so
phase = pi - sep
1) If the body name to SPICE ID look-up fails for any of the
`target', `illmn', or `obsrvr' names, the error
SPICE(IDCODENOTFOUND) is signaled by a routine in the call
tree of this routine.
2) If the aberration correct, `abcorr', indicates a transmission
based correction, the error SPICE(INVALIDOPTION) is signaled
by a routine in the call tree of this routine.
3) If the `target', `illmn', and `obsrvr' are not unique, the error
SPICE(BODIESNOTDISTINCT) is signaled by a routine in the call
tree of this routine.
4) If any of the input arguments, `et', `target', `illmn',
`obsrvr' or `abcorr', is undefined, an error is signaled by
the IDL error handling system.
5) If any of the input arguments, `et', `target', `illmn',
`obsrvr' or `abcorr', is not of the expected type, or it does
not have the expected dimensions and size, an error is
signaled by the Icy interface.
None.
None.
ABCORR.REQ
ICY.REQ
None.
J. Diaz del Rio (ODC Space)
B.V. Semenov (JPL)
E.D. Wright (JPL)
-Icy Version 1.0.2, 01-JUN-2021 (JDR)
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
Edited the header to comply with NAIF standard. Renamed example's
meta-kernel.
Removed reference to the routine's corresponding CSPICE header from
-Abstract section.
Added arguments' type and size information in the -I/O section.
-Icy Version 1.0.1, 02-FEB-2017 (EDW) (BVS)
Eliminated typo in example code; no change to functionality.
Shortened permutted index entry.
-Icy Version 1.0.0, 11-NOV-2013 (EDW)
compute phase angle for arbitrary illumination source
|