/*

  *   This program is free software: you can redistribute it and/or modify

  *   it under the terms of the GNU General Public License as published by

  *   the Free Software Foundation, either version 3 of the License, or

  *   (at your option) any later version.

  *

  *   This program is distributed in the hope that it will be useful,

  *   but WITHOUT ANY WARRANTY; without even the implied warranty of

  *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

  *   GNU General Public License for more details.

  *

  *   You should have received a copy of the GNU General Public License

  *   along with this program.  If not, see <http://www.gnu.org/licenses/>.

  */

 /*

  * CachedKernel.java

  * Copyright (C) 2005-2012 University of Waikato, Hamilton, New Zealand

  */

 package weka.classifiers.functions.supportVector;

 import java.util.Enumeration;

 import java.util.Vector;

 import weka.core.Instance;

 import weka.core.Instances;

 import weka.core.Option;

 import weka.core.Utils;

 /**

  * Base class for RBFKernel and PolyKernel that implements a simple LRU.

  * (least-recently-used) cache if the cache size is set to a value > 0.

  * Otherwise it uses a full cache.

  * 

  * @author Eibe Frank (eibe@cs.waikato.ac.nz)

  * @author Shane Legg (shane@intelligenesis.net) (sparse vector code)

  * @author Stuart Inglis (stuart@reeltwo.com) (sparse vector code)

  * @author J. Lindgren (jtlindgr{at}cs.helsinki.fi) (RBF kernel)

  * @author Steven Hugg (hugg@fasterlight.com) (refactored, LRU cache)

  * @author Bernhard Pfahringer (bernhard@cs.waikato.ac.nz) (full cache)

  * @version $Revision: 8034 $

  */

 public abstract class CachedKernel 

   extends Kernel {

   /** for serialization */

   private static final long serialVersionUID = 702810182699015136L;

   /** Counts the number of kernel evaluations. */

   protected int m_kernelEvals;

   /** Counts the number of kernel cache hits. */

   protected int m_cacheHits;

   /** The size of the cache (a prime number) */

   protected int m_cacheSize = 250007;

   /** Kernel cache */

   protected double[] m_storage;

   protected long[] m_keys;

   /** The kernel matrix if full cache is used (i.e. size is set to 0) */

   protected double[][] m_kernelMatrix;

   /** The number of instance in the dataset */

   protected int m_numInsts;

   /** number of cache slots in an entry */

   protected int m_cacheSlots = 4;

   /**

    * default constructor - does nothing.

    */

   public CachedKernel() {

     super();

   }

   /**

    * Initializes the kernel cache. The actual size of the cache in bytes is

    * (64 * cacheSize).

    * 

    * @param data        the data to use

    * @param cacheSize        the cache size

    * @throws Exception        if something goes wrong

    */

   protected CachedKernel(Instances data, int cacheSize) throws Exception {

     super();

     setCacheSize(cacheSize);

     buildKernel(data);

   }

   /**

    * Returns an enumeration describing the available options.

    *

    * @return                 an enumeration of all the available options.

    */

   public Enumeration listOptions() {

     Vector                result;

     Enumeration                en;

     result = new Vector();

     en = super.listOptions();

     while (en.hasMoreElements())

       result.addElement(en.nextElement());

     result.addElement(new Option(

         "\tThe size of the cache (a prime number), 0 for full cache and \n"

         + "\t-1 to turn it off.\n"

         + "\t(default: 250007)",

         "C", 1, "-C <num>"));

     return result.elements();

   }

   /**

    * Parses a given list of options. <p/>

    * 

    * @param options         the list of options as an array of strings

    * @throws Exception         if an option is not supported

    */

   public void setOptions(String[] options) throws Exception {

     String        tmpStr;

     tmpStr = Utils.getOption('C', options);

     if (tmpStr.length() != 0)

       setCacheSize(Integer.parseInt(tmpStr));

     else

       setCacheSize(250007);

     super.setOptions(options);

   }

   /**

    * Gets the current settings of the Kernel.

    *

    * @return an array of strings suitable for passing to setOptions

    */

   public String[] getOptions() {

     int       i;

     Vector    result;

     String[]  options;

     result = new Vector();

     options = super.getOptions();

     for (i = 0; i < options.length; i++)

       result.add(options[i]);

     result.add("-C");

     result.add("" + getCacheSize());

     return (String[]) result.toArray(new String[result.size()]);          

   }

   /**

    * This method is overridden in subclasses to implement specific kernels.

    * 

    * @param id1           the index of instance 1

    * @param id2                the index of instance 2

    * @param inst1        the instance 1 object

    * @return                 the dot product

    * @throws Exception         if something goes wrong

    */

   protected abstract double evaluate(int id1, int id2, Instance inst1)

     throws Exception;

   /**

    * Implements the abstract function of Kernel using the cache. This method

    * uses the evaluate() method to do the actual dot product.

    *

    * @param id1         the index of the first instance in the dataset

    * @param id2         the index of the second instance in the dataset

    * @param inst1         the instance corresponding to id1 (used if id1 == -1)

    * @return                 the result of the kernel function

    * @throws Exception         if something goes wrong

    */

   public double eval(int id1, int id2, Instance inst1) throws Exception {

     double result = 0;

     long key = -1;

     int location = -1;

     // we can only cache if we know the indexes and caching is not 

     // disbled (m_cacheSize == -1)

     if ( (id1 >= 0) && (m_cacheSize != -1) ) {

       // Use full cache?

       if (m_cacheSize == 0) {

         if (m_kernelMatrix == null) {

           m_kernelMatrix = new double[m_data.numInstances()][];

           for(int i = 0; i < m_data.numInstances(); i++) {

             m_kernelMatrix[i] = new double[i + 1];

             for(int j = 0; j <= i; j++) {

               m_kernelEvals++;

               m_kernelMatrix[i][j] = evaluate(i, j, m_data.instance(i));

             }

           }

         } 

         m_cacheHits++;

         result = (id1 > id2) ? m_kernelMatrix[id1][id2] : m_kernelMatrix[id2][id1];

         return result;

       }

       // Use LRU cache

       if (id1 > id2) {

         key = (id1 + ((long) id2 * m_numInsts));

       } else {

         key = (id2 + ((long) id1 * m_numInsts));

       }

       location = (int) (key % m_cacheSize) * m_cacheSlots;

       int loc = location;

       for (int i = 0; i < m_cacheSlots; i++) {

         long thiskey = m_keys[loc];

         if (thiskey == 0)

           break; // empty slot, so break out of loop early

         if (thiskey == (key + 1)) {

           m_cacheHits++;

           // move entry to front of cache (LRU) by swapping

           // only if it's not already at the front of cache

           if (i > 0) {

             double tmps = m_storage[loc];

             m_storage[loc] = m_storage[location];

             m_keys[loc] = m_keys[location];

             m_storage[location] = tmps;

             m_keys[location] = thiskey;

             return tmps;

           } else

             return m_storage[loc];

         }

         loc++;

       }

     }

     result = evaluate(id1, id2, inst1);

     m_kernelEvals++;

     // store result in cache

     if ( (key != -1) && (m_cacheSize != -1) ) {

       // move all cache slots forward one array index

       // to make room for the new entry

       System.arraycopy(m_keys, location, m_keys, location + 1,

                        m_cacheSlots - 1);

       System.arraycopy(m_storage, location, m_storage, location + 1,

                        m_cacheSlots - 1);

       m_storage[location] = result;

       m_keys[location] = (key + 1);

     }

     return result;

   }

   /**

    * Returns the number of time Eval has been called.

    * 

    * @return                 the number of kernel evaluation.

    */

   public int numEvals() {

     return m_kernelEvals;

   }

   /**

    * Returns the number of cache hits on dot products.

    * 

    * @return                 the number of cache hits.

    */

   public int numCacheHits() {

     return m_cacheHits;

   }

   /**

    * Frees the cache used by the kernel.

    */

   public void clean() {

     m_storage = null;

     m_keys = null;

     m_kernelMatrix = null;

   }

   /**

    * Calculates a dot product between two instances

    * 

    * @param inst1        the first instance

    * @param inst2        the second instance

    * @return                 the dot product of the two instances.

    * @throws Exception        if an error occurs

    */

   protected final double dotProd(Instance inst1, Instance inst2)

     throws Exception {

     double result = 0;

     // we can do a fast dot product

     int n1 = inst1.numValues();

     int n2 = inst2.numValues();

     int classIndex = m_data.classIndex();

     for (int p1 = 0, p2 = 0; p1 < n1 && p2 < n2;) {

       int ind1 = inst1.index(p1);

       int ind2 = inst2.index(p2);

       if (ind1 == ind2) {

         if (ind1 != classIndex) {

           result += inst1.valueSparse(p1) * inst2.valueSparse(p2);

         }

         p1++;

         p2++;

       } else if (ind1 > ind2) {

         p2++;

       } else {

         p1++;

       }

     }

     return (result);

   }

   /**

    * Sets the size of the cache to use (a prime number)

    * 

    * @param value        the size of the cache

    */

   public void setCacheSize(int value) {

     if (value >= -1) {

       m_cacheSize = value;

       clean();

     }

     else {

       System.out.println(

           "Cache size cannot be smaller than -1 (provided: " + value + ")!");

     }

   }

   /**

    * Gets the size of the cache

    * 

    * @return                 the cache size

    */

   public int getCacheSize() {

     return m_cacheSize;

   }

   /**

    * Returns the tip text for this property

    * 

    * @return                 tip text for this property suitable for

    *                         displaying in the explorer/experimenter gui

    */

   public String cacheSizeTipText() {

     return "The size of the cache (a prime number), 0 for full cache and -1 to turn it off.";

   }

   /**

    * initializes variables etc.

    * 

    * @param data        the data to use

    */

   protected void initVars(Instances data) {

     super.initVars(data);

     m_kernelEvals = 0;

     m_cacheHits   = 0;

     m_numInsts    = m_data.numInstances();

     if (getCacheSize() > 0) {

       // Use LRU cache

       m_storage = new double[m_cacheSize * m_cacheSlots];

       m_keys    = new long[m_cacheSize * m_cacheSlots];

     } 

     else {

       m_storage      = null;

       m_keys         = null;

       m_kernelMatrix = null;

     }

   }

   /**

    * builds the kernel with the given data. Initializes the kernel cache. 

    * The actual size of the cache in bytes is (64 * cacheSize).

    * 

    * @param data        the data to base the kernel on

    * @throws Exception        if something goes wrong

    */

   public void buildKernel(Instances data) throws Exception {

     // does kernel handle the data?

     if (!getChecksTurnedOff())

       getCapabilities().testWithFail(data);

     initVars(data);

   }

 }