Initializing Hierarchical Swarms

[Manor Askenazi]

                   Initializing Hierarchical Swarms
                   --------------------------------

At least two users (Benedikt Stefansson, Sven Thommesen) have raised some 
important questions about the way in which hierarchical swarms should be
initialized. The setup of the problem is as follows:

      Observer Swarm
              \
               \
                \
           Model Swarm
             /   |   \
            /    |    \
           /     |     \
     Swarm1   Swarm2   Swarm3 ....


The questions are (in order of difficulty):
-------------------------------------------

1. When and where do I activateIn: the various Swarms?

2. How do I assign an order to the different schedules occurring in the
   sub-swarms?

3. How do I organize multiple probe entry phases. This is useful in
   the following case: if there is some variable in the Model Swarm which 
   indicates the number of subswarms to build then we need that variable
   to be set before actual creation of the sub-swarms, but then, we still
   want to be able to set variables on the sub-swarms etc. etc. 

So, some answers:
-----------------

1. The lower-level swarms should be activated in their immediate parent:

   -activateIn: (id) swarmContext {

     [super activateIn: swarmContext];

     [swarm1 activateIn: self];
     [swarm2 activateIn: self];
     [swarm3 activateIn: self];

     [localSchedule activateIn: self];
  
     return [self getSwarmActivity];
   }

2. Referring to this code, we can see the implicit order that the user 
   is requesting:

   The system will order events using the time values etc., but if two 
   events land on the same time-slot then events in swarm1 have precedence
   over events in swarm2 which have precedence over the events of swarm3
   which have precedence over the events in localSchedule defined on the 
   modelSwarm itself. Default handling of concurrent events from different 
   schedules or subswarms is to keep them in the same order as their original
   activation (there are other techniques for randomizing concurrent events, 
   inserting some application-specific tie-breaking schemes and so on, but I 
   guess we should cross that bridge once y'all get to it).

   Note: the order of schedule creation does not affect the order of 
   execution, so the following code:
  
   -buildActions {

     localSchedule = [Schedule create: [self getZone]];
       ...
       ...

     [swarm3 buildActions];
     [swarm1 buildActions];
     [swarm2 buildActions];
  
     return self ;
   }

   Has absolutely no effect on the ordering of events.

3. When building the simulation (i.e. before you do [observerSwarm go]) the
   way you stop the system is essentially the same as the way it is done at
   runtime:

   -buildObjects {

     [super buildObjects];
  
     ...build the basic stuff...

     [probeDisplayManager createProbeDisplayFor: self] ;

                                      //controlPanel must be passed down to
     [controlPanel setStateStopped] ; //any Swarm which will need to stop the
                                      //system...

     for(i = 0 ; i < user_input ; i++){

       .. create subSwarms ..

       [probeDisplayManager createProbeDisplayFor: subSwarm[i] ] ;
     }    
    
     [controlPanel setStateStopped] ;

     for(i = 0 ; i < user_input ; i++)
       [subSwarm[i] buildObjects] ;

     return self ;
   }

   Note: you are probably used to seeing this:

   [controlPanel waitForControlEvent];
   // Check now if the user hit the quit button: if so, abort.
   if ([controlPanel getState] == ControlStateQuit)
     return self;

   Which is now obsolete in favor of the unified way of stopping an 
   interactive simulation (namely using setStateStopped).

   Note Also: Right now you will need to pass the controlPanel along to 
              any lower level swarm which needs to stop the initialization,
              also, you will need to make some 'fake' control panel for 
              batch-mode... On the next release this will be cleaned-up!
              If anyone gets there before the next release we can provide 
              some interim code.

4. Before doing what is described in answer 3 you need to update the 
   file ..wherever../swarm/src/simtools/ControlPanel.m, replace the
   following method:

   ++++++++++++++++++++++++++++++ OLD +++++++++++++++++++++++++++++++++++++

   -setStateStopped {
     if (getTopLevelActivity())
       [getTopLevelActivity() stop];
     return [self setState: ControlStateStopped];
   }

   ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

   with:

   ++++++++++++++++++++++++++++++ NEW +++++++++++++++++++++++++++++++++++++

   -setStateStopped {
     if (getTopLevelActivity()){
       [getTopLevelActivity() stop];
       return [self setState: ControlStateStopped];
     } else {
       [self waitForControlEvent];
       // Check now if the user hit the quit button: if so, abort.
       if ([self getState] == ControlStateQuit)
         exit(0) ;
       else
         return self ;
     }
   }

   ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++


Hope this helps!

Regards,

Manor.