Adding node-type elements

The node-type elements are:

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

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

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

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

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

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

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

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

In: Contents >> Working with model diagrams

Adding arrow-type elements

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

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

Alternatively,

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

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

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

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

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

Specific instructions for each type of arrow

Flow and  squirt arrow

A flow or squirt arrow must:

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

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

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

Influence arrow

An influence arrow must:

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

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

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

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

Role arrow

A role arrow must:

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

In: Contents >> Working with model diagrams

Adding submodels

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

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

Alternatively,

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

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

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

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

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

Submodel is drawn around existing model elements

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

Submodel does not enclose existing elements

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

In: Contents >> Working with model diagrams

Selecting model diagram elements

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

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

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

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

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

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

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

Duplicating elements

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

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

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

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

In: Contents >> Working with model diagrams

Moving model diagram elements around

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

The basic steps are:

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

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

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

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

Special considerations apply to the following elements:

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

In: Contents >> Working with model diagrams

Changing the label for elements on a model diagram

To re-label any element in the model diagram:

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

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

Suggestions

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

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

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

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

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

Appropriate types of label for different types of model element

Compartments

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

Flows

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

Simple submodels

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

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

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

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

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

Association submodels

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

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

Role arrow

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

In: Contents >> Working with model diagrams

Creating ghost elements

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

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

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

Alternatively, you can:

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

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

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

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

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

In: Contents >> Working with model diagrams

Rescaling symbol size in submodels

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

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

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

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

In: Contents >> Working with model diagrams

Adding background pictures

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

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

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

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

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

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

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

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

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

In: Contents >> Working with model diagrams

Preferences dialogue box

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

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

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

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

Please consult each section for further help.

In: Contents >> Working with model diagrams