// Copyright (c) 2007 David Grangier
// Copyright (c) 2007 Samy Bengio
// 
// All rights reserved.
// 
// Redistribution and use in source and binary forms, with or without 
// modification, are permitted provided that the following conditions are 
// met: Redistributions of source code must retain the above copyright 
// notice, this list of conditions and the following disclaimer.
// Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the 
// documentation and/or other materials provided with the distribution.
// The name of the author may not be used to endorse or promote products
// derived from this software without specific prior written permission.
// 
// THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 
// IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 
// WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
// DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 
// INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
// (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 
// SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 
// HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
// STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
// ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 
// THE POSSIBILITY OF SUCH DAMAGE.


PAMIR
Passive Aggressibe Model for Image Retrieval
--------------------------------------------------------------
Reference documents:

A Discriminative Approach for the Retrieval of Images from Text Queries
D. Grangier, F. Monay & S. Bengio - European Conference on Machine Learning (ECML). 2006.

Learning to Retrieve Images from Text Queries with a Discriminative Model
D. Grangier, F. Monay & S. Bengio - International Workshop on Adaptive Multimedia Retrieval (AMR). 2006.
--------------------------------------------------------------
INSTALLATION

1. copy the 'mains' directory to your_torch3_directory/examples/passive_aggressive/
2. copy the 'classes' directory to your_torch3_directory/passive_aggressive/
3. add ' passive_aggressive kernels distributions gradients' in the package list of Torch3
4. compile the main files as any other Torch example program.
---------------------------------------------------------------
README FILE

This file first decribes the classes, then the main example files
---------------------------------------------------------------
Basic PA classes (most classes are abstract, just define the infrastructure)
path: ./classes

PAExample
-> abstract example class
-> child: PABasicExample (a single vector), PASparseExample (a single sparse vector)
PADataset
-> dataset providing examples either through sampling or sequentially
-> child: PASparseDataset (a set of sparse vectors)
PAMachine
-> a machine consists of a kernel and a support set
PAKernel
-> a kernel, evaluate dot product between examples
-> child: PAKernelSparseLinear (linear kernel for sparse vectors)
PASupportSet
-> a set of pairs (example, weight)
-> child: PASparseSupportSet (examples are sparse vectors), PASparseSupportSetLK (idem but for linear kernel, allow vector addition to add support)
PAMeasurer
-> measure the quality of a machine wrt a dataset
PALoss 
-> given an example and a machine, return wether the correp training constraint is satisfied, if not it also provide the support to add
PATrainer 
-> Passive Aggressive training, require a train set, a loss, a machine and eventually a measurer.

-------------------------------------------------------
Image Retrieval Class (Sparse Linear Model)
path: ./classes

ImgConstraint
-> an example embedding a query, a relevant picture, a non-relevant picture, epsilon (what should be the min difference in the scores of the pictures for query q)
   and a weight (allow for weighting the constraint, not used now)
-> note that for test it is also possible to provide only a query and a picture (negative_img=NULL)
ImgConstraintDataset
-> take a set of queries and pictures along with correponding relevance data and allows to sample image contraints
ImgConstraintPolicies
-> allow to attach refined epsilon/weight policies to an ImgConstraintDataset
PAMachineImageIR
-> a machine working on image constraints
PAMachineImageIR_identity
-> not a learned machine, simply perform text retrieval when the images are provided as captions (i.e. in the same space as queries).
ImgLoss
-> the loss working with PAMachineImageIR and ImgConstraint
DocumentFinder
-> deprecated
ImgRtrvMeasurer
-> evalutate a PAMachineImageIR wrt to a ImgConstraintDataset according to BEP, AvgPrec, P@top10 and AUC.
-> note: the fast version (ImgRtrvMeasurerFast) shares infered image representations among queries.
ImgRtrvMeasurerScores
-> just output the score of each picture for each query
ImgRtrvMeasurerRanking
-> return the n best pictures for each query
RetrievalEvaluation
-> compute ranking quality measures for ImgRtrvMeasurer

--------------------------------------------------------
Image Retrieval Class (Non Linear Model)
path: ./classes
(for small dataset so far, as all kernel eval should be pre-computed and cached)

SequenceKernel
-> different kernels between sets
ExpectedLikelihoodGaussian
-> expected likelihood kernel between pre-trained GMM
PAIndexDataset
-> a dataset in which the examples are just indexes to be used in conjuction with PACachedKernel
PACachedKernel
-> hold several precomputed kernel evaluation matrices
PAIndexSupportSet
-> support set for PACachedKernel
PAExpKernel
-> deprecated
--------------------------------------------------------
Mains
path: ./mains

trainImg2
-> train a model

testImg2 
-> test a model

computeSim
-> compute all kernel evalutions for a pair of image sets
