Tutorial Two


This second tutorial builds on the first by adding some additional features to our model. The numeric node labels will now be a random number between a user defined minimum and a user defined maximum. The intention here is to demonstrate what parameters are and how to use them and to illustrate how the compiler reports errors in your action code and how to fix them.
  1. Start RepastPy if it is not already started.

  2. Click on the open button on the toolbar or choose open from the file menu, and open the file where you saved the tutorial one project (e.g. tutorial1.sbp).

    You use "open" to load previously saved RepastPy models.

  3. Change the model Display Name to Tutorial 2, and the Model Name to TutorialTwoModel by clicking on the model node (labeled Tutorial 1) in the project pane, and changing the Display Name and Model Name properties appropriately.

  4. Rename the agent to TutorialTwoAgent and the Group Name to TutorialTwoAgentNodes by clicking on the agent in the project pane and changing the Name and Group Name properties appropriately.

  5. Save your project as tutorial2.sbp by choosing the "Save As" item from the file menu. Note that if you click the save button you will save the current project in tutorial1.sbp. "Save As" allows you save the current project to a new file.






In order to set the node labels to a random value between some user defined minimum and maximum, we need some way for the user to input new parameter values into the simulation once it is compiled and run. We do this by defining parameter fields in our model component. These parameters are then displayed in the parameters settings panel of the resulting Repast simulation. For example the image below displays the model parameters for the prisonner's dilemma demonstration model.




We want to add, then, model parameters such as these to our tutorial model.
  1. Click on TutorialTwoModel and click on the Fields property edit button. This will bring up the Fields Editor.




    You'll see several fields already defined. RepastPy will silently add fields to allow you to control your simulation once it is compiled and to allow you access to various other components from within the model code. In this case, the RepastPy-defined-fields that you see are created as part of choosing a random density network source. Changing the values of these parameters will change the structure of the initial network.

  2. In the fields editor fill in the following:

    • name: labelMin
    • type: int
    • DefaultValue: 10
    • Parameter: true (click it to check the box).

    So the editor will look like




    Then click add. You should see this new field added to the list of fields in the fields table.

    This adds a field called labelMin to TutorialTwoModel. This field is of type int meaning that it represents an integer and if we try to assign anything else to it, we will get an error. It will have a default value of 10 and is a parameter. By marking it as a parameter of the model, the parameter appears in the parameter settings pane of the resulting Repast simulation.

    In creating a field you create a variable of the same name that can be used from within a components actions, as we shall see below. However, by marking it as a parameter or as accessible you also create implicit accessor actions for that field, In this case, a getLabelMin action and a setLabelMin action are implicitly created. This allows other component's actions access to this field.

  3. In the parameter editor fill in the following:

    • name: labelMax
    • type: int
    • DefaultValue: 100
    • Parameter: true (click it check the box).

    Then click add. You should see it added to the list of fields in the fields table.




    This adds a field called labelMax with a default value of 100.

  4. Click ok in the parameter editor to register your parameter changes with RepastPy.

  5. Click on the actions property of TutorialTwoModel and choose the initAgents action if it is not already selected.

    Notice that the variables list now contains our new self.labelMax, and self.labelMin. The self here means that this variable is part of the component you are currently editing. If you want to refer to variables or actions that belong to the currently selected component, you need to prefix them with self.

  6. Delete the lines that read


    i = 1
    i = i + 1

    and add

    i = Random.uniform.nextIntFromTo(self.labelMin, self.labelMax)

    before agent.setNodeLabel("id - " + i)

    make sure that this new line is indented correctly. The new code should look like




    Random is a java class that provides random number distributions for Repast simulations. Here, you are drawing integer values between labelMin and labelMax from a uniform distribution. More info on Random can be found in the Repast javadoc documentation here

  7. Click ok to register your changes to the action property with RepastPy.

  8. Save the project. Its okay to overwrite your previous save file (e.g. tutorial2.sbp) by clicking the save button .

  9. Compile the project by pressing the compile button .

    At this point, the Actions Editor should pop-up and display an error in its Errors pane at the bottom of the editor.




    The error should read

    Block: default_package.TutorialTwoModel.initAgents, line: 1
    Compiler Error: Field 'tutorialOneNodes' is not accessible or not found in default_package.TutorialTwoModel
    for agent as TutorialOneAgent in self.tutorialOneNodes:

    This means that there is an error in the specified line in the specified action or block. In this case, the error is in line 1 of the initAgents action of the TutorialTwoModel component. The Compiler Error: line indicates the kind of error and the next line is the line where the error occured. The problem heres is

    in the line

    for agent as TutorialOneAgent in self.tutorialOneNodes:

    What this line does is iterate through all the agents in TutorialTwoModel's self.tutorialOneNodes group and treat each item in the group as a TutorialOneAgent. By treating each one as a TutorialOneAgent, the compiler can ensure that any code in the for loop that references agent (which is being treated as a TutorialOneAgent) is correct.

    The error means that the field self.tutorialOneNodes is either inaccessible or not found in the TutorialTwoModel, that is, the tuorialOneNodes is a not field of TutorialOneModel. The solution is very simple. Recall that we changed the Group Name of the TutorialTwoAgents to tutorialTwoNodes. Consequently, the fields tutorialOneNodes no longer exists in TutorialTwoModel. We can easily fix this by changing "tutorialOneNodes" to read "tutorialTwoNodes". To do this, you can just edit the offending line, or double click on the error itself to be taken to the line directly. One you have done that click OK.

  10. Save and compile the model. You'll see another error. This time the error reads:

    Block: default_package.TutorialTwoModel.initAgents, line: 1
    Compiler Error: Cast class 'TutorialOneAgent' not found
    for agent as TutorialOneAgent in self.tutorialTwoNodes:

    The error says that the cast class 'TutorialOneAgent' cannot be found. This means that the compiler is having trouble treating each item in the list as a TutorialOneAgent because it doesn't know what a TutorialOneAgent is. Recall that the items in the agent group tutorialTwoNodes are created from our agent component template. We renamed this template to TutorialTwoAgent and so the compiler doesn't know what a TutorialOneAgent is. So to fix the error we need to change TutorialOneAgent to TutorialTwoAgent.

  11. After you've edited the code click on OK to register your changes with the TutorialTwoModel component.

  12. Save and compile. You should not receive any errors this time.

  13. Run the simulation by clicking the run button (the green flag) on the RepastPy toolbar.

    The first thing to notice is the addition of the labelMax and labelMin parameters in the Model Parameters pane of the Repast simulation. As mentioned above, the other parameters are "silently" created from the random network source by RepastPy and can be edited to change how the random network is created.






  14. Click the step button to run one iteration of the simulation. You should see something like

    id - 47
    id - 41
    id - 30
    ...

    printed to the console. Of course your id numbers will most likely differ as the id number is now some random number between 10 and 100.

  15. Click the stop button on the RePast toolbar, and then the setup button .

    Stop stops the simulation run, and setup prepares it for another run by, among other things, setting the parameters back to their default values.

  16. Enter 1 in labelMin and 5 in labelMax.




    Press the step button. You should now see something like

    id - 5
    id - 3
    id - 2
    ...

    on the console. The point is that by defining fields in RepastPy which compile to parameters in the resulting Repast simulation you can alter the initial conditions of the simulation.

  17. Play with the parameters and do some runs, if you like. Then exit the simulation by pressing the exit button .