/*

  * 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.automatic.analysis;

 import java.io.IOException;

 import java.io.InputStream;

 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.nabla.core.DifferentialPair;

 import org.apache.commons.nabla.core.DifferentiationException;

 import org.apache.commons.nabla.core.UnivariateDerivative;

 import org.apache.commons.nabla.core.UnivariateDifferentiable;

 import org.apache.commons.nabla.core.UnivariateDifferentiator;

 import org.objectweb.asm.ClassReader;

 import org.objectweb.asm.ClassWriter;

 /** Automatic differentiator class based on bytecode analysis.

  * <p>This class is an implementation of the {@link UnivariateDifferentiator}

  * 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} or

  * {@link java.lang.StrictMath StrictMath}. 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.Fetchdifferentiator

  */

 public class AutomaticDifferentiator implements UnivariateDifferentiator {

     /** Name for the DifferentialPair class. */

     public static final String DP_NAME = DifferentialPair.class.getName().replace('.', '/');

     /** Descriptor for the DifferentialPair class. */

     public static final String DP_DESCRIPTOR = "L" + DP_NAME + ";";

     /** Descriptor for the derivative class f method. */

     public static final String DP_RETURN_DP_DESCRIPTOR = "(" + DP_DESCRIPTOR + ")" + DP_DESCRIPTOR;

     /** UnivariateDifferentiable/UnivariateDerivative map. */

     private final HashMap<Class<? extends UnivariateDifferentiable>,

     Class<? extends UnivariateDerivative>> map;

     /** Math implementation classes. */

     private final Set<String> mathClasses;

     /** Simple constructor.

      * <p>Build a AutomaticDifferentiator instance with an empty cache.</p>

      */

     public AutomaticDifferentiator() {

         map = new HashMap<Class<? extends UnivariateDifferentiable>,

         Class<? extends UnivariateDerivative>>();

         mathClasses = new HashSet<String>();

         addMathImplementation(Math.class);

         addMathImplementation(StrictMath.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 class 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

         throw new RuntimeException("not implemented yet");

     }

     /** {@inheritDoc} */

     public UnivariateDerivative differentiate(final UnivariateDifferentiable d)

         throws DifferentiationException {

         // get the derivative class

         final Class<? extends UnivariateDerivative> derivativeClass =

             getDerivativeClass(d.getClass());

         try {

             // create the instance

             final Constructor<? extends UnivariateDerivative> constructor =

                 derivativeClass.getConstructor(d.getClass());

             return constructor.newInstance(d);

         } catch (InstantiationException ie) {

             throw new DifferentiationException("abstract class {0} cannot be instantiated ({1})",

                                                derivativeClass.getName(), ie.getMessage());

         } catch (IllegalAccessException iae) {

             throw new DifferentiationException("illegal access to class {0} constructor ({1})",

                                                derivativeClass.getName(), iae.getMessage());

         } catch (NoSuchMethodException nsme) {

             throw new DifferentiationException("class {0} cannot be built from an instance of class {1} ({2})",

                                                derivativeClass.getName(), d.getClass().getName(), nsme.getMessage());

         } catch (InvocationTargetException ite) {

             throw new DifferentiationException("class {0} instantiation from an instance of class {1} failed ({2})",

                                                derivativeClass.getName(), d.getClass().getName(), ite.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 UnivariateDerivative>

     getDerivativeClass(final Class<? extends UnivariateDifferentiable> differentiableClass)

         throws DifferentiationException {

         // lookup in the map if the class has already been differentiated

         Class<? extends UnivariateDerivative> derivativeClass =

             map.get(differentiableClass);

         // build the derivative class if it does not exist yet

         if (derivativeClass == null) {

             // perform analytical 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 UnivariateDerivative>

     createDerivativeClass(final Class<? extends UnivariateDifferentiable> differentiableClass)

         throws DifferentiationException {

         try {

             // set up both ends of the class transform chain

             final String classResourceName = "/" + differentiableClass.getName().replace('.', '/') + ".class";

             final InputStream stream = differentiableClass.getResourceAsStream(classResourceName);

             final ClassReader reader = new ClassReader(stream);

             final ClassWriter writer = new ClassWriter(reader, ClassWriter.COMPUTE_FRAMES);

             // differentiate the function embedded in the differentiable class

             final ClassDifferentiator differentiator = new ClassDifferentiator(mathClasses, writer);

             reader.accept(differentiator, ClassReader.SKIP_DEBUG | ClassReader.SKIP_FRAMES);

             differentiator.reportErrors();

             // create the derivative class

             return new DerivativeLoader(differentiableClass).defineClass(differentiator, writer);

         } catch (IOException ioe) {

             throw new DifferentiationException("class {0} cannot be read ({1})",

                                           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 UnivariateDifferentiable> differentiableClass) {

             super(differentiableClass.getClassLoader());

         }

         /** Define a derivative class.

          * @param differentiator class differentiator

          * @param writer class writer

          * @return a generated derivative class

          */

         @SuppressWarnings("unchecked")

         public Class<? extends UnivariateDerivative>

         defineClass(final ClassDifferentiator differentiator, final ClassWriter writer) {

             final String name = differentiator.getDerivativeClassName().replace('/', '.');

             final byte[] bytecode = writer.toByteArray();

             return (Class<? extends UnivariateDerivative>) defineClass(name, bytecode, 0, bytecode.length);

         }

     }

 }