The following is a description of the four configuration command (config-cmd) sets: Variable config-cmds, Module config-cmds, Application config-cmds, and External config-cmds. Each config-cmd is composed of a name followed by a set of arguments enclosed in parentheses. Section 6 gives a detailed description of configuration file and config-cmd format.
The following is a list of the config-cmds that are accepted by Variable objects.
S ( scale, offset )
required float scale: s parameter in scale equation (Eq. 1)
required float offset: o parameter in scale equation (Eq. 1)
The Scaling config-cmd can be used to set the scaling parameters used in map input and output when converting between floating point values in the Driver and n-byte binary values in the archived maps.
The SME input scaling transformation routine uses the following equation in each cell of the map:
y = s*x + o, [1]
where y is the floating-point cell value, s is the scale parameter value, x is the n-byte HDF cell value (expressed as a long integer), and o is the offset that may be used to add or subtract the same value from all cells. The inverse of Eqn. 1 is used on output to create integer maps in HDF or animation format ( x = (y-o)/s ).
d ( mapSource, mapName)
required char mapSource: Source of Map.
required string mapName: Name of Map.
This config-cmd is used to initialize the current variable with a map mapName. The map is read from a source determined by the argument mapSource:
mapSource = ‘H’ : HDF map read from <ProjectPath>/Data/.
mapSource = ‘M’ : Map2 format map read from <ProjectPath>/Data/
mapSource = ‘G’ : GRASS Map read from GRASS.
mapSource = ‘P’ : PPM map read from <ProjectPath>/Data/.
mapSource = ‘A’ : ArcInfo Exchange format map read from <ProjectPath>/Data/.
mapSource = ‘V’ : ArcInfo SVF format map read from <ProjectPath>/Data/.
mapSource = ‘I’ : IDRISI map from <ProjectPath>/Data/.
mapSource = ‘E’ : ERDAS map read from <ProjectPath>/Data/.
mapSource = ‘C’ : CME format map read from <ProjectPath>/Data/.
For all except GRASS maps a full path (relative to root) may be specified for mapName to override the default search path <ProjectPath>/Data/. The Map is interpreted as a surface, i.e. the floating point values in each cell are treated as a continuous surface.
Note that when reading ppm maps no colormap is defined, so the SME simply concatenates the three bytes or integers ( RGB channel values, max value must be 255 or less ) representing a pixel to generate an integer value for that cell. This make no sense in term of colormaps- this format is provided only to allow construction of input maps by hand (or by user code) using a well defined format.
d ( mapSource, mapName)
required char mapSource: Source of Map.
required string mapName: Name of Map.
This config-cmd is used to initialize the current variable with a map mapName. The map is read from a source determined by the argument mapSource, as described in section 7.1.3. The map is treated as a class map, i.e. the integer values in each cell are treated as classification values. See the note in 7.1.3 regarding reading ppm maps.
t ( TSDataName, format)
required string TSDataName: TimeSeries data file name.
optional int format: TimeSeries format.
This config-cmd is used to update the values of the current variable with timeseries data from a set of timeseries data files. See section 10.3 for a description of timeseries datafile formats. The SME will search for TSDataName relative to the <ProjDir>/Data directory unless a full path (relative to root) is given for TSDataName.
At the beginning of the simulation the SME will read a timeseries datafile named <TSDataName><index>.ts, where <index> is a file index starting at 0. The driver will initialize the variable with this timeseries. When the simulation run has exceeded the temporal extent of the timeseries, the driver finds and reads (into the variable) the next timeseries in the dataset, obtained by incrementing <index>. This process will continue for the length of the simulation. If at any point an appropriately indexed timeseries is not found in the data structure, then the first series will be used.
mx ( fileName, Map1, Map2 )
required string fileName: Dbase File name.
required string Map1: Map Name.
optional string Map2: Map Name.
m4( dBaseName, MapName, functionName, args... )
required string dbaseName: DataBase Name.
required string MapName: Map Name.
required string functionName: Name of SQL function.
required strings args: Function Arguments.
This config-cmd is used to initialze map dependent parameters. The index x=(1 or 2) in the mx config-cmd gives the order of the mapping from class maps to parameters. This format is being phased out in favor of the m4 format.
The m4 config-cmd is used to read parameter from the Postgress database. It will initialize the variable with the map-dependent parameter data read from the specified dataBase. The functionName gives the name of an DBaseFunction object that is read from the SQLFunctions.SMML file in the project’s UserCode directory, and the following arguments are passed to the SQL Function defined by that object. When the simulation is run, the value of the variable will be determined at each point as a function of map MapName in SME.
The user can specify the default behavior by specifying the functionName sme-default, which is predefined in the default SQLFunctions.SMML file. This function takes three arguments: ( tableName, sectorName, parmName). It assumes a table named tableName with (at least) four colums. The required columns are called (SectorName, ParmName, HabIndex, ParmValue). Note: this table can be created using the SME dBase interface, execute ‘SME db’ for info. In this case the data for the map dependent parameter is read from the ParmValue field in rows with SectorName=sectorName and ParmName=parmName.
The user may read data from databases configured differently by creating new DBaseFunction objects in the SQLFunctions.SMML file. The recommended preocedure is to copy and edit the sme-default object (giving it a new name) and then reference that object in the m4 command. See section 11.2 for more details on creating new database readers.
p ( PTSname, format )
required string PTSname: Name of PTS data structure in HDF file.
optional int format Format of the PTS.
The Point Timeseries config-cmd is used to configure the current variable as a PointTimseries, and initialize the variable with a PointTimeseries data structure (see section 10) from the PTS file PTSName. The value of this spatial variable will generated at the beginning of each timestep by interpolation between a set of spatially referenced timeseries.
DD ( )
This command is used to send the Variable data to the java Viewserver at each timestep. Once in the Viewserver, the data may be visualized using the Viewserver’s palette of visualizers.
M ( D, precision, fileName, scale, offset )
required char D: Destination of Map.
required int precision: Number of bytes per cell in output map.
required string fileName: Name of output file.
optional float scale. Scale Parameter.
optional float offset. Offset Parameter.
optional float cellsize. Cellsize Parameter.
The Map "M" config-cmd causes spatial variable data to be output to a map named <fileName>. The D parameter determines the type of map output:
D = H : Output in HDF Format to DriverOutput/Animation/ dir.
D = S : Output in SDS Format to DriverOutput/Animation/ dir.
D = M : Output in MapII Format to DriverOutput/Maps/ dir.
D = B : Output in Binary Format to DriverOutput/Maps/ dir.
D = A : Output in ArcInfo exchange Format to DriverOutput/Arc/ dir.
D = a : Output in ASCII Format to DriverOutput/Maps/ dir.
D = G : Output in GRASS Format.
D = P : Output in PPM Format to DriverOutput/Maps/ dir.
D = C : Output in CME Format.
D = I : Output in HDF Format to DriverOutput/DriverOutput.hdf file.
The precision argument value determines the number of bytes of output data for each cell. The smaller the map size the more rapid the processing rate, therefore it is most efficient to minimize precision. The scale and offset parameters are handled the same as in the S() config-cmd, section 7.1.2. When outputting Arc exchange maps the cellsize parameter should be used to set the cellsize field in the Arc header, and the UTM global Config-cmd (section 7.4.4) should be used to set the UTM coordinates of the corners of the map.
P ( c0, c1 )
required int c0: Row coordinate of timeseries output.
required int c1: Column coordinate of timeseries output.
The Point Timeseries Output config-cmd is used to output a timeseries consisting of the value of the variable evaluated at cell location (c0,c1) at each timestep. All coordinates used in the Driver follow the MapII convention (origin at the upper left-hand corner of the map). The first coordinate c0 is the number of rows below the origin, and the second coordinate c1 is the number of columns to the right of the origin. A string of P(c0,c1) statements may be added for output at more than one point (cell). Currently, the output of each P() config-cmd declaration is written to a separate TEXT file in the project’s DriverOutput file. The file name will begin with the name of the variable being configured, and will end in a SME-defined extension. This convention is subject to change in future versions.
W ( c0, c1, size, format)
required int c0: Row coordinate of center of window.
required int c1: Column coordinate of center of window.
required int size: Window size parameter Sz.
optional int format.
The Window config-cmd can be used to archive a square sub-array of cell values from any spatial variable. The values are not scaled, i.e. floating-point cell values are stored in floating-point format. The config-cmd arguments are used to locate and size the square array. The first two window config-cmd arguments are the coordinates of the window center (c0,c1) (see discussion of coordinate system in the Section 2.4). The third argument defines the window size Sz. The window size is defined as (2Sz+1) by (2Sz+1) centered at (c0,c1), which indicates the number of rows above and below the center cell, and the number of columns to the left and right of the center. For example if Sz is 2 then the window array is 5 x 5. The window center coordinates can be located using the tracker feature in Map II on the spatial data files. Currently, the output of each W() config-cmd declaration is written to a separate TEXT file in the project’s DriverOutput file. The file name will begin with the name of the variable being configured, and will end in a SME-defined extension. This convention is subject to change in future versions.
C ( c0 ,c1, size, type )
required int c0: Row coordinate of center of Combine window.
required int c1: Column coordinate of center of Combine window.
required int size: Window size parameter.
optional char type: Type Π{ M, m, S, A }.
optional char format:
The Combine config-cmd can be used to obtain several iterative or cumulative calculations for any spatial variable for all (and only) outStep iterations in a defined array of cells.
The first three config-cmd arguments are used to locate and size the array (the Combine window), and the argument form is identical to first three arguments in the "W" config-cmd (see section 7.1.11). Combined calculations for the whole study area may be output by selecting a combine window that covers the whole study area map. The Combine facility ignores all cells outside the study area. The array will be a square only if it is wholly contained in the study area.
The last argument (type) is used to define the type of operation to be performed over the window cells at outStep iterations:
Type Function
S Iterative and cumulative sum.
A Iterative and cumulative average.
m Iterative and cumulative minimum.
M Iterative and cumulative maximum.
Cumulative operation apply the operation cumulatively over all valid timesteps, non-cumulative operations are re-applied at each valid timestep. Currently, the output of each C() config-cmd declaration is written to a separate TEXT file in the project’s DriverOutput file. The file name will begin with the name of the variable being configured, and will end in a SME-defined extension. This convention is subject to change in future versions.
G (c0, c1, Rmin, Rmax, Dmin, Dmax, index)
required int c0: Row coordinate of point to be graphed.
required int c1: Column coordinate of point to be graphed.
required float Rmin Minimum y axis value.
required float Rmax Maximum y axis value.
optional float Dmin Minimum x axis value (initial time).
optional float Dmax Maximum x axis value (final time).
optional int index Graph index.
The Graph config-cmd can be used to generate a timeseries graph of the value of the current variable at cell coordinates (c0,c1). . (Note this command is only available if the SME is installed with JSimTools enabled). The graph is displayed on the screen and is updated each timestep of the simulation. The arguments (Rmin,Rmax) set the range of the graph. If the current variable is non-spatial then the first two arguments are ignored. The Max/Min axis value simply provide initial values, the graph can be rescaled at any time using buttons on the viewer. If (Dmin,Dmax) = (0,0) then the start and stop time of the simulation will be used as max and min values of the graph’s time axis.
GS ( cell0, cell1 )
required int c0: Row coordinate of output cell.
required int c1: Column coordinate of output cell.
Note: this command is currently unavailable.
{ This config-cmd outputs a timeseries consisting of the value of the variable evaluated at cell location (c0,c1) at each timestep. All coordinates used in the Driver follow the MapII convention where the origin is in the upper left-hand corner of the map. The first coordinate c0 is the number of rows below the origin, and the second coordinate c1 is the number of columns to the right of the origin. The output is displayed numerically in a spreadsheet-like format. }
pm ( pValue0, increment, step, modStep )
required string pValue0 Initial value of Parameter.
optional float increment parameter adjustment increment
optional int step parameter adjustment step
optional int modStep parameter adjustment modStep
This config-cmd used to declare the current variable to be a simulation parameter and define the parameter's value. Parameters are constants whose value is read by the Diver at runtime from the Driver config file. By default, all VIEW variables that are defined by a numeric value only are declared as parameters by CGP in the CGP configuration file. The first argument, pValue0, is the initial value of the parameter. The remaining arguments are used in sensitivity analyses to change the value of the parameter each time the simulation. If these extra arguments are used, then the value of the parameter, pValue, for the i'th simulation run is run by the equation:
pValue = pValue0 + increment*( (i/step) % modStep )
where % is the modulus operator.
i (iLevel,rValue)
required int iLevel: Ignore action level.
optional string rValue: Replacement value.
The ignore config-cmd tells CGP or MCP that this VIEW variable is not used (ignored) in the spatial unit model. The variable will not be declared in the Driver code. If iLevel is >0 then wherever the variable is referenced in the model it's value will be replaced by rValue. If rValue is not specified then it defaults to 0.0. If iLevel is =0 then if the variable is referenced anwhere in the model a compile error will be generated at build time.
s ( INX )
required char I: Clamping Method: Π{ C, N }.
required int N: Integration order: Π{ 1, 2, 3, 4 }.
required char X: IntegrationMethod: Π{ C }.
This config-cmd is used to declare a variable to be a State Variable and define the variable's integration routine (which may differ among state variables). This config-cmd is generated by the code generators, so the user should not delete or create new s() config-cmds. The user may, however, change the integration method. The string argument that is used to configure the integration method is composed of three characters, denoted above as I, N, and X. The first character configures state variable clamping ( C= clamp, N=noclamp ). The second character, which must be an integer between 1 and 4, configures the order of the integration method. The last character currntly must be ‘C’, which denotes constant time step. The default configuration is s(C1C).
The SME uses an explicit Adams-Bashforth integration algorithm of order N. The clamping algorithm prevents the state variable from going negative by constraining the outgoing fluxes such that they never take a total value that is greater then the current amount in the state variable.
oi ( tI, sI )
optional int tI: Time Index.
optional int sI: Space Index.
The Override Initialization config-cmd is used change the variable’s space/time properties from the config file. If tI > 0 then the variable is declared to be constant. If sI > 0 then the variable is declared to be spatial.
rs ( mode )
required char mode: Spatial Mode of rnadom number generator ( ‘s’ or ‘n’ )
If mode = ‘s’ then this config-cmd declares all random number generators (RNGs) referenced by this Variable’s update equations to be spatially-articulated. That is, each RNG will generate an independently calculated random value in each cell in the Variable’s grid during an update calculation. The default behavior is to generate a single random value across the entire grid. If the Variable does not reference a RNG in it’s update equation then this command has no effect.
B ( max, min, Errormode )
required float max: Max Value of Variable data.
required float min: Min Value of Variable data.
required char mode: Spatial Mode of rnadom number generator ( ‘s’ or ‘n’ )
This config-cmd is used to check the bounds on a Variable’s internal data at each update. If a Variable’s data falls outside of the limits imposed then an Error is flagged. This config-cmd is operative at optimization level 0 only.
ip ( value )
required float value: Value of input Variable.
This config-cmd is used to override the default value given to a Module’s Input Variable. This is typically used if the input comes from a Module that is being ignored, and the default value for broken inputs (0.0) causes the simulation to blow up.
UF ( fileName, functionName, functionArgs )
required string fileName: Name of User Code FIile.
required string functionName: Name of Function defined in User Code FIile.
required strings functionArgs: List of arguments to function.
This config-cmd is used in the MCP configuration file create a new sim-cmd for the current Variable that executes a function defined by the user. The first argument to the UF() config-cmd is the name of the file in which the function is defined. This file should be located in the project workspace as <projDir>/UserCode/< fileName>.cc. The second argument is the name of the user-defined function. The third argument functionArgs is a comma-delimited list of names of variables in the model. This command causes MCP to create the SMML code defining the new sim-cmd, and set up the makefiles for compiling and linking the UserCode file < fileName>.cc with the Driver. The current Variable is always passed as the first argument to the function, followed by the argument list declared in this config-cmd. The function should be written using C++ objects declared in the SME Programming Interface, documented in section 11. The sim-cmd is generally executed just after the current Variable’s other sim-cmds. However, if the user appends the operator “END^” to the funcionName ( e.g. END^SWTransport ) then the sim-cmd is executed after all other sim-cmds for all modules have been executed for a given timestep.
This config-cmd is typically used to implement intercellular fluxes (e.g. of water and waterborne constituents).
F ( Library, functionName, functionArgs )
required string Library: Name of SME Library.
required string functionName: Name of Function defined in Library.
required strings functionArgs: List of arguments to function.
This config-cmd is used in the MCP configuration file create a new sim-cmd for the current Variable that executes a function defined in one of the SME libraries of spatial functions. The first argument to the UF() config-cmd is the name of the Library in which the function is defined. The only library currently existing is called Space, and the functions defined in this library are listed in the sme3/lib/SpaceLib.SMML file. See the sme3/lib/README.SpaceLib file for descriptions of these functions. The second argument is the name of a function defined in this Library. The third argument functionArgs is a comma-delimited list of names of variables in the model. This command causes MCP to create the SMML code defining the new sim-cmd. The current Variable is always passed as the first argument to the function, followed by the argument list declared in this config-cmd. This config-cmd is typically used to implement complex or long-range spatial operations such as global max/min/average, convection terms, or computing spatial indices.
The following is a list of config-cmds accepted by Module objects.
g ( mapSouce, StudyAreaMapName, linkMethodName )
required string mapSource Name of Map of Study Area
required string MapName Name of Map of Debug Points
optional string linkMethodName Name of Link Algorithm
This config-cmd causes the current module to be configured with a 2 dimensional grid frame. The StudyAreaMap is read and used to initialize the frame. The mapSource argument is described in section 7.1.1. The grid is set up with the same number of rows and columns as the StudyAreaMap, and every cell in StudyAreaMap that has a non-zero value is declared an active cell. The default link method links each cell to it’s eight neighbor cells in a rectangular grid.
Vß ( mapSouce, StudyAreaMapName, linkMethodName )
required string mapSource Name of Map of Study Area
required string MapName Name of Map of Debug Points
optional string linkMethodName Name of Link Algorithm
This config-cmd causes the current module to be configured with a 3 dimensional volume frame. The StudyAreaMap is read and used to initialize the frame. The mapSource argument is described in section 7.1.1. The grid is set up with the same number of rows and columns as the StudyAreaMap. The (integer) value at each (row,col) element in StudyAreaMap denotes the depth (in cells) of the (3D) Study Area at that coordinate. The default link method links each cell to it’s eight neighbor cells in a rectangular grid horizontally and to the pair of cells directly above/below each cell vertically.
t ( mapSouce, StudyAreaMapName, linkMethodName )
required string mapSource Name of Map of Study Area
required string MapName Name of Map of Debug Points
optional string linkMethodName Name of Link Algorithm
This config-cmd causes the current module to be configured as a tree network. A tree network is a network of cells in which each cell is connrcted to one other cell. It is typically used to represent river or canal networks, in which each cell in the network flows into only one other cell. The StudyAreaMap is read and used to initialize the frame. The mapSource argument is described in section 7.1.1. The grid is set up with the same number of rows and columns as the StudyAreaMap, and every cell in StudyAreaMap that has a value >0 and <9 is declared an active cell. The actual value in the cell is used to determine which of the 8 neighboring cells it is linked to, according to the format {NE=2,EE=3,SE=4,SS=5,SW=6,WW=7,NW=8,NN=9}.
es ( s )
required string s Script to be executed
This config-cmd directs the Driver to execute the script s in the shell environment at each of the Module’s update events.
i( )
The ignore config-cmd tells CGP or MCP that this module is not used (ignored) in the spatial unit model. The Module will not be declared in the Driver code. The user may need to use the Variable ip() config-cmd to reset the default value for broken inputs in other modules.
The following is a list of config-cmds accepted by the Model object.
n ( nSims )
required int nSim Number of times to re-run simulation
This config-cmd causes the simulation to be run nSim times. The default value is 1. This config-cmd may not be implemented yet.
op ( opLevel )
required int opLevel Optimization Level.
This config-cmd sets the optimization Level for the simulation. Most users will use the default value.
s( iSeed )
required int iSeed Seed for random number generator
This config-cmd causes the seed for the random number generator to be set to iSeed. CGP generates a default configuration of s(4332).
UTM( index, coord0, coord1 )
required int index index of corner (0,1)
required float coord0 UTM coordinate
required float coord1 UTM coordinate
This config-cmd is used to associate a UTM coordinate system with the study area of the simultion. This coordinate system can be referenced, for example, when associating time series with map locations. Index 0 refers to the lower corner of the study area, index 1 refers to the upper corner.
Y( start, DT )
required float start Start year, e.g. 1956.37
required float DT Timestep of simulation in year units
This config-cmd allows the simulation to compute a time value in year units at each step of the simulation. This information can be used to read in timeseries data for various timespans during the course of the simulation.
The following is a list of config-cmds are are accepted by objects at any level ( Variable, Module, or Model ). Higher level configurations become default values for lower level objects, e.g. if no configuration is given for a Variable object then it inherits it’s configuration values from it’s Module object.
OS ( outStep, outStart, outEnd )
required int outStep: Output step.
optional int outStart: Output start index.
optional int outEnd: Output end index.
The OutStep config-cmd determines how often pipe sim-cmds will be executed. Each event has an index iS which starts at zero and is updated each time the event is executed. Each sim-cmd has a schedule containing the parameters (outStep, outStart, outEnd), and the sim-cmd is executed if (outStart > iS >= outEnd) and (iS >= iS0 + outStep), where iS0 is the event index at the last execution of the sim-cmd. When OS is used on the command line of the config file, it applieas to all pipe config-cmds on the line prior to itself and after any other OS() config-cmds on the line. When OS is applied at runtime, it applies to either the current sim-cmd (when executed at command level) or to all pipe sim-cmds of the current variable (when executed at variable level).
OT( tStep, Start, Stop )
required float tStep Value for simulation timestep
required float tStart Value for simulation initial time
required float tStop Value for simulation final time
This config-cmd configures the schedule of the current object ( Command, Variable, Module, Model). It causes the execution timestep to be set to tStep, and the initial and final execution times to be set to tStart and tStop respectively. The Schedule of a higher level object (e.g. Variable) is inherited by lower level objects (e.g. that Variable’s sim-cmds) as a default which may be overridden by an OT command at the lower level. At the Module and Model level the Schedule is attached to the object’s Events, at the Variable amd Command level the Schedule is attached to the Object’s sim-cmds.
At the Event level, a Schedule detemines how an event is scheduled. The Event will be scheduled to be executed first at tStart. Each time the Event is executed it is rescheduled to be executed again tStep timeunits later until the simulation time is greater then tStop.
At the Command level, a Schedule determines how often a sim-cmd is executed. Each sim-cmd is associated with an Event, and by default a sim-cmd is executed every time it’s Event is executed. However, if a Schedule is specified for the sim-cmd, then each time the Event is executed the Schedule is checked to see if it is OK to ececute the sim-cmd. The Schedule grants the sim-cmd execution permission if the following three conditions are satisfied:
1. cur_time >= tStart,
2. cur_time <= tStop,
3. cur_time >= last_exec_time + tStep
where cur_time = current simulation time and last_exec_time = simulation time when the sim_cmd was last executed.
When OT is used to configure a Variable object in the config file, it applies to all pipe config-cmds on the current line that are prior to itself and after any other OT() config-cmds on the line. { If the OT cnfg-cmd is first on the line, it is applied to the Variable object directly: this usage is experimental } When OT is applied at runtime, it applies to either the current sim-cmd (when executed at command level) or to all pipe sim-cmds of the current variable (when executed at variable level).
d( dLevel )
required int dLevel Debug Level
This config-cmd causes the object’s debug level to be set to dLevel.