Citizen class documentation

Authors

Generated by pauljohn

Software documentation for the Citizen class

Citizen : Swarm

Declared in:

Citizen.h

The Citizen is the root agent in this model. This class has the key record-keeping and scheduling role.

We do not ever intend that this class should be instantiated. Rather, subclasses which implement particular theories should be written and used in the models. The Citizen class contains general purpose variables and methods that we exect all subclasses are likely to need.

Subclassing Guide For starters, we suggest you allow Citizen's step method to work as it is. If you allow step to be called, it will control movement and will tell the agent to interact. The interact method will cause the agent to find someone and discuss with them. In order for this to function, it is necessary for a subclass to override these two methods:

- selectADiscussantInPosition: (Position *)position;

- adjustOpinionAgainst: other;

There are a number of class variables and class methods. Class variables save on storage because one value is set and used by all agents. The Class methods are the ones that begin with plus signs. There are a number of advantages in using Class methods and variables in the serialization part of this program. Class values need not be serialized, rather they are easily set at runtime.

Each Citizen has personal stances or opinions that we are calling "culture" in honor of Robert Axelrod. Original versions of this model benefitted greatly from the assistance of Rick Riolo of the University of Michigan and Lars Erik Cederman of UCLA.

The culture is kept in an integer array. The number of opinions is set by the numCultureFeatures parameter. The number of positions that exist for each issue is set by the numCultureTraits parameter. Every citizen holds some position on each issue at all times. The initial positions are assigned by code in the ModelSwarm. Typically, opinions are randomly assigned.

Each citizen is aware of various "positions" (2D grids) in which it can interact. One position is the home grid, another is the work grid. To allow the possibility that a model might have agents with many positions they would visit, we have put all positions into a Swarm Array, positions.

The Citizen class has vital record keeping tools, including the moving averages that summarize the experiences of the agents. These keep track of the rate of acquaintance among agents, the rate of similarity, and identicality (a word?).

Citizen also has machinery to schedule agent actions and move agents around.

We expect that subclasses will handle the problems of choosing discussants, and responding to the interaction. Some methods are included in this class to keep track of experiences/observations, and they can be used in subclasses.

The one method that is vital for any sublcass is "interact". In the root class Citizen, this is the method that chooses a discussant and then responds to the interaction. Since interact calls both the "selectADiscussantInPosition" and "adjustOpinionAgainst:" methods, then the subclass must either override interact or it must do something about selecting discussants and responding to them. Note the subclass HJCitizen is mainly about choosing discussants differently and responding to them strategically. Not that this class has code in it that mandates that a subclass must implement these last two methods.

• +getNumCultureFeatures
• +getNumCultureTraits
• +getObserverSwarm
• +setConsistentAdjustment:
• +setDayLength:
• +setModelSwarm:
• +setNumCultureFeatures:
• +setNumCultureTraits:
• +setObserverSwarm:
• +setOnlyOneAdjusts:
• +setOnlySelfAdjusts:
• +setParochialism:
• +setWrapAround:
• -activateIn:
• -adjustOpinionAgainst:
• -bareLispOutDeep:
• -becomeUnavailable
• -buildActions
• -buildObjects
• -changeFeature:to:
• -computeSimilarityWith:
• -createAttribute:
• -createEnd
• -describeInteractionWith:
• -drawColor:
• -getAgentName
• -getChangeFlag
• -getContacts
• -getCultureArray
• -getCultureFeature:
• -getFeature:
• -getFlexibility
• -getIDNumber
• -getInteractionFlag
• -getNContacts
• -getNFriends
• -getPerceivedAcquaintance
• -getPerceivedHarmony
• -getPerceivedIdentical
• -goHome
• -grabRandomPersonInPosition:Parochialism:
• -interact
• -lispInReset
• -moveToOtherPosition
• -moveToPosition:
• -pulseFeature:Magnitude:
• -sayHi
• -scheduleAvailablePosition:Start:
• -scheduleInteractionTime:
• -scheduleMeAgain:
• -scheduleSleepAt:
• -selectADiscussantInPosition:
• -setAgentName:
• -setChangeFlag:
• -setFeature:to:
• -setFlexibility:
• -setHomeDuration:
• -setIDnum:
• -setInteractionFlag:
• -setPosition:GridN:atX:Y:
• -setPosition:X:Y:
• -setSchedule:
• -showContacts
• -showFriends
• -step
• -updateAcqRecord:
• -updateAttribute:Total:Selected:
• -updateContactRecord:Feature:Similarity:
• -updateSimilarityRecords:

getNumCultureFeatures 

Returns the number of issues/features that this class is using.

getNumCultureTraits 

Returns the number of opinions (traits) that the agents might hold for each issue/feature

getObserverSwarm 

Return the observerSwarm that objects of type Citizen are using

setConsistentAdjustment: 

Set the consistentAdjustment parameter

setDayLength: 

The dayLength is the number of timesteps that are considered as a separate time frame for the agent. The day begins at home and the agent should return there at the end of the day

setModelSwarm: 

When agents change their opinions, they tell the centralized record keeper about it. This method tells the agent who the record keeper is.

setNumCultureFeatures: 

Methods that set/get fixed features common to all citizens (Class Variables)
A class method that sets the number of issues/culture features. All agents are able to access the variable numCultureFeatures.

setNumCultureTraits: 

A class method that sets the number of culture traits. All agents are able to access the variable numCultureTraits.

setObserverSwarm: 

Sometimes it is useful to let the agent know the location of the class that is drawing graphs in the simultion. This does it.

setOnlyOneAdjusts: 

In Axelrod's original model, only one agent could change as a result of interaction. We wanted to generalize a bit, so we created these toggles.

setOnlySelfAdjusts: 

These control adjustment: to self, to other, to both?
Set the YES or NO variable indicating only the agent who initiates the interaction--self--is able to change its opinion in response to the interaction.

setParochialism: 

Set the parochialism parameter. This is the probability that an agent will look outside its current cell for a discussion partner. This is relevant only when there is more than one agent in a cell.

setWrapAround: 

Do agents look for discussants within the truncated VonNeumann neighborhood? If yes, then wrapAround is YES. If no, then the grid in the position has to be a torus, and wrapAround is NO

activateIn: 

If the NO_MASTER_SCHEDULE CPP flag is used, then each agent is a Swarm unto itself, and so it has to create a schedule and activate its schedule within the larger condext. This ties the agent's schedule into the time stepping of the system.

adjustOpinionAgainst: 

All sublcasses must know how to adjustOpinionAgains: another agent

bareLispOutDeep: 

For serialization, each agent needs to dump out its instance variables, so that the agent can be brought back to life in exactly the same state.

becomeUnavailable 

Remove self from locations in which others can reach for interaction

buildActions 

Create the schedule on which actions can be placed. This is only used if there is no master schedule.

buildObjects 

"Initialize Classes that require zone allocations
When a Citizen object is created, several record keeping objects must be created. This method creates those objects.

changeFeature: to: 

This does two things. It changes the culture feature f to v, and it also reports that change to the record keeper, the ModelSwarm.

computeSimilarityWith: 

Take a culture array and find out how many elements are the same as agent's own culture, and return that integer value

createAttribute: 

Create an attribute record for a contact. That means create an object where data about the other can be stored. Also it inserts that Attribute into the contacts map, which agents can use to lookup these attributes.

createEnd 

Initialize important instance variables
Finalizes the creation of objects from Citizen, and in so doing it sets initial values for a number of start-time variables.

describeInteractionWith: 

For diagnostic information about the agent and his discussant

drawColor: 

Sometimes, such as in showContacts, we want agents to be able to signal to us by drawing on the raster. Since the rasters represent only the home positions, this method gets world 0 and draws a color there.

getAgentName 

Description forthcoming.

getChangeFlag 

Return YES or NO indicating that the agent has changed an opinion/trait during the current step

getContacts