The model: a simple bank account

Next Step >>

We will make a model for a simple bank account, with interest paid annually at a rate of 10%, and $10 taken out every year. The account initially contains $300. This is what we expect to happen:

Year 1

Year 2

Year 3

And so on. Note that the increments are getting bigger each year because each time the balance goes up, so the interest paid increases. The balance of the bank account is increasing at a faster and faster rate.

Having understood the calculations that we are going to perform, we now turn to the concepts needed to express these ideas in Simile.

We use a compartment to represent the amount of money held in the bank account, since this a quantity that changes incrementally over time. We use two flows, one to represent the gain of money from interest and the other to represent the loss of money by withdrawal. One flow (interest) will go into the compartment, while the other flow (withdrawal) will come out of the compartment. We will also use a variable to represent the interest rate (10%, or 0.1). This variable will be linked to the flow representing the payment of interest by an influence arrow, indicating that the amount of interest paid depends on the interest rate. Since the amount of interest paid also depends on the amount in the bank account, there we will also use an influence arrow from the compartment representing the bank account to this flow.

In this tutorial we want to introduce you mainly to the mechanics of working with Simile, and these are explained in detail in the following steps. The concepts involved in representing even a simple system like this one in a modelling language can be quite complex.

Next Step >>

Step 1: Starting Simile: what's on the screen

<< Previous Step Next Step >>

Starting Simile

You start Simile by double-clicking on the desktop icon created during installation, or by clicking on the Simile icon in the Start Menu.

These are both shortcuts to the file <Simile Program Files>\System\bin\Simile.exe, where <Simile Program Files> is the directory you chose to install the program. By default, this is commonly "C:\Program Files\Simile50", though if you are using a network, it may be on a remote hard drive. If you would like to be able to start Simile from a different location, create a shortcut to this file.

Linux users can start Simile by typing the command 'simile' in a terminal. Also, a shortcut is added to the Science/Education submenu of the Applications menu, which can be dragged to the desktop or taskbar, depending on your desktop environment.

On a Mac, Simile will be added to the Applications folder, from which it can be dragged to the desktop or task bar.

Within a few seconds, the main window will be displayed.

The Main Window

When Simile starts, you see a single window. This contains:
 

• a menu bar (at the top of the screen on a Mac), containing a standard File menu, some menus specific to Simile, and a Help menu. Hold the mouse over the title for each menu to see the options it contains.
   
• a toolbar, extending over two rows. The top row has standard tools (e.g. for opening and closing files), plus some specific to Simile.

• a component bar, containing buttons corresponding to each type of model-diagram element: you will use these for building up your model diagram. The right-hand part contains buttons for editing the model diagram. Hold the mouse over each button to get a brief description of its function.

• an equation bar, for entering equations into the model. At the right-hand end of the equation bar are the tools to accept or reject changes to equations, and to help build equations.
   
• a big blank area (the "desktop canvas") with faint lines. This is where you will draw your model diagram. The grid can help you arrange your diagram neatly.

<< Previous Step Next Step >>

Step 2: Making the model diagram

<< Previous Step Next Step >>

We begin by drawing the model diagram for the bank account model. A note on colours used in the following description: when you add a component to the model diagram, it is initially drawn in blue. This means that the component is selected. You will see the ways in which this is useful later on. When the component is not selected, it will turn red. This is its usual colour, and means that the component needs some extra information (like a value or equation) before the model can be built.

1. Add a compartment to the model diagram.

• Click on the compartment symbol in the toolbar.
• Move the mouse to the middle of the desktop window, and click again.

You should see a box labelled comp1.

2. Rename the compartment "account".

3. Add an interest flow and a withdrawal flow.

• Click on the flow symbol in the toolbar.
• Move the mouse into some space to the left of the compartment labelled account, hold the mouse button down, and drag the mouse into the centre of the compartment. Release the mouse button.
• Type in the label interest.
• Move the mouse into the centre of the compartment, and drag to the blank area to its right. Release the mouse button.
• Type in the label withdrawal.

As an alternative to dragging out the flow, you can just click on its start and finish positions.

4. Add a variable for the interest rate

• Click on the variable symbol in the toolbar.
• Move the mouse to the blank area above the interest flow, and click once.
• Type in the label interest rate.

7. Draw the influences

• Click on the influence arrow button in the toolbar.
• Move the mouse to the middle of the compartment labelled account, and drag an influence arrow to the flow labelled interest.
• Release the mouse button when the flow has turned green.
• Move the mouse to the middle of the variable labelled interest rate, and again drag an influence arrow to the flow labelled interest.

8. Re-arrange the model diagram

• Click on the pointer button in the toolbar.
• Move the mouse to the middle of the compartment labelled account.
• Drag the mouse, and watch the compartment and its associated arrows re-arrange themselves.
• You can also move the following components:
• the cloud symbol at the end of each flow arrow;
• the variable;
• the valve symbols on the flows;
• the middle of an influence arrow;
• the position of the "kink" that appears in a flow arrow when it goes between two components that are not exactly above, below or to the left or right of one another; and
• the labels. (A note on moving captions: if a component is selected, and is coloured blue, then the caption can be edited. To edit a caption, click on the label and type. You can drag the mouse to select a range of characters. To move the label relative to its component, make sure the component is not selected. You can then drag the label into its new position.)

This completes the drawing of the model diagram. In the next step, you will provide the numeric values and equations you need for simulating the behaviour of the bank account. Note, however, that this sequence (complete the model diagram before providing any quantitative information) is followed here for convenience: in general, you are free to provide the quantitative information at any stage in the diagramming process.

<< Previous Step Next Step >>

Step 3: Adding initial values, parameter values and equations

<< Previous Step Next Step >>

1. Prepare to set component properties

Click on the pointer button in the toolbar.

2. Assign the initial value for the compartment

• Click on the compartment labelled account.
• Enter the value 300 into the equation bar.
• Click on the green tick mark or press the Return key.

3. Add the interest rate equation

• Click on the flow labelled interest.
• Variables account and interest_rate are now listed as influences upon interest. These influences are visible by clicking on the x_s button. Selecting an influence from the drop-down list, places the text in the equation bar.­

• Enter the expression account*interest_rate into the equation bar, either by selecting each variable in turn or by typing. Be sure to use an underscore rather than a space in interest_rate.
• Click on the green tick mark.

4. Assign the value for the withdrawal flow

• Click on the withdrawal flow.
• Enter the value 10 in the equation bar.
• Click on the green tick mark.

5. Assign the value for interest rate

• Click on the variable labelled interest rate.
• Enter the value 0.1 in the equation bar.
• Click on the green tick mark.

Notice that every component of the model diagram is now black, rather than red as it was before. This indicates that every component has been mathematically specified, and so the model is ready for running: Simile has enough information to work out the flows, and thus to update the amount of money in your bank account forward through time.

<< Previous Step Next Step >>

Adding node-type elements

The node-type elements are:

• the variable
• the compartment
• the event
• the ​​​​ state

as well as the elements used in population submodels. The T text box and  image element also behave as node-type elements, though no node is associated with them. The following procedure is used to add node-type elements.

1. Click on the required node symbol in the tool bar.
2. Click on the diagram canvas where you want to place the element.
3. At this point the caption is selected and you can type in your chosen caption (except for images).
4. Repeat (2) if you want to add more nodes of the same type.

Note that the button you selected on the tool bar remains depressed until you select another button (i.e. to add a different element, or to change into a different mode, such as label or move). This allows you to add quickly several elements of the same type.

There are other methods if you want to add just one element without leaving pointer mode. Any of the following will add a single element to the diagram:

• Drag from the tool bar symbol to the chosen place on the diagram.
• Right-click at the chosen place on the diagram, and in the context menu select "Create New" -> your chosen node type. The population submodel membership controls are listed in their own submenu.

However you add a node, it appears with a default caption, e.g., "comp33". Since this caption is rarely what it needs to be in the finished model, it is selected for editing when the node is added, so you can immediately type in a more appropriate one, e.g., "Bananas".

Note that it is not possible to add a node-type element to an area of your diagram that is already occupied. A warning message appears, so if this happens, simply click somewhere else where there is sufficient space, or move existing elements around to make sufficient space. You can also adjust the relative size of components in a submodel to make more room around them.

In: Contents >> Working with model diagrams

Adding arrow-type elements

The arrow-type elements are the influence, flow,  squirt and role arrows. In general, arrows link two nodes, though there are exceptions, as explained below. There are two methods of adding arrow-type elements.

1. Click on the required arrow symbol in the tool bar.
2. Drag the mouse from the place where you want the arrow to start, to the place where you want it to end. If you drag outside the model window during this operation, it will be scrolled in that direction bringing more space into view.
3. Repeat (2) if you want to add more arrows of the same type.

Alternatively,

1. Click on the required arrow symbol in the tool bar.
2. Click on the place where you want the arrow to start. The cursor becomes a 'cross-hairs' indicating another click on the diagram is needed to finish adding the link.
3. Click on the place where you want the arrow to end. If you miss the exact point, you can keep the button down and drag to it. If you drag outside the model window during this operation, it will be scrolled in that direction bringing more space into view.
4. Repeat (2) and (3) if you want to add more arrows of the same type.

Note that the button you selected on the tool bar remains depressed until you select another button (i.e. to add a different element, or to change into a different mode, such as label or move). This allows you to add quickly several elements of the same type.

You can also add a single link using either of the methods you would use to add a single node without changing mode, i.e.,

• Drag from the link's toolbar symbol to the start point on the diagram, or
• Right click at the start point to get the context menu, and select "create new" followed by the link type.

Either of these actions sets the cursor to 'cross-hairs', requiring another click to set the end point of the new link.

Specific instructions for each type of arrow

Flow and  squirt arrow

A flow or squirt arrow must:

• begin in a blank area of the screen, and end in a compartment; or
• begin in a compartment, and end in a blank area of the screen; or
• begin in a compartment, and end in a compartment.

Note that if the flow or squirt arrow begins or ends in a blank area of the screen, Simile automatically adds the source/sink symbol (a cloud).

Note also that if you draw two flow arrows between the same two compartments in opposite directions, the arrows mainly lie on top of each other, but the valve (bow-tie or target) symbols are separated. You need to be careful that you know which valve symbol is associated with which arrow, when you come to add influence arrows or equations to the flows. You may like to use the move tool to drag the ends of the flows around one of the compartments to separate them from one another.

Influence arrow

An influence arrow must:

• begin in any model element (except a submodel or an influence arrow); and
• end in any model element (except a submodel or influence arrow).
   

There is an exception to this rule. If you have an influence arrow coming from an input variable inside a submodel to some element (E1); then it is legal to draw an influence arrow from some other element (E2) to this influence arrow. The effect of this is to eliminate the input variable and to cause the influence arrow to go directly from E2 to E1.

Note that if you should accidentally miss the target model element, then the influence arrow will go shooting off to the edge of the model diagram window or submodel boundary. If that happens, then simply click on the undo button in the toolbar, and try again. The reason for this behaviour is to allow you to add placeholders for influence arrows to be taken from submodels. Drag an influence arrow from the placeholder on the submodel boundary, to the desired element outside the submodel to complete the link.

Multiple influences coming from a variable in a submodel to variables outside it will share a common link as far as possible. So will multiple influences coming from a variable outside a submodel to variables inside it. This makes for a much neater diagram when there are lots of influences. However, this can cause odd behaviour when the influences point to variables on opposite sides of the submodel. You can usually fix this by selecting the move tool from the toolbar, and dragging the attachment point around the submodel boundary.

Role arrow

A role arrow must:

• begin in a submodel; and
• end in a submodel.

In: Contents >> Working with model diagrams

Adding submodels

The following procedure is used to add a submodel to the model diagram.

1. Click on the submodel symbol in the tool bar.
2. Drag the mouse from a blank area of the desktop canvas, corresponding to one corner of the submodel envelope, to the opposite corner of the area that you want to be enclosed in the submodel envelope. If you drag outside the model window during this operation, it will be scrolled in that direction bringing more space into view.
3. Repeat (2) if you want to add more submodels.

Alternatively,

1. Click on the submodel symbol in the tool bar.
2. Click on the place where you want to put one corner of the submodel envelope. The cursor becomes a 'cross-hairs' indicating another click on the diagram is needed to finish adding the link.
3. Click on the opposite corner of the area that you want to be enclosed in the submodel envelope. If you miss the exact point, you can keep the button down and drag to it. If you drag outside the model window during this operation, it will be scrolled in that direction bringing more space into view.
4. Repeat (2) and (3) if you want to add more submodels.

You can also add a single submodel using either of the methods you would use to add a single node without changing mode, i.e.,

• Drag from the submodel symbol to the first corner point on the diagram, or
• Right click at the corner point to get the context menu, and select "create new -> submodel".

Either of these actions sets the cursor to 'cross-hairs', requiring another click to position the diagonally opposite corner of the new submodel.

Note that the submodel you make may, or may not, enclose existing model elements. Simile will not allow you to add a submodel with the boundary passing through an existing component other than a link. When making a submodel, you can either make it to enclose some existing model elements, or it can begin life empty, with the intention of adding elements later on. The following notes apply to the two situations:

Submodel is drawn around existing model elements

The elements must be arranged so that it is possible to enclose them in a rectangle without enclosing any elements you don't want in the submodel. You may need to move them around prior to drawing the submodel envelope to achieve this. The elements are then deemed to be enclosed inside the submodel. Any links coming from outside this new submodel to elements inside it, or vice versa, will be redrawn to show a crossing point at the submodel boundary.

Submodel does not enclose existing elements

You need to find an empty area of your model diagram that is big enough to contain the new submodel. You may need to move existing model elements around in order to create some space.

In: Contents >> Working with model diagrams

Selecting model diagram elements

The selection mechanism is straight-forward. First select one or more elements on the model diagram, then perform an action on the selection.

To select a single element, click on it using the pointer. To continue to select further elements, hold down the Ctrl key (Cmd key on the Mac) whilst clicking on them. If you select an element by mistake, click on it again with the Ctrl key held down, and it will be unselected, leaving the rest of the selection unchanged. To abandon a selection altogether, click in a blank area of the diagram, outside any selected submodels. To select multiple elements at once, drag the pointer across the area containing them: a marquee (rectangular selection) will be drawn around the elements that are included in the area. If you drag outside the model window during this operation, it will be scrolled in that direction bringing more space into view. The elements will all be selected when the drag is released. If any part of an element (other than the caption) is included in the area, it will be included in the selection. If you drag a marquee around some elements while holding the Ctrl key down, any elements in the marquee that were not already selected will be added to the selection. You cannot unselect elements by ctrl-dragging.

The context menu contains the commands "Select all", "Unselect all" and "Invert selection". These apply within the submodel in which you right-click to display the menu, and any submodels nested within it.

Selected components and captions will be highlit in blue. Links between selected components are also highlit in blue, while links between selected and unselected components are green. These green links will stretch if the selection is moved, and will be deleted if it is cut, but will not be put on the clipboard.

Ghosts of selected components, and base components of selected ghosts, will be highlit in bright green. It is also possible to have components connected to the selection highlit like this. Under the "View" menu, select "Highlight back" -> "One level". Now all components starting influences going to the selection, including via ghosts, are highlit. There is also the option to highlight back two or three levels, and an equivalent choice for highlighting forwards, which shows up components influenced by the selection. Components that are highlit in this way are not affected by actions done on the selection.

Various actions can be performed on selected element(s). The actions are available in the context menu, invoked with a right click. Once one or more elements are selected, the action chosen from the context menu will be performed on the selection, wherever the mouse is when the right-button is clicked.

The selection can be cut or copied to the clipboard. If you paste the clipboard into another program, such as Microsoft Word, a picture (metafile) will be shown in the document. If you paste the clipboard into Simile, the elements will be inserted, complete with functions and other properties.

Duplicating elements

You can make multiple copies of one or more elements. This can be quick when some parts of your model are similar to one another. Follow these basic steps.

1. Click on the pointer tool on the tool bar.
2. Click to select the element you wish to copy. If you wish to copy more than one element, hold down the Ctrl key whilst selecting the elements.
3. Use the context menu (right-click) copy and paste commands.

The selected elements will be duplicated into an area where there is sufficient space to receive them. The elements will also receive new valid names to avoid clashing with the existing selection. The elements are selected ready to move to the desired position together.

Important! You should not need to duplicate groups of elements multiple times in Simile -- if you find yourself doing so, think about using a multi-instance submodel instead.

In: Contents >> Working with model diagrams

Moving model diagram elements around

You will inevitably want to change the layout of the elements in your model diagram. For the elements you have placed on the diagram yourself, such as compartments and variables, you will find that at some stage you need to move them around, to make the diagram neater, easier to understand, etc. For some elements, such as the route taken by arrows and the placement of labels, you will want to arrange them to suit yourself: perhaps an influence arrow goes behind a compartment, or two labels run together.

The basic steps are:

1. Select the pointer tool if not already selected.
2. Move the mouse to the element you wish to move.
3. Click to select the element.
4. Drag the element to the new position.

For node-type elements, the effect is pretty obvious. But note that:

• All arrows are sticky, so that moving any node-type element causes all the arrows associated with it to move around, according to the built-in arrow pathway algorithm.

• Nodes cannot be moved into space occupied by other nodes. However, if you keep on dragging past an obstruction, then the element you are moving will leap into position as soon as there is sufficient free space.

Special considerations apply to the following elements:

• Moving labels
• Moving flow valve symbols
• Moving influence arrows
• Moving role arrows
• Moving and re-sizing submodels
• Moving groups of elements

In: Contents >> Working with model diagrams

Changing the label for elements on a model diagram

To re-label any element in the model diagram:

1. Click on the select tool on the toolbar.
2. Select an element in the model diagram, or a group of elements whose labels you wish to change.
3. Click on the label of a selected element to change it, or drag across the label to select some text for cut/copy/delete.
4. Use the Backspace or the Delete key to remove the existing label.
5. Type in the label you wish for this model element. You can use any characters from the keyboard, including spaces, capital letters, the RETURN character and special characters, except for the period ( . ), the forward slash ( / ) and the reverse slash ( \ ).

If you try to change a label to one that already exists in the same submodel, or you use illegal characters in the label, or only use whitespace in the label so it cannot be seen, then Simile will generate an error message and leave the label unchanged. However any label is allowed for a T text element.

Suggestions

• Using the RETURN character is a good way of avoiding having long labels that stretch across the model diagram.

• You should choose labels that to some extent make the model diagram self-documenting: someone who is knowledgeable about the subject area of the model should be able to read the diagram and have a good idea of what most of the labels mean.

• However, remember that the labels are (by default) the names of the variables used in equations. Therefore, you should avoid labels that are too long and wordy. (You can however provide your own local names for variables inside equations, so you can use long labels if you prefer.)

• Remember also that the full label for an element in the model diagram is the label that you give it, along with the labels of any submodel(s) that it is enclosed within. (This is just like file names: the name of a file is the name given to it, along with the names of all the directories it is enclosed within.) Therefore, if you have a biomass compartment in each of two submodels - say "animal" and "plant" - then it is quite acceptable to label each of the two compartments with the same label, "biomass", since one is "plant/biomass" and the other is "animal/biomass".

• Choose names that reflect the type of element that you are re-labelling: see below.

Appropriate types of label for different types of model element

Compartments

The label should reflect the fact that this is (usually) referring to an amount of something. Thus, use terms like biomass, area or numbers.

Flows

The label should reflect the fact that the a flow is (usually) some process. Thus, use terms like production, growth, reproduction.

Simple submodels

The label should reflect the subsystem being modelled, for example, "vegetation".

Multiple-instance submodels (fixed-membership and population submodels)

The name should reflect one instance of the type represented by the submodel. Thus:

• if you are modelling a stand of trees, then the submodel should be called "tree";
• if you are modelling an area as multiple patches, then the submodel should be called "patch";
• if you are modelling multiple size classes, then the submodel should be called "size-class".

i.e. use the singular, not the plural. The reason for this is that the submodel represents a single individual: the fact that there is a set of them is indicated by the appropriate setting in the Properties box for the submodel: it is not an intrinsic property of the submodel itself.

Association submodels

The label should reflect the type of association that exists between the two types of object involved in the relation. Thus:

• if the association submodel represents ownership between people and patches of land, then label it "ownership";
• if the association submodel represents the fact that some spatial units are next to others, then label it "next to".

Role arrow

The label should reflect the role of the object in the association. Thus, if the association submodel is used to represent ownership of patches of land by people, then the role arrow coming from the person submodel should be labelled "owner", and the role arrow coming from the patch submodel should be labelled "owned".

In: Contents >> Working with model diagrams

Creating ghost elements

Large diagrams can become unwieldy, due to the long distances across which influence arrows must be drawn. To work around this, it is possible to create a ghost of a node element, which has the same value at all times as the original. The ghost can be placed close to the other element(s) that the original element influences. A ghost can be recognised by its appearance (ghostly).

A single original element can be ghosted more than once, each ghost being placed closer to other elements. Influence arrows and flows can be drawn to and from ghosts as usual. These will affect all instances of the original. To create a ghost, the following procedure is used:

1. Click on the ghost button on the tool bar, or select the "Ghost" item on the "Tools" menu.
2. Click on the element to be ghosted. The cursor now takes on a 'cross-hair' appearance, indicating another click is needed to complete the operation.
3. Click on the model diagram to place the ghost. If you click on an existing element on the model diagram, it will become the ghost. If you click in a blank area, a new symbol will be placed there.

Alternatively, you can:

1. Click on the ghost button on the tool bar, or select the "Ghost" item on the "Tools" menu.
2. Drag from the component to be ghosted, to the location of the new ghost.

Once a ghost is created, changes to its equation or other properties will also affect the original, and other ghosts created from the same original. Care must be taken in using ghosts as it is easy to overlook the fact that a ghost exists elsewhere and will be affected by changes made to the original which are not appropriate for the ghost. When a component is selected, all its ghosts are highlit in bright green.

There are implied influence arrows between the original element and its ghost. You can turn on the display of these influence arrows, in order to find all related ghosts for example, using the "Show detail… Ghost links" command of the View menu. Once the ghost links are displayed, they can be deleted, in which case the component at the end ceases to be a ghost, and is marked incomplete (red) unless it has an equation of its own.

It is sometimes useful to replace a component in one part of a model with the ghost of another, allowing the value of the ghosted component to be used everywhere the value of the original component was previously used. To do this, you can click on, or drag to, another component when creating a ghost. The component becomes a ghost, keeping all its connections. For this to happen it must be the same type as the component being ghosted. The original equation of the replaced component is remembered, and reappears if it ceases to be a ghost.

Note that if you delete the original element, all its ghosts will become undefined unless they previously had equations of their own. You can delete a ghost without affecting the original, unless you have added influence arrows or flows to the ghost, in which case these will no longer be used by the original.

In: Contents >> Working with model diagrams

Rescaling symbol size in submodels

When you construct a submodel envelope around part of a model diagram, then the symbols inside it are the same size as the ones outside. Similarly, if you construct an empty submodel, then the symbols you place inside the submodel are, by default, the same size as symbols you place outside. In principle, one could construct a complex model, containing many (perhaps nested) submodels, with all the symbols being the same size at any level of nesting. In practice, however, this may be undesirable or difficult to achieve.

You can control the scale of the symbols inside the submodel relative to those in the desktop by using the "Relative scale" slider control in the "basic" tab of the submodel properties dialogue box. This dialogue box is displayed by double-clicking anywhere within the submodel, or by selecting the "Properties…" command from the context menu, which can be displayed either by right-clicking in the submodel or by opening the submodel in a new window, and using the "Edit" menu in this window.

The default symbol size is the same as the desktop, i.e. a relative scale of 1, and using the slider control it is possible to reduce this to make the symbols smaller. If you wish to make the symbols in a submodel larger than in the desktop, you must use the same slider control on the desktop window, either by double-clicking on the desktop or selecting the "Properties…" command from the context menu. This control allows you to reduce the absolute size of the desktop symbols, meaning that the symbols in submodels are now relatively larger.

Note that if you open a separate window to display the submodel's contents (e.g., by doubleclicking on its border) and then do zoom operations in that window, these may also affect the relative scale of the submodel contents. For instance, if you "zoom out" and this results in more whitespace being added around the components, then the scale is reduced because the extra space has to fit inside the same submodel envelope in the parent. This may also happen if you expand the separate window to display more space. Conversely if you "zoom to fit" in the separate window, this may trim whitespace from the submodel contents, causing their relative scale to increase so they fill the submodel envelope.

In: Contents >> Working with model diagrams

Adding background pictures

There is limited support for including pictures on the model diagram.

To include a picture on the model diagram it can be in one of a wide range of formats, including gif, png  or jpeg format. An image can be placed on the diagram using the  image component, in which case it cannot overlap other components. Alternatively it can cover the whole desktop background, or a particular submodel. The image can be cropped, stretched or tiled to fit in the available space.

The following procedure is used to add a background image to the model diagram.

• Firstly, if you wish to use a submodel as a placeholder, add a submodel of the desired size and shape, as described in Adding submodels.

• Secondly, to add the picture, use the select tool to double-click within a blank area, within the submodel if you have added one, or if not, anywhere on the desktop. This invokes the submodel properties dialogue box. Then:

1. Click the "Image…" button in the "Background shade" section.
2. Browse your file system and select the picture you wish to use, which must be in gif or jpeg format, and click "Open".
3. Select one of the "Tiled", "Centred" or "Scaled" radio buttons to control how it is positioned. "Tiled" or "Centred" will cause it to be cropped if it is larger in pixels than the space available.
4. Click "OK" to return to the model window.

The selected picture will now appear in the background of the model, or on the model desktop. You can continue to work with the submodel exactly as normal. You can resize it, in which case the picture will be cropped, stretched or tiled as necessary, or add model diagram elements, which will appear in front of the picture.

The submodel's background colour, or whatever is behind it if it is transparent, will show through any transparent or low-alpha parts of the image.

Note that if the image is positioned centred (i.e., cropped if it is larger in pixels than the space available) the zoom commands do not affect the size of bitmaps (these are fixed in pixels). Therefore if a model diagram is zoomed in to higher magnification, the bitmap will appear smaller than before, relative to its placeholder.

In: Contents >> Working with model diagrams

Preferences dialogue box

You can specify your preferred settings for the interface. The settings are edited using the preferences dialogue box. The settings are stored between sessions in a file called "prefs" in the .simile hidden folder in your home directory. The settings are stored in this file automatically; there is no need to edit it yourself.

The preferences box is displayed by selecting the last item in the "Edit" or context menu, but the preferences always apply to the whole of Simile. It is a 'persistent' rather than a modal box, which means you can continue working with Simile while it is displayed. Most changes take effect instantly, though some only apply when you actually interact with the relevant part of the diagram (e.g., flow routing). Those where you have to type in a preference (e.g., numerical) can be made to take effect immediately by hitting Return. The "OK" or "Cancel" buttons will remove the box; "OK" saves changes to the preferences, while "Cancel" puts the preferences back as they were when it was opened.

The options are displayed in six sections, in a tabbed notebook in the box:

• Layout, for options relating to how the diagram window looks
• Content, for options relating to popups and dialogues
• Edit, to control the model design process
• Build, for options which affect how the model is converted into a program
• Save, for choices about how much information to save
• Run, for options about how the output of the model is presented.

Please consult each section for further help.

In: Contents >> Working with model diagrams

The equation bar

The equation bar offers a quick and simple way to enter equations for any elements on the model diagram.

• Select the pointer tool
• Click on the element whose equation you wish to edit.

The name of the element is placed on the left hand side of the equation bar.

• Click on the equation bar edit box to enter a value or an expression for the element.
• Click on the button, or hit return, to set the equation.
• Click on the button if you make a mistake. It restores the previous entry.

Elements which are calculated from other elements, i.e. are at the end of one or more influence arrows, have the local names of those elements listed in a drop-down list under the button.

• Click on any name listed in the drop-down box to enter it into the equation. The name is added at the position of the cursor in the equation text.

A selection of the most-commonly used functions are listed in a menu cascade under the button. The top level of this cascade also contains an entry labelled "Enum. type constants", for adding the names and members of any enumerated types defined in the hierarchy containing the selected component. This also allows access to the "boolean" unit type and its values.

• Click on any function that appears in the menu cascade to enter it into the equation. The function is added at the position of the cursor in the equation text, and the cursor is moved to inside the parentheses after the function, so you can immediately add its arguments. One more useful thing: if you select part of the text in the equation bar before adding a function from the menus, the function is added with its parentheses around the selection, so the selection becomes the argument.

Auto-complete feature

Typing in the equation bar activates the auto-complete feature. If the first few characters typed match the start of any entry in the cascade menu described above, i.e., valid input parameters, function names or enumerated type names or members, the remaining text in the shortest of those possible matches will be inserted into the text and highlit. The cursor moves to the end of the highlit text. The modeller can then do one of the following:

• Hit the left or right arrow, return or tab to keep the inserted text. If a function name has been completed, the text includes the pair of parentheses that will enclose its arguments, so hitting left-arrow will keep the completion and position the cursor within the parentheses ready to add the arguments.
• Hit the up arrow; this will select alternative completions from the same initial characters.
• Continue to type; the completion text will be ignored. Completions will continue to appear as long as the typed characters still match some menu entries.

Re-use previously entered equation

The entry field in the equation bar has a drop-down list containing equations previously entered in the current editing session. The list can be accessed by hitting down-arrow while editing the equation, or by clicking the down-arrow button to the right of the entry field. This is useful if you need to add similar equations for a lot of components (though you should think about using a single component in a multiple-instance submodel instead!) Also if you leave the equation bar and the equation produces an error message, you need to click on the component again to get back into the equation bar after which the equation you entered will be gone -- you can get it back from the drop-down list to edit it and fix the problem.

In: Contents >> Working with equations

• Graph: This button enables the user to sketch a graph for a mathematical relationship. The relationship is sketched in a window opened up by clicking on this button. Having done this, a reference to a function graph() is automatically added to the expression in the Equation box. This function is evaluated at run time by referring to the graph sketched by the model developer. See the help entry for the graph function for more information.

• Table: This button enables a user to specify a tabulated relationship. The tabulated values are held in a data file, and clicking on this button enables you to browse through your file system for the data file, which can be in a variety of formats, and then choose the particular column of data you require from this file. Having done this, a reference to a function table() is automatically added to the expression in the Equation box. The function is evaluated at run time by doing a table look-up on the values provided. See the help entry for the table function for more information.

Components of an equation

Expressions can consist of one or more of these components: numerical constants, symbolic names, mathematical operators, functions, and conditional expressions.

Numerical constants

Numerical constants are any numeric values, consisting of the digits 0-9, with an optional decimal point and a leading minus sign (for negative values). A leading 0 is optional for numbers less than 1.0. Standard scientific notation is provided (e.g. 0.12345E3 for 123.45), or you can enter very small or very large numbers by multiplying a value by 10 raised to a power, e.g. 0.12345*10^11 or 0.12345*10^-11. See also the section on Arrays and lists for details of how to enter arrays of numerical constants.

Enumerated Type constants
 

Symbolic names

A symbolic name represents the value of one of the variables, compartments or flows that influences the element in question. Each time the value of the expression is calculated, the current value of the influencing element is used.

The only symbolic names for model quantities that you can enter into an expression are those that influence the element in question. These are listed by clicking on the  pull-down menu button on the equation bar, and in the "Parameter" column of the main tab of the equation dialogue box. These must be entered exactly as shown, using the same punctuation (note especially the _ underscore symbols), and using the same case. The easiest way to do this is to select them from the pull-down menu, or to double-click on the name in the "Parameter" column.

Note that the symbolic name entered into the expression is the local name. This can be different from the name displayed on the model diagram, either to make the expression easier to read, or to avoid using certain illegal characters. Local names will also be modified when values come from a multi-instance submodel.
 

Mathematical operators

You can use the following mathematical operators:

Functions

Simile provides a large number of functions that you can use in expressions already built-in, and the facility to extend this list.

Conditional expressions

Equations can include conditional expressions. These enable a complex expression to be constructed from a number of sub-expressions, with the conditional elements being used to select between one expression or another. Standard Boolean operators are available for constructing conditional expressions.

Intermediate variables

The equation dialogue box can be used to enter one or more assignments, before the expression that returns the element's value. These intermediate variables can be used to simplify complex expressions.

In: Contents >> Working with equations

Arrays and lists

Arrays are data structures that consist of more than one element. Each element of the array may be:

• a scalar: a single real, integer or Boolean value; or
• an array or list: thus arrays and lists can be nested (to any depth).

Arrays can be created either automatically (when required) or by the user.

Lists are data structures that consist of zero or more elements, and can only be created automatically. Lists are created when values from a population submodel, conditional submodel or other variable-membership submodel are used outside the submodel itself.

Referring to arrays and lists

An array variable is denoted by enclosing the variable's name in square brackets. Thus, [weight] represents an array of one or more weights. This is a one-dimensional array (a vector), because the variable name is enclosed in a single pair of square brackets. By contrast, [[weight]] is a two-dimensional (rectangular) array of weights. This could be used to represent, for example, the weight of each of 10 varieties of fruit (orange, apple, banana, etc) in each of 20 samples.

Note that the size of the array (also known as its dimensions) is not referred to when the array is used in equations. The dimensions are shown in dimensions field of the equation dialogue box.

An list variable is denoted by enclosing the variable's name in curly brackets. Thus, {weight} represents a list of zero or more weights.

How arrays are made

There are three ways in which an array can appear in a model.

1. An influence arrow might be drawn from a variable inside a fixed-membership, multiple-instance submodel to a variable outside the submodel. As soon as the influence crosses the submodel boundary, what was referred to as a scalar variable inside the submodel becomes an array outside it, since there is now a fixed set of values (one for each submodel instance).

1. The user might build an array inside the equation dialogue for a variable by explicitly listing all the elements of the array. Thus, if you enter [2,4,6,7] in the equation dialogue for a variable, then its value becomes the array consisting of these four values. Note that the square bracket notation has two quite different interpretations. When the square brackets enclose the name of a single variable, then it is understood that this variable is an array. When the square brackets enclose more than one values, then it is understood that the whole structure is an array. This difference is illustrated by the following examples: (a) [weight] and (b) [weight, height]. The first is referring to an array called weight (which could have any number of values). The second is defining an array with two elements, the scalar variable weight and the scalar variable height. The latter has just two elements.

1. The user might use the makearray(…) function. This is called explicit replication.

Processing arrays

Arrays can be processed in a number of ways.

1. You can use a function that is expecting an array as an argument. For example, the function sum(…) will sum the elements of an array.

1. You can use arrays in mathematical expressions. Simile has powerful built-in methods for calculating with array variables which totally avoid the need for looping structures for calculating with arrays. For example, the expression: [k]*[weight] where both arrays have the same number of elements, returns an array with each element equal to the corresponding value of [k] multiplied by the corresponding value of [weight].
2. You can also combine scalar values with arrays in expressions. In this case, the result has the same dimensionality as the array, with the scalar value being used the same way for each element. For instance, 2 + [3,4,6,7] = [5,6,8,9]. This is called implicit replication.
3. Similarly you can combine arrays of different dimensionalities (but not different dimensions), e.g., a 3-element array with a 3x2-element array. What happens is that the function is applied separately to each corresponding set of elements in the argument arrays, and the results combined to give the result array.
4. You can extract particular values from an array. The function element(array,i) returns the i'th element from the array. Thus: element([2,4,6,3],2) returns the value 4 (being the second element of the array).

Array-valued components

If a component's equation evaluates to an array, the component will be displayed with a repeated border as shown above, to indicate a stack of different values. An influence from that component to another will allow the array to be used in the destination component's equation in any of the ways described above. The number of layers in the stack indicates the outermost dimension of the array, up to a maximum of four. Condition boxes and population membership channels cannot have array values.

How lists are made

There is only one way in which a list can appear in a model: by having an influence arrow coming out of a submodel with a variable number of instances. This means:

• a population submodel;
• a relation (association) submodel; or
• a conditional submodel.

As of Simile v6.1 an influence arrow within a special-purpose submodel can be set to deliver values from 'neighbour' components, which form a list as some instances have more neighbours than others.

Processing lists

Lists can be used in functions and operators along with scalar values or other lists with the same member ids (e.g., from another variable in the same submodel). The rules for combining scalars and lists are similar to those for combining arrays as described above. Lists must be processed as soon as they appear in the variable outside the submodel which receives an influence arrow from a variable inside it. You cannot have a component whose value is a list or array of lists. Rather, you must perform some legitimate list-processing operation, such as using the function sum(…) to sum the values of the list, so the variable's value is a scalar or fixed array.

As of Simile v6.1 the 'element()' function can be used to extract a sublist from a list, but the result is still a list, so some aggregating function must be applied to it when creating a component value from it.

More about Replication

In many cases, it is obvious how implicit replication will be applied when combining values with functions or operators. If one is scalar, then whatever the dimensions of the other, the result will have those dimensions. But what if the values are arrays with different nestings? If we add a 1-D array to a 2-D array, the result will be a 2-D array -- but how will the values of the 1-D array be shared out?

What happens is, the elements of the lesser-dimensional array are assigned to the elements of the higher-dimensional array with the same outer indices. For instance, [[1,2],[3,4]] + [10,20] is [[11,12], [23,24]] and not [[11,22], [13,24]]. Effectively the second argument is replicated from [10,20] to [[10,10], [20,20]]. Another way of looking at the same process is to imagine that the arguments are separated into groups, then the function applied to each group and the results combined back into arrays. So, [[1,2],[3,4]] + [10,20] becomes [ [1,2] + 10, [3,4] + 20 ].

The easiest way to remember how it is done is to learn the reason for it being that way, which is as follows: a modeller might wish to get either of the two possible results above, depending on the needs of their model. If they want the second case, they can be sure of getting it by using the makearray() function on the second argument, so they are actually adding [[1,2],[3,4]] and [[10,20], [10,20]] which have the same dimensions. However, if they want the first case, it would be more complicated to arrange it using such explicit replication, so to make things simpler, that is how implicit replication works.

In: Contents >> Working with equations

Enumerated types

Enumerated types allow you to refer to a each object in a collection by name, where the alternative is to use an arbitrary index number. To understand what is meant by an arbitrary index number, consider the following contrasting situations.

Let's say, for example, that you want to model soil water dynamics, with the soil divided into (say) four layers. You would create a submodel with four instances, numbered 1 to 4. You can then find the value for water content in the third layer using an expression such as element([water],3). In this case, the index number refers meaningfully to the layer number.

Now, suppose you wanted to model the growth and yield of four fruit trees: say apples, oranges, lemons and pears. You could use the above approach, creating a submodel with four instances, but in this case you would have to remember that instance 1 is "apples", 2 is "oranges", and so on. The index number is now arbitrary, since any order would be as good as any other.

The enumerated type mechanism enables you to associate the name of each fruit with each instance of the submodel, and to use this name (rather than a number) when referring to a particular instance. This considerably increases the clarity of your model, since someone trying to follow the logic of the model does not need to keep on checking up on the correspondence between an integer number and some more meaningful label.

Defining an enumerated type

Before you can use an enumerated type, you must define it. Enumerated types are defined at the level of the submodel. All submodels contained within the submodel in which the type is defined also have access to the definition. It is therefore most simple to define it for the whole model (so that any submodel in the model can then use it). To do this:

1. Go into the submodel properties dialogue for the Desktop, either by doubleclicking on the background or by selecting "Properties..." from the edit or context menus
2. Click on the "Advanced" tab in the Properties dialogue window to view the advanced options.
3. Click in the edit field above the "Add type" button, type in the name for the enumerated type, e.g. "fruit", and click the "Add type" button.
4. Click on the word "fruit" now entered into the Enumerated types list, to highlight it.
5. Type "apples" into the same edit field, and click on "Add member".
6. Repeat for "oranges", "lemons" and "pears". If at any stage the word "fruit" becomes un-selected, select it again to enable you to add new members.
7. To see what the list of values is for "fruit", hover over the name and observe the pop-up reminder.
8. You can now (or at some later stage) define additional enumerated types in the same way.

Alternatively, once you have supplied the name of the type, you can read the members from a file. To do this, click on the "Get from file" button. This displays the table entry dialogue, and you can use this as if you were specifying a data table to load. However, the data is not actually loaded; instead, all the different values are listed, removing duplicates, and these are made into the members of your enumerated type. The values must be textual, not numbers, so only data entry from columns or grids is allowed.

Using an enumerated type

The following model diagram will serve to illustrate how an enumerated type can be used. It shows a variable size inside a multiple-instance submodel (one instance for each fruit). This variable is exported as an array outside the submodel, then one value is picked up from this array.

If this model were set up without using an enumerated type, then the following would be used:

Submodel fruit: Number of instances (using specified dimensions): 4

Variable size: if index(1)==1 then 4.2 else 3.7

Variable sizes: [size] (Dimensions are automatically set to 4)

Variable size_apples: element([sizes],1)

If this model (with the same model diagram) were set up using an enumerated type (e.g. fruit, as defined above), then the following would be used:

Submodel fruit: Number of instances (using specified dimensions): fruit (i.e. the name of the enumerated type is entered into the dimensions edit field, and automatically sets the number of instances for the submodel to the number of values in the enumerated type - in this case, four.)

Variable size: if index(1)=="apples" then 4.2 else 3.7

Variable sizes: [size] (dimensions are automatically set to fruit)

Variable size_apples: element([sizes],"apples")

Things to note:

The same enumerated type can be used in several places. For example, you could have another submodel that also has dimensions of fruit.

A component's value can be a member of an enumerated type, either specified as a constant or the result of a function such as posgreatest() that returns an array index. Such a value can be used to index an array, or tested for equality with another member of the same type.

Note that the only test we can do with an enumerated type value is a test of equality with the index of a submodel (if index(1)=="apples"...). We can't use the greater-than or less-than operators, since the list is unordered (what a statistician would call nominal rather than ordinal).

Additional considerations

You can use the member names as indices when reading parameter values from a file. This is particularly convenient when the file was used to create the list of member names.

For example, the following file could be used

fruit, price

apples, 7.0

oranges, 7.4

lemons, 7.2

pears, 8.1

Using array functions

You can use the makearray function to create an array. For example, the equation

makearray(1,"fruit")

will create an array with dimensions (size) equal to the number of members in the enumerated type "fruit". It will be populated with values of 1. You can use the test place_in(n)==member to set each value separately. For example, the equation

makearray(if place_in(1)=="apples" then 7.0 elseif place_in(1)=="oranges" then 7.4 elseif place_in(1)=="lemons" then 7.2 else 8.1, "fruit")

will result in the same array as the above table.

Why is it called an enumerated type?

In programming, a type is a set of values from which a variable may take its value. Thus if a variable is of type "integer", then this set of values is all the whole numbers. If it is of type "real", then it is the set of all decimal values that can be represented on the computer. If it is an enumerated type, then the set of values is defined by an explicit list of all the values that the variable is allowed to take. The standard example is the enumerated type "days of the week", in which the set of allowed values is given by the list [Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday]. A particular variable (e.g. "washing day") can be defined to be of this type: we then know that its value must be one of these seven possible values.

In: Contents >> Working with equations