Oobj56
cell4x4
cell1x1b
cell2x2b
Oobj151
Oobj152
Oobj156
Home
Detailed Explanation of Main Processes/Events
WalkThru
Screen shots with explanations
Scre'nshots
Project Design Details
Design
Oobj59
Documents
Walkthru - Installation
Installation
Walkthru - Introduction
Introduction
Walkthru - Gathering
Gathering
Walkthru - Mating
Mating
Walkthru - Barter
Barter
Walkthru - Seasons, Inheritance & Pollution
Misc
Installation
Compiling & executing the program
To run the Sugarscape applet you need to:

1a) Download and install the Java 2 SDK with "AppletViewer.exe" (this is something that would be available on your system if you do some Java programming yourself. Make sure the CLASSPATH variables are set correctly and that the Java directory is included in your PATH system variable.

OR

1b) Internet Explorer 5.x or greater AND the Java 2 Runtime Environment(JRE), which is freely available from Sun at the following website:
        http://www.java.com/en/download/windows_automatic.jsp

Alternatively you can manually download & install the latest Java Runtime(JRE) from:
        <http://www.java.com/en/download/manual.jsp>

If you feel you already have the latest Java Runtime(JRE), try loading this page:
         <http://www.java.com/en/download/help/testvm.jsp>

The page should display the message, "Congratulations. Java is installed on your system" and some animation within a gray box on the webpage.


2a) Download and uncompress the Sugarscape source (Linklist version) available at
        http://sourceforge.net/projects/sugarscape/
...Unzip it on your computer. Maintain the directory structure specified within the Zip file.

2b) Once you have Internet Explorer 5.x and the JRE 2 installed on your computer, simply close all currently open browser windows and restart Internet Explorer. Type the Sugarscape website URL once again in the Address bar of your browser and you should see the applet being downloaded and executed.


3a) Open a MS-DOS window, change to the Sugarscape directory and type the following command, then press Enter.
        appletviewer Sugarscape.html



If you wish to compile the program files, you may do so in the following manner:
open a DOS window & change to the first Sugarscape folder
type the following commands in the given order:
        javac GoLconst.java <enter>
        javac Citizen.java <enter>
        javac Cellspace.java <enter>
        javac GameOfLife.java <enter>
If no errors are generated, you can execute the compiled program as described in the
preceding paragraph.
Note: The a.bat file automates this process & combines compilation & execution in one
command, type:
        a GameOfLife <enter>
...to automatically compile & execute the program.



Introduction
Start the program as described above and you should see the Sugarscape window containing the three major components - the control bar, the cell grid or Cellspace and the tabbed pane.
The Control Bar: enables the user to select from various Game of Life or one Sugarscape template. It also provides buttons to start, stop or step through the simulation one cycle (time period) at a time. A final selection box allows users to adjust the speed of the simulation.
The Cellspace: is a visual representation of our society of primitive beings. It comprises of cells arranged in a grid format with horizontal bars originating from the side of each cell denoting resource levels. Occupied cells aslo contain an icon made up of a combination of cmall circles and rectangles.
The Tabbed Pane: is the interface for displaying results of the simulation and to set/change parameters that control the simulation. It comprises six panels of which the first is used to display summarized data (totals, averages & distributions). The last panel is used to display details about individual processes and responses to commands from the user. The Cellspace tab is used to control the variable options that apply to/control the entire grid of cells, i.e., the number of columns & rows, processes to be activated, grid fertility levels etc. The Cell tab is similarily used to control variables controlling settings for individual cells. These include maximum sugar-n-spice levels, regrowth rates, pollution and dispersal rates etc. The Citizen tab is used to regulate Citizen attributes. They include genetic attributes (vision & metabolism), initial resource levels, life expectancy, mating rules etc.
By tweaking numerous aspects of the simulation, a researcher is able to set a desired initial state. They can then execute the simulation and compare its results to the predictions of their hypotheses.


Gathering
Citizens possess genetic attributes of metabolism and vision. These traits are inherited by offspring from their parents. Citizens possess seperate metabolic requirements for sugar & spice. They need both goods to survive and exhaustion of either will lead to death by starvation. Citizens therefore need to search for these goods and accumulate them in order to survive. Citizens do so by following a simple set of connected instructions that are generally referred to as a ruleset. The ruleset for gathering can be described as follows:
  1. Evaluate personal stocks and determine which good is needed more urgently (preferred good).
  2. Look around as far as vision permits and identify the site with the greatest value of the preferred good.
  3. If the greatest value exists at multiple locations, select one randomly.
  4. Move to that site and harvest all resources from that site.
  5. If no value is found within the visible grid, then the citizen randomly relocates to one of the farthest cells within its vision range.
The last step helps the Citizen avoid getting bogged down in an area of the grid that is barren of any resources or expending valuable search cycles in corner cells of the grid. The following commentary is a sample of feedback generated by the Gather process within the simulation.





























Mating
Citizens may or may not have their lives curtailed by death. This choice is determined by the current setting of the Mating process. When Mating is activated, citizens will die at the end of their lifespan. Conversely, citizens continue to live past their slated lifespan when Mating is turned off (not implemented yet. When citizens die of hunger, new citizens emerge to replace them, thus keeping the population constant (not implemented yet).
When activated, Citizens seek a prospective mate from the population located in cells adjacent to the location of the citizen. As for Gathering, Mating too has its own ruleset, note the number of pre-qualifiers that trim the set of citizens allowed to mate.
  1. IF the Citizen is of child-bearing age, i.e., post-puberty, pre-meno/andropause, past the mating gap (time interval between successive mating events), possessinf reserves atleast twice the poverty level and having an adjacent empty cell to locate the child, then the Citizen proceeds to seek mates.
  2. Prospective mates must be located in a cell adjacent to the citizen and must be of the opposite sex in addition to satisfying all except the last requirement in step 1.
  3. Additional restrictions may be applied at the discretion of the researcher, for e.g., the researcher can choose to allow or deny citizens directly related to each other to mate. The researcher may also adjust wealth levels required to qualify for mating.
If more than one prospec satisfies the above restrictions, a weighted random selection is made. The weight attached to each mate is a function of their ranking, a composite of their genetic attributes and material wealth. The greater the ranking, the greater their chances of selection. Each citizen can initiate just one mating event per cycle.
Once the selection is made, the citizen couple produce a child. The child is located in a pre-determined cell located during an earlier step in the mating process. The child  randomly inherits genetic attributes of one or the other parent. It inherits half of each parents original inheritance by default. This can be changed so the child inherits half of the current wealth of its parents at the option of the user by setting the 'Inherit Initial Wealth' field in the Citizen panel to "false".
The inheritance received by the child is a transfer and each parents wealth is adjusted to reflect the depletion.
The following commentary is a sample of feedback generated by the Mating process within the simulation.









































Barter
Citizens need both sugar & spice to survive. They have independent metabolism rates for each resource. There may arise situations where citizens starve to death due to a paucity of one resource, despite having a plentiful supply of the other. Barter offers them a means to acquire a scarce resource in exchange for an abundant commodity. The personality of the citizen is an important attribute affecting their approach to trade. Personality is randomly assigned at birth and determines the trading strategy pursued by the citizen. A bear (cautious) personality seeks to minimize surplus and will only trade the surplus commodity. A bull (aggressive) personality seeks to maximize trades even if it involves trading the scarce commodity. The bull only trades the minimum quantity required to recieve one unit of the other commodity. By maximizing trades, the bull seeks to hedge its exposure to unfair trades.
For eg. the bear seeks trading partners that possess a surplus of its scarce commodity. It then attempts to trade a certain proportion of its surplus such that the quantity received in exchange can be combined with the balance of its surplus to mitigate the  risk of depletion of any one commodity. The bear strategy is at risk of wild fluctuations in the exchange price depending on the variance in the MRS values of the trading partners. Since they attempt to sell all available surplus immediately, bears could end up trading all their surplus in a single unfavorable trade.
The Bull strategy, by trading unit amounts with as many traders as possible, seeks to average out price fluctuations and arrive closer to the equilibrium price.
For purposes of our projects some concepts need definition. The first of these are:
The Barter process when activated causes citizens to look for trading partners in cells adjacent to their location. Depending on personality, citizens will apply one of the two rulesets detailed below.

The Bear Ruleset:
  1. IF negligible surplus, abandon trade attempt.
  2. Prospective trading partners must be located in a cell adjacent to the citizen.
  3. If prospect also posseses a bear personality and has negligible surplus or needs the same good as the citizen, reject prospect.
  4. If MRS equal for both, reject prospect.
  5. Sort the list of available traders by decreasing order of variance in MRS.
  6. Set surplus of both parties to half of their current value, trade the lower of the two surpluses at a price that is the geometric mean of the two MRS values.
The Bull Ruleset:
  1. Set surplus to 1.
  2. Prospective trading partners must be located in a cell adjacent to the citizen.
  3. If MRS equal for both, reject prospect.
  4. Sort the list of available traders by decreasing order of variance in MRS.
  5. Price is the geometric mean of the two MRS values.
  6. The agent with the higher MRS gets sugar, the agent with the lower MRS gets spice.
Trades are consumated once per cycle with all available partners subject to the above conditions holding true prior to each new trade. The following commentary is a sample of feedback generated by the Barter process within the simulation.
































Change of Seasons
Migratory behavior of a predictable nature is caused by a change of seasons. Citizens tend to move from the region of scarcity to the region of abundance. Fertility fluctuates dramatically, resulting in a concerted move to the region enjoying summer (higher fertility) from the region in the throes of winter.
The summer region also witnesses a spurt in new births as citizens there accumulate enough reserves to enable them to bear children. This coupled with an increase in deaths in the winter regions caused by scarcity leads to a population concentration in one half of the grid.
As the season changes, and the tables are reversed a migratory pattern emerges as the bulk of the population moves to the other area. The Sugarscape follows a simple two-phase cycle for change of seasons, so there are only two seasons currently. The duration of a season can be adjusted in the Cellspace panel.



Inheritance
Inheritance when activated kicks in following the death of a citizen. It results in the citizens surviving wealth being distributed equally among its surviving progeny. There is no provision to pass the wealth to grandchildren in the absence of their parents.


Pollution
Pollution when activated accumulates in each cell as a result of the gathering activity. Each unit of sugar or spice when harvested results in specified increases in pollution within the cells. Both sugar & spice have separate levels of pollutant per unit harvested.
As citizens move about the Cellspace, the prefer the less polluted cells to their more polluted alternatives given matching resource levels. Nature's effect of dispersing pollution over time is also replicated via a pollution dispersal event that occurs once every cycle. It reduces pollution levels by a specified amount. These values can be adjusted from the Cell panel.
Vision = 1
Search grid for curr citizen ->i0 = 31  j0 = 16        ix = 33  jx = 18
Better Dest.[31][16]        8Su, -1Sp, 0P        
Better Dest.[31][17]        5.1Su, 10Sp, 0P        
Better Dest.[32][18]        10Su, 10Sp, 0P        
Ideal Cell: sugar = 10        spice = 10        Destinations = 1
+--Search over, RandomDest = 0        Highest sugar-n-spice in cell[32][18]        10Su, 10Sp, 0P        
moveNGather: Completed move from [32][17] to [32][18]

Vision = 2
Search grid for curr citizen ->i0 = 5  j0 = 10        ix = 9  jx = 14
Better Dest.[5][12]        -1Su, 7.87Sp, 0P        
Better Dest.[5][13]        10Su, 10Sp, 0P        
Cell[7][11] contains 10.0 sugar & 10.0 spice & 0.0 pollution
Cell[8][11] contains 10.0 sugar & 10.0 spice & 0.0 pollution
Cell[9][10] contains 10.0 sugar & 10.0 spice & 0.0 pollution
Ideal Cell: sugar = 10        spice = 10        Destinations = 4
Random Destination = 4
+--Search over, RandomDest = 1        Highest sugar-n-spice in cell[9][10]        10Su, 10Sp, 0P        
moveNGather: Completed move from [7][12] to [9][10]

Vision = 1
Search grid for curr citizen ->i0 = 36  j0 = 0        ix = 38  jx = 1
No goods found around [37][0]
Picking farthest cell to relocate!!
New Destination = 1         Distance  of cell[38][1] = 2
Random Destination = 1
***Destination found!!         Distance to cell[38][1] = 2
moveNGather: Completed move from [37][0] to [38][1]
Initiating mating processes for: (120)KRUSE
        Unsuccessful attempt to mate

Initiating mating processes for: (124)SERRANO
        SERRANO is of mating age & has sufficient surplus
        Seeking empty cell & mates
        Found mate :   165) FLOYD                    [33][15]        1V  140.65Su/1SuM/130.94SuI        123.21Sp/1SpM/106.24SpI        Female  16(69) yrs old, Rank 14        Risk Taker
         MRS=0.876         Dies in = 123         surplus=17
        New child's destination: [31][13]
        New child:   232) SERRANO                [31][13]        1V  125Su/1SuM/125SuI        126.21Sp/1SpM/126SpI        Female  0(60) yrs old, Rank 15        Risk Taker
         MRS=1.008         Dies in = 125         surplus=0

Initiating mating processes for: (113)DUGAN
        DUGAN is of mating age & has sufficient surplus
        Seeking empty cell & mates
        foundDestination=TRUE        Mate list empty!!
        Unsuccessful attempt to mate

Initiating mating processes for: (92)LARA
        LARA is of mating age & has sufficient surplus
        Seeking empty cell & mates
        Found mate :    67) BOSTON                  [9][12]        3V  109.05Su/2SuM/126.07SuI        154.98Sp/3SpM/140.3SpI        Male  16(78) yrs old, Rank 15        Risk Taker
         MRS=0.947         Dies in = 51         surplus=7
        Found mate :   39) GRIGGS                  [11][10]        2V  146.55Su/1SuM/135.65SuI        138.85Sp/1SpM/108.58SpI        Male  16(60) yrs old, Rank 14        Risk Taker
         MRS=0.963         Dies in = 139         surplus=7
        New child's destination: [9][11]
        Chosen Mate:   39) GRIGGS                  [11][10]        2V  146.55Su/1SuM/135.65SuI        138.85Sp/1SpM/108.58SpI        Male  16(60) yrs old, Rank 14        Risk Taker
         MRS=0.963         Dies in = 139         surplus=7
        New child:    235) GRIGGS                  [9][11]        2V  127Su/1SuM/127SuI        111Sp/1SpM/111SpI        Female  0(65) yrs old, Rank 14        Risk Taker
         MRS=0.874         Dies in = 111         surplus=16
Initiating barter processes for: (213)FLEMING
        No surplus for barter

Initiating barter processes for: (121)PEREZ
        Found trader:    115) GOINS                    [17][5]        1V  112.18Su/3SuM/108.07SuI                116.6Sp/3SpM/107.22SpI        Male  1(76) yrs old, Rank 10        
        Risk Taker        MRS=0         Dies in = 0         surplus=0
        Before Exchange:
        Citizen   121) PEREZ                    [18][6]        1V  147.44Su/1SuM/138.63SuI        150.75Sp/1SpM/133.84SpI        Male  1(61) yrs old, Rank 15        Risk Averse
         MRS=1.022         Dies in = 147         surplus=3
        Trader    115) GOINS                    [17][5]        1V  112.18Su/3SuM/108.07SuI        116.6Sp/3SpM/107.22SpI        Male  1(76) yrs old, Rank 10        Risk Taker
         MRS=1.039         Dies in = 37         surplus=0
        Final tradeable surplus = 1 @ Price 1.0309213
        1)Citizen gets 1 sugar, Trader gets 1.0309213 spice
        After Exchange:
        Citizen   121) PEREZ                    [18][6]        1V  148.44Su/1SuM/138.63SuI        149.72Sp/1SpM/133.84SpI        Male  1(61) yrs old, Rank 15        Risk Averse
         MRS=1.022         Dies in = 147         surplus=0
        Trader    115) GOINS                    [17][5]        1V  111.18Su/3SuM/108.07SuI        117.63Sp/3SpM/107.22SpI        Male  1(76) yrs old, Rank 10        Risk Taker
         MRS=1.039         Dies in = 37         surplus=0

Initiating barter processes for: (39)LACEY
        No prospects available for trade