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.

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

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

Step 4: Preparing to run the model

<< Previous Step Next Step >>

This and subsequent steps assume that you are using the single-window Run-Time Environment. This is the default, so it is the one that you will be using if you have installed Simile and not changed your Preference settings. If the windows that appear when you come to run the model differ from the ones shown here, then please go to the "Edit" menu, select the "Preferences" item, and then select the "Use single-window Run-Time Environment" option.

1. Run the model

• Open the Model menu
• Select the Run item.

Simile creates a new window: the execution window. This contains the controls for running the model; a list of the variables in the model; and an area where any of a variety of tools for showing model results can be displayed.

2. Change the time step

Simile supplies a default time step of 0.1 when you first run a model. In natural science, a time step shorter than the time unit results in greater mathematical accuracy, but here we are dealing with an unnatural example; a bank paying compound interest on the balance of the account at the start of each year.

The above screenshot was taken from Simile v4; in v5 and later, the run settings are displayed on a separate tab within the run control notebook. Click on this tab to get at them, and then on the Run Control tab again to get the main controls back.

• Change the value for Time step #1 from 0.1 to 1.

This is because we want to use a time step of 1 year rather than the default value of 0.1 years.

3. Change the duration of the simulation run

• Change the value for Execute for from 100 to 10.

This is because we want to run the model for just 10 years at a time.

<< Previous Step Next Step >>

Step 5: Choosing the output displays

<< Previous Step Next Step >>

1. Select the graph-plot display

• Click on the "Plotter" display tool on the toolbar; or select it from the list in the Add menu.

2. Choose the variable you wish to have displayed

Note the graph window that appears. This is initially scaled with default values on both axes, but will rescale itself as needed. You can re-size the panel containing the graph by dragging on the little boxes on the horizontal and vertical panel separators.

• Click on the "Add a variable" button on the plotter toolbar
• Click on the compartment labelled account in the list of model variables.

You can either click on the line representing the compartment in the "Explorer" tab at the bottom left of the execution window, or you can go back to the model diagram and click on the compartment there.

<< Previous Step Next Step >>

Step 6: Running the model

<< Previous Step Next Step >>

1. Start the simulation

• Click on the "Play" button in the Run control dialogue window.

Note the line that appears on the graph.

2. Continue the simulation

• Click on the "Play" button again.

The simulation carries on for another 10 years.

<< Previous Step Next Step >>

Step 7: Repeating the model edit / run cycle

<< Previous Step Next Step >>

1. Return to the desktop canvas

• Click on the "Go to Model Window" toolbar button.

2. Prepare to edit the component properties

• Click on the pointer button in the toolbar.

2. Change the interest rate from 10% to 15%

• Click on the interest rate variable.
• Change its value from 0.1 to 0.15
• Click on the green tick mark.

3. Run the model again

• Click on the "Run" button on the toolbar.

The model will automatically rebuild, re-initialise and run again.

<< Previous Step Next Step >>

Step 8: Saving and loading the model

<< Previous Step

1. Save the model to file

• Select the "Save As…" item in the File menu in the main (model diagram) window.
• Navigate through the file directory system in the normal way, to the directory where you wish to save the model.
• Enter a name for your model, and save it.

3. Loading a model from file

Either:

• Select the "Open…" item in the File menu
• Search for your model.
• Click on the OK button.

or:

• Select the "Reopen -->" item in the File menu
• Select from the list of recently-used models

<< Previous Step

Adding node-type elements

The node-type elements are the variable and the compartment, as well as the elements used in population submodels. The T text box also behaves as a node-type element, though no node is associated with it. 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.
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 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 arrow

A flow 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 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) 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. 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 may find that one or more arrows leaving the submodel become detached from the point on the submodel boundary that the influence is attached to. You can usually fix this by selecting the move tool from the toolbar, and dragging the attachment point around the submodel.

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 l 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. You will need to move them around prior to drawing the submodel envelope if this is what you wish to do. 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 break 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.

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 function". Now all components starting influences going to the selection, including via ghosts, are highlit. There is also the option to highlight back two functions, and an equivalent choice for highlighting forwards, which shows up nodes 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.

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. Click on the pointer tool.
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

Deleting elements from the model diagram

To delete elements from the model diagram, follow these basic steps:

1. Click on the pointer tool.
2. Move the mouse to the element in the model diagram that you wish to delete.
3. Click to select the element. You can select more than one element at this point, holding down the Ctrl key.
4. Use the context menu (right-click) and choose the delete command.

Please note

If you should accidentally delete something, then the Undo tool will bring it back again.

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. Click on the label of the element in the model diagram that you wish to change.
3. Use the Backspace or the Delete key to remove the existing label.
4. 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 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, then Simile will generate an error message and leave the label unchanged.

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 (a compartment or a variable), 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 value or equation, 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

Printing model diagrams

To print a model diagram, either select the "Print…" option on the "File" menu, or click the button on the tool bar. Either command will invoke the print dialogue box, which allows you to select a printer, choose the number of copies, and change printer settings, such as printing in portrait or landscape orientation.

The model diagram is scaled to fit on a single sheet of paper.

In: Contents >> Working with model diagrams

Undoing and redoing changes to the model diagram

A record is kept of the last 32 changes you have made to the model diagram, including operations like adding new elements, deleting, moving and renaming elements, and entering or changing a value or equation.

Undo

The Undo button on the toolbar and the Undo command on the Edit menu reverses the effect of the preceding operations in turn (up to a maximum of 32). You must undo operations in sequence, it is not possible to undo an earlier change without also undoing all subsequent changes.

Redo

The Redo button on the toolbar is, in effect, an un-undo button: it reverses the effect of a preceding click on the Undo button. As with the Undo button, you can Redo any number of Undo's (up to the maximum of 32). However, note that the Redo button is only activated immediately after a click on the Undo button. If you click on Undo, then do something else (like add a new compartment), then the Redo button is greyed out and you can no longer use it.

In: Contents >> Working with model diagrams

Zooming in and out

You can zoom in and out of a model diagram. Zooming in makes the symbols bigger but shows less of a large diagram. Zooming out shows more of the diagram but makes the symbols smaller.

There are two methods for zooming:

• using the Zoom... item in the View menu
• using the Zoom buttons on the toolbar

Zooming using the "Zoom..." item in the View menu

Zooming using the Zoom buttons on the toolbar

• has an effect between the "Zoom...in a bit" and "Zoom...in lots" items in the View menu: it scales by approx. 1.4x, making the symbols larger and showing less of the diagram.

• has the same effect as the "Zoom...to fit" item in the View menu: see above for a detailed description of its behaviour.

• has the same effect as the "Zoom...to selection" item in the View menu: see above for a detailed description of its behaviour.

• has an effect between the "Zoom...out a bit" and "Zoom...out lots" items in the View menu: it scales by approx. 0.7x, making the symbols smaller and showing more of the diagram. Whitespace may be added.

In: Contents >> Working with model diagrams

Searching for a particular element

Navigating through large or complicated diagrams is made easier by the search facility. This will highlight the element you are looking for, and centre it in the window, if the model diagram extends beyond the window's edges. You can search for elements using text contained in the element's caption, equation or description and comments, using the "Find" tool.

The simplest way is to use the two tools provided on the toolbar:

• "Find" calls up a dialogue box into which you enter the text, and specify which text elements to search
• "Find Next" searches for successive occurrences of variables satisfying your search criterion

Elements are searched in order, with the first to match the text being highlighted. If this is not the one you want, or you want to find others using the same text, use the "Find Next" tool. Alternatively, you can choose the commands "Find..." and "Find next" on the Edit menu. If you choose "Find..." from the context menu after right clicking in a submodel, the search will only turn up components within that submodel, even if you choose "Find next" somewhere else.

Searching equations is a useful way to find where a particular function is used. For example, searching for the text "rand" in equations will find all the elements using the functions "rand_var" and "rand_const".

As well as searching for text, the search system can follow influences around the diagram, even when these come to and from ghosts of the starting point. To use this feature, first select one or more nodes in the diagram, then hit the "Find" button. The dialogue contains a "Follow influences" panel with three buttons, "Components influencing selection", "Components equivalent to selection" and "Components influenced by selection". If you hit the first of these, the selection will be cleared and a component which starts an influence arrow going to a previously selected component will itself be selected. Now you can hit either "Find next" to go to another component that influences the original selection, or "Find" followed by "Components influencing selection" to go to a component influencing the one you just went to. "Components influenced by selection" does the same thing but searches forwards along influences rather than backward, and "Components equivalent to selection" merely finds ghosts of selected components, or bases of selected ghosts.

The description and comments associated with an element are entered using the equation dialogue window, as is the equation itself. The caption (or name) of an element is entered on the model diagram.

Note that the text is not case-sensitive, so "VAR" will mach "var". Note also that the text will match its use anywhere within the text elements searched, so "ar" will match both "car" and "arm". Also note that you cannot put a newline in the search string, as hitting the Return key starts the search. You can instead include \n (backslash-n) in the search string, and this will match a newline in the text being searched for.

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 "advanced" 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.

In: Contents >> Working with model diagrams

Controlling the amount of detail shown in the model diagram

By default, Simile displays all the elements in the model diagram (except for ghost links): compartments, flows, variables, influence arrows, labels, etc. However, you may want to suppress the display of some of the elements to make the diagram less cluttered and less confusing, especially if you are showing a fairly complicated model to someone else for the first time.

Simile enables you to control:

• which types of elements are displayed; and
• the levels of submodel nesting that are displayed for each type of element.

The first submenu for the Show detail item in the View menu enables you to select the type of element whose display you want to change. You can then select the submodel nesting level from a further submenu.

If you select:

The elements are arranged in order, such that turning off the view of compartments also turns off the view of variables at the same level. Turning off the view of variables also turns off the view of influence arrows, and so forth. This is to avoid producing nonsensical or misleading views.

Note that they apply within each window that displays part of the model. So, if you set submodel display to 1 level, so only the outlines of the submodels are displayed, then click on a submodel's boundary to open a new window for it, that window will show the contents of the submodel down to the next level.

There are three other mechanisms for limiting the amount of detail.

1. If you open the properties dialogue box for a particular submodel and go to the Advanced tab, there is a checkbutton labelled "hide contents" in the Appearance panel. If you check this, the submodel will be displayed as an empty box, while other submodels at the same level still display their contents.
2. At the bottom of the "Show detail" menu is a submenu for "Influence sections". This can be set to "Local", meaning only influences fully inside the same submodel are shown, or "Terminal" meaning only those actually connecting a component are shown, as well as "All", the default setting.
3. As described in Customizing the diagram's appearance, you can set the default colour of a component's outline or fill to transparent. This is useful because it will then normally be invisible, but will show up if it is selected or highlit or becomes incomplete.

If you adjust the level of detail in a model's display, then save the model, these settings will be restored when the model is reopened.

In: Contents >> Working with model diagrams

Adding 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. Either the whole model desktop can be used, or a submodel can be used as a placeholder. The image can be cropped, stretched or tiled to fit in the available space.

The following procedure is used to add a picture 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 five 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

Compartment

How to add a Compartment symbol

See Adding node-type elements.

Interpretation

The compartment symbol is used to represent a quantitative state variable. Notionally, we think of a compartment as containing an amount of some substance, though it can be used in other situations where we want to represent the concept of state.

The informal interpretation of a compartment in System Dynamics modelling is that it represents a real, physical compartment that can contain some substance, just like a tank holds water. The compartment requires to be given an initial value - how much water does the tank hold at the start of the simulation? - and we need to construct flows in and out of the compartment so that the amount it holds can change over time.

This interpretation is fine to begin with, but must not be taken too literally. A compartment in System Dynamics modelling is, mathematically-speaking, a state variable: i.e. it is a variable whose behaviour is described by a differential (or difference) equation. And, unlike real, physical compartments, a compartment in System Dynamics:

• can go negative (if the flows out are greater than the flows in, when the compartment gets to zero);
• has infinite capacity (can go on increasing indefinitely);
• cannot contain multiple substances. A real tank can contain both water and oil, but in System Dynamics modelling we would need a separate compartment for each one. However Simile allows a compartment to be an array with the dimensions of an enumerated type -- this could be used to model a single tank containing multiple substances.
• can represent some state that does not correspond to the amount of a substance (such as the height of a tree, the area of land, the time when some event happened, or the x co-ordinate of a moving object).

Rules

• You should not draw an influence arrow to a compartment, except for the special case of initialising it from other model variables. The behaviour of a compartment is determined solely by the net flows in and out of it. Its value at any point of time is found by incrementing or decrementing its value from the previous time step with the net inflow. But when you draw an influence arrow to a model element, you are saying that its value is calculated directly from the influencing variable, and that is incompatible with an approach base on adding or subtracting something from its previous value.

• If you do draw one or more influence arrows to a compartment to initialise it in terms of other model variables, then those variables should be static (i.e. not time-varying).

• If two compartments are connected by a flow arrow, then the two compartments should represent the same substance, and should have the same units.

In : Contents >> Model diagram elements

Flow arrow

How to add a Flow arrow

See Adding arrow-type elements.

Interpretation

The flow arrow is used to specify a term contributing to the rate of change of a compartment. If the flow arrow enters a compartment, it specifies a positive contribution to the rate of change of that compartment. If it leaves the compartment, it specifies a negative contribution to the rate of change.

The information on the flows entering and leaving each compartment is used to calculate the net rate of change of the compartment. The net rate of change is the sum of all the inflow values minus the sum of all the outflow values. The net rate of change is in turn used to calculate the change in the value of the compartment.

If your model needs to keep track of changes in the amount of a substance but you are not interested in where it comes from or goes to, your flow may start or finish on a blank part of the model diagram. In this case a "cloud" will be drawn at the end point, indicating that the amount of substance there plays no role in the model. Each cloud may only have one flow connected to it.

Influences to and from a flow are attached to a "bowtie" (or "valve") symbol which is positioned on the flow. This represents the point that controls the rate of the flow.

In most respects, a flow is treated just like a variable. You can use the full range of the equation language when you enter an equation for the flow, just as you can do for a variable. You can have influence arrows going from it to other parts of the model, again just like a variable. The two differences are that:

• a flow is the only way you can express a rate of change term for a compartment; and
• a flow cannot be a "file parameter".

Rules

• A flow arrow can only be drawn into and/or out of a compartment.
• Influence arrows can be drawn to and from flows.

• The units for a flow value must be the units of the corresponding compartment(s) that it is linked to, per unit of time. For example, if you have a flow going into a compartment whose units are kg, and the unit of time for the model is a year, then the units for the flow must be kg/year.

• It is quite legitimate to have an influence arrow going from one flow to another. You might wish to do this if one flow is proportional to another, or if the two flows are in different submodels.

In : Contents >> Model diagram elements

Variable

How to add a Variable symbol

See Adding node-type elements.

Interpretation

A variable is used to hold one or more values. The value or values come from a mathematical expression. The expression may simply be a number, or it may be a complex mathematical expression involving various variables, operators (such as + and -), functions (such as log or square root), and conditional elements. The value of a variable may vary during the course of a simulation, if it is calculated from other parts of the model that change over time, or it may be constant.

The term "variable" is used to refer to a specific type of model element. This single element can be used for a wide variety of purposes, each of which is referred to in a different way by some modellers. There is rich potential for confusion here, so the following table sets out the correspondence between how a Simile variable is used in a model, and how a modeller would interpret that use. (In case you are wondering why we don't have a number of model elements, one for each type of use: the answer is that this would lead to an unnecessary proliferation of element types. Also, you might wish to change the role of a variable as you build up a model, and you would not want to have to keep on deleting one symbol and replacing it by another.)

Rules

• A variable symbol may have zero or more influence arrows pointing to it.
• A variable cannot have influence arrows pointing to it if it is a "file parameter".

• A variable symbol may have zero or more influence arrows pointing from it.

• A variable may not have other kinds of arrow pointing to or from it.

In : Contents >> Model diagram elements

Influence arrow

How to add an Influence arrow

See Adding arrow-type elements.

Interpretation

To say that "A influences B" (i.e. to draw an influence arrow from A to B) means that A is used to calculate a value for B: in other words, the equation for calculating B will include A.

Rules

You can drag an influence arrow from and to most model elements. The exceptions and special cases are noted here below. Note that if you try to drag an influence arrow to a model element that cannot receive one, then it turns blue instead of green, and you will not be able to connect them together. You can store comments associated with an influence arrow by double-clicking the arrow.

Compartments

• Elements that influence a compartment are used only to calculate the initial value of the compartment. Thereafter, the value of the compartment is calculated by adding the flows in and subtracting the flows out. It is not common therefore to draw an influence arrow to a compartment, though it is possible (in order to calculate the initial value). For example, although one may informally say "water temperature influences fish population size", in the model, temperature must actually influence one of the processes (reproduction, death and so forth) which change the fish population size. The influence arrow from the temperature variable must therefore point to one (or more) of the flows in or out , and not to the compartment representing fish population size itself.

Submodels

• When working with submodels, you may find that an input parameter (A) in one submodel actually corresponds to a variable (B) in another, especially when the two submodels were developed separately, then later brought together. In order to get rid of the duplication, draw an influence arrow from B to the influence arrow from A. This is the only circumstance in which it is possible to draw one influence arrow pointing to another. Input parameter A will disappear, and the influence arrows will be re-drawn to show B directly influencing the element previously influenced by A.

• You can drag an influence arrow to a submodel boundary, from either inside or outside the submodel. This has no meaningful modelling function, but acts as a temporary placeholder to the influence arrow until it is connected to an element on the other side of the boundary. In order to do this, drag an influence arrow from the head of the existing arrow to the desired element.

• You cannot drag an influence arrow from a submodel boundary, other than to complete an influence arrow drawn to the submodel boundary (as described in the previous bullet point).

Influence and role arrows

• You cannot drag an influence to a role arrow or to another influence arrow.

Calculation order

An influence arrow indicates that the value of one component is used in calculating the value of another. So it puts a constraint on the order in which the two values can be calculated each time step; the one at the head must be done after the one at the tail.

This means that if it is possible to get from a model component around a loop of influence arrows back to the same component, the model cannot be executed, because no ordering of the calculations can satisfy all the constraints. The problem is called circularity. Usually this problem indicates that a certain variable in the model should in fact be a compartment, and an influence that connects to it should instead connect to a flow going to it. But there are some circumstances in which circular influences are OK.

• Influence arrows have one property that can be set. To invoke the property dialogue box for an influence arrow, double-click on the arrow. The property is "Use values made in same time step". The property indicates how the ambiguity associated with a circular loop of influences is to be resolved.
• Normally, the value of the component at the end of an influence is calculated after that at its start in each time step. Selecting "Use values..." removes this constraint, and shows this by drawing the arrow dashed instead of solid.
• This may be used in combination with the iteration symbol to implement many iterative methods.

• You can also use this property to create a model process that iterates a fixed number of times and stores all its intermediate results in an array. In this case you do not need the iteration symbol. If you have two components in different fixed-membership submodels, and each has the same number of instances, then they can each have an influence to the other provided one of the influences has the "Use values made in same time step" property, and the equation of the component at the end of this influence uses only values of the other component with indices lower than its own. Subject to a similar restriction it is also possible to specify iteration between a base submodel and its association submodels.

There are two functions in the equation language, "last()" and "sofar()", which also allow a model with a circular chain of influences to execute. Putting "last()" around an expression means that its value at the end of the last time step is to be used, so the component using it does not have to be evaluated after it each time step. Putting "sofar()" round a value has the same effect as selecting the "Use values..." property described above for the influences used by that value; it is used to resolve circularity problems involving intermediate variables, where there is no influence arrow on which the property could be set.

In : Contents >> Model diagram elements

Submodel

How to add a submodel symbol:

See Adding Submodels

A submodel is first and foremost a way of grouping together a number of other model elements, including other submodels. This is done by either drawing a submodel envelope around a number of elements in the model diagram, or by creating an empty submodel and inserting model elements into it.

However, the reasons for wanting to do this are many and varied, and it is important to appreciate that the submodel construct can be used for a range of modelling needs. There are considerable benefits to using a single method to fulfil this range of needs, both in reducing what you need to learn, and keeping the resulting models simple and flexible.

This section overviews the different uses of the submodel construct, and the different types of submodel that you can have. Other sections provide more detail on particular topics.

Using a submodel to show the main components of a complex model

You have constructed a model with a number of compartments and flows. Some relate to vegetation; some to the animals in the area; some to soil water and nutrients. By grouping the model-diagram elements for these different parts into submodels (called "Vegetation", "Animals" and "Soil"), the gross structure of the model is immediately apparent.

Conversely, you may prefer to design a model in a top-down fashion. Starting with a blank screen, you can rapidly add submodels corresponding to the main components of a proposed model, then subsequently add the various compartments, flows etc inside these.

Using a submodel for multiple views on a model, perhaps at different scales

Once part of a model is made into a submodel, you can open a separate window for it (by double-clicking on its boundary with the pointer). This window can be kept on the screen while you scroll the main model diagram to some other part of the model. Also, you can change the zoom factor for each main model window or submodel window separately, enabling you to see part of the model in fine detail while maintaining an overview of the whole model at a coarser scale.

Using a submodel to make a part of a model into a stand-alone model

For the model described above, you may want to see how the vegetation part behaves, assuming fixed inputs from the animal and soil sections that affect it. You draw a submodel envelope around the vegetation, open up a separate window for it, then use the File: Save command to save it to a file. You can then start up Simile again, and load just the saved vegetation submodel (which is now a model in its own right). You can now explore how it behaves by itself. This can be very useful for testing and debugging purposes.

Using a submodel for modular modelling: swapping one module for another

For many years, the battle cry of those fed up with the implementation of models in computer programs was "modular modelling!". If we had a modular modelling system, it was argued, then models could be easily constructed from a number of pre-programmed modules, and the effectiveness of the community as a whole would be greatly increased by the sharing of these modules, avoiding huge duplications of effort.

The submodel concept in Simile supports modular modelling. You can open up a separate window for a submodel (say, a vegetation submodel); clear the contents of the submodel (by doing File: New), then load a different vegetation model into the submodel window. Influence links with the rest of the model can then be made one by one.

Furthermore, Simile supports plug-and-play modularity (which is what is normally meant by "modular modelling"). If two or more vegetation submodels have been designed to share a common set of influences (in and out) with the rest of the model, then the information about this interfacing can be stored in a file (an interface specification file). When you next load one of the submodels from a file, you simply refer to the interface specification file, and all the influence links are made in one quick operation.

Using a submodel for disaggregation;

or (conversely) specifying a fixed number of objects of a certain class

These two terms are lumped together because they are the same concept, seen from opposite perspectives. You can disaggregate an area into a number of patches; or you can think in terms of one patch, then have multiple patches to represent some larger area. The end result in both cases is exactly the same.

Once you have made a submodel you can specify (by going to its Properties dialogue box) that it is a "fixed-membership submodel", and specify a number of instances. In the "Control of number of instances" panel, select the "Using specified dimensions" radio button and enter the number you require. The submodel then represents each of that number of instances. Visually, it now appears different, because it now has multiple lines on the right- and bottom-edges: like a stack of cards. Internally, Simile now handles each instance separately: each can have its own parameter and initial values, while they all have the same compartments, flows etc.

This enables many forms of disaggregation to be captured. For example:

• disaggregating a population into age, size, or sex classes;
• disaggregating a vegetation component into the several species that make it up;
• disaggregating soil or forest canopy into a number of layers;
• disaggregating space into grid squares, polygons, or some other form of spatial unit.

Using a submodel to specify a dynamically-varying population of objects

The modelling world divides into those whose models are based on differential/difference equations (with or without disaggregation); and those who subscribe to an approach based on collections of objects (variously called object-oriented, individual-based or agent-based modelling).

Simile enables a population approach to be combined with a differential-difference equation approach. For example, a modeller might represent the vegetation in terms of compartments and flows, while the herbivores might be represented as individual animals, which are created, grow and die. In order to do this, a submodel is specified as being a population submodel (Specify control of number of instances as "using population symbols" in its Properties dialogue box), and model elements can be added for specifying the initial number, and the rules for the creation of new individuals and the elimination of those already n the population. Visually, the submodel now appears with a shadow line for the top- and left-edges, and another for the bottom- and right-edges.

The remaining option for controlling instance numbers is "Using number of data records in file". This will set the number of instances according to the number of values provided for fixed parameters within that submodel, so the same model can be used for simulations involving datasets of different sizes.

Using a submodel to specify the conditional existence of some part of the model

When a model is implemented in a conventional programming language, large chunks of the program can be enclosed inside an if … end if block: i.e. whether it is actually evaluated depends on some condition. This programming device may be applied to several different purposes:

• You may want to have several alternative ways of modelling some part of the system (e.g. a growth function), only one of which is active in any one run of the model. A flag determines which one is active.
• You may want to model a set of species using a single submodel, but with only some species present in any one run of the model.
• You may want to model a number of spatial patches, some of which contain one land use type, and others of which contain another. You need to include a submodel for each one within the multiple-instance patch submodel - but switch one or the other on in a particular patch.

All these situations can be handled in Simile using a conditional submodel. This is simply a normal submodel, but with a condition symbol added. Visually, we can tell that it's a conditional submodel both by the presence of the condition symbol, and by a set of dots going down diagonally to the right from the submodel envelope. The condition contains a Boolean expression: if this evaluates to "true", then the submodel (or an instance of it) exists; if not, then it doesn't.

A conditional submodel will, like any other, have influences coming out from the model elements it contains. However, the number of values passed along each influence will either be zero (if the submodel does not exist), or one, if it does. This is thus a variable-size data structure: in other words, a list (with the name of the variable enclosed in curly braces {…} ). In Simile, the only thing that can be done with a list is to evaluate it: usually, to sum its values. If the list is empty, then the sum is zero. If the list contains a single element, then the sum is whatever this value is.

Using a submodel to specify an association between objects

Once our modelling language allows us to think in terms of multiple objects of a certain type, then it is frequently the case that we start to recognise relationships between objects. These relationships may be:

• between objects of the same type: one tree shades another; one grid square is next to another; one person is married to another; or
• between objects of one type and objects of another: one farmer owns a field; one field is close to a village.

Since Simile is a visual modelling language, and since such relationships are an important aspect of the design of a particular model, Simile provides visual elements to show diagramatically such relationships between objects. Unfortunately, the term "relationship" is normally used in ecological modelling to refer to a relationship between variables (as opposed to objects), so we use the term "association" instead. This is the same term used in UML (the Unified Modelling Language, the standard object-oriented design language used in the software-engineering community).

An association can itself have properties. We can, for example, have a variable representing the actual distance between a field and a village: this is a property of neither the field or the village, but of the association between them. In Simile, the submodel is the construct that is able to hold a number of quantities, therefore we use a submodel to represent an association: it is then called an association submodel.

However, such a submodel is simply a normal Simile submodel. It becomes an association submodel by virtue of being linked to the submodel (or submodels) representing the objects that have the association. The linking is done using role arrows: one role arrow is drawn for each type of object that participates in the association. Thus:

• for the owns association between farmer and field, we draw a single role arrow from the farmer submodel to the owns association submodel, and one from the field submodel to the owns association submodel;
• for the next to association between one grid square and another, we draw two role arrows from the grid square submodel to the next to association submodel: one role arrow represents the field under consideration, while the other represents its neighbour.

Using a submodel to specify a satellite relationship between one object and another

Let's say that you have a multiple-instance submodel containing information on the species and volume of a set of individual trees: each instance is one tree. You would like to find the total volume of all trees belong to species 1.

This is easy to do if you have model the trees using a fixed-membership submodel (i.e. assuming that you have a fixed number of trees). You simply take influence arrows from the species and volume variables inside the submodel to a variable outside (say total), and give total the equation:

total = sum(if [species]==1 then [volume] else 0)

[species] and [volume] are both arrays with the same number of elements, and Simile's array language matches them up.

This technique will also work if you use a population submodel to model the trees. But suppose you want to do several operations on only the trees of a particular species? Rather than apply the species condition each time, you can make a satellite submodel corresponding just to the individuals you are interested in. It would involve creating a new submodel for the species 1 trees, using a single role arrow from the tree submodel to this satellite submodel, and entering the condition "species==1". An instance of this submodel will be created for each tree of species 1, and not for the others. If you then take the "volume" value into the submodel, then you can extract the volumes just for species 1.

A satellite model with the appropriate condition can represent any subgroup of the instances in its base model, including cases where instances may become members or stop being members of the subgroup as the model runs.

Using a submodel to specify different time bases for different parts of a model

By default, Simile uses the same time step to update all the model state variables. However, if you are modelling a system containing trees and crops, then you might very well want to model the trees on an annual basis (time step of one year), and the growth of the crop on a weekly basis (time step of 1 week).

Simile enables you to specify a time step category for any submodel. For each new time step category that you request, Simile adds an extra Update every entry in the Run Control dialogue window, and that is where you specify the actual time step (e.g. 0.01) to be used for each category.
 

Using a submodel to allow iterative calculation of a function

Some calculations simply cannot be done within the system-dynamics paradigm, as they involve actions that are repeated until some indication of completion is achieved -- for instance, methods involving successive approximation.

These can be included in a Simile model by creating a submodel for the iterative calculation, and including an alarm symbol. This is a boolean valued component, and will cause all the variables in the submodel to evaluate repeatedly until it evaluates to 'true'. If the iteration involves values from the previous calculation step, these can be referenced using an influence arrow with the "Use values made in same time step" property.

In : Contents >> Model diagram elements

Initialisation

The Initialisation symbol is used to specify the initial number of individuals in a population submodel. It is sometimes called the Creation symbol, and belongs to the group of symbols known as channels. The symbol's icon represents the rising sun.

How to add an Initialisation symbol

The Initialisation symbol only has meaning in the context of a population submodel. Therefore, it makes sense to construct a population submodel first, then add the Initialisation to it. This is not strictly necessary: you can add the Initialisation first, then construct a submodel around it, then make the submodel into a population submodel, but it is better practice to construct the population submodel first.

See Adding node-type elements.

Rules

• You can have any number of Initialisation symbols in any one population submodel. The initial population count will be the sum of their values. You may use more than one when the initial population consists of subgroups with different properties. You can use the channel_is( ) function on the initialisation channels to indicate which group each individual belongs to, and set its properties accordingly.

• You do not need to have an Initialisation symbol in a population submodel. If you do not have one, then the initial number of instances for the population is zero. You would then have to have a migration symbol if you wanted your population ever to have any instances. (If you only had a reproduction symbol, then the population would never be able to get going, since reproduction only works for individuals already in the population.)

• The Initialisation symbol may receive influence arrows, but (usually) only from variables calculated at the start of the simulation run, whose values do not change. A typical application would be to initialise the number of instances in the population from some fixed environmental attribute, such as the soil type or the area of the system being modelled.

• It is possible to draw an influence arrow from the initialisation symbol to another element. The usual use of this is with the channel_is( ) function. Otherwise, the value of the initialisation symbol is always the number of individuals it caused to be created at the start of the run, even if the value of its expression changes as the model runs.

In : Contents >> Model diagram elements

Migration

The Migration symbol is used to specify the creation of new instances of a population submodel during the course of a simulation. In contrast to the Reproduction symbol, which specifies this in per instance terms (i.e. the creation of new instances per existing member of the population), the Migration symbol determines the total number of new instances that are created. It belongs to the group of symbols known as channels. The symbol's icon represents a bird on the wing.

How to add a Migration symbol

The migration symbol only has meaning in the context of a population submodel. Therefore, it makes sense to construct a population submodel first, then add the migration symbol to it. This is not strictly necessary: you can add the migration symbol first, then construct a submodel around it, then make the submodel into a population submodel, but it is better practice to construct the population submodel first.

See Adding node-type elements.

Rules

• The migration symbol can receive influence arrows from anywhere in the model, including from within the same submodel. This information is then be used to calculate the current value for the rate of creation of new instances of the population. If the influence arrow comes from within the same population, then this input will be presented (in the Equation dialogue window) as a list, not as a scalar. See below for the reasons for this, and what you should do about it.

• You can include as many migration symbols as you like. In real-world terms, each one corresponds to a separate process leading to the new instances being created: for example, some new trees can appear in a forest from seeds blowing in from outside the forest, while others can appear from a forester planting seedlings.

• It is possible to draw an influence arrow from the migration symbol to another element. The usual use of this is with the channel_is( ) function. The value of the migration symbol is the value of its equation.

Interpretation

The migration symbol it is used to determine the creation of new instances of a population submodel. This must be in terms of whole numbers: you cannot have a part of a new individual. And yet, the value for the migration term can be a floating-point number, e.g. 1.3. So how does Simile use this value to calculate the creation of new instances?

The value of the migration symbol's equation is the number of new instances created over the course of one time unit. Typically the time step is not the same as a time unit, so each time step the value of an internal variable is incremented by the migration symbol's value divided by the number of time steps in a time unit. If this value is one or greater, the integer part of the number is subtracted from it and that number of new individuals are added to the population. The fraction part remains to be incremented on the next time step.

In order that a model with many immigration processes behaves realistically rather than adding all new individuals synchronously, the internal variable for each one is initialized to a random fraction between 0 and 1. Thus there is a possibility that a new individual will arrive through immigration in any time step, even if the value of the channel is small.

Avoiding random behaviour

You might well feel uncomfortable with the non-deterministic nature of the process. To avoid any random variation between runs, you can make sure that the value of the equation for migration divided by the number of time steps in a time unit is always a whole number, which will result in exactly that number of individuals being added each time step. The length of the time step is selected when running the model, and can be found with the dt() function.

In : Contents >> Model diagram elements

Reproduction

The reproduction symbol is used to specify the rate of creation of new instances of a population submodel by each existing instance. It thus differs from the migration symbol, which specifies the total rate of creation of new instances. It belongs to the group of symbols known as channels. The symbol's icon represents an egg.

How to add a Reproduction symbol

The reproduction symbol only has meaning in the context of a population submodel. Therefore, it makes sense to construct a population submodel first, then add the reproduction symbol to it. This is not strictly necessary: you can add the reproduction symbol first, then construct a submodel around it, then make the submodel into a population submodel, but it is better practice to construct the population submodel first.

See Adding node-type elements.

Rules

• The reproduction symbol can receive influence arrows from anywhere in the model, including from within the same submodel. This information can then be used to calculate the current value for the rate of creation of new instances of the population. As with all other relationships within a population submodel (except for the migration symbol), influences coming from within the same submodel relate to the properties of the same instance. So, for example, an influence from a variable "bodyweight" to the reproduction symbol indicates that it is each individual's body weight that influences its own rate of reproduction.

• You can include as many reproduction symbols as you like. Biologically it would normally be pretty inappropriate to have more than one method for reproduction, but it is perfectly legal as far as Simile is concerned.

• It is possible to draw an influence arrow from the migration symbol to another element. The usual use of this is with the channel_is( ) function. The value of the migration symbol is the value of its equation.

Interpretation

The reproduction symbol captures the concept that, in many biological situations, the production of new individuals by those already in the population - reproduction - is an important mechanism for increasing population size. Moreover, the ability of an individual to reproduce will depend on its own characteristics: its age or weight, for example.

As with the migration symbol, Simile needs to resolve the fact that the value for reproduction is a floating point number, while new individuals can only be created one-by-one. The method it uses to do this is similar to that used for migration, and essentially involves the use of the reproduction term to contribute fractions of an individual to an accumulator: when the accumulator exceeds a whole number, then that number of new instances for the submodel are created, and the accumulator is reduced by the number of instances created.

There is, however, an important issue that the designers of Simile had to address. Should there be one accumulator for the whole population, or one for each of the current set of instances? In the former case, if you had five instances, each with a reproduction value of 0.1, then one new individual would be created every 2 time units. In the latter case, for the same settings, you would get no new instances for ten time units, then five would be created at the same time. The first approach seems more attractive, but suffers from a fatal flaw: it assumes that the parentage of newly-created individuals is irrelevant. This severely restricts the modelling you can do: in particular, it rules out modelling evolution, since that requires some concept of (biological) inheritance, which in turn means that each individual needs to know who its parent(s) are. Also, the second approach gives the same behaviour as the first if the value for reproduction is treated stochastically (e.g. as a probability), rather than as a precise deterministic contribution until you have enough credit to make one individual. Therefore, in Simile, each individual accumulates its own credit until it has sufficient to make one new individual.

As in the case of the migration symbols, the accumulators are initialized to random fractions between 0 and 1. This ensures that if the reproduction rates are the same in a lot of individuals, the new ones do not all appear in the same time step but in a random pattern with no pre-determined peaks or troughs. If this non-deterministic behaviour is not required, the technique described for deterministic migration can be used to eliminate it.

In : Contents >> Model diagram elements

Extermination

The extermination symbol is used to specify the conditions under which one instance of a population submodel ceases to exist. It is sometimes called the loss or mortality symbol. It belongs to the group of symbols known as channels. The symbol's icon represents an axe.

How to add a Extermination symbol

The extermination symbol only has meaning in the context of a population submodel. Therefore, it makes sense to construct a population submodel first, then add the mortality symbol to it. This is not strictly necessary: you can add the mortality symbol first, then construct a submodel around it, then make the submodel into a population submodel, but it is better practice to construct the population submodel first.

See Adding node-type elements.

Rules

• The mortality symbol can receive influences from anywhere in the model, both inside and outside the population submodel of which it is a part. This means that the chances of an individual instance being destroyed can depend on both factors that are external to the population, and on the characteristics of that particular individual.

• There can be multiple mortality symbols in the same population submodel.
• It is possible to draw an influence arrow from the mortality symbol to another element. The usual use of this is with the dies_of( ) function. The value of the mortality symbol is the value of its equation.

Interpretation

A mortality channel represents a 'risk factor' for the individuals in its population. Its value should be a fraction between 0 and 1, and this represents the probability of the individual for whom it has that value being removed over one time unit. In this sense it works like radioactive decay; the individuals do not 'lose health' before they die, but rather any surviving individual's chance of dying is determined solely by its current mortality, no matter what it has been in the past. Note that this is different from the behaviour of the migration and reproduction channels, where the rate is summed over multiple time steps. If you require your model to capture a situation in which individuals do die as a result of losing health, the process of health loss must be represented explicitly in the model, with the mortality channel only becoming nonzero when they actually go.

The rate of removal is spread over every time step; if there are 10 time steps in a time unit, and an individual's mortality is 0.3, then there is a roughly 0.03 (exactly 1- (1-0.3)^0.1) chance of removal in each time step. Multiple mortality channels act independently; if there are two, and for a given individual they each have a value of 0.5 over a time unit, then the probability of that individual being removed in that time unit is 0.75. A value of 1 in any time step makes it certain that the individual will be removed in that time step.

Individuals are removed at the start of the time step following the one in which their number came up. This means other values from their submodel instances can be used in that time step. A function is available in the equation language, dies_of(), which returns true if the argument is from a mortality symbol that results in the individual's removal in that time step (cf. channel_is( ))

In : Contents >> Model diagram elements

Role arrow

How to add a Role arrow

See Adding arrow-type elements.

Interpretation

Role arrows join submodels that participate in some form of association, or where one is a satellite of the other. The following sections detail the mathematical methods invoked by the role arrow. In each case, a multi-dimensional matrix is created containing instances of the submodel at the head of the role arrow. The dimensions of the matrix depend on the number of role arrows used, and the different uses are therefore described in separate sections.

• one role arrow
• two role arrows from different submodels
• two role arrows from the same submodel

Rules

• A role arrow can only be drawn between two submodels, one representing the object that plays a role in an association, and the other representing the association itself.
• Role arrows cannot be added in such a way that they form a loop.

In : Contents >> Model diagram elements

Condition

A condition model element is used to specify whether a submodel, or a potential instance of a multiple-instance submodel, actually exists.

How to add a Condition symbol

The condition symbol only has meaning inside a submodel. Therefore, you should make the submodel first, then add the condition symbol to it. This is not strictly necessary: you can add the condition symbol first, then construct a submodel around it, but it is better practice to construct the submodel first.

See Adding node-type elements.

Rules

• A condition element only has use within a submodel (since it specifies which potential instances exist). It should not appear in a population or per-record submodel because these have their own means of creating and destroying instances.

• The expression in the equation dialogue box for a condition element is a Boolean expression: that is, it returns the value "true" or "false". This normally takes the form of some sort of comparison, using the conditional operators such as >, <, >= etc, combined with logical operators such as "and" and "or". However, conditions of the form "index(1) is <expr>" or "any(index(1) is <list_expr>)" are also allowed; see one-sided relation enumeration.

• If a condition is inside a simple submodel, then that submodel either exists or not, depending on the result of evaluating the condition's expression.

• If a condition is inside a fixed-membership submodel, then each instance of the submodel may exist or not, depending on the condition's expression (which would make use of the built-in function index to refer to particular instances).

• If the condition model element is inside an association submodel, then the relation exists between a particular pair of object instances only if the condition's expression evaluates to "true" for that pair.

In : Contents >> Model diagram elements

Iteration

An iteration model element makes its parent submodel an iterative submodel, whose contents should be evaluated repeatedly until a finishing condition is met.

How to add an Iteration symbol

See Adding node-type elements.

Rules

The iteration symbol contains the condition that marks the successful convergence of the iteration. An influence arrow coming FROM the alarm symbol can be used as an argument to the function iterations( ). This function returns the number of iterations made so far. This function can be used to set the initial value (also called the guess) for the loop, i.e. when the number of iterations so far is equal to zero. If the number of iterations so far is one or more, then the result of the last calculation should be used. Since the last calculation depends on the result calculated from the guess, a circular loop of influences is present. Normally, Simile would reject this loop at build time, but setting a property of the influence arrow: "Use values made in same time step" to true, allows the loop to be processed. Influence arrows with this property set are drawn with a dashed line. To set this property for an influence arrow, double-click on it to invoke the property dialogue box.

• The expression in the equation dialogue box for a iteration element is a Boolean expression: that is, it returns the value "true" or "false". This normally takes the form of some sort of comparison, using the conditional operators such as >, <, >= etc, combined with logical operators such as "and" and "or".

In : Contents >> Model diagram elements

Introduction to equations

Equations are used for two purposes:

• to provide the initial value for model elements that need to be initialised, such as

  compartments;

• to enable a value for each other type of element to be calculated while the model is running.

In the first case, the equation is used only at the very start of the simulation: the element’s value may change subsequently as the simulation proceeds. This use of the equation applies to just two types of model element: the compartment and the initialisation element for population submodels. For a compartment, it specifies the initial value of that compartment: the value of the compartment will change during the course of the simulation as a result of the flows into or out of it. For the initialisation element, the equation specifies how many instances of a population submodel initially exist: these may be destroyed and others created as the simulation proceeds.

In the second case, the equation is being referred to throughout the simulation. This use of the equation applies to all other types of model element.

In all cases, you (the model developer) enter the equation using the equation bar or equation dialogue window. The equation dialogue window is required for entering some more complex types of expression. This window is displayed by double-clicking on a model element (except for a submodel or an influence arrow) when you are in

Pointer mode.

An equation has the general form: quantity = expression where “quantity” is some quantity in the model (such as variable or flow) and “expression” is some algebraic expression that is evaluated when the model is running to provide the value for the quantity.

Since you have clicked on the symbol for a particular quantity, you have already specified what quantity the equation is for, and thus you do not have to enter the left-hand side of the equation: all you have to do is to enter the expression.

It is sometimes not appreciated that an equation is constantly being re-evaluated during the course of a simulation run. Thus, an equation for calculating the flow rate for water out of a tank, in terms of the amount of water in the tank, might be:

outflow = 0.1*tank

i.e. the outflow is proportional to the amount of water in the tank. When the model is running, the value for the amount of water in the tank is changing, and thus the calculated outflow changes as well.

In: Contents >> Working with equations

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 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 prentheses ready to add the rguments.
• Hit the up or down arrows; these 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.

In: Contents >> Working with equations

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 button on the equation bar, and in the "Parameter" column 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 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.
 

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

Functions

Simile provides a large number of built-in functions that can be used in mathematical expressions. These include standard mathematical functions, such as log(…) as well as functions specific to Simile.

Some functions have one or more arguments (in brackets, after the function name). Others, such as the time() function, which returns the current simulation time, do not. You must still write the brackets after the function name, even if there are no arguments. This indicates that the name is a function name.

For most functions, the arguments are scalar values, i.e. a single quantitative value. In some cases, an argument is expected to be some other type of data structure, such as a Boolean value (true or false), or an array or list (such as the sum(…) function, which returns the sum of the values in an array or list.

It is possible to include user-defined functions. These can be specific to modelling in a restricted domain (such as plant physiology), so it will be possible for researchers in a particular community to build up and share common libraries of functions. These functions are listed in a text file, and are either macros, which use Simile's equation language to formulate the expression, or external, where a definition is provided in c++ code.

Two special functions are graph(…) and table(…), which relate to a graphically-represented and a tabulated relationship respectively. These can be included in an expression like any other function, but differ from other functions in that the result they return for a given input value can be different in each equation in which it is used: it's definition is local to the equation, rather than being universally defined (like the log(…) function, for example).In: Contents >> Working with equations >> Components of an equation

User-defined functions

There are two different mechanisms for users to supply functions for use in expressions. One is user-defined macros, which provide a short-hand for long or complex expressions that would otherwise have to be used repeatedly in expressions. The other is user-defined external procedures, written in a programming language such as Tcl or C++.

User-supplied function declarations and definitions should be put in files in the Functions directory in Simile's local data tree. This tree is created automatically when you first run Simile. Its location is:

• On Windows: "My Simile Files", under "Documents" (Windows 7 or Vista) or "My Documents" (earlier Windows versions)
• On Linux: .simile, in the user's home directory
• On MacOS: Simile, in the user's home directory

Declarations and definitions in the Functions directory in Simile's installation tree (e.g., "Program files/Simile54") are for functions treated as "Built-In", i.e., expected to be available in any Simile system. It is worth looking at these for guidance in writing your own functions, as the formats are the same.

In: Contents >> Working with equations

Graph function

The Sketch Graph window is called from the equation dialogue when the modeller wishes to sketch, by hand, the relationship between two variables. The relationship is, mathematically, a function: that is, there is only one Y value possible for any given X value.

The graph is sketched using the mouse. The graph consists of a number of straight-line segments. The x-coordinates of the two ends of each segment is fixed, but the y-coordinate of each end can be dragged up or down with the mouse. The y-coordinate at the end of one segment is constrained to be the same as the y-coordinate at the start of the next, making a continuous, if angular, curve. The modeller can vary the number of line segments used to make up the curve: if this number is quite high, then a close approximation to a smooth curve can be obtained.

The function is actually evaluated using linear interpolation. On any one occasion, there will be a single value for the x (independent) variable. The function calculates which line segment this occurs in, and how far along the line segment it lies. Simple algebra is then used to calculate the corresponding value for the resulting dependent (y) variable. Alternatively, you can choose to have the exact y value for the closest defined x value to the one given; see "options" below.

The window itself does not show the names of the variables involved. The independent (X-axis) variable is not yet specified at this stage, since that only happens when the user returns to the Equation window. The x value can be any Simile expression. There does not need to be a specific variable associated with y-axis, since the result of evaluating the graph function is just like any other function result - a value to be incorporated into the rest of a mathematical expression: graph(weight) plays the same role in an equation as log(weight), for example.

Click the OK button to return to the equation dialogue window. New text reading "graph()" has been inserted into the expression field, if this is the first time the sketch graph has been used for this equation. You must insert, between the brackets, the name of the independent (x-axis) variable or other expression. If you have already entered a graph() expression in the equation dialogue box, then the opportunity is given to edit the previously-drawn curve. It is not possible to use two different graph() functions in the same expression.

Drawing the curve

The curve is constructed by moving the mouse into the graph pad, holding the mouse button down, then moving the mouse from left to right (or from right to left) along the desired path. You are unlikely to get it right first time. If a line segment ends up in the wrong place, just try again. For finer control, you can click on a vertical line at the required point: the ends of the two line segments meeting at this line will then jump into position.

Scaling the axes

The two edit fields along each axis (Min and Max) are used to indicate the range of each axis. You click in the edit field, then enter a value that is appropriate to the lower and upper limits respectively of the variable in the relationship. Thus, if the independent variable were temperature, and we were modelling a site in Africa, then the x-axis might be scaled to be between 10 and 40 (the units of degrees Celsius are implicit). When you change the scaling of an axis, the actual sketch stays the same, so the behaviour of the function is changed to correspond to the new axis scaling.

By default, "Min" and "Max" are 0 and 100 respectively on both axes. It is not permissible to leave any entry blank.

Current position

These two edit fields display the current position of the mouse pointer in the graph area whilst dragging the curve. You can use this display to exercise finer control over the curve. It is also possible to enter values directly into these boxes, copying values from a table for example. After entering the Y-value, press the return or enter key on the keyboard to have the graph re-drawn to include the new pair of values.

If you want exact values for all the points in the graph, click the "Edit as table" button, and enter them with the keyboard, or by cutting and pasting.

Options

Between points

The normal behaviour of the graph function is to interpolate between the two nearest defined y values to get the function's result. Alternatively you can select 'Round' here, in which case you get the exact y value for the nearest defined argument value. The shape of the sketch graph changes to illustrate the actual values returned.

Out of range

There are three options to determine what happens if the independent variable falls outside the range scaled in this window, whilst the model is running.

• truncate: this option extends the curve horizontally to the left and to the right.
• extrapolate: this option extends the curve along a line with the same slope as the first and the last segment.
• wraparound: this option joins up the left and the right ends of the curve. It is useful for defining repeating functions like sin(x).

X axis resolution

Clicking on the right-arrow button doubles the number of vertical lines in the graph pad area; clicking on the left-arrow button halves the number of lines. The higher the resolution, the greater the number of line segments making up the curve, and the smoother the curve is.

Altering function while model is running

The behaviour of the sketch can be altered while the model is running, using the edit sketch helper. This does not affect the version of the function in the saved model.

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

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

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

2. 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].
3. 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. Similarly you can combine arrays of different dimensionalities (but not different dimensions), e.g., a 3-element array with a 3x2-element 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. Only compartments, variables and flows can 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.

Processing lists

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

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 dimensnsions. 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]]. 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

Dimensions

The dimensions field in the equation dialogue box is provided for reference only. It is not necessary to edit this information. The dimensions are a measure of the size of an array (or vector). Note that a vector is a one-dimensional array, and the term array is used here to cover both.

[2,3,4] has dimensions 3

[[2,3,4],[4,6,8]] has dimensions 2,3

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 an arbitrary index number.

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.

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.

Local names

The local name is automatically composed from the full path name by replacing characters that are illegal in equations (such as spaces and carriage returns) with underscores. If you would prefer to use a different local name to refer to the full path name, the local name can be edited. To do this, you must have the equation dialogue box open, and click on the tab labeled "Parameters etc.".

Right-click on the name in the list box to edit it. Each other model element can have only one local name in this one (though the other model element might be referred to using a different local name in further other model elements expressions). For this reason, if you edit the local name, you may also need to edit the expression itself to update the corresponding references.

In: Contents >> Working with equations

Submodel properties dialogue

The submodel properties window enables you to set the properties of a particular submodel. To invoke the dialogue box, either:

• double-click in any blank area of the submodel, or
• select the "Properties..." item in the context menu for the submodel.

The properties dialogue has two tabs, "Basic" for those most commonly used, and "Advanced" for those that are needed less often.

Basic properties

Control of number of instances

The most important property of a submodel is that it can exist in a number of different instances. Each instance follows the same logic in its calculations, but can differ in the values of its attributes. There are two mechanisms for controlling the number of instances of each submodel.

• Using specified dimensions (default)
  This radio button enables you to specify that the submodel has fixed dimensions. By default, each new submodel exists only in a single instance. The dimensions can be set to be any vector or higher-order array. For example, entering 10 in the edit box, creates a vector of 10 instances of the submodel. Entering "10,10" in the edit box, creates an two-dimensional array of 100 instances of the submodel.
• Using number of data records in file

  This radio button allows the number of instances of a submodel to be controlled by the number of data records in the file. The submodel must contain one or more fixed parameters, (i.e. a variable whose values are read in from a data file). The values for the fixed parameters are set in the normal way, and the number of records determines the number of instances created.

• Using population symbols
  This radio button enables you to specify that the submodel is a population submodel. In this case, control of the number of instances is performed using the population symbols: creation, reproduction, immigration and extermination.

Background shade and/or image

These three buttons are used to specify the nature of the background colour for the submodel. The "Clear background" button specifies that the submodel is actually transparent: it will take on the colour of the enclosing submodel (or the main desktop window). (i.e. it should be read as "the background is clear", rather than the instruction "Clear the background").

The "Background shade" button calls up a standard colour selection dialogue window. Use this to select the colour of the submodel's background. This is highly recommended: having coloured submodels greatly enhances the effectiveness of the model diagram in communicating the structure of the model to other people.

The "Image…" button calls up a standard file selection dialogue window. Use this to select an image file (in either gif or jpeg formats) for the background of the submodel. There are three modes for image display:

• Tiled: If the submodel is larger than the image, the image will be repeated (tiled) across the area of the submodel; if the submodel is smaller than the image, the bottom and right of the image will be cropped to fit.
• Centred: The image will be displayed at the centre of the submodel. If the image is larger than the submodel box, only the centre of the image will be displayed. Note that a centred image will not be displayed in the background of windows showing only that submodel, because it might look confusing.
• Scaled: the image will be stretched or shrunk along each axis to fit the submodel exactly.

If a background shade as well as an image is specified, the background shade will be visible through transparent parts of the image, and also around a centred image if it is smaller than the submodel.

Description and comments

The Description and Comments boxes enable you to type in free-form comments about the submodel. Use this to document the date of creation, author, main features, etc.

Advanced properties

Calculation

• Use own code

  Allows an external procedure to set values in the submodel. See Using externally-supplied procedures for details.

• Use units in math

  This selects how physical units and dimensions are handled when checking equations in this submodel. The two mechanisms for handling units are described here. Selecting 'No' means only the first mechanism is used. 'Yes' enables both mechanisms. 'Default' uses the same setting as the submodel's parent model, or first mechanism only for the top-level model.

• Time step index

  This enables you to specify on which time step the submodel is updated. In most models, there is only one time step (the "Time step #1" value in the Run Control window), which applies to all submodels. In that case, you do not need to do anything here. However, in certain circumstances, it is useful to be able to change this. See time step index for information on these cases.

Appearance

• Hide contents

  This suppresses the display of all model elements inside the submodel. You can do this for neatness of the diagram, so that some person looking at a complex model is spared the detail of a nested submodel. However, it is also useful if you are working with a complex model diagram, since a number of screen operations (such as deleting a model element) become quite slow with a complex model when all model elements are displayed.

• Relative scale

  This changes the size of the model diagram elements in this submodel relative to those in its parent.

Enumerated types

Enumerated types are created using this dialogue box. Enumerated types are lists of names that can be chosen amongst when setting the value of a variable of that type. Please see the help page for more information on enumerated types and on how to create them.

In: Contents >> Working with submodels

Opening a new window for a submodel

You may want to open a new window for a submodel for one of two reasons:

• to view and edit the submodel independently of the main model
• to save the submodel to file, or load a previously-saved submodel into the current model.

You open up a new window for the submodel by selecting Pointer mode from the tool bar, then double-clicking on the submodel envelope. Note that it is fairly easy to miss, and click inside the submodel. In that case, the submodel properties dialogue will appear. If that happens, click "Cancel" and try again.

Note that any changes you make to the submodel in its own window are simultaneously made to the submodel in the desktop window. You can edit the model diagram using the same set of tools as are available in the desktop window. Note however, that the toolbars may not be displayed if the window is not large enough. All the tools must then be accessed through the menus.

Note also that any actions that change the scroll region of the new window, for instance growing it beyond its current scroll region, will alter the scale of the submodel relative to its parent. To understand this, consider the following terminology:

• The submodel panel is that part of the main desktop window occupied by the submodel, i.e. that is enclosed in the submodel envelope.
• The submodel window is the separate window opened up for viewing and editing the submodel.
• The submodel scroll region (also called the canvas) is the area behind the submodel window that is available for the submodel diagram.

Thus, the submodel window reveals part of the canvas. We can move around the canvas by scrolling the window with the side and bottom scroll bars. Only if the window is actually the same size as the canvas, will not need to scroll the window to see the whole canvas.

Note, now, that the submodel canvas always represents the same area as the submodel panel. Thus:

• if you increase the size of the submodel canvas, then the size of model-diagram elements in the submodel panel will decrease, relative to the other elements in the desktop window; and
• if you increase the size of the submodel panel, and use the zoom to fit option for the submodel window, then the size of model-diagram elements in the submodel panel will increase, relative to the other elements in the desktop window.

In all cases, however, you can also adjust the relative scale of the submodel without opening up a separate window for it, by using the relative scale slider in the submodel dialogue window.

In: Contents >> Working with submodels

Saving a submodel

In order to save a submodel to file, open a new window for the submodel, then select the "Save" command on the "File" menu of the submodel window.

The submodel will be saved as a .sml file. In fact, this file will contain nothing to indicate that it is a submodel: Simile makes no distinction between a main (top-level) Simile model saved to file, and a submodel saved to file. If the submodel had influences coming into it from other parts of the model, then the influenced variables in the submodel will be converted to "Input Parameters", indistinguishable from input parameters in top-level models specified by the model designer. The only thing to note is that these automatically-created input parameters will appear red in the model diagram if you have not specified "Min" and "Max" values for them in the equation dialogue prior to saving the submodel.

In: Contents >> Working with submodels

Loading a saved model as a submodel

In your current model, create an empty submodel. This should be fairly large, so that the diagram of the model you will be inserting is not all squashed up.

Select pointer mode, and double-click on the boundary of the submodel. (If you miss, you will see the submodel properties dialogue window: cancel this and try again). You will see a new model diagram window, just like the main desktop window except smaller. It will have the same menu as the main desktop window.

Select the "Open" command from the "File" menu, and locate and load the Simile model (.sml) file.

You will see the loaded model in both the new submodel window, and in the round-cornered submodel box in the main Desktop window. You can close the submodel window, or keep it there if you want to work on the submodel and it is too small in the main Desktop window. Note that, if you enlarge the submodel window, you will probably want to do Zoom to fit in order to get the model submodel diagram to occupy the whole of the available space.

Any model or submodel saved to file can be treated as a submodel or as a model. No real distinction is made between the two concepts. If you load a previously-saved model into a submodel window, then it will become a submodel in the current model. If, on the other hand, you load a previously-saved submodel into the desktop window (i.e. the main, top-level window), then it will become a model in its own right.

So, in order to load a previously-saved submodel as a stand-alone model, all you need to do is to start a new session of Simile (or select the "New" command from the "File" menu in the desktop window), then select the "Open" command from the "File" menu in the desktop window, and find the .sml file that contains the previously-saved submodel.

Any variables in the submodel that had previously received influences from outside the submodel automatically become "Input parameters". If they had been previously assigned min and max values, then you will get a slider for each such variable when you come to run the submodel (now a model). Any such variable that had not been assigned minimum and maximum values will appear red when you load the submodel, and you need to open up the equation dialogue for this variable and either:

• unclick the "Input parameter" check box and enter a value into its equation dialogue; or
• enter min and max values.

In: Contents >> Working with submodels

Multiple-instance submodels: fixed membership

A fixed-membership submodel is one type of multiple-instance submodel. In this case, the number of instances is fixed throughout the simulation run.

By making a fixed-membership multiple-instance submodel, we are saying that:

• The model contains a fixed number of objects, each of which behaves according to the same rules (represented by the model elements and equations inside it).

• Each object may (and usually does) differ in one or more numeric values: the initial value for compartments, or the values of parameters.

When should I use a fixed-membership multiple-instance submodel?

Fixed-membership submodels are useful for handling many forms of disaggregation in model design. You may, for example, be interested in modelling the changing population of a country like the UK. You first model has a single compartment, representing the total population size. You then decide to represent this information on a regional basis, in order to capture differences in population parameters in different regions. You have now disaggregated your model into multiple regions. Your model diagram looks very similar: the only difference is that the part representing population dynamics is now wrapped up in a multiple-instance submodel, one instance for each region. This is a fixed membership submodel, because the number of regions is fixed.

Conversely, fixed-membership models can be used for scaling up. To take the previous context, you might have begun making a model of the population growth of just one region. You then want to scale the model up to the whole of the UK. Again, you wrap up the original model and make it into a fixed-membership, multiple-instance submodel.

Although disaggregation and scaling up are conceptually very different - in fact, opposite - activities, the appearance of both the before and after model diagrams is the same in both cases. The only difference comes in terms of the initialisation and parameterisation for the original model.

How to make a fixed-membership submodel

1. Use the submodel tool to drag a submodel envelope on your model diagram. The submodel may be drawn in an open area of the model diagram, and not enclose anything. Or you can drag the submodel around existing elements on your model diagram, if you want those enclosed in the submodel.

1. Open up the submodel properties dialogue by selecting the Pointer tool, then double-clicking anywhere in the blank area of the submodel (not on its border, and not on any existing elements). Note that the "Generated set" radio button has been selected by default. This term denotes that the submodel is to be fixed-membership. Enter a value into the "Dimensions" box corresponding to the number of instances you want. Click on the "OK" button.

2. Back on the model diagram, the submodel's appearance has now changed. Its simple border has now been replaced by multiple lines on the bottom and right, indicating that there is a fixed number of multiple instances (it's meant to look like a stack of cards).

How to make the different instances different

There are two main ways in which you can make one instance different from the others.

• You can give each instance a different initial value for one or more compartments.
• You can give each instance a different value for one or more parameters.

Conceptually, these are very different. In the first case, you are saying that the differences between the individuals are simply in terms of the state they happen to be in when you start the simulation. In the second case, you are saying that the individuals differ in some intrinsic property. You can of course mix these: individuals may differ in both their initial state and their parameterisation.

There are several methods you can use to assign different values to different instances. These techniques apply equally to compartments and parameters.

Load the values from a file

If you put a fixed parameter inside a fixed membership submodel, then when you run the model, there will be an entry in the file parameters dialogue requiring values for this parameter. The data you enter will have to include a value for each instance of the submodel.

Generate the values randomly

Enter the expression

rand_const(0,10) (replacing 0 and 10 by whatever range you want)

in the Equation box for the compartment or parameter to cause each instance to be assigned a value randomly picked from the specified range. rand_const(A,B) samples from a rectangular probability distribution over the range A...B: Simile also alows you to use values from other distributions, e.g. Normal (and it is possible to engineer these yourselves).

Note that if there is no explicit indication that they return a constant value, Simile's statistical functions return a new sample from the given distribution on each time step. If you are using a sampling function to set up a multiple instance submodel with data that conforms to a statistical pattern, it is probable that you want each instance to keep the value it was given when the model was initialized or reset. This can be arranged by wrapping the statistical function in the at_init() function, e.g., at_init(gaussian_var(50,10)).

Select elements from an array

If your submodel has a small number of instances, you can explicitly list the value for each instance in an array, and select from this array the value for each instance.

Let's say you want to model the loss of water from 5 tanks. The tanks differ in terms of the initial amount of water they hold: say 10,5,20,50 and 9 litres. You have made the water flow model into a submodel with 5 instances. You could use the following expression in the Equation box to initialise the water compartment:

element([10,5,20,50,9],index(1)) (replacing [10,…,9] by whatever you need)

This selects the value 10 for the first instance, the value 5 for the second, and so on. See the help information on the functions element and index for more information.

Alternatively, you could have a separate array variable, say "initial_water", whose only job is to hold the array of values, take an influence arrow from it to the compartment, then select a value from that array for each instance:

initial_water = [10,5,20,50,9]

water = element([initial_water],index(1))

Use conditional expressions

You can develop expressions conditional on the value of index(1) (i.e. the numeric index of each instance) in a wide variety of ways. For example, you want the first three instances to have a value of 20, and the rest 10, then you could use the expression:

if index(1)<=3 then 20 else 10

Use a sketched graph or built-in table

You could use the sketch graph or built-in table functions in the equation dialogue to specify the values of the compartment or parameter as a function of index(1). This is particularly appropriate if the instances have a natural ordering, e.g. age-classes in a population, or soil layers, when the quantity under consideration might be considered to have some ordered relationship with the instance number.

Variables exported from a fixed-membership multiple-instance submodel

If you take an influence from a variable (a) in a fixed-membership multiple-instance submodel to another variable (b) in the same submodel, then b sees a as a scalar variable: i.e. as having a single value. You could use an expression for b like

3*a

How can this be, when we know that a has one value for every instance of the submodel? It's because the equation is expressed as a general rule: whatever value of a a particular instance has, then its value of x is 3 times greater.

However, things change when we take an influence from a variable (a) in the submodel to one outside (c). Because c is outside the submodel, it can see all the values of a. a must now be treated as an array of values, not as a single value.

An array is denoted by enclosing the name of the variable with [...], thus a inside the submodel has become [a] outside it. Thus, when we open up the Equation dialogue window for c, the influencing variable appears as an array, and its name is enclosed in square brackets. And the expression for calculating c must do the same. Thus, legitimate expressions for c are:

3*[a] c becomes an array with as many elements as a, each multiplied by 3

sum([a]) c has a single value, equal to the sum of the elements in the array [a]

In: Contents >> Working with submodels

Multiple-instance submodels: population

A population submodel is one type of multiple-instance submodel. In this case, the number of instances may vary throughout the simulation run.

By making a population submodel, we are saying that the model contains a collection of objects, and individual objects can be created and destroyed during the course of a simulation run. The objects may (and usually do) differ in their attributes, but this is not such a central idea as it is for fixed-membership submodels: we can get interesting behaviour from a population model even if all the individuals have the same initial state and the same parameterisation.

When should I use a population submodel?

When I introduced the idea of fixed-membership multiple-instance submodels, I said that you can decide to have one in your model either by breaking something into smaller pieces (disaggregation), or by representing a larger unit as a multiple of a set of smaller units (scaling up).

Similar ideas apply to using a population submodel, but we use slightly different language. If you are interested in the behaviour of some large unit, such as the population dynamics of the deer on an estate, then you may consider it appropriate to model this in terms of all the individual deer on the estate. This is more a process of decomposition of the population into individuals rather than disaggregation. With the latter term, the small unit is like a miniature version of the larger one, with all the same attributes, whereas an individual deer is not a smaller version of a population. Conversely, you may have first modelled one deer, following its life history, then decided to make a model with lots of those rather than just one. This is more a process of multiplication rather than scaling up. (There is no standard terminology here. Don't worry too much about the terms used: the important point is to see that something different is going on with populations.)

How to make a population submodel

1. Use the submodel tool to drag a submodel envelope on your model diagram. The submodel may be drawn in an open area of the model diagram, and not enclose anything. Or you can drag the submodel around existing elements on your model diagram, if you want those enclosed in the submodel.

2. Open up the submodel properties dialogue by selecting the Pointer tool, then double-clicking anywhere in the blank area of the submodel (not on its border, and not on any existing elements). Click on the "Population" radio button. Do not enter a value into the "Dimensions" box. You can use the Creation symbol to specify the initial number of individuals in the population. Click on the "OK" button.

3. Back on the model diagram, the submodel's appearance has now changed. Its simple border has now been replaced by a double line on the bottom and right, and a double line on the top and left.

How to make the different instances different

In general, you can use methods that are the same as or similar to those used for fixed-membership multiple-instance submodels, with some differences:

• Use the channel_is() function. If your population has multiple channels (creation, immigration and reproduction symbols) then an equation can apply this function to a parameter corresponding to an influence from one of the channels to get a boolean result which is true in each individual that appeared due to that channel.
• Use the parent() function. If your population contains a reproduction symbol, an equation can apply this function to a parameter corresponding to an influence from this symbol. The result is the index number of the individual that became the parent of the current individual, or 0 if the current individual appeared due to some other channel.
• You cannot put a file parameter (fixed or variable) in a variable-membership submodel. This is because the table created by loading the data for a file parameter has a fixed number of values, and cannot be matched to a variable number of submodel instances.

Variables exported from a population submodel

With a fixed-membership multiple-instance submodel, variables are exported as arrays, since Simile knows precisely how many elements there are, and this number remains fixed for the duration of the simulation run. However, the number of instances for a population submodel can change dynamically during the course of the simulation run. Therefore, the set of values for a variable are exported as a list rather than an array. The number of elements in a list can vary, and (unlike an array) we can attach no particular significance to "the third element" of the list (since this might refer to quite different instances at different times during the course of the simulation)

Note that although an array can be passed around from one variable to another, a list must be processed into a scalar (single-valued) quantity as soon as it is received. Since any quantity exported from a population submodel must be a list, this means that the receiving variable must derive a single value from this list: its sum, perhaps, or its largest value, using a function capable of having a list as one of its arguments.

Special model diagram elements for population submodels

Four of the model diagram elements are only used in population submodels. They are:

• initialisation, for specifying the initial number of instances;
• migration, for specifying an absolute rate of creating new instances;
• reproduction, for specifying the rate per individual for creating new instances; and
• extermination, for specifying the conditions under which an instance is removed.

See the appropriate entries for further information on how to use these elements.

In: Contents >> Working with submodels

Plug-and-play modularity using submodels

"Plug-and-play" modularity means the ability to replace one module in a model with another, without having to specify how the module's inputs and outputs link up with the rest of the model. This requires that the modules to be swapped share the same interface to the rest of the model.

In Simile, a module is a submodel. There is a mechanism for replacing one submodel with another: simply open a separate window for the submodel, and use the File: Open command to load a new submodel. However, this by itself does not automatically remake all the links between variables in the submodel and those in the rest of the model.

In order to have plug-and-play modularity, we need to specify the interface between a submodel and the rest of the model. This means stating which variable in the submodel is linked to which variable in the main model, and the nature (dimensions, units) of the two variables. This specification is saved in a separate interface specification file, and can be loaded when we create a new submodel, in order to re-make all the linkages.

Demonstration of plug-and-play modularity

• Step 1: Build a model with submodels
• Step 2: Save one of the submodels as a separate model
• Step 3: Save the interface specification
• Step 4: Clear the submodel
• Step 5: Load an alternative version of the submodel
• Step 6: Load the interface specification file

In: Contents >> Working with submodels

Conditional submodels

A conditional submodel is used when there are conditions under which a submodel, or an instance of a fixed-membership multiple-instance submodel, may or may not exist. By "exist" we mean that Simile evaluates the expressions in the submodel. The existence of each instance of the submodel is determined by evaluating a Boolean expression in a condition symbol placed inside the submodel.

The conditional submodel may represent a phenomenon that only occurs at certain times, for instance bush fires. Or it may represent a phenomenon that occurs in some, but not all, of the members of a group; for instance, if an area of interested is represented by a grid, then some vegetation types, e.g., forest, may be present in only some of the grid squares, so the processes associated with them sould be represented in a conditional submodel of the grid-square model.

If the submodel has influence arrows going from inside to variables outside itself, then:

• if the submodel exists, the values emerging from the submodel are those calculated from the variables in the normal way;
• if the submodel (or instance of it) does not exist, then a value is not exported for each variable: there is no value, since the variable just doesn't exist.

This means that we cannot be sure how many values are going to be exported from a single variable inside the conditional submodel. For a simple submodel, there could be zero or one values. For a fixed-membership multiple-instance submodel, there could be 0…n values, where n is the number of instances for the submodel.

Therefore values are always exported as a list from a conditional model, since a list (as opposed to an array) is the data structure used when the number of values in the data structure can vary dynamically over time. A list must be processed as soon as it is received: it cannot be passed around as a persistent data structure. Typically, you will simply use the sum function to add the values in the list together.

A few more detailed considerations:

• The condition equation itself, and the equations of any variables in the submodel that affect the condition, must be evaluated in every case. If the condition comes out false, the values of these variables are discarded.
• The condition cannot depend on a value outside the submodel that itself depends directly on values inside, since getting this value would require the existence status of the submodel to be already known. Simile reports this as a circularity problem.

In: Contents >> Working with submodels

Iterative submodels

An iteration symbol and a property for influence arrows are included, to allow a loop to be executed multiple times within one time step. Such looping may be required, for example, when the value of a variable cannot be calculated directly from others, but is found by trying many successive values to minimise some error function.

The basic elements of an iterative loop are as follows.

The iteration symbol contains the condition that marks the successful convergence of the iteration. An influence arrow coming from the alarm symbol can be used as an argument to the function iterations( ). This function returns the number of iterations made so far. This function can be used to set the initial value (also called the guess) for the loop, i.e. when the number of iterations so far is equal to zero. If the number of iterations so far is one or more, then the result of the last calculation should be used. Since the last calculation depends on the result calculated from the guess, a circular loop of influences is present. Normally, Simile would reject this loop at build time, but the definition of the iterations() function makes it explicit that the influence from the alarm symbol refers to its value on the previous iteration, and therefore cannot be part of a circularity.

You do not have to use the iterations( ) function; if the results of previous iterations are irrelevant, as for instance in a generate-and-test algorithm, you may not need to have any influences from the alarm symbol at all. Alternatively, if each result does depend on previous ones but the actual number of iterations is irrelevant, you can use the boolean value of the alarm symbol directly to choose between starting a new iterative approximation (true) and refining the result of the previous iteration (false).  In this case you would get a circularity, but setting a property of the influence arrow: "Use values made in same time step" to true, allows the loop to be processed. You also need to set this property on influences that convey the result of the last iteration step for use at the start of the following step. Influence arrows with this property set are drawn with a dashed line, and the equation that uses their value gets the one from the previous iteration rather than the current one. To set this property for an influence arrow, double-click on it to invoke the property dialogue box.

It is unlikely that any of the above description is comprehensible without an example. The included example model for Ball-Berry stomatal conductance poses a problem for conventional System Dynamics modelling tools because it depends upon the solution of the following pair of simultaneous equations.

Gs = g₀ + g₁ * A * H / C_a

A = Gs * A_Q

Apart from the external parameters, g₀, g₁, H, C_a and A_Q, the equation for Gs depends only on A, and the equation for A depends only on Gs. In this implementation, the loop is opened, by introducing a place-holder for Gs, called Gs_0. This variable is calculated from A. A is calculated using Gs. A guess is made for the initial value of Gs. Subsequently, Gs is set to the last calculated value of Gs_0. The influence arrow from Gs_0 to Gs is dashed, indicating that the value from the previous iteration is to be used. The alarm symbol terminates the iterative loop when Gs and Gs_0 differ by less than one part in one thousand.

That's all there is to it, except that it's worth noting what to do if the iteration does not converge. It is necessary to use the new "Abort Execution" command in the "Model" menu of the model diagram window (i.e. NOT in the run control window).

In: Contents >> Working with submodels

Time step index

Introduction

Specifying different time step indices for different submodels is an advanced topic. It can lead to misleading results, and should be used only in accordance with the following notes.

By default, all the model state variables are updated using the same time step. When Euler integration is used to update the state variables, differential equations are, in practice, solved as if they were difference equations, with a small but finite δt. By specifying δt , the time step, to be reasonable small, the results of the difference equations are the same as the expected results of the differential equations. You can, however, take advantage of this ability to specify δt, to use different time steps for different submodels.

A common example is in the calculation of compound interest on money in a savings account. It is important when specifying that interest is to be compounded, that the period over which the compounding occurs is specified. For example, the same investment in two savings accounts, both paying compound interest at 12 per cent, will yield different amounts after one year if one account compounds monthly and the other compounds annually. In modelling these accounts, you would need to specify a different δt, the time step, for each, in order that the state variable (the amount in the account) was updated at different rates, either monthly or annually.

Another reason for having several time steps is when a model contains components that behave on different time scales. For instance a model of a grazing system might contain a lot of plants, with physiological processes that can be modeled with a time step of a day, and animals whose movements would be modeled on a time step of seconds or minutes. To model all the plants at the shorter time step would be inefficient, so the animals are handled by a separate submodel which is run with a shorter time step.

It is possible to specify up to seven time step indices. For each new time step category that you request, an extra Time step #x entry is added in the Run Control window, and that is where you specify the actual time step (e.g. 0.01) to be used for each index.

Notes

The following notes will help you use this concept:

• Note that the TIME UNIT is the same over the whole model, and that all flows are expressed per time unit. The run control also specifies how long the model should be run for, in terms of time units.

• Each submodel TIME STEP is specified in terms of a multiple of the time unit. The submodel time steps *must* be ordered from long to short, #1 must be the longest, #7 the shortest. During each time step that affects a submodel (i.e. its own and all longer ones) all the elements of the submodel are updated. Note, particularly, that since flows are expressed in time units, a compartment's value does not change each time step by the value that is entered (or calculated) for the flow, but by the same multiple of that value as the time step is of the time unit.

• To refer to the time step in the model, use the function dt().

Special cases

In addition to the seven time step indices available, there are three special cases:

• "Initialize only" denotes that the submodel should be updated only when the model is built.
• "New params only" denotes that the submodel should be updated only when the model is built or when it is reset after new values for fixed parameters have been loaded.
• "Reset only" denotes that the submodel should be updated only when the model is built or when it is reset.

In none of these cases will the submodel be updated during the simulation.

Example

For the example of compound interest given above, set the time step index for the annual submodel to #1 and for the monthly submodel to #2. In the run control, you will then need to set time step #1 = 12 and time step #2 = 1. Flows in both submodels will be expressed in the same time units, in this case, per month.

Note that this is exactly equivalent to time step #1 = 1 and time step #2 = (1/12). Then the implicit time unit is one year, and the flows will be expressed on an annual basis.

As a final point, note that it is possible to set explicitly the time unit for each flow. Enter explicit physical units such as kg/week or kg/day. If the compartment has compatible physical units, such as kg, then the appropriate conversion will be performed. If you do this, note especially that you must be consistent throughout a network of flows.

In: Contents >> Working with submodels >> Submodel properties

Satellite submodels

A satellite submodel is one that has a single role arrow that connects to it from another submodel. An example is illustrated in the Role arrow topic. Put simply, the effect of the role arrow is to allow the satellite model to behave in some ways as if it were a submodel of the base model, while still also being a submodel of the model actually containing it. Each instance of the satellite model is associated with an instance of the base model, and influences running between the two will only reference data between base model instances and their own associated satellite model instances. By default there is one satellite model instance per base model instance, but this can be made more by giving the satellite model its own dimensions, or nesting it in another submodel which has dimensions. Also satellite models can be conditional, so some base model instances have different numbers of satellites, or none at all.

Satellite submodels are not used very often, because most modelling problems are expressed more clearly by association submodels. But they are worth discussing because they are the simplest use case of the role arrow, so they are a good way of understanding its semantics, which remain the same when it is used in more complex cases. Also, some problems are best modelled in terms of satellite submodels.

Let's say that you have a multiple-instance submodel containing information on the species and volume of a set of individual trees: each instance is one tree. You would like to find the total volume of all trees belong to species 1.

This is easy to do if you have model the trees using a fixed-membership submodel (i.e. assuming that you have a fixed number of trees). You simply take influence arrows from the species and volume variables inside the submodel to a variable outside (say total), and give total the equation:

total = sum(if [species]==1 then [volume] else 0)

[species] and [volume] are both arrays with the same number of elements, and Simile's array language matches them up. If you use a population submodel to model the trees, then you do not have a problem: you can use more than one list in the arguments of a Simile function or operator, provided they always have the same length, and the result will be a list of the same length, which is fine so long as it is not assigned to the result without being summed or otherwise converted into a single value. The equatuion would be:

total = sum(if {species}==1 then {volume} else 0)

If you want to get lots of summary information about trees of one particular species, then rather than summing the results of a conditional expression like this for each one, you could make the equations simpler by creating a satellite submodel with variables for the same values that are in the base model. In the above case, it would involve creating a new submodel for the species 1 trees, using a single role arrow from the tree submodel to this satellite submodel, and entering the condition "species==1". An instance of this submodel will be created for each tree of species 1, and not for the others. If you then take the "volume" value into the submodel, then you can extract the volumes just for species 1.

In: Contents >> Working with submodels

Association submodels

Association submodels are used to contain properties of relationships between one or more other submodels. If only one submodel is involved, the relationship is between different instances of the submodel. If there are two submodels, the relationships are between the instances of the two submodels. An association submodel (which looks just like a normal submodel) is used to contain elements that are held in common between the submodel instances taking part in the association. In effect, these elements do not belong to just one or other submodel but to both. For instance, the concept of a salary requires an employer paying the salary as well as the employee receiving it.

Association submodels are often used to represent a model concisely that otherwise would require repetition. If you are familiar with object-oriented programming, you will notice that association submodels are similar in concept to association classes.

For more information:

• please see the "Introduction to the association submodel concept".

Terminology

A 'base submodel' is a submodel that takes part in an association.

A 'relation' is an association between instances of the same base model.

A 'role' is the arrow that connects a base submodel to an association.

To create an association submodel:

1. Create one or more multiple instance submodels that will be associated, each playing a role in the association. These are the base submodels.
2. Create unique identifying variables in the base submodels. The variables allow unique identification of an instance. This is easy to specify, using variables taking the value of the submodel index (or indices).
3. Create a single instance submodel which will be the association submodel itself, containing variables that specify the association.
4. Draw role arrows from the base submodels to the association submodel. The role arrows should be given meaningful names indicating the role the instances of the base submodel play in the association. Meaningful role names make specifying the equations in the association much easier.
5. Add a condition symbol in the association submodel specifying when the association holds true. The condition is an expression involving the identity variables of the base submodels.
6. Include in the association submodel all the variables that belong equally to all base submodels.
7. Draw influences between relevant variables in associated submodels and the association submodel and specify these variable's equations.

To follow this in practice:

• please see the "Worked example: water flow between soil layers".

Note that there are some advanced aspects of optimising the performance of models using associations For more information please see:

• Role arrow properties dialogue box
• One-sided relationship enumeration

In: Contents >> Working with submodels