Programmatic Interaction with a Repast simulation model

1. Introduction

This article mainly introduces the steps on how to interact with a REPAST Simphony model, and gives a gaming example.

To run a simulation purely programmatically with fine control, you need to create a class that extends repast.simphony.engine.environment.AbstractRunner and modify to suit your needs. The runner class can then be used to initialize, step, run, pause, stop and reset the model. This approach uses components from the GUI which is totally user driven and the Batch run which is completely self-contained with no user-interaction.

If you want to fully interact with the model, e.g. to control a specific method within the model, you need to get the reference to the Context etc. To do this, simply call the RunState.getInstance().getMasterContext() function after each step.

2. Steps

There are only 4 simple steps to do this.

2.1 Before initialization:

• Set the parameters:
  

  ParametersCreator creator = new ParametersCreator();
  creator.addParameter("gridwidth", Integer.class, 4, true);
  creator.addParameter("gridheight", Integer.class, 4, true);
  creator.addParameter("randomSeed", Number.class, 3, true);
  params = creator.createParameters();
  

• Load the file and parameters:
  

  public void load(File scenarioDir) throws Exception {
    if (scenarioDir.exists()) {
  	BatchScenarioLoader loader = 
             new BatchScenarioLoader(scenarioDir);
  	ControllerRegistry registry = 
             loader.load(runEnvironmentBuilder);
  	controller.setControllerRegistry(registry);
    } else {
  	msgCenter.error("Scenario not found", 
                     new IllegalArgumentException(
  	           "Invalid scenario " + 
                     scenarioDir.getAbsolutePath()));
  	return;
    }
  
    controller.batchInitialize();
    controller.runParameterSetters(params);	
  }
  

2.2 Initialize the simulation:

public void runInitialize() {
	controller.runInitialize(params);
	schedule = RunState.getInstance().getScheduleRegistry()
			.getModelSchedule();
	context=RunState.getInstance().getMasterContext();	
}

2.3 Step run

public void step() {
	schedule.execute();
}

You should also implement your own logic within each step run. And you can get the Context after calling the step() method and then may control a specific method within the model.

2.4 Stop

By calling the stop method, you should also clean up all the actions within the contexts. Here are the methods you may use:

// stop the schedule
public void stop() {
	if (schedule != null)
	schedule.executeEndActions();
}

public void cleanUpRun() {
	controller.runCleanup();
}

public void cleanUpBatch() {
	controller.batchCleanup();
}

Example

Here is a simple example of how to interact with a REPAST model.

The diagrams above give us the basic components and the sequence on interaction with the REPAST model. This model simply stands for a Tic-Tac-Toe game. Human uses the frontend to play with the computer which is built by REPAST agent.

Here we just use only four ports that REPAST model provides. Three of them we've already discussed above. For the play() method, it's a specific method you write in a certain model. To get this method outside the model, just call RunState.getInstance().getMasterContext(), and you will get the Context and have the method name and other properties you need. You can also wrap up those mentioned method into a middleware for a visualized frontend to invoke.

The basic interaction logic is:

The frontend calls the start to the middleware, then the middleware initialize the model and call step once to get to step one. After the initialization, human may moves first, so calls play once to the middleware, and the middleware notes the position he plays and pass it to the model behind. The simple strategy for the game judgement of the model is to check if there is a winner or draw game after each move, if not, the game goes on and return the position the computer plays.