/*

  * 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);

         }

     }

 }