The iThink/STELLA window

The iThink and STELLA window is organized into the following areas:

Tabs on the left side of the window give you access to the different layers of the
model: Interface, Map, Model, and Equation. Each layer provides a different way of
designing and presenting a model. Click a tab to navigate to the layer you want to
work with.

Panels on the right side of the window allow you to specify and edit properties for
the selected model building block, including equations, documentation, and other
properties. Click a tab at the bottom of the panels to navigate to the panel you want
to use. Panels are available when you are viewing the Map and Model layers only.

The menu bar and toolbar along the top of the window give you access to many of
the commands you'll need when building and modifying a model.

The Run controller at the bottom-left of the window gives you quick access to many
of the commands on the Run menu. In addition, it gives you a visual indication of the
progress of a simulation.

The
and
buttons (at the bottom of the window, just above the Run controller)
allow you to easily adjust the magnification of the view by zooming in or out of the
model.

The following picture shows the Model layer, with the panels open, and the Equation
panel revealed.

Working in the iThink/STELLA window

iThink and STELLA provide the same interface tools and options you're used to using with
other Windows and Macintosh applications, including clicking, double-clicking, dragging, and
right-clicking.

Clicking Use clicking to select an item in any layer of a model. To select most
items in a model, click the item once. When the item is selected, it becomes
highlighted. To select a button, click its border. When a button is selected, selection
handles appear around the button.
You also use clicking to indicate where to add a new element on the Interface, Map,
or Model layers; to select commands from the menus; to select a toolbar button; and

to move from one layer to another by clicking a navigation tab on the left side of the
window.

Double-clicking Use double-clicking as a shortcut to view or edit the properties of

most items in a model. For example, to view the details of a table, double-click the
table pad icon in the model. To define the table's properties, double-click the table
pad's page to view the Define Table dialog box.
Single- or double-clicking a button "pushes" the button so that it performs its
associated action.

Dragging Use dragging to select one or more items by holding down the mouse
button and then dragging to draw a rectangle around the items you want to select.
When you release the mouse button, the items within the rectangle are selected.
You can also use dragging to move selected items to a new location on the layer and
to change the size of an item by dragging a corner of the item to stretch it to a new
size.

Right-clicking Right-click any element to see a shortcut menu of commands that

apply to the element. When the shortcut menu appears, choose the command you
want to use. For example, to view or change the properties of a button object, rightclick the button and then choose Open. The Button dialog box appears

Closing models
Use the following procedure to close the currently open model.

To close a model
1

From the File menu, choose Close, or press CTRL+W (Windows) or Command+W
(Mac).
A message appears that asks you if you want to save changes to the currently open
model.

Select whether or not you want to save changes to the currently open model.
The model closes.

Creating new model files

Use the following procedure to create a new, blank model file.
Tip: You can create a new model file by copying an existing model file with the Save
As command. For more information, see Saving models.

To create a new model file

1

From the File menu, choose New, or press CTRL+N (Windows) or Command+N
(Mac).
If you already have a model open in the iThink/STELLA window, a message appears
that asks you if you want to save changes to the currently open model.

Select whether or not you want to save changes to the currently open window.
A new, blank diagram opens in the iThink/STELLA window.

Opening models
Use the following procedure to open an existing model.
Note: Opening an iThink or STELLA model that was created in a previous version will
automatically translate the model so that it is compatible with version 10. In some cases,
the translation requires additional manual updates to the model. For more information,
see www.iseesystems.com/translation.

To open a model
1

From the File menu, choose Open, or press CTRL+O (Windows) or Command+O
(Mac).
Note: If you are opening a model created with a version of iThink or STELLA prior to
Version 10, a message appears that tells you the model will be converted to Version
10 format (.ITMX or .STMX). Click OK to convert the model.
If you already have a model open in the iThink/STELLA window, a message appears
that asks you if you want to save changes to the currently open model.

Select whether or not you want to save changes to the currently open model.
The Open dialog box opens.

Navigate to and select the model file that you want to open.

Click Open.
The model you selected opens in the iThink/STELLA window.

Saving models
When you save a model, the model's information is saved in two separate files: a model file
(.ITMX or .STMX) and a database file (.ISDB).

The model file (.ITMX or .STMX) contains the information that defines the model,
such as its entities, equations, interface objects, documentation, and page layout
information.

The database file (.ISDB) contains the simulation run data for the model, if any.

Note: If you share your model by sending the model file to someone else and you want to
include the model's simulation run data, you also need to send the database (.ISDB) file.
For more information about the files you need to include when you share your models,
see Distributing models to users.

To save a model
1

From the File menu, choose Save.

If you have already saved this model before, iThink/STELLA saves the changes to
your model in the same model and database files.
If you have never saved this model before, the Save File As dialog box opens.
If you are saving a model that was converted from an older version
of iThink/STELLA when you opened it, the Save File As dialog box opens.

Specify the location and name for the model file.

Click Save.
The model file is saved with the name and to the location you specified.
If there are saved runs for the model, a database file is also saved to the location
you specified, with the same name as the model file.
Note: If you are saving a model created with a version of iThink or STELLA that is
older than Version 10, the model will be saved with the new .ITMX or
.STMX extension. You cannot save a model as an earlier version.

To make a copy of a model

Use the Save As command to save a copy of the currently open model as a new model.

From the File menu, choose Save As.

The Save File As dialog box opens.

Specify the location and name for the new model file.

Click Save.
The new model file is saved with the name and to the location you specified.
If there are saved runs for the model, a database file is also saved to the location
you specified, with the same name as the model file.
Note: If you are saving a model created with a version of iThink or STELLA that is
older than Version 10, the model will be saved with the new .ITMX or .STMX
extension. You cannot save a model as an earlier version.

Working in the iThink/STELLA window

iThink and STELLA provide the same interface tools and options you're used to using with
other Windows and Macintosh applications, including clicking, double-clicking, dragging, and
right-clicking.

Clicking Use clicking to select an item in any layer of a model. To select most
items in a model, click the item once. When the item is selected, it becomes
highlighted. To select a button, click its border. When a button is selected, selection
handles appear around the button.
You also use clicking to indicate where to add a new element on the Interface, Map,
or Model layers; to select commands from the menus; to select a toolbar button; and
to move from one layer to another by clicking a navigation tab on the left side of the
window.

Double-clicking Use double-clicking as a shortcut to view or edit the properties of

most items in a model. For example, to view the details of a table, double-click the
table pad icon in the model. To define the table's properties, double-click the table
pad's page to view the Define Table dialog box.
Single- or double-clicking a button "pushes" the button so that it performs its
associated action.

Dragging Use dragging to select one or more items by holding down the mouse
button and then dragging to draw a rectangle around the items you want to select.
When you release the mouse button, the items within the rectangle are selected.
You can also use dragging to move selected items to a new location on the layer and
to change the size of an item by dragging a corner of the item to stretch it to a new
size.

Right-clicking Right-click any element to see a shortcut menu of commands that

apply to the element. When the shortcut menu appears, choose the command you
want to use. For example, to view or change the properties of a button object, right-

click the button and then choose Open. The Button dialog box appears

You can close the panels at any time to see the full diagram. If you prefer, you can undock
the panels. When you undock the panels, they become a floating window that you
can resize and place anywhere on your screen.
The following procedures describe how to work with the panels by

opening and closing them

undocking and docking them

pinning and unpinning them

resizing them when they are undocked

selecting them

viewing entity properties on them

editing entity properties on them

applying edits made on them

undoing edits made on them

To open or close the panels

When you first open a model and navigate to the Map or Model layer, the panels will
automatically be open. On the Model layer, the panels open to the Equation panel. On the
Map layer, the panels open to the Documentation panel (the only panel available on the Map
layer).
If you close the panels, they will remain closed on the layer on which you closed them until
you open them again.

To close the panels, click the

panels).

To open the panels, use one of the following methods:

button on the panel bar (on the left side of the

Click the button on the panel bar (on the right side of
the iThink/STELLA window).

or
Select the building block's icon, and then choose Open Selection from the Model
menu.
or
Right-click the building block's icon, and then choose Open from the menu that
appears.
or
Double-click the building block's icon.

To undock and dock the panels

To undock the panels, click the

To dock the panels, click the

button in the upper-right corner of the panels.

button in the upper-right corner of the panels.

To pin and unpin the panels

By default the panel will stay open unless you explicitly close it. You can unpin the panel to
have it close whenever you click off a model entity (on a blank part of the model) or run the
model.

To unpin the panels, click the

To pin the panels, click the

button in the upper-right corner of the panels.

button in the upper-right corner of the panels.

Note The orientation of the button indicates if the panel is pinned or unpinned.
is pinned and

means it

means it is unpinned.

To resize undocked panels

Click and drag the resize area

in the bottom-right corner of the undocked panels
until the panels are the size you want.

To select a specific panel

Click the appropriate tab at the bottom of the panels to select and view that panel:

Equation panel

Graphical Function panel

Array panel

Scales and Ranges panel

Messages panel

Module Properties panel

Documentation panel

To view entity properties on a panel

1

Click the entity on the Map or Model layer to select it (or use drag-select to select it).
The panels are enabled and the last viewed panel is displayed if the panel is valid for
the selected entity; otherwise, the appropriate default panel for the entity is
displayed:
o

On the Model layer, the default panel is the Equation panel.

On the Map layer, the default panel is the Documentation panel.

If the selected entity has been defined as a graphical function, the default
panel is the Graphical Function panel.

Note: If you closed the panels with the

panels.
1

button, click the

button to open the

Click the tab for the panel that contains the properties you want to view. For
information about the options on a specific panel, see the documentation for that
panel.

To edit building block properties on a panel

1

On the model diagram, select the building block whose properties you want to edit.

Select the panel for the properties you want to view or edit. For information about
the options on a specific panel, see the documentation for that panel.

Tip: to automatically select the default field on the currently displayed panel, doubleclick the building block.
1

Use the options on the panels to make the edit you want.

When you are finished making changes, apply your edits.

For more information about building blocks, see Working with building blocks.

To apply edits made on panels

In general, changes you make on the panels are applied to the selected entity as soon as
you make the change.
Use the following procedure to apply all changes made on all panels for the entity and to
have the software check for errors in the entity's equation and other properties.

Click

in the bottom-right corner of the panels.

The software applies any changes that are not yet applied and checks for errors.

To undo or revert edits made on panels

To revert all changes made to the entity's properties since the last time you applied
changes, click

To undo only the last change you made, select Undo from the Edit menu (or use
CTRL+Z [Windows] or Command-Z [Mac]).

The model building process

The following steps provide a high-level view of the model-building process, from
determining the model's goals to distributing the finished model. If you are new to model
building, use this procedure as a guide for organizing your thoughts and getting started with
model building.
Tip: For detailed information on most of these steps, refer to the "Guidelines for the "Writing
Process" chapter in An Introduction to Systems Thinking.
1

Define the purpose of your model, the problem you are trying to solve, or
the story you are trying to tell.

Write your purpose statement down on paper and check back during the model
building process to make sure that your model addresses your initial purpose.
1

Determine the model boundary.

Decide what needs to be in the model, what can or should be left out, and how
detailed your model needs to be. Look back to your model goals in step 1 and make
sure that your plan includes the entities and features that support your goals.

Map the model.

Identify the key entities in your model. You can think of this as determining the
"main chain," a sequence of stocks connected by flows that provides the "backbone"
of the model. Another way to start is to identify the stock you consider to be the
closest to the heart of the issue you're modeling, and then add an inflow and an
outflow to that stock. You can then build on to those flows and stocks. In the end,
you want to account for all the stocks, flows, and converters required to model your
original goals, and then make sure all feedback loops are closed.

Build the model.

On the Map layer, place the key entities in your model. On the Model layer, assign
equations and numerical values to the entities.

Test the model.

Run the model and look for errors, anomalous values, strange or implausible
behavior, etc. Fix problems you identify, then re-run the model. Continue testing and
fixing until you are satisfied that your model is running correctly.

Create an interface.
If you will be sharing your model with others, add objects on the Interface layer to
help explain your model and make it easy to interact with. You can add text to
describe the model's goals or to provide user instructions, and you can add
interactive objects such as buttons or other ways that users can change the model's
input values. You can also add graphs and tables that make it easier to read and
understand the results of the model's run.

Share the model.

Use tools such as isee RunTime, isee Player, and isee NetSim to publish and
share your model with other

Overview: Building models

Once you've spelled out the goals and boundary of your model and have developed an initial
map of the model (as described in The model building process), you need to add the
information that will transform the model in your head into a working simulation. This
process is called building the model, and it requires you to place the key entities in your
model on the diagram, and then assign equations and numerical values to those entities.
The following procedure is a high-level guide to the steps involved in building a model. Use
the links in each step for more information about the step.

Steps for building a model

1

Place the stocks and flows for the "main chains" in your model on the Map
layer.
When you were first planning your model, you identified the stocks and flows that
were central to the system or process you're trying to convey. Now, you want to lay
those out on the diagram and connect them to each other to see how they connect
and may interact.
Note: Be aware of unit consistency (each flow into or out of a stock must use the
same units of measure as the stock itself, except for "per time"; all stocks in a main
chain must use the same units of measure) and conservation laws.

Add connectors.
Connectors function as conjunctions. Use them to join stocks and flows together, and
flows together with other flows, to transmit information and actions from one entity
to another.

Add converters.
Converters have two main roles: they function as adverbs by modifying flows (for
example, indicating how quickly or slowly a flow is moving); converters also convert
units of measure from one entity so that they are compatible with another,
connected entity.

Define graphical functions.

Graphical functions are graphs that show the relationships between entities in a
model. When one model entity changes, the other will change depending on the
assumptions or perception of what happens in reality.

Define entities by adding equations and values.

If you haven't already done so, specify the equations and/or initial values for the
stocks, flows, and converters in the model. When defining constants, use simple
numbers for testing before you introduce more realistic numbers.
1

Assign and check units.

If you did not assign units to the stocks and converters in your model already, go
back and do so. Then, check the model's units to ensure that the left- and right-hand
sides of equations have consistent units, and that conserved flow chains have
consistent units.

Identify and highlight feedback loops in your model.

Make the model's feedback loops clear by assigning polarity to connectors and flows
in your model. Assigning positive ("+/s") or negative ("-/o") polarity lets you visually
indicate the cause-and-effect relationship between model entities. You can also mark
loops as either balancing ("-" or "B") or reinforcing ("+" or "R") by placing a text box
in the loop and then using the Format for CLD button in the Text Box dialog box.

Add objects to fill out detail.

On the Model layer, add buttons, graphs, tables, text, images, or other objects to
help you use your model and easily understand its output. Note that this differs from
using objects to create an interface for you model because these objects are directly
on the Model layer and are accessible only to those who are looking at the model on
the Model layer.

When you have finished building a first draft of your model, test it by running the model and
looking for errors, implausible results, and other problems.

Assigning polarity to building blocks

Assigning polarity to flows and connectors in your model allows you to visually indicate the
cause-and-effect relationship between model entities. Assigning polarity can also make it
easier to tell a story about the feedback loops in your model.

A positive polarity (+/s) means that, when the cause increases, the effect
increases; the relationship between the entities goes in the same (or "s") direction.

A negative polarity (-/o) means that, when the cause increases, the effect
decreases; the relationship between entities goes in the opposite (or "o") direction.

For example, in the following model, when being born increases, its effect is to also increase
Population (note the "+" polarity sign at the right end of the being born flow). This is a
positive polarity. Conversely, as dying increases, the effect is to decrease Population, a
negative ("-") polarity.

An odd number of -/o links around a loop signifies a Balancing loop. An even number of -/o
links signifies a Reinforcing loop.
For connectors, you can choose the polarity you want to assign (positive or negative), based
on the interaction between the two entities.
For flows, the polarity is determined by the flow's association to the attached stocks: an
inflow always has a positive (+/s) influence on a stock and an outflow always has a negative
(-/o) influence on a stock. Although you can't select their polarity, you can choose whether
or not to display their polarity in the model.
Note: The default polarity symbols that are displayed on the diagram are - and +. If you
prefer to use the letter symbols (o and s) instead, select the Use Lettered Polarity check
box in theModel Preferences dialog box.

To assign polarity to connectors

Right-click the connector's handle, choose Polarity from the menu that appears, and
then choose +/s, -/o, or None.

To display polarity for flows

Right-click the circle portion of the flow icon, choose Polarity from the menu that
appears, and then choose +/s, -/o, or None.

Creating new model files

Use the following procedure to create a new, blank model file.
Tip: You can create a new model file by copying an existing model file with the Save
As command. For more information, see Saving models.

To create a new model file

1

From the File menu, choose New, or press CTRL+N (Windows) or Command+N
(Mac).
If you already have a model open in the iThink/STELLA window, a message appears
that asks you if you want to save changes to the currently open model.

Select whether or not you want to save changes to the currently open window.
A new, blank diagram opens in the iThink/STELLA window.

You can now start building the model and can save the new model

Defining global scales and ranges

Although you can define scales and ranges for an entity that is used in a particular input or
output device (such as a graphs, tables, or sliders), if the entity is used in multiple input
and output devices in the model, you may want to document or define this information in
one place.
Tip: Once you define global scale and range information for an entity, you can override the
global value for a specific instance (for example, in a single graph) by editing scale or range
values in the dialog box for the specific input or output device.

To define global scales and ranges for an entity

1

In the model, select the entity for which you want to define global scales and ranges.

At the bottom of the panels, click the

Use the options on the Scales and Ranges panel to define global scale and range
values for the selected entity.

Click

tab to view the Scales and Ranges panel.

below the panel to apply your changes.

Defining graphical functions

A graphical function is a sketch of a relationship between an input (which itself can be an
algebraic relationship) and an output.
You can choose to define the graphical function's input by specifying an equation, or you can
use the default equation (Time).

For example, you may have a time series of data (sales per month, or average temperature
per month). In these examples, the value of the graphical function is dependent on time. In
other cases, you might have a graphical function where the value is dependent on other
entities. For example, the death rate for an animal population is dependent on the
availability of food, the productivity of a worker is dependent on the number of hours
worked, etc.
You can define a graphical function for a flow or a converter.

To define a graphical function

1

In the model, select the flow or converter for which you want to define a graphical
function.

On the Equation panel, define the graphical function's input by entering an equation
in the Equation box. To use the default equation (TIME), leave the Equation box
blank.

On the Graphical Function panel, select the Graphical check box.

On the Graph tab, use the two boxes beneath the graphical function grid to specify
the minimum and maximum values for the X-axis.

Use the two boxes to the left of the graphical function grid to specify the minimum
and maximum values for the Y-axis.

In the Data Points box, specify the number of data points.

Use one (or a combination) of the following procedures to define the values for the
data points:
o

On the Graph tab, click and drag to draw a curve that represents the function.
As you draw the curve, the software determines the values associated with
each data point in the curve.

On the Points tab, use the table to specify the value for each data point in the
function.
Notes: To specify values for the X-axis values (in the first column), first
click

above the column to unlock the column, then type the values.

You can paste values that you've copied from another source into either
column. For more information, see Importing and exporting data with copy
and paste.

At the bottom of the Graphical Function panel, click the appropriate picture to select
the type of graphical function you want to use: Continuous, Continuous
extrapolation, or Step. For more information about these options, see Graphical
Function panel.

When you are finished defining the graphical function, click

corner of the panels.

in the bottom-right

To define a separate graphical function for each element

When you define a graphical function for an arrayed flow or converter and you clear
the Apply To All check box, you need to specify a separate graphical function for each
combination of dimensions and elements in the array.
For example, if the array has two dimensions, and one dimension has three elements and
the other has four elements, you need to specify 12 separate graphical functions. Similarly,
if the array has three dimensions, and one dimension has two elements, one has three
elements, and one has four elements, you need to specify 36 separate graphical functions.
1

Select the arrayed flow or converter for which you want to define separate graphical
functions.

Clear the Apply To All check box on the Graphical Function panel.
A table appears at the bottom of the Graphical Function panel so that you can define
the graphical functions for up to two dimensions at a time.
The row of boxes above the table indicates the combination of elements and
dimensions you are currently editing in the table.
In the following example, the table allows you to define the graphical functions for
the "Department" and "Employee Type" elements for the "Boston" dimension.

To define a graphical function for any cell in the table, click the cell, then use the
options at the top of the Graphical Function panel to define the graphical function for
the cell (see steps 4-8, in the previous procedure).

When you have finished defining the graphical functions for the currently displayed
combination of elements and dimensions, click the
combination of elements and dimensions.

button to display the next

Tip: You can move backwards through the displayed element/dimension

combinations by clicking the
1

button.

Repeat steps 3-4 until you have defined graphical functions for each
element/dimension combination.
Tip: You can define a graphical function for a specific element/dimension combination
by selecting the elements you want in the boxes above the table. The table adjusts
to display the appropriate cells in which to define the graphical function for the
selected elements.

To delete a graphical function

1

In the model, select the converter or flow for which you want to delete the
associated graph.

On the Graphical Function panel, clear the Graphical check box.

Defining messages for building blocks

The message posting feature allows you to have messages appear during a model
simulation whenever a building block's value meets criteria that you define. For example,
you can specify that a text message appears when a stock's value exceeds the value you
define.
You can define multiple messages for a single entity to provide ongoing information to your
users as the simulation progresses and the entity's value changes.
By using messages in your model, you can provide model users with information about
model output while the simulation progresses. In addition, messages give you a way to
coach model users toward a deeper understanding of model structure and behavior.
When defining messages, you can specify that the software displays text, pictures, movies,
or sounds at the specified thresholds. You can also use message posting to navigate users
to a specific location in the model (for example, a sequence of coaching screens).

Note: During the simulation run, any entities that have messages defined for them will post
their messages when their threshold criteria have been met. All visible messages (text,
pictures, and movies) appear in a message window, which floats above the model's surface.
If you assign a sound only to the message, the model will pause and play the sound, but no
visible message box appears.
To define a message, you first need to create one or more message stakes for an entity. A
message stake defines the criteria for when the message should appear: the value threshold
that triggers the message, and whether the entity's value must be greater or less than the
value threshold.
For example, you might create a message stake for an entity that says that a message
should appear when the entity's value drops below a value threshold of 50. You could also
create a second message stake for the entity that appears when the entity's value rises
above a value threshold of 100. Further, you can define multiple messages for each
message stake, so that one message appears the first time the entity's value crosses a
threshold, a second message appears when the entity's value crosses the same threshold,
and so on.
After you create and define the criteria that triggers a message, you specify the type and
content of the message that should appear (for example, the exact text, picture, sound, etc.
to be displayed).
Tip: You can suppress all message posting for a model by selecting the Disable
Posters check box in the Model Preferences dialog box.

To define a message for a building block

1

On the model layer, select the building block (stock, flow, or converter) for which you
want to define a message.

Select the Messages panel.

At the top of the panel, click in the message stake box to add a message threshold
stake.

Use the options beneath the message stake box to define a minimum and maximum
value range and the criteria for when the message should be posted (for example,
"Post the message when the entity's value becomes > 1000."). For detailed
descriptions of these options, see Messages panel.

With the message stake still selected, use the options under "Message Properties"
select the type message you want to appear: Text Message or Media Message.
Note: If you selected > or < in step 4, the message stake has a double-sided arrow
head (
). Each side can have a different set of messages. Click a side to highlight
it, then define its message type and content.

Use the rest of the options under "Message Properties" to define the content of the
message (text, image, movie, sound, and/or navigation). For detailed descriptions of
these options, seeMessages panel.

To define additional messages for the same message stake (for example, to have a
different message appear the second time the message threshold is met), click the
"Message 1" box and then select Add New. Use the options in the "Message
Properties" section to define the second message. Repeat this step to define more
messages for the message stake, as needed.

Use the options under "Frequency" to specify how often per simulation run the
message should appear.

When you are finished defining the message stake, click

corner of the panels

To create a new message stake for the selected entity, repeat steps 3-9.

To define messages for a different entity, select the entity in the model diagram, then
repeat steps 2-10.

in the bottom-right

To edit a message
You can edit the definition of any message you have already defined.
1

On the model layer, select the building block (stock, flow, or converter) whose
message you want to edit.

Select the Messages panel.

In the message stake box, select the message stake for the message that you want
to edit. If the message stake has a double-sided arrow head (
for which you want to edit messages.

), select the side

Use the options on the rest of the panel to edit the message. For detailed
descriptions of these options, see Messages panel.

When you are finished editing the message, click

the panels.

in the bottom-right corner of

To delete a message
You can delete a message stake (and all its associated messages), one or more messages
defined for a single message stake, or all messages defined for an entity.

To delete a message stake and all its associated messages, select the stake in the
message stake box, then click the Delete button below the message stake box.

To delete one or more messages defined for a message stake, select the message
stake in the message stake box, select the message that you want to delete in the
box at the bottom of the "Message Properties" section, and then click

To delete all messages for the selected entity, click the Delete All Messages button
at the bottom of the Messages panel.

Overview: Arrays
In many modeling efforts, you may find that you need to replicate a model structure
multiple times. For example, a demographic model might treat the aging of a population and
be replicated for multiple ethnic groups in multiple areas. Conceptually, the model is very
straightforward; visually, however, the structure takes up a lot of diagram space and can
look confusing. Similarly, you might model a supply chain in which a supplier ships out of a
single inventory to multiple customers. Conceptually, this structure is very straightforward.
Diagrammatically, it can be appear quite complex. In a marketing model, you might
repeatedly use a simple structure to keep track of customer affinity for several different
product lines. In an ecological model, you might repeatedly use a simple structure to
represent the different serial stages associated with plant succession.
In each of these cases, copy and paste is the most straightforward way to represent the
multiple parallel model structures involved. Unfortunately, the associated visual complexity
of the resulting model diagram can become hard to manage, both for the model builder and
the model user.
Arrays provide a simple yet powerful mechanism for managing this visual complexity. By
"encapsulating" parallel model structures, arrays can help you to present the essence of a
situation in a simple diagram. Beneath the scenes, of course, arrays retain the richness of
the disaggregated structure.
The following example shows how arrays can help you simplify a model diagram:

Using arrays in a model is straightforward. The process consists of the following three steps:
1

Define one or more dimensions and elements for the array.

Think of a dimension as a category. Each dimension contains a set of set of elements
within that category. For example, if you create a dimension named "City", it might
contain the elements "London", "Sarajevo", and "Tokyo." A dimension named
"Mammal" might contain the elements "lion", "tiger", and "bear."
You define dimensions in the Array Editor dialog box. For more information about
creating dimensions and elements, see Working with array dimensions and elements.

Transform model entities into arrayed entities.

After you have defined one or more dimensions, you can transform a non-arrayed
entity into an arrayed entity. To do this, select the entity on the model diagram, and
then select theArrayed check box on the Array panel. For more information,
see Creating arrayed entities.
Tip: You don't need to worry about transforming flows into arrayed flows; whenever
you transform a stock into an arrayed stock, any attached flows are automatically
transformed into arrayed entities as well.

Define the equation logic for arrayed entities.

For each arrayed entity, you need to define the initial value/equation for each
element within the array. You can choose to apply a single value/equation to all
elements in an array, or you can provide unique values/equations for each element.
For more information, see Creating arrayed entities.

Overview: Building models

Once you've spelled out the goals and boundary of your model and have developed an initial
map of the model (as described in The model building process), you need to add the
information that will transform the model in your head into a working simulation. This
process is called building the model, and it requires you to place the key entities in your
model on the diagram, and then assign equations and numerical values to those entities.
The following procedure is a high-level guide to the steps involved in building a model. Use
the links in each step for more information about the step.

Steps for building a model

1

Place the stocks and flows for the "main chains" in your model on the Map
layer.
When you were first planning your model, you identified the stocks and flows that
were central to the system or process you're trying to convey. Now, you want to lay
those out on the diagram and connect them to each other to see how they connect
and may interact.
Note: Be aware of unit consistency (each flow into or out of a stock must use the
same units of measure as the stock itself, except for "per time"; all stocks in a main
chain must use the same units of measure) and conservation laws.

Add connectors.
Connectors function as conjunctions. Use them to join stocks and flows together, and
flows together with other flows, to transmit information and actions from one entity
to another.

Add converters.
Converters have two main roles: they function as adverbs by modifying flows (for
example, indicating how quickly or slowly a flow is moving); converters also convert
units of measure from one entity so that they are compatible with another,
connected entity.

Define graphical functions.

Graphical functions are graphs that show the relationships between entities in a
model. When one model entity changes, the other will change depending on the
assumptions or perception of what happens in reality.
1

Define entities by adding equations and values.

If you haven't already done so, specify the equations and/or initial values for the
stocks, flows, and converters in the model. When defining constants, use simple
numbers for testing before you introduce more realistic numbers.

Assign and check units.

If you did not assign units to the stocks and converters in your model already, go
back and do so. Then, check the model's units to ensure that the left- and right-hand
sides of equations have consistent units, and that conserved flow chains have
consistent units.

Identify and highlight feedback loops in your model.

Make the model's feedback loops clear by assigning polarity to connectors and flows
in your model. Assigning positive ("+/s") or negative ("-/o") polarity lets you visually
indicate the cause-and-effect relationship between model entities. You can also mark
loops as either balancing ("-" or "B") or reinforcing ("+" or "R") by placing a text box
in the loop and then using the Format for CLD button in the Text Box dialog box.

Add objects to fill out detail.

On the Model layer, add buttons, graphs, tables, text, images, or other objects to
help you use your model and easily understand its output. Note that this differs from
using objects to create an interface for you model because these objects are directly
on the Model layer and are accessible only to those who are looking at the model on
the Model layer.

When you have finished building a first draft of your model, test it by running the model and
looking for errors, implausible results, and other problems.

Overview: Modules
Modules are self-contained models that you can connect to other models. Modules allow you
to break a single model into well-defined "chunks". Each module within a model is a
cohesive model on its own, which you can run separately or within the larger model.
By using modules, you can:

Build small, self-contained portions of a model, one-at-a-time.

Test a single portion of a large model.

Represent a hierarchical system in a model, by making each level of the hierarchy

into a separate module, with each module linked to one or more levels above it

Work with teams to build a complex model by having each team member build
separate modules that are later linked together.

Reuse portions of a model in as many models as you want.

Create very large models (models that may have previously exceeded size limits).

Incorporate locked models into other models.

You can create as many modules as you need, and you can incorporate as many modules as
you want into a single model. This allows you to create very large or complex models that
are broken down into cohesive, self-contained pieces.
Note: When you import or export data from a model that contains modules, all module data
in the model are also imported or exported. For more information, see Importing and
exporting module entities.

Understanding module concepts

Understanding module concepts
To understand how to use modules to build a hierarchy, you need to understand the basic
concepts of working with modules:
Module A module is a self-contained model that specifies the inputs it needs to run and
the output it will generate when the module is run. Once a module is built, its inputs and
outputs can be connected to entities in other models (or modules). These entities provide
the input values for the module and accept the output values from the module.
You can think of a module as a "black box" that has inputs and outputs. To connect the
module to other modules, you need to specify what information needs to come from other
modules ("Module Inputs") and what information is sent out to other modules ("Module
Outputs").

Module input A module input is an entity (for example, a stock or a converter) that
contains information that the module needs in order to run. When you build a module, you
decide what information in the module needs to come from outside the module and you
create an entity to hold this information. These are the module inputs. When you are ready

to use the module, you select the entity outside the module that will provide the value for
the module input by assigning the module input to an entity.
If you think of a module as a mathematical function, unassigned module inputs (and
outputs) correspond to the formal parameters of a function. When you assign the input to
an entity outside the module, you are assigning the actual parameter.
You can assign a module input to any entity that is connected to the module that contains
the module input. For the module to run, an entity defined as a module input must be
assigned to an entity outside the module that will provide the input value.
Module output A module output is an entity in the module that contains information
generated by the module. A module's outputs can be assigned to other entities when that
module is connected to an entity or another module (thus, the module output value is
assigned to a module input). This allows you to have the results of one module become the
input value to another entity or module. You can manually define an entity as a module
output, or you can assign it as a module input and it will be automatically defined as a
module output.
Levels Modules within a hierarchy exist in levels. The hierarchy begins with a top level,
which is a model. The top-level model contains connections down into one or more modules.
Although several modules can exist on the same level, you can view only one module at a
time. You can navigate up and down levels to view modules, but you cannot navigate
sideways.

A Module Example

Imagine you are building a business model for an airline. The causal loop diagram for the
model (the dynamic hypothesis) might look like this:

This is the top level of the model, which comprises five modules (Customers, Fleet,
Reputation, Quality, and Service). The connectors between modules indicate how values
flow from one module to another. For example, you can see that entity values flow in both
directions between the Customers and Fleet modules; however, entity values flow only in
one direction from the Quality to Reputation modules, and from the Reputation to
Customers modules. Similarly, the connectors show you that there is no direct connection
between the Service and Customers modules.
You develop each underlying module as a separate model. For example, this is what the
Customers (customer acquisition) module might look like:

Note that this module depends on several inputs from elsewhere in the model and will not
be able to run until those inputs are assigned. The unassigned module inputs are indicated
visually by a double-thick border for their entity icons and a bold font for their labels:

plane overcrowding factor

Reputation

Average Service Quality

drop price sw

When these module inputs are assigned to entities elsewhere in the model, the module is
fully defined and able to simulate as it stands in isolation.

Notice that the previously unassigned module inputs are now named this way:

Fleet.plane overcrowding factor

Reputation.Reputation

Quality.Average Service Quality

Quality.drop price sw

The part of the name before the period indicates the module where the entity is defined (for
example, Fleet, Reputation, and Quality). The part of the name after the period
indicates the entitys actual name, as defined in the module where the entity is defined (for
example, plane overcrowding factor and Average Service Quality). Notice that the
assigned module inputs are now indicated visually by an italic font for the entitys label, and
a double-thick gray border for the entitys icon.
This module also contains an entity that is defined as a module output (remember that the
Customers module had connectors indicating that it had inputs and outputs to both the Fleet
and Quality modules). In the Customers module, the Customers entity is defined as an
output. Outputs are indicated visually by a double-line border (which looks like an O in
converters and flows). The name for outputs appears in a regular font.
Now, lets look at the Quality module, which tracks service quality. This is the way the
module looks after the module inputs have been assigned:

In this module, there are two module inputs (Customers.Customers and Service.Service
Capacity) and four module outputs ("drop price sw", Average Service Quality, "Service
Quality", and normal service quality).
A module input can be assigned to

Entities that are directly connected to this module with an incoming connector.

Entities that are defined as module outputs in any module that is connected to this
module via an incoming connector.

Entities defined as module outputs in any submodule that has a connector into the
module input.

If you look back at the top-level of the module, you'll see that the Customers and Service
modules are both connected to the Quality module via incoming connectors, so module
outputs from both of those modules are available to be assigned as inputs to the Quality
module.
See Also

Overview: Ways to use modules

One way is to use modules is to start at the top by determining the connections between
modules and then creating the contents of each module. This method is called "developing
the dynamic hypothesis". With this method, you first look at the connections between
modules, envisioning the overall flow of information from one module to the other. Only
after you've made a plan for how each module is connected to the other do you start
building the contents of each module. The airline module example shows a module that is
built this way.

Another way is to use modules is to use (or re-use) an already-built structure in your model,
or to hide the details of a complex process. With this method, you are using the module to
perform a function in your model. You may not have built the module yourself, and you may
not even be able to see the details of the module if it is locked, but you have access to the
module by providing input values to the module and retrieving output values generated
from the module.

Using modules to communicate between

modules
The following procedure describes the overall process for building a hierarchical module by
first determining the connections between modules and then creating or importing the
modules. For more information about each step, click the link provided in each step.
1

Click
on the Map or Model toolbar and then click the diagram surface to place
module icons.

Use connectors to create connections between the module icons.

In the following example, connections indicate that the both modules supply and
receive entity values from each other.

Create and test the contents of each module. You can do this by building the
module directly within the model that contains it, or by creating a separate model.

In each module (or separate model to be used as a module), define the module
outputs.
In the following example, the "plane overcrowding factor" in the Fleet module is
defined as an output.

If you created a separate model to be used as module, import it into the module.

Assign the module inputs for each module.

In the following example, the "plane_overcrowding factor" entity from the Fleet
module is assigned as an input to the "plane overcrowding factor" entity in the
Customers module.

See Also

Using modules to re-use a common structure

The following procedure describes the overall process for using an already-built structure in
your model to provide input values to the model. For more information about each step,
click the link provided in each step.
1

Create and test a model for the process that you want to be able to re-use in other
models.
The Smooth3 model is an example of a process that you might want to build once to
use as a part of other models.

Define the inputs and outputs of the model.

In the Smooth3 example, there are two inputs: the converter named "input" (shown
below) and the converter named "averaging time".

The output is the stock named "Smooth3":

When you are finished creating the process model, save it.

Create or open the model that will use the process model.

Use the

Import the process model as a module by selecting module icon on the Model layer
and then clicking the Import button on the Module Properties panel.

Use connectors to create connections between the model entities and the module.

building block to add a module to the model.

In the Smooth3 example, the module is defined as having two inputs and one
output, so we could draw the connections this way, with "demand" and "perception
delay" providing the input value to Smooth3, and "perceived demand" accepting the
returned output value from Smooth3:

Assign the parameters and return values in the model to the defined module inputs
and module outputs in the module.
In the Smooth3 example, the two module inputs ("input" and "averaging time") are
the entities available to assign to the "demand" and "perception delay" entities in the
model.

Similarly, the module output "Smooth3" is the only entity available to be assigned to
"perceived demand".

This is what the model looks like with all entities assigned:

Overview: Module inputs and outputs

To prepare a module for use in a hierarchy, you need to decide which entities in the module
get their values from other modules, and which entities in the module (if any) output the
module's results. In most cases, you explicitly indicate which entities are module inputs and
which are module outputs by defining module inputs and module outputs.
When you are ready to use the module in a hierarchy, you need to assign each module input
to an actual entity. To make entities available for assigning to a module input, you first need
to make explicit connections (with connectors) between the module and other modules, or
between the module and an entity in the model. Once those connections are established,
you can assign module inputs.
You can also use the Ghost tool to connect entities. Using the Ghost tool allows you to
automatically assign module inputs and outputs as well as make connections between
modules and other modules or entities.

Defining module connections

Before you can assign inputs in your modules, you first need to establish the connections
that determine the source of data flowing into the module, and the recipient of data flowing
out of the module. To define the connections, you use connectors to draw the relationship
between modules and other modules, or between modules and entities in other models.
A completely defined module (one with all module inputs assigned and all entities defined)
can be run independently of the model that contains it and any other modules it is
connected to.

To define module connections

1

On the Map or Model layer, draw a connector from the module or entity that will
provide entities as outputs to the module that will accept those entities as input. In
the following example, entities in Module 1 are available as inputs for entities in
Module 2":

In the next example case, the "Customers" entity is available as an input for entities
in "Module 1".

Continue drawing connectors to define the input/output relationships among all

modules and entities in the model.
The following example (from the sample hierarchy discussed in A Module Example)
shows how some modules are related by both inputs and outputs, where others are
related by only one or the other, and still others are not directly related at all.

You can change the relationships at any time by adding or removing connectors. If
you make changes to the connectors after you assign input entities in each module,
you may need to reassign inputs to their proper outputs to be able to run the model.
See Also

Defining module inputs and module outputs

To allow model entity values to be used as values in a module, you must define module
entities as either module inputs or module outputs.

A module input is an entity in the module (a stock, a flow, or a converter) that

contains information that the module needs in order to run. Although you can
explicitly define an entity as a module input, you are not required to; when
you assign an entity as a module input (by using the Assign Input To command),
that entity is automatically made a module input.

A module output is an entity in the module that contains information generated by

the module and that can supply a value to other connected entities or modules.
Entities directly connected into a module (via a connector from the entity to the
module) can be assigned to a module input in the connected module without
explicitly defining them as outputs. These entities are providing data into the
connected module. On the other hand, entities that are providing data out of the
module (into the model that contains the module, or into another module) must be
explicitly defined as outputs.

Note: You can also define an entity to be neither a module input nor a module output by
selecting the Neither option.

To define an entity as a module input or module output

1

Navigate into the module for which you want to define an entity as a module input or
output.

Right-click the entity that you want to define, choose Module, and then
choose Accept Input, Provide Output, or Neither.

Note: Changing an entitys input/output definition disconnects any existing assignments

made between that entity and another entity.
See Also

Assigning module inputs

In order to use a module in a hierarchy, you need to assign each module input to an actual
entity. You can assign a module input to

Entities that are directly connected to this module with an incoming connector.

Entities that are defined as module outputs in any module that is connected to this
module via an incoming connector.

Entities defined as module outputs in any submodule that has a connector into the
module input.

There are two ways to assign module inputs:

From within a module, by selecting an available entity that is outside the module.

From outside of a module, by selecting an entity that has a connector into or out of a
module and assigning it to an entity that is inside the module.

Assigning module inputs from inside the module is possible only when you have access to
the module. If the module is locked, you can only assign module inputs from outside the
module.

To assign module inputs from inside a module

1

Navigate into a module to which you want to assign inputs by double-clicking the
module entity on the Map or Model layer.

In the module, right-click the entity to which you want to assign an input and then
choose Assign Input to. A list of entities that can be assigned to this entity
appears.

If the module input has already been assigned, a check mark appears next to
the entity assigned to it (Quality.normal_service_quality, in the above
example).

If an entity is assigned to another entity in the module, it appears grayed out

(Quality.Service_Quality in the above example).

If an entity is a flow, it can only be assigned to a flow if the module output

flows into a cloud (sink) and the module input originates from a cloud
(source). If these conditions are not met, the entity's name appears grayed
out.

If an entity is a flow and has already been assigned to a flow in the model, it
appears grayed out for all other flows in the model.

Note: Although module outputs that are flows can only be assigned to one
other flow in the model, they can still be assigned to as many converters as
you wish.

All other listed outputs have not yet been assigned and can be assigned to
inputs.

Select an available entity to assign to the module input. When an input is already
assigned, choosing a different output reassigns the input to the new entity. When
you assign a module input, the entity's name is automatically changed to that of the
output.

To assign module inputs from outside a module

When you are assigning module inputs from outside a module, you can assign both input
entities to the connected module as well as return values from within the module.
1

To assign an entity as an input value to a module input in a connected module, rightclick the entity and then choose Assign to. A list of module inputs to which you can
assign the entity appears:

If the entity has already been assigned to a module input, a check mark
appears next to the entity assigned to it.

If an entity is assigned to another entity, its name appears grayed out.

All other listed module inputs have not yet been assigned and can be assigned
to the entity.

Select an available module input to assign to the entity. When an entity is already
assigned to a module input, choosing a different module input reassigns the entity to
the new entity.

To assign a module output as a return value to an entity connected to the module,

right-click the entity and then choose Assign Input to. A list of module outputs that
can be assigned to the entity appears.

Select an available module output to assign to the entity. When an entity is already
assigned to a module output, choosing a different module output reassigns the entity
to the new entity. When you assign an entity to a module output, the entity's name
is automatically changed to that of the module output.

See Also

Creating entity aliases

An entity alias is a copy of a stock, flow, or converter that allows you to use the original
entity elsewhere in your model. The entity alias is not a new, separate entity. Instead, it is a
shortcut to the original entity.
Entity aliases (also called ghosts) help you keep your diagrams tidy by allowing you to use
the same entity in separate locations in your model. This helps you keep connections neat,
as the following pictures illustrate.

Note: You can also use the ghost tool to connect entities across modules and to
automatically assign module inputs and outputs.
A ghost of an entity has no independent identity; it is simply an image of the building block
from which it was ghosted. The ghosted replica has no equation of its own. When you
double-click a ghosted replica, the dialog box that opens belongs to the original entity which
the replica was made. No matter how many ghosted replicas of a given building block you
create, only one dialog box exists, because only one building block exists.
A ghost adds no real structure to a model. Ghosted stocks have no inflows or outflows;
ghosted flows and ghosted converters (when you "ghost" a flow, its ghost appears as a
converter) have no input connectors. Ghosts are thus read-only information holders. You
can draw connectors from them. Nothing can go into them.
The ghost is available on the Map and Model layers only.

To create an alias
1

On the Map or Model layer, navigate to the stock, flow, or converter for which you
want to create an alias.

On the Map or Model toolbar, click the ghost tool

Click once on the stock, flow, or converter that you want to ghost.
The mouse pointer changes from the ghost pointer
building block you are ghosting.

to a small image of the type of

Click the diagram where you want to place the ghost.

Use the ghosted entity by adding connections between it and other model entities, as
needed.

See Also

Assigning module inputs

In order to use a module in a hierarchy, you need to assign each module input to an actual
entity. You can assign a module input to

Entities that are directly connected to this module with an incoming connector.

Entities that are defined as module outputs in any module that is connected to this
module via an incoming connector.

Entities defined as module outputs in any submodule that has a connector into the
module input.

There are two ways to assign module inputs:

From within a module, by selecting an available entity that is outside the module.

From outside of a module, by selecting an entity that has a connector into or out of a
module and assigning it to an entity that is inside the module.

Assigning module inputs from inside the module is possible only when you have access to
the module. If the module is locked, you can only assign module inputs from outside the
module.

To assign module inputs from inside a module

1

Navigate into a module to which you want to assign inputs by double-clicking the
module entity on the Map or Model layer.

In the module, right-click the entity to which you want to assign an input and then
choose Assign Input to. A list of entities that can be assigned to this entity
appears.

If the module input has already been assigned, a check mark appears next to
the entity assigned to it (Quality.normal_service_quality, in the above
example).

If an entity is assigned to another entity in the module, it appears grayed out

(Quality.Service_Quality in the above example).

If an entity is a flow, it can only be assigned to a flow if the module output

flows into a cloud (sink) and the module input originates from a cloud
(source). If these conditions are not met, the entity's name appears grayed
out.

If an entity is a flow and has already been assigned to a flow in the model, it
appears grayed out for all other flows in the model.
Note: Although module outputs that are flows can only be assigned to one
other flow in the model, they can still be assigned to as many converters as
you wish.

All other listed outputs have not yet been assigned and can be assigned to
inputs.

Select an available entity to assign to the module input. When an input is already
assigned, choosing a different output reassigns the input to the new entity. When
you assign a module input, the entity's name is automatically changed to that of the
output.

To assign module inputs from outside a module

When you are assigning module inputs from outside a module, you can assign both input
entities to the connected module as well as return values from within the module.
1

To assign an entity as an input value to a module input in a connected module, rightclick the entity and then choose Assign to. A list of module inputs to which you can
assign the entity appears:

If the entity has already been assigned to a module input, a check mark
appears next to the entity assigned to it.

If an entity is assigned to another entity, its name appears grayed out.

All other listed module inputs have not yet been assigned and can be assigned
to the entity.

Select an available module input to assign to the entity. When an entity is already
assigned to a module input, choosing a different module input reassigns the entity to
the new entity.

To assign a module output as a return value to an entity connected to the module,

right-click the entity and then choose Assign Input to. A list of module outputs that
can be assigned to the entity appears.

Select an available module output to assign to the entity. When an entity is already
assigned to a module output, choosing a different module output reassigns the entity
to the new entity. When you assign an entity to a module output, the entity's name
is automatically changed to that of the module output.

See Also

Creating modules
You can create a module either by creating a model, saving it, and then importing it into a
module; or by creating and building a module directly within a model. Both procedures are
described below.

To create a module by importing a model

1

Create a model that you want to import as a module.

Define the model as you would any other model, but also define its module inputs
and outputs.

Save the model.

Import the saved model into the module.

To create a module from within a model

1

Open or create the model in which you want to create a module.

On the Map or Model tool bar, click the

tool.

Click the diagram surface to place the module entity on the layer.

Name the module entity as you would any other entity.

On the Model layer, double-click the new module entity.

The Map or Model layer appears for the module.

Build the module as you would any model.

Save your changes as you work by choosing Save from the File menu. This saves all
changes you made to the top-level model and any modules in the model.
Note: By default, modules are saved in the model file. To save a module in a
separate file, select the Save in separate file check box on the Module Properties
panel. For more information, see Setting module properties.

Repeat this procedure to add as many modules as you need to the model.
You can add modules to the top-level model, or to any other modules within the
model by navigating to the module into which you want to add another module.

Tip: To navigate from the module to another level in the hierarchy, click
navigate up one level, or click

to

to go to the top level.

When you having finished creating a module, define the module inputs and outputs for the
module, and then assign the module inputs. The model, as a whole, cannot run until all
module inputs have been assigned (each module, though, can run in isolation). For more
information, see Running modules.
Note: After you've created a module, you can also add a picture to appear on a module's
icon, select to password-protect the module, and select whether you want to save the
module in a separate file from the model. For more information, see Setting module
properties.
See Also

Overview: Units
A great way to clarify conceptualization, disambiguate terminology and guard against
common formulation errors is to specify units of measure for each model variable and check
the model for dimensional consistency. Stella makes this very easy to do, and allows you to
quickly find and correct any inconsistencies that might arise.

To specify the units of measure for a variable you enter them in the Units editor at the
bottom of the Equation panel.

You can type into the Units editor and you will be prompted with the names of units already
used in the model as well as defined unit names. Alternatively you can select the units from
the popup menu that opens when you click on the popup indicator at the right. Stella has a
number of built in units and the popup menu organizes these into categories as well as
providing access to any units of measure that you have defined or have already been used
in the model. There are also options to check whether the units for the current variable are
consistent and to suggest units for the variable based on the equation as discussed
in Assigning units.
The units of measure you specify can be a name, or an equation. Unit equations are simpler
than variable equations. They can contain names, multiplication operators (* or -), division
operators (/), power (^) and parentheses to control precedence. The names of units must
start with a letter or Unicode character beyond the Latin character range and contain letters,
numbers, spaces or $. You can also use both $ and % as a unit of measure and 1 is treated
as the identity unit of measure. Because of their simple format you can use a space or
underbar interchangeably when specifying units.
The following are valid units of measure:
$/Hours
US$/Months
Months Per Year
1/Seconds
Meters/Second^2
Meters/Second/Second
Meters/(Second-Second)
The last three of these are equivalent.
The following are not valid units of measure:
$US/Day - $ can't be followed by anything
Feet/(Second/Second - mismatched parentheses
Tonnes^Apples - can only follow ^ with a number

Checking Units
The software checks units by passing through the equations for a variable substituting the
units of measure for the variables used for the variable values. For example if we have the
equation
production = workers * productivity
and we have specified that workers are measured in Person, and productivity is measured in
Widget/Month/Person, the substituting these values would give Widget/Month. If the units
of measure for production are Widget/Month then the units will match.
If, on the other hand, workers was measured in People then what would happen? Reducing
the equation would give People/Person*Widget/Month. People and Person should reasonably
cancel in this equation, and Stella does this by having person as an alias for People. This
alias, and a number of others are built in by Stella. Similarly, if the units assigned to
productivity were Widgets_per_Month_per_Person, you could create an equation settings
Widgets_per_Month_per_Person to be equal to Widget/Month/Person.
You can define a Unit of measure by specifying an equation and zero or aliases using
the Unit Editor dialog box. The equation is not required if there are one or more aliases.
Stella has a variety of defined Units of measure built in, including Widgets with alias
widgets, Seconds with aliases s and second, Per Second with equation 1/Seconds and so on.
Having the equations and aliases in place allow you to attach easy-to-read units to all your
model variables, but still have them resolve to a well defined meaning for units checking.
If there are any problems with Units in your model they are displayed in the error list at the
end of the Run toolbar.

Creating and deleting unit definitions

If the units you want to assign are not in the list of available units, you can create a new
unit of measure from scratch or by basing it on one or more existing units. You can also
simply type in the units you want to use as a name or an equation involving names.
Tip: You can choose to make units you create in one model available for all of your models
or create them only for the current model.
The following procedures describe how to use the Unit Editor dialog box to create new unit
definitions from scratch, how to create new unit definitions by deriving them from other
definitions, and how to delete unit definisions you have created.

To create new unit definitions

1

Open the Unit Editor dialog box by using one of these methods:
o

From the Interface, Model, or Equation menu, choose Unit Editor from the
Model menu.

Next to the Unit entry box on the Equation panel, click

choose Unit Editor.

Right-click a stock or converter in the diagram, choose Units, and then

choose Unit Editor.

, and then

The Unit Editor dialog box opens.

The available unit definitions are divided into three sections: Default Units, My Units
and Model Specific Units. All can be used within the current model, and you can add
definitions to My Units or Model Specific Units. To add a unit definition:
1

In the Unit Name box, type a unique name for the new unit of measure. This name
will appear in the shortcut menu used to assign units and autocomplete will also
prompt you with it.

In the Unit Equation box, type the equation for the new unit of measure. If you leave
the box blank, the software assumes that the unit of measure's name and equation
are the same. If you want to create an additional alias for an existing unit definition
type in that unit for the equation. For more information about creating equations,
see Creating equations for units.

In the Unit Alias box, optionally type in a comma separated list of equivalent names
for the unit you are defining. For example the unit Cans might have aliases Can, Tin
Can, Tin Cans.

When you are finished specifying the new unit definition, click Add To My Units or
click Add To Model Specific UnitsThe new unit of measure definition is added to
the corresponding list in alphabetical order. Assigning the named unit, any of its
aliases, or its equation to a variable will have the meaning.

To derive units from existing units

1

Open the Unit Editor dialog box by using one of these methods:
o

From the Interface, Model, or Equation menu, choose Unit Editor.

After typing a new unit of measure in the Units box on the Equation panel,
click

, and then choose Add to my units.

Right-click an entity in the diagram, choose Units, and then choose Unit
Editor.

The Unit Editor dialog box opens.

1

In the "Available Units" list, select the existing unit of measure from which you want
to derive the new unit of measure.

Click Derive New Unit.

The name, equation (if any) and short name (if any) for the selected unit of measure
appear in the boxes at the bottom of the dialog box.

Edit the name, equation, and short name for the new unit of measure.

When you are finished specifying the new unit of measure, click Add To List.

To delete units you have created

You can delete Unit definitions that you have created or that are in a model you are working
withby clicking on the black X next to the Unit in the appropriate list of the Unit Editor dialog
box. You may also move unit definitions between being model specific and kept for all your
models by clicking on the Unit in the list and clicking either the << or >> buttons.
If you delete Units definitions that are being used in the model, the equivalence they used
to provide will no longer hold. For example if you had defined Das with equation Days and
then removed it, the units Days and Das would no longer match.
Moving Unit definitions between My Units and Model Specific Units will have no effect on
check Units results, whereas deleting definitions may. Removing Unit definitions from either
category will have no effect on Check Unit results for other models: Unit definitions used in
those models will simply change category according to the changes you make.
See Also

Checking unit consistency

Checking unit consistency allows you to ensure that the left- and right-hand sides of entity
equations have consistent units, and that stocks in conserved flow chains all have the same
units of measure.
When you check unit consistency, if any assigned units are incorrectly defined, the software
displays a warning message, but you can still run the model.

You can check units for a specific entity or for the entire model. Both procedures are
described below.

To check unit consistency for a single entity

1

In the model diagram, select the entity whose units you want to check.
Note: You must have an equation defined for the entity in order to check its units.

On the Equation panel, click

next to the Units box, and then choose Check units.

A message appears that indicates if the units are consistent or inconsistent.

To check unit consistency for the entire model

1

From the Run menu, choose Check Units.

The software checks all units assigned to entities in the model.

If no problems are found, a message appears that tells you that all units in the
model are consistent. Click OK to close the message.

If it finds any problems, a message appears that tells you that some units are
inconsistent. Click OK to close the message.
The entities that have inconsistent units are highlighted in the model diagram.
If the Enforce Unit Consistency check box is selected in the Model Preferences
dialog box, an "?" appears in any entity that fails the unit consistency check. You
cannot run a simulation until all inconsistencies are resolved.

To troubleshoot the inconsistencies, select each highlighted entity, and then check
the entity's units on the Equation panel to verify that the correct unit of measure is
assigned to the entity.

See Also

Viewing building block values

When you are building and testing a model, it's often useful to be able to determine the
numerical value taken on by a given entity at a particular point in time.
You can do this by hovering the mouse pointer over any building block while the simulation
is paused or stopped. The entity's numerical value appears.

For an entity that has been loaded into a table or a graph, hovering displays a small graph
with the entity's value.

Tip: To display a graph on hover for all model entities if the model has run, select
the Analyze Mode check box in the Run Specs dialog box. If the model has not yet run,
hovering over an entity will display the entity's initial value.
See Also

Working with building blocks

Building blocks are the tools you use to construct the model on each layer.
The Map and Model layers provide five building blocks:

Stocks Stocks are accumulations. They collect whatever flows into them, net of
whatever flows out of them.

Flows The job of flows is to fill and drain accumulations. The unfilled arrow head on
the flow pipe indicates the direction of positive flow

Converters Converters hold values for constants, define external inputs to the
model, calculate algebraic relationships, and serve as the repository for graphical
functions. In general, they convert inputs into outputs.

Connectors Connectors connect model entities to each other.

Modules Modules are self-contained models that you can connect to other models.
Modules allow you to break a single model into well-defined "chunks".

Note: In addition to these building blocks, you can use sector frames to group together
functionally related chunks of model structure. For more information about working with
sector frames, seeSector frames.

The following sections describe how to work with building blocks by

placing them on the diagram

selecting them to move or modify them

moving them

renaming them

moving their name plates

viewing or editing their properties

changing their colors

deleting them

To place a building block on the diagram

1

On the appropriate layer toolbar, click the tool for the building block you want to
place.
Tip: To place multiple building blocks of the same type on the diagram, double-click
the tool to keep it selected.

If more than one type of the building block is available (for example, stocks), click
and hold the building block's tool in the toolbar to view a list of the available types,
then select the type you want to use.

Click the diagram to place the building block.

If you double-clicked to place more than one building block of this type on the
diagram, continue clicking to place the building blocks.

When you are finished placing the building block, press ESC to deselect the building
block type.

Tip: For detailed notes on placing each type of building block, refer to the discussion of the
specific building block you are using.

To select a building block

Click within the building block icon's border. The building block is highlighted.

For a flow, click within the circle portion of the flow icon.

To move a building block

1

Click inside the building block icon's border and hold the mouse button down.

Drag the building block to the desired location.

To move a building block with handles

A handle is a square block at one or more ends of a building block. For example, the flow
has a handle on each end.

Click and drag a building block's move handle to the new location.

For a flow attached to a stock, click and drag the flow's move handle to drag it up or
down the side of the stock.

To detach a flow from a stock, click and drag the flow's move handle away from the
stock.

To re-attach a flow to a stock, click and drag the cloud end of the flow onto the
stock.

For a connector, click and drag the connector's handle to the new position on the
entity to which it's attached.

To rename a building block

Building block names can be up to 65 characters long.
1

Click the building block's name plate. The name plate and building block become
highlighted.

Type the new name:

o

To replace the existing name, type a new name. The new name replaces the
existing name.

To edit the existing name, hover the mouse pointer over the name. The
pointer changes to an I-beam. With the I-beam, click within the name where
you want to begin editing, then type your changes.

To create a multi-line name, press RETURN at the end of a line to move to the
next one.

When you are finished editing the name, click a blank space on the diagram.

To move a building block's name plate

You can position a name plate anywhere around the border of a building block's icon, or
inside the building block's icon.

Click and drag the name plate to its new location.

Tip: To constrain the position of the name plate to North, South, East, or West, hold the
CTRL key (Windows) or the Command key (Macintosh) while dragging the name plate.

To view or edit a building block's properties

1

On the model diagram, select the building block whose properties you want to edit.

On the right side of the window, select the panel for the properties you want to view
or edit.
Tip: Double-click the building block to automatically select the building block's
default field on the currently displayed panel.

Use the options on the panels to make the edits you want.

When you are finished making changes, apply your edits.

For more information about using panels, including making, applying, and undoing changes
to properties, see Working with panels.

To change colors for a building block

Use the paintbrush tool

to change the color of building blocks. For more
information, see Adding color to models.

To delete a building block

1

Select the building block that you want to delete.

From the Edit menu, choose Delete .

or
Right-click the object and then choose Delete from the menu that appears.
or
Press the DELETE key.
See Also

Working with objects

Objects help you communicate information about your model and allow users to interact
with it. Objects are classified into four groups: input devices, output devices, annotations,
and buttons.

Input devices allow you and your model's users to provide or adjust input values
for model entities. Input devices include objects like knobs, sliders, and list input
devices.

Output devices allow you to display model output in ways that make it easier for
model users to understand the results of the model run. Output devices include
objects like graph pads,table pads, and numeric displays.

Annotations include things like text descriptions, instructions, and images.

Buttons allow you to initiate actions, such as navigating to another page of the
model, executing a menu command, or unfurling the story of your model.

The objects you can use depend on the layer on which you are working. The following table
indicates which objects are available for each diagram layer.
Interface layer Map and Model layer
Annotations

Input devices

Text box

Graphics frame

Loop pad

Graphical input device (GID)

Knob

List input device (LID)

Interface layer Map and Model layer

Slider

Switch

Output devices Graph pad

Buttons

Table pad

Numeric display

Status indicator

Information

Navigation

Menu

Hyperlink

Play Movie

Storytelling

Tracing

Many of the tasks associated with objects (placing them on the diagram, selecting them,
moving them, etc.) are the same, regardless of the type of object you're working with. For
details about using a specific object, refer to the documentation for the object you want to
use.
The following sections describe how to work with objects by

placing them on the diagram

selecting them to move or modify them

moving them

resizing them

moving their name plates

changing their colors

viewing or editing their properties

deleting them

To place an object on the diagram

1

On the appropriate layer toolbar, click the tool for the object you want to place.
Tip: To place multiple objects of the same type on the diagram, double-click the tool
to keep it selected. This feature is not available for buttons, loop pads, graph pads,
and table pads.

If more than one type of the object is available, click and hold the object's tool in the
toolbar to view a list of the available types, then select the type you want to use.

Click the diagram to place the object.

If you double-clicked to place more than one object of this type on the diagram,
continue clicking to place the objects.

When you are finished placing the objects, press ESC to deselect the object type.

Tip: For detailed notes on placing each type of object, refer to the discussion of the specific
object you are using.

To select an object

Click within the object icon's border. The object is highlighted.

Note: To select a button, text box, or graphics frame, hover the mouse pointer over the
icon's border or edge. When the mouse pointer changes to cross-hairs, click to select the
object.

To move an object
1

Select the object that you want to move.

Click and drag the object to the desired location.

Note: Moving an object is not the same as moving its associated pad (for instance, a loop
pad, graph pad, or table pad). The object's icon can appear in one location on the diagram
while the associated pad opens in another. For more information, see Working with pads.

To resize an object
Use this procedure to resize buttons, list input devices, text boxes, graphics frames,
and pads.
1

Select the object that you want to resize.

Click and drag one of the resize handles until the object is the size you want.

To move an object's name plate

You can move the name plate for a loop pad, knob, slider, graph pad, or table pad.
You can position a name plate anywhere around the border of an object's icon.

Click and drag the name plate to its new location.

Tip: To constrain the position of the name plate to North, South, East, or West, hold the
CTRL key (Windows) or the CMD key (Macintosh) while dragging the name plate.

To view or edit an object's properties

Select the object whose properties you want to edit, and then choose Open
Selection from the Interface, Map, or Model menu.
or
Right-click the object's icon, and then choose Open from the menu that appears.
or
Double-click the object's icon:
o

For buttons, text boxes, or graphics frames, select the icon first, then doubleclick the icon.

For list input devices, double-click the empty space to the left or right of the
list's name or in an empty row in the list.

The object's dialog box or pad opens.

Note: If you are opening a pad, the last viewed page in the pad will be displayed;
right-click the pad and then choose Open, or double-click the pad to view the
object's dialog box. For more information, see Working with pads.
Tip: For many of the objects, you can select the entities to be associated with the
object by dragging the entity from the diagram or from the Find palette onto the
object. For example, you can include an entity in a table by dragging the entity from
the model diagram or the Find palette. For more information, see the Help topic for
the object you are defining.

To change colors for an object

Use the paintbrush tool to change the background color of objects. Depending on the type
of object, you can also change the color of elements within the object (for example, plot
curve and scale colors in a graph pad). For more information, see Adding color to models.

To delete an object
1

Select the object that you want to delete.

From the Edit menu, choose Delete.

or
Right-click the object and then choose Delete from the menu that appears.
or
Press the DELETE key.

See Also

Overview: Creating model interfaces

An interface provides a way for model users to interact and understand a model without
getting bogged down in the details of the model's structure.
A model interface allows your model's users to interact with the model by changing model
inputs, running the simulation, and viewing its output. The interface also gives you a way to
organize the model for clear communication by laying it out in pages or by using the
storytelling feature, and by adding text and graphics that help clarify or point out important
points in the model.

The following procedure is a high-level guide to the steps involved in creating a model
interface. Use the links in each step for more information about the step.

Steps for creating a model interface

1

Specify the size of your interface.

The first step in defining an interface is to specify how large the interface will be,
both in number of pages (for example, three pages wide and two pages high) and in
page size/resolution (for example 800 x 600) visible on the Interface layer.
Note: The size you specify can be completely unrelated to the size of the actual
model structure on the Map and Model layers.

Create a "Home" page.

Use a Home page on your interface to introduce the model and its context to model
users. Include a title, illustrations, and other introductory material by
adding text, images and information and navigation buttons. Use information
buttons to display text in pop-up windows that appear when the user clicks the
button (for example, use an information button to display supplementary or lengthy
text that you don't want to clutter the main interface). Use navigation buttons to
allow users to move to a place you select in the model interface (for example, to a
specific page or object on a page) and then to move back to the Home page.

Create a "Simulation Lab" page.

Add interface objects that provide a "laboratory" environment where users can
experiment with the model. Let users modify model inputs, run simulations and view
results by providing interface objects such as graphs, menu buttons, numeric
displays, status indicators, sliders, and switches.
Note In the simulation lab you can specify interactive runs in which the simulation
pauses and use interation is called for or simulation runs that unfold after the user
has made changes to assumptions without further interaction. It is also possible to
put the interface in Stella Live mode as described in Defining menu buttons. Stella
Live mode is not available for use with isee NetSim.

Create an "Assumptions" page.

Allow users to change initial values or assumptions about the relationships defined in
your model by including knobs and graphical input devices.

Create a story.

Tell a story with your model by using the storytelling feature. Storytelling allows you
to customize the sequential unfurling of the entities in your model. You choose which
entities are revealed and in what order. Storytelling also allows you to intersperse
text, graphics, sounds, or movies between each entity that is being revealed. Finally,
you can simulate the structure that is showing on the diagram, in mid story.
See Also

Working with building blocks

Building blocks are the tools you use to construct the model on each layer.
The Map and Model layers provide five building blocks:

Stocks Stocks are accumulations. They collect whatever flows into them, net of
whatever flows out of them.

Flows The job of flows is to fill and drain accumulations. The unfilled arrow head on
the flow pipe indicates the direction of positive flow

Converters Converters hold values for constants, define external inputs to the
model, calculate algebraic relationships, and serve as the repository for graphical
functions. In general, they convert inputs into outputs.

Connectors Connectors connect model entities to each other.

Modules Modules are self-contained models that you can connect to other models.
Modules allow you to break a single model into well-defined "chunks".

Note: In addition to these building blocks, you can use sector frames to group together
functionally related chunks of model structure. For more information about working with
sector frames, seeSector frames.
The following sections describe how to work with building blocks by

placing them on the diagram

selecting them to move or modify them

moving them

renaming them

moving their name plates

viewing or editing their properties

changing their colors

deleting them

To place a building block on the diagram

1

On the appropriate layer toolbar, click the tool for the building block you want to
place.
Tip: To place multiple building blocks of the same type on the diagram, double-click
the tool to keep it selected.

If more than one type of the building block is available (for example, stocks), click
and hold the building block's tool in the toolbar to view a list of the available types,
then select the type you want to use.

Click the diagram to place the building block.

If you double-clicked to place more than one building block of this type on the
diagram, continue clicking to place the building blocks.

When you are finished placing the building block, press ESC to deselect the building
block type.

Tip: For detailed notes on placing each type of building block, refer to the discussion of the
specific building block you are using.

To select a building block

Click within the building block icon's border. The building block is highlighted.

For a flow, click within the circle portion of the flow icon.

To move a building block

1

Click inside the building block icon's border and hold the mouse button down.

Drag the building block to the desired location.

To move a building block with handles

A handle is a square block at one or more ends of a building block. For example, the flow
has a handle on each end.

Click and drag a building block's move handle to the new location.

For a flow attached to a stock, click and drag the flow's move handle to drag it up or
down the side of the stock.

To detach a flow from a stock, click and drag the flow's move handle away from the
stock.

To re-attach a flow to a stock, click and drag the cloud end of the flow onto the
stock.

For a connector, click and drag the connector's handle to the new position on the
entity to which it's attached.

To rename a building block

Building block names can be up to 65 characters long.
1

Click the building block's name plate. The name plate and building block become
highlighted.

Type the new name:

To replace the existing name, type a new name. The new name replaces the
existing name.

To edit the existing name, hover the mouse pointer over the name. The
pointer changes to an I-beam. With the I-beam, click within the name where
you want to begin editing, then type your changes.

To create a multi-line name, press RETURN at the end of a line to move to the
next one.

When you are finished editing the name, click a blank space on the diagram.

To move a building block's name plate

You can position a name plate anywhere around the border of a building block's icon, or
inside the building block's icon.

Click and drag the name plate to its new location.

Tip: To constrain the position of the name plate to North, South, East, or West, hold the
CTRL key (Windows) or the Command key (Macintosh) while dragging the name plate.

To view or edit a building block's properties

1

On the model diagram, select the building block whose properties you want to edit.

On the right side of the window, select the panel for the properties you want to view
or edit.
Tip: Double-click the building block to automatically select the building block's
default field on the currently displayed panel.

Use the options on the panels to make the edits you want.

When you are finished making changes, apply your edits.

For more information about using panels, including making, applying, and undoing changes
to properties, see Working with panels.

To change colors for a building block

Use the paintbrush tool

to change the color of building blocks. For more
information, see Adding color to models.

To delete a building block

1

Select the building block that you want to delete.

From the Edit menu, choose Delete .

or
Right-click the object and then choose Delete from the menu that appears.
or
Press the DELETE key.

See Also
Running model next