source: src/main/java/weka/classifiers/functions/neural/NeuralConnection.java @ 16

/*
 *    This program is free software; you can redistribute it and/or modify
 *    it under the terms of the GNU General Public License as published by
 *    the Free Software Foundation; either version 2 of the License, or
 *    (at your option) any later version.
 *
 *    This program is distributed in the hope that it will be useful,
 *    but WITHOUT ANY WARRANTY; without even the implied warranty of
 *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *    GNU General Public License for more details.
 *
 *    You should have received a copy of the GNU General Public License
 *    along with this program; if not, write to the Free Software
 *    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */

/*
 *    NeuralConnection.java
 *    Copyright (C) 2000 University of Waikato, Hamilton, New Zealand
 */

package weka.classifiers.functions.neural;

import weka.core.RevisionHandler;

import java.awt.Color;
import java.awt.Graphics;
import java.io.Serializable;

/** 
 * Abstract unit in a NeuralNetwork.
 *
 * @author Malcolm Ware (mfw4@cs.waikato.ac.nz)
 * @version $Revision: 5402 $
 */
public abstract class NeuralConnection
  implements Serializable, RevisionHandler {

  /** for serialization */
  private static final long serialVersionUID = -286208828571059163L;

  //bitwise flags for the types of unit.

  /** This unit is not connected to any others. */
  public static final int UNCONNECTED = 0;
  
  /** This unit is a pure input unit. */
  public static final int PURE_INPUT = 1;
  
  /** This unit is a pure output unit. */
  public static final int PURE_OUTPUT = 2;
  
  /** This unit is an input unit. */
  public static final int INPUT = 4;
  
  /** This unit is an output unit. */
  public static final int OUTPUT = 8;
  
  /** This flag is set once the unit has a connection. */
  public static final int CONNECTED = 16;



  /////The difference between pure and not is that pure is used to feed 
  /////the neural network the attribute values and the errors on the outputs
  /////Beyond that they do no calculations, and have certain restrictions
  /////on the connections they can make.



  /** The list of inputs to this unit. */
  protected NeuralConnection[] m_inputList;

  /** The list of outputs from this unit. */
  protected NeuralConnection[] m_outputList;

  /** The numbering for the connections at the other end of the input lines. */
  protected int[] m_inputNums;
  
  /** The numbering for the connections at the other end of the out lines. */
  protected int[] m_outputNums;

  /** The number of inputs. */
  protected int m_numInputs;

  /** The number of outputs. */
  protected int m_numOutputs;

  /** The output value for this unit, NaN if not calculated. */
  protected double m_unitValue;

  /** The error value for this unit, NaN if not calculated. */
  protected double m_unitError;
  
  /** True if the weights have already been updated. */
  protected boolean m_weightsUpdated;
  
  /** The string that uniquely (provided naming is done properly) identifies
   * this unit. */
  protected String m_id;

  /** The type of unit this is. */
  protected int m_type;

  /** The x coord of this unit purely for displaying purposes. */
  protected double m_x;
  
  /** The y coord of this unit purely for displaying purposes. */
  protected double m_y;
  

  
  
  /**
   * Constructs The unit with the basic connection information prepared for
   * use. 
   * 
   * @param id the unique id of the unit
   */
  public NeuralConnection(String id) {
    
    m_id = id;
    m_inputList = new NeuralConnection[0];
    m_outputList = new NeuralConnection[0];
    m_inputNums = new int[0];
    m_outputNums = new int[0];

    m_numInputs = 0;
    m_numOutputs = 0;

    m_unitValue = Double.NaN;
    m_unitError = Double.NaN;

    m_weightsUpdated = false;
    m_x = 0;
    m_y = 0;
    m_type = UNCONNECTED;
  }
  
  
  /**
   * @return The identity string of this unit.
   */
  public String getId() {
    return m_id;
  }

  /**
   * @return The type of this unit.
   */
  public int getType() {
    return m_type;
  }

  /**
   * @param t The new type of this unit.
   */
  public void setType(int t) {
    m_type = t;
  }

  /**
   * Call this to reset the unit for another run.
   * It is expected by that this unit will call the reset functions of all 
   * input units to it. It is also expected that this will not be done
   * if the unit has already been reset (or atleast appears to be).
   */
  public abstract void reset();

  /**
   * Call this to get the output value of this unit. 
   * @param calculate True if the value should be calculated if it hasn't been
   * already.
   * @return The output value, or NaN, if the value has not been calculated.
   */
  public abstract double outputValue(boolean calculate);

  /**
   * Call this to get the error value of this unit.
   * @param calculate True if the value should be calculated if it hasn't been
   * already.
   * @return The error value, or NaN, if the value has not been calculated.
   */
  public abstract double errorValue(boolean calculate);
  
  /**
   * Call this to have the connection save the current
   * weights.
   */
  public abstract void saveWeights();
  
  /**
   * Call this to have the connection restore from the saved
   * weights.
   */
  public abstract void restoreWeights();

  /**
   * Call this to get the weight value on a particular connection.
   * @param n The connection number to get the weight for, -1 if The threshold
   * weight should be returned.
   * @return This function will default to return 1. If overridden, it should
   * return the value for the specified connection or if -1 then it should 
   * return the threshold value. If no value exists for the specified 
   * connection, NaN will be returned.
   */
  public double weightValue(int n) {
    return 1;
  }

  /**
   * Call this function to update the weight values at this unit.
   * After the weights have been updated at this unit, All the
   * input connections will then be called from this to have their
   * weights updated.
   * @param l The learning Rate to use.
   * @param m The momentum to use.
   */
  public void updateWeights(double l, double m) {
    
    //the action the subclasses should perform is upto them 
    //but if they coverride they should make a call to this to
    //call the method for all their inputs.
    
    if (!m_weightsUpdated) {
      for (int noa = 0; noa < m_numInputs; noa++) {
        m_inputList[noa].updateWeights(l, m);
      }
      m_weightsUpdated = true;
    }
    
  }

  /**
   * Use this to get easy access to the inputs.
   * It is not advised to change the entries in this list
   * (use the connecting and disconnecting functions to do that)
   * @return The inputs list.
   */
  public NeuralConnection[] getInputs() {
    return m_inputList;
  }

  /**
   * Use this to get easy access to the outputs.
   * It is not advised to change the entries in this list
   * (use the connecting and disconnecting functions to do that)
   * @return The outputs list.
   */
  public NeuralConnection[] getOutputs() {
    return m_outputList;
  }

  /**
   * Use this to get easy access to the input numbers.
   * It is not advised to change the entries in this list
   * (use the connecting and disconnecting functions to do that)
   * @return The input nums list.
   */
  public int[] getInputNums() {
    return m_inputNums;
  }

  /**
   * Use this to get easy access to the output numbers.
   * It is not advised to change the entries in this list
   * (use the connecting and disconnecting functions to do that)
   * @return The outputs list.
   */
  public int[] getOutputNums() {
    return m_outputNums;
  }

  /**
   * @return the x coord.
   */
  public double getX() {
    return m_x;
  }
  
  /**
   * @return the y coord.
   */
  public double getY() {
    return m_y;
  }
  
  /**
   * @param x The new value for it's x pos.
   */
  public void setX(double x) {
    m_x = x;
  }
  
  /**
   * @param y The new value for it's y pos.
   */
  public void setY(double y) {
    m_y = y;
  }
  
  
  /**
   * Call this function to determine if the point at x,y is on the unit.
   * @param g The graphics context for font size info.
   * @param x The x coord.
   * @param y The y coord.
   * @param w The width of the display.
   * @param h The height of the display.
   * @return True if the point is on the unit, false otherwise.
   */
  public boolean onUnit(Graphics g, int x, int y, int w, int h) {

    int m = (int)(m_x * w);
    int c = (int)(m_y * h);
    if (x > m + 10 || x < m - 10 || y > c + 10 || y < c - 10) {
      return false;
    }
    return true;

  }
  
  /**
   * Call this function to draw the node.
   * @param g The graphics context.
   * @param w The width of the drawing area.
   * @param h The height of the drawing area.
   */
  public void drawNode(Graphics g, int w, int h) {
    
    if ((m_type & OUTPUT) == OUTPUT) {
      g.setColor(Color.orange);
    }
    else {
      g.setColor(Color.red);
    }
    g.fillOval((int)(m_x * w) - 9, (int)(m_y * h) - 9, 19, 19);
    g.setColor(Color.gray);
    g.fillOval((int)(m_x * w) - 5, (int)(m_y * h) - 5, 11, 11);
  }

  /**
   * Call this function to draw the node highlighted.
   * @param g The graphics context.
   * @param w The width of the drawing area.
   * @param h The height of the drawing area.
   */
  public void drawHighlight(Graphics g, int w, int h) {
   
    drawNode(g, w, h);
    g.setColor(Color.yellow);
    g.fillOval((int)(m_x * w) - 5, (int)(m_y * h) - 5, 11, 11);
  }

  /** 
   * Call this function to draw the nodes input connections.
   * @param g The graphics context.
   * @param w The width of the drawing area.
   * @param h The height of the drawing area.
   */
  public void drawInputLines(Graphics g, int w, int h) {

    g.setColor(Color.black);
    
    int px = (int)(m_x * w);
    int py = (int)(m_y * h);
    for (int noa = 0; noa < m_numInputs; noa++) {
      g.drawLine((int)(m_inputList[noa].getX() * w)
                 , (int)(m_inputList[noa].getY() * h)
                 , px, py);
    }
  }

  /**
   * Call this function to draw the nodes output connections.
   * @param g The graphics context.
   * @param w The width of the drawing area.
   * @param h The height of the drawing area.
   */
  public void drawOutputLines(Graphics g, int w, int h) {
    
    g.setColor(Color.black);
    
    int px = (int)(m_x * w);
    int py = (int)(m_y * h);
    for (int noa = 0; noa < m_numOutputs; noa++) {
      g.drawLine(px, py
                 , (int)(m_outputList[noa].getX() * w)
                 , (int)(m_outputList[noa].getY() * h));
    }
  }


  /**
   * This will connect the specified unit to be an input to this unit.
   * @param i The unit.
   * @param n It's connection number for this connection.
   * @return True if the connection was made, false otherwise.
   */
  protected boolean connectInput(NeuralConnection i, int n) {
    
    for (int noa = 0; noa < m_numInputs; noa++) {
      if (i == m_inputList[noa]) {
        return false;
      }
    }
    if (m_numInputs >= m_inputList.length) {
      //then allocate more space to it.
      allocateInputs();
    }
    m_inputList[m_numInputs] = i;
    m_inputNums[m_numInputs] = n;
    m_numInputs++;
    return true;
  }
  
  /**
   * This will allocate more space for input connection information
   * if the arrays for this have been filled up.
   */
  protected void allocateInputs() {
    
    NeuralConnection[] temp1 = new NeuralConnection[m_inputList.length + 15];
    int[] temp2 = new int[m_inputNums.length + 15];

    for (int noa = 0; noa < m_numInputs; noa++) {
      temp1[noa] = m_inputList[noa];
      temp2[noa] = m_inputNums[noa];
    }
    m_inputList = temp1;
    m_inputNums = temp2;
  }

  /** 
   * This will connect the specified unit to be an output to this unit.
   * @param o The unit.
   * @param n It's connection number for this connection.
   * @return True if the connection was made, false otherwise.
   */
  protected boolean connectOutput(NeuralConnection o, int n) {
    
    for (int noa = 0; noa < m_numOutputs; noa++) {
      if (o == m_outputList[noa]) {
        return false;
      }
    }
    if (m_numOutputs >= m_outputList.length) {
      //then allocate more space to it.
      allocateOutputs();
    }
    m_outputList[m_numOutputs] = o;
    m_outputNums[m_numOutputs] = n;
    m_numOutputs++;
    return true;
  }
  
  /**
   * Allocates more space for output connection information
   * if the arrays have been filled up.
   */
  protected void allocateOutputs() {
    
    NeuralConnection[] temp1 
      = new NeuralConnection[m_outputList.length + 15];
    
    int[] temp2 = new int[m_outputNums.length + 15];
    
    for (int noa = 0; noa < m_numOutputs; noa++) {
      temp1[noa] = m_outputList[noa];
      temp2[noa] = m_outputNums[noa];
    }
    m_outputList = temp1;
    m_outputNums = temp2;
  }
  
  /**
   * This will disconnect the input with the specific connection number
   * From this node (only on this end however).
   * @param i The unit to disconnect.
   * @param n The connection number at the other end, -1 if all the connections
   * to this unit should be severed.
   * @return True if the connection was removed, false if the connection was 
   * not found.
   */
  protected boolean disconnectInput(NeuralConnection i, int n) {
    
    int loc = -1;
    boolean removed = false;
    do {
      loc = -1;
      for (int noa = 0; noa < m_numInputs; noa++) {
        if (i == m_inputList[noa] && (n == -1 || n == m_inputNums[noa])) {
          loc = noa;
          break;
        }
      }
      
      if (loc >= 0) {
        for (int noa = loc+1; noa < m_numInputs; noa++) {
          m_inputList[noa-1] = m_inputList[noa];
          m_inputNums[noa-1] = m_inputNums[noa];
          //set the other end to have the right connection number.
          m_inputList[noa-1].changeOutputNum(m_inputNums[noa-1], noa-1);
        }
        m_numInputs--;
        removed = true;
      }
    } while (n == -1 && loc != -1);

    return removed;
  }

  /**
   * This function will remove all the inputs to this unit.
   * In doing so it will also terminate the connections at the other end.
   */
  public void removeAllInputs() {
    
    for (int noa = 0; noa < m_numInputs; noa++) {
      //this command will simply remove any connections this node has
      //with the other in 1 go, rather than seperately.
      m_inputList[noa].disconnectOutput(this, -1);
    }
    
    //now reset the inputs.
    m_inputList = new NeuralConnection[0];
    setType(getType() & (~INPUT));
    if (getNumOutputs() == 0) {
      setType(getType() & (~CONNECTED));
    }
    m_inputNums = new int[0];
    m_numInputs = 0;
    
  }

 

  /**
   * Changes the connection value information for one of the connections.
   * @param n The connection number to change.
   * @param v The value to change it to.
   */
  protected void changeInputNum(int n, int v) {
    
    if (n >= m_numInputs || n < 0) {
      return;
    }

    m_inputNums[n] = v;
  }
  
  /**
   * This will disconnect the output with the specific connection number
   * From this node (only on this end however).
   * @param o The unit to disconnect.
   * @param n The connection number at the other end, -1 if all the connections
   * to this unit should be severed.
   * @return True if the connection was removed, false if the connection was
   * not found.
   */  
  protected boolean disconnectOutput(NeuralConnection o, int n) {
    
    int loc = -1;
    boolean removed = false;
    do {
      loc = -1;
      for (int noa = 0; noa < m_numOutputs; noa++) {
        if (o == m_outputList[noa] && (n == -1 || n == m_outputNums[noa])) {
          loc =noa;
          break;
        }
      }
      
      if (loc >= 0) {
        for (int noa = loc+1; noa < m_numOutputs; noa++) {
          m_outputList[noa-1] = m_outputList[noa];
          m_outputNums[noa-1] = m_outputNums[noa];

          //set the other end to have the right connection number
          m_outputList[noa-1].changeInputNum(m_outputNums[noa-1], noa-1);
        }
        m_numOutputs--;
        removed = true;
      }
    } while (n == -1 && loc != -1);
    
    return removed;
  }

  /**
   * This function will remove all outputs to this unit.
   * In doing so it will also terminate the connections at the other end.
   */
  public void removeAllOutputs() {
    
    for (int noa = 0; noa < m_numOutputs; noa++) {
      //this command will simply remove any connections this node has
      //with the other in 1 go, rather than seperately.
      m_outputList[noa].disconnectInput(this, -1);
    }
    
    //now reset the inputs.
    m_outputList = new NeuralConnection[0];
    m_outputNums = new int[0];
    setType(getType() & (~OUTPUT));
    if (getNumInputs() == 0) {
      setType(getType() & (~CONNECTED));
    }
    m_numOutputs = 0;
    
  }

  /**
   * Changes the connection value information for one of the connections.
   * @param n The connection number to change.
   * @param v The value to change it to.
   */
  protected void changeOutputNum(int n, int v) {
    
    if (n >= m_numOutputs || n < 0) {
      return;
    }

    m_outputNums[n] = v;
  }
  
  /**
   * @return The number of input connections.
   */
  public int getNumInputs() {
    return m_numInputs;
  }

  /**
   * @return The number of output connections.
   */
  public int getNumOutputs() {
    return m_numOutputs;
  }


  /**
   * Connects two units together.
   * @param s The source unit.
   * @param t The target unit.
   * @return True if the units were connected, false otherwise.
   */
  public static boolean connect(NeuralConnection s, NeuralConnection t) {
    
    if (s == null || t == null) {
      return false;
    }
    //this ensures that there is no existing connection between these 
    //two units already. This will also cause the current weight there to be 
    //lost
 
    disconnect(s, t);
    if (s == t) {
      return false;
    }
    if ((t.getType() & PURE_INPUT) == PURE_INPUT) {
      return false;   //target is an input node.
    }
    if ((s.getType() & PURE_OUTPUT) == PURE_OUTPUT) {
      return false;   //source is an output node
    }
    if ((s.getType() & PURE_INPUT) == PURE_INPUT 
        && (t.getType() & PURE_OUTPUT) == PURE_OUTPUT) {      
      return false;   //there is no actual working node in use
    }
    if ((t.getType() & PURE_OUTPUT) == PURE_OUTPUT && t.getNumInputs() > 0) {
      return false; //more than 1 node is trying to feed a particular output
    }

    if ((t.getType() & PURE_OUTPUT) == PURE_OUTPUT &&
        (s.getType() & OUTPUT) == OUTPUT) {
      return false; //an output node already feeding out a final answer
    }

    if (!s.connectOutput(t, t.getNumInputs())) {
      return false;
    }
    if (!t.connectInput(s, s.getNumOutputs() - 1)) {
      
      s.disconnectOutput(t, t.getNumInputs());
      return false;

    }

    //now ammend the type.
    if ((s.getType() & PURE_INPUT) == PURE_INPUT) {
      t.setType(t.getType() | INPUT);
    }
    else if ((t.getType() & PURE_OUTPUT) == PURE_OUTPUT) {
      s.setType(s.getType() | OUTPUT);
    }
    t.setType(t.getType() | CONNECTED);
    s.setType(s.getType() | CONNECTED);
    return true;
  }

  /**
   * Disconnects two units.
   * @param s The source unit.
   * @param t The target unit.
   * @return True if the units were disconnected, false if they weren't
   * (probably due to there being no connection).
   */
  public static boolean disconnect(NeuralConnection s, NeuralConnection t) {
    
    if (s == null || t == null) {
      return false;
    }

    boolean stat1 = s.disconnectOutput(t, -1);
    boolean stat2 = t.disconnectInput(s, -1);
    if (stat1 && stat2) {
      if ((s.getType() & PURE_INPUT) == PURE_INPUT) {
        t.setType(t.getType() & (~INPUT));
      }
      else if ((t.getType() & (PURE_OUTPUT)) == PURE_OUTPUT) {
        s.setType(s.getType() & (~OUTPUT));
      }
      if (s.getNumInputs() == 0 && s.getNumOutputs() == 0) {
        s.setType(s.getType() & (~CONNECTED));
      }
      if (t.getNumInputs() == 0 && t.getNumOutputs() == 0) {
        t.setType(t.getType() & (~CONNECTED));
      }
    }
    return stat1 && stat2;
  }
}