/********************************************************/
/*                         riset.h                      */
/*  Header file for utility functions which are useful  */
/* in the calculation of rising, setting and culmination*/
/*   times of objects with time-dependent RA and Dec.   */
/*(For objects with fixed RA and Dec, see file 'radec'.)*/
/********************************************************/

/* Define values for a flag specifying type of calc.    */
#define RISECALC TRUE
#define  SETCALC FALSE

/*------------------------------------------------------*/
/*   Define a type corresponding to a function which    */
/*      returns the RA and Dec of the object at a       */
/*                   specified time.                    */
/*------------------------------------------------------*/
/* Parameters:  int id       -- ID of object in question.
 *              observerstr *ob_ptr -- pointer to observerstr containing
 *                                     details of date, time zone and
 *                                     location.
 *              int hour     -- time of day (hour part).
 *              int min      -- time of day (min part).
 *              REAL *raptr  -- ptr to REAL to fill in with RA.
 *              REAL *decptr -- ptr to REAL to fill in with Dec.
 *
 * Other info:  The following fields in the observerstr must be valid:
 *              year, month, day, offset, latit, longit.
 */
typedef void radecfntype(int id, observerstr *ob_ptr, int hour, int min,
                         REAL *raptr, REAL *decptr);


/*------------------------ riset_cul ---------------------
 * Description: Attempts to find time of culmination, given an
 *              initial guess.  Uses an iterative process.
 *
 * Parameters:  observerstr *ob_ptr  -- pointer to observerstr containing
 *                                      observer details.
 *              int maxit     -- limit on number of iterations.
 *              int converge  -- convergence criterion (in minutes).
 *              radecfntype *radecfn -- pointer to function which gives
 *                                      the RA & Dec of the object (see
 *                                      typedef above).
 *              int id        -- ID of object. (To be passed to radecfn.)
 *              int *hourptr  -- pointer to int containing guessed hour on 
 *                               entry. If function returns TRUE, guess has
 *                               been replaced by final value.  If FALSE,
 *                               value of *hourptr is undefined.
 *              int *minptr   -- as hourptr, but refers to minute.
 * Returns:     TRUE if time of culmination was found, FALSE otherwise.
 * Other info:  The following fields of the observerstr must be valid:
 *              year, month, day, offset.  The sid field of the observerstr
 *              must correspond with the hour and min fields.
 */

  BOOL riset_cul(observerstr *ob_ptr, int maxit, int converge,
                 radecfntype *radecfn, int id, int *hourptr, int *minptr);



/*---------------------- riset_riset ----------------------
 * Description: Attempts to find time of rising or setting, given
 *              an initial guess.  Uses an iterative process.
 *
 * Parameters:  observerstr *ob_ptr  -- pointer to observerstr containing
 *                                      observer details.
 *              int maxit     -- limit on number of iterations.
 *              int converge  -- convergence criterion (in minutes).
 *              radecfntype *radecfn -- pointer to function which gives
 *                                      the RA & Dec of the object (see
 *                                      typedef above).
 *              int id        -- ID of object. (To be passed to radecfn.)
 *              BOOL rise     -- If TRUE on entry, function looks for
 *                               time of rising.  Otherwise looks for
 *                               time of setting.
 *              REAL horalt   -- altitude of 'horizon' in radians
 *                               (assumed > 0).
 *              int *hourptr  -- pointer to int containing guessed hour on 
 *                               entry. If function returns TRUE, guess has
 *                               been replaced by final value.  If FALSE,
 *                               value of *hourptr is undefined.
 *              int *minptr   -- as hourptr, but refers to minute.
 * Returns:     TRUE if time of phenomenon was found, FALSE otherwise.
 * Other info:  The following fields of the observerstr must be valid:
 *              year, month, day, offset, latit.  The sid field of the
 *              observerstr must correspond with the hour and min fields.
 */

  BOOL riset_riset(observerstr *ob_ptr, int maxit, int converge,
                   radecfntype *radecfn, int id, BOOL rise, REAL horalt,
                   int *hourptr, int *minptr);
