The package includes considerable browser-based documentation in the docs/ directory for fast viewing, and the readme.html includes an overall description.  The docs/how_to/how_to.html gets into running and programming RePast, while docs/api/ contains the JavaDocs.

To run the model, click either the "Single Step" or "Forward" buttons.  To pause the model, click the "Pause" button.  The parameters can be set using the parameter window controls.  The simulation is a version of the SugarScape model made famous by Axtell and Epstein in their 1996 book Growing Artificial Societies.

Take some time to browse through the RePast HowTo . Its Running a Simulation and GUI sections are good starting places for how to use the demos. The SimpleModel HowTo describes initial programming using the SimpleModel class we'll use below.  The FAQ is a good place if all else fails!   The code for the demos is in the downloaded src/ directory under uchicago/src/sim. 

Its a good idea to bookmark your local copy of the API documentation, for both Java and RePast.  They will be your constant companion as you write models!

Initially there are lots of isolated pairs tied together.  Later threes, fours and abruptly there is a steep transition to most of the buttons being tied together .. an emergent giant cluster.  In the example shown here, there are 500 buttons and we plot 1000 turns.  The rapid change occurs at around the 1/4 mark where the number of threads is about half the number of buttons.

      javac -classpath lib/repast.jar:. TutModel.java
      java  -classpath lib/repast.jar:. TutModel &

Note that I've changed directory to where the java file is, and made a link to the RePast lib/ directory .. both to simplify the compilation and execution of the model. The results are to the right:

The class only has three methods: "setup" and "buildModel", along with a static (Class) "main" method who's only job is to start the model.

Setup is called when a model is initialized, or is restarted, both from the Control Panel.  BuildModel is called when the model is first run, either by the Step or the Run buttons in the Control Panel.

Both are discussed in the HowTo.

Note that only 16 lines of code got us running!

If you run this model, clicking on Step or Run simply increase the tick count with no other effect because we have not added a "step" method. 

So this is a "no-op" model at this point, but has the initial structure we need to get started.

public class TutModel extends SimpleModel {
  private DisplaySurface dsurf;
  private int spaceSize = 50;

  public void setup() {
    super.setup();

    if (dsurf != null) dsurf.dispose();
    dsurf = new 
      DisplaySurface(this,"Buttons Display");
    super.registerDisplaySurface
                   ("Buttons Display",dsurf);
  }

  public void buildModel() {
    Object2DTorus space = new 
      Object2DTorus(spaceSize, spaceSize);

    Object2DDisplay display = new 
       Object2DDisplay(space);
    dsurf.addDisplayable(display,"Buttons Space");

    dsurf.display();
  }

  public static void main(String[] args) {
    SimInit init = new SimInit();
    init.loadModel(new TutModel(), null, false);
  }
}

In our second phase, we create our Button "agent", TutAgent.java, along with the changes needed in TutModel.java needed to incorporate the agents and initialize them randomly on the DisplaySurface.  TutAgent is quite minimal, just enough to be Turtle-like: have a color, an ID (who) and be a Drawable.

The changes to TutModel are the minimum to add the agents: introduce a variable "buttons" to hold the number of buttons and add a loop creating the buttons.

We added the "who" and "color" attributes to make the TutAgent be turtle-like, both for our button experiment and for future NetLogo-like models in RePast.

We added "setXY" method, and the "space" instance variable so that TutAgents could add themselves to spaces automatically for the TutModel.  Thus "setXY" both updates the x, y instance variables and places the agent correctly in the space. 

Note "setXY" also removes us from out prior position in the space if need be.

public class TutAgent implements Drawable {
  private int who;
  private int x, y;
  private Color color;
  private Object2DTorus space;

  public TutAgent(Object2DTorus space, int who){
    this.who = who;
    this.space = space;
  }

  public void draw(SimGraphics g) {
    g.drawFastCircle(color);
  }

  public void setXY(int x, int y) {
    if (space.getObjectAt(this.x, this.y)==this)
      space.putObjectAt(this.x, this.y,null);
    this.x = x;
    this.y = y;
    space.putObjectAt(x,y,this);
  }

  //Getter/Setters
  public int getX() { return x; }
  public int getY() { return y; }
  public int getWho(){ return who; }

  public void setColor(Color color) {
    this.color = color;
  }
}

Nothing is added to "setup".  In "buildModel" we simply add the code to create the buttons (TutAgent's) and initialize them randomly, both random colors and random positions.

The call to btn.setXY, in addition to setting the x and y instance variables, adds the TutAgent to the RePast "space" .. the grid the agents live on.  See above.

We also add the TutAgent to a list, agentList, which is part of the SimpleModel class as a convenience.

public class TutModel extends SimpleModel {
  ...
  private int buttons = 500;
  ...
  
  public void buildModel() {
    ...
    for (int i = 0; i<buttons; i++) {
      int x = getNextIntFromTo(0, spaceSize - 1);
      int y = getNextIntFromTo(0, spaceSize - 1);
      Color color =  new Color(
        getNextIntFromTo(0,255),
        getNextIntFromTo(0,255),
        getNextIntFromTo(0,255)
      );

      TutAgent btn = new TutAgent(space, i);
      btn.setXY(x,y);
      btn.setColor(color);
      agentList.add(btn);
    }
    ...
  }
}

Now when we run the demo model, we see the buttons begin to change colors and after running for a bit, the colors merge to being primarily the same color.

Here is the new source code for TutModel.java and TutAgent.java.

Like in the NetLogo model, we chose two random buttons, and then merge their groups by making all of the group1 agents become group2 agents.

Note the final call to dsurf.updateDisplay().  This is how the changes occur to the display.  It is more efficient having the Model explicitly decide when to redraw the display  rather than having it always do so.

public class TutModel extends SimpleModel {
  ...
  public void step(){
    TutAgent a1=(TutAgent)agentList.get
      (getNextIntFromTo(0,buttons-1));
    TutAgent a2=(TutAgent)agentList.get
      (getNextIntFromTo(0,buttons-1));
    int g1=a1.getGroup();
    int g2=a2.getGroup();
    for (int i = 0; i < agentList.size(); i++) {
      TutAgent a = (TutAgent)agentList.get(i);
      if (a.getGroup() == g1) {
        a.setGroup(g2);
        a.setColor(a2.getColor());
      }
    }
    dsurf.updateDisplay();
  }
}

We provide getters/setters for "group" so that we can merge the groups during the "step" method above.

This completes TutAgent, there will be no more changes to it.

public class TutAgent implements Drawable {
  ...
  private int group;
  ...

  public TutAgent(Object2DTorus space, int who){
    ...
    this.group = who;
  }
  ...
  public void setGroup(int group)
                        {this.group = group;}
  public int getGroup() { return group; }
}

Only TutModel changes.  It adds two features, user setable parameters (for number of buttons and size of the space), and a graph showing the growth of the largest cluster of connected buttons.

Here is the final source code for TutModel.java and TutAgent.java.

To tell RePast which elements to include in the parameter panel, we create a constructor for the TutModel which sets the SimpleModel variable "params" to a string array of the parameters to display. (See getInitParam in SimpleModel)

RePast requires all user parameters to be available via getter/setter methods, which we also add to TutModel

public class TutModel extends SimpleModel {
  ...
  public TutModel () {
    params = new String[] {"Buttons", "SpaceSize"};
  }
  ...
  public int getButtons() { return buttons; }
  public void setButtons(int buttons)
    {this.buttons = buttons;}
  public int getSpaceSize() { return spaceSize; }
  public void setSpaceSize(int spaceSize)
    {this.spaceSize = spaceSize;}
}

First, we add two instance variables: "clusterSz", which holds the largest cluster of buttons so far, and "plot", the RePast OpenSequenceGraph object.

In "setup", we initialize both .. clusterSz to 1, and plot to have the desired name and axis labels, and to plot the clusterSz variable via a new Sequence instance.  Graphs can have many of these, one per plot line.  We only need one.  Note the use of a dynamically created class with a single method reporting clusterSz.

In "buildModel", we use the current value of "buttons" to set the axes to reasonable values, and pop-up the plot window.

In "step" we add code to manage "clusterSz", updating it if the current size is greater.  We then plot the current value by calling "plot.step".  Finally we pause the model when we get to the point that all the buttons are connected.

public class TutModel extends SimpleModel {
  ...
  private int clusterSz;
  private OpenSequenceGraph plot;
  ...
  public void setup() {
    ...
    clusterSz = 1;
    ...
    if (plot != null) plot.dispose();
    plot = new OpenSequenceGraph("Buttons", this);
    plot.setAxisTitles("time", "cluster");
    plot.addSequence("MaxCluster", new Sequence() {
      public double getSValue() {return clusterSz;}
    });
  }

  public void buildModel() {
    ...
    plot.setXRange(0, buttons*2);
    plot.setYRange(0, buttons);

    plot.display();
  }
  ...
  public void step(){
    ...
    int thisClusterSz = 0;
    for (int i = 0; i < agentList.size(); i++) {
      ...
      if (a.getGroup() == g2)
        thisClusterSz++;
    }
    clusterSz = Math.max(clusterSz,thisClusterSz);

    plot.step();
    if (clusterSz == buttons)
        getController().pauseSim();
  }
}