/*  SCCS - @(#)NslModule.java	1.2 - 02/19/99 - 20:45:53 */

// Copyright: Copyright (c) 1997 University of Southern California Brain Project.
// Copyright: This software may be freely copied provided the toplevel
// Copyright: COPYRIGHT file is included with each such copy.
// Copyright: Email nsl@java.usc.edu.

/*
 * $Log: NslModule.java,v $
 * Revision 1.7  1998/01/30 20:02:31  erhan
 * ver 5
 *
 * Revision 1.6  1997/11/06 03:15:24  erhan
 * nsl3.0.b
 *
 * Revision 1.5  1997/07/30 21:19:21  erhan
 * nsl3.0
 *
 * Revision 1.4  1997/06/17 19:07:05  erhan
 * noneed abstract methods:modified
 *
 * Revision 1.3  1997/06/16 22:21:50  erhan
 * goerges changes
 *
 * Revision 1.1.1.1  1997/03/12 22:52:19  nsl
 * new dir structure
 *
 * Revision 1.1.1.1  1997/02/08 00:40:39  nsl
 *  Imported the Source directory
 *
*/
//
// NslModule.java
//
//////////////////////////////////////////////////////////////////////


//////////////////////////////////////////////////////////////////////
// Documentation about documentation
//
// command      explanation
// -------      ------------
// @param       parameter list
// @return      return value
// @throw       exception that could be thrown in run-time
// @see         see also "class"#"method"
// <tt>...</tt> prints out text anchored in typewriter font
//              for parameter, method or class names
// <b>,,.</b>   prints out text anchored in bold type font
//              for warning messages
// <i>...</i>   prints out test anchored in italic type font
//              for concepts in the program
// <br>         new line
//////////////////////////////////////////////////////////////////////

/**
* A basic module.
          |###########|
   ----->o| NslModule |o---->
          |###########|
         ^             ^
         |             |
        Inport       Outport
*/

package nslj.src.lang;

import tcl.lang.*; 

import nslj.src.system.NslSystem;
import nslj.src.math.NslDiff;

import nslj.src.display.*;  // ERH


import nslj.src.nsls.struct.*;

import java.lang.*;
import java.util.Vector;
import java.util.Enumeration;

abstract public  class NslModule implements Runnable{
private static boolean use_parameter_passing = true;

NslDisplayFrame displayframe=null;
 


// testing purposes
public static int num = -1;
public static int num2 = -1;
public static int index = -1;



  static protected NslSystem system;
// static NslScheduler scheduler;

  String name; // name label of the module

//  protected NslDouble0 run_step_size;
//  protected NslDouble0 integration_time_step;

  protected double run_step_size; // delta t, dt
  protected double train_step_size;
  
  boolean run_enable_fg; // this module executes when it is true,
                         // idle otherwise
                         
  boolean train_enable_fg; // this module executes when it is true,
                         // idle otherwise

  protected double integration_time_step; // integration step size, tm
  protected NslDiff diff_method; // differentiation method

  protected boolean doubleBuffering; // Double buffering default value
  
  Vector missing_links; // temporary vector to store the links
                        // not connected in the instantiation stage
                        // for later reconstruction


  NslModule module_parent; // parent module
  Vector module_children;  // list of modules inside this module
  Vector inports;  // inport list
  Vector outports;  // outport list
  Vector environ_vars; // environment variables
  Vector visible_vars;
  
  //changes from the previous file.
  
  Vector accessible_vars;
  Vector globals;

/***********************/

  public String ID_str;
  public String order_str;
  public int ID=0;
  public int child_c =0;
  public boolean postorder;
  static final int MAXDIGIT=3; // max child=10^MAXDIGIT 
  /** 
   * Bare Constructor. Setup internal variables and lists.
   */

  public NslModule(){
    module_children = new Vector();
    // assume at least one port, increment one at a time.
    inports = new Vector(1, 1);
    outports = new Vector(1, 1);
    environ_vars = new Vector(1, 1);
    accessible_vars = new Vector(1, 1);
    visible_vars = new Vector(1, 1); //98/9/16 ERH


    //run_step_size = new NslDouble0("run_step_size", NslNumeric.Env, this);
    // check if it is root module. If so, set to a default value
    //if (run_step_size.get() == 0.0)
    //        run_step_size.set(0.1);

    run_enable_fg = true;
    train_enable_fg = true;
    //integration_time_step= new NslDouble0("integration_time_step", NslNumeric.Env, this); // tm = 1.0
    //if (integration_time_step.get() == 0.0)
    //    integration_time_step.set(1.0);
    // default value
    run_step_size = system.getRunStepSize();
    train_step_size = system.getTrainStepSize();
    integration_time_step = 1.0;
    

    diff_method = system.getDiffMethod();
    
    doubleBuffering = system.getBuffering();
    
    ID=0;
    ID_str=makestr(ID);
    order_str =ID_str;
    child_c=0;
    // postorder=true; 98/9/11 aa changed
    // preorder - parent before children -- default
    // postorder - parent after children
  }


  /**
   * Default constructor. Call bare constructor to setup internal
   variables and lists. Attach itself to parent  module. It calls
   <tt>makeinst</tt> for child modules creation.
   * @param label - the name of the module
   * @param parent - parent module, null if this is the top level
   */
  public NslModule(String label, NslModule parent) {
    this();
    this.name=label;   
        
    module_parent = parent;  
    if (parent != null) {
        run_step_size   = parent.getRunStepSize();
        train_step_size = parent.getTrainStepSize();
        integration_time_step = parent.getIntegrationTimeStep();
      }

    if(use_parameter_passing) 
    	if (parent != null) {
    		//System.out.println("Adding Module");
    		parent.addModule(this);
    	}
     
     reflectModule();     
   }


  public NslModule(String label, NslModule parent, String options) 
 {
  this(label,parent);
  System.err.println("Error in NslModule: option parsing not ready. options:"+options);
 }


  private void reflectModule() {
  	try {
		String objectName = ReflectObject.newInstance(Executive.interp, this.getClass(), this).toString();
        	Executive.interp.eval("set "+this.getName()+" "+objectName);
        } catch (TclException e) {
        }
  }


  /**
   * Default parameter setting routine. Should be called by
   all <tt>setParams()</tt> methods to setup the link to parent
   module/worksplace to get parent information. It calls <tt>
   makeinst</tt> for child modules creation.
   * @param label - the name of the module
   * @param parent - parent module, null if this is the top level
   */
  public void setParent(String label, NslModule parent) {
    this.name=label;
    module_parent = parent;
    parent.addModule(this);
    //System.out.println(
    //"Debug: NslModule:setParent: " + label + " "+ parent.getName() + " "+ parent);
  }
 

  public void setParams(String label, NslModule parent) {
    this.name=label;
    //System.out.println(" Params SET " + label);
    module_parent = parent;  
    if (parent != null) {
        run_step_size = parent.getRunStepSize();
        train_step_size = parent.getTrainStepSize();
        integration_time_step = parent.getIntegrationTimeStep();
    }

    // call makeinst to create children, specified by the user
    //     makeinst();

    if (parent != null){
      //System.out.println("Adding module from SETPARMS "+label);
      parent.addModule(this);
    }
  }

  /**
   * define the NslSystem to use
   * @param sys - NslSystem to use
   */
  public static void setSystem(NslSystem sys) {
    system = sys;
  }

  public static NslSystem getSystem() {
    return system;
  }



  /**
   * define the scheduler to use
   * @param schduler
   *
  public static void setScheduler(NslSchduler sch) {
    scheduler = sch;
  }
  */
  public Vector getModuleChildrenVector(){
    // list of modules inside this module
    return module_children;
  }

 public  Vector getInportsVector() {
    return inports;  // inport list
  }

  public Vector getOutportsVector() {
    return outports;  // outport list
  }

  public Vector getEnvironVarsVector() {
    return environ_vars; // environment variables
  }

  private String makestr(int a)
  {String s;
   s="";
   for (int i=0;i<MAXDIGIT;i++)  {s=(a%10)+s; a/=10;}
   return s;
  } 
  public void setID(NslModule parent,int id) {
   ID=id;
   ID_str=parent.ID_str+" "+makestr(id);
   order_str = ID_str;
   }

  public int    getID()        { return(ID); } 
  public String getID_str()    { return(ID_str); } 
  public String getorder_str() { return(order_str); } 
 
  /**
   * Add child module into this module and into the scheduler
   * @param child - child NslModule
   * @throw NullPointerException if the module supplied is null
   */
   public void addModule(NslModule child) {
    
  
       //System.out.println("#debug: NslModule: Adding Module "+child.getName()+" to "+getName());
   	 if (child == null)  throw new NullPointerException();

         module_children.addElement(child);
         
	 child_c++;                  // Having one more baby
	 child.setID(this,child_c);  // give new baby a name	 

	 /* */
	 if ((system.schedulerMethod.equals("pre")) ||
	     (system.schedulerMethod.equals("mixed"))) {
		//preorder - parent goes before childeren
	        //TODO: mixed not implemented yet
	 }
	 if (system.schedulerMethod.equals("post")) {
		//postorder - parent goes after childeren
		//TODO: change this so we are not dependent on string lengths
		order_str=child.getorder_str()+"$"; 
	 }
         system.addModule(child);  
       /*System.out.println("#debug: NslModule: add "+child.getName()+"["+
                             child.getorder_str()+"]  to Parent "+
			     getName()+"["+order_str+"]  (pre:"+ID_str+")");
       */
   }

  /**
   * Get a child module with name <tt>name</tt>
   * @param name name of target child module
   * @return children module, null if not found
   */
   public NslModule getModule(String name) {
    Enumeration E = module_children.elements();
    NslModule child = null;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	child = (NslModule)E.nextElement();
	if (name.equals(child.getName()))
	  return child;
      }
    }
    return null;
  }

   public boolean hasChild(String s) {
    Enumeration E = module_children.elements();
    NslModule child = null;
 
    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
        child = (NslModule)E.nextElement();
        //System.out.println("Debug: NslModule: Adding Module "+child.getName());
        if(s.equals(child.getName()))
          return(true);
      }
    }
    return(false);
  }
   public void printChild() {
    Enumeration E = module_children.elements();
    NslModule child = null;
 
    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
        child = (NslModule)E.nextElement();
        // System.out.println("Debug: NslModule: Adding Module "+child.getName());
      }
    }
  }


  /**
   * Create an outport which makes reference to an Object
   * @param name name of this outport
   * @param n reference to a single object
   * @throws NullPointerException if n is not defined
   */
  // initialize outport of this object
  // The object itself should be fully initialized
  public NslNumeric out(String name, NslNumeric n) {
    if (n == null) {
      throw new NullPointerException();
    }
//    System.out.println("Debug: NslModule: ADDING TO OUTPORT OF "+getName()+" element "+name);
    outports.addElement(new NslOutport(name, n));
    return n;
  }

  /**
   * Create an outport which makes reference to a NslNumeric
   * @param name name of this outport
   * @param n reference to a NslNumeric, can be NslNumeric0, NslNumeric1 or NslNumeric2
   * @throws NullPointerException if n is not defined
   */
  // initialize outport of this object
  // The object itself should be fully initialized
  public NslNumeric out(NslNumeric n) {
    if (n == null) {
      throw new NullPointerException();
    }
//    System.out.println("ADDING TO OUTPORT OF "+getName()+" element ");
    outports.addElement(new NslOutport(n));
    return n;
  }

  /**
   * Add an Outport to the current outport list
   * @param outport the outport to be added
   * @throws NullPointerException if outport is null
   */
  public void out(NslOutport outport) {
    if (outport == null) {
      throw new NullPointerException();
    }

//    System.out.println("ADDING TO OUTPORT OF "+getName()+" with no-name element.");
    outports.addElement(outport);
  }

  /**
   * Create an inport which makes reference to an Object
   * @param name name of this intport
   * @param n reference to a NslNumeric, can be NslNumeric0, NslNumeric1 or NslNumeric2
   * @throws NullPointerException if n is null
   */
  // initialize inport of this object
  public NslNumeric in(String name, NslNumeric n) {
    if (n == null) {
      throw new NullPointerException();
    }
    inports.addElement(new NslInport(name, n));
    return n;
  }
  /**
   * Create an inport which makes reference to a Numeric object
   * @param name name of this intport
   * @param n reference to a NslNumeric, 
   can be NslNumeric0, NslNumeric1 or NslNumeric2
   * @throws NullPointerException if n is null
   */
  // initialize inport of this object
  public NslNumeric in(NslNumeric n) {
    if (n == null) {
      throw new NullPointerException();
    }
    inports.addElement(new NslInport(n));
    return n;
  }

  /**
   * Add an inport to the current inport list
   * @param inport the inport to be added
   * @throws NullPointerException if inport is null
   */
  public void in(NslInport inport) {
    if (inport == null) {
      throw new NullPointerException();
    }
    inports.addElement(inport);
  }

// <tt>...</tt> below prints typewriter font
  /**
   * Get an inport with name <tt>name</tt>
   * @param name name of target inport
   * @return inport, null if not found
   */

   NslInport getInport(String name) {
    Enumeration E = inports.elements();
    NslInport port;

    if (E.hasMoreElements()) {
    while(E.hasMoreElements()) {
      port=(NslInport)E.nextElement();
      if(name.equals(port.getName()))
	    return port;
      }
    }
    return null;
  }

  /**
   * Get an outport with name <tt>name</tt>
   * @param name name of target outport
   * @return outport, null if not found
   */

   NslOutport getOutport(String name) {
    Enumeration E = outports.elements();
    NslOutport port;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	    port=(NslOutport)E.nextElement();
    	if(name.equals(port.getName()))
	      return port;
      }
    }
    return null;
  }

   NslNumeric getVisible(String name) {

/* change*/

    if (visible_vars==null) return null;
/***/

    Enumeration E = visible_vars.elements();
    NslNumeric vis;

      while(E.hasMoreElements()) {
	    vis=(NslNumeric)E.nextElement();
    	if(name.equals(vis.getName())) return vis;
	  }
    return null;
  }

  /**
   * Get a port with name <tt>name</tt>
   * @param name name of target port
   * @return port, null if not found
   */
   public NslPort getPort(String name) {
    NslPort  port = (NslPort)getOutport(name);
    if (port == null)
      port = (NslPort)getInport(name);
    return port;
  }


  /**
   * Add an environment variable  to the current environment list
   * @param env environment variable to be added
   * @throws NullPointerException if outport is null
   */
  public boolean env(NslEnv env) {
    if (env==null)
      throw new NullPointerException();
    environ_vars.addElement(env);
    return env.isDataSet();
  }


  /**
   * Add a NslNumeric object as an environment variable 
   to the current environment list. This method also searches
   the module tree to get the environment variable reference. 
   If there does not exist any variable with the same name
   it returns null pointer.
   * @param name name of the environment variable
   * @param n NslNumeric object that stores the value
   * @throws NullPointerException if outport is null, or evnironment of the same
   name cannot be found in the parent modules.
   */
  // todo: communicate with the system if the parent_env is not found
  public NslNumeric env(String name, NslNumeric n) {
    NslEnv env;
    NslEnv parent_env;


//System.out.println("OUTPUTTING !!! "+ name);
    if (n == null) {
      throw new NullPointerException();
    }
    parent_env = getEnv(name);   
    if(parent_env == null) {
      System.err.println("Error in NslModule: Cannot find environment variable '"+name+
			 "' from the parent modules of '" +this.name+"'");
      throw new NullPointerException();
    }
    env = new NslEnv(name, n, parent_env);
    environ_vars.addElement(env);
    return n; //env.isDataSet();
  }
/* change*/
public NslNumeric nslDummy(NslNumeric n) { return n;}


public NslNumeric nslHier(NslNumeric n) {
   NslNumeric nn;
   return n; //================
/*
   nn=common(n);
   System.out.println("Debug: NslModule: nslHier returning:"+n);
   return nn;

   //return common(n);
*/
  }

/***************/

  public NslNumeric nslHier(String name, NslNumeric n) 
{ return common(name,n);}

  public NslNumeric common(NslNumeric n) {
    return (common(n.getName(),n));
  }

  public NslNumeric common(String name, NslNumeric n) {
    NslEnv env;
    NslEnv parent_env;

   return n; //================
/*
//System.out.println("OUTPUTTING !!! "+ name);
    if (n == null) {
      throw new NullPointerException();
    }
    parent_env = getEnv(name);   
    if(parent_env == null) {
//    System.out.println("Debug: NslModule: Creating nslHier variable ["+name+
			 "] within scope of " +this.name);
      return (envt(name,n));
    }
//    System.out.println("Debug: NslModule: parent_env not null!");
    env = new NslEnv(name, n, parent_env);
//    environ_vars.addElement(env);
//      System.out.println("Debug: NslModule: Referencing nslHier variable ["+name+
//			 "] defined in " +this.name);
    return n; //env.isDataSet();
*/
  }

public void nslPutInGraphicsList(NslNumeric n) {
NslOutport fake_port;
fake_port=new NslOutport(n.getName(),n);
  //System.out.println("Debug:NslModule:nslPutInGrahicsList: "+fake_port.getName());
fake_port.owner=this;
this.out(fake_port);
}

public void nslPutInGraphicsList(NslNumeric n1,NslNumeric n2) {
nslPutInGraphicsList(n1);
nslPutInGraphicsList(n2);
}
public void nslPutInGraphicsList(NslNumeric n1,NslNumeric n2,NslNumeric n3) {
nslPutInGraphicsList(n1);
nslPutInGraphicsList(n2);
nslPutInGraphicsList(n3);
}
public void nslPutInGraphicsList(NslNumeric n1,NslNumeric n2,NslNumeric n3,NslNumeric n4) {
nslPutInGraphicsList(n1);
nslPutInGraphicsList(n2);
nslPutInGraphicsList(n3);
nslPutInGraphicsList(n4);
}

public void nslPutInGraphicsList(NslNumeric n1,NslNumeric n2,NslNumeric n3,NslNumeric n4,NslNumeric n5) {
nslPutInGraphicsList(n1);
nslPutInGraphicsList(n2);
nslPutInGraphicsList(n3);
nslPutInGraphicsList(n4);
nslPutInGraphicsList(n5);
}

/*changed |>*/

  /* TODO Remove NslVisible */
  public NslNumeric NslVisible(NslNumeric n) {
    return (common(n.getName(),n));
  }

  public NslNumeric NslVisible(String name, NslNumeric n) {
    if (n == null) {
      throw new NullPointerException();
    }
      // System.out.println("Debug:NslModule:NslVisible: variable ["+name+"] within scope of " +this.name);
      visible_vars.addElement(n);
      return (n);
}

public NslNumeric enableAccess(NslNumeric n) {

    if (n == null) {
      throw new NullPointerException();
    }
      // System.out.println("Debug: NslModule: Making variable child accessiblename: ["+n.getName()+"] scope : " +this.name);
//      NslEnv env = new NslEnv(n.getName(), n, null);  //aa 98/9/15
//      environ_vars.addElement(env);	//aa

      accessible_vars.addElement(NslVisible(n.getName(),n));  // ERH 98/9/16
      return (n);
}

public NslNumeric nslValParent(String name) {
	return(nslRefParent(name)); 
}
public NslNumeric nslRefParent(String name) {
    //Enumeration E = environ_vars.elements();
    Enumeration E = accessible_vars.elements();
    NslNumeric n;
      //System.out.println("Debug: nslRefParent>"+this.getName());
      while(E.hasMoreElements()) {
	n=(NslNumeric)E.nextElement(); //old
        //n=(NslNumeric)((NslEnv)E.nextElement()).getData(); //98/9/15 aa: added getData
        // System.out.println("Debug: nslRefParent: ACCESSIBLE LOOKUP:compare ["+name+"] with ["+n.getName()+"] ");
        if(name.equals(n.getName()))
              return n;
      }
// 98/7/30 aa: if you did not find him in the parent then look in the grandparent 
    if (module_parent == null)
	{
	System.err.println("Error in NslModule: Could not find hierarchy variable >"+name);
	System.err.println("Went all the way to >"+this.getName());

        return null;
	}
    else
      return module_parent.nslRefParent(name);
  }


  /**
   * Add a NslNumeric object as an environment variable 
   to the current environment list. The name of the environment
   variable is the same as the NslNumeric object
   * @param n NslNumeric object that stores the value
   * @throws NullPointerException if outport is null
   */

  public NslNumeric env(NslNumeric n) {
    return env(n.getName(), n);
  }

  /**
   * Add a NslNumeric object as a <i>top</i> environment variable 
   to the current environment list
   * @param name name of the environment variable
   * @param n NslNumeric object that stores the value
   * @throws NullPointerException if outport is null
   */
  public NslNumeric envt(String name, NslNumeric n) {
    NslEnv env;
    NslEnv parent_env;

    if (n == null) {
      throw new NullPointerException();
    }
    env = new NslEnv(name, n, null);
    environ_vars.addElement(env);
    //System.out.println("Debug: NslModule: envt RETURNNING");
    return n; //env.isDataSet();
  }

  /**
   * Add a NslNumeric object as a <i>top</i> environment variable 
   to the current environment list. The name of the environment
   variable is the same as the NslNumeric object
   * @param n NslNumeric object that stores the value
   * @throws NullPointerException if outport is null
   */
  public NslNumeric envt(NslNumeric n) {
    NslEnv env;
    NslEnv parent_env;

    if (n == null) {
      throw new NullPointerException();
    }
    parent_env = getEnv(n.getName());   
    env = new NslEnv(n, null);
    environ_vars.addElement(env);
    return n; //env.isDataSet();
  }



  /**
   * Get an environment variable with name <tt>name</tt>
   * @param name name of target environment variable
   * @return environment variable, null if not found
   */
   NslEnv getEnv(String name) {
    Enumeration E = environ_vars.elements();
    NslEnv env;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
    	env=(NslEnv)E.nextElement();
        /// System.out.print("Debug: NslModule:getEnv["+name+" x "+env.getName()+"] ");
    	if(name.equals(env.getName()))
	      return env;
      }
    }

    if (module_parent == null)
      return null;
    else
      return module_parent.getEnv(name);
  }

  /**
   * Remove environment variable <tt>env</tt> from the list
   * @param env the environment variable
   * @return flase if the environment variable was not found
     and true if it was found and removed
   */

   boolean removeEnv(NslEnv env) {
    return environ_vars.removeElement(env);
  }

  /** 
   * Get the reference pointer of a registered variable, either
   outport, inport, env, envt.
   * @param name the name of variable to search
   * @return the reference pointer, null if not found
   */
  public NslNumeric getVariable(String name) {
    NslInport ni;
    NslOutport no; 
    NslEnv ne;
	  // System.out.println("Debug:NslModule:getvariable("+name+")");

    ni = getInport(name);
    if (ni != null && ni.getData() instanceof NslNumeric ) {
      return (NslNumeric)ni.getData();
    }
    no = getOutport(name);
    if (no != null && no.getData() instanceof NslNumeric ) {
      return (NslNumeric)no.getData();
    }
    ne = getEnv(name);
    if (ne != null && ne.getData() instanceof NslNumeric ) {
      return (NslNumeric)ne.getData();
    }
    return(getVisible(name));

  }

  /**
    * Get a vector contains all data memeber registered in this
    module
    * @return a vector of NslNumeric objects
    */
  // todo: is there any better solution than creating a vector
  // each time it is called?
  public Vector getVariableVector() {
	// TODO: environ_vars == accessible_var
	// thus remove environ vars = hierarchyvars = accessible
        // 98/9/15 aa
    Vector vars= new Vector(inports.size()+
			outports.size()+environ_vars.size());
    Enumeration E = inports.elements();
    while(E.hasMoreElements()) {
      vars.addElement(((NslInport)E.nextElement()).getData());
    }
    E = outports.elements();
    while(E.hasMoreElements()) {
      vars.addElement(((NslOutport)E.nextElement()).getData());
    }
    // 98/9/16 aa
    E = environ_vars.elements();
    while(E.hasMoreElements()) {
      vars.addElement(((NslEnv)E.nextElement()).getData());
    }
    // 98/9/16 aa
    E = accessible_vars.elements();
    while(E.hasMoreElements()) {
      vars.addElement((NslNumeric)E.nextElement());
    }

    return vars;
  }

  /**
   * Connect two child modules and add the connection to the scheduler<br>
     The connection is done in two phases. First, it will connect
     outport of a child module to the inport of another child module,
     and outport of a child module to the outport of the parent module
     (ie the wall of module in one level higher in hierarchy). Second,
     the connection between the inport of the parent module and the
     intport of the child module is established. Two phases are needed
     because the content of the inport of the parent module is not
     available in the first phase. Here is an illustration: <br>
     <pre>
     +-NslModule Top-----------------------------------------------+
     | +-NslModule A----------+       +-NslModule B-------------+  |
     | | +-NslModule a---+    |       |     +-NslModule b-----+ |  |
     | | | variable x    | 1  | 2     | 3   | variable y      | |  |
     | | |               |o##o|o#####i|i###i|i                | |  |
     | | |               |    |       |     |                 | |  |
     | | +---------------+    |       |     +-----------------+ |  |
     | +----------------------+       +-------------------------+  |
     +-------------------------------------------------------------+
    o   outport
    i   intport
    ### connection
    </pre>
    Assume we are at the top level in the hierarchy: NslModule Top
    and we are going to connect two modules, NslModule A and
    NslModule B. All links #1, #2, #3 are not available. In general
    case, we need to connect all the links internal to the child
    modules first, ie #1, and #3. <br>

    However, in our implementation of ports, the variable, instead
    of referencing through ports, references the corresponding
    variable directly. For instance, for a variable y in NslModule b
    to read a variable x in NslModule a, y makes a direct reference
    to x. <br>

    This implementation is very efficient in the simulation running
    phase, but not the initialization, as well as the conneciton,
    phase. The connection #1 works fine, since it can reference
    variable x. But connection #3 does not work, since at the time
    of connection, NslModule b cannot see variable x in NslModule a.
    In this implementation, we "remember" this link and delay the
    construction. <br>

    Go back to the highest level. Link #2 can be done since #1 is
    established. Link #2 can see variable x in NslModule a now.
    At this time we can construct the <i>Missing Links</i>.<br>

    The missing links in the first phase is stored in <tt>
    missing_links</tt>. The system will call another method
    <tt>connMissingLinks</tt> to construct the links in the second
    phase.

   * @param child1 From module <tt>child1</tt>
   * @param name1 Port of child1
   * @param child2 To module <tt>child2</tt>
   * @param name2 Port of child2
   * @return true if connection is successful
   * @see NslModule#connChildren_callinitsys
   * @see NslModule#connMissingLinks

   * Side Effect: change missing_link: all links not established
                  is stored in missing_link
   */
  // connect from child1.name1 to child2.name2
  // return true is success
   public boolean connect(NslModule child1, String name1, NslModule child2, String name2) { return(conn(child1,name1,child2,name2));}

   public boolean conn(NslNumeric num1, NslNumeric num2) {
    NslModule child1,child2; // these are the owners of num1 & num2
    NslInport inport1;
    NslInport inport2;

    NslOutport outport1;
    NslOutport outport2;

    NslPort port1;
    NslPort port2;

    String name1;
    String name2;

    boolean success = true;

    port1=num1.getPort();
    port2=num2.getPort();
    name1=port1.getName();
    name2=port2.getName();
    child1=port1.getOwner();
    child2=port2.getOwner();


    if (port1==null) {
      System.err.println("Error in NslModule: Cannot find port '"+name1+
			 "' in module '"+child1.getName()+
			 "' in the connection with port '"+name2+
			 "' of module '"+child2.getName()+"'.");
      return false;
    }
    if (port2==null) {
      System.err.println("Error in NslModule: Cannot find port '"+name2+
			 "' in module '"+child2.getName()+
			 "' in the connection with port '"+name1+
			 "' of module '"+child1.getName()+"'.");
      return false;
    }


    // inter child connection
    // the outport of first child is connected to the inport of the
    // second child.
    // todo: we have to ensure that both children are in the current
    //       module.
    if (port1.getType() == NslPort.OUTPORT
	&& port2.getType() == NslPort.INPORT) {
    		//System.out.println("Debug: NslModule: Link "+child1.getName()+" outport "+name1+" w/ "+child2.getName()+ " inport "+name2);

      ((NslInport)port2).setPort((NslOutport)port1);
        //system.scheduler.addConnection(new NslConnection(leaf1, name1, leaf2, name2));

    }
    // outport to outport connection
    // The outport of child module is connected to the outport of this
    // module.
    // todo: we have to ensure that port1 is the outport of child module of
    //       this module and port2 is the outport of this module.
    else if (port1.getType() ==  NslPort.OUTPORT
	     && port2.getType() == NslPort.OUTPORT) {
      if (((NslOutport)port1).isInitialized()) {
		//System.out.println("Debug: NslModule: Link "+child1.getName()+" outport "+name1+" w/ "+child2.getName()+ " outport "+name2);

      ((NslOutport)port2).setPort((NslOutport)port1);
        //system.scheduler.addConnection(new NslConnection(leaf1, name1, leaf2, name2));
      }
      else{
	if (missing_links==null)
	  missing_links = new Vector(1,1);
	missing_links.addElement(new NslConnection(child1, name1, child2, name2));
	//System.out.println("Debug: NslModule: Link "+child1.getName()+" outport "+name1+" w/ "+child2.getName()+ " outport "+name2);
	success = false;

      }

    }
    // inport to inport connection
    // The inport of this module is connected to the outport of the
    // child module.
    // todo: we have to ensure that port1 is the inport of this module
    //       and port2 is the inport of the child module.
    else if (port1.getType() == NslPort.INPORT
	     && port2.getType() == NslPort.INPORT) {
      if (((NslInport)port1).isInitialized()) {
	 //System.out.println("Debug:NslModule: Link "+child1.getName()+" inport "+name1+" w/ "+child2.getName()+ " inport "+name2);
    	((NslInport)port2).setPort((NslInport)port1);
    	  //system.scheduler.addConnection(new NslConnection(leaf1, name1, leaf2, name2));
      }
      else{
	if (missing_links==null)
	  missing_links = new Vector(1,1);
	missing_links.addElement(new NslConnection(child1, name1, child2, name2));
		//System.out.println("Debug: NslModule: Link "+child1.getName()+" inport "+name1+" w/ "+child2.getName()+ " inport "+name2);

	success = false;

      }

    }
    // connect inport of this module to the outport of this module
    // it is only for the direct connection from inport of this
    // module to the outport.
    // todo: establish the connection
    //       ensure that both inport/outport are from this module
    else {
      success = false;
      System.err.println("Error in NslModule: in connecting "+name1+" and "+name2);
    }
    return success;
}



   public boolean conn(NslModule child1, String name1, NslModule child2, String name2) {
    NslInport inport1;
    NslInport inport2;

    NslOutport outport1;
    NslOutport outport2;

    NslPort port1;
    NslPort port2;

    boolean success = true;

   // System.out.println("Debug: NslModule: conn: child1:"+child1+"   child2:"+child2);
    port1 = child1.getPort(name1);
    port2 = child2.getPort(name2);
    if (port1==null) {
      System.err.println("Error in NslModule: Cannot find port '"+name1+
			 "' in module '"+child1.getName()+
			 "' in the connection with port '"+name2+
			 "' of module '"+child2.getName()+"'.");
      return false;
    }
    if (port2==null) {
      System.err.println("Error in NslModule: Cannot find port '"+name2+
			 "' in module '"+child2.getName()+
			 "' in the connection with port '"+name1+
			 "' of module '"+child1.getName()+"'.");
      return false;
    }

    // inter child connection
    // the outport of first child is connected to the inport of the
    // second child.
    // todo: we have to ensure that both children are in the current
    //       module.
    if (port1.getType() == NslPort.OUTPORT
	&& port2.getType() == NslPort.INPORT) {
    		//System.out.println("Debug: NslModule:  Link "+child1.getName()+" outport "+name1+" w/ "+child2.getName()+ " inport "+name2);
      ((NslInport)port2).setPort((NslOutport)port1);
	//system.scheduler.addConnection(new NslConnection(leaf1, name1, leaf2, name2));

    }
    // outport to outport connection
    // The outport of child module is connected to the outport of this
    // module.
    // todo: we have to ensure that port1 is the outport of child module of
    //       this module and port2 is the outport of this module.
    else if (port1.getType() ==  NslPort.OUTPORT
	     && port2.getType() == NslPort.OUTPORT) {
      if (((NslOutport)port1).isInitialized()) {
	//System.out.println("Debug: NslModule: Link "+child1.getName()+" outport "+name1+" w/ "+child2.getName()+ " outport "+name2);

	((NslOutport)port2).setPort((NslOutport)port1);
        //system.scheduler.addConnection(new NslConnection(leaf1, name1, leaf2, name2));
      }
      else{
	if (missing_links==null)
	  missing_links = new Vector(1,1);
	missing_links.addElement(new NslConnection(child1, name1, child2, name2));
	//System.out.println("Debug: NslModule: Link "+child1.getName()+" outport "+name1+" w/ "+child2.getName()+ " outport "+name2);

	success = false;

      }

    }
    // inport to inport connection
    // The inport of this module is connected to the outport of the
    // child module.
    // todo: we have to ensure that port1 is the inport of this module
    //       and port2 is the inport of the child module.
    else if (port1.getType() == NslPort.INPORT
	     && port2.getType() == NslPort.INPORT) {
      if (((NslInport)port1).isInitialized()) {
    //#1 System.out.println("Debug:NslModule:Link "+child1.getName()+" inport "+name1+" w/ "+child2.getName()+ " inport "+name2);
    	((NslInport)port2).setPort((NslInport)port1);
    	  //system.scheduler.addConnection(new NslConnection(leaf1, name1, leaf2, name2));
      }
      else{
	if (missing_links==null)
	  missing_links = new Vector(1,1);
	missing_links.addElement(new NslConnection(child1, name1, child2, name2));
    //#1 System.out.println("Debug:NslModule:Link "+child1.getName()+" inport "+name1+" w/ "+child2.getName()+ " inport "+name2);
	//System.out.println("Connection is delayed");
	success = false;

      }

    }
    // connect inport of this module to the outport of this module
    // it is only for the direct connection from inport of this
    // module to the outport.
    // todo: establish the connection
    //       ensure that both inport/outport are from this module
    else {
      success = false;
      System.err.println("Error in NslModule connecting "+name1+" and "+name2);
    }
    return success;
  }

  /**
   * Connect two modules using defined link
   * @param link The connection between two modules
   * @return true if the connection is successful
   */
  public boolean conn(NslConnection link) {
    return conn(link.child1, link.name1, link.child2, link.name2);
  }


  /**
   * Call child modules to connect their own internal modules
     recursively. It is the first stage of connection in makeinst.
     The links not well defined will be put in <tt>missing_links</tt>
     vector for the second stage
   * @see NslModule#conn
   * @see NslModule#connMissingLinks
   */
  // call makeconn recursively to connect all modules in the
  // module

  // todo: ensure the connection is valid. Otherwise, throw
  //       exception of do something else that will warning
  //       the programmer that the link is not in correct fashion

/* This was here for calling initsys within connChildren ...
  public void connChildren() {
    System.err.println("Error in NslModule: *WARNING* connChildren() shouldn't be called anymore");
    connChildren_callinitsys();
  }
*/
  public void connChildren() {

//System.out.println("Debug: NslModule: connChildren Called");
    int num3=0;
    Enumeration E = module_children.elements();
    Enumeration E2 = module_children.elements();
    NslModule child = null;

    // connect the components inside the children of this module first
      while(E.hasMoreElements()) {
    	child = (NslModule)E.nextElement();
        //System.out.println("Debug: NslModule: Connecting "+getName()+" with its child "+child.getName());
    //System.out.println("Debug:NslModule "+getName()+":  INPORTS "+inports+" OUTPORTS "+outports+" ENVIRON "+environ_vars);
	child.connChildren();
      }
    // connect the components of this module
    makeconn();
    // initsys();  //ERH july 13'97
    // ERH oct 21'97 
     //System.out.println("Completed Connection of "+getName());
  }


  /**
   * Call child modules to connect their missing links, if possible
     It checks the <tt>missing_links</tt> vector for the connection
     required.
   * @see NslModule#conn
   * @see NslModule#connChildren_callinitsys
   */
  // todo: ensure the connection is valid. Otherwise, throw
  //       exception or do something else that will warning
  //       the programmer that the link is not in correct fashion

   public void connMissingLinks() {
    Enumeration E;
    NslConnection link = null;
    NslModule child = null;
      //# System.out.println("Connecting missing links of module "+getName());

    if (missing_links != null) {

      //System.out.println("Debug: NslModule: NOT NULL!!!: Connecting missing links of module "+ getName());
      E  = missing_links.elements();
      if (E.hasMoreElements()) {
	while(E.hasMoreElements()) {
	  link = (NslConnection)E.nextElement();
	  if(!conn(link)) {
	    // some problem in connection even in second phase
	    System.err.println("Error in NslModule: Cannot connect module '"+link.child1+
			       "' port '"+link.name1+
			       "' -> module '"+link.child2+
			       "' port '"+link.name2+"'");
	  }
	}
      }

      missing_links = null;
    }

    E = module_children.elements();
    // connect the components inside the children of this module first
    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	child = (NslModule)E.nextElement();
	child.connMissingLinks();
      }
    }
  }
  /**
   * get run step size, delta t
   * @return step size
   */
  public double getStepSize() {
  
    switch (system.train_or_run) {
        case 'R':
            //System.out.println("Taking run step size: "+run_step_size);
    	    return run_step_size;
        case 'T':
            //System.out.println("Taking train step size: "+train_step_size);
    	    return train_step_size;
    	default:
    	    System.out.println("Taking 0.0 step as size");
    	    return 0.0;
    }
  }


  /**
   * get run step size, delta t
   * @return step size
   */
  public double getRunStepSize() {
    return run_step_size;
  }
  /**
   * set run step size, delta t.  The setting will propagate to all child modules
     in the hierarchy if the module is an internal node.
   * @param t step size
   */
  public void setRunStepSize(double t) {
    Enumeration E = module_children.elements();
    NslModule child = null;
    run_step_size = t;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	child = (NslModule)E.nextElement();
    child.setRunStepSize(t);
      }
    }


  }
  
  /**
   * get train step size, delta t
   * @return step size
   */
  public double getTrainStepSize() {
    return train_step_size;
  }
  /**
   * set train step size, delta t.  The setting will propagate to all child modules
     in the hierarchy if the module is an internal node.
   * @param t step size
   */
  public void setTrainStepSize(double t) {
    Enumeration E = module_children.elements();
    NslModule child = null;
    train_step_size = t;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	child = (NslModule)E.nextElement();
    child.setTrainStepSize(t);
      }
    }


  }
  /**
   * Examine whether the module runs on execution command <tt>run</tt>
     or <tt>step</tt>
   * @return true if it is active, false if idle on execution command
   */
  public boolean getTrainEnableFlag() {
    return train_enable_fg;
  }
  /**
   * To set if the module runs on execution command <tt>run</tt>
     or <tt>step</tt>. The setting will propagate to all child modules
     in the hierarchy if the module is an internal node.
   * @param b true if active, false if idle
   */
  public void setTrainEnableFlag(boolean b) {
    Enumeration E = module_children.elements();
    NslModule child = null;
    train_enable_fg = b;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	child = (NslModule)E.nextElement();
    child.setTrainEnableFlag(b);
      }
    }

  }
  /**
   * Examine whether the module runs on execution command <tt>run</tt>
     or <tt>step</tt>
   * @return true if it is active, false if idle on execution command
   */
  public boolean getRunEnableFlag() {
    return run_enable_fg;
  }
  /**
   * To set if the module runs on execution command <tt>run</tt>
     or <tt>step</tt>. The setting will propagate to all child modules
     in the hierarchy if the module is an internal node.
   * @param b true if active, false if idle
   */
  public void setRunEnableFlag(boolean b) {
    Enumeration E = module_children.elements();
    NslModule child = null;
    run_enable_fg = b;

    if (E.hasMoreElements()) {
      while(E.hasMoreElements()) {
	child = (NslModule)E.nextElement();
    child.setRunEnableFlag(b);
      }
    }

  }
  /**
   * get integration time step / numerical method time step tm
   * @return time step size
   */
  public double getIntegrationTimeStep() {
    return integration_time_step;
  }
  /**
   * To set the time step size
   * @param t time step size
   */
  public void setIntegrationTimeStep(double t) {
    integration_time_step = t;
  }

  public NslDiff getDiffMethod() {
    return diff_method;
  }

  public void setDiffMethod(NslDiff dm) {
    diff_method = dm;
  }

  /*
     static NslNumMethod getNumericMethod() {
     return numeric_method;
     }
     static void getNumericMethod(NslNumMethod method) {
     numeric_method = method;
     }
     */


  public String tostring() {
    String tmp = new String ("Nsl Module "+name
			     +" Parent Module "+module_parent.tostring());
    return tmp;
  }

  public void showStatus() {
    System.out.println(statusString());
  }

  public String statusString() {
    return new String("Nsl Leaf "+name+
		      " Parent Module "+module_parent.getName());
  }


  /**
   * Get the name of the module
   * @return name of this module
   */
  public String getName() {
    return name;
  }
  /**
   * Set the name of the module
   * @param name name of this module
   */
  public void setName(String s) {
    name = s;
  }


  /**
   * Update the status of all outports. It is done after each major
     numerical calculation
   */
  public void update() {
  
//    if (doubleBuffering) {
      Enumeration E = outports.elements();
      NslOutport port;

      if (E.hasMoreElements()) {
        while(E.hasMoreElements()) {
	  port=(NslOutport)E.nextElement();
	  port.update();
        }
      }
 //   }
  }

    public void setBuffering (boolean v) {
      doubleBuffering = v;
      Enumeration E = outports.elements();
      NslOutport port;

      if (E.hasMoreElements()) {
        while(E.hasMoreElements()) {
	  port=(NslOutport)E.nextElement();
	  if (port.getBuffering()!=doubleBuffering) {
	      port.setBuffering(doubleBuffering);
          }
        }
      }

    }

  /**
   * Call when multi-threaded. It simply calls execute() defined by
     the user
   * @see NslModule#execute
   */
  public void run() {
    runsim();
  }

  protected void finalize() {
    missing_links.removeAllElements();
    module_parent = null;
    module_children.removeAllElements();
    inports.removeAllElements();
    outports.removeAllElements();
    environ_vars.removeAllElements();

  }

  /**
   * Instantiation the internal variable of this object. It is called
     automatically at the construction phase of this module. It must
     be defined by user.
   */
  public void makeinst(String name, NslModule p) { makeInst(name,p); }
  public void makeInst(String name, NslModule p) {}
 //ERH: why this is commented?  ERH: uncommented 
 //ERH: made it non abstract july 16'97

  public void initsys(){ initSys(); }
  public void initSys(){}

  public void endsys(){ endSys(); }
  public void endSys(){}
  
  /**
   * Initialization step of this module. It is called automatically
     at the start of the simulation, or by <tt>init</tt> command
     in interactive environment.
   */
  public void initrun() { initRun();}
  abstract public void initRun();
 /* need to have initrun abstract, since NPP
    fills something inside through MethodNode. Unless you
    change this, they must be abstract */
  public void endrun(){ endRun(); }
  public void endRun(){  }


  /**
   * Make the connection between child modules. It is automatically
     called at the construction phase of this module, but after the
     instantiation of those internal modules
   */
  public void makeconn(){ makeConn();} // connect between modules (using ports)
  public void makeConn(){ } // connect between modules (using ports)

  /**
   * The <b>run</b> block of this module
   */
//note that schedular calls runsim()
  public void runsim(){
//register module's name for error reporting
	NslSystem.module_executing=this.getName();
	simRun();
  }
  /* 98/9/11 aa TODO - remove */
  public void simrun(){ // main run method
   simRun();
  } 

 public void simRun() {} // this the latest syntax 01/19/98

  // SM 

  public void initTrain() {}
  public void simTrain() {}
  public void endTrain() {}
 

  public void setDisplayFrame(NslDisplayFrame  df) { displayframe=df; }
 
  public void addModelPlots(NslDisplayFrame df) { initwindow(df); }
  public void addModelPlots(NslDisplayFrame df, String s) {initwindow(df,s); }
  public void initwindow(NslDisplayFrame df) { initWindow(df);}
  public void initwindow(NslDisplayFrame df, String s) {initWindow(df,s);  }
  public void initWindow(NslDisplayFrame df) { }
  public void initWindow(NslDisplayFrame df, String s) { }
}