/*
    * 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.math3.ml.neuralnet;
  
  import java.io.Serializable;
  import java.io.ObjectInputStream;
  import java.util.NoSuchElementException;
  import java.util.List;
  import java.util.ArrayList;
  import java.util.Set;
  import java.util.HashSet;
  import java.util.Collection;
  import java.util.Iterator;
  import java.util.Comparator;
  import java.util.Collections;
  import java.util.concurrent.ConcurrentHashMap;
  import java.util.concurrent.atomic.AtomicLong;
  import org.apache.commons.math3.exception.DimensionMismatchException;
  import org.apache.commons.math3.exception.MathIllegalStateException;
  
  /**
   * Neural network, composed of {@link Neuron} instances and the links
   * between them.
   *
   * Although updating a neuron's state is thread-safe, modifying the
   * network's topology (adding or removing links) is not.
   *
   * @since 3.3
   */
  public class Network
      implements Iterable<Neuron>,
                 Serializable {
      /** Serializable. */
      private static final long serialVersionUID = 20130207L;
      /** Neurons. */
      private final ConcurrentHashMap<Long, Neuron> neuronMap
          = new ConcurrentHashMap<Long, Neuron>();
      /** Next available neuron identifier. */
      private final AtomicLong nextId;
      /** Neuron's features set size. */
      private final int featureSize;
      /** Links. */
      private final ConcurrentHashMap<Long, Set<Long>> linkMap
          = new ConcurrentHashMap<Long, Set<Long>>();
  
      /**
       * Comparator that prescribes an order of the neurons according
       * to the increasing order of their identifier.
       */
      public static class NeuronIdentifierComparator
          implements Comparator<Neuron>,
                     Serializable {
          /** Version identifier. */
          private static final long serialVersionUID = 20130207L;
  
          /** {@inheritDoc} */
          public int compare(Neuron a,
                             Neuron b) {
              final long aId = a.getIdentifier();
              final long bId = b.getIdentifier();
              return aId < bId ? -1 :
                  aId > bId ? 1 : 0;
          }
      }
  
      /**
       * Constructor with restricted access, solely used for deserialization.
       *
       * @param nextId Next available identifier.
       * @param featureSize Number of features.
       * @param neuronList Neurons.
       * @param neighbourIdList Links associated to each of the neurons in
       * {@code neuronList}.
       * @throws MathIllegalStateException if an inconsistency is detected
       * (which probably means that the serialized form has been corrupted).
       */
      Network(long nextId,
              int featureSize,
              Neuron[] neuronList,
              long[][] neighbourIdList) {
          final int numNeurons = neuronList.length;
          if (numNeurons != neighbourIdList.length) {
              throw new MathIllegalStateException();
          }
 
         for (int i = 0; i < numNeurons; i++) {
             final Neuron n = neuronList[i];
             final long id = n.getIdentifier();
             if (id >= nextId) {
                 throw new MathIllegalStateException();
             }
             neuronMap.put(id, n);
             linkMap.put(id, new HashSet<Long>());
         }
 
         for (int i = 0; i < numNeurons; i++) {
             final long aId = neuronList[i].getIdentifier();
             final Set<Long> aLinks = linkMap.get(aId);
             for (Long bId : neighbourIdList[i]) {
                 if (neuronMap.get(bId) == null) {
                     throw new MathIllegalStateException();
                 }
                 addLinkToLinkSet(aLinks, bId);
             }
         }
 
         this.nextId = new AtomicLong(nextId);
         this.featureSize = featureSize;
     }
 
     /**
      * @param initialIdentifier Identifier for the first neuron that
      * will be added to this network.
      * @param featureSize Size of the neuron's features.
      */
     public Network(long initialIdentifier,
                    int featureSize) {
         nextId = new AtomicLong(initialIdentifier);
         this.featureSize = featureSize;
     }
 
     /**
      * {@inheritDoc}
      */
     public Iterator<Neuron> iterator() {
         return neuronMap.values().iterator();
     }
 
     /**
      * Creates a list of the neurons, sorted in a custom order.
      *
      * @param comparator {@link Comparator} used for sorting the neurons.
      * @return a list of neurons, sorted in the order prescribed by the
      * given {@code comparator}.
      * @see NeuronIdentifierComparator
      */
     public Collection<Neuron> getNeurons(Comparator<Neuron> comparator) {
         final List<Neuron> neurons = new ArrayList<Neuron>();
         neurons.addAll(neuronMap.values());
 
         Collections.sort(neurons, comparator);
 
         return neurons;
     }
 
     /**
      * Creates a neuron and assigns it a unique identifier.
      *
      * @param features Initial values for the neuron's features.
      * @return the neuron's identifier.
      * @throws DimensionMismatchException if the length of {@code features}
      * is different from the expected size (as set by the
      * {@link #Network(long,int) constructor}).
      */
     public long createNeuron(double[] features) {
         if (features.length != featureSize) {
             throw new DimensionMismatchException(features.length, featureSize);
         }
 
         final long id = createNextId();
         neuronMap.put(id, new Neuron(id, features));
         linkMap.put(id, new HashSet<Long>());
         return id;
     }
 
     /**
      * Deletes a neuron.
      * Links from all neighbours to the removed neuron will also be
      * {@link #deleteLink(Neuron,Neuron) deleted}.
      *
      * @param neuron Neuron to be removed from this network.
      * @throws NoSuchElementException if {@code n} does not belong to
      * this network.
      */
     public void deleteNeuron(Neuron neuron) {
         final Collection<Neuron> neighbours = getNeighbours(neuron);
 
         // Delete links to from neighbours.
         for (Neuron n : neighbours) {
             deleteLink(n, neuron);
         }
 
         // Remove neuron.
         neuronMap.remove(neuron.getIdentifier());
     }
 
     /**
      * Gets the size of the neurons' features set.
      *
      * @return the size of the features set.
      */
     public int getFeaturesSize() {
         return featureSize;
     }
 
     /**
      * Adds a link from neuron {@code a} to neuron {@code b}.
      * Note: the link is not bi-directional; if a bi-directional link is
      * required, an additional call must be made with {@code a} and
      * {@code b} exchanged in the argument list.
      *
      * @param a Neuron.
      * @param b Neuron.
      * @throws NoSuchElementException if the neurons do not exist in the
      * network.
      */
     public void addLink(Neuron a,
                         Neuron b) {
         final long aId = a.getIdentifier();
         final long bId = b.getIdentifier();
 
         // Check that the neurons belong to this network.
         if (a != getNeuron(aId)) {
             throw new NoSuchElementException(Long.toString(aId));
         }
         if (b != getNeuron(bId)) {
             throw new NoSuchElementException(Long.toString(bId));
         }
 
         // Add link from "a" to "b".
         addLinkToLinkSet(linkMap.get(aId), bId);
     }
 
     /**
      * Adds a link to neuron {@code id} in given {@code linkSet}.
      * Note: no check verifies that the identifier indeed belongs
      * to this network.
      *
      * @param linkSet Neuron identifier.
      * @param id Neuron identifier.
      */
     private void addLinkToLinkSet(Set<Long> linkSet,
                                   long id) {
         linkSet.add(id);
     }
 
     /**
      * Deletes the link between neurons {@code a} and {@code b}.
      *
      * @param a Neuron.
      * @param b Neuron.
      * @throws NoSuchElementException if the neurons do not exist in the
      * network.
      */
     public void deleteLink(Neuron a,
                            Neuron b) {
         final long aId = a.getIdentifier();
         final long bId = b.getIdentifier();
 
         // Check that the neurons belong to this network.
         if (a != getNeuron(aId)) {
             throw new NoSuchElementException(Long.toString(aId));
         }
         if (b != getNeuron(bId)) {
             throw new NoSuchElementException(Long.toString(bId));
         }
 
         // Delete link from "a" to "b".
         deleteLinkFromLinkSet(linkMap.get(aId), bId);
     }
 
     /**
      * Deletes a link to neuron {@code id} in given {@code linkSet}.
      * Note: no check verifies that the identifier indeed belongs
      * to this network.
      *
      * @param linkSet Neuron identifier.
      * @param id Neuron identifier.
      */
     private void deleteLinkFromLinkSet(Set<Long> linkSet,
                                        long id) {
         linkSet.remove(id);
     }
 
     /**
      * Retrieves the neuron with the given (unique) {@code id}.
      *
      * @param id Identifier.
      * @return the neuron associated with the given {@code id}.
      * @throws NoSuchElementException if the neuron does not exist in the
      * network.
      */
     public Neuron getNeuron(long id) {
         final Neuron n = neuronMap.get(id);
         if (n == null) {
             throw new NoSuchElementException(Long.toString(id));
         }
         return n;
     }
 
     /**
      * Retrieves the neurons in the neighbourhood of any neuron in the
      * {@code neurons} list.
      * @param neurons Neurons for which to retrieve the neighbours.
      * @return the list of neighbours.
      * @see #getNeighbours(Iterable,Iterable)
      */
     public Collection<Neuron> getNeighbours(Iterable<Neuron> neurons) {
         return getNeighbours(neurons, null);
     }
 
     /**
      * Retrieves the neurons in the neighbourhood of any neuron in the
      * {@code neurons} list.
      * The {@code exclude} list allows to retrieve the "concentric"
      * neighbourhoods by removing the neurons that belong to the inner
      * "circles".
      *
      * @param neurons Neurons for which to retrieve the neighbours.
      * @param exclude Neurons to exclude from the returned list.
      * Can be {@code null}.
      * @return the list of neighbours.
      */
     public Collection<Neuron> getNeighbours(Iterable<Neuron> neurons,
                                             Iterable<Neuron> exclude) {
         final Set<Long> idList = new HashSet<Long>();
 
         for (Neuron n : neurons) {
             idList.addAll(linkMap.get(n.getIdentifier()));
         }
         if (exclude != null) {
             for (Neuron n : exclude) {
                 idList.remove(n.getIdentifier());
             }
         }
 
         final List<Neuron> neuronList = new ArrayList<Neuron>();
         for (Long id : idList) {
             neuronList.add(getNeuron(id));
         }
 
         return neuronList;
     }
 
     /**
      * Retrieves the neighbours of the given neuron.
      *
      * @param neuron Neuron for which to retrieve the neighbours.
      * @return the list of neighbours.
      * @see #getNeighbours(Neuron,Iterable)
      */
     public Collection<Neuron> getNeighbours(Neuron neuron) {
         return getNeighbours(neuron, null);
     }
 
     /**
      * Retrieves the neighbours of the given neuron.
      *
      * @param neuron Neuron for which to retrieve the neighbours.
      * @param exclude Neurons to exclude from the returned list.
      * Can be {@code null}.
      * @return the list of neighbours.
      */
     public Collection<Neuron> getNeighbours(Neuron neuron,
                                             Iterable<Neuron> exclude) {
         final Set<Long> idList = linkMap.get(neuron.getIdentifier());
         if (exclude != null) {
             for (Neuron n : exclude) {
                 idList.remove(n.getIdentifier());
             }
         }
 
         final List<Neuron> neuronList = new ArrayList<Neuron>();
         for (Long id : idList) {
             neuronList.add(getNeuron(id));
         }
 
         return neuronList;
     }
 
     /**
      * Creates a neuron identifier.
      *
      * @return a value that will serve as a unique identifier.
      */
     private Long createNextId() {
         return nextId.getAndIncrement();
     }
 
     /**
      * Prevents proxy bypass.
      *
      * @param in Input stream.
      */
     private void readObject(ObjectInputStream in) {
         throw new IllegalStateException();
     }
 
     /**
      * Custom serialization.
      *
      * @return the proxy instance that will be actually serialized.
      */
     private Object writeReplace() {
         final Neuron[] neuronList = neuronMap.values().toArray(new Neuron[0]);
         final long[][] neighbourIdList = new long[neuronList.length][];
 
         for (int i = 0; i < neuronList.length; i++) {
             final Collection<Neuron> neighbours = getNeighbours(neuronList[i]);
             final long[] neighboursId = new long[neighbours.size()];
             int count = 0;
             for (Neuron n : neighbours) {
                 neighboursId[count] = n.getIdentifier();
                 ++count;
             }
             neighbourIdList[i] = neighboursId;
         }
 
         return new SerializationProxy(nextId.get(),
                                       featureSize,
                                       neuronList,
                                       neighbourIdList);
     }
 
     /**
      * Serialization.
      */
     private static class SerializationProxy implements Serializable {
         /** Serializable. */
         private static final long serialVersionUID = 20130207L;
         /** Next identifier. */
         private final long nextId;
         /** Number of features. */
         private final int featureSize;
         /** Neurons. */
         private final Neuron[] neuronList;
         /** Links. */
         private final long[][] neighbourIdList;
 
         /**
          * @param nextId Next available identifier.
          * @param featureSize Number of features.
          * @param neuronList Neurons.
          * @param neighbourIdList Links associated to each of the neurons in
          * {@code neuronList}.
          */
         SerializationProxy(long nextId,
                            int featureSize,
                            Neuron[] neuronList,
                            long[][] neighbourIdList) {
             this.nextId = nextId;
             this.featureSize = featureSize;
             this.neuronList = neuronList;
             this.neighbourIdList = neighbourIdList;
         }
 
         /**
          * Custom serialization.
          *
          * @return the {@link Network} for which this instance is the proxy.
          */
         private Object readResolve() {
             return new Network(nextId,
                                featureSize,
                                neuronList,
                                neighbourIdList);
         }
     }
 }