The
Spatial Modeling Environment
Users Guide
1. Introduction 4
1.1 Obtaining the SME 4
2 Building Models Using The SME 5
3. Unit Model Development 6
3.1 STELLA Model Guidelines 6
3.2 Specifying Order of Outflow Calculation 7
3.3 Creating the STELLA Equations File 7
4. SME Object and Command Types 7
4.1 SME Object Hierarchy 7
4.1.1 Model Object 7
4.1.2 Module Object 7
4.1.3 Variable Object 8
4.1.4 Frame Object 8
4.1.5 External Objects 8
4.2 SME Commands 8
4.2.1. Configuration Commands 9
4.2.2 Simulation Commands 9
4.2.3 Execution Commands 9
4.3 SME Simulation Dynamics and Scheduling 10
5 Using the SME Command-Line Interface 10
5.1 Using the SME Script 10
5.1.1 Creating Projects 11
5.1.2 Creating Models 11
5.1.3 Importing Modules 11
5.1.4 Creating Scenarios 12
5.1.5 Building Models 12
5.1.6 Running Models 12
5.1.7 SME Utilities 13
6 Model Configuration 13
6.1 Reading Configuration Files 13
6.2 Configuration file format 14
6.3 Configuration commands 14
7: SME Configuration Commands 15
7.1 Variable Configuration Commands 15
7.1.2 Scaling Config-cmd S() 15
7.1.3 Surface Map input config-cmd d() 16
7.1.4 Class Map input config-cmd c() 16
7.1.5 Serial Timeseries Input Config-cmd t() 17
7.1.6 Dbase Input Config-cmd mx() 17
7.1.7 Point Timeseries Config-cmd p() 18
7.1.8 Send to Viewserver Config-cmd DD() 18
7.1.9 Map Output Config-cmd M() 18
7.1.10 Point Timeseries Output Config-cmd P() 19
7.1.11 Window Config-cmd W() 19
7.1.12 Combine Config-cmd C() 20
7.1.13 Graph Config-cmd G() 21
7.1.14 Sheet Data Config-cmd GS() 21
7.1.15 Parameter Config-cmd pm() 21
7.1.16 Ignore config-cmd i() 22
7.1.17 State Variable Config-cmd s() 22
7.1.18 Override Initialization Config-cmd oi() 23
7.1.19 Spatial Random Config-cmd rs() 23
7.1.20 Bounds Config-cmd B() 23
7.1.21 Input Override Config-cmd ip() 23
7.1.22 User Function config-cmd UF() 24
7.1.23 Builtin Function config-cmd F() 24
7.3. Module Configuration Commands 25
7.3.1 2D Grid Frame Config-cmd g() 25
7.3.2 3D Volume Frame Config-cmd V() 25
7.3.3 Tree-network Frame Config-cmd t() 25
7.3.5 Execute Script Config-cmd es() 26
7.3.6 Ignore config-cmd i() 26
7.4. Application Configuration Commands 26
7.4.1 ReSimulation Config-cmd n() 26
7.4.2 Optimization Config-cmd op() 26
7.4.3 Seed Config-cmd s() 27
7.4.4 Global Coordinate System Config-cmd UTM() 27
7.4.5 Year Config-cmd Y() 27
7.5. General Commands 27
7.5.1 OutStep Config-cmd OS() 27
7.5.2 Schedule Config-cmd OT() 28
7.5.3 Debug Level Config-cmd d() 29
8 Driver Command Line Interface 29
8.1 Simulation Control Sim-cmds 29
8.1.1 Step Sim-cmd: s 29
8.1.2 Run Sim-cmd: r 29
8.1.3 Break Sim-cmd: b 30
8.1.4 Stop Sim-cmd: S 30
8.1.5 Exit Sim-cmd: X 30
8.2 Sim-cmds for Setting Context 30
8.2.1 Set Module Sim-cmd: m 30
8.2.2 Set Variable Sim-cmd: v 31
8.2.3 List Objects Sim-cmd: l 31
8.2.4 Choose Object Sim-cmd: c 31
8.3 Data Access Sim-cmds 32
8.3.1 Query Sim-cmd: q 32
8.3.2 Dump Sim-cmd: d 32
8.3.3 Dump Grid Sim-cmd: dg 32
8.3.4 Dump Point Sim-cmd: dp 33
8.3.5 Display Code Sim-cmd: dc 33
8.3.6 Display Data in Viewer: dv 33
8.3.7 Variable Data Sim-cmd: V 33
8.4 Configuration Sim-cmds 33
8.4.1 Configure Sim-cmd: C 33
8.4.2 Network Sim-cmd: N 34
8.4.3 Delete Pipe Sim-cmd: k 34
9 Viewing Simulation Output 34
10. SME Data Preparation 35
10.1 Maps 35
10.1.1 Map II format 35
10.1.2 GRASS format 35
10.1.3 HDF format 35
10.1.4 ArcInfo format 35
10.2 Timeseries Data 36
10.3 PointTimeseries Data 36
10.4 Class-Dependent Parameter Data 37
11. SME Programming Interface 37
11.1 C++ Programming Interface 37
11.2 SQL Programming Interface 37
12. SME Java Interface 38
12.1 Using the standalone ViewServer 38
12.1 Using the full java interface 38
13. STELLA Array Support 39
For a general introduction to the Spatial Modeling Environment (SME), see the SME OverView. This document provides hands-on directions for using the SME. In this document, the term View refers to the graphical modeling environment (e.g. STELLA, Extend, etc.) that is used to create the set of unit modules, see the SME OverView and section 4 for further terminology discussion.
Our latest Spatial Modeling publication can be accessed via the World Wide Web at:
http://iee.umces.edu/SME3
Our papers and software can also be downloaded from our anonymous ftp site:
ftp://iee.umces.edu/SME3
The following documents are available in directory SME3:
sme*.tar.gz :SME source distribution for UNIX.
README :Text file with installation instructions.
Docs/SME*.pdf :SME full documentation in Adobe pdf format.
Docs/README :TEXT file describing SME documents.
The SME should be installed following the directions in the README file. The following guidelines assume that the SME distribution has been succesfully unpacked and installed.
The SME is designed to runs spatial simulations generated from a set of unit model specifications in the Simulation Module Markup Language (SMML). There are three methods for generating SMML code: 1) write a model in SMML using a text editor 2) use an external modelling package import its (exported) equations into SMML and 3) use a SMML graphical modelling tool (provided in SME java interface). Currently the only supported translator is designed to be used with STELLA models. Refer to Section 3 for naming conventions and hints on how to export a proper STELLA equations file. The following steps are involved in building a model using the SME.
1) Unit Model development (section 3). An ecosystem cell model is developed using a graphical modeling tool (STELLA or another supported modeling package), referred to here as "View" (See the OverView document for clarification). Guidelines for preparing a STELLA model for import to the SME are given in Section 4.1.
2) Project creation (section 5.1). A Project is a directory tree that will contain all of the sources, executables, data, and simulation output associated with a simulation model. Henceforth this directory will be referred to as <ProjectName>.
3) Module construction (section 5.1). The application MCP may be used to import View equation files into the Simulation Module Markup Language (SMML). Each View sector is converted into an SMML Module object. The user can link modules from various sources at this step, and create new SMML modules using a TEXT editor or a graphical SMML development tool.
4) Data assembly. The maps and time series data that will be input to the simulation must be assembled in the proper format. The SME includes tools for importing data in a number of commonly used formats (see section 10).
5) Code generation (section 5.2) and configuration. The application CGP is used to convert the SMML objects into C++ objects which plug into our distributed simulation driver application (Driver). The user then provides configuration information, either by editing a set of configuration files that are generated by the CGP application, or by entering configuration information into the java interface's Configuration panel.
6) Simulation run (sections 5.3). The runs the simulation by executing the Driver application using either the SME java interface (section 12) or the command line interface (section 8).
7) Output analysis (section 6). There are several built-in methods for displaying the non-spatial and spatial model output.
The following sub-sections provide guidelines for preparing STELLA models for import into the SME. Similar guidelines should be followed when using other graphical modeling tools.
The STELLA importer is compatible with STELLA II v. 2.2 (and later) or any version which generates equivalent equations. If you are using an earlier version that saves equations in a different format you may run into problems.
There are some limitations to the SME's implementation of STELLA models: 1) although we have implemented the most commonly used STELLA built-in functions, it is unlikely that all the functions in all versions of STELLA will be implemented, 2) Converters (as of 6/99) have not yet been implemented, 3) The SME support for STELLA arrays is limited to map-dependent parameters (see section 13), and 4) the STELLA DELAY function must take a single variable as an argument (not an equation).
One can write equations that access values in neighboring cells (in the spatial model) via the following convention: Any variable vName@N (or @E, @W, @S) is interpreted to represent the value of the variable vName in the cell directly to the North of the current cell. Except for this usage, no variable names should contain the character '@'. More generally, the notation vName@(x,y) is used to access the the value of the variable vName in the cell x cells to the North and y cells to the East of the current cell. In a 3D simulation, 3 dimensional coordinates can be used and the notations @U and @D may be used to denote the cells up and down from the current cell.
Boundary conditions can be specified using the notation vName@D:BC, where D is a relative coordinate (as described in 2) and BC is a boundary condition notation. Possible values for BC are:
S or C: Continuous BC: Returns value in current cell if referenced cell is not in StudyArea ( default ).
Z or 0: Zero BC: Returns 0 if referenced cell is not in StudyArea .
T: Test BC: Returns +1 if referenced cell is in StudyArea, -1 otherwise.
No special characters 1 should be used in STELLA variable names, e.g., ?, #, &, unless specifically permitted above.
The order of calculation of outflows in STELLA is determined by the order in which they were created. This may be overridden by the introduction of flow dependencies in the equations for flow. In the SME, the order of calculation of outflows from state variables is ordered by dependency, if no inter-flux dependencies exits then the ordering is undefined (random). The user may define the order of calculation by placing "dummy dependencies" in the outflow equations of the STELLA unit model. For instance if outflow B is to be calculated before outflow A, then make A dependent upon B by inserting the kludged dependency "+B*0" into the equation for A.
The user must create an equations file from the STELLA unit model that will be translated into SMML by the MCP application. To display the equations in proper format, bring up the equation window and display the equations in order of sector with the 'show documentation' switch turned off. Due to a bug in STELLA II, you may have to cut and paste these equations into a text file in order to create the equations file (otherwise equations may be randomly deleted).
This section introduces some terminology which will aid in the understanding of the remainder of this document.
An “object” is a structure that contains both data and methods for operating on that data. The primary SME applications (Module Constructor (MCP), Code Generator (CGP), and Driver) share a common set of object hierarchies. In this section we discuss five classes of objects that are relevant to this document: Model, Module, Variable, Frame, and External.
The Model object, (also refered to as the “Application object”) is the top level controller that handles execution of tasks. All communication with the application is handled through the Model object. The Model object handles a list of Module objects.
Each module (sector) in the View application, and each Module object defined in SMML, correspond to an SME Module object. A spatial simulation running within the SME is structured as a set of independent Module objects, each with a unique spatio-temporal representation, defined by a data structure called a Frame object. The Module object handles a list of Variable objects.
Each variable in the View application, and each Variable object defined in SMML, correspond to a SME Variable object. Each Variable object has an internal data structure (IDS) that may be updated during the course of the simulation. Variable objects fall into a number of different classes based on their IDSs. Some of the most common Variable classes are:
Spatial Variables: IDS contains one float for each active cell in a spatial grid (generated by the Module’s Frame object).
Temporal Variables: IDS contains one float for each timestep of the simulation.
Class-Dependent (or Map-dependent) Variables: IDS contains one float for each possible class (e.g. LandUse, SoilType) value.
TimeSeries Variables: IDS contains a timeseries read from the simulation input database. May be spatially referenced.
Extraploated TimeSeries Variables: IDS contains a spatial array (one float for each active cell in a spatial grid) generated by extrapolating between the current float values from a set of spatially referenced timeseries read from the simulation input database.
Each Module has a Frame object which generates the spatial grid for it’s Spatial Variable objects. The Frame object includes a specification of the topology of the module, implemented as a set of Point objects (cells) with (inter-cellular) links, as well as methods for transferring/translating data to/from other Frames. The SME maintains a catalog of available Frames. Examples include two-dimensional grids (e.g., for landscapes), graphs and networks (e.g., for river, canal, or road networks), and Point sets (e.g., for embedded lumped-parameter models). By this method simulations involving modules with disparate spatio-temporal scales can be executed transparently, since each module’s Frame knows how to remap incoming data to fit it’s topology, and remap outgoing data into a universally acceptable format.
External Objects are used to wrap code that is external to the SME (i.e. user generated or modified).
There are three types of Commands utilized in the SME: configuration commands (config-cmds), simulation commands (sim-cmds) and execution commands (exe-cmds).
Configuration commands are passed to the four classes of objects described in section 4.1 in any of the SME applications (MCP, CGP, Driver) to configure code translation & generation, and set up the simulation. These commands are generated by three methods:
Editing configuration files, which are read by the SME applications.
Inputting configuration information through the SME java interface.
Inputting commands through the SME Driver command-line interface.
These commands are discussed in detail in secions 6 and 7.
Simulation commands (sim-cmds) are passed to the Model object in the SME Driver during a running simulation to configure and control the simulation. The commands are generated by two methods:
User generated sim-cmds: In this case the user types the sim-cmds at the SME> prompt during a simulation runnning in stand-alone mode (without the full java interface).
Interface generated sim-cmds: In this case the user controls the simulation through the buttons and menus of the java interface, the interface then creates the sim-cmds and passes them to the running Driver application.
These commands are discussed in detail in section 8.
Execution commands (exe-cmds) constitute the “actions” that update the data structures of the Variable objects during a running simulation. These commands are not directly accessible by the user, but can be impacted by means of config-cmds and sim-cmds. Each Variable object handles a list of exe-cmds that are used to update that Variable’s data structures. There are a number of different types of exe-cmds:
Update: These exe-cmds are used to update the Variable’s data structures using the equations defined in the SMML module definition. There are two specializations of update exe-cmds: Init-exe-cmds, used to initialize the data structures of State Variables, and Statevar-exe-cmds, used to update the data structures of State Variables.
Pipe: These exe-cmds are used to move data between the Variable’s data structures and the simulation dataBase. . There are two specializations of pipe exe-cmds: input pipes and output pipes.
Function: These exe-cmds are used to execute user-defined functions that modify the Variable’s data structures.
Script: These exe-cmds are used to execute a user-defined script in the Shell environment.
The dynamics of a simulation in the SME Driver are executed by a set of exe-cmds organized by a set of Event objects. Each Event object has a time stamp and a sorted list of exe-cmds. The SME Model object has a list of Event objects, sorted by increasing time stamp. The simulation dynamics are generated by consequtively executing Events in the Event list. When an Event object is executed, the following actions are generated:
1) The global simulation time is set equal to the Event’s timestamp.
2) The exe-cmds in the Event’s command list are consequtively executed.
3) The Event object determines the next time it should be executed using it’s Schedule object, as describe in section 7.5.2.
4) The Event object changes it’s timestamp to the new execution time and re-posts itself to the Model’s Event list.
The exe-cmds in the Event’s command list are sorted by dependency. For Example, if variable A’s update exe-cmd references (i.e. uses in it’s equation) the value (IDS) of variable B, and variable B has an exe-cmd in the same list, then variable B’s exe-cmd will always be executed before A’s. Event objects inherit their Module’s Schedule by default, which can be configured using the Module OS() and OT() config-cmds (sections 7.5.1-2).
The SME consists of three primary applications, the Module Constructor (MCP), the Code Generator (CGP), and the SME Driver (Driver). The user may invoke these applications either through a command line interface or using the SME graphical user interface. ). The functionality of the applications was outlined in section 2 and the Overview document. In this section we discuss the most commomly used command line interface, accessed by invoking the SME script.
Building projects and models is accomplished by means the SME script, installed by the 'install' target of the makefile. The usage of the script (for most up-to-date info use 'SME -h' ) is as follows:
Usage:
SME [options] { project | model | scenario | import | build | run } [args]
options:
-h :print usage help
-p :parallel (MPI) code
-java <host> : Use java interface on <host> ( use localhost for local machine )
arguments:
project <pname> [pdir] :Sets current proj/workspace
model <mname> :Sets current model
scenario <sname> [prev_scen] :Sets current scenario Copies config files from previous scenario
import <modelName> <STELLA file> :import STELLA file
into model modelName
build :create/build current model.
run :run current model
clean <modelName> :delete unnecessary files
of model <modelName>
db <dbArgs> :SME database interface
The -p flag tells it to use MPI code (error messages result if an MPI version of the SME has not been installed).
SME maintains a 'current' project and a 'current' project directory that are written into $HOME/.sme_project. These are accessed and changed through the SME script: the file is not meant to be modified manually. If you execute the SME script with no arguments it will tell you the current directory and project. To create a new project, execute:
SME project <projname> [projdir]
If you supply projdir this becomes the current root directory of the projects. This directory is not project-specific: the actual project will be created in a directory <projname> under it. If you do not supply projdir, the current one is used if set, otherwise the program will ask you if you want to use the current directory. If you have already created a project, executing
SME project <projname>
will make projname the current one.
SME maintains a 'current' model that is written into $HOME/.sme_project. It is accessed and changed through the SME script: the file is not meant to be modified manually. If you execute the SME script with no arguments it will tell you the current model. To set the current model nane, execute:
SME model <modelname>
which will make <modelname> the current one.
To 'import' a set of modules from a STELLA equation file into the current model, execute:
SME import [<STELLA equation file>]
which will invoke the MCP application on the current imported equation file to create the corresponding set of SMML files, which will be put in the Models/<modelName>/ directory under the project workspace. If a <STELLA equation file> is specified then that file is imported into the Project (and becomes the current imported equation file). See section 6 for information on configuration options for the translator MCP which can be used to automate the process of adding/deleting SMML code to/from the SMML file (e.g. ignoring some variables or adding user-defined functions) each time it is generated.
SME maintains a 'current' scenario that is written into $HOME/.sme_project. It is accessed and changed through the SME script: the file is not meant to be modified manually. If you execute the SME script with no arguments it will tell you the current scenario. If no scenario is specified, then the SME assumes a default scenario named "def".
A scenario is a named configuration of a model. A model can have have any number of scenarios. To set the current scenario name, execute:
SME scen <scenario_name> <old_scen>
which will make <scenario_name> the current scenario. It will copy the previous scenario's config file to create an initial configuration for the current scenario. The previous scenario is taken to be the last one specified (or "def") unless <old_scen> is provided to specify a different one. See section 6.1 for a more detailed discussion of configuration files.
To create and/or build the current model, execute:
SME build
to build a simulation driver. This command first invokes the CGP application to convert the SMML files into C++ code to be linked into the SME Driver. The makefile will take care of all the dependencies and invoke the SMML and C++ compilers as needed.
After the C++ code has been generated, 'make' is invoked to build the model driver (MPI multiprocessing is used if it's installed and you supply the -p option).
To run the current model, execute
SME run
The correct driver will be invoked for MPI or serial, according to the -p option. Refer to section 6 for information on Driver configuration options, section 7 for information on data formats, section 8 for information on use of the SME driver command-line interface, and section 12 for information on running the SME with the java interface.
The command
SME clean
will delete the object files and the drivers associated with the current model. It will not delete the SMML file or any file that you import, so that you can run ‘SME build’ again after running ‘SME clean’.
The command:
SME db
will return a list of option for using the SME datbase interface. Execute SME db -help for a detailed description of the database interface.
The MCP, CGP, and Driver applications are configured using a simple configuration format, which is described in the following sections. The configuration commands (config-cmds) referred to in this section are documented in section 7.
When running under the command line interface, the MCP, CGP, and Driver applications read configuration files from the Project ‘Config’ directory to customize their behavior. (When running under the java interface, these commands may be viewed and edited from the Configuration panel ). In general, only the Driver configuration is important, but it is possible to configure the MCP and CGP apps if necessary. The MCP config file can be used to automate the process of adding/deleteing SMML code to/from the SMML file each time it is generated ( e.g. ignoring some variables or adding user-defined functions ).
In the default configuration, the following configuration files are read/written by these applications:
<ModleName>.MML.config read (if exists) and written by MCP
<ModleName>.<scenario>.config read (if exists) and written by CGP
<ModleName>.<scenario>.config~ initial config file backup generated by CGP
<ModleName>.<scenario>.config read by Driver
If MCP or CGP fail to find a config file then they generate and write a default version. The MCP, CGP and Driver apps are usually never executed directly, but are invoked by the SME script (or java interface tool) with appropriate arguments. Developers may determine the command-line arguments to these apps by executing them with the -help argument ( e.g. executing ‘MCP -help’ gives a list of the MCP command-line arguments).
All configuration files follow the same format. The reader may want to examine a sample configuration file, such as <ProjName>/Config/<ModelName>.def.config from one of the sample projects included in the distribution. Default versions of all the configuration files are generated by the SME applications.
A configuration file is structured as a set of records, usually with a single record on each line. Each record begins with a special character, called the "class character", belonging to the set { #, $, *, ~ }, and continues until the next class character is encountered. The class character denotes the class of object that is being configured. Each object class accepts it's own unique set of configuration commands (config-cmds). Table 1 lists the current set of class characters with the corresponding object class and config-cmd sets. The various config-cmd sets are described in detail in section 7.
After the class character, the next field in a record is the object name. There is always a single model object called "global". Other object classes (Module, Variable, and External) may have many objects as defined in the SMML (or View) equation files. The class characters and object names are generated by CG and should not be edited by the user.
|
Class Character(s) |
Object Class |
Config-cmd Sets |
|
* |
Variable |
Variable Cmds. |
|
$ |
Module |
Module Cmds. |
|
# |
Model |
Model Cmds |
|
~ |
External |
External Cmds |
Table 1: Configuration classes.
Following the object name in each record is an optional space-delimited list of config-cmds. Some config-cmds will be generated by default by CG. The user can edit the default config-cmds and/or enter new config-cmds. The config-cmds are in the form x(ArgList), where x is the config-cmd name (a character or character string, but usually one or two characters), and ArgList is a list of configuration parameters, i.e., arguments, which are separated by commas when more than one argument is used. Spaces between arguments are ignored. The number and type of arguments depend on the config-cmd being entered. Arguments may be either text strings (e.g., a variable name), integers, or floating point numbers. Arguments may either be required or optional. The ordering of config-cmds is usually irrelevant (the OS() config-cmd is one exception), but the arguments of ArgList must be presented in the order given in the documentation below.
Commands may be commented out by placing a ‘|’ character inthe command list: this character causes all commands following it to be ignored until the end of the line is reached.
For example, a typical record in a configuration file might look like:
* elevation_MSL_map d(G,Elevation_map,1.0,0.0)
In this record, the class character '*' indicates that a variable object is being configured. The name of the variable object is 'elevation_MSL_map'. One cmd is used to configure this variable. The d(G,...) config-cmd from the variable c-cmd set configures map input such that the map Elevation_map is read from Grass ( ‘G’ argument ) and used to initialize elevation_MSL_map. Following arguments set the elevation_MSL_map scaling parameters to (1.0,0.0).
For another example, a typical record in a module configuration file might look like:
$ VEGETATION_SECTOR g(G,StudyArea)
In this record, the class character '$' indicates that a module object is being configured. The name of the module object is 'VEGETATION_SECTOR'. The g() config-cmd from the module config-cmd set then configures the module such that is will be linked with a 2D grid frame, initialized with the map StudyArea (read from Grass).
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.
When the Driver application is executed, after a brief setup period it returns control to the user with a ‘SME>‘ prompt. The user may input the following simulation commands (sim-cmds) at the SME prompt to control and configure various aspects of the simulation.
These sim-cmds are used to start, stop, step, break, and exit the simulation.
s {e,c}
DESCRIPTION:
This sim-cmd steps the simulation forward by one exe-cmd or one event. Each event is composed of a sorted list of exe-cmds that are executed at the same (simulation) time (see section 4.3). Each exe-cmd updates the data structures of one variable.
ARGUMENT1 (optional char):
e :Step one event (default).
c :Step one exe-cmd.
r {endTime}
DESCRIPTION:
This sim-cmd is used to run the simulation until endTime is reached in simulation time. The endTime parameter is measured in simulation time units (i.e. same units as the argument x to the dt(x) config-cmd).
ARGUMENT1 ( optional float ):
endTime :Run Simulation until endTime is reached.
b {c,a,i,u,p,C,D} {0,1}
DESCRIPTION:
This sim-cmd is used to set break points in the simulation execution. The simulation retruns control to the user ( ‘SME>‘ prompt ) jut prior to executing a exe-cmd with a break point attached.
ARGUMENT1 ( optional char ):
c :Set a break point on the current exe-cmd.
a :Set breaks on all exe-cmds associated with the current variable.
i :Set break on init exe-cmds associated with current variable.
u :Set break on update exe-cmds associated with current variable.
p :Set break on pipe exe-cmds associated with current variable.
C :Clear breaks associated with current variable.
D :Clear breaks associated with current exe-cmd.
ARGUMENT2 ( optional bool (0,1): default = 1 ):
1 :Set break point(s) on the selected exe-cmd(s).
0 :Remove break point(s) on the selected exe-cmd(s).
S
DESCRIPTION:
This sim-cmd is used reset the simulation to it’s inital state. At this point, issuing a r sim-cmd will restart the simulation from the beginning.
X
DESCRIPTION:
This sim-cmd is used exit the simulation.
The following sim-cmds are used to choose the current Module, Variable, Event, or exe-cmd. These sim-cmds set the context for other sim-cmds.
m {<moduleName>}
DESCRIPTION:
This sim-cmd sets the current module to the module listed in the first argument.
ARGUMENT1 ( optional string, default = NULL ):
<moduleName>} :Name of a module in the simulation.
v {<moduleName>} {<variableName>}
DESCRIPTION:
This sim-cmd sets the current variable to the variable listed in the first two arguments.
ARGUMENT1 ( optional string, default = NULL ):
<moduleName> :Name of a module in the simulation.
ARGUMENT2 ( optional string, default = NULL ):
<variableName> :Name of a variable in module <moduleName>.
l {m,v,c,d}
DESCRIPTION:
This sim-cmd is used to generated a numbered list of module, variable, exe-cmd, or dependency objects. Items can be choosen from this list using the ‘Choose’ (c) sim-cmd. An item that is choosen becomes current.
ARGUMENT1 ( optional char, default = previous value ):
m :List the modules in the simulation.
v :List the variables in the current module.
c :List the exe-cmds associated with the current variable.
d :List the variable dependencies associated with the current exe-cmd.
c [index]
DESCRIPTION:
This sim-cmd is used to choose a module, variable, command, or dependency object from the most recently generated list ( ‘List Objects’ sim-cmd ). An item that is choosen becomes current.
ARGUMENT1 ( required int ):
index: Index of item in list to be choosen.
The following sim-cmds are used to retrieve data from the the current Model, Module, Variable, Event, or exe-cmd object.
q {s,t,m,i,c}
DESCRIPTION:
This sim-cmd is used to query the current variable for information classified as space, time, mode, initmode, and class (according to the first argument). With no arguments the name of the current variable is returned.
ARGUMENT1 ( optional float ):
s :Return Spatial mode.
t :Return temporal mode.
m :Return special mode.
i :Return init mode.
c: :Return class.
d {startIndex} {endIndex}
DESCRIPTION:
This sim-cmd is used to dump an array of floating-point data from the current variable. The array ordering follows the internal ordering of data for the variable. If a spatial grid is needed, use the dg sim-cmd.
ARGUMENT1 ( optional int, default=0 ):
Index of first data element.
ARGUMENT2 (optional int, default=100):
Index of final data element.
dg { rowIndex, colIndex }
DESCRIPTION:
This sim-cmd is used to dump a 25x25 array of floating-point data from the current variable. The array is spatially ordered, the first argument gives that coordinate of the upper-left corner of the array on the Frame’s grid.
ARGUMENT1 ( optional coordinates, default=(0,0) ):
Frame coordinates of the upper-left corner of the array (row,col).
dp [ rowIndex, colIndex ]
DESCRIPTION:
This sim-cmd is used to dump a floating-point value from the current variable at a specified point. The first argument gives the coordinate of the point on the Frame’s grid.
ARGUMENT1 ( required coordinates ):
Frame coordinates of the point to be printed(row,col).
dc
DESCRIPTION:
This sim-cmd is used to display the code executed by the current exe-cmd.
dv
DESCRIPTION:
This sim-cmd is used to display the the variable’s data in a viewer. (Note this command is only available if the SME is built with Java enabled). If the variable is spatial then the variable’s spatial data at the current timestep will be sent to a map viewer, if the variable is non-spatial then the variable’s timeseries data will be sent to a graph viewer.
V
DESCRIPTION:
This sim-cmd is used display data about the current variable.
The following sim-cmds are used configure various aspects of the simulation. They are used primarily by the SME java interface, but are listed here for completeness.
C [a,m,v,<externalName>] [config-cmd]
DESCRIPTION:
This command is used to pass config-cmds to one of the current objects in the simulation. The first argument determines the class of object to receive the config-cmd, and the second argument is any config-cmd that can be accepted by that class of objects (see section 7 for details).
ARGUMENT1 ( required string or char ):
a :Pass the config-cmd to the model object.
m :Pass the config-cmd to the current module object.
v :Pass the config-cmd to the current Variable object.
<externalName> : Pass the config-cmd to the external object named.
ARGUMENT2 ( required string ):
config-cmd : config-cmd as listed in section 7.
N [<hostName>] {<timeOut>} {<buffSize>} {<dataSize>} {<sync>}
DESCRIPTION:
This sim-cmd is used to pass network information to the Driver that is used when the socket connection is established between the interface and the Driver. This sim-cmd is used primarily by the SME interfaces.
k {pipeCmd}
DESCRIPTION:
This sim-cmd is used to delete a pipe command associated with the current variable. With no arguments all pipes associated with the current variable are deleted. The sim-cmd is used primarily by the SME interfaces.
ARGUMENT1 ( optional string ):
pipeCmd :Pipe command to be deleted (see SECTION 7).
The current version allows simulation output to be archived in a number of formats, including HDF (SDS & Raster), Grass, MapII, and ArcInfo exchange formats. See sections 6 and 7 for details on how to configure the various types of simulation input and output. Real-time visualization of simulation variables is also available using the SME Java interface (section 12). Debugging output is written to the Driver Log File:
<ProjectName>/DriverOutput/Driver.Log.x
where x is a processor number. The d() configuration command is used to configure the level of debug information that is printed.
Obtaining and preprocessing the data necessary to execute a spatial simulation can be the most time consuming part of spatial modeling. There are two general methods for importing data into the SME: 1) Import the date into the SME database and then configure the Driver to read from the DataBase, or 2) Configure the Driver to read the data directly from disk. Whichever method is used, the user must initially convert his/her data into a format that is readable by the SME.
There are a number of different types of data that can be imported into the SME, which are discussed in the following sections.
A map is a generally a two-dimensional array of N-byte unsigned values, where N can range from 1 to 4, although some import methods allow arrays of floats. The N-byte binary data is converted to floating point values when read into the SME, see the documentation on the S() config-cmd (section 7.1.2) for an explanation of the scaling algorithm. Maps can be imported into the SME in a number of different formats.
The Macintosh-based GIS application MapII can be used to generate maps for import to the SME. Use the ‘M’ mapSource option in the d() or c() config-cmd (section 7.1.3-4) to configure map input in MapII format SMESpatial data may be input from other databases and GIS programs to MapII, and other GIS programs (such as GRASS) can be used to generate maps in MapII format. The MapII project documents must be exported as MapII binary interchange format files (referred to here as "MapII format"). MapII format consists of a simple header file, and a binary file for each MapII file. The user may check ou the examples in one of the DEMO projects if MapII is not available.
Maps may be imported directly from GRASS if the SME is running inside of the GRASS environment. Use the ‘G’ mapSource option in the d() or c() config-cmd (section 7.1.3-4) to configure map input from GRASS. Be sure to set the current region for the GRASS environment using the command "g.region" before the simulation is started. All maps read into the SME should exist in the current mapSet selected within GRASS. The user should also configure the Frame-definition maps (in Modules receiving GRASS maps) to be read from GRASS (sections 7.3.1-2) to make sure that there is no conflict between the GRASS current region and the SME Frames.
Maps can be imported in HDF format. Both RIS and SDS format are supported. Use the ‘H’ mapSource option in the d() or c() config-cmd (section 7.1.3-4) to configure map input in HDF RIS format.
Maps can be imported in ArcInfo exchange format. Use the ‘A’ mapSource option in the d() or c() config-cmd (section 7.1.3-4) to configure map input in ArcInfo format.
A common form for data is the timeseries. Two timeseries input data formats (denoted ‘format 1’ and ‘format 2’) are currently supported by the SME. Data may be exported in these formats from spreadsheets or other database programs. Examples of these formats are included in the demo project Data/Examples directory. The Example1.ts file is format 1, Example2.ts file is format. 2. To get data into these formats the user may: 1) copy the example file and edit the values, 2) configure a spreadsheet program worksheet in this format and export the file, or 3) write and/or use a program to format timeseries data.
Format 1 is specifically for a one-year tabulation of daily data, where row headings are days of the month and column headings are months. There are more than 10 data fields for header information. The data above and below the separating ---------- lines is ignored. The data between the lines may be tab or space(s) delimited.
Format 2 is the simpler one consisting of a single column of data with a header to define timestep and number of data points. In format 2 the user may set the time step of the data.
The SMP Extrapolated TimeSeries Variable is able to generated an extrapolated spatial grid (map) at each timestep from a set of spatially referenced timeseries data files. The extrapolation routine generates a map at each timestep of the simulation by interpolation of a slice of the time series data at the current time.
To define which timeseries files are to be included in the extrapolation, the user creates a Spatial Extrapolation Point Timeseries (PTS) file that must be identified with the suffix ".pts". The data included in this PTS file must follow the form of the PTS file included in the demo project Data/Examples directory. The header defines the data directory:
Data Directory = <ProjDir>/Data
followed by a column of timeseries filenames preceded by the row (c0), and column (c1) coordinates for each point:
c0 c1 <Timeseries filename>.
To configure the SME to import this data, use the Spatially Extrapolated Timeseries config-cmd (section 7.1.7). At the beginning of the simulation the SME will read a set of timeseries named <Timeseries filename><index>.ts (where <index> is an file index starting at 0, see section 7.5.1) from the directory <Data Directory>. The variable's value (IDS) will be generated at each step of the simulation by extrapolation between the spatially referenced timeseries.
Class-Dependent parameter data is used to initialize Class-Dependent Variables (section 4.1.3). The SME can be configured to import this Data using the Dbase Input config-cmd (section 7.1.6).
This feature is not yet fully documented. Please refer to the example code in the UserCode directory of one of the demo projects, such as PLM.
This programming interface is used to created customized database readers for importing parameters into the SME from SQL databases. The current implementation of the SME is set up to interoperate with the Postgres database, other databases will probably require some reconfiguration.
A new database reader is created by defining a DBaseFunction object in the SQLFunctions.SMML file in the project’s UserCode directory. This object is invoked by the m4 config-cmd described in Section 7.1.6. As an example we will look at the default reader sme_default which is pre-definedin SQLFunctions.SMML:
DBaseFunction sme_default {
Arg tableName = NULL;
Arg sectorName = NULL;
Arg parmName = NULL;
Code = !{
SELECT HabIndex, ParmValue FROM tableName WHERE
SectorName = 'sectorName' and ParmName = 'parmName';
}!;
}
This block of SMML code defines a DBaseFunction object called sme_default which has three arguments: tableName, sectorName, parmName. The Code attribute declaration declares the SQL code that is used to implement the reader. When this funcion is invoked by the m4 config-cmd, the arguments supplied in the config-cmd are substituted for the declared arguments in the SQL code block, which is then used to define the reader. Substitutions are case-sensitive, and arguments are matched by order of declaration. For example, an m4 command which looks like:
m4(CME_Maxwell,HAB,sme_default,PLM_HDP,Forest,Canopy_Height)
will result in an SQL reader the executes the code:
SELECT HabIndex, ParmValue FROM PLM_HDP WHERE
SectorName = 'Forest' and ParmName = 'Canopy_Height';
to read a set of parameters form the table PLM_HDP in the database CME_Maxwell. The reader should return a set of tuples with two fields, the first giving the map index value (in this case, HabIndex for the map HAB) and the second giving the parameter value (in this case, ParmValue) for that index. This example assumes that a table called PLM_HDP exists in the dataBase CME_Maxwell and has the columns HabIndex, ParmValue, SectorName, and ParmValue. This table may be created using the SME datbase interface, see section 5.1.5 for a brief introduction.
If the SME is configured and installed with java enabled ( requires JDK 1.2 ), then the user has the option of running the SME with a java interface attached. The java interface can be used in two modalities, offering different levels of functionality: the full interface, and the standalone ViewServer.
The standalone ViewServer allows the user to display simulation output using a set of java viewers, but control and execution of the simulation is handled through the SME command-line interface. The ViewServer is started using the startup_viewserver script. The ViewServer can remain up for many simulation runs. If the ViewServer is started on a host that is different from the host on which the simulation is running, then the simulation must be run with the command "SME -VShost <hostName> run <modelName>". If the ViewServer default port is busy, then the ViewServer will use an alternate port. In this case, the user may have to run with the SME arguments "-VSport <port_number>".
The user can specify that the data of any Variable in the simulation be piped to the ViewServer at each timestep using the "DD()" config-cmd ( see section 7.1.8 ). Also, at any time in the simulation the "dv" sim-cmd can be used from the SME> prompt to display the data of the current Variable ( chosen using the "l" and "c" sim-cmds ). The ViewServer provides a palette of viewers for visualizing any simulation data that is piped to it.
The full java interface allows the user to configure, execute, control, and visualize a simulation through the interface. The ViewServer described above runs as one component of the full interface. To start up the SME using the full interface, with the interface and the simulation running on the same host, execute "SME -java local run SME". To run the simulation and interface on different hosts, start up the SME with the command "SME -java <interface_host_name> run <modelname>". The SME will then start up and pause while listening for connections, giving the port number that it is using. Next, start up the interface on the interface host using the command "startup_client -p <SME_port> -h <SME_host> xxx". The interface will then start up and connect to the SME driver.
The first panel that comes up in the interface is the Configuration panel, which displays the configuration information read from the SME configuration files and allows the user to reconfigure the model. When the user is ready to run the model they should choose the Control Panel, where they can set up and execute simulation runs, pipe data to the ViewServer, browse through the Variable dependency tree, view the equation for any Variable, and bring up a snapshot of the simulation data for any Variable in the model. The Messages panel is the screen output of the running SME Driver, arranged in pages, and the View panel is the ViewServer described above.
The use of STELLA arrays in the SME is limited to map-dependent parameters, i.e. parameters, such as porosity, which depend on a spatially-varying index, such as soil_type. Thus the array must be a parameter ( i.e. take on a constant value for each value of the index ), and the array index must be an class (integer-valued) map ( i.e. configured with "c" config-cmd ).
The SME extracts the array data from the Stella model and writes it to a DBaseParameters.out file, which is read by the Driver at run-time and used to set up the map-dependent parameters. Any commands in the SME configuration files associated with Variables listed in the DBaseParameters.out file will override the information in that file. Thus, if a Varaible is declared as an array in STELLA but is declared as a parameter ( "pm" config-cmd ) in the SME config data, the Variable will be set up as a parameter in the Driver.
1 Special characters are any other than numbers ( 0 - 9 ) or letters ( a - z ). Compatiablity problems may result with the C code.