## 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