/*
* 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.
*
* @since 3.3
*/
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);
}
}
}