Other visualization tools : Event sounds helper

The motivation behind Simile's visualization tools is to provide the modeller with a continuous, immediate understanding of what the model is doing. Sometimes the best way to do this is with sounds rather than graphics. With the addition of discrete events to the modelling language, we realized that their instantaneous nature does not lend itself to the kind of graphical displays that work for continuous values. 

So we created an event logger that also produces a sound each time a selected event occurs. Add an instance of this tool in the standard way, selecting 'Event sounds' from the list of helper titles. Now after clicking '+' in the helper window's toolbar, you can select a discrete event component in your model, and a sound file to play each time the event occurs. The window will show a 'ticker bar' which will move across the screen right to left, with a vertical line added each time the event occurs. Hovering over the lines will pop up the exact time and magnitude of the occurrence they represent.

Also, the sound will be played each time the event occurs. If your event has a numeric magnitude, then the volume of the sound will be determined by where each event's magnitude falls between the min and max values given for the event. Sound files in WAV format will play on all platforms -- files in other formats (e.g., mp3) may play on your particular platform but are not guaranteed to play on all.

If the chosen event occurs very frequently, or if it is in a simple model that runs very fast, the sounds may overrun each other producing unpleasant noise. In this case you can use the 'limit updates/sec' feature to slow the model execution down to the point where the sounds can be heard separately.

Polygon diagram

This tool enables a dataset to be displayed as the colours of polygonal areas on a map. It can be used either where vector data for an actual map is available (either in the model, or in a separate file), or where an area is represented as some regular set of shapes whose vertices can be calculated by the model, e.g. hexagonal tiling.

A lot of the functionality of the polygon helper, including scrolling and zooming, working with the colour legend, and using it to edit model parameter values, is exactly the same as for the grid helper. However, the graphics of the polygon helper are not quite as fast, so you are more likely to need the 'freeze display' and 'manual update' features.

Loading co-ordinates from file

If you choose this option you will get a file selector to locate the data for the coordinates. If you choose a file with the extension .dxf, Simile will attempt to load it as a DXF file, and will then colour the polygons in the order in which they are defined in the file. Otherwise, Simile currently expects the file to contain all the X coordinates in nested list form, followed by all the Y coordinates. This is not particularly convenient, so we should add the option to set the coordinates from file using the table data dialogue too.

Loading co-ordinates from model

Of course you can put fixed parameters in the model and load them using the table data dialogue, then use them to set the boundaries of the polygons. If you choose this option, you will be asked to select model elements representing the X and Y coordinates of the polygon vertices. These elements should have two-dimensional data arrays, with the outer index being the number of the polygon whose border they define, and the inner index being the number of the vertex around that polygon. There should be the same number and arrangement of X and Y coordinates.

The usual way to get the coordinates is to have a submodel for the vertices inside the submodel representing the polygons. This should be a per-record submodel if different polygons have different numbers of vertices. Put fixed parameters for Xs and Ys inside the vertices submodel. 

In: Contents >> Running models >> Working with helpers

Standard helpers : edit sketch graph function

If your model contains equations that use the graph function, their function can be altered while the model is running. The tool for doing this appears as a helper, although it does not display values from the model or directly set them.

The helper is located in the "Standard tools" subdirectory menu and is called "Edit sketch graph function". Create an instance of the helper and click on the model component whose function you wish to alter. You will then see the same sketch graph editing window as when you originally created the sketch graph. You are able to drag the sketch line as well as edit the axis values and change the settings that control how the sketch is interpreted.

Any changes you make to the sketch graph function will take effect as soon as you hit the 'OK' button, but the helper will stay up until you delete it, allowing further changes to be made at any point. Note that the edited function will not be saved with the model. If you save the model after editing the sketch using the helper, it will keep the original version of the function. To change this you must go back to the equation dialogue and hit the "Graph" button.

The Data Logger tool does not display model data, but records it in files for later analysis with statistical tools. There are other ways of doing this:

• The Table Helper can save its contents as a .csv file, but has poor performance with large data sets
• The Snapshot tool can record values as the model runs, but only handles one variable, and needs setting up every time the model is run

By contrast, the Data Logger can handle any size of data set that is usable within Simile, and can log multiple variables, either in separate files or as columns in a single file. Since it is a standard helper, many instances can be added for different groups of values, and the setup can be saved as part of a general helper layout.

Using the tool

The tool's canvas will be blank when it is first added. To log a variable, hit the + button and click the variable on the model diagram. It will be listed within its hierarchy of submodels, with a '-' button ffor its removal. Hit + again to add more variables. The rightmost button in the helper's toolbar switches between saving separate files for each variable (named by the variable's caption) and a single file (log.csv) with each variable in its own column.

Saved file format

The helper will not save any data until you select a folder in which to save it. Click the toolbar button with the folder icon and navigate to the desired location. Now a line is written to the log file(s) at each display point as the model executes. The files are in .csv format with the time points stored in the left hand column. If the values being saved are arrays, they will be written as series of alternating indices and values, with each series enclosed in curly brackets, i.e., the same format as data popups or directly-entered file parameters.

The file is closed when the model is paused, and opened for appending more data when it is restarted. When the model is first run after a reset or rebuild, the file will be opened for writing, so the previous contents will be overwritten unless they have been moved.

As of Simile v6.9, it is also possible to log model data to a database -- either a file in some Excel-compatible format (.xls, .xlsx etc) or a MySQL database. To log to a database file, simply select it from the file dialogue. To log to a MySQL database, cancel the file dialogue and this will cause the database specification dialogue to appear. Here you enter the hostname, username, password and name of the MySQL database.

When logging to a database, each component being logged will have values put in its own column in the database. If logging an array component, there will be a separate column for each element in the array, named value/n where value is the name of the component and n is the index of the element. (value/n1/n2/... for multi-dimensional arrays). The values will be written to a table called 'Run 0' until the model is reset, after which new tables called 'Run 1', 'Run 2' etc will be created for data values from subsequent runs.