Welcome to the Harris Geospatial product documentation center. Here you will find reference guides, help documents, and product libraries.


LITMSOL2

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
  $Id: litmsol2.pro,v 1.5 2010/05/04 21:01:52 craigm Exp $



© 2018 Harris Geospatial Solutions, Inc. |  Legal
My Account    |    Store    |    Contact Us