/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You under the Apache License, Version 2.0
    * (the "License"); you may not use this file except in compliance with
    * the License.  You may obtain a copy of the License at
    *
    *      http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  package org.apache.commons.nabla.forward;
  
  import java.io.IOException;
  import java.io.OutputStream;
  import java.lang.reflect.Constructor;
  import java.lang.reflect.InvocationTargetException;
  import java.util.HashMap;
  import java.util.HashSet;
  import java.util.Set;
  
  import org.apache.commons.math3.analysis.UnivariateFunction;
  import org.apache.commons.math3.analysis.differentiation.DerivativeStructure;
  import org.apache.commons.math3.analysis.differentiation.UnivariateDifferentiableFunction;
  import org.apache.commons.math3.analysis.differentiation.UnivariateFunctionDifferentiator;
  import org.apache.commons.math3.util.FastMath;
  import org.apache.commons.nabla.DifferentiationException;
  import org.apache.commons.nabla.NablaMessages;
  import org.apache.commons.nabla.forward.analysis.ClassDifferentiator;
  import org.objectweb.asm.ClassWriter;
  import org.objectweb.asm.Type;
  import org.objectweb.asm.tree.ClassNode;
  
  /** Algorithmic differentiator class in forward mode based on bytecode analysis.
   * <p>This class is an implementation of the {@link UnivariateFunctionDifferentiator}
   * interface that computes <em>exact</em> differentials completely automatically
   * and generate java classes and instances that compute the differential
   * of the function as if they were hand-coded and compiled.</p>
   * <p>The derivative bytecode created the first time an instance of a given class
   * is differentiated is cached and will be reused if other instances of the same class
   * are to be created later. The cache can also be dumped in a jar file for
   * use in an application without bringing the full nabla library and its
   * dependencies.</p>
   * <p>This differentiator can handle only pure bytecode methods and known methods
   * from math implementation classes like {@link java.lang.Math Math}, {@link
   * java.lang.StrictMath StrictMath} or {@link FastMath}. Pure bytecode methods are
   * analyzed and converted. Methods from math implementation classes are only
   * recognized by class and name and replaced by predefined derivative code.</p>
   * @see org.apache.commons.nabla.caching.FetchDifferentiator
   * @version $Id$
   */
  public class ForwardModeDifferentiator implements UnivariateFunctionDifferentiator {
  
      /** UnivariateFunction/UnivariateDifferentiableFunction map. */
      private final HashMap<Class<? extends UnivariateFunction>,
                            Class<? extends UnivariateDifferentiableFunction>> map;
  
      /** Class name/ bytecode map. */
      private final HashMap<String, byte[]> byteCodeMap;
  
      /** Math implementation classes. */
      private final Set<String> mathClasses;
  
      /** Simple constructor.
       * <p>Build a ForwardAlgorithmicDifferentiator instance with an empty cache.</p>
       */
      public ForwardModeDifferentiator() {
          map         = new HashMap<Class<? extends UnivariateFunction>,
                                    Class<? extends UnivariateDifferentiableFunction>>();
          byteCodeMap = new HashMap<String, byte[]>();
          mathClasses = new HashSet<String>();
          addMathImplementation(Math.class);
          addMathImplementation(StrictMath.class);
          addMathImplementation(FastMath.class);
      }
  
      /** Add an implementation class for mathematical functions.
       * <p>At construction, the differentiator considers only the {@link
       * java.lang.Math Math} and {@link java.lang.StrictMath StrictMath}
       * classes are math implementation classes. It may be useful to add
       * other classes for example to add some missing functions like
       * inverse hyperbolic cosine that are not provided by the standard
       * java classes as of Java 1.6.</p>
       * @param mathClass implementation class for mathematical functions
       */
      public void addMathImplementation(final Class<?> mathClass) {
          mathClasses.add(mathClass.getName().replace('.', '/'));
      }
  
      /** Dump the cache into a stream.
       * @param out output stream where to dump the cache
       */
      public void dumpCache(final OutputStream out) {
          // TODO: implement cache persistence
         throw new RuntimeException("not implemented yet");
     }
 
     /** {@inheritDoc} */
     public UnivariateDifferentiableFunction differentiate(final UnivariateFunction d) {
 
         // get the derivative class
         final Class<? extends UnivariateDifferentiableFunction> derivativeClass =
             getDerivativeClass(d.getClass());
 
         try {
 
             // create the instance
             final Constructor<? extends UnivariateDifferentiableFunction> constructor =
                 derivativeClass.getConstructor(d.getClass());
             return constructor.newInstance(d);
 
         } catch (InstantiationException ie) {
             throw new DifferentiationException(NablaMessages.CANNOT_INSTANTIATE_ABSTRACT_CLASS,
                                                derivativeClass.getName(), ie.getMessage());
         } catch (IllegalAccessException iae) {
             throw new DifferentiationException(NablaMessages.ILLEGAL_ACCESS_TO_CONSTRUCTOR,
                                                derivativeClass.getName(), iae.getMessage());
         } catch (NoSuchMethodException nsme) {
             throw new DifferentiationException(NablaMessages.CANNOT_BUILD_CLASS_FROM_OTHER_CLASS,
                                                derivativeClass.getName(), d.getClass().getName(), nsme.getMessage());
         } catch (InvocationTargetException ite) {
             throw new DifferentiationException(NablaMessages.CANNOT_INSTANTIATE_CLASS_FROM_OTHER_INSTANCE,
                                                derivativeClass.getName(), d.getClass().getName(), ite.getMessage());
         } catch (VerifyError ve) {
             throw new DifferentiationException(NablaMessages.INCORRECT_GENERATED_CODE,
                                                derivativeClass.getName(), d.getClass().getName(), ve.getMessage());
         }
 
     }
 
     /** Get the derivative class of a differentiable class.
      * <p>The derivative class is either built on the fly
      * or retrieved from the cache if it has been built previously.</p>
      * @param differentiableClass class to differentiate
      * @return derivative class
      * @throws DifferentiationException if the class cannot be differentiated
      */
     private Class<? extends UnivariateDifferentiableFunction>
     getDerivativeClass(final Class<? extends UnivariateFunction> differentiableClass)
         throws DifferentiationException {
 
         // lookup in the map if the class has already been differentiated
         Class<? extends UnivariateDifferentiableFunction> derivativeClass =
             map.get(differentiableClass);
 
         // build the derivative class if it does not exist yet
         if (derivativeClass == null) {
 
             // perform algorithmic differentiation
             derivativeClass = createDerivativeClass(differentiableClass);
 
             // put the newly created class in the map
             map.put(differentiableClass, derivativeClass);
 
         }
 
         // return the derivative class
         return derivativeClass;
 
     }
 
     /** Build a derivative class of a differentiable class.
      * @param differentiableClass class to differentiate
      * @return derivative class
      * @throws DifferentiationException if the class cannot be differentiated
      */
     private Class<? extends UnivariateDifferentiableFunction>
     createDerivativeClass(final Class<? extends UnivariateFunction> differentiableClass)
         throws DifferentiationException {
         try {
 
             // differentiate the function embedded in the differentiable class
             final ClassDifferentiator differentiator =
                 new ClassDifferentiator(differentiableClass, mathClasses);
             final Type dsType = Type.getType(DerivativeStructure.class);
             differentiator.differentiateMethod("value",
                                                Type.getMethodDescriptor(Type.DOUBLE_TYPE, Type.DOUBLE_TYPE),
                                                Type.getMethodDescriptor(dsType, dsType));
 
             // create the derivative class
             final ClassNode   derived = differentiator.getDerivedClass();
             final ClassWriter writer  = new ClassWriter(ClassWriter.COMPUTE_FRAMES);
             final String name = derived.name.replace('/', '.');
             derived.accept(writer);
             final byte[] bytecode = writer.toByteArray();
 
             final Class<? extends UnivariateDifferentiableFunction> dClass =
                     new DerivativeLoader(differentiableClass).defineClass(name, bytecode);
             byteCodeMap.put(name, bytecode);
             return dClass;
 
         } catch (IOException ioe) {
             throw new DifferentiationException(NablaMessages.CANNOT_READ_CLASS,
                                                differentiableClass.getName(), ioe.getMessage());
         }
     }
 
     /** Class loader generating derivative classes. */
     private static class DerivativeLoader extends ClassLoader {
 
         /** Simple constructor.
          * @param differentiableClass differentiable class
          */
         public DerivativeLoader(final Class<? extends UnivariateFunction> differentiableClass) {
             super(differentiableClass.getClassLoader());
         }
 
         /** Define a derivative class.
          * @param name name of the differentiated class
          * @param bytecode bytecode of the differentiated class
          * @return a generated derivative class
          */
         @SuppressWarnings("unchecked")
         public Class<? extends UnivariateDifferentiableFunction>
         defineClass(final String name, final byte[] bytecode) {
             return (Class<? extends UnivariateDifferentiableFunction>) defineClass(name, bytecode, 0, bytecode.length);
         }
     }
 
 }