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).