Overview of the scenario file mechanism

A simulation model may require various types of input data. These can include:

• values for parameters
• values for site conditions: e.g. soil type
• values for time-varying inputs (exogenous variables, such as temperature)
• initial values for compartments (state variables)
• values for management decisions: e.g. harvesting rate

For each of these, there may be a need to enter a set of values. For example, a compartment of a site-condition variable may be in a multiple-instance submodel and so (if you do not want all instances to have the same value), you will need to provide a different value for each instance.

Simile provides a variety of mechanisms for providing these values:

Entered into the Equation field of the equation dialogue

This is the standard way of doing things, and is the method illustrated in Simile introductory tutorials.

Generated by sampling from some random distribution

For example, you might use the rand_var function, with arguments of 10 and 20, to get randomly-generated temperature values in the range of 10 to 20 degrees. (It is a moot point as to whether you consider that this technique comes under the heading of providing input data: whatever your view, it certainly does the same job as if the data had been provided from a data file.)

Entered into the sketch graph function in an equation

This could be used, for example, to provide a set of observed temperature records over time:
 

graph(time())
 

or different values for some parameter for different instances of a multiple-instance submodel:

graph(index(1)).

See the help information on the graph function for more details.

Entered into the table function in an equation

This enables you to pick up tabulated values from a .csv data file. It has close similarities to the mechanism described in this section, but it differs in one important respect. When you use the table function to load tabulated data values from a file, and then subsequently save the model, the values are saved along with the model. This is fine for small data sets, but can greatly increase the size of models using large amounts of data. In contrast, the File Parameter mechanism does not save loaded data with the model. See the help information on the table function for more details.

Set using a slider

If you declare a variable to be an "Input parameter" in the equation dialogue, then Simile automatically generates a window containing a slider for each variable so declared (or a set of sliders if the variable has multiple instances). You can then move the slider to set the value of the variable - and indeed to change it during the course of a simulation run.

None of these mechanisms satisfies a common modelling requirement: that a set of data values be provided for the model when the model is run. We need to be able to store the set of values in one or more files, and specify which set is to be used for a particular run. This is where the File Parameter mechanism comes in.

Design of the Simile File Parameter mechanism

The File Parameter mechanism was designed to meet the following design goals:

• A model can be complete even though it is lacking data values needed to simulate its behaviour. By complete, I mean that Simile can proceed to build the model: i.e. generate the Tcl or C++ program. Simulating the behaviour of the model requires that the built model is associated with one or more files ("scenario files") at run time. The job of these files is to tell Simile how to obtain values for variables in the model that have not had a value provided.

• One model can be associated with several scenario files for a single run, each file providing values for a different subset of variables.

• Different runs of the model can be associated with a different set of scenario files (thus allowing the modeller to quickly change data inputs for a model).

• The scenario file may either contain actual data values (e.g. for a single-valued parameter), or may contain a reference to a comma-separated value (CSV) file containing tabulated data. This means that a single (potentially very large) CSV file can be referenced by several scenario files, thus avoiding the need to duplicate the same large volumes of data in a number of scenario files.

In: Contents >> Working with external data