6.2. What Are You Supposed to Learn from the Tutorial?

So, after you worked on the tutorial for 20 hours or so, what then? You should know all kinds of details about how Swarm can be used, of course, but there are some bigger themes.

It is not vital to know how to model bugs (although, perhaps for an entomologist...), rather, it is vital to understand that Swarm is a toolkit that provides a housing for a modeling exercise. Swarm imposes no inherent limitations on the nature of agents that can be represented within its framework.

Don't read much further in this user guide until you work on the tutorial. You will know if you have worked on it long enough when you understand clearly each of the following points.

• Swarm has many classes to make the modeling job easier. There are workhorse classes like Swarm, SwarmGUI, and SwarmObject, but also there are many "little helpers" like List. Getting to know the ins-and-outs of these little helpers is extremely important.

• Swarm handles memory details. Did you note that there are no malloc and free and other standard C memory-managing commands in Swarm code? Those commands exist, but they exist inside the Swarm library, and they are accessed on behalf of users who use create or createBegin and drop to access memory for objects and get rid of them. To create objects (instances of classes) in Swarm, there must either be a createmessage sent to a class or there must be a createBegin/createEnd pair that serves as bookends for commands that create an instance, set its internal state, and complete the instantiation.

• Case is important. Including the right header files may give you access to "factory objects" like List or Schedule. You can use any name you like for the objects that are created as instances. By custom, an instance of a class--an object--is named in small letters, such as bugList as an instance of List or modelSchedule as an instance of Schedule. In the tutorial, when there is a single instance of a class to be created, by convention, it is typically named the lowercase version of the class name, such as the foodSpace object which is an instantiation of FoodSpace.

• Neatness counts. As in any kind of programming task, neatness counts. Classes in Swarm are created with methods that group together their jobs by functions. One will often find, in ObserverSwarm for example, commands that create a modelSwarm instance and then issue it these commands:

  [modelSwarm buildObjects]; [modelSwarm buildActions];

  The buildObjects method creates objects and buildActions creates schedules. If one wanted to, one could build a gigantic method in the ModelSwarm class called doStuff and then call that method with:

  [modelSwarm doStuff];

  Programs written with this approach are hard to proofread and manage. It is much better to write small methods, each of which accomplishes a relatively specific task.

• There is often a need for "record keeping" classes. In order for data to be displayed meaningfully in a graph, for example, it must be provided to the graph object in a format that the graph object can handle. The class World in simpleObserverBug is subclassed from Swarm's Grid2d class.

• Graphics are optional, but nice. Commands in the Observer Swarm control the graphical display. There are many kinds of graphs and ways to alter their appearance. It is not necessary to design a Swarm program to make pretty pictures, however. One might just as well run in a "batch" mode that prints numbers into files for later inspection. There is a useful example of the batch mode in the Heatbugs code.

• Open Source means open the source. To find out what messages an instance of a class will respond to, you should first consult the API [1]: the Swarm Reference Guide. In most cases the average user will encounter, consulting the API is sufficient, but when you really need to know how something is implemented (either to understand the efficiency implications of using a certain method in your program or if a particular method appears to not behave as documented), you can go look in the Swarm source code itself. That's what the members of the Swarm team do when users ask questions.