These objects can be used as part of a Swarm application
to provide easy ways to:
The RParameters macros and subroutines
This section describes some macros and subroutines intended to make
life a little easier and programs a little cleaner.
The first set of macros are to make obtaining
random variates easier (and also to buffer applications
from changes in the underlying swarm random library).
A second set of macros and subroutines are for accessing values
of parameters in the RParameters object (or subclasses thereof).
There are also a few macros (and functions) for other
typical tasks (eg checking to see if a string is an ascii
representation of an integer) and for producing debugging
messages that can be turned on and off with the rDebug (-D) parameter.
Note well: To use these macros, you must of course #import
the RParameters interface (or subclasses of it).
Furthermore, some of these macros depend on having a variable
declared literally "parameters" which points to the applications
Parameters object which is a subclass of RParameters.
That is, those macros attempt to send messages to an object
pointed to by a variable called parameters.
The random variate macros:
-
extern id uniformUR, uniformIR, uniformDR, normalDR, gammaDR, logNormalDR;
getUniformU(mn,mx)
getUniformI(mn,mx)
getUniformD(mn,mx)
getNormalD(mean,var)
getLogNormalD(mean,var)
- Call these to get random variates of the various types described.
These send messagest to the distribution objects specified on
the extern line.
-
getNormalDPRepeatUntilInRange(mean,var,mn,mx)
- This keeps trying to get a normal variate with mean and max
as described, but requiring it in [mn,mx].
Subroutines for getting the values of parameters:
These subroutines can be used anywhere in a program
(but you do need to import the Parameters.h file
for your Parameters object).
Note the case of these (small "r" to start)!
-
retDPar("Name")
retIPar("Name")
retSPar("Name")
retUPar("Name")
retFPar("Name")
retBPar("Name")
- These return value of parameter of specified type, where
D=doublePar, I=intPar, S=stringPar, U=unsignedPar, F=floatPar and
B=boolPar. Its the callers responsibility to be sure the
parameter Name is of the specified type. The value returned
is of the specified type.
The macros for getting values of parameters:
Note all these macros for getting values of parameters
depend on having in scope a variable named "parameters"
which points to the user's RParameters instance.
-
RetDPar("Name")
RetIPar("Name")
RetSPar("Name")
RetUPar("Name")
RetFPar("Name")
RetBPar("Name")
- Return value of parameter of specified type, where
D=doublePar, I=intPar, S=stringPar, U=unsignedPar, F=floatPar and
B=boolPar. Its the callers responsibility to be sure the
parameter Name is of the specified type. The value returned
is of the specified type. These depend on having a
variable "parameters" in scope.
-
getDPar("Name")
getIPar("Name")
getSPar("Name")
getUPar("Name")
getFPar("Name")
getBPar("Name")
- Aliases which do the same as the analogous RetXPar macros
describe above.
-
RetDParFrom(p,"Name")
RetIParFrom(p,"Name")
RetSParFrom(p,"Name")
RetUParFrom(p,"Name")
RetFParFrom(p,"Name")
RetBParFrom(p,"Name")
- These macros are analogous to those above, except
the take a first argument which is a pointer (id) to the
Parameters object which has the parameters.
-
#define FTC(t) (*(id *)(&t))
- This is useful for getting values of various types back
from perform-calls to execute methods.
Need more notes here...
-
extern unsigned int *GlobalRDebug;
#define DMSG(N,S) if(*GlobalRDebug >= N) fprintf S;
- This macro can be used to conditionally print
debugging messages, under the control of the built-in
parameter rDebug (-D). A typical call to this would look like
DMSG(3,(stderr,"A message with one double value %d .\n",dd));
This would print out that message with D parameter is greater than
or equal to 3, on stderr, substituting the value of dd in the message.
-
BOOL IsInt( char *s );
BOOL IsUInt( char *s );
BOOL IsFloat( char *s );
int SameString( char *s1, char *s2, int KeepCase );
char *stripUI ( char *buff, unsigned int *v );
char *stripFloat ( char *buff, float *v );
#define max(a,b)
#define min(a,b)
- Some utility functions and macros.
How to use RParameters in your Swarm application
This section describes one way to use the RParameters object.
The basic steps necessary to use RParameters in this way are roughly
as follows (assuming you have a Swarm application that
has a top structure that approximates that of the basic
heatbugs application):
0. Make your Makefile look like the one in
/appl/swarmXXX-um/UM-HeatbugsPlus
(XXX=2.1.1 for version 2.1.1 of Swarm and UM-HeatbugsPlus.)
In particular, it links in the ExpTools4 library,
and it tells make to include the path to the *.h files
from ExpTools on the compile commands.
1. Define a Parameters object in your application,
a subclass of RParameters.
This will hold instance variables for all parameters
you want to be settable on the command line or via the GUI.
The super class provides the following parameters:
reportFileName (RFN) = report
file to which report will be written
reportFileNameSuffix (RN) =
appended to reportFileName, after a dot (.)
reportFrequency (RF) = 1
frequency averages will be written to report
outputDirName (OD) = .
directory into which report will be written.
default is the directory in which heatbugsPlus is run.
NOTE: the directory must exist.
stopT (T) = 4
number of steps to run in batchmode.
seed (S) = 0
RNG seed. Default (0) means generate a new one
from clock time and process number.
inputFileName (IF) = rparameters.in
file from which parameters were read.
(this is ignore when in an input file!)
rDebug (D) = 0
sets rDebug flag (not currenlty used...could be used
to control debugging messages).
2. To your Parameters.h interface definition,
add your model-specific instance variables.
Note you don't have to add specific methods to get/set them.
3. In the Parameters+createBegin method, assign initial values,
and build a probe for the variables if you plan to use a GUI.
4. In the Parameters-initParameters object, create and add
a Parameter object for each of your new parameters.
Bascially you specify:
- Name: this must match the instance variable name!
- Alias: some short version of the name.
You will be able to use this on command lines, eg.
- The parameter type: unsignedPar, doublePar, intPar,
floatPar, stringPar, boolPar.
See the /appl/swarmXXX-um/UM-HeatbugsPlus/Parameters.m file for
examples of how to do this
(where XXX is, e.g., 2.1.1, for that version of Swarm).
3. Link your Parameters object (its best if you name
it "parameters") to your Observer, Batch and Model objects.
This can be done when you create the Parameters object,
as shown in the HeatbugsPlus example program.
4. Modify main.m and buildObjects methods so the
argc and argv can get passed to the RParameters
processComdLineArgC:Argv method, which you need
to send to your Parameters object.
You also need to import RParametersArgs.h and pass it to
the initialization function like this:
initSwarmArguments(argc, argv, [RParametersArgs class] );
(Again, see HeatbugsPlus).
Also send a message to the parameters object to
tell it the name and version of your program.
(This gets printed in the report file, eg.)
Other Classes in the UM-ExpTools-4 Library
This section describes some other classes that are included
in the UM-ExpTools-4 library.
To use each class, import the appropriate interface file.
NOTE: As of Swarm 2.2x, the Swarm libraries provide all the functionality
(and more) previous provided by these classes, e.g.,
the Averager provides moving averages and moving standard deviations.
So as of UM-ExpTools4 for Swarm-2.2x, these are no longer
in the UM-ExpTools4 library.
The RAverager Class
This is a simple subclass of the Swarm Averager object (see the
Analysis library).
It adds one method, getStd, to those provided by the base class.
-
-getStd
Returns the standard deviation associated with the mean.-
The RunningAverage Class
Documentation to be provided...
-
The Shuffler Class
Documentation to be provided...
-
The RParameter interface
The RParameter object and methods are not intended to be
used directly in user applications.
Instead, they are used by the RParameters object.
But for completeness, the RParameter interface is described here.
-(void) setParameters: (id) p;
-setParName: (char *) name Aka: (char *) A
Type: (ParameterType) type;
-setLB: (double) db;
-setUB: (double) db;
-createEnd;
-(char *) getParName;
-(char *) getParAlias;
-setDesc: (char *) desc;
-setsetFn: (SEL) aSel;
-(SEL) getsetFn;
