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 connection points where arrows meet nodes (these can be dragged around the boundary of the node); 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

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

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

Compartment

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);
• 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

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.

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 an "Input parameter".

Rules

• A flow arrow can only be drawn into and/or out of a compartment.

• 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

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 symbol may have zero or more influence arrows pointing from it.

• A variable may not have flow arrows pointing to or from it.

In : Contents >> Model diagram elements

Influence arrow

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. This has no meaningful modelling function, but acts as a temporary placeholder to the influence arrow until it is connected to an element inside the submodel. In order to do this, drag an influence arrow from the node at the submodel boundary to the desired element inside the submodel.

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

Iteration

• 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". This is used in combination with the iteration symbol to implement many iterative methods. The property indicates how the ambiguity associated with a circular loop of influences is to be resolved.

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

In : Contents >> Model diagram elements

Submodel

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. The submodel then represents each of that number of instances. Visually, it now appears different, because it now has multiple lines on the left- 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 (again, 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.

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.

However, if you use a population submodel to model the trees, then you have a problem. A population submodel exports a list of values rather than an array: it has to do this, because the number of values can change dynamically, rather than being fixed. Currently, Simile does not have a list-processing language corresponding to the array-processing language as above. All you can do with a list is to sum it, count the number of elements in it, or find it minimum or maximum value.

The satellite submodel is a mechanism for dealing with problems like this. 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.

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 incremental compilation of a complex model

Complex models - that is, models with a large number of symbols and equations - can take a significant to build (i.e. generate the program for simulating the behaviour of the model). It can be as long as 10+ minutes for a complex model (100s of equations) on a slow computer.

Normally the build process is done with the whole model, and every time you make some change, no matter how small, it has to be done again before you can run the model. However, it is possible to specify that a submodel is built separately (in technical terms, a separate DLL is generated for it). This greatly speeds up the re-building process for any changes made to this submodel, since Simile has only to re-build the submodel, not the whole model.

In : Contents >> Model diagram elements

Initialisation

The Initialisation symbol is used to specify the initial number of individuals in a population submodel.

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.

So, assuming that you already have a population submodel in your model diagram:

1. click on the Initialisation symbol on the toolbar;
2. move the mouse to within the envelope of the population submodel;
3. click the mouse to deposit the Initialisation symbol in the submodel.

Rules

• You can have a maximum of one Initialisation symbol in any one population submodel. It does not make sense to have more than one, since Simile would then not know which one to use.

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

• Although it is possible to draw an influence arrow from the migration symbol to another element, the only use of this is with the channel_is( ) function. The value of the migration symbol is not the value entered or calculated.

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.

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.

So, assuming that you already have a population submodel in your model diagram:

1. click on the migration symbol on the toolbar;
2. move the mouse to within the envelope of the population submodel;
3. click the mouse to deposit the migration symbol in the submodel.

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.

• Although it is possible to draw an influence arrow from the migration symbol to another element, the only use of this is with the channel_is( ) function. The value of the migration symbol is not the value entered or calculated, but the fraction remaining before the next instance is created. (See "Interpretation" below for details.)

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?

Case 1: time step = 1, migration = 3

Three new instances are created every time step.

Case 2: time step = 1, migration = 0.7

During the first time step, the value for migration (0.7) is not enough to create a new instance of the population submodel. Simile then remembers the value 0.7. When it comes to the next time step, the value for migration is then added on, giving 0.7+0.7=1.4. This is sufficient to create one new instance, leaving 0.4 in the bank.

The process continues, as shown here:

1 0.0 0.7 0.7 0 0.7

2 0.7 0.7 1.4 1 0.4

3 0.4 0.7 1.1 1 0.1

4 0.1 0.7 0.8 0 0.8

5 0.8 0.7 1.5 1 0.5

6 0.5 0.7 1.2 1 0.2

7 0.2 0.7 0.9 0 0.9

8 0.9 0.7 1.6 1 0.6

9 0.6 0.7 1.3 1 0.3

10 0.3 0.7 1.0 1 0.0

Case 3: time step = 0.1, migration = 0.7

The value for migration is a migration rate, expressed in whatever your global unit of time is (typically 'year'). Therefore a value of migration of 0.7 individuals per year gives a value of 0.07 individuals in one time step (0.1 year). Exactly the same procedure as above is applied, with the migration value accumulating until a whole number of individuals can be created.

Case 4: time step = 1, migration = 3.4

The same procedure as above is applied, with 3 new instances being created in some time steps, and 4 in others.

You might well feel uncomfortable with the deterministic nature of the process. In this case, it is up to you to engineer a suitable stochastic mechanism that generates new individuals at the same average rate. In the future, Simile will include functions for sampling from appropriate frequency distributions for handling a variety of options (please contact the authors of Simile if you want to discuss this). In the meantime, and if your rate of migration is less than 1, then you can treat the value as a probability that migration will occur, and use the following expression for migration:

if rand_var(0,1)<0.7 then 1 else 0

where 0.7 is the migration rate.

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.

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.

So, assuming that you already have a population submodel in your model diagram:

1. click on the reproduction symbol on the toolbar;
2. move the mouse to within the envelope of the population submodel;
3. click the mouse to deposit the reproduction symbol in the submodel.

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.

• Although it is possible to draw an influence arrow from the reproduction symbol to another element, the only use of this is with the channel_is( ) function. The value of the reproduction symbol is not the value entered or calculated, but the fraction remaining before the next instance is created. (See "Interpretation" below for details.)

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.

The following cases illustrate how Simile interprets the information provided in the reproduction symbol. In all cases, the analysis is for ONE INDIVIDUAL in the current population: the total input of new individuals into the population is the sum of the input from each individual.

Case 1: time step = 1, reproduction = 3

Three new instances are created every time step.

Case 2: time step = 1, reproduction = 0.7

During the first time step, the value for reproduction (0.7) is not enough to create a new instance of the population submodel. Simile then remembers the value 0.7. When it comes to the next time step, the value for reproduction is then added on, giving 0.7+0.7=1.4. This is sufficient to create one new instance, leaving 0.4 in credit. The process continues, as shown here:

1 0.0 0.7 0.7 0 0.7

2 0.7 0.7 1.4 1 0.4

3 0.4 0.7 1.1 1 0.1

4 0.1 0.7 0.8 0 0.8

5 0.8 0.7 1.5 1 0.5

6 0.5 0.7 1.2 1 0.2

7 0.2 0.7 0.9 0 0.9

8 0.9 0.7 1.6 1 0.6

9 0.6 0.7 1.3 1 0.3

10 0.3 0.7 1.0 1 0.0

Case 3: time step = 0.1, reproduction = 0.7

The value for reproduction is a reproduction rate, expressed in whatever your global unit of time is (typically "year"). Therefore a value of reproduction of 0.7 individuals per year gives a value of 0.07 individuals in one time step (0.1 year). Exactly the same procedure as above is applied, with the reproduction value accumulating until a whole number of individuals can be created.

Case 4: time step = 1, reproduction = 3.4

The same procedure as above is applied, with three new instances being created in some time steps, and four in others.

You might well feel uncomfortable with the deterministic nature of the process. In this case, it is up to you to engineer a suitable stochastic mechanism that generates new individuals at the same average rate. In the future, Simile will include functions for sampling from appropriate frequency distributions for handling a variety of options (please contact the authors of Simile if you want to discuss this). In the meantime, and if your rate of reproduction is less than 1, then you can treat the value as a probability that reproduction will occur, and use the following expression for reproduction:

if rand_var(0,1)<0.7 then 1 else 0

where 0.7 is the reproduction rate.

This may be a pretty reasonable way of representing things, if it is the case that some individuals produce 1 offspring, and others produce none, with a probability of 0.7 and 0.3 respectively. (Biologically, it is possible that some individuals may produce 2 or more offspring, with the average being 0.7. In that case, the above method is only a rough approximation, and you should aim to develop a solution based on the relative probability of different numbers of offspring.)

In : Contents >> Model diagram elements

Extermination

The mortality symbol is used to specify the conditions under which one instance of a population submodel is destroyed.

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.

So, assuming that you already have a population submodel in your model diagram:

1. click on the mortality symbol on the toolbar;
2. move the mouse to within the envelope of the population submodel;
3. click the mouse to deposit the mortality symbol in the submodel.

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.

In : Contents >> Model diagram elements

Role arrow

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. 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 - two submodels
• two role arrows - one submodel

How to add a role arrow

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. Therefore, these two submodels must already exist in your model diagram.

1. click on the role arrow symbol on the toolbar;
2. move the mouse to inside the submodel that has a role in an association;
3. drag the mouse to inside the submodel that represents the association itself;
4. release the mouse button.

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.

So, assuming that you already have the submodel that you wish to make conditional in your model diagram:

1. click on the Condition symbol on the toolbar;
2. move the mouse to within the envelope of the multiple-instance submodel;
3. click the mouse to deposit the Condition symbol in the submodel.

Rules

• A condition element only has use within a submodel (since it specifies which potential instances exist).

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

• 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

1. Click on the Iteration symbol on the toolbar.
2. Click the mouse to deposit the Iteration symbol.

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

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 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. 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. The elements will all be selected when the drag is released. If any part of an element (excluding the caption) is included in the area, it will be included in 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.

Adding node-type elements

The node-type elements are the variable and the compartment, as well as the elements used in population submodels. 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. 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.

Note that it is not possible to add a node-type element to an area of your diagram that is already occupied. No error message appears, so if this happens, simply click somewhere else where there is sufficient space, or move existing elements around to make sufficient space.

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.
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 node where you want the arrow to start.
3. Click on the node where you want the arrow to end.
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.

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.
3. Repeat (2) if you want to add more submodels.

Note that the submodel you make may or may not enclose existing model elements. When making a submodel, you can either make it to enclose some exi