Tutorial One - A Simple "Simulation"


This first tutorial builds a simple model. This model will create a random network of 10 nodes, and assign each node a numerical label. When the model runs, each node will print out its own label. The completed tutorial simulations can be found in the tutorial directory.

  1. Start RepastPy or, if it is already running, choose new from the file menu, or click the new button on the toolbar. This will bring up the New Model Dialog.




    Choose "Network Model" and click OK.

  2. Click on the Network Model component's Display Name property. Erase the current display name and change the display name to Tutorial 1. Do the same for the Model Name property and change the model name to TutorialOneModel. You should see something like:




    The display name will be displayed in title bars of the various windows of your repast simulation once it is running. The model name is the name of the java class that this component gets compiled into. You needn't worry about this except that the model name CANNOT contain spaces, and should, by convention, have its first letter capitalized.

  3. Click on the Default Network Node component . You will see the mouse cursor change shape indicating that the cursor is now "carrying" the component.

    Clicking on a component in the palette selects that component. Clicking on the selector icon will discard a selected component without dropping it on your project. Do NOT do this now.

  4. Click on the Network Model Component (now labeled Tutorial 1) in the project pane.

    This "drops" the Default Network Node component into your model. The Default Network Node component is now part of the project.

  5. Change the Name property of the Default Network Node component to TutorialOneAgent. Hit enter so that RepastPy can easily register the change. Change the Group Name property to tutorialOneNodes.

    The Name property is the name of the java class that this component gets compiled to. As before, this is important only in that the name cannot contain any spaces, and should by convention start with a capital letter. The Group Name property is the name of the group into which your compiled TutorialOneAgent-s will be placed.

  6. Choose save from the file menu, or click the save button on the toolbar. You can save the simulation wherever you like. The RepastPy GUI should now look like




    Note that the title bar of the window now contains the location of your project file in square brackets.

    You now have the core components of your simulation. A model component (TutorialOneModel) that once compiled sets up the simulation, and an agent component (TutorialOneAgent) whose behavior drives the simulation. We now need to customize these components by further editing their properties.

  7. Click on TutorialOneAgent in the project pane. This should display TutorialOneAgents's properties in the property pane, if they are not already displayed.

    This is how you navigate between components in the project pane. Clicking on a component to display its properties in the property pane.

  8. Click on the combo box for the network source property in the property table, and choose random density.

    The network source property allows you to choose the structure and number of nodes in your network. Your agent components will become the nodes in this network. Random Density creates a network of a random density, that is, it creates some number of nodes, and randomly creates links between them.

  9. Click on the edit button in the network source property. This pops up an editor for a random density network. Change the size to 10, and the density to 0.2. Click OK.

    The edit button will pop-up an editor appropriate to whatever network source you have selected. In this case, the random density network will be created with 10 nodes, and a density of approximately 0.2.

  10. Click on the Tutorial 1 model component. Then Click on the edit button for the Actions property. You should see the Action editor come up with the "initAgents" action displayed.




    The initAgents action is a default action in the Default Network Model component. This is the place to add any custom agent initialization code.

    Add the following code in the source pane

    i = 1
    for agent as TutorialOneAgent in self.tutorialOneNodes:
      agent.setNodeLabel("id - " + i)
      i = i + 1

    what this code does is to iterate through all the agents in the group called tutorialOneNodes and assign them a numeric label of "id - " followed by the current value of i. Recall that we defined "tutorialOneNodes" as the Group Name of our agents in a previous step. This group then becomes a field in our model. As it is a field in the model and we are defining an action in the model, we preceed its name with "self" where "self" here refers to the model component. In Python this is how actions etc. refer to fields defined in the same object, by preceeding the field name with "self.".

    The new complete code should look like




    Make sure the code indents as it does in the image above.

    We want to give each agent a numerical label, and the initAgents action in the model component is the place to do this kind of initialization.

  11. Click on the TutorialOneAgent component in the project pane to display its properties in the property pane.

  12. Click on the actions property's edit button to display the actions editor and chose the step action from the combo box if it is not already displayed.




  13. In the source pane of the step action, type

    print self.getNodeLabel()




    This will print this agent's label to the Repast Console everytime this agent's step action is executed.

    This step action is a default action provided by the Default Network Node component. It is here in the step action where you should define your agent's behavoir. Each iteration of the model, this step action is executed for every agent. In the above, we defined the TutorialOneModel component so that it would create 10 TutorialOneAgents and link them randomly. In addition we assigned each of these ten a different numeric id. These agents are created using the TutorialOneAgent component as a template. The 10 are separate however, and thus although each one has the same step action (i.e. print self.getNodeLabel()), their actual labels will be different.

  14. Save your project as in step 6. You can overwrite your previous save.

    You have now defined the properties of your core components so that when the simulation is run,

    1. A random network of 10 nodes is created (done in steps 8 and 9).

    2. A numeric id is assigned to each agent (step 10).

    3. Every iteration of the model, each agent will print out its id to the console (step 13).

    It is now time to compile and run the simulation.

  15. Choose compile from the model menu, or click the compile button on the toolbar.

    This compiles the project into Java code in order that it can be run like any other RePast simulation. If there are any errors in your code, they should be displayed together with an error message.

  16. Choose run from the project menu or click the run button on the toolbar.

    This will run the simulation. Note that running the simulation will also force a compile.

    You should now see the user interface for your RePast simulations. You controll it via the toolbar.




    You'll also see a window with settings for your simulation.




    Note that these settings mimic those of the Network Source editor that you saw in steps 8 and 9. You can change these settings prior to each Repast run, thereby altering the topology of the network as you see fit. The names of the parameters are in this case the Network Source properties (e.g. density) prefixed by the name of the agent group that they apply to, in this case, tutorialOneNodes. This is a common pattern in RepastPy created simulations where parameters are often prefixed by the name of the group that they apply to.

  17. Press the step button on the RePast toolbar.

    This will step through one iteration of the simulation. You should see the appropriate node ids printed out to the console.




    When you start the RePast simulation the following happens

    1. A random network is created with 10 nodes. These are placed into a DefaultGroup variable called tutorialOneNodes contained by the model. (Recall that in the model's initAgents action we iterated through this list.)

    2. TutorialOneModel's initAgents action is executed.

    3. The simulation loop begins. This loop executes the step action on each node in the tutorialOneNodes group, and then increments the tick count.

  18. Exit the RePast simulation by clicking on the exit button.