Sugarscape
Class Citizen

java.lang.Object
  Sugarscape.Citizen

class Citizen

extends java.lang.Object

The Citizen object is modeled on a human being. It possesses attributes like location, vision, metabolism rates, resource stockpiles, parents, sex etc.
Each Citizen lives a randomly determined lifespan during which they gather & eat food, seek & select mates, bear children, trade to increase their wealth, inherit wealth upon the death of parents etc.
As the simulation is developed further, these citizens become more capable and are able to partake in more complex tasks. They function absolutely at a local level and are unaware of external influences beyond their immediate surroundings.
Collectively however I hope their actions add to our understanding of how communal behavior, that cannot be explained solely from individual actions, emerges.

Author:

abraham kannankeril

Field Summary

(package private) int	birthYear
(package private) java.lang.String	causeOfDeath
(package private) java.util.List	childList
(package private) static int	citizenID
(package private) java.lang.String	cultureTag
(package private) java.lang.String	family
(package private) int	father
(package private) static int	HIGH_ENDOWMENT_SPICE
(package private) static int	HIGH_ENDOWMENT_SUGAR
(package private) int	homeCol
(package private) int	homeRow
(package private) int	id
(package private) float	inheritSpice
(package private) float	inheritSugar
(package private) int	lastMating
(package private) int	lifeSpan
(package private) int	metabSpice
(package private) int	metabSugar
(package private) int	mother
(package private) float	MRS
(package private) int	persona
(package private) int	ranking
(package private) int	sex
(package private) float	spice
(package private) int	spUnits
(package private) float	sugar
(package private) static java.util.List	surnames
(package private) int	surplus
(package private) int	suUnits
(package private) int	TUD
(package private) int	vision

Constructor Summary

Citizen()
Base constructor for the Citizen object.

Citizen(Citizen citizen, Citizen mate, int col, int row)
Constructor used to create citizen object inheriting attributes from a pair of parent Citizen objects.

Citizen(int col, int row)
Constructor used to create new citizen object inside a cell object.

Method Summary

int	addChild(Citizen child) Adds citizen to child list.
int	checkChildren() Returns count of children in the child list.
private int	createFamilyNameList() The following collections is randomly assigned to the initial inhabitants.
static java.lang.String	customFormat(java.lang.String pattern, double value) Method to format float and double vars for display on screen.
boolean	eatSpice() Subtracts one consumption unit (spice metabolism) from the spice stockpile.
boolean	eatSugar() Subtracts one consumption unit (sugar metabolism) from the sugar stockpile.
int	getAge() Returns the age, defined as the birth year subtracted from the current cycle or time period.
int	getBirthYear() Returns the cycle or time period when the citizen was born.
java.lang.String	getCauseOfDeath() Returns a string describing the citizen's cause of death.
int	getCol() Returns the column on the grid where the citizen is located.
java.lang.String	getFamily() Returns a string identifying the citizen's family.
int	getFather() Returns a numeric code uniquely identifying the citizen's father.
int	getID() Returns a unique identification number for the citizen.
float	getInheritSpice() Returns the spice inherited by the citizen from its parents.
float	getInheritSugar() Returns the sugar inherited by the citizen from its parents.
int	getLastMating() The cycle or time period when the citizen last mated successfully.
int	getLifeSpan() Returns the expected lifespan of the citizen.
int	getMetabSpice() Returns the value representing the citizen's metabolic rate for spice.
int	getMetabSugar() Returns the value representing the citizen's metabolic rate for sugar.
int	getMother() Returns a numeric code uniquely identifying the citizen's mother.
float	getMRS() Calculated value.
Citizen	getNextChild(int childIndex) Returns next child on list, null if no more children.
int	getPersona()
int	getRanking() Returns the ranking previously calculated for the citizen.
int	getRow() Returns the row on the grid where the citizen is located.
float	getSpice() Returns the value representing the citizen's spice stockpile.
int	getSpUnits() Calculated value, depicting the number of units of spice available to the citizen.
float	getSugar() Returns the value representing the citizen's sugar stockpile.
int	getSurplus() Returns the surplus available for trade.
int	getSuUnits() Calculated value, depicting the number of units of sugar available to the citizen.
int	getTUD() Returns an estimated Time Until Death.
int	getVision() Returns the value representing the vision of the citizen.
boolean	hasSurplus() Returns true if the citizen has enough sugar to support prospective offspring.
boolean	isAlive() Returns true if the citizen is still within the lifespan determined at birth.
boolean	isCautious() Returns true, if the personality type for the citizen is risk-averse OR below the poverty level as defined by GoLconst.SUGAR_LEVEL_POOR and GoLconst.SPICE_LEVEL_POOR
boolean	isChild() Returns true if the citizen's age falls within the range that defines childhood.
boolean	isChildOf(Citizen zenB) Returns true if citizen is a child of the citizen passed as a parameter to this method..
boolean	isKinOf(Citizen zenB) Returns true if citizen is related to the citizen passed as a parameter to this method.
boolean	isMale() Returns true if the citizen is of the 'male' sex.
boolean	isParentOf(Citizen zenB) Returns true if citizen is a parent of the citizen passed as a parameter to this method.
boolean	isPoor() Returns true if sugar or spice consumption units are less than or equal to wealth levels specified in the global constants (GoLconst.java) file.
boolean	isSenior() Returns true if the citizen's age falls within the range that defines senior citizens.
boolean	isSiblingOf(Citizen zenB) Returns true if two citizens share both parents.
boolean	needsSpice() Returns true when citizen is 'Risk-Averse' and MRS < 1.
boolean	needsSugar() Returns true when citizen is 'Risk-Averse' and MRS > 1.
boolean	ofCompatibleSex(Citizen zenB) Returns true if the two prospective mates belong to the opposite sex.
boolean	ofMatingAge() Returns true if the citizen's age falls between the range of values signifying childhood and old age.
void	paintZen(java.awt.Graphics g, int cellSize) Paints the citizen in to one of eight possible shapes The classification comprises eight categories and are representedgraphically as icons drawn using a combination of ovals and rectangles.
boolean	pastMatingInterval() Returns true if the period specified in the global constants file has passed since the last successful mating for the citizen.
static boolean	preferSame(float MRSA, float MRSB) Returns true if two MRS values supplied as parameters have a preference for the same good.
boolean	prefersSpice() Returns true when MRS < 1.
boolean	prefersSugar() Returns true when MRS > 1.
static void	resetID() Resets the variable that is used to generating unique ID's for each new citizen.
void	setCauseOfDeath(java.lang.String cause) Stores the string describing cause of death in citizen.
void	setCol(int col) Stores the column representing a current or designated location within the citizen object.
private void	setFamily()
private void	setFamily(Citizen citizen, Citizen mate)
static int	setID() Returns a unique numeric ID and increments it in preparation for the next request.
private void	setInheritAttributes(Citizen citizen, Citizen mate) Randomly choses newborn child's genetic attributes from one or the other parent.
void	setLastMating(int generation) Updates last mating of citizen to current cycle or time period.
void	setLifeSpan(int ageVal) Sets citizen lifespan to a specified or random value.
int	setMetabSpice(int metabolismVal) Sets citizen spice metabolism to a specified or random value.
int	setMetabSugar(int metabolismVal) Sets citizen sugar metabolism to a specified or random value.
float	setMRS() Calculates value.
private void	setParents(Citizen citizen, Citizen mate)
int	setPersona() Sets citizen vision to a random value.
int	setRanking() Recalculates ranking for citizen.
void	setRow(int row) Stores the row representing a current or designated location within the citizen object.
int	setSex() Sets citizen sex to a specified or random value.
float	setSpice(float spiceVal) Sets citizen spice to a specified or random value.
int	setSpUnits() Calculates value, depicting the number of units of spice available to the citizen.
float	setSugar(float sugarVal) Sets citizen sugar to a specified or random value.
int	setSurplus() Calculates and returns the surplus available for trade.
int	setSuUnits() Calculates value, depicting the number of units of sugar available to the citizen.
int	setTUD() Calculates and returns an estimated Time Until Death.
int	setVision(int visionVal) Sets citizen vision to a specified or random value.
java.lang.String	showStats(java.lang.String message) Returns a string describing some of the key attributes for the citizen.
private void	transferWealth(Citizen citizen, Citizen mate)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

birthYear

int birthYear

causeOfDeath

java.lang.String causeOfDeath

childList

java.util.List childList

citizenID

static int citizenID

cultureTag

java.lang.String cultureTag

family

java.lang.String family

father

int father

HIGH_ENDOWMENT_SPICE

static int HIGH_ENDOWMENT_SPICE

HIGH_ENDOWMENT_SUGAR

static int HIGH_ENDOWMENT_SUGAR

homeCol

int homeCol

homeRow

int homeRow

id

int id

inheritSpice

float inheritSpice

inheritSugar

float inheritSugar

lastMating

int lastMating

lifeSpan

int lifeSpan

metabSpice

int metabSpice

metabSugar

int metabSugar

mother

int mother

MRS

float MRS

persona

int persona

ranking

int ranking

sex

int sex

spice

float spice

spUnits

int spUnits

sugar

float sugar

surnames

static java.util.List surnames

surplus

int surplus

suUnits

int suUnits

TUD

int TUD

vision

int vision

Constructor Detail

Citizen

public Citizen()

Base constructor for the Citizen object. Used to initialize temporary variables of type Citizen.

Citizen

public Citizen(Citizen citizen,
               Citizen mate,
               int col,
               int row)

Constructor used to create citizen object inheriting attributes from a pair of parent Citizen objects.

Parameters:

citizen - parent of newborn citizen.

mate - parent of newborn citizen.

col - column identifying cell where citizen is to be created.

row - row identifying cell where citizen is to be created.

Citizen

public Citizen(int col,
               int row)

Constructor used to create new citizen object inside a cell object. Citizen object initialized to random attributes.

Parameters:

col - column identifying cell where citizen is to be created.

row - row identifying cell where citizen is to be created.

Method Detail

addChild

public int addChild(Citizen child)

Adds citizen to child list.

Parameters:

child - newborn to be added to list of children born in current cycle.

checkChildren

public int checkChildren()

Returns count of children in the child list.

createFamilyNameList

private int createFamilyNameList()

The following collections is randomly assigned to the initial inhabitants. The method creates a list of surnames from which names are randomly assigned to new citizens created at the beginning of each simulaton. The 2000 names in the list were picked from a list of most popular surnames in USA that was posted online.

Returns:

number of items left in surname list.

See Also:

GoLconst.CREATE_UNIQUE_SURNAMES

customFormat

public static java.lang.String customFormat(java.lang.String pattern,
                                            double value)

Method to format float and double vars for display on screen.

Parameters:

pattern - format pattern.

value - float/double value to format.

Returns:

string containing formatted value.

eatSpice

public boolean eatSpice()

Subtracts one consumption unit (spice metabolism) from the spice stockpile.

eatSugar

public boolean eatSugar()

Subtracts one consumption unit (sugar metabolism) from the sugar stockpile.

getAge

public int getAge()

Returns the age, defined as the birth year subtracted from the current cycle or time period.

getBirthYear

public int getBirthYear()

Returns the cycle or time period when the citizen was born.

getCauseOfDeath

public java.lang.String getCauseOfDeath()

Returns a string describing the citizen's cause of death.

getCol

public int getCol()

Returns the column on the grid where the citizen is located.

getFamily

public java.lang.String getFamily()

Returns a string identifying the citizen's family. The family name is usually inherited from the father and currently has no relevance.

getFather

public int getFather()

Returns a numeric code uniquely identifying the citizen's father.

getID

public int getID()

Returns a unique identification number for the citizen.

getInheritSpice

public float getInheritSpice()

Returns the spice inherited by the citizen from its parents.

getInheritSugar

public float getInheritSugar()

Returns the sugar inherited by the citizen from its parents.

getLastMating

public int getLastMating()

The cycle or time period when the citizen last mated successfully. Minimum gaps between successive mating periods can be configured in the global constants (GoLconst.java) file.

getLifeSpan

public int getLifeSpan()

Returns the expected lifespan of the citizen.

getMetabSpice

public int getMetabSpice()

Returns the value representing the citizen's metabolic rate for spice.

getMetabSugar

public int getMetabSugar()

Returns the value representing the citizen's metabolic rate for sugar.

getMother

public int getMother()

Returns a numeric code uniquely identifying the citizen's mother.

getMRS

public float getMRS()

Calculated value. Represents the Marginal Rate of Substitution of spice for each unit of sugar.

getNextChild

public Citizen getNextChild(int childIndex)

Returns next child on list, null if no more children.

Parameters:

childIndex - index pointing to a specific child in the child list.

getPersona

public int getPersona()

Returns:

getRanking

public int getRanking()

Returns the ranking previously calculated for the citizen. This influences the likelihood of selection by other citizens looking to mate.

getRow

public int getRow()

Returns the row on the grid where the citizen is located.

getSpice

public float getSpice()

Returns the value representing the citizen's spice stockpile.

getSpUnits

public int getSpUnits()

Calculated value, depicting the number of units of spice available to the citizen. Each unit is equal to the metabolic rate for spice.

getSugar

public float getSugar()

Returns the value representing the citizen's sugar stockpile.

getSurplus

public int getSurplus()

Returns the surplus available for trade. Surplus is defined as the amount of any one good that is in excess of what is required to ensure TUD is not negatively affected.

getSuUnits

public int getSuUnits()

Calculated value, depicting the number of units of sugar available to the citizen. Each unit is equal to the metabolic rate for sugar.

getTUD

public int getTUD()

Returns an estimated Time Until Death. Based on sugar & spice consumption units available. Is taken as the lower of the two values and assumes no more goods are added to the citizen's stockpile.

getVision

public int getVision()

Returns the value representing the vision of the citizen.

hasSurplus

public boolean hasSurplus()

Returns true if the citizen has enough sugar to support prospective offspring.

isAlive

public boolean isAlive()

Returns true if the citizen is still within the lifespan determined at birth.

isCautious

public boolean isCautious()

Returns true, if the personality type for the citizen is risk-averse OR below the poverty level as defined by GoLconst.SUGAR_LEVEL_POOR and GoLconst.SPICE_LEVEL_POOR

See Also:

SUGAR_LEVEL_POOR, SPICE_LEVEL_POOR

isChild

public boolean isChild()

Returns true if the citizen's age falls within the range that defines childhood.

isChildOf

public boolean isChildOf(Citizen zenB)

Returns true if citizen is a child of the citizen passed as a parameter to this method..

Parameters:

zenB - other citizen whose relation is being examined.

isKinOf

public boolean isKinOf(Citizen zenB)

Returns true if citizen is related to the citizen passed as a parameter to this method. The relation could be that of a parent, child or sibling.

Parameters:

zenB - other citizen whose relation is being examined.

isMale

public boolean isMale()

Returns true if the citizen is of the 'male' sex.

isParentOf

public boolean isParentOf(Citizen zenB)

Returns true if citizen is a parent of the citizen passed as a parameter to this method.

Parameters:

zenB - other citizen whose relation is being examined.

isPoor

public boolean isPoor()

Returns true if sugar or spice consumption units are less than or equal to wealth levels specified in the global constants (GoLconst.java) file.

See Also:

SUGAR_LEVEL_POOR, SPICE_LEVEL_POOR

isSenior

public boolean isSenior()

Returns true if the citizen's age falls within the range that defines senior citizens.

isSiblingOf

public boolean isSiblingOf(Citizen zenB)

Returns true if two citizens share both parents.

Parameters:

zenB - other citizen whose relation is being examined.

needsSpice

public boolean needsSpice()

Returns true when citizen is 'Risk-Averse' and MRS < 1. This indicates that the citizen will only trade for spice.

needsSugar

public boolean needsSugar()

Returns true when citizen is 'Risk-Averse' and MRS > 1. This indicates that the citizen will only trade for sugar.

ofCompatibleSex

public boolean ofCompatibleSex(Citizen zenB)

Returns true if the two prospective mates belong to the opposite sex.

Parameters:

zenB - other citizen whose relation is being examined.

ofMatingAge

public boolean ofMatingAge()

Returns true if the citizen's age falls between the range of values signifying childhood and old age. These values can be configured in the global constants file.

paintZen

public void paintZen(java.awt.Graphics g,
                     int cellSize)

Paints the citizen in to one of eight possible shapes The classification comprises eight categories and are representedgraphically as icons drawn using a combination of ovals and rectangles. These geometric shapes may be filled or hollow.
Each citizen is represented by combining two circles (the figure eight) or rectangles (ladder) placed one below the other. The choice of shapes is determined by the 'vision' property of the citizen. The '8' signifies a high and the 'ladder' signifies a low-value for vision. It follows that a citizen with a high vision will move around more vigorously, hence the term 'hyper'. Conversely the 'ladder' citizens will move at a more liesurely pace and are categorized as 'slow'.
Each circle & rectangle component of these icons may be 'filled' to signify a low metabolic rate or 'hollow' to signify a high metabolism.
Finally, the color of these icons indicate the level of their food stockpiles. This may range from lighter shades of red indicating near-zero (< 10)consumption units, to yellow indicating resonably sufficient reserves (> 10 & < 100), to green indicating more than a normal lifetime (> 100) supply of food.
The table below summarizes the eight categories,

• Hyper citizens with high vision and metabolism values.
• Hyper, prefer Sugar citizens with high vision & sugar metabolism but low spice metabolism. These are said to prefer sugar.
• Hyper, prefer Spice citizens with high vision & spice metabolism but low sugar metabolism.
• Efficient citizens with high vision and low metabolism values.
• Inefficient citizens with low vision and high metabolism values.
• Slow, prefer Sugar citizens with low vision & spice metabolism but high sugar metabolism.
• Slow, prefer Spice citizens with low vision & sugar metabolism but high spice metabolism.
• Slow citizens with low vision and metabolism values.

Parameters:

g - the handle to the graphics object that provides access to all drawing methods.

cellSize - current cell size

pastMatingInterval

public boolean pastMatingInterval()

Returns true if the period specified in the global constants file has passed since the last successful mating for the citizen.

preferSame

public static boolean preferSame(float MRSA,
                                 float MRSB)

Returns true if two MRS values supplied as parameters have a preference for the same good. This indicates that both citizens whose MRS are being compared prefer the same good. Thus if both MRS are less than one, both prefer spice, if both MRS are greater than one, both prefer sugar. Note: this rules out a trade only if both parties are risk-averse. A trade can always be made such that both parties benefit except when both have the same MRS.

Parameters:

MRSA - Marginal Rate of Substitution of spice to sugar for Citizen

MRSB - Marginal Rate of Substitution of spice to sugar for Trader.

prefersSpice

public boolean prefersSpice()

Returns true when MRS < 1. This indicates that the citizen possesses a surplus of sugar and has a greater preference for spice.

prefersSugar

public boolean prefersSugar()

Returns true when MRS > 1. This indicates that the citizen possesses a surplus of spice and has a greater preference for sugar.

resetID

public static void resetID()

Resets the variable that is used to generating unique ID's for each new citizen.

setCauseOfDeath

public void setCauseOfDeath(java.lang.String cause)

Stores the string describing cause of death in citizen.

Parameters:

cause - String explaining cause of death.

setCol

public void setCol(int col)

Stores the column representing a current or designated location within the citizen object.

Parameters:

col - column identifying cell where citizen is currently located.

setFamily

private void setFamily()

setFamily

private void setFamily(Citizen citizen,
                       Citizen mate)

setID

public static int setID()

Returns a unique numeric ID and increments it in preparation for the next request.

setInheritAttributes

private void setInheritAttributes(Citizen citizen,
                                  Citizen mate)

Randomly choses newborn child's genetic attributes from one or the other parent.

Parameters:

citizen - parent #1

setLastMating

public void setLastMating(int generation)

Updates last mating of citizen to current cycle or time period.

Parameters:

generation - current time period.

setLifeSpan

public void setLifeSpan(int ageVal)

Sets citizen lifespan to a specified or random value.

Parameters:

ageVal -

setMetabSpice

public int setMetabSpice(int metabolismVal)

Sets citizen spice metabolism to a specified or random value.

Parameters:

metabolismVal - spice metabolism of citizen

setMetabSugar

public int setMetabSugar(int metabolismVal)

Sets citizen sugar metabolism to a specified or random value.

Parameters:

metabolismVal - sugar metabolism of citizen

setMRS

public float setMRS()

Calculates value. Represents the Marginal Rate of Substitution of spice for each unit of sugar. Calculated by deriving the consumption units of spice (spUnits) and sugar(suUnits). consumption unit = quantity / metabolism MRS is then derived by dividing spUnits by suUnits. MRS results less than 1 signify a preference for spice, results greater than 1 conversely indicate a preference for sugar.

setParents

private void setParents(Citizen citizen,
                        Citizen mate)

setPersona

public int setPersona()

Sets citizen vision to a random value.

setRanking

public int setRanking()

Recalculates ranking for citizen. This influences the likelihood of selection by other citizens looking to mate.

setRow

public void setRow(int row)

Stores the row representing a current or designated location within the citizen object.

Parameters:

row - row identifying cell where citizen is currently located.

setSex

public int setSex()

Sets citizen sex to a specified or random value.

setSpice

public float setSpice(float spiceVal)

Sets citizen spice to a specified or random value.

Parameters:

spiceVal - value indicating how spice stockpile of citizen is to change.

setSpUnits

public int setSpUnits()

Calculates value, depicting the number of units of spice available to the citizen. Each unit is equal to the metabolic rate for spice.

setSugar

public float setSugar(float sugarVal)

Sets citizen sugar to a specified or random value.

Parameters:

sugarVal - value indicating how sugar stockpile of citizen is to change.

setSurplus

public int setSurplus()

Calculates and returns the surplus available for trade. Surplus is defined as the amount of any one good that is in excess of what is required to maintain current TUD.

setSuUnits

public int setSuUnits()

Calculates value, depicting the number of units of sugar available to the citizen. Each unit is equal to the metabolic rate for sugar.

setTUD

public int setTUD()

Calculates and returns an estimated Time Until Death. Based on sugar & spice consumption units available. Is taken as the lower of the two values and assumes no more goods are added to the citizen's stockpile.

setVision

public int setVision(int visionVal)

Sets citizen vision to a specified or random value.

Parameters:

visionVal - citizen vision

showStats

public java.lang.String showStats(java.lang.String message)

Returns a string describing some of the key attributes for the citizen.

Parameters:

message - String to precede display of important citizen stats.

transferWealth

private void transferWealth(Citizen citizen,
                            Citizen mate)