/*
 * File:        UnitEncoder.java
 * Author:      Justin Basilico
 * Course:      PO CS 152: Neural Networks
 * Assignment:  Final Project
 * Updated:     2001.12.18
 * Created:     2001.12.03
 *
 * Description:
 * This file contains the UnitEncoder abstract class, which is an abstract
 * class that implements the common functionality among classes that take a
 * NetworkInput and encode some aspect (property) of it using some
 * representation into an array of doubles, which are units in a network.
 *
 * Copyright:    Justin Basilico (2001).
 */

import java.io.Serializable;

/**
 * UnitEncoder abstract class
 *
 * This abstract class implements the common functionality among classes that
 * encode some property of a NetworkInput into a representation that a
 * NeuralNetwork can use, which are an array of real values. The property and
 * the way that the encoding is done can vary for each encoder, which is done
 * by implementing the encode(NetworkInput, double[]) method. In addition,
 * each encoding needs to have a fixed dimensionality, which is the number of
 * units that the encoding is using to encode an input. This class also
 * implements an offset, which is the index in a given array of network units
 * for the encoder to start its encoding at. The default offset is 1, because
 * it is assumed that there is always a bias unit. The reason for the offset
 * is so that multiple UnitEncoders can be used together easily to encode
 * multiple properties of the same NetworkInput.
 *
 * A UnitEncoder needs to be Serializable so that they can be saved along with
 * the NeuralNetwork that they are encoding for. Currently, however, they are
 * only tied to FeedForwardNetworks, and not all general NeuralNetwork
 * objects. UnitEncoders are generally used for encoding the input for a
 * network along with a target output for supervised learning algorithms such
 * as backpropagation.
 *
 * @author  Justin Basilico
 * @version 2001.12.18
 * @see     NetworkInput
 * @see     NeuralNetwork
 * @see     FeedForwardNetwork
 */
public abstract class UnitEncoder
    extends Object
    implements Serializable
{
    /** offset
     * This is the index to start the encoding at in the given array. */
    protected int           offset = 1;

    /**
     * UnitEncoder default constructor
     *
     * This constructor sets the offset to 1, because it is always assumed
     * that there is a bias unit.
     */
    public UnitEncoder()
    {
        this.offset = 1;
    }

    /**
     * UnitEncoder offset constructor
     *
     * This constructor takes a (non-negative) integer offset and initializes
     * this UnitEncoder to use that offset to start encoding at. If a negative
     * offset is given, it will use that as the offset, which will cause an
     * ArrayOutOfBoundsException if you try to encode anything before changing
     * it to a proper value.
     *
     * @param  offset The (non-negative) integer index to start encoding at in
     *         the encode() method.
     * @see    UnitEncoder.encode(NetworkInput, double[])
     */
    public UnitEncoder(
        int                 offset)             // Index to start encoding at.
    {
        this.offset = offset;
    }

    /**
     * getDimensionality
     *
     * This method returns the dimensionality of the encoding, which is the
     * number of units that the UnitEncoder will encode in a given array. This
     * needs to be a fixed number because the size of input or output units
     * in a network cannot change.
     *
     * @return The (positive) integer dimensionality of this encoder.
     */
    public abstract int getDimensionality();

    /**
     * encode
     *
     * This method takes a NetworkInput and an array of doubles, which are
     * units in a network. It encodes the given input in some manner into the
     * given units. The encoding starts encoding at the index in the array
     * that corresponds to its current offset and encodes from there until the
     * dimensionality of the encoding. The encoding is taking the NetworkInput
     * and encoding some property of it into the units as double values so
     * that it can be used by a NeuralNetwork in some capacity. If the given
     * array's size is less than the offset plus the dimensionality of this
     * UnitEncoder, the given array will remain unchanged. No value is
     * returned because the given array of units themselves are changed to
     * represent the fact that they are now encoded for the given input.
     *
     * @param  input The NetworkInput to encode into the given network units.
     * @param  units The array of doubles that are the network units to encode
     *         the given NetworkInput into.
     * @see    UnitEncoder.getDimensionality()
     * @see    UnitEncoder.getOffset()
     * @see    NetworkInput
     */
    public abstract void encode(
        NetworkInput        input,              // Input to encode.
        double[]            units);             // Units to encode into.

    /**
     * setOffset
     *
     * This method takes a new integer offset, which is the new integer index
     * that this UnitEncoder is to start encoding at. It changes the offset to
     * the given value as long as it is greater than or equal to 0. If it is
     * not, then the offset will remain unchanged.
     *
     * @param  newOffset The new offset for this UnitEncoder to start encoding
     *         at. It must be at least 0 or the offset will remain unchanged.
     */
    public void setOffset(
        int                 newOffset)          // The new offset.
    {
        if ( newOffset >= 0 )
            offset = newOffset;
        // else - New offset out of range.
    }

    /**
     * getOffset
     *
     * This method just returns the current offset of the UnitEncoder, which
     * is the index in a given array of units that the encoder will start its
     * encoding at.
     *
     * @return The (non-negative) integer index that the encoder starts
     *         encoding at.
     * @see    UnitEncoder.encode(NetworkInput, double[])
     */
    public int getOffset()
    {
        return offset;
    }
}