1-001 Paul Johnson 1-002 2003-04-18 1-003 1-004 Swarm SugarScape was done by Nelson Minar and now it has undergone 1-005 some updating/facelifting. I think sss is an interesting and 1-006 important piece of code not only because the Epstein & Axtell book 1-007 "Growing Artificial Societies" was a landmark accomplishment, but also 1-008 because this code shows several handy ways to design Swarm models and 1-009 incorporate external data sources. In particular, I like very much 1-010 the way this code (unlike many Swarm examples) creates one 1-011 "environment class"--the SugarSpace--that holds a variety of 1-012 Swarm spaces. In there one finds the agent grid and various 1-013 grids that monitor the state of the environment. I have found 1-014 this to be a very useful organizing principle and I strongly 1-015 suspect it planted that idea in my mind and caused me to 1-016 re-do it in the new version of the Schelling segregation model 1-017 (schelling2-2.0-Swarm-2.1.141) that was just now released. 1-018 1-019 Now, about the features. First, you can make movies! 1-020 You can cause the model to create a stream of ppm 1-021 pictures if you do a "make clean" and then build with 1-022 1-023 make EXTRACPPFLAGS=-DMAKEMOVIE 1-024 1-025 Second, I've replaced the old "ObjectLoader" with Swarm's lisp 1-026 archiver to manage model parameters. The model will run with defaults 1-027 set in ModelSwarm.m if you don't tell it otherwise. The "otherwise" 1-028 happens when you load a parameter file. This model can grab 1-029 parameters for a ModelSwarm from the parameters directory and put them 1-030 to use. Actually, it creates an instance of ModelSwarm and sets some 1-031 variables according to the file. It works like this. Note in the 1-032 parameters subdirectory there are files with names like "test.scm". 1-033 The ObserverSwarm's probe display is set so that if you type just 1-034 "test", hit return, and punch the "setParameters:" button, it will 1-035 load the parameter file from "parameters/test.scm". Similarly, if you 1-036 want to save the parameters you currently have specified, then type in 1-037 a word like "testAgain", hit enter, and then punch the 1-038 "saveParameters:" button. The convenience, which many new users 1-039 do not notice, is that you can edit the *.scm file and run a new 1-040 model without recompiling. 1-041 1-042 Warning: you cannot load a saved parameters file back into a Swarm 1-043 model without editing it. The saved file has many variables--the ones 1-044 that are created in buildObjects--set as nil. Unfortunately, the 1-045 instance variable "activity" is set to nil. That "erases" the 1-046 pre-existing activity variable that ModelSwarm inherits from its super 1-047 class. That makes the model die. So if you want to read a parameter 1-048 file back in, use an editor to delete the nil variables, at least the 1-049 activity variable. Then it will work to read those parameters back 1-050 into a model. 1-051 1-052 The model could be redesigned to avoid that problem. The more proper 1-053 approach would be to create a separate Parameter class, and then 1-054 archive that file. That way, no complications due to the nils will 1-055 result. That is a proper topic in the issue of "serialization." I 1-056 have other models which demonstrate how that can be done. If I get 1-057 written requests (emails!) from 5 Swarm users before July 31, 2003, I will 1-058 go ahead and introduce that serialization feature in the next version 1-059 of this model (write me: pauljohn@ku.edu). 1-060 1-061 Nelson's original parameter directory had some files named *.obs, 1-062 which were all empty. They originally had been planned for 1-063 ObserverSwarm parameters, but I figure if I really want to archive 1-064 them, I'll just go ahead and make a Parameters object to hold all 1-065 parameters. So, as of now, there is no way to read in the parameters 1-066 for the ObserverSwarm. I've left the example settings he specified 1-067 for the ModelSwarm. His settings are in files called *.model, while 1-068 the ones I intend for the current version of sss are in files called 1-069 *.scm. 1-070 1-071 I notice that there have been some other undocumented changes 1-072 in this program since Nelson wrote it. One is that the user 1-073 has the choice of reading in the data from the old-fashioned 1-074 sugarspace.pgm file, or from the new, hdf5 technique. There is 1-075 an R program distributed with this program called "hdf5.R". If 1-076 you install the hdf5 library for R that Marcus Daniels created, 1-077 and then run this R program, it will create an hdf5 file 1-078 with the data in it. (Use the h5dump program from hdf5 to see the 1-079 contents.) I've included with this package one example hdf file, 1-080 "sss.hdf". That was created by teh R program. 1-081 1-082 To compile and use the hdf5 data, build with 1-083 1-084 make EXTRACPPFLAGS=-DUSE_HDF5 1-085 1-086 One might wonder "why would I want hdf5 data?" Well, you can hand 1-087 edit "sugarspace.pgm" all you want, but it might kill you. On the 1-088 other hand, if you study up on R a bit, you will see it is a 1-089 fully-fledged, wonderful statistics and mathematical programming 1-090 system. In R, you could write arbitrarily complicated/interesting 1-091 patterns for the sugar. 1-092 1-093 1-094 Of course, if you want movies and hdf5, do 1-095 1-096 make EXTRACPPFLAGS="-DUSE_HDF5 -DMAKEMOVIE" 1-097 1-098 Other changes: 1-099 1-100 * The Shuffler class is now deleted, because Swarm's collections 1-101 library now includes the same class with the name ListShuffler. 1-102 * Methods in SugarSpace that read in the *.pgm file and copy 1-103 one Discrete2d to another have been deleted, because those 1-104 functions have been incorporated into Discrete2d itself. 1-105 1-106 If you find other things that can be updated or adapted, 1-107 please let me know. 1-108 1-109 1-110 Here's Nelson's original README content: 1-111 1-112 ----------------------------------------- 1-113 1-114 SugarScape in Swarm 1-115 1-116 sss is a Swarm implementation of some of the models from Joshua 1-117 Epstein and Robert Axtell's book "Growing Artificial Societies". 1-118 http://www.brookings.edu/SUGARS~1/DEFAULT.HTM 1-119 1-120 This code should be used in conjunction with the book; the text 1-121 describes the various models, and in general is an interesting 1-122 exercise in agent based modelling of social systems. This Swarm code 1-123 implements the basics of the Sugarscape model, mostly the versions in 1-124 chapter 2. In particular, the growth rule G_alpha, the movement rule 1-125 M, and the replacement rule R are implemented here. These are the 1-126 basics of an ecosystem - the rest of the book covers adding more 1-127 social features to the system such as combat, sex, cultural exchange, 1-128 etc. 1-129 1-130 This code could serve as a base for implementing more sophisticated 1-131 versions of the Sugarscape models. It was originally written for a 1-132 series of lectures on Swarm and complex systems modelling. See the 1-133 file Exercises.html for some suggested exercises. 1-134 1-135 There are two basic types of objects in the system. One is SugarAgent, 1-136 the actors in the model. The other is SugarSpace, the state of the 1-137 world. Both of these objects are hybrids of a lot of different 1-138 functions and behaviours. 1-139 1-140 There are a couple of nice Swarm coding tricks here. One is the 1-141 SugarSpace method 1-142 -(int) setDiscrete2d: (Discrete2d *) a toFile: (char *) filename; 1-143 It's used to read the file sugarspace.pgm into the SugarSpac as data. 1-144 PGM is a simple greyscale image format. 1-145 1-146 // pj 2003-04-17 this next paragraph is outmoded by the 1-147 // lisp archiver approach discussed in the beginning of this file. 1-148 The other trick is the parameterFile in the ObserverSwarm. It uses the 1-149 ObjectLoader to override the probe windows if asked to. The files in 1-150 the subdirectory parameters/ can then be used to load in parameter 1-151 sets in a GUI swarm. 1-152 1-153 This code is free software. It is distributed under the GPL, see the 1-154 file LICENSE for details. All code is Copyright (c) Nelson Minar, 1-155 1997. It was written while kindly being hosted by the Systems Lab at 1-156 the Central European University (http://www.syslab.ceu.hu/) 1-157 1-158 Nelson Minar nelson@media.mit.edu 1-159 http://nelson.www.media.mit.edu/people/nelson/ 1-160 Budapest 7/26/97