Table of contents
Deprecated: This routine has been superseded by the Icy routine
cspice_subslr. This routine is supported for purposes of
backward compatibility only.
CSPICE_SUBSOL determines the coordinates of the sub-solar
point on a target body as seen by a specified observer
at a specified epoch, optionally corrected for planetary
(light time) and stellar aberrations.
Given:
method a short string specifying the computation method to be used.
help, method
STRING = Scalar
The choices are:
'Near point' The sub-solar point is defined
as the nearest point on the
target to the sun.
'Intercept' The sub-observer point is
defined as the target surface
intercept of the line
containing the target's center
and the sun's center.
In both cases, the intercept computation treats the
surface of the target body as a triaxial ellipsoid.
The ellipsoid's radii must be available in the kernel
pool.
Neither case nor white space are significant in
`method'. For example, the string ' NEARPOINT' is
valid.
target the name of the target body.
help, target
STRING = Scalar
`target' is case-insensitive, and leading and trailing blanks
in `target' are not significant. 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.
This routine assumes that the target body is modeled
by a tri-axial ellipsoid, and that a PCK file
containing its radii has been loaded into the kernel
pool via cspice_furnsh.
et the epoch in ephemeris seconds past J2000 at which the sub-solar
point on the target body is to be computed.
help, et
DOUBLE = Scalar
abcorr indicates the aberration corrections to be applied when
computing the observer-target state.
help, abcorr
STRING = Scalar
`abcorr' may be any of the following.
'NONE' Apply no correction. Return the
geometric sub-solar point on the target
body.
'LT' Correct for planetary (light time)
aberration. Both the state and rotation
of the target body are corrected for one
way light time from target to observer.
The state of the sun relative to the
target is corrected for one way light
from the sun to the target; this state
is evaluated at the epoch obtained by
retarding `et' by the one way light time
from target to observer.
'LT+S' Correct for planetary (light time) and
stellar aberrations. Light time
corrections are the same as in the 'LT'
case above. The target state is
additionally corrected for stellar
aberration as seen by the observer, and
the sun state is corrected for stellar
aberration as seen from the target.
'CN' Converged Newtonian light time
correction. In solving the light time
equation, the 'CN' correction iterates
until the solution converges (three
iterations on all supported platforms).
Whether the 'CN+S' solution is
substantially more accurate than the
'LT' solution depends on the geometry
of the participating objects and on the
accuracy of the input data. In all
cases this routine will execute more
slowly when a converged solution is
computed. See the -Particulars section
of cspice_spkezr for a discussion of precision
of light time corrections. Light time
corrections are applied as in the 'LT'
case.
'CN+S' Converged Newtonian light time
corrections and stellar aberration
correction. Light time and stellar
aberration corrections are applied as
in the 'LT+S' case.
obsrvr the name of the observing body, typically a spacecraft, the
earth, or a surface point on the earth.
help, obsrvr
STRING = Scalar
`obsrvr' is case-insensitive, and leading and trailing blanks
in `obsrvr' are not significant. Optionally, you may supply a
string containing the integer ID code for the object. For
example both 'EARTH' and '399' are legitimate strings that
indicate the earth is the observer.
the call:
cspice_subsol, method, target, et, abcorr, obsrvr, spoint
returns:
spoint the sub-solar point on the target body at `et' expressed
relative to the body-fixed frame of the target body.
help, spoint
DOUBLE = Array[3]
The sub-solar point is defined either as the point on
the target body that is closest to the sun, or the
target surface intercept of the line containing the
target's center and the sun's center; the input
argument `method' selects the definition to be used.
The body-fixed frame, which is time-dependent, is
evaluated at `et' if `abcorr' is 'NONE'; otherwise the
frame is evaluated at et-ltime, where `ltime' is the one way
light time from target to observer.
The state of the target body is corrected for
aberration as specified by `abcorr'; the corrected
state is used in the geometric computation. As
indicated above, the rotation of the target is
retarded by one way light time if `abcorr' specifies
that light time correction is to be done.
The state of the sun as seen from the observing
body is also corrected for aberration as specified
by `abcorr'. The corrections, when selected, are
applied at the epoch et-ltime, where `ltime' is the one way
light time from target to observer.
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) Calculate the location of the sub solar point on the Earth as
seen from Mars at a specified epoch, using the 'near point'
and the 'intercept' options. Apply light time correction to
compensate for Mars' extreme distance from Earth.
Compute the distance between the location of the sub-solar
points computed using the two different options, and the
angular separation between their position vectors.
Use the meta-kernel shown below to load the required SPICE
kernels.
KPL/MK
File name: subsol_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
pck00008.tpc Planet orientation and
radii
naif0009.tls Leapseconds
\begindata
KERNELS_TO_LOAD = ( 'de421.bsp',
'pck00008.tpc',
'naif0009.tls' )
\begintext
End of meta-kernel
Example code begins here.
PRO subsol_ex1
;;
;; Load kernels.
;;
cspice_furnsh, 'subsol_ex1.tm'
;;
;; First use 'Near Point'
;;
cspice_subsol, 'near point', 'earth', 0.d, 'lt+s', 'mars', point1
print, 'Sub-solar location coordinates - near point:'
print, FORMAT='(" ",3F15.8)', point1
print
;;
;; Now 'Intercept'
;;
cspice_subsol, 'intercept', 'earth', 0.d, 'lt+s', 'mars', point2
print, 'Sub solar location coordinates - intercept'
print, FORMAT='(" ",3F15.8)', point2
print
;;
;; Calculate the Euclidean distance between the two locations
;; and the angular separation between the position vectors.
;;
dist = cspice_vnorm( point1 - point2 )
sep = cspice_vsep ( point1, point2 ) * cspice_dpr( )
print, FORMAT ='(A,F8.5)', $
'Distance between locations (km): ', dist
print, FORMAT ='(A,F8.5)', $
'Angular separation between locations (deg): ', sep
;;
;; 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:
Sub-solar location coordinates - near point:
5850.45333391 509.68870743 -2480.24473621
Sub solar location coordinates - intercept
5844.43860060 509.16470673 -2494.39670104
Distance between locations (km): 15.38602
Angular separation between locations (deg): 0.13829
Note that the difference between the location of the sub-solar
points computed using the two different options, results from the
non-spherical shape of the Earth.
cspice_subsol computes the sub-solar point on a target body, as seen by
a specified observer.
There are two different popular ways to define the sub-solar point:
"nearest point on target to the sun" or "target surface intercept of
line containing target and sun." These coincide when the target is
spherical and generally are distinct otherwise.
When comparing sub-point computations with results from sources
other than SPICE, it's essential to make sure the same geometric
definitions are used.
If any of the listed errors occur, the output arguments are
left unchanged.
1) If the input argument `method' is not recognized, the error
SPICE(DUBIOUSMETHOD) is signaled by a routine in the call tree
of this routine.
2) If either of the input body names `target' or `obsrvr' cannot be
mapped to NAIF integer codes, the error SPICE(IDCODENOTFOUND)
is signaled by a routine in the call tree of this routine.
3) If `obsrvr' and `target' map to the same NAIF integer ID codes,
the error SPICE(BODIESNOTDISTINCT) is signaled by a routine in
the call tree of this routine.
4) If frame definition data enabling the evaluation of the state
of the target relative to the observer in target body-fixed
coordinates have not been loaded prior to calling cspice_subsol, an
error is signaled by a routine in the call tree of this
routine.
5) If the specified aberration correction is not recognized, an
error is signaled by a routine in the call tree of this
routine.
6) If insufficient ephemeris data have been loaded prior to
calling cspice_subsol, an error is signaled by a
routine in the call tree of this routine.
7) If the triaxial radii of the target body have not been loaded
into the kernel pool prior to calling cspice_subsol, an error is
signaled by a routine in the call tree of this routine.
8) If the size of the `target' body radii kernel variable is not
three, an error is signaled by a routine in the call tree of
this routine.
9) If any of the three `target' body radii is less-than or equal to
zero, an error is signaled by a routine in the call tree of
this routine.
10) If PCK data supplying a rotation model for the target body
have not been loaded prior to calling cspice_subsol, an error is
signaled by a routine in the call tree of this routine.
11) If any of the input arguments, `method', `target', `et',
`abcorr' or `obsrvr', is undefined, an error is signaled by
the IDL error handling system.
12) If any of the input arguments, `method', `target', `et',
`abcorr' or `obsrvr', is not of the expected type, or it does
not have the expected dimensions and size, an error is
signaled by the Icy interface.
13) If the output argument `spoint' is not a named variable, an
error is signaled by the Icy interface.
Appropriate SPK, PCK, and frame data must be available to
the calling program before this routine is called. Typically
the data are made available by loading kernels; however the
data may be supplied via routine interfaces if applicable.
The following data are required:
- SPK data: ephemeris data for sun, target, and observer must
be loaded. If aberration corrections are used, the states of
sun, target, and observer relative to the solar system
barycenter must be calculable from the available ephemeris
data. Ephemeris data are made available by loading
one or more SPK files via cspice_furnsh.
- PCK data: triaxial radii for the target body must be loaded
into the kernel pool. Typically this is done by loading a
text PCK file via cspice_furnsh.
- Further PCK data: a rotation model for the target body must
be loaded. This may be provided in a text or binary PCK
file which is loaded via cspice_furnsh.
- Frame data: if a frame definition is required to convert
the sun, observer, and target states to the body-fixed frame
of the target, that definition must be available in the
kernel pool. Typically the definition is supplied by loading
a frame kernel via cspice_furnsh.
In all cases, kernel data are normally loaded once per program
run, NOT every time this routine is called.
1) The appropriate kernel data must have been loaded before this
routine is called. See the -Files section above.
ICY.REQ
FRAMES.REQ
PCK.REQ
SPK.REQ
TIME.REQ
None.
N.J. Bachman (JPL)
J. Diaz del Rio (ODC Space)
B.V. Semenov (JPL)
E.D. Wright (JPL)
-Icy Version 1.0.5, 01-NOV-2021 (JDR)
Edited the header to comply with NAIF standard. Added example's
problem statement and meta-kernel. Reformatted example's output
and added call to cspice_kclear.
Added -Parameters, -Exceptions, -Files, -Restrictions,
-Literature_References and -Author_and_Institution sections.
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.4, 10-JUL-2014 (NJB) (EDW)
Discussion of light time corrections was updated. Assertions
that converged light time corrections are unlikely to be
useful were removed.
-Icy Version 1.0.3, 18-MAY-2010 (BVS)
Index line now states that this routine is deprecated.
-Icy Version 1.0.2, 11-NOV-2008 (EDW)
Edits to header; -Abstract now states that this routine is
deprecated.
-Icy Version 1.0.1, 27-MAR-2006 (EDW)
Corrected typo "non-spherical shape of Mars" to "non-spherical
shape of earth".
-Icy Version 1.0.0, 16-JUN-2003 (EDW)
DEPRECATED sub-solar point
|