SwarmObject

The SwarmObject library encapsulates various fundamental aspects of the Swarm object model in easy-to-use pieces for users. Most of the real functionality behind the classes here is contained in the defobj and activity libraries. In addition, most of the probe support is here. The main classes here for user subclassing are Swarm and SwarmObject.

class SwarmObject

SwarmObject is the base class for most simulated Swarm objects. When writing simulation code, your agents should inherit from SwarmObject. Currently, most of the SwarmObject behaviour itself is contained in the defobj library. SwarmObjects also package up probing functionality.

The most essential addition SwarmObject makes to generic Objective C objects is ia new mechanism for creation. This mechanism is inherited directly from defobj's CreateDrop class. Briefly, SwarmObjects never use the methods +alloc, +new, or -init. Instead they use +createBegin and -createEnd. All memory allocation occurs explicitly in a Zone, an object that encapsulates heap functionality.

+createBegin: (id) aZone

createBegin takes the place of +alloc. createBegin is sent to a factory object, and the return value is a newly allocated instance. For example,

mySwarmObject = [SwarmObject createBegin: globalZone];

-createEnd;

createEnd is used to finalize the creation of an object after the object was created with +createBegin: and initialized with whatever set methods the class specifies. -createEnd typically checks to make sure the object was initialized properly and does internal initialization. The return value from createEnd should now be used as the object: it's possible the original object was destroyed during createEnd and a substitute was returned. For example,

mySwarmObject = [mySwarmObject createEnd];

In cases where you don't need to do anything between createBegin and createEnd, a shorthand message "+create" is allowed. In addition, some classes define special create messages that initialize particular fields.

class Swarm

The Swarm class encapsulates all of the abstract execution machinery in the activity library, as well as the notion of a group of related objects. Briefly, a Swarm is a combination of a collection of objects and a schedule of activity over those objects. A typical model consists of a group of agents wrapped up in a Swarm, along with a schedule of activity for those agents. See the example Swarm applications for more detail.

Users are expected to create subclasses of Swarms for their own models. A subclass of Swarm should have slots to contain its own objects and override methods for important functionality.

+createBegin: (id) aZone

Typically, the createBegin method is overridden to provide default initial values for all of the Swarm's slots.

-buildObjects

The buildObjects method is the place where your Swarm should build all the objects it will contain. For instance, in the heatbug model swarm buildObjects creates a list of heatbugs and a world for them to live in.

-buildActions

In buildActions, your Swarm should build any schedule data structures it needs. During buildActions these structures are static, they are actually used later.

-activateIn: (id) swarmContext

activateIn is where your static schedules are given to the activity library in preparation for actually running. Here your Swarm should activate itself (via the superclass activateIn method) and then activate any schedules it has build. Even after activation your Swarm is not actually running - only after the -run method is sent to the swarmActivity do things start to execute. In typical Swarm applications, run is sent as part of the execution framework.

The swarmContext argument refers to what parent Swarm is running your Swarm - it's possible for this to be nil, in which case your Swarm will be the top level of execution. For typical users you can just pass the swarmContext argument off to the superclass activateIn method. Note also that the return for activateIn should be [self getSwarmActivity], not just self.

MessageProbe subclasses

A couple of subclasses of MessageProbe are implemented here that might be of use to Swarm model builders. Most of their behaviour derives from MessageProbe itself.

Averager

Averager objects read a value (via a MessageProbe) from a list of objects and collect statistics over them. They are used as part of a data analysis suite: for instance, it's common to set an Averager up over a list of agents, and then connect it to an ActiveGraph for graphing data.

-setList: (id) list: sets the list of objects that will be probed.
-setProbedSelector: (SEL) s: The message to be sent to each element on the list (inherited from MessageProbe)
-(double) getAverage, -(double) getTotal, -(double) getMax, -(double) getMin -(int) getCount: various statistics that the averager collects. These are read out of the object, not computed everytime they are asked for.
-update: Update the average - send the message down the list and update the average, total, etc. Schedule this message when you need to collect data.

ActiveGraph

An active graph object is the glue between a MessageProbe (for reading data) and a BLTGraph GraphElement. ActiveGraphs are created and told where to get data from and send it to, and then are scheduled to actually do graphic functions.

-setElement: get: Sets the graph element used to draw on
-setDataFeed: d: Sets the object that will be probed for dta
-setProbedSelector: (SEL) s: Sets the message sent to the object for graphing (inherited from MessageProbe)
-step: Fires the probe, reads the value from the object, and draws it on the graph element. The X value is implicitly the current simulation time: Y is the value read.

Nelson Minar <nelson@santafe.edu>

Last modified: Sun May 12 18:41:03 MDT 1996