commons-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From er...@apache.org
Subject svn commit: r1557267 [1/3] - in /commons/proper/math/trunk: ./ src/changes/ src/main/java/org/apache/commons/math3/ml/neuralnet/ src/main/java/org/apache/commons/math3/ml/neuralnet/oned/ src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/ src/mai...
Date Fri, 10 Jan 2014 22:01:28 GMT
Author: erans
Date: Fri Jan 10 22:01:27 2014
New Revision: 1557267

URL: http://svn.apache.org/r1557267
Log:
MATH-923
Implementation of Kohonen's Self-Organizing Feature Map (SOFM).
New package "o.a.c.m.ml.neuralnet" contains base functionality for implementing
different map types, i.e. methods that project a high-dimensional space onto one
with a low dimension (typically 1D or 2D).
The SOFM-specific code is in "o.a.c.m.ml.neuralnet.sofm".

Added:
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunctionFactory.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/NeighbourhoodSizeFunction.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/NeighbourhoodSizeFunctionFactory.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/package-info.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/util/
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/util/ExponentialDecayFunction.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/util/QuasiSigmoidDecayFunction.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/util/package-info.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/twod/
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/twod/NeuronSquareMesh2D.java   (with props)
    commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/twod/package-info.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/MapUtilsTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/NetworkTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/NeuronTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/OffsetFeatureInitializer.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/oned/
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronStringTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTaskTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateActionTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunctionFactoryTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/NeighbourhoodSizeFunctionFactoryTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/TravellingSalesmanSolver.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/util/
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/util/ExponentialDecayFunctionTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/sofm/util/QuasiSigmoidDecayFunctionTest.java   (with props)
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/twod/
    commons/proper/math/trunk/src/test/java/org/apache/commons/math3/ml/neuralnet/twod/NeuronSquareMesh2DTest.java   (with props)
    commons/proper/math/trunk/src/userguide/java/org/apache/commons/math3/userguide/sofm/
    commons/proper/math/trunk/src/userguide/java/org/apache/commons/math3/userguide/sofm/ChineseRings.java   (with props)
    commons/proper/math/trunk/src/userguide/java/org/apache/commons/math3/userguide/sofm/ChineseRingsClassifier.java   (with props)
Modified:
    commons/proper/math/trunk/LICENSE.txt
    commons/proper/math/trunk/findbugs-exclude-filter.xml
    commons/proper/math/trunk/src/changes/changes.xml

Modified: commons/proper/math/trunk/LICENSE.txt
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/LICENSE.txt?rev=1557267&r1=1557266&r2=1557267&view=diff
==============================================================================
--- commons/proper/math/trunk/LICENSE.txt (original)
+++ commons/proper/math/trunk/LICENSE.txt Fri Jan 10 22:01:27 2014
@@ -434,3 +434,8 @@ ON ANY THEORY OF LIABILITY, WHETHER IN C
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ===============================================================================
 
+The initial commit of package "org.apache.commons.math3.ml.neuralnet" is
+an adapted version of code developed in the context of the Data Processing
+and Analysis Consortium (DPAC) of the "Gaia" project of the European Space
+Agency (ESA).
+===============================================================================

Modified: commons/proper/math/trunk/findbugs-exclude-filter.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/findbugs-exclude-filter.xml?rev=1557267&r1=1557266&r2=1557267&view=diff
==============================================================================
--- commons/proper/math/trunk/findbugs-exclude-filter.xml (original)
+++ commons/proper/math/trunk/findbugs-exclude-filter.xml Fri Jan 10 22:01:27 2014
@@ -363,4 +363,11 @@
     <Bug pattern="ICAST_IDIV_CAST_TO_DOUBLE" />
   </Match>
 
+  <!-- The following switch fall-through is intended. -->
+  <Match>
+    <Class name="org.apache.commons.math3.ml.neuralnet.twod.NeuronSquareMesh2D" />
+    <Method name="createLinks" />
+    <Bug pattern="SF_SWITCH_FALLTHROUGH" />
+  </Match>
+
 </FindBugsFilter>

Modified: commons/proper/math/trunk/src/changes/changes.xml
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/changes/changes.xml?rev=1557267&r1=1557266&r2=1557267&view=diff
==============================================================================
--- commons/proper/math/trunk/src/changes/changes.xml (original)
+++ commons/proper/math/trunk/src/changes/changes.xml Fri Jan 10 22:01:27 2014
@@ -51,6 +51,10 @@ If the output is not quite correct, chec
   </properties>
   <body>
     <release version="3.3" date="TBD" description="TBD">
+      <action dev="erans" type="add" issue="MATH-923">
+        Utilities for creating artificial neural networks (package "o.a.c.m.ml.neuralnet").
+        Implementation of Kohonen's Self-Organizing Feature Map (SOFM).
+      </action>
       <action dev="tn" type="fix" issue="MATH-1082">
         The cutOff mechanism of the "SimplexSolver" in package o.a.c.math3.optim.linear
         could lead to invalid solutions. The mechanism has been improved in a way that

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,32 @@
+/*
+ * 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;
+
+/**
+ * Defines how to assign the first value of a neuron's feature.
+ *
+ * @version $Id$
+ */
+public interface FeatureInitializer {
+    /**
+     * Selects the initial value.
+     *
+     * @return the initial value.
+     */
+    double value();
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializer.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,94 @@
+/*
+ * 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 org.apache.commons.math3.distribution.RealDistribution;
+import org.apache.commons.math3.distribution.UniformRealDistribution;
+import org.apache.commons.math3.analysis.UnivariateFunction;
+import org.apache.commons.math3.analysis.function.Constant;
+
+/**
+ * Creates functions that will select the initial values of a neuron's
+ * features.
+ *
+ * @version $Id$
+ */
+public class FeatureInitializerFactory {
+    /** Class contains only static methods. */
+    private FeatureInitializerFactory() {}
+
+    /**
+     * Uniform sampling of the given range.
+     *
+     * @param min Lower bound of the range.
+     * @param max Upper bound of the range.
+     * @return an initializer such that the features will be initialized with
+     * values within the given range.
+     * @throws org.apache.commons.math3.exception.NumberIsTooLargeException
+     * if {@code min >= max}.
+     */
+    public static FeatureInitializer uniform(final double min,
+                                             final double max) {
+        return randomize(new UniformRealDistribution(min, max),
+                         function(new Constant(0), 0, 0));
+    }
+
+    /**
+     * Creates an initializer from a univariate function {@code f(x)}.
+     * The argument {@code x} is set to {@code init} at the first call
+     * and will be incremented at each call.
+     *
+     * @param f Function.
+     * @param init Initial value.
+     * @param inc Increment
+     * @return the initializer.
+     */
+    public static FeatureInitializer function(final UnivariateFunction f,
+                                              final double init,
+                                              final double inc) {
+        return new FeatureInitializer() {
+            /** Argument. */
+            private double arg = init;
+
+            /** {@inheritDoc} */
+            public double value() {
+                final double result = f.value(arg);
+                arg += inc;
+                return result;
+            }
+        };
+    }
+
+    /**
+     * Adds some amount of random data to the given initializer.
+     *
+     * @param random Random variable distribution.
+     * @param orig Original initializer.
+     * @return an initializer whose {@link FeatureInitializer#value() value}
+     * method will return {@code orig.value() + random.sample()}.
+     */
+    public static FeatureInitializer randomize(final RealDistribution random,
+                                               final FeatureInitializer orig) {
+        return new FeatureInitializer() {
+            /** {@inheritDoc} */
+            public double value() {
+                return orig.value() + random.sample();
+            }
+        };
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/FeatureInitializerFactory.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,247 @@
+/*
+ * 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.util.HashMap;
+import java.util.Collection;
+import org.apache.commons.math3.ml.distance.DistanceMeasure;
+import org.apache.commons.math3.ml.neuralnet.twod.NeuronSquareMesh2D;
+import org.apache.commons.math3.exception.NoDataException;
+import org.apache.commons.math3.util.Pair;
+
+/**
+ * Utilities for network maps.
+ *
+ * @version $Id$
+ */
+public class MapUtils {
+    /**
+     * Class contains only static methods.
+     */
+    private MapUtils() {}
+
+    /**
+     * Finds the neuron that best matches the given features.
+     *
+     * @param features Data.
+     * @param neurons List of neurons to scan. If the list is empty
+     * {@code null} will be returned.
+     * @param distance Distance function. The neuron's features are
+     * passed as the first argument to {@link DistanceMeasure#compute(double[],double[])}.
+     * @return the neuron whose features are closest to the given data.
+     * @throws org.apache.commons.math3.exception.DimensionMismatchException
+     * if the size of the input is not compatible with the neurons features
+     * size.
+     */
+    public static Neuron findBest(double[] features,
+                                  Iterable<Neuron> neurons,
+                                  DistanceMeasure distance) {
+        Neuron best = null;
+        double min = Double.POSITIVE_INFINITY;
+        for (final Neuron n : neurons) {
+            final double d = distance.compute(n.getFeatures(), features);
+            if (d < min) {
+                min = d;
+                best = n;
+            }
+        }
+
+        return best;
+    }
+
+    /**
+     * Finds the two neurons that best match the given features.
+     *
+     * @param features Data.
+     * @param neurons List of neurons to scan. If the list is empty
+     * {@code null} will be returned.
+     * @param distance Distance function. The neuron's features are
+     * passed as the first argument to {@link DistanceMeasure#compute(double[],double[])}.
+     * @return the two neurons whose features are closest to the given data.
+     * @throws org.apache.commons.math3.exception.DimensionMismatchException
+     * if the size of the input is not compatible with the neurons features
+     * size.
+     */
+    public static Pair<Neuron, Neuron> findBestAndSecondBest(double[] features,
+                                                             Iterable<Neuron> neurons,
+                                                             DistanceMeasure distance) {
+        Neuron[] best = { null, null };
+        double[] min = { Double.POSITIVE_INFINITY,
+                         Double.POSITIVE_INFINITY };
+        for (final Neuron n : neurons) {
+            final double d = distance.compute(n.getFeatures(), features);
+            if (d < min[0]) {
+                // Replace second best with old best.
+                min[1] = min[0];
+                best[1] = best[0];
+
+                // Store current as new best.
+                min[0] = d;
+                best[0] = n;
+            } else if (d < min[1]) {
+                // Replace old second best with current.
+                min[1] = d;
+                best[1] = n;
+            }
+        }
+
+        return new Pair<Neuron, Neuron>(best[0], best[1]);
+    }
+
+    /**
+     * Computes the <a href="http://en.wikipedia.org/wiki/U-Matrix">
+     *  U-matrix</a> of a two-dimensional map.
+     *
+     * @param map Network.
+     * @param distance Function to use for computing the average
+     * distance from a neuron to its neighbours.
+     * @return the matrix of average distances.
+     */
+    public static double[][] computeU(NeuronSquareMesh2D map,
+                                      DistanceMeasure distance) {
+        final int numRows = map.getNumberOfRows();
+        final int numCols = map.getNumberOfColumns();
+        final double[][] uMatrix = new double[numRows][numCols];
+
+        final Network net = map.getNetwork();
+
+        for (int i = 0; i < numRows; i++) {
+            for (int j = 0; j < numCols; j++) {
+                final Neuron neuron = map.getNeuron(i, j);
+                final Collection<Neuron> neighbours = net.getNeighbours(neuron);
+                final double[] features = neuron.getFeatures();
+
+                double d = 0;
+                int count = 0;
+                for (Neuron n : neighbours) {
+                    ++count;
+                    d += distance.compute(features, n.getFeatures());
+                }
+
+                uMatrix[i][j] = d / count;
+            }
+        }
+
+        return uMatrix;
+    }
+
+    /**
+     * Computes the "hit" histogram of a two-dimensional map.
+     *
+     * @param data Feature vectors.
+     * @param map Network.
+     * @param distance Function to use for determining the best matching unit.
+     * @return the number of hits for each neuron in the map.
+     */
+    public static int[][] computeHitHistogram(Iterable<double[]> data,
+                                              NeuronSquareMesh2D map,
+                                              DistanceMeasure distance) {
+        final HashMap<Neuron, Integer> hit = new HashMap<Neuron, Integer>();
+        final Network net = map.getNetwork();
+
+        for (double[] f : data) {
+            final Neuron best = findBest(f, net, distance);
+            final Integer count = hit.get(best);
+            if (count == null) {
+                hit.put(best, 1);
+            } else {
+                hit.put(best, count + 1);
+            }
+        }
+
+        // Copy the histogram data into a 2D map.
+        final int numRows = map.getNumberOfRows();
+        final int numCols = map.getNumberOfColumns();
+        final int[][] histo = new int[numRows][numCols];
+
+        for (int i = 0; i < numRows; i++) {
+            for (int j = 0; j < numCols; j++) {
+                final Neuron neuron = map.getNeuron(i, j);
+                final Integer count = hit.get(neuron);
+                if (count == null) {
+                    histo[i][j] = 0;
+                } else {
+                    histo[i][j] = count;
+                }
+            }
+        }
+
+        return histo;
+    }
+
+    /**
+     * Computes the quantization error.
+     * The quantization error is the average distance between a feature vector
+     * and its "best matching unit" (closest neuron).
+     *
+     * @param data Feature vectors.
+     * @param neurons List of neurons to scan.
+     * @param distance Distance function.
+     * @return the error.
+     * @throws NoDataException if {@code data} is empty.
+     */
+    public static double computeQuantizationError(Iterable<double[]> data,
+                                                  Iterable<Neuron> neurons,
+                                                  DistanceMeasure distance) {
+        double d = 0;
+        int count = 0;
+        for (double[] f : data) {
+            ++count;
+            d += distance.compute(f, findBest(f, neurons, distance).getFeatures());
+        }
+
+        if (count == 0) {
+            throw new NoDataException();
+        }
+
+        return d / count;
+    }
+
+    /**
+     * Computes the topographic error.
+     * The topographic error is the proportion of data for which first and
+     * second best matching units are not adjacent in the map.
+     *
+     * @param data Feature vectors.
+     * @param net Network.
+     * @param distance Distance function.
+     * @return the error.
+     * @throws NoDataException if {@code data} is empty.
+     */
+    public static double computeTopographicError(Iterable<double[]> data,
+                                                 Network net,
+                                                 DistanceMeasure distance) {
+        int notAdjacentCount = 0;
+        int count = 0;
+        for (double[] f : data) {
+            ++count;
+            final Pair<Neuron, Neuron> p = findBestAndSecondBest(f, net, distance);
+            if (!net.getNeighbours(p.getFirst()).contains(p.getSecond())) {
+                // Increment count if first and second best matching units
+                // are not neighbours.
+                ++notAdjacentCount;
+            }
+        }
+
+        if (count == 0) {
+            throw new NoDataException();
+        }
+
+        return ((double) notAdjacentCount) / count;
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/MapUtils.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,476 @@
+/*
+ * 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.
+ *
+ * @version $Id$
+ */
+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} */
+        @Override
+        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}
+     */
+    @Override
+    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);
+        }
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Network.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,215 @@
+/*
+ * 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.concurrent.atomic.AtomicReference;
+import org.apache.commons.math3.util.Precision;
+import org.apache.commons.math3.exception.DimensionMismatchException;
+
+
+/**
+ * Describes a neuron element of a neural network.
+ *
+ * This class aims to be thread-safe.
+ *
+ * @version $Id$
+ */
+public class Neuron implements Serializable {
+    /** Serializable. */
+    private static final long serialVersionUID = 20130207L;
+    /** Identifier. */
+    private final long identifier;
+    /** Length of the feature set. */
+    private final int size;
+    /** Neuron data. */
+    private final AtomicReference<double[]> features;
+
+    /**
+     * Creates a neuron.
+     * The size of the feature set is fixed to the length of the given
+     * argument.
+     * <br/>
+     * Constructor is package-private: Neurons must be
+     * {@link Network#createNeuron(double[]) created} by the network
+     * instance to which they will belong.
+     *
+     * @param identifier Identifier (assigned by the {@link Network}).
+     * @param features Initial values of the feature set.
+     */
+    Neuron(long identifier,
+           double[] features) {
+        this.identifier = identifier;
+        this.size = features.length;
+        this.features = new AtomicReference<double[]>(features.clone());
+    }
+
+    /**
+     * Gets the neuron's identifier.
+     *
+     * @return the identifier.
+     */
+    public long getIdentifier() {
+        return identifier;
+    }
+
+    /**
+     * Gets the length of the feature set.
+     *
+     * @return the number of features.
+     */
+    public int getSize() {
+        return size;
+    }
+
+    /**
+     * Gets the neuron's features.
+     *
+     * @return a copy of the neuron's features.
+     */
+    public double[] getFeatures() {
+        return features.get().clone();
+    }
+
+    /**
+     * Tries to atomically update the neuron's features.
+     * Update will be performed only if the expected values match the
+     * current values.<br/>
+     * In effect, when concurrent threads call this method, the state
+     * could be modified by one, so that it does not correspond to the
+     * the state assumed by another.
+     * Typically, a caller {@link #getFeatures() retrieves the current state},
+     * and uses it to compute the new state.
+     * During this computation, another thread might have done the same
+     * thing, and updated the state: If the current thread were to proceed
+     * with its own update, it would overwrite the new state (which might
+     * already have been used by yet other threads).
+     * To prevent this, the method does not perform the update when a
+     * concurrent modification has been detected, and returns {@code false}.
+     * When this happens, the caller should fetch the new current state,
+     * redo its computation, and call this method again.
+     *
+     * @param expect Current values of the features, as assumed by the caller.
+     * Update will never succeed if the contents of this array does not match
+     * the values returned by {@link #getFeatures()}.
+     * @param update Features's new values.
+     * @return {@code true} if the update was successful, {@code false}
+     * otherwise.
+     * @throws DimensionMismatchException if the length of {@code update} is
+     * not the same as specified in the {@link #Neuron(long,double[])
+     * constructor}.
+     */
+    public boolean compareAndSetFeatures(double[] expect,
+                                         double[] update) {
+        if (update.length != size) {
+            throw new DimensionMismatchException(update.length, size);
+        }
+
+        // Get the internal reference. Note that this must not be a copy;
+        // otherwise the "compareAndSet" below will always fail.
+        final double[] current = features.get();
+        if (!containSameValues(current, expect)) {
+            // Some other thread already modified the state.
+            return false;
+        }
+
+        if (features.compareAndSet(current, update.clone())) {
+            // The current thread could atomically update the state.
+            return true;
+        } else {
+            // Some other thread came first.
+            return false;
+        }
+    }
+
+    /**
+     * Checks whether the contents of both arrays is the same.
+     *
+     * @param current Current values.
+     * @param expect Expected values.
+     * @throws DimensionMismatchException if the length of {@code expected}
+     * is not the same as specified in the {@link #Neuron(long,double[])
+     * constructor}.
+     * @return {@code true} if the arrays contain the same values.
+     */
+    private boolean containSameValues(double[] current,
+                                      double[] expect) {
+        if (expect.length != size) {
+            throw new DimensionMismatchException(expect.length, size);
+        }
+
+        for (int i = 0; i < size; i++) {
+            if (!Precision.equals(current[i], expect[i])) {
+                return false;
+            }
+        }
+        return true;
+    }
+
+    /**
+     * 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() {
+        return new SerializationProxy(identifier,
+                                      features.get());
+    }
+
+    /**
+     * Serialization.
+     */
+    private static class SerializationProxy implements Serializable {
+        /** Serializable. */
+        private static final long serialVersionUID = 20130207L;
+        /** Features. */
+        private final double[] features;
+        /** Identifier. */
+        private final long identifier;
+
+        /**
+         * @param identifier Identifier.
+         * @param features Features.
+         */
+        SerializationProxy(long identifier,
+                           double[] features) {
+            this.identifier = identifier;
+            this.features = features;
+        }
+
+        /**
+         * Custom serialization.
+         *
+         * @return the {@link Neuron} for which this instance is the proxy.
+         */
+        private Object readResolve() {
+            return new Neuron(identifier,
+                              features);
+        }
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/Neuron.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,38 @@
+/*
+ * 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;
+
+/**
+ * Defines neighbourhood types.
+ *
+ * @version $Id$
+ */
+public enum SquareNeighbourhood {
+    /**
+     * <a href="http://en.wikipedia.org/wiki/Von_Neumann_neighborhood"
+     *  Von Neumann neighbourhood</a>: in two dimensions, each (internal)
+     * neuron has four neighbours.
+     */
+    VON_NEUMANN,
+    /**
+     * <a href="http://en.wikipedia.org/wiki/Moore_neighborhood"
+     *  Moore neighbourhood</a>: in two dimensions, each (internal)
+     * neuron has eight neighbours.
+     */
+    MOORE,
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/SquareNeighbourhood.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,34 @@
+/*
+ * 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;
+
+/**
+ * Describes how to update the network in response to a training
+ * sample.
+ *
+ * @version $Id$
+ */
+public interface UpdateAction {
+    /**
+     * Updates the network in response to the sample {@code features}.
+     *
+     * @param net Network.
+     * @param features Training data.
+     */
+    void update(Network net, double[] features);
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/UpdateAction.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,236 @@
+/*
+ * 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.oned;
+
+import java.io.Serializable;
+import java.io.ObjectInputStream;
+import org.apache.commons.math3.ml.neuralnet.Network;
+import org.apache.commons.math3.ml.neuralnet.FeatureInitializer;
+import org.apache.commons.math3.exception.NumberIsTooSmallException;
+import org.apache.commons.math3.exception.OutOfRangeException;
+
+/**
+ * Neural network with the topology of a one-dimensional line.
+ * Each neuron defines one point on the line.
+ *
+ * @version $Id$
+ */
+public class NeuronString implements Serializable {
+    /** Underlying network. */
+    private final Network network;
+    /** Number of neurons. */
+    private final int size;
+    /** Wrap. */
+    private final boolean wrap;
+
+    /**
+     * Mapping of the 1D coordinate to the neuron identifiers
+     * (attributed by the {@link #network} instance).
+     */
+    private final long[] identifiers;
+
+    /**
+     * Constructor with restricted access, solely used for deserialization.
+     *
+     * @param wrap Whether to wrap the dimension (i.e the first and last
+     * neurons will be linked together).
+     * @param featuresList Arrays that will initialize the features sets of
+     * the network's neurons.
+     * @throws NumberIsTooSmallException if {@code num < 2}.
+     */
+    NeuronString(boolean wrap,
+                 double[][] featuresList) {
+        size = featuresList.length;
+
+        if (size < 2) {
+            throw new NumberIsTooSmallException(size, 2, true);
+        }
+
+        this.wrap = wrap;
+
+        final int fLen = featuresList[0].length;
+        network = new Network(0, fLen);
+        identifiers = new long[size];
+
+        // Add neurons.
+        for (int i = 0; i < size; i++) {
+            identifiers[i] = network.createNeuron(featuresList[i]);
+        }
+
+        // Add links.
+        createLinks();
+    }
+
+    /**
+     * Creates a one-dimensional network:
+     * Each neuron not located on the border of the mesh has two
+     * neurons linked to it.
+     * <br/>
+     * The links are bi-directional.
+     * Neurons created successively are neighbours (i.e. there are
+     * links between them).
+     * <br/>
+     * The topology of the network can also be a circle (if the
+     * dimension is wrapped).
+     *
+     * @param num Number of neurons.
+     * @param wrap Whether to wrap the dimension (i.e the first and last
+     * neurons will be linked together).
+     * @param featureInit Arrays that will initialize the features sets of
+     * the network's neurons.
+     * @throws NumberIsTooSmallException if {@code num < 2}.
+     */
+    public NeuronString(int num,
+                        boolean wrap,
+                        FeatureInitializer[] featureInit) {
+        if (num < 2) {
+            throw new NumberIsTooSmallException(num, 2, true);
+        }
+
+        size = num;
+        this.wrap = wrap;
+        identifiers = new long[num];
+
+        final int fLen = featureInit.length;
+        network = new Network(0, fLen);
+
+        // Add neurons.
+        for (int i = 0; i < num; i++) {
+            final double[] features = new double[fLen];
+            for (int fIndex = 0; fIndex < fLen; fIndex++) {
+                features[fIndex] = featureInit[fIndex].value();
+            }
+            identifiers[i] = network.createNeuron(features);
+        }
+
+        // Add links.
+        createLinks();
+    }
+
+    /**
+     * Retrieves the underlying network.
+     * A reference is returned (enabling, for example, the network to be
+     * trained).
+     * This also implies that calling methods that modify the {@link Network}
+     * topology may cause this class to become inconsistent.
+     *
+     * @return the network.
+     */
+    public Network getNetwork() {
+        return network;
+    }
+
+    /**
+     * Gets the number of neurons.
+     *
+     * @return the number of neurons.
+     */
+    public int getSize() {
+        return size;
+    }
+
+    /**
+     * Retrieves the features set from the neuron at location
+     * {@code i} in the map.
+     *
+     * @param i Neuron index.
+     * @return the features of the neuron at index {@code i}.
+     * @throws OutOfRangeException if {@code i} is out of range.
+     */
+    public double[] getFeatures(int i) {
+        if (i < 0 ||
+            i >= size) {
+            throw new OutOfRangeException(i, 0, size - 1);
+        }
+
+        return network.getNeuron(identifiers[i]).getFeatures();
+    }
+
+    /**
+     * Creates the neighbour relationships between neurons.
+     */
+    private void createLinks() {
+        for (int i = 0; i < size - 1; i++) {
+            network.addLink(network.getNeuron(i), network.getNeuron(i + 1));
+        }
+        for (int i = size - 1; i > 0; i--) {
+            network.addLink(network.getNeuron(i), network.getNeuron(i - 1));
+        }
+        if (wrap) {
+            network.addLink(network.getNeuron(0), network.getNeuron(size - 1));
+            network.addLink(network.getNeuron(size - 1), network.getNeuron(0));
+        }
+    }
+
+    /**
+     * 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 double[][] featuresList = new double[size][];
+        for (int i = 0; i < size; i++) {
+            featuresList[i] = getFeatures(i);
+        }
+
+        return new SerializationProxy(wrap,
+                                      featuresList);
+    }
+
+    /**
+     * Serialization.
+     */
+    private static class SerializationProxy implements Serializable {
+        /** Serializable. */
+        private static final long serialVersionUID = 20130226L;
+        /** Wrap. */
+        private final boolean wrap;
+        /** Neurons' features. */
+        private final double[][] featuresList;
+
+        /**
+         * @param wrap Whether the dimension is wrapped.
+         * @param featuresList List of neurons features.
+         * {@code neuronList}.
+         */
+        SerializationProxy(boolean wrap,
+                           double[][] featuresList) {
+            this.wrap = wrap;
+            this.featuresList = featuresList;
+        }
+
+        /**
+         * Custom serialization.
+         *
+         * @return the {@link Neuron} for which this instance is the proxy.
+         */
+        private Object readResolve() {
+            return new NeuronString(wrap,
+                                    featuresList);
+        }
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/NeuronString.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+
+/**
+ * One-dimensional neural networks.
+ */
+
+package org.apache.commons.math3.ml.neuralnet.oned;

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/oned/package-info.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,22 @@
+/*
+ * 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.
+ */
+
+/**
+ * Neural networks.
+ */
+
+package org.apache.commons.math3.ml.neuralnet;

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/package-info.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,59 @@
+/*
+ * 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.sofm;
+
+import java.util.Iterator;
+import org.apache.commons.math3.ml.neuralnet.Network;
+
+/**
+ * Trainer for Kohonen's Self-Organizing Map.
+ *
+ * @version $Id$
+ */
+public class KohonenTrainingTask implements Runnable {
+    /** SOFM to be trained. */
+    private final Network net;
+    /** Training data. */
+    private final Iterator<double[]> featuresIterator;
+    /** Update procedure. */
+    private final KohonenUpdateAction updateAction;
+
+    /**
+     * Creates a (sequential) trainer for the given network.
+     *
+     * @param net Network to be trained with the SOFM algorithm.
+     * @param featuresIterator Training data iterator.
+     * @param updateAction SOFM update procedure.
+     */
+    public KohonenTrainingTask(Network net,
+                               Iterator<double[]> featuresIterator,
+                               KohonenUpdateAction updateAction) {
+        this.net = net;
+        this.featuresIterator = featuresIterator;
+        this.updateAction = updateAction;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    public void run() {
+        while (featuresIterator.hasNext()) {
+            updateAction.update(net, featuresIterator.next());
+        }
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenTrainingTask.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,213 @@
+/*
+ * 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.sofm;
+
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.concurrent.atomic.AtomicLong;
+import org.apache.commons.math3.ml.neuralnet.Network;
+import org.apache.commons.math3.ml.neuralnet.MapUtils;
+import org.apache.commons.math3.ml.neuralnet.Neuron;
+import org.apache.commons.math3.ml.neuralnet.UpdateAction;
+import org.apache.commons.math3.ml.distance.DistanceMeasure;
+import org.apache.commons.math3.linear.ArrayRealVector;
+import org.apache.commons.math3.analysis.function.Gaussian;
+
+/**
+ * Update formula for <a href="http://en.wikipedia.org/wiki/Kohonen">
+ * Kohonen's Self-Organizing Map</a>.
+ * <br/>
+ * The {@link #update(Network,double[]) update} method modifies the
+ * features {@code w} of the "winning" neuron and its neighbours
+ * according to the following rule:
+ * <code>
+ *  w<sub>new</sub> = w<sub>old</sub> + &alpha; e<sup>(-d / &sigma;)</sup> * (sample - w<sub>old</sub>)
+ * </code>
+ * where
+ * <ul>
+ *  <li>&alpha; is the current <em>learning rate</em>, </li>
+ *  <li>&sigma; is the current <em>neighbourhood size</em>, and</li>
+ *  <li>{@code d} is the number of links to traverse in order to reach
+ *   the neuron from the winning neuron.</li>
+ * </ul>
+ * <br/>
+ * This class is thread-safe as long as the arguments passed to the
+ * {@link #KohonenUpdateAction(DistanceMeasure,LearningFactorFunction,
+ * NeighbourhoodSizeFunction) constructor} are instances of thread-safe
+ * classes.
+ * <br/>
+ * Each call to the {@link #update(Network,double[]) update} method
+ * will increment the internal counter used to compute the current
+ * values for
+ * <ul>
+ *  <li>the <em>learning rate</em>, and</li>
+ *  <li>the <em>neighbourhood size</em>.</li>
+ * </ul>
+ * Consequently, the function instances that compute those values (passed
+ * to the constructor of this class) must take into account whether this
+ * class's instance will be shared by multiple threads, as this will impact
+ * the training process.
+ *
+ * @version $Id$
+ */
+public class KohonenUpdateAction implements UpdateAction {
+    /** Distance function. */
+    private final DistanceMeasure distance;
+    /** Learning factor update function. */
+    private final LearningFactorFunction learningFactor;
+    /** Neighbourhood size update function. */
+    private final NeighbourhoodSizeFunction neighbourhoodSize;
+    /** Number of calls to {@link #update(Network,double[])}. */
+    private final AtomicLong numberOfCalls = new AtomicLong(-1);
+
+    /**
+     * @param distance Distance function.
+     * @param learningFactor Learning factor update function.
+     * @param neighbourhoodSize Neighbourhood size update function.
+     */
+    public KohonenUpdateAction(DistanceMeasure distance,
+                               LearningFactorFunction learningFactor,
+                               NeighbourhoodSizeFunction neighbourhoodSize) {
+        this.distance = distance;
+        this.learningFactor = learningFactor;
+        this.neighbourhoodSize = neighbourhoodSize;
+    }
+
+    /**
+     * {@inheritDoc}
+     */
+    @Override
+    public void update(Network net,
+                       double[] features) {
+        final long numCalls = numberOfCalls.incrementAndGet();
+        final double currentLearning = learningFactor.value(numCalls);
+        final Neuron best = findAndUpdateBestNeuron(net,
+                                                    features,
+                                                    currentLearning);
+
+        final int currentNeighbourhood = neighbourhoodSize.value(numCalls);
+        // The farther away the neighbour is from the winning neuron, the
+        // smaller the learning rate will become.
+        final Gaussian neighbourhoodDecay
+            = new Gaussian(currentLearning,
+                           0,
+                           1d / currentNeighbourhood);
+
+        if (currentNeighbourhood > 0) {
+            // Initial set of neurons only contains the winning neuron.
+            Collection<Neuron> neighbours = new HashSet<Neuron>();
+            neighbours.add(best);
+            // Winning neuron must be excluded from the neighbours.
+            final HashSet<Neuron> exclude = new HashSet<Neuron>();
+            exclude.add(best);
+
+            int radius = 1;
+            do {
+                // Retrieve immediate neighbours of the current set of neurons.
+                neighbours = net.getNeighbours(neighbours, exclude);
+
+                // Update all the neighbours.
+                for (Neuron n : neighbours) {
+                    updateNeighbouringNeuron(n, features, neighbourhoodDecay.value(radius));
+                }
+
+                // Add the neighbours to the exclude list so that they will
+                // not be update more than once per training step.
+                exclude.addAll(neighbours);
+                ++radius;
+            } while (radius <= currentNeighbourhood);
+        }
+    }
+
+    /**
+     * Retrieves the number of calls to the {@link #update(Network,double[]) update}
+     * method.
+     *
+     * @return the current number of calls.
+     */
+    public long getNumberOfCalls() {
+        return numberOfCalls.get();
+    }
+
+    /**
+     * Atomically updates the given neuron.
+     *
+     * @param n Neuron to be updated.
+     * @param features Training data.
+     * @param learningRate Learning factor.
+     */
+    private void updateNeighbouringNeuron(Neuron n,
+                                          double[] features,
+                                          double learningRate) {
+        while (true) {
+            final double[] expect = n.getFeatures();
+            final double[] update = computeFeatures(expect,
+                                                    features,
+                                                    learningRate);
+            if (n.compareAndSetFeatures(expect, update)) {
+                break;
+            }
+        }
+    }
+
+    /**
+     * Searches for the neuron whose features are closest to the given
+     * sample, and atomically updates its features.
+     *
+     * @param net Network.
+     * @param features Sample data.
+     * @param learningRate Current learning factor.
+     * @return the winning neuron.
+     */
+    private Neuron findAndUpdateBestNeuron(Network net,
+                                           double[] features,
+                                           double learningRate) {
+        while (true) {
+            final Neuron best = MapUtils.findBest(features, net, distance);
+
+            final double[] expect = best.getFeatures();
+            final double[] update = computeFeatures(expect,
+                                                    features,
+                                                    learningRate);
+            if (best.compareAndSetFeatures(expect, update)) {
+                return best;
+            }
+
+            // If another thread modified the state of the winning neuron,
+            // it may not be the best match anymore for the given training
+            // sample: Hence, the winner search is performed again.
+        }
+    }
+
+    /**
+     * Computes the new value of the features set.
+     *
+     * @param current Current values of the features.
+     * @param sample Training data.
+     * @param learningRate Learning factor.
+     * @return the new values for the features.
+     */
+    private double[] computeFeatures(double[] current,
+                                     double[] sample,
+                                     double learningRate) {
+        final ArrayRealVector c = new ArrayRealVector(current, false);
+        final ArrayRealVector s = new ArrayRealVector(sample, false);
+        // c + learningRate * (s - c)
+        return s.subtract(c).mapMultiplyToSelf(learningRate).add(c).toArray();
+    }
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/KohonenUpdateAction.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision

Added: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java
URL: http://svn.apache.org/viewvc/commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java?rev=1557267&view=auto
==============================================================================
--- commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java (added)
+++ commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java Fri Jan 10 22:01:27 2014
@@ -0,0 +1,34 @@
+/*
+ * 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.sofm;
+
+/**
+ * Provides the learning rate as a function of the number of calls
+ * already performed during the learning task.
+ *
+ * @version $Id$
+ */
+public interface LearningFactorFunction {
+    /**
+     * Computes the learning rate at the current call.
+     *
+     * @param numCall Current step of the training task.
+     * @return the value of the function at {@code numCall}.
+     */
+    double value(long numCall);
+}

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java
------------------------------------------------------------------------------
    svn:eol-style = native

Propchange: commons/proper/math/trunk/src/main/java/org/apache/commons/math3/ml/neuralnet/sofm/LearningFactorFunction.java
------------------------------------------------------------------------------
    svn:keywords = Id Revision



Mime
View raw message