;+ ; NAME: ; LITMSOL ; ; 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 ; ; CALLING SEQUENCE: ; LITMSOL, T1, X1, Y1, Z1, T2, INFO2, RAW2, OBJ2, INFOSUN, RAWSUN, $ ; /RECEIVER, TBASE=, TOLERANCE=, POSUNITS=, MAXITER=, $ ; /NO_SHAPIRO ; ; DESCRIPTION: ; ; The procedure LITMSOL solves the light time equation between two ; moving bodies in the solar system. Given the time and position of ; reception or transmission of a photon, this equation determines the ; time of transmission or reception at the other solar system body. ; Since both bodies may be moving, the equation must be solved ; iteratively. ; ; The trajectories of solar system bodies must be described by either ; a JPL ephemeris, or by a JPL-like ephemeris generated by ; JPLEPHMAKE. This routine calls JPLEPHINTERP. ; ; The user specifies the known time and position of interaction as ; T1, X1, Y1 and Z1, in units of POSUNITS. The time of interaction ; at the other body -- the solution to the light time equation -- is ; returned as T2. If the photon was *received* at time T1, then the ; RECEIVER keyword should be set (in which case the transmission must ; have occurred in the past). ; ; Since the solution is iterative, the user may specify a solution ; tolerance, and a maximum number of iterations. ; ; If users wish to include the Shapiro time delay, which has a ; maximum amplitude of approximately 250 usec, they must specify the ; ephemeris of the Sun (INFOSUN, RAWSUN). The Shapiro delay is the ; extra general relativistic delay caused by the Sun's potential. ; ; ; 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) ; ; INFO2, RAW2 - ephemeris of other solar system body, returned by ; JPLEPHREAD or JPLEPHMAKE. ; ; INFOSUN, RAWSUN - ephemeris of at least the Sun, as returned by ; JPLEPHREAD. Only used of NO_SHAPIRO is not set. ; ; ; OUTPUTS: ; ; T2 - upon output, epoch of interaction at the second solar system ; body, in Julian days, in the TDB timescale. ; ; ; KEYWORD PARAMETERS: ; ; RECEIVER - if set, then the epoch T1 is a reception of a photon. ; Otherwise T1 is the epoch of transmission of a photon. ; ; VX1, VY1, VZ1 - upon input, the body velocity at time T1, in ; VELUNITS units. This information is required only ; if the SHAPIRO_DERIV is required. ; ; X2, Y2, Z2 - upon return, the body position at time T2, in ; POSUNITS units. ; VX2, VY2, VZ2 - upon return, the body velocity at time T2, in ; VELUNITS units. ; ; TBASE - a fixed epoch time (Julian days) to be added to each value ; of T1. Since subtraction of large numbers occurs with ; TBASE first, the greatest precision is achieved when TBASE ; is expressed as a nearby julian epoch, T1 is expressed ; as a small offset from the fixed epoch. ; Default: 0 ; ; POSUNITS - the units for positions, one of 'CM', 'KM', 'LT-S' or ; 'AU'. ; Default: 'CM' ; VELUNITS - the units for velocities (and Shapiro derivative). ; Default: POSUNITS+'/S' ; ; TOLERANCE - the solution tolerance, expressed in POSUNITS. ; Default: 1000 CM ; ; 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. ; ; MAXITER - maximum number of solution iterations to be taken. ; Default: 5 ; NITER - upon return, contains the actual number of iterations used. ; ; SHAPIRO_CALC - method of calculating Shapiro delay, a string with ; one value of 'NONE', 'DELAY' or 'BOTH'. NONE means ; do not calculate any Shapiro delay values. DELAY ; means calculate Shapiro delay only. BOTH means ; calculate the delay *and* its derivative with ; respect to time. If SHAPIRO_CALC is set to ; DELAY or BOTH, then INFOSUN and RAWSUN must be ; specified. If BOTH, then VX1, VY1 and VZ1 must ; also be specified. This keyword overrides ; NO_SHAPIRO. ; NO_SHAPIRO - if set, then the Shapiro delay will not be accounted ; for. Use SHAPIRO_CALC instead. ; SHAPIRO_DELAY - upon return, contains the Shapiro delay in ; seconds, if SHAPIRO_CALC is set to 'DELAY' or ; 'BOTH'. ; SHAPIRO_DERIV - upon return, contains the derivative of the ; Shapiro delay, in light seconds per time unit of ; velocity (SHAPIRO_CALC must be set to 'BOTH' to ; enable this calculation). Note that you must ; supply VX1, VY1 and VZ1 to get the derivative ; value. ; ; ; EXAMPLE: ; ; ; ; SEE ALSO: ; ; JPLEPHREAD, JPLEPHINTERP ; ; ; MODIFICATION HISTORY: ; Written, 6 May 2002, CM ; Documented, 12 May 2002, CM ; Added TGUESS keyword, 29 May 2002, CM ; Added ERROR and X/Y/ZOFF keywords, 25 Sep 2002, CM ; Extensive revisions: addition of SHAPIRO_{CALC,DELAY,DERIV} ; values; input VX1, VY1 and VZ1; output X2, Y2, Z2 and VX2 VY2 ; and VZ2; and VELUNITS keyword, 07 Mar 2007, CM ; Allow user specified function to interpolate INFO2/RAW2 via ; INTERP_FUNC keyword, 09 Oct 2008, CM ; ; $Id: litmsol.pro,v 1.7 2008/10/10 00:50:19 craigm Exp $ ; ;- ; Copyright (C) 2002, 2007, 2008, Craig Markwardt ; This software is provided as is without any warranty whatsoever. ; Permission to use, copy, modify, and distribute modified or ; unmodified copies is granted, provided this copyright and disclaimer ; are included unchanged. ;-