/*////////////////////////////////////////////////////////////////////////////////////////////////////////
 // HeroSvm 2.0 Copyright (c) 2002 by Jianxiong Dong
 //
 //  Name
 //
 //   SVMTrain.h -- interface for HeroSVM dynamic link library (DLL)
 //
 //  Exported Functions:
 //
 //   SvmInit              -- set the training parameters and allocate the memory dynamically
 //   SvmTrain_Parallel    -- Train support vector machine with multi-classes to
 //                            remove non-support vectors quickly
 //   
 //   SvmTrain_Sequential  -- Train support vector machine sequentially 
 //
 //   SvmClean             -- Free dynamically allocated memory
 //
 //  Author
 //
 //   Jianxiong Dong ( jdong@cenparmi.concordia.ca )
 //   Homepage: http://www.cenparmi.concordia.ca/~people/jdong
 //
 //  COPYRIGHT INFORMATION:
 //
 //	   This software can be used for research over the world and is free
 //    of charge. Anybody who likes to use it for a commercial purpose 
 //    should get the permission of the author. Note that distributing this
 //    software bundled in with any product is considered to be a 
 //    commercial purpose. 
 //
 //	   THE SOFTWARE IS PROVIDED ``AS-IS" AND WITHOUT WARRANTY OF ANY
 //    KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION,
 //    ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
 //    PURPOSE
 //
 //    IN NO EVENT SHALL THE AUTHOR LIABLE FOR ANY SPECIAL, INCIDENTAL, 
 //    INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES 
 //    WHATSOEVER RESULTING FROM LOSS OR USE, DATA OR PROFITS, WHETHER 
 //    OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF
 //    LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
 //    THIS SOFTWARE
 //	
 //  Reference:
 //
 //	[1] Jian-xiong Dong, Adam Krzyzak and Ching Y. Suen, A fast SVM training algorithm. 
 //     International workshop on Pattern Recognition with Support Vector Machines.  
 //     S.-W. Lee and A. Verri (Eds.): Springer Lecture Notes in Computer Science  LNCS 2388, 
 //     pp. 53-67, Niagara Falls, Canada, August 10,  2002. 
 //
 // [2] Jian-xiong Dong, Adam Krzyzak and Ching Y. Suen, A fast parallel optimization for 
 //     training support vector machines. Technical report, CENPARMI, Concordia University,
 //     Montreal, Canada, November 2002.
 //
 ////////////////////////////////////////////////////////////////////////////////////////////////////////
 */

#ifndef __SVMTrain_H
#define __SVMTrain_H

#ifndef WINAPI
#define WINAPI __stdcall
#endif 

#ifndef DllExport
#define DllExport  __declspec( dllexport) 
#endif 

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/*//////////////////////////////////////////////////////////////////////////////
//		SvmInit
// 
//  Synopsis: 
//     This function sets the SVM training parameters and allocate the memory
//     
//	Parameters:
//
//    
//   nDim [in]              --- Dimension of the input feature vector
//   nWorkingSetSize  [in]  --- Size of working set  
//   nTrainingSetSize [in]  --- Number of training samples
//   kernel_Para1 [in]      --- Parameters of non user-specified kernel
//   kernel_Para2 [in]      --- Parameters of non user-specified kernel
//   kernel_Para3 [in]      --- Parameters of non user-specified kernel
//   nKernelType  [in]      --- Kernel type
//   C            [in]      --- Upper bound of alpha in SVM
//   nApplicationType [in]  --- Application type (console or window program ) for the output of 
//                              error message
//   ClassNum         [in]  --- Number of classes
//   TrainingType     [in]  --- Type of optimization
//                              0: 1st step: parallel optimization 
//                              1: 2nd step: sequential optimization
//  Return:
//   
//   If succeed, return 0; otherwise -1
//
//
///////////////////////////////////////////////////////////////////////////////////
*/

/*
Let a = kernel_Para1, b = kernel_Para2, c = kernel_Para3, 

RBF         : exp(-||x1-x2||^2/(2*c))
Polynomial  : (x1 * x2 + b)/c)^a
Linear      : ( x1 * x2 + b)/c

where x1 and x2 are vectors in R^nDim.

nKernelType:
  1:  RBF kernel (radial basis function) 
  2:  Polynomial kernel
  3:  Linear kernel

nApplicationType:

  0: console application
  1: window application

*/

DllExport int WINAPI SvmInit(int nDim, int nWorkingSetSize, int nTrainingSetSize,
			    float kernel_Para1, float kernel_Para2, float kernel_Para3, 
			    int nKernelType, int ClassNum, float C, int TrainingType,
			    int nApplcationType);


/*///////////////////////////////////////////////////////////////////////////////////////
//
//	 SvmTrain_Parallel
//
//  Synopsis:
//    Train support vector machine with multi-classes to remove non-support 
//                    vector quickly 
//	 	
//  Parameters:
//
//   szDataFilePathName [in]          --- a pointer to data filename
//   szLabelFilePathName [in]         --- a pointer to filename for data labels
//   PositiveSamplesFilePathName [in] --- a pointer to filename for positive samples
//   SaveFilePath [in]                --- a pointer to the saved file path
//
//  Return:
//   If succeed, return 0; otherwise -1
//
/////////////////////////////////////////////////////////////////////////////////////////
*/

/*
	All labels of input vectors are mapped into integers in an interval from 0
	to ClassNum - 1. That is, 0, 1, 2, ..., ClassNum-1 .

	data structure of file szDataFilePathName: input feature vectors are sequentially stored 

	input vector 1
	input vector 2
	...
	input vector n

    data structure of file szLabelFilePathName: the correspoinding labels of the input 
	     feature vectors in the above file szDataFilePathName are sequentially stored

    label of input vector 1 
	label of input vector 2
	...
	label of input vector n

   data structure of file PositiveSamplesFilePathName: this file consists of ClassNum records.
   Each class has a record.

   position + input vector of class 0
   position + input vector of class 1
   ...
   position + input vector of class ( ClassNum - 1)

   where position specifies the sequential number of the current sample in the file
   szDataFilePathName.

*/
  DllExport int WINAPI SvmTrain_Parallel(char* szDataFilePathName, 
					 char* szLabelFilePathName, 
				        char* PositiveSamplesFilePathName, 
					char* SaveFilePath);

/*///////////////////////////////////////////////////////////////////////////////////////
//
//	 SvmTrain_Sequential
//
//  Synopsis:
//    Train support vector machine sequentially 
//	 	
//  Parameters:
//
//   szDataFilePathName   [in]     --- a pointer to data filename
//   szTargetFilePathName [in]     --- a pointer to target data filename. The target value is 
//                                     1.0 or -1.0
//   nClassID                      --- identity number of a class
//   szSummaryFilePathName [in]    --- a pointer to summary filename
//   szSvFilePathName      [in]    --- a pointer to data file where support vectors, training and optimized
//                                     parameters are stored
//                      
//   szSvIndexFilePathName [in]    --- index file for support vectors  
//
//  Return:
//   If succeed, return 0; otherwise -1
//
/////////////////////////////////////////////////////////////////////////////////////////
*/

/*
	data structure of file szDataFilePathName: input feature vectors are sequentially stored 

	input vector 1
	input vector 2
	...
	input vector n


    data structure of file szTargetFilePathName: the correspoinding target value of the input 
	     feature vectors in the above file szDataFilePathName are sequentially stored

    target value of input vector 1 
	target value of input vector 2
	...
	target value of input vector n
*/

DllExport int WINAPI SvmTrain_Sequential( char* szDataFilePathName, char* szTargetFilePathName, 
                                          int nClassID,
		                          char* szSummaryFilePathName,
					  char* szSvFilePathName,
                                          char* szSvIndexFilePathName);


/*///////////////////////////////////////////////////////////////////////////////////////////
//	
//    SvmClean
//
//  Synopsis:
//   
//     Free dynamically allocated memory in terms of training type.
//	
//  Parameters:
//   
//   TrainingType [in] --- Type of optimization
//		           0: 1st step: parallel optimization
//			   1: 2nd step: sequential optimization
//
//
//  Returns:
//
//	 NONE
//
/////////////////////////////////////////////////////////////////////////////////////////////
*/
    DllExport void WINAPI SvmClean(int TrainingType );
};

#ifdef __cplusplus
}
#endif /*__cplusplus */

#endif /* __SVMTrain_H */