NAME:
  appuldis
 PURPOSE:   (one line only)
  Find the circumstances of an appulse between a star and a solar system object
 DESCRIPTION:
  Given the ephemeris
  The approximate time of the appulse must be within +/-30 minutes or this
    will fail.
 CATEGORY:
  Astronomy
 CALLING SEQUENCE:
  appuldis,objcode,obscode,jd,ra,dec,jdmin,sep
 INPUTS:
  objcode - Standard object code (see ephem.pro)
  obscode - Standard observatory code or a structure with the observatory
              information.  WGS84 assumed.
              name - name of observatory
              lat  - latitude of observatory (radians)
              lon  - west longitude of observatory (radians)
              alt  - altitude of observatory (meters)
  jd   - Approximate time of appulse
  ra   - right ascension of the star, J2000
  dec  - declination of the star, J2000
 OPTIONAL INPUT PARAMETERS:
 KEYWORD INPUT PARAMETERS:
  ET      - Flag, if set, all times are in Ephemeris Time, default is UTC
              This is most important for the output.  You can get away with
              inputing either.
  VERBOSE - Flag, if set, prints information about event to terminal
  STARERR - Star position uncertainty (arcsec), default is 0.050 arcsec
  PREDERR - You can override the ephemeris error based calculation of the
              event errors with this.  Provide a two element vector:
                  [xtrackerr,time_err]
              where xtrackerr is the cross-track 1-sigma uncertainty in km
              and time_err is the down-track 1-sigma uncertainty in seconds.
            This is optional for 'A' objects but required for 'P' objects.
  OBJNAME - Object name.
            This is optional for 'A' objects but required for 'P' objects with
              the verbose option.
  IN_HV   - Hv value to use for the object.  Unsed only if OBJNAME is supplied.
              If not provided and OBJNAME is, this value defaults to 10
  SUPP - optional anonymous structure that contains extra information about
           the object.  This can be used either to override the standard
           information, or to provide missing information in cases where
           a spice kernel is being used.  Tags required are:
             name: descriptive name the way you want to see it
             diameter: size of object in km
             hv: absolute magnitude of object
             albedo: albedo for surface
             etrack: 1-sigma uncertainty in cross-track position [km]
             etime: 1-sigma uncertainty in the down-track position [seconds]
           This takes precedence over any other sources of information
 OUTPUTS:
  jdmin   - Time of the minimum separation
  sep     - Separation between star and object at jdmin (arcsec)
                 If you get a negative number it means the search was not
                 successful in finding a minimum near the input time.
 KEYWORD OUTPUT PARAMETERS:
  info - Anonymous structure with auxillary information about the object
            at the time of the minimum separation.
           objname - Full name/designation of object
           jd  - Time of close approach
           hv  - Absolute magnitude of object
           et  - Flag, set if time is ET
           minsep - separate at close approach time (arcsec)
           pa  - Position angle of object wrt star at minimum separation
           sun - Heliocentric distance of object
           earth - topocentric distance of object
           phang - phase angle (degrees)
           selong - solar elongation (degrees)
           melong - lunar elongation (degrees)
           mphase - Lunar phase
           kmscale - scale on plane of sky in km/arcsec
           oam    - Airmass of object at time of event
           oalt   - object elevation (degrees)
           oaz    - object azimuth, westward from south
           salt   - solar elevation (degrees)
           malt   - lunar elevation (degrees)
           speed - projected speed of object relative to the star (km/sec)
           rate  - projected speed of object ralative to the star (arcsec/hr)
           diam1  - Diameter of object assuming 5% albedo (km)
           diam2  - Diameter of object assuming 30% albedo (km)
           chord1 - Maximum occultation duration assuming a 5% albedo size
           chord2 - Maximum occultation duration assuming a 30% albedo size
           angsha - Position angle of track on the plane of the sky, E of N
           etime  - 1-sigma error in event time (seconds)
           etrack - 1-sigma error in cross-track position (km)
           coverage - Fraction of the 1-sigma cross track error that could
                         be covered if track is centered on network
           err    - 1-sigma ephemeris uncertainty for the object at the
                       time of the close approach in arcsec
           errkm  - 1-sigma ephemeris uncertainty in km.
 COMMON BLOCKS:
 SIDE EFFECTS:
 RESTRICTIONS:
 PROCEDURE:
 MODIFICATION HISTORY:
  Written by Marc W. Buie, Southwest Research Institute, 2015/03/07
  2015/09/24, MWB, Added position angle output
  2019/10/11, MWB, Added PREDERR option
  2019/12/30, MWB, Added OBJNAME keyword
  2020/03/25, MWB, Avoid computing ephemeris error for P objects.
  2020/11/18, MWB, fixed bug introduced with OBJNAME keyword, fix includes
                     the new IN_HV keyword
  2022/01/11, MWB, added summary printout information to returned structure
  2023/07/24, MWB, added SUPP keyword
  2024/04/21, MWB, added vmag and gtarg to returned structure
  2024/07/06, MWB, rework for new obs tools