LITMSOL2 Name
LITMSOL2
Author
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
Purpose
Solve the light-time equation between two moving bodies
Major Topics
Geometry, Physics, Dynamics Calling Sequence
LITMSOL2, T1, X1, Y1, Z1, T2, $
FUNC2, INFO2, RAW2, FUNCTARGS=, FUNCTSAVE=, $
/RECEIVER, TBASE=, TOLERANCE=, POSUNITS=, MAXITER=, $
LIGHT_TIME=, TGUESS=, ERROR=, NITER=, $
VX1=, VY1=, VZ1=, $
X2=, Y2=, Z2=, VX2=, VY2=, VZ2=, $
METHOD=, $
DELAY_FUNCTION=, DELAY_ARG1=, DELAY_ARG2=, $
DELAY_FUNCTARGS=
Description
The procedure LITMSOL2 solves the light time equation between two
moving bodies, A and B, in the solar system. Given the time and
position of reception or transmission of a photon at A, this
equation determines the time of transmission or reception at the
other solar system body B. Since both bodies may be moving, the
equation must be solved iteratively.
The user must know the "A" endpoint of the ray, with time T1 and
position X1,Y1,Z1. LITMSOL2 solves for the "B" endpoint time and
position T2 and X2,Y2,Z2 by propagating a light ray from one to the
other.
The position of the "B" body must be described as an interpolatable
function. The user function FUNC2 must calculate the position (and
velocity) of the body at any applicable time T2, in the requested
units.
By default the body "A" is considered the transmitter and LITMSOL2
calculates the time at which body "B" receives the ray. However,
if /RECEIVER is set, then body "A" is considered the receiver, and
LITMSOL2 calculates the time T2 in the past at which the ray must
have been transmitted by body "B" in order to be received by "A" at
time T1.
LITMSOL2 is able to estimate the T2 knowing only the time and
position at body "A". However, convergence may be faster if the
TGUESS, METHOD and/or VX1,VY1,VZ1 keywords are used. By default,
the initial guess for T2 is simply the same as T1. A better
estimate can be passed in the TGUESS keyword.
If velocity information is available, then LITMSOL2 can use a
simple linear corrector method in order to speed convergence
(i.e. Newton's method). The user should pass the velocity
at time T1 in the VX1,VY1,VZ1 keywords, and METHOD='CORRECTOR'.
The user may also specify a "delay" function which estimates any
additional light propagation delays along the path based on the
current estimates of the two ray endpoints. One such delay might
be the "Shapiro" delay due to general relativity.
Since the solution is iterative, the user may specify a solution
tolerance, and a maximum number of iterations. An estimate of the
solution error is returned in the ERROR keyword.
User Functions
The user must supply a function to interpolate the position of the
body at time T, which is passed in parameter FUNC2. FUNC2, a
scalar string, is the name of subroutine to call which must compute
position of body at time T2. The calling convention is the same as
JPLEPHINTERP, namely,
PRO FUNC2, INFO2, RAW2, T2, X2, Y2, Z2, VX2, VY2, VZ2, $
VELOCITY=, POSUNITS=, VELUNITS=, SAVE=, ...
The variables INFO2 and RAW2 are described below. The variable T2
is the requested time (TDB), and the position and velocity must be
returned in X2,Y2,Z2, VX2,VY2,VZ2, with the requested units. The
SAVE keyword can designate one keyword whose value will be returned
to the calling routine. Any other keywords can be passed using the
_EXTRA calling convention using the FUNCTARGS keyword.
The user may also supply an optional function to compute an
additional delay. The delay may be a function of the time and
position of both points "A" and "B". For example, the "Shapiro
delay" of photons in the solar potential is one such kind of delay.
The calling convention is,
DELAY = DELAY_FUNCTION(DELAY_ARG1, DELAY_ARG2, $
T1, X1, Y1, Z1, T2, X2, Y2, Z2, $
POSUNITS=, TBASE=, ...)
The returned delay must be in seconds, with the sense that a
positive value of DELAY indicates that the actual light travel time
is *longer* than the classical geometric travel time.
DELAY_ARG1, DELAY_ARG2 - can be any user-desired variables
T1 - same as T1 passed to LITMSOL2
X1,Y1,Z1 - same as passed to LITMSOL2
T2 - trial T2 interaction time in TDB Julian days
X2,Y2,Z2 - trial T2 interaction position, in POSUNITS
POSUNITS, TBASE - same as passed to LITMSOL2
... additional keywords - passed via DELAY_FUNCTARGS
Inputs
T1 - epoch of interaction, in Julian days, in the TDB timescale.
(scalar or vector)
X1, Y1, Z1 - coordinates of interaction, referred to the solar
system barycenter, in J2000 coordinates. Units are
described by POSUNITS. (scalar or vector)
FUNC2 - a scalar string, is the name of subroutine to call which
must compute position of body at time T2.
INFO2, RAW2 - arguments to the FUNC2 interpolation function. At
the very minimum, the INFO2 variable must be a
structure of the form,
INFO2 = {C: (speed of light in m/s), $
AU: (1 AU in light-seconds), $
... other fields ... }
The AU field is only required if POSUNITS EQ 'AU'.
Outputs
T2 - upon output, epoch of interaction at the second solar system
body, in Julian days, in the TDB timescale.
Keyword Parameters
DELAY_FUNCTION - user function to compute extra delay factors
based on the photon trajectory.
DELAY_ARG1,DELAY_ARG2 - arguments to the DELAY_FUNCTION. These
variables are not touched by LITMSOL2, but merely passed
directly to DELAY_FUNCTION.
DELAY_FUNCTARGS - a single structure containing additional keyword
arguments passed to DELAY_FUNCTION using the _EXTRA method.
ERROR - upon return, a vector giving the estimated error in the
solution for each point, expressed in POSUNITS. This
quantity should be less than TOLERANCE unless the number
of iterations exceeded MAXITER.
FUNCTARGS - a single structure containing additional keyword
arguments passed to FUNC2 using the _EXTRA method.
FUNCTSAVE - a named variable which will contain the results of
the SAVE keyword when calling FUNC2 upon return.
LIGHT_TIME - upon return, LIGHT_TIME is an array containing the
estimated light time for each requested time.
MAXITER - maximum number of solution iterations to be taken.
Default: 5
METHOD - solution method used, one of 'CONSTANT' or 'CORRECTOR'
The 'CONSTANT' method uses simple iteration. The
'CORRECTOR' method uses a linear corrector to accelerate
convergence by accounting for the line of sight velocity,
but requires VX1, VY1, VZ1 to be passed.
Default: 'CONSTANT'
NITER - upon return, contains the actual number of iterations used.
POSUNITS - the units for positions, one of 'CM', 'KM', 'LT-S' or
'AU'.
Default: 'CM'
RECEIVER - if set, then the epoch T1 is a reception of a photon.
Otherwise T1 is the epoch of transmission of a photon.
TGUESS - a vector of the same size as T1, containing an initial
estimate of T2.
Default: LITMSOL2 uses its own estimate based on T1.
TOLERANCE - the solution tolerance, expressed in POSUNITS.
Default: 1000 CM
VX1, VY1, VZ1 - upon input, the body velocity at time T1, in
VELUNITS units. This information is required only
if the CORRECTOR method is used.
VELUNITS - the units for velocities (and Shapiro derivative).
Default: POSUNITS+'/S'
X2, Y2, Z2, VX2, VY2, VZ2 - upon return, the body position and
velocity at time T2, in units of POSUNITS and VELUNITS.
Example
See Also
JPLEPHREAD, JPLEPHINTERP, SHAPDEL
Modification History
Major modifications, based on LITMSOL, 2009-01-05, CM
Documented, 2009-05-12, CM