/********************************************************
 * algorithm.h
 *
 * These are the routines for a near neighbor algorithm.
 *
 * Sixth Annual DIMACS Implementation Challenge
 * Author:  Michael Goldwasser (wass@cs.princeton.edu)
 * Created: Dec 23, 1997
 *******************************************************/


#ifndef _ALGORITHM
#define _ALGORITHM

#include "oracle.h" 


/*  abstract object -- cast to correct type within algorithm.c */
typedef void AbstractDS;



/********************************************************
 * AbstractDS* Preprocess(Oracle* ora)
 *
 * Parameters:
 *   Oracle* ora --- pointer to the data set oracle
 *
 * Returns:
 *   A pointer to a data structure of your choice which is passed on
 *   to the routine `FindNeighbor' whenever a later query is made.
 *
 * Description:
 *   The purpose of this routine depends greatly on the nearest
 *   neighbor algorithm which will be used to answer queries.  Access
 *   to the data set is given through the use of the oracle.  All
 *   preprocessing should take place in this routine, and any
 *   resulting data structures must be saved as part of the returned
 *   object.
 *
 * Note:
 *   This routine should NOT ask the oracle about any of the query
 *   points. 
 *  
 * Additional Note:
 *   If the algorithm requires additional parameters from the user,
 *   These should be added to the functions parameter list, and the
 *   corresponding values should be sent by the main program when
 *   calling this function.
 *  
 *******************************************************/
AbstractDS* Preprocess(Oracle* ora);



/********************************************************
 * void FindNeighbor(Oracle* ora,  AbstractDS* ads, int query)
 *
 * Parameters:
 *   Oracle* ora     --- pointer to the data set oracle
 *   AbstractDS* ads --- pointer to your data structure
 *   int query       --- which query point
 *
 * Description:
 *   This is the neighbor search query routine.  The algorithm may use
 *   the preprocessed data structure in conjunction with questions to
 *   the oracle about the query point.  Any output or responses to the
 *   query should be made from within this routine.
 *
 * Note:
 *   If theory, you could consider query algorithms which alter the
 *   preprocessed data structure to reflect any new and useful
 *   knowledge. 
 *  
 *******************************************************/
void FindNeighbor(Oracle* ora,  AbstractDS* ads, int query);



/********************************************************
 * void DestroyAbstractDS(AbstractDS* ads)
 *
 * Parameters:
 *   AbstractDS* ads --- pointer to your data structure
 *
 * Description:
 *   This is simply a cleanup routine.
 *  
 *******************************************************/
void DestroyAbstractDS(AbstractDS* ads);



/********************************************************
 * int CostPreprocess(AbstractDS* ads)
 *
 * Parameters:
 *   AbstractDS* ads --- pointer to your data structure
 *
 * Returns:
 *   An integer value which represents the 'cost' of the
 *   preprocessing step, in whatever units you choose to report.
 *
 * Note:
 *   The accounting should have been done during the preprocessing
 *   step, with the cost value saved as part of the data structure, in
 *   order to report it at the time of this procedure call.
 *  
 *******************************************************/
int CostPreprocess(AbstractDS* ads);


/********************************************************
 * int CostQuereies(AbstractDS* ads)
 *
 * Parameters:
 *   AbstractDS* ads --- pointer to your data structure
 *
 * Returns:
 *   An integer value which represents the 'cost' of the combined
 *   total of all neighbor queries. 
 *
 * Note:
 *   The accounting should have been done during each of the neighbor
 *   queries, with the cost value saved as part of the data structure,
 *   in order to report it at the time of this procedure call.
 *  
 *******************************************************/
int CostQueries(AbstractDS* ads);




 
#endif