Frequently Asked Questions

  1. How do I make my model the "main" executable class?

    2. Executable classes in java, that is classes that can be run from the command line with java MyClass.class to start an application, must implement the main method. The main method has the following signature public static void main(String[] args). If you wish your model to be executable then you need to implement this method in your code. The method itself will look something like: 
    public static void main(String[] args) {
  SimInit init = new SimInit();
  HeatBugsModel model = new HeatBugsModel();
  init.loadModel(model, null, false);      
}
    This code creates an instance of the SimInit class (the same class with which you can load your models on the command line), and instance of the model itself. It then uses SimInit to load the model via the loadModel method. The second and third parameters of the loadModel method specify a parameter file and whether or not the model is a batch model. You can either pass values to these parameters via the args array or if you know that this model is a batch model, you can specify the method parameters directly. The following is an example of the later. 
    public static void main(String[] args) {
  SimInit init = new SimInit();
  EnnBatchModel model = new EnnBatchModel();
  init.loadModel(model, "./EnnParams.txt", true);      
}
    This code snippet is from EnnBatchModel.java in the enn demo (see repast/demo/enn). Here we create an instance of SimInit and the model as above. We then pass a parameter file path and a value of true to the second and third arguments of the loadModel method. With these parameters SimInit would load EnnBatchModel in batch mode, and read the parameters from the EnnParams.txt file.

    If you wish to parse the arguments in the args parameter of the main method and pass them to the loadModel, the following shoudl help. For a command line of: 

    java -cp c:\repast\lib\repast.jar;. MyModel param.pf true
    args[0] = param.pf and args[1] = true. And knowing this it should not be hard to parse args[] and extract the appropriate values to pass to the loadModel method.

  2. How do I make my jar files executable?

    3. See answer to item 4.

  3. How can start my model with 'java -jar mymodel.jar'?

    4. See answer to item 4

  4. How can I start my model by clicking on it (i.e. how can I make it behave like other windows applications)?

    5. To do this you must create your own manifest file and then use this manifest file when you create your jar file. A manifest file is simply a plain text file with some special tags that the Java virtual machine knows how to work with. You can include special tags in the mainfest file that tell the Java virtual machine which file in that jar file is the executable "main" class, as well as specifying a classpath. As of Repast 1.3 all the demonstration simulations are run in this way. The following is the manifest file from bugs.jar (the heatbugs demo simulation). 
    Main-Class: uchicago.src.sim.heatBugs.HeatBugsModel
Class-Path: ../../lib/repast.jar ../../lib/trove.jar ../../lib/colt.jar 
../../lib/jgl3.1.0.jar ../../lib/excelaccessor_Runtime.jar ../../lib/jmf.jar 
../../lib/jcchart.jar ../../lib/junit.jar ../../lib/plot.jar 
../../lib/xerces.jar
    The Class-Path: entries should all be one line. Here the main class is uchicago.src.sim.heatBugs.HeatBugsModel and it requires the specified classpath in order to execute correctly. The class path is space delimited here, and the paths of the jar files are defined relative to the bugs.jar file. In this case two directories above the repast/demo/bugs directory in the repast/lib directory. With this manifest file in the bugs.jar archive, we execute the heatbugs simulation with java -jar bugs.jar. This has the added benefit of making the jar file executable when double click under windows. Given the above manifest file, this is directly equivalent to: 
    java -cp  ./bugs.jar;../../lib/repast.jar;../../lib/trove.jar;
../../lib/colt.jar; ../../lib/jgl3.1.0.jar;
../../lib/excelaccessor_Runtime.jar;../../lib/jmf.jar;
../../lib/jcchart.jar;../../lib/junit.jar;../../lib/plot.jar;
../../lib/xerces.jar uchicago.src.sim.heatBugs.HeatBugsModel
    (Note that as of Repast v.1.3, you no longer start models this way. repast.jar itself contains a manifest file that specifies a classpath containing all the other required jar files. So instead of the above, you can do java -cp ./bugs.jar;../../lib/repast.jar uchicago.src.sim.heatBugs.HeatBugsModel.)

    Once you've written your manifest file, you need to include it in your jar. If you haven't yet created your jar file, you can do this all in one step with the 'jar' utility that comes with the java development kit. 

    jar cfvm my_model.jar mymanifest my_model_dir
    where my_model.jar is the name of the jar file you are creating, mymanifest is the manifest file you've created and my_model_dir is the directory for your actual model. So for heatbugs this looks like: 
    jar cfvm bugs.jar bugs_manifest uchicago/src/sim/heatBugs
    If your model is in a package (as it should be) its important to jar it from the directory above the first package directory. In the heatbugs case I would run the jar command from the directory in which the uchicago directory resided.

    If you already have your classes in a jar file and just want to add the manifest file, replace the 'c' in the above command with a 'u'.

    You can inspect the contents of your jar file with jar -tf name_of_jar_file. Your manifest won't be included in the jar itself as its contents are actually copied into the MANIFEST.MF file.

    For more information run the jar utility with no arguments and see Sun's jar tutorial

  5. How do I stop or pause my model from within the model

    As of Repast 1.3, SimModelImpl (and thus all models that inherit from it) implements two new methods: public void stop() and public void pause. You can call these methods from within the model to stop or pause it. Like any other public method, this methods are schedulable so you can schedule your model to pause (or stop) at particular intervals or at specified ticks. For example, 
    int pauseTick = -1;
...
private void buildSchedule() {
  schedule.scheduleActionAt(pauseTick, this, "pause", Schedule.LAST);
  ...
}

public void setPauseTick(int val) {
  pauseTick = val;
  schedule.scheduleActionAt(pauseTick, this, "pause", Schedule.LAST);
}

public int getPauseTick() {
  return pauseTick;
}
    will allow you to schedule pauses through the gui.

  6. My agents display too many parameters when probed. How can I limit them?

    7. If your agent implements the CustomProbeable interface only those parameters whose names are returned in the String[] from CustomProbeable.getProbedProperties() will be displayed. For example, 
    public class MyAgent implements CustomProbeable {

  private int age;

  ...

  public int getAge() {
    return age;
  }

  public void setAge(int val) {
    age = val;
  }

  public String[] getProbedProperties() {
    return new String[] {"Age"};
  }                             
}
    When probed MyAgent classes will now only display the "Age" parameter.

  7. How do I add my own button to the Repast toolbar?

    8. The following code demonstrates how to do this: 
    public void setup() {
  
  ...

  Controller c = (Controller)this.getController();
  c.addButton("Help", new ActionListener() {
     public void actionPerformed(ActionEvent evt) {
       showHelp();
     }
  });

}
    Controller has three new methods for adding custom buttons to the toolbar. Using the addButton methods you can add a JButton directly, specify a label and an ActionListener, or specify the path to an Icon and an ActionListener. The above code snippet will add new a JButton with the label "Help" to the toolbar and call the showHelp method whenever it is clicked. You must add new buttons in your model's setup() method otherwise they will not appear in the toolbar.

    If you don't understand how to work with JButtons, and ActionListeners, you should learn a bit about the Java's Swing gui toolkit before adding custom buttons to the toolbar.

  8. I'd like my model to do X when I hit a key. How do I do this?

    9. You can perform some action in response to key events when either the DisplaySurface, or the Controller (i.e. the Repast toolbar) has focus. Which one you choose depends on which one is more appropriate for your action. For example, if you wish to do something to the display in the DisplaySurface, then you'd hook the key code up to the DisplaySurface. In either case, the code to listen for key events is the same. For example, 
    Controller c = (Controller)this.getController();
c.addKeyListener(new KeyAdapter() {
  public void keyPressed(KeyEvent evt) {
    if (evt.getKeyCode() == KeyEvent.VK_K) {
	    System.out.println("k key typed");
    }
  }
});
    will print "k key typed" to the console whenever the toolbar (i.e. the Controller) has focus and the "k" key is pressed. To perform the same action when a DisplaySurface has focus, you'd replace the reference to the Controller with one to your DisplaySurface. So, 
    myDisplaySurface.addKeyListener(new KeyAdapter() {
  public void keyPressed(KeyEvent evt) {
    if (evt.getKeyCode() == KeyEvent.VK_K) {
	    System.out.println("k key typed");
    }
  }
});
    Typically you place this sort code to the setup() method in your model. This ensures that you can listener for key events before your simluation begins to run. Note that KeyAdapter and KeyEvent are in the java.awt.event package, so you'll have to import them into your model. Adding KeyListeners in this way is standard Java and any Java book can provide more details.

  9. I'd like my model to do X when I click one of the toolbar buttons. How do I do this?

    10. By default Repast takes the appropriate action whenever you click one of the toolbar buttons. However, you can also add your own to code to be executed when a button is clicked. You can listen for button clicks on the start, stop, pause, step, and exit buttons. For example, 
    Controller c = (Controller)this.getController();
c.addStartListener(new ActionListener() {
  public void actionPerformed(ActionEvent evt) {
    System.out.println("start");
  }
});
    This code listens for start button clicks and prints "start" to the console whenever a start button click occurs. Each button has its own add listener method so addStopListener will add code for execution on stop button clicks, addPauseListener for pause button clicks and so on. If you wish to know which button has been clicked (assuming you've got the same listener listening to more than one button), the button's actionCommand reports the buttons name. For example, the code 
    Controller c = (Controller)this.getController();
c.addStartListener(new ActionListener() {
  public void actionPerformed(ActionEvent evt) {
    javax.swing.JButton b = (javax.swing.JButton)evt.getSource();
    System.out.println(b.getActionCommand());
  }
});
    will print "start", the Start button's action command, to the console. The exit button's action command is "exit", pause is "pause" and so on. Adding listeners to buttons in this way is standard Java and any good book on Java can tell you more.

  10. How can I write some text to the display?

    11. If you want to display some text, e.g. some informative message or statistic, on the display. You can use a TextDisplay. See     How to Create Displays for more info, as well as the TextDisplay docs.

  11. I'd like to make my own Display. What's the best way to do that?

    12. The uchicago.src.sim.gui package contains an abstract Display class that can be used as the base class for new Display classes. See the source for Display.java (repast/src/src/uchicago/src/sim/gui/Display.java) for more.

  12. I've written a network model. What's that funny square on all the edges?

    13. The square indicates edge directionality. The square is closer to the "to" node and farther from the "from" node. If the nodes are too close to each other to determine directionality, you can use the mouse (click and drag) to move the nodes further away.

  13. How do I update my model or agent's probe panel from within the model or agent?

    14. Suppose you have two properties connected with each other such that a change to implies a change to other. When you change the first such property in a probe panel (either the agent's probe panel, or your model's parameter panel) you'd like the panel to update and display the concommitant change in the second property.

    You can update an Object's probe panel using ProbeUtilities.updateProbePanel(Object object) method. The object here is the object whose probe panel you wish to update. So, for example, we could implement the above scenario where a change to parameter X, changed the value of parameter y and we want the parameter (probe) window to display the new value of y, as follows: 

    public void setX(int val) {
  x = val;
  setY(val / 2);
  ProbeUtilities.updateProbePanel(this);
}

public void setY(int val) {
  y = val;
}

...
    This is also useful for turning various exclusive boolean switches on and off in response to others being set on.

    See the API documentation for the ProbeUtilities class for more.

  14. I'd like my probes to update every iteration of the model. How do I do that?

    15. The context here is that you are running your model in gui mode and that you are probing your agents such that their properties are displayed in a probe window. You'd like these properties to update every tick of the model. This can be done both via the GUI and in code. To turn this on via the gui, switch to the Repast actions tab panel and click on Update Probes. To do this in code, you set the UPDATE_PROBES flag in Controller to true. For example, 
    Controller.UPDATE_PROBES = true;
    This will update all probes except for that on the model. To update the model probe, you'll have to call ProbeUtilities.updateModelProbePanel. Updating the model's probe is computationally expensive.

    Note that updating probes will slow down your model although considerably less in java 1.4 vs. previous version of java.

  15. I'd like turn the Repast Console on or off. How do I do that?

    16. Stdout (output written to System.out) and stderr (errors written to System.err) can be redirected to The Repast Console. The Repast Console can be turned on or off via the GUI and in code. To turn it on/off via the GUI, switch to the Repast actions tab panel and click on "Stdout to Console" or "Stderr to Console" to either one on or off. Note that if they are both off then the Repast Console will not appear. To do this in code, you need to set the flags AbstractGUIController.CONSOLE_OUT and AbstractGUIController.CONSOLE_ERR. For example,

    AbstractGUIController.CONSOLE_ERR = false;
AbstractGUIController.CONSOLE_OUT = false;
    You can do this in the constructor of your model.

  16. What is the button with the three arrows?

    17. That is the button used to start a batch run through the Repast GUI. More information on this can be found here

  17. I would like to request a feature or file a bug report or would generally like to give feedback, where do i do this?

    18. Repast's website is found at repast.sourceforge.net and includes information on Repast itself. The primary repast email address is repast@sourceforge.net. You can also ask questions on the repast mailing lists, the main list being the repast interest list. Feel free to sign up for or browse this list at http://lists.sourceforge.net/lists/listinfo/repast-interest (direct link to the mailing list archives is here) and email this list through repast-interest@lists.sourceforge.net