Use Swarm -> Get Stuff

[Manor Askenazi]

Hi Everyone!

Here is a list of new classes which have rolled off the Swarm Software
production line. Many of these classes are useful for the next step in
the scientific effort -> you've got the model now you want to do some
serious data gathering! 

Note that none of these classes require any code changes on your part, 
and they do not require any new libraries etc. so this may be a good 
incentive to move on to the next release according to the Sven Thommesen 
formula:

  N = (everyone else's recoding time) / (Manor's coding time)

  If it exceeds e, or perhaps pi, reconsider (a new release)...

------------------------------------------------------------------------

First of all, at the lowest level we have two FileI/O objects, namely
the OutFile and InFile objects:


/************************** InFile *****************************/

  @interface InFile : SwarmObject {
    FILE *theFile ;
  }

  +create: aZone withName: (char *) theName ;

  -_setFile_: (FILE *) aFile ;

  -(int) getWord: (char *) aWord ;
  -(int) getInt: (int *) anInt ;
  -(int) getDouble: (double *) aDouble ;
  -(int) getFloat: (float *) aFloat ;
  -(int) getChar: (char *) aChar ;
  -(int) unGetChar: (char) aChar ;
  -(int) skipLine ;

  @end

/****************************************************************/


/************************** OutFile *****************************/

  @interface OutFile : SwarmObject {
    FILE *theFile ;
  }

  +create: aZone withName: (char *) theName ;

  -_setFile_: (FILE *) aFile ;

  -putString: (char *) aString ;
  -putInt: (int) anInt ;
  -putDouble: (double) aDouble ;
  -putFloat: (float) aFloat ;
  -putChar: (char) aChar ;
  -putTab ;
  -putNewLine ;

  @end

/****************************************************************/


On top of these we now have objects which are used for initialization 
of experiments (ObjectLoader) as well as for archiving of parameter 
settings (ObjectSaver):


/************************** ObjectLoader *****************************/

  @interface ObjectLoader : SwarmObject {
    id probeMapCache ;  
    id theFileObject ;    
  }

  +load: anObject from: aFileObject ;
  +load: anObject fromFileNamed: (char *) aFileName ;

  -setFileObject: aFileObject ;
  -loadObject: anObject ;

  -updateCache: exampleTarget ;

  -(void) _crash_: anObject ;

  @end

/****************************************************************/


/************************** ObjectSaver *****************************/

  @interface ObjectSaver : SwarmObject {
    id templateProbeMap ;  
    id theFileObject ;    
  }

  +save: anObject to: aFileObject ;
  +save: anObject to: aFileObject withTemplate: aProbeMap ;
  +save: anObject toFileNamed: (char *) aFileName ;
  +save: anObject toFileNamed: (char *) aFileName withTemplate: aProbeMap ;

  -setFileObject: aFileObject ;
  -setTemplateProbeMap: aProbeMap ;
  -saveObject: anObject ;

  -(void) _crash_: anObject ;

  @end

/****************************************************************/


But what about analysis? How can we simplify the task of the user when
s/he is trying to visualize data or collect it into a file? For this
we have three new classes...

The EZBin class takes a stream of input form a list of objects and bins
the values according to the number of bins and bounds set by the user.
The histogram thus generated can be displayed graphically (with the ability 
to click on a given bar to know exact data about it, also by pressing 'o' 
one can find out the number of outliers generated) but will also be 
saved to a file if this is requested by the user. The EZBin class will tell
you the Average, Standard Deviation, Min and Max of the stream of numbers
fed to it.


/************************** EZBin *****************************/

  @interface EZBin : MessageProbe {
    int graphics ;
    id aHisto ;

    int fileOutput ;
    id anOutFile ;

    char *theTitle ;
    char *xLabel ;
    char *yLabel ;

    int *distribution ;
    double *locations ;
    double *cachedLimits ;
    double min, max ;
    int clean ;
    int binNum ;
    int count ;
    int outliers ;
    id list;

    double minval,maxval,average,average2,std ;
  }

  -setTitle: (char *) aTitle ; 
  -setAxisLabelsX: (char *) xl Y: (char *) yl ;

  -setGraphics: (int) state ;
  -setFileOutput: (int) state ;

  -setBinNum: (int) theBinNum ;
  -setLowerBound: (double) theMax ;
  -setUpperBound: (double) theMin ;
  -setList: (id) list;

  -reset;
  -update;
  -output ;

  -(int *)getDistribution ;

  -(int) getCount;
  -(int) getOutliers ;
  -(int) getBinNum ;
  -(double) getUpperBound ;
  -(double) getLowerBound ;

  -(double) getMin ;
  -(double) getMax ;
  -(double) getAverage ;
  -(double) getStd ;

  @end

/****************************************************************/


The EZDistribution class generates a histogram of relative frequencies, 
in other words it generates the empirical distribution as measured by the
user. Since EZDistribution always stores a valid distribution, it provides
the entropy of the distribution as well as the other metrics provided by
EZBin...


/************************** EZDistribution *****************************/

  @interface EZDistribution : EZBin {
    double *probabilities ;
    double entropy, maximumEntropy ;
  }

  -(double *)getProbabilities ;
  -(double) getEntropy ;

  @end

/***********************************************************************/


Finally, EZGraph which was introduced in a previous email now has the
capability of doing FileI/O on request. (Note: for the record, the file
will be closed when the EZGraph is dropped...).


/************************** EZGraph *****************************/

  @interface EZGraph : Widget {
    int graphics ;
    id theGraph ;

    int fileOutput ;

    id sequenceList ;

    char * xLabel ;
    char * yLabel ;
    char *  title ;
  }

  -setGraphics: (int) state ;
  -setFileOutput: (int) state ;

  -setTitle: (char *) aTitle ;
  -setAxisLabelsX: (char *) xl Y: (char *) yl ;

  -createEnd ;

  -getGraph ;

  -createSequence: (char *) aName  
     withFeedFrom:          anObj 
      andSelector: (SEL) aSel ;

  -createAverageSequence: (char * ) aName 
            withFeedFrom: aList 
             andSelector: (SEL) aSel ;

  -createTotalSequence: (char *) aName 
          withFeedFrom: aList 
           andSelector: (SEL) aSel ;

  -createMinSequence: (char *) aName 
        withFeedFrom: aList 
         andSelector: (SEL) aSel ;

  -createMaxSequence: (char *) aName 
        withFeedFrom: aList 
         andSelector: (SEL) aSel ;

  -createCountSequence: (char *) aName 
          withFeedFrom: aList 
           andSelector: (SEL) aSel ;

  -step ;

  @end

/***********************************************************************/


The EZ series of widgets relies on the ActiveOutFile object for continuous
storage of data to a file (the File equivalent of ActiveGraph):


/************************** ActiveOutFile *****************************/

  @interface ActiveOutFile : MessageProbe {
    id theFile ;
    id dataFeed;
  }

  -setFileObject: aFileObj ;
  -setDataFeed: d;
  -step;
  @end

/***********************************************************************/


Also with respect to 'serious' scientific simulation (especially in the
humanities :-) we have the Gaussian object:


/************************** Gaussian *****************************/

  @interface Gaussian: SwarmObject {
    id uniform ;
    float mean, std ;
    int stored ;
    float stored_result ;
  }

  +create: aZone withMean: (float) aMean 
                      Std: (float) aStd 
                  andSeed: (unsigned) aSeed ;

  +create: aZone withSeed: (unsigned) aSeed ;

  -initSeed: (unsigned) aSeed ;

  -setMean: (float) theMean ;
  -setStd: (float) theStd ;

  -setUniform: aUniform ;
  -getUniform ;

  -(float) rFloat ;

  @end

/****************************************************************/


Note that unlike the other RNGs, Guassian is a Swarmobject and also has
a very visible and straightforward way to change the seed (Nelson's original
RNG's were meant to be distributable separately from Swarm so they are not
created in the usual way, also, the way in which users change the seed is 
not intuitive enough - this may be 'corrected' by the next release).


/-----------------------------------------\
| Other Small Changes To Existing Classes |
\-----------------------------------------/


  Histo
  -----

Low level changes have been made to the tkobjc Histo object so as to
support the aforementioned EZBin class -> namely two methods have been 
added:

  // This is used by EZBin to avoid the usual integer tagging of elements...
  -drawHistoWithInt: (int *) points atLocations: (double *) locations ;
  -drawHistoWithDouble: (double *) points atLocations: (double *) locations ;

This allows us to use Histos where we want to express some value for the 
x-location of the bars (the default is to simply tag them as 1,2,3 which
is not suitable when the bars actually represent some average value in a 
specific range -- such as the range -3 to +3 in the histo_test program).

  
  UName
  -----

By the way, the code for the UName class (which generates unique names)
I sent out a few weeks ago is buggy and was fixed (however, the interface
has not changed)...

  
  ProbeLibrary
  ------------

This class can now produce a CompleteVarMap for any class (in other words a 
CompleteProbeMap without the MessageProbes. This is used by the ObjectLoader
class. There is consequently a new class called CompleteVarMap which I did
not report on, because it will probably only be used internally by the 
Swarm system itself...


  VarProbe
  --------

A VarProbe can now be deactivated. This means that if this VarProbe is used
when creating a ProbeDisplay, the window representing this Variable will 
show the value of the variable, but will not allow the user to change that
variable:

  -setNonInteractive ;
  -(int) isInteractive ;

Also, the method:

  -(int) setData: (id) anObject ToString: (const char *) s ;

now returns an int which is set to 0 if the Variable could not be updated
correctly (this error code is used by the ObjectLoader).


  CompleteProbeMap
  ----------------

Like ProbeMaps, CompleteProbeMaps now preserve the order of variables 
as they are found in the original header file.


  Batch Mode Flag
  ---------------

Also, as mentioned in a previous mail, one can now write: 

  heatbugs -batchmode

and the swarmGUImode variable will be set accordingly.