Professional Documents
Culture Documents
User’s Guide
Powersim Studio 2003
User's Guide
by Powersim Software AS
The Business Simulation Company
-3-
Copyright © 1997 – 2003 by Powersim Software AS. All rights reserved.
No portion of the contents of this publication may be reproduced or transmitted in any form or by
any means without the express written permission of Powersim Software AS.
Trademark, service mark, and copyright acknowledgements appear in the Powersim Studio 2003
Reference Manual.
The Software License Agreement and Limited Warranty also appears in the Appendix of the
Reference Manual.
We have done our best to ensure that the material found in this publication is both useful and
accurate. However, please be aware that errors may exist in this publication, and that neither the
authors nor Powersim Software AS make any guarantees concerning the accuracy of the
information found here or in the use to which it may be put.
Mention of third-party products is for informational purposes only and constitutes neither an
endorsement nor a recommendation. Powersim Software AS assumes no responsibility of models
created using software marketed by Powersim Software AS.
-4-
Foreword
-5-
From models to simulators
Why this sudden change in business practices? Business models are not substantially easier to build
now than they were at the before. Nor has there been a watershed event that has made the business
community suddenly more receptive to simulation. From the viewpoint of us in the business
modeling community, building simulation models for years, the change is welcome, but a little
mysterious. However, from the viewpoint of our business customers, there has been a technology
revolution of sorts. Once a model is built, it is easy to build a high-quality user interface around it,
and turn it into a business simulator. Anyone can run the business simulator, trying different
decision scenarios and understanding the resultant behaviors.
-6-
mechanics. Through simulation, a businessperson can thus acquire experience not only without
"field" work, but also without necessarily understanding details of the model behind it.
Powersim Studio supports two approaches to building business simulators: building a simulator
within Powersim itself, and building a simulator in a general-purpose, interface-building language
and using Powersim as a simulation engine through the available Powersim Studio Software
Development Kit (SDK).
Within Powersim Studio, a modeler can use a host of interface objects. You can present the state of
the simulation by a gauge, by a graph of an array, and by many other means. You may also
program events that will occur when certain situations occur in your simulation.
As more and more organizations build business simulators to understand their world, and
communicate it to others within their organization and outside, your job will become more exciting
and more important. We at Powersim are committed to supporting you in your efforts to build
business simulators.
Good luck with your purchase of Powersim Studio 2003!
-7-
Table of Contents
Foreword............................................................................................................................ 5
-9-
Customize the help window ................................................................................ 65
Hide or show the navigation pane....................................................................... 66
Use the Powersim Learning Lab ......................................................................... 66
Find a help topic.................................................................................................. 66
Copy a help topic ................................................................................................ 67
Print the current help topic.................................................................................. 67
Use the favorites tab............................................................................................ 67
Find information with full-text search ................................................................ 67
Get help in a dialog box ...................................................................................... 68
Highlight words in searched topics ..................................................................... 68
- 10 -
Select entries in treeviews................................................................................... 82
Switch between hierarchical and flat view in treeviews ..................................... 82
Organize windows............................................................................................... 83
Save window position ......................................................................................... 83
Open a new window for the active component ................................................... 84
Close the active window ..................................................................................... 84
Close all windows ............................................................................................... 85
The Project Window ........................................................................................... 85
The Status Bar..................................................................................................... 85
Dock the Project Window ................................................................................... 86
Create a folder in the Project Window................................................................ 86
Show or hide the Project Window ...................................................................... 86
Working with toolbars and keyboard shortcuts................................................... 86
Select a persistent tool......................................................................................... 87
Move or dock a toolbar ....................................................................................... 87
Show or hide a toolbar ........................................................................................ 87
Diagram commands ............................................................................................ 88
Format commands............................................................................................... 91
Layout commands ............................................................................................... 93
Simulation commands......................................................................................... 94
Standard commands ............................................................................................ 96
Symbol commands.............................................................................................. 98
Presentation commands....................................................................................... 99
View commands................................................................................................ 101
Constructor keyboard shortcuts and modifiers ................................................. 103
Studio keyboard shortcuts ................................................................................. 105
- 11 -
Diagram errors and inconsistencies .................................................................. 120
Adding controls and auto reports to a diagram ................................................. 121
The stacking order of diagram objects .............................................................. 122
Toggle between Design and User mode............................................................ 123
Change stacking order of objects ...................................................................... 123
- 12 -
Consistency rules for submodel diagrams......................................................... 144
Create a submodel ............................................................................................. 146
Create a submodel from a component............................................................... 146
Include child variables in parent diagrams........................................................ 147
Open a diagram for a variable........................................................................... 148
Create links to or from a submodel ................................................................... 148
Create flows to or from a submodel.................................................................. 149
Create an anonymous flow................................................................................ 151
- 13 -
Work with auto reports ................................................................................................ 170
Show a number auto report ............................................................................... 170
Show a time graph auto report .......................................................................... 171
Hide an auto report............................................................................................ 171
Unhide an auto report........................................................................................ 172
Change type of auto report................................................................................ 172
Move and position an auto report...................................................................... 172
Delete an auto report ......................................................................................... 173
Size an auto report............................................................................................. 173
- 14 -
Add a bookmark................................................................................................ 189
Add a hyperlink................................................................................................. 190
Create hyperlinks without text .......................................................................... 191
Open a hyperlink............................................................................................... 191
Resize a frame to fit a picture ........................................................................... 191
Use a frame as background ............................................................................... 192
Select a transparent frame ................................................................................. 192
Draw a freeform line ......................................................................................... 192
Reshape a freeform ........................................................................................... 193
Create image maps ............................................................................................ 193
Change arrowheads and –tails on freeform lines .............................................. 194
Change the order of freeforms .......................................................................... 194
Delete a hyperlink ............................................................................................. 194
Delete a bookmark195
- 15 -
Add cue points to the simulation run ................................................................ 212
Go to a cue point in the simulation run ............................................................. 212
Manually autoscale all variables ....................................................................... 213
Restore permanent variables ............................................................................. 213
About runs and reference data........................................................................... 213
Saving a simulation run..................................................................................... 214
Activating a saved run....................................................................................... 215
Rename a simulation run................................................................................... 215
Exporting a simulation run................................................................................ 215
Importing a simulation run................................................................................ 216
Make a simulation run visible in Presentation Mode........................................ 216
Enter documentation for a simulation run......................................................... 217
Delete a simulation run ..................................................................................... 217
Select reference data ......................................................................................... 217
About the report window and intervals............................................................. 218
Set up major and minor time intervals .............................................................. 218
Set up report window ........................................................................................ 219
- 16 -
About discrete flows ......................................................................................... 249
About logical flows........................................................................................... 251
Flow function examples .................................................................................... 252
About circular definitions ................................................................................. 260
About the function wizard................................................................................. 261
About value formatting ..................................................................................... 262
Adding comments to definitions ....................................................................... 262
Define a variable on the property pages............................................................ 263
Define a variable in the name box..................................................................... 263
Define variable in the Equations View ............................................................. 264
Change variable type......................................................................................... 264
Define flow equations for a level ...................................................................... 264
Formatting variable definitions ......................................................................... 265
Insert a function in a definition ......................................................................... 265
Insert range name for a dimension .................................................................... 266
Insert unit name................................................................................................. 266
Insert variable name in a definition................................................................... 266
Set array dimensions from the Definition property page .................................. 267
Set unit of measurement.................................................................................... 267
Set data type for a variable................................................................................ 268
Insert a function expression with the Function Wizard..................................... 268
View the current value of a variable ................................................................. 269
Write documentation for a variable................................................................... 269
Customize the appearance of definitions .......................................................... 269
About hierarchical models ................................................................................ 270
Private and public variables .............................................................................. 271
Hierarchical syntax ........................................................................................... 273
Monitor the flows of a level .............................................................................. 275
Hierarchical models: Examples......................................................................... 276
- 17 -
Define an enumerated range.............................................................................. 288
Rename range elements .................................................................................... 289
Define an enumerated subrange ........................................................................ 289
Define a numerical subrange............................................................................. 290
Specify a global range for a variable................................................................. 290
Specify a local range for a variable................................................................... 291
Explicitly select a range for a variable .............................................................. 291
Delete a global range or index variable............................................................. 291
Delete a local range or index variable............................................................... 292
- 18 -
Hide or show parameters in User Mode............................................................ 319
Change the input mode of a control .................................................................. 319
- 19 -
Work with the Slider Bar Control............................................................................... 349
Change the orientation of the slider bar ............................................................ 349
- 20 -
Work with Risk Assessment......................................................................................... 373
About Risk Assessment .................................................................................... 374
The Risk Assessment process ........................................................................... 375
How to assess risk ............................................................................................. 375
The Monte Carlo sampling method................................................................... 376
The Latin Hypercube sampling method ............................................................ 376
Select and define a sampling method................................................................ 377
Working with Risk Assessment variables......................................................... 377
Probability distributions.................................................................................... 378
Select variables for Risk Assessment................................................................ 379
Define an assumption with a probability distribution ....................................... 379
Define an assumption with a fixed value .......................................................... 380
Specify an effect variable.................................................................................. 381
Delete a Risk Assessment variable ................................................................... 381
Presenting Risk Assessment results .................................................................. 381
Create a high-low chart ..................................................................................... 384
Create a high-low table ..................................................................................... 385
Create a histogram ............................................................................................ 386
- 21 -
Edit the history of a dataset variable ................................................................. 401
Import the history of a dataset variable............................................................. 402
Export the history of a dataset variable............................................................. 403
- 22 -
Set and lock packages in the SEM Dataset ....................................................... 435
Set and lock versions in the SEM Dataset ........................................................ 436
Allow the simulation user to specify package and version ............................... 436
Disconnect Powersim Studio from SEM .......................................................... 437
- 23 -
Add an action to an event.................................................................................. 460
Change action order .......................................................................................... 461
Delete an action................................................................................................. 461
Delete an event.................................................................................................. 461
- 24 -
Getting Started in Powersim Studio
If you are new to Powersim Studio, the following steps will help you get started creating simulation
models. If you want more detailed instructions on how to create models and simulations, please refer
to the tutorials available in the Learning Lab.
Although the list below gives a linear view of the modelling process, you will soon experience that it
is rather an iterative process where you revisit previous stages many times before you have finished
the model. The steps below are only meant as an overview of the steps required.
Powersim Studio is always opened with a new project (unless you started Studio by
opening an existing simulation project, that is). The project contains one component by
default, and you can add as many components that you need. All components and
views are available in the Project Window that you can see on the left of the
application. Each component can contain many simulations, with various simulation
settings. Each component has one simulation by default.
In the real world, most quantities are expressed using units of measurement. This is
also the case in Studio, where all variables will usually have a unit. To be able to
define the variables, you will therefore have to create the units first. You can always go
back and create more units as you find necessary!
Tip! It is easiest to create and use global units, which are available to all the
components in the project.
You create variables and link them together using links and flows in Constructor
diagrams. The diagrams offer a good visualization of your model, and it is easy to see
the feedback loops that make up the system.
Tip! You can create as many diagrams you want per component. All variables
do not have to be part of each diagram. You can see all your variables in the
Details Window or the Equations View.
- 25 -
4. Define variables and flows
Once you have created the variables, it's time to define them. This is done in the
Definitions property page, available when you double-click the variable (or hit
ALT+ENTER). The variable definition expresses how the variable relates to other
variables in the model. Flows are defined by the flow rate that controls them, and they
are added to the level according to the level's flow definition.
Tip! You will probably often create variables and define them at the same time,
performing this and the previous step simultaneously.
Note! You must always make sure that (continuous) flow rates have a "rate"
unit, that is, it has to have a unit compatible with the level's unit divided by time.
Before you can run your simulation, you must specify the simulation settings to be
used by the component. The simulation setup is essential to make your simulation
behave the way that you want to. The time horizon of a simulation will vary with the
system your are studying. If you are studying a human population, as an example, your
time horizon will probably be about a century or two, with a resolution of a year or
two. If you are studying the life cycle of a product, however, you are more likely to
require a time horizon of a few years, with weeks or months as the time step.
It is not very useful to run a simulation unless you can view the results of your
simulation while it runs. You can use auto reports and controls to display the
simulation results. You have time graphs, charts, tables, slider bars, and gauges at your
disposal for displaying simulation results.
In many cases you also need to provide input for your constants while the simulation
runs. This is also achieved by the use of controls. You can create buttons or sliders as
tools for data input.
When your simulation behaves the way you want to, it's time for the final touch. Add
navigation to your simulation by the use of hyperlinks and bookmarks, and add
documentation to your model diagrams using freeforms and frames with text. If you
need to further document your simulation, you can create your own help system in
HTML that can be started from the project.
It is often useful to be able to compare a simulation run to data from other simulation
runs. This is possible in Studio by using reference parameters and reference data. You
can also save a simulation run and activate it again later.
- 26 -
9. Set up the Presentation Mode
Finally, you can use the Presentation Mode to present the simulator interface you have
created to the user. The Presentation Mode removes all the development-related tools
and buttons, and displays only the simulator itself.
You can use the Presentation Mode as a "simulation browser," which makes your simulation easily
available for your end-users.
- 27 -
What's New in Powersim Studio 2003?
Powersim Studio 2003 contains a range of new features and functionality that makes your simulations
easier to create and more powerful to analyse. The most important features are described below. You
can also read a brief listing of the new features and functionality.
Risk Assessment
Studio 2003 now includes the Risk Assessment task — one of the four tasks earlier available in
Powersim Solver. Factors that are external to your own organization, such as the inflation rate, or
other values that are difficult to determine, represent risk factors if they seriously affect the results
from your simulation. Through the Risk Assessment task in Studio, you can now investigate how
changes in these assumptions affect your results. The result of such a simulation is the likelihood of
achieving a certain result. You can also use Risk Assessment to find variables that are leverage points
for improving performance.
The Risk Assessment task let you analyze the sensitivty of your model.
Hierarchical Models
With the introduction of model hierarchy, Powersim Studio 2003 allows you to divide your
simulation model into smaller submodels that hide away unnecessary implementation details. As each
submodel can contain its own diagram book, modelling these submodels is just as easy as creating
any other model. In addition, submodels can be created from components in any simulation project.
This makes the duplication of existing model structures extremely easy! Utilizing model hierarchy
allows you to make more abstract models, divide your model into subsections that are easier to
maintain and model, and start reusing model structures from project to project.
- 28 -
Hierarchical models allow implementation details to be hidden inside submodels, making your
models easier to read and understand.
Summary types enable you to present your simulation results summarized over a period. You can
display summaries in time graphs and time tables.
The improvements also include optimisations to simulation speed; new and better views for
equations, units, co-models, and ranges; and index variables.
- 29 -
Anonymous flows allow you to gather all the flows from a submodel to another variable (level or
submodel) in your diagram in one common flow. An anonymous flow doesn’t have a flow rate,
obviously, but is a tidy way of showing how the flows run through your system.
When you have finished your simulation model and are working on documenting it, you can copy
model structures directly into your documents as graphics.
Other improvements and new features include improved delete and undo functionality; text search in
tree views, such as the Equations and Units views; the ability to organize your components and
datasets into your own folders; and much more.
Connectivity
Datasets have gone through a complete overhaul since Studio 2001. The user interfaces are now user-
friendlier, and now allow you to drag-and-drop variables from models into the datasets. The internal
workings of the datasets are also vastly improved. The new SAP® SEM dataset allows Powersim
Studio 2003 to run stand-alone and still connect to the SAP systems. You can also create multiple
instances of the dataset within Studio. The user interface for the Spreadsheet dataset is also
redesigned, and makes export and import of data from and to Microsoft® Excel a lot easier.
Studio 2003 introduces the new Studio Dataset, where you can record your time series to internal data
storages inside your simulation project. The Studio Dataset allows you to store data for later use; edit
time series that are used in the simulation manually; share simulation data between several
components; and more.
You have greater control over your external connections in Studio 2003 than in earlier versions of
Studio.
Presentation of simulations
The improvements to time series mentioned above, makes it easier than before to create interesting
presentations of simulation results. Combined with improvements in graphs and tables available in
Studio, this constitutes a powerful means of conveying your message. And you can now even copy
the history of a time graph to the Windows Clipboard!
Hyperlinks can now be made relative, allowing the same simulation interface to be used for all the
simulations within a component.
The introduction of index variables makes it possible for you to create controls that select between the
dimensions of array variables without having to implement this by the use of model variables.
Index variables can be used as parameters by input controls. You can in turn use the index variable to
index the parameter of output controls, greatly simplifying the user interface of complex simulations.
It is now easier to add parameters to your controls and you can even use controls to set simulation
- 30 -
details, such as the start and stop times. Automatic detection of the states of the Switch control
simplifies the creation of buttons that control index variables and logical variables.
Other new features include field codes; rotation of tick labels; bar and step graphs in the Time Graph
control; the possibility to save and load external data (when using datasets) from Presentation Mode;
and much more.
- 31 -
Introduction to System Dynamics
Simulations in Powersim Studio are based on system dynamics. System dynamics is a computer-
based simulation modeling methodology developed at the Massachusetts Institute of Technology
(MIT) in the 1950s as a tool for managers to analyze complex problems. Its primary audience is still
managers, although it has spread widely in academia, where professors and students use it to model
systems from every conceivable discipline ranging from history and literature to biology, physics, and
economics.
The word "dynamic" implies continuous change and that is what dynamic systems do - they
continuously change over time. Their position, or state, is not the same today as it was yesterday and
tomorrow it would have changed yet again.
Using system dynamics simulations allows us to see not just events, but also patterns of behavior over
time. The behavior of a system often arises out of the structure of the system itself, and behavior
usually changes over time. Sometimes the simulation looks backward, to historical results. At other
times it looks forward into the future, to predict possible future results.
Understanding patterns of behavior, instead of focusing on day-to-day events, can offer a radical
change in perspective. It shows how a system's own structure is the cause of its successes and failures.
This structure is represented by a series of causally linked relationships. The implication is that
decisions made within an organization have consequences, some of which are intentional and some
are not. Some of these consequences will be seen immediately while others might not be seen for
several years.
System dynamics simulations are good at communicating not just what might happen, but also why.
This is because system dynamics simulations are designed to correspond to what is, or might be
happening, in the real world.
Solving Problems
When confronted with problems or new situations, we can react to them in several possible ways. The
approach we select is based on prior experience and our knowledge of the problem at hand. As
humans, the most common approach to new problems and situations is to take them apart and
examine their pieces. We do this in the hope that by understanding the pieces we will also be able to
understand the entire problem or situation at hand. We are taught this method in our youth and it is
reinforced almost daily. This approach helps us manage the incredible amount of data, stress,
problems, and chaos that bombards us every day. If we didn't have this ability, all but the simplest
problems would appear overwhelming.
Although this method is a good approach in some situations, it can be inappropriate or even
dangerous under different circumstances. More sophisticated approaches are usually required when
- 32 -
investigating corporate problems. If a company is experiencing a serious threat to its survival, be it
declining market shares or disagreements with the labor union, resources are mobilized to deal with
the problem. The company might already be divided into "parts", such as the accounting department,
the sales department, and so on. Problems affecting the entire company are often blamed on a
department, as when a loss in market shares causes executives to target the sales department for
investigation or punishment. The reason for the problem might seem obvious. The company must be
losing market shares because the salespeople are not selling the product. What is often lost in the
picture is the fact that the sales department depends on many other departments to do its job.
Deficiencies may be in any or all of them. Perhaps the management information services department
has not provided the salespeople with the computer support they need. Or maybe manufacturing has
been suffering from poor scheduling of orders and a backlog has developed. This will in turn make it
harder for the salespeople to sell the product to customers who want an immediate delivery. A number
of factors may be the cause of the problem, which may come to light only when the interactions
among all parts of the corporation, and not just the parts themselves, are examined.
- 33 -
models are brought to light in the context of an organization, we can begin to see where, how, and
why the models diverge. This is the first step in building a shared understanding within an
organization. As long as mental models remain hidden, they constitute an obstacle to building shared
understanding.
System dynamics is closely related to systems thinking. System dynamics was invented to give
managers a tool to understand the complex systems that they were charged with controlling. The
methodology uses computer simulation models to relate the structure of a system to its behavior over
time. Viewed in this way, system dynamics can translate the understanding gained by systems
thinking into a computer simulation model. By experimenting with this prototype of the system at
hand, we can gain further knowledge about the system. System dynamics is capable of creating a
learning environment - a laboratory that acts like the system in miniature.
Even if building a learning organization - an organization with a high degree of shared understanding
and knowledge about how the organization works - isn't the goal, systems thinking can be a very
valuable tool at the outset of a system dynamics study. It helps bring together the people necessary to
the success of the system dynamics study, and get them in a frame of mind that is open to new ideas,
and allow an evolution of mental models. For change to be successfully implemented, people must be
motivated to learn and able to act on what they've learned, and they must be in an environment of
open and honest exchange. Systems thinking, by helping people in an organization see what the
problems are and how their mental models contribute to the problems, sets the stage for a successful
system dynamics study.
When we conduct a systems thinking or system dynamics study, we must base it on existing
information. The information we can use exists on several levels. The largest and most complete
information available to us is our mental information; everything we carry in our heads. In sheer size,
this information database is the largest and most complete available to us. Next is the written
database, which may be smaller by a factor of a hundred or even a thousand. It represents all the
information we have on paper or stored electronically. Finally, we have a numerical database,
representing all information that is stored as numbers and constituting another hundred- or thousand-
fold loss in the amount and richness of the information. Obviously, the place to find the most
complete information about a situation is in the mental database. What we do with that information is
another matter. The human mind is a brilliant storage device, but we do have trouble relating cause
and effect, especially when they are not close in time. In such cases, we cannot reliably predict the
outcome of any but the simplest situations with the simplest inputs. This is one of the reasons why
computer simulation can be a useful addition to the method of systems thinking.
A systems thinking study usually produces causal-loop diagrams to map the feedback structure of a
system, and generic structures to illustrate common behavior. System dynamics takes the information
about a system's structure that normally remains hidden in mental models and formalizes it into a
computer model. The behavior generated by that particular structure is revealed when the model is
simulated. It constitutes a powerful tool for understanding complex problems. Instead of trying to
relate pieces of information in our heads, we can use the computers to formalize our ideas and
assumptions and then simulate them through time. That is the beauty and power of system dynamics
models.
- 34 -
The Tools and Rules of System Dynamics
System dynamics simulations are based on the principle of cause and effect, feedback, and delay.
Some simple simulations will incorporate only one or two of these principles. More sophisticated
simulations will use all three to produce the kind of behavior we encounter in the real world.
Figure 1: A simple causal-loop diagram illustrating connections between price, sales, and unit costs.
Feedback
Feedback is a concept that most people associate with microphones and speakers. A microphone that
isn't properly set up will pick up the sound coming from its own speaker. This sound gets amplified
further by the speaker and picked up by the microphone again. This process keeps going until the
speaker is producing the loudest sound it can or the microphone cannot pick up any louder sound.
If the microphone and the speaker were set up correctly, the system would work linearly. The
loudness of the sound going into the microphone would only affect the loudness of the sound coming
out of the speaker. Because of the misplacement of the microphone, however, the loudness of sound
coming out of the speaker also affects the loudness of sound going into the microphone. Cause and
effect feed back on each other.
- 35 -
This is the general principle of feedback - that some causal chains are linked together so that cause
and effect feed back to each other. This happens everywhere in real world in all kinds of systems,
though people are often not aware of it.
Competitive pricing is one example of such feedback. Competitors set their prices based on our price
based on our competitors' prices.
Infrastructure of network effects is another example. Buyers on eBay are attracted to the large number
of goods available for sale. Sellers on eBay are attracted to the large numbers of buyers. Thus, the
more buyers, the more sellers and the more sellers, the more buyers.
Epidemics are yet another example. Viruses spread when a member of an infected population comes
into contact with someone, who is uninfected, but susceptible. This person then becomes part of the
infected population, and can spread the virus to others. The larger the infected population, the more
contacts, the larger the infected population.
The simple causal-loop diagram presented above illustrates feedback as seen in a price and sales
example. If we used a cost-based pricing strategy, then we could show that as sales increase, the unit
costs for the product goes down. As the unit costs go down, the price can go down. As the price goes
down, the sales go up.
The causal-loop diagram of figure XX shows that the price we charge today will affect what we
charge in the future. A low price will increase sales and reduce unit costs, making it possible to
further reduce price in the future. A high price will reduce sales and increase unit costs, making it
necessary to increase price in the future. This is obviously not the whole story. This structure is only
one part of a larger system and the level of price and sales are also subject to influences from other
variables in the system. But still, this isolated feedback loop is easy to understand.
Feedback relationships can produce a variety of behaviors in real systems and in simulations of real
systems. Figure 2 illustrates four common behaviors created by various feedback loops.
- 36 -
Delays
Not all cause and effect relationships occur instantaneously. Sometimes the consequences of an action
or decision are not apparent until several days, months, or even years after an event has taken place.
Often the relationship between cause and effect is obscured by separation in time. It is difficult to
understand a system when the consequences cannot be seen in close proximity to the behavior. A
child touching a hot stove will immediately understand the consequences of that behavior and will
likely never repeat the mistake. Many decisions have outcomes that cannot be known for years and
may never be linked to early mistakes.
Delays occur everywhere in the real world. A project may for example have cascading side effects
when critical-path tasks are delayed. New investments can have limited "windows of opportunity" for
making a return on investment. Introducing new products or services sometimes has first mover
advantages.
Delays can produce interesting and complex behavior in systems even when those systems have no
feedback and limited cause and effect complexity. To illustrate this let us look at the price and sales
example once again.
Revenue for a product line is determined by multiplying price by sales. So increasing either price or
sales will result in higher revenue, as long as nothing else changes. Figure 3 shows this relationship.
Figure 4: The behavior of the sales, price, and revenue variables. Notice that even though price and
revenue change during the simulation, sales does not change.
However, demand is usually affected by price, though often not immediately. Customers may take
time to adjust their consumption patterns even after a price change. This may be because they have
imperfect information about alternatives, or some infrastructure is temporarily forcing them to a
- 37 -
specific option.
For example, in the early 1970s, gas prices around the world increased quickly and substantially. Car
owners couldn't reduce their demand for gas instantly - they owned an expensive asset (i.e., their big
car with high gas consumption per mile) that couldn't be immediately replaced. Also, a lot of travel
that car owners do isn't optional, for example work commute. Moreover, not many cars with low gas
consumption per mile existed in the early 1970s. It took consumers years before they could adjust
their consumption patterns.
This linkage between price and sales is now similar to the original link we saw in the causal-loop
diagram, except that we have introduced a delay, as shown in Figure 5.
Figure 6: When a sudden change in price occurs, it causes an immediate increase in revenue.
Because of the delay involved, sales will not decrease immediately. After a certain time, however,
sales will drop, resulting in a decrease in revenue as well.
Even though this system contains no feedback and only three cause and effect linkages, the behavior
of the system is already becoming complicated. This is due to the delay in the system. This is also a
good example of how structure creates behavior. Through one additional delayed linkage in the
system, the results are vastly different.
Understanding the concepts of cause and effect, feedback loops, and delays provides a good
foundation when beginning to uncover the intricacies of a system's nature - what elements are acting
on other elements and whether the interaction is positive or negative. However, feedback loops alone
do not indicate what the entire system's behavior will be. It is hard to anticipate the behavior of a
system from a causal-loop diagram representing the feedback structure of a system alone. Such
diagrams are useful when it comes to isolating the feedback structures. When creating a system
- 38 -
dynamics simulation, however, we represent the feedback structures by the use of levels and flows.
Levels and flows are the main building blocks of computer simulation models in Powersim Studio.
Every element in feedback loops, and therefore every element in a system, is either a level or a flow.
Levels are accumulations and flows represent the changes to these levels. Flows fill up or drain the
levels, much as the flow of water into a bathtub fills it, and the drain at the other end (another flow)
empties it. This action of flows being accumulated in levels is the cause of all dynamic behaviors in
the world.
Levels
Things accumulate or pile up around us every day. Many managers deal with the issue of inventory,
one of the most important accumulations in many companies. System dynamics refer to such
accumulations as levels. Levels give a snapshot view of reality. Their values tell us how the system is
doing at any given point in time. If time suddenly stops, levels would remain and be observable and
measurable. Levels can best be understood as the "nouns" of a system; they are somewhat static or
inactive. Levels have several distinct characteristics. They have memory, which means they do not
change instantaneously. They do change, of course, through the actions of flows, but it takes time. If
our inventory is 6,000 units and we want to increase it to 7,500 units in anticipation of an increase in
demand, we must allow some time for those additional 1,500 units to be placed in our warehouse. A
delay is involved in changing any level, be it inventory or the amount of water in a bathtub. A level
may seem to be changing instantaneously, but there is nonetheless a delay, no matter how small.
Flows
If levels are the nouns of a system, flows are the "verbs". Flows are action variables, creating
dynamics when they accumulate in levels. Dynamics are not created by feedback loops, even though
it may seem that feedback (transmission and return of information) is causing the changes to occur.
Dynamic behavior can occur with absolutely no feedback, because it is simply the result of flows
accumulating in levels. Without flows, levels would never change, and there would be no dynamic
behavior. Thus, flows represent the system's activity and are dependent on the values of the levels.
Because levels are increased or decreased only by their associated flows and flows depend on levels,
an alternating level-flow structure must exist for all systems.
- 39 -
organization, spoken or unspoken, implicit or explicit, that provides the setting for decisions.
We can illustrate this idea easily with the concept of inventory. Companies that must keep inventory
have specific rules for when more inventory is ordered. No matter who orders the inventory, the
decision of when and how much to order will always be the same in the sense that it fulfills the
inventory policy. If the policy is that inventory must not drop below 6,000 units, and it takes four
weeks to receive orders from suppliers, decisions regarding inventory can be made accordingly.
When problems with inventory develop - there is too much or too little inventory or the amount has
fluctuated wildly in the past six months - a common reaction is to look for the person who has been
"ordering the wrong amount". This can be described as a reaction-driven or "open-loop" approach.
However, it is often more appropriate to examine the pattern of behavior and compare it to a desirable
pattern. If the inventory pattern is essentially chaotic while the desired pattern is a flat line, we must
make changes to the structure - the policies - of the organization, not just the decisions.
Decision-making Process
Decisions must always be based on observable variables. In a system dynamics model, this means that
decisions must be based entirely upon levels, as flows are never instantaneously observable and
therefore can never affect instantaneous decision-making. In the example above, the decision on how
much inventory to order must be based on the present value of the level of inventory. Levels can
represent the actual state of the system at a given point in time (current inventory) or the desired state
of the system (desired inventory). When there is discrepancy between actual and desired conditions,
corrective actions are usually taken to move the actual state closer to the desired state.
The first attempt to solve a complex problem rarely succeeds. This is not surprising, given the
complex cause and effect relationships and feedback loops that exist in most systems we are in
contact with. Usually, corrections change the system and lead to a total redefinition of the problem.
Decisions are attempts to move the system toward our goals. Actual conditions are continuously
compared to the desired conditions and action is taken according to the discrepancy between them.
This is an iterative process. In the context of a corporate model, decisions could be how many orders
to submit to the supplier to replace inventory, how many workers to hire, or when to replace capital
equipment.
A decision to replenish inventory should be based on the present level of inventory (a level) and not
on the rate of sales (a flow). Levels should be the only inputs to decisions; decisions control the flows
to and from levels, and the flows determine the change in the levels. As Jay Forrester states it: "Only
rates [flows] resulting from decisions change levels. Only levels control decisions and rates of flows.
In other words, decisions control all processes of change". Decisions are governed by policies.
Therefore, the way decisions control change is through policies. Flows are defined by equations, and
these equations are statements of system policy. Policies describe how and why decisions are made.
Specifically, it is the policy statement that attempts to move the system toward a goal. It provides the
connection between information inputs and the resulting decisions stream.
Policies may be informal, such as a consequence of habit, intuition, personal interest, and social
pressures and power within the organization. They can also be explicit, with a formal awareness of the
reasons of action. In the latter case, participants know exactly what policies are guiding their
decisions and are able to anticipate the actions of others in a similar situation. Informal policies can be
hazy, but the system dynamics model attempts to make them explicit. In such a model, informal
policies are treated with as much concern as explicit policies. They are considered equally important
in understanding the behavior of a complex system. To truly capture the problematic behavior of a
system, a system dynamics model must represent the basic policy structure of that system. The model
can then be used to try out various policies before implementing them in the real system. In this way,
effective policies can be developed to provide a proper guiding framework for the average manager.
The ultimate goal, if real change is sought, is to find the optimal mix of policies that create the desired
behavior (smooth growth of revenue, constant inventory, etc.), no matter who is in the decision-
- 40 -
making process.
Corporations can be designed so that only highly skilled professionals will be able to navigate the
company through the ups and downs of the business world without creating the symptoms of the
corporation's problems. However, with improved policies and structures, managers will have the
tendency to make correct decisions because the structure has been built with an autopilot in mind
(goal-seeking feedback loops, for example). Just as non-pilots in crisis situations have been able to
land planes because of the design of the plane, so can managers more easily "pilot" a well-designed
company.
This doesn't mean that every manager should be thinking in terms of corporate design instead of
corporate management. The people who should be involved in corporate design are those who have
the power to truly change the structure of the company - the executives. According to Forrester,
corporate executives should be corporate designers. They should create the necessary policies so their
managers will be able to make good and informed decisions. Changing the structure - the policies - of
the corporation can eliminate problematic behavior of the corporation, and the only people in a
position to do so are the executives.
In the previous pages we have introduced the concepts and principles of system dynamics. For many
of us, using these concepts represents a new way of viewing the world around us. By using Powersim
Studio, we can formalize these concepts and views of the world into a computer simulation model.
Let us take a closer look at the stages of the modeling process. Although we will go through these in a
certain order, we should always keep in mind that creating simulation models is an iterative process.
Usually, when creating a model, we will not create it in a linear fashion. Instead, we will advance one
step, then take three steps back and reevaluate everything we've already done.
This is the art of modeling: it is subjective, frustrating at times, and in the end we can never say that
the model is "correct" or even finished. It is simply one representation of reality, built to explain a
particular problem. You may find that you learn more in the process of creating the model than in
manipulating it after it is finished.
Problem Definition
The modeling process begins with defining a problem. The problem definition is the keystone of the
entire activity. Although it might sound like the easiest part, it is not enough to have a vague notion
about the problem behavior. Defining the problem is essentially defining the purpose of the model.
The problem should therefore be defined as precisely as possible. This definition is the basis of all our
future efforts and our guide in decisions concerning boundaries and validity of our model. The
narrower our focus, the easier it will be to resist the temptation to overdo the structure.
Numbers are a useful tool in this stage of the process. If we can use numbers to define the problems,
such as real inventory data to illustrate the problem of inventory fluctuations, we will be better
equipped to define the problem. If no real data are available, it is extremely useful to draw the shape
of the behavior against time. If the problem concerns the interactions of variables, such as the effect
of seasonal fluctuations in demand on the level of inventory, it is necessary to map the relevant
variables against each other. This way we can build an understanding of how each of the various
variables affects each other. We should always keep in mind that system dynamics models are not
concerned with the behavior of individual variables. The main focus is on how each variable interacts
with the other variables to produce the system's behavior.
- 41 -
Model Boundaries
Given the problem definition, we can start to set the boundaries of the model. Creating boundary
diagrams can be useful at this stage of the process. Such diagrams will help us identify the variables
to include in the model, and whether these variables will be endogenous or exogenous. A boundary
diagram is shown in Figure 7.
Figure 7: The boundary diagram illustrates the scope of the model. Exogenous variables are usually
parameters to the model, while the behavior of endogenous variables are generated within the model.
Endogenous variables are those whose behavior is generated within the model. Exogenous variables
are essentially parameters to the model. Their values come from outside the model, and they can
usually be considered constant. The model should only contain the structure that is required to
generate the problem behavior. We should always attempt to eliminate structures that don't contribute
a significant difference to this behavior. Likewise, if the behavior of the model changes wildly when
parameters are changed, the model is not generating the behavior internally. It is simply too
dependent on outside influences. In such cases the model boundaries should be extended to make
room for these exogenous variables to become endogenous.
- 42 -
problem.
When we are comfortable with the collected data, we must identify the key concepts and components
to include in the model. It is important to refer back to the problem definition for the model. This
helps us structure our information, and to start generating names and units of measurement for
variables. The list of variables usually becomes very long. From this list, we should identify primary
system variables. Again, we can use the problem definition and boundaries of the model to identify
these primary system variables. We can throw out the variables that are irrelevant to the purpose of
the model and set aside the variables that we are not sure of. The latter ones might become helpful
later, when we arrive at the stage of model design.
Model Formalization
With the conceptual design in place, we can start creating the Constructor diagrams and defining the
equations of the model. Although Powersim Studio takes care of the calculus, we need to relate the
variables in much the same way as we would create cell expressions in a spreadsheet. The units of
measurement for each variable will now provide an instant check for you, since Powersim Studio
requires the units of measurement to be consistently defined throughout your model.
If we look at a simple inventory model, we would probably have a 'Production Rate' (a flow) filling an
'Inventory' (a level). The flow rate would be dependent on the inventory level, since production will
depend on how much inventory is available. In addition, the flow would also be dependent on two
constants, namely the desired level of inventory ('Desired Inventory') and the time delay in adjusting
the production rate ('Inventory Adjustment Time'). The units of measurement of such a system could
be 'widgets' for 'Desired Inventory' and 'Inventory', and 'weeks' for 'Inventory Adjustment Time'. The
equation defining 'Production Rate' (the flow rate) must combine the variables it depends on in a form
that yields a rate equation with the unit 'widgets/week', as shown below.
('Desired Inventory' - 'Inventory')/'Inventory Adjustment Time'
In addition to specifying the equations, this stage also involves choosing parameter values. We should
always keep the real system in mind when we choose constants. We might already know the values
from the system data we collected at the beginning of the study, or we might have to estimate
reasonable values. The key is to be consistent. Initial values of levels should also be realistic for the
particular system. In the beginning, however, it might be a good idea to stick to round numbers, to
make it easier to evaluate the outcome of the model.
Sometimes we find it difficult to relate variables directly using strict, mathematical equations. In these
cases it is often better to create a graph that expresses the relationship between the variables, and use
graph functions available in Powersim Studio to define them. Graph functions are most useful when
representing nonlinear relationships between variables. These graphs are also specified in this stage.
- 43 -
Simulation
We are now ready for the simulation stage of the system dynamics modeling. When we have put our
conceptual model into the computer using Powersim Studio, and all the variables and equations are
well defined, we can simulate the model and view its behavior over time. It is often useful to try a few
"mental simulation" exercises before simulating the model. We should try to imagine what the model
should do when it is simulated. When the model is simulated, we will see whether the actual behavior
differs from our expectations - it most probably will - and thereby have a starting point in figuring out
why. It could be that the structure of the model is in error. It could be that we forgot to take certain
variables into account and that our expectations of the behavior were wrong.
When we simulate the computer model, we must set up appropriate simulation settings for the model.
The two most important are the time horizon and the time step. The time horizon represents the period
of time we want our model to simulate. It is specified by a start and stop time given relative to the
selected calendar. The time horizon will vary from model to model, and we will usually select it so it
matches the time frame of the problem behavior. The time step represents the time interval that the
simulation progresses for each calculation. The shorter the time step, the more calculations Studio will
perform, and the slower the model will run.
Once we have determined the time horizon and time step of the simulation, we will be able to
simulate our model under different conditions and observe the results. To truly understand the model,
we must relate the structure we have created to the behavior that results from simulating the model.
If we cannot get the behavior we want we must go back and reexamine the structure of the model and
try to determine why it is creating the unwanted behavior. The causal-loop diagram is often useful in
this regard. When we understand why the model generates a certain behavior, we can experiment with
changes in the structure to generate the actual problem behavior as we described it in the early stages
of the model creation. When the model adequately represents the real problem, we can use it for
policy analysis and experimentation. We now have a mini-laboratory in which to simulate the effects
of various policy changes before implementing them in the real system.
Powersim Studio is a modeling environment based on the science of system dynamics. Studio allows
us to model systems - with all their cause and effect relationships, feedback loops, and delays - in an
intuitive graphical manner. Symbols representing levels, flows, and "helper" variables (so called
auxiliaries) are used to create graphical representations of the system in Constructor diagrams. Flows
and information links represent relationships and interconnections. The entire structure of a system,
no matter how complex, can be represented in Studio by the use of these variable types and
connections.
- 44 -
Figure 8: When integrating a function, the area underneath the function is measured. This is done by
dividing it into equal-width partitions and summing up the area of all the partitions.
When creating a simulation model graphically in Studio, connecting the variable symbols generates
the integral (flow) equations. Every variable in the model is defined by an equation, in the same way
as cells in a spreadsheet are defined.
In Studio, boxes represent levels. Double arrows represent the flows, and the flow is controlled by a
flow rate. The flow rate is defined in the same way as auxiliaries (see below). Figure 9 shows a simple
model when created graphically in Studio.
Figure 9: A simple model created in the graphical modeling language of Powersim Studio.
Notice the cloud-like symbol to the left of the first flow and to the right of the second flow. These are
the source and sink of the structure, respectively. The cloud symbol indicates infinity and marks the
boundary of the model. For instance, in the simple structure illustrated in the figure, the level is the
'Workforce', measured in people, which is increased by the 'Hiring Rate' (flow) and decreased by the
'Firing Rate' (flow). The clouds tell us that in this model we are not concerned with where the hired
people come from or where the fired people go. That information is beyond the model boundaries.
If we were interested in including this information, we could add another level to the left of the hiring
rate and one to the right of the firing rate extending the model boundary. This is shown in Figure 10,
where we have the hiring rate draining a level of applicants, and the firing rate adding to a level of
former employees.
Auxiliaries
While it is possible to create an entire model with only levels and flows, Studio has a few more tools
to help us capture real-world phenomena in a model. To achieve a certain level of detail or to aid in
the formulation of flow rate equations, it is sometimes necessary to model a variable as an auxiliary.
In Studio, a circle represents auxiliaries, as shown in Figure 11.
- 45 -
Figure 11: Auxiliary
An auxiliary is used to combine or reformulate information. It has no standard form; it is an algebraic
computation of any combination of levels, flow rates, or other auxiliaries. Although auxiliary
variables may appear to be accumulations, they have no memory, unlike levels. Auxiliaries are used
to model information, not the physical flow of goods, so they change with no delay, instantaneously.
They can be inputs to flows, but never directly to levels, because flows are the only variables that
change their associated levels. Levels, however, can be inputs to auxiliaries. Note that flow rates and
auxiliaries are defined in exactly the same manner. The difference is that the flow rate is connected to
the flow valve, and thereby controls the flow directly.
Constants
Constants are, unlike ordinary auxiliaries, constant over the time period of the simulation. A diamond
represents these constants, as shown in Figure 12.
Information Links
Connections are made among constants, auxiliaries, and levels by means of information links. These
links appear as thin connectors in the Constructor diagram, as shown in Figure 13.
- 46 -
dependence of the flow on the level, as well as the obvious dependence of the level on the flow, as
seen in Figure 14.
Figure 14: A closed feedback loop representing the interest earned from an account in a bank.
For a Constructor diagram to be consistent, the equation that defines a variable must contain all the
variables that are linked to the variable itself. In the simple model structure in Figure 14, this means
that for the model to be consistently defined, the definition of Interest must include Account and
Interest Rate. In this example, the definition of Interest is simply
'Interest Rate' * 'Account'
Creating a Model
The previous chapters have introduced you to the field of system dynamics and the principles behind
building computer simulation models. To help you create your first simulation models we have
created a Learning Lab that will guide you through the steps of modeling and simulating a model. The
Learning Lab also contains finished models that you can study.
- 47 -
Import Models From Constructor 2.51
To import a model from Constructor 2.51:
1. Click Open on the toolbar.
2. In the Files of Type field, select Powersim Simulation Models (*.sim).
3. Select the model you want to import and click Open.
There are big differences between Powersim Studio and earlier versions of Powersim Constructor.
Some parts of the models will therefore not be converted correctly. The list below summarizes these
conversion issues.
Diagrams
All modeling objects, such as variables, links and flows are converted and displayed. However, some
objects, such as the Command Button, are not converted. You must in these cases use the new
controls to create a new user interface for your simulations.
With few exceptions, model variables and their definitions are converted. In most cases, this means
that you should be able to run your simulation immediately after converting the model.
Functions
The function groups listed below are not converted, as they no longer exist in Studio. You will be
warned at the end of the model conversion if your model contained one or more of these functions.
If any conversion function contains the % (percentage) operator, the requirement of the new
- 48 -
conversion functions are not satisfied unless additional parameters are given. Any variable
containing a conversion function where the % operator is used in the parameter (e.g. ROUND
(A*5%)), the variable will become undefined in Studio. You must manually specify the
resolution parameter to define the variable properly.
Functions with side-effects (such as ASSIGN, SHIFTLIF, etc.).
Functions working on complex numbers. In Constructor 2.51 you could emulate complex numbers
by using arrays containing the real part in the first element, and the complex part in the second
element. In Studio, complex numbers are a unique data type, and functions will handle complex
numbers in a much more advanced way. The complex functions from Constructor 2.51 are
therefore obsolete in Studio. If your model used complex numbers (modeled as arrays), you should
go through it after converting it and use complex numbers instead. (The syntax for creating
complex numbers is: (<real>, <imaginary>).)
Functions that were obsolete in Constructor 2.51 (having names with the extension '__OLD').
Functions connected to the Network Gaming Object, such as SELECTDECISION(),
STRATEGICMODE(), etc.
Arrays
Some of the array functionality that was present in Constructor 2.51, is not available in Studio. The
most significant difference is that constrained expressions, as mentioned above, are not supported.
However, the FOR and IF functions can be used to replace these expressions.
You were not always required to include array subscripts when using arrays as input parameters to
functions in Constructor 2.51. This has changed, and when converted, Studio inserts a FOR function in
these cases. However, you might experience problems when this is the case, so if your model uses
unsubscripted arrays, please check your variable definitions before running the simulation.
The syntax for defining and indexing arrays has also changed a bit. When creating arrays, you should
now use the following syntax:
aux A = {1,2,3,4,5,6}
To find elements in arrays, you can still use the SCAN* and LOOKUP functions.
Constrained Expressions
Constrained expressions (expressions containing the keywords WHEN, BUT, OTHERWISE, etc.) are not
supported in Studio. The expressions are, however, converted to expressions that will work in Studio.
The new expressions are built up using nested IF functions combined with the FOR function.
Dimensions
The dimensions defined for a variable, also when using named ranges, will be converted to the new
Studio model. Because Constructor 2.51 in some cases didn't calculate ranges correctly, you might
experience problems for some range definitions. If you run into trouble after converting models
containing this kind of dimension, please check your dimension definitions. The table below shows a
few example of range errors in Constructor 2.51.
- 49 -
Interpretation
Dim. Expression Constructor 2.51 Studio
(-3)..6 3..6 -3..6
(-3+2)..3 2..3 -1..3
Index(2)..4 2..4 Invalid
Units
In Constructor 2.51, the unit field was merely a text field that had no impact at all on the variable
expressions. In Studio, units are an integral part of the variable expression and are computed at run
time. To avoid causing unit inconsistencies in the new model, units from Constructor 2.51 are
therefore not imported. Instead, Studio will automatically detect the unit based on the variable
definition. The contents of the unit field is moved to the variable's note field.
Data Types
Studio supports four data types: INTEGER, REAL, COMPLEX, and LOGICAL. None of these were
present in Constructor 2.51. When converting the model, Studio tries to adapt the data type of the
variable to the variable definition.
Constructor 2.51 models that performed calculations on complex numbers must be revised manually.
Constructor 2.51 emulated complex numbers as (real) arrays with two elements. In Studio complex
numbers are a data type, and you should revise your model to implement complex numbers correctly.
Complex numbers are now created using the syntax (<real>, <imaginary>). For information
on whether a function accepts complex numbers as input parameters, please refer to the function's
reference sheet.
When you convert a model from Constructor 2.51 to Studio, you will have the option of turning data
type conversion off. If you choose to turn off the automatic type conversion, you will manually have
to go through your model to change the data types of the various variables.
Note! Some functions might require that the input parameters have certain data types in order
to work. Most notably is the IF function, that requires the first parameter (the condition) to be a
LOGICAL variable.
Notes
If the model conversion runs into problems when converting a variable expression into the new
format, it will add a note in the note field of the variable, notifying you about the problems.
- 50 -
Import Models: About Diagram Conversion
All variable symbols, links, and most other diagram objects are converted from Constructor 2.51 to
Studio. In some cases, however, you will be required to go through the model and create new input or
output objects.
Note! While you could specify the Keep Value property for a single array element in
Constructor 2.51, Studio requires the entire array (the variable itself and not the element) to be
permanent. When the model is converted, the entire array will therefore become permanent.
Report objects in Constructor 2.51 could contain field codes. These field codes were substituted by
the text information they represented in the diagram. Powersim Studio doesn't support field codes,
and field codes from Constructor 2.51 will be displayed as if it were normal text. In the converted
diagram this will appear as a code enclosed in curly brackets, like '{Par:Global}'. In these
cases, edit the text manually and remove the field codes.
- 51 -
Simulator Layout
A typical simulator layout in Constructor 2.51 utilized control buttons, several windows that
displayed various parts of the diagrams, etc. The windows could be customized to avoid resizing and
scrolling, among other properties.
Although you can still open several windows for the same diagram book in Studio, you can now
create several diagrams for each model. This will, to an extent, eliminate the need of having several
windows for the same diagram. Moreover, the command button is no longer present in Studio.
Because of the difference in the capabilities and uses of the two versions, the window and simulator
layout is not converted with the model. You should go through your model and utilize the new
features in Studio to redo the simulator layout as you please.
Tip! You can use the new Presentation Mode to create simulator interfaces in Studio!
Model Information
The model title, author and summary are transferred to Project Information for the new simulation
project. Information about document dates for creation and last saving are not transferred to the new
component.
When converting models, a lot of information concerning simulation times, ranges and unit settings
and so on, also needs to be converted.
Ranges
All ranges are converted into global ranges in Studio. In some special cases, range definitions can fail
to convert correctly. Models containing such range expressions are rare, so this should not pose a big
problem. The only error would be that the variable(s) defined by the range expression will be
undefined in the converted model.
Units
In Constructor 2.51, units were not taken into account when calculating the simulation results. In
Studio, however, the units are used in the calculations. The unit names that were defined for a model
in Constructor 2.51 will be included in the Global Units list in Studio, but they will remain undefined
until you define them properly.
Data Types
Studio introduces data types for variables. The data type defines the value characteristics of the
variable, and restricts what operations are valid for them. The data types are: LOGICAL, INTEGER,
REAL and COMPLEX. When converting models, Studio attempts to adapt the types of sub expressions
according to the way they are used in variable expressions. For example, a numerical value that is
used as the condition parameter in the IF function will be converted into a logical value by comparing
- 52 -
its magnitude to the value of 0.5.
Definitions using complex numbers in Constructor 2.51 (or rather arrays interpreted as complex
numbers) should be reviewed after converting the model.
Passwords
View and Edit passwords are transferred to the converted project. Further, you will be prompted for
passwords when you start the model import.
Co-models
Studio does not support co-models as Constructor 2.51 did. Information about co-models, and the co-
models themselves are therefore not converted.
- 53 -
The ASSIGN function took two input parameters. The first parameter would be assigned the value of
the second.
The definition of the model above would be:
aux A = ...
aux B = ...
aux C = ASSIGN(A, B)
The result of the simple model above was that the variable A was assigned the value of the variable B.
Studying the diagram, this is not the behavior we would expect. Rather, we would expect the value of
C to be dependent on A and B, not the value of A to be dependent of C and B.
In Constructor 2.51, the ASSIGN function could be used to assign a new value to both constants and
levels. It is also worth noticing that the ASSIGN function didn't take effect immediately. The
assignment was made effective from the start of the next time step in the simulation. Also, when the
assignment had been performed, the new value of A was not dependent on the integration method.
In addition, the auxiliary C is defined with the Zero Order or Zero Order Immediate integration
setting (available on the Integration property page in the Properties dialog box). This structure
behaves correctly regardless of what integration method is selected for the component. Note also that
using zero order integration makes the value of C independent of the selected time step.
- 54 -
Note! If you select Zero Order integration, the level A will be changed at the start of the next
time step (similar to the effect caused by the old ASSIGN function). If you select Zero Order
Immediate, the level will be changed at the start of the current time step. Thus, if you are
creating an "assign" structure that reacts to a condition, the first setting will cause the level to
be changed the time step after the condition becomes TRUE, while the second setting will cause
the level to be changed the same time step that the condition becomes TRUE.
If there are other flows connected to the level A, then these should be made dependent on C, so that
they become zero when the "assign" occurs.
The ASSIGN function in Constructor 2.51 was often used in combination with the IF function. This is
also possible with the model structure presented above. If, say, we want the assignment to occur 10
days after the start of the simulation, C would be defined as:
aux C = IF(TIME =STARTTIME+10<<da>>,(B-A),0)
The definitions are shown below (the example assumes the arrays have 10 elements):
aux A = ... (defined as an array with 10 elements)
aux B = ...
aux C = SUM(i=1..10; IF(cond(i), ASSIGN(A(i), B), 0))
The SUM function was often used to "simulate" the FOR function that is now available in Studio. The
expression cond(i) denotes a condition for each array element of the array A. Or to put it in a different
way, it is a condition deciding when the individual elements of the array A should be assigned the
value of B.
This structure can also be modeled in Studio. The model structure is shown below.
- 55 -
Only one minor problem is left to resolve. In some cases, you would maybe use the value of C in the
Constructor 2.51 model in another equation. To solve this, you would have to add a variable, say D, to
your Studio model, and add a link to it from C. Since the return value of the ASSIGN function was B,
the result of the SUM function in the 2.51 model above can be expressed in the Studio model as
aux D = ARRSUM(C)
When creating models, we often face the fact that an array structure not only influences a variable at
its own layer (having the same index), but also influences elements with other index values. In
Powersim Constructor 2.51, constrained expressions made it possible to create rules for how this
connection between different dimensions behaved. Using constrained expressions, you could treat the
various elements of an array differently, based on the index of the element.
Constrained expressions are no longer part of Studio, but you still have the capability of treating each
array element differently. In Studio this is achieved using the CONCAT, FOR, IF, INDEX, and LOOKUP
functions, rather than the constraint operators of Constructor 2.51 (WHEN, BUT, OTHERWISE, etc.).
This produces variable expressions that are easier to read, and are tidier to work with.
Example 1
A typical constrained expression in Constructor 2.51 is shown below. The definition required the
dimension of the variable to be defined as 'i=1..3', and the variables A and B to be defined.
A*B WHEN i<= 1 BUT A/B OTHERWISE
Using the FOR and IF functions, this can be achieved by the following expression in Studio. Rather
than including the index variable i in the dimension definition of the variable, it is now included in the
FOR function instead.
FOR(i=1..3 | IF(i<=1, A*B, A/B))
Example 2
If you have a model that contains both array structures and scalar variables, you might need to have
them interconnect. The example below shows how to feed scalar variables into an array variable, by
the use of indexed variables and guards in Constructor 2.51.
Say you have a model where different divisions work towards selling software products. The
divisions work in such different ways, that the model does not use arrays to represent sales. But when
it comes to presenting for example sales as economical figures, we want to use arrays for the different
divisions. Four scalar variables will feed their values to every element of the array variable. The
model is shown below.
- 56 -
Connecting scalar and array variables
The equation for Sales_per_Division is shown below. In Constructor 2.51, you needed a constrained
expression to create the array. In addition, the range 'Sales' must be defined as 'Resellers, Direct,
Salesmen, Consultants', and the dimension of the variable had to be set to S=Sales.
aux Sales_per_Division = Sales_by_Resellers WHEN S=Resellers BUT
Direct_Sales WHEN S=Direct BUT
Sales_by_Salesmen WHEN S=Salesmen BUT
Sales_by_Consultants WHEN S=Consultants
Alternatively, you could exchange WHEN with '|'and BUT with ';'.
In Studio there is no longer a need to use these constrained expressions, since an array can contain
both literals as well as function expressions and variables. Thus, you can simply enter the equation
aux 'Sales per Division' = {'Sales by Resellers', 'Direct Sales',
'Sales by Salesmen', 'Sales by Consultants'}
Note! You can create long names in Studio including spaces. Just remember to enclose variable
names containing spaces within '.
- 57 -
functions in Constructor 2.51.
The model structure below, created in Studio, performs the same conditional, circular shift as the
SHIFTCIF function shown above. The definitions works on an array with ten elements, but you are of
course free to create as many elements you wish.
In addition, the two variables Shift and Cycle are defined with the Zero Order or Zero Order
Immediate integration setting (available on the Advanced property page in the Properties dialog box).
This structure behaves correctly no matter what integration method is selected for the component.
Note also that using zero order integration makes the value of C independent of the selected time step.
Note! If you select Zero Order integration, the shift will occur at the start of the time step after
Condition becomes TRUE. If you select Zero Order Immediate, the shift will occur at the start
of the same time step that Condition becomes TRUE.
- 58 -
A Model Equivalent of the SHIFTLIF Function
The illustration below shows how the SHIFTLIF function could be used in Constructor 2.51. While the
SHIFTCIF performed a circular shift (the last element was inserted at the start again), the SHIFTLIF
function inserted zero at the beginning of the array.
The model structure below performs the same conditional, linear shift as the SHIFTCIF function shown
above. The structure works on an array with ten elements, but can of course be expanded if necessary.
In addition, the two variables Shift and Cycle are defined with the Zero Order or Zero Order
Immediate integration setting (available on the Advanced property page in the Properties dialog box).
This structure behaves correctly no matter what integration method is selected for the component.
Note also that using zero order integration makes the value of C independent of the selected time step.
Note! If you select Zero Order integration, the shift will occur at the start of the time step after
Condition becomes TRUE. If you select Zero Order Immediate, the shift will occur at the start
of the same time step that Condition becomes TRUE.
Tip! It is also easy to add a new value at the beginning of the array, in the first element. Simply
add a discrete inflow named 'Shift In' containing the new value, and edit the flow definition in
Array to + SUFFIXZERO({'Shift In'}).
- 59 -
A Model Equivalent of the SHIFTLCNT Function
The SHIFTLCNT function in Constructor 2.51 was a bit more complicated than the SHIFTCIF and
SHIFTLIF functions. First, it allowed you to specify the element that was shifted into the array.
Second, it allowed you to shift the array in both directions, and third, it allowed you to shift the
elements by a real number, and not only an integer number or places in the array. This was achieved
by performing interpolation between the elements and finding their new value based on this
interpolation. Creating a model equivalent that allows you to shift array elements a decimal number of
places is a difficult task, and one that we will not cover in this topic. However, the rest of the
functionality found in the SHIFTLCNT function is covered by the model structure below.
A SHIFTLCNT structure from Constructor 2.51 is shown below.
The value of Cnt decides the number of places to shift the array elements (a negative number
indicates a left shift), Array is the array to shift, while Input specifies the value of the new elements
that are shifted into the array.
The model structure below performs identically to the SHIFTLCNT function (with the exception that
Cnt must be an integer). The equations are shown below.
- 60 -
) //IF
) // FOR
aux 'Shift Out' = Array
The two variables Shift and Cycle are defined with the Zero Order or Zero Order Immediate
integration setting (available on the Advanced property page in the Properties dialog box). The
definitions above are independent of the time step.
Tip! By changing the Cnt variable into a constant, you can manually change the value using a
input control.
The important part of the model structure is the Shift In variable. It uses a FOR function to create the
new array, and shifts the elements accordingly. It uses twodifferent structures to determine the values
of the new cells. If Cnt is positive, the first check (if i <= Cnt) is TRUE, and the according elements
are given the value of Input. However, if Cnt is negative, the first check will always be TRUE.
However, when the array is indexed with values that are outside the dimension of the array, the
elements will return NAN. This happens for the Cnt last elements in the array. Thus, by checking
whether the indexed elements are NAN or not using the ISNAN function, the last elements can be
replaced by the value of Input.
Tip! If you feel that the new diagram becomes cluttered by the introduction of the new model
structure, you can simply remove it from the diagram by using the Exclude capability of Studio,
which allows you to exclude variables from the diagram without deleting them.
- 61 -
The function causes the controlled variable, in this case Target, to never exceed the value interval
given by the two variables MinVal and MinVal. The return value of the function was the correction
that the function would have to perform on Target, shown below:
As we see from the equation above, the value of the flow rate Control must be multiplied with
TIMESTEP for the variable Return to return the same value as the LIMIT function did. This is simply
to make unit of the return value equal to the unit of the limited level. Also, we see that the variable
that controls the level is used as a flow rate for a outflow of the target level. However, when Target is
below MinVal, then the value of the flow rate becomes negative, which means that the direction of the
flow is reversed. We also see that the variable definition of Control is somewhat complicated in
Studio. This is compensated for by the fact that the real influences are shown correctly in the diagram.
Tip! If the Target level contains more in- or outflows, then these must be included in the
Control variable as well, in the same manner as the Input flow rate is; (Target +
Input*TIMESTEP + Flow2*TIMESTEP + ...)
- 62 -
Working with Help in Powersim Studio
There are several ways of finding assistance while you are working in Powersim Studio. These are:
Point to a toolbar button and, after a short delay, a description of the button appears. You will also
see descriptions of the commands on the status bar.
There is a Help button inside the dialog boxes. Click this to get assistance about the dialog box.
Use the online help system to get assistance. There are several ways of finding the help topics you
want, including a Table of Contents, an Index, and Full-text Search. We recommend you try the
index or the table of contents first.
When you are working with variable definitions, you can hover the mouse cursor over a function
name in the definition to view the syntax of the function. Similarly, hover the mouse cursor over a
variable name to view the variable's value.
When you are working in Constructor diagrams, hover the mouse pointer over an object to read
error messages or view the value of a variable. If you are creating links and flows, you will get
helpful information in the status bar as you are working.
Topic Layout
To help you navigate through the help system, we have consistently used symbols to categorize the
information available. In addition, each topic contains an icon in the upper right corner, which
indicates to what part of the software the topic applies.
Note! The formatting referred to below applies to the online help system. The symbols and
icons presented below are not present in the printed manual.
- 63 -
Icons
Below is a short explanation of each icon used in the help system.
Icon Explanation
The help topic applies to Powersim Studio.
The help topic applies to Powersim Engine, and contains reference information about
functions, etc.
The help topic applies to Powersim Engine, and contains reference information about
functions, etc.
- 64 -
Home opens the Home page of the help system.
Font changes the font size that the topic is displayed with. The button will loop through the
font size list.
Note! The font size you have selected in the help system will affect the font size of Internet
Explorer (and vice versa).
You can use the Help Control Panel to customize the appearance of the help system. You can change
the font and color schemes, as well as control the appearance of hidden sections (does not affect help
in dialog boxes inside Studio). You will see the changes immediately in the Preview window.
Note! The changes are saved immediately. You must revert the selection manually if you don't
like the new settings.
Note! The help system shares the same font settings as Internet Explorer on your computer. A
change to the font size in the Powersim help system will therefore affect the font setting for the
browser and vice versa.
- 65 -
and drag the side.
To reposition the Help Viewer on your screen, click the title bar and drag the Viewer to a new
position.
Note! The next time you open the Powersim Studio help system, its window will use the last size
and position settings you selected.
The Help Viewer uses Internet Explorer's HTML engine, and therefore also the same set of
preferences as Internet Explorer. If the page appears difficult to read, please check your Internet
Explorer settings.
Note! If you close the Help Viewer with the Navigation pane hidden, it will remain hidden the
next time you display the Help Viewer.
The Powersim Learning Lab contains tutorials and sample models meant to demonstrate some of the
features available in Powersim Studio. It offers a good starting point if you are familiarizing yourself
with our software.
The Learning Lab is available in two ways:
Click Learning Lab on the Help menu. This will bring the Learning Lab up in a stand-alone
window that is easy to position while you work.
In the normal help system, located almost at the top of the Table of Contents.
You can utilize several navigation tools in the Help System. These are available in the Navigation
pane. If the Navigation pane of the help window is closed, click Show on the toolbar to display it.
Click one of the following tabs:
To browse through a table of contents, click the Contents tab. The table of contents is an
expandable list of important topics.
To search using the index, click the Index tab. The index contains keywords for each help topic in
the help system.
To locate every occurrence of a word or phrase in the help system, click the Search tab, and then
type the word.
The Favorites tab allows you to make shortcuts to the help topics that you often revisit.
Note! Click the contents entry, index entry, search results entry or favorite entry to display the
corresponding topic.
- 66 -
Copy a Help Topic
1. Right-click inside the topic you want to copy, and then click Select All.
2. Right-click again, and then click Copy. This copies the topic to the Clipboard.
3. Open the target document.
4. Position your cursor where you want the information to appear.
5. On the Edit menu, click Paste.
Note! If you want to copy only parts of a topic, select the portion you want to copy, right-click
and then click Copy.
Note! The appearance of the printed page can differ somewhat from the online view.
You can use the Favorites tab in the Navigation pane to create and maintain links to the help topics
you often use.
1. Navigate to the topic you want to add.
2. Select the Favorites tab. If the Navigation tab is hidden, click Show to display it.
3. Click Add to add the topic to the list of favorite entries.
Tip! To remove a favorite entry, select the entry, and click Remove.
If the Navigation pane of the help window is closed, click Show on the toolbar to display it.
1. Click the Search tab, and then type the word or phrase you want to find.
2. Click List Topics, select the topic you want, and then click Display.
You can also create more advanced searches by adding the logical operators AND, OR, NEAR, and
NOT. These are available by clicking the arrow to the right of the entry field. These operators will
- 67 -
make your search more accurate.
The operators work like this:
No operator: Search for topics that contains one or more word from the search string.
AND: Search for topics that contain both words.
OR: Search for topics that contain one (or both) of the words
NEAR: Search for topics where the words in the search string are close to each other.
NOT: Search for topics that contain the first but not the second words.
If you need help while working with specific features in dialog boxes, you can click Help in the
dialog box.
1. Click Help in the lower right corner of the dialog box.
2. A page describing the various parts of the dialog box will appear.
Tip! Most of the dialog boxes in Studio are resizable. Make the dialog box bigger by dragging
the edge of the dialog box, and make the help window bigger by dragging the bar separating
the dialog box and the help window.
Some pages contain information that is not open by default. Such sections have a small button ([»]) at
the end, indicating that there is more information available. To view this information, simply click the
button to open the section. Click it again to close the section.
When you search for words in help topics using full-text search, you can set HTML Help to highlight
each occurrence of the word or phrase found.
To highlight all instances of a search word or phrase, click Options, and then click Search
Highlight On.
Note! To turn off this option, click Options, and then click Search Highlight Off.
- 68 -
Work with Powersim Studio
Powersim Studio has several features to help you work quickly and efficiently while creating your
simulation models. Each item on the screen has a set of actions, or commands, that you can perform
on them. The easiest way of accessing these commands, is through the shortcut menu, available by
right-clicking the item. In addition, you will find a host of commands available in ordinary menus,
located on the top of the screen, and in the toolbars.
Windows in Studio
There are three different types of windows in Powersim Studio. First, there are Catalog Windows.
These windows cover the entire simulation project, also referred to as the Catalog. These include the
Global Units and Global Ranges windows. Second, there are Component Windows. These
windows cover each component individually, and will always work on the active component, which is
marked with bold typeface in the Project Window. These include the Local Units, Runs, and
Local Ranges. Third, there are Simulation Windows. These are windows that are specific to the
tasks that are currently available. These include Shared Diagrams, Private Diagrams,
Equations, and Co-models.
- 69 -
Language Support
Powersim Studio also allows you to set the language of your simulation project. In fact, you can save
variable names and texts in as many languages as you wish to. This makes it easier to share your
models with users that normally use other languages than your own. Powersim Studio will start in the
language that is selected in Regional Settings on your computer. This is available in the Control
Panel of your computer.
Powersim Studio allows you to create several components in each simulation project. In addition, you
can create several simulations for each component. Most of the information contained in a component
is shared between the various simulations, such as Local Units, Local Ranges, Runs, Equations, and
Shared Diagrams. However, each simulation contains their own Events, Co-models, Run
Controllers, and Private Diagrams.
Shared Diagrams
You will find the component's diagram book under the Shared Diagrams entry under each
Simulation entry. By double-clicking the entry, the component's diagrams will open in Studio.
Alternatively, you can right-click the entry and select View on the shortcut menu.
If the component contains submodels with diagrams, these diagram books will appear as child nodes
to the Shared Diagrams node.
Shared diagrams are Constructor Diagrams. These diagrams allow you to create model structures
using all the various model variables, links, and flows. They can also contain presentation objects like
controls, frames, hyperlinks, etc.
Note! Although Shared Diagrams and Equations appear under a simulation in the Project
Window, they are shared between all the simulations of the given component. They are located
below the simulation simply because the values displayed for the variable's belong to that
simulation. However, if you perform a change in a shared diagram, the change will be reflected
in all simulations instantly.
Equations
A component's equations contain the actual implementation of the simulation model. The Equations
View offers complete access to all variables and variable definitions in the component. You open the
Equations View by double-clicking the entry, or by right-clicking it and selecting View on the
shortcut menu.
- 70 -
By expanding the tree view in the Equations View, you can inspect the variable's definitions,
dimensions, and values. You can also edit the model directly in the view, and you can run the
simulation.
Working with the Equations View and using the Details Window will allow you to study the
variables of the model directly. While the Equations View display the entire structure of the model,
the Details Window will only display the child variables of the variable that owns the diagram.
Note! When running the simulation while the Equations View and/or Details Window of the
diagram book is open, the simulation might run a little slower than running it while viewing a
diagram. This is due to the fact that all values are updated throughout the view. To speed up
the simulation, close the Details Window and close (or minimize) the Equations View.
Tip! By selecting the Auto-synchronize Details with Diagram option in the shortcut menu for
the Details Window, you can make the window automatically scroll the variable you have
selected in the diagram into view.
Private Diagrams
Each simulation can contain its own diagram book. These diagrams are Interaction Diagrams, and
they are located under Private Diagrams. Interaction diagrams allow you to create user interfaces
using presentation and input objects, but you are not allowed to create or include variable symbols.
When working with Solver Tasks, the task will contain Solver variables that are not available outside
the given task at all. In this tasks, you have to use private diagrams to be able to present the data to the
user.
Co-models
If you need to exchange data with external data stores, you can use datasets that are connect to your
simulation as co-models. When a dataset connection is created in the Co-models view, a
connection to an external (or internal) data store is established, based on the definition of the dataset.
The dataset variables can be connected to the simulation's interface variables (variables with a defined
transfer direction in the component) in a simple and intuitive manner.
Events
Events enables you to specify actions to be performed when certain conditions in your simulation are
TRUE. By using events you can notify the user through message boxes, get user input interactively
using input boxes, set the value of parameters, and so on. The events system available in Studio is a
great means of giving your simulator an interactive user interface.
Note! Since events are defined for each simulation, they will only work when run inside Studio
(not if you use the Studio SDK to embed your simulation in a stand-alone application).
- 71 -
Work with a Simulation Project
The simulation project contains everything associated with the model or models you choose to group
together in one project folder. The simulation file stores all the information needed to run and work
with the project in Powersim Studio:
The simulation models, each contained within its own component;
The diagrams and windows associated with the various components;
Datasets that hold the results of simulations or are imported from external sources;
The units and ranges that are defined for the project.
You manage the project in the Project Window.
Although you can create text frames easily inside diagrams, you might sometimes have the need to
include more documentation with your simulation projects. Studio therefore features a way of linking
your HTML pages directly from within Studio itself. Just follow these simple steps:
1. Document your simulation project in any application that allows you to save HTML pages (for
example Microsoft Word, Microsoft FrontPage Express, Netscape Composer, etc.).
2. Save your HTML pages in the same folder where you saved your simulation project.
3. Rename the main page of your HTML document set to the same name as your simulation project.
If your simulation project is saved as C:\My Documents\Models\MySimulation.sip, then you should
- 72 -
save your HTML documents to C:\My Documents\Models, and rename the first page of you document
set to MySimulation.htm
To open the project documentation:
1. Select Project Documentation on the Help menu.
Tip! You can also use a hyperlink object pointing to a web page or file to open the project
documentation from inside a diagram.
If you are viewing the simulation in Presentation Mode, the project documentation will be
automatically opened when you hit F1, or when you click Help on the toolbar.
Note! Only one project can be open at a time. If you want to work on two projects
simultaneously, you must run two instances of Powersim Studio.
- 73 -
3. Make sure that Simulation Projects (*.sip) or All Files (*.*). is chosen for Files of type, and type a
name for the new project under File name.
4. Click Save.
Note! The difference between Save As and Save Copy As, is that when you save a copy, you
will continue working on the "old" project. For Save As, you will continue working on the
project with the new name.
Every time you save your simulation project, Studio will back up your simulation project. The backup
file has the same file name, but with the file extension *.~si rather than .sip. Therefore, when you
have saved your project twice, you will have two files in your folder: MyProject.sip and
MyProject.~si. The *.sip file contains the last saved version, while the *.~si file contains the
previously saved version.
To create a back up project:
1. Click Save, or select Save on the File menu.
Note! You are advised to manually back up your work every now and then. This might be useful
if you need to revert to an earlier stage of your development process.
When you save a simulation project by clicking Save, a backup project is created in the same
folder and with the same file name, but with a different extension: *.~si. This feature is convenient if
your simulation project for any reason should become invalid and will not open in Studio, or if you
for any other reason should want to revert to the previously saved version of the simulation project.
Note! Studio will not be able to open a .~si file directly. It must be renamed to a .sip extension
first.
Although Studio doesn't contain a direct way to compact a simulation project, it is easy to perform
this task manually. Simply save the simulation project to a new file name using Save As… on the File
- 74 -
menu.
In most cases this shouldn't be necessary. However, if you have been changing picture fills a lot
(adding and removing pictures several times, for example), the size of the project might be larger than
what is actually required by the current content of the file.
Note! The project documentation must be saved in the same folder as the simulation project
itself. The first page of the documentation must have the same name as the simulation project
itself (with a .htm-extension rather than .sip).
Tip! When you are viewing the simulation project in Presentation Mode, you can access the
project documentation by hitting F1 or clicking Help on the toolbar.
A list of the most recently used simulation projects is available on the File menu. To open one of
these files:
1. Select the name of the file on the File menu.
- 75 -
View Project Statistics
Note! The ability to password protect simulation projects is only available to Enterprise
licensees. All licensees can open password protected projects, however.
When you have created a model and want to distribute it to others, you can protect it against
undesired editing. Thus you allow other users to run your simulations, but prevent them from making
changes to it. There are three levels of protection available:
Run Access: Allows the user to run the simulation. However, he cannot view the model diagrams;
Run and View Access: Allows the user to run the simulation and view the model diagrams and
variable equations. However, he cannot perform changes to the model;
Full Access: Allows the user full access to the simulation project.
By setting passwords for the various levels, you can control the way your users can use your
simulation project.
Levels of Protection
There are three levels of protection available in Powersim Studio: Run Access, Run and View
Access, and Full Access. The list below summarizes the permissions given on each level.
Level Description
The simulation project can only be run. No model diagrams or equations will be
Run Access
available. The model can, for example, be accessed using Powersim Studio SDK.
The simulation project can be viewed, but not edited. Access to all views are
Run and
available, including units and ranges. However, no definitions can be changed
View Access
(including units, ranges, and variables).
Full Access The simulation project can be viewed and edited freely.
Each access level can be locked by an individual password. To unlock a higher protection level,
simply enter the password for that level.
- 76 -
Protect the Simulation Project
Redo an Operation
Undo an Operation
- 77 -
The last operation is negated. Repeat the Undo command until you reach the point you wanted to
go back to.
For a list of the most recently performed commands,
1. Select the arrow next to the Undo icon.
2. Click the earliest command you want to cancel. You are brought back to the stage before that.
Note! Not all operations are possible to undo in Powersim Studio, such as deleting
components, datasets, and diagrams. If an operation cannot be undone, you will be warned.
Note! Switching between components and submodel diagrams will usually clear the undo stack,
making it impossible to undo previous actions in the diagrams of other components or
submodels.
- 78 -
Work with Windows and Diagrams
There are several types of windows in Studio. These windows are used to view various parts of the
simulation project, such as equations, diagrams, ranges, units, and datasets.
Tip! You can exclude (and include) diagrams from the diagram book, both for Shared and
Private diagrams. The exclusion (or inclusion) status is kept for each simulation individually,
allowing you to hide shared diagrams for a particular simulation, if you wish to.
- 79 -
View Equations
Tip! The Details Window is also available when you right-click the diagram tabs at the
bottom of the diagram book.
A tree view of the model variables is displayed in the left section of the active diagram window. You
can choose to show definitions of some or all variables of the underlying model. You can also dock
the Details Window on the top of the diagram window by right-clicking inside the Details Window
pane, selecting Details at Left, and then select Top on the submenu.
From this view you may open property dialog boxes of any variable in the model, delete variables and
add new ones.
Each component in a simulation project has its own diagram workbook, containing as many diagrams
that you need. To create a new diagram sheet:
1. Right-click a sheet tab and select Insert Constructor Diagram on the shortcut menu.
Tip! You can rearrange the order of the diagram sheets by dragging their tabs to new
positions.
Select Sheets
- 80 -
To select multiple sheets:
Select the sheets while holding down Shift.
Tip! A number of useful commands are found on the sheets' shortcut menu. Simply right-click a
sheet tab to activate the shortcut menu..
Move Sheets
Tip! If you wish, you can move several diagrams at once by selecting multiple sheets at a time.
You select multiple files by holding down SHIFT while selecting more sheets.
Exclude a Sheet
Include a Sheet
You can include a sheet that has previously been excluded in a diagram book:
1. Right-click the diagram tab at the bottom of the window.
2. Select Include Diagram on the shortcut menu.
3. Select the diagram you wish to include on the submenu. If it doesn't appear there, you can select
Diagrams…, and select the diagram in the dialog box that appears.
The include/exclude status of diagrams are saved for each simulation individually. This feature can be
used to contol which diagrams are available in a simulation.
Rename a Sheet
1. Right-click the tab of the sheet that you want to rename.
2. Select Rename on the shortcut menu.
3. Type the new name and hit Enter.
- 81 -
Delete a Sheet
1. Right-click the diagram sheet you wish to delete, and select Delete on the shortcut menu.
You can group the treeview by several properties by dragging several column headers to the grouping
area.
The Equations View offers two ways of viewing your model; hierarchical (default) or flat. In the
hierarchical view, child variables are listed as nodes in a tree below their parent variables. In the flat
view, however, each variable is listed by its unique name in the model. A child variable is listed by its
entire name, including its parents name. The figures below shows the difference between flat and
hierarchical view.
- 82 -
The Equations View displaying a model in hierarchical view (left) and flat view.
Note! The parent variable is always included for a child variable, either as the parent node in
the tree, or in the variable's name. This is especially useful if you need to sort the Equations
View based on one of the other fields, as you can clearly identify the variable in question.
Organize Windows
When you close your simulation project, the windows and their position will be saved with the
project. The next time you open the project, the windows that were open when you closed it will open
- 83 -
automatically.
Note! If you only change the appearance of windows after opening a project, you will not be
prompted to save your model before exit. If this is your only change to the project, please click
Save before quitting Studio!
It is possible to open more than one window for a component, for example to view different diagram
sheets in separate windows.
1. Select an already open window.
2. On the Window menu, select New Window.
A new window is created that displays the diagrams of the same component.
Note! All actions performed in one window of a component are carried out in all open windows
for that component. For instance, if you include a variable in a diagram sheet, it will also be
included in the same sheet in the other windows.
Maximizing and minimizing windows in Studio is done in the same way as in any other Windows
program:
Click Maximize in the upper right corner of the window to maximize it.
Click Minimize in the upper right corner of the window to minimize it.
- 84 -
Close All Windows
1. On the Window menu, select Close All.
All open windows are closed.
The Project Window, if switched on, is shown on the left hand side of the window (by default). It
displays all contents of the open project as a tree structure.
Tip! The actions you can perform on the various items in the Project Window are available on
the items' shortcut menus. To open the shortcut menu, right-click the relevant item.
The Status Bar is located at the bottom of the application window. The status bar shows information
about menus and toolbars, the project, and the simulation.
When the mouse pointer hovers over a menu command or toolbar button, a description is shown in
- 85 -
the status bar.
When you are creating your model using Constructor Diagrams, you will receive messages and
tips in the Status Bar while you are working.
The simulation progress bar shows how far the simulation has advanced relative to the total
simulation time, as well as the current simulation time.
The Project Window can be docked on either of the four edges of the application window, or it can
float as a separate window.
To dock the Project Window:
1. Drag the Project Window by using the toolbar handle, and position it along one of the edges of the
application. If the window is undocked, drag the window by its title bar.
To undock the Project Window:
1. Drag the Project Window by using the toolbar handle, and position it somewhere inside the
application area (but not too close to the edges, where it will automatically dock).
You can create folders for your components and datasets in the Project Window. The components and
dataset can be dropped in the different folders.
1. Right-click a folder or the Project node, and select New Folder on the shortcut menu.
The Project Window is displayed by default when you create a new simulation project.
To switch it on or off:
1. Click Toggle Project Window on the toolbar.
The toolbars offer quick access to commands that are useful when you work with your simulation
project, create and edit Constructor diagrams, and so on.
When you click a command on a toolbar, you select it for one operation. To lock a command, double-
click it on the toolbar. The command is then active until you select another command.
Powersim Studio remembers the position and display state of all the toolbars. Therefore, the toolbars
will reappear in the same positions as they had the last time you used Studio.
- 86 -
There are also a number of keyboard shortcuts available in Studio. In addition to the ordinary
Windows shortcuts (Alt to access menus and Alt + underlined characters in dialog boxes as
accelerators), many commands have also keyboard shortcuts (such as Ctrl+C to copy and Ctrl+V
to paste the selected objects) that enable you to use the keyboard instead of the mouse to navigate and
operate Studio. There are also a few modifier keys that you can use to alter the mouse actions (such as
holding down Ctrl while dragging an object in a diagram changes the move operation to a copy
operation).
Tip! To reactivate a toolbar that you have hidden, right-click in the toolbar area of Powersim
Studio and select it on the shortcut menu.
Tools used to create diagrams (such as Level, Auxiliary, Time Graph Control, etc.) can be
selected persistently, which enables you to insert more than one instance of the selected object
without a need to click the specific button again. This is achieved by double-clicking the object on the
toolbar.
1. Double-click the tool you wish to select as persistent.
2. Insert the object(s) you wish to insert in the diagram.
3. When you are finished, click Pointer, or hit Esc.
All toolbars can be moved and placed elsewhere on the screen. You may also dock them to the edge
of the program window.
1. Grab the title line (on a floating toolbar) or the move handle (on a docked toolbar) and drag it to
the desired position.
2. If you drag it to the edge of the program window, it becomes docked, which means that its outline
snaps to the program window.
If you hide a toolbar, that toolbar will not appear again in any projects until you turn it back
on.
- 87 -
Diagram Commands
Diagram Commands include the tools that you use to create and modify a Constructor Diagram.
Pointer Tool
The default tool, used for selection.
Level Tool
Create a level variable.
Auxiliary Tool
Create an auxiliary variable.
Constant Tool
Create a constant variable.
Submodel Tool
Create a submodel variable.
Link Tool
Create a link between two variables.
Flow Tool
Create a flow (without a rate) in the active diagram.
Snapshot Tool
Create a snapshot of a variable. If you click the button and then click inside the diagram, a dialog
box appears containing the variables that can be made snapshots of. Alternatively, you can click the
small arrow next to the button and select the variable to snapshot in the drop-down list.
- 88 -
Include Variable Tool
Include an existing variable in the active diagram. If you click the button and then click inside the
diagram, a dialog box appears containing the variables that can be made included. Alternatively, you
can click the small arrow next to the button and select the variable to include in the drop-down list.
Frame Tool
Create a frame in the diagram. Select a different shape by clicking the small arrow next to the button,
and select a shape from the drop-down list.
Freeform Tool
Create a freeform in the diagram. The freeform will be created as an arrow as default, but you can
turn off the arrowheads if you wish to.
Hyperlink Tool
Create a hyperlink in the diagram.
Bookmark Tool
Create a bookmark in the diagram.
- 89 -
Table Control Tool
Create a Table Control in the active diagram.
Design Mode
Switch between Design and User Mode. When the button is depressed, the diagram is in Design
Mode, and you are allowed to perform changes to the diagram.
Diagram Properties
Open the Diagram Properties dialog box containing settings for grids, guides, and diagram
background fill.
Tip! You can make a tool persistent by double-clicking the toolbar button. This is useful if you
need to insert several objects in your diagram. Hit ESC to turn off the persistent tool when
you're finished.
- 90 -
Format Commands
The Format Toolbar contains items that let you choose the visual characteristics of text, symbols, and
other objects in your diagram.
Font Name
Select a font name in the drop-down box to change the font of the selected text.
Font Size
Select a font size in the drop-down box to change the font size of the selected text.
Text Alignment
Alter the text alignment of the selected objects. You can right align, left align, center or justify the
text.
Font Color
Change the text color of selected objects.
Fill Color
Change the fill color of the selected objects.
Line Color
Changes the line color of the selected objects.
Line Style
Changes the line style of the selected objects.
Dash Style
Changes the line dash style of the selected objects.
Shape Type
- 91 -
Change the line shape type of the selected objects.
- 92 -
Layout Commands
The commands on the Layout Toolbar can be used to arrange the objects in your diagram.
Snap to Grid
Switch grid snapping on or off. When the button is depressed, snapping is turned on.
Snap to Guides
Switch guide snapping on or off. When the button is depressed, snapping is turned on.
- 93 -
Simulation Commands
The simulation commands include commands for controlling the simulation of a model. The most
commonly used simulation controls are also available on the Simulation MiniBar.
Reset Simulation
Reset the simulation.
Play
Start the simulation.
Stop the simulation by clicking once again. When the button is depressed, the simulation is running.
Go to Cue Point
Go to the latest cue point in the list. To select a different cue point (if the project contains more than
one), click the small arrow next to the button, and select the desired cue point from the drop-down
list.
Autoscale Now
Update the autoscaling of all variables in the project. Use this command to automatically scale the
value axis of all controls whenever you need to. All variables will also be automatically scaled at the
end of the simulation.
Add to Runs
Add the current simulation run to the saved runs. Runs are available Runs view, under Simulation in
the Project Window. Saved runs can be loaded into the simulation again (and thereby replace the
current run), or they can be used as reference data for the current run.
- 94 -
Reference Data
Select a saved run as reference data for the current run. The reference data must be previously saved
(obviously) in order to appear under Reference Data.
External Data
Load, save, or view details for dataset connections and external data stores.
- 95 -
Standard Commands
New Project
Create an empty project. If you already have a project open, you will be asked to save the changes.
Open Project
Open an existing project.
Save Project
Save the current project.
Print Project
Print the current project.
Cut
Cut the currently selected object from the active view to the clipboard.
Copy
Copy the currently selected object(s) in the active view to the clipboard.
Paste
Paste the content of the clipboard into the currently active view.
Undo
Undo the last operation. If you click the arrow, you can undo the last operations (chronologically).
Redo
Redo the last operation that was undone. If you click the arrow, you can redo the last operations
(chronologically). The Redo button will remain unavailable until at least one operation has been
undone.
- 96 -
Contents
Open the help system.
- 97 -
Symbol Commands
The Symbol Toolbar contains useful tools for adding auto report and changing the appearance of
flows and their associated flow rates.
Anonymous Rate
Make the selected flow rate anonymous.
- 98 -
The Presentation Toolbar
The Presentation Toolbar allows you to navigate through your simulator interface, and also allows
you to switch back to Design Mode.
Home
Brings you back to the default window of the simulator (as specified in the Presentation Mode Setup
property page).
Reference Data
Presentation Mode
Switch off Presentation Mode and return to Design Mode of the simulation project. If the project is
protected, you must enter the correct password to unlock the project.
Zoom
- 99 -
Allows you to zoom the current view in or out.
Advanced Commands
The button opens a submenu where you can work with cue points, restore permanent variables,
autoscale, and work with external data.
Help
Launches the project documentation, if one exists. Otherwise, a generic help for Presentation Mode
will be launched.
- 100 -
View Commands
The view commands include commands for controlling the current view (or project).
Properties
Edit the properties of the selected object(s) in the active view.
Language
Select project language. To change language for the active view only, select a language under
Language on the View menu.
Details Window
Toggle the Details Window on or off (this command is only available for diagrams).
Go to a Variable
Go to a variable in the project. The Go to variable… dialog box contains several options where you
can specify search criteria for finding the variable you are looking for. You can search for variables
themselves, variables defined by given variables, or for problematic variables.
Go to Previous Variable
Go to the previous variable that matches the given search criteria.
Go to Next Variable
Go to the next variable that matches the given search criteria.
Zoom
Select or enter the magnification in percent for the active view.
Zoom Tool
Magnify a section of the active diagram. Click the button, and then select the area of the diagram that
you wish to magnify.
Zoom to Fit
Fit the content of the current view to the window.
Presentation Mode
- 101 -
Switch to Presentation Mode. The project's presentation mode settings will be used.
- 102 -
Constructor Keyboard Shortcuts and Modifiers
Drag-and-Drop Modifiers
These modifiers can be used when you perform drag-and-drop operations to change the
Notes operation that is performed. You can use several modifiers at the same time, if you
wish to.
The Alt key has several functions, depending on the drag-and-drop operation you are
performing:
Temporarily reverse snap to grid and guides
If snapping is turned on the Layout menu, you can temporarily turn it off while
dragging an object by holding down the Alt key while you drag the object to its new
Alt
position. This also applies when inserting guides.
Data input in chart control
In the Chart control you can drag any graph that allows input to a new shape by
pointing to it and sweep along the value and element axis. If you hold down ALT
while dragging, you can restrict the input to the selected element (data point) only.
The Ctrl key has several functions, depending on the drag-and-drop operation you
are performing:
Create or reshape segments
Holding down Ctrl while creating line segments (in links or lines) will make the
segments straight.
Create flows
Hitting Ctrl once while creating a flow will turn off the elbow style of that flow.
Holding down Ctrl while creating flow segments will make the segment curved.
Adjusting connected nodes
Holding down Ctrl while moving a connected node or while moving the vertex of a
connected node, will force the control handle to always be perpendicular to the edge
Ctrl of the symbol.
Selecting nodes in segments
Holding down Ctrl while selecting nodes in line, link, or flow segments, will delete
the selected node.
Drag objects
Holding down Ctrl while dragging diagram objects will copy them rather than
moving them (a small '+' appears on the mouse pointer to indicate that a copy
operation is performed).
Resize objects
Holding down Ctrl while resizing diagram objects will cause the resize to be
symmetrical around the center point of the object rather than extending only the
edges dragged by the mouse.
The Shift key has several functions, depending on the drag-and-drop operation you
are performing:
Create or reshape segments
Temporarily reverse snapping to the angular grid for straight segments of lines, links
Shift and flows. Thus, if snap to angular grid is turned off in the Grid Settings property
page, you can temporarily turn it on by holding down the Shift key while creating
the straight segment.
Note! Creating a straight line or link requires holding down the Ctrl key (see
above).
- 103 -
Resize objects
Holding down Shift while resizing diagram objects will lock the aspect ratio and
ensure that the shape of the object is maintained.
The Ctrl-Alt key combination will usually work as a combination of the two
individual key functions, except in one case:
Ctrl-
Alt Adjusting the vertex of a connected node
Holding down Ctrl-Alt while adjusting the vertex of a control handle to a
connected node, will lock the connection point of the node itself.
Delete the last inserted node when you are creating segments (for flows, links, or
Del
lines).
Ins Insert a new node when you are creating segments (for flows, links, or lines).
- 104 -
Studio Keyboard Shortcuts
Application Commands
Alt+F4 Exit Powersim Studio
F1 Open Help for Powersim Studio
Simulation Commands
Ctrl+Space Play the simulation
Ctrl+Shift+Space Play the simulation stepwise
Ctrl+R Reset the simulation
Edit Commands
Ctrl+X Cut
Ctrl+C Copy
Ctrl+V Paste
Del Delete
Ctrl+A Select All
Ctrl+Z Undo
Ctrl+Y Redo
Alt+Enter Properties (of the selected object)
Go To Commands
Ctrl+G Go to variable (Open Go To… dialog box)
F3 Go to next variable
Shift+F3 Go to previous variable
Go to next variable defined by the selected variable (variable can be
Ctrl+F3
selected in the Equations View, the Details Window, or in a diagram)
Project Commands
Ctrl+N New project
Ctrl+O Open (existing) project
Ctrl+S Save project
Ctrl+P Print project
Window Commands
Ctrl+F4 Close active window
Ctrl+Tab Next window
Ctrl+Shift+Tab Previous window
Alt+0 Project Window
Alt+1 Details Window
- 105 -
F5 Presentation Mode
- 106 -
Working with Components
Components in Studio represent self-contained models that can be run independently from eachother.
The global settings for the entire simulation project, including global units, global ranges, time
measurements, and other project settings available in the Project Settings dialog box, are used for all
components within the simulation project.
Each component can contain several simulations and tasks. All the simulations and tasks of a given
component share the model structure and definitions, the local ranges and units, and the saved runs of
the component. A change in any of these objects will be immediately reflected in all other simulations
and tasks. A component also has a set of Shared Diagrams that are common to all simulations and
tasks, called Shared Diagrams. As the name implies, a change in one of these diagrams will also be
reflected in all of the component's simulations and tasks.
Each simulation and task holds it own, individual simulation settings. This allows you to alter the
time horizon and timestep of the simulation independently from the other simulations, allowing the
model to be used for different purposes without having to change the project at all. In addition to the
Shared Diagrams, each simulation and task may contain their own Private Diagrams. As the name
indicates, these diagrams are private to the selected simulation, and will not appear in any other
simulations. These private diagrams allow you to create customized user interfaces for each
simulation, if you wish. Co-models and events are also set up for each simulation individually.
Tip! Since all simulations and tasks share the same model variables and definitions, private
diagrams doesn't support model variable symbols. They can only contain presentation objects,
such as time graphs, tables, frames, etc.
The Project Window allows you easy access to all the views and settings of the component and its
simulations and tasks. You can easily create new components, simulations and tasks, rename or delete
them, and edit their settings.
Tip! Although the Equations node appears for each simulation and task in the Project
Window, the equations themselves are shared by all simulations. The values of the variable that
appear in the view, however, may differ from simulation to simulation.
- 107 -
use to quickly duplicate model structures that you often use.
When you create components that you intend to use as submodels later, you should define a transfer
direction for your interface variables. When the component is copied as a submodel later, all these
variables will automatically be made public, which enables them to be defined by variables or used in
definitions outside the submodel itself.
About Simulations
A component can contain several simulations, all of which can use their own individual simulation
settings. Co-models, Events, and Private Diagrams are also unique to each individual simulation.
The list below shows which parts of the settings and controls belong to the global project, component
and simulation.
Project
Global Ranges
Global Units
Project settings for calendar, time unit
Presentation Mode setup
Component
Local Ranges
Local Units
Runs
All variables and definitions
Shared (Constructor) diagrams
Simulation
Co-model connections
Events
Private (Interaction) Diagrams
Simulation Settings, including integration method, start and stop times, time step, reporting
windows and intervals.
Note! Although the variables and their definitions all belong to the component, the Equations
and Shared Diagrams nodes appear below the Simulation in the Project Window. The reason
for this is that the values that will be displayed for each variable belong to the current
simulation. Hence, even though the shared diagrams are identical in all simulations, the values
and time series of the variables will differ with the current simulation time and the selected
simulation settings.
Components in Studio can contain several simulations and tasks, each with their own simulation
settings. A simulation contains two types of diagrams: Private Diagrams and Shared Diagrams.
Shared diagrams are common to all simulations and tasks for a component, and contains the model
- 108 -
structures of the component. Private diagrams belongs only to the simulation in question, and can
only contain presentation objects (like controls, frames, hyperlinks, etc.).
Rename a Component
1. In the Project Window, select the component you wish to rename.
2. Hit F2 on the keyboard.
3. Edit the new name for the component, and hit Enter.
A component can contain several simulation, each with their own individual name and simulation
settings.
To add a simulation to a component:
- 109 -
1. Right-click the component in the Project Window, and select Add Simulation on the
shortcut menu.
2. Select the name of the new simulation, and hit F2 to enter a new name. Type the new name and
hit Enter when you're finished.
3. Right-click the new simulation, and select Simulation Settings... on the shortcut menu. Enter
appropriate values for each of the properties, and click OK when you're finished.
A simulation have two types of diagrams: Shared and Private Diagrams. The shared diagrams are
Constructor Diagrams that are shared by all the simulations of a component. These can be used to
create the model itself, as well as creating user interfaces. Private diagrams, on the other hand, are
Interaction Diagrams that are unique to the current simulation. These can only be used to create
user interfaces.
Note! The simulation's name will be shown in the title bar of the diagram window. This makes
it easy to identify which simulation the window belongs to, should you have several similar
windows open at the same time.
You can copy a component as a submodel inside other models at any time. Interface variables -
variables within your component that has a defined transfer direction - will automatically be made
public in the resulting submodel, which makes it easy to connect them to the surrounding model
variables.
If you deselect the Keep definition in component copy option for the interface variables, the variable
definition will not be copied when you create the submodel. This will make the resulting public child
- 110 -
variables undefined as well, making it obvious which public child variables should be used for input
to the submodel.
Note! Although the transfer direction indicates that the variables are interface variables, they
will all become public in the resulting submodel. However, the Keep definition in component
copy can only be deselected for interface variables with the transfer direction set to in.
If the component requires special ranges and units, these will also be create in the simulation project
where you copy your component. However, keep in mind that if components that get dimensions and
units via the interface variables are easier to reuse.
When you create a submodel from a component, the diagrams of the component are copied to the
submodel as well. You should therefore remove all empty diagrams from your diagram book prior to
using the component as a submodel. You should also take care that the diagrams are not larger than
necessary.
The name of the component will be used as the name of the submodel as well. You should therefore
name each component in an intuitive way, so it's easy to find the component you need later. You can
rename the component in the Project Window by selecting the name, hitting F2, typing the name,
and then hit Enter.
Example
The illustration below shows a simple model structure modelling the behavior of an account. The
component is named Account and has four interface variables. The Opening Balance, Period, and
Rate all have a transfer direction of in, indicating that they are supposed to be used as input variables
for the resulting submodel. For all of them, the Keep definition in component copy have been turned
off. The Balance level has a transfer direction of out, allowing it to be used as an output variable in
the resulting submodel.
- 111 -
The Account component ready for duplication as a submodel.
When the component is copied as a submodel into a new model (or submodel), the interface variables
will become public child variables, and the variables marked for input will become undefined, as
shown below.
When the component is copied as a submodel, the interface variables become public child variables,
and the input variables are undefined (resulting in all variables becoming undefined as well).
The public child variables can now be included in the variable next to the submodel symbol itself,
which makes them easily available for definition. When you define them properly, the entire
submodel will soon become valid. Suggested values are Rate = 12<<%/yr>>, Period = 1<<mo>>,
and Opening Balance = 1000<<USD>> (remember to define the unit USD in Global Units).
a) b)
When the public child variables have been included in the parent's model (a), they can be easily
defined (b). The entire submodel will become well-defined as soon as the three input variables have
been properly defined.
- 112 -
Since the submodel contains one public level, flows can be connected to the level by drawing the flow
directly to and from the submodel. Any number of flows can be connected to the level, but for now
one inflow and one outflow will do.
Flows have been connected to the submodel (and thereby directly to the public level Balance), and the
implementation of the component Account as a submodel is finished.
Delete a Component
1. Right-click the component you wish to delete in the Project Window.
2. Select Delete on the shortcut menu.
- 113 -
Constructor and Interaction Diagrams
Powersim Studio contains two different types of diagrams: Constructor and Interaction
diagrams. Constructor diagrams are used to create models and user interfaces, and belong to a
component, where it is shared between all the available simulations. Interaction diagrams, on the
other hand, are used to create user interfaces and data presentations only. Interaction diagrams have
the same features as Constructor diagrams, except you cannot create variables, flows, or links. Each
simulation on a component can contain its own book of Interaction diagrams.
Constructor Diagrams
After having, for instance, used a causal loop diagram to single out the key variables of your system
and their patterns of influence, you are ready to create the model in a Constructor diagram. The
diagramming environment supports the design of the Accumulator Flow diagrams used in System
Dynamics. It is quite simple to get started, and though it will take time and practice to master all
facets of it, you will soon have the capacity to start simulating the behavior of real world systems.
You work in the diagram with graphical representations of the building blocks used in System
Dynamics: Levels (or accumulators) and flows, auxiliary and constant variables, and information
links. You include the variables of a system that has the potential to change over time and connect
them in the way that best represents the relationships between them. For auxiliaries, you must supply
the equations that define them, whereas Powersim Studio takes care of the calculus involved in
computing the values of the levels after you have given them an initial value.
A simple model implementing the functionality of a conveyor. The model contains a submodel -
Conveyor - which are full-fledged models built within a variable and connected to the surrounding
model by public variables.
Furthermore, make sure to use all the possibilities that Powersim Studio offers in terms of monitoring
the development of crucial variables and bringing the simulation process to life for the audience of
your model. By implementing user input controls, you can even turn the simulation process into a test
laboratory where the user can change the value of key variables before and during the simulation to
- 114 -
see how the system as a whole is affected.
In addition to the standard variable symbols, links, and flows, Constructor diagrams support
Powersim controls, frames, lines, hyperlinks and bookmarks, and more.
Interaction Diagrams
Interaction diagrams allow you to create user interfaces that are unique for each simulation for your
component. Interaction diagrams can, as an example, be used to create data presentations for the Risk
Assessment task that is available in Studio.
Interaction diagrams support Powersim controls, frames, lines, hyperlinks and bookmarks, and more.
Working with these objects are identical in both Interaction and Constructor diagrams.
- 115 -
Work with the Constructor Diagram
One model can contain several diagrams, all contained in sheets in the Diagram Book. Independent of
how you design and edit the diagrams, you can always view the entire model in the Equations View.
Use the Equation View to edit the model hierarchy directly. You can also use the Details Window for
this purpose, with the exception that you cannot access child variables in this view.
You can create as many diagram sheets as you wish. At the bottom of the diagram window you will
find a row of tabs that let you switch between the sheets. A diagram may also be zoomed in and out.
All commands and editing functions are accessible through the menu bar. The most commonly used
commands and features can also be reached from the toolbars, or from shortcut menus that appear
when you right-click the object you want to modify.
To help you keep your diagram nice and tidy, there are two kinds of grids. The regular grid runs
vertically and horizontally and you can choose to let variables and other objects be aligned along it.
The radial grid runs at angles to help you give your links and flows a uniform appearance.
When creating simulations in Studio you have different needs than when you run and experiment with
your simulations. Studio therefore offers an option of switching between Design and User mode.
When Studio is in Design mode, you are free to perform any changes you wish to the diagrams and
simulation model. When Studio is in User mode, however, you are only allowed to run and interact
with the model, not change it.
The diagram is a graphical representation of the model. When you design the model in the diagram
window, the relationships that define the structure of the model are automatically created and the
diagram is a complete representation of the model. You may choose, however, to exclude some
elements from the diagram while still keeping them in the model. In that case, the entire model can
still be viewed (and edited) in the Details Window or the Equations view. Of course, you may
also choose to create the entire model in the Equations View or Details Window, and include only a
few variables of most interest in a diagram.
A variable in Studio can itself contain a diagram book with child variables.
As a result of the separation between the diagram and the actual model, you can create as many
diagrams as you wish in order to illustrate your model. The different diagrams can focus on different
parts or aspects of your simulation model. All diagrams belonging to the same variable or component
(which can be considered a "root variable"), are collected diagram books. Each diagram can contain
variable symbols representing the child variables of the variable owning the diagram book.
- 116 -
Diagram and Details Window.
A Constructor Diagram is used to graphically represent the simulation model. The various model
variables are presented by variable symbols. The relationships between the model variables are shown
by means of connector symbols. In addition, value output and input is provided through auto reports
and controls.
Variables
There are four types of variables: levels, auxiliaries, constants, and submodels. The level can be filled
or depleted, very much like a bathtub. The flow that fills or depletes it corresponds to either the faucet
or the drain. Auxiliaries compute and pass on information. Constants are, as the name implies,
constant during the course of the simulation and can only be changes by user input. Auxiliaries can
also be used to control the flow between levels. In these cases they are referred to as flow rates.
Any variable in Studio can contain child variables. Child variables within levels, auxiliaries, and
constants can access any variable outside their parent variable, but cannot themselves be referred to
by variables outside their parent. They cannot be included in diagrams outside their parent's own
diagram book, either.
Submodels are specialized containers for child variables, and you can create full models within them.
Since they only act as child variable containers, they don't have a definition, data type, or unit.
Through the use of public variables you can allow input and output from your submodels. These
public variables can refer to any variable above them in the hierarchy, they can themselves be referred
to by variables outside the parent, and they can be included in the diagram in which their parent
variable exists. You can also create submodels as copies of existing components.
Connectors
There are two types of connectors: Flows and Links. Flows represent relationships between levels,
while links can represent relationships between both auxiliaries and levels.
- 117 -
Variable and connector symbols as they appear in a Constructor diagram in Studio.
The Model
The model is built up of the basic building blocks mentioned above. The level can be filled or
depleted by flows. Valves control the flows and can in turn be controlled by auxiliaries used as rate
variables. Auxiliaries compute necessary information and make it available to other variables. The
information links between them represent the channels of information in your system.
When you create variables and connections between the variables in the diagram, you must also
eventually determine their relationships in quantitative terms. You have to define equations for the
rates and auxiliaries. These mathematical expressions combine to form the model. Technically
speaking, the diagram is not the model itself but rather a representation of it, and you are free to
choose which parts of the model to include in the diagram. You can, however, build and modify your
model just working with the diagram. Studio takes care of the calculus involved in computing the
value of the levels.
The table below summarizes the various symbols that can appear in a Constructor diagram.
Symbol Name Description
Level A variable that accumulates changes. Influenced by flows.
Array variables A variable symbol with double frames indicates that the variable
it represents is an array.
- 118 -
Variable with A document indicator indicates that the variable has diagrams.
diagrams Any variable can have its own diagrams and child variables.
Permanent A variable symbol with a pin in the upper left corner indicates that
variables the variable is a permanent variable. Permanent variables keeps
their value when the simulation is reset. The permanent symbol
can appear on constants and levels.
Variable with A variable symbol with an arrow in the upper right corner
transfer direction pointing outwards, indicates that the variable has its transfer
set to out direction set to out. This implies that values from the variable is
exported from the model via co-models (such as datasets).
Variable with A variable symbol with an arrow in the upper right corner
transfer direction pointing inwards, indicates that the variable has its transfer
set to in direction set to in. This implies that values are imported to the
variable via co-models (such as datasets).
Variable with A variable symbol with an arrow in the upper right corner
transfer direction pointing both ways, indicates that the variable has its transfer
set to in-out direction set to in-out. This implies that an initial value is
imported to the variable at the start of the simulation (the hollow
arrow indicates an initial import), while for the rest of the
simulation, values are exported from the variable via co-models
(such as datasets).
Public variable A public variable inside a submodel is indicated by a cross in the
upper right corner. A public variable can be included in the
diagram of the parent variable, can be referred to by variables
outside the submodel, and itself refer to variables outside the
submodel.
Snapshot A variable symbol with an extra set of corners represents an alias
for another variable on the same diagram. Snapshots are useful for
linking variables located in different parts of a model.
- 119 -
variables.
Cloud A symbol illustrating an undefined source or outlet for a flow to
or from a level. The cloud symbol, also referred to as the source
or sink or a flow, indicates the model's outer limits.
Cloud for public A symbol illustrating an undefined source or outlet for a public
flow flow to or from a level inside a submodel. A public flow can be
connected to a level outside the submodel.
Error symbol A symbol with a '?' (question mark) indicator indicates that the
symbol is not properly defined. The undefined symbol can appear
on variables and flows.
Inconsistency in A symbol with a '#' (hash mark) indicator indicates that there
diagram exists inconsistencies between the diagram and model definitions.
The inconsistency symbol can appear on variables, links, and
flows.
Controls, freeforms, auto reports, etc., are also symbols in the diagram. They are however not shown
above, since their appearance and presence in the diagram is immediately obvious.
Diagram errors and inconsistencies are shown by error ( ) and inconsistency ( ) indicators
respectively. These indicators appear where the appearance of the diagram does not match the
variable definitions. The table below shows how these symbols are shown and what they can mean.
The list is not exhaustive but displays the most common errors and inconsistencies.
You can read a message explaining the error or inconsistency by hovering the mouse pointer over the
indicator, as illustrated below.
Read a tool tip describing the error or inconsistency when hovering the mouse pointer over the error
or inconsistency indicator.
Display Description Tip!
Error indicators on model Inspect the definition on the
variable symbols indicate that Definition property page. Check for
their variable definitions are unit inconsistencies or use the
invalid. Function Wizard to debug your
function expressions.
Error indicators on flows into Inspect the flow rate's and level's
or out of levels indicate that definitions on the Definition
the flow rate or level is not property page. Common mistakes
correctly defined. The error are that flow rates are not defined
indicator shows on which with rate units (e.g. 'people/day'),
side of the flow the error and levels using a compatible
occurs. accumulated unit (e.g. 'people').
Inconsistency indicators on Reconnect the correct flow rate to
- 120 -
flows indicate that the flow the valve, or simply delete the flow
doesn't represent a flow in the and create a new, correct flow
underlying model. instead.
Note! If you display your model diagram in User or Presentation Mode, the error ( )and
inconsistency ( )indicators will be hidden.
Controls and auto reports are used to present simulation results, and also allow user input to the
simulation. Auto reports are simple presentation tools that show the values of single variables.
Controls are more advanced, and allow you to define them more freely. You can also choose to
present the values from several variables in each control. Whereas auto reports can only present data,
controls can also be used for data input.
- 121 -
A number auto report (for 'Income') and a time graph auto report allow you to inspect the behavior of
the variables as the simulation advances. The final report is done using a time graph control.
Together, the controls and auto reports let you create an interactive user interface for your simulation.
The user can enter data into the simulation in one control, for instance a slider, and inspect the results
of the simulation in another, say a time graph.
You can also use pictures to enhance your diagrams. You are allowed to use picture fills for all
controls, symbols, and frames that support fills. The illustration below shows how pictures can be
used.
By using picture fills inside controls, frames, and other symbols, you can make your diagram a
visually pleasing sight.
The objects of a diagram are, when overlapping, placed on top of each other in a particular order.
This is the normal stacking order of symbols and objects, from top to bottom:
Stacking order
1 Auto Reports
2 Names
3 Links
4 Flows and Valves
5 Variables
6 Powersim Controls
- 122 -
Toggle between Design and User Mode
Note! When Studio is in Run mode, you are not allowed to make changes to the structure of the
simulation model. You can only play the simulation and provide input to the simulation through
controls.
You can change the order of the objects on the diagram by using the Layout toolbar. An object can be
sent to the back of the stack, to the front, or be moved step-wise through the stack in both directions.
! Click Bring Forward on the Layout toolbar.
! Click Send Backward on the Layout toolbar.
! Click Bring to Front on the Layout toolbar.
! Click Send to Back on the Layout toolbar.
Note! There are certain restrictions to how you can order the objects and symbols on a page.
As an example, you cannot move a level symbol behind a frame symbol (to read more, click the
The Stacking Order of Diagram Objects link below).
- 123 -
Work with Variables in Constructor Diagram
A model consists of variables that are linked together and interact with each other. Building a model
in Powersim Studio is done by creating variables, and defining them and the way they interact. The
model is created graphically, and you can easily see how the variables interact through the way they
are connected to each other.
In Powersim Studio, variables can contain child variables, allowing you to create a hierarchical model
structure. Although any variable in Studio can contain child variables, the submodel variable type is
specifically designed for containing models.
There are several types of variables in Powersim Studio:
! Levels represent accumulations in the system that is being modeled. They can be regular levels
or reservoirs. The latter can never be depleted below zero.
! Auxiliaries receive, compute and pass on information. Regular auxiliaries change their value
over time.
! Constants are computed only at the initial time step of the simulation. From that time on, they
are constant. They can, however, receive input from input controls, such as tables, switches, etc.
Constants that are marked as Permanent will never be recalculated, and will retain their given
value (user-assigned) between simulations.
! Flow rates control flows to and from levels. Any variable that has a value can be used as a
flow rate.
! Submodels are hierarchical, and only as containers for their child variables. Submodels doesn't
have values.
Tip! You will get tips in the status bar when you work with links and flows. The tip follows the
movement of the cursor, so if you wonder whether you can perform an action or not, simply
hover over the target symbol and read the message in the status bar!
- 124 -
About Snapshots
When a model diagram becomes large or complex, you can make snapshots of variables to avoid
awkward links. A snapshot will always have the same value as the original symbol, and you can
create links from it to make it available to other variables' definitions. However, you can only create
links from it, not to it. You can therefore only use snapshots to provide input to other variables, and
not to the variable it represents.
You can have as many snapshots of each variable as you like in the diagram. Although the snapshot
will adopt the formatting of the original variable symbol, you are free to format each snapshot
independently. When working with a snapshot, you should keep in mind that definitions and
documentation refer to the original variable, while symbol formatting refers to the snapshot itself.
Tip! You can go to the original symbol by right-clicking the snapshot and select Go to Original
on the shortcut menu.
Since a snapshot cannot accept incoming links (only outgoing), you will sometimes experience a need
to change a snapshot into the original symbol. This is possible by right-clicking the snapshot and
selecting Make Original on the shortcut menu. The original symbol will immediately become a
snapshot.
Note! You cannot make a snapshot into an original if the original symbol has input links. In
this case, the menu item will be disabled.
You can only create snapshots of variables that are already present in your diagram. To include a
variable that is not present in your diagram, use the Include Variable command.
If you have several snapshots of a variable in a diagram, and then exclude the original symbol, one of
the remaining snapshots will become the original symbol instead. Thus, to completely exclude all
instances of a variable in your diagram, you must exclude all snapshots as well.
A snapshot is indicated by an extra set of corners around the variable symbol. Apart from that they are
identical to the variables they refer to.
Note! Links are only allowed from, not to snapshots. Flows are not allowed at all!
Create a Level
A level is a variable with a memory. It accumulates value very much like a bathtub collects the water
running from the faucet. It is the level that makes a model dynamic. It accumulates flows going into it
and subtracts flows going out of it.
1. Click Level on the toolbar.
2. Click in the active diagram where you want to insert a level of the default size, or click and drag
to create a level of a different size.
3. Double-click the level to define it.
- 125 -
Levels must have an initial value. This initial value can be a number, but it can also be the value of
another variable.
Tip! You can drag the level to the desired size when creating it, or you can resize it after it has
been created.
Tip! If you double-click Level, the tool becomes persistent, so that you can insert multiple
levels without having to click the tool each time. When you are finished, click Pointer or hit
Esc.
Create an Auxiliary
An auxiliary receive, compute, and then pass on information within one time step. An auxiliary
change its value over time.
1. Click Auxiliary on the Diagram toolbar.
2. Click in the active diagram where you want to place the auxiliary, or click and drag to create an
auxiliary of a different size.
3. Double-click the auxiliary to define it.
Tip! You can drag the auxiliary to the desired size when creating it, or you can resize it after it
has been created.
Tip! If you double-click Auxiliary, the tool becomes persistent, so that you can insert
multiple auxiliaries without having to click the tool each time. When you are finished, click
Pointer or hit Esc.
Create a Constant
1. Click Constant on the Diagram toolbar.
2. Click in the active diagram where you want to place the constant, or click and drag to create a
constant of a different size.
3. Double-click the constant to define it.
A constant will not change over time. Thus, even if it is defined by an expression that would normally
vary as the simulation advances, it will retain the initial value of the expression at the start of the
simulation.
Tip! You can drag the constant to the desired size when creating it, or you can resize it after it
has been created.
Tip! If you double-click Constant, the tool becomes persistent, so that you can insert
multiple constant auxiliaries without having to click the tool each time. When you are finished,
click Pointer or hit Esc.
- 126 -
Create a Flow Rate Variable
When you create a flow using the Flow tool, you must manually connect the flow rate that is going
to control the flow, to the flow valve. If you use the Flow with Rate tool, an auxiliary flow rate is
created automatically.
You can use any variable (including levels) as the flow rate for a flow by connecting it to the flow
valve. Only one variable can be connected to a valve.
1. If there is another variable connected to the flow valve, either the link or the variable itself must
be deleted. To delete the link, select the variable and drag it away from the valve. You can now
delete the link itself.
2. Use the Link tool to connect the new flow rate variable to the flow valve.
3. To attach the variable to the flow, drag it close to the valve. When it is close enough, it will
automatically connect to the flow valve, as shown below.
Tip! You can also right-click the valve itself and use the Detach Rate from Valve and
Attach Rate to Valve commands to detach or attach the connected flow rate automatically.
A flow rate variable is connected to the valve using an information link. It can also be attached to the
flow valve by dragging it close enough.
Note! A flow rate must always be defined with a unit relative to time and the flow it controls. If,
for example, the level is defined as 'm', then the flow rate must be defined as 'm/s', 'm/da', or
similar. Otherwise the connected flow will not be correctly defined.
Create a Snapshot
A snapshot is a "shortcut" to another variable in your diagram. The snapshot represents the variable
symbol and is a convenient way of creating tidy model diagrams for large models. By using a
snapshot, you can represent a variable many times in the same diagram, avoiding the long links
required to connect the variable to other variables in different places of your model.
You are allowed to create links from a snapshot, but you cannot create links to them. Only the original
variable symbol can have links going into it.
To create a snapshot of a variable (or a group of variables):
1. Select the variable(s) you wish to create snapshot(s) for.
2. Drag the selected variable(s) to the target area using the right mouse button. When you release the
- 127 -
mouse button, a shortcut menu will appear.
3. Select Copy with Snapshot Creation Here on the shortcut menu to create snapshot(s) of the
selected variable(s).
Note! If you drag the variable(s) using the left mouse button, you will move them in the
diagram!
You can easily find the original symbol that a snapshot represents:
1. Right-click the snapshot and select Go to Original on the shortcut menu.
Tip! You can also convert a snapshot into the original symbol, if you wish to. The command
Make Original is available on the snapshot's shortcut menu.
If you wish, you can turn a snapshot into the original symbol:
1. Right-click the snapshot you wish to turn into the original, and select Make Original on the
shortcut menu.
The symbol that was previously the original symbol will automatically be converted into a snapshot.
A snapshot can only have links from itself, and no links to itself. If you perform this operation, you
may therefore get quite a few inconsistencies in your diagram. You must go through the model and
connect all input links to the new original symbol, and remove the input links from the old original
symbol, which is now a snapshot.
Create a Reservoir
A reservoir is a level that cannot be depleted below zero. When the simulation engine depletes a
reservoir, it will subdivide the time step into smaller parts to calculate the depletion exactly. If the
below drops below zero, the value of the reservoir becomes undefined (NAN).
- 128 -
1. Click Level.
2. Click inside the active diagram where you want to insert a level of the default size, or click and
drag to create a level of a different size.
3. Right-click the level, and select Advanced on the shortcut menu, and then select Reservoir on the
submenu.
or
1. Click Level.
2. Click inside the active diagram where you want to insert a level of the default size, or click and
drag to create a level of a different size.
3. Double-click the level to define it.
4. Click the Advanced tab.
5. Select the Reservoir option under Characteristics.
6. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Just as for ordinary levels, reservoirs must also be defined by an initial value. This initial value can be
a number, but it can also be the value of another variable or expression.
You must make sure that the flows out of the reservoir stops once the reservoir is depleted, since the
reservoir's value will become NAN rather than negative.
A Reservoir Symbol is similar to a Level Symbol, except it has a double line at the bottom.
Note! The simulation engine will recalculate the entire simulation model when the size of the
timestep is altered for the reservoir. You should therefore be aware that your model might
produce slightly different results when using reservoirs than when using ordinary levels.
Variables must have unique names. As soon as you create a variable, it receives a default name, which
is unique.
To rename an object:
1. Click anywhere inside the name. The pointer becomes the shape of a caret.
2. Type the new name.
3. Press Enter or click outside the name box to assign name and exit naming mode.
Note! Long variable names will be broken into several lines when displayed in the diagram.
This is done automatically, and you cannot control the line breaks of variable names manually.
When the variable has been selected and is active, start typing the name. The old name is
automatically deleted. The F2 key toggles the edit mode for the active object!
- 129 -
Resize a Basic Variable Symbol
1. Select the symbol(s) that you want to resize.
2. Move the pointer over a selection handle.
3. Drag the handles to achieve the desired size.
or
1. Select the symbol(s) you want to resize, and click Properties.
2. Select the Symbol tab.
3. Enter the new width or height under Position & Size, in the Width or Height box.
The latter method can also be used to change the position of the symbol(s) by using the Horizontal
and Vertical boxes, which control the position of the symbol in the diagram.
Variable symbols have minimum and maximum sizes. By using the Symbol tab in the Properties
dialog box, you can reset the symbol to its default size.
Tip! Reverse the default Snap to Grid setting by holding down the Alt key while resizing with
the mouse. Hold down Ctrl to resize from the corner of the object.
You can scale a variable symbol freely in the diagram to make it bigger or smaller than other
symbols.
1. Select the symbol(s) you want to scale, and click Properties.
2. Select the Symbol tab.
3. Enter the scaling percentage under Scale and Width or Height.
Note! The ration between the width and height of variable symbols are always locked.
- 130 -
Work with Links and Flows
Links and flows, or connectors, are diagram objects that connect variables in a diagram. They convey
information from one variable to another.
Flows connect levels and represent quantities transported between them. A flow has a source and a
destination (sink) attached to it. If one end is unconnected, a cloud symbol appears at the unconnected
end, indicating that the source or the sink of the flow is beyond the scope of the model or the diagram.
The flow is controlled by a valve that may be linked to an auxiliary variable, often referred to as the
flow rate.
A link provides a variable as a parameter to the variable at the end of the link. In fact, to keep the
diagram consistent, the variable at the end is required to use the one at the start in its definition.
Likewise, a link must always connect two variables; it cannot, like a flow, end in white space.
A link is by default an information link, but can also fill other functions, such as that of an
initialization link or a delayed link. Studio will automatically detect these situations based on the
definition of the linked variables.
Tip! You will get tips in the status bar when you work with links and flows. The tip follows the
movement of the cursor, so if you wonder whether you can perform an action or not, simply
hover over the target symbol and read the message in the status bar!
When creating and modifying links and flows, you can use keyboard modifiers to alter the appearance
of the link and flow. The table below summarize how these keyboard modifiers work. You apply the
modifiers by holding the keys down while working with the mouse the way you're used to. There are
three modifier keys: Ctrl, Alt, and Shift. You get different effects by using different
combinations of each.
- 131 -
Using the Alt key will reverse the Snap to Grid and Snap go Guides settings. If these settings are
enabled in the Layout, hitting Alt will temporarily disable them, and vice versa.
Using the Shift key will temporarily reverse the Snap to Radial Grid option, which is available in
Diagram Settings dialog box. If the option is already selected, hitting Shift will temporarily
disable it, and vice versa.
Using the Ctrl key have different effects when working with links and flows. If you are creating
links and flows, using the Ctrl key will toggle the segment type between Straight and Curved. Thus,
pressing Ctrl while creating a link, will create a straight link segment. Pressing Ctrl while creating
a flow, will create a curved flow segment.
Note! New flows are create with the Elbow style by default. The first time you press Ctrl will
automatically disable the Elbow option. You can enable it again on the shortcut menu for the
flow.
When moving a node that is connected to a symbol, the control handle of the node will always be
drawn in a straight line from the center of the symbol and through the node itself. However, by using
the Ctrl key, you can force the control handle to always be perpendicular to the edge of the symbol.
This allows you to move the connection point of the link or flow without significantly changing its
shape.
If you hold Ctrl while selecting a node, the node will be deleted.
Pressing Ctrl-Alt when dragging the vertex of a a control handle, will lock the connection point of
the node to the variable symbol.
You can also hit Del and Ins while creating links and flows. Hitting Ins will insert a new node,
while Del will remove the previously inserted node.
A link consists of one or more segments that can be either curved or straight. When a link is selected,
nodes appear at the points where the segments meet. Use the control points of the nodes, which
appear when you select the node, to change the shape of the link.
The Alt key temporarily reverses the Snap to Regular Grid setting. Use the Shift key to
reverse Snap to Radial Grid setting.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
- 132 -
Create a Link
1. Click Link.
2. Click inside the symbol you want the link to start from.
3. Drag the link to the destination symbol. You can divide the link into several segments by clicking
where you want one segment to end and a new one to start.
4. Click inside the destination variable to complete the link.
Hitting Del while drawing a freeform, link, or flow, will delete the last inserted node (except the start
node).
If you wish to create a straight link, hold down CTRL while you drag the link.
A link cannot be detached from one symbol and reattached to another. You have to delete the original
link and create a new one.
If you double-click Link, the tool becomes persistent, so that you can insert multiple links without
having to click the tool each time. When you are finished, click Pointer or hit Esc.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
To give a level or a constant an initial value, you can create a link to it from another variable. The
value carried by the link is then used to compute the initial step of the simulation. (The alternative is
to enter the initialization value directly in the level's definition.)
1. Click Link.
2. Drag the link from a variable to the level or constant you want it to initialize.
The link will be drawn as a dotted line.
Using initialization links together with levels enhances the readability of the diagram and makes it
easier to tune and optimize the model, for example with Powersim Solver.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
Use delayed links to let one variable influence another only after a certain amount of time has elapsed.
1. Use the Link to create a link between the variables.
2. Select the target variable.
3. Click Properties and click the Definition tab.
4. Define the variable using a delay function, for example DELAYPPL.
Studio will automatically detect when the link is used as a delayed link and will change the link into a
- 133 -
delayed link. This link type is shown below.
A delayed link indicates that the input variable is used in a delay expression.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
Delete a Link
1. Select the link you wish to delete.
2. Select Delete on the Edit menu, or hit Delete on the keyboard.
If you remove a link that is required for the diagram to be consistent, the diagram will become
inconsistent when you delete a link.
If a variable is defined by another variable without being connected by a link, a hash (#) will appear
to indicate the inconsistency. To remove the hash, simply create the link.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
A flow consists of one or more segments that can be either curved or straight. When a flow is
selected, nodes appear at the points where the segments meet. Use the control points of the nodes,
which appear when you select the node, to change the shape of the flow.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
- 134 -
symbol and read the message in the status bar!
Create a Flow
A flow can be created either between two levels in white space, or into or out of one level.
1. Click Flow with Rate (or click Flow to create a flow without a flow rate).
2. Click inside the source of the flow and move the pointer in the direction you want the flow to go.
3. Click in white space to start a new flow segment.
4. Click inside the destination level to complete the flow.
If you want the source or the sink of the flow to remain unspecified, either start in white space or
double-click in white space to end the flow. A cloud appears, indicating that this end of the flow
extends beyond the boundaries of the model.
The flow snaps to the radial grid by default. Press down the SHIFT key to temporarily turn off the grid.
To make a curved flow, press the Ctrl key.
If you double-click Flow with Rate, the tool becomes persistent, so that you can insert multiple
flows without having to click the tool each time. When you are finished, click Pointer or hit Esc.
The default flow type created by Studio is a continuous flow. To change it into a discrete flow you
must change the integration settings for the flow variable explicitly.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
A flow can be created either between two levels in white space, or into or out of one level.
1. Click Flow.
2. Click inside the source of the flow and move the pointer in the direction you want the flow to go.
3. Click in white space to start a new flow segment.
4. Click inside the destination level to complete the flow.
If you want the source or the sink of the flow to remain unspecified, either start in white space or
double-click in white space to end the flow. A cloud appears, indicating that this end of the flow
extends beyond the boundaries of the model.
The flow snaps to the radial grid by default. Press down the SHIFT key to temporarily turn off the grid.
To make a curved flow, press the Ctrl key.
If you double-click Flow, the tool becomes persistent, so that you can insert multiple flows without
having to click the tool each time. When you are finished, click Pointer or hit Esc.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
- 135 -
Disconnect Head or Tail of a Flow
1. Select the flow you want to disconnect.
2. Point to the node you want to disconnect.
3. Hold the mouse button down while dragging the node away from the level.
A cloud symbol will appear at the unconnected end of the flow, to indicate that the source or
destination of the flow extends beyond the scope of the diagram or the model.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
At any point, you may connect a flow to another level. You can perform this action on flows already
connected to another level, and flows that start or end in a cloud symbol.
1. Click the end node of the flow you want to reconnect and drag it over the level you want to
connect it to.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
The rate variable is by default attached to the flow valve. In some cases, however, you might want to
move it away from the valve.
! Drag the rate variable away from the flow valve until a link appears. Drop the rate wherever you
want to.
Or:
! Right-click the flow valve, and select Detach Rate on the shortcut menu.
To attach the rate to the flow valve again, perform the reverse operation.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
- 136 -
! Right-click the flow valve, and select Attach Rate on the shortcut menu.
A flow rate can be attached to the valve once a link is established and the flow rate dragged close
enough.
The flow rate must be attached to the valve by a link. Any variable can be used as a flow rate, even
levels and constants.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
When a flow is created, the rate and its valve are positioned in the middle of the flow. You may later
move the valve to any position along the flow.
1. Right-click the valve you want to move.
2. Select Move Valve to Next Flow Segment on the shortcut menu to move the flow valve to the
next segment of the flow. Alternatively, select Move Valve to Previous Flow Segment to
move the valve to the previous segment.
If the rate symbol is attached to the valve, it will be moved together with the valve. If it is detached
and connected to the valve by a link, it will not be moved.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
Before changing the flow rate of a flow, the existing flow rate must either be detached from the flow
valve, or deleted.
1. Delete the flow rate by selecting Delete on the Edit menu,
or
drag the flow rate away from the flow valve, select the link that connects them, and delete it by
selecting Delete on the Edit menu.
2. Connect the variable you want as the new flow rate to the valve by creating a link from the
- 137 -
variable to the flow valve.
The variable now acts as a flow rate and controls the flow.
A flow rate that is linked to a valve by an information link, can be attached to the valve by dragging it
close enough to the valve in the diagram.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
Delete a Flow
1. Select the flow you wish to delete.
2. Select Delete on the Edit menu.
or
1. Select the flow you want to delete in the diagram.
2. Hit Delete on the keyboard.
The flow rate will not be deleted though you delete the flow it controls.
You will get tips in the status bar when you work with links and flows. The tip follows the movement
of the cursor, so if you wonder whether you can perform an action or not, simply hover over the target
symbol and read the message in the status bar!
- 138 -
Build Hierarchical Models
Studio introduces hierarchical structures to simulation models - the ability to create submodels within
your model. The most striking advantage is that you can divide your simulation model into smaller
sections, each contained within its own submodel. Your main model will connect the various
submodels and only contain the variables that are unique to the "top-layer" of the model.
In a hierarchical model all variables are allowed to contain child variables. Submodels are different
from other variables, since they only act as containers for child variables, and therefore don't have a
value nor a data type. Using Submodel variables is the preferred way of making hierarchical models,
and offers more advanced functionality than submodels created within variables of other types. As an
example, public variables that can be accessed from outside the submodel is only permitted within
Submodels, while submodels within variables of other types can only be accessed from within the
variable itself.
Note! How to define variables in hierarchical models are explained in detail here.
The illustration below shows what an hierarchical model may look like. In this example, a conveyor is
implemented as a submodel that accepts any number of flows into the conveyor, and one total output
from it.
- 139 -
The submodel structure used in the conveyor model above.
Note! The complete description and definitions of the Conveyor model are available here.
Note! If you delete a variable (submodel) that has diagrams, you cannot undo the deletion! The
deleted variable, all its child variables, and all its diagrams will be lost.
About Submodels
A submodel in Studio refers to the variable type submodel and how it is used inside a model. Unlike
auxiliaries, levels, and constants, the submodel doesn't have a definition, and consequently doesn't
have a value during simulation either. The submodel is merely a container for child variables, and as
such it offers more functionality for its child variables than other variables does. A submodel is
represented by an octagon in Constructor diagrams.
The submodel symbol as it appears in a Constructor diagram. You are allowed to alter the size and
aspect ratio of the symbol, unlike other variable symbols.
When using submodels, you can utilize the advanced features listed below.
Diagram book
Each variable in a Constructor diagram can contain its own diagram book. This diagram book is
identical to any other diagram books in Studio, and allows you to create your submodel just as you
would create any other model in your project. That a submodel (or any other variable for that matter)
has its own diagram book is indicated by a small document indicator in the lower left corner of the
variable symbol.
When a submodel (or another variable) has a diagram book, a small document indicator is attached
to the lower left corner of the variable symbol.
Public variables
In a submodel, only public variables can access or be accessed by sibling variables of the parent
variable. A small indicator in the upper right corner of the symbol indicates that a variable is public. A
public variable can also be accessed by child variables of its own sibling variables.
- 140 -
When a variable is made public, an indicator appears on the upper right corner of the variable's
symbol.
A public variable can be included in the parent's diagram. It will be connected to its parent with a
satellite line and a small circle indicates the parent of the relationship.
If you include a flow rate in a parent diagram, the flow itself will also be included if it is open in one
end. If it is connected in both ends, the flow will not be included.
Note! When you edit the definition of an included variable, all variable references are relative
to the parent rather than the child variable itself. This means that you don't have to type
"Parent~" for each variable you use in the included variable's definition. However, if other
variables (siblings of the parent) use the included variable in their definitions, they must use the
correct syntax (Model_1.Auxiliary_1 in the picture above).
Anonymous flows
Anonymous flows allow you to merge several flows from a submodel to the same level into one flow
without a flow rate. This hides implementation details if desired, and indicates how flows run through
your system.
Two (or more) flows from the same submodel into the same level can be simplified into an anonymous
flow.
- 141 -
Copy components as submodels
You can copy any pre-made component from any simulation project as a submodel inside your model.
This allows you to model common or similar structures only once in a component, and then reuse this
component in later projects. The variables you have set a transfer direction for, will be automatically
defined as public in the submodel. You can also select to not copy the definition for selected variables
when the submodel is created. This is useful for variables that provide input to the submodel, as it
allows you to easily connect these to variables in the parent diagram by dragging links from these
variables to the submodel symbol itself.
Note! After you have copied the component to a submodel, no link will exist between them.
Changes you perform to the component will not be reflected in the submodel, and vice versa.
Any variable in a Constructor diagram can have its own diagram book. The diagram book is created
the first time you open the diagram book for the variable. A variable that has a diagram book has a
diagram indicator in its lower left corner, as shown below.
When a variable has a diagram book, it receives a small diagram indicator in the lower left corner.
Any variable in Studio can have its own diagram book.
The diagram book can be opened in two ways:
! By right-clicking the variable and selecting Open Diagrams on the shortcut menu;
! By double-clicking the variable's diagram node in the Project Window, or by right-clicking it
and select View on the shortcut menu.
Note! If you delete a variable that has diagrams, you cannot undo the deletion! The deleted
variable, all its child variables, and all its diagrams will be lost.
Child variables within a submodel (of the submodel variable type) can be defined as public. In a
submodel, only public variables can refer to variables outside the parent variable, or can themselves
be referred to by variables outside the parent variable. A public variable is indicated by a cross in the
upper right corner in a Constructor diagram, or by a green dish in a tree view (see illustration).
- 142 -
a) b)
You can create child variables within auxiliaries, levels, and constants. Other accessibility rules are
valid for child variables within these variable types than for child variables of submodels. In
particular, child variables of auxiliaries, levels, and constants cannot be made public, and can
therefore not be included nor referred to by variables above them in the hierarchy. They can
themselves refer to any variable above them in the hierarchy, though, so they are highly useful as an
alternative means of calculating the value of their parent variable.
Any variable in a Constructor diagram can have its own diagram book, also auxiliaries, levels, and
constants. This makes it simple to create models within them. Each variable contains its own name
space, so you can reuse variable names in various parent variables.
The example below shows how a model inside an auxiliary can be used to calculate the payroll tax of
a given salary (represented by a variable on the parent's level). The submodel of the auxiliary Payroll
Tax is shown below.
- 143 -
// its child variable 'Due Payment'
{ // The variables below are children of 'Payroll Tax'
const 'Payment Period' = 2 <>
const Percentage = 14%
level Due = 0 <>
aux Amount = Parent~'Gross Salary Payment'
aux 'Due Amount' = Amount * Percentage
aux 'Due Payment' = IF(TIMECYCLE
(STARTTIME,'Payment Period'), Due,0 <>)
} // End of 'Payroll Tax's child variables
In the final model, the auxiliary Payroll Tax can be used to control a flow deducting the payroll tax
from the company account. To see the entire example, please click here.
There are various consistency rules that apply to submodels and how its child variables can be
included in the parent diagram. Some of these rules are described below.
Note! The child variables described below must all be public variables, since this is a
requirement for a child variable to refer to or be referred to by variables outside the submodel.
It is also a requirement for the child variable to be included in the parent's diagram.
a)
b)
A flow can either be connected directly to a) a submodel or to b) a public level that is included in the
parent diagram.
- 144 -
as shown in the figure below.
A flow can either be connected directly to a) a submodel or to b) a public level that is included in the
parent diagram.
Note Observe that even if both the level and the flow rate are public, you are not allowed to
connect them in the parent diagram. This prevents implementation details from the submodel to
be exposed in the parent diagram.
a) b) c)
If a child variable refers to a variable outside the submodel, a link is optional as long as the child
variable is not included in the parent diagram. When the child variable is included, the link is
required, as in c above.
If a variable on the submodel's level refers to one of its children, a link is only required if the child
variable is included in the parent diagram. as illustrated below. Otherwise, a link between the
submodel and the referring variable is optional.
- 145 -
a) b) c)
If a variable refers to a child variable inside the submodel, a link is optional as long as the child
variable is not included in the parent diagram, as shown in a) and b) above. When the child variable
is included in the parent diagram, the link is required, as shown in c) above.
The same applies to child variables that refer to the child variables of other submodels. In this case, a
link is optional between the two submodels as long as none of the child variables are included. A link
from one submodel to an included child variable, however, will become inconsistent. To make a
consistent diagram, include both child variables and draw the appropriate link between them.
Create a Submodel
1. Click Create Submodel on the Diagram toolbar.
2. Click in the active diagram where you want to place the submodel, or click and drag to create a
submodel of a different size.
3. Right-click the submodel and select Open Diagrams to create a submodel within it. You can
also define it in the Equations View.
The diagrams for the submodel are created when you open them the first time. They are available on
the submodel's shortcut menu and in the Project Window.
Note! If you delete a submodel that has diagrams, you cannot undo the deletion! The deleted
variable, all its child variables, and all its diagrams will be lost.
Tip! You can create submodels from existing components in both the current project or in any
other simulation project you have created. Use the Copy Component into Submodel
command to achieve this.
Tip! You can drag the submodel to the desired shape and size when creating it, or you can
resize it after it has been created.
If you double-click Create Submodel, the tool becomes persistent, so that you can insert multiple
auxiliaries without having to click the tool each time. When you are finished, click Pointer or hit
Esc.
You can copy a component from any simulation project as a submodel in the current component.
When you have copied a component as a submodel, there will be no "link" between the two. The
component is copied and new variables are created. If you need to perform changes to the
- 146 -
implementation of the original component, these changes must also be done in the submodel
manually.
When a component is copied as a submodel, all variables that have a defined transfer direction will be
automatically converted to public variables. Also, if you deselect the Keep Definition in Component
Copy option on the Advanced property page, the definition of the variable will not be copied. This
makes it easier to connect the interface variables of the submodel to the rest of the model. When you
draw a link to a submodel, a dialog box containing the public child variables of the submodel will
appear. If you select a child variable in the list and click OK, a link is created to the submodel, and
the selected public child variable will automatically refer to the variable at the starting end of the link.
When you copy components as submodels, you can copy components from the same project or from
external files.
You can include a submodel's public child variables in the submodel's diagram.
- 147 -
1. Right-click the submodel symbol and select Include Variable on the shortcut menu.
2. Click in the diagram where you want to include the child variable. If there is more than one public
variable in your submodel that is not included, a dialog box will appear. Select the variable you
wish to include and click OK.
The included variable will be connected to the submodel by a satellite line. A circle on the submodel
symbol indicates the owner symbol.
Tip! To include several public variables at once, you can select Include Child Variable on
the submodel's shortcut menu, select an area where you want to create the symbols, and then
select the variables you wish to include in the appearing dialog box. The included variable
symbols will be distributed inside the area that you selected, starting in the upper left corner.
Any variable in Studio can have its own diagram book. When you open the diagram(s) the first time,
the diagram book is created. The diagrams are accessible in two ways, through the shortcut menu on
the submodel, and in Project Window.
When a variable has a diagram book, it receives a small diagram indicator in the lower left corner.
Any variable in Studio can have its own diagram book.
To open the diagram book:
! Right-click the variable symbol and select Open Diagrams.
If the variable doesn't already have a diagram book, a new will be created.
To open the diagram book (when it already exists):
! Browse the Project Window. Below the Shared Diagrams node, you will find the diagram
books of the various variables. Browse to the variable you wish to view, double-click the diagram
node, or right-click it and select View on the shortcut menu.
You can create links to and from your submodel and its included public child variables. When
creating links from a variable to a submodel, Studio will display a dialog box if the submodel contains
public child variables that can be defined by the source variable of the link. This makes it easy for you
to connect the submodel to the variables surrounding it on the parent's level.
Note! Since variables outside the symbol can only refer to or be referred to by public variables
within the submodel, the following only applies to public child variables!
- 148 -
To create a link to a submodel:
1. Create a link from a variable to the submodel.
2. A dialog box appears, containing a list of the public variables of the submodel. This dialog box
allows you to automatically generate a definition for the public variable that contains a reference
to the variable at the start of the link. Select a public variable and click OK. Alternatively, if you
want to create the link without changing any definitions, select the Create Link Only option in
the dialog box and click OK.
You can also create a link the opposite way, from a submodel and to a (sibling) variable. In this case,
no dialog box will appear, so you must manually alter the variable's definition.
Creating links to and from public variables that are included in the parent's diagram is identical to
creating links to and from any other variable in the diagram. Simply draw the link from the source to
the target variable.
If you want to use a variable in the definition for more than one public child variable, you only need
one link from the variable to the submodel. However, you can easily define the variables by creating a
link from the variable to the submodel again, and define the public child variable using the Define
Child Variable dialog box. When you click OK, the link will disappear (as two links cannot exist
between two objects in a diagram), but the child variable will be correctly defined.
Tip! Sometimes a public child variable will have an explicitly defined unit, dimension, or data
type. If the list of the Define Child Variable dialog box contains public child variables that have
one (or more) of these three properties explicitly defined, this property(-ies) will be shown in
the Explicit Definition column. This information is included for your convenience.
Tip! You can sort the contents of the Define Child Variable dialog box by clicking the column
headers.
You can create flows that run in and out of levels in your submodel. These flows can be controlled by
flow rates that are siblings to the submodel, or they can be controlled by flow rates that are children of
the submodel. If the flows are controlled by siblings to the submodel, they can also be connected
directly to the child level, provided that the child level is included in the parent's diagram. These three
scenarios are shown in the figure below.
a)
b)
- 149 -
c)
A flow controlled by variables can either be connected directly to a) a submodel or to b) a public
level that is included in the parent diagram. A flow controlled by child variables that are included in
the parent's diagram can be connected directly to the submodel. These flows cannot be connected to
the child level, even if it is included in the diagram.
When you attach a flow to a submodel symbol, a dialog box containing all the public levels of the
submodel appears. You use this dialog box to select which level you want to connect the flow to.
Note! Only flows controlled by public variables and that are unconnected in one end can be
included in the parent diagram.
Note! If you wish to include only the flow rate and not the flow itself, you follow the procedure
above. When the flow is included, right-click it and select Exclude Flow(s) on the shortcut
menu.
- 150 -
Create an Anonymous Flow
Anonymous flows allow you to indicate the direction in which the information or material in your
system flows, without showing the flow rate. Flows can only be made anonymous when they are
connected to a level or a submodel in both ends of the flow.
Follow the procedure below to create an anonymous flow. The procedure requires that the levels,
flows, and flow rates are already present in the diagram.
1. Right-click the flow rate controlling the flow you wish to make anonymous, and select
Exclude Variable on the shortcut menu. The flow will automatically become anonymous.
2. Repeat step 1 for the flow rates of all the flows you wish to convert.
3. Delete all but one of the flows. As long as the flow rate is excluded, deleting a flow will not
destroy the structure of your model.
The illustration below illustrates how anonymous flows can be utilized to create a simpler model that
is easier to understand.
a) b)
You can greatly simplify the flow structure of your model by using anonymous flows. The models in a)
and b) show the same model structure, but a) uses ordinary flows, while b) utilizes anonymous flows.
The valve will return on the flow if you right-click it and deselect the Anonymous Rate option. To
make the flow valid, you must also include the flow rate controlling the flow, and connect it to the
valve of the flow, otherwise the flow will be inconsistent.
- 151 -
Work with Diagram Editing
In Powersim Studio you have a lot of editing capabilities by drag and drop. These allow you to:
! Move objects from one location in the diagram to another.
! Copy objects from one location in the diagram to another, or to the Clipboard.
! Copy objects from one diagram to another, or between views.
! Cut objects and move them to the Clipboard.
! Paste objects from the Clipboard to the diagram.
! Copy an Area as a Picture to easily copy a section of a diagram to the Clipboard and paste them
in another application as a picture (Enhanced Metafile).
! Link objects in the diagram to variables in the model, for example give a time graph parameters to
display.
! Delete objects in the diagram.
You use the mouse to control a lot of the operations in Powersim Studio. You can copy, move, resize,
select and format objects in the diagram using the mouse. This is achieved by using ordinary drag-
and-drop (holding the left mouse button while dragging), and by using various keyboard accelerators
while dragging (holding down CTRL will create a copy, while no accelerators will perform a move
operation). In addition, if you drag-and-drop by using the right mouse button rather than the left, a
menu will appear where you drop the object, allowing you to select the operation to perform.
If you wish to cancel the drag-and-drop operation, hit Esc during the operation. The diagram will
scroll automatically if the target area is beyond the visible area of the diagram.
Transfer operations can be achieved in several ways. Move operations can be performed by drag and
drop, by keyboard shortcuts, or by accessing the property page for the symbol, and alter the
coordinates of the position. Cut and copy operations can be achieved by right-clicking an item or a
selection of items; by drag and drop; by accessing the Edit menu; or by using toolbar buttons. Linking
operations can be performed by accessing the controls property page, or by drag and drop.
- 152 -
various Add operations, Cut, Copy, and Delete.
In a Constructor diagram, however, three commands more are required to achieve all possible actions.
Include Variable will include a variable symbol for a model variable that is already present in the
model but not in the diagram. Exclude Variable will remove a variable symbol from the diagram
without deleting the variable itself from the model. And finally, Delete Variable will delete all
variable symbols in all Constructor diagrams, and delete the model variable itself from the model.
The two commands Exclude Variable and Delete Variable are both available on the shortcut menu for
a variable symbol.
As a safety precaution, the Delete command in a Constructor diagram works as a combination of
Exclude Variable and Delete Variable. The functionality of the Delete are shown below.
The functionality of the Delete command in Constructor diagrams:
1. If the variable symbol you are trying to delete are present in other diagrams as well, the variable
symbol will be excluded from the current diagram only. (Equivalent command: Exclude
Variable.)
2. If the variable symbol is only present in the current diagram, but is also represented by a snapshot
in the diagram as well, the variable symbol will be excluded and the snapshot be converted to an
original symbol instead. (Equivalent command: Exclude Variable.)
3. If the variable symbol is the only symbol representing the model variable in any diagram, the
variable symbol will be excluded from the diagram, and the model variable itself will be deleted
from the model. (Equivalent command: Delete Variable.)
Drag-and-Drop Operations
Within a diagram
! An unmodified drag-and-drop operation usually moves the object(s).
! Dragging with the Ctrl key pressed results in a copy operation.
! Dragging a variable into a Powersim control causes the control to show that variable's value during
the simulation.
! Dragging with the right mouse button produces a shortcut menu which lets you select the resulting
operation.
! Dragging with the Shift key makes it possible to position variables over objects (rather than
dropping them on the objects).
! Hitting Esc cancels a drag-and-drop operation.
! If the target area is beyond the visible area of the diagram, the diagram will scroll automatically.
- 153 -
the object to the target component.
! Dragging with the Ctrl key pressed results in a copy operation between the two components.
Tip! When dragging between diagrams in the same view, you can change diagram by hovering
over the sheet tab.
Note! If all variables are already shown in the diagram, this command will be disabled. If you
want to show the same variable in more than one place in a diagram, create a Snapshot
instead.
Excluding a variable symbol from a diagram doesn't delete the variable from the model. When a
model variable should still be present in the project but not in the current diagram, you can use the
exclude capability.
To exclude a variable from the diagram without deleting it from the model itself:
1. Right-click the variable you wish to exclude from the diagram, and select Exclude Variable on
the shortcut menu.
Note! If you delete a variable (submodel) that has diagrams, you cannot undo the deletion! The
deleted variable, all its child variables, and all its diagrams will be lost.
- 154 -
Using Delete
Deleting a variable symbol using Delete causes the symbol to be removed from the diagram.
If the symbol is the last symbol representing the model variable in ANY Constructor Diagram,
the model variable itself will also be deleted from the model. To remove the last variable
symbol from your diagrams but still keep the variable in the model, right-click it and select
Exclude Variable on the shortcut menu.
1. Select the variable(s) that you want to delete from the diagram.
2. Select Delete on the Edit menu, or hit Delete on the keyboard.
If you deleted a level that was connected to a flow, a cloud will replace the level in the diagram.
Note that other variables that received information from the deleted variable through a link will now
have illegal definitions.
Excluding a variable symbol using Exclude Variable causes the symbol to be removed from
the diagram. The model variable will not be deleted from the model.
1. Select the variable(s) that you want to exclude from the diagram.
2. Right-click the variable (or one of the variables), and select Exclude Variable on the shortcut
menu.
Deleting a variable using Delete Variable deletes the model variable itself in the model. All
variable symbols representing the model will automatically be removed from all diagrams.
1. Select the variable(s) that you want to delete from the model and diagram.
2. Right-click the variable (or one of the variables), and select Exclude Variable on the shortcut
menu.
There are two ways to link a variable to a dynamic control such as a graph, table, or a button. Either:
1. Drag the variable onto the control,
or,
1. Double-click the object, or right-click it and select Properties on the shortcut menu.
2. Select the Parameters tab.
3. Add parameters to the control by selecting them from the list.
4. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
This operation must not be confused with the Link tool that is used to connect two variables,
such as an auxiliary and a level.
- 155 -
Copy and Paste an Object
Tip! When copying between diagrams, hover over the sheet tab of the target diagram to change
active diagram.
Tip! You can achieve the same operation by dragging the object from one position to another.
This drag-and-drop operation is allowed between diagrams, both in the same component and in
different components.
You can easily copy an area in a diagram as a picture by either using Copy to copy a single object
or a selection of objects, or by using Copy Area as Picture to copy an area of the diagram.
To copy a selection of objects:
1. Select the object(s) you wish to copy by selecting them using the Pointer tool (holding down
Shift will allow you to extend the selection).
2. Click Copy in the toolbar or on the Edit menu, or use the shortcut Ctrl-C.
3. Go to the file where you want to use the picture, and paste it there (usually using a Paste tool).
- 156 -
The object will be pasted as a picture in the target application.
Tip! If you use this method to copy and paste an object in Studio, you will make a copy of it,
rather than a picture.
Note! Pictures are copied from Studio in the Windows Enhanced Metafiles format (*.emf). If
you experience problems pasting these pictures using the ordinary paste command in the target
application, you should try to select paste special, and then specify the file format as Enhanced
Metafile.
Studio allows you to paste text and pictures directly from the Windows Clipboard and onto a
Constructor Diagram. When you do this, the picture or text will be inserted in a new frame object
using the default frame settings. You can then format the frame in any way you wish.
1. Switch to the application from which you want to copy an object (can be any application such as
Notepad, Paintbrush, Word, Powerpoint, Excel, etc.).
2. Copy the object to insert.
3. Switch to Powersim Studio again.
4. Select the diagram in which you want to paste the object.
5. Click Paste (or hit Ctrl-V) to paste the object into the diagram.
Tip! Studio supports bitmaps and metafiles when pasting pictures and objects from the
Windows Clipboard.
You have to select an object, for example a variable, a connector, or a Powersim control in order to
modify or edit it in any way.
To select all objects in a diagram:
1. Select Select All on the Edit menu, or hit CTRL+A on the keyboard.
- 157 -
2. Select the type of objects you want to select in the Select Special dialog box. Click All to check
all options in the dialog box, and None to uncheck all options.
3. Click OK to select the specified objects, or Cancel to exit the dialog box without selecting any
objects.
Tip! To deselect an already selected object, click it while holding down the Shift key.
To perform the same operation on several objects, for instance formatting or moving, you first need to
select all of them. There are several ways of achieving this:
! Click each and every object while holding down shift.
! Use the Pointer tool to drag a rectangle around the objects you want to select. All objects
completely encompassed by the rectangle are selected.
! Select Select All on the Edit menu to select all objects in a diagram.
! Select Select Special on the Edit menu to select all objects of a certain type (or types) that you
specify in the Select Special dialog box.
All editing operations are now performed on the entire selection.
Note! On the property pages, only properties common to all the selected objects may be
modified.
For resizing and alignment purposes you sometimes need to select one object as dominant within a
multiple selection.
1. Make a multiple selection. One object is automatically made dominant.
2. If you want to make another object dominant, just click it.
The object with solid handles is the dominant one, as illustrated below. Alignment and resizing
operations are now dependent upon this object.
Move an Object
1. To move an object within or between diagrams, simply drag it to the desired position. Links and
other connectors will be automatically updated.
- 158 -
The operation will also work between components.
To reverse default Snap to Grid setting, hold down the Alt key.
Note! Coordinates [0,0] designate the upper left corner of the diagram.
Tip! If you prefer another unit of measure, change it from points (pt) to centimeters (cm) or
inches (in).
Note! Deleting a variable symbol in a diagram causes the symbol AND the underlying variable
to be removed from the model. In order to remove only the symbol from your diagram but keep
the variable in the model, right-click the symbol and select Exclude on the shortcut menu.
- 159 -
Work with Nodes, Segments and Lines
Links, flows and freeforms are represented by lines in the diagram. Each line can be divided by nodes
into segments. To reshape the line, be it a link, flow or freeform, you can change the properties for
individual nodes and segments. There is also a set of accelerator keys (Ctrl, Alt,and Shift)
available, allowing you to modify the nodes and segments directly without right-clicking them.
As shown in the figure below, each node has adjustment handles. These handles allow you to change
the shape of the connector at both sides of the node. The handles can be adjusted automatically, or
you can freely arrange them yourself. The choices are: Automatic, Symmetrical, Smooth and Cusp.
A node has adjustment handles that can be used to alter the shape of the connector on both sides of it.
Each segment of a line can also be individually adjusted. You have two choices: Straight and Curved.
If a segment is set to straight, it will override the settings of the adjacent node handles. This is shown
in the figure below.
A segment can be either straight or curved. If a segment is straight, it will override the adjustment
handles of the adjacent nodes.
You can also change the appearance for the entire line by using the line operations available on the
shortcut menu when you right-click a line. These line operations allow you to alter all nodes or
segments of a line at the same time. You can also change the line into one straight or curved segment
if you wish to.
Finally, a line can be elbowed, in which case all segments are straight, and all nodes are straight
angles, as shown below.
A line (the entire line) can have elbow shape. When a line is elbowed, all segments are straight, and
- 160 -
the nodes have no adjustment handles. When a node is moved, the segments next to it are also moved
correspondingly.
Types of Nodes
Nodes are used to shape lines in the diagram. A node affects the shape of the segments next to it,
allowing you to control the appearance of the line's segments freely. When you add a new node to a
line, it will always be an Automatic node, controlled automatically by Studio. You can however
change the type of the node by right-clicking it and selecting a new type on the shortcut menu.
There are four types of nodes: Automatic, Symmetrical, Smooth and Cusp. The table below
summarizes the differences between the types. The difference lies in the degree of freedom you have
when altering the control handles of the node.
Node Illustration Description
Studio takes care of the layout of the curve automatically. (If you
Automatic change the control handles, the node is automatically changed into a
Symmetrical node.)
The control handles are changeable. They will always be parallel,
Symmetrical and both handles will have the same length. The node ensures that
the adjacent segments are always symmetrical at the node.
The control handles are changeable. They will always form a straight
Smooth line, but they can have different lengths. The node ensures that the
adjacent segments are smooth but not symmetrical at the node.
The control handles are changeable and totally independent of one
another; they can both have different directions and lengths. The
Cusp
node allows you to create sharp bends between the adjacent
segments.
Types of Segments
Segments are the portion of a line that lies between two nodes. There are two types of segments:
Straight and Curved. If the segment is curved, the control handles of the nodes can be used to shape
the segment. If the segment is straight, however, the segment will be drawn as a straight line between
the nodes.
If you have made an elbowed line, all the segments of the line will all be straight. In addition, the
nodes will not only affect the position of the end (or start) of the segment. It will also affect the
starting (or ending) point of the segment, making sure that the segment is always horizontal (or
vertical). This is illustrated below.
Note! Only freeforms and flows can use the elbow style.
- 161 -
When a line is elbowed, moving a node will automatically adjust the starting and ending nodes of a
segment to ensure that the neighboring segments are always horizontal or vertical.
Note! When the Elbow option is selected for a line, the functionality for segments and nodes
are reduced. Segments can only be straight, and nodes must always have straight angles.
Add a Node
Note! When you add a new node, it will always be an Automatic node. If you wish to change
the type of the node, right-click it and select a new type on the shortcut menu.
There are four types of nodes: Automatic, Symmetrical, Smooth, and Cusp. When a new
node is added to a line, it will be an automatic node.
To change the type of the node:
1. Right-click the node you wish to change and select the new type on the shortcut menu.
The difference between the four different node types is mainly the amount of freedom you have when
controlling the position of the control handles.
! Automatic nodes: You cannot control the control handles at all.
! Symmetrical nodes: The control handles are always equally long and parallel.
! Smooth nodes: The control handles must be parallel, but they may have different length.
! Cusp nodes: The control handles can be adjusted completely independently from each other.
Delete a Node
1. Right-click the node, and select Delete Node on the shortcut menu.
- 162 -
If the deleted node connected a straight and a curved segment, the resulting segment will become a
curved segment.
Tip! Hitting Del while drawing a freeform, link, or flow, will delete the last inserted node
(except the start node).
You can apply an elbow style to lines in your diagram. When a line is elbowed, all angles will be
straight, and all segments will be straight as well. When a node is moved, the entire segments joined
- 163 -
by the node will be changed to retain straight angles and segments.
Note! Only freeforms and flows can use the elbow style.
Note! When the Elbow option is selected for a line, the functionality for segments and nodes
are reduced. Segments can only be straight, and nodes must always have straight angles.
When a line is elbowed, moving a node will automatically adjust the starting and ending nodes of a
segment to ensure that the neighboring segments are always horizontal or vertical.
Sometimes you might experience the need to convert a line with several nodes and segments into a
line with only one curved segment. Instead of manually removing each node and finally reshaping the
resulting segment to the desired shape, you can let Studio take care of the conversion automatically.
1. Right-click the line you wish to convert, and select Line Operations on the shortcut menu. Select
Single Curved Segment on the submenu.
You can have Studio automatically convert lines with several nodes and segments into a single curved
segment.
Sometimes you might experience the need to convert a line with several nodes and segments into a
straight line. Instead of manually editing the line, you can let Studio take care of the conversion
automatically.
1. Right-click the line you wish to convert, and select Line Operations on the shortcut menu. Select
- 164 -
Single Straight Segment on the submenu.
You can have Studio automatically convert lines with several nodes and segments into a straight line.
- 165 -
Work with the Details Window
You can use the Details Window to inspect all the variables on the current level of your model,
including their definitions and values. You can also create, delete, and define variables.
The Details Window will display the variables that are child variables to the owner of the diagram. If
you're in a submodel, only the child variables of the submodel will be shown. If you are in the main
diagram, the variables of the first level (child variables of the "root variable") will be shown.
Note! If you delete a variable (submodel) that has diagrams, you cannot undo the deletion! The
deleted variable, all its child variables, and all its diagrams will be lost.
The content of the Details Window can be auto-synchronized with the selection of the diagram. When
the auto-synchronization option is enabled, the variable you select in the diagram will automatically
be selected in the Details Window as well. This makes the window extremely useful as a construction
or debug facility.
The Details Window can be docked on the left side of the diagram window, and will display a list
containing all the variables of the current level of the model.
The default position of the Details window is along the left side of the diagram window. If you wish,
you can also dock the window at the top of the diagram window, allowing more columns to be visible
at the same time.
Working with variables and definitions in the Details Window is identical to working with variables
and definition in the Equations View.
- 166 -
Show and Hide the Details Window
1. Click Toggle Details Window on the toolbar or on the View menu.
or
1. Right-click the row of diagram tabs at the bottom of the diagram window, and select Details
Window on the shortcut menu.
The Details Window is shown (or hidden) in a column on the left-hand side of the variable window.
You can drag it to any desired width. You can also dock it on the top of the window by right-clicking
inside the view, and select Details at Top on the shortcut menu.
The Details Window appears on the left side of the Diagram Window by default, but you can also
place it at the top of the window, if you like.
The Details Window can be displayed at the left or at the top of the diagram window.
1. Click Toggle Details Window on the toolbar or on the View menu to display the Details
Window (if it is not already visible).
2. Right-click inside the view, and select Details at… on the shortcut menu. Select either Left or Top
in the submenu.
Displaying the Details Window on the top of the diagram window and using the Auto-synchronize
feature, makes the Details Window extremely useful for constructing and debugging models, as
illustrated below.
- 167 -
When displaying the Details Window at the top of the diagram window and enabling the Auto-
synchronization feature, you have a terrific design and debugging environment for your models!
The Auto-synchronize Details with Diagrams option will automatically scroll the Details Window
to the variable you selected in the diagram.
1. Click Toggle Details Window on the toolbar or on the View menu to display the Details
Window (if it is not already visible).
2. Right-click inside the view, and select Auto-synchronize Details with Diagrams on the shortcut
menu.
When you select a variable in the diagram, the same variable will be automatically selected in the
Details Window.
Tip! Hitting Alt-1 will automatically move focus to the Details Window.
Displaying the Details Window on the top of the diagram window and using the Auto-synchronize
feature, makes the Details Window extremely useful for constructing and debugging models, as
illustrated below.
- 168 -
When displaying the Details Window at the top of the diagram window and enabling the Auto-
synchronization feature, you have a terrific design and debugging environment for your models!
- 169 -
Work with Auto Reports
An auto report displays the value of the variable it belongs to. Auto reports offer a flexible way of
presenting simulation results.
Auto reports can display either the current numeric value, or a time graph displaying the development
of the variable over time.
There are two types of auto reports:
! Number auto report, which displays the current value of the variable. If the variable is an array, a
table will be displayed.
! Time graph auto report, which displays the development of the variable's value over time as a
graph.
Each variable can only have one auto report associated with it. When the auto report is switched on
the first time, it gets a default position close to the variable, opposite from the variable name. You can
drag it to another position, if you wish to. You are also free to format it in any way you please. When
the auto report is deleted, position information and formatting is deleted with it.
A number auto report shows the current value of a variable as a number. For arrays, the auto report is
displayed as a table.
1. Right-click the variable(s) that you want to show a number auto report for.
2. Select the arrow on Show Auto Report, and select Number Auto Report from the
dropdown list.
or
1. Select the variable(s) that you want to show a number auto report for.
2. Select the arrow on Show Auto Report, and select Number Auto Report from the
dropdown list.
A number auto report will be displayed opposite the name symbol of the selected variable(s).
- 170 -
The number auto report displays the current value of the variable.
Tip! When you click Show Auto Report, an auto report of the same type as the last inserted
auto report is inserted automatically.
A time graph auto report shows the time series for a variable as a time graph. For arrays, the auto
report will be displayed as a collection of graphs, with one graph for each array dimension.
1. Right-click the variable(s) that you want to show a number auto report for.
2. Select the arrow on Show Auto Report, and select Time Graph Auto Report from the
drop-down list.
or
1. Select the variable(s) that you want to show a number auto report for.
2. Select the arrow on Show Auto Report, and select Time Graph Auto Report from the
drop-down list.
A time graph auto report will be displayed opposite the name symbol of the selected variable(s).
A time graph auto report shows the value development of the variable over time.
Tip! When you click Show Auto Report, an auto report of the same type as the last inserted
auto report is inserted automatically.
In some cases, you may want to temporarily hide an auto report from the diagram. If you delete the
auto report entirely, all the formatting that you have applied to the auto report will also be deleted.
You therefore have the option to hide and unhide auto reports. In this case, all formatting will still be
preserved in your diagram.
! Right-click the belonging variable symbol, and select Hide Auto Report on the shortcut menu.
! Select the variable symbol in the diagram, and click Hide Auto Report on the toolbar
Tip! To unhide the auto report, click Unhide Auto Report. To delete the auto report
permanently, click Delete Auto Report.
- 171 -
Unhide an Auto Report
If a variable symbol already has a hidden auto report associated with it, you can unhide it. Its
formatting and position will be preserved.
! Right-click the belonging variable symbol, and select Unhide Auto Report on the shortcut
menu.
! Select the variable symbol in the diagram, and click Unhide Auto Report on the toolbar.
Tip! You can delete a hidden auto report by selecting the variable, and clicking Delete Auto
Report.
You can move an auto report around the symbol it belongs to.
1. Simply drag the auto report object to the desired position. It will snap to the radial grid.
Powersim Studio will remember the position of an auto report if you hide it. The next time you turn it
on, it will reappear in the same relative position to the variable it belongs to as it had the last time it
was displayed.
Tip! Turn off Snap to Radial Grid by holding down the Shift key.
- 172 -
Delete an Auto Report
Note! When an auto report is deleted, all formatting is lost. If you wish to temporarily remove
an auto report but keep its formatting, you should use Hide Auto Report instead.
Studio contains several features that makes it easy for you to lay out your model. By using grids,
guides, and rulers, you can fully control the alignment of objects on the diagram. In addition you can
also use the built-in commands for alignment and spacing.
Tip! Holding down the Alt key while working in the diagram reverses the current Snap to
Grid setting.
The radial grid allows you to draw straight lines at regular angles, such as links, flows or freeforms.
Note, however, that the radial grid will not have any effect when drawing curved lines (obviously). To
draw straight lines hold down the Ctrl key while drawing. To draw straight lines at regular angles,
hold down Ctrl-Shift while drawing.
Tip! Holding down the Shift key while working in the diagram reverses the current Snap to
Radial Grid setting.
- 173 -
Rulers
You can turn on (and off) rulers for each diagram. The setting will be saved for each diagram
individually. Rulers make it easier to align objects properly with each other, and they also make it
easier to add guides to your diagram.
Guides
Guides are straight lines that you can use to align objects on the diagram. You can insert both vertical
and horizontal guides. When used in combination with the regular grid, a guide will have precedence,
making the object snap to the guide rather than the grid. You use the Alt key to reverse the setting of
the Snap to Guide setting, but this works in conjunction with the Snap to Grid setting in the
following way:
Setting With Alt key
Snap to Grid Snap to Guides Snap to Grid Snap to Guides
On Off Off Off
On On Off Off
Off On On Off
Off Off On On
Tip! When the rulers are visible you can easily add guides by clicking inside the corresponding
ruler and drag a new guide onto the diagram area (click inside the horizontal ruler for a
horizontal guide, and inside the vertical ruler for a vertical guide). You can remove a guide
from the diagram by dragging it back onto the corresponding ruler again.
The rulers will appear on the left and on the top of your diagram. The position of the mouse pointer
will be shown on the rulers, supporting you when you are designing your diagram.
To show (or hide) the rulers:
! Select Rulers on the View menu.
! Right-click the diagram (outside symbols or objects), and select Rulers on the shortcut menu.
Tip! When the rulers are visible, you can easily insert guides by clicking inside the ruler, and
drag a new guide onto the diagram.
- 174 -
Turn the Display of Guides On or Off
There are several ways to permanently turn snapping to the normal grid on or off. On toolbars and
menus, the state of the Snap to Normal Grid button shows whether snapping is turned off or not.
When the button is pressed, snapping is turned on.
To turn on (or off) snapping to the normal grid:
! Click Snap to Normal Grid on the Layout toolbar or menu.
! Right-click the diagram (outside objects or symbols) and select Snap to Normal Grid on the
shortcut menu.
! Select (or deselect) the Snap to normal grid option on the Grid Settings property page to turn
snapping on (or off). The property page is available by right-clicking the diagram and selecting
Diagram Settings on the shortcut menu.
You can temporarily reverse the setting of the Snap to normal grid option by holding down the Alt
key while working. The permanent setting will be restored when you release the Alt key.
Note! The Alt key will also temporarily affect the Snap to guide setting. The effect will vary
according to the permanent setting of the two options.
The radial grid allows you to draw straight lines at a given angle, as specified in the radial grid
settings.
To permanently turn the radial grid on (or off):
1. Right-click the diagram (outside symbols or objects), and select Diagram Settings on the
shortcut menu.
2. Click Grid Settings.
3. Select Snap to radial grid to turn the radial grid on (or deselect it to turn the radial grid off).
You can temporarily reverse the snap to radial grid by holding down the Shift key while working.
When you release the Shift key, the permanent setting will be restored.
There are several ways to permanently turn snapping to guides on or off. On toolbars and menus, the
state of the Snap to Guides button shows whether snapping is turned of or not. When the button is
- 175 -
pressed, snapping is turned on.
To turn on (or off) snapping to guides:
! Click Snap to Guides on the Layout toolbar or menu.
! Right-click the diagram (outside objects or symbols) and select Snap to Guides on the shortcut
menu.
! Select (or deselect) the Snap to guides option on the Guide Settings property page to turn snapping
on (or off). The property page is available by right-clicking the diagram and selecting Diagram
Settings on the shortcut menu.
You can temporarily reverse the setting of the Snap to Guides option by holding down the Alt key
while working. The permanent setting will be restored when you release the Alt key.
Note! The Alt key will also temporarily affect the Snap to Grid setting. The effect will vary
according to the permanent setting of the two options.
Tip! You can temporarily reverse the Snap to normal grid setting by holding down Alt while
working. Likewise, holding down Shift will reverse the Snap to radial grid setting.
- 176 -
! Hit F2 to enter a new position for the selected guide.
4. Select (or deselect) the Snap to guides option to turn snapping to guides on (or off).
5. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.
You can temporarily reverse the Snap to guides setting by holding down Alt while working. The
effect is, however, dependent on the setting of the Snap to normal grid option. The table below
summarizes the behavior of holding down the Alt key for the various combination of the two
options.
Setting With Alt key
Snap to Grid Snap to Guides Snap to Grid Snap to Guides
On Off Off Off
On On Off Off
Off On On Off
Off Off On On
Insert Guides
You may insert horizontal and vertical guides in the diagram window by drag and drop:
1. If rulers are not displayed, then display them by selecting Rulers on the View menu, or by
right-clicking in the diagram and selecting Rulers on the shortcut menu.
2. To insert a horizontal guide, click inside the horizontal ruler and drag a new guide onto the
diagram area.
3. To insert a vertical guide, click inside the vertical ruler and drag a new guide onto the diagram
area.
Inserting a vertical guide is achieved by clicking inside the vertical ruler and dragging a new guide to
the desired position in the diagram.
You may insert guides on the Guide Settings property page as well:
1. Right-click the diagram (outside symbols or objects), and select Diagram Settings on the
shortcut menu.
2. Click Guide Settings.
3. Insert guides by clicking New in the appropriate list box (Vertical for vertical guides and
Horizontal for horizontal guides).
4. Enter the position of the guide. Valid units are Point (pt), Centimeter (cm), and Inches (in).
5. If you wish to lock the guide in position, click Lock. When a guide is locked, you cannot move
it by drag and drop in the diagram.
6. Repeat steps 3 to 5 to create as many guides as you need.
7. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.
Move Guides
If the guide is not locked on the property page, you can move it by drag and drop:
- 177 -
1. Point to the guide. The mouse cursor changes to , depending on the orientation of the guide.
2. Click the guide, and drag it to its new position.
You can also move the guide on the Grid Settings property page:
1. Right-click the diagram (outside symbols or objects), and select Diagram Settings on the
shortcut menu.
2. Click Guide Settings.
3. Select the guide you wish to move.
4. Hit F2 and enter the new position of the guide.
5. Repeat steps 3 and 4 for all guides you wish to reposition.
6. Click OK to save the changes, or click Apply to save changes without closing the dialog box.
Delete Guides
! If the guide is vertical, drag it beyond the left edge of the diagram and drop it.
You can also delete guides on the Guide Setting property page:
1. Right-click the diagram (outside any symbols or objects), and select Diagram Settings on the
shortcut menu.
2. Click the Guide Settings tab.
3. To remove a vertical guide, select it in the Vertical list, and click Delete. Click Delete All
to delete all the guides in the list.
4. To remove a horizontal guide, select it in the Horizontal list, and click Delete. Click Delete
All to delete all the guides in the list.
Tip! You can turn off the display of guides and turn guide snapping off if you wish to disable
guides without deleting them from the project.
- 178 -
Work with Object Properties
The properties of an object are accessible on the object's Property Pages. To access these:
1. Select the diagram object(s) whose properties you want to edit.
2. Click Properties in the toolbar, or right-click the object and select Properties on the
shortcut menu.
or
1. Double-click the object you wish to modify.
or
1. Select the object you wish to edit, and hit Alt-Enter on your keyboard.
Although all attributes of an object are shown, not all can necessarily be edited. Sometimes you have
to select an object (or an object's sub-object, like a name box) explicitly to gain access to the
characteristic you want to change.
Tip! Many of an objects' properties can also be set on the shortcut menu or by using toolbar
buttons. Right-click the object - or part of the object - to see what is available on the shortcut
menu.
You can apply the same format to many objects in one operation, for example change the color or
border width.
1. Select all diagram objects whose attributes you want to edit.
2. Use the formatting options available on shortcut menus and toolbars to format the objects.
or
1. Select all diagram objects whose attributes you want to edit.
2. Select Properties on the toolbar.
You will see all accessible property pages in the dialog box.
Note! When you define properties for many objects simultaneously, only the property pages
that all the objects have in common will be accessible.
- 179 -
Format Text
You can format the text of several objects or sub-objects in Studio. Most of the text formatting
options are available on the Format toolbar. Alternatively, you can use the Font property page in the
Properties dialog box.
You must first select the object(s) you wish to format.
! To change font, select the font you want in the Font box.
! To change font size, use the Font Size drop-down box.
! To make the text bold, click Bold.
! To make italics, click Italic.
! To underline text, click Underline.
! To select the color previously selected, click Font Color.
! To select a color, click the arrow in Font Color, and select a new color.
! To left align the text, click Align Left.
! To center text, click Center.
! To right align text, click Align Right.
! To justify text, click Justify.
Tip! You can remove underline, bold, or italic formatting by clicking the button once again.
You can format the diagram background of each diagram in your workbook individually. You can
select between No Fill, Solid Color, or Pattern.
To format the diagram background:
! Click Diagram Settings on the toolbar or on the Diagram menu.
! Click the Fill tab.
! Select the fill type and colors on the Fill property page.
! Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Note! The background color of the diagram is ignored when you print your diagram.
You are allowed to use picture fills for all objects that has the Fill Property Page; variable symbols,
presentation controls, frames, etc.
To use a picture fill:
1. Right-click the object you wish to format, and select Properties on the shortcut menu.
- 180 -
2. Click the Fill tab.
3. Select Picture under Type.
4. Click Select Picture…
5. You select the picture to use in the Select Picture dialog box. There are several ways of selecting a
picture:
! Select a previously used picture in the Resource list.
6. If you insert the picture from a file or from the Clipboard, you can rename it in the Resource list.
7. Click OK to return to the Fill Property Page.
8. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.
Studio currently supports three picture formats: Windows Bitmap (*.bmp), Windows Metafile
(*.wmf), and Enhanced Metafile (*.emf).
Aligning objects, in most cases, means placing them relative to one object with which you want to
align the rest. This object is called the dominant object, and will have filled (not hollow) selection
handles. To make a selection with a dominant symbol.
1. Select all the objects to be aligned, including the object you want to be dominant.
2. If the desired object is not dominant (e.g. another symbol has filled handles), click the object
while pressing the Ctrl key.
You can rotate objects in your diagram. You can use one of four preset rotations, or you can
customize the rotation freely on the Symbol property page.
- 181 -
Note! It is currently only frames that support rotation in Constructor diagrams.
Tip! The commands are available on both the Layout menu and toolbar.
You can resize a selection of objects to the same size as an object of your choice. This object is called
the dominant object, and will have filled (not hollow) selection handles. To make a selection with a
dominant symbol.
1. Select all the objects to resize, including the object you want to be dominant.
2. If the desired object is not dominant (e.g. another symbol has filled handles), click the object
while pressing the Ctrl key.
- 182 -
! Click Make Same Width to make the objects the same width as the dominant object.
! Click Make Same Height to make the objects the same height as the dominant object.
! Click Make Same Size to make the objects the same size as the dominant object.
Position Objects
Note! Coordinates [0,0] designate the upper left corner of the diagram.
See also the various specialized commands for aligning, spacing and moving objects.
Resize an Object
1. Select one or more objects and click Properties.
2. On the Symbol tab, specify a new width and height under Width and Height respectively.
Or:
1. Select the object you want to resize. Move the pointer over one of the handles that appear on the
edges of the object.
2. Drag the handle to achieve the desired size.
Tip! Reverse the default Snap to Grid setting by holding down the Alt key while resizing.
Press Ctrl to change the point from where the object is resized - from the center or from the
corner.
Tip! To determine the size in centimeters or inches, replace 'pt' (points) with 'cm' or 'in'.
To change the size of several objects without disturbing the relative size difference:
1. Select the objects to be resized.
2. Use the handles of the dominant object to resize the selection.
- 183 -
Resizing a multiple selection
The objects will now be resized relative to the dominant one. Thus, if the width of the dominant
object is increased by 60%, so will the width of the other objects. Note that all objects have minimum
and maximum sizes.
You can use the Format toolbar to change the line style and color of the objects you have selected.
! Click the arrow in Line Color and select the line color you wish. It will be applied to the
selected object(s).
! Click Line Color to apply the same line color as was used the last time (the color is indicated
on the button).
! Click the arrow in Line Style and select the line style you wish. It will be applied to the
selected object(s).
! Click Line Style to apply the same line style as was used the last time.
! Click the arrow in Dash Style and select the dash style you wish. It will be applied to the
selected object(s).
! Click Dash Style to apply the same line style as was used the last time.
Alternatively, you can use the Properties dialog box:
1. Select the object and click Properties.
2. On the property pages, click the Line tab.
3. Set line style, dash style, color and width to be applied to the selected object(s) and click Apply or
OK.
Tip! To give several objects the same line or border color, select them all before going to the
property pages.
- 184 -
object(s).
! Click Shape Type to apply the same shape as was used the last time.
You can also use the Properties dialog box to change the fill color.
1. Select the object and click Properties.
2. On the Property pages, click the Fill tab.
3. Select a color and click OK.
Tip! To format several objects at the same time, select them all before assigning the formatting.
- 185 -
Work with Freeforms, Frames, Hyperlinks and
Bookmarks
Freeforms and frames allow you to include notes, arrows, and illustrations based upon these in your
diagrams. You can format the objects to suit your needs. Frames can be filled with a solid color,
patterns, images, or be transparent.
About Bookmarks
Bookmarks are used to defined target locations for hyperlinks. When you insert a bookmark in your
diagram, you can choose whether it should have extent or not (see illustration below).
- 186 -
centered on the page when visited. If the bookmark has extent, you can also allow Studio to
automatically zoom the area within the bookmark when it is visited.
When used in combination with hyperlinks, bookmarks offer an excellent way of navigating in
simulation projects.
About Hyperlinks
Hyperlinks constitute a way of jumping between various locations in your simulation project.
Although hyperlinks can be used in all view modes - Design, User, and Presentation - they are more
effective for the latter two. When combined with bookmarks and frames with picture fills, you can
create image maps as simulator interfaces. It is only your own imagination that limits the potential of
such simulator interfaces.
You should be aware that when Studio is in Design Mode, you will not be able to use the hyperlink by
clicking it, as this will only select the hyperlink (and/or the text inside it). To open the hyperlink in
Design Mode, you must right-click the hyperlink object and select Open on the shortcut menu. To
gain full advantage of the hyperlink, you should switch to User or Presentation Mode.
Available Targets
Although bookmarks will in many cases be the target location for a hyperlink, it accepts a lot of other
locations as well. Using hyperlinks, you can jump to:
! Runs and diagrams in Studio.
! Any bookmark in any diagram.
! An e-mail address. When the hyperlink is clicked, a new e-mail message is created using the
computer's default mail setup.
! A file. When the hyperlink is clicked, the file will be launched using the default program. As an
example, if you select an html-file, it will be opened in the default web browser.
! A web page on the Internet. Simply enter the web address to be used, such as
'www.powersim.com'.
- 187 -
hyperlink from a shared diagram to a private diagram, you must use absolute links. Absolute
hyperlink targets make reference to a unique identifier within the simulation project itself. Hence, by
using absolute hyperlink targets, you can jump from any diagram within any component and
simulation, to any other diagram within the simulation project.
Creating absolute hyperlinks from a shared diagram to a private diagram within a simulation is not
recommended. If you later add more simulations, the link would appear in all simulations, but the
would inevitably lead to one particular private diagram in one of these simulations.
If you are creating a "global homepage" for a simulator that allows your simulation users to select a
given simulation or component, you must use absolute hyperlinks. In this case, we recommend that
you create a separate component for this homepage, to avoid cross-linking between various
simulations within the same component.
Add a Frame
Tip! When you have created a frame, you can change its shape by clicking Shape Type on
the Format toolbar, and select the new shape from the drop-down list.
Tip! When you have created a frame, you can change its shape by clicking Shape Type on
the Format toolbar, and select the new shape from the drop-down list.
Tip! You can also paste text directly from the Clipboard and onto your diagram. The pasted
text will be inserted in a new frame in the diagram using the default frame properties.
- 188 -
Add a Picture to a Frame
A frame in Studio can contain a picture fill. The easiest way of adding a picture to a frame, is to
simply paste it into Studio. Studio will then automatically create a new frame, and add the picture as
the fill of the frame.
Alternatively, you can manually create a frame and add the picture fill by following the steps below.
1. Right-click the frame you want to add a picture to, and select Properties on the shortcut menu.
2. Select the Fill tab.
3. Select Picture under Type.
4. Click Select Picture….
5. There are three ways of selecting a picture in the Select Resource dialog box:
! If the picture has been used previously in the project, you can select it in the Resource list in the
dialog box.
! Click Browse to open an image file from a file location.
6. If you insert the picture from a file or from the Clipboard, you can rename it in the Resource list.
7. Click OK to return to the Fill Property Page.
8. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Studio currently supports three picture formats: Windows Bitmap (*.bmp), Windows Metafile
(*.wmf), and Enhanced Metafile (*.emf).
Add a Bookmark
Bookmarks can be used as hyperlink targets when you create user interfaces for your simulation
model.
Tip! By giving the bookmark an intuitive name, you make it easier to identify it when you are
creating hyperlinks to it.
Note! If the bookmark has extent after you have created it, you can turn it off in the Properties
dialog box.
- 189 -
bookmark.
The bookmark snaps to the grid if it is turned on. To temporarily reverse the grid setting, press Alt
while dragging.
If the bookmark has extent, it will be drawn using a dotted line to show its area. This line will
disappear when the diagram is switched to User or Presentation Mode.
Add a Hyperlink
Hyperlinks are used to create user interfaces for your simulations. You can use hyperlinks in
combination with bookmarks and frames to create user interfaces that are intuitive and straight-
forward to use.
1. Click Hyperlink.
2. Drag the hyperlink object to the desired size and position in your diagram.
3. Type the text that should appear on the hyperlink (you can start typing immediately).
4. Right-click the hyperlink, and select Edit Hyperlink on the shortcut menu.
5. Select the link you wish to make under Link to. Options are Target this project, Web page, File,
and E-mail address.
6. Select the target of the hyperlink under Address. If you wish to make an absolute link to a target
in the current simulation project, deselect the Relative option, and select the target in the treeview
below.
7. Click OK to save your selections.
When you have inserted the hyperlink, it appears transparent and with no line. You can format it
visually in the same way as you can format a frame, except that you cannot change the shape of it.
You can select it by clicking the text or dragging out an area around it.
Note! Be careful when you are using absolute hyperlinks, so that you avoid cross-simulation
links. When creating user interfaces for simulations, it is recommended that you use only
relative links, since relative links will always provide jumps within the same simulation only.
The exception is when you are creating global homepages where the user is intended to select
between several available simulations (in which case it is a good idea to create these
homepages in separate components).
- 190 -
Create Hyperlinks without Text
Note! Be careful when you are using absolute hyperlinks, so that you avoid cross-simulation
links. When creating user interfaces for simulations, it is recommended that you use only
relative links, since relative links will always provide jumps within the same simulation only.
The exception is when you are creating global homepages where the user is intended to select
between several available simulations (in which case it is a good idea to create these
homepages in separate components).
Open a Hyperlink
How to open (sometimes called visit or jump to) a hyperlink depends on the mode you are working in.
To open a hyperlink in Design Mode:
1. Right-click the link that you wish to open.
2. Select Open on the shortcut menu if you want to open the hyperlink in the current window, or
select Open in New Window if you want to open the hyperlink in the current window.
To open a hyperlink in User or Presentation Mode:
1. Simply click the hyperlink that you wish to open.
A frame in Studio can contain a picture. However, if the frame is larger or smaller than the picture
shown inside it, the picture will be stretched to fit the frame. You can resize the frame to fit the
picture:
1. Right-click the frame you want to resize, and select Fit to Picture.
- 191 -
Tip! You can paste a picture directly from the Windows Clipboard and onto your diagram. A
new frame with the picture as picture fill will be automatically created.
When creating model diagrams, you will often have the need to use a frame as a background for other
symbols and controls. However, when a frame is positioned in the background of other objects, it is
difficult to perform a multiple selection inside the frame. To solve this, you can specify that the
selected frame is used as a background:
1. Right-click the frame you wish to use as a background, and select Use as Background on the
shortcut menu.
Note! When a frame is used as background, you can only select it by clicking its border.
When the Use as Background option is selected for a frame, it behaves in the same way as if its
interior fill is specified as No Fill.
If a frame is transparent (the No Fill option is selected on the Fill Property Page), the frame can only
be selected by clicking its frame. You must click the frame itself (or within a distance of a few pixels
to either side) in order to change the properties of the frame. This allows a frame to act as a
background for other objects (such as variables and controls) in your diagram.
When selecting a transparent frame, you must click the border directly (or within a few pixels
distance to each side).
Note! If you select the Use as Background option on the shortcut menu of a frame, you can
force a filled frame to behave in the same way as a transparent frame.
- 192 -
Tip! You can add arrowheads or -tails to the freeform. Double-click the freeform, and specify
the arrows you like on the Arrowheads property page in the Properties dialog box.
Reshape a Freeform
Reshaping a freeform line is identical to reshaping a link. When you select the line, the nodes appear.
Use the nodes and their adjustment handles to reshape the freeform line.
The various segments that make up a freeform line are divided by nodes. Each node can be formatted.
Tip! You can change the line style, dash style, and line color of the freeform line.
Many pages on the internet uses image maps to create visually stunning user interfaces. Now you can
also create image maps inside your simulation project, should you wish to. The procedure below
explains how to create an image map using frames with picture fill, hyperlinks with no text and target
bookmarks. The procedure assumes that you have an image located on your disk that you want to use
as an image map background.
1. Insert one bookmark for each of the target locations you want your image map to point to. Name
them in an intuitive manner to make it easy to identify the targets when creating hyperlinks.
2. Select the diagram in which you want to create an image map. If necessary, inset a new diagram
by right-clicking the diagram tabs at the bottom of the diagram book, and select Insert
Constructor Diagram.
3. Insert a frame in your diagram by clicking Frame and dragging the frame to about the correct
size.
4. Right-click the new frame, and select the Properties on the shortcut menu.
5. Click the Fill tab, and select Picture under Type. Click Select Picture to select a picture to use as
picture fill. The Select Resource dialog box allows you to either browse for the image or to paste
it from the Windows Clipboard. When you're finished, click OK to save the changes.
6. If the size of the frame is not properly adjusted to fit the picture, right-click the frame, and select
Fit to Picture on the shortcut menu. This will resize the frame to fit the exact size of the
picture.
7. Right-click the frame again, and select Use as Background on the shortcut menu. When this
option is selected, the frame can only be selected by clicking the frame border. This makes it
easier to place other objects on top of it and prevents you from accidentally selecting the frame.
8. Click Hyperlink and create a new hyperlink inside the picture frame. Adjust the position and
size of the hyperlink until it covers the area for which you wish to create a hyperlink jump.
9. Select the text of the hyperlink and delete it.
10. Define the destination of the hyperlink by right-clicking it and selecting Properties on the
shortcut menu, and selecting the appropriate destination in the Location box.
- 193 -
11. Repeat steps 8 to 10 until you have defined all the necessary hyperlink spots on the image map.
12. Switch to User or Presentation Mode to test the image map.
Tip! You can also test the image map by right-clicking the hyperlinks and selecting Open on
the shortcut menu.
When you draw a freeform line, it is always drawn with a default arrowhead. To change the
arrowhead or -tail:
1. Double-click the freeform you wish to alter, or right-click it and select Properties on the
shortcut menu.
2. Select the Arrowheads tab.
3. Specify the styles and size of the arrow on the property page.
4. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Tip! You can also change the line style, dash style, and line color of the freeform line.
You can change the order of the objects on the diagram by using the Layout toolbar. An object can be
sent to the back of the stack, to the front, or be moved step-wise through the stack in both directions.
! Click Bring Forward on the Layout toolbar.
! Click Send Backward on the Layout toolbar.
! Click Bring to Front on the Layout toolbar.
! Click Send to Back on the Layout toolbar.
Delete a Hyperlink
To delete a hyperlink:
1. Right-click the hyperlink you wish to delete, and select Delete on the shortcut menu.
Tip! If the hyperlink is transparent and doesn't have a borderline, it might be difficult to select
it. If the hyperlink is not previously selected, right-clicking the text should select the hyperlink
and bring up the correct shortcut menu. If the hyperlink is already selected, it is better to right-
click the surrounding border instead.
- 194 -
Delete a Bookmark
To delete a bookmark:
1. Right-click the bookmark and select Delete on the shortcut menu.
or
1. Select the bookmark you wish to delete.
2. Hit Del on your keyboard to delete the bookmark.
Note! You should carefully check your project for broken hyperlinks when deleting bookmarks.
- 195 -
Work with Zooming
Studio allows you to zoom a diagram in and out as you like. All the various zoom options are
available on the View menu and in the Zoom dialog box on the View menu. You can zoom by using a
selection, specifying a zoom percentage, or fit the full diagram in the current view.
Note! When zooming a diagram, all objects will become larger. To individually resize objects,
resize the object in question instead of zooming the diagram.
Zoom a Diagram
For a closer or more remote view of the diagram, zoom in on or out of it.
1. On the Layout toolbar, click Zoom
2. Select zoom ratio from the drop-down list, or type in any zoom ratio between 7% and 400%.
Note! If you magnified the diagram, you may have to use the scroll bars in order to find the
part that you wanted to have a closer look at.
Zoom a Selection
- 196 -
Zoom to Fit Diagram in View
You can fit the entire diagram into the current view:
1. Click Zoom to Fit.
The entire diagram will be fitted within the current view, provided it is room for it there with at least a
magnification of 7%.
- 197 -
Work with Simulations
You define the simulation settings in two places. Project Settings apply to all the components in a
project, while Simulation Settings apply to one component only.
Project Settings
Under Project Settings you control which calendars should be available in the project, and the time
unit that will be used by default (also referred to as the preferred time unit). The available calendars
will influence on what time units are available in the project (as the definition for month, quarter, and
year differ between the three calendars). Only the Bank calendar is available by default.
The preferred time unit will always be used when presenting time intervals (points in time such as
dates) in Studio. A good example of this is the time step, which you find in the Simulation Settings
dialog box. The time step is always formatted using the preferred time unit, and if you enter only a
number (without a unit), it will be interpreted using that time unit. Thus, if you enter '5' and the
preferred time unit is 'day', then it will be interpreted as '5 days'. Thus, you should specify a time unit
that matches the time horizon of your simulation (and the time step), or you might get time values that
are pretty difficult to read.
You can also define whether the simulation time should have unit or not. While it is possible to turn
off units for time (and thus become compatible with models created in Constructor 2.51), we strongly
recommend that you keep the Time has units enabled. This will also ensure that the unit consistency is
kept and validated while you work.
Simulation Settings
Each component can contain several simulations, that also allows you to build your model. You can
define the simulation settings for each simulation in the Simulation Settings dialog box. A number of
default settings apply as long as you have not defined any other values. Sensible simulation time
settings are essential to gaining as much insight from the simulation as possible, both regarding the
accuracy of the results themselves and their readability.
You have full control over the time horizon of the simulation, and you can define the start time and
stop time, as well as the timestep of the simulation. Start and stop times are defined relative to a
calendar. The time step is defined using the preferred time unit of the project.
Note! To enter hours, minutes, and seconds, use the format HH:MM:SS.SS. Otherwise, use the
available time units in the project (such as '1da', '1mo', 1'yr', etc.).
In order to study the progress of the simulation even for small models that run very fast, you can set
- 198 -
the speed of the simulation in relation to the selected timestep. You can also pause the simulation by
using the toolbar buttons.
There are several calendars available: Bank, Fiscal, and Gregorian. The main difference between them
is the number of days per year, and how the year is divided into weeks and months. Thus, calendar
selection will affect the number of timesteps for the simulation, since the start and stop times are
defined related to the selected calendar.
In addition to the simulation settings, the settings for the integration methods will also influence the
speed and precision of the simulation. The various integration methods available have different
characteristics and accuracy.
Powersim Studio allows you to save the simulation state and history of the model with the simulation
project. You are also allowed to save simulation runs and even export them to share them with others.
You should therefore be aware that simulation state and history represents two different aspects of the
simulation run.
! Simulation State represents the current situation of the simulation, and includes all values for all
variables in the component. Thus, the simulation state represents a "snapshot" of the simulation at
that specific time step.
! Simulation History on the other hand, represents the history of the simulation, including all
values for all variables over the entire simulation run.
When you add a cue point to your simulation run, you actually save the simulation state of the
component in that time step. Later in the simulation run, you can recall the state at that time,
"rewinding" the simulation to an earlier time step. The value of all variables are restored to reflect the
situation at that time step, and you can continue your simulation using new strategies, should you
wish to.
The simulation history is kept for all variables by default. Keeping the history for all variables
requires Studio to store one value per time step per variable. If your simulation component contains a
high number of variables, this might result in a large dataset to store. In some situations it might
therefore be advisable to turn off the History for all Variables option in Simulation Settings, to save
RAM on your computer. If this option is turned off, the history will only be saved for variables that
are parameters to controls or that have auto reports. The consequence is that if you add an auto report
to a variable (or add the variable to a control) during the simulation, you will only see the simulation
history from that point on in the simulation. The next time you run the simulation, though, it will
behave identically to all other variables with auto reports or in controls.
When you save a simulation run, you save all the data in Studio. Thus, the selected history option will
be used when saving a simulation run. Likewise, if you have selected to save the simulation state with
the project (select the Save State option in Simulation Settings), both the final state and the history is
saved.
The Calendars
- 199 -
! The Bank Calendar
These calendars are different in regards to the number of days and weeks in each year. The following
table shows the various calendars.
Calendar # of days # of weeks
Gregorian 365, each 4th year (leap year) has 366 52 and 1 (or 2) days
Fiscal 364 days 52 weeks (exactly)
Bank 360 51 weeks and 3 days
The Gregorian Calendar is the common calendar over most parts of the world. The Fiscal Calendar is
often used in the financial world, where each company makes up their status at the end of the fiscal
year. The Bank Calendar is also used in the financial world.
By default, only the Bank calendar is available for your simulation project. You can control the
available calendars in Project Settings, and you can select which calendar to use for your simulation
in Simulation Settings..
Note! The selection of available calendars will also affect the definition of some time units that
are dependent on the selected calendar, such as month, quarter and year.
By default, simulation time is measured in seconds, or in a time unit derived from seconds. It is
strongly recommended that you simulate your models in this mode, since this will ensure valid units
for all of your variables.
However, you can choose to use a simulation time that is not measured in seconds. This is done in the
Project Settings dialog box (right-click Project in the Project Window, and select Project Settings on
the shortcut menu). At the same time, you must also select an interval for interpreting the new unitless
time scale. The possible time increment intervals are dependent on the available calendars. If you
select all calendars, the highest available increment is '1 week', while the highest increment if you
select only the Bank or Fiscal calendars is '1 year'.
Tip! Setting the timestep equal to the time interpretation interval will yield flows per timestep
- 200 -
that are equal to the size of the flow rate controlling them.
Unit consistency
Turning off the time unit for simulation time does not turn off the unit consistency checks performed
by Studio. However, entering units in this mode can sometimes return strange units when time is
involved in the equation. This is due to the fact that the simulation time unit is defined as unity, and
can therefore be omitted from the unit calculation. To preserve correct units throughout your model,
you should therefore avoid running in this mode if possible.
In this variable definition, the assumed time interpretation interval is most probably '1 year'. If this is
the case, the value of the variable will step up from 1000 to 2000 at 1/1/2001. However, this variable
expression will be differently interpreted if the time interpretation interval is set to '1 week'. In this
case, the step will occur at 2001 weeks after 1/1/1, and most probably occur beyond the time horizon
of the model.
Although the variable expression above is valid when simulation time has no unit, using the DATE
function is recommended when creating expressions like the one above.
Since the output from the DATE function is always compatible with simulation time, the expression
will always yield an unambiguous result. No matter what time interpretation interval, unit selection, or
calendar you have selected, the expression will be valid. As a result, the increase will always occur on
1/1/2001.
When the simulation engine calculates values for variable definitions, it will at the same time evaluate
the unit for the expression. However, it is often convenient to control the time unit that is yielded from
such calculations. You can do this by selecting a preferred time unit in the Project Settings dialog box.
This preferred time unit will be used as the default time unit for the entire project.
Note! This setting applies only when the Time has units option is selected.
- 201 -
column shows the resulting unit for the variable A defined as:
aux A = 1<<m>>/TIMESTEP
unit m = __METER // Defined in Global Units
All calendars
Time Unit Comment UnitA
second m/s
minute m/min
hour m/hr
day Default setting for new projects m/da
week m/wk
Bank Calendar only
30 days One bank month m/mo
90 days One bank quarter m/qtr
360 days One bank year m/yr
Fiscal Calendar only
91 days One fiscal quarter m/qtr
364 days One fiscal year m/yr
When setting up a simulation in Studio, you should always specify a time horizon that refers to the
time perspective of the real-world system. The start and stop times of the simulation decide when the
simulation should start or stop, while the timestep of the simulation defines the size of the length
between saved results.
If you, for example, are showing a process over a year, you should enter the start and stop times
corresponding to the calendar year you want to simulate. This could be from 1/1/2000 until 1/1/2001.
The size of the timestep will then decide the number of simulation steps the model will perform.
Selecting a timestep of 1 day will lead to 365 simulation steps, while selecting 1 week will lead to 52
simulation steps. In both cases, however, the simulation time horizon is one entire year. (The example
assumes that the Gregorian calendar is selected.)
You should carefully select the length of the timestep to allow for an interesting development.
However, the shorter the timestep, the higher the number of calculations per simulation, which can
cause more numerical round-off errors and reduce the simulation speed. On the other hand, a long
timestep will produce simulation results with a lower accuracy.
To set the start and stop times and the timestep for the simulation of a model:
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. Select the calendar to use in the Calendar box (the default is the Gregorian Calendar).
3. Enter the start time (a date) of the simulation in the Start Time box.
4. Enter the stop time (a date) in the Stop Time box.
5. Enter the timestep in the Timestep box. This number is entered using a special time format (for
- 202 -
details, click here).
6. Click OK to save the changes, or click Apply to apply the changes without closing the dialog
box.
There are currently three calendars available in Powersim Studio. You must specify in the settings for
the simulation project which calendars are available within the simulation project. This will affect
which time units are available in your simulation project.
The different calendars have different number of days per calendar year, and are used in different
scenarios. The Fiscal Calendar, for example, is often used in the financial world.
To change the calendar for the simulation of a model:
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. Select the calendar among the available calendars you wish to use in the Calendar box.
3. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.
To specify the available calendars for a simulation project:
1. Select Project Settings… on the Project menu.
2. Select the calendars you wish to be available in the project under Available Calendars in the
Project Settings dialog box.
3. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.
The available calendars will decide which time units are available in the simulation project, since all
time units are not compatible with all calendars.
The available time units in Studio are dependent on the available calendars in the project. This is due
to the difference in number of days and weeks every year. As an example, when the Gregorian
calendar is available, the highest possible time unit available is 'week'. In contrast, when only the
Bank calendar is available, all the time units, including 'year', 'quarter', and 'month' can be uniquely
defined.
You can therefore select which calendars that should be available in your simulation project.
1. Select Project Settings… on the Project menu, or right-click Project in the Project Window, and
select Project Settings… on the shortcut menu.
2. Select the calendar(s) that you want to be available in the project (you must select at least one
calendar).
3. Click OK to save the changes, or click Apply to apply the changes without closing the dialog
box.
Note! Changing available calendars can sometimes change the definition of some time units, or
even make them undefined.
- 203 -
Set Start Time and Stop Time
To set the start and stop times for the simulation of a model:
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. Select or enter a value for Start Time to indicate the beginning of the time horizon. This is entered
as a date referring to the selected calendar.
3. Select or enter a value for Stop Time to indicate the end of the time horizon. This is entered as a
date referring to the selected calendar.
4. Click OK to save the changes, or click Apply to apply the changes without closing the dialog
box.
You can enter the times as numbers as well as dates. If you do this, the time is interpreted using the
preferred time unit specified in Project Settings. The default setting for the preferred time unit is Day
('da'). If you enter 0 for Start Time, the start time is set at 01/01/01 BC, and if you enter 100 for Stop
Time, the stop time is set to 11/04/01 BC (100 days after 01/01/01 BC).
Note! The time step is always displayed using the preferred time unit specified in Project
Settings. Thus, if the time unit is 'day', then a time step of 1 week will be shown as 7 days.
It can be difficult to visually follow the development of the process at maximum simulation speed. To
remedy this problem:
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. Under Simulation Speed, select Maximum, Real Time or Custom to run at the maximum possible
speed, real time speed, or a custom speed respectively.
3. Click OK to save the changes, or click Apply to apply the changes without closing the dialog
box.
The custom time is entered as a number of milliseconds per timestep.
- 204 -
Autoscale Variables when the Simulation is Paused
Variables in Powersim Studio will be autoscaled every time the simulation reaches the specified stop
time. This scaling is performed by finding the minimum and maximum values of the variable over the
entire simulation run. This scaling information is used by all auto reports and controls to scale the
value axis properly. You can also have Studio perform this automatic scaling every time you pause
the simulation.
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. On the Simulation tab, select the Autoscale When Paused option.
3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Note! For arrays, the minimum value will be the minimum value for all the array elements,
while the maximum value will be the maximum value for all the array elements, regardless of
whether the maximum (or minimum) element is shown in an output control or not.
Studio can keep the history for all variables in your simulation project, if you prefer to.
Note! If your simulation project contains many variables, you might want to turn off this option
in order to free computer memory. If the option is disabled, history will only be kept for
variables that are parameters to controls or variables that have auto reports turned on.
You can have Studio save the simulation state of the current simulation run when you save the
project. If you save the simulation state, the project will be opened at the same time step that you
saved the project on, and the values of all variables at that time step will be preserved. The simulation
run history will also be restored, depending on the History for all Variables setting for the simulation.
If the option is enabled, history for all variables will be restored, otherwise, only the history for
variables with auto reports or variables that are parameters to controls will be restored.
To save the simulation state with the project:
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. On the Simulation tab, select the Save State option.
3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
- 205 -
Set the Run Count
The run count allows you to specify how many runs should be counted before the run index is reset
again. By using the RUNINDEX function, you can display the run index (number) or the active run.
When the RUNINDEX reaches the specified run count, it starts over again. The RUNINDEX is also
reset every time you click Reset Simulation to reset the simulation.
Note! To avoid resetting RUNINDEX, simply start the simulation again when it has reached the
end of the simulation, rather than resetting the simulation.
Note! In Constructor 2.51, the run count allowed you to run a number of simulation runs
continuously. In Studio you must manually start the simulation between each simulation run by
clicking Start.
The RUNINDEX function will return the current run number, while RUNCOUNT will return the
number of runs specified above.
Note! This is the default setting when creating a new simulation project.
- 206 -
you select '1 day', the value returned will denote the number of days from 1/1/1. Likewise, the time
interpretation interval will also decide the magnitude of flows, since a flow is defined as the flow rate
divided by the time step. As for the example above, a flow rate of 1 will, with '1 week' as the selected
interpretation interval, be of a magnitude of 1 per week. If '1 day' is selected, the flow rate will be of a
magnitude of 1 per day.
Tip! Setting the same value for both the interpretation value and the timestep will automatically
yield a flow of X per timestep from a flow rate of X.
Integration Methods
The simulation settings - start and stop times and timestep - affects the time horizon and resolution of
simulation results. The integration method affects the way the simulation results are calculated. The
integration method gets its default settings from the Simulation Settings for your component, but you
can further customize these to suit your needs.
The Euler integration method, which is the default integration method for a new component, will
perform one integration step per timestep. However, if your component requires it, you can specify a
higher order integration method. Powersim Studio supports four different methods of integration,
each having a different integration order:
! First order Euler integration
! Second order Runge-Kutta integration
! Third order Runge-Kutta integration
! Fourth order Fixed Step Runge-Kutta integration
Euler is the default method. It calculates the changes in the level variables once per timestep. This
means that in complex simulations, it needs a high number of integration steps to be accurate.
Increasing the number of integration steps (reducing the size of the timestep) can lead to two different
problems. First, it slows down the simulation process, and second, more calculations can cause more
round off errors. Worse, however, is that Euler can cause unwanted oscillations to occur in your
model.
When you encounter the problems described above, you should switch to a higher order integration
method. The second order Runge-Kutta method uses two flow calculations within the given
integration step. The reason why this yields a more accurate result - more accurate even than doubling
the number of integration steps when using Euler's method - is that the Runge-Kutta method uses a
weighted average of the two calculations: the flow during the second part of the integration step is
given more weight than the first. The higher order Runge-Kutta methods use even more sophisticated
calculation algorithms.
When you define the simulation settings for a model, you specify a time horizon and a timestep. The
integration method will perform one integration step per timestep. Thus, to increase the number of
integration steps performed during a simulation run, you must reduce the size of the timestep.
As a general rule you can decrease the number of integration steps at least as much as you increase
the order of integration. Hence, when going from Euler to the fourth-order Runge-Kutta, do not
hesitate to decrease the number of integration steps by at least a factor of four (by increasing the
timestep by a factor of four). This usually makes the simulation more accurate - the only problem is
that it tends to smooth out sudden changes. This happens because the higher order methods use the
value of the flow during the time step to calculate, while Euler's computes the next flow only once, at
the beginning of the time step.
- 207 -
About Integration
The change in a level's value is determined by integration of the flows going in and out of the level.
For example, in a model of a company's hiring policy, the level 'Workforce' has an inflow called
Change In Workforce. Change In Workforce equals Desired Workforce minus Workforce divided by
Time To Adjust Workforce (which is set to 2). The time unit is mo (month), so the gap between desired
and actual workforce is halved each month. For each time step, the area defined by the flow function
that is colored green in the illustration below, is added to Workforce.
Each time step the colored area is added to the value of 'Workforce'
The colored areas designate what is added to 'Workforce' each time step
The time step you set for the simulation run can greatly influence the integration. The graphs above
came about with a time step of 1 month. A smaller time step would mean that the calculation of the
flow would take place more often and thus increase the level of accuracy and detail, while a greater
time step would cause the opposite. For example, if Time To Adjust Workforce were equal to the time
step, the simulation results would be far less accurate:
Example of a simulation setup where the time step is too high to allow accurate integration
This presentation of how Powersim calculates the value of a level is based on the Euler integration
method. As mentioned, one way of enhancing simulation accuracy is to lower the time step. Another
way is to use one of the Runge-Kutta methods of integration.
- 208 -
Integration Methods: Known Quirks
The different integration methods behave differently, and not using the optimal method may in certain
contexts give rise to some strange simulation results.
1. Problems may arise when using higher order (Runge-Kutta) methods to calculate sudden changes
in a level, the reason being that these methods will try to smooth them out.
2. Euler's method usually needs very small time steps to be accurate. In complex models, this may
lead to quite slow simulation runs. The rule of thumb here is that you can increase the time step at
least as much as you increase the order of integration. Hence, going from Euler to Runge-Kutta 4,
do not hesitate to increase the time step by at least a factor of four.
3. As the time step gets smaller, the effects of round-off errors grow. If decreasing the time step is
accompanied by diverging oscillation or other unexpected effects, change the integration method
rather than decreasing the time step further.
Euler's method first calculates the initial values of the levels and flows. Then it uses the flows to
update the levels, the new values of the levels to recalculate the flows, and so on.
Euler's method assumes that a flow is constant over the interval of the time step.
If you find your simulation results wanting in accuracy and detail, you can usually amend this by
decreasing the simulation time step. The flows are calculated more often and smaller changes are
registered.
Note! When you lower the time step, the increased number of calculations increases the amount
of round-off error.
If your model is oscillating wildly, and you cannot relate this behavior to the structure of the model or
the size of the time step, you may need to deploy a more sophisticated integration method, that is, one
of the Runge-Kutta methods.
The Algorithm
In the equations below, Lt represents the value of the level L at time t, and F(Lt, t) represents the value
of the flow F into (or out of) level L at time t.
Powersim executes the following two steps to calculate the integral over an interval from T to T+dt:
1. Calculate the derived flow when t=T
Flow=F(LevelT, T)
- 209 -
Runge-Kutta Integration Methods
The Runge-Kutta methods for integration are used to achieve a higher degree of accuracy.
These higher order methods use several flow calculations within the given time step. The reason why
this yields a more accurate result - more accurate even than by decreasing the time step when using
Euler's method - is that the Runge-Kutta methods use a weighted average of the calculations.
For the discussion of the integration methods below, note that In the equations below, Lt represents
the value of level L at time t. Likewise, F(Lt, t) represents the value of flow F of level L at time t.
2. Calculate a third order estimate of LT+dt by using a weighted average of F1, F2, and F3
- 210 -
1. Estimate the flow at four points in the interval T to T+Dt
F1 = Dt*F(LT, T)
F2 = Dt*F(LT + 1/2 * F1, T + 1/2 * Dt)
F3 = Dt*F(LT + 1/2 * F2, T + 1/2 * Dt)
F4 = Dt*F(LT + F3, T + Dt)
2. Calculate a fourth order estimate of LT+Dt by using a weighted average of F1, F2, F3, and F4
The default integration method for a new component is the first-order Euler method. You can select
between four different integration methods, each with a different integration order.
1. Select Simulation Settings… on the Simulation menu, or right-click the component's Simulation
in the Project Window, and select Simulation Settings… on the shortcut menu.
2. Click the Integration tab.
3. Select the integration order in the Order box. The adherent integration method is also shown in
the list. Options are 1st order, Euler; 2nd order, Runge-Kutta; 3rd order, Runge-Kutta; and 4th
order, Runge-Kutta.
4. Click OK to save the changes, or click Apply to apply the changes without closing the dialog
box.
To start a simulation:
1. Click Play on the Simulation toolbar.
To stop a simulation:
1. Click Play once again.
The simulation stops immediately, and you can read the results at the step at which the simulation
stopped. The status bar indicates at what simulation time the simulation was stopped.
To study the development of your system step by step, it is a good idea to play the simulation
stepwise.
To play a simulation forward stepwise:
1. Click Advance Simulation One Step on the Simulation toolbar.
- 211 -
Reset a Simulation
Tip! You can start the simulation again without resetting it by simply clicking Play.
Cue points allow you to "rewind" the simulation to a given point in the simulation history, and play
the simulation over again from that point on. You can add as many cue points to a simulation as you
wish. Cue points are saved with the simulation run. The values of all variables in the component will
be saved when you add a cue point.
Note! When you "rewind" a simulation by going to a previously inserted cue point, the
simulation history is cleared from that point up. Thus, all variable history and other cue points
will be lost.
Tip! Cue points can be inserted both when the simulation is paused and when it is running.
Go to a Cue Point
Cue points allow you to "rewind" the simulation to a given point in the simulation run, and replay the
simulation from that point on. When you go to a cue point, all variables are reset to the value they had
at that point in the simulation. Cue points are saved with the simulation run.
Note! When you go to a previously inserted cue point, cue points between the activated cue
point and the simulation end will be lost. All variable history from the activated cue point and
to the end of the simulation is also lost! It might therefore be a good idea to save the simulation
run before "rewinding" to prevent loss of valuable information!
- 212 -
Manually Autoscale all Variables
All the variables in your component are automatically scaled when the simulation reaches the end.
The variable's scale is set to the interval between the minimum and maximum values of the variable
over the last simulation run. This interval is used to determine the value axis of auto reports and
controls in your diagrams.
Tip! If you select the Autoscale When Paused option in Simulation Settings…, all variables
are autoscaled when the simulation is paused.
You might sometimes need to manually autoscale your variables, for example in the middle of the
simulation if variable values far exceed the current scaling of displayed value axes. You achieve this
by:
1. Select Autoscale Now on the Simulation menu.
Permanent variables keep their values even when the simulation is reset. This is especially useful
when constants are parameters of input controls and are used to let the user interact with the
simulation. By using permanent variables, the user don't have to provide the same input before each
simulation run. Permanent variables may also be used for levels that accumulate values not only over
one simulation run, but over several simulation runs.
However, you might sometimes need to reset all variables to their original definitions. You do this by:
1. Click Restore Permanent Variables on the Simulation menu.
Note! Permanent variables are ordinary constants or levels with the Permanent option set on
the Definition property page.
- 213 -
Variables option is selected in Simulation Settings…).
! The state for all cue points inserted in the simulation run.
You can activate previous simulation runs in the model. When you do this, all information from the
current active run will be replaced by the information from the previous run.
The inventory of the current simulation run (Population) is compared to reference data from a
previous simulation run (*Population).
You can save the simulation run if you want to keep interesting simulation results. When you save a
simulation run, the following information is saved:
! Simulation State (at the time step when the simulation run was saved).
! Variable history (as specified in Simulation Settings…).
! Cue points.
- 214 -
Activate a Saved Run
You can activate a previously saved run into the component. Both runs stored in the project and in
separate files (*.sir) can be activated.
Note! When you activate a previously saved run, all the information from the current
simulation run will be lost!
To activate a run:
1. Select Activate Previous Run on the Simulation menu, and select the run you wish to activate
on the submenu. Select Load from File… to open a simulation run previously exported to file.
or
1. Open the Runs collection, available under the component in the Project Window.
2. Right-click the run you wish to activate, and select Activate Run on the shortcut menu.
When you activate a simulation run, the following information is restored from the run:
! The simulation state.
! Variable history.
! Cue points
Note! If your model has changed since you saved the simulation run, all the variables that have
the same dimension and data type will be restored. New variables or variables that have
changed will become NAN ('?').
Tip! The name of the simulation run will appear in the Reference Data list box in the toolbar
and on the Simulation menu.
You can export a simulation run to file (*.sir). This enables you to share your simulation run with
others with whom you share the same simulation model. It also lets you save simulation runs outside
the simulation project, which can be useful if you develop a model that other people will run (to avoid
keeping your own testing runs in the project).
- 215 -
To save the current simulation run to file:
1. Select Export… on the Simulation menu.
2. Enter a new name for the simulation run file, and select a location where you want to save it.
3. Click Save to save the simulation run. The file is saved as a *.sir-file.
You can also export any of the previously saved runs in the Runs collection:
1. Double-click the Runs view under the component in the Project Window.
2. Right-click the run you wish to export, and select Export Run… on the shortcut menu.
3. Enter a new name for the simulation run file, and select a location where you want to save it.
4. Click Save to save the simulation run. The file is saved as a *.sir-file.
You can import simulation runs that are previously exported to file.
Note! You can only import simulation runs into the same component that they were previously
saved.
To import a simulation run, but not include it in the Runs collection of the component:
1. Select Activate Previous Run on the Simulation menu, and select Load from File… on the
submenu.
2. Locate the file on your hard disk, and click Open to load the simulation run.
Note! Since the file is only loaded into the active run, the data will be lost when you reset the
simulation. To avoid this, import the run into the Runs collection, as described below.
You can also import a simulation run into the Run collection.
1. Double-click the Runs view under the component in the Project Window.
2. Right-click in the empty area of the view, and select Import Run… on the shortcut menu.
3. Locate the file on your hard disk, and click Open to load the simulation run.
4. If you want to activate the run, right-click it and select Activate Run.
Note! If your model has changed since you saved the simulation run, all the variables that have
the same dimension and data type will be restored. New variables or variables that have
changed will become NAN ('?').
In order for a simulation run to be visible as Reference Data in Presentation Mode, it has to be defined
as Public in the Runs collection.
1. Double-click the Runs view under the component in the Project Window.
2. Right-click the run you want to make public, and select Public on the shortcut menu.
- 216 -
Enter Documentation for a Saved Run
When you have saved a simulation run you can use it as reference data for future runs. To do so, the
simulation run must be selected as Reference Data. All controls that have reference data parameters
will, as soon as a reference run is selected, display these parameters along with the active run
parameters. Reference data parameters are prefixed with an '*' (asterisk).
To select reference data run:
1. Select Reference Data on the Simulation menu, and select the simulation run to use
from the drop-down list. (The list box is also available on the Simulation toolbar.)
or
1. Open the Runs collection, available under the component in the Project Window.
2. Right-click the run you wish to use as reference data, and select Use as Reference on the
shortcut menu.
Reference data makes it easy for you to compare your current simulation run to previously saved
simulation runs.
Tip! Only simulation runs that are marked as Public in the Runs collection will be visible when
the simulation project is viewed in Presentation Mode.
- 217 -
Note! If your model has changed since you saved the simulation run, reference data is only
available for variables that have not changed dimensions or data type since the reference data
was saved.
Studio allows you to specify a reporting window as well as major and minor intervals. These concepts
are explained below.
Report Window
The report window allows you to select a smaller portion of the total simulation to view. The report
window is defined by a length and slide. The length of the report window specifies the portion of the
simulation to view at a time, while the slide specifies the interval by which the report window will
scroll. If, say, the simulation runs for one year, the report length is one quarter, and the slide interval
is one week, the report will show data for the last quarter at a time, and when the end of the current
quarter is reached, the report window will slide one week further.
The animation illustrates how the report window can be used to present only a portion of the
simulation at a time. The report window has a length of one month, and when the first month is
completed, it slides by an interval of one day. The entire simulation lasts for two months.
- 218 -
minor gridlines in controls.
Report Window
1. Select Simulation Settings on the Simulation menu.
2. Click the Report tab.
3. Under Reporting Window, deselect Auto to enter the length of the reporting window.
4. Under Reporting Window, deselect Auto to enter the length of the slide interval.
5. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Note! If you select Auto for Length or Slide, Studio will automatically adjust the length to equal
the length of the simulation.
The report window allows you to select a smaller portion of the total simulation to view.The length of
the report window specifies the portion of the simulation to view at a time, while the slide specifies
the interval by which the report window will scroll.
The animation illustrates how the Time Graph Control uses the report window to present portions of
the simulation data.
- 219 -
Work with Units of Measurement
Units of measurements are an integral part of the variable definitions. For variables that do not get
their values from an expression, you are allowed to set the unit explicitly in the Definition property
page of the variable. Otherwise, the unit will be evaluated automatically.
Units are also taken into account when the simulation engine evaluates whether the model is
consistent or not. If a variable definition includes a unit operation that is not allowed, the definition is
not accepted as valid.
There are some units that are built-in in Studio, including the seven base units of the SI system. In
addition, a few time units, temperature scales, and angular units are pre-defined. These System Units
are maintained by Studio, and you cannot alter them. They are marked by green icons in the unit
views.
Note! The selected calendar of your simulation will affect the definition of the time units mo
(month), qtr (quarter), and yr (year).
An example of a unit that can act as both a point and normal unit. On the left side, the unit denotes a
specific point on the temperature scale (such as 100@C, the boiling point of water). On the right side,
the unit represents an interval on the scale. This illustrates the difference between 80@C and 60@C
of 20C.
- 220 -
Atomic Units
A unit can be either derived from other units, or it can itself constitute the basis for other units to be
derived from. In the latter case, the unit is an atomic unit. You are free to create your own atomic
units as you please. Such atomic units can be 'cars', 'products', 'people', etc.
All variables in Studio have units associated with them even though they appear to be unitless, in
which case their actual unit is '1' (=unity). The unit is calculated from the expression that defines the
variable, or it is specified in the Unit box in the Properties dialog box. When creating models it is only
necessary to include the units on the "border" variables that surround the model, usually constant
auxiliaries, and the units will propagate throughout your model. You can, however, change the unit of
a variable to a compatible unit, if you wish to. As an example, if you have a variable that has the unit
'm' (=meter) as a result of its definition expression, you can explicitly specify that it should use the
unit 'km' (=1000*m) instead.
As units are part of the computation, you must make sure that the definition expressions that you enter
preserve the unit consistency of the model. Otherwise, the variable definition will not be accepted,
and the variable will still be regarded as undefined. The various functions that you can use in
definition expressions follow rules for unit computation. You can find the requirements for each
function in their reference page, together with information on the unit returned from them.
You can include literal expressions including units inside other expressions without having to define
them as constant auxiliaries first. In this case, you enter the literal expression in the following pattern:
Example:
50<<m>>/10<<s>> = 5<<m/s>>
Not all operations and functions accept point units as input parameters. This is due to the different
nature of point units as compared to normal units. To illustrate this, let us consider an example
including two dates. The difference between the two is the time interval between them, which is easy
- 221 -
to understand. However, the sum of two dates is worse, not to mention the multiple of the two. There
are therefore certain restrictions that apply when using point units in definition expressions.
Unit Identifiers
The definition text of a unit can also contain several unique identifiers that enable Studio to recognize
the unit's behavior. These identifiers are used to identify atomic units (that is, units that are not
dependant on other units), local currency, the base units of the SI system, etc. The table below
explains these identifiers.
Identifier Description How to define it
Identifies point units. Enter the scale of
the unit in the first
part of the
@(<scale>,@<offset>) expression, and the
offset of the unit in
the second (after the
@-sign).
Identifies an atomic unit. Select the Atomic
radio button in the
ATOMIC
Unit Definition
property page.
Creates a local currency unit. Available under
Add Currency Unit
__LOCALCURRENCY on the shortcut
menu inside the
Global Units view.
- 222 -
Creates a unit for the currency identified Some are available
by the string. The currency symbol and under Add
currency formats for the specified Currency Unit on
currency is used. To define a conversion the shortcut menu
rate towards another currency, you are inside the Global
__CURRENCY
allowed to define it as an optional Units view. If you
("<string>" [=<Conversion
definition parameter (this requires the need other
Expression>])
currency used in the conversion to be currencies, simply
defined). define them
Example: __CURRENCY("USD"), manually.
__CURRENCY("EUR"), __CURRENCY
("BEF"=EUR/40.3399)
__SECOND Creates a base unit from the SI system. Available under
__METER Add Standard Unit
__KILOGRAM on the shortcut
__CANDELA menu inside the
__AMPERE Global Units view.
__KELVIN
__MOLE
Creates a pseudo-unit from the SI system. Available under
Add Standard Unit
__RADIAN
on the shortcut
__STERADIAN
menu inside the
Global Units view.
Pre-defined Units
When you create a simulation project in Powersim Studio, there are several units already defined in
Global Units. These units are listed in the table below. These System Units are maintained by Studio,
and cannot be altered. System Units have a green unit icon in the views.
Unit Definition Notes
@(__SECOND; 0@__SECOND) Second. Based on the base unit for time from the SI
s system. The unit is a System Time Unit that cannot
be deleted or modified.
@(60s; 0@s) Minute. The unit is a System Time Unit that cannot
min
be deleted or modified.
hr @(60min; 0@min) Hour.
@(24hr; 0@hr) Day. The unit is a System Time Unit that cannot be
da
deleted or modified.
@(7da; 0@da) Week. The unit is a System Time Unit that cannot be
wk
deleted or modified.
@(30da; 0@da) (Bank calendar) Month. The unit is a System Time Unit that cannot be
deleted or modified. It will be undefined if the
mo
calendar specified for the simulation is Gregorian or
Fiscal.
@(90da; 0@da) (Bank calendar) Quarter. The unit is a System Time Unit that cannot
qtr @(91da; 0@da) (Fiscal calendar) be deleted or modified. It will be undefined if the
calendar specified is Gregorian.
- 223 -
@(360da; 0@da) (Bank calendar) Year. The unit is a System Time Unit that cannot be
yr @(364da; 0@da) (Fiscal calendar) deleted or modified. It will be undefined if the
calendar specified is Gregorian.
@__RADIAN Radians. A pseudo-unit for plane angles from the SI
system. The unit is a System Unit that cannot be
rad
deleted or modified. The unit represents a plane
angle.
@ Degrees. Based on the pseudo-unit rad. The unit is a
deg ((3,14159265358979323846/180) System Unit that cannot be deleted or modified. The
rad; 0@rad) unit represents a plane angle.
@ Gradians. Based on pseudo-unit from the SI system.
grad ((3,14159265358979323846/200) The unit is a System Unit that cannot be deleted or
rad; 0@rad) modified. The unit represents a plane angle.
0.01 Percentage. A built-in unit in Studio. The unit is a
System Unit that cannot be deleted or modified. The
unit makes it possible to work with percentages as a
%
unit rather than as functions (as earlier). Corresponds
to the PCT function. The following expression is true:
x% = x * 0.01
- 224 -
°(__KELVIN; 273,15° Celsius. Based on the base unit for temperature from the SI
C
__KELVIN) system, Kelvin.
F °(5/9C; -32*5/9°C) Fahrenheit. Based on Celsius.
Note! The definition of currencies that are fixed towards the euro are based on the irrevocable
euro conversion rates published 31 December 1998. The conversion rate for the Greek
Drachma (GRD) is based on the conversion rate published 19 June 2000.
- 225 -
__CURRENCY("FIM"=EUR/5.94573) Finnish Markka. This currency is fixed towards
FIM
the euro.
USD __CURRENCY("USD") US Dollars (independent).
GBP __CURRENCY("GBP") British Pound (Pound Sterling, independent).
JPY __CURRENCY("JPY") Japanese Yen (independent)
NOK __CURRENCY("NOK") Norwegian Kroner (independent).
__LOCALCURRENCY Locale Currency Unit. A unit for currency
which takes it settings from the locale currency
unit specified in Regional Settings (or Options)
loc on your computer. Use this currency unit if the
currencies used in your model should use the
locale settings (and isn't dependent on currency
conversion).
Tip! You can find the latest (daily) euro foreign exchange reference rates for most other
currencies at the European Central Bank.
- 226 -
The 'PER' Identifier
Studio allows you to use the 'PER' identifier as a substitute for the division operator ('/') when
defining units. To use the 'PER' identifier for a variable, it must be exiplicitly defined, as the default
operator when Studio calculates a unit for a variable will usually be '/'.
Units are essential in Studio and are evaluated at run time. Units are used to relate values to each
other, and are taken into account when simulation results are computed. Their importance is
particularly noticeable when it comes to flow rates. For the simulation to know the magnitude of the
flow, it has to know the time horizon to which the flow relates. Evidently there is a major difference
between having one car entering an intersection per second, and having one car entering per hour.
Therefore, it is a lot easier to create models with units than without.
If you need to create a model without using units, there are two ways to achieve it. You should be
aware, however, that creating models in this way can cause strange units to be computed by
Constructor.
Unity variables
If a unit is not explicitly chosen for a variable, the variable will have 1 (=unity) as its unit (achieved
by leaving out the unit part or setting it to 1). By using unity as the unit for the variables in the model,
all variables except flow rates can be defined without a specific unit. However, you must make sure
that your flow rates are defined with a rate unit (1/time). This offers a good and stable way of
modelling. However, unit consistency will not be checked, increasing the possibility that your model
contains errors in the definition expressions..
Once you select calendars to be available to your project, this will also affect the sum of the time units
for the project. This is because the various calendars have a different number of days, thereby making
it possible to define units such as month, quarter, and year. Only units that are equal for the selected
calendars will be available in the project. As an example, since 'quarter' is defined differently for the
bank and fiscal calendar and undefined for the Gregorian calendar, it will be available if only one of
either the bank or fiscal calendar is selected. If you select two or more calendars, 'quarter' will become
undefined.
The table below shows how the various time units are defined for the various calendars.
- 227 -
Calendar
Unit Gregorian Bank Fiscal
s (second) @__second @__second @__second
min (minute) 0@s+60s 0@s+60s 0@s+60s
hr (hour) 0@s+60min 0@s+60min 0@s+60min
da (day) 0@s+24hr 0@s+24hr 0@s+24hr
wk (week) 0@s+7dy 0@s+7dy 0@s+7dy
mo (month) undefined 0@s+30dy undefined
qtr (quarter) undefined 0@s+90dy 0@s+91dy
yr (year) undefined 0@s+360dy 0@s+364dy
Tip! You can also define the unit directly in the Global Units view. Simply select the cell in the
column you wish to edit (click F2 if the cell isn't opened for editing immediately), and enter the
definition.
A newly created unit will remain undefined until you have defined it on the property page. An
undefined unit is indicated in the Global Units view with a red question mark. If you use it in a
variable definition before it is properly defined, the variable definition will not be accepted as a valid
definition.
Local units are available only to the component it is defined in. You can define both normal and point
units as local units, but they cannot be atomic.
To add a local unit:
1. Open the Local Units view by double-clicking its entry in the Project Window (located
under Component and Simulation), or select Local Units under Simulation Windows on the
View menu.
2. Right-click somewhere in the white space inside the view, and select Add Unit on the shortcut
menu.
3. Hit F2 and enter a name for the unit.
4. Double-click the unit to define it on the Unit Definition property page.
- 228 -
Tip! You can also define the unit directly in the Local Units view. Simply select the cell in
the column you wish to edit (click F2 if the cell isn't opened for editing immediately), and enter
the definition.
You should always prefix local units with a '.' (punctuation mark) when using it in expressions and
fields. Thus, the local unit 'km' should always be referred to as '.km'.
Note! Since local units cannot be atomic, they must be derived from global units.
You can add currencies to your list of units. There are two types of currency units available in Studio.
First, there is the loc unit, which is a unit that uses the currency settings on the computer running the
model. Thus, values are presented using the user's own currency settings. To add the loc unit to your
project:
1. Right-click inside the Global Units view (somewhere in the white space), and select Add
Currency Unit on the shortcut menu.
2. Select loc - Locale Currency on the submenu that appears.
Studio also have a list of pre-defined currencies that you can add to your project. These are the euro
and the currencies that are fixed towards it, in addition to US Dollars and British Pound Sterling. To
add a pre-defined currency to your project:
1. Right-click inside the Global Units view (somewhere in the white space), and select Add
Currency Unit on the shortcut menu.
2. Select the currency you wish to add on the submenu that appears.
Note! If you insert one of the currencies that are fixed towards the euro (such as DEM or FRF),
the euro (EUR) will be added automatically.
You can also create currencies with conversion rates towards other currencies, to enable your model
to convert between various currencies. To create two currencies with a defined conversion rate:
1. Add the two currencies to Global Units. Select them under Add Currency Unit on the
shortcut menu, or define them manually using the __CURRENCY("") syntax.
Example: USD = __CURRENCY("USD") and GBP = __CURRENCY("GBP").
2. Find the conversion rate to use (either on the Internet or elsewhere).
3. Double-click one of the currency units to open the Unit Definition property page.
4. Alter the definition of the currency to include the conversion rate.
Example: USD = __CURRENCY("USD"=0.728544*GBP)
5. Click OK to save the changes, or click Apply to save the changes without exiting the dialog box.
Tip! You can also define the unit directly in the Global Units view. Simply select the cell in
the column you wish to edit (click F2 if the cell isn't opened for editing immediately), and enter
the definition.
Note! The conversion rate used in the example below will change on a daily basis. Please find
the correct rate to use on the Internet or elsewhere before implementing the rate in your
project!
- 229 -
Add Standard Units
A list of commonly used standard units are available in the Global Units view. To add a standard unit:
1. Right-click inside the Global Units view (somewhere in the white space), and select Add
Standard Unit on the shortcut menu.
2. Select the unit you wish to add on the submenu that appears.
Note! If the unit you have selected is dependent on other units, all those units will be
automatically added to your project.
An atomic unit is a unit that is not based on other units. Typical examples of atomic units are the
seven base units of the SI system, currency, and various units such as products, cars, people, etc. You
can define as many atomic units as you like. Only global units can be defined as atomic.
1. Double-click the unit you wish to define, or right-click it and select Properties on the shortcut
menu.
2. Enter the long and plural names in Long name and Plural name respectively.
3. Select the type of unit you want to create by selecting either the Point Unit or the Normal Unit
option.
4. Select the Atomic option to create an atomic unit.
Tip! You can also define the unit directly in the Global Units view. Simply select the cell in
the column you wish to edit (click F2 if the cell isn't opened for editing immediately), and enter
the definition.
When you have selected Atomic, the text 'atomic' is automatically entered in the Definition box. If you
created an atomic point unit, the text field will read '@atomic'.
Tip! When you have become familiar with the unit definition syntax, you can enter your unit
definitions directly in the Definition box.
Normal units represent intervals on a scale of known quantities. Such units can be used to measure
lengths, masses, products, cars, people, etc. Derived units are derived from SI base units or from your
own atomic units.
Note! To be able to define a derived unit, all the units used to define it must already be defined
in your project.
- 230 -
shortcut menu.
2. Enter the long and plural names in Long name and Plural name respectively.
3. Select the Normal Unit option. The lower half of the page is activated.
4. Select the Derived option.
5. Replace the default text <scale> by the scale of the unit. (Example: To define km as a unit, enter
'1000m'.)
6. Click OK to finish the definition, or click Apply to apply the changes without closing the
property page.
Tip! You can also define the unit directly in the Global Units or Local Units views.
Simply select the cell in the column you wish to edit (click F2 if the cell isn't opened for editing
immediately), and enter the definition.
Tip! You can enter the appropriate unit (or unit expression) by selecting the unit in the list on
the right of the property page, and transfer it to the unit field by clicking the << button.
Point units are used to explicitly define a unique point on a scale. The boiling point of water, 100°C, a
date in history, such as January 1, 2000, are examples of such unique points that can be represented
by point units in Studio. Point units are prefixed with '@'.
A point unit is defined by two parts. The first defines the scale of the unit, while the other defines the
offset. A derived point unit is derived from SI base units or from your own atomic units. The
definition syntax of a point unit is
@(<scale>, @<offset>)
°(<scale>, °<offset>) // Alternative syntax
and when used, the variable definition expression can take the form
aux A = 85<<@C>>
Note! You can use either of the two available identifiers '@' and '°'.
- 231 -
Tip! You can also define the unit directly in the Global Units or Local Units views.
Simply select the cell in the column you wish to edit (click F2 if the cell isn't opened for editing
immediately), and enter the definition.
Example: Let's say we wish to create a new temperature unit that has its zero at the boiling point of
water: 100 degrees Celsius. The unit should measure temperature in intervals of 10 degrees Celsius.
In this case, the scale of our unit will be '10C', and the offset will be '100@C' (remember the '@' to
indicate the offset). Thus, our unit will have the definition
Note! To be able to define a derived unit, all the units used to define it must already be defined
in your project.
A level is defined by an initial value and the sum of flows that run into or out of it. In order for the
level to work properly, you must explicitly select a unit for it.
1. Double-click the level, or right-click it and select Properties on the shortcut menu.
2. In the Definition page, enter the unit you wish to use in the Unit box. All previously used unit
expressions will be available in the box.
Or:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition text field, you can enter the unit directly in the definition expression, as '<<Unit
name>>'. (Example: 100 <<m>>.)
Tip! You can use the multi-function list at the bottom of the property page to select units for
your definition. When the cursor is placed in the Unit box you can double-click the unit in the
list to insert it.
A constant is a variable that does not change over time. If the constant is defined as a literal only (a
number) you can explicitly define its unit.
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition page, enter the unit you wish to use in the Unit box. All previously used unit
expressions will be available in the box.
Or:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition text field, you can enter the unit directly after the literal expression expressed as
'<<Unit name>>'. (Example: 100 <<m>>.)
- 232 -
Tip! The latter method can also be used when creating variable expressions. (Example: 100
<<m>>/ 10 <<s>>, which would produce the value 10 <<m/s>>.)
Note! If an auxiliary is defined by an expression, you are not allowed to specify the unit
yourself unless it is compatible with the computed unit.
Some restrictions apply to how you can specify units for auxiliaries. If the auxiliary is defined by a
literal (a number) only, you can specify any unit for the variable. You can do this either in the Unit
box or directly in the expression. If the auxiliary is defined by an expression involving other variables
(with units) and/or expressions involving units, Studio will itself compute the unit for the variable. In
this case, you can only specify a unit in the Unit box that is compatible with the computed unit. If, for
example, the computed unit is 'm', you are free to assign any unit that is defined using 'm'. If 'km' is
defined as '1000m', you can assign 'km' as the unit for the auxiliary.
To specify a unit for an auxiliary:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition page, enter the unit you wish to use in the Unit box. If Studio has computed a
unit for the variable, the selected variable must be compatible with the computed unit.
You can also include the unit directly in the definition expression of the variable:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition text field, you can enter the unit directly after the literal expression expressed as
'<<Unit name>>'. (Example: 100 <<m>>.)
Tip! The latter method can also be used when creating variable expressions. Such expressions
can also contain other variables. (Example: A / 10 <<s>>, where A is a properly defined
variable.)
Units are an integral part of the variable definition, and is calculated automatically by Studio. It is
therefore important that units are included correctly in the variable expressions, since you later can
only specify units that are compatible with the already computed unit. It is, in other words, impossible
to "fix the mistake" by overriding the computed unit by a specified unit.
It is therefore a good solution to use constant auxiliaries rather than literals in variable expressions.
By using constant auxiliaries with the appropriate units, the units are automatically included in your
expression. Provided your variable definitions are correct, the units will propagate throughout your
model immediately.
It is, however, possible to include literals with units in your definitions. You do this using the
following syntax:
Value <<Unit Name>>.
- 233 -
Examples
The following expressions are valid:
aux A = 3<<m>>
aux B = 3<<m>>/6<<s>> (=0.5 <<m/s>>)
Instead of including literal expressions with units inside definitions of variables, we recommend you
to create constants for all such literal expressions. You can then use these constants in your variable
definitions, making your model easier to maintain.
const A = 3<<m>>
const B = 6<<s>>
aux Result = A/B (yielding a unit of 'm/s')
unit Result = <<m/s>>
The units of A and B are entered in the Unit box in the Definition property page. The unit of Result is
automatically calculated.
Note! To enter a point unit, always remember the preceding '@'. (Example: 20<<@C>>.)
unit m = __METER
unit km = 1000m
unit cm = 0.01m
unit knot = 1852m/hr // nautical miles per hour
ppl = ATOMIC
USD =__CURRENCY("USD")
GBP = __CURRENCY("GBP"=1.51USD)
NKR = __CURRENCY("NKR"=0.11USD)
Using these units and the time units in Studio, we can create some examples of compatible units:
- 234 -
Ex. Compatible units
1. m/s km/s km/hr
2. m cm km
3. ppl/da (people per day) ppl/mo (people per month) ppl/qtr (people per quarter)
4. $ £ Nkr
Sometimes you might not want to include units throughout your model. In such cases, you should
leave the Unit box empty. In addition, if you want to make flow rates appear without time rate units as
well, you can turn off time units for simulation time.
1. Right-click the Project entry in the Project Window, and select Project Settings on the
shortcut menu.
2. Uncheck the Time has unit option.
3. Select the time interpretation interval.
4. Click OK to apply the changes, or click Apply to apply the changes without closing the dialog
box.
You can now run your models without units on flow rates or other variables. When you have selected
a time interpretation interval, all your flow rates are given relative to this interval. Thus, if you have
selected a time interpretation interval of '1 week', all your flow rates will be given in the (hidden) rate
unit <<1/week>>.
Tip! Using units of measurement makes it easier to create models with correct variable
definitions, since unit computations provide an instant consistency check of your model!
Note! Deleting a unit will render all variables that use the unit invalid. Furthermore, any unit,
both global and local, that depend on the deleted unit will also become invalid.
- 235 -
Delete a Local Unit
Note! Deleting a unit will render all variables that use the unit invalid. Furthermore, any unit,
both global and local, that depend on the deleted unit will also become invalid.
1. Open the Local Units view by double-clicking its entry in the Project Window (located under
Component and Simulation), or select Local Units under Simulation Windows on the View
menu.
2. Right-click the unit that you wish to delete in the list, and select Delete on the shortcut menu.
- 236 -
Work with Variable Definitions
There are three types of variables in Studio: constants, levels, and auxiliaries. Levels are initialized at
the start of the simulation, and thereafter accumulate their value over the simulation run. Auxiliaries
are calculated every time step. Finally, constants are initialized at the start of the simulation and then
left unchanged by the simulation over the run. Constants accept input from the user, however. Both
constants and levels can be made Permanent, in which case they keep their values between
simulations rather than being initialized when the simulation is reset.
The main property of a variable, regardless of variable type, is the variable's definition. Studio will
automatically find the variable's unit, dimension, and data type based on the defining equation,
provided the definition contains enough information. The definition is used to calculate the variable's
value during the simulation (or initially, if the variable is a level or a constant). Unit, dimension, and
data type can also be defined manually, which can be useful in some cases, especially when using
named ranges when creating arrays.
Note! If you manually override the automatic definitions, you must make sure that all the
definitions are compatible!
Levels accumulate the value of flows that flow in and out of them. There are three types of flows in
Studio: Continuous, Discrete, and Logical. The type of the flow is determined by the integration
setting and data type of the flow rate that controls the flow. The way the flow influences the level is
defined by the level's flow definition. When you connect flows to a level, Studio will automatically
set up the flow definition, but you can change it manually. You can create level-and-flow structures
where the flow rates and the levels have different dimensions by using flow functions in the flow
definition.
Studio also features a special type of levels called reservoirs. Reservoirs can never be depleted below
zero. This is achieved by the use of advanced integration techniques.
The three variable types as they are represented in a Constructor diagram. The flow rate is an
auxiliary that controls the flow out of a level. The flow is a continuous flow (the most common flow
type).
Editing variable definitions can be done in several ways. First, you can use the Definition Property
- 237 -
page. The Definition box of the Definition property page features advanced railway syntax checking
and color coding. Second, you can edit the definitions in the variable's definition node in the Details
Window and in the Equations View. And third, you can use the variable name field in the
Constructor diagram to enter the definition directly. Simply start by typing an equal sign ('=') in the
same way that you normally do when entering cell formulas in spreadsheets.
There are three variable types in Studio: Levels, Auxiliaries, and Constants. In a simulation model,
levels represent states in the system that change over time. Auxiliaries combine and reformulate
information as it passes through the system. Constants represent information that is not changed by
the simulation, but they can be changed by the user (through input controls).
Below you will find information that is common for all variables, and then information that is specific
to the various variable types.
Note! Although Studio recognizes integers, variables will always use REAL as the automatic
data type. This is to prevent that other variables that use these variables as inputs become
invalid due to data type mismatch. If you need an INTEGER variable, you must select the data
type it explicitly.
The Unit of a variable defines the unit of measurement of the variable. For a unit expression to be
valid, you must use or build on valid atomic or predefined units as they are defined in Local or
Global Units (available in the Project Window). Units are set automatically based on the
variable's definition, and you will usually not have to do anything about them. If the definition is a
literal expression without a unit (or rather unity), you are allowed to assign any unit to the variable
using the Unit box. You may override the automatic unit for a variable as long as the unit is
compatible with the unit yielded by the variable's definition (you will be warned if this is not the
case).
Tip! Create constants for all the actual constants in your model, rather than including them as
literal expressions inside your variable definitions. This makes it easier to maintain the
variable definitions in your model (should a unit name change, for example).
The Dimensions of a variable defines the structure of a variable. Variables that have no dimensions
are called scalars, while variables that have one or more dimensions are called arrays. The dimension
of the variable defines both the size of the array and the indices that apply. Studio can automatically
detect the dimension of a variable based on the variable's definition. You are free to manually define
the dimension as well, in which case you have full control of both the size and the indices used. As an
- 238 -
example, while the two dimensions '1..10' and '11..20' have the same size (both containing 10
elements), their indices are not the same (the first is indexed from 1 to 10, while the second is indexed
from 11 to 20). When you manually set the dimension of a variable, you must observe that the
dimension is compatible with the variable's definition (you will be warned if this is not the case).
The Variable Type defines how the variable may be used in the model. There are three variable types
currently available in Studio: Level, Constant, and Auxiliary. The three variable types are described
in detail below. You are usually allowed to change the type of a variable after you have inserted it in
the model. However, certain restrictions apply when you do this. You cannot change the type of a
level if it has flows connected to it, since it is only levels that can have flows.
Variables can import their values from external sources through datasets. Similarly, they can export
their values. A variable can be imported in two ways. Either it can have an initial import, which
means that only the initial value of the variable is imported (the value at the start of the simulation), or
it can have a full import, which means that the variable gets its value for all time steps from the
external source. If the variable is exported, on the other hand, it is calculated in the normal way, and
the results are exported to the external source as specified in the dataset. You may also combine the
settings, allowing you to import and export values from the same variable in the same simulation.
Note! Imported values will override the values calculated by the variable's definition.
The defining expression, called the Definition is the most important part of the variable's properties.
Usually, most of the information described above can be automatically generated by the definition,
and you will experience this in your own work. The definition acts differently for the three variable
types, and it is therefore treated individually below. Applicable for all variable definitions, however,
is that the definition must follow the function and operator requirements, as set forward in the
functions' and operators' data sheets.
Levels and constants may also be defined as permanent variables (not applicable to auxiliaries). A
permanent variable keeps it value between simulation runs, as opposed to ordinary variables which
will always be initialized again when the simulation is reset. Permanent variables can therefore be
used to create levels that accumulate their value over several simulation runs, as opposed to ordinary
levels that will only accumulate their value over one simulation run. Permanent constants allow you to
create user interfaces where the values entered by the user "survive" when the simulations are reset.
Permanent variables will only be recalculated by their definitions on demand, when you click
Restore Permanent Variables.
Level
Levels are variables with memory, and their value are determined by the flows that flow in and out of
them. The value of a level at time t can always be found by the expression below, where dt is the time
step of the simulation run. As we can see by this expression, levels conserve the matter that flows in
and out of them.
Levelt+∆t = Levelt + inflowst - outflowst
For levels, the definition is used to calculate the initial value of the variable; the value at start-up. In
addition, a level contains a flow definition, that defines how the flows should be accumulated each
time step. The flows themselves are controlled by other variables (one per flow) that work as flow
rates.
There are three types of flows available in Studio; continuous, discrete, and logical. If one or more
flows that are connected to the level are continuous, the data type of the level must be either REAL or
COMPLEX for the flow to be defined. This is due to the nature of continuous flows, since a rate cannot
be defined in terms of integers and logical values. If the flow is discrete, the level can be INTEGER as
- 239 -
well. Obviously, for logical flows, both the flow rate and the level must be LOGICAL. The flows are
controlled by flow rates, and when creating level-and-flow structures, it is important that the
controlling flow rates and the levels match each others definitions (including units, data types, and
dimensions).
Note! The level itself can be of any of the available data types. It is actually the connected flows
that will be undefined if the data type of the level doesn't match the data type of the flow rate
that controls the flow.
When connecting a level to an external data source, you are allowed to export the entire time series
yielded by the variable. You are, however, only allowed to import the initial value, since allowing
import of later values would violate the basic principle of levels presented in the equation above.
Levels can also be defined as reservoirs (available on the Integration property page of the variable).
Reservoirs cannot be depleted below zero.
Auxiliary
Auxiliaries are "helper variables" that allow you to combine and reformulate information that exists in
your model. Auxiliaries are volatile in the sense that they have no memory and are calculated at least
once every time step. Their values are always calculated by their defining expressions. Auxiliaries are
usually defined entirely by other variables (used as parameters and operands in the defining
expression). Units, data type, and dimensions will be detected automatically, and you can in most
cases accept the automatic settings of these properties. If you decide to change them, you must ensure
that the new settings are compatible with the automatic settings given by the definition.
Tip! It is good advice to use constant variables instead of including literal constants in variable
definitions. By isolating such constants in their own variables you give yourself the opportunity
to fully utilize Studio's automatic unit detection, as well as visualize potential decision
parameters in your project.
When you create a simulation project, you define the integration order for the entire project. In
addition you can define individual integration order for selected auxiliaries. In addition to the default
option of using the project's settings, you can select between first and zero order integration. The
integration order setting for the variable is especially useful when the auxiliary is used as a flow rate.
Selecting first order integration creates a continuous flow that is unchanged over the entire time step.
Using zero order integration creates a discrete flow. If the auxiliary does not control a flow, the
integration order will only affect the calculation of the individual auxiliary, and thus only affect other
variables indirectly (by the fact that its value is not changed during the time step, as it would normally
be when using higher order integration methods).
Note! While discrete flows are similar to transactions where a certain amount is transferred at
the start of the time step, continuous flows are controlled by rates relative to time. Thus, while a
flow rate controlling a discrete flow has a compatible unit to the corresponding level, a flow
rate controlling a continuous flow must have a unit that is compatible with the level's unit
divided by time.
Auxiliaries allow you to only import the full time series, thus giving you the option of either
calculate all values for the simulation run using the variable's definition, or importing all values from
an external source. In addition, auxiliaries cannot be defined as permanent variables.
- 240 -
Constant
Constants are often used to identify and quantify the boundaries of the model, and to represent
decision parameters. They are, as the name implies, constant, and the definition only defines the
initial value (the definition is only calculated at the start of the simulation). You are allowed to assign
a new value to a constant through input controls, thereby changing the scenario of the model.
By creating permanent constants, you can create constants that not only keep their values over one
simulation run, but also keeps its value between simulation runs. Permanent constants thereby allow
you to create simulations that "remember" the input given by the user.
As mentioned above, it is often useful to create constant variables rather than including literal
constants in various variable definitions. This cleans up your model, and visualize parameters that
might be decision parameters in your system. It also enables you to gain full effect of Studio's
powerful unit detection capabilities. Also, should you have to change units at a later stage, you will
only have to do so for a handful of constants rather than going through all the variables of your
system to find them.
Permanent variables are ordinary levels or constants that keep their values between simulation runs.
You can use permanent constants for user input, since these constants will remember the user's input
when the simulation is reset. If you use normal constants for this purpose, the user must reenter all her
parameter settings when the simulation is reset. Permanent levels are also useful in some situations.
While normal levels are always initialized using their definitions when the simulation is reset,
permanent levels will use the value they had at the end of the last simulation run. Permanent levels
will therefore accumulate their value over several simulation runs, not only over one simulation run as
normal levels do.
The definitions of normal constants and levels are used to initialize the variables at the start of the
simulation. For permanent variables the definitions are only evaluated when the variable is defined or
when the command Restore Permanent Variables is invoked (on the Simulation toolbar or
menu). You can thereby reinitialize the model at any time, should you need to.
Note! When the Restore Permanent Variables command is invoked, the levels are also
reinitialized, even if the simulation is in the middle of a simulation run.
About Reservoirs
A reservoir is a level that cannot be depleted below zero. In other words, it does not permit a negative
initial value and a reservoir's outflow is leveled out when the reservoir's value reaches zero.
Note! A reservoir will never become negative, but rather become undefined (NAN) if an outflow
tries to empty it below zero. The outflow should therefore handle the situation when the
reservoir becomes zero specially.
When the reservoir approaches zero, the simulation engine divides the time step into smaller parts, to
ensure that the depletion is performed correctly. When the value of the reservoir reaches 0, the normal
- 241 -
time step is resumed, and the simulation continues as normal.
Note! The simulation engine will recalculate the entire model, and not only the reservoir at the
subdivided time step. You should therefore be aware that the model might produce slightly
different results when you use reservoirs than when you use ordinary levels.
The integration method used when calculating reservoirs will, as mentioned above, subdivide the time
step into smaller portions if the reservoir is depleted towards zero. It is therefore impossible for a
reservoir to have zero order (discrete) or first order flows connected to it. Please observe that your
reservoirs have flows using the project's default integration method connected to it!
Example 1
As mentioned above, the flow rate controlling the flow out of the level must feature some kind of
feedback from the level. Otherwise the value of the reservoir will become undefined (NAN). A
sample model that has this feedback is shown below.
With normal levels, such a depletion of a level is difficult to program. Usually the feedback would
lead to an uncontrollable oscillation in the level. With reservoirs, the simulation engine will divide the
time step into smaller parts, to ensure that the depletion is done correctly. When the value of the
reservoir reaches 0, the normal time step is resumed, and the simulation continues as normal.
Example 2
The second example model shows a simpler case than the model above. In this model, the reservoir is
depleted with a constant value until it becomes zero, in which case the flow out of the reservoir ends.
In addition, it also illustrates the difference between using a level and reservoir for modeling this
behavior.
- 242 -
If we, on the other hand, define Level as an ordinary level, the result will be quite different. In this
case, the level will drop below 0 before the flow rate can reduce the outflow. In this case, the final
value of the level will be too low. The behavior of the model (using a level rather than a reservoir) is
shown below.
Finally, if you leave the flow rate constant throughout the simulation, the reservoir will become
undefined as its value drops below zero. The behavior of the model (using a reservoir but not
including a feedback to the flow rate) is shown below.
The sections below contain various examples of variable definitions in Studio. Although there are
unlimited possibilities for defining variables, these examples should give you an idea of how to get
started.
The examples below show how to define the variables on the Definition property page. To open this,
either:
! Double-click the variable;
! Right-click the variable and select Properties on the shortcut menu;
! Select the variable and click Properties on the View menu or on the View toolbar;
! Select the variable and hit Alt-Enter on your keyboard.
The examples require that there are no previous definitions in the various boxes. If there are, please
delete them (or click Auto in front of them) before applying the changes from the example.
Note! Some of the definitions below are started by the string "def". This implies that the
variable can be of any variable type. Otherwise, "const" represents a constant, "aux"
represents an auxiliary, and "level" represents a level.
- 243 -
Example 1: Literal Expressions
Literal expressions are useful when initializing levels and constants. They are entered as:
def Variable = 10
You can include the unit directly in the literal expressions (or literal parts of other expressions) like
this:
Alternatively, you can use the Unit box to specify the unit:
def Variable = 10
unit Variable = m // Unit 'm' must be defined (as __METER)
If you define an array, you can enter the array using '{' and '}', as:
In the latter case Studio will automatically calculate the dimension of the variable. In this case, it will
be 1..2,1..3. You can also specify the dimensions yourself, if you wish to. You can also specify
the dimensions explicitly. In addition, if all elements are equal, you don't have to enter all the
elements separately.
If units are included in the expression, they must be included together with one or both of the
operands:
You can only explicitly set a unit for the variable that is compatible with the unit yielded from the
expression itself. In the above example, you can only set a unit that is compatible with m/s.
- 244 -
def Variable_3 = ... // Any definition
def Variable = Variable_2*Variable_3
If several operators are involved in the expression, the calculation order and operator precedence is
used to evaluate the expression. Thus, the expression
Most of the operators accept arrays as operands, except where noted on the operator's reference sheet.
The default operators will perform the operation element by element. If you wish the operation to be
performed according to mathematical rules for arrays (such as matrix division, etc.), you can precede
the operator by '#' (hash). The difference between the division ('/') and array division ('#/') operators
are illustrated below.
The ABS function will also accept another function expression as its input parameter.
The expression above can also be modeled using three different variables, which is the preferred
method to do this. We would use two auxiliaries named Sine Wave and Positive Wave and a constant
named Period. The variable definitions are shown below.
Note! When referring to variable names with spaces, you must always enclose them in
apostrophes (').
- 245 -
aux 'Positive Wave' = ABS('Sine Wave')
The output from this simple model is shown in the time graph below.
Note! If you enter an array for each array element, the dimensions for the elements entered
must be identical for all elements.
To illustrate, let's create two auxiliaries and name them Array and Summary. The definitions are
presented below.
Note! If Array in the above example is defined with a unit, the definition for Summary will
become invalid, since the unit of the four elements wouldn't be compatible.
You can also use the FOR and CONCAT functions to create arrays, illustrated by the two definition
expressions presented below.
Note! Succeeding '*' can be omitted. The expression A[i,*,*] is identical to the expression A[i].
However, preceding '*' are mandatory. The expression A[*,*,i] is NOT identical to the
expression A[i]!
- 246 -
To illustrate, create four auxiliaries and name them Array, Single, Multiple, and All. The definitions
are presented below.
The second example above, resulting in the array Multiple, uses a numerical subrange (1..2) to
index the array. When indexing arrays, such numerical subranges can be open in one end (replacing
the start or end index with '?'). If they are open, Studio assumes that the ranges include the elements to
the end of the dimensions. The example below, which requires three variables Array, A, and B,
illustrates this.
Sometimes it can be useful to use ordinary variables as the index of an array. In Studio this can be
achieved in two ways; by the LOOKUP and INDEX functions. The example below illustrates both
approaches. While the LOOKUP function takes the array and the indices as input parameters, the
INDEX function converts an (integer) variable into an index variable that can be used to index the
array directly. You need five variables: Array, A, B, C and D.
def A = {1,2,3,4,5}
- 247 -
def B = {6,7,8,9,10}
def C = CONCAT(A,B[6..10:6..10])
result C = {1,2,3,4,5,6,7,8,9,10}
If you try to concatenate arrays with more than one dimension, you must observe that only one
dimension is different between the arrays. The following example illustrates this. You need four
auxiliaries A, B, C, and D.
def A = {{1,2},{3,4},{5,6}}
def B = {{7,8},{9,10},{11,12}}
def C = CONCAT(A,B[*,3..4:3..4])
result C = {{1,2,7,8},{3,4,9,10},{5,6,11,12}}
def D = CONCAT(A,B[4..6:4..6,*])
result D = {{1,2},{3,4},{5,6},{7,8},{9,10},{11,12}}
To be able to add the value of the flow to the value of the level, their units must be compatible. Given
the expression above, the unit of the controlling flow rate must be compatible with the unit of the level
divided by time, as shown below. Likewise, the data type of the rate and the level must match, and
they can only be REAL or COMPLEX (if the level is REAL, the flow rate is allowed to be INTEGER).
unitRate = unitLevel/unit∆t
Note! Reservoirs (levels that cannot be depleted below zero) cannot have first order flows
- 248 -
connected to them.
Tip! You can create discrete flows by using zero order integration.
The flow equation of the level defines how the flow is added to the level each time step. Each flow
connected to the level is presented in the flow equation, with a sign (+ or -) denoting the direction
relative to the level. Inflows are added to ('+') and outflows are subtracted ('-') from the level. The
value of the level at a given time t is therefore defined by the expression:
Levelt+∆t = Levelt + inflowst - outflowst
= Levelt + dt*('In Rate 1't) + dt*('In Rate 2't) + ...
- dt*('Out Rate 1't) - dt*('Out Rate 2't) + ...
where In Rate 1, In Rate 2, … represents the flow rates controlling the inflows of the level, while Out
Rate 1, Out Rate 2, … represents the flow rates controlling the outflows of the level. Studio will
automatically detect flows that are connected to the level, and will suggest a flow equation based on
the definition of the flow rate and the level.
Since the flow is simply accumulated by the level, the unit of the flow and level must be compatible.
Given the expression below, the unit of the flow rate must be compatible with the unit of the level, as
shown below.
unitRate = unitLevel
Note! When changing a continuous flow into a discrete flow, you must make sure that the unit
of the controlling rate is changed accordingly!
- 249 -
Note! You cannot use discrete flows with reservoirs, due to the special integration methods
used for reservoirs.
Before the introduction of discrete flows in Studio, discrete flows had to be modelled using
continuous flows with flow rates defined using pulse functions. The problem with these constructions
was that the flow rate was dependent on the selected time step. Changing the time step therefore made
it necessary to redefine the affected variables. Another problem was that if the time step was not 1, the
values yielded by the flow rate was difficult to relate to the quantum actually being represented. A
third problem was caused by higher order integration methods, which would subdivide the time step
and thereby causing different values. To avoid this problem, the flow rate would have to be defined
using the EULER function. With discrete flows you can now create robust model structures that are
easily defined and understood, and that are independent of the time step.
Whereas continuous flows only accept REAL or COMPLEX levels, discrete flows also accepts INTEGER
levels.
The difference between the two methods is the time at which the flow rate F is calculated, and at what
time the flow is added to the level L. When Zero Order is selected, the integration is performed at the
end of the time step. When Zero Order Immediate is selected, the integration occurs at the beginning
of the time step. This means that the variable will only be evaluated upon entry of the time step and
stay constant for the remainder of the time step. The flow rate's value calculated in the current time
step is then immediately accumulated by the level, hence the name immediate.
Note! When using immediate discrete flows, the value of the flow rate will remain constant over
the time step.
Tip! The ASSIGN function available in previous versions of Powersim Constructor can easily be
modeled using discrete flows. Using a zero order flow creates the behavior of the ASSIGN
function, while using a zero order immediate flow allows you to create a structure that
immediately assigns a value to a level when the condition occurs.
The flow equation of the level defines how the flow is added to the level each time step. Each flow
that is connected to the level is presented in the flow equation, with a sign (+ or -) denoting the
direction relative to the level. Inflows are added to ('+') and outflows are subtracted from ('-') the
level. The value of the level at a given time t is therefore defined by the expression below.
Levelt+∆t = Levelt + inflowst - outflowst // zero order
- 250 -
Levelt+∆t = Levelt + inflowst+∆t - outflowst+∆t // zero order immediate
where each in- and outflow is given as described above. Studio will automatically detect flows that are
connected to the level, and will suggest a flow equation based on the definition of the flow rate and
the level.
As for continuous flows, you can use flow functions to create flows where the controlling flow rate
and the connected level are of different dimensions.
where O represents the total outflows and I the total inflows, as expressed below. ( = AND, = OR,
and ¬ = NOT.)
Ot = 'O 1't 'O 2't ... // Outflows
It = 'I 1't 'I 2't ... // Inflows
For logical flows using zero order immediate integration, the flow equation can be expressed as:
Lt+dt = Lt ¬Ot+dt It+dt
- 251 -
The logical level-and-flow structure as it is represented in a Constructor diagram.
The behavior of the model is shown in the table below for various values of the in- and outflows.
Int Outt Statet Statet+∆t = Statet ¬Outt Int
You will find several examples of different flow definitions below, all utilizing the various flow
functions that are available in Studio. You find the flow definition for a level if you click the Flows
tab on the Definition property page. To edit the flow definitions, simply select the flow equation you
wish to edit, and click once to start edit.
Studio will usually find the correct flow definitions automatically. If a flow definition is automatically
created, it will have a comment added to the definition:
dt*COLLECT(Auxiliary) //Automatic
Note! Flow functions can only be used with array flows (not scalars). You must either make
sure that the controlling flow rate is an array (with at least a one element dimension, such as
1..1), or include the vectorization operators ('{' and '}') in the flow expression, such as
FILLINZERO({'Flow Rate'}).
- 252 -
aux Rate = 1<<1/da>>
level Level = 0
flow Level = dt*Rate
The flow definition lets the content of Rate flow directly into Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 0
1/2/2001 1
1/3/2001 2
1/4/2001 3
1/5/2001 4
The flow definition lets the content of each element in Rate flow directly into the corresponding
element in Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 {0,0,0}
1/2/2001 {1,2,3}
1/3/2001 {2,4,6}
1/4/2001 {3,6,9}
1/5/2001 {4,8,12}
- 253 -
Example #3: dt*COLLECT(Rate)
This example shows a flow definition, where an array flow rate controls a flow into a scalar level.
The flow definition creates the sum of all array elements in Rate and lets it flow (joint) into Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 0
1/2/2001 6
1/3/2001 12
1/4/2001 18
1/5/2001 24
The flow definition creates the sum over the second dimension for each element in the first
dimension, thereby creating a flow that has the same dimension as the level. The contents of the flow
is added to the corresponding element in Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 {0,0}
1/2/2001 {3,7}
- 254 -
1/3/2001 {6,14}
1/4/2001 {9,21}
1/5/2001 {12,28}
The flow definition creates the sum over the second dimension for each element in the second
dimension (rather than the first, which is the case for DISTRIBUTE), thereby creating a flow that has
the same dimension as the level. The contents of the flow is added to the corresponding element in
Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 {0,0}
1/2/2001 {9,12}
1/3/2001 {18,24}
1/4/2001 {27,36}
1/5/2001 {36,48}
- 255 -
The flow definition creates a new dimension by dividing the contents of the array elements in Rate by
the number of elements in the missing dimension, thereby creating a flow that has the same dimension
as the level. The contents of the flow is added to the corresponding element in Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 {{3,3,3},{6,6,6}}
1/2/2001 {{6,6,6},{12,12,12}}
1/3/2001 {{9,9,9},{18,18,18}}
1/4/2001 {{12,12,12},{24,24,24}}
1/5/2001 {{15,15,15},{30,30,30}}
The flow definition creates a new dimension by dividing the contents of the array elements in Rate by
the number of elements in the missing dimension, thereby creating a flow that has the same dimension
as the level. In DISTRIBUTETOFRONT, the flow function creates a new dimension in front of the
existing dimensions (as opposed to DISTRIBUTE, which creates new dimensions behind the existing).
The contents of the flow is added to the corresponding element in Level.
The model produces the following time series (for the five first time steps).
Time Level
1/1/2001 {{5,10,15},{5,10,15}}
1/2/2001 {{10,20,30},{10,20,30}}
1/3/2001 {{15,30,45},{15,30,45}}
1/4/2001 {{20,40,60},{20,40,60}}
1/5/2001 {{25,50,75},{25,50,75}}
- 256 -
different dimensions.
The flow definition first creates the sum of all the array elements in Rate, and then distributes them
evenly over all the array elements in Level.
The model produces the following time series (for the five first time steps).
Note! You have to enter the flow definition above, since Studio is unable to create this flow
definition automatically.
Time Level
1/1/2001 {{0,0},{0,0},{0,0},{0,0}}
1/2/2001 {{10,10},{10,10},{10,10},{10,10}}
1/3/2001 {{20,20},{20,20},{20,20},{20,20}}
1/4/2001 {{30,30},{30,30},{30,30},{30,30}}
1/5/2001 {{40,40},{40,40},{40,40},{40,40}}
The flow definition adds a zero element in front of the existing elements in Rate to create a flow with
the same dimension as Level.
Time Level
1/1/2001 {0,0,0,0}
1/2/2001 {0,1,2,3}
{0,2,4,6}
- 257 -
1/3/2001
1/4/2001 {0,3,6,9}
1/5/2001 {0,4,8,12}
The flow definition appends a zero element at the end of the existing elements in Rate to create a flow
with the same dimension as Level.
Time Level
1/1/2001 {0,0,0,0}
1/2/2001 {1,2,3,0}
1/3/2001 {2,4,6,0}
1/4/2001 {3,6,9,0}
1/5/2001 {4,8,12,0}
The flow definition appends zero elements at the end of the existing elements in Rate in all
dimensions to create a flow with the same dimension as Level.
Time Level
- 258 -
1/1/2001 {{0,0,0},{0,0,0},{0,0,0}}
1/2/2001 {{1,2,0},{3,4,0},{0,0,0}}
1/3/2001 {{2,4,0},{6,8,0},{0,0,0}}
1/4/2001 {{3,6,0},{8,12,0},{0,0,0}}
1/5/2001 {{4,8,0},{12,16,0},{0,0,0}}
The flow definition lets the element from Input flow into the corresponding element in Container.
The difference in the dimension, the elements 2..10, are replaced by 0. The flow rate 'In Transit'
empties the contents of elements 1..9 from Container. The difference in the dimension, the element
10..10, is replaced by 0 on the outflow. On the inflow, however, a preceding 0 is added to the
array. Thereby, the contents of elements 1..9 are shifted to the elements 2..10 by the flow
controlled by 'In Transit'. Finally, the last outflow, controlled by Output, empties element 10 from
Container. The missing elements in the dimension, elements 1..9, are replaced by 0.
The table below shows the results from the simulation for the first 11 simulation steps.
Note! Since the dimensions for Input is 1..1 and Output is 10..10, the variables are
considered arrays by Studio.
- 259 -
1/3/2001 {1}da^-1 {1,1,0,0,0,0,0,0,0,0} {1,0,0,0,0,0,0,0,0}da^-1 {0}da^-1
1/4/2001 {1}da^-1 {1,1,1,0,0,0,0,0,0,0} {1,1,0,0,0,0,0,0,0}da^-1 {0}da^-1
1/5/2001 {1}da^-1 {1,1,1,1,0,0,0,0,0,0} {1,1,1,0,0,0,0,0,0}da^-1 {0}da^-1
1/6/2001 {1}da^-1 {1,1,1,1,1,0,0,0,0,0} {1,1,1,1,0,0,0,0,0}da^-1 {0}da^-1
1/7/2001 {1}da^-1 {1,1,1,1,1,1,0,0,0,0} {1,1,1,1,1,0,0,0,0}da^-1 {0}da^-1
1/8/2001 {1}da^-1 {1,1,1,1,1,1,1,0,0,0} {1,1,1,1,1,1,0,0,0}da^-1 {0}da^-1
1/9/2001 {1}da^-1 {1,1,1,1,1,1,1,1,0,0} {1,1,1,1,1,1,1,0,0}da^-1 {0}da^-1
1/10/2001 {1}da^-1 {1,1,1,1,1,1,1,1,1,0} {1,1,1,1,1,1,1,1,0}da^-1 {0}da^-1
1/11/2001 {1}da^-1 {1,1,1,1,1,1,1,1,1,1} {1,1,1,1,1,1,1,1,1}da^-1 {1}da^-1
One of the strengths in Studio is that you can create feedback loops. However, these feedback loops
must be delayed, so that they affect the origin of the loop at the start of the next time step. A normal,
valid feedback loop is shown below.
This feedback loop is valid since it incorporates a time delay using a flow into a level.
It is not allowed to create feedback loops, or circular references, between auxiliaries and constants,
however. If a structure of auxiliaries are mutually dependent on each other, Studio would not be able
to determine where to start when calculating the values of the variables. When Studio detects such
circular definitions, it will mark the links and auxiliaries in the diagram to make it easier for you to
identify them. The figure below illustrates an illegal circular loop in Studio.
This circular loop is invalid since it only includes auxiliaries. Such a structure would cause an infinite
loop in the simulation engine. To help you identify the circular references, the links and variables will
be marked by question (?) marks in the diagram.
In some cases, Studio will be unable to recognize circular references. This happens when one of the
variables involved in the loop has explicit definitions for Type, Unit, and Dimension. Given the
structure above, if one of the variables is defined explicitly with regards to either Type, Unit, or
Dimension (it is sufficient to uncheck the Auto check box in front of the boxes), the structure will
appear well-defined in the diagram. However, when you start the simulation, Studio will not be able
- 260 -
to evaluate any of the variables, and they will all return the value of NAN (Not a Number). This
situation is shown below.
If the type, unit, and dimension are explicitly defined for one of the variables in the loop, then Studio
will be unable to detect the circular references. However, the values of the variables will be
impossible to determine, and will therefore be NAN (Not a Number). This will appear as a ? (question
mark) in the variables' values (here presented using auto reports).
If you suspect that there might exist circular references in your model, you should go through the
variables that are not calculated correctly (with ? as their values), and set at least one of the properties
Type, Unit, or Dimension to Auto. This will uncover any circular references present in your model, as
explained above.
The Function Wizard allows you to easily insert function expressions into your definition equations.
The Wizard is easily available on the Definition property page in the Properties dialog box.
Apart from the operators, the Function Wizard contains all the available functions in Studio. When
you have selected a function in the alphabetical list - you can select a function category to narrow the
list - a list of all the functions parameters is shown. Additional information, such as a description and
list of valid data types for the parameters, are present in the wizard, making it easy for you to create
valid function expressions. For some functions, the wizard also contains a graph view that facilitates
graphical data input.
When you work in the Function Wizard, you will see the value produced by the expression as you
define it. You will also see the error messages (if any) that is produced by the simulation engine. This
is a great help when creating valid function expressions.
The table below explains the various abbreviations and codes in the parameter list.
Sign Description
L The parameter must be a LOGICAL.
I The parameter must be an INTEGER.
R The parameter must be a REAL (or INTEGER).
C The parameter must be a COMPLEX.
A The parameter can be of any type.
<> The parameter is required.
[] The parameter is optional.
- 261 -
About Value Formatting
Values shown in controls and auto reports are automatically formatted using the number of decimals
specified in Regional Settings (or Options) on your computer (the default setting is 2).
Although this formatting is performed automatically, you can still control the appearance of values in
your models. You can achieve this by using units that match the value range you wish to display.
Consider the examples below, which expresses two lengths using two different length units. The first
value is the unformatted value, the second is the automatically formatted value shown in Studio (using
the default setting of 2 decimals). The example requires that the unit mm is defined in Global Units
as specified below.
You should always try to use units that best reflect the value range of the variable.
Tip! You can still view the unformatted value of the variable by hovering the mouse pointer
over the variable until a tool tip appears. The value appearing in the tool tip is unformatted.
Tip! You can always override the automatically generated unit for a variable by specifying a
unit in the Unit box of the Definition property page. The only requirement is that the two units
are compatible.
Flow equations that are generated automatically by Studio will get an automatic comment added in
the Flows box of the Definition property page. Once you have edited the flow definition, the comment
will disappear, and you are not allowed to add your own.
Note! All characters that occur between two '//'s or between '//' and the end of the line will be
ignored when Studio compiles the equations. Make sure that your comments don't interfere with
the definition equations!
- 262 -
Define a Variable on the Definition Property Page
1. Select the variable and click Properties.
2. Click the Definition tab on the Property pages.
3. Enter the definition text in the Definition edit box.
4. Enter the unit definition in the Unit edit field. You can either enter a single unit or a unit
expression.
5. Enter the dimension definition in the Dimensions edit box.
6. Click OK to accept the definition and return to the diagram, or click Apply to make the changes
and remain on the Definition Property page.
Tip! Other variables can be used as parameters in your definition. To view the value of
individual variables in the definition, simply point to it, and a tool tip containing the variable's
value will appear:
If you are defining a level, you can inspect the level's flow definitions by clicking Flows tab above the
Definition box.
Note! The example below assumes that the unit m (meter) is added to Global Units. The unit is
available on the Add Standard Units when you right-click in the view.
3. Enter a new variable definition or edit the old one. You can edit the name of the variable in the
same operation (type Variable name=variable definition):
4. Press Enter or click elsewhere in the diagram to finish the edit operation. The definition text
now disappears and only the name is shown.
Tip! When editing definitions in the name box of the variable, you can use soft line breaks to
format the definition in the same way you would in the Definition box on the property pages. To
create line shifts, hit CTRL+ENTER.
- 263 -
Define a Variable in the Equations View
You can also define variables in the Equations View, which is located under the Simulation in the
Project Window. There are two ways of defining variables in this view.
To define the variable, and in addition have the possibility to set type, unit, and dimensions explicitly:
1. Locate the variable you wish to define in the list.
2. Double-click it, or right-click it and select Properties on the shortcut menu.
3. Enter the variable definitions in the Definition property page.
4. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.
To define the variable using only the definition expression:
1. Expand the items under the variable by clicking Expand.
2. Hit F2 to edit the definition.
3. Enter the new variable definition, and hit Enter to save the changes.
You can change a variable into a different variable type. There are several ways of doing this.
! In the Details Window, right-click the variable, and select the new variable type on the shortcut
menu.
! Right-click the variable in either the Constructor Diagram or the Details Window, and select
Properties on the popup menu. On the Definition property page, select the new variable type in
the Variable Type box.
Note! You cannot change a level into an auxiliary or a constant if it is connected to a flow!
Studio will automatically create flow definitions based on the dimensions of the flows that are
connected to the level. You are, however, free to change these flow definitions at any time.
- 264 -
3. Expand the subitems under the level item by clicking Expand. The flow definitions will
appear.
4. Select the flow definition to edit.
5. Hit F2 to edit the definition
If you wish to let Studio automatically define your flows again:
! In the Details Window, right-click the flow, and select Automatic on the shortcut menu.
! On the level's definition property page, select Flows, and enter an empty string for the flow
definition you wish Studio to calculate.
When creating flow definitions, you can use the different flow functions available in Studio. You
must also observe that the unit of the flow rate that controls the flow has the right unit. For continuous
flows, the unit should be compatible with the unit of the level divided by a time unit. If, say, the level
has the unit 'm', then the flow rate should have a unit of 'm' divided by a time unit. In this example, the
flow rate could have the unit 'm/s' or similar. For discrete flows, the unit of the flow rate should be
compatible with the unit of the level. Given the example above, both units should be 'm'.
There are several ways in which you can format your variable definitions. By splitting the definition
into several lines and indenting them, you can make it a lot easier to read for others (including
yourself, obviously).
! To indent your line hit CTRL+I or Tab.
! To add comments to your definition, enclose them in '//'. If the comment lasts for the rest of the
line, then you don't need to include the trailing '//'.
The example below shows how a definition including several FOR and IF functions can be made a lot
more readable by using indentation and comments.
FOR(i=..,j=.. |
IF(i<=ELEMCOUNT(R[*,1]),
IF(j<=ELEMCOUNT(R[1,*]),
LOOKUP(LOOKUP(R,j),i),
0<<unitR>>
), // End IF
0<<unitR>>
) // End IF
) // End FOR
- 265 -
1. On the Definition property page, click the Function Wizard button to launch the Function
Wizard.
2. Select a function in the list on the left and the parameters you need to fill in will automatically
appear on the right side of the wizard.
3. Define the input parameters according to their requirements.
4. Click OK to insert the function expression into the Definition text field.
5. Click OK to save the changes, or Apply to save the changes without closing the property page.
The Function Wizard contains a lot of useful information when you are defining a function
expression. The accepted input type is indicated to the right of the parameter field, and a short
description for each parameter is provided at the bottom of the wizard.
You can display already defined ranges and insert them into the definition of a variable.
1. Select the variable and click Properties.
2. Click the Definition tab, and select the Dimensions box. All ranges defined in the model will now
appear in the multi-function box.
3. Double-click a range in the list to insert it into the Dimensions box.
Tip! All the dimension definitions that have been previously used in the model, will be available
in the dropdown list of the Dimensions box.
Note! The Linked Variables list contains the variables currently linked to the variable in the
Constructor diagram, whereas the All Variables list contains all the variables in the model.
(Required Input implies that if a linked variable is not used in the definition, an inconsistency
will appear in the diagram.)
- 266 -
Set Array Dimensions from the Definition Property Page
When you are working with arrays, you can allow Studio to automatically detect the dimension of
your arrays, or you can explicitly define it yourself. If you use automatic detection, Studio will define
the dimensions using numeric subranges, whereas you can use range definitions when you define the
dimensions yourself.
To automatically detect the dimensions:
1. Select one or more variables you want to define as arrays.
2. Click Properties, and click the Definition tab.
3. Select Auto for Dimensions.
4. Click OK to save the changes, or Apply to save the changes without exiting the property page.
To manually define the dimensions:
1. Select one or more variables that you want to define as arrays.
2. Click Properties, and click the Definition tab.
3. Type or select the dimensions of the variable in the Dimensions box. Double-click a range in the
list at the bottom of the property page to insert the selected range in the expression. You can use
both numeric subranges and named ranges when defining the dimension.
4. Click OK to save the changes, or Apply to save the changes without exiting the property page.
Note! Named ranges must be defined in the Local Ranges or Global Ranges view, available in
the Project Window.
You can allow Studio to automatically detect the unit of the variable, or you can explicitly define it
yourself.
Note! You must define the units in either the Global Units or Local Units view, before you can
use them in your model.
- 267 -
Note! Normally you would enter the unit of measurement for constants and levels only and let
Studio detect the units for all computed variables that depend on these. When you wish to
explicitly assign the unit of measurement, it is important that the unit you select is compatible
with the unit computed from the variable's definition.
The data type of a variable can be changed manually, or Studio can automatically detect it based on
the definition of the variable. There are four data types in Studio: LOGICAL, INTEGER, REAL, and
COMPLEX.
To automatically detect the data type for a variable:
1. Select the variable in either the Constructor Diagram or the Details Window, and click
Properties.
2. Select Auto for Type.
3. Click OK to save the changes or Apply to save the changes without exiting the property page.
To manually select the data type for a variable:
1. Select the variable in either the Constructor Diagram or the Details Window, and click
Properties.
2. Select the data type from the list in Type.
3. Click OK to save the changes or Apply to save the changes without exiting the property page.
Note! Be cautious when changing the data type of a variable, as it can lead to inconsistencies
in your model!
You can let the Function Wizard guide you through the process of inserting function expressions in
the variable that you are defining.
1. Click a variable and select Properties on the toolbar.
2. Click the Definition tab and click Function Wizard (located directly below the Definition
box).
3. Under Function Category, select a category of functions. All the available functions of this
category are listed under Function Name.
4. Select the function you want to use. An explanation of each function is shown beneath the list. In
addition, all the parameters of a function are shown.
5. Define each parameter in the appropriate definition field. When a parameter is selected, a
description is shown beneath the list.
6. Click OK to enter the function expression into the variable definition.
Tip! Please refer to the help system for more information about the functions available in
Constructor.
- 268 -
View the Current Value of a Variable
! Equations view: You can view the value of any variable by expanding the variable in the
Equations View.
! Details Window: The value of a variable appears next to its name.
You can use the Documentation property page to document the variables in your model. You can also
attach notes to them.
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. Click the Documentation tab, and use the Documentation and Notes boxes to document the
variable.
Tip! Using the Documentation property page to document your model makes it easier for
others to understand your model.
The Definition box on the Definition property page features syntax highlighting and coloring as you
enter your definitions. In addition, parenthesis are matched making it easier to keep track with your
function expressions.
You can specify your own colors for the syntax colors, should you wish to. In addition, you can
specify the font and font size used in the box, as well as specify the appearance of function names.
Note! You cannot change the formatting used in the Definition box while you are editing a
definition due to the automatic syntax checking that Studio performs while you work. If you
have started editing the definition, click Apply to save the changes first, and then proceed with
the steps below.
- 269 -
To customize the appearance of the definitions:
1. Right-click inside the definition box, and select Options… on the shortcut menu.
2. To change color for a syntax element, select the element under Element, and select a new color
under Color.
3. To change the appearance of function names, select the desired option under Function Names.
There are three options available:
! Uppercase (ex: DELAYPPL)
4. Specify the font and font size you prefer under Font and Size.
5. When you're finished, click OK to save the changes.
Studio introduces hierarchical structures to simulation models - the ability to create submodels within
your model. The most striking advantage is that you can divide your simulation model into smaller
sections, each contained within its own sub-model. Your main model will connect the various
submodels and only contain the variables that are unique to the "top-layer" of the model.
- 270 -
Note! You can only access variables on level up or down in the hierarchy. Thus, a child
variable may only access sibling variables of their parents, or child variables of their siblings.
Variables that are made public are tagged with a green dot. These variables can be accessed from
outside the model, and they can themselves access variables at a higher level in the hierarchy.
The variables K and Y in the submodel M1 are public. Thus, the variable A can use M1.K in its
definition. Likewise, the variables Y is allowed to use the variable D in its definition.
The variable B refers to the variable L in its definition, but since L is not public, the reference is illegal
and B is undefined. The same is the case for X, which refers to C outside the model without being
public. This results in an invalid variable reference. To make the definitions of B and X valid, you
must make the variables L and X inside M1 public, as shown below.
- 271 -
By defining both L and X as public variables, all the definitions in the model becomes valid.
The child variables of an auxiliary, constant, or level cannot be made public. They can access
variables on a higher level of the hierarchy, but cannot themselves be accessed by such variables.
As you can see in the figure, the child variables of K, G and X can be defined by the means of K's
sibling variables. However, the variable A, which is a sibling of K, cannot be defined by referring to
the child variables of K.
A simple component implementing the payroll tax and similar amounts to be deducted with given
periods.
When the component is copied (by drag and drop, for example) into another model diagram, it will
become a submodel. The variables that have defined a transfer direction, will automatically become
public, as shown below. You can thereafter define them using any variable on the parent level.
- 272 -
When a component is copied to a model as a submodel, all variables that have a defined transfer
direction (in or out) will automatically be converted to public variables.
Hierarchical Syntax
The discussion below shows some very simple examples of how to refer to variables at different
levels of the model hierarchy. You should keep in mind that each submodel has its own "name space",
making it possible to use the same variable name in many different submodels. Thus, it is extremely
important that you follow the rules for referring to variables very strictly, otherwise you can easily
refer to a variable in the wrong submodel!
Note! You can only refer to variables one level above or below the variable you are defining!
Consider the example below, where the submodel M1 contains two child variables. The simple model
and its definitions are shown below.
const A = 10
aux X = 2*A
- 273 -
Consider the model shown below. A new variable named F on the parent's level and a new child
variable named Y inside the submodel are added. Y is also made public on the shortcut menu (or on
the Advanced property page in the Properties dialog box).
A, X, and Y are child variables of M1, while F is a sibling of M1. Notice the green dot on Y that
indicates that the variable is made public.
To define Y like it's parent's sibling F times A, we define it using the Parent~ prefix, like this:
const F = 10
aux Y = A*Parent~F
Again, consider the simple example below. A new auxiliary is added, named K.
A, X, and Y are child variables of M1, while F and K are siblings of M1. Y is Public.
We will define K as F*Y. However, since Y is a child of M1, we must use the syntax explained
above, like this:
aux K = F * M1.Y
- 274 -
A more complex hierarchical model.
The table below shows how the various variables can refer to other variables in the hierarchy. Keep in
mind that you can only refer to variables one level above or below the variable you are defining. In
this example no variables have the same name, to make it easier to analyze the syntax. When you
create your own models and submodels, a name can be used once on each level.
When working with hierarchical public child levels in submodels, the flows will usually come from
outside the submodel itself. When you are creating the submodel - especially when implementing the
submodel as a component that you would wish to make as general as possible - you cannot know how
many flows are connected to the level (since these can be added to a public level after you finished
the submodel itself).
To enable you to access the total sum of the in- and outflows for a level, Studio offers the option to
turn on Monitored Flows for any level. There are six flow types that you can monitor independently
from each other. The flow type is dependent of the integration order selected for the flow rate that
controls the flow. The value of these are made available as public child variables within the level
itself.
! Inflows: The sum of all continuous flows into the level. Can be accessed through the
variable .inflows.
! Outflows: The sum of all continuous flows out of the level. Can be accessed through the
variable .outflows.
! Zero Order Inflows: The sum of all flows into the level controlled by zero order flow rates. Can
be accessed through the variable .zo_inflows.
! Zero Order Outflows: The sum of all flows out of the level controlled by zero order flow rates.
Can be accessed through the variable .zo_outflows.
- 275 -
! Zero Order Immediate Inflows: The sum of all flows into the level controlled by zero order
immediate flow rates. Can be accessed through the variable .zoi_inflows.
! Zero Order Immediate Outflows: The sum of all flows out of the level controlled by zero order
immediate flow rates. Can be accessed through the variable .zoi_outflows.
Although child variables of a level cannot be public, the generated monitor flow child variables can
nevertheless be accessed from any sibling variable of their parent level.
We have presented a few examples below of how to implement hierarchical models. These models are
presented with their Constructor diagrams, to make them easier to understand.
The conveyor
A conveyor carries quantities, taking input at one end and delivering output at the other end with a
given time delay. Examples of conveyors are moving side walks, conveyor belts (hence the name),
and other processes that take a fixed amount of time.
The submodel below shows how a conveyor may be implemented using the DELAYPPL function.
The conveyor submodel. The public variables are marked with a cross in the upper right corner.
When the submodel is used, a flow is connected directly to the submodel and into the Contents level.
By monitoring the inflows of the level and accessing the total value of the inflows, any number of
flows may be connected in the main model to the conveyor submodel. The value of the inflows can be
accessed through the Contents.inflows child variable.
The variable definitions of this submodel are presented below. Note that all the input is coming from
outside the submodel, including units and dimensions. By allowing the interface variables to import
these properties, the submodel can be kept generic and can be used anywhere a conveyor is needed.
- 276 -
level Contents = Initial
To allow variables outside to be used in the definition of the Delay Time, Initial, and Contents
variables, all of them are defined as Public. Similarly, to be able to connect the flow controlled by
Output to a level outside the submodel, Output is also defined as Public.. As you can see in the
diagram above, this is indicated by a small cross in the upper right corner of the variable symbol.
Tip! When the two variables Initial and Time in Conveyor are made public, the modeler can
control these properties without having to open the submodels diagram.
The diagram below shows how you can use the submodel in the parent model. Connect the flow
controlled by Input to the submodel, and Studio will automatically connect it to the Conveyor level
(since it is the only public level available in the submodel). Links are drawn from the two variables
Time in Conveyor and Initial Amount in Conveyor and to the submodel. When the links are created, a
dialog box allows you to easily use them to define the public child variables Delay Time and Initial.
Finally, you can include the public child variable Output in the parent diagram, and connect the flow
that is automatically created to a any compatible level. The child relationship between the submodel
Conveyor and the public child variable Output is shown by a straight satellite line.
If you need to access the contents of the conveyor in your simulation, you can draw a link from the
submodel to the variable in question, and define it with a reference to Conveyor.Contents. Similarly, if
you need to create a parameter for it, you can create a parameter with Conveyor.Contents as the value
source.
- 277 -
An implementation of a submodel for sorting, processing, and resorting an array.
The four variables Sort Input, Sorted Array, Processed Array and Sort Output are defined as public
variables, since they will be used to provide input and output from the submodel. To view equations
for the submodel, please refer to the documentation of the VBFUNCTION.
When the submodel is used in the parent diagram, you can decide yourself whether you want to link
directly to the submodel, or if you want to include the public variables in the parent diagram. The
following diagram shows two different scenarios. In the first diagram, all the public variables are
included in the parent diagram. In this case the links from the surrounding model should be connected
directly to the included child variables.
The submodel used in a parent diagram. All the public auxiliaries are included in the diagram,
making it easy to see the variable connections between the main model and the submodel.
The Calculation submodel is another submodel that performs some actions on the sorted array from
the Array Sort submodel. In this diagram, the only variables belonging to the parent diagram are the
auxiliaries Array and Array 2, and the submodels Array Sort and Calculation. The other variables are
child variables that are included in the parent diagram.
An alternative diagram is shown below, where the child variables have been left out of the parent
diagram. In this diagram the variable to variable connections are missing, and the diagram only
indicates that information flows between the two submodels Calculation and Array Sort, and that the
Array variable provides input to the submodel, and that the Array 2 variable receives information
from Array Sort.
- 278 -
The submodel used in a parent diagram. None of the public auxiliaries are included in the diagram,
hiding the implementation of the submodels completely.
The Account submodel will calculate the running interest, and add the interest to the account at
regular intervals. The user can specify the Opening Balance, and the Period and Rate for interest
calculation.
The variable definitions are shown below.
- 279 -
// The flow rate controls when the 'Accumulated Interest' is
// emptied into Balance. In the last parameter of the IF function,
// 0 * 'Accumulated Interest' is used to define the parameter
// with the same unit as the second parameter.
When using the submodel in the parent diagram, you can connect any number of incoming flows to
the submodel, and they will all connect directly to Balance (provided their unit is compatible).
Likewise, any number of outgoing flows can be drawn from the submodel.
To define the three input parameters of the submodel, you can include them in the parent diagram, as
shown in the illustration below. By defining them by the appropriate values and units, the Account
submodel will be properly initialized.
Simply draw flows in and out of the submodel to connect the appropriate inputs and outputs to the
Account.
If a public level is included in the parent diagram, any flows that run to or from it must be connected
to the included child level rather than to the submodel itself.
- 280 -
Work with the Equations View
The Equations View allows you to create your model without using any diagrams at all. You can
create, delete, and define variables.
The Equations View always displays the entire structure of your model. It is unaffected by
operations in the diagrams that do not alter this structure, for instance excluding variables and creating
snapshots.
The columns of the Equations View allows you to view and edit the most important properties of a
variable in a convenient way. If your model contains child variables, these can be shown below their
parents as a tree view in the Name column. You can also use the columns to group the variables to
make it easier to navigate in the list of variables. You can hide and display columns and sort them.
The Equations View allows you to modify and/or view the following properties: Name,
Dimensions, Unit, Type, Definition, Value, Transfer Direction, Documentation, Note, Reservoir,
Modify Time, Create Time.
Tip! Working in the Equations View and in the Details Window are equal operations.
Tip! You can drag the variable from the Equations View and onto open diagram (that belongs
to the component) to include it in the diagram.
- 281 -
Create a Link in the Equations View
There is no Create Link command in the Equations View. The link in a Constructor diagram is
merely a visual representation of the fact that one variable (at the end of the link) is defined by
another variable (at the start of the link).
In the Equations View, this kind of dependency is created by incorporating one variable in the
definition of another.
The variable 'Interest' depends on two other variables: 'Balance' and 'Interest_Rate'.
The dependency of the variable 'Interest' on 'Balance' and 'Interest_Rate' in the illustration above
corresponds to information links going into 'Interest'.
Tip! If the variable name contains a space, such as Interest Rate, remember to enclose
the name in apostrophes ('), as in 'Interest Rate'.
Define a Variable
A variable that is undefined - either because it is newly created or for any other reason lacks a valid
definition - will be marked with a red circle in the Equations View.
1. Locate the variable in the list.
2. Select the Definition column.
3. If the field is not automatically opened for editing, hit F2. The field will be automatically opened
for editing if you select is using the mouse.
4. Enter the new variable definition, and hit Enter to save the changes.
Alternatively, you can click Properties or Alt-Enter, and define the variable in the Properties
dialog box.
Tip! You can include the unit of measurement in the definition if you wish to. You enter the unit
using the following syntax: value <<unit>>.
You can create flows to and from a level directly in the Equations View.
1. Right-click the level that you want to create a flow to, and select Add Flow on the shortcut menu.
2. A flow and a rate variable is created. Define the rate variable to determine the flow. Use the same
procedure as when defining an auxiliary variable.
3. The new flow is by default an inflow. You can reverse it on its shortcut menu.
You can also modify the flow definition, if you wish to:
- 282 -
1. Expand the subitems under the level.
2. Select the flow definition you wish to change.
3. Hit F2 to edit the flow definition.
4. Enter the new flow definition, and hit Enter to save the changes.
Note! If the flow is present in a diagram, both the flow and level will be shown with '#' (hash)
marks to indicate that the diagram is no longer consistent. To fix this, delete the flow, add a
new in the opposite direction, and reconnect the flow rate to the valve.
You are allowed to change the type of a variable, for example change an auxiliary into a level. Certain
restrictions apply to this operation. You are not allowed to change a level into an auxiliary if flows are
connected to it.
To change the type of a variable:
1. Right-click the variable you want to change, and select the new variable type on the shortcut
menu.
or
1. Right-click the variable you want to change, and select Properties on the shortcut menu.
2. On the Definition property page, select the variable type under Variable Type.
3. Click OK to save the changes, or click Apply to save the changes without exiting the dialog box.
Note! To change a level into a reservoir, you must change the level's integration settings
available on the Integration property page.
Note! If you delete a variable (submodel) that has diagrams, you cannot undo the deletion! The
deleted variable, all its child variables, and all its diagrams will be lost.
1. Select the variable and hit Del, or right-click it and select Delete on the shortcut menu.
The variable is removed from the model itself, and will therefore disappear from all the diagrams it
previously was included in.
Note! If you delete a variable, you may render other variable's definitions invalid!
- 283 -
Note! If the variable you delete contains child variables, these child variables will also be
deleted.
- 284 -
Work with Ranges and Index Variables
Index variables
Index variables are also defined in the Ranges view. They are useful for different purposes. First,
index variables allow you to select elements to view in a control. By connecting the index variable to
a switch control, you can easily change the value being displayed in another control, for example a
time graph. Second, index variables can be used in the FOR function, to declare the dimension part.
Types of Ranges
There are three types of ranges in Studio: Enumerated ranges, and enumerated and numerical
subranges.
! An enumerated range is a list of enumerations by which you refer to the various array elements.
An example is the named range 'Population Groups', defined as 'Born Females,
Young Females, Adult Females, Old Females, Born Males, Young
- 285 -
Males, Adult Males, Old Males'. When you use this range to define an array, you can
refer to the elements of the array using these enumerations rather than index numbers. This is a
highly useful way of making your model readable and easy to understand.
! an enumerated subrange is a subset of an enumeration. When you define an enumerated
subrange, you must specify the lower and upper elements of an existing enumerated range. The
subrange will then contain the elements of the enumerated range between these borders. Given the
example above, we can create one subrange Females defined as 'Born Females'..'Old
Females', and one subrange Males defined as 'Born Males'..'Old Males'. The first
subrange will contain all elements containing females, while the other will contain all elements
containing males.
! A numerical subrange is similar to an enumerated range, with the exception that the numerical
subrange is actually a subset of the range of all integers. To define it, you specify the lower and
upper integer to use as range elements. The numerical subrange defined as 1..5 will contain five
elements, indexed from 1 to 5.
Note! When renaming enumeration element names, be sure to use the Rename Elements
command available on the shortcut menu of the range. Changing the names of elements directly
in the Property Page or definition text will redefine rather than rename elements!
Index variables can be used to access or define various elements of an array. Index variables can
either be defined locally (within the FOR function) or in the Global or Local Ranges View. Only index
variables defined in the two ranges views are accessible outside the variable definition itself.
Index variables can be defined in various ways:
! By another range;
! As a numerical subrange;
! As an enumerated subrange.
The index variable definition defines the range of the variable. The value of the index variable itself
will vary within the limits defined. If you use the FOR function, the value of the index variable will
step through the range from the lower to the upper limit automatically for each iteration.
Alternatively, you can use a Switch control to allow the user to select the value of the index variable
manually (see example below).
Since the value of the index variable can be either a numerical or an enumeration element, you must
use the NUMERICAL function when using the index variable within a definition (see example below)
The value of an index variable is independent of the simulation and of other simulations. This means
that even if you have two (or more) windows open of the same simulation, the value of the index
variable will be independent between the two windows. Say, if you have connected the index variable
to a switch control to select parameters to view in a time graph, for example, you can view different
parameters in different windows even if it is the same simulation.
- 286 -
Examples
The following examples uses the range Regions and the index variable Graph Selector, defined as
below. These are both defined in the Global Ranges view:
The top time graph displays the sales for all four regions simultaneously. The lower time graph shows
the sales for each region individually. The switch control allows you to switch between the various
regions easily. (Click the radio buttons to illustrate the functionality.)
- 287 -
Add a Global Range
1. Open the Global Ranges view by double-clicking its entry in the Project Window, or select
Global Ranges under Catalog Windows on the View menu.
2. Right-click somewhere in the white space inside the view, and select Add Range on the
shortcut menu.
3. Hit F2 and enter a name for the new range.
4. Double-click the range to define it on the Range Definition property page.
A newly created range will be undefined until you have defined it on the property page. An undefined
range is indicated in the Global Ranges view with a red question mark. If you use it in a variable
definition before it is properly defined, the variable definition is not accepted as a valid definition.
A local range is available only to the component it is defined in. A local range is prefixed with a
'.' (punctuation mark) when you use it in variable definitions.
To add a local range:
1. Open the Local Ranges view by double-clicking its entry in the Project Window (located under
Component and Simulation), or select Local Ranges under Simulation Windows on the View
menu.
2. Right-click somewhere in the white space inside the view, and select Add Range on the
shortcut menu.
3. Hit F2 and enter a name for the new range.
4. Double-click the range to define it on the Range Definition property page.
Note! You can also create a local index variable in the same way in the Local Ranges view.
An enumerated range specifies a series of named elements that is used as indexes rather but than
- 288 -
integers. The ranges North, East, South, West and Infants, Young, Adults, Old
are examples of enumerated ranges.
The range elements are shown as nodes below the range they belong to in the Ranges View. This
makes it easy to edit their names, rearrange them, and add more range elements to the range.
To create an enumerated range:
1. Right-click inside the Ranges View, and select Add Range on the shortcut menu. Enter a new
name for your new range.
2. Right-click the new range, and select Add Element on the shortcut menu. Enter a name for
your new element.
3. Repeat step 2 for all the elements you wish to add to the range.
You may also enter the range definition directly in the Definition Text box in the Properties dialog
box.
You can rename the range elements of a range in the Global Ranges or Local Ranges view.
1. Open the Global Ranges (or Local Ranges) view.
2. Locate the range containing the range elements you wish to rename, and expand it to display all
the range elements in the list.
3. Select the range element you wish to rename, and hit F2.
4. Enter the new name of the range element, and hit Enter.
Tip! If you wish to quickly rename several elements in one process, you can hit Arrow Down
rather than Enter when you have entered the first name. This will select the name of the next
range element ready for input.
Note! Before you can create an enumerated subrange you must define an enumeration range to
base it on.
- 289 -
2. Select the Subrange option.
3. Select the range that you want to base your subrange on, in the Enumeration box. (Select
<numerical> to create a numerical subrange.)
4. Select the first element of the subrange in the First box.
5. Select the last element of the subrange in the Last box.
6. Click OK to finish the definition, or click Apply to apply the changes without closing the
property page.
You may also enter the range definition directly in the Definition Text box.
A numerical subrange specifies a continuous interval of positive integers used to index arrays. The
subranges 1..5 and 4..20 are examples of numerical subranges.
You use ranges (and named ranges) to specify the dimensions of a variable. Any variable can have
more than one dimension, and you can use ranges for all of the dimension definitions. A variable with
two dimensions, a matrix, will have two dimension definitions, a three-dimensional will have three,
and so on.
Ranges can also be used when defining index variables (for example in the FOR function).
To specify a global range:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition page, enter the range you wish to use in the Dimensions box. All previously used
dimension definitions will be available in the box.
3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
If the variable is defined by an expression that automatically yields an array definition, the
Dimensions box will already have a definition. In this case, the range(s) you specify for the variable
must be compatible with the ranges automatically found by Studio.
- 290 -
Tip! After selecting the Dimensions box, the multi-functional list on the bottom of the property
page will show all the defined named ranges.
You can use ranges to specify the dimensions of a variable. Any variable can have more than one
dimension, and you can use ranges for all of the dimension definitions. A variable with two
dimensions, a matrix, will have two dimension definitions, a three-dimensional will have three, and so
on.
Ranges can also be used when defining index variables (for example in the FOR function).
To specify a local range:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition page, enter the range you wish to use in the Dimensions box. The range must be
prefixed with a punctuation mark (.). All previously used dimension definitions will be available
in the box.
3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Tip! After selecting the Dimensions box, the multi-functional list on the bottom of the property
page will show the named ranges.
You can explicitly select the dimension of a variable expression provided the range you select is
compatible with the calculated range.
To select an explicit range:
1. Double-click the variable, or right-click it and select Properties on the shortcut menu.
2. In the Definition page, enter the range you wish to use in the Dimensions box.
3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Note! If you delete a range or index variable that is in use by variables in your model, this
operation will render the definition of these variables invalid. Furthermore, the definitions of
any other variables that depend on them will also become invalid.
- 291 -
Delete a Local Range or Index Variable
1. Open the Local Ranges view by double-clicking its entry in the Project Window (located under
Component and Simulation), or select Local Ranges under Simulation Windows on the View
menu.
2. Select the range or index variable you wish to delete in the list, and hit DELETE, or right-click it
and select Delete on the shortcut menu.
Note! If you delete a range or an index variable that is in use by variables of your model, this
operation will render the definition of these variables invalid. Furthermore, the definitions of
any other variables that depend on them will also become invalid.
- 292 -
Work with Summary Types
Powersim Studio features two ways of recording parameters. You can either record them using the
highest possible resolution (normally one value per time step, unless the size of the simulation doesn't
permit it), or you can summarize them over a given summary period. When using summary types,
each data point will represent a summary for the past period rather than the exact value at a given
time.
Summary types are available for parameters in controls, dataset variables, and Risk Assessment
variables. The summary types behave identical for all these types of parameters and variables, but the
summary period they use are defined in different ways. While control parameters and Risk
Assessment variables use the major interval as specified in the Report tab of the Simulation Settings
dialog box, dataset variables use the selected reporting period for the dataset.
When you choose to record summaries you can select from different summary types. These are:
! First: Record the variable's value at the start of the summary period.
! Last: Record the variable's value at the end of the summary period.
! Minimum: Record the variable's minimum value over the summary period.
! Maximum: Record the variable's maximum value over the summary period.
! Average: Record the variable's average value over the summary period.
! Accumulated: Record the variable's accumulated value over the summary period. This is identical
to letting the variable control a flow into a level, and then report the level's value.
The figure below illustrates the difference between the various summary types when applied to a
variable showing a linear growth.
- 293 -
The graph shows a linear variable shown with various summary types and a summary period (major
interval) of one quarter.
Note! The First value of the next period equals the Last value of the current period. This can be
seen as the First value being the value at 4/1/2003 00:00, while the Last value is the value as
3/30/2003 24:00.
Note! When using the Accumulated summary type, the unit of the resulting parameter will not
be identical to the variable's unit (except if the integration order of the variable is Zero). It will
always be the variable's unit multiplied with time (if the variable's unit is ppl/da, the
accumulated parameter's unit will be ppl).
Discrete variables are variables where the Integration Order of Controlled Flows is set to either Zero
Order or Zero Order Immediate. Certain limitations apply when using summary types on auxiliaries
with zero order integration order.
Zero Order equals Incoming, and Zero Order Immediate equals Outgoing
An auxiliary that is defined as Zero Order is considered an Incoming value to the current time step.
An auxiliary that is defined as Zero Order Immediate is considered an Outgoing value from the
previous time step. The reason for this is that the calculations of flows controlled by these auxiliaries
are performed at various times during the time step. Zero Order Immediate flows are performed
immediately before the current time step starts, while Zero Order flows are performed at the same
time as other flows in the system; during the time step. This is illustrated below.
- 294 -
Calculating auxiliaries and constants.
Calculating all flows controlled by Zero Order Immediate auxiliaries.
Reporting simulation results for the time step.
Calculating all flows controlled by ordinary or Zero Order auxiliaries.
Discrete flows are calculated at different times depending on their integration setting. Zero Order
flows are calculated along with ordinary flows; at the end of the time step and before values for the
next time step are reported, while Zero Order Immediate flows are calculated at the start of the
current time step before the values of the time step are reported.
When you apply a summary type to a parameter based on a zero order variable, you will notice that
either the Incoming or the Outgoing summary type will produce undefined numbers consistently:
! When using Zero Order integration, Outgoing is always undefined;
! When using Zero Order Immediate integration, Incoming is always undefined.
- 295 -
Summary period: 3 months
Time Case 1 Case 2
1/1/2003 $100 $300
2/1/2003 $100 $0
3/1/2003 $100 $0
Average $300/3 = $100 $300/3 = $100
Summary period: 4 months
Time Case 1 Case 2
1/1/2003 $100 $300
2/1/2003 $100 $0
3/1/2003 $100 $0
4/1/2003 $100 $300
Average $400/4 = $100 $600/4 = $150
If you need to display the average of discrete variables, we suggest you create a simple model
structure to calculate it for you the way you need it to be.
- 296 -
Work with Arrays
Arrays are variables that can hold sets of values rather than single values. Arrays can be used to create
layers in a model, create queues, and model various other behaviors.
The dimensions of the array specifies the size and structure of the array. You can easily create arrays
that match each other by using named ranges and subranges. Named ranges also makes your model
easier to understand.
This chapter assumes that you have a good knowledge on how to create variables and define them.
You will therefore not find step by step instructions here. Instead, you will find examples of variable
definitions, and explanations on how to work with arrays.
An extremely powerful feature of Powersim is the possibility to define indexed variables, or arrays.
One array variable can hold several values, as opposed to an ordinary scalar variable, which holds
only a single value. Each array variable consists of several elements. When linking together several
array variables with the same number of elements in a model, you can depict the model as a stack of
layers. At each layer the variable elements are interconnected. This is illustrated in the figure below.
You may treat the layers as four individual models or, for more advanced use, make connections
between variable elements on different layers of the model.
- 297 -
Using Arrays to Represent Groups of Values
By defining a variable as an array, a group of related values may be represented as one variable. To
demonstrate the power of arrays, imagine a model of a population accumulated into three levels:
Young, Adult, and Old. Using scalar variables, we would need three different levels to represent each
of the age groups. However, since each level represents a group of people in a population, and since
each age group will have similar characteristics and model structures attached to them, all groups can
be represented using a single level with three array elements. In the Constructor diagram, an array
variable is represented by a symbol with a double frame.
The population example can easily be modeled using an array level rather than single levels. An
array will be represented by a double-framed variable symbol.
In the Population example, it would be a good idea to use the named range 'Age Groups' rather
than give the level the dimension 1..3. The reason for this is that you might later want to expand the
population model by new age groups. If you have entered numerical subranges directly into the
definitions, you will have to change these throughout the model. If you, on the other hand, used
named ranges, you could change the definition of the range itself, and the changes would be
immediately recognized throughout the model.
- 298 -
Create Layered Models Using Arrays
Models often contain a lot of identical or almost identical structures. By using arrays, you can model
these structures once and use them as many times as you wish. If you make a business simulator, you
might include work force, capital, production, markets, and finance. It is easy to identify duplicate
structures, such as different kinds of workers, different kinds of capital (for example buildings and
machines), different product lines, different market segments, different accounts payable (for example
marketing expenses, goods, taxes, and wages) and so on.
This layering of models is easily achieved by the use of arrays. You carefully model each structure,
and make sure that it behaves the way you want. When the structure is finished, you simply add one
dimension to each layer in your model. If you want to make a model of four competing companies,
for example, this would involve four similar structures. The main difference consists of parameter
values (constant auxiliaries) and levels. Once a model of one company is developed, you can add
more companies by adding a company dimension to each array variable in the model.
Layering of models gives you two important advantages.
! Maintainability: Changes to an array structure immediately takes effect for all elements of the
array.
! Complexity: Models can sometimes become significantly smaller when using arrays.
! Dimension changes: If you use ranges when creating your models, you can simply redefine the
range in one place, and the change is immediately reflected in all the array variables that uses the
same range.
You can easily create queues using arrays. By creating a flow with as many elements as the delay of
the flow, and then let the array elements flow one element up in the array for each simulation step.
The model shown below illustrates how to model such a queue.
- 299 -
dim Level = 1..10
flow Level = + dt*FillInZeroes(Input)
- dt*SuffixZero('In Transit')
+ dt*PrefixZero('In Transit')
- dt*FillInZeroes(Output)
The flow definition will automatically be inserted based on the dimension of the various variable and
dimension definitions.
The graph below shows the result of the model, when Input is defined as a sine wave.
Array Syntax
Creating Arrays
Arrays are created by listing the elements of the dimension inside '{'and '}' (braces). An array element
can be a literal, function expression, or an array itself. If an array element is an array, then all the
elements must have the same dimension. The syntax is
{Element1, Element2, ..., ElementN)
Dimensions define the structure and number of elements in the array, and can be either subranges
(numerical or enumeration) or named ranges (enumeration ranges, numerical or enumeration
subranges). The named ranges - and also the elements of enumeration subranges - must be defined as
either local or global ranges. You can override the automatic dimension by entering a compatible
range expression for the array manually.
Arrays can also be created by using the FOR and CONCAT functions. Assigning dimensions to a
(scalar) variable definition also creates an array with identical elements.
Indexing Arrays
Arrays are indexed by using the syntax
Array[<index-expression>]
where <index-expression> identifies the elements in the array. The table below summarizes the legal
index expressions, and explains how they work. (A and B denote an integer.)
Index Description
An exact position within a dimension. You can include one integer per dimension.
A
Examples: Array[1], Array[1,1], Array[1,1,1], etc.).
- 300 -
Indexes a range in the array. The elements in the range (including A and B) are returned.
You can include one range per dimension. If the starting or ending point is replaced by
'?' (question mark), the range includes all elements from start or all elements to end,
A..B respectively.
Examples: Array[1..2], Array[1..3,2..4], A[3..?], A[?..3],
etc.).
Indexes the entire dimension. All elements in the dimension are returned. You can include
one '*' per dimension. If the '*' is used at the end of the expression, you can omit it.
* Examples: Array[1,*]=Array[1], Array[*,2..4], Array[*,*,2],
etc.).
Redimensioning Arrays
Arrays can be redimensioned to temporarily change the dimension. The index expression must be
constructed based on the new, temporary dimension. The syntax is
Array[<redimension-expression>:<index-expression>]
where <redimension-expression> identifies the new start end value for the dimension. <index-
expression> follows the syntax described above. The redimension expression can contain be both
numerical or enumeration subranges, as well as named ranges. The redimension expression can also
be open (ending or starting with '?' (question mark).
Examples:
A[1..4:2..?]
A[*,4..6:4]
A[*,?..6:2..4]
Create Arrays
There are two ways of turning a variable into an array. You can enter a variable definition and let
Studio automatically detect the dimension of the array, or you can explicitly set the dimension of the
array yourself. You should note, however, that if you explicitly set the dimension of the array, the
dimension must match the dimension of the variable definition.
Note! When a dimension is defined automatically, it will be defined with a starting point of 1. If
you define an array with the variable definition {26,6,99}, the dimension will be
- 301 -
automatically set to '1..3'.
If the array should contain more than one dimension, then the elements of each dimension must be
enclosed in '{' and '}' (braces). Thus, an array containing two dimensions (a table) can be entered
using the definition below.
The examples have shown how arrays can be built up using literals only. However, the same syntax
can very well be used even if the various elements are function expressions.
aux Variable = 0
dim Variable = 1..2,1..2 // Manually defined
result Variable = {{0,0},{0,0}}
In some cases you might find that the automatically detected dimension is not correct for your use. If
you are performing operations related to other arrays with other dimensions, it can cause trouble. In
this case you can override the automatically detected dimension, as shown below. The example shows
how another variable can index the array we have created.
Note! When you assign dimensions to an array, you must make sure that the dimensions match.
If the automatically detected dimension contains four elements, then the explicitly assigned
dimension must also contain four elements.
Named ranges and subranges can be defined as either global or local ranges. The only difference
between these is that local ranges are referred to with a preceding '.' (punctuation mark). Ranges are
useful because the number of elements within them can be altered later without causing a need to go
through the entire simulation model and change definitions accordingly. To gain the full effect of
ranges, it is therefore important that your model doesn't refer to array elements directly, but use the
named range.
The example below shows how the global range Regions - defined as
'north,south,east,west' - is used to define a variable.
- 302 -
result Variable = {0,0,0,0}
All the dimensions in a dimension definition can be named ranges, as the following example suggests.
It uses the local range 'Age Groups' - defined as '.youth,.adult,.old' - in conjunction
with the Regions range above.
Note! When using names with spaces or other special characters, remember to enclose them in
apostrophes ('). Also, when referring to local ranges, remember the preceding '.' (punctuation
mark) for both range and range elements.
Given the definitions above, a change in the named ranges will automatically be recognized
throughout the model. The arrays will automatically be resized to the new dimensions.
where Element1, ..., are the various array elements. Each element may also be an array. It is
important that all the elements share the same dimensions.
Note! All elements listed within one set of braces must share the exact same dimensions. It is
not sufficient that they have the same number of elements in each dimension.
The definition
aux C = {A, B}
will produce an array with one more dimension than A and B have. A and B must also share the same
dimension. The table below shows a few examples for given A and B.
A B C dim C
3 2 {3,2} 1..2
{3,2} {6,10} {{3,2},{6,10}} 1..2,1..2
{{1,2}, {{5,6}, {{{1,2},{3,4}},{{5,6}, 1..2,1..2,1..2
{3,4}} {7,8}} {7,8}}}
The FOR function offers a convenient way of building arrays, since the function takes the resulting
array's dimensions as input parameters. You can add index variables to the dimension expression in
- 303 -
the first part. Index variables can be used to compute values or to index other arrays. The second part
of the input parameters contains the element definitions. By using the IF function, you can specify
various definitions for various parts of your array.
Note! The resulting dimension for the variable is derived from the expression directly, and
inserted into the Dimension field of the property page. You cannot explicitly assign dimensions
to a variable defined by the FOR function.
The table shows a few examples on how the FOR function can be used to define arrays. In some of the
examples, the index variable i is used to define the array elements. It exists only internally in the FOR
function, and cannot be used outside the function (the expressions F(i=1..3 | 1)*i is not allowed). The
examples use the following range definitions that must be added to your simulation project to make
the examples work:
Note! When referring to local ranges or range elements, a '.' (punctuation mark) must be added
in front of the range or element name.
You can also use the index variable in the FOR function to index an array. The example below
illustrates how a combination of the FOR and IF functions is used to shift the elements of an array A,
defined as {1,2,3,4,5,6,7,8,9,10} (dimension automatically detected to '1..10').
The dimension of the index variable must match the dimension of the array it is used to index. If the
dimensions doesn't match, Studio will regard the variable expression as invalid. If you are sure that
your variable expression handles the index variable correctly, you can use the INDEX function to
index the variable. Thus, instead of using the expression A[i-1] (in which case the dimension of the
index variable will be '0..9', which is outside the dimension of A and therefore will cause an
invalid expression), you can use the expression A[INDEX(i-1)], as shown below.
aux A = {1,2,3,4,5,6,7,8,9,10}
dim A = 1..10
aux B = FOR(i=1..10 | IF(i>1, A[INDEX(i-1)], A[10]))
dim B = 1..10
result B = {10,1,2,3,4,5,6,7,8,9}
- 304 -
Build Arrays Using the CONCAT Function
The CONCAT function - concatenate arrays - can be used to construct arrays. The syntax of the
function is
CONCAT(Input1, Input2, ...)
where Input1, Input2, … must share all but one dimension. The last dimension must be either
open or sequential. The last dimension can, as an example, be '1..1' for Input1, '2..8' for
Input2, '9..11' for Input3, and so on.
Note! A dimension is open only when the array is created immediately, as in the expression
{1,2,3}.
The CONCAT function can be used in conjunction with both the FOR and IF functions, and is thereby
capable of creating the most advanced array expressions.
The example below shows how the CONCAT function is used to concatenate various array
expressions.
Index Arrays
The elements of an array can be accessed by its index value. The index of an array element is relative
to the dimension definition and to the position of the element inside the array. This is illustrated in the
figure below.
The figure illustrates the relationship between the dimensions of an array and the index values of the
array elements.
The array can be indexed by the following syntax:
Array[<index-expression>]
where <index-expression> is the index dimension for the element(s) you wish to index. The
index expression can be an integer (to uniquely identify one array element), a numerical subrange (to
identify two or more array elements), or an '*' (asterisk) (to identify all elements in a dimension). The
dimension of an array that is indexed is reduced by the number of indices that is used.
- 305 -
When indexing arrays, the index expressions refers to the dimensions as they are defined for the
variable. The first index refers to the first dimension, the second to the second dimension, etc. Trailing
'*'s can be omitted, making the expressions A[1,*] and A[1] identical.
Examples
The illustration below demonstrates how a two-dimensional array can be indexed in various ways.
The array, for convenience named Array, is defined as:
Array can be compared to a table, and is presented as such below. The index of the first dimension
is presented in the first column, while the index of the second dimension ('1..5') is presented in
the first row.
1 2 3 4 5
1 48 39 0 42 94
2 69 57 19 51 18
3 8 15 35 63 68
4 97 1 67 45 11
Result: <--Result-->
Dimension: <--Dimensions-->
Note! The two last examples shows how an array can be redimensioned in Studio.
Redimensioning affects the dimensions of the resulting array.
The INDEX function allows you to convert a normal variable into an index variable. This is useful if
you have one variable that computes the array element you need to index, while another variable
contains the array itself. The input parameter for the INDEX function must be an integer (data type). If
the variable you have computed is a real, you can use the INTEGER function to convert it to an integer.
The example below illustrates this use of the INDEX function.
- 306 -
Using INDEX with FOR and IF
The INDEX function can also be used in conjunction with the IF and FOR functions. Studio will not
accept an index variable if its dimension exceeds the dimension of the array it tries to index. By using
the INDEX function instead, you can avoid this dimension matching check. Be aware, however, that
you ensure not to index a value outside the dimension of the array, as this will return '?' (NAN).
The following example shows how the contents of an array can be shifted.
The LOOKUP function allows you to look up values in an array. The LOOKUP function takes the array
as its first parameter, and the index(-es) as its next parameters. This is an alternative to using the
INDEX function. The expression below shows the relationship between LOOKUP and INDEX.
LOOKUP(Array,i,j) = Array[INDEX(i),INDEX(j)]
Note! The variable used as an index variable must be defined with INTEGER as its datatype.
Examples
The table shows a few examples on how to use the LOOKUP function. The dimensions are
automatically found by Studio when you click Apply. The expressions are based on the following
array:
aux A = {{4,1,5},{9,3,8},{2,6,7}}
The integers used as indices in the examples below can be replaced by integer variables.
If an array's dimensions are defined using ranges or subranges, you use the element name rather than
the index number to access each array element.
The advantage of using named ranges and subranges is apparent when you need to resize your model
to accommodate new array elements. If the arrays are defined either automatically or by numerical
subranges directly (e.g. '1..10'), then you have to revisit every array throughout your model to resize
the arrays. However, if they are defined using named ranges, you can change the definition of the
- 307 -
range, and the change will propagate throughout your model. You only have to revisit the boundary
models that contain initialization values for the various elements.
The following examples illustrate how to use named ranges. The example requires the global range
Regions to be defined as north,east,south,west.
Redimension Arrays
Sometimes you might need to give an array new dimensions temporarily. In this case, you can use the
powerful redimensioning syntax in Studio. By adding the new dimension of the array before the index
expression, you can give the array new dimensions that will only be used within the current function
expression. The syntax is shown below.
Array[<redimension-expression>:<index-expression>]
where <redimension-expression> is the new dimension of the array. Be aware that the index
expression must be entered relative to the new dimension of the array. Needless to say, the
redimension expression must have the same number of elements as the dimension of the array you are
indexing. The redimension expression can be open in either end.
Tip! You can also redimension an array using the REDIM function, with the syntax REDIM
(<redim_expression> | Array).
The redimension feature is especially useful when used in conjunction with the CONCAT function.
Since you cannot concatenate arrays that have the same dimensions, you can redimension the arrays
to make it possible to concatenate them.
The example below shows how to redimension and concatenate two arrays with two dimensions each.
In this case you must observe that only one of the dimensions differ from each other.
aux A = {{1,2},{3,4}}
dim A = 1..2,1..2
aux B = {{5,6},{7,8}}
dim B = 1..2,1..2
aux 'Result 1' = CONCAT(A,B[*,3..4:3..4])
= {{1,2,5,6},{3,4,7,8}}
- 308 -
dim 'Result 1' = 1..2, 1..4
aux 'Result 2' = CONCAT(A,B[3..4:3..4])
= {{1,2},{3,4},{5,6},{7,8}}
dim 'Result 2' = 1..4,1..2
- 309 -
About Powersim Controls
Dynamic controls constitute the most convenient means of displaying simulation results and letting
the user control the values of key model variables.
There are several controls available in Constructor. These are highly customizable, and you can
change the appearance to suit your needs. The figure below shows how a time graph control can be
used to display inventory fluctuations over time.
The time series control used to display a time graph of inventory fluctuations over time in two
different inventories.
- 310 -
Using Index Variables in Controls
Index variables can be used to access or define various elements of an array. Index variables are
defined in the Global Ranges or Local Ranges views, and provide a useful measure of
controlling which dimensions in an array is being displayed in your control. Index variables can be
used to index parameters in your controls, allowing a switch control to control the displayed
parameters of a time graph, etc. Using index variables can simplify complex simulation interfaces a
lot!
Tip! You can alter the settings of the various parts of the control by right-clicking them, and
selecting options on the shortcut menu. Alternatively, you can select the object and click
Properties on the toolbar or in the shortcut menu.
Tip! You can change the appearance of a control at any time, even when the simulation is
running.
Move a Control
Index variables are defined in the Global Ranges or Local Ranges views, and provide a useful
measure of controlling which element in an array is being displayed in your control. The index
variable can be used directly as the parameter in the control, allowing you to control the value of the
index variable. Alternatively, it can be used as an indexing variable for another parameter.
The switch, slider, gauge, and table controls allow you to set the value of the index variable directly.
You will be allowed to alter the value of the index variable within the range defined in Global Ranges
- 311 -
or Local Ranges.
You can index arrays using index variables in all controls. This allows you to control which
dimensions of the control's parameter is displayed by altering the value of the index variable in an
input control. The various combinations of indices and relevant index variables will show up in the
Parameter list box on the Parameter property page.
Example
Let's consider an example and see how the Powersim controls can be used to present the various
elements of an array in a time graph by using index variables.
Let's assume that you wish to present the sales of a factory. There are three different products, and
there are four different geographical areas. The sales figures are kept in an array, defined by the
global ranges Regions and Products.
The variable Sales has the dimensions Region, Products, and we wish to display the results for each
geographical region separately. To achieve this, we create an index variable IV_Region, like this:
You should insert a switch control and a time graph control in the diagram. Select IV_Region as the
parameter for the switch control. For the time graph, select the parameters Sales[IV_Region, Bolts],
Sales[IV_Region, Washers], and Sales[IV_Region, Nuts]. The controls will now look something like
this:
The switch control allows you to select which graphs to display in the time graph, by setting the value
of the index variable IV_Regions. (Click the radio buttons to see effects.)
Alternatively, you can display the time graphs as region per product group. To achieve this, create a
new index variable, like this:
By selecting IV_Products as the parameter for the switch control, and Sales[North, IV_Product],
Sales[East, IV_Product], Sales[South, IV_Product], and Sales[West, IV_Product] as the parameters
for the time graph, you can achieve this effect. This is shown below.
- 312 -
The switch control allows you to select which graphs to display in the time graph, by setting the value
of the index variable IV_Product. (Click the radio buttons to see effects.)
Finally, you can have one switch control setting the value for each of the index variables, and thereby
creating a time graph where you can view any combination of the two. To achieve this, you need to
select IV_Region as the parameter for one of the switch controls, IV_Product for the other, and finally
Sales[IV_Region, IV_Product] as the parameter for the time graph. The resulting control complex is
shown below.
The switch control allows you to select which graphs to display in the time graph, by setting the value
of the index variable IV_Product. (Click the radio buttons to see effects.)
Delete a Control
To delete a control:
1. Select the control you wish to delete.
2. Hit Del on the keyboard, or select Delete on the Edit menu.
Powersim Studio allows you to toggle between Design and User mode. While in Design mode you
can alter any objects, move them, resize them, etc., whereas the User mode only allow you to run the
simulation and provide input to the variables using controls.
To toggle between Design and User mode:
1. Click Toggle Design Mode to toggle between the two modes.
- 313 -
The state of the button shows the current mode:
! : When the button is depressed, Studio is in Design mode, and you can edit the diagram freely.
! When the button is not depressed, Studio is in User mode, and you can only interact with the
simulation.
Tip! When the simulation is in User mode, you can right-click a control to show or hide the
parameters. You can also hide graphs in the time graph or chart controls by right-clicking them
and select Hide on the shortcut menu.
- 314 -
Work with Parameters
A control can have two different types of parameters: Active Run Parameters and Reference Data
Parameters. While active run parameters display the current value of the variables at any time,
reference data parameters displays the value that the variables had in a reference, previous simulation
run. Reference parameters thereby offer the capability of comparing the current simulation run to
previous runs.
Summary types allow you to display a summary for a parameter rather than the full time series. You
can select from various types, including minimum, maximum, average and accumulated. The
summary period used differs from control to control.
Most of the controls available in Studio allow you to enter new values for their parameters. However,
if the Permanent option is not selected for the corresponding variables, their initial values will be
restored when the simulation is reset. If you want Studio to remember the values you've entered in
controls between simulation runs, you should define their parameter's corresponding variables as
permanent.
You can also use Index variables as input parameters in Studio. Index variables allow you to select
array elements to view in controls, which means that you can use one control to provide input or
output for several array elements without cluttering the view.
Finally, you can use Control parameters to control the simulation settings. Some of these can only be
read, while some of them can also accept input. Control parameters include run information and time
related parameters.
The active run parameters of a control are the variables from the current run that you want to display
in the control.
To add active run parameters to a control:
1. Drag the variable(s) you wish to display, and drop it on the control. You can drag the variable
from a diagram, from the Details Window, or from the Equations View.
or
1. Select the control you wish to change, and click Properties.
2. Click the Parameters tab in the Properties dialog box.
3. Expand the component's folder in the Value Source list.
4. Select the variables one at a time from the list on the left side, and click Add Parameter to
- 315 -
add them to the parameter list on the right as active run parameters.
5. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Some variables have several dimensions. For these variables, all the possible parameters for a control
will be listed in a treeview in the Parameter property page. You can browse through this treeview to
find the parameters you want to add. Some controls accept only scalar parameters, while others accept
both scalars and vectors. The parameters that cannot be selected will be marked with a small red sign.
Note! For some controls - such as the table control - you might have to perform additional
formatting before the parameters are actually shown in the control.
The reference data parameters of a control are the variables from the selected reference run that you
want to display in the control. Reference data parameters are displayed with a preceding '*' (asterisk)
to distinguish them from active run parameters.
To add reference data parameters to a control:
1. Select the control you wish to change, and click Properties.
2. Click the Parameters tab in the Properties dialog box.
3. Select the variable you wish to add a paraameter from the list on the left side, and click Add
Advanced Parameter. The Add Advanced dialog box will appear.
4. Select the Reference run option, and click OK.
5. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Before you will actually see the reference data parameter in the control, you must first select a
simulation run as the reference data on the Simulation menu. You can choose between previously
stored simulation runs available in your simulation project. When the reference data has been
specified, the reference data parameter will become visible in your control.
A reference data parameter has a preceding '*' (asterisk) to distinguish it from active run parameters.
Reference data parameters enables you to compare results from various simulation runs in an
intuitive and simple way.
Note! Simulation control parameters can only be used in controls that display the current value
of the parameter and that support scalar parameters, such as the Slider, Switch,
Table, and the Gauge controls.
- 316 -
Simulation Control Parameters can be used to access the run count and time information of the current
simulation. The available control parameters are:
! RunCount: Get or set the run count of the simulation settings.
! RunIndex: Get the current run index.
! StartTime: Get or set the start time of the simulation.
! StopTime: Get or set the stop time of the simulation.
! Time: Get the current simulation time.
! Timestep: Get or set the timestep of the simulation.
The two parameters Time and RunIndex are read-only, while you can use the other parameters to view
and change the simulation settings using controls.
Note! Index variable parameters can only be used in controls that display the current value of
the parameter and that support scalar parameters, such as the Slider, Switch, Table,
and the Gauge control.
Index variables are defined in the Global Ranges or Local Ranges views, and provide a useful
measure of controlling which dimensions in an array is being displayed in your control. The index
variable can be used directly as the parameter in the control, allowing you to control the value of the
index variable. Alternatively, it can be used as an indexing variable for another parameter.
To add an index variable parameter to a control:
1. Select the control you wish to change, and click Properties.
2. Click the Parameters tab in the Properties dialog box.
3. Expand the Index Variables node of the Value Source list.
4. Select the index variable you wish to add, and click Add Parameter.
5. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Note! Parameters with summary types can only be displayed in controls with a time axis, such
as the Time Table and the Time Graph.
Both Active run parameters and Reference parameters can utilize summary types. There are six
- 317 -
summary types available: First, Last, Maximum, Minimum, Average, and Accumulated.
To add a parameter with a summary type to the control:
1. Select the control you wish to change, and click Properties.
2. Click the Parameters tab in the Properties dialog box.
3. Expand the components folder in the Value Source list.
4. Select the variable you wish to add, and click Add Advanced Parameter….
5. Select the Summarize over Period option in the Add Advanced dialog box that appears.
6. Select the summary type to use under Summary type.
7. Click OK to add the parameter with the selected summary type.
8. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
When calculating the value of the parameter, a summary period will be used. By default, this
summary period equals the Major Interval defined in the Simulation Settings dialog box. However,
you can also control the summary period for each control individually by changing the Major Interval
of the time axis ( Time Graph) or the Report Interval ( Time Table).
You can control the value domain of a variable directly on the variable itself. If you have set the value
domain for a variable, the control will use this for its value axis as long as you select Auto for the
scaling.
To set the scale of a parameter:
1. Double-click the variable you wish to change, or click Properties.
2. Select the Scale tab in the Properties dialog box.
3. Specify the value domain of the parameter under Minimum and Maximum. Select Auto to allow
Studio to automatically scale the parameter.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
The scaling of a variable doesn't affect the value of the variable, but is used to automatically scale the
value axis of controls that has the variable as its parameter.
- 318 -
Delete on the shortcut menu.
When Powersim Studio is in User mode, you can hide or show parameters in controls easily.
1. Right-click the control, and select the parameter to show or hide (checked parameters are visible)
on the shortcut menu.
If the control is a time graph or chart control you can easily hide a graph:
1. Right-click the graph and select Hide on the shortcut menu.
Note! Studio is in User mode when the Toggle Design Mode button is not depressed.
Note! You can only set new values for constants of levels. Auxiliaries will never accept input
from controls.
- 319 -
A slider bar used in read only mode to indicate the amount accumulated over time in a level.
Tip! By enabling the Permanent option for constants and levels used as input parameters in
controls, you can make Studio remember the value entered by the user even when the
simulation is reset.
- 320 -
Format Controls
The various controls available inside Powersim Studio are very different, but much of the formatting
capabilities are the same between them. Below is a list of topics that explain procedures that are
common to all Powersim controls. For more specialized information on how to use a specific control,
please refer to each individual control.
You can format individual objects within the control - such as time and value axis - by selecting them
and using toolbar buttons, or by right-clicking them and use the shortcut menus. You can also format
them in the Properties dialog box. This is available by clicking Properties on the shortcut menu or
on the toolbar.
If you double-click the control, or select it and then click Properties on the toolbar (or shortcut
menu), you can access all the properties of the control at once.
Axis Formatting
The table below explains the various options when formatting axis.
Major Tick Style
Cross Displays the major ticks as a cross on the axis:
Outside Displays the major ticks on the outside (away from the center of the control)
of the axis:
Inside Displays the major ticks on the inside (toward the center of the control) of the
axis:
None Turns off the major ticks on the axis.
Minor Tick Style
Cross Displays the minor ticks as a cross on the axis:
Outside Displays the minor ticks on the outside (away from the center of the control)
of the axis:
Inside Displays the minor ticks on the inside (toward the center of the control) of the
axis:
None Turns off the minor ticks on the axis.
Axis Position
- 321 -
Auto The axis cross as close as possible to the origin of the coordinate system.
Low Displays the axis on the bottom or right of the control.
High Displays the axis on the left or top of the control.
Tick Label Position
None Turns off the tick labels for the axis.
High Displays the tick labels on the bottom or right of the control.
Low Displays the tick labels on the left or top of the control.
With Axis Displays the tick labels close to the axis.
Unit Label Position (Value Axis only)
None Turns off the unit label for the axis.
Auto Automatically places the unit label based on the orientation and type of value
axis.
At Minimum Displays the unit label at the minimum point of the value axis.
At Maximum Displays the unit label at the maximum point of the value axis.
Along Axis Displays the unit label along the value axis, at the middle of the axis.
With Tick Displays the unit with the tick labels of the value axis.
Labels
You will often experience the need to display parameters with different units in the same control. The
value axis of the controls will in these cases automatically detect the units and display the parameters
in the best way. There are two possible cases, described below.
Note! If the parameter you have added to the control is undefined, the name of the parameter is
followed by (?) in the control's legend.
When the parameters shown in the control have equal or compatible units, the unit of the topmost
- 322 -
parameter is chosen for the value axis. The unit name of the value axis is displayed above the value
axis.
When the parameters shown in the control have incompatible units, the parameters' units are
displayed in the control's legend.
Resize a Control
Format an Axis
There are various axis types available in Studio: Value Axis, Element Axis, and Time Axis. While the
options discussed below are available for all of these axis types, each may have individual options not
discussed below. These will be discussed for each axis type individually.
To change major and minor tick styles:
1. Right-click the axis, and select Major Tick Marks (or Minor Tick Marks) on the shortcut
menu.
2. On the shortcut menu that appears, select the tick style.
To change the axis position:
1. Right-click the time axis, and select Axis Position on the shortcut menu.
2. On the shortcut menu that appears, select the axis position.
To change the tick label position:
1. Double-click the axis, and select the Time Axis tab (alternatively Value Axis or Element Axis).
- 323 -
2. Select the tick label position under Tick Label Position.
3. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Note! All the formatting options are also available on the Time Axis (or alternatively Value
Axis or Element Axis) property page when clicking Properties.
Tip! You can also change the position of the tick labels for the axis, on the axis' property page
when clicking Properties.
Texts in various labels and titles can be oriented in various ways. Most texts available for labels and
titles can be oriented either Horizontal, Downwards, Upwards, and Vertical. Tick labels in axes can
also be oriented in a custom angle (from -90° to 90°).
To format the objects, you must select the object itself, or its parent object, if the object itself is
unavailable for selection (such as tick labels for an axis). All the objects are available if you select the
entire control.
1. Right-click the object (or parent object) whose texts you wish to format, and select Properties
on the shortcut menu.
2. Click the Alignment tab.
3. Select the objects you wish to format in the Properties list.
4. Select the orientation you wish to use under Orientation. Available options are Horizontal,
Downwards, Upwards, and Vertical. For tick labels you can also enter a custom rotation angle by
selecting the Custom option, and then enter the angle under Degrees. Allowed values are from -
90° to 90°.
5. Click Apply to save the changes, or OK to save the changes and close the dialog box.
Time graph control using a time axis with tick labels rotated to -45°.
- 324 -
Show Label for an Axis
1. Right-click the axis, and select Show Label on the shortcut menu.
2. Select the label and edit it if you like.
You can hide the label by right-clicking it and select Hide on the shortcut menu.
You can also change the appearance of the axis label on the Text and Font property pages when
clicking Properties, or by using the Format toolbar.
Tip! You can use the field codes to dynamically update the axis label.
The value axis will use the scale information of the parameter by default, unless you specify another
scale for the axis:
1. Double-click the value axis, or select it and click Properties.
2. Click the Value Axis tab.
3. Under Scale, specify the new Maximum and Minimum values, as well as the Major and Minor
units for the value axis. To let Studio automatically select a value, select the corresponding Auto
option.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
You can change the appearance of each control available in Studio in numerous ways. You can alter
the shape of the control, the interior fill and colors, dash styles and thickness of all the lines, the font
of labels and values, the title, etc. The options vary from control to control.
There are three methods you can use to change the appearance of a control:
! Toolbar buttons: Use the toolbar buttons on the Format toolbar to format the selected control or
object within the control.
! Shortcut menu: Right-click the control or object within the control to access the shortcut menu.
Many formatting options are present on the menu.
! Properties dialog box: Double-click the control or object within the control to access the
Properties dialog box of the control or object (alternatively, click Properties). All the
properties of the object is available here. The Properties dialog box for the control contains all the
properties for all the objects within the control, as well as for the control itself.
You can also change the visibility of items. You can hide or show axis labels, title, legend, and so on.
Simply right-click the object it belongs to - such as the time axis - and select the object to show. To
alter the text, simply select the text and replace it with a text of your choice. You are of course free to
format the text using any font, font size, or font variation you wish.
- 325 -
Tip! When selecting a property from the list, hold down the SHIFT key down while selecting
another property from the list and all properties between the two selected will also be selected.
Use the CTRL key to add or remove a single property to or from the selection.
If the parameters displayed on the value axis share the same (or compatible) units, the unit will be
displayed in a label on the axis. You can select between several unit label positions. To change the
position of the unit label:
1. Right-click the unit label, and select the new position on the shortcut menu.
To show the unit label:
1. Right-click the value axis and select Show Unit Label on the shortcut menu.
To hide the unit label:
1. Right-click the unit label and select Hide on the shortcut menu.
You can format the appearance of the title on the Format toolbar.
To change the position of the title:
1. Right-click the title, and select Position on the shortcut menu.
2. Select the position of the title on the shortcut menu that appears.
To hide the title:
1. Right-click the title and select Hide on the shortcut menu.
- 326 -
About Field Codes
Field codes allow you to include details from your simulation model in your presentations, for
example titles, legends, axis labels, and so on. The field codes are entered as the text for the label you
wish to use it for.
The syntax for field codes are shown below. The sections in italics are optional. Field codes are not
case-sensitive.
{"<optional text>"!<object.property>\<switch>!"<optional text>"}
The core of the field code consists of an object and the property you wish to display. In addition, you
can use switches to control the appearance of the text. You can also add optional texts before the and
after the field code. If the field code itself is empty, these strings will not be displayed, either. The
available objects, properties and switches are shown in the table below.
Tip! You are allowed to use the short form Par instead of typing the complete word Parameter.
Studio will translate Par into Parameter on the fly.
- 327 -
Where can Field Codes be Applied?
Field codes can be applied in all of the controls available in Studio. The table below summarizes what
texts support field codes in each control.
Used
Text Available Default Description
in
Parameter.Name Empty The title can be set up to
Parameter.Unit display the time label, or the
Time.Label name or unit of the parameter
(s) shown in the control. In the
Title Chart control, it can also
Parameter.Name
Parameter.Unit display the name of the
Range.Name parameters' range.
Time.Label
Parameter.Name {Parameter.Name\I} By using the optional "\I"
Parameter.Unit {" ("! switch, you can shorten the
Parameter.Unit\I!")"} legend into showing the parts
of the parameter names that
are different from each other.
If you are displaying an array
A with the elements North,
East, South, and West, using
the \I switch will display
Legend
North, East, South, and West
in the legend. The legends will
be displayed as A[North], A
[East], A[South], and A[East]
if the switch is not used. The
default field code will also
display the parameters' units in
a parenthesis behind the
parameter name.
Parameter.Name {Time.Label} The time axis label can
Parameter.Unit display the parameter name (if
Time Time.Label there is only one parameter
Axis.Label available), the parameters' unit
(if there is only one unit
available), and the time label.
Parameter.Name {Range.Name} The element axis label can
Parameter.Unit display the parameter name (if
Time.Label there is only one parameter
Element Range.Name available), the parameters' unit
Axis.Label (if there is only one unit
available), the time label, or
the name of the range of the
parameter(s).
Parameter.Name {Parameter.Name} The value axis label can
Parameter.Unit display the parameter name (if
Time.Label there is only one parameter
available), the parameters' unit
- 328 -
(if there is only one unit
available), and the time label.
Value NB! The property is named
Axis.Label Gauge Display.Value
Axis.Label in the Gauge
control.
Parameter.Name {Time.Label} The time title (the header of
Parameter.Unit the column or row containing
Time.Title Time.Label time information) can display
parameter names or units, or
the time label.
Parameter.Name {Parameter.Name\I} See description for Legend
Parameters
Parameter.Unit {" ("! above.
[<name>].Title
Parameter.Unit\I!")"}
Gauge Parameter.Name {Parameter.Name\I} See description for Legend
Dial.Value Parameter.Unit {" ("! above.
Axis.Label Parameter.Unit\I!")"}
Parameter.Name {Parameter.Name} The label can be set up to
Parameter.Unit display the time label, or the
Time.Label name or unit of the parameter
Label (s) shown in the control. In the
Chart control, it can also
display the name of the
parameters' range.
Field codes can be used to create graphs that display nicely and at the same time update their display
should you alter the parameter selections of the controls, or the language settings for the project or
view. The field codes themselves are language independent, and will return the string in the correct
language.
However, if you are writing strings that are combinations of field codes and normal text, you can
select whether the string is used for all languages or only for the selected language. This is controlled
by using the For all languages option on the Text property page. This behavior of this option is shown
below:
! If the text contains only field codes, the For all languages option is not available, but is always
selected. The same string will always be used for all languages.
! If the text contains only normal text and no field codes, the For all languages option is not
available, but is always deselected. The text will only exist in the selected language.
! If the text contains a mixture of normal text and field codes, the For all languages option is
available. You can specify yourself whether the text should be used for all languages or only for
the selected language.
Note! If you are creating a language specific text, make sure you create texts for all the
languages that the model will be displayed in!
- 329 -
Legends and Parameter Titles when using Field Codes
Legends and Parameter titles can be defined using field codes. When using the parameter names and
units in these texts, you can use the optional \I switch to hide the common sections of the variable and
unit names. This is convenient when you want to save space in your legends.
If you want to display both the parameter name and the parameter unit, you can do so by combining
the Parameter.Name and Parameter.Unit field codes. You can even include extra texts to separate
them. By including optional text within the field code, the text will only be shown when the rest of the
field code is shown.
The default field code for legends and parameter titles are shown below.
{Parameter.Name\I}{" ("!Parameter.Unit\I!")"}
If you display an array in a time graph when using this field code, the resulting legend will display the
parts of the parameter names that are not equal, and it will not show the unit. An example is shown
below, for the array Sales. The dimension of the variable is Region = North, East, South, and West.
The default formatting of a time graph legend when displaying an array with four elements.
Tip! You are allowed to type only Par (the field code is not case-sensitive) for simplicity. Studio
will automatically convert this into Parameter for you.
If you are displaying parameters with the same unit, the unit itself is not included in the legend.
However, if the parameters have different units, the part containing the unit in the field code will be
visible. As you can see from the field code, it adds a space between the parameter name and the unit,
and encloses the unit in parenthesis. The control below displays two scalar variables Shipment and
Weight, where the two have different units.
When two parameters have different units and different names, all the information is shown in the
legend.
The default field codes for the parameter titles in the Time Table are equal to the default field code for
legends. To allow the title to automatically display the parameter name and unit (if the parameter
name and unit are unique), the following field code is used by default:
- 330 -
{Parameter.Name}{" ("!Parameter.Unit!")"}
The first example above, with the array Sales show in the Time Table, is shown below. (The display
itself is formatted, but the control uses the default field codes.)
When an array is displayed in a Time Table, the variable name and unit is displayed in the title of the
control, while the array element names are shown in the parameter titles.
The second example above, with two different parameters with separate units, are shown below. In
this case, since there are more than one parameter and unit name, they are shown in the columns
rather than in the title.
When two parameters have different units and names, the information is shown in the column
headers.
You can enter a field code in the property page for the text, or by entering it directly in the text itself.
1. Right-click the text you wish to alter, and select Edit Text on the shortcut menu.
2. Enter the new text, and hit Enter when you're finished.
To enter the field code on the property page:
- 331 -
1. Right-click the control (or the item containing the text) that you wish to change.
2. Click the Text tab.
3. Select the text you wish to alter under Properties.
4. Enter the new text under Text.
5. If the text contains a mixture of normal text and field codes, you can select to use the same text
for all languages by selecting the For all languages option.
6. Click Apply to save the changes, or OK to save the changes and close the dialog box.
- 332 -
Work with the Chart Control
As opposed to the time series control, the Chart Control is used to display the instant value of its
parameters, which must be arrays. In the chart control, the value of the array elements are shown
along the value axis, while the element index is shown along the element axis (corresponding to the
time axis in the time graph). You can display as many parameters you wish in the chart control, but
they must all have just one dimension each (they must be vectors).
You can also use the chart control to provide input to the simulation. If the parameter is a constant,
you can control the shape of the graph by dragging the shape of the graph along the element and value
axes.
The Chart Control supports parameters using index variables to index its dimensions, allowing you to
create user interfaces where you can select different parameter elements for display.
Tip! You can restrict data input to one point only by holding down Alt while dragging the
data point along the value axis.
The chart graph showing a bar graph that represents the market share, share of income and
development expenses for four different products.
Note! All the parameters of a chart control must be vectors (arrays with only one dimension).
The elements are drawn from left to right (the first element in position 1, the second element in
- 333 -
position 2, etc.) regardless of the dimension of the array.
Tip! If a graph is filled, you can select the graph by clicking the filled area under the graph.
The four available chart types: Line (top left), Smooth Line (top right), Step (bottom left), and Bar
(bottom right).
The options are also available on the Chart Graph property page for each selected parameter. The
property page can be accessed by right-clicking the graph or the entire control, and selecting
Properties on the shortcut menu.
- 334 -
Change the Order of Parameters
The order of the parameters will decide the order in which they are displayed in the time graph. The
topmost parameter is displayed at the back of the graph area, and the other parameters are displayed in
front of it. However, the topmost parameter is displayed at top of the legend.
To change the order of the graphs:
1. Right-click the graph you wish to change, and select Order on the shortcut menu.
2. Select a command on the shortcut menu that appears. The options are:
! Bring to Front: Brings the graph to the front of the control.
! Bring Forward: Brings the graph one step closer to the front.
! Send Backward: Sends the graph one step closer the back.
You can also perform the change in the Properties dialog box:
1. Double-click the control that you wish to change, or click Properties.
2. Select the Parameters tab in the property dialog box.
3. Sort the parameters in the list by selecting them and clicking Up or Down.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
- 335 -
Format the Chart Area
You can format the color and style of the border of the graph area, as well as its interior fill on the
Format toolbar. Alternatively, you can use the Properties dialog box:
1. Double-click the graph area of the control that you wish to change, or select it and click
Properties.
2. Select the Line tab to format the lines. You can change the line settings for the following
properties:
! Line: The outline of the graph area.
3. Select the Fill tab to format the interior fill of the graph area.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Note! The intervals for the gridlines of the value axis are specified on the Value Axis property
page. The intervals for the gridlines of the time axis are specified on the Report property page
in the Simulation Settings dialog box.
Show Gridlines
1. Double-click the control that you wish to change, or select it and click Properties.
2. Select the General tab in the Properties dialog box.
3. Under Gridlines, select the gridlines to display.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Note! The intervals used for the value axis gridlines are specified on the Value Axis tab in the
Properties dialog box for the control. Vertically, the chart control will draw one gridline per
element.
- 336 -
Presenting a Set of Scalar Variables in a Chart Control
The chart control only accepts vectors - arrays with one dimension - as parameters. If you need to
present a set of scalar variables in a chart control, you will first have to build an array where the
various scalar variables form the various elements. The procedure below shows you how to achieve
this.
Note! Before you can arrange several variables in an array, you must observe that their units
are compatible.
1. Add an auxiliary to your model (either in the Details Window or the Constructor diagram).
2. Create information links from the scalar variables to the new auxiliary.
3. Define the new auxiliary as an array with the linked variables as elements, using the syntax
{Element_1, Element_2, ...}.
4. Click OK to save the changes.
5. Insert a chart control in your diagram.
6. Drag the recently defined auxiliary and drop it on the control.
7. Format the chart control in any way you wish.
The control will now show the values of the four scalar variables along the element axis.
Note! Although the Chart control can be used to provide input for the elements of the array,
these values will not be reflected in the original scalar variables, hence this method is
unsuitable to provide input to scalar variables!
Example
The model below shows the market share of four companies, where each variable is a scalar auxiliary.
To display the value of these four variables, we add an extra auxiliary - Market Share - and use the
four scalars as elements. The definitions are shown below. The only requirement is that the units of
the scalar variables are compatible.
The chart control allows you to input values to parameters that accept this input. This means that you
can only input values to constants or to levels. If you change a level, the change will only affect its
initial value.
Tip! If you define the parameter's corresponding variable as Permanent, the value(s) you have
entered for the variable during the simulation run will not be reset when you reset the
- 337 -
simulation.
Tip! If you hold down Alt while you drag, you can lock the mouse pointer to the current data
point only, so that you
Tip! When the graph is used for input, it is useful to format it as either a step or bar graph,
since these graphs allow a wider input area.
- 338 -
Work with the Gauge Control
The Gauge Control displays the immediate value of its parameter, and can display only one
parameter at a time. Similar to a speedometer or an analog ammeter, the gauge displays the value by
pointing a needle to a fixed scale.
A gauge shows the current value of a parameter. You can create sectors in the gauge dial by using
customized picture fills.
The various components of the gauge control can be customized allowing you to create a gauge that
fully satisfies your requirements. You control the size, shape, and color of the gauge disc; the margins
of the dial (the area between the boundary of the dial and the span of the value axis); the size, shape,
color, and position of the gauge needle; if the gauge hub should be visible; the color and fonts used by
the value axis; as well as the rotation of the gauge itself. If you need to create sectors in the gauge
dial, you can create your own picture fills that you can use for the gauge dial.
The control may also be used for data input. Simply drag the gauge needle to change the value of the
control's parameter.
The Gauge Control accepts index variables as parameters. The index variable can be used to control
which element of a parameter is displayed in, say, a time graph.
This page contains several examples of gauges. Values for gauge specific properties are presented for
each gauge. Use these examples as an inspiration to create nice gauges for your simulator interfaces!
Gauge Notes
Dial style: Auto (or Pie Based)
Direction: 90
Dial span: 100
Display span: 90
Dial inner radius: 40%
- 339 -
Dial fill type: Picture Fill
Needle style: Triangle
Head position: Outside Dial
Tail position: At Dial Center
Hub visibility: Visible
Hub size: 5%
Notes: The picture fill of the gauge dial is created as
explained here.
Dial style: Auto (or Pie Based)
Direction: 90
Dial span: 100
Display span: 90
Dial inner radius: 60%
Dial fill type: Solid
Needle style: Arrowhead
Head position: Inside Axis
Tail position: Outside Dial
Hub visibility: Hidden
Hub size: -
Dial style: Auto (or Pie Based)
Direction: 90
Dial span: 100
Display span: 90
Dial inner radius: 70%
Dial fill type: No Fill
Needle style: Spear
Head position: Inside Dial
Tail position: Behind Dial Center
Hub visibility: On
Hub size: 5%
Dial style: Chord Based
Direction: 180
Dial span: 150
Display span: 140
Dial inner radius: 50%
Dial fill type: Solid
Needle style: Line
Head position: At Axis
Tail position: Inside Dial
Hub visibility: Hidden
Hub size: -
Dial style: Auto (or Chord Based)
Direction: 90
Dial span: 240
Display span: 220
Dial inner radius: 0%
Dial fill type: Solid
Needle style: Triangle
Head position: Inside Axis
Tail position: Behind Dial Center
Hub visibility: Visible
Hub size: 12%
- 340 -
Dial style: Pie Based
Direction: 90
Dial span: 270
Display span: 270
Dial inner radius: 40%
Dial fill type: Solid
Needle style: Arrowhead
Head position: 80% (custom)
Tail position: 50% (custom)
Hub visibility: Hidden
Hub size: -
Dial style: Pie Based
Direction: 90
Dial span: 360
Display span: 360
Dial inner radius: 40%
Dial fill type: Solid
Needle style: Diamond
Head position: 80% (custom)
Tail position: 80% (custom)
Hub visibility: Visible
Hub size: 12%
Dial style: Auto (Pie Based)
Direction: 90
Dial span: 80
Display span: 70
Dial inner radius: 40%
Dial fill type: No Fill
Needle style: Triangle
Head position: Inside Axis
Tail position: Inside Dial
Hub visibility: Visible
Hub size: 7%
You can specify the direction, shape, margins, and colors of the gauge dial to suit your preference.
There are unlimited combinations available, and by using picture fills for the interior fill of the gauge
dial, you can create gauges with various sectors.
Style
The Style property allows you to control the shape of the gauge dial. The shape of the dial is
dependent on the dial span, and the various options will have different effects on different spans. The
illustration below shows the two options Pie Based and Chord Based. If you select Auto, the dial
will be pie based if the dial span is less than 180 degrees, and chord based if the dial span is more than
180 degrees.
- 341 -
a) Pie Based dials. b) Chord Based dials.
Direction
The Direction property allows you to control the direction of the gauge dial (and hence the gauge
needle). The default value is 90 degrees, which creates dial pointing upwards. Possible values are 0 to
359.
The illustration shows the gauge dial when rotated to various angles (0°, 90°, 180°, and 270°).
Tip! If the value for Display span is higher than the value for Dial span, Studio will
automatically make them equal.
The Dial span and Display span are shown on the illustration below.
- 342 -
Gauge Needle Properties
The gauge needle can be customized in several aspects. You can change the shape of the needle, and
select between several predefined shapes such as arrowhead, diamond, and spear. Next, you can also
customize the starting and ending point of the needle. By selecting a starting point outside the gauge
dial, you can even create a gauge needle that points "inwards" to the value axis.
Style
The Style property allows you to control the shape of the gauge needle.
The gauge needle can have several shapes: a) arrowhead, b) diamond, c) line, d) spear, and
e) triangle.
Position
The Head property allows you to control the position of the head of the gauge needle. You can choose
between several predefined positions, or you can enter a custom value. The custom value is given as a
percentage of the entire gauge dial. The various options are the same as for the Tail property below,
and are listed in the table below.
The Tail property allows you to control the position of the tail of the gauge needle. You can choose
between several predefined positions, or you can enter a custom value. The custom value is given as a
percentage of the entire gauge dial. The various options are the same as for the Head property above,
and are listed in the table below.
Option Description
Outside The end of the needle touches the outer limit of the value axis.
Axis
At Axis The end of the needle touches the line of the value axis.
Inside The end of the needle touches the inner limit of the value axis.
Axis
Outside The end of the needle touches the outer line of the gauge dial.
Dial
Inside The end of the needle touches the inner line of the gauge dial.
Dial
At Dial The end of the needle is placed exactly at the center of the gauge dial (at the center of
Center the gauge hub, if it is visible).
The end of the needle is placed at a position corresponding to the percentage entered
in the Custom box. The number represents a percentage of the outer radius of the
- 343 -
gauge dial, 100% being equal to the option Outside Dial, and 0% equal to the option
At Dial Center above. You can enter any value, even negative numbers. A value
Custom
larger than 100% will cause the end of the needle to be placed outside the gauge dial,
while a negative value will place the end of the needle beyond the dial center.
Tip! You can hide the gauge hub if you like, by right-clicking it and selecting Hide on the
shortcut menu.
You can specify the direction, shape, margins, and colors of the gauge dial to suit your preference.
There are unlimited combinations available, and by using picture fills for the interior fill of the gauge
dial, you can create gauges with various sectors.
To format the shape of the gauge dial:
1. Double-click the gauge dial, or right-click it and select Properties on the shortcut menu.
2. On the Gauge Dial property page, specify the appearance of the gauge dial using the properties
listed below.
! Style: Select the style of the dial (pie or chord based).
! Direction: Specify the direction of the gauge dial, valid values are 0 to 359.
! Dial span: Specify the curvature of the gauge dial, valid value are 1 to 360.
! Display span: Specify the area of the dial covered by the value axis. Valid values are 1 to 360,
but the entered value must be less than or equal to the value entered for Dial span.
3. On the Gauge Dial property page, specify the size of the dial using the properties listed below.
! Outer radius: The outer radius of the dial (100% represents the maximum size possible).
! Inner radius: The inner radius of the dial given in percentage of the total dial size. Valid values
are 0% to 100%.
4. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
To format the interior fill and line of the gauge dial:
1. Select the dial of the gauge that you wish to format.
2. Click the small arrow next to Fill Color, and select a color for the dial fill.
- 344 -
3. Click the small arrow next to Line Color, and select a color from the dropdown for the dial
line.
4. Click the small arrow next to Line Style, and select a color from the dropdown for the dial
line.
5. Click the small arrow next to Dash Style, and select a style from the dropdown for the dial
line.
Tip! You may of course format the fill and line on the corresponding property pages also, by
right-clicking the gauge dial itself and selecting Properties on the shortcut menu.
You can freely format the gauge dial as you wish to. Gauge dials can be a) pie shaped or b) chord
shaped.
The gauge needle is highly flexible through its advanced style and position properties, in addition to
the common color and line properties.
To format the shape of the gauge needle:
1. Double-click the gauge needle, or right-click it and select Properties on the shortcut menu.
2. On the Gauge Needle property page, specify the appearance of the gauge needle under Style.
There are several styles available: Arrowhead, Diamond, Line, Spear, and Triangle.
3. On the Gauge Needle property page, specify the position of the needle using the properties listed
below.
! Head The position of the head of the needle. There are several available options. You may also
enter a custom percentage value representing the distance from the center of the gauge dial.
Negative numbers are allowed (although they are seldom useful).
! Tail The position of the tail of the needle. There are several available options. You may also
enter a custom percentage value representing the distance from the center of the gauge dial.
Negative numbers are allowed.
4. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
Tip! You can make the gauge needle point "inwards" by entering a custom tail position larger
than the head position.
- 345 -
4. Click the small arrow next to Line Style, and select a color from the dropdown for the needle
line.
5. Click the small arrow next to Dash Style, and select a style from the dropdown for the needle
line.
Tip! You may of course format the fill and line on the corresponding property pages also, by
right-clicking the gauge dial itself and selecting Properties on the shortcut menu.
The gauge hub is placed in the center of the gauge dial. The hub can be formatted freely, and it can be
visible or hidden.
The gauge hub can be formatted independently of the gauge needle, and can be visible or hidden.
To format the size of the gauge hub:
1. Right-click the gauge, and select Properties on the shortcut menu.
2. On the General property page, enter a new percentage size in the Size box under Hub. Note that
the percentage refers to the total size of the gauge control. Entering a value of 99% will make the
hub cover the entire gauge dial.
3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
You can format the fill and line of the gauge hub using the toolbar:
1. Select the hub of the gauge that you wish to format.
2. Click the small arrow next to Fill Color, and select a color for the hub fill.
3. Click the small arrow next to Line Color, and select a color from the dropdown for the hub
line.
4. Click the small arrow next to Line Style, and select a color from the dropdown for the hub
line.
5. Click the small arrow next to Dash Style, and select a style from the dropdown for the hub
line.
Tip! You may of course format the fill and line on the corresponding property pages also, by
right-clicking the gauge hub itself and selecting Properties on the shortcut menu.
- 346 -
3. Under Hub, deselect the Visible option.
4. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
To show the gauge hub:
1. Right-click the gauge control, and select Show Hub on the shortcut menu.
or
1. Right-click the gauge control, and select Properties on the shortcut menu.
2. Select the General tab.
3. Under Hub, select the Visible option.
4. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.
The illustration shows the gauge dial when rotated to various angles (0°, 90°, 180°, and 270°).
You control the input mode of the gauge control on the General property page. If the control accepts
input, you can control the value of its parameter:
1. Click the gauge needle, and drag the needle to a new position while holding down the mouse
button.
Tip! If you define the parameter's corresponding variable as Permanent, the value(s) you have
entered for the variable during the simulation run will not be reset when you reset the
simulation.
If Studio is in User Mode, the control will not be selected when you drag the needle. The state of the
Design Mode button indicates what mode Studio is currently in.
- 347 -
Create a Gauge with Sectors
You can create a gauge dial with sectors by creating a bitmap with the correct shape and color sectors,
and then use that bitmap as the fill for the gauge dial. Before creating the bitmap, you should consider
the following factors:
! The shape of the bitmap must match the shape (not necessarily the size) of the gauge dial (inner
radius and dial span).
! The sectors are (obviously) static on the bitmap, and are not influenced by changes in scaling of
the value axis (and/or parameter).
! Colors used in bitmaps might be displayed differently on other people's computers (if the end user
has fewer colors than you have yourself).
Use the following guidelines to create a gauge with sectors.
1. Insert and format the gauge. Make sure that the shape of the gauge dial (inner radius and dial
span) are correct. The gauge might look something like this:
2. Make sure that the value axis and scaling of the parameter are correct before continuing.
3. Make a screen shot of the gauge (by hitting Alt+Enter), and paste the screen shot into your
favorite image processor.
4. In the image processor, crop the screen shot until only the gauge dial is visible, and clean up the
image until you have only the gauge dial left in the image. To make it easier to create the sectors,
it is useful to leave the tick marks of the value axis.
5. In the image processor, create the desired colored sectors. Use the tick marks to ensure that the
sectors have the correct size and shape.
6. In the image processor, select the bitmap and copy it to the Windows clipboard.
7. Switch back to Powersim Studio, and double-click the dial to open the Property Pages. Select the
Fill property page, and select Picture under Type. Then click Select Picture to open the Select
Resource dialog box.
8. Click Paste, select Bitmap in the Paste As dialog box, and click OK. Enter a suitable name for the
bitmap in the Select Resource dialog box. Click OK to select the picture.
9. Click Apply to view the changes. The gauge should now look something like this:
- 348 -
Work with the Slider Bar Control
The Slider Control can be used to provide input to constant auxiliaries and levels, or it can be used
to monitor the value of other variables. If the parameter is a level, the slider bar will only allow you to
set its initial value. The slider bar is shown below.
The slider bar used to provide input to a constant auxiliary (left) and as a tool to measure the value of
an auxiliary (right).
As for the other controls, you are allowed to alter the appearance of the Slider control to a wider
extent.
The Slider Control accepts index variables as parameters. The index variable can be used to control
which element of a parameter is displayed in, say, a time graph.
Tip! If you define the parameter's corresponding variable as Permanent, the value(s) you have
entered for the variable during the simulation run will not be reset when you reset the
simulation.
- 349 -
Work with the Switch Control
The Switch Control allows you to select between a set of given inputs to parameters during the
simulation. You should use the Switch Control when you want the user to quickly be able to switch
between two or more strategies or input alternatives.
You can create several different button types with the Switch Control:
Push Button: Set the value while the button is depressed.
Check Button: A two-state button which sets the value on check/uncheck. This button type can
also be shown as a push button.
Radio Button: A multi-state button that sets the value on selection. This button type can also be
shown as a set of push buttons.
List Box: A list with several entries that sets the value on selection.
Combo Box: A drop-down list with several entries that sets the value on selection.
Static: A static text that change with the value of the control's parameter.
The Switch Control makes it possible to create control panels for controlling input to your simulation.
Each control will set the value of a constant auxiliary based on the selection in the control. In this
figure, four Switch Controls are used, with a frame object providing the outer frame and the title of
the panel.
The Switch Control accepts index variables as parameters. The index variable can be used to control
which element of a parameter is displayed in, say, a time graph.
Tip! If you define the parameter's corresponding variable as Permanent, the value(s) you have
entered for the variable during the simulation run will not be reset when you reset the
simulation.
- 350 -
Create a Button
The value under Set is the value when the button is clicked.
7. To enter a different label for the button, click the Text tab, and select Label under Properties.
8. Enter the new text or field code for the label under Text. The default field code will display the
parameter's name on the face of the button.
9. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Tip! To create a "sticky" button, select Check Button under Type, and then select the Push-like
option. The appearance of the buttons are identical, but you must click once to depress the
button, and once again to revert it.
Value: Clear
A push button changes the value of the parameter only when it is depressed.
(Click the image to demonstrate.)
Note! The push button will not use the texts entered for the Text property available under
States.
- 351 -
option, the control will find settings based on the type and value of the selected parameter. To
specify the values manually, you must deselect the Automatic option.
The value under Clear is the value when the button is not selected.
The value under Set is the value when the button is selected.
7. To enter a different label for the button, click the Text tab, and select Label under Properties.
8. Enter the new text or field code for the label under Text. The default field code will display the
parameter's name on the face of the button.
9. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
You can create a "sticky" button by selecting the Push-like option. The difference between a check
button and a push-like check button is illustrated below.
A check button can have two styles: check button or push-like check button.
(Click the images to demonstrate.)
Note! The check button will not use the texts entered for the Text property available under
States.
Specify the text for each option under Text. If Auto is selected, the text will equal the value.
7. To enter a different label for the group, click the Text tab, and select Label under Properties.
8. Enter the new text or field code for the label under Text. The default field code will display the
parameter's name on the face of the button.
9. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
You can create "sticky" buttons by selecting the Push-like option.
- 352 -
Value: Val 1
A switch control will have as many radio buttons as the selected number of states. The value selected
corresponds to the selected radio button.
(Click the image to demonstrate.)
Specify the text for each entry under Text. If Auto is selected, the text will equal the value.
7. To enter a different label for the list box, click the Text tab, and select Label under Properties.
8. Enter the new text or field code for the label under Text. The default field code will display the
parameter's name on the face of the button.
9. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
First
Second
Third
Fourth
Value: Val 1
A switch control will have as many entries in the list as the selected number of states. The value
selected corresponds to the selected list entry.
(Click the image to demonstrate.)
- 353 -
Create a Combo Box
Specify the text for the entry under Text. If Auto is selected, the text will equal the value.
8. To enter a different label for the combo box, click the Text tab, and select Label under Properties.
9. Enter the new text or field code for the label under Text. The default field code will display the
parameter's name on the face of the button.
10. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
First
Value: Val 1
A switch control will have as many entries in the list as the selected number of states. The value
selected corresponds to the selected list entry.
(Click the image to demonstrate.)
- 354 -
Specify the text for the entry under Text. If Auto is selected, the text will equal the value.
8. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
The text that is displayed in the control will depend on the value of the connected parameter. This
allows you to control a text string that appears in the diagram by controlling the value of a variable.
The Switch Control is an ideal tool if you want to give the users of your simulations a change to select
between alternative strategies. The simplest way of achieving this is by allowing the user to choose
between two (or more) possible initial values for levels or constant auxiliaries. A more advanced
method is to actually allow the user to change strategy during the simulation. These two methods are
explained below.
Tip! If you define the parameter's corresponding variable as Permanent, the value(s) you have
entered for the variable during the simulation run will not be reset when you reset the
simulation.
aux Switch = 2
type Switch = Integer
aux 'Wave Input' = 40+sinwave(40, 90<<da>>)
aux 'Step Input' = STEP(40, STARTTIME+90<<da>>)
aux 'Random Input' = RANDOM(0,80)
aux Strategy = {'Wave Input', 'Step Input', 'Random Input'}[INDEX(Switch)]
- 355 -
As can be seen from the definition, the three input alternatives are concatenated into an array in the
variable Strategy. The array is indexed by the value of Switch.
Note! Switch must be defined as an INTEGER for the INDEX function to work.
A switch control is added to the diagram to control the value of Switch. The switch control is a three-
state radio button, and the values are selected accordingly to the index value of the corresponding
input variable. Under Values you should therefore enter the contents of Table 1.
Value Text
Val 1 1 Wave
Val 2 2 Step
Val 3 3 Random
The animation shows one possible simulation run of the example described above.
Tip! The same techniques can be used for switches formatted as list or combo boxes.
- 356 -
Work with the Table Control
The Table Control is used to display the value of a variable in the present simulation period.
Through its flexible formatting capabilities, the table control is ideal for creating a report form that
updates as the simulation advances.
You can display either a text, the name of a variable, or a variable value in a table cell. You can also
insert as many rows and columns you wish, including the ability to insert single cells.
The Table Control can be used to present data from read only variables. If a constant auxiliary is
selected as a parameter, you can enter a new value for it in the table control.
The Table Control accepts index variables as parameters. The index variable can be used to control
which element of a parameter is displayed in, say, a time graph. The control also supports parameters
using index variables to index its dimensions, allowing you to create user interfaces where you can
select different parameter elements for display.
A table control used to supervise a company's stock. The table displays the current simulation time,
along with the quantity in stock at this time.
Tip! To display the entire time series of the variable, you should use the Time Table
Control rather than the Table Control.
You can easily display an array in a table control. By dropping the array variable on a cell in the table,
the automated insertion process can distribute the first two dimensions of the array in the cells of the
table, starting from the cell where you dropped the variable.
The insertion process is generic, and can be used for any array of any dimension. However, it is
mostly useful for vectors (one dimensions) and matrices (two dimensions), since the table can easily
display these as lists or tables without using the array syntax to display elements. If you add arrays
with more than two dimensions, the array syntax must be utilized to display the other dimensions than
- 357 -
the two first.
1. Insert a table control in your diagram. The size of the control should be made large enough to
accommodate most of the elements of the array.
2. Drop the array variable you wish to display onto the first cell where you want its value to appear.
Thus, if you wish to save a column (and/or a row) for headers, drop the variable on the second
column (and/or second row) of the control.
3. In the Paste Array Parameter dialog box that appears, you can specify how the array should be
displayed in the table control.
! You can select whether to display the array in a table (the two first dimensions distributed in
columns and rows), list (the first dimension distributed in columns or rows), or single cell (no
dimensions distributed) under Paste as.
! Under Layout you specify whether the first dimension of the array should be displayed
downwards (rows) or across (columns) the control.
4. Click OK to add the array into the table.
The array will be displayed as specified. If the control contains too few rows (or columns), new rows
(or columns) will be created as necessary, provided there is enough space to accommodate them. If
the new rows (or columns) becomes too narrow, the overshooting array elements will not be added to
the control. In this case you should delete the control, and create a new and bigger one before trying
again.
You can enter text in any empty cell in the table control. If a parameter is shown in the cell, and it
accepts input (constant auxiliary or initial value of level), you can enter a new value for it in the cell.
- 358 -
To enter text in a cell:
1. Select the cell in the table (point and click with mouse).
2. Type the text, and finish typing by hitting Enter.
Once you have selected one cell, you can use the pointer buttons on the keyboard to move the
selection.
Note! If the cell displays a variable name or read only value, you are not allowed to edit the
text.
Tip! When you have selected a cell, you can format the font and color of the cell on the Format
toolbar.
Once you have inserted a table control in your diagram, you can display the name of a variable in any
cell you wish.
Note! This procedure requires that you have added at least one parameter to the control (you
can do this by dropping a variable symbol on a table cell).
1. Right-click the cell, select Assign Parameter Name on the shortcut menu, and select the
parameter name on the menu that appears.
Only the first 10 parameters are available on the shortcut menu. To display the name of another
variable in a cell:
1. Right-click the cell, and select Assign Parameter… on the shortcut menu.
2. Select the variable whose name you wish to display in the dialog box.
3. Select the Name option under Type.
4. Click OK to display the variable name in the cell.
Tip! To show an empty cell, select Remove Assigned Parameter on the shortcut menu.
Once you have inserted a table control in your diagram, you can display the value of a variable in any
cell you wish.
1. Drop the variable on the cell where you want to display its value.
Tip! You can drag variables from diagrams or from the variable window.
Alternatively,
1. Right-click the cell, select Assign Parameter Value on the shortcut menu, and select the
parameter name on the menu that appears.
Only the first 10 parameters are available on the shortcut menu. To display the value of another
- 359 -
variable in a cell:
1. Right-click the cell, and select Assign Parameter… on the shortcut menu.
2. Select the variable whose name you wish to display in the dialog box.
3. Select the Value option under Type.
4. Click OK to display the variable name in the cell.
Tip! To show an empty cell, select Remove Assigned Parameter on the shortcut menu.
Tip! To change the overall width of the table control, drag the outline of the control itself. The
width of the columns will automatically adjust to the new control width.
Tip! To change the overall height of the table control, drag the outline of the control itself.
However, the height of the rows will not adjust to the new control height.
Note! Deleting a column does not remove parameters from the control.
Note! Deleting a row does not remove the parameters displayed in it from the control.
The table control allows you to input values to parameters that accept this input. This means that you
- 360 -
can only input values to constant auxiliaries or to levels. If you change a level, the change will only
affect its initial value.
Tip! If you define the parameter's corresponding variable as Permanent, the value(s) you have
entered for the variable during the simulation run will not be reset when you reset the
simulation.
When typing input values, you can type the unit of the variable directly as text (or omit it, if you like).
For example, if you wish to enter 20 m/s as the new value, simply type '20 m/s' or '20' (without
quotation marks).
Tip! You can enter new values using any compatible unit of the target variable's unit. Using the
example above, you could very well enter '3600 m/hr', which would immediately be converted
to 1 m/s in the target variable.
- 361 -
Work with the Time Graph Control
The time graph control is used to display the time series of variables as they develop over time. The
time graph control is ideal for graphically presenting one or more variable's behavior over time.
The time graph control shows the time series for wind variations at two different locations.
The time graph uses the report window of the simulation when it displays data. Thus, if the report
window is shorter than the total simulation length, the time graph will scroll as the simulation
advances. The scroll interval is determined by the report window's slide value.
The time graph control supports parameters using index variables to index its dimensions, allowing
you to create user interfaces where you can select different parameter elements for display.
Tip! To show the behavior of a variable over time in a table, use the time table control.
Tip! If a graph is filled, you can select the graph by clicking the filled area under the graph.
- 362 -
Format the Time Axis in the Time Graph Control
Formatting the time axis in the Time Graph control allows you to control the position and style of tick
labels - like for other axes available - the minor and major intervals used by the axis, and also the
format of the (time) tick labels.
To change the properties of the time axis:
1. Right-click the time axis, and select Properties on the shortcut menu.
2. Click the Time Axis tab.
3. Change the settings for the properties you wish to change.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
Properties Explained
The default settings for major and minor intervals will follow the selections done in the Simulation
Settings for the simulation. You can override these for each Time Graph control individually, if you
want to. The major interval of the time axis will be used as the summary period for the summary
parameters selected for your control.
The time axis offers extensive control of the tick labels. You can specify short or long time formats,
whether to show static information, and more.
Tick Label Options
Available
Property Description
options
Automatic Specify the placement of the first level tick labels relative to the tick
In intervals marks.
Between If you select In intervals, the tick label will be shown inside the
intervals interval and denote the period. If the major interval of the time axis
Placement is month, then the tick label may be shown as Jan, Feb, etc.
If you select Between intervals, the tick label will be shown directly
below the tick label and denote that point in time. With a major
interval of one month, the tick label may be shown as Jan 1, Feb 1,
etc.
Short Select the date and time format to use for the tick label. It is
Medium recommended that you try the various options to see how they work
Long for various intervals and periods. As an example, Short will display
Format
the month number (1), Medium will display the month with three
letters (Jan), while Long will display the entire month name
(January).
on/off Select whether time information that is common for all tick labels
Show static
should be shown or not. If, say, the simulation runs for one full year,
time
selecting this option will display the year in the tick label, while
elements
deselecting it will remove the year from the tick label.
on/off Select whether the tick labels should be shown in one or two lines. If
you select this option, information that is common for some of the
Allow
tick labels will be shown below a range of tick labels. while
second level
deselecting it will include the common information in all the tick
labels of the range.
- 363 -
Format Short Select the data and time format to use for the second level tick
(second Medium labels.
level) Long
Examples
The three illustrations below show how the tick labels of the time axis can be changed by using the
options above. The settings for each are shown in the table.
Time Graph Tick Label Options
Placement: In intervals
Format: Medium
Show static time elements: Off
Allow second level: On or Off
Format (second level): Any
Placement: In intervals
Format: Short
Show static time elements: On
Allow second level: On
Format (second level): Long
- 364 -
Use Parameters with Summary Types in the Time Graph Control
The Time Graph Control allows you to use parameters with summary types. Unlike ordinary
parameters, these parameters are summarized over a summary period, and then reported once per
period.
Tip! You can display both normal and summary parameters in the same time graph!
The summary period for the summary parameters are equal to the major interval of the time axis of
the control. The default value is the major interval selected in Simulation Settings on the Simulation
menu, but you can also change it for each individual control, should you wish to.
Since summary parameters contain only periodic data, you may change their graph type to Step,
and Bar as well. These options are available when you right-click the graph for each individual
summary parameter in the control.
A Time Graph control displaying four parameters, where three are summarized and displayed as bar
graphs. The summary period equals the major interval of the time axis, which in this example is set to
one quarter.
The order of the parameters will decide the order in which they are displayed in the time graph. The
topmost parameter is displayed at the back of the graph area, and the other parameters are displayed in
front of it. However, the topmost parameter is displayed at top of the legend.
To change the order of the graphs:
1. Right-click the graph you wish to change, and select Order on the shortcut menu.
2. Select a command on the shortcut menu that appears. The options are:
! Bring to Front: Brings the graph to the front of the control.
! Bring Forward: Brings the graph one step closer to the front.
! Send Backward: Sends the graph one step closer the back.
You can also perform the change in the Properties dialog box:
1. Double-click the control that you wish to change, or click Properties.
2. Select the Parameters tab in the property dialog box.
- 365 -
3. Sort the parameters in the list by selecting them and using the Up and Down buttons.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
You are allowed to change the graph type for parameters with summary types in the time graph
control.
1. Right-click the graph you wish to change, and select the graph type to use on the shortcut menu.
The options are: Line, Smooth Line, Step, and Bar.
The figure below illustrates the difference between the four types.
The four available chart types: Line (top left), Smooth Line (top right), Step (bottom left), and Bar
(bottom right).
The options are also available on the Chart Graph property page for each selected parameter. The
property page can be accessed by right-clicking the graph or the entire control, and selecting
Properties on the shortcut menu.
- 366 -
Show Hidden Parameters in the Time Graph
You can show and export the history for a parameter in the Time Graph control. The history can
be exported to a file or to the clipboard.
1. Right-click the graph of the parameter whose history you would like to show in the time graph
control, and select Show History on the shortcut menu. The history of the parameter will appear
in the history dialog box.
2. To export the history to a file or the clipboard, click Export….
3. Control the layout of the history in the Export History dialog box.
1. Select Include headers to include column (or row) headers.
2. Select Include times to include time information with the history.
3. Select Times down to control the orientation of the variable history. If selected, the values will
be separated by a line shift.
4. Control the decimal separator and column delimiter under Format.
1. Select the Decimal Separator. Options are '.' (point) and ',' (comma).
2. Select the Delimiter. Options are 'Tab', 'Space', ';' (semi-colon), and ',' (comma).
5. Select the destination for the export under Destination.
1. Select File to export the history to a text file. You will be prompted to specify a file name and a
location when you click OK.
2. Select Clipboard to export the history to the Windows Clipboard. When you click OK the
history is copied to the Clipboard, and you can paste it into the any Windows application.
6. When you are satisfied with your selections, click OK to export the data.
7. Click OK to close the history dialog box.
You can format the color and style of the border of the graph area, as well as its interior fill on the
Format toolbar. Alternatively, you can use the Properties dialog box:
1. Double-click the graph area of the control that you wish to change, or select it and click
Properties.
2. Select the Line tab to format the lines. You can change the line settings for the following
- 367 -
properties:
! Line: The outline of the graph area.
3. Select the Fill tab to format the interior fill of the graph area.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Note! The intervals for the gridlines of the value axis are specified on the Value Axis property
page. The intervals for the gridlines of the time axis are specified on the Report property page
in the Simulation Settings dialog box.
Show Gridlines
1. Double-click the control that you wish to change, or select it and click Properties.
2. Select the General tab in the Properties dialog box.
3. Under Gridlines, select the gridlines to display.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
Note! The intervals used for the time axis gridlines are specified on the Time Axis tab, while the
intervals used for the value axis gridlines are specified on the Value Axis tab in the Properties
dialog box for the control.
The report window - which you can specify on the Report tab in the Simulation Settings dialog box -
allows you to select a smaller portion of the total simulation to view. The report window is defined by
a length and slide. The length of the report window specifies the portion of the simulation to view at a
time, while the slide specifies the interval by which the report window will scroll. If, say, the
simulation runs for one year, the report length is one quarter, and the slide interval is one week, the
report will show data for the last quarter at a time, and when the end of the current quarter is reached,
the report window will slide one week further.
- 368 -
The animation illustrates how the report window can be used to present only a portion of the
simulation at a time. The report window has a length of one month, and when the first month is
completed, it slides by an interval of one day. The entire simulation lasts for two months.
To set up a report window for the simulation:
1. Select Simulation Settings… on the Simulation menu.
2. Select the Report tab.
3. Under Reporting Window, select the appropriate length and slide of the reporting window. The
length denotes the size of the window, while the slide indicates when the window will scroll.
4. Click OK to save the changes.
The changes are immediately recognized by the time graph control.
- 369 -
Work with the Time Table Control
The Time Table Control is used to display the time series of variables as they develop over time.
The time table control is ideal for presenting one or more variable's behavior over time. You can
change the orientation of the table, as well as the formatting of text and cells.
Parameters in the Time Table control will always be defined with summary types. If you add
parameters to the Time Table control by clicking Add Parameter button, the parameter will be
added with Automatic as the summary type. The default summary type used for parameters made
from model variables is First. The specified reporting interval for the control will be used as the
summary period for its parameters.
The Table Control supports parameters using index variables to index its dimensions, allowing you to
create user interfaces where you can select different parameter elements for display.
Tip! If all the parameters of the control use the First summary type, the control will display the
time rather than the period.
The Time Table can be used to display the value of parameters over the simulation in various periods.
The way time is displayed in the Time Table control is dependent of the interval used, the
summary types of the parameters, and the settings done in the Time Table property page.
Time in the time table will be displayed in two alternative ways. It can be displayed accurately,
indicating the exact time of the time step when the value is reported (such as 1/1/2003). The other
alternative is to display the name of the period that the value belongs to (such as January 2003). The
first alternative can only be used when all the parameters displayed in the control use the First
summary type. You can, however, always force the time to be displayed as period name by selecting
the Always show interval names option. When any other summary type is detected, the time table will
always display the interval names.
- 370 -
Note! The reason for displaying the period name rather than the time of the reporting time step,
is simply that the value displayed is valid for the entire period, and not only for the time step in
which it is displayed. The parameter may, as an example, display the average over the period,
and therefore the only time display that makes sense is the name of the period.
You can also control the format of the time display, and you can specify whether time elements that
are static over the
Times Options
Available
Property Description
options
Short Select the date and time format to use for the tick label. It is
Medium recommended that you try the various options to see how they work
Long for various intervals and periods. As an example, Short will display
Format
the month number (1), Medium will display the month with three
letters (Jan), while Long will display the entire month name
(January).
Always on/off Select whether to display interval names or not. If this option is
show selected, the time table will always display interval names, even
interval when all the parameters are defined using the First summary type.
names
on/off Select whether time information that is common for all tick labels
Show static
should be shown or not. If, say, the simulation runs for one full year,
time
selecting this option will display the year in the times, while
elements
deselecting it will remove the year.
The order of the parameters will decide the order in which they are displayed in the time table. The
topmost parameter is displayed to the left in a vertical table, or on top in a horizontal table.
To change the order of the parameters:
1. Double-click the control that you wish to change, or click Properties.
2. Select the Parameters tab in the property dialog box.
3. Sort the parameters in the list by selecting them and using the Up and Down buttons.
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
The Time Table Control allows you to specify a report interval for the control. This report interval is
used as the summary period for the parameters.
To change the report interval and summary period of the Time Table:
1. Double-click the control that you wish to change, or click Properties.
2. Select the General tab in the Properties dialog box.
3. Under Report Interval, specify the report interval and summary period to be used.
- 371 -
4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.
The report interval is specified using an integer and one of the predefined intervals in the box. The
Time Step, Minor Interval, and Major Interval refer to the settings specified in the Simulation Settings
dialog box, under the Report tab.
- 372 -
Working with Risk Assessment
A risk assessment analysis will provide you with a probability distribution of how the variation in
assumptions will affect the value of effect variables.
Since the various Risk Assessment variables are only available internally in the task, all presentations
for the task must be created in private diagrams.
- 373 -
Sample methods
The Risk Assessment task uses sophisticated sampling methods to produce sample value sets for the
selected assumptions defined by probability distributions, before simulating the model. This is
required to approximate the probability distribution function of the selected effects.
Latin Hypercube is the recommended method, but you can also use the Monte Carlo method. While
the Monte Carlo method is a simple random sampling method, Latin Hypercube combines random
sampling with factorial design.
Uncertainty in your models can relate to uncertainty about the future, and to uncertainty about the
cause-and-effect relationships between elements of the system you are modeling. The Risk
Assessment task shows how sensitive a model is to changes in its assumptions.
Assumption variables must be changeable variables. Assumptions can be defined as fixed values or
probability distributions. The latter allows you to specify the probabilities of possible values to occur.
Effect variables must be computed variables of which you want to study the effects of uncertainty in
the selected assumptions.
The Risk Assessment task produces distributions of values for the effect variables. You can study the
probabilities of results in different ranges, and below or above certain percentiles. This way you can
test the model's robustness to variations in assumptions, and you can see the likelihood (risk) of
undesirable results, as well as favorable results (opportunities).
Example of use
The effect of motivation on productivity and the effect of price on demand could be typical
assumptions of a model. Many models will include relationships and variables that are difficult to
define accurately, and you must make "guesstimates" in order to complete the models. By using the
Assess Risk task, you can study how sensitive your model is to changes in these assumptions.
Being an inventory manager, it is your policy to keep the inventory equal to the expected demand plus
some extra. Now you want to assess the risk of running out of inventory due to uncertainties regarding
delivery times for supplies.
Let us say that you make the following choices for assumptions and effects:
! assumption - inventory coverage (fixed value)
! assumption - demand pattern (distribution)
! assumption - average delivery delay for supplies (distribution)
! effect - cost of lost sales plus cost of inventory
The Risk Assessment task now produces distributions of values for the effect variables.
Risk Assessment has been used for example to find what levels of production, staffing and capital
costs allow minimal inventories, and to show which investments maximize profits without hurting the
cash flow.
You can easily experiment with future scenarios and develop the best long-term strategy.
- 374 -
The Risk Assessment Process
The graphical overview below explains how the Risk Assessment task in Studio works.
The guidelines below outlines the main operations of how to use the Risk Assessment task in Studio.
For further details, please refer to the appropriate sections in the help system or use the links below to
jump directly.
Open the simulation project that contains the component that you wish to perform the Risk
Assessment on.
You add the Risk Assessment task to the component by right-clicking the component in the
Project Window, point to Add Solver Task, and select Risk Assessment on the
submenu. The Risk Assessment task will be added to the component as a separate
simulation task. The simulation runs performed on this task will not interfere with the
normal simulation runs in other simulation tasks on your component.
You select the assumptions and effects in the Risk Assessment Variables window,
available by double-clicking Risk Assessment Variables in the Project Window.
- 375 -
Assumption variables must be changeable variables. Assumptions can be defined as fixed
values or probability distributions. The latter allows you to specify the probabilities of
possible values to occur.
Effect variables must be computed variables of which you want to study the effects of
uncertainty in the selected assumptions.
The simulation settings for the Risk Assessment task includes two parts: The simulation
setting for each run (which is the same as the simulation settings for a normal simulation)
and the Risk Assessment specific settings for how to control the multiple runs associated
with a Risk Assessment analysis.
The Risk Assessment analysis allows you to select between two different sampling
methods: Latin Hypercube and Monte Carlo. You can also select the number of generations
to generate, and how to record the resulting time series from the analysis.
The Risk Assessment data are only available within the Risk Assessment task of the
component. The presentation diagrams for your analysis must therefore be created in a
private diagram for the task itself. These are available by double-clicking Private
Diagrams in the Project Window.
Use the selection of available controls to present the results from the analysis.
When you click Play, the Risk Assessment will start running its batch of simulation runs.
You will see the run number and the simulation status of the current run in the status bar.
When all runs have finished, the results will be presented in the controls.
The Monte Carlo sampling method uses computer-generated random numbers (like a Monte Carlo
roulette wheel) to produce sets of values. Their probability is determined by the probability
distribution function chosen for the particular variable.
Note! Note that the Monte Carlo method needs a higher number of samples than the Latin
Hybercube method, to properly approximate the probability distribution of the assumptions.
The Latin Hypercube sampling technique is the recommended sampling method, because it is tenfold
better than the Monte Carlo technique. It combines the advantages of simple random sampling (as
used in the Monte Carlo technique), and full factorial designs, which means that all areas of the
sample space are represented. The probability distribution of each assumption is segmented into a
number of non-overlapping intervals with equal probability. For each assumption, a sample is
- 376 -
generated from each interval.
Tip! When you use this sampling method, it is recommended the number of generations is 40 in
the final run. A lower value may produce a rougher approximation of the probability
distribution, while a higher value requires more processing time. It might be wise, however, to
use a lower number in the test runs.
Note! Powersim Studio assumes that the assumptions are independent of each other, i.e. that
there is no correlation between them.
The Risk Assessment task uses sophisticated sampling methods to produce sample value sets for the
selected assumptions defined by probability distributions, before simulating the model. This is
required to approximate the probability distribution function of the selected effects.
Latin Hypercube is the recommended method, but you can also use the Monte Carlo method. While
the Monte Carlo method is a simple random sampling method, Latin Hypercube combines random
sampling with factorial design.
Before you can start your Risk Assessment analysis, you have to select the variables that you wish to
study. You must select one or more assumption variables and one or more effect variables.
- 377 -
Assumptions are changeable variables beyond your control. Changeable variables are model
variables that the Risk Assessment task can alter during the execution of the simulation runs.External
factors that influence a model are assumptions if they are modeled as constants rather than computed
variables. It is quite common that there is uncertainty around the value of assumptions. Inflation rate
and interest rate are typical examples of assumptions. Assumptions can take place at any time in the
simulation.
Decisions are assumptions with fixed values, and are variables that you can directly influence. You
can, for example, decide upon the production volume of a new production line or the salary of a group
of employees. At the policy level, decisions are parameters to policy procedures. Decisions can take
place at the start or at a specified time of the simulation. (Decisions are a conceptual term in Studio,
and there is no distinction between decisions and assumptions in the software.) Note that the initial
value of a level can be controlled by the task, and it can therefore be selected as an assumption with a
fixed value.
Effects are computed variables for which you want to study the uncertainty distribution in the Risk
Assessment task. Computed variables are variables that the Risk Assessment task cannot alter during
the execution of a task. Levels that accumulate flows and auxiliaries that depend on other variables
belong to this category.
The table below describes the probability distributions that you can use in the Risk Assessment task in
Powersim Studio.
Normal Distribution
The normal distribution is bell-shaped. The normal distribution is very
useful, because many random variables of practical interest are normal or
approximately normal or can be transformed into normal random variables
in a relatively simple fashion. In addition, the normal distribution is a
useful approximation of more complicated distributions. You are requested
to enter the expected (mean) value, which determines where the peak
occurs, and standard deviation, which determines the width and height of
the peak.
Parameters: Mean, Standard Deviation.
Truncated Normal Distribution
Identical to the normal distribution, but you can limit the values at both
ends of the distribution. Use it when you wish to avoid values above or
below a certain limit, for example to avoid negative values for a population
variable. You are requested to enter the expected value and standard
deviation, and to set a lower/upper limit for values to be included.
Parameters: Mean, Standard Deviation, Lower Limit (optional), Upper
Limit (optional).
Uniform Distribution
In the uniform distribution, all values within the specified range are
equally likely to occur. You are requested to enter minimum and
maximum values for the range.
Parameters: Minimum, Maximum.
- 378 -
Triangular Distribution
For the triangular distribution, you are requested to enter minimum,
maximum and peak values.
Parameters: Minimum, Peak, Maximum.
Exponential Distribution
For the exponential distribution, you are requested to enter a location input
value, My (µ), which must be a positive value that shifts the curve along
the horizontal axis, and scale input value, Beta (ß), which determines the
shape of the curve. You can, for example, use this distribution when
describing lifetime probability for a device.
The general form of the exponential probability density function is:
When you have opened a model and added a Risk Assessment task to the component you wish to
study, you can create assumption and effect variables.
1. Double-click Risk Assessment Variables in the Project Window. The Risk Assessment
Variables window will open.
2. Right-click the Assumption node and select Add Assumption... on the shortcut menu to add an
assumption variable.
or
Right-click the Effects node and select Add Effect... to add an effect variable.
3. Select the variable you wish to select in the dialog box, and click OK to make a selection.
The selected variable will appear under the appropriate node in the treeview. The various properties of
the variable will be available in the treeview, too, so you can use the treeview to define the variable to
suit your analysis.
When you want to include uncertainty in your task, you can specify a statistical distribution instead of
a fixed value for one or more assumptions. Studio features five different distributions that you can
select between. These are explained in detail below.
To define an assumption with a probability distribution in the treeview:
1. Select the assumption you wish to define in the Risk Assessment Variables window.
2. Select the time at which the assumption should be applied in the Apply Time column of the
treeview. To apply the assumption at the start of the simulation, enter the value Start or right-click
and select Apply at Start Time on the shortcut menu. Alternatively, you can enter a time at
which the assumption should be applied. You will be warned if you try to enter a start time that is
beyond the time interval of the simulation.
3. Right-click the Distribution cell of the treeview, click Distribution on the shortcut menu, and
select the probability distribution you wish to use on the submenu. The treeview is updated with
properties corresponding to the selected distribution.
- 379 -
4. Select the various properties, such as Mean, Standard Deviation, etc., in the treeview, and change
their values in the Value column of the treeview.
To define a probability distribution for an assumption in the Properties dialog box:
1. Right-click the assumption you wish to define in the Risk Assessment Variables window, and
select Properties on the shortcut menu.
2. Select the Assumption tab.
3. Enter the time at which the assumption should be applied in the Apply Time field. To apply the
assumption at the start of the simulation, enter the value Start or use the spin button to select it.
Alternatively, you can enter a time at which the assumption should be applied. You will be
warned if you try to enter a start time that is beyond the time interval of the simulation.
4. Select the probability distribution to use in the Distribution Type list. The available parameters in
the Distribution Parameters list will be automatically updated to correspond to the selected
distribution.
5. Change the available parameters for the distribution according to your preferences.
6. Click OK to save the changes, or click Apply to save the changes without closing the dialog box
Assumptions with a fixed value can be considered as decisions in the analysis. These are parameters
that you can control fully in your system, and you can yourself decide their values. Decisions can
occur at any time during the simulation.
To define a fixed value for an assumption in the treeview:
1. Select the assumption you wish to define in the Risk Assessment Variables window.
2. Select the time at which the assumption should be applied in the Apply Time column of the
treeview. To apply the assumption at the start of the simulation, enter the value Start or right-click
and select Apply at Start Time on the shortcut menu. Alternatively, you can enter a time at
which the assumption should be applied. You will be warned if you try to enter a start time that is
beyond the time interval of the simulation.
3. Right-click the Distribution cell of the treeview, click Distribution on the shortcut menu, and
select Fixed Value on the submenu.
4. Select the Fixed Value property and enter the correct value in the Value column of the treeview.
To define a fixed value for an assumption in the Properties dialog box:
1. Right-click the assumption you wish to define in the Risk Assessment Variables window, and
select Properties on the shortcut menu.
2. Select the Assumption tab.
3. Enter the time at which the assumption should be applied in the Apply Time field. To apply the
assumption at the start of the simulation, enter the value Start or use the spin button to select it.
Alternatively, you can enter a time at which the assumption should be applied. You will be
warned if you try to enter a start time that is beyond the time interval of the simulation.
4. Select Fixed Value in the Distribution Type list.
5. Enter the value of the assumption in the field under Distribution Parameters.
6. Click OK to save the changes, or click Apply to save the changes without closing the dialog box
- 380 -
Specify an Effect Variable
The Risk Assessment task will produce probability distributions for the various effect variables that
you have selected. These distributions are produced by varying the assumptions according to their
defined probability distributions, and then record the resulting time series from the various runs.
These time series are computed at the end, and you can have Studio compute various estimates from
the data. You select which estimates to compute for each effect separately.
You can record the time series for the effects in different ways. You can either record them in the
traditional way, yielding one recorded value per time step. You can also summarize the data over an
interval. You can select several different summary types, and each effect may use a different
summary type (if required). The summary interval is selected in the Simulation Settings dialog box.
Note! The same interval is used for all effect variables. Thus, you can either sample all the
effects with maximum resolutions, or you summarize all effects over the same period. The
summary type is individual for each effect, though.
or
1. Open the Risk Assessment Variables window by double-clicking the node in the Project
Window.
2. Right-click the variable you wish to delete in the list, and select Delete on the shortcut menu.
Results from a Risk Assessment are most often presented using High-Low Charts and High-Low
Tables. These presentations can be created using time graphs and time tables. It is also possible to
model structures that can be used to present histograms by the use of chart graphs.
- 381 -
Private Diagrams
The Risk Assessment variables will only be available inside the task itself, and you must therefore use
Private Diagrams to set up data presentations for these analyses. Private Diagrams are so-called
Interaction Diagrams, which can only be used for data input and output. You can use any presentation
objects at your disposal in Studio.
Note! Shared diagrams are Constructor diagrams, and they are identical in all simulation tasks
of a component. A Constructor diagram can contain any available symbol, such as variables,
flows, and controls. Private diagrams, on the other hand, are Interaction diagrams, and they
only exist within the simulation task where they were created. An Interaction diagram can only
contain presentation symbols, such as frames, hyperlinks, and controls.
High-Low charts
High-low charts display graphs showing bands of the lowest to the highest output values over time, as
affected by variation in assumption values. High-Low charts are created in Studio by using the
standard Time Graph control and using different line and fill colors for the different estimates.
The bands of the high-low chart is created by coloring the area between pairs of an effect's
estimates.Bands can be created by using these pairs: High/low, 5%/95%, 10%/90%, and 25%/75%.
The illustration below shows one such high-low chart where all of these pairs have been used. The red
line in the center is the effect's average value.
The High-Low chart shows the bands of the lowest to the highest output values over time. In this
graph, the yellow band shows 0-100%, the blue band shows 10-90%, the green band shows 25-75%,
while the red line shows the 50% Percentiles.
The table below shows line and fill colors of the various parameters to achieve the display above.
Parameter Line color Fill color
High Orange Yellow
90% Percentile Blue Cyan
75% Percentile Dark green Light green
50% Percentile Red None
25% Percentile Dark green Cyan
Low Orange White (use the background color of the graph area).
- 382 -
High-Low tables
The High-Low tables shows the time series for the various effect estimates. It is achieved simply by
adding a time table to your diagram and selecting the desired estimates as parameters.
Histograms
The histogram displays the number of occurrences of different values for the given effect. The total
number of occurrences equals the number of samples specified in the method tab. Powersim Studio
doesn't feature a specialized histogram control. However, you can present your data in a histogram by
using a simple model structure and a Chart control. The model structure is presented below.
range Histogram = ... // A range defining the number of categories for your histogram
// By
var Parent~Input = ... // The Input variable to create a histogram for.
// This variable is defined outside the submodel
// (on the parent level).
const 'Category Size' = ... // The size (or width) of the histogram categories
// The variable should have the same unit as
// Parent~Input
const Offset = ... // The offset of the first category (0 + Offset).
// The variable should have the same unit as
// Parent~Input
level Histogram = 0
dim Histogram = Histogram
aux Category = // The variable uses the Zero Order Immediate integration setting
FOR(i=Histogram |
IF(TIMEIS(STOPTIME),
IF(FLOOR((Parent~Input-Offset)/'Category Size',1)=NUMERICAL(i), 1, 0)
,0) //End IF
) //End FOR
integration Category = Zero Order Immediate
aux Reset = IF(RUNINDEX=1,Histogram,0)
- 383 -
integration Result = Zero Order Immediate
The level Histogram can now ben displayed in a chart control You control the display of the
histogram by several factors, such as:
! Define Category Size corresponding to the output range of your effect.
! Define Offset corresponding to the output range of your effect.
! Define the Histogram range using an enumeration range, where the name corresponds to your
categories.
The illustration below shows how a histogram can be presented.
The submodel has been defined with a Category Size of 5000USD and an Offset or 50000USD. The
range Histogram has eight elements, with the name '50-54', '55-59', etc.
High-low charts display graphs showing bands of the lowest to the highest output values over time, as
affected by variation in assumption values. High-Low charts are created in Studio by using the
standard Time Graph control and using different line and fill colors for the different estimates.
Note! If you are creating a high-low chart for a Risk Assessment effect, you must create the
graph in a Private Diagram, or else the effect will not be available to the graph.
Note! If you are working with a Risk Assessment presentation, remember that you must perform
- 384 -
one analysis before the graph will be drawn.
The High-Low chart shows the bands of the lowest to the highest output values over time. In this
graph, the yellow band shows 0-100%, the blue band shows 10-90%, the green band shows 25-75%,
while the red line shows the 50% Percentiles.
The table below shows line and fill colors of the various parameters to achieve the display above.
Parameter Line color Fill color
High Orange Yellow
90% Percentile Blue Cyan
75% Percentile Dark green Light green
50% Percentile Red None
25% Percentile Dark green Cyan
Low Orange White (use the background color of the graph area).
The High-Low tables shows the time series for the various effect estimates. It is achieved simply by
adding a time table to your diagram and selecting the desired estimates as parameters.
To create a high-low chart in Studio:
1. Insert a Time Table control in your diagram by clicking Time Table and drag the object to the
desired size.
2. Right-click the time graph, select Properties on the shortcut menu and select the Parameters
tab.
3. Select the parameters you wish to display in the high-low chart.
4. Use the Down and Up to sort the parameters the way you prefer.
5. Click the General tab. You can control the reporting interval under Report Interval. You can select
between several available intervals.
6. Click Apply to save the changes, or OK to save the changes and close the dialog box.
- 385 -
The time table shows the time series from a Risk Assessment analysis. It shows the Average, Highest
and lowest values, as well as the 25% and 75% percentiles.
Create a Histogram
The histogram displays the number of occurrences of different values for the given effect. The total
number of occurrences equals the number of samples specified in the method tab. Powersim Studio
doesn't feature a specialized histogram control. However, you can present your data in a histogram by
using a simple model structure and a Chart control.
We have included the Histogram submodel as a component in the ra_presentation.sip project of the
Learning Lab, so you can easily utilize it in your Risk Assessment projects. The few steps below
shows you how to use it.
To add a histogram to your simulation project:
1. Open the simulation project where you want to utilize the Histogram submodel.
2. Open the diagram where you want to insert the submodel.
3. Click the small arrow next to Copy Component as Submodel and select Browse for File to
Copy from... on the submenu.
4. Click inside the diagram where you want to place the submodel.
5. Browse to the folder where you installed Powersim Studio, then go to the Samples\Bits\ folder.
Select ra_presentation.sip
6. Select Histogram in the Copy Component dialog box.
7. Drag a link from the variable you wish to create a histogram for and to the submodel.
8. Select the Histogram.Input variable in the Define Child Variable dialog and click OK.
9. You have to set two more variables inside the submodel; Category Size and Offset. You can either
set them directly in the Equations view by defining them, or you can insert two constants in your
diagram, drag links to the Histogram submodel, and connect them to the corresponding variables
inside Histogram. Both these variables need the same unit of measurement as the variable you
wish to chart.
10. Insert a Chart Control on your diagram. Add the variable Histogram.Histogram as a parameter for
the chart. Format it to suit your preferences.
11. If you need more categories in your histogram, you can increase the number of elements in the
Histogram range, which you will find in Global Ranges. The default value is 8.
- 386 -
Tip! You can also get category names in the histogram. By deleting the existing range named
Histogram and then creating a new enumeration range by the same name, the histogram will
get the range element names along the category axis.
The illustration below shows how the finished histogram may look.
The submodel has been defined with a Category Size of 5000USD and an Offset or 50000USD. The
range Histogram has eight elements, with the element names '50-54', '55-59', etc.
- 387 -
Datasets in Powersim Studio
Datasets represent a connection between data from external files or data sources and the variables in
your simulation. Datasets are flexible, and allow you to both import input data to variables and export
simulation results. You can even perform a combination of the two, where you import initial values
and export simulation results. Datasets are managed in the Project Window in Powersim Studio. From
the Datasets entry you are allowed to add new datasets, remove them and define them.
The dataset contains connections between the data source and one or more variables in your
simulation project. These connections can go both ways; the same dataset can very well be used to
import input data into some variables, while exporting simulation results from others. In addition to
handling data input and output, datasets are also capable of importing range, unit and time definitions.
About Datasets
Datasets allow you to transfer data between a simulation and a "value store," such as SEM-BPS,
Microsoft Excel spreadsheets, or internally in Studio. A dataset supports bidirectional transfer,
making it easy to export the time series of a model variable to the value store, while at the same time
receiving time series to another model variable.
A dataset contains variables, in much the same way as a component (or model, if you like) does.
Variables in the model and the dataset have defined transfer directions, and variables can be
interconnected if their transfer directions correspond to each other — a model variable with a transfer
direction of out can connect to a dataset variable with a transfer direction of in). To be able to connect
to each other, the variables must also have compatible type, dimension, and unit definitions.
Architecture
The dataset definition contains the definition of the variables, history for the variables (if available),
and information about how these histories are being transferred to external data sources (except the
Studio dataset, which stores its histories internally in Studio). Most datasets will keep the last saved
data in its cache, allowing you to run the simulation even if a connection to the external data source is
not available.
The connection between the dataset and the simulation is made in the Co-models View. When a
connection is made, an instance of the dataset is created. This instance keeps a copy of the history for
each variable, provided one exists. The transfer setting of the connection controls when new data in
the dataset instance is saved back to the main dataset. In Automatic mode, new data is saved
immediately, while in Manual mode, you control when the data is written back to the main dataset
- 388 -
yourself.
When the connection between the simulation and the dataset is made, you can connect the model
variables to the dataset variables. This connection can be made automatically, if you wish, or you can
define them manually by drag and drop. The transfer direction of the dataset and model variables
must match each other in order for a connection to be established.
Note! You can only create dataset connections at the start of the simulation, since the value of
model variables may change significantly as you start to import data from the dataset (rather
than calculating the imported model variables internally).
During a simulation, a time series is generated for the model variable. This time series is transferred
continuously to the connected dataset variable in the co-models view. If the dataset is set to
Automatic transfer, the co-models dataset variable will transfer its time series to the main dataset at
the end of the simulation. If the dataset is set to Manual transfer, you decide yourself when the
transfer from the co-models dataset to the main dataset is made. You can only save data at the end of
the simulation, however.
Dataset Overview
The relationship between simulations and datasets. The connection between the simulation and the
dataset is set up in the Co-models view. This is also where the connections are established on a
variable to variable level.
- 389 -
About Dataset Variables
Dataset variables are counterparts to ordinary model variables. They have a data type, dimension, unit
of measurement, and a defined transfer direction. However, instead of having a definition that
controls the way the variable is computed as the time advances - as the a model variable has - a
dataset variable has a history of values. This history can be recorded from a simulation, be data from a
real system, or be computed using other software.
Dataset variables can be created in two ways. You can create and define them manually in the
dataset's view, or you can create them on basis of existing model variables. The last method enables
you to quickly connect your model variables to datasets and have their time series saved in external
data stores.
Unlike model variables, dataset variables are only treated as continuous variables. You should
therefore take care when exporting or importing model variables using either Zero Order or Zero
Order Immediate integration settings. These will be exported to and from the dataset as ordinary
continuous variables.
Just like model variables, dataset variables have a defined dimension. The dimensions are specified in
the same way as for model variables, using either named or unnamed numerical subranges, or
enumeration ranges or subranges.
A connection can only be established between a model variable and a dataset variable if the
dimension of the two have matching (identical) dimensions.
Note! If you use named ranges (either numerical or enumeration ranges), you can only use
ranges that are defined in Global Ranges.
- 390 -
Common or Individual Dimensions
There are two ways of setting dataset variable dimensions in Studio. You can either set the dimension
for each individual dataset variable, or you can set a common dimension for all the variables in the
dataset. If you set a common dimension for all dataset variables, the dimension definition is entered
on the dataset itself rather than on each variable individually. When changing the dataset's dimension
definition, the change is immediately reflected for all the dataset variables as well.
Note! Some datasets support both individual and common dimensions, while other datasets
only support one of them. This will be apparent when working with the dataset in question.
Variable history is recorded in the dataset connection per dataset variable. The history is summarized
over a given period, and you can select the summary type for each dataset variable individually. The
available summary types are:
! First: Records the first value of the sample period;
! Last: Records the last value of the sample period;
! Minimum: Records the minimum value during the sample period;
! Maximum: Records the maximum value during the sample period;
! Average: Records the average value over the sample period;
! Accumulated: Records the accumulated value over the sample period.
Data is transferred on two different levels when using datasets in Studio. Data are transferred between
the data store and the dataset connection, and data are transferred between model and dataset
variables.
Dataset transfers
The data transfer between the dataset connection and the data store can be set to Automatic or
Manual.
For automatic transfers, data is read from the data store when the simulation is initialized. All data
from the dataset are read at once, and stored in the data connection. When the simulation is finished,
the data is transferred back to the data store from the data connection.
- 391 -
For manual transfers, you control the data transfer between the data connection and the data store
yourself. Data can only be loaded at the start of the simulation, and data can only be saved at the end
of the simulation. However, in this transfer mode you don't have to load or save data for every
simulation, but choose yourself when you want to transfer data to and from the data store.
Variable transfers
Data transfer on the variable level occurs continuously throughout the simulation. If the dataset
contains data with a lower resolution than the simulation requires, data will be interpolated for the
intermediate data points.
The data transfer on this level is performed between the simulation and the dataset connection, and
doesn't involve the external data store at all, during the simulation.
Create a Dataset
You can add and delete datasets from your project in the Project Window.
1. If the Project Window is not open, open it by clicking Project Window on the View menu.
2. Right-click Project in the Project Window, and select Add Dataset on the shortcut menu.
Select the dataset you wish to add on the submenu.
- 392 -
The dataset you added will appear in the Project Window.
Tip! You can organize the content of your project in folders in the Project Window. Simply
right-click Project in the Project Window, and select New Folder on the shortcut menu
to create the folder. You can then drag the components and datasets into the folder.
A dataset connection represents the physical connection between a simulation and a data storage. The
connection details for the data storage are defined in the dataset definition.
Importing data from an external data source (rather than calculating the variables inside Studio) will
significantly change the behavior of the model. It is therefore not possible to create dataset
connections when the simulation has started. If you have started (or finished) a previous simulation
run, the simulation must be reset before you can create new dataset connections.
Dataset connections are managed in the Co-models view.
1. If the simulation is not at start time (initial time), reset it by clicking Reset Simulation in the
toolbar, or by hitting Ctrl-R.
2. If the Co-models view is not open, expand the nodes in the Project Window until the Co-
models node for the current simulation is visible.
3. Open the Co-models view by double-clicking the node, or right-clicking it and select View
on the shortcut menu.
4. Right-click anywhere inside the Co-models view, and select Create Dataset Connection. Select
the dataset you wish to connect on the submenu.
The dataset you selected will appear below the Main node, as illustrated below.
When a dataset connection has been made in the Co-models view, the connection will appear below
the main model in the list.
You can create dataset variables by dragging their model variable counterparts onto either the
Dataset connection node in the Co-models view, or onto the Dataset node in the dataset's
view. The difference is that if you drop the model variable on the dataset connection, a connection
will also be established at the same time.
Model variables can be dragged from the Diagrams view, the Equations view, or from the Main
node in the Co-models view.
Tip! Before performing the drag-and-drop operations, we recommend that you arrange the
views you need to use using the Window menu. This makes it easy to drag from the source and
- 393 -
drop it on the correct target.
Tip! If you drag the variable using the right mouse button, a shortcut menu will appear when
you have dropped the variable, allowing you to select the transfer direction of the model and
dataset variables.
A new dataset variable with the same type, dimension, and unit is created. If the variable was dropped
on the Main node in the Co-models view, a connection is also established.
When manipulating model or dataset variables by drag-and-drop, a defined transfer direction will
never be altered. Thus, if you drag-and-drop a model variable that you already set the transfer
direction for, the dataset variable will automatically get the opposite transfer direction. Likewise, if
the a dataset variable existed (with the same name as the model variable), and the model variable
didn't have a defined transfer direction, the model variable would get the opposite direction of the
dataset variable.
You are allowed to drop a selection of variables on the drop targets, as well. Each variable will be
handled individually, and dataset variables are created to match the properties of the model variables.
Note! Unlike model variables, dataset variables are only treated as continuous variables. You
should therefore take care when exporting or importing model variables using either Zero
Order or Zero Order Immediate integration settings. These will be exported to and from the
dataset as ordinary continuous variables.
- 394 -
You can define the dataset variable in the different columns in the Dataset view. You can also access
most of the properties in the Properties dialog box.
Note! You can set all dataset variables to have the same dimension by right-clicking the
Dataset node and selecting Common Dimensions on the shortcut menu. In this case you
must specify the dimension in the Dimension entry for the Dataset node.
Note! Unlike model variables, dataset variables are only treated as continuous variables. You
should therefore take care when exporting or importing model variables using either Zero
Order or Zero Order Immediate integration settings. These will be exported to and from the
dataset as ordinary continuous variables.
Model and dataset variables are connected in the Right-click the Co-models view. The connection
can be established in several ways. You can auto-connect all the variables of the dataset at once, auto-
connect a single variable at a time, or make the connection by drag-and-drop.
Note! The procedures below assume you have already opened the Co-models view (double-
click the node in the Project Window), and that a dataset connection is already established.
- 395 -
connected), and there exists model variable counterparts (with the same variable name) for all the
dataset variables.
Tip! If you use the right mouse button when dragging and dropping, a shortcut menu appears
when you have dropped the variable, allowing you to select the action yourself. If you use the
left mouse button when dragging and dropping, the default action will be executed.
The transfer direction of model and dataset variables will be set automatically if the variables are
connected or created by drag and drop. You may also defined these transfer directions manually,
should you wish to.
Note! If you change the transfer direction of variables that are already connected, the
connection will automatically be broken.
- 396 -
To set the transfer direction for a dataset variable
The transfer direction for a dataset variable can only be set in the given dataset's view.
1. Right-click the dataset variable you wish to set the transfer direction for.
2. Select Transfer Direction on the shortcut menu, and select the direction to use on the submenu
that appears. Options are In, Out, and Out-In.
1. Right-click the variable you wish to set the transfer direction for.
2. Select Advanced on the shortcut menu.
3. Select Transfer Direction on the submenu, and then select the direction to use. Options are In,
Out, and In-Out.
All transfer directions are not compatible with all model variable types. The table below shows the
different transfer directions that are allowed for each variable type.
Variable Type Allowed transfer directions
Level Out; In-Out
Auxiliary In; Out
Constant In; Out; In-Out
The dataset variables must share the same dimensionality as the model variables to which they are
connecting. Sometimes, you will experience that all the model variables have the same dimension,
and it is convenient in this case to make all the dataset variables have the same dimension, too. In
datasets this is achieved by enabling the Common Dimensions option.
1. Right-click the Dataset node in the Dataset view, and select the Common Dimensions option
on the shortcut menu.
2. Select the Dimension entry in the dataset view next to the Dataset node.
- 397 -
3. Hit F2, and enter the dimension definition you want to use for all the dataset variables.
4. Hit Enter to save the definition.
When the Common Dimensions option is enabled, all the dataset variables will use the dimension
definition entered on the dataset node. This makes it easy to change the dimensions of all the dataset
variables in one operation.
Most datasets are recorded with a lower resolution than the simulation is run on. In this case you can
select how the dataset variable should be summarized over the sampling period of the dataset. You
can select between different summary types, as shown below.
! First: Record the variable's value at the start of the summary period.
! Last: Record the variable's value at the end of the summary period.
! Minimum: Record the variable's minimum value over the summary period. This summary type is
only available for dataset variables that have the transfer direction in in the dataset.
! Maximum: Record the variable's maximum value over the summary period. This summary type is
only available for dataset variables that have the transfer direction in in the dataset.
! Average: Record the variable's average value over the summary period.
! Accumulated: Record the variable's accumulated value over the summary period. This is identical
to letting the variable control a flow into a level, and then report the level's value.
The dataset variable must have a dimension definition that is compatible with the dimension of the
model variable it is going to connect to. The dataset variable's dimension is defined in the dataset's
view.
1. Right-click the dataset variable you wish to define and select Properties on the shortcut menu.
2. Enter the dimension definition in the Dimension box.
3. Click Apply to save the changes, or OK to save the changes and close the dialog box.
You can also define the dimension directly in the dataset view under the Dimension column:
1. Double-click inside the Dimension cell of the column view for the appropriate dataset variable, or
select the cell and hit F2.
2. Enter the dimension definition, and hit Enter.
Tip! If the Dimension column is not visible, right-click the column headers, and select it in the
- 398 -
shortcut menu. There are several columns available for you.
You can disconnect dataset and model variables in the Co-models view.
1. Right-click the dataset or model variable you wish to disconnect, and select Disconnect on the
shortcut menu.
The connection between the two variables will be lost, but no changes will be done to the model
and/or dataset variables.
Note! To be able to connect the variable to a variable in a component, they must both share
exactly the same name.
Rename a Dataset
To rename a dataset:
1. Locate the dataset in the Project window, by expanding the Datasets entry
2. Select the dataset you want to rename and hit F2 to rename it. Alternatively, click the entry twice
(not too fast).
3. Enter the new name for the dataset, and hit Enter .
- 399 -
Rename a Dataset in the Co-models View
Note! Any data that are not transferred to an external data store will be lost when a dataset
variable is deleted and the project is saved. (You can undo the operation without loosing data.)
1. Open the Dataset view of the dataset you wish to work on.
2. Right-click the dataset variable(s) you wish to delete, and select Delete on the shortcut menu.
The dataset variable will disappear from the dataset. If it was already connected to a model variable,
the connection will obviously be lost.
Delete a Dataset
You can add and delete datasets from your project in the Project Window.
1. If the Project Window is not open, open it by clicking Project Window on the View menu.
2. Right-click the dataset you wish to delete, and select Delete on the shortcut menu.
The dataset you will disappear in the Project Window.
If the transfer mode for a dataset is set to Automatic, the transfer between the external data store and
the dataset connection will be performed automatically when needed.
If the transfer mode for the dataset is set to Manual, on the other hand, you must control the data
transfer yourself. This is done inside the simulation, by selecting External Data on the
Simulation menu, or by using the shortcut menu on the dataset connection in the Co-models view
itself.
Note! You are only allowed to load data at the start of the simulation!
- 400 -
1. Select External Data on the Simulation menu, and select Load... on the submenu.
2. Select the dataset(s) you wish to load in the Load External Data dialog box. Datasets that have
changed since the last time you saved will be marked with an asterisk (*).
3. Click OK to save data to the external data store.
Some datasets allow you to change settings for the external data store, such as version or package
information in the SEM Dataset. You can access these settings by clicking … for the relevant
dataset
You can also load the history for the dataset connection itself in the Co-models view.
1. Right-click the dataset you wish to load, and select Load Data on the shortcut menu.
Save a Dataset
If the transfer mode for a dataset is set to Automatic, the transfer between the external data store and
the dataset connection will be performed automatically when needed.
If the transfer mode for the dataset is set to Manual, on the other hand, you must control the data
transfer yourself. This is done inside the simulation, by selecting External Data on the
Simulation menu, or by using the shortcut menu on the dataset connection in the Co-models view
itself.
Note! If the dataset receives data from the simulation (contains connected dataset variables
with a transfer direction set to in), you can only save data at the end of the simulation!
1. Select External Data on the Simulation menu, and select Save... on the submenu.
2. Select the dataset(s) you wish to save in the Save External Data dialog box. Datasets that have
changed since the last time you saved will be marked with an asterisk (*).
3. Click OK to save data to the external data store.
Some datasets allow you to change settings for the external data store, such as version or package
information in the SEM Dataset. You can access these settings by clicking … for the relevant
dataset
You can also save the history for the dataset connection itself in the Co-models view.
1. Right-click the dataset you wish to load, and select Save Data on the shortcut menu.
If the dataset allows it, you can edit the history of a dataset variable in the Co-models view. The
dataset will only allow you to edit a dataset variable's history if the Allow Manual Edit option is
enabled, the dataset variable has a transfer direction of out, and the transfer mode for the dataset
connection is set to manual.
- 401 -
4. Right-click the Dataset connection node, and select Transfer on the shortcut menu. Select
Manual on the submenu.
Note! If you want to be able to save the edited history you must also select the Allow Write-
back option.
An external data history can be imported to a dataset variable in the Studio Dataset. You can import a
history in both the Studio Dataset view or in the Co-models view. While you can import a
history for any variable at any time in the Studio Dataset view, certain limitations apply to
importing histories in the Co-models view. In the latter case, you are only allowed to import a
history at the start of the simulation, when the dataset supports manual edit, the transfer mode for the
dataset connection is set to manual, and the dataset variable itself has the transfer direction set to out.
When importing data from the clipboard or a file, the data must be saved without times and headers.
The data must only contains values separated by delimiters. You can control the orientation of the
import in the Import History dialog box.
- 402 -
orientation of the data array, select the Flipped option.
7. If the history you are importing are smaller than the dataset variable's history (times and/or
dimensions), you can control where in the variable's history the data is inserted.
1. Select the dimension at which to start the import under Element Offset.
2. Select the time period at which to start the import under Time Offset.
8. When you're satisfied with your selections, click OK to import the history.
Note! This functionality is only available to datasets that display the History property page for
the dataset variables in the Co-model view of the simulation.
You can export data from both the Studio Dataset view and the Co-models view. Data can only
be exported for each dataset variable individually. When exporting data, you can select to include
header and time information with the data. You can also specify the orientation, decimal point and
column separator. You also select whether you wish to export to text files or the Windows Clipboard.
The Studio dataset stores data for the dataset variables in a data store internally in Powersim
Studio. The Studio dataset also allows you to export and import data to and from the Windows
Clipboard or a text file.
- 403 -
The Studio dataset contains dataset variables that you can connect to model variables in the
simulation. The dataset variables are defined in the Studio Dataset view, which is available in the
Project Window.
The connection between the dataset and the simulation is managed in the Co-models view.
Tip! The first and last periods of the dataset doesn't have to match the simulation's start and
stop times. If the dataset doesn't contain data for the current simulation time, the dataset will
return NAN.
You can specify a summary type to use for each dataset variable individually. The summary type
allows you to control the way the history for the dataset variable is recorded during the simulation.
Options are First, Last, Maximum, Minimum, Average, and Accumulated. The summary period is
identical to the specified period for the dataset.
Note! The two summary types Min and Max are only available when the dataset variable has
the transfer direction set to in.
When you create a Studio dataset you have to specify the sampling period for the dataset, as well as
the first and last periods to record.
1. Open the Studio Dataset view by double-clicking it in the Project Window, or by right-
clicking it and select View on the shortcut menu.
2. Right-click the Dataset node in the view, and select Properties on the shortcut menu.
3. Click the Times tab to specify the period information.
4. Define the sampling period under Period. You can specify the period in any number of months,
quarters, and years.
5. Specify the first period of the dataset under First Period.
6. Specify the last period of the dataset under Last Period.
Note! These are the settings that control the time span and resolution of the dataset. They do
not have to match the simulation settings of the simulation they are being connected to. If the
simulation requests data that are beyond the time span of the dataset, the value NAN will be
returned.
- 404 -
Working with the Spreadsheet Dataset
The Spreadsheet Dataset allows you to transfer data between Powersim Studio and Microsoft
Excel. The Dataset supports bi-directional transfer, making it easy to export the value history
produced by some variables to the spreadsheet, while at the same time importing value history to
other variables.
The dataset contains variables, in much the same way as a component (model) does. When the dataset
is connected to the model, the corresponding variables in the dataset and model interconnect and
exchange data. The dataset variables have type, dimension, and unit definitions, just like the model
variables. These definitions must correspond to each other for two variables to be able to connect.
After the dataset is connected to the component, you can auto-connect dataset variables and interface
variables that have the same name in the specified spreadsheet language. The variables' respective
names in other languages are unimportant. The language of the dataset view is thus independent of the
spreadsheet (connection) language. The selected spreadsheet language is also used when creating the
resulting spreadsheet file.
The dataset can transfer the immediate behavior of a variable, or it can transfer the entire time series.
In addition, the dataset also offers advanced formatting control over the output - the resulting
spreadsheet.
In order to connect a variable in the model to a variable in the dataset, you must define the connection
type in both the model and the dataset. The connection state of a model variable is indicated in the
Constructor diagram. This is shown in the figure below.
A small arrow on the outline of the variable symbol indicates that the variable can be connected to a
dataset. The model variable can have three different transfer directions: states: out, in, and in-out.
- 405 -
be auto-connected, but you are also allowed to connect variables with different names as long as the
data type, unit, dimensions, and transfer direction is compatible.
The translation follows the same principles when the simulation uses the Fiscal calendar. However,
since the January, April, July, and October have 31 days and the rest of the months have 30 days, the
strecthing factor is different from the ones used by the Bank to Gregorian calendar conversion.
The best solution is to simply run your simulation using the Gregorian calendar, if you need to
transfer data with a period less than a full month. Alternatively, you must manually adjust the times in
your Excel sheet with the appropriate calendar conversion factor.
- 406 -
Tip! If you need to create the times for such calendar conversions, simply set up a Spreadsheet
dataset with the correct sampling times and calendar combinations that exports a time series to
Excel. You can then simply copy the times from the exported time series, and use those times for
your input data.
The sampling times specify the intervals at which values are transferred to or from the dataset.
Note! The sampling times can only be set for transfer to the spreadsheets or for bi-directional
transfer.
You can connect the dataset to an existing spreadsheet on your computer, or you can let the dataset
create a new spreadsheet when it is connected to the component.
Note! When using an existing spreadsheet, be sure to select the correct transfer options in the
dataset to avoid accidentally overwriting important data!
- 407 -
use. Click Browse to select the workbook file from a location on your computer.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When you connect the dataset to a simulation, the dataset will launch Microsoft Excel with the
specified file name. If the file doesn't already exist on your computer, Excel will automatically create
it.
Tip! If the file doesn't already exist on the computer, you can specify a template to use for the
new file under Template on the General property page.
Tip! You can use the {RUNINDEX} code to allow the names in Sheet, Cell, or Workbook to
automatically change for new simulation runs. (Requires you to set the Run Count in
Simulation Settings for the project.)
You can control the layout of the resulting spreadsheet using the Layout properties page for the
dataset. You can access this by right-clicking the Dataset node in the Spreadsheet Dataset view,
and selecting Properties on the shortcut menu. The options here allow you to change the
orientation of the tables, and to control how subscripts and units are written to (or read from) the
spreadsheet.
The illustration shows the difference between the two possible orientations of the output table.
The various variable header formats: a) Name, b) Name, Subscript, c) Name, Subscript, Unit, and d)
Name, Unit.
- 408 -
You can also select to put the subscript and/or the unit in separate cells, which will be placed below
the variable header. The table below shows the layout for the example above, with both subscripts and
units in separate cells.
My Var
(m)
[1,1] [1,2] [2,1] [2,2]
<Value> <Value> <Value> <Value>
<Value> <Value> <Value> <Value>
The table header for the variable My Var, when units and subscripts are presented in separate cells.
Include Times
Finally, you can select whether to include times in the spreadsheet or not. This will affect the first
column of the spreadsheet. If the option Times in separate cells is selected, the first column will
contain time information. If it is not selected, the variable table will start at the first column.
You can turn the time column on and off using the "Times in separate cells" option.
When you use the dataset to transfer data to the spreadsheet, you might want to adjust the starting
position of the tables generated by the dataset. You might want to include headers, explanatory cells,
and so on.
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the General tab (if necessary).
3. Under Cells, enter the cell reference for the upper left corner of the area you wish the dataset to
produce its table.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
As cell reference, you can either enter a normal cell reference (such as A4, C3, etc.), or you can use a
name referring to a range of cells in Microsoft Excel. For information on how to create named cell
ranges, please refer to the documentation for Microsoft Excel.
Note! If the cell reference is omitted in the definition, the upper, left cell in the spreadsheet is
selected by default.
Tip! You can use the {RUNINDEX} code to allow the cell reference to automatically change for
- 409 -
new simulation runs. (Requires you to set the Run Count in Simulation Settings for the project.)
When using a one-directional transfer from the spreadsheet, you must include the sampling times in
the first column of the spreadsheet. To do this, you simply use the time format in Excel, and Studio
will automatically convert these relative to the simulation time of the component. If you use a bi-
directional transfer, you are also allowed to include the sampling times in the spreadsheet. There are a
few issues you should be aware of when setting up a spreadsheet like this.
! First, the first sampling time in the spreadsheet should coincide with the start time of the
simulation. The reason for this is that the dataset will return NAN (Not a Number) for any
simulation times that lie beyond the time series in the spreadsheet. Thus, the dataset will not
contain an initial value for the variable.
! Second, the last sampling time in the spreadsheet should coincide with the stop time of the
simulation, for the same reason as mentioned above.
! Third, the layout of the spreadsheet must be equal to the layout that you have specified on the
Layout tab of the Spreadsheet Dataset. You must take into account all the rows (or columns) that
the dataset will use for variable headers, units, and subscripts.
Tip! When creating a spreadsheet with sampling times, it is a good idea to create a bi-
directional dataset first, with sampling times at regular intervals. When you synchronize the
spreadsheet, Studio will format the spreadsheet using the layout specifications you have
selected in the Layout tab. Then you can use this file as a template when formatting the
spreadsheet to include sampling times.
If all the variables in your dataset have the same dimensions, you can format the output in an
alternative way using the Common Dimensions for All Variables option. This option allows you to
group the array elements in a grid rather than a long list. If you transfer Immediate Behavior, the array
elements can be grouped in a grid, while Behavior over Time will always present the array elements
subsequent cells.
Note! If you select Common Dimensions for All Variables, the dataset will require all dataset
variables (as well as their model variable counterparts) to have the same dimension.
When you have selected Common Dimensions for All Variables, you can specify how many
dimensions should appear next to the name, when transferring Immediate Behavior. If, say, all
variables have four dimensions and you specify that two should appear next to name, the dataset will
produce the output shown in the figure below. (In the figure, the dataset contains X variables all
having the dimensions 1..N, 1..M, 1..P, 1..Q)
- 410 -
Variable 1 ... Variable X
1 ... M ... 1 ... M
1 ... N ... 1 ... N ... 1 ... N ... 1 ... N
1 <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
1 ... <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
Q <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
... ... <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
1 <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
P ... <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
Q <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>
The table above shows the output produces by the dataset when the Common Dimensions for All
Variables option is selected. The example shows an example with X variables, all having the
dimensions '1..M,1..N,1..P,1..Q'.
The layout above is achieved by transferring Immediate Behavior. In addition, two dimensions is
selected to appear next to the name. If one dimension next to name was selected, three dimensions
would appear in the three leftmost columns. If three dimensions next to name was selected, three
dimensions would appear in the three columns below the name, while only one would appear in the
left column.
When you transfer Behavior over Time, all dimensions are presented in rows below the variable
names.
The dataset variables are listed in the spreadsheet in the order decided by the number in the Order
column of the Spreadsheet Dataset view. To sort the order of the variables:
1. Right-click the variable you wish to promote (or demote) in the list.
2. Select Move Forward (or Move Backward) on the shortcut menu.
To view the order of the variables, right-click the column headers and select the Order column on the
shortcut menu to display it in the view. To sort the variables in the order they will appear in the
spreadsheet, simply click the header of the Order column.
When you have changed the order of the variables, you need to update the spreadsheet as well.
1. Open the Co-models view.
2. Right-click the correct dataset connection in the list.
3. Select Synchronize Spreadsheet on the shortcut menu to update the spreadsheet.
Tip! You can use a template to format the spreadsheet. You can also select to only transfer
values, and leave formatting and header content remain unchanged when transferring data
from the simulation.
- 411 -
When changing the definition of the dataset, you will often change the layout of the resulting
spreadsheet. To update these changes in the spreadsheet:
1. Righ-click the dataset connection in the Co-models view, and select Synchronize
Spreadsheet on the shortcut menu.
Note! When you synchronize the spreadsheet, you might loose data. It is a good precaution to
always work on a copy of the workbook file to prevent loss of important data.
You can also show the spreadsheet and select the cells in the spreadsheet by using the Select
Spreadsheet and Select Cells commands available on the shortcut menu of the dataset connection.
These utilities makes it easy to see the area in the workbook that will be updated by the dataset
connection.
If you have created a spreadsheet workbook that you wish to connect the simulation to, you might not
want the dataset to update anything except for the numerical values only. To achieve this:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. You specify what to updated under Update in dataset.
1. Select the Headers option to allow the dataset to always update the variable headers.
2. Select the Number formats option to allow the dataset to always update the number formats in
Microsoft Excel.
3. Select the Time formats option to allow the dataset to always update the time formats in
Microsoft Excel.
4. If you want to update the spreadsheet with values only, deselect all of the options mentioned
above.
5. Click Apply to save the changes, or OK to save the changes and close the dialog box.
If you only wish Microsoft Excel to work on a temporary file (which is not saved):
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the General tab.
3. Select the Temporary option.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When running in this mode, the spreadsheet workbook will not be saved when the simulation project
is closed, unless you manually switch to Microsoft Excel and save the workbook. However, if you
have specified a template for the dataset, it will be used when creating the temporary file.
- 412 -
Ensure Valid Data from Spreadsheet
When transferring data between a spreadsheet and a component, it is always useful to be certain that
the data is transferred is actually valid for the target variable. To ensure this, you can use the Data
Validation feature in Microsoft Excel.
1. Switch to Microsoft Excel after connecting the dataset to a component.
2. Select the cell range for which you want to validate data.
3. On the Data menu, select Validation.
4. Under Allow, select the type of value to allow. Recommended choices are Whole Number or
Decimal, corresponding to INTEGER and REAL in Powersim Studio.
5. Use the Data, Minimum, and Maximum boxes to specify the criteria for the data validation.
6. Click OK to save the changes.
The selected range will now make sure that the data that is added to the cells in the range are valid
with regards to the entered validation criteria.
Use Names for Cells, Sheets, or File that Change with Run Number
If you have specified the run count in Simulation Settings for the project, you can make the
spreadsheet dataset automatically change cell, sheet, or file reference to reflect the run number. This is
useful if you want to save the results from various simulation runs.
Note! The run number is reset when the simulation is reset. When the simulation has reached
the end, you should start a new simulation by clicking Start simulation directly rather than
resetting the simulation first.
Example
You can save the results from the various simulation runs in various sheets in the workbook. The
sheets should all start with Simulation, and end with the run number. To achieve this, you enter the
following text in the Sheet box:
Simulation{RUNINDEX}
Each time you click Start Simulation, new simulation results will be stored on separate sheets
named Simulation1, Simulation2, etc. This continues until the run count specified in Simulation
Settings is reached. At this point the run number is reset.
- 413 -
Use a Spreadsheet Template
When you create a new file, or when the Temporary option is selected on the General property page,
you can specify a template that the dataset will use when it connects to Microsoft Excel:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the General tab (if necessary).
3. Enter the name of the template to use under Template on the General tab.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
The file can be a normal spreadsheet (*.xls) or a template (*.xlt).
Tip! Under Update in Dataset you can turn off updating of headers, number, and time formats.
This way the formatting you have performed in your file (or template) will remain intact as the
simulation advances.
The dataset can operate in two different modes. It can either transfer the entire time series - Behavior
over Time - or it can transfer instant values - Immediate Behavior - between the spreadsheet and the
variable.
When you transfer immediate behavior, the spreadsheet will only contain one value per variable. This
transfer method is ideal if you wish to monitor the value of a variable, or if you want to use the value
of one variable to perform calculations in the spreadsheet, and then return it as an input to another
variable.
To set up a transfer of immediate behavior:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. Select Immediate Behavior under Category.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When Immediate Behavior is selected, several of the options are disabled, since they are not used by
the dataset in this mode. Working with variables - both in the model and the dataset - is identical
when working with Immediate Behavior and Behavior over Time.
The dataset can operate in two different modes. It can either transfer the entire time series - Behavior
over Time - or it can transfer instant values - Immediate Behavior - between the spreadsheet and the
variable.
When you transfer behavior over time, the spreadsheet will contain a series of values per variable.
This transfer method is ideal if you wish to save the value development over time, or if you want to
provide historical data as input to a variable. You can also provide the model with an historical initial
- 414 -
value, and afterwards record the output from the variable as a time series.
To set up a transfer of behavior over time:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. Select Behavior over Time under Category.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When you have selected to transfer behavior over time, you must also provide the dataset with
information on the sampling times for the behavior. Be careful to select a sampling time that captures
the interesting behavior, but still doesn't generate to many output points. If the connection is Bi-
directional or From Spreadsheet, you can also provide the sampling times directly from the
spreadsheet.
You can transfer data in both directions between Powersim Studio and Microsoft Excel by use of the
Spreadsheet Dataset. This means that you can import values for a model variable from the spreadsheet
while at the same time exporting values from other model variables to the spreadsheet. Thus, it is
possible to let Microsoft Excel perform calculations on output values from one or more model
variables, and provide the result from those calculations as input values to another model variable.
When you have created a bi-directional dataset, you can specify the sampling times in two different
ways. You can either set the sampling times at regular intervals that you specify yourself, or you can
let the dataset load the sampling times from the spreadsheet.
Note! When using bi-directional transfer, there is always a danger that you might overwrite
data in the spreadsheet workbook. It is a good precaution to always work on a copy of the
original workbook, to avoid deleting important data accidentally.
You can restrict the dataset to only allow transfer of data in one direction between Powersim Studio
and Microsoft Excel. In this case, the dataset will not add any information to the spreadsheet, unless
you explicitly tell it to (by clicking Synchronize Spreadsheet in the Properties dialog box of dataset
in the Co-models View). However, when in this mode, the dataset will only allow values to be
transferred from the spreadsheet to a model variable.
- 415 -
When transferring only from the spreadsheet to the model variable, you have to specify the sampling
times in the spreadsheet. The dataset will read the times from the first column of the spreadsheet, and
automatically convert them into times that are compatible with the simulation time. When entering
times in the spreadsheet, you should use one of Microsoft Excel's date formats.
To set up a transfer from a spreadsheet to a model variable:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. Select Transfer from Spreadsheet under Transfer direction..
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When you have selected this option, a dataset variable can only have one transfer direction: out. The
corresponding transfer direction for the model variable is in.
You can restrict the dataset to only allow transfer of data in one direction between Powersim Studio
and Microsoft Excel. In this case, the dataset will not import any information from the spreadsheet to
the model, but only allow values to be transferred from a model variable to the spreadsheet.
Note! When transferring in this direction, be aware that all data will be overwritten for every
simulation run, unless you change the spreadsheet workbook to use by the dataset.
When transferring only from the model to the spreadsheet, you have to specify the sampling times at
regular intervals.
To set up a transfer from a model variable to a spreadsheet:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. Select Transfer to Spreadsheet under Transfer direction.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When you have selected this option, a dataset variable can only have one transfer direction: in. The
corresponding transfer direction for the model variable is Exported.
When the sampling times are longer than the time step of the simulation, you can allow the dataset to
produce estimates of the values that lie between the sampling points. Thus, if you have only five data
points for the entire simulation, you can in some cases get a better estimate of the behavior of the real-
life system.
Currently, you can let the dataset interpolate linearly between existing data points. Thus, when
between sampling points, the dataset will transfer a value that corresponds to a value on a straight line
between the neighboring sampling points. If you don't want to use interpolation, you simply select
Step, which will transfer the last sampling point until the new sampling point is reached.
- 416 -
To turn on linear interpolation:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. In the Variables list on the Variables tab, select the variable to create interpolated, intermediate
values for.
3. Under Interpolation, select Line.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
You can transfer data at times that are specified in the spreadsheet, rather than at regular time
intervals. This requires that the transfer direction of the data is set to either Bi-directional Transfer or
Transfer Data from Spreadsheet.
Note! If you select the Transfer at Regular Intervals option, and the Times in Separate Cells
option under Dataset Includes is selected, the times in the spreadsheet will be overwritten. You
should therefore be sure to select the Load Times from Dataset before connecting the dataset to
the component in step 4 below!
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. Under Transfer Direction, select either Bi-directional transfer or Transfer Data from Spreadsheet.
4. Under Sampling Times, select the Load Times from Dataset option.
5. Click Apply to save the changes, or OK to save the changes and close the dialog box.
6. Create and define the variables you need to in the Studio Dataset view. You can create
variables by dragging them from the simulation and dropping them on the Dataset node. You
can also define variables by drag and drop after the dataset connection below is established.
7. Connect the dataset to the simulation in the Co-models view for the simulation in question.
Microsoft Excel will open automatically with the file specified in the dataset.
8. Expand the dataset connection node in the Co-models view.
9. Right-click each variable, and select Auto-connect Variable on the shortcut menu to connect it to
the corresponding variable in the simulation. You can also connect variable by drag-and-drop, by
dragging an interface variable from the Main node and dropping it on the dataset variable you
wish to connect it to.
10. Repeat the step above for all the interface and dataset variables you wish to connect.
Tip! You can also create dataset variables and connections directly by dragging a model
variable with the right-button from the diagram and dropping it on the dataset connection node
in the Co-models view. When you have dropped it on the node, you can select whether you want
to export it from or import it to the simulation on the shortcut menu that appears. This process
automates several of the steps above, as the dataset variable is created, all properties are set
corresponding to the model variable, and a connection is established.
The connection is now established, and you can add the custom times to the spreadsheet. If the dataset
uses a pre-defined file, you can of course add the times to the spreadsheet before the dataset has been
connected to the component.
1. Switch to Microsoft Excel (if you haven't already entered the times in the workbook used by the
- 417 -
dataset).
2. In the first column (if Variable Names Across is selected under Orientation) or the first row (if
Variable Names Down under Orientation is selected) of the spreadsheet, enter the times at which
you wish to import data. You can use the time formats available in Microsoft Excel. The dataset
will automatically convert these times to their equivalent in Powersim Studio.
Note! Be sure to select the correct sheet when entering the times (you must obviously use the
same sheet as specified under Sheet on the General tab of the dataset.
You can let the dataset transfer all the simulation data at the end of the simulation. This can speed up
the simulation, as the simulation is not delayed by communication between Studio and Microsoft
Excel.
1. Deselect the Continuous Data Transfer on the Layout tab.
To transfer data continuously to the spreadsheet:
1. Right-click the Dataset node in the Spreadsheet Dataset view, and select Properties on
the shortcut menu.
2. Click the Layout tab.
3. Select the Continuous Data Transfer option.
4. Click Apply to save the changes, or OK to save the changes and close the dialog box.
Note! This option will only affect data transfers from the component to the spreadsheet. If
values are imported from the spreadsheet to a model variable, the transfer will occur at the
defined intervals (controlled either by dataset settings or by explicitly defined times in the
spreadsheet).
- 418 -
Work with the SEM Dataset
The SEM Dataset provides a connection between Powersim Studio and the SAP Strategic
Enterprise Management - Business Planning and Simulation (SEM-BPS) system. It allows you to use
Powersim Studio as a planning tool with SEM-BPS for creating group-wide business plans. The
purpose is to produce consistent and realistic plans by adding the capability to test various scenarios
before applying them in the business.
The connection to the SAP Business Warehouse (BW) InfoCube is set up through SEM-BPS and the
planning architecture supplied there. The main purpose of the dataset is to connect model variables in
Studio to their counterparts, the key figures, in the SAP BW InfoCubes. The dataset can import values
from key figures to model variables in the simulation, or export simulation results from model
variables to the key figures.
The SEM Dataset uses the planning architecture in SEM-BPS to establish a connection between
the two systems. This architecture is constituted by planning areas, planning levels, planning
packages, and planning layouts. The planning area contains the link to the SAP BW InfoCube. The
planning level contains the characteristics and key figures that are used in the business planning
process, and restrictions that apply to all the various planning tasks being performed within that level.
The planning package contains the final restriction of data for the specific planning task that is done
with that package.
Planning layouts are defined in the planning level, and are forms that define data input and output to
the SEM-BPS system. The SEM Dataset utilizes these layouts to define the data transfer between
the two systems. A planning level must therefore contain at least one planning layout that complies
with the requirements set by the SEM Dataset.
The characteristics included in the planning level as well as the restrictions made for these
characteristics in the planning level and/or in the planning package, is read by the SEM Dataset,
and this information is used to map the simulation time to the reporting times of the SEM-BPS
system, as well as to define units, dimension and version ranges, and dataset variables in the
simulation project.
The connection between dataset variables and model variables are done on either a one-to-one basis
or one-to-many basis, depending on the transfer direction of the variable connection. A dataset
variable that exports data from the dataset connection to the simulation can be connected to any
number of model interface variables. If, on the other hand, a dataset variable is importing data from
the simulation to the dataset connection, it can only be connected to one model interface variable.
The documentation available in the following topics concentrates on how the SEM Dataset is set
up and utilized inside Powersim Studio. It also covers the requirements that must be met by the
planning architecture in SEM-BPS in order for the connection to work. For further information on the
SAP SEM-BPS system, please refer to the documentation distributed with the SAP system.
- 419 -
Note! When you run simulations that use the SEM Dataset, you must always use the
Load… and Save… commands available under External Data… to load and save
data that are temporarily stored in the dataset connection inside Powersim Studio.
The SAP SEM-BPS system features a planning architecture that is structured into planning areas,
levels, and packages. The connection between Powersim Studio and SAP SEM-BPS also relates to
this structure, and the planning level and the package are the most important. In Powersim Studio, the
data connection is based on a SEM Dataset definition, which is associated with a planning area and a
planning level. You can, however, apply the simulation to all planning packages within the selected
level.
SEM-BPS also contains layouts, which control the presentations of the data available in a given
package. Layouts are defined in the planning level, and one layout may therefore be used by several
packages. The SEM Dataset in Studio interacts with layouts to structure the data in and out from
SEM-BPS, and you must therefore specify a layout to be used by the dataset when you define it.
It is important to keep in mind that the actual time series is retrieved from the planning package, and
you must therefore select a planning package when you want to perform simulations on data from the
SAM BW InfoCube. This package can be specified in the dataset definition, or for each individual
dataset connection.
A planning level and area in SEM-BPS contains various characteristics and key figures. When Studio
uses the SEM Dataset to connect to SEM-BPS, characteristics related to time are translated into time
information in Studio, characteristics describing ranges are translated into dimension and version
ranges, while currency and unit characteristics are translated into units in the simulation project. Key
figures are translated into dataset variables. Characteristics describing ranges can also be restricted to
a single value, in which case it will not appear in the simulation at all, but will instead be handled by
the Dataset itself when reading or writing data to the SEM system.
Note! Dimension ranges are added to Global Ranges as ordinary ranges when the Dataset is
synchronized with SAP SEM-BPS. Version ranges, on the other hand, does not affect the
simulation model directly, but is used to decide where the data are going to be read and written
in the SEM-BPS system. Version ranges may only be restricted in the planning package,
whereas dimension ranges may be restricted in the planning package only if the planning
package is part of the dataset definition, otherwise it must be restricted in the planning level.
- 420 -
the dataset definition, it is locked and cannot be changed for each dataset connection individually.
Note! If the package is defined in the dataset definition, characteristics that define dimension
ranges, units, and currencies may be restricted in the planning package. Otherwise these
characteristics must be restricted in the planning level.
- 421 -
status, whether it's logged off, logged on but not transferring data, or data transfer is active. The icons
are shown below.
SEM Dataset Offline: The open simulation project contains a SEM Dataset, but you are not
currently logged on to the SAP SEM-BPS system.
SEM Dataset Online: You are logged in to the SAP SEM-BPS system, but there is currently no
active data transfer.
SEM Dataset Active: You are logged in to the SAP SEM-BPS system, and data are being
transferred.
When the icon is visible in the system tray, you can right-click it and control the connection status of
the SEM Dataset on the shortcut menu. You may also define a time-out interval, allowing Studio
to automatically log off the SAP system when the specified time has elapsed.
Connection Details
The various key figures and characteristics available in SEM-BPS are interpreted into various
properties within Studio and the SEM Dataset. The various mappings are discussed below. You can
view the different characteristics available in the SEM-BPS system on the Characteristics property
page for the SEM Dataset.
Key figures
Key figures in SEM-BPS are transferred to the dataset as dataset variables, which in turn can be
connected to model variables when a dataset connection is made. The key figures in SEM-BPS must
be marked as InLevel, and they must be included in the planning level. Different layouts in the SEM-
BPS structure can use different selections of key figures (or all, should you wish so). Only the key
figures that are present in the selected layout of the SEM Dataset definition will be available in
Studio.
When you synchronize your SEM Dataset to SEM-BPS, a dataset variable will be created for each
key figure available in the selected layout. The technical name of the dataset variable will be identical
to the technical name of the key figure. This allows you to change the display name of the dataset
variable to anything you like, should you wish to. The transfer direction you specify for the dataset
variable will control the direction of data transfer to and from SEM-BPS. If the direction is set to in,
data will be transferred from Studio to SEM-BPS; if it set to out, data will be transferred from SEM-
BPS to Studio; and if it is set to out-in, the initial value will be transferred from SEM-BPS to Studio,
while the rest of the time series will be transferred from Studio to SEM-BPS.
After creating a dataset connection between a SEM Dataset and a simulation in the simulation's
Co-models view, you can connect the dataset variables to their model variable counterparts. Model
variables that have a defined transfer direction are called interface variables, and these will be
available under the Main node. Once you have created a dataset connection, the dataset variables
will be available under the SEM Dataset node. Connecting the model interface variables to the
corresponding dataset variable can be achieved by a simple drag-and-drop operation.
When connecting a model variable to a dataset variable, the variables must have compatible units,
dimensions, data types, but opposite transfer directions.
- 422 -
Time-related characteristics
When you create the planning level of the planning architecture, you must include time characteristics
that control the recording times of the dataset. There are quite a few valid combinations of time
characteristics and restrictions of these that can be used with the SEM Dataset. For a complete
listing of allowed combinations of time characteristics, please read Mapping Time Characteristics to
Simulation Time.
There are two different types of time characteristics in SEM-BPS: calendar and fiscal time
characteristics. If your SEM-BPS system utilizes fiscal time characteristics, the conversion will be
defined using one of the fiscal translation schemes available in the SEM Dataset. Calendar time
characteristics will be mapped to the calendar of the simulation directly.
The time characteristics available in the planning level are used by the SEM Dataset in various
ways, and these three interpretations are shown below.
Time Interval Characteristic: There must always be at least one time characteristic available,
and one of these must be a time interval characteristic. This characteristic is used to determine the
sampling interval of the dataset. A time interval characteristic is restricted to a continuous time
interval in the planning level or the planning package.
Locked Time Characteristic: In systems with two time characteristics, one of them can be
interpreted as a locked time characteristic. A locked characteristic must be restricted to a single
value in the planning level. Note that the fiscal time characteristic 0FISCVARNT will always be
treated as a locked time characteristic.
Unrestricted Time Characteristic: In systems with two (or more) time characteristics, one of
them may be left unrestricted. Such chacteristics are used to determine the resolution of the
dataset. If an unrestricted time characteristic is present, the time interval characteristic above will
be used to determine the major interval, while the unrestricted time interval is used to determine
the minor interval of the reporting time.
Note! When connecting a dataset variable to a model variable, you must make sure that they
have compatible units.
- 423 -
connection individually, or you can select them when saving and loading the simulation data.
Characteristics that are used as version ranges can only be restricted in the planning package.
Tip! If you restrict the version range to a single value in the planning package, it will be
selected automatically when you establish a dataset connection.
If a characteristic in SAP SEM-BPS is assigned to the lead columns of the planning layout, it will be
used as a dimension range in Powersim Studio. The dimension range will be used to define the
dimensions of the dataset variable, and the resulting dataset variable will be an array. Characteristics
that are used as dimension ranges must be restricted in the planning level, or it may be restricted in the
planning package, provided the planning package is a part of the connection details that are saved
with the dataset definition.
Ranges that are used to define the dimension of variables are copied to Global Ranges for the
simulation project. The dimension range will affect the dimension of the simulation model, the dataset
variables, and their connected interface variables. To be able to connect dataset and interface
variables, their dimensions must be identical.
Note! When you restrict a characteristics in the SAP SEM-BPS system to a range, you must
ensure that it is restricted to a continuous subrange of the available values for the
characteristic. This is similar to defining subranges in Studio, where you can define subranges
from a range by selecting the first and the last range element, and the resulting subrange will
contain all the elements between the start and end element.
There are a wide selection of available time characteristics in the SEM-BPS system. When preparing
a planning architecture that is going to communicate with Powersim Studio through the SEM
Dataset, you must make sure that the time characteristics that are included in the planning level, are
compatible with Powersim Studio. The table below summarizes the allowed combinations.
The time characteristics in SEM-BPS can be interpreted in three different ways by the SEM
Dataset, depending on whether they are restricted to a single value, to a continuous range, or are left
unrestricted.
Time Interval Characteristics: A time characteristic that is restricted to a continuous range in
either the planning level or in the planning package. A time interval characteristic must always be
included in the planning level. It must be assigned to the lead columns of the planning layout. A
time interval characteristic may appear alone (as the only available time characteristic in the
planning level), or it may be accompanied by a locked or an unrestricted time characteristic.
Examples of time interval characteristics are 0CALDAY, 0CALWEEK, 0CALMONTH, and
0CALYEAR restricted to a continuous subrange in the planning level or package.
Locked Time Characteristics: A time characteristic that is restricted to a single value in the
planning level or planning package. A locked time characteristic must always be accompanied by
a time interval characteristic, and it must be assigned to the header area of the planning layout.
Examples of locked time characteristics are 0FISCVARNT or 0CALYEAR restricted to a single
value.
Unrestricted Time Characteristics: A time characteristic that is, as the name implies,
unrestricted in the planning architecture. It is used by the SEM Dataset to determine the
resolution of the sampled time series. An unrestricted time series must always be accompanied by
a time interval characteristic, and it must be assigned to the lead columns of the planning layout.
Examples of unrestricted time characteristics are 0CALMONTH2, 0CALQUART1, and
- 424 -
0CALWEEKDAY1 that are left unrestricted in the planning architecture, and combined with
corresponding time interval characteristics as listed in the tables below.
- 425 -
Time Translations in the SEM Dataset
Data in SEM-BPS are structured in time periods, much like time series in Powersim Studio. To be
able to map the data correctly to time series in Powersim Studio, the SEM Dataset must specify
how the calendars should be mapped.
Although the planning level and package can contain several time characteristic, all except one must
be single. If the time characteristic that is not single is restricted, then it is available at the planning
level, otherwise it is only available in planning packages.
- 426 -
001.2003, the simulation time 1 August 2002 will be mapped to 002.2003, and so on.
Note! When you select this translation method, Studio will analyze the time characteristic and
suggest parameters for you. In most cases, these default values will be appropriate for most
purposes. You should review them and only change them once you're certain they must be
changed.
If you select to translate the fiscal time characteristic by fiscal periods, you specify the starting time of
the first period and the ending time of the last period in the data source. You must then mark all the
special periods for the data source manually. It is a requirement that the entire time scope of the
dataset is known in the dataset definition if you are going to use this translation method. Thus, if the
time characteristics are restricted in the planning package, the planning package must be specified in
the dataset definition.
Independently of the translation method selected, you can always change the parameters of the
selected translation method on the Time Translation property page, for the SEM Dataset definition.
To open this property page, right-click the Dataset node in the SEM Dataset view, and select
Properties on the shortcut menu.
Characteristics in the SEM-BPS system that are related to ranges, units, and currency are imported to
the simulation project as global ranges (for dimension ranges), version ranges (within the SEM
Dataset), and global units (units and currency).
Characteristics that are used as dimension ranges, version ranges, and units, must be restricted when
the dataset definition is created. Thus, if the planning package is set for the dataset definition, these
characteristics may be restricted in either the package or in the level. If the planning package is left
open in the dataset definition, then these characteristics must be restricted in the planning level.
- 427 -
the first dimension, the second as the second dimension, and so on.
Note! When you restrict a characteristics to a range in the SAP SEM-BPS system, you must
ensure that it is restricted to a continuous subrange of the available values for the
characteristic. This is similar to defining subranges in Studio, where you can define subranges
from a range by selecting the first and the last range element, and the resulting subrange will
contain all the elements between the start and end element.
Alternatively, you can use the ranges as version ranges, in which case the range will affect the data
source of the simulation rather than the dimension of the model variable. If a dimension is used as a
version, you must explicitly select what version to simulate on. You do this in the Connection
property page of the dataset connection in the Co-models view under the simulation, or in the
External Data Details dialog box.
Units
When the dataset is synchronized with SEM, the unit definitions that are available in SEM-BPS and
that are not already present in the simulation project, will be automatically created in Global Units.
All used units are imported as global units, and will be available for all the components in the project.
Note! All imported units will be defined as ATOMIC in Global Units, even if an imported unit
may be an SI unit. Studio has no means of detecting whether this is the case or not. If so, it is
recommended that you add the unit before making the connection to SEM-BPS.
The SEM Dataset requires that all units used in the simulation must be restricted to a single value.
In addition to the units included as characteristics in the planning level, a single variable can also have
a unit definition attached to it. These units will also be added to the system as global units.
The Units property page of the SEM Dataset allows you to inspect the unit definitions that are present
in the planning level. The information available includes the units name, technical name, definition,
description, and whether or not it is a currency unit. The property page is available by right-clicking
the Dataset node in the SEM Dataset view, and selecting Properties on the shortcut menu.
The SEM Dataset will store the data that was loaded from the SEM-BPS system at the last data
transfer, even if the simulation project was saved and closed in the meantime. The dataset will not
hold data for all versions of a dataset, however, so you are restricted to using one version while
working offline. When you are running the simulation, new time series will temporarily be stored in
the dataset connection. Once you are online again, you can save the changes that you made to the
dataset connection back to the SEM-BPS system.
Note! The SEM Dataset is, strictly speaking, always working offline, as it only connects to
SEM when synchronizing, loading, or saving data. However, since a connection must be
established each time you change a version, package, or synchronize the dataset with SEM-
BPS, it will usually be required to have a connection readily available.
The table below shows which operations require a connection to be established between Studio and
SEM-BPS, and which operations that can be run completely offline.
- 428 -
Connection
Operation
Required
Defining dataset (importing characteristics and key figures) Yes
Synchronizing dataset Yes
Creating dataset connection (in Co-models view) Yes
Loading and saving data Yes
Changing versions Yes
Changing package for dataset connection Yes
Inspect or change dataset properties (dimension ranges, version ranges, No
time translation details)
Viewing/Editing history for dataset variables No
Running simulation No
Note! When you run a simulation, all the dataset variables with the transfer direction set to in
will be reset when you reset the simulation.
The planning architecture of the SEM-BPS system consists of three structures: the planning area, the
planning level, and the planning package. The discussion below will not explain how these interact
with eachother, and how you should define them, as this discussion belongs to the SAP SEM-BPS
documentation. The discussion does, however, point out the most important aspects that needs to be
taken care of in order for a connection between SAP SEM-BPS and Powersim Studio to be
established.
- 429 -
Setting up the planning area
The planning area of SEM-BPS is used to create a link to an InfoCube in the SAP Business
Information Warehouse (SAP BW). No particular selections are required on the planning area to
make the SEM Dataset work.
Note! When you restrict a characteristic to a range, you must always make sure that the
restriction is a continuous subset of the available values for the characteristic. You cannot
build a selection of elements from various sections of the available values. Thus, restricting a
range characteristic for a SEM Dataset in SEM-BPS is pretty similar to creating enumeration
subranges from enumeration ranges in Studio-
Superior characteristics must always be included and restricted to a single-value in the planning level.
All other characteristics included in the planning level, including units of measurement and
- 430 -
currencies, must be restricted to a single value either in the planning level or in the planning package.
- 431 -
Setting up the planning layout
The planning layout serves as a form for structuring data for in- and output in SEM-BPS. A planning
layout can be viewed in SEM-BPS as an Excel spreadsheet. The planning layout contains three panes:
The header area; the lead columns; and the data columns. Powersim Studio uses the structure of a
planning layout to transfer data to and from SEM-BPS, and you must therefore add at least one
planning layout to your SEM-BPS system to be able to connect to it from the simulation model.
Each SEM Dataset in Studio may connect to a different planning layout within the same planning
architecture, and this allows you to make different layouts for different datasets.
The characteristics available in the header area are valid for the entire planning layout. The lead
columns determine the contents of the rows, and you are allowed to define several lead columns in
each layout. Finally, the data columns contain the actual data transmitted to and from the database.
Note! A planning layout may only contain 10,000 rows of data, so keep this in mind when you
define the planning layouts to use for the dataset connections.
Note! All the characteristics that are included in the planning level must be assigned to the
planning layout for the layout to be compatible with the SEM Dataset. You may, however,
include only a selection of the key figures available in the planning level.
The time, unit, currency, and superior characteristics that are restricted to a single value, must be
assigned to the header area of the layout.
To use a range characteristic as a version range, it must be assigned to the header area of the planning
layout. This is the way Powersim Studio will identify version ranges when synchronizing the dataset
with SEM-BPS.
The time characteristics that are not restricted to a single value must be assigned to the lead columns
of the planning layout. If you have more than one such time characteristic in your planning
architecture, you should assign each of them to an individual lead column.
The range characteristics that are being used as dimension ranges in the simulation model, must be
assigned to the lead columns of the layout. This is the way Powersim Studio will identify dimension
ranges.
Note! Dimension ranges are created when the dataset definition is made. The characteristics
defining dimension ranges may therefore only be restricted in the planning package if the
package is a part of the connection details of the dataset definition.
Finally, the key figures that should be available to the SEM Dataset that connects to the planning
layout, must be assigned to the data columns of the planning layout.
- 432 -
Version range characteristics
Lead Columns
Data Columns
Key figures
The steps below provide an overview of the process of how to define a SEM Dataset.
1. Create a new SEM Dataset in the Project Window. When you have created the dataset, open
its view by double-clicking it.
2. Right-click the Dataset node, and select SEM Connection… on the shortcut menu.
3. In the SEM Connection dialog box, specify the planning area, planning level, and planning layout
you wish to connect to. The planning package may also be specified on the dataset definition. If
your simulation must access different packages, however, you should set the package on each
dataset connection individually instead. You are also allowed to set the package to use when
loading and saving data from the simulation (unless it is locked in the dataset connection or
defined directly in the dataset definition). Click OK to accept the connection details.
4. The SEM Dataset will load the available characteristics and key figures from SEM-BPS.
Studio will automatically generate dataset variables for the key figures, global ranges for
dimension range characteristics, and global units for unit and currency characteristics. You can
inspect the available characteristics in the Characteristics property page of the SEM Dataset.
5. If the planning level you are connecting to contains a fiscal time characteristic, a translation
method is automatically set up for the dataset. In most cases, the automatic interpretation of the
fiscal calendar schemes will be good, but please ensure that the translation settings are correct
before running a simulation. The settings are available in the Time Translation property page for
the SEM Dataset.
6. You can control the order in which dimension ranges will appear in the dataset variable definitions
by sorting the order of the available ranges in the Characteristics property page of the SEM
Dataset.
7. You can now verify that the dimension ranges have been created in Global Ranges and units
have been created in Global Units.
8. To connect the dataset to the simulation, you must open the Co-models view of the respective
simulation.
9. Right-click inside the Co-models view, and select Create Dataset Connection on the shortcut
menu. Select the newly created SEM Dataset on the submenu to create a dataset connection.
10. Make sure that the interface variables of your simulation have corresponding unit, dimension, and
transfer directions, and connect them to the dataset connection.
11. If the dataset connection needs package and version information, right-click the dataset
connection, and select Properties on the shortcut menu.
12. On the Connection property page, you can set the package to work on by entering the technical
name of the package in the Package text box. You can also click Change… and specify the
package in the SEM Connection dialog box.
13. You can also select an element for each version range in the dataset. Select the row containing the
- 433 -
version range, and click on the element field to open a drop down list where you can select
between the available versions.
14. You can lock both the package and the version by selecting the Lock options for each. If the
package and/or version is locked, it cannot be changed when you access the Load External
Data… or Save External Data… dialog boxes. Click Apply (or OK) to apply the changes.
15. Once the complete connection details (including package and versions) are set, you can load data
to the dataset connection. Right-click the dataset connection and select Load Data on the shortcut
menu, or select External Data… on the Simulation Menu, and select Load… (this
command will only be available if you have connected variables to the dataset connection).
16. You can now run the simulation.
17. You can save simulation data back to SEM-BPS at any time you wish (you can run as many
simulation runs as you wish without saving data). Right-click the dataset connection and select
Save Data on the shortcut menu, or select External Data… on the Simulation Menu, and
select Save… (this command will only be available if there are unsaved information in the
dataset).
There are other options and functionality available in the SEM Dataset as well, but the steps above
should enable you to make an initial connection.
Sometimes the planning area, level, and packages will change after you created the SEM Dataset.
In this case you can easily synchronize the dataset with the SEM-BPS system.
1. Open the SEM Dataset view.
2. Right-click the Dataset node, and select Synchronize on the shortcut menu.
The SEM Dataset will be updated with the latest changes from the SEM-BPS system. You can create
new dataset variables for key figures, and characteristics will be updated.
All dataset variables, including dataset variables in the SEM Dataset, can use summary types.
However, when using the summary type Accumulated, the unit of the resulting time series will
become the unit of the dataset variable multiplied with time. This is similar to the relationship
between the units of a level and of the flow rate controlling a flow to the flow rate (when the flow is
continuous). If the unit of a dataset variable is USD/mo, the resulting unit when using the
Accumulated summary type will be USD.
You should take this into account when using the Accumulated summary type for a dataset variable in
the SEM Dataset - which represents a key figure in SEM-BPS. Changing the unit of the dataset
variable accordingly will ensure that the time series that is saved to SEM-BPS has the same unit as the
key figure it is saved to.
When you run a simulation that utilizes a SEM Dataset, you control when data is loaded and saved
manually. If a package is defined in the dataset definition and the dataset doesn't contain versions,
- 434 -
data will be automatically loaded from SEM when you first create the dataset connection. Otherwise,
if a package isn't selected or a version is required for the data to load, you control when data are
loaded and saved between Studio and SEM manually by using the commands available under
External Data….
To load (or save) data for a SEM Dataset, please follow the procedure below.
1. Click External Data… on the Simulation menu or toolbar, and click Load… (or
Save… on the menu that appears. The Load External Data (or Save External Data) dialog box
will appear.
2. If you need to select a version and/or a package for a dataset connection, click … next to the
dataset connection name in the dialog box. A dialog box will appear, allowing you to select the
required connection details. Click OK when finished.
Note! You will not be able to transfer data between Studio and SAP SEM-BPS if some of the
required connection details are missing.
3. Click OK to load the data from the SEM Dataset.
Remember that when working with the SEM Dataset, no data will be transferred unless you use
the Load… or Save… commands yourself.
Tip! You may use the External Data dialog box to view versions or packages. The dialog box is
available by clicking External Data…, and then selecting Details… on the submenu.
While the planning area and level must be specified in the global definition for the SEM Dataset,
the planning package can be specified on three levels:
In the dataset definition in the SEM Dataset view;
On the individual dataset connection in the Co-models view for the simulation;
In the External Data… dialog box when loading or saving data.
If the package is specified in the dataset definition, it cannot be changed in the dataset connection or
when loading or saving external data.
If the package is specified in the dataset connection, it is available for selection when loading or
saving external data, provided it has not been locked in the dataset connection.
To set a package for a dataset connection:
1. Right-click the Connection of SEM Dataset in the Co-models view, and select
Properties on the shortcut menu.
2. Specify the package to use for the dataset connection in the Details property page.
3. Click Apply to save the changes, or OK to save the changes and close the dialog box.
To lock the package for a dataset connection:
1. Right-click the Connection of SEM Dataset in the Co-models view, and select
Properties on the shortcut menu.
2. Select the Lock option under the package name in the Details Property page.
3. Click Apply to save the changes, or OK to save the changes and close the dialog box.
- 435 -
Set and Lock Versions in the SEM Dataset
When setting up the planning layout that the SEM Dataset will use when connecting to SEM-BPS,
you can assign range characteristics to the header area. These characteristics will be used as version
ranges when you work with the simulation. The version will decide where in the InfoCube you save
your data.
The version of a dataset connection can be specified in two different ways:
On the individual dataset connection in the Co-models view for the simulation;
In the External Data… dialog box when loading or saving data.
The version is available for selection when loading or saving external data, provided it has not been
locked in the dataset connection.
To set (and lock) a version for a dataset connection:
1. Right-click the Connection of SEM Dataset in the Co-models view, and select
Properties on the shortcut menu.
2. Select the version you wish to use in the Version column for the various available version ranges.
3. To lock the selected version element, select the corresponding lock option in the list.
4. Repeat the last two steps for all the version ranges (otherwise you will not be able to save or load
data).
5. Click Apply to save the changes, or OK to save the changes and close the dialog box.
When connecting to SEM-BPS, the SEM Dataset needs information about the planning area, level,
layout, and package it should connect to. If the dataset also contains version ranges, it will also
require a version to be selected before data can be read or written. While the planning area, level, and
layout must be specified in the dataset definition itself and defines large parts of the dataset directly,
the package and version may be selected in different ways.
- 436 -
External Data…
Thus, to allow the user to specify the package when loading or saving data to and from SEM, leave
the package field empty in the dataset definition, specify the default package in the dataset
connection, and leave the field unlocked.
When you have synchronized your dataset connection with SEM-BPS, you can disconnect Powersim
Studio from SAP.
1. Right-click the SEM Connection icon in the system tray (on the taskbar next to the clock).
2. Select Log off on the menu that appears.
The next time you need to connect to SEM (to save or load data, etc.), a new connection will be
opened, and you must identify yourself with your username and password.
You may also allow Studio to automatically log you off after a given time period.
1. Right-click the SEM Connection icon in the system tray (on the taskbar next to the clock).
2. Select Timeout Settings on the menu that appears, and select the timeout interval from the
submenu. Available options are 1 min, 2 min, 3 min, 5 min, 10 min (default), 20 min, or Never.
If you haven't manually logged off the SAP system within the specified timeout interval, Studo will
automatically log you off. If you select Never in the submenu, Studio will keep the connection to the
SAP system open until you manually close it.
- 437 -
Utilizing Modes in Studio
Since you have various needs based on the status of the project, Studio features three various modes
for you to run your project in. The Design Mode allows you to edit and create your model using
variables, controls, objects, etc. When you are running the simulation and varying input parameters to
study their effects, you can run your project in User Mode, preventing yourself from accidentally
making changes to the model. The diagram will be in read-only state. Finally, when you have created
a simulator interface for your simulation, you can let your users run the project in Presentation
Mode. The Presentation Mode acts pretty much like a browser, where the user can run the simulation,
play with input values, and study the results.
Note! Before you can switch to Presentation Mode, you must define the appearance of the
mode in Project Settings on the Project menu.
There are two ways to enter Presentation Mode. You can switch to Presentation Mode at any time
while you work in Studio, allowing you to test your simulator before you publish it. If you have
specified that the simulation project will start up in Presentation Mode, you can double-click the
project in Windows Explorer, and it will automatically open up in a dedicated Presentation Mode.
You can save your simulation runs in Presentation Mode in Simulation game files (*.sig). This allow
your users to save interesting runs for later use and use the as reference data, much in the same way as
working with runs in projects in Studio. A simulation game can be opened again by double-clicking
the file in Windows Explorer, or by opening it clicking Open in the Presentation Toolbar.
Note! If Presentation Mode is opened in dedicated mode (by double-clicking a *.sig or *.sip-
file), you cannot switch back to Design mode.
Note! Executive Authoring, the ability to create simulation projects that can be opened in the
Executive edition of Studio, is only available in the Enterprise edition of Studio.
A Simulator Browser
The Presentation Mode can best be described as a "simulation browser", where the user is allowed to
browse and play through your simulation in a way specified by you. The Presentation Mode itself is a
single-document interface (SDI) where the Project Window, Details Window, and all other
simulation-oriented development aids have been removed. There is only one toolbar available; the
- 438 -
Presentation Toolbar. The toolbar contains browser-buttons like the ones we know from web
browsers, which allow you to navigate in the simulator. The picture below shows how a simple
simulator interface might look when viewed in Presentation Mode.
By using controls, frames, freeforms, hyperlinks and bookmarks, you can create an attractive user
interface on top of your simulation. Studio also allows you to customize both the icon and caption
used for the Presentation Mode, should you wish to.
Tip! You can utilize the strong capabilities available in the Hyperlink and Bookmark objects to
further increase the functionality of your simulation interface. In addition to provide inter-
diagram jumping, the Hyperlink object may also be used to launch external files, visit web
pages, send e-mail messages, etc.
While all simulation projects might feature a Presentation Mode setup (except projects created in the
free Express edition of Studio), only projects created using an edition of Studio featuring Executive
- 439 -
Authoring can be opened using the Executive edition. Using the Enterprise edition and then
distributing the simulator using the Executive edition, is a convenient way of sharing your simulator
with others.
The Executive version will always start up in dedicated Presentation Mode, as described above.
The Presentation Mode gives you a browser-like presentation method for your simulation. The user
can access only the parts of the simulation project that you have specified, and cannot inspect the
underlying model unless you grant them access to do so. As you will see, the Presentation Mode
changes the interface of Powersim Studio completely, and removes unnecessary toolbars and menus.
The User Mode is, however, more a testing environment that you can switch to while creating your
simulator. Switching to User Mode allows you to test controls and hyperlinks as they will appear in
Presentation Mode, without changing the user interface. Also, while the Presentation Mode changes
the appearance of the entire project, User Mode will only affect the current diagram. You can thereby
switch your simulator interface to User Mode to allow easier access to controls and hyperlinks, while
keeping your model diagrams in Design Mode.
The Presentation mode can be utilized to create a stand-alone simulator. Although the simulator runs
inside Powersim Studio, it appears to be a stand-alone application with its own interface and help
system. The end-user can open the simulator, run it, save and load simulation runs, and control
external datasets, without performing changes to the original simulation project.
The list below describes some of the options available for you when creating your simulation.
! User Interface: Use hyperlinks, bookmarks, and controls to create user interfaces for your
simulator. A carefully designed user interface makes it easy for the user to browse the simulation
using the browser capabilities available in Presentation Mode. Using index variables to index
parameters in controls is an elegant way of simplifying the user interface.
! Use Reference Runs: Reference runs that can be displayed alongside the current simulation
results enable your users to quickly see the effects of changes compared to the known scenarios.
Remember to make all reference runs that are going to be visible in Presentation Mode public.
Reference runs can also be loaded from files (*.sir) that are previously saved in Studio (not in
Presentation Mode).
! Create Flexible Models: Make sure that your controls can cope with the results produced by the
simulation. Restricting the input range and making sure the controls can automatically scale
themselves will avoid the user to create scenarios where the data exceeds the scaling of value axis
and table cells.
! Utilize Multiple Simulations: Powersim Studio allows you to create several simulations for each
component. Each simulation can contain its own simulation settings, enabling the various
simulations to display different scenarios and time horizons. By using private diagrams, you can
also create customized user interfaces for each simulation. This allows you to create simulators
that are tailored to different user groups and decision scenarios but still have only one model
source. By creating a simulator home page you can easily create links that jump to various
diagrams within different simulations. Make sure, however, that you do not implement hyperlinks
that makes the user jump inadvertently from one simulation to another!
- 440 -
! Use Game Files: Games files (*.sig) allows you to save a simulation game. When you double-
click the file, it will open the simulator in Studio's Presentation Mode, and load the state of the
simulation at the time it was saved. A game file contains a "snapshot" of the simulator (and all its
simulations) at the time when the game was saved. The user may save in the middle of the
simulation, and opening the file again to start at that particular time and state. Game files can also
be used to share interesting simulation runs between several users.
! Implement Dedicated Simulator Help: You can create your own help system that will open
when the user clicks Help in the toolbar. Create the help system in HTML files in the same
folder as your simulation project (like a miniature web site), and name the starting page by the
same file name as your simulation project (except the file extension, obviously). When the user
clicks Help, the "help web" will be automatically opened in the default HTML browser selected
for the system.
! Add a Simulator Title and Icon: You can add a customized title for your simulation under
Project Settings on the Project menu. You can also specify an icon to replace the default
Powersim Studio icon in the titlebar. An icon must be saved as an icon file (*.ico) on your system.
Remember to include it with your simulator when you distribute it!
! Distribute your Simulator in Studio Executive: If you create your simulator in an Enterprise
version of Studio, you can distribute the simulator using Powersim Studio Executive. This is a
specialized simulation player provided by Powersim. The simulation will always be opened in
Presentation Mode when running this version.
Note! When Studio is in Run mode, you are not allowed to make changes to the structure of the
simulation model. You can only play the simulation and provide input to the simulation through
controls.
Note! If you have not specified a home page for the Presentation Mode, you will not be allowed
to switch mode. To specify a different default window, select Project Settings on the Project
menu, and specify the window on the Presentation Mode Setup property page.
- 441 -
Switch to Design Mode from Presentation Mode
Note! The Presentation Mode button is only available if you started Powersim Studio in
Design Mode. If you launch a simulator by double-clicking a file which starts directly in
Presentation Mode, the button will not be available to the user.
Tip! You can use passwords to protect your simulation project from viewing and/or editing. By
applying different passwords to different levels of protection, you can ensure that only
authorized users run and edit the model.
You specify the Presentation Mode for a project on the Presentation Mode Setup property page.
1. Select Project Settings on the Project menu.
2. Click the Presentation Mode Setup tab.
3. If you would like the project to automatically start up in Presentation Mode, select the Start up in
Presentation Mode option.
4. Specify a custom icon and caption to appear in the titlebar when the project is viewed in
Presentation Mode.
5. Specify the default startup window in Presentation Mode Home Page. This is the window that
will be presented when Presentation Mode is entered.
Note! The icon must be an icon file (*.ico), and not a bitmap picture.
When your simulation project is supposed to be viewed in Presentation Mode, you should implement
- 442 -
navigation means for your users to take advantage of. By using hyperlinks and bookmarks, you build
a structure of your simulator in much the same way as implementing web pages. When the user has
visited one bookmark, the Presentation Mode's browser buttons Back and Forward will be
activated, allowing your users to navigate back and forward through their browser history. This works
exactly as you would expect in web browsers.
Game files (*.sig) allow your users to save and load simulations when using your simulator in
Presentation Mode. The game file will contain a "snapshot" of the simulator, including the state and
available history for all simulations. A game file can only be saved when Studio is opened in
dedicated Presentation Mode. This happens when you have specified that the simulation project
should always be run in Presentation Mode when loaded, and you load a simulation project (by
double-clicking the simulation project or game file in Windows).
Game files allow your users to save a simulation for their own reference; save an interesting state that
they can revisit later; and share interesting simulation runs with other users of your simulator. They
also allow you to save different versions of the simulator that the user can load in Presentation Mode.
You may of course also load simulation run files (*.sir) files directly in Presentation Mode.
Tip! Reference runs can also be saved internally in the simulation project. They must be
marked as Public to be available in Presentation Mode.
When the user double-clicks a game file, Studio will launch the simulator in Presentation Mode and
load the saved game.
- 443 -
3. Click OK.
By applying security settings to your simulation project, you can prevent your simulator users from
accessing the underlying model. Follow the procedure below to protect your model:
1. Select Project Settings on the Project menu, and select the Presentation Mode Setup tab.
2. Select the Start up in Presentation Mode option (this will make your project automatically open in
Presentation Mode).
3. Select Protect on the Project menu.
4. Enter a password for the Full Access level of protection.
The user will now be able to open the project in Presentation mode, but will be prompted to enter a
password to switch to Design Mode to see the underlying model.
Tip! By protecting both the Run Access and Full Access levels in Studio, you can make sure
that only licensed users (who know the Run Access password) can open the simulator in
Presentation Mode. To be able to edit the model, the user must also enter the Full Access
password.
The Presentation Toolbar allows you to navigate through your simulator interface, and also allows
you to switch back to Design Mode.
- 444 -
Home
Brings you back to the default window of the simulator (as specified in the Presentation Mode Setup
property page).
Reference Data
Presentation Mode
Switch off Presentation Mode and return to Design Mode of the simulation project. If the project is
protected, you must enter the correct password to unlock the project.
Zoom
Advanced Commands
The button opens a submenu where you can work with cue points, restore permanent variables,
autoscale, and work with external data.
Help
Launches the project documentation, if one exists. Otherwise, a generic help for Presentation Mode
will be launched.
- 445 -
Work with Languages
Views in Powersim Studio support a range of different languages to make it easier for you to share
your work with colleagues who speak other languages than yourself. This allows you to enter variable
names, comments, documentation, etc., in several languages for each simulation project. The names
and texts will be saved in all the different languages you have entered. In addition to controlling the
names and texts, the selected language also influences the decimal and list separators, currency
symbols, number formatting, and so on. Thus, when you have changed languages, you must also be
aware that definitions must be entered using the separators for that language.
You select the language for the entire simulation project. However, you are free to specify the
language explicitly for each open view, should you need to. This feature is useful if you need to
translate the simulation project. If a text doesn't exist on the selected language, the text of another
language will be displayed instead, with an added prefix.
(a) The variable is named 'Inventory' in English (United States). (b) Since there is no name for the
variable in German (Germany), the English name is used with a prefix of '_ENU_' when the language
is changed to German (Germany). (c) By editing the name again, a German name for the variable is
added to the simulation project.
Tip! You can hide the language prefix from the diagrams if you wish to, by deselecting
language prefix on the View menu.
When you load a simulation project, Studio will automatically select a language for your project.
- 446 -
next two rows displays two different suggestions of names in English (United States). The ones that
are not accepted by Studio are written in red text.
First Second Third Fourth
Language Variable Variable Variable Variable Comment
Name Name Name Name
English Sales Behaviour Chips Crisps The original names of the
(United variable.
Kingdom)
Sales Behavior 'French Fries' Chips The model is localized to
US English, but since the
name Chips is already
English used in English (United
(United Kingdom), an error
States) message will be produced
for that name. The others
are valid and will be
accepted.
Sales Behavior 'French Fries' 'Potato Chips' The model is localized to
US English, and since all
English the names in both
(United languages are either
States) unique or identify the
same variable, all names
are accepted.
Salg Adferd 'Pommes frites' Chips The model is localized to
Norwegian (Bokmål), and
since Norwegian doesn't
belong to the same
Norwegian language group as English
(Bokmål) (United Kingdom), Chips
is accepted as the name for
the fourth variable, even
though it is used to
identify another variable.
When you open an existing simulation project Powersim Studio will attempt to select the language
that comes closest to the language you have selected in Regional Settings on your computer. The list
below summarizes the criteria used in this selection process. Remember that this only applies to the
first window that is opened for the project. New windows will use the same language as the currently
active window.
1. If you have worked on the project earlier, the language that you used at that time will be selected
(provided you are among the ten last users of the project).
2. Your default (system) language will be selected if it is present.
3. If only one language exists (in addition to Neutral), it will be selected.
4. If another language in the same language family of your default language is present, it will be
selected (or the one with the lowest sublanguage ID if more than one sublanguage exists).
- 447 -
5. If all the languages in the project share the same primary language ID (for example English), the
language with the lowest sublanguage ID will be selected.
6. If all else fails, one of the existing languages will be selected.
The table below provides a few examples on how this automatic language selection works.
System Language Languages in Project Selected Language
English(US) English(US) English(US)
English(UK)
English(US) Greek Greek
English(US) English(UK) English(UK)
English(Australia)
German(Germany)
English(US) German(Common) German(Germany)
German(Germany)
German(Austria)
German(Luxembourg)
English(US) German(Germany) One of the languages will be selected.
Greek
Norwegian(Bokmal)
Finnish
The Neutral language is used in Powersim Studio to give you a possibility of creating language
independent strings. If a string exists in the Neutral language, it will be used for all languages where
the same string is not defined. The variable name 'My Variable' created in English (United States) will
always be shown as '_ENU_My Variable' in all other languages, unless the language prefix is turned
off, or the string is already defined on the selected language. However, if you enter the variable name
in the Neutral language, it will always appear as 'My Variable' for all languages that don't already
have a name defined.
Note! We recommend that you use a "real" language for all strings that are related to a
language, and use Neutral only for strings that are common between all languages. Examples
of such strings are unit names (at least for standard ST units) and strings built entirely by field
codes.
For the Neutral language, the list, decimal, and thousand separator will be constant, regardless of the
options you have selected in Regional Settings on your computer. The table below shows the
separators used by the Neutral language.
Separator Sign
List ; (semicolon)
Decimal . (punctuation)
Thousand , (comma)
- 448 -
The Common Languages
The Common languages belong to a language group and will define strings that will appear for all
languages of that language group. Common languages are now not used when creating simulation
projects anymore, and they will only appear in your simulation project if it already had strings in this
language when it was opened.
In newer versions of Studio, languages belonging to a language group will share the same name
space, which replaces the need of the common languages.
We recommend that all new simulation projects utilize one of the "real" languages available for
selection.
Note! Be aware that the selected language also influences decimal separators, list separators,
currency symbols, and other settings found in Regional Settings on your computer.
You can override the language selection of the project for a single view, if you wish to.
1. Select Language on the View menu.
2. On the submenu, click Select…
3. Select the language you wish to use for the view in the dialog box, and click OK.
The language selection is only used for the current view, and will be displayed in the titlebar of the
view. If you close the view, the language setting will be reset.
To reset the language selection of the view to the project default:
1. Select Language on the View menu.
2. Select Automatic on the submenu.
Note! Be aware that the selected language also influences decimal separators, list separators,
currency symbols, and other settings found in Regional Settings on your computer.
When you create your model, all the texts that you enter are stored only on the language that was
selected. If you share your model with a user with a different language setup than yourself, language
- 449 -
prefixes will be displayed. This is very useful when you are translating your model, but it can be
annoying and tedious in some cases. You therefore have the ability in Studio to turn off the language
prefix.
Note! The language prefix will not be hidden in definitions (variable, unit, or range).
! Select Language Prefix on the View menu to display language prefixes. A check mark will
appear in front of the option to indicate that the option is turned on. (The option is selected by
default.)
! Deselect Language Prefix on the View menu to hide language prefixes. A check mark will
disappear to indicate that the option is turned off.
Note! The selection above only affects the prefix of strings viewed in diagrams. Language
prefixes will still be shown in variable definitions and in the Details Window and Equations
View. The selected language still influences decimal separators, list separators, currency
symbols, and other settings found in Regional Settings on your computer.
Translate a Project
The built-in language support in Powersim Studio makes it easy for you to translate your simulation
project to other languages. Below is a suggested procedure for translating your project.
Tip! It is recommended that you do all the development of your model in your own language to
avoid confusion, since decimal and list separators also follow the selected language.
- 450 -
names can be translated directly in the view, while the range elements are translated in the
Rename Elements dialog box, available on the shortcut menu of the range itself.
Note! If you use the Language box available on the toolbar or on the Project menu, you will
change the language for the entire simulation project, and not only for the current view.
- 451 -
Finding Variables in Studio
When you are creating models in Studio, and especially large ones, you will often need to search for
variables in your project. Studio's extensive search capabilities allows you to search not only for given
variables in both equations and diagrams, but also for other variables that are defined by the given
variable.
Locating variables that are the "source" of trouble for other variables is often a tedious task. Studio
now allows you to select a variable, and then search for the corresponding problematic variables. A
variable is called problematic when the reason why it is undefined is given entirely in its own
definition, and not caused by linked variables being undefined. When you are debugging a large
model, you should always start by searching for problematic variables. This might save you a lot of
time and energy.
Problematic variables are variables that are undefined in themselves; they are not undefined because
one of their linked variables are undefined (in which case the linked variable might be problematic
instead). Thus, problematic variables are sources of other variables being undefined.
The model described below shows a model structure where several variables are undefined.
Given the definitions above, we immediately conclude that both variables C and D are defined
properly, but they are both still undefined since variables A and B are undefined. Therefore, these two
variables are problematic variables for both C and D. By selecting C or D as the variable in the Go To
Variable dialog box and selecting the Problematic Variable(s) for Selected Variable option, Studio
- 452 -
will locate A and B for you.
Defining A will fix only part of the problem, as can be seen in the illustration below.
C and D are still undefined, and searching for problematic variables will disclose B as the source of
the problem. Defining B rules out the problem, as displayed below.
aux A = 10<<m>>
aux B = 4<<m>>
Problematic variables represent variables that cause problems for other variables. When resolving
problems in your model, you should start by locating the problematic variables and define them
properly.
To find problematic variables in your model:
1. Click Go To Variable on the toolbar, or select Go To… on the Edit menu.
2. Select the Variable named under Go to what, and select the Problematic option under Enter
Variable Name to display only problematic variables in the Variable list.
3. Select the variable you wish to find in the Enter Variable Name combo box (or type the name
manually).
4. Select the scope of the search under Look In (and under Scope, if you search in Diagrams).
5. Click Next to find the variable.
You can also search for the problematic variables of an undefined variable:
1. Click Go To Variable on the toolbar, or select Go To… on the Edit menu.
2. Select Problematic Variable of under Go to what.
- 453 -
3. Select the variable for which you wish to find the corresponding problematic variables, in Enter
Variable Name (or type the name manually). To display only undefined variables in the list, select
the Undefined option under Enter Variable Name.
4. Select the scope of the search under Look In (and under Scope, if you search in Diagrams).
5. Click Next to find the variable.
6. To find the next problematic variable for the selected variable, simply click F3 or click Go to
Next Variable on the toolbar.
Tip! Hit Ctrl-G to open the Go To Variable dialog box, F3 to find the next variable, and
Shift-F3 to find the previous variable. You can also click Go to Next Variable and
Go to Previous Variable on the toolbar.
Tip! Hit Ctrl-G to open the Go To Variable dialog box, F3 to find the next variable, and
Shift-F3 to find the previous variable.
Tip! Hit Ctrl-G to open the Go To Variable dialog box, F3 to find the next variable, and
Shift-F3 to find the previous variable. If you hit CTRL-F3 , Studio will locate the next
variable (if any) that is defined by the variable that is currently selected.
- 454 -
Find Variables Defined by the Selected Variable
Studio allows you to easily find variables that are defined by the selected variable:
1. Select the variable in the diagram that you wish to find in other variable's definitions.
2. Hit CTRL+F3.
If there are other variables in the simulation project that are defined by the selected variable, Studio
will locate them for you.
Go To a Variable
1. Click Go To Variable.
2. Select the name of the variable you wish to go to under Enter Variable Name combo box. You
can use the three available options under Filter to filter the variable selection available in the
combo box. If you select Undefined, only undefined variables will populate the list, and if you
select Problematic, you will only find problematic variables in the list.
3. You can search for the selected variable itself, for other variables that are defined by the selected
variable, or the variable's problematic variables under Go to what.. Select the option that best suits
your needs. You have three alternatives:
! Select Variable named to go to the variable itself;
! Select Variables defined by to go to variables that are defined by the selected variable;
! Select Problematic variables of to go to variables that cause problems for the definition of the
selected variable.
4. Select the scope of the search. You can search in diagrams, equations, or both. If you wish to
search in diagrams, you must also select whether you wish to search only the active diagram, the
selected diagrams, or if you would like to run the search in all the available diagrams.
5. Click Next (or Previous) to find a variable that matches your search.
6. Click Go To Next Variable or hit F3 to find the next variable that matches your search.
7. Click Go To Previous Variable or hit Shift-F3 to find the previous variable that matches
your search.
The located variable is highlighted.
When you have performed a search, you can easily find the next (or previous) variables that match
your search criteria:
! Click Go To Next Variable to search for the next variable that matches your search.
! Hit F3 to search for the next variable that matches your search.
! Click Go To Previous Variable to search for the previous variable that matches your search.
! Hit Shift-F3 to search for the previous variable that matches your search.
- 455 -
Work with Events
You can use events to implement interactive simulations. When you create an event, you connect it to
a logical variable in your simulation project. When the logical variable becomes TRUE (or NAN, if
you prefer), the event will be triggered. When the event is triggered, you can specify how the
simulation should proceed.
An event is composed by several actions. There are currently three action types available:
hyperlink, Message Box, and Set Parameter. You can use these actions to implement various
types of interactivity in your simulator.
You work with events in the Events View, available by double-clicking the Events entry in the
Project Window. Events are added on the outer level, and actions added below each event to
achieve the desired effect. The illustration below gives an example on what an event might look like.
There are currently three action types available in Studio. The actions and their properties are
summarized in the table below.
Message Box
This action displays a message box when the condition is met. You are allowed to use any standard
message box in Windows, with various button arrangements and icons. You author the title and
contents of the message box freely.
When you insert a Message Box action in the Events tree, corresponding return values marked with
, are automatically inserted below the action entry. You can use these return values to provide
- 456 -
actions based on the input from the user. Using the return values you can allow the user to select
between several options and implement them by inserting actions below the return values, as
illustrated below.
The return values, in this case OnOK and OnCancel can be used to program various actions
depending on the user input.
Note! The return values will correspond to the type of message box you have selected. For a
Yes/No message box, the return values will be OnYes and OnNo, and so forth.
If you change the button combination for the message box, you might get different return values. If
the return values still exists for the altered message box, it will be used without any changes. If the
return value no longer exists and has actions, it will be marked by to indicate that the message box
will not return that value. This way the actions that were assigned to the return value are not lost if
you change the type of message box. The return value will of course never be executed, and you
should copy or move the actions to the appropriate return value where they belong.
The table below describes the properties of the Message Box Action.
Type
The button configuration of the message box you want to display. You can select
Description between the standard button configurations available in Windows. These are listed
below.
Abort, Retry, Ignore
OK
OK, Cancel
Options
Retry, Cancel
Yes, No
Yes, No, Cancel
Icon
The type of message box you want to display. You can select between the standard
Description message box types available in Windows. These are listed below together with the
icon that they feature.
<No Icon>
Error:
Options Information:
Question:
Warning:
- 457 -
Title
Description The title of the message box.
Message Text
The message (body) text of the message box. The message box will automatically
Description
adjust to the size of the message text.
Set Parameter
The Set Parameter event allows you to change the value of a parameter in your model depending on a
whether a condition is met or not. The action is pretty straight-forward to use. Simply select the
variable you want to change, and enter the value you wish to change it to.
Tip! If you use the Set Parameter action in combination with the Message Box action, you can
control the value of a variable depending on the user input, as mentioned above (under
Message Box).
The table below describes the properties of the Set Parameter Action.
Parameter
Description The parameter you wish to change when the action is executed.
Value
Description The value you wish to assign to the parameter.
Hyperlink
The hyperlink allows you to jump to a bookmark, window, or another URL when the action is
executed. Defining the hyperlink action is more or less identical with defining the hyperlink diagram
object. You simply select the target of the hyperlink, and that's it.
Tip! You can use the hyperlink action to launch files, send e-mail, visit web pages, or go to a
different part of the simulation project.
Event Properties
When you create an event, you must also connect it to a variable containing the condition deciding
when the event is triggered. You can also specify how the simulation should behave when the event is
triggered. You can also disable the event. This is useful, as it allows you to prevent the event from
happening without having to delete the entire event or alternatively redefine it.
The table below describes the various properties of the event. You can access these properties in the
Event property page, available on the shortcut menu when right-clicking the event in the Events View.
- 458 -
Property Description
Condition
The variable that the event "listens" to. This variable must be a LOGICAL
Variable
variable.
The event will be triggered when the value of the selected variable becomes
Trigger on TRUE. Note that the event will not be triggered again until the variable
TRUE becomes TRUE again, after being FALSE (or NAN). It will not be triggered
every time step, if the value of the variable doesn't change.
The event will be triggered when the value of the selected variable becomes
NAN. Note that the event will not be triggered again until the variable
Trigger on NAN
becomes NAN again, after being TRUE or FALSE. It will not be triggered
every time step, if the value of the variable doesn't change.
Simulation Control
Pause When The simulation will be paused when the condition becomes TRUE. You can
Condition continue the simulation immediately.
Becomes TRUE
The simulation cannot be started until the Condition is FALSE. By selecting
Prevent Play this option you can prevent your user from running the simulation more until
While Condition the input parameters are "correct." If your user attempts to start the
Is TRUE simulation, a message box with the text entered under Prevent Play Message
will appear.
Try Playing Once the event is finished, the event will attempt to start the simulation again.
Simulation After Normally this will work fine, unless you have other events that prevent the
Event simulation from proceeding (see above).
Miscellaneous
This option disables the event, and gives you the opportunity to "turn off" an
Disabled
event without deleting it.
Prevent Play The Prevent Play Message will appear if the user attempts to play the
Message simulation while the Condition is TRUE.
Add an Event
Define an Event
When you have added an event to the Events View, you can define it:
1. Right-click the event, and select Properties on the shortcut menu.
2. In the Variable box, select the variable containing the condition that you want to connect the
- 459 -
event to.
3. Select whether the event should be triggered when the selected variable becomes TRUE or NAN.
4. Select the way that the event should handle the simulation. You can have the event stop the
simulation, prevent the simulation from playing as long as the condition is met, prevent the
simulation from playing while any actions are being executed, and have the simulation run again
once the event is finished. Note that you can combine the various simulation options.
5. If you choose to let the event prevent the simulation from playing while the condition is TRUE,
you should also enter a message that will be presented to the user if she tries to run the simulation
again. Enter this message under Prevent Play Message.
6. You can disable the event if you don't want it to be triggered when the condition is met. This
option is ideal when you want to stop the event from occuring but avoid deleting it from the
project.
You can manually change the order of the events. This allows you to control the order of execution if
two events have the same condition. This might affect the final result of the events.
Tip! Although several events may very well share the same condition, the same effects can
normally be achieved by adding more actions to one event. This will prevent any execution
order conflicts, as actions are processed in the order they appear inside the event.
When you have added an event to your project, you can add actions to it:
1. Right-click the event, and select Add Action on the shortcut menu.
2. Select the action you wish to add on the submenu. You have three options:
! Hyperlink
! Message Box
! Set Parameter
3. Click Expand to see the newly created actions.
You should then proceed to define the actions, or add new ones. You can also add actions to return
values from Message Box Actions.
Tip! You can change the order of the actions within an event on the action's shortcut menu.
- 460 -
Change Action Order
You can manually change the order of the actions for an event. This allows you to control the order of
execution, which is crucial to achieving the effects you desire.
Note! You can only move actions on the same level. As an example, moving an action from
under a return value of a Message Box action and up above the Message Box action itself, is
not possible.
Delete an Action
To delete an action:
1. Select the action you wish to delete in the Events view.
2. Right-click it and select Delete on the shortcut menu, or hit Del on your keyboard.
Delete an Event
To delete an event:
1. Select the event you wish to delete in the Events view.
2. Right-click it and select Delete on the shortcut menu, or hit Del on your keyboard.
Tip! It is possible to disable an event in the property page. This allows you to to keep unused
events in your project without triggering them every time the condition is met.
- 461 -
Printing a Simulation Project
Studio allows you to print different aspects of your simulation project. You can print the content of
the active window by clicking Print.
You control the scaling, margins, and orientation of the printed page in the Page Setup dialog box.
The Print… dialog box allows you to select which diagrams you want to print, and whether you wish
to print equations.
Tip! When you have changed the page or margin setup, page break lines will become visible in
your diagram sheet.
If you print the equations of a simulation project, be aware that it's not only the variable equations
from the active component that is printed, but all equations in your simulation project. This includes
both global units and ranges, as well as all variables, local ranges and local units in all the components
of the project. The equations are printed in a "C-like" syntax. Although the printed equations might
look a bit complex at first, the syntax is rather self-explanatory.
When you print the equations from a simulation project, the document is printed in a specialized
syntax. Although the printed equations might seem complex at first sight, the syntax is fairly self-
explanatory. The printed equations cover all variables, local ranges, and local units in all components,
in addition to global ranges and units. Each defined object (variable, unit, etc.) appears in the
equations list as an entry. The properties of each object is listed below the object, enclosed by '{' and
'}' (braces), as you will probably recognize from Java or C++.
The table below briefly summarizes the various entries in the equations syntax. The list is not
complete, but in most cases the meaning of the entry is rather obvious.
Entry Description
A component in the simulation project. The variables are listed below the
mainmodel
component they belong to.
level A level variable.
aux An auxiliary variable.
model A submodel variable.
A unit. If the unit appears inside a mainmodel entry, it is a local unit. If the unit
- 462 -
unit (or appears inside a level or aux entry, it represents the unit of the variable. If the
autounit) unit is automatically detected by Studio, the entry is named autounit.
range A range. If the range appears inside a mainmodel entry, it is a local range.
type (or The data type of a variable. If the data type is automatically detected by Studio,
autotype) the entry is named autotype.
dim (or The dimension of a variable. If the dimension is automatically detected by Studio,
autodim) the entry is named autodim.
inflow A flow into a level. The entry represents a flow definition.
outflow A flow out of a level. The entry represents a flow definition.
def The definition of a level, auxiliary, unit, range, inflow, or outflow.
init The initial value of a level or constant auxiliary.
doc The documentation of an entry.
note The note of an entry.
mainmodel Component1 {
level distance {
type real
unit m
init 1
inflow { def Production }
}
aux Production {
autotype real
autounit da^-1
autodim 1..3
def sinwave(1,90<<da>>)
note Remember to connect to Sales.
}
}
unit A {
def __ampere
doc Ampere - electric current
}
range Regions {
def north,east,south,west
note Represents the four directions.
}
(...)
- 463 -
tabs.
2. Click Print on the File menu.
3. Select Diagram under Print What, and then select Selected Diagram(s).
4. Click OK to start printing and close the dialog box.
Tip! You can print diagrams and equations at the same time by selecting both.
Tip! If you click Print on the Standard menu, you will print directly to the printer using the
previous settings.
Print Equations
1. Select Print on the File menu.
2. Select Equations under Print What.
3. Click OK to start printing and close the dialog box.
You can print several copies by entering a number under Number of copies.
Tip! You can print diagrams and equations at the same time by selecting both.
Tip! If you click Print on the Standard menu, you will print directly to the printer using the
previous settings.
- 464 -
Set Page Orientation
1. Select Page Setup on the File menu.
2. Click the Page tab.
3. Select Portrait or Landscape.
4. Click OK.
You may reduce or enlarge a diagram to a percentage of the normal size, or fit it to a given number of
pages.
To adjust the contents to a percentage of normal size:
1. On the File menu, click Page Setup, and then click the Page tab.
2. Under Scaling, click the Adjust to radio button.
3. Select or enter the percentage of normal size that you want your page to be.
4. Click OK to save the page setup.
To fit the page to a given number of pages:
1. On the File menu, click Page Setup, and then click the Page tab.
2. Under Scaling, click the Fit to radio button.
3. Enter the number of pages width and height of the printed diagrams.
4. Click OK to save the page setup.
- 465 -
www.powersim.com
Powersim Software AS
E-mail powersim@powersim.no
Web www.powersim.com