GIS Model

 GIS Model

This is the default model for creating simulations that take place on a GIS topology and whose agents can be created from a shape file.

Appropriate Parent Component

Project. The GIS model is added to an Environemt component.

Properties

Properties are the items that appear in the property pane when you click on a component in the project tree. For more information of properties, see here.

Name     Description
Actions See the section on Actions and editing them if you are unfamiliar with Actions.

GIS Model includes a three default actions.

  • initAgents This action will be executed at the beginning of the simulation as part of set up. This action will execute after the agents have been created and added to their respective groups. Consequently, you can iterate through an agent group and perform any additional custom initialization. For example,

    for agent as VectorAgent in self.vectorAgentGroup:
      agent.init()

    which will iterate through all the agents in the vectorAgentGroup group and call the init() action on them. This assumes of course, that you have created an init action for your VectorAgent component.

  • updateDisplay This action will update the GIS display. Note that if you are using ArcGIS as the GIS display, you must call the writeAgents action prior to updateDisplay in order to see the current state of the agents. In addition, if you are working with ArcGIS, the default implementation of updateDisplay assumes that you have installed RepastPy in c:\Program Files\repastpy and that the file Refresh.exe is in c:\Program Files\repast\Refresh. If this is not the case, then you can change the default code in updateDisplay

    self.updateGISDisplay()

    to

    self.updateGISDisplay(path_to_Refresh.exe)

    For example, self.updateGISDisplay("c:\\repastpy\\Refresh")

  • writeAgents This action writes an VectorAgents you have defined back to a specified shapefile, in effect updating the features and attributes in that shapefile with those from your VectorAgent. In order to use this action, you need to edit it. The default code reads:

    #self.writeAgents(your_agentGroup_here, your_shapefile_here)

    In order to use the action, you need to remove the comment marker ("#"); replace, "your_agentGroup_here" with the name of the group of VectorAgents that you want to save; and replace "your_shapefile_here" with the path to the shapefile where you want to save the agents. For example,

    self.writeAgents(self.vectorAgentGroup, "c:\\projects\\shapefiles\\test.shp")

Display Name This name will be displayed as the title of your model when it is running.
GIS Package Here you can choose which GIS package you will use to display and manipulate your GIS based simulation. The two choices are ArcGIS, and OpenMap. Choosing ArcGIS assumes you have ArcMap running and loaded with the shapefile that is the data source for your agents. See the section entitled GIS packages below for more information.
Master Schedule See the schedule help and tutorial 3 for more information on schedules and scheduling.

The master schedule property gives you an editable view of all the scheduled actions in relation to each other. You can edit their relative order here. By default, the step action of every agent is scheduled to execute every iteration of the simulation beginning at the first iteration.

Model Name The name of the model used internally by Repast Py during compilation.The java class created by Repast Py uses this name and normally it need not be changed.
Fields See the the Fields section of the help docs for information on creating and editing fields. Here you can define any fields you want your model to have.
Schedule See the schedule help and tutorial 3 for more information on the schedule property. The schedule property defines the execution schedule of any actions defined in your model.



Implicit Fields

Implicit Fields are variables that RepastPy exposes for your use in code. For example, if there is an implicit field named agentGroup, you can refer to that field with self.agentGroup in your NQPy code.

Name     Description
Agent Groups For each type of agent that you create, Repast Py creates a DefaultGroup (a Java class) that contains all the agents of that type. The name of this variable is the value of the Agent Component's Group Name property. For example, if the group name is "agents" then Repast Py will create a Default Group called "agents". You can access this group from within model actions with self.groupName (e.g. self.agents). These groups are also exposed via a "get" accessor method. So, assuming you have a reference to the model, you can do something like model.getGroupName() (e.g. self.getAgents()). A Default Group in general behaves much like an indexable list. So, you can do things like

agent = self.agents[3]

to get the third agent in the list, and

numAgents = self.agents.size()

to get the size of the Default Group and so on.



GIS Packages

The major difference between the two GIS packages supported by repastpy is that depending on which you chose the geometry object that you will be working with is different.

  • If you choose ArcGIS, the underlying geometry object will be in the com.vividsolutions.jts.geom package, and mostly likely of the MultiPolygonType. You can get more information about these sorts of geometry types at http://www.vividsolutions.com/JTS/doc.htm

  • If you choose OpenMap, the underlying geometry object will be of the com.bbn.openmap.omGraphics.OMGraphic. You can find more information about this type at http://openmap.bbn.com/doc/api/.

Depending on which GIS package you are using, ArcGIS or OpenMap, RepastPy and Repast provide two GIS utility classes. These are GeotoolsData and OpenMapData. The first used with the ArcGIS package and the second with OpenMap. Using these class, you can, for example, read and write VectorAgents to a shapefile and so forth. Further documention of these are at OpenMapData and GeotoolsData.

You use these classes in your own actions just as you would any other class. For example, to determine the center of a VectorAgent using the OpenMapData class, you would do

center = OpenMapData.getInstance().getCenter(self)

where self is the VectorAgent. Note that the getCenter method returns its result as a LatLonPoint. More information about LatLonPoints can be found at http://openmap.bbn.com/doc/api/.



Java Parent Class

Many of the RepastPy components are based on Java code. What this means is that these components come with built-in fields and methods inherited from their Java parent classes. The docs below describe these built in fields and methods.

GIS Model is based on SimModelImpl. SimModelImpl is a partial implementation of the SimModel interface. Most, if not all, actual models will inherit from this class. By default SimModelImpl initializes the random number generator in the Random class using the current timestamp as a seed. Random can then be used for random number generator. If you need to have two random number streams with different seeds, you'll need to make your own. See the random number how to in repast/docs/how_to/random.html for more information. When data is collected from a model, it is this seed for this rng that is written out.


The fields of a Java parent class can be used just as if they were fields in your own model. For example, self.descriptors and so on. The format used below is

field name : field type
description

where the field type is a Java class type.

Java Parent Class Fields
descriptors : Hashtable
Used to store property descriptors. The key should be the property or parameter name and the value the descriptor associated with that property.

modelManipulator : ModelManipulator
A ModelManipulator that can be used to manipulate the model at run time.


The methods or actions of a Java parent class can be used just as if they were actions in your own model. For example, self.setRngSeed(33) and so on. The format used below is

method name(argument types, if any) : return type - an optional explanation of the return type
description

where the return type is a Java class type.

Java Parent Class Methods (Actions)
addPropertyListener( PropertyListener ) :
Adds a PropertyListener to this model.

addSimEventListener( SimEventListener ) :
Adds a SimEventListener to listen for SimEvents broadcast from this model.

clearMediaProducers( ) :
Clears the vector of media producers.

clearPropertyListeners( ) :
Clears the list of PropertyListeners.

fireBooleanPropertyEvent( PropertyEvent ) :
Broadcasts a boolean property event to all this model's PropertyEventListeners.

fireEndSim( ) :
Broadcasts a SimEvent with an id of SimEvent.END_EVENT to all this model's listeners.

fireNumericPropertyEvent( PropertyEvent ) :
Broadcasts a numeric property event to all this model's PropertyEventListeners.

fireObjectPropertyEvent( PropertyEvent ) :
Broadcasts an object property event to all this model's PropertyEventListeners.

firePauseSim( ) :
Broadcasts a SimEvent with an id of SimEvent.PAUSE_EVENT to all this model's listeners.

fireSimEvent( SimEvent ) :
Broadcast the specified SimEvent to all this model's SimEventListeners

fireStopSim( ) :
Broadcasts a SimEvent with an id of SimEvent.STOP_EVENT to all this model's listeners.

fireStringPropertyEvent( PropertyEvent ) :
Broadcasts a string property event to all this model's PropertyEventListeners.

generateNewSeed( ) :
Generates a new seed for the random number generator using the current timestamp.

getAgentList( ) : ArrayList
Gets list of agents controlled by this model.

getController( ) : IController
Gets the BaseController associated with this model.

getMediaProducers( ) : Vector
Gets the mediaProducers registered with this model. The returned vector will contain a ProducerNamePair objects.

getModelManipulator( ) : ModelManipulator
Gets the ModelManipulator.

getParameterDescriptors( ) : Hashtable
Gets a hashtable of ParameterDescriptors where key is parameter name, and value is the ParameterDescriptor.

getPropertiesValues( ) : String - a list of the model parameters and values.
Gets a String listing the model parameters and values.

For example,
MaxVision: 3
MaxMetabolism: 4
NumAgents: 52

getRngSeed( ) : long
Gets the current random seed.

getTickCount( ) : double
Gets the current tick count

pause( ) :
Pause the simulation.

registerDisplaySurface( String , DisplaySurface ) :
Registers a DisplaySurface with this model and associates it with a particular name.

registerMediaProducer( String , MediaProducer ) :
Registers a MediaProducer with this model and associates it with the specified name.

removePropertyListener( PropertyListener ) :
Removes a PropertyListener from this model.

removeSimEventListener( SimEventListener ) :
Removes a SimEventListener from the list of listeners listening for SimEvents broadcast from this model.

setController( IController ) :
Sets the controller associated with this model

setRngSeed( long ) :
Sets the random number generator in Random to a new value. Note this will invalidate any distributions created with Random. These will need to be recreated.

stop( ) :
Stops the simulation.

writeAgents( Collection , String ) :
writes the agents in the specified Collection out to the the shapefile specified in the String. Note that this shapefile must be the original one from which they agents were created.

writeAgents( Collection , String, String ) :
writes the agents in the specified Collection out to a new shapefile. The first String argument is the path of the original shapefile from which the agents were created and the second String argument is the path to the new shapefile.