What is in initSwarm()? Was going to ask, but now propose an answer for FAQ or DOCS

[Paul Johnson]

A student yesterday said "what does this initSwarm() thing do in main.m"
and I said "oh, that's a function that initializes a lot of stuff. look
in the functions index of the swarmdocs to se about it."  To be honest,
I had never before taken the time to pursue it. My student pointed out
none of the initSwarm family are listed in there. Then I wished i had a
list of the global objects that are created when initSwarm (or any of
its colleagues, like initSwarmArguments()) runs.  Off the top of my
head, I knew of the 3 random distributions, as well as "probeLibrary".  

So I did some exploring.  Some parts I still don't know, those have ??. 
If you all have feedback, please let me know.

I found the initSwarm is listed in the swarm docs under the Simtools
protocol, General subheading, and I find the definition in the source
code in the simtools directory, simtools.m.  I gather that all of the
"init" family listed in the swarmdocs are in fact macros that actually
feed parameters to _initSwarm_ in the simtools.[h,m] directory.  The
_initSwarm_ function triggers off a series of inits:   
  initModule (activity);
  initDefobj (argc, argv,
              appName, version, bugAddress,
              argumentsClass,
              options, optionFunc,
              inhibitExecutableSearchFlag);
  initProbing ();
  if (![arguments getBatchModeFlag] && !forceBatchMode)
    swarmGUIMode = YES;
  initRandom (arguments);
  if (swarmGUIMode)
    initSimtoolsGUI ();

In other words, to get a clear idea of what is entailed by initSwarm, we
have to go to each of the "sub-inits" and see what they do.  

1. initDefobj provides: 
        arguments   (a class that handles command line arguments)
        lispArchiver     (for using files in lisp format)
        lispAppArchiver    (??)
               for people that have hdf5, this also starts:
         hdf5Archiver    (a class for use of hdf5 data format files)
         hdf5AppArchiver   (?? )

2. initProbing:  
        probeLibrary  (a global record keeper for probes)

3. initRandom:
   randomGenerator : default MT gives integers that "drive" the random
distribution drawing objects listed next
   uniformIntRand   integer distribution
   uniformUnsRand   unsigned integer distribution
   uniformDblRand   double distribution 

4. initSimtoolsGUI (only for GUI sims, not batch in the background mode)        
        
   probeDisplayManager      (??)

5. initModule.  
        This one is the most mysterious. In the defobj/Program.m file, it gets
re-routed to _obj_initModule, and I can't see what it does, or if there
are any global objects created.

-- 
Paul E. Johnson                       email: address@hidden
Dept. of Political Science            http://lark.cc.ukans.edu/~pauljohn
University of Kansas                  Office: (785) 864-9086
Lawrence, Kansas 66045                FAX: (785) 864-5700

                  ==================================
   Swarm-Support is for discussion of the technical details of the day
   to day usage of Swarm.  For list administration needs (esp.
   [un]subscribing), please send a message to <address@hidden>
   with "help" in the body of the message.