Compartment

How to add a Compartment symbol

See Adding node-type elements. Note that you can add a compartment on top of a cloud, in which case the cloud becomes a 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. 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 >> Graphical Modelling >> System Dynamics

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 >> Graphical Modelling >> System Dynamics

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 >> Graphical Modelling >> ​System Dynamics

 Immigration

The Immigration 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 Immigration symbol determines the total number of new instances that are created. Note that the process adding new individuals need not be an actual immigration from another place -- it could be anything that causes new members of a population, unrelated to existing individuals, to appear throughout a run.

Immigration belongs to the group of symbols known as channels. The symbol's icon represents a bird on the wing.

How to add an Immigration symbol

The immigration symbol only has meaning in the context of a population submodel. Therefore, it makes sense to construct a population submodel first, then add the immigration symbol to it. This is not strictly necessary: you can add the immigration 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 immigration 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 immigration 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 immigration symbol to another element. The usual use of this is with the channel_is( ) function. The value of the immigration symbol is the value of its equation.

Interpretation

The immigration 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 immigration 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 immigration 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 immigration 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.

Immigration events

An immigration symbol can be either continuous or discrete event valued. If any influences from events or squirts terminate on the immigration symbol, it is discrete event valued. In this case it will be evaluated in the same way as an event or squirt. When the event occurs, the value will be added to the latency (fraction remaining after previous additions) and new individuals added to the popualtion immediately if the result is 1 or greater.

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

If using discrete event valued immigration channels, all you need to do is make sure the event magnitude is integer valued, as the time step size does not affect the result of an addition event.

In: Contents >> Graphical Modelling >> Object/agent based

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 is unusual to have more than one method for reproduction (though some organisms reproduce asexually and sexually at different stages of their life cycle), but it is perfectly legal as far as Simile is concerned.

• It is possible to draw an influence arrow from the reproduction symbol to another element. The usual use of this is with the channel_is( ) function. The value of the reproduction 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 would severely restrict the modelling you could do: in particular, it would rule 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, starting with a random fraction, until it has sufficient to make one new individual.

Like migration channels, reproduction channels can be discrete event valued. If the event that triggers a reproduction event is outside the population submodel, then when it occurs, all individuals in the population will reproduce, subject in each case to the equation of the reproduction channel having a positive value. Alternatively the triggering event can be inside the population submodel, in which case only the individuals in which the event occurs will reproduce.

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 >> Graphical Modelling >> Object/agent based

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

A removal channel can also be discrete-event valued, if it has an influence from an event or squirt. In this case, when the triggering event happens, individuals may be removed immediately. The magnitude of the removal event is the probability, as a fraction of 1, that the individual will be removed at that point. If the value is 1 or greater, removal is certain. In order to avoid any random behaviour in a model containing removal channels, they should only ever have values of 0 or 1. Removal symbols, whether discrete or continuous valued, can have boolean units ("true" or "false") which have the same effect as 1 and 0. 

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.
• A condition may have influences to it from anywhere in the model. It cannot have influences from it, since either its value is "true" or its submodel instance does not exist.

• 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. The condition's equation can use values from base instances in particular roles in order to set the association to exist only if the base instances' values match in a certain way.

In: Contents >> Graphical Modelling >> Object/agent based

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. On each time step of the model, after the compartment values have been adjusted, the values of all variables are calculated as normal. Then if the alarm symbol's equation evaluates to "false", the variables in its submodel are calculated again, and the test repeated, until it evaluates to "true" at which point the loop exits. See iterative submodel for a full description with examples, but a simple case of evaluation by successive approximation could be implemented as follows.

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. This can also be set if the value of the alarm is "true" since this is how it is left at the end of the previous time step. If the number of iterations so far is one or more, or if the value of the alarm is "false", 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.

Note that if the value of the alarm symbol is used directly to decide if the initial guess should be used, then its influence should also be dashed, as the value of the alarm symbol is set by a test on the result. This is not necessary if using the "iterations()" function, which does not check for circularity involving its argument.

• The expression in the equation dialogue box for an 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".