PPoowweerrssiimm SSttuuddiioo 22000033 UUsseerr’’ss GGuuiiddee

Powersim Studio 2003 User's Guide

by Powersim Software AS The Business Simulation Company

Sandbrugt. 5-7 ● PO Box 3961, Dreggen ● N-5835 Bergen ● Norway

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.

Foreword

Making business decisions

Today, business simulations are used in making business decisions. Faced with a decision on where to build natural gas storage containers, and how big to build these containers, one oil company used Powersim to build a simulation of the wells, the pipelines, and the markets. Once the simulation was built, decision-makers at the oil company could try different storage container scenarios. The consequences of the different scenarios could be understood in a risk-free environment before any investments in construction of storage containers were made.

Business simulations are also used in explaining business decisions to others in the organizations. For example, a major telecommunications company saw many of their competitors making risky forays into interactive television, adventures that were garnering much publicity. It was not enough to just focus on their core business; they also had to explain to the employees why investing in interactive TV and similar ventures were bad business decisions. This telecommunications company built an interactive simulation of how they perceived their business. Over 1200 employees used this simulation in a series of management training workshops, where employees had an opportunity to run the simulated business and make investment decisions. The employees gained new appreciation for the corporate strategy, and a better understanding of how the thought leaders in their organization saw the dynamics of the next few years unfolding.

Both of these simulation success stories were achieved using Powersim software. In each case a team of modelers and thought leaders from the business collaborated to build a custom model of the business problem. The models contained enough of the important details and complexities of the real world situation to be useful and believable.

Business simulations more common

The use of simulation in business is not yet an everyday occurrence, but it is spreading. In 1990, both of these examples would have been quite unusual. Although simulation technology was well understood by 1990, and the cost of the necessary software tools had become modest, very few business decisions were supported by simulating the consequences before taking action. It simply was not part of standard business practice. Now things are changing, and the use of business simulation is becoming more common.

At Powersim Software AS, we are committed to supporting the emerging practice of business simulation. We appreciate that the process of business decision-making is different from that of decision-making in public policy. Our tools are focused on modeling business problems, not on public policy or academic issues.

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.

The joy of simulators

Who has the time and interest to play with a business simulator? Everyone seems to make time. Some commercial simulators – like SimCity and The Sims – are so much fun to play that they are sold as entertainment. While few business executives might admit to playing games, they will gladly play with a custom business simulator, crafted to model an aspect of their current environment. One very serious senior executive remarked that playing a custom simulator of his telecommunications company was "a joyful experience." Another senior executive at the same organization spent 10 hours over two evenings playing the simulation.

Crafting a joyful experience can mean the difference between 4 people understanding your model and its implications--and 1000 people understanding it. And joy is impossible if casual users must struggle with arcane controls, obscure commands, or cryptic numerical displays.

The value of simulators

Joy alone is not enough in a business context: there must also be value. What is the value of business managers playing a business simulator? Do the people playing the simulation make better decisions? Do they learn more about the world in which they must succeed?

For many years, we in the business modeling community have approached the problem of creating value by teaching business people a new way of thinking. We have taught them the basics of building models, and when that was too difficult, we taught "systems thinking," how to see their world the way a modeler might see it. Systems thinking is undoubtedly valuable for anyone who chooses to undergo the education--but it has certain shortcomings as a discipline that can be put to use within a business. Some people will never learn how to think systemically; and in fact, business people expect something less abstract and more tangible for their investments in time and money. Provide them a simulated experience – with their new situation, in their industry, in their context, with their assets and constraints – and you’ve empowered them to solve existing problems, and avoid potential ones.

Our goal at Powersim Software AS is to support you in "publishing" custom models of your business, making them available to everyone who might need to know or care. And there are a lot of people who might care: existing employees, new recruits, suppliers, distributors, customers, and investors.

Learning from simulators

By playing a simulator, by trying different combinations of decisions, a business manager can understand a simulation in a kind of kinesthetic way. Just as you don’t need to understand the physics of skiing to learn how to ski, in the same way it is possible to play a simulation model and learn the dynamics of a business situation – without understanding the details of the underlying

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!

The Powersim Software Development Team

Table of Contents

Foreword............................................................................................................................ 5

Table of Contents .............................................................................................................. 9

Getting Started ................................................................................................................ 25

What’s new in Powersim Studio 2003? ......................................................................... 28

Introduction to System Dynamics.................................................................................. 32 The tools and rules of System Dynamics ............................................................ 35 Building the models ............................................................................................ 41 Building blocks in Powersim Studio................................................................... 44 Creating a model ................................................................................................. 47

Importing models from Powersim Constructor 2.51 ................................................... 48 About variable conversion .................................................................................. 48 About diagram conversion .................................................................................. 51 About simulation conversion .............................................................................. 52 Convert the ASSIGN function ............................................................................ 53 Convert constrained expressions......................................................................... 56 Convert the SHIFT functions .............................................................................. 57 Convert the LIMIT functions .............................................................................. 61

Working with help in Powersim Studio ........................................................................ 63 Topic layout ........................................................................................................ 63 The help window................................................................................................. 64

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

Work with Powersim Studio .......................................................................................... 69 Components and simulations .............................................................................. 70

Work with a simulation project ..................................................................................... 72 Create a simulation project.................................................................................. 72 Create project documentation ............................................................................. 72 Open an existing project ..................................................................................... 73 Save a simulation project .................................................................................... 73 Create a backup project....................................................................................... 74 Restore a backup project ..................................................................................... 74 Compact a simulation project.............................................................................. 74 View project documentation ............................................................................... 75 Show and edit project information...................................................................... 75 Show recently opened projects............................................................................ 75 View project statistics ......................................................................................... 76 Work with levels of protection............................................................................ 76 Levels of protection ............................................................................................ 76 Protect the simulation project.............................................................................. 77 Unprotect the simulation project ......................................................................... 77 Change level of protection .................................................................................. 77 Redo an operation ............................................................................................... 77 Undo an operation............................................................................................... 77

Work with windows and diagrams................................................................................ 79 View equations.................................................................................................... 80 Create a new diagram sheet................................................................................. 80 Select sheets ........................................................................................................ 80 Move sheets......................................................................................................... 81 Exclude a sheet.................................................................................................... 81 Include a sheet..................................................................................................... 81 Rename a sheet.................................................................................................... 81 Delete a sheet ...................................................................................................... 82 Adjust columns in treeviews ............................................................................... 82

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

Working with components ........................................................................................... 107 About simulations ............................................................................................. 108 About private and shared diagrams................................................................... 108 Create a new component ................................................................................... 109 Rename a component ........................................................................................ 109 Add a simulation to the component .................................................................. 109 Open a simulation’s diagram window............................................................... 110 Create a submodel from a component............................................................... 110 Delete a component........................................................................................... 113

Constructor and Interaction Diagrams....................................................................... 114

Work with Constructor diagrams ............................................................................... 116 Diagrams and models........................................................................................ 116 The building blocks of a Constructor diagram.................................................. 117 Constructor diagram symbols ........................................................................... 118

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

Working with variables in Constructor diagrams ..................................................... 124 About snapshots ................................................................................................ 125 Create a level..................................................................................................... 125 Create an auxiliary ............................................................................................ 126 Create a constant ............................................................................................... 126 Create a flow rate variable ................................................................................ 127 Create a snapshot .............................................................................................. 127 Go to original from a snapshot.......................................................................... 128 Make original from a snapshot.......................................................................... 128 Create a reservoir .............................................................................................. 128 Name and rename a variable ............................................................................. 129 Resize a basic variable symbol ......................................................................... 130 Scale a basic variable symbol ........................................................................... 130

Work with links and flows............................................................................................ 131 Keyboard modifiers when working with links and flows ................................. 131 Change the shape of a link ................................................................................ 132 Create a link ...................................................................................................... 133 Create an initialization link ............................................................................... 133 Create a delayed link......................................................................................... 133 Delete a link ...................................................................................................... 134 Change the shape of a flow ............................................................................... 134 Create a flow ..................................................................................................... 135 Create a flow without a rate variable ................................................................ 135 Disconnect the head or tail of a flow ................................................................ 136 Reconnect a flow to a different level ................................................................ 136 Detach a flow rate variable ............................................................................... 136 Attach a flow rate variable ................................................................................ 136 Move the valve of a flow .................................................................................. 137 Change the rate variable of a flow .................................................................... 137 Delete a rate variable......................................................................................... 138 Delete a flow ..................................................................................................... 138

Build hierarchical models............................................................................................. 139 About submodels............................................................................................... 140 About submodel diagrams ................................................................................ 142 About public variables ...................................................................................... 142 About child variables in auxiliaries, levels, and constants................................ 143

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

Work with diagram editing .......................................................................................... 152 Drag and drop operations .................................................................................. 153 Include a model variable in a diagram .............................................................. 154 Exclude a model variable from a diagram ........................................................ 154 Delete a variable................................................................................................ 154 Link variables to Powersim Controls ................................................................ 155 Copy and paste an object .................................................................................. 156 Cut and paste an object ..................................................................................... 156 Copy an area as a picture .................................................................................. 156 Paste from Windows Clipboard ........................................................................ 157 Select objects..................................................................................................... 157 Select multiple objects ...................................................................................... 158 Select dominant object ...................................................................................... 158 Move an object.................................................................................................. 158 Position an object by coordinates...................................................................... 159 Delete diagram objects...................................................................................... 159

Work with nodes, segments and lines.......................................................................... 160 Types of nodes .................................................................................................. 161 Types of segments............................................................................................. 161 Add a node ........................................................................................................ 162 Change the type of a node................................................................................. 162 Change the type of all nodes of a line ............................................................... 162 Delete a node..................................................................................................... 162 Change the type of a segment ........................................................................... 163 Change the type of all segments of a line ......................................................... 163 Drag a line into a new shape ............................................................................. 163 Make an elbowed line ....................................................................................... 163 Change a line into a single curved segment ...................................................... 164 Change a line into a single straight segment ..................................................... 164

Work with the Details Window.................................................................................... 166 Show and hide the Details Window.................................................................. 167 Display the Detail Window at top..................................................................... 167 Auto-synchronize Details with diagram............................................................ 168

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

Working with grids and guides.................................................................................... 173 Show or hide rulers ........................................................................................... 174 Turn the display of grid on/off .......................................................................... 174 Turn the display of guides on/off ...................................................................... 175 Turn snap to regular grid on/off ........................................................................ 175 Turn snap to the radial grid on/off .................................................................... 175 Turn snap to guides on/off ................................................................................ 175 Change grid settings.......................................................................................... 176 Change guide settings ....................................................................................... 176 Insert guides ...................................................................................................... 177 Move guides...................................................................................................... 177 Delete guides..................................................................................................... 178

Work with object properties ........................................................................................ 179 Format several objects in one operation............................................................ 179 Format text ........................................................................................................ 180 Format the diagram background ....................................................................... 180 Use picture fills for objects ............................................................................... 180 Align diagram objects ....................................................................................... 181 Rotate diagram objects...................................................................................... 181 Space diagram objects....................................................................................... 182 Make diagram objects the same size ................................................................. 182 Position objects ................................................................................................. 183 Resize an object ................................................................................................ 183 Resize a multiple selection................................................................................ 183 Change line style and color ............................................................................... 184 Change object color and shape.......................................................................... 184

Work with freeforms, frames, hyperlinks and bookmarks ....................................... 186 About bookmarks.............................................................................................. 186 About hyperlinks............................................................................................... 187 Add a frame....................................................................................................... 188 Add text to a frame............................................................................................ 188 Add a picture to a frame.................................................................................... 189

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

Work with zoom............................................................................................................ 196 Zoom a diagram ................................................................................................ 196 Zoom a selection ............................................................................................... 196 Zoom to fit diagram in view.............................................................................. 197

Work with simulations.................................................................................................. 198 About simulation state and history.................................................................... 199 The calendars .................................................................................................... 199 Simulations without time units ......................................................................... 200 Set preferred time units ..................................................................................... 201 Set simulation times .......................................................................................... 202 Change the calendar .......................................................................................... 203 Select available calendars ................................................................................. 203 Set start time and stop time ............................................................................... 204 Set the time step ................................................................................................ 204 Set the simulation speed.................................................................................... 204 Autoscale variables when simulation is paused ................................................ 205 Keep history for all variables ............................................................................ 205 Save simulation state with project..................................................................... 205 Set the run count ............................................................................................... 206 Turn o/off time units for simulation time.......................................................... 206 Integration methods........................................................................................... 207 About integration .............................................................................................. 208 Integration methods: Known quirks.................................................................. 209 The Euler integration method............................................................................ 209 The Runge-Kutta integration methods .............................................................. 210 Set integration order.......................................................................................... 211 Start and stop a simulation ................................................................................ 211 Play a simulation stepwise ................................................................................ 211 Reset a simulation ............................................................................................. 212

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

Working with Units of Measurement .......................................................................... 220 About unit operations........................................................................................ 221 Properties, Identifiers, and pre-defined units .................................................... 222 Create a model without units............................................................................. 227 Available time units in the project .................................................................... 227 Add a global unit............................................................................................... 228 Add a local unit ................................................................................................. 228 Add currency units ............................................................................................ 229 Add standard units ............................................................................................ 230 Define an atomic unit ........................................................................................ 230 Define a derived normal unit............................................................................. 230 Define a derived point unit................................................................................ 231 Specify a unit for a level ................................................................................... 232 Specify a unit for a constant.............................................................................. 232 Specify a unit for an auxiliary........................................................................... 233 Include units in variable expressions ................................................................ 233 Explicitly select unit for an expression ............................................................. 234 Create unitless variable expressions.................................................................. 235 Delete a global unit ........................................................................................... 235 Delete a local unit ............................................................................................. 236

Working with variable definitions............................................................................... 237 Variable properties and options ........................................................................ 238 About permanent variables ............................................................................... 241 About reservoirs................................................................................................ 241 Variable definition examples ............................................................................ 243 About continuous flows .................................................................................... 248

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

Working with the Equations View............................................................................... 281 Create a variable in the Equations View ........................................................... 281 Create a link in the Equations View.................................................................. 282 Define a variable ............................................................................................... 282 Create a flow in the Equations View................................................................. 282 Reverse a flow in the Equations View .............................................................. 283 Change variable type in the Equations View .................................................... 283 Delete an object................................................................................................. 283

Working with Range and Index Variables ................................................................. 285 Types of ranges ................................................................................................. 285 About index variables ....................................................................................... 286 Add a global range ............................................................................................ 288 Add a local range .............................................................................................. 288 Create an index variable.................................................................................... 288

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

Work with summary types ........................................................................................... 293 Summary types and discrete variables .............................................................. 294

Working with arrays..................................................................................................... 297 Why use arrays? ................................................................................................ 297 Create layered models using arrays................................................................... 299 Create queues using arrays................................................................................ 299 Array syntax...................................................................................................... 300 Create arrays ..................................................................................................... 301 Create arrays using ranges and subranges......................................................... 302 Build arrays element by element....................................................................... 303 Build arrays using the FOR function ................................................................ 303 Build arrays using the CONCAT function........................................................ 305 Index arrays....................................................................................................... 305 Index arrays using the INDEX function............................................................ 306 Use basic variables as index variables .............................................................. 307 Index arrays using ranges and subranges .......................................................... 307 Redimension arrays........................................................................................... 308

About Powersim Controls ............................................................................................ 310 Insert a control in your diagram........................................................................ 311 Move a control .................................................................................................. 311 Use index variables in controls ......................................................................... 311 Delete a control ................................................................................................. 313 Toggle between Design and User Mode ........................................................... 313

Work with parameters.................................................................................................. 315 Add active run parameters to a control ............................................................. 315 Add reference run parameters to a control ........................................................ 316 Add simulation control parameters to a control ................................................ 316 Add index variable parameters to a control ...................................................... 317 Add parameters with summary types................................................................ 317 Adjust the scale of a parameter ......................................................................... 318 Remove parameters from a control ................................................................... 318

Hide or show parameters in User Mode............................................................ 319 Change the input mode of a control .................................................................. 319

Formatting controls ...................................................................................................... 321 Axis formatting ................................................................................................. 321 The value axis and parameters with different units........................................... 322 Resize a control ................................................................................................. 323 Format an axis................................................................................................... 323 Change position of an axis ................................................................................ 324 Change the orientation of text in controls ......................................................... 324 Show label for an axis ....................................................................................... 325 Change the scaling of the value axis ................................................................. 325 Customize the appearance of a control ............................................................. 325 Change position of the unit label ...................................................................... 326 Show and format the title .................................................................................. 326

About field codes ........................................................................................................... 327 Field codes and languages................................................................................. 329 Legends and parameter titles when using field codes ....................................... 330 Define a field code ............................................................................................ 331

Work with the Chart Control ...................................................................................... 333 Format the graphs.............................................................................................. 334 Change the graph type of a parameter............................................................... 334 Change the order of parameters ........................................................................ 335 Hide parameters from the chart......................................................................... 335 Show hidden parameters in the chart ................................................................ 335 Format the chart area......................................................................................... 336 Show gridlines................................................................................................... 336 Toggle on/off the legend for the chart............................................................... 336 Presenting a set of scalar variables in a Chart Control...................................... 337 Use the Chart Control as an input object .......................................................... 337

Work with the Gauge Control ..................................................................................... 339 Examples of gauge formatting .......................................................................... 339 Gauge dial properties ........................................................................................ 341 Gauge needle properties.................................................................................... 343 Format the gauge dial........................................................................................ 344 Format the gauge needle ................................................................................... 345 Format the gauge hub........................................................................................ 346 Show or hide the gauge hub.............................................................................. 346 Rotate the Gauge Control.................................................................................. 347 Use the Gauge Control as an input control ....................................................... 347 Create a gauge with sectors............................................................................... 348

Work with the Slider Bar Control ............................................................................... 349 Change the orientation of the slider bar ............................................................ 349

Work with the Switch Control ..................................................................................... 350 Create a button .................................................................................................. 351 Create a check button........................................................................................ 351 Create radio buttons .......................................................................................... 352 Create a list box................................................................................................. 353 Create a combo box........................................................................................... 354 Create a static text object .................................................................................. 354 Use the Switch Control to select strategy ......................................................... 355

Work with the Table Control....................................................................................... 357 Add an Array to the Table Control ................................................................... 357 Add or insert a column in the Table Control..................................................... 358 Add or insert a row in the Table Control .......................................................... 358 Display text in a cell.......................................................................................... 358 Display a variable’s name in a cell ................................................................... 359 Display a variable’s value in a cell ................................................................... 359 Change the height of rows and width of columns............................................. 360 Delete a column in the Table Control ............................................................... 360 Delete a Row in the Table Control.................................................................... 360 Use the Table Control as an input object .......................................................... 360

Work with the Time Graph Control ........................................................................... 362 Format the graphs.............................................................................................. 362 Format the time axis in the Time Graph Control .............................................. 363 Use parameters with summary types in the Time Graph Control ..................... 365 Change the order of parameters ........................................................................ 365 Change the graph type of a parameter............................................................... 366 Hide parameters from the Time Graph ............................................................. 366 Show hidden parameters in the Time Graph..................................................... 367 Show and export the history of a parameter...................................................... 367 Format the graph area ....................................................................................... 367 Show gridlines................................................................................................... 368 Toggle on/off the legend for the Time Graph ................................................... 368 Create a scrolling Time Graph .......................................................................... 368

Work with the Time Table Control ............................................................................. 370 Format the time display in the Time Table Control .......................................... 370 Change the order of parameters ........................................................................ 371 Change the reporting interval in the Time Table Control ................................. 371 Change the orientation of the Time Table......................................................... 372 Hide parameters from the Time Table Control ................................................. 372

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

Datasets in Powersim Studio ........................................................................................ 388 About datasets ................................................................................................... 388 Dataset overview............................................................................................... 389 About dataset variables ..................................................................................... 390 About dataset variable dimensions.................................................................... 390 About history in datasets................................................................................... 391 About transfers in datasets ................................................................................ 391 Create a datasets................................................................................................ 392 Connect a dataset to a component..................................................................... 393 Create dataset variables by drag and drop......................................................... 393 Create dataset variables manually..................................................................... 394 Connect model and dataset variables ................................................................ 395 Set the transfer directions for model and dataset variables ............................... 396 Set all the dataset variables to the same dimensions......................................... 397 Set the summary type for a dataset variable...................................................... 398 Set the dimension of a dataset variable ............................................................. 398 Disconnect dataset and model variables ........................................................... 399 Disconnect a dataset from a simulation ............................................................ 399 Rename a variable in the dataset ....................................................................... 399 Rename a dataset............................................................................................... 399 Rename a dataset in the Co-models View......................................................... 400 Delete dataset variables..................................................................................... 400 Delete a dataset ................................................................................................. 400 Load history from a dataset............................................................................... 400 Save a dataset .................................................................................................... 401

Edit the history of a dataset variable ................................................................. 401 Import the history of a dataset variable............................................................. 402 Export the history of a dataset variable............................................................. 403

The Studio Dataset ........................................................................................................ 403 About the Studio Dataset .................................................................................. 403 Set period information for the Studio Dataset................................................... 404

Working with the spreadsheet datset .......................................................................... 405 The inner workings of the SpreadsheetDataset ................................................. 405 Set sampling times for the dataset..................................................................... 407 Connect the dataset to a spreadsheet ................................................................. 407 Control spreadsheet layout................................................................................ 408 Define starting cell of the spreadsheet .............................................................. 409 Format a spreadsheet for transfer to a model variable ...................................... 410 Format array dimensions................................................................................... 410 Sort the order of variables in the spreadsheet ................................................... 411 Synchronize the component and the spreadsheet.............................................. 411 Update the spreadsheet with values only .......................................................... 412 Use the dataset without saving the spreadsheet ................................................ 412 Ensure valid data from spreadsheet................................................................... 413 Use names for cells, sheets, or file that change with run number ..................... 413 Use a spreadsheet template ............................................................................... 414 Use the dataset to transfer immediate behavior ................................................ 414 Use the dataset to transfer behavior over time .................................................. 414 Create a bi-directional transfer for variables..................................................... 415 Transfer behavior from a spreadsheet to a model variable ............................... 415 Transfer behavior from a model variable to a spreadsheet ............................... 416 Interpolate transferred data between data points............................................... 416 Transfer data at given times in the spreadsheet................................................. 417 Transfer all data at the end of the simulation .................................................... 418

Work with the SEM Dataset ........................................................................................ 419 How the SEM Dataset works ............................................................................ 420 Connection details for the SEM Dataset ........................................................... 422 Mapping time characteristics in SEM to simulation time ................................. 424 Time translations in the SEM Dataset............................................................... 426 Ranges and units in the SEM Dataset ............................................................... 427 Work offline with the SEM Dataset.................................................................. 428 How to prepare SEM-BPS for the SEM Dataset............................................... 429 Define a SEM Dataset....................................................................................... 433 Synchronize a SEM Dataset with SEM ............................................................ 434 Using summary types for key figures ............................................................... 434 Load and save date using the SEM Dataset ...................................................... 434

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

Utilizing modes in Studio.............................................................................................. 438 About the Presentation Mode............................................................................ 438 The difference between User and Presentation Mode....................................... 440 Create a simulator for Presentation Mode......................................................... 440 Toggle between Design and User Mode ........................................................... 441 Switch to Presentation Mode ............................................................................ 441 Switch to Design Mode from Presentation Mode ............................................. 442 Start Project in Presentation Mode.................................................................... 442 Specify the Presentation of a project................................................................. 442 Navigate in Presentation Mode ......................................................................... 442 Add and view project documentation in Presentation Mode ............................ 443 Use game files in Presentation Mode................................................................ 443 Protect your project in Presentation Mode........................................................ 444 The Presentation Mode toolbar ......................................................................... 444

Work with Languages................................................................................................... 446 Automatic language selection ........................................................................... 447 The Neutral language ........................................................................................ 448 The Common languages.................................................................................... 449 Set language for a project.................................................................................. 449 Explicitly set language for a view..................................................................... 449 Toggle language prefix on/off........................................................................... 449 Translate a project ............................................................................................. 450

Finding variables........................................................................................................... 452 About problematic variables ............................................................................. 452 Find problematic variables................................................................................ 453 Find undefined variables ................................................................................... 454 Find variables by definition .............................................................................. 454 Find variables defined by the selected variable ................................................ 455 Go to a variable ................................................................................................. 455 Go to next variable............................................................................................ 455

Working with events ..................................................................................................... 456 Types of event actions....................................................................................... 456 Event properties ................................................................................................ 458 Add an event ..................................................................................................... 459 Define an event ................................................................................................. 459 Change event order ........................................................................................... 460

Add an action to an event.................................................................................. 460 Change action order .......................................................................................... 461 Delete an action................................................................................................. 461 Delete an event.................................................................................................. 461

Printing a simulation project ....................................................................................... 462 Syntax for printed equations ............................................................................. 462 Print one or more diagrams ............................................................................... 463 Print equations................................................................................................... 464 Set page margins ............................................................................................... 464 Set page orientation........................................................................................... 465 Set page scaling................................................................................................. 465 Set paper size .................................................................................................... 465

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.

1. Create a new simulation project

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.

2. Create units of measurement

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.

3. Create variables, links, and flows

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.

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.

5. Set up the simulation

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.

6. Create data in- and output objects

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.

7. Add navigation capabilities and documentation

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.

8. Create and save reference data

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.

You can use the Presentation Mode as a "simulation browser," which makes your simulation easily

available for your end-users.

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.

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.

Hierarchical models allow implementation details to be hidden inside submodels, making your

models easier to read and understand.

Improved simulation capabilities

While you in earlier version of Studio could only have one simulation for each component in your simulation project, you can now add as many simulations as you wish. Each simulation will maintain its own set of variable values, but the model structure will be identical between each simulation. A change to the Shared Diagrams of the component will always be reflected in all simulations. By using Private Diagrams, however, you can create diagrams that are unique to the simulation you are working on.

Improvements have also been done to time series, where you are now allowed to record summary information for periods. You can select between several summary types, such as average, accumulated, max, min, etc.

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.

New modelling features

The property pages for variable definitions are greatly improved and simplified, especially when implementing large variable definition expressions. A new function, the VBFUNCTION, allows you to create your own custom functions by programming them in VBScript.

Variable expression validation will now be performed when you edit a variable’s expression directly in the diagram. You will also experience new user-friendliness when working with connectors (links and flows) in Constructor diagrams, including more flexible point editing and useful messages on the status bar while you work. Moving symbols between diagrams is also greatly improved.

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

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.

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

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.

Connecting the Pieces

We are viewing a system when we look at a group of individual parts, as well as the connections or interactions among these parts. A corporation is an example of such a system, composed of many departments that in turn act as systems themselves. When we study the parts and the interactions between them, we in fact study the entire system.

The study of systems is not new. It dates back to the 1920s when researchers from different disciplines began to see that many patterns were common to all fields. A new field, general systems theory, developed around the notion that no matter how different the parts of individual systems were, they were put together using a set of rules common to all. Systems theory suggests that knowledge of one type of system can be applied to many other types. By studying interactions and connections between the pieces of a system, we can gain knowledge that can be useful when confronted with other problems.

Systems theory expands further to include two major fields in management science: systems thinking and system dynamics.

Systems Thinking and System Dynamics

The ideas we have presented thus far are important in both systems thinking and system dynamics. Systems thinking involves changing paradigms about the way the world works, the way corporations function, and the human role in each. In systems thinking we look for interrelationships among system elements. We do this to avoid placing blame in favor of finding the true, long-term solution to a problem. Seeing the interrelationships can also help us find leverage points within a system (places where a slight change will have a tremendous effect on the system's behavior). Gaining awareness about how the system is built up and how it works can also help us avoid solutions that only treat the symptoms of an underlying problem without curing the problem itself.

Systems thinking is powerful because it helps us see our own mental models and how these models color our perception of the world. In many cases, it is difficult for us to alter our mental models. There are always some beliefs or viewpoints that we are not willing to change, no matter what evidence is presented against it. This causes a certain resistance to new concepts. Problems can occur, however, when a rigid mental model stands in the way of a solution that might solve a problem. In such situations, adherence to mental models can be dangerous to the health of the organization.

We all use mental models every day. Our minds do not contain real economic or social systems. Instead, they contain representations - models - of reality. We use these models in all aspects of decision-making. Being explicitly aware of our mental models can help us understand why we make the decisions we do and how we can improve our decision-making processes. If everyone's mental

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.

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.

Cause and Effect

Cause and effect is a simple idea, but some simulations based on methodologies other than system dynamics don't use it. The idea is that actions and decisions have consequences. Price affects sales. Births affect the size of a population. Advertising affects market awareness.

If we examine these cause and effect relationships isolated, they are usually very easy to understand. However, when they are combined into long chains of cause and effect, they can become complex. This is one reason for using simulations. The human mind is good at developing intuition around complex problems, but poor at keeping track of dozens, hundreds, or even thousands of interconnections and cause and effect relationships.

We can create causal-loop diagrams, as are often used in systems thinking to illustrate cause and effect relationships. In such diagrams we use arrows to indicate the relationships. Sometimes, information about the way in which the relationship works is also included in the diagram. An added "o" in the diagram implies a "change in the opposite direction". The relationship between price and sales is such a relationship, where an increase in price leads to a decrease in sales. The relationship between births and population is of another character. When births increase, so does the population. This is a situation where a change leads to a "change in the same direction". Adding an "s" to the arrow in the diagram indicates this.

Figure 1 shows a simple causal-loop diagram. In this diagram, which we will discuss closer in the next section, price has a negative effect on sales, which in turn has a negative effect on unit costs, which in turn has a positive effect on price.

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.

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.

Figure 2: Four common behaviors created by various feedback loops. Exponential growth. (Examples: sales within a start-up; a population of rabbits.) Goal-seeking behavior. (Examples: the number of employees in a workforce and the number of new hires; the number of potential customers and new sales.) S-shaped behavior. (Examples: Product lifecycle dynamics; the acceptance of a revolutionary scientific idea.) Oscillations. (Examples: Business cycles; inventory oscillations.)

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 3: A diagram illustrating the effect of sales and price on revenue.

In this view of the world, it makes sense to always increase price because revenue will always be higher. In economic terms, demand is perfectly inelastic with respect to price in this example (there is no relationship between price and sales). The behavior of the variables can be seen in Figure 4.

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

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 5: The effect of changes in price on sales is illustrated by a delay.

Because there is no delay between price and revenue, when the price shock occurs, the first thing to happen is that revenue goes up. Eventually, however, customers are able to adjust their consumption patterns and sales will go down, resulting in lower revenue. Whether the new revenue is lower or higher than it was before the price shock depends on how sensitive sales is to price. The behavior of the price shock and the subsequent changes in sales and revenue can be seen in Figure 6.

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

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.

Decisions and Policies

Many people intuitively understand the difference between decisions and policies. However, we often do not realize that every decision we make is somehow governed by a policy. Even the system of a swinging pendulum can be described in terms of its "decisions" in the face of governing policies (the rules of physics).

Within corporations, the distinction between the two is extremely important. Managers must often make decisions based on limited information and their own previous experience. They may have little or no control over what information they receive, what form it is in, when they receive it, or how much they receive. When their decisions turn out to be wrong, they are often blamed for misinterpreting the data. Sometimes the conclusion is that the manager simply didn't have enough information to make the correct choice. Unfortunately, the actual problem is usually much deeper.

As mentioned earlier, the behavior of a system is a consequence of its structure. Therefore, the only real changes we can make to a system are changes to the structure. Other changes to the system will soon be canceled out through the actions of negative feedback loops. Providing the managers with more and more information is not necessarily the correct solution, since too much detail or complexity might do more harm than good. It is often a better idea to examine the structure of the organization. This way we can gain knowledge and insight about the policies of the company; the rules of the

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-

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.

Building the Models

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.

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.

Variables and Reference Modes

The next stage in the process is to make reference modes for all relevant variables. Reference modes graph the behavior of variables over time. It is essential that we have a reference mode of the problem variable itself. However, we do need reference modes for all other variables as well. This may sound tedious, but there is a good reason for including them. When we simulate our model and discover that it isn't working the way we anticipated, we can compare the behavior of the variables to the reference modes to identify missing or incorrect structures in the model.

We can create reference modes in various ways. One quick solution is to quickly sketch the behavior of the variables based on your own experience or anticipation. If you are experimenting with Constructor, or creating small models to illustrate decisions or facts, this can be a desirable way of working. Another more time consuming and costly way is to base the reference modes on real data. Sometimes these data are readily available in the organization, but often we will have to gather the system data ourselves. The process of data collection will of course vary from system to system. No matter how we collect the data, the purpose is to understand the structure and behavior of the

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.

Conceptual Model Design

Now that we have reference modes that we have confidence in, have a clear view of the domain of the problem, and have generated a list of primary system variables, we are ready to create a conceptual model design. This is the stage at which we will make causal-loop diagrams and diagrams using levels and flows. Which comes first is a matter of personal preference, and it might be useful to experiment with both to find the most comfortable. At this stage we are simply trying to formulate the problem, using the primary system variables, in terms of feedback loops or levels and flows. It is usually a good idea to go down the list of variables first and identify levels, flows, or constants.

We can begin to determine which variables influence each other and how they can be connected by physical connections (flows to levels and levels to flows) or information links (all other connections). The units of measurement can provide a good check in this stage.

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.

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.

Building Blocks in Powersim Studio

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.

Levels and Flows

In a system dynamics model, the structure of the system is represented mathematically. A level is the accumulation (or integration) of the flows that causes the level to change. In integrating a function, we are simply measuring the area underneath the function by dividing it into equal-width partitions and then summing up the area of all the partitions. This is illustrated in Figure 8.

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.

Figure 10: The model of Figure 9 with extended model boundaries

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.

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.

Figure 12: Constant

A constant is defined by an initial value, and maintains this value throughout the simulation, unless the user changes the value manually (by using a slider bar, for example). For instance, in a one-year simulation, a company may have an essentially fixed workforce that can be represented as a constant auxiliary. If the simulation were to expand to 20 years, however, workforce would most likely become a level and be allowed to vary over time. Once again we return to the important issues of problem definition and model boundaries. Without a clearly defined problem to model, we will be unable to set the proper boundaries.

Sometimes we find ourselves confused about whether an element of the system should be included as a constant auxiliary or as a level. In these situations we should try to rethink the problem. We should think of the time period of the problematic behavior and whether or not it is reasonable to expect the element to change over that period. We will then be in a better position to decide what elements should be constants and what elements should be allowed to vary during the simulation.

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.

Figure 13: Information links connects various variables.

Information links show how the individual elements of the system are put together. In a sense they close the feedback loops. We have already seen how flows change the levels by filling them or draining them. Information links can transfer the value of the level back to the flow, indicating a

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.

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.

Variables and definitions

Variables and their definitions are converted. However, there are some differences between the current version and earlier version when it comes to functions and syntax.

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.

Simulation settings, units, ranges, etc.

Simulation settings, units, ranges and so on, are partly converted.

Import Models: About Variable Conversion

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

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}

When indexing arrays, the following syntax is used

aux A = Array[1,3]

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.

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.

Custom Flow Definitions

When creating custom flow definitions in Constructor 2.51, you could (to a certain extent) create flows that wasn't dependent on the flow rate itself. Rather, it was dependent on a value that in turn was dependent on the flow rate. In Studio the flow has to be dependent on the rate itself, thus restricting some of the flexibility found in Constructor 2.51. Custom flows and flows that are not expressible through a flow expression in Powersim Studio will therefore by converted by disconnecting the rate variable and adding a new rate variable that implements the custom flow.

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.

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

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.

Model Object Symbols

All model object symbols - links, flows, levels, auxiliaries, and constants - are converted to the simulation project. However, you might want to go through the simulation project and use the new diagramming features in Studio. These allow you to separate your model into several diagrams, and more freely format colors, sizes, etc.

Data Input and Output Objects

The following objects are converted: Lines, frames, and texts are converted using freeform lines and frames (with text); Number objects are converted using Table Controls; Time tables are converted using time Table Controls; Time graphs are converted using time Time Graph Controls; Array graphs are converted using Chart Controls; Button Reports are converted using Switch Controls; Gauges are converted using Gauge Controls.

The new Chart Control in Studio only accepts arrays (vectors) as input parameters, in contrast to the Array graph in Constructor 2.51. If necessary, the converter will collect the variable elements from the Array graph's parameter list into a vector variable and add this to the Chart Control's parameter list.

The Button Report in Constructor 2.51 had a lot of features not supported by the new Switch Control in Studio. Some of the functionality will therefore be lost in the conversion process.

The Gauge Report in Constructor 2.51 featured sectors, yet unsupported in Studio.

While the Keep Value property for a parameter belonged to each control in Constructor 2.51, the same functionality is now achieved by using Permanent Variables in Studio. All parameters with the Keep Value property set in Constructor are therefore converted into permanent variables in Studio.

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.

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.

Import Models: About Simulation Conversion

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

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.

Time and Time Settings

In Constructor 2.51, the time value of the simulation was not directly connected to physical time. Both the simulation time horizon and the step length for the numerical integration method was given as pure numbers. The declared time unit were assumed to be the unit of these values.

In Studio, both the simulation time horizon and the step length are values given with associated time units. This makes it possible to create flow rates that are given with respect to any time unit, rather than per period (for example 10 cars/day, 5m/s, etc.). However, the introduction of time units for simulation time, is most likely to cause trouble when converting older models.

Therefore, a unitless time scheme has been created in Studio. At the start of the model conversion, you are asked to enter a time interpretation interval, which should be set equal to the "time unit" of your Constructor 2.5 model. You should review the project and simulation settings after the conversion is finished.

Also, if you change the project or simulation settings after the conversion is finished, you should review any definitions containing expressions related to time. This is very important if the value of the current time step is used directly as a part of your expressions. You should consider changing these definitions to implement the DATE function, which will always give an unambiguous result: the exact point in time to include in your definitions.

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.

Tip! Datasets are connected to components in the Co-models view.

Convert the ASSIGN function

The ASSIGN function of Constructor 2.51

Maybe the most significant change in functions between Constructor 2.51 and Studio, is the removal of the ASSIGN function. The main reason why the ASSIGN function is removed, is that it caused an influence in the opposite direction than was indicated in the flow diagram. The illustration below shows how the ASSIGN function could be used in a model.

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.

A Model Equivalent of the ASSIGN Function

Although there is no function in itself that covers the functionality of the ASSIGN function, it is actually not at all difficult to create a model equivalent that performs the same operation.

With the introduction of discrete flows, creating a model structure that behaves like the ASSIGN function is very easy. The only difference is that the assigned variable must in Studio always be a level (it can never be a constant). This shouldn't really matter, though, since you can use the level in any situation where you would normally use a constant. Both have initial values, and both can be used as target for user input through controls (switch, slider, or chart controls).

The model equivalent of the ASSIGN function available in Constructor 2.51.

The definitions are as follows:

level A = ... const B = ... aux C = (B-A) // zero order integration method selected

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.

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)

A Model Equivalent for Array Operations

In certain cases, the ASSIGN function in Constructor 2.51 could also be used to assign a given value to a single element within an array. A commonly used model structure is shown below:

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.

The definitions for this structure are:

aux A = ... (defined as an array with 10 elements) aux B = ... aux C = FOR(i=1..10 | IF(cond(i), (B - A[i]), 0))

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)

Convert Constrained Expressions

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

Alternatively, the CONCAT function can be used, as shown below:

CONCAT(FOR(i=1..1 | A*B), FOR(i=2..3 | 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.

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

Convert the SHIFT functions

The SHIFT functions of Constructor 2.51

There were three SHIFT functions in Constructor 2.51; SHIFTCIF, SHIFTLCNT, and SHIFTLIF. SHIFTCIF and SHIFTLIF both performed a conditional shift of the array elements in the target variable. The difference was that SHIFTCIF performed a circular shift, while SHIFTLIF performed a linear shift. SHIFTLCNT allowed you to perform a linear shift a given number of elements. The count parameter of the function specified the number of elements to shift at a time. If the count was negative, the shift would be performed in the opposite direction. In Constructor 2.51, the count could even be a real number, in which case the resulting elements were found by internal interpolation between the existing elements.

The SHIFT functions are no longer present in Studio. However, most of the functionality gained when using them, can be implemented using ordinary model structures. The three sections below explains how to do this. Although the structures require the use of more variables than was needed in Constructor 2.51, they do preserve the diagram consistency better. They don't allow influences to go in the opposite direction of the links and flows that connect the variables, as was the case with SHIFT

functions in Constructor 2.51.

A Model Equivalent of the SHIFTCIF Function

The SHIFTCIF function caused the array to be shifted circularly (the last element was added at the beginning of the array). The illustration below shows how the SHIFTCIF function could be used in Constructor 2.51. The defining equations are also shown.

const Array = ... (The array to shift) aux Condition = ... (The condition for when to perform the shift) aux Shift = SHIFTCIF(Condition, Array)

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.

const Array = ... (The array to shift) aux Condition = ... (The condition for when to perform the shift) aux 'Shift' = IF(Condition; FOR(i=1..9 | Array[i]); 0) aux 'Cycle' = IF(Condition;Array[10];0) flow Array = + (PREFIXZERO(Shift)) // Automatic - (SUFFIXZERO(Shift)) // Automatic - (PREFIXZERO({Cycle}) + (SUFFIXZERO({Cycle})

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.

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.

const Array = ... (The array to shift) aux Condition = ... (The condition for when to perform the shift) aux Shift = SHIFTLIF(Condition, 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.

const Array = ... (The array to shift) aux Condition = ... (The condition for when to perform the shift) aux 'Shift' = IF(Condition; FOR(i=1..9 | Array[i]); 0) aux 'Shift Out' = IF(Condition;Array[10];0) flow Array = + (PREFIXZERO(Shift)) // Automatic - (SUFFIXZERO(Shift)) // Automatic - (PREFIXZERO({'Shift Out'})

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'}).

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.

const Array = ... (The array to shift) aux Input = ... (The value to shift into the array when performing the shift) aux Cnt = ... (The number of places to shift the elements of the array) aux Shift = SHIFTLCNT(Cnt, Array, Input)

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.

const Array = ... (The array to shift) aux Input = ... // The value to shift into the array when performing the shift aux Cnt = ... // The number of places to shift the elements of the array aux 'Shift In' = FOR(i=1..10 | IF(i <= Cnt, Input, IF(ISNAN(Array[INDEX(NUMERICAL(i)-Cnt)]), Input, Array[INDEX(NUMERICAL(i)-Cnt)] ) // IF

) //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.

Convert the LIMIT function

The LIMIT function of Constructor 2.51

The LIMIT function in Constructor 2.51 allowed you to restrict the value domain of a variable (usually a level) from another variable. The model structure below illustrates how the LIMIT function could be used to prevent a level from dropping below a given minimum value or rising above a given maximum value. The equations are also presented.

aux Input = ... // The inflow of the Target level level Target = ... // The target variable to control const MinVal = ... // The minimum value for the LIMIT function const MaxVal = ... // The maximum value for the LIMIT function aux Control = LIMIT(Target, MinVal, MaxVal)

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:

result Control = -(MinVal - Target) or (MaxVal - Target)

Creating a Model Equivalent of the LIMIT Function

Creating a model equivalent of the LIMIT function is not difficult, but it involves one extra variable; the return value from the function. The model structure is shown below, together with the equations that define it.

aux Input = ... // The inflow of the Target level level Target = ... // The target variable to control const MinVal = ... // The minimum value for the LIMIT function const MaxVal = ... // The maximum value for the LIMIT function aux Control = IF( (Target + Input*TimeStep) < MinVal, -(MinVal - (Target + Input*TimeStep))/TimeStep, IF( (Target + Input*TIMESTEP) > MaxVal, ((Target + Input*TIMESTEP) - MaxVal)/TIMESTEP, 0/TIMESTEP ) ) aux Return = Control * TIMESTEP

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 + ...)

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.

Icons

Below is a short explanation of each icon used in the help system.

The Help Window

The Help System appears in a window with three panes: On the left side of the window is the Navigation pane. It contains four navigational tabs: Contents, Index, Search, and Favorites On the right side of the window is the Topic pane. It displays the selected help topic, or the default help topic. The third pane is the toolbar, which is located below the help window title bar.

The Toolbar of the Help Window, contains buttons that are useful to you when you browse the help system.

Hide and Show expands or collapses the left pane. Locate locates the current topic in the table of contents.

Back opens the previous help topic in the browse history Forward opens the next help topic in the browse history.

Icon Explanation

The help topic applies to Powersim Studio.

The help topic applies to Constructor Diagrams.

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.

The link leads to an overview topic containing more textual explanations.

The link leads to an 'how-to'-topic containing task descriptions.

The link opens a menu with related topics that you can choose from.

The link leads to a web page, in most cases on Powersim's web site.

The link leads to a task related to the concept.

Indicates a note associated with the topic text.

Indicates a tip associated with the topic text.

Indicates that the heading contains a section that is hidden. Expand it by clicking the heading.

Indicates that the heading contains a section that is shown. Collapse it by clicking the heading.

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

Print opens the Print dialog box. Options opens a menu containing various options you can select for the help system.

Customize the Help Viewer

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.

To change the appearance of the help system 1. Visit the Help Control Panel available in the Table of Contents. 2. Under Font Scheme, select the font that you prefer to view. You have four options: Verdana

(default), Arial, Times New Roman, and Georgia. 3. Under Color Scheme, select the font that you prefer to view. You have seven options: Powersim

(default), Vertical Bar, Horizontal Bar, Powersim Classic, Yello, Ocean, and Spring. 4. Under Hidden Sections, select the if you wish that sections that are hidden by default should be

displayed or not. Default option is hidden.

Change the font size of the help system 1. Click the Font button to change the font size used. 2. The font size will cycle through the font size list, so click again until you find a font size that suits

you.

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.

Customizing the Help Window To resize the Navigation or Topic pane, point to the divider between the two panes. When the pointer changes to a double-headed arrow, hold down the mouse button and drag the divider right or left. To shrink or enlarge the entire help window, point to any corner of the Help Viewer. When the pointer changes to a double-headed arrow, hold down the mouse button and drag the corner. To change the height or width of the Help Viewer, point to the top, bottom, left or right edge of the Help Viewer. When the pointer changes to a double-headed arrow, hold down the mouse button

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.

Hide or Show the Navigation Pane

On the toolbar, click Hide or Show to close or display the Navigation pane. The Navigation pane contains the Contents, Search, Favorites, and Index tabs.

Note! If you close the Help Viewer with the Navigation pane hidden, it will remain hidden the next time you display the Help Viewer.

Use Powersim Learning Lab

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.

Find a Help Topic

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.

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.

Print the Current Help Topic

There are several ways of printing help topics: Click the Print button on the toolbar. Right-click inside the topic and select Print on the shortcut menu. In the Contents tab, right-click the topic you want to print, and select Print on the shortcut menu. In the Contents tab, right-click a heading and select Print on the shortcut menu to print all the topics under that heading.

Note! The appearance of the printed page can differ somewhat from the online view.

Use the Favorites Tab

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.

Find Information with Full-text Search

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

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.

Get Help in a Dialog Box

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.

Highlight Words in Searched Topics

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.

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.

Working with Dialogs and Toolbars

You can format objects by right-clicking them and selecting Properties on the shortcut menu. In the Properties dialog box you can select the properties you wish from various categories. The categories are separated into tabs, each containing similar properties. A lot of these properties are also available on the Format toolbar, by default located on the bottom of the screen (you are free to relocate it, if you wish to).

You can turn on and off toolbars as you like, and also relocate them. The next time you open Studio, the toolbars will be located in the same place as you left them the last time you used Studio.

The Project Window

The Project Window is another useful feature in Powersim Studio. It allows you to directly access the various parts of your simulation project, and view or edit them. Most of the items in the Project Window have a set of commands that you can apply to them. These are of course available in the shortcut menu by right-clicking the items. Some of the items, such as Diagrams, Private Diagrams, Global Ranges, and Global Units have their own windows. To open them, simply double-click the item. The view will then open in the document area to the right.

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.

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.

Design and User Mode

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.

Components and Simulations

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.

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

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.

Create a Simulation Project

To create a new project using your standard system language: 1. Click New on the Standard toolbar.

To create a new project and specifically select the language of the project yourself: 1. Click New… on the File menu. 2. Select the language of the new simulation project in the dialog box that appears, and click OK.

If any other simulation project is currently open, this will automatically be closed before the new one is opened and you will be asked to save or discard any changes.

Create Project Documentation

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

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.

Open an Existing Project

1. Click Open on the toolbar, or select Open… on the File menu. 2. Under Look in, select the folder where the project is located. 3. Make sure that Simulation Projects (*.sip) or All Files (*.*) is chosen for Files of type, and click

the name of the project in the files list. 4. Click Open.

Before the project is opened, you will be asked to save or discard changes you have made in the currently open project, if any. This project will then be closed before the new one is opened.

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.

Save a Simulation Project

To save changes under the current name: 1. Click Save, or select Save on the File menu. 2. If this is the first time you save the project, you will be asked to enter the path and name of the

new project: 1. Select the folder where you want to save your simulation project. 2. 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. 3. Click Save.

If you want to save the project under a different name: 1. On the File menu, select Save as… 2. Select the folder where you want to save your simulation project. 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.

If you want to save a copy of the project under a different name: 1. On the File menu, select Save Copy As… 2. Select the folder where you want to save the copy of your simulation project.

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.

Create a Backup Project

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.

Restore a Backup Project

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.

To restore a backup project: 1. Open Windows Explorer, and browse to the folder where you saved your simulation project. 2. Locate the *.sip file containing the project you wish to restore. 3. Rename the *.sip file if you wish to keep the simulation project, or delete it if it is invalid. 4. Locate the file with the same file name, but with the extension *.~si. 5. Rename the extension of the *.~si file to .sip, or give the file a new name (such as MyFile.sip). 6. Open the file as usual in Powersim Studio.

Compact a Simulation Project

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

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.

View Project Documentation

To view the project documentation for the current simulation project: 1. Select Project Documentation on the Help menu.

The project documentation will be opened in the standard HTML browser of your computer.

If there is no documentation available for the project, the menu entry will be disabled.

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.

Show and Edit Project Information

1. Select Project Information on the File menu.

A Project Information dialog box appears that shows you information about the project. It is divided into two sections:

General

Under this tab you will find automatically generated information about the simulation file. The file status, either Read only, Archive, Hidden, or System, can be changed under the file's Properties in Windows.

Summary

Under this tab there is room for a description of the project, including title, subject, author and company information. You can also enter keywords and project category.

Show Recently Opened Projects

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.

View Project Statistics

To view the project statistics for the current simulation project: 1. Select Project Information on the File menu. 2. Click the Statistics tab. 3. Click OK to close the dialog box.

The statistics page contains information about the number of components, variables, variable elements, global units, and global ranges in your simulation project.

Work with Levels of Protection

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.

Each access level can be locked by an individual password. To unlock a higher protection level, simply enter the password for that level.

Level Description

Run Access The simulation project can only be run. No model diagrams or equations will be available. The model can, for example, be accessed using Powersim Studio SDK.

Run and View Access

The simulation project can be viewed, but not edited. Access to all views are available, including units and ranges. However, no definitions can be changed (including units, ranges, and variables).

Full Access The simulation project can be viewed and edited freely.

Protect the Simulation Project

To protect the simulation project: 1. Select Protect on the Project menu. 2. Select the desired protection levels by checking the boxes next to them. 3. Enter the desired passwords for the selected protection levels. 4. Click OK. 5. If it is the first time you enter the password, you will be asked to confirm it. Repeat the password,

and click OK again.

The passwords will be activated the next time you save the project.

Unprotect the Simulation Project

To unprotect the simulation project: 1. Select Protect on the Project menu. 2. Uncheck the unwanted protection levels by deselecting the boxes next to them. 3. Click OK.

Change Level of Protection

To change the level of protection of the current simulation project: 1. Select Enter Password… on the Project menu. 2. Enter the password of the protection level you wish to unlock.

Redo an Operation

To reverse the effect of the Undo command: 1. Click Redo on the toolbar.

The last undo operation is negated. Repeat the Redo command until you reach the point you wanted to restore your work to.

For a list of the most recent commands that were undone: 1. Click the arrow next to the Redo icon. 2. Click the earliest command you want to cancel. You are brought back to the stage before that.

Undo an Operation

If you regret an operation: 1. Click Undo on the toolbar.

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.

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.

Diagram Windows with Constructor and Interaction Diagrams

With Constructor diagrams, you can both design and edit the model, as well as create a user friendly environment for experimenting with it. Constructor diagrams are shared by all simulations in a component, and can be accessed by opening the simulation's Shared Diagrams.

With Interaction diagrams, you can design user environments that are specific to the simulation where they are created. They can be accessed by opening the simulation's Private Diagrams.

Submodels and other model variables can have their own diagram book, as well. If submodel diagram books exists, they will appear as children of the Shared Diagrams node of the simulations. You access them by double-clicking them, or by right-clicking the submodel or model variable, and select Open Diagram Book on the shortcut menu.

You can use the diagram tabs at the bottom of the diagram window to navigate between the diagrams.

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.

Multi-column Treeview Windows

There are several multi-column treeview windows in Studio, including the views for ranges and units, Details Window and Equations View others. The Equations View and the Details Window

gives you a compact, at-a-glance access to the model structure, but still supports easy model design through the use of shortcut menus and multi-columns. The Details Window is available in the diagram window, making it easy to include variables or make them parameters in controls, for example. Except from its location, working with the Details Window is similar to working with the Equations View.

All the various multi-column treeview windows feature grouping, easy editing by using the Arrow Down key, column width adjustment by dragging the column header dividers, column sorting, and more.

View Equations

The Details Window 1. Click Details Window.

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.

The Equations View 1. Double-click Equations (located under the Simulation of the component in the Project

Window).

or 1. Select Equations under Simulation Windows on the View menu.

You can view, edit and create variables in the Equations View. Working in the Equations View and in the Details Window are similar process.

Create a New Diagram Sheet

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

There are two ways of switching between diagram sheets: In the diagram window, click the tab of the sheet you would like to see or do something with. Right-click the arrows next to the diagram tabs, and select the diagram to view on the shortcut menu. If there are more than 15 sheets in the project, you can select More Diagrams on the shortcut menu, and select the diagram to view in the dialog box that appears.

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

You may move sheets within the component: 1. Select the sheet(s). 2. Drag the sheet(s) to its new position among the existing diagram tabs.

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

You can exclude a sheet from a diagram book: 1. Right-click the diagram tab of the diagram you wish to exclude at the bottom of the window. 2. Select Exclude Diagram on the shortcut menu.

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.

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.

Delete a Sheet

Note! This operation cannot be undone!

1. Right-click the diagram sheet you wish to delete, and select Delete on the shortcut menu.

Adjust Columns in Treeviews

The columns in of multi-column treeviews can be adjusted in several ways: Sort: Click the column header to sort the column in descending order. Click again to sort in ascending order. A tiny arrow on the column header indicates the sorted column and the sorting order. Reorder: Click the column header, and drag the column to a new position in the view while holding the mouse button. Release the mouse button when you have found a new position for the column. Resize: Click the dividers between the column headers and drag the column width to the appropriate width while holding the mouse button. Hide/Display: You can hide or display any of the columns in the Equations View by right-clicking the header row and selecting the column you wish to hide or display. The columns marked with a checkmark are currently displayed.

Select Entries in Treeviews

You can select one or more entries in all multi-column treeviews: Select entries while holding down the Ctrl key to expand the selection entry by entry. Select an entry, and then select one more while holding down the Shirt key to select all intermediate entries. Select an entry, and hold down Shift while using the navigation keys to expand the selection (Arrow Up, Arrow Down, Page Up, and Page Down Select all entries by hitting Ctrl-A, or by selecting Select All on the shortcut menu.

You can group the treeview by several properties by dragging several column headers to the grouping area.

Switch between Hierarchical and Flat View

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.

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.

To switch to flat view 1. Right-click on the column header row. 2. Select Flat on the shortcut menu. A checkmark will appear next to the command.

To switch to hierarchical view 1. Right-click on the column header row. 2. Select Flat once again on the shortcut menu. The checkmark next to the command will disappear.

Organize Windows

A number of commands are available on the Window menu: New Window opens a new variable window (a duplicate of the currently active window).

Close closes the active window. Close All closes all open windows. Use Next and Previous to maneuver between windows. Use Tile, Arrange Horizontal and Arrange Vertical, and Cascade to organize the position of all open windows. Select which window to activate from the list at the bottom.

Save Window Position

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

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!

Open a New Window for the Active Component

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.

Maximize or Minimize Window

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.

Go to Next or Previous Window

1. On the Window menu, select Next or Previous to switch between windows.

There are also keyboard shortcuts available for these operations: Ctrl-Tab: Go to the next window; Ctrl-Shift-Tab: Go to the previous window.

Close the Active Window

There are several ways of closing the active window: On the Window menu, select Close. Hit Ctrl-F4 on your keyboard. Click Close in the upper right corner of the window.

The currently active window is closed.

Close All Windows

1. On the Window menu, select Close All.

All open windows are closed.

The Project Window

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.

The Project Window allows you to organize your project.

The Project Window is for organizing the simulation project. It gives you immediate and intuitive control over the model components, units, ranges and datasets.

You can use the Project Window to: Expand and collapse the branches of the project tree by clicking Expand and Collapse. Add folders and structure your project. Open windows for the various simulations, where you can view and edit the model, diagrams, co-models, runs, and events. Open views where you can define ranges, units, and datasets.

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

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

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.

Dock the Project Window

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

Create a Folder in the Project Window

You can create folders for your components and datasets in the Project Window. The components and dataset can be dropped in the different folders.

Note! You can not move the active component!

1. Right-click a folder or the Project node, and select New Folder on the shortcut menu.

Show or Hide the Project Window

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.

Work with Toolbars and Keyboard Shortcuts

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.

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.

Select a Persistent Tool

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.

Move or Dock a Toolbar

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.

Show or Hide a Toolbar

1. Select Toolbars on the View menu. 2. Select the toolbar that you want to show or hide.

or 1. Right-click in the toolbar area. 2. Select the toolbar that you want to show or hide from the shortcut menu.

If you hide a toolbar, that toolbar will not appear again in any projects until you turn it back on.

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.

Copy Area as Picture Tool

The area tool allows you to select an area and copy it to the clipboard as a picture file (in Windows Meta File format).

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 with Rate Tool

Create a flow with a rate attached in the active diagram.

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.

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.

Copy Component as Submodel

Copy a component as a submodel in the active diagram. If you click the button and then click inside the diagram, a dialog box appears allowing you to select the simulation project containing the component you wish to copy. Once you select a simulation project, a new dialog box containing the components that are available for copying. Alternatively, you can click the small arrow next to the button and select a component from the drop-down list. The list contains recently copied components, recently used simulation projects to copy from, as well as the components available in the current simulation project.

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.

Time Series Control Tool

Create a Time Series Control in the active diagram.

Time Table Control Tool

Create a Time Table Control in the active diagram.

Chart Control Tool

Create a Chart Control in the active diagram.

Table Control Tool

Create a Table Control in the active diagram.

Gauge Control Tool

Create a Gauge Control in the active diagram.

Slider Control Tool

Create a Slider Control in the active diagram.

Switch Control Tool

Create a Slider 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.

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.

Bold, Italic, Underline

Change the appearance of the selected text, or the text of selected objects. A second click on the button removes the formatting.

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

Change the line shape type of the selected objects.

Layout Commands

The commands on the Layout Toolbar can be used to arrange the objects in your diagram.

Align Left, Right, Center

Align the left or right edges or the center of the selected symbols with the dominant symbol.

Align Top, Bottom, Middle

Align the top or bottom edges or middle of the selected symbols with the dominant symbol.

Make Same Height, Width, Size

Resize the selected symbols to the same height, width, or size as the dominant symbol.

Space Evenly Across, Down

Space the selected symbols evenly either across or vertically.

Bring To Front, Bring Forward

Bring the selected object to front of overlapping symbols, or one step closer to the top layer.

Send Backward, Send to Back

Send the selected symbol one step closer to the back of the stack, or send it to the very back (lowest layer).

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.

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.

Advance Simulation one Step

Advance the simulation one step.

Add Cue Point

Add a cue point at the current simulation time. A cue point allows you to "rewind" the simulation to that point, and replay it from that point forward.

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.

Restore Permanent Variables

Restore the initial values of all permanent variables according to their definitions. Permanent variables will retain the value they are assigned between simulation runs. Use this command to force all permanent variables to be reset to their original definitions.

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.

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.

Load External Data

Load data to dataset connection from external data stores.

Save External Data

Save data from dataset connection to external data stores.

External Data Details

View details for dataset connections and external data stores.

Standard Commands

The standard commands include commands for handling project documents.

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.

Show or Hide Project Window

Toggle the Project Window on/off.

Contents

Open the help system.

Symbol Commands

The Symbol Toolbar contains useful tools for adding auto report and changing the appearance of flows and their associated flow rates.

Show Auto Report

Turn on auto report(s) for the selected object(s). The auto report type used last time will be selected when you click the button. To change the auto report type, click the small arrow next to the button, and select the type from the drop-down menu.

Hide Auto Report

Hide auto report(s) for the selected variable(s). Hiding an auto report doesn't delete it, and you can later display it again without loosing any formatting.

Unhide Auto Report

Unhide previously hidden auto report(s) for the selected variable(s). The command is disabled if (none of) the selected variable(s) has hidden auto report(s).

Delete Auto Report

Delete the auto report(s) for the selected variable(s).

Make Single Straight Segment

Convert the segments of the selected line, flow, or link to a single straight segment.

Make Single Curved Segment

Convert the segments of the selected line, flow, or link to a single curved segment.

Move Flow Valve to Next or Previous Segment

Moves the flow valve of the selected flow to the next or previous segment of the flow.

Anonymous Rate

Make the selected flow rate anonymous.

Toggle Elbow Style

Toggle Elbow Style for the selected line(s), link(s), and/or flow(s). When the button is depressed, the elbow style is enabled for the selected object(s).

The Presentation Toolbar

Note! This toolbar is only available in Presentation Mode!

The Presentation Toolbar allows you to navigate through your simulator interface, and also allows you to switch back to Design Mode.

Open Simulation Project or Simulation Game

Open Simulation Project or Simulation Game File allows you to open another simulation project or a simulation game file into Presentation mode. The button is only available when Studio is started in Presentation mode (by double-clicking either a simulation project or a simulation game file).

Open Simulation Project or Simulation Game

Save Simulation Game File allows you to save the decisions and the simulation you have done in the current project. The simulation game is saved in a simulation game file (*.sig), containing a link to the active project. You can load the game file later by double-clicking it in Windows Explorer, or by opening it directly in Presentation Mode.

Back and Forward

The Back and Forward buttons let you navigate through your browsing history in the same way as similar buttons in a web browser. By clicking the small arrow next to Back, a list of the most recently visited windows will be displayed.

Home

Brings you back to the default window of the simulator (as specified in the Presentation Mode Setup property page).

Reset, Play, Play Stepwise

Identical to the buttons on the Simulation toolbar, these commands let you reset the simulation, play and stop it, and play stepwise.

Reference Data

Allows you to select reference data to be presented in controls.

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

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.

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

Switch to Presentation Mode. The project's presentation mode settings will be used.

Constructor Keyboard Shortcuts and Modifiers

Drag-and-Drop Modifiers

Notes These modifiers can be used when you perform drag-and-drop operations to change the operation that is performed. You can use several modifiers at the same time, if you wish to.

Alt

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

Ctrl

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

Shift

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

Resize objects Holding down Shift while resizing diagram objects will lock the aspect ratio and ensure that the shape of the object is maintained.

Ctrl-Alt

The Ctrl-Alt key combination will usually work as a combination of the two individual key functions, except in one case:

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.

Del Delete the last inserted node when you are creating segments (for flows, links, or lines).

Ins Insert a new node when you are creating segments (for flows, links, or lines).

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

Ctrl+F3 Go to next variable defined by the selected variable (variable can be 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

F5 Presentation Mode

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.

Copying Components as Submodels

You can also copy components as submodels in other models. By using the Copy Component as Submodel feature, you can create a new submodel based on the component you select. This component can come from the current simulation project, or from a previously saved on. This makes it easy to reuse components, and it allows you to create your own "component libraries" that you can

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.

About Private and Shared Diagrams

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

structures of the component. Private diagrams belongs only to the simulation in question, and can only contain presentation objects (like controls, frames, hyperlinks, etc.).

Shared Diagrams - Constructor Diagrams

Shared Diagrams are Constructor Diagrams, and are shared by all the simulations and tasks belonging to the component. 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.

Since these diagrams are shared by all the simulations and tasks, a change to the structure in one of them will be immediately reflected in all other simulations and tasks as well. The reason that the Shared Diagrams node is present for each simulation, is that all the user input and variable values will be different in each simulation that uses the diagrams. Hence, the volatile information presented is unique for each simulation, while the model structures and objects themselves are shared among all simulations.

Private Diagrams - Interaction Diagrams

Private Diagrams are Interaction Diagrams, and are unique for the simulation in which they are defined. These diagrams allow you to create user interfaces, and you are limited to using only presentation and input objects (hence the name).

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.

Create a New Component

1. Right-click Project in the Project Window, and select Add Component on the shortcut menu. You can also right-click a category folder, if you have added one to your project.

The component is inserted in the project structure, and you can rename it directly in the project window. By default it receives the name Component 1. Subsequent new components are numbered accordingly (Component 2, Component 3, 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.

Add a Simulation to the Component

A component can contain several simulation, each with their own individual name and simulation settings.

To add a simulation to a component:

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.

Open a Simulation's Diagrams

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.

To open the Shared Diagrams of a simulation 1. In the Project Window, expand the component and simulation, until the Shared Diagrams node

is visible. 2. Double-click the Shared Diagrams node, or right-click it and select View on the shortcut

menu.

or 1. Select Simulation Windows on the View menu, and then select Shared Diagrams

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.

To open the Private Diagrams of a simulation 1. In the Project Window, expand the component and simulation, until the Private Diagrams

node is visible. 2. Double-click the Private Diagrams node, or right-click it and select View on the shortcut

menu.

or 1. Select Simulation Windows on the View menu, and then select Private Diagrams

Create a Submodel from a Component

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

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.

To Copy a Component as a Submodel 1. Click Copy Component as Submodel on the Diagram toolbar 2. Click once in the diagram where you want to insert the submodel. You can control the size of the

resulting submodel symbol by dragging the size of the symbol before releasing the mouse button. 3. Select the simulation project (.sip) containing the component you wish to copy in the Copy

Component from File dialog box that appears. 4. Select the component to copy in the Copy Component dialog box that appears. The dialog box

contains all the components of the simulation project you selected. 5. Click OK to copy the component as a submodel.

By clicking the tiny arrow next to the Copy Component as Submodel button, you can select the component to copy from a list containing the recently used copied components as well as the components of the current simulation project.

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.

The Account component ready for duplication as a submodel.

Tip! The full submodel with definitions and explanations is here.

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.

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.

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

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.

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.

Diagrams and Models

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.

Diagram and Details Window.

The Building Blocks of a Constructor Diagram

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.

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.

Constructor Diagram Symbols

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.

Reservoir A level symbol with a double line at the bottom represents a reservoir, which is a special type of levels that cannot be depleted below zero.

Auxiliary A variable that contains calculations based on other variables.

Constant A variable that contains a fixed (initial) value.

Submodel A variable that contains child variables. A submodel variable has no definition (value), data type, or unit.

Array variables A variable symbol with double frames indicates that the variable it represents is an array.

Variable with diagrams

A document indicator indicates that the variable has diagrams. Any variable can have its own diagrams and child variables.

Permanent variables

A variable symbol with a pin in the upper left corner indicates that 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 transfer direction set to out

A variable symbol with an arrow in the upper right corner pointing outwards, indicates that the variable has its transfer direction set to out. This implies that values from the variable is exported from the model via co-models (such as datasets).

Variable with transfer direction set to in

A variable symbol with an arrow in the upper right corner pointing inwards, indicates that the variable has its transfer direction set to in. This implies that values are imported to the variable via co-models (such as datasets).

Variable with transfer direction set to in-out

A variable symbol with an arrow in the upper right corner pointing both ways, indicates that the variable has its transfer 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.

Continuous flow A connector that influences levels. A flow is controlled by a

variable connected by an information link (or attached directly) to the valve.

Discrete flow A connector that influences levels. A flow is controlled by an

auxiliary connected by an information link (or attached directly) to the valve.

Flow with anonymous rate

A flow where the rate is made anonymous. This flow can represent several flows in the underlying model.

Information link A connector that provides information to auxiliaries about the

value of other variables.

Delayed link A connector that provides delayed information to auxiliaries about

the value of other variables at an earlier stage in the simulation.

Initialization link A connector that provides start-up (initial) information to

variables (both auxiliaries and levels) about the value of other

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

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.

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 flow

A symbol illustrating an undefined source or outlet for a public 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 diagram

A symbol with a '#' (hash mark) indicator indicates that there exists inconsistencies between the diagram and model definitions. The inconsistency symbol can appear on variables, links, and flows.

Display Description Tip!

Error indicators on model variable symbols indicate that their variable definitions are invalid.

Inspect the definition on the Definition property page. Check for unit inconsistencies or use the Function Wizard to debug your function expressions.

Error indicators on flows into or out of levels indicate that the flow rate or level is not correctly defined. The error indicator shows on which side of the flow the error occurs.

Inspect the flow rate's and level's definitions on the Definition property page. Common mistakes are that flow rates are not defined with rate units (e.g. 'people/day'), and levels using a compatible accumulated unit (e.g. 'people').

Inconsistency indicators on Reconnect the correct flow rate to

Note! If you display your model diagram in User or Presentation Mode, the error ( )and inconsistency ( )indicators will be hidden.

Adding Controls and Auto Reports to a Diagram

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.

flows indicate that the flow doesn't represent a flow in the underlying model.

the valve, or simply delete the flow and create a new, correct flow instead.

Inconsistency indicators on links indicate that the source variable of the link is not used in the variable definition of the target variable.

Either remove the link, or redefine the target variable so that it uses the linked variable in its definition.

Inconsistency indicators on model variables indicate that a variable that is present in the diagram is used in the variable definition.

Either remove the variable from the definition, or create a link from it to the variable containing the inconsistency indicator. Tip! The missing link will be described in the tool tip of the model variable when you hover the mouse pointer over it.

Error indicators on variables and links connecting them indicates that there is a circular definition present in the diagram.

Make sure that the circular definition is broken. This can be done by remodeling, by including a delayed parameter (using a delay function), or by introducing a flow and a level somewhere in the structure.

Error indicators on a submodel indicates that one or more of the child variables are not properly defined.

Open the submodel's diagram (alternatively the Equations View) and correct the erroneous child variable definitions.

Inconsistency indicators on anonymous flows indicate that the flow doesn't represent a flow in the underlying model.

Include the flow rate again, and make sure that the level at both ends use the flow rate as an in- and outflow.

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 Stacking Order of Diagram Objects

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

Toggle between Design and User Mode

The Design mode allows you to make changes to your model.

To toggle between Design and User mode: 1. Click Toggle Design Mode.

The state of the button shows the mode of Studio: ! : If the button is depressed, Studio is in Design mode. ! : If the button is not depressed, Studio is in Run 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.

Change Stacking Order of Objects

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

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.

Various variables in Constructor Diagrams.

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!

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.

Illustration of original and snapshot in a model.

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.

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.

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

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 also use the Snapshot command to create snapshots: 1. Click the arrow of the Snapshot button on the Diagram toolbar and select the variable you

want to make a snapshot of from the drop-down list. 2. Click in the diagram where you want to place the snapshot, or drag to make a snapshot of a

different size.

or 1. Click Snapshot. 2. Click in the diagram where you want to place the snapshot. 3. Select the variable(s) (the dialog box allows multiple selection) you want to create snapshot(s) for

in the dialog box, and click OK.

Go to Original from Snapshot

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.

Make Original from Snapshot

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

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.

Name and Rename a Variable

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!

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.

Scale a Basic Variable

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.

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!

A small model containing several variables connected by links and flows.

Keyboard Modifiers when Working with Nodes in Links and Flows

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.

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.

Change the Shape of a Link

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.

Curved segments of a link, with nodes and control points

The link segments are by default drawn as curves with symmetrical nodes and are affected by the normal grid settings. Press the Ctrl key to make a straight link segment.

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!

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!

Create an Initialization Link

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!

Create a Delayed Link

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

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!

Change the Shape of a Flow

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.

Various segments of a flow, with nodes and control points

A flow is drawn by default with straight segments and cusp nodes. Snap to Radial Grid is automatically activated, and will facilitate the drawing of accurate angles and give your diagrams a more uniform appearance.

Use the shift key to temporarily turn off Snap to Radial Grid. The alt key reverses the Snap to Regular Grid setting. Press the ctrl key to make the flow curved.

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!

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!

Create a Flow without a Rate Variable

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!

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!

Reconnect a Flow to a Different Level

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!

Detach a Flow Rate Variable

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!

Attach a Flow Rate

To Attach a flow rate to its valve: ! Drag the rate onto the linked flow valve. When close enough, the rate snaps to the valve.

or

! 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!

Move the Valve of a Flow

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!

Change the Rate Variable of a Flow

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

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 Rate Variable

1. Select the flow rate you wish to delete. 2. Select Delete on the Edit menu.

or 1. Select the flow rate variable you want to delete in the diagram. 2. Hit Delete on the keyboard.

The flow is not deleted though you delete the flow rate that controls it.

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!

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.

A model utilizing a submodel to implement a conveyor functionality.

The implementation of the submodel is shown below. The flows into the submodel are automatically connected to the public level Contents, which represents the content of the conveyor at any given time. There are two input variables to the model: Initial defining the initial content of the conveyor, and Delay Time defining the time it takes each item to pass through the conveyor. These inputs are defined by the Time in Conveyor and Initial Amount in Conveyor variables in the parent diagram.

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.

When a variable is made public, an indicator appears on the upper right corner of the variable's

symbol.

Include public variables in parent diagram

You can include any public variable of a submodel in the parent diagram. An included variable will be connected to the parent symbol with a satellite line. A circle at the boundary of the parent symbol indicates which of the variables is the parent (useful if you have a submodel as a child).

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.

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.

Reuse variable names

Each submodel contains its own name space, so you can use the same name for variables inside different submodels as well as in the main model.

About Submodel Diagrams

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.

About Public Variables

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

A public variable as it appears in a) Constructor diagrams and b) tree views.

Public variables can also be included in the parent diagram. The included (public) variable will be connected to the parent symbol by a satellite line, and a small circle indicates the parent, as shown below.

The child variable Auxiliary_1 of Model_1 is included in the parent diagram.

When you drag a link to a submodel, a dialog box will appear. The public variables of the submodel populate this dialog box, and you can select to let one of these variables refer directly to the linked variable. This is a convenient way of connecting a submodel to the surrounding system.

When you copy a component into a model diagram as a submodel, all the variables that have a defined transfer direction will automatically be defined as public.

About Child Variables in Auxiliaries, Levels, and Constants

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.

The model structure inside the auxiliary Payroll Tax.

The equations are shown below.

aux 'Gross Salary Payment' = ... // The total salary payment of the company aux 'Payroll Tax' = .'Due Payment' // The variable is defined equal to

a) b)

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

Consistency Rules for Submodel Diagrams

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.

External flows to and from levels inside submodels

You can allow flows to run from the parent diagram and into a level inside the submodel (as shown in fig a). Simply connect the flows directly to the submodel, and a dialog box appears asking to what level inside the submodel you'd like the flow to connect to. You can also include the level in the parent diagram, if the level is public (as shown in fig b).

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.

Public flows to and from submodels

Public flows (flows controlled by a public auxiliary) can be included in a parent diagram. If you include a flow rate, the flow will automatically be created. You may also create the flow manually, and attach the flow rate to the valve manually. The flow itself is connected directly to the submodel,

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.

Flows that are included when a flow rate is included

If a public flow rate is included in the parent diagram, the flow will be automatically included if it is unconnected in one end. Otherwise the flow will not be included in the parent diagram.

Links to and from submodels and child variables

If a child variable within a submodel refers to a variable outside the submodel, a link can be made from that variable to the submodel itself (the link is optional). If the child variable is included in the parent diagram, a link must be made to the included child variable itself (the link is mandatory). This is illustrated below. The child variable Model_1.Auxiliary_2 refers to Auxiliary_1.

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.

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.

Create a Submodel from a Component

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

a) b) c)

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.

To create a good submodel from a component ! Define a transfer direction for variables that provide input or output from the component (although

not required, defining input variables as in and output variables as out will make your component model easier to read);

! Let the input variables contain only a single value, as this makes it a lot easier to connect the submodel to the surrounding model. Deselecting the Keep Definition in Component Copy option for these variables will make it even easier to connect the submodel.

! Give the component an intuitive name so you can easily find it when you want to include it in your models.

To copy a component as a submodel 1. Click the small arrow next to Copy Component as Submodel on the toolbar. A small menu

appears, containing several options. Select the component you wish to copy (the list contains the recently copied components as well as the components in the current project); select a recent simulation project to copy a component from; or browse for a file to copy a component for. If you select a simulation project, a dialog box containing the components from the selected project will appear. In this case you should select the component and click OK.

2. Click somewhere inside your Constructor diagram to insert the submodel symbol. You can resize and reshape the submodel symbol by dragging it while holding the mouse button down.

3. Drag links from the variables that contains the input data to the submodel symbol. A dialog box will appear when the link is connected to the submodel, and you can select a variable inside the submodel. When you click OK, the definition of the selected variable will be replaced by a reference to the linked variable.

4. Include the output variables from the submodel in the submodel's diagram. 5. Drag links from the included output (child) variables to the variables in the system that will use

their values. Define the variables as required. The included child variables can now be excluded if you wish, and replaced by links directly from the submodel to the variables referring to the output child variables.

Include a Child Variable in a Parent Diagram

You can include a submodel's public child variables in the submodel's diagram.

Note! Only public variables can be included!

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.

The child variable Auxiliary_1 of Model_1 is included in the parent diagram.

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.

Open a Diagram for a Variable

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.

Create Links to or from a Submodel

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!

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.

Create Flows to or from a Submodel

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)

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.

To connect a flow with external flow rates to a submodel

To create a flow as illustrated in figure a) above: 1. Create a flow and connect it to the submodel. 2. If the submodel doesn't contain any public levels, you will not be allowed to attach the flow to the

submodel symbol. Otherwise, if there is only one public level in the submodel, the flow is automatically connected to this level. Finally, if the submodel contains more than one public level, a dialog box appears. Select the level you wish to connect the flow to in the dialog box that appears, and click OK to exit the dialog box and create the flow. If you click Cancel, the operation is aborted (no flow is created).

To create a flow as illustrated in figure b) above: 1. Right-click the submodel and select Include Variable on the shortcut menu. 2. Click where you want to place the included level, and select the appropriate level in the dialog

box that appears (if you have more than one public variable in the submodel that hasn't been included yet). Click OK to include the variable.

3. Create a flow and connect it to the included level.

To connect a flow with internal flow rates to a submodel

Note! Only flows controlled by public variables and that are unconnected in one end can be included in the parent diagram.

To create a flow as illustrated in figure c) above: 1. Right-click the submodel, and select Include Variable on the shortcut menu. 2. Click where you want to place the included flow rate, and select the appropriate flow rate in the

dialog box that appears (if you have more than one public variable in the submodel that hasn't been included yet). Click OK to include the flow rate. The flow will be automatically included in the diagram provided it is unconnected in one end.

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.

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.

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.

a)

b)

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.

Deleting Variable Symbols in Constructor Diagrams

When you are working with copying and deleting variable symbols in Constructor diagram, you should be aware that a model variable can be represented by several variable symbols in different Constructor diagrams. Likewise, a model variable can be present in the model itself without being presented by any variable symbols in Constructor diagrams at all. The Equations View always shows all the variables in the model, while a Constructor Diagram only shows a selection of the variables in the model.

When working with variables in the Equations View, the only operations that are required are the

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

Powersim Studio supports a wide range of 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.

Between diagrams or views ! Dragging into another diagram moves the object from the source diagram to the target diagram. ! Dragging with the Ctrl key pressed includes (if the object is a variable) or copies (for all other

objects) the object in the target diagram. ! Dragging a variable from the Equations View (alternatively the Details Window) onto a

diagram, includes the variable in the diagram. ! Dragging an object from a diagram of one component to a diagram of another component, moves

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.

Include a Model Variable in a Diagram

To include in the diagram a variable that is defined in the model: 1. Click the arrow next to Include Variable on the Diagram toolbar and select the variable you

want to include from the appearing list. 2. Click in the diagram where you want to place the variable.

or 1. Click Include Variable (main button) on the toolbar. 2. Click in the diagram. Select the variable(s) you want to include from the dialog box. 3. Click OK.

or 1. Click Details Window to open the Details Window. 2. Select the variable to include in the tree. 3. Drag it onto the diagram, and drop it where you want to place it.

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.

Exclude a Model Variable from a Diagram

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.

Delete a Variable Symbol

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.

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.

Using Exclude Variable

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.

Using Delete Variable

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.

Link Variables to Powersim Controls

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.

Copy and Paste an Object

To copy an object within or between diagrams: 1. Select the object(s) you want to copy. 2. Drag the object(s) to their target position (either within or between diagrams or components)

while pressing the Ctrl key. A copy of the object(s) will appear when you release the mouse button.

or 1. Select the object(s) you want to copy. 2. Click Copy. 3. If you want to paste the selection onto another diagram, select the new diagram. 4. Click Paste. A copy of the object(s) will appear. 5. Drag the pasted objects to their correct positions.

The default name of a copy is 'Copy of <Original Name>'. Edit it as you like.

Tip! When copying between diagrams, hover over the sheet tab of the target diagram to change active diagram.

Cut and Paste an Object

1. Select the object(s) you want to cut from the diagram. 2. Click Cut. 3. If you want to paste the selection onto another diagram, select the target diagram now. 4. Click Paste. The pasted objects will appear in the diagram. 5. Drag the object(s) to the desired position. 6. The default name of a copy is Copy of <Original Name>. Edit it as you like.

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.

Copy an Area as a Picture

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

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.

To copy an area of the diagram: 1. Select Copy Area as Picture on the Diagram toolbar or menu. 2. Drag out the area you wish to copy as a picture in the diagram. The area is copied as a picture as

soon as you release the mouse button. 3. Go to the file where you want to use the picture, and paste it there (usually using a Paste tool).

The object will be pasted as a picture in the target application.

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.

Paste from Windows Clipboard

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.

Select Objects in the Diagram

1. To select an object, simply click it. When it is selected, it will become highlighted.

To make a multiple selection: 1. Click the objects you wish to select while holding down the Shift key.

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.

To select all objects of a certain type in a diagram: 1. Select Select Special on the Edit menu.

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.

Select Multiple Objects

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.

Select Dominant Object

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.

The operation will also work between components.

To reverse default Snap to Grid setting, hold down the Alt key.

Position an Object by Coordinates

For accurate positioning of a diagram object: 1. Select the variable and click Properties. 2. Click the Symbol tab. 3. Enter the coordinates or click the arrows to adjust them.

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

Delete Diagram Objects

1. Select the object(s) you wish to delete. 2. Hit Del on the keyboard, or right-click the object(s) and select Delete on the shortcut menu.

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.

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

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.

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.

Node Illustration Description

Automatic Studio takes care of the layout of the curve automatically. (If you

change the control handles, the node is automatically changed into a Symmetrical node.)

Symmetrical The control handles are changeable. They will always be parallel,

and both handles will have the same length. The node ensures that the adjacent segments are always symmetrical at the node.

Smooth The control handles are changeable. They will always form a straight

line, but they can have different lengths. The node ensures that the adjacent segments are smooth but not symmetrical at the node.

Cusp

The control handles are changeable and totally independent of one another; they can both have different directions and lengths. The node allows you to create sharp bends between the adjacent segments.

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

To add a new node to a line segment (of a flow, link, or freeform): 1. Right-click the segment where you want to create a new node, and select Add Node on the

shortcut menu.

Select the node, and alter its control points to shape the line the way you want.

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.

Change the Type of a Node

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.

Change the Type of All Nodes of a Line

To change the type of all nodes of a line: 1. Right-click the line (or one of the nodes) that you wish to change, and select Line Operations on

the shortcut menu, then select either All Nodes Automatic or All Nodes Cusp on the submenu.

Delete a Node

1. Right-click the node, and select Delete Node on the shortcut menu.

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

Change the Type of a Segment

There are two types of segments: Straight and Curved.

To change the type of a segment: 1. Select the line containing the segment you wish to alter. The nodes of the line will appear, making

it easier to identify the segments of the line. 2. Right-click the segment you wish to change, and select the new type on the shortcut menu.

Change the Type of All Segments of a Line

To change the type of all the segments of a line: 1. Right-click the line you wish to alter, and select Line Operations on the shortcut menu. Select

All Segments Straight or All Segments Curved on the submenu.

Drag a Line into a New Shape

You can drag a line into a new shape by its nodes. 1. Select the line you wish to reshape. The nodes will appear on the line. 2. Move the cursor over a node until it becomes the following shape: . 3. Click and drag the node to a new position.

You can also reshape the line by altering the control handles of the nodes rather than the position of the nodes: 1. Select the line you wish to reshape. The nodes will appear on the line. 2. Select a node on the line. Control handles appear for the two segments joined by the node. 3. Click and drag the control handles until the segment joint has the desired shape. 4. Repeat the steps above for each node until the line has the desired shape.

By changing the node type you can get more flexible segment joints. To change the node type, right-click the node and select the new node type on the shortcut menu.

Make an Elbowed Line

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

by the node will be changed to retain straight angles and segments.

Note! Only freeforms and flows can use the elbow style.

To apply elbow style to a line: 1. Right-click the line you wish to make elbowed, and select Elbow on the shortcut menu.

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.

Change a Line into a Single Curved Segment

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.

Change a Line into a Single Straight 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

Single Straight Segment on the submenu.

You can have Studio automatically convert lines with several nodes and segments into a straight line.

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.

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.

Display the Details Window at Top

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.

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!

Auto-synchronize Details with Diagrams

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.

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!

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.

Show a Number Auto Report

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

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.

Show a Time Graph Auto Report

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.

Hide an Auto Report

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.

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.

Change Type of Auto Report

To change the type of the auto report: 1. Right-click the auto report that you want to change, and select the new auto report type from the

shortcut menu.

or 1. Select the variable symbol that you want to change the auto report type for. 2. Click the arrow on Show Auto Report, and select the auto report type from the drop-down

list.

or 1. Right-click the variable symbol, and click the arrow next to Show Auto Report, on the

shortcut menu. 2. Select the new auto report type from the drop-down list.

Move and Position an 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.

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.

There are several ways of deleting an auto report: ! Right-click the auto report, and select Delete on the shortcut menu. ! Right-click the belonging variable symbol, and select Delete Auto Report on the shortcut

menu. ! Select the belonging variable symbol in the diagram, and click Delete Auto Report on the

toolbar

Size an Auto Report

1. Select the auto report that you want to size. Handles appear at the borders and corners of the auto report.

2. By dragging the handles, you can resize the auto report to any size you wish.

Powersim Studio will remember the size of an auto report if you hide it. When you unhide it, it will appear with the same size and formatting as it had before it was hidden.

Work with Grids and Guides

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.

Normal and Radial Grids

The normal grid points are placed at regular intervals in the diagram. The regular grid is used to position diagram objects such as variable symbols, frames, and controls. When the Snap to Grid option is switched on, new objects will snap to the grid points. If you wish, you can both view the grid and define the vertical and horizontal distance between the grid points.

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.

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:

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.

Show or Hide Rulers

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.

Turn the Display of Grid On and Off

You can show or hide the normal grid in the diagram: ! Select Grid on the View menu. ! Right-click the diagram, and select Grid on the shortcut menu.

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

Turn the Display of Guides On or Off

You can show or hide guides in the diagram: ! Select Guides on the View menu. ! Right-click the diagram, and select Guides on the shortcut menu.

You can of course snap to guides even though they are not visible in the diagram.

Turn Snap to Normal Grid On and 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.

Turn Snap to Radial Grid On or Off

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.

Turn Snap to Guides On or Off

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

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.

Change Grid Settings

1. Select Diagram Settings on the Diagram menu. 2. Click the Grid Settings tab. 3. Alter the settings of the normal grid:

1. Set the spacing of the horizontal and vertical grid lines. Points (pt), centimeters (cm), and inches (in) are allowed units.

2. Set the coordinates of the grid's starting point (the coordinates (0cm,0cm) designate the top left-hand corner of the diagram window).

3. Select the Snap to normal grid option to turn snapping to the normal grid on, or deselect it to turn snapping off.

4. Alter the settings of the radial grid: 1. Set the step angle for the radial grid using the Angle box. 2. Set the offset angle (the offset from a horizontal line) of the radial grid using the Offset angle

box. 3. Select the Snap to radial grid option to turn snapping to the radial grid on, or deselect it to turn

snapping off. 5. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

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.

Change Guide Settings

1. Select Diagram Settings on the Diagram menu. 2. Click the Guide Settings tab. 3. The guides are listed in two dialog boxes, sorted by orientation. You can:

! Add new guides by clicking New. ! Lock a guide by clicking Lock. ! Delete the selected guide by clicking Delete. ! Delete all the guides in a list box by clicking Delete All.

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

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:

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

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

To delete a guide from the diagram: 1. Move the mouse pointer over the guide you wish to delete. The cursor will change into one of

these cursors: . 2. Drag the guide out of the diagram by drag and drop:

! If the guide is horizontal, drag it beyond the top edge of the diagram and drop it. ! 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.

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.

Format Several Objects in One Operation

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.

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.

Format the Diagram Background

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.

Use Picture Fills for Objects

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.

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. ! Click Browse to open an image file from a file location. ! Click Paste to paste an image from the Windows Clipboard.

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

Align Diagram Objects

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.

Selection with dominant object

All alignment commands are found on the Layout toolbar and menu. ! Click Align Top Edges to align the top edges of the selected objects to the top edge of the

dominant one. ! Click Align Bottom Edges to align to the bottom edge. ! Click Align Left Edges to align to the left edge. ! Click Align Right Edges to align to the right edge. ! Click Align Horizontal Centers to align the objects centered horizontally. ! Click Align Vertical Centers to align objects centered vertically.

Rotate Diagram Objects

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.

Note! It is currently only frames that support rotation in Constructor diagrams.

To rotate the object(s) using the Symbol property page: 1. Select the frame(s) you wish to rotate. 2. Click Properties on the toolbar, or right-click the frame and select Properties on the

shortcut menu. 3. Click the Symbol tab. 4. Enter the new rotation angle in the Rotation box on the property page. The number must be an

integer between -359 and 359. 5. Click OK to save the changes, or click Apply to save the changes without exiting the dialog box.

You find the four rotation commands on the Symbol toolbar. To use them: ! Select the object(s) you wish to rotate. ! Click Rotate Left to rotate the object(s) 90° to the left. ! Click Rotate Right to rotate the object(s) 90° to the right. ! Click Flip Horizontal to flip the object(s) horizontally (mirror them). ! Click Flip Vertical to flip the object(s) vertically.

Space Diagram Objects

1. Select the objects to be evenly spaced in the diagram. 2. Click Space Evenly Across to space evenly along the horizontal axis or Space Evenly

Down to space vertically.

The objects will be spaced evenly across the boundaries of the selection.

Tip! The commands are available on both the Layout menu and toolbar.

Make Diagram Objects Same Size

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.

Selection with dominant object

All alignment commands are found on the Layout toolbar and menu.

! 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

Objects and symbols can be positioned in different ways. 1. Select the object and drag it to its new position in the diagram.

Or: 1. Select the object(s) and click Properties on the toolbar. 2. Enter the exact position of the symbol under the Symbol tab of the Property pages.

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.

Resize a Multiple Selection

To make all selected objects the same size: 1. Select the objects and click Properties on the toolbar. 2. On the Symbol tab, specify a new width and height under Width and Height respectively.

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.

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.

Change Line Style and Color

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.

Change Object Color and Shape

To change the fill color of an object:

You can use the Format toolbar to change the fill color of the objects you have select. ! Click the arrow in Fill Color and select the fill color you wish. It will be applied to the selected

object(s). ! Click Fill Color to apply the same fill color as was used the last time (the color is indicated on

the button). ! Click the arrow in Shape Type and select the shape you wish. It will be applied to the selected

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.

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.

You can fully customize the appearance of freeforms and frames.

Lines can have arrows at one or both ends, and you can fully customize the appearance of these arrowheads and -tails.

Hyperlinks and bookmarks allow you to create hyperlink jumps inside your simulation project. These can be used in combination with frames and lines to create visually stunning simulator interfaces.

The Constructor diagram lets you fully control the order in which the objects appear in the diagram. A frame can thereby form the background for other frames or forms, or they can simply be used to separate your model into different sections. You can create visual user interfaces using them, and you can also use them to create causal-loop diagrams.

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

A bookmark with extent (left) and without extent (right).

When you define a bookmark, you must assign a unique name for it within the component. This name is used when you jump to it from a hyperlink. You can also specify whether the bookmark should be

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

Relative Versus Absolute Addresses

When you specify a hyperlink target, you can select whether the address should be relative or absolute. Relative hyperlinks can only point to information that is unambiguously identified relative to the location of the hyperlink itself. When you use relative addresses, you are ensured that the link will always lead to a target within the current simulation only.

There are two types of diagrams in a simulation. The component contains a diagram book that is shared by all the simulations belonging to the component, while each simulation itself may contain one or more exclusive private diagrams.

All hyperlinks leading from one shared diagram to another; from one private diagram to another; or from a private diagram to a shared diagram, are always unambiguous, and can be defined with relative addresses. This ensures that all jumps made using these hyperlinks will always be within the current simulation.

However, you cannot create relative hyperlinks that lead from a shared diagram to a private diagram, because the private diagrams are dependent on the simulation they exist in. Thus, when the shared diagram is opened in another simulation, the hyperlink target would not exist. If you need to create a

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

To create a frame with the previously selected (or default) shape: 1. Click Frame. 2. Drag the frame to the desired size and position in your diagram.

To create a frame with a different shape: 1. Click the arrow in next to Frame, and select the shape you want. 2. Drag the frame to the desired size and position in your diagram.

The frame snaps to the grid if it is turned on. To temporarily reverse the grid setting, press Alt while dragging.

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.

Add Text to a Frame

A frame in Studio can contain text. To add text to a frame: 1. Select the frame you want to add text to. 2. Start typing the text. Hit Ctrl-Enter to create a line shift. 3. Hit Enter to stop typing.

Hit F2 to edit the text of a frame.

The text can be formatted on the Format toolbar.

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.

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. ! Click Paste to paste an image from the Windows Clipboard.

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.

To create a bookmark without extent 1. Click Bookmark. 2. Click once where you would like to place the bookmark. 3. Right-click the new bookmark, and select Properties on the shortcut menu to define the

bookmark.

Note! If the bookmark has extent after you have created it, you can turn it off in the Properties dialog box.

To create a bookmark with extent: 1. Click Bookmark. 2. Drag the bookmark to the desired size and position in your diagram. 3. Right-click the new bookmark, and select Properties on the shortcut menu to define the

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.

Zooming and centering a bookmark when it is visited

You can have Studio automatically center the bookmark when it is visited. If the bookmark has extent, you can also make Studio automatically zoom the diagram to fit the bookmark within the visible area of your screen when it is opened. 1. Double-click the bookmark you wish to alter, or right-click it and select Properties on the

shortcut menu. 2. Select Center bookmark when visited to automatically center the bookmark. 3. Select Zoom bookmark when visited to automatically zoom the bookmark. 4. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.

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

Create Hyperlinks without Text

To create a hyperlink without text: 1. Click Hyperlink. 2. Drag the hyperlink object to the desired size and position in your diagram. 3. Select the text and delete it. 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 in this project, Web page, File,

and E-mail address. 6. Select the target of the hyperlink under Address. If you wish to make a 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 deleted the text from the hyperlink, the surrounding area of the hyperlink will be drawn using a dotted line instead of a transparent line. This is to make it easier for you to see where the hyperlink is and the area it covers. When you switch the diagram to either User or Presentation Mode, the dotted line will automatically disappear.

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.

Resize a Frame to Fit a Picture

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.

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.

Use a Frame as Background

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.

Select a Transparent Frame

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.

Draw a Freeform Line

1. Click Open Freeform. 2. Click where you want the line to start. 3. While you drag the line towards its end position, you can click to add nodes and divide the line

into segments. 4. Drag the line to the end position and click to complete the line.

The line snaps to the normal grid setting if it is turned on. You can reverse the setting by pressing Alt.

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.

Create Image Maps

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.

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.

Change Arrowheads or -tails on Freeform Lines

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.

Change the Order of Freeforms

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.

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.

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

For a closer or more remote view of a selected part of the diagram: 1. Click Zoom. 2. Drag an outline around the area you wish to zoom.

When you release the mouse button, the area you selected will be magnified to fit the view.

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

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

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.

About Simulation State and History

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

There are three different calendars available in Studio. These are ! The Gregorian Calendar ! The Fiscal Calendar

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

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.

Simulations without Time Units

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

The time interpretation interval

The time interpretation interval affects the time value of the system, as returned by the TIME function. Selecting an interpretation interval of '1 week' will result in a time value representing the current simulation time in the number of weeks since 1/1/1. Similarly, selecting an interpretation interval of '1 year' will result in a time value representing the current simulation time in the number of years since 1/1/1. In this case, the time value will represent the date 1/1/2000. In comparison, when simulation time has time units, it is measured in seconds from 1/1/1. Thus, the value of 2000@s represents the point in time 2000 seconds after 1/1/2000, which is 1/1/2000 00:33:20.

The time interpretation interval affects the flows and the time values of your system. If you select an interval of one week, all your flows will be calculated relative to one week. Thus, with a timestep of one day, a flow rate with value 7 will be interpreted as 7 per week. The flow will therefore yield 1 per timestep (in this case 1 per day).

Tip! Setting the timestep equal to the time interpretation interval will yield flows per timestep

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

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.

Expressions involving time values

When running simulations without time units, you are allowed to include time values (without units) directly in your variable expressions. This can be illustrated in the following definition:

aux A = IF(TIME=2001, 1000, 2000).

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.

aux A = IF(TIME=DATE(2001), 1000, 2000)

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.

Set Preferred Time Unit

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.

To set the preferred time unit: 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 preferred unit under Time Unit. 3. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.

The table below summarizes the time units you are allowed to select from the list. Note that some options are only available when certain calendars have been selected. For your convenience, the last

column shows the resulting unit for the variable A defined as:

aux A = 1<<m>>/TIMESTEP unit m = __METER // Defined in Global Units

Set Simulation Times

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

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

details, click here). 6. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

Change the Calendar

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.

Select Available 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.

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

Set the Time Step

To set the time step 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 the Time Step to indicate the time interval to separate the simulation

results. The timestep is entered using the syntax given below. 3. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

When entering times, you can use the available units (as you can in all other boxes in Studio). If you enter '1<<da>>', you get a time step of 1 day. If you enter only a number, the time unit is assumed to be the preferred time unit as specified in Project Settings.

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.

Set Simulation Speed

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.

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.

Keep History for all Variables

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.

To keep history for all variables: 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 History for all Variables option. 3. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.

Save Simulation State with Project

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.

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.

To set the run count: 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 Run Count, enter the number of runs. 3. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

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.

Turn on/off Time Units for Simulation Time

To turn on units for simulation time: 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 Time has unit option. 3. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

Note! This is the default setting when creating a new simulation project.

To turn off units for simulation time: 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. Deselect the Time has unit option. 3. Select a time interpretation interval in the Time measured in intervals box. This option allows you

to specify what a time step should be interpreted as in your simulation. 4. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

The time interpretation interval indicates the scale of the (unitless) time axis. If you select '1 week', the value returned by the TIME function, for example, will denote the number of weeks from 1/1/1. If

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.

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.

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.

The Euler Integration Method

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)

2. Calculate the value of Level at t=T+dt based on LevelT and Flow

LevelT + dt = LevelT + dt*Flow

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.

Second Order Runge-Kutta Integration

The Second Order Runge-Kutta method uses two flow calculations within the given time step. As mentioned above, the two calculations are weighted with the second given more weight than the first.

Powersim executes the following two steps to calculate the integral over an interval from t to t+dt:

1. Estimate the flow at two points in the interval T to T+dt

F1 = dt*F(LT, T)

F2 = dt*F(LT + F1, T + 3/4*dt)

2. Calculate a second order estimate of LT+dt by using a weighted average of F1 and F2

LT+dt = LT + 1/3*F1 + 2/3*F2

Third Order Runge-Kutta Integration

The Third Order Runge-Kutta integration method works like the Second Order method, but uses three rather than two flow calculations to compute an estimate of the flow over one time step. The integration algorithm is described below.

1. Estimate the flow at three 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 + 3/4 * F2, T + 3/4 * dt)

2. Calculate a third order estimate of LT+dt by using a weighted average of F1, F2, and F3

LT+dt = LT + 2/9*F1 + 3/9*F2 + 4/9*F3

Fourth Order Runge-Kutta Integration

The Fourth Order Runge-Kutta method works like the Second Order method, but uses four rather than two flow calculations to compute an estimate of the flow within a time step. The final calculation uses a weighted average of the four derivatives, and this calculation is based on the Taylor series expansion for a function of two variables. The algorithm is outlined below.

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

LT+Dt = LT + 1/6*F1 + 2/6*F2 + 2/6*F3 + 1/6*F4

Set Integration Order

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.

Start and Stop a Simulation

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.

Play a Simulation Stepwise

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.

Reset a Simulation

To reset the simulation: 1. Click Reset Simulation on the Simulation toolbar.

Tip! You can start the simulation again without resetting it by simply clicking Play.

Add Cue Points to the Simulation Run

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.

To add cue points to your simulation run: 1. Select Add Cue Point on the Simulation menu.

You can go to a previously inserted cue point by clicking Go to Cue Point on the Simulation menu.

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!

To go to a last cue point in the simulation: 1. Select Go to Cue Point on the Simulation menu.

To select the cue point that you wish to go to: 1. Click the small arrow next to Go to Cue Point on the Simulation menu, and select the cue

point that you wish to go to in the drop-down list.

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.

Restore Permanent Variables

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.

About Runs and Reference Data

Store Simulation Runs for Later Use

Sometimes when you experiment with your simulations, you find simulation runs that are interesting and that you wish to store for later use. Studio allows you to save as many simulation runs that you wish. You can save simulation runs in two ways: ! Store in Runs: Simulation runs can be stored under the component's collection of simulation runs,

located under Runs under the component in the Project Window. ! Save to disk: Simulation runs can be saved to disk (in *.sir-files). This is useful if you want to

share the simulation run with peers who have the (exact) same simulation project on their computer.

The following is stored when you save a simulation run: ! The simulation state (the value of all variables at the current time step). ! The history of variables used in controls and auto reports (or all variables, if the History for All

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.

Use Stored Simulation Runs as Reference Data

You can use previously stored simulation runs as reference data in the active simulation run. When you create parameters in controls, you can create two different types of parameters: Active Run Parameters and Reference Data Parameters. When you have specified a simulation run to be used for reference data, reference data parameters will become visible in controls, displaying the values of the corresponding variable in the selected run. This allows you to visually compare the results of the current simulation run with a previous run. Reference data parameters are prefixed with an '*' (asterisk) in controls and elsewhere.

The inventory of the current simulation run (Population) is compared to reference data from a

previous simulation run (*Population).

Save a Simulation Run in the Project

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.

Tip! You can save a run at any time in the simulation.

To save a simulation run: 1. Select Add to Runs on the Simulation menu or on the Simulation toolbar.

or 1. Open the Runs collection, available under the component in the Project Window. 2. Right-click somewhere in the white space, and select Add Active Run on the shortcut menu.

The run will be saved with a default name that you can change in the Runs view if you want to.

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 ('?').

Rename a Simulation Run

You can rename a simulation run in the Runs collection.

Tip! The name of the simulation run will appear in the Reference Data list box in the toolbar and on the Simulation menu.

To rename a simulation run: 1. Double-click Runs under the component in the Project Window. 2. Select the simulation run that you wish to rename. 3. Hit F2 and type the new name of the run. Hit Enter when you have finished typing the new

name.

Export a Simulation Run to File

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

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.

Import a Simulation Run from 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 ('?').

Make a Simulation Run Visible in Presentation Mode

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.

Enter Documentation for a Saved Run

You can enter documentation for a saved run: 1. Double-click the Runs view under the component in the Project Window. 2. Select the Documentation field of the run that you wish to enter a documentation note for. 3. Type the text, and hit Enter when you are finished.

Delete a Simulation Run

You can delete a run from the Runs collection.

Note! You cannot delete a run that is used as reference data!

1. Double-click Runs under the component in the Project Window. 2. Right-click the run you wish to delete, and select Delete on the shortcut menu. Alternatively,

select the run, and hit Del on the keyboard.

Select Reference Data

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.

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.

About Report Window

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.

Minor and Major Intervals

These intervals allow you to specify globally the major and minor time intervals that are being used in your component. As an example, these intervals are used by the Time Graph Control to identify the major and minor ticks on the time axis. You can specify them manually, or have Studio select them automatically based on the simulation settings.

Set up Major and Minor Time Intervals

1. Select Simulation Settings… on the Simulation menu. 2. Click the Report tab. 3. Under Intervals, deselect Auto to enter the major time interval of the simulation. 4. Under Reporting Window, deselect Auto to enter the minimum time interval of the simulation. 5. Click OK to save the changes, or Apply to save the changes without exiting the dialog box.

Studio uses the time intervals to major and minor tick marks on time axis, and to draw major and

minor gridlines in controls.

Set up Report Window

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.

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

Point and Normal Units

There are two different types of units: Point Units and Normal Units. Point units are used to identify a specific point on a scale, while normal units are used to identify an interval relative to a scale. Thermodynamic temperature and points in time are measured using point units, while temperature differences and time intervals are measured using normal units. The figure below illustrates this distinction. A point unit is defined by two elements; the scale and the offset. A normal unit is defined by a scale alone. A point unit is referred to by a preceding '@', as in 100@C.

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.

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.

Global and Local Units

In most cases, units are created and defined globally in the simulation catalog, and are available for all the model components. However, you can also define units that are local to the component only. Local units must, however, be derived from global units - they cannot be atomic units. You define global units in the Global Units view, and local units in the Local Units view. Both are available from the Project Window.

Preferred Time Unit

It is often convenient to control the time unit part of a unit calculated automatically. 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. This way, you can control whether an automatically generated unit becomes km/s or km/hr, just to illustrate one commonly used unit of measurement.

About Unit Operations

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:

Constant <<Unit Name>>

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

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.

Properties, Identifiers, and Pre-defined Units

The Properties of a Unit

A unit in Studio has several properties. Some of these properties are used to define the unit uniquely, while other properties are used for presentation purposes by Studio. The table below summarizes these properties and how they are used.

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.

Property Description Example

Unit Name The name of the unit. m, person, stock

Short Name The short name is an abbreviation used by Studio if the space for presenting units are limited.

m, psn, st

Plural Name The plural name is used whenever Studio detects that the quantity exceeds one.

m, persons, stocks

Definition The definition of the unit. The definition can contain expressions as well as literals and single units.

kgm/s^2 (=N), 1/s (=Hz), 0.3048m (=ft).

Documentation A text field that you can use to document your unit. Any text.

Note A text field that you can use to attach notes to your unit.

Any text.

Identifier Description How to define it

@(<scale>,@<offset>)

Identifies point units. Enter the scale of the unit in the first part of the expression, and the offset of the unit in the second (after the @-sign).

ATOMIC

Identifies an atomic unit. Select the Atomic radio button in the Unit Definition property page.

__LOCALCURRENCY

Creates a local currency unit. Available under Add Currency Unit on the shortcut 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.

__CURRENCY("<string>" [=<Conversion Expression>])

Creates a unit for the currency identified by the string. The currency symbol and currency formats for the specified currency is used. To define a conversion rate towards another currency, you are allowed to define it as an optional definition parameter (this requires the currency used in the conversion to be defined). Example: __CURRENCY("USD"), __CURRENCY("EUR"), __CURRENCY("BEF"=EUR/40.3399)

Some are available under Add Currency Unit on the shortcut menu inside the Global Units view. If you need other currencies, simply define them manually.

__SECOND __METER __KILOGRAM __CANDELA __AMPERE __KELVIN __MOLE

Creates a base unit from the SI system. Available under Add Standard Unit on the shortcut menu inside the Global Units view.

__RADIAN __STERADIAN

Creates a pseudo-unit from the SI system. Available under Add Standard Unit on the shortcut menu inside the Global Units view.

Unit Definition Notes

s @(__SECOND; 0@__SECOND) Second. Based on the base unit for time from the SI

system. The unit is a System Time Unit that cannot be deleted or modified.

min @(60s; 0@s) Minute. The unit is a System Time Unit that cannot be deleted or modified.

hr @(60min; 0@min) Hour.

da @(24hr; 0@hr) Day. The unit is a System Time Unit that cannot be deleted or modified.

wk @(7da; 0@da) Week. The unit is a System Time Unit that cannot be deleted or modified.

mo

@(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 calendar specified for the simulation is Gregorian or Fiscal.

qtr @(90da; 0@da) (Bank calendar) @(91da; 0@da) (Fiscal calendar)

Quarter. The unit is a System Time Unit that cannot be deleted or modified. It will be undefined if the calendar specified is Gregorian.

Available Standard Units

There are several commonly used units easily available on the Add Standard Unit on the shortcut menu of the Global Units view. Among these are the base units of the SI system (except for time, which is already defined by default), as well as a other commonly used units.

yr @(360da; 0@da) (Bank calendar) @(364da; 0@da) (Fiscal calendar)

Year. The unit is a System Time Unit that cannot be deleted or modified. It will be undefined if the calendar specified is Gregorian.

rad

@__RADIAN Radians. A pseudo-unit for plane angles from the SI system. The unit is a System Unit that cannot be deleted or modified. The unit represents a plane angle.

deg @((3,14159265358979323846/180)rad; 0@rad)

Degrees. Based on the pseudo-unit rad. The unit is a System Unit that cannot be deleted or modified. The unit represents a plane angle.

grad @((3,14159265358979323846/200)rad; 0@rad)

Gradians. Based on pseudo-unit from the SI system. The unit is a System Unit that cannot be deleted or 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

Unit Definition Notes

m __METER Meter. Based on the base unit for length from the SI system.

kg __KILOGRAM Kilogram. Based on the base unit for mass from the SI system.

sr __STERADIAN Steradians. A built-in unit in Studio that is based on the pseudo-unit for solid angles from the SI system.

mol __MOLE Mole. Based on the base unit for amount of substance from the SI system.

cd __CANDELA Candela. Based on the base unit for luminous intensity from the SI system.

A __AMPERE Ampere. Based on the base unit for electric current from the SI system.

K __KELVIN Kelvin. Based on the base unit for temperature from the SI system.

km 1000m Kilometer. Derived from m (meter).

cm 0.01m Centimeter. Derived from m (meter).

l (0.1m)^3 Liter. A measurement for volume based on the SI base unit m.

N kgm/s^2 Newton. The standard unit for force, derived from four different SI base units.

J kgm^2/s^2 (= Nm) Joule. The standard unit for energy, derived from SI base units.

W kgm^2/s^3 (= J/s) Watt. The standard unit for power, derived from SI base units.

Available Currency Units

There are several currency units easily available on the Add Currency Unit on the shortcut menu of the Global Units view. Among these are the thirteen European currencies that are fixed against the Euro. When one of these are added, the Euro is also automatically included. The loc unit representing a currency using the currency formatting specified under Regional Settings (or Options) on your computer is also available on the submenu.

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.

C °(__KELVIN; 273,15°__KELVIN)

Celsius. Based on the base unit for temperature from the SI system, Kelvin.

F °(5/9C; -32*5/9°C) Fahrenheit. Based on Celsius.

Unit Definition Notes

loc

__LOCALCURRENCY Local Currency Unit. A unit for currency which takes it settings from the local currency unit specified in Regional Settings (or Options) 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).

EUR __CURRENCY("EUR") The euro currency.

BEF __CURRENCY("BEF"=EUR/40.3399) Belgian Franc. This currency is fixed towards the euro.

DEM __CURRENCY("DEM"=EUR/1.95583) Deutsche Mark. This currency is fixed towards the euro.

GRD __CURRENCY("GRD"=EUR/340.750) Greek Drachma. This currency is fixed towards the euro.

ESP __CURRENCY("ESP"=EUR/166.386) Spanish Peseta. This currency is fixed towards the euro.

FRF __CURRENCY("FRF"=EUR/6.55957) French Franc. This currency is fixed towards the euro.

IEP __CURRENCY("IEP"=EUR/0.787564) Irish Pound. This currency is fixed towards the euro.

ITL __CURRENCY("ITL"=EUR/1936.27) Italian Lira. This currency is fixed towards the euro.

LUF __CURRENCY("LUF"=EUR/40.3399) Luxembourg Franc. This currency is fixed towards the euro.

NLG __CURRENCY("NLG"=EUR/2.20371) Dutch Guilder. This currency is fixed towards the euro.

ATS __CURRENCY("ATS"=EUR/13.7603) Austriann Schilling. This currency is fixed towards the euro.

PTE __CURRENCY("PTE"=EUR/200.482) Portuguese escudo. This currency is fixed towards the euro.

Tip! You can find the latest (daily) euro foreign exchange reference rates for most other currencies at the European Central Bank.

Other Useful Units of Measurement

The table below contains other useful units of measurement not found in Studio. The table shows their definitions.

FIM __CURRENCY("FIM"=EUR/5.94573) Finnish Markka. This currency is fixed towards 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).

loc

__LOCALCURRENCY Locale Currency Unit. A unit for currency which takes it settings from the locale currency unit specified in Regional Settings (or Options) 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).

Unit Definition Notes

mm 0.001m Millimeter. Unit for length, derived from m (meter).

mile 1609.344m (= 1760yd)

Mile. Unit for length, derived from m (meter).

yd 0.9144m Yard. Unit for length, derived from m (meter).

ft 0.3048m Feet. Unit for length, derived from m (meter).

in ft/12 Inch. Unit for length, derived from m (meter).

nm 1852m Nautical mile. Unit for length, derived from m (meter).

gl 3.7853l US Gallon. Unit for volume, derived from l (liter).

Hz 1/s Hertz. Unit for frequency, derived from s (second).

g 0.001kg Gram. Unit for mass, derived from kg (kilogram).

ton 1000kg Ton. Unit for mass, derived from kg (kilogram).

pound 0.45359237kg Pound. Unit for mass, derived from kg (kilogram).

knot 0.514444m/s (=nm/hr)

Knot. Unit for velocity, derived from m (meter) and s (second).

mph 0.44704m/s (= mile/hr)

Miles per hour. Unit for velocity, derived from m (meter) and s (second).

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 '/'.

Create a Model without Units

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

Time without units

The most extreme solution, is to turn off time units for the simulation time in addition to using 1 (=unity) as the unit for all variables. This is a way of emulating the time scheme familiar from Constructor 2.51 and other simulation tools. All flow rates can now be defined without a rate unit. Be aware, however, the unit inconsistencies might occur.

Available Time Units in the Project

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.

Add a Global Unit

1. Open the Global Units view by double-clicking its entry in the Project Window, or select Global Units under Catalog 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.

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.

Add a Local Unit

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.

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

Add Currency 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!

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.

Define an Atomic Unit

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.

Define a Normal Derived Unit

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.

To define a derived normal unit: 1. Double-click the unit to define as a normal unit, 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 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.

Define a Derived Point Unit

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

In this example, the auxiliary A is defined as the temperature of 85 degrees Celsius.

Note! You can use either of the two available identifiers '@' and '°'.

To define a derived point unit: 1. Double-click the unit to define it as a normal unit, 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 Point Unit option. The lower half of the page is activated. 4. Select the Derived option. 5. Replace the default text <scale> in the Scale box by the scale of the unit. 6. Replace the default text <offset> in the Offset box by the offset of the unit. 7. Click OK to finish the definition, or click Apply to apply the changes without closing the

property page.

You may also enter the unit definition directly in the Definition Text box.

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

unit temp = @(10C, 100@C)

Note! To be able to define a derived unit, all the units used to define it must already be defined in your project.

Specify a Unit for a Level

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.

Specify a Unit for a Constant

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

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.

Specify a Unit for an Auxiliary

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

Include Units in Variable Expressions

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

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

Explicitly Select Unit for an Expression

To explicitly select a unit for an expression: 1. Double-click the variable, or right-click it and select Properties on the shortcut menu. 2. On the Definition page, enter the unit you wish to use in the Unit box.

You should note that you can explicitly select the unit of a variable expression only if the unit you select is compatible with the calculated unit. You will find examples of compatible units in the examples listed below.

Examples:

To create some examples, let's define a few units.

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:

Create Unitless Variable Expressions

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!

Delete a Global 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.

To delete a global unit: 1. Open the Global Units view by double-clicking its entry in the Project Window, or select

Global Units under Catalog 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.

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

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.

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

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.

Variable Properties and Options

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.

General Information (All Variable Types)

All variables, whether they are levels, constants, or auxiliaries, share many properties. These properties define the variable's dimension, unit, data type, whether their values are imported to or exported from the component, and so on. Most of these properties are identical for the various variable types.

The (Data) Type of the variable defines the set of values accepted by the variable. The data type defines the operations that are available for that variable. There are currently four data types available in Studio: LOGICAL, INTEGER, REAL, and COMPLEX. When variables are used as parameters in function or operator expressions in definitions, they must fulfill the data type requirements of that expression. These requirements are described in the data sheet for the various functions and operators.

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

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

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.

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.

About Permanent Variables

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

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.

This model is defined as:

unit kg = __KILOGRAM // Added in Global Units level Reservoir = 10<<kg>> aux Ratio = 0.3<<hr>> aux Flow = Reservoir/Ratio

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.

The model is defined as:

unit kg = __KILOGRAM // Added in Global Units level Reservoir = 10<<kg>> aux Flow = If(Reservoir>0<<kg>>, 1.1<<kg/da>>, 0<<kg/da>>)

The behavior of the model is shown in the time graph below.

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.

Variable Definition Examples

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.

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:

def Variable = 10<<m>>

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:

def Variable = {{1,2,3},{4,5,6}} (auto) dim Variable = 1..2,1..3

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.

dim Variable = 4..5,8..10 def Variable = 4 result Variable = {{4,4,4},{4,4,4}}

Example 2: Expressions with Operators

Expressions involving operators are entered in the same way as in spreadsheets:

def Variable = 10/5 result Variable = 2

If units are included in the expression, they must be included together with one or both of the operands:

def Variable = 10<<m>>/5<<s>> unit m = __METER // Added in Global Units

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.

def Variable = 10<<m>>/5<<s>> unit Variable = m/hr

Expressions with operators can very well include variable references.

def Variable_2 = ... // Any definition

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

def Variable = 10!+5/3

is equal to the expression

def Variable = (10!)+(5/3)

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.

def Variable_1 = {{1,2},{3,4}} def Variable_2 = {{5,6},{7,8}} def Variable_3 = Variable_1 / Variable_2 result Variable_3 = {{0.2,0.33},{0.43,0.5}} def Variable_4 = Variable_1 #/ Variable_2 result Variable_4 = {{3,-2},{2,-1}}

Example 3: Function Expressions

Functions in Studio usually require one or more parameters. Some have optional parameters that you can leave out if you don't need them. In those cases, the function will use the default value (as specified on the function's reference sheet). Functions can take both literal expressions and other variables as input parameters. Most of them will also accept other function expressions as input parameters. For the function to be properly defined, however, you must make sure that the input parameters follow the requirements (for type, unit, and dimensions) stated in the function's reference sheet.

A function usually accepts literal expressions as input parameters.

unit m = __METER // Added to Global Units def Variable = ABS(-1.321<<m>>) result Variable = 1m

The ABS function will also accept another function expression as its input parameter.

def Variable = ABS(2*SINWAVE(1,90<<da>>))

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

const Period = 90<<da>> aux 'Sine Wave' = SINWAVE(1,Period)

aux 'Positive Wave' = ABS('Sine Wave')

The output from this simple model is shown in the time graph below.

Example 4: Array Expressions

Arrays can be created by entering the various array elements enclosed by '{' and '}'. Each array element can very well be a function or array expression itself. It is important to observe that all elements of an array have compatible units and the same data type.

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.

aux Array = {{32,14,23,52},{42,61,93,38},{49,10,20,31}} aux Summary = {ARRSUM(Array),ELEMCOUNT(Array), ARRAVERAGE(Array),ARRSTDEVP(Array)} result Summary = {465, 12, 38.75, 22.13}

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.

def 'First Array' = FOR(i=1..3,j=1..2|i*j) result 'First Array' = {{1,2},{2,4},{3,6}} def 'Second Array' = CONCAT({1,2},FOR(i=3..7|i*2),{30,40}) result 'Second Array' = {1,2,6,8,10,12,14,30,40}

Example 5: Indexing Arrays

When you want to access one or more array elements in an array, you specify an index reference enclosed in '[' and ']' (square brackets). The index reference per dimension can be either a single value (ex.: 2), a range (ex.: 1..2), or an entire range ('*'). You can include one index reference for each dimension in the array. If you omit the index reference for a dimension, the entire dimension is returned.

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]!

To illustrate, create four auxiliaries and name them Array, Single, Multiple, and All. The definitions are presented below.

def Array = {{32,14,23,52},{42,61,93,38},{49,10,20,31}} def Single = Array[2,3] result Single = 93 def Multiple = Array[1..2,3] result Multiple = {23,93} def All = Array[*,3] result All = {23,93,20}

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.

def Array = {{32,14,23,52},{42,61,93,38},{49,10,20,31}} def A = Array[2..?,3..?] result A = {{93,38},{20,31}} def B = Array[*,?..2] result B = {{32,14},{42,61},{49,10}}

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 Array = {{32,14,23,52},{42,61,93,38},{49,10,20,31}} def A = 2 type A = Integer def B = 3 type B = Integer def C = LOOKUP(Array,A,B) result C = 93 def D = Array[INDEX(A),INDEX(B)] result D = 93

Example 6: Redimensioning Arrays

In some cases, you might need to assign new dimensions to an array. This is useful when you build up arrays using the CONCAT function, since the CONCAT function can only concatenate succeeding dimensions. As an example, it is not allowed to concatenate two arrays which both have the dimension 1..4. In this case, the last array must be redimensioned to 5..9. To achieve this, you specify an index range consisting of two parts. The first part contains the new starting and ending points of the dimension. The second part contains the reference to the cells within the new range. The two parts are separated by a ':' (colon). Thus, to redimension an array A with the dimension 1..4 to the dimension 5..8 and pull out the new elements 6..7, you write A[5..8:6..7]. One or both of the parts can be open, so you could also write A[5..?:6..7]. To pull out the elements from 6 and on, you could write A[5..?:6..?]

The following example illustrates how this redimensioning can be used to concatenate two arrays. You need three auxiliaries A, B, and C.

def A = {1,2,3,4,5}

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}}

About Continuous Flows

What Is a Continuous Flow?

A continuous flow represents the idea of quantities being transported between level variables. Levels are changed by adding the value of inflows and subtracting the value of outflows from their current values. Flows are controlled by flow rates. For a flow Flow controlled by a flow rate Rate, the value of the flow at a give time t is found by the expression below.

Flow = dt*Rate

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

The Parts Defining a Flow

The flow is defined by two parts. The first is the definition of the flow rate variable. The second is the flow equation specified for the level(s) it is connected to.

You can use any variable as the flow rate variable, as long as the data type of the flow rate matches the data type of the connected level, and the flow rate's unit matches the expression above. Further, you can alter the behavior of the flow rate by selecting an individual integration order for the flow rate variable. For continuous flows, you can either use the default simulation settings for the project, or you can opt for a first order flow, which means that the flow rate is calculated only at the start of the time step. This option will only differ from the default option if a higher order integration method is chosen for the simulation project. Using first order integration for the flow rate is identical to defining the flow rate using the EULER function, as shown below:

aux Rate = EULER(Expression) // equals first order integration for Rate

Note! Reservoirs (levels that cannot be depleted below zero) cannot have first order flows

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.

Using Functions in Flow Equations

When the flow involves flow rates and levels of different dimensions, you must use flow functions in your flow equations to define how the flow should be added to (or subtracted from) the level. Flow functions give you exact control of how the flow flows into the level on an element basis, and provides functionality for creating advanced structures such as queues.

About Discrete Flows

What is a Discrete Flow?

While continuous flows represent quantities being transported between levels per time (such as cars passing through an intersection, or water flowing through a water hose), discrete flows represent transactions of given quantities at given times (a shipment of cars, a or a purchase of a certain goods). While continuous flows are integrated over the time step (and is thus dependent of the length of the time step), discrete flows represent a quantity that is accumulated by the level each time step (and is thus independent of the length of the time step). The expressions for continuous flows and discrete flows are shown below (as they appear in the flow expression for the connected level).

Flow = dt*Rate // continuous flow Flow = Rate // discrete flow

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!

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 Parts Defining a Flow

The flow is defined by two parts. The first is the definition of the flow rate variable. The second is the flow equation specified for the level(s) it is connected to.

You can use any variable as the flow rate variable, as long as the data type of the flow rate matches the data type of the connected level, and the flow rate's unit matches the expression above. Further, you can alter the behavior of the flow rate by selecting an individual integration order for the flow rate variable. To create a discrete flow the flow rate must use a zero order integration setting (available on the Integration tab in the variable's Properties). The difference between the two settings Zero Order and Zero Order Immediate is shown in the expressions below, where L is the level and F the controlling flow rate.

Lt+∆t = Lt + Ft // Zero Order Lt+∆t = Lt + Ft+∆t // Zero Order Immediate

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

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.

About Logical Flows

What is a Logical Flow?

At first, a flow of logical values might be hard to imagine. But if you consider states that have only two possible values, they do make sense. If, say, a worker's union is negotiating the conditions and terms for their members and the negotiation is broken, new negotiations will normally not start again for a while. New negotiations will not be tried again until the conditions have changed and the parts agree to try again. In the meantime, the worker's union might go on strike for a while, or the employers might try a forced lockout. This state might be modeled using a logical flow, where the state is identified as Negotiations Failed. When the negotiations are broken, the state becomes TRUE, and will remain TRUE until the conditions are changed, and thereby causing the state to become FALSE again.

Logical flows differ from other flows in several ways. First of all, the flow rate controlling the flow must use Zero Order or Zero Order Immediate integration settings. Second, all the flows that are connected to a logical level must be logical flows. Third, since logical levels can have only two values, they don't really conserve what flows in and out of them. They are more similar to switches being turned on and off.

A logical flow can be expressed as:

Lt+∆t = Lt ¬Ot It

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

The Behavior of a Logical Level-and-Flow Structure

The illustration below shows a model structure containing a logical level State and two logical flows In and Out . In flows into State, while Out flows out. Both the flows are logical flows using zero order integration.

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.

Flow Function Examples

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

If you edit these flow definitions, the comment will disappear.

All the examples below assume that the timestep of the simulation is 1da (1 day). Also, the examples can be modeled without adding ranges or units to the simulation project. Simply create a new simulation project, create the examples, and run them.

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'}).

Example #1: dt*Rate

This example shows a standard flow definition, where a scalar flow rate controls a flow into a scalar level.

Int Outt Statet Statet+∆t = Statet ¬Outt Int

1 TRUE TRUE TRUE TRUE

2 FALSE TRUE TRUE FALSE

3 TRUE TRUE FALSE TRUE

4 FALSE TRUE FALSE FALSE

5 TRUE FALSE TRUE TRUE

6 FALSE FALSE TRUE TRUE

7 TRUE FALSE FALSE TRUE

8 FALSE FALSE FALSE FALSE

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

Example #2: dt*Rate

This example shows a standard flow definition, where an array flow rate controls a flow into a level with equal dimensions.

aux Rate = {1,2,3}<<1/da>> dim Rate = 1..3 level Level = {0,0,0} dim Level = 1..3 flow Level = dt*Rate

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

1/2/2001 1

1/3/2001 2

1/4/2001 3

1/5/2001 4

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}

Example #3: dt*COLLECT(Rate)

This example shows a flow definition, where an array flow rate controls a flow into a scalar level.

aux Rate = {1,2,3}<<1/da>> dim Rate = 1..3 level Level = 0 flow Level = dt*COLLECT(Rate)

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

Example #4: dt*COLLECT(Rate)

This example shows a flow definition, where an array flow rate controls a flow into a level with one dimensionless.

aux Rate = {{1,2},{3,4}}<<1/da>> dim Rate = 1..2,1..2 level Level = {0,0} dim Level = 1..2 flow Level = dt*COLLECT(Rate)

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

1/2/2001 6

1/3/2001 12

1/4/2001 18

1/5/2001 24

Time Level

1/1/2001 {0,0}

1/2/2001 {3,7}

Example #5: dt*COLLECTFRONT(Rate)

This example shows a flow definition, where an array flow rate controls a flow into a level with one dimensionless. It is the first dimension that differs.

aux Rate = {{1,2},{3,4},{5,6}}<<1/da>> dim Rate = 1..3,1..2 level Level = {0,0} dim Level = 1..2 flow Level = dt*COLLECTFRONT(Rate)

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

Example #6: dt*DISTRIBUTE(Rate)

This example shows a flow definition, where an flow rate controls a flow into a level with more dimensions.

aux Rate = {9,18}<<1/da>> dim Rate=1..2 level Level = {{0,0,0},{0,0,0}} dim Level = 1..2,1..3 flow Level = dt*DISTRIBUTE(Rate)

1/3/2001 {6,14}

1/4/2001 {9,21}

1/5/2001 {12,28}

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}

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

Example #7: dt*DISTRIBUTETOFRONT(Rate)

This example shows a flow definition, where an array flow rate controls a flow into an array level with more dimensions. The dimensions of the flow rate and the level must be equal except from one dimension.

aux Rate = {10,20,30}<<1/da>> dim Rate=1..3 level Level = {{0,0,0},{0,0,0}} dim Level = 1..2,1..3 flow Level = dt*DISTRIBUTETOFRONT(Rate)

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

Example #8: dt*DISTRIBUTE(COLLECTALL(Rate))

This example shows a flow definition, where an array flow rate controls a flow into a level with

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}}

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}}

different dimensions.

aux Rate = {15,20,45}<<1/da>> dim Rate=1..3 level Level = {{0,0},{0,0},{0,0},{0,0}} dim Level = 1..4,1..2 flow Level = dt*DISTRIBUTE(COLLECTALL((Rate))

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.

Example #9: dt*PREFIXZERO(Rate)

This example shows a flow definition, where an array flow rate controls a flow into a level with one element more in one dimension.

aux Rate = {1,2,3}<<1/da>> dim Rate=1..3 level Level = {0,0,0,0} dim Level = 1..4 flow Level = dt*PREFIXZERO(Rate)

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},{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}}

Time Level

1/1/2001 {0,0,0,0}

1/2/2001 {0,1,2,3}

{0,2,4,6}

Example #10: dt*SUFFIXZERO(Rate)

This example shows a flow definition, where an array flow rate controls a flow into a level with one element more in one dimension.

aux Rate = {1,2,3}<<1/da>> dim Rate=1..3 level Level = {0,0,0,0} dim Level = 1..4 flow Level = dt*SUFFIXZERO(Rate)

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.

Example #11: dt*FILLINZEROES(Rate)

This example shows a flow definition, where an array flow rate controls a flow into a level with several elements more in one or more dimensions.

aux Rate = {{1,2},{3,4}}<<1/da>> dim Rate=1..2,1..2 level Level = {{0,0,0},{0,0,0},{0,0,0}} dim Level = 1..3,1..3 flow Level = dt*FILLINZEROES(Rate)

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.

1/3/2001

1/4/2001 {0,3,6,9}

1/5/2001 {0,4,8,12}

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}

Time Level

Example #12: Pipeline Delay

This example shows how to create a pipeline delay using an array level with three different flows attached to it. The number of elements in the level decides the delay time.

aux Input = 1<<1/da>> dim Input=1..1 aux 'In Transit' = FOR(i=1..9 | Container[i]*1<<1/da>>) dim 'In Transit' = 1..9 aux Output = Container[10] dim Output = 10..10 level Container = 0 dim Container = 1..10 flow Container = + dt*FILLINZEROES(Input) - dt*SUFFIXZERO('In Transit') + dt*PREFIXZERO('In Transit') - dt*FILLINZEROES(Output)

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.

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}}

Time Input Container 'In Transit' Output

1/1/2001 {1}da^-1 {0,0,0,0,0,0,0,0,0,0} {0,0,0,0,0,0,0,0,0}da^-1 {0}da^-1

1/2/2001 {1}da^-1 {1,0,0,0,0,0,0,0,0,0} {0,0,0,0,0,0,0,0,0}da^-1 {0}da^-1

About Circular Definitions

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

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

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.

About the Function Wizard.

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.

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.

unit m = __METER // Added in Global Units unit mm = 0.001m // Added in Global Units Length = 0.00124 m = 0.00 m Length = 1.24 mm = 1.24 mm

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.

Adding Comments to Definitions

To add comments directly in your definitions: 1. Select the definition field where you wish to add a note. 2. Position the cursor where you want to add the note. 3. Add the comment(s) enclosed by '//' (two division signs). If the comment occurs at the end of the

line, the succeeding '//' can be omitted.

The examples below illustrate how you can use comments in your definition equations. (Just copy and paste the examples into the Definition box in the Definition property page of the variable.)

Income // The income from sales - Expenses // The expenses generated from sales activity

RANDOM() // Amplitude // * SINWAVE(1,20<<da>>) // Wave //

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!

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.

Define a Variable in the Name Box

You can enter a variable definition in the name 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.

1. Click the name symbol or the variable itself to select it. 2. Type an equal sign. The current definition equation (if any) appears in the name box. You can

type the new definition equation directly:

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.

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.

Change Variable Type

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!

Define Flow Equations for a Level

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.

Note! Automatically created flow definitions are succeeded by a comment: '//Automatic'

To edit the automatically created flow definitions: 1. Double-click the level that you wish to change, or select it and click Properties. 2. Click the Flows tab on the Definition tab. 3. Select the flow definition you wish to edit. 4. Click once inside the flow definition to make it editable. 5. Enter the new flow definition, and end it by hitting Enter. 6. Click OK to save the changes, or click Apply to save the changes without closing the dialog box.

or 1. Open the Details Window (or the Equations View). 2. Locate the level whose flow definition you wish to edit.

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

Formatting Variable Definitions

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

Insert a Function in a Definition

There are two ways of inserting a function to your definition. 1. Double-click the variable, or select it and click Properties. 2. On the Definition property page, put your cursor in the Definition text box. 3. Select Functions in the multi-function list at the bottom of the property page. All available

functions are listed. 4. Double-click a function to insert it in the definition expression.

or

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.

Insert Range Name for a Dimension

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.

Insert Unit Name

To insert a unit of measure that has already been defined: 1. On the Definition Property page, select Units in the multi-function box. All units that are defined

in the project, both global and local units, will be listed. 2. Double-click a unit to insert it in the previously active box.

Insert Variable Name in a Definition

To insert variable names into the definition expression: 1. On the Definition Property page, select All Variables or Linked Variables in the multi-function

box. 2. From the list of variables that appears, double-click the name of the variable you want to include

in the definition expression.

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

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.

Set Unit of Measurement

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.

To automatically detect the unit of measurement: 1. Select one or more variables. 2. Click Properties and click the Definition tab. 3. Select Auto for Unit. 4. Click OK to save the changes, or click Apply to save the changes without exiting the property

page.

To manually define the unit of measurement: 1. Select one or more variables. 2. Click Properties and click the Definition tab. 3. Type or select the unit for the variable in Unit. Double-click a unit in the list at the bottom of the

property page to insert it into the expression. 4. Click OK to save the changes, or click Apply to save the changes without exiting the property

page.

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.

Set Data Type for a Variable

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!

Insert a Function Expression with the Function Wizard

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.

View the Current Value of a Variable

There are several ways of viewing the current value of a Variable: ! Pop-up: Point to a variable in the diagram. After a short delay, the value of the variable will pop-

up similar to a tool tip. The label will disappear when you move the mouse pointer away from the variable.

! Auto report: Right-click the variable and select Show Auto Report and select an auto report type on the shortcut menu. An auto report will be added to the diagram. This will, at all times, show the current value of the variable.

! Powersim control: Insert a data presentation control, such as the table or time series control, and define the variable as a parameter.

! Definition Property Page: Double-click the variable in the diagram, and view the value in the value field below the Definition box in the Definition property page.

! Definition Property Page: You can view the value of a variable that is part of another variable's definition simply by pointing to its name in the definition. The value will appear in a tool tip:

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

Write Documentation for a Variable

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.

Customize the Appearance of Definitions

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.

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) ! Mixed case (ex: DelayPPL) ! Lower case (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.

You can customize the appearance of the definitions.

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

Parent, Child , and Public Child variables

A hierarchical model resembles the structure of a folder structure on your computer. Each variable represents a node in the structure, and each variable can in turn have child variables. When referring to a variable on another level - say, when referring to a variable that is the child of another variable - the relative path to this variable must be used. Apart from this, variable definitions are not affected.

Any variable in Studio can contain child variables. All sibling variables can freely access each other, and a parent variable can access all its child variables. Access to variables outside the parent variable or child variables within other variables are restricted.

Child variables of levels, auxiliaries, and constants can freely access all their parent's sibling variables (all variables one level up in the hierarchy). However, only the parent variable can access child variables. Thus, child variables in variables of these types can only be used to create internal models that define the value of the parent variable itself.

Child variables of submodels, on the other hand, can be defined as public. This allows them to access or be accessed by any sibling variable of their parent, as well as by any public child variable of their sibling submodels. Hence, public variables of a submodel constitute an interface for the submodel.

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.

Creating Submodels from Components

Components, from either the current simulation project or from an external file, can be copied into your current simulation model as a submodel. In this process, all variables that have a transfer direction defined in the component, will become public when the new submodel is created. This makes it easy to create an interface to your component, and simplify the process of connecting your submodel to the main model (or to the other submodels of your simulation hierarchy).

Private and Public Variables

Public Variables in Submodels

When you create hierarchical models using the submodel variable type, you can allow variables to be Public. A public variable in a submodel is allowed to access variables on the parents level, and it can also be accessed from outside the submodel. Variables that are not public, are referred to as private variables, since they can only be accessed from within the submodel itself. All variables are private by default.

The figure below illustrates how public and private variables relate to each other in a submodel.

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.

By defining both L and X as public variables, all the definitions in the model becomes valid.

Child Variables inside Auxiliaries, Constants, and Levels

When using child variables inside auxiliaries, constants, or levels, the child variables can not be accessed from outside the parent variable itself. However, these child variables can freely access any variable above them in the hierarchy. The simple example below illustrates this.

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.

The Relationship between Public Variables and Connection

Studio allows you to create components that can later be copied directly into a model as a submodel. By defining a Connection (Transfer Direction) for the variable, it will automatically become a public variable in the resulting submodel. The figure below shows how a component named Due Payment can be modeled. The variable Amount defines the amount to base the calculation on, and is defined with a transfer direction of in. Likewise, the variable Due Payment is the output from the component, and is defined with a transfer direction of Out.

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.

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!

Referring to variables on the same level

When you define variables on the same level of a model — referred to as sibling variables — you use the variable name directly. The syntax is:

<Variable Name> // Refers to the variable named Variable Name // on the same level in the hierarchy

Consider the example below, where the submodel M1 contains two child variables. The simple model and its definitions are shown below.

A and X are both child variables of the model variable M1.

We want to define A as 10 and X as 2*A. In this simple case, the definitions will look like:

const A = 10 aux X = 2*A

Referring to variables on a higher level

You can also define a child variable of a submodel by referring to variables on its parent's level. In this case, the referring child variable must be marked as public if the parent variable is a submodel. To refer to a variable on the parent's level, you use the syntax shown below.

Parent~<Variable Name> // Refers to the variable named 'Variable Name' // on the level above in the hierarchy

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

Referring to a variable on a lower level

You can refer to a variable at a lower level of the model. You must make sure, however, that the variable you wish to refer to is defined as Public. This is indicated in the Equations View by a green dot on the variable entry. When the variable is public, it is accessible by and can also itself access variables above it in the hierarchy. The syntax to access a variable lower in the hierarchy is:

<Variable Name>.<Child Variable Name>

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

Referring to variables at different levels of the hierarchy

The basic syntax has been discussed above. But to illustrate how the syntax can be used in a more advanced manner, consider the example below. Notice that all the child variables have been made public to allow other variables anywhere in the hierarchy to access them (otherwise only variables below them in the hierarchy would be allowed to refer to them).

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.

Monitor the Flows of a 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.

Referring variable

Referred variables

A C F H K

B A M1.C Unavailable M3.H Unavailable

D Parent~A C M2.F Parent~M3.H Unavailable

G Unavailable Parent~C F Unavailable Unavailable

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

To Enable Flow Monitoring 1. Right-click the level you wish to monitor flows for, and select Properties on the shortcut

menu. 2. Click the Advanced tab. 3. Select the flow types you wish to monitor under Monitored Flows. 4. Click Apply to save the changes, or OK to save the changes and close the dialog box.

Hierarchical Models: Examples

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.

const Initial = ... // This is the initial content of the conveyor. const 'Delay Time' = ... // This is the time it takes it takes for the input // to travel through the conveyor aux Output = DELAYPPL(Conveyor.inflows, 'Delay Time', Initial/'Delay Time')

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.

The conveyor submodel in the main model diagram.

The definitions of the variables Stock, Demand, and Warehouse are not relevant to this discussion, so we will leave them out. The definition of Output is already given in the submodel, and we will not change it (changing it will change the behavior of the submodel). However, we need to define Input as the maximum of the Demand and the available Stock.

aux Input = MAX(Stock * TIMESTEP, Demand)

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.

Array Sort Module

The discussion about the VBFUNCTION in Powersim contains an algorithm for sorting an array, processing it, and then sort it back to its original order. This model structure is very suitable for submodel implementation. The model could look something like this:

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.

The submodel used in a parent diagram. None of the public auxiliaries are included in the diagram,

hiding the implementation of the submodels completely.

A Generic Account Submodel

Similar to the conveyor submodel above, we can easily create a submodel that represents an account. By specifying the opening balance, interest rate, and the interest period, the submodel can be used as an account level. The account will automatically calculate and add the interest to the account, and you can add as many inflows and outflows that you wish to and from the submodel.

The submodel itself is shown below.

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.

const 'Opening Balance' = ... // The opening balance of the account. // Example: 1000<<USD>> const 'Interest Rate' = ... // The interest rate to be used. // Example: 10<<%/yr>> const 'Discount Period' = ... // The period for when interest is added to // the balance of the account. level Balance = 'Opening Balance' aux 'Running Interest' = Balance*Rate level 'Accumulated Interest' = 0 * 'Opening Balance' // This is defined as 0, but is multiplied with // 'Opening Balance' to ensure that the correct // currency is used for the variable. aux 'Due Interest' = IF( TIMECYCLE( STARTTIME, Period), 'Accumulated Interest', 0 * 'Accumulated Interest')

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

A Note on the Account Example

If you wish, you can define the three child variables Interest Rate, Discount Period, and Opening Balance within the submodel directly, instead of including them in the parent diagram. You can also create input variables on the parent's level, and then link these input variables directly to the submodel, as shown in the conveyor example.

You may also enter the initial definition directly in the Balance level, if you define it internally in the submodel. You can also create an input variable on the parent's level, and draw a link from this variable and directly to the submodel, and define the initial value of the level that way. However, if you include the Balance level in the parent diagram, the flows must flow to and from the included level rather than to and from the submodel itself. This is illustrated below.

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.

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.

Create a Variable in the Equations View

1. Right-click anywhere in the white space. 2. Select the variable type you want to create on the shortcut menu.

A new variable of the selected type is created in the Equations View.

You can also create child variable for a variable in the Equations View: 1. Right-click the variable for you wish to add a child variable. 2. Select the variable type of the child variable you wish to create on the shortcut menu.

A new child variable is added to the selected variable.

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.

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

Create a Flow in the Equations View

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:

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.

Reverse a Flow in the Equations View

1. Expand the subitems under the level for which you wish to reverse a flow. 2. Right-click the flow you wish to reverse. 3. Select Flip Flow.

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.

Change Variable Type in the Equations View

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.

Delete a Variable in the Equations View

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!

Note! If the variable you delete contains child variables, these child variables will also be deleted.

Work with Ranges and Index Variables

Ranges and dimensions

Ranges are interval definitions that can be used to specify dimensions for array variables. Ranges can be specified in two different ways. You can create unnamed ranges by simply using the range definition directly. This is what Studio itself does when it automatically creates dimension definitions. Alternatively, if you use a range definition many different places in your model, you can create a range with a unique range name. You are then allowed to refer to the given range name when you use the range definition.

Creating named ranges makes it easier for you to ensure that all your dimension definitions are identical throughout your model. Named ranges also make it easier for you to change the dimensions across your project. By changing the definition of your range, the new dimension is instantly recognized by all your array variables using the same range definition.

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.

Global and Local Ranges and Index Variables

There are two different views in which you can create and define ranges and index variables. Global ranges are available to all the components in a simulation catalog. You can also define ranges locally for each component. A local range will, as the name implies, only be available to the component in which it is defined. To refer to a local range, you should prefix it with a '.' (punctuation mark).

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

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!

About Index Variables

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.

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:

range Regions = North, East, South, West index 'Graph Selector' = Regions

Index variable used in controls

The range Regions can be used for many purposes, but let's consider an example where it is used to identify the sales in different regions of, say, a country. The sales for each region is shown in a time graph. There are three ways in which to achieve this. First, you can create one time graph for each region, where you select one array element as the parameter in each time graph. Second, you can create one time graph where all four elements are parameters. Third, you can create one time graph where the Graph Selector is the parameter for the time graph. By connecting the index variable to a switch control, you can control its value and thereby which element to view in the time graph. The illustration below shows how the simulation can be presented in two ways, either as a time graph with all the elements displayed simultaneously, or by using the index variable and a switch control.

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

Index variable used in FOR function

The index variable can also be utilized when the FOR function is used to define variables. In such a case, the index variable is used in the same way as an internal index variable would normally be. However, since a globally defined index variable can be either an enumerated or a numerical subrange, you must use the NUMERICAL function if you want to use the value of the index variable in the definition.

The simple example below shows how you can use a globally defined index variable within the FOR function.

aux Auxiliary_1 = FOR('Graph Selector' | NUMERICAL('Graph Selector')) = {1, 2, 3, 4}

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.

Add a Local Range

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.

Create an Index Variable

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 Index Variable on the shortcut menu.

3. Hit F2 and enter a name for the new range. 4. Double-click the index variable to define it on the Definition property page.

or Select the Definition field in the multi-column view, hit F2 and enter the definition. Hit Enter when you've finished typing.

Note! You can also create a local index variable in the same way in the Local Ranges view.

Define an Enumerated Range

An enumerated range specifies a series of named elements that is used as indexes rather but than

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.

Deleting and sorting range elements

By right-clicking any range element in the list you can ! Delete: Select Delete to delete the range element; ! Reorder: Select Move Up or Move Down to change the order of the range elements.

Rename Range Elements

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.

Define an Enumerated Subrange

An enumerated subrange specifies a continuous interval of enumeration elements from an enumerated range to use as index arrays. The subranges North..South and Adult..Old are examples of enumerated subranges.

Note! Before you can create an enumerated subrange you must define an enumeration range to base it on.

To define an enumerated subrange: 1. Double-click the range to define, or right-click it and select Properties on the shortcut menu.

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.

Define a Numerical Subrange

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.

To define a numerical subrange: 1. Double-click the range to define, or right-click it and select Properties on the shortcut menu. 2. Select the Subrange option. 3. Select <numerical> in the Enumeration box. (Select an enumerated range to create an

enumerated subrange.) 4. Enter the first element of the subrange in the First box. You can either enter the number directly

or use the spin buttons. 5. Enter the last element of the subrange in the Last box. You can either enter the number directly or

use the spin buttons. 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.

Specify a Global Range for a Variable

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.

Tip! After selecting the Dimensions box, the multi-functional list on the bottom of the property page will show all the defined named ranges.

Specify a Global Range for a Variable

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.

Explicitly Select a Range for a Variable

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.

Delete a Global Range or Index Variable

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. Select the range 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 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.

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.

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.

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

Summary Types and Discrete Variables

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.

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.

Average is Undefined for Zero Order Variables

The Average summary type is not available to Zero Order parameters. The reason for this is the nature of zero order flows in the simulation engine. The engine calculates one transaction per timestep, so even if the value of the transaction is zero, it still counts as a transaction. Hence, the result of the average would be dependent on the summary period, since the average would be calculated as the sum of all transactions divided by the number of timesteps within the summary period.

This can be illustrated by considering two examples of loan payments. In both cases, we have a timestep of one month and a summary period of three months. In the first example, a monthly instalment of $100 is used, while in the second example, the instalment is $300 every third month. There are three timesteps in each summary period, so the average payment per transaction would be $100 in the first case, which is correct. However, in the second case, there is still three timesteps, but only one transaction. The average becomes $100 per transaction, while it should have been $300. However, if we change the summary period to four months, the values will change. The table below illustrates this behavior.

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.

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.

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

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.

Why Use 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.

A scalar model and an array model with four layers.

Arrays may be one-dimensional, also called vectors, or multi-dimensional, also called matrices. Array variables may be used in many different ways, which will be described below. Arrays make the flow diagram smaller and more presentable, while reducing the amount of work necessary to create and maintain a model.

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.

Dimensions and Ranges

An array's dimensions specifies the number of elements and the structure of these elements. An array with the dimension 1..3 has three elements, structured as a vector. An array with the dimension 1..3;1..3 has two dimensions. Altogether, the array will have 9 elements. They are structured in a 3x3 matrix (table).

Global and Local Ranges offer the capability to predefine such array dimensions as named ranges. When you later specify array variables, you can refer to the named ranges rather than the numerical dimensions (actually numerical subranges) used above. You can define three types of ranges: ! Enumeration Ranges: An enumeration range contains a set of (labeled) elements. Thus, we can

create the range Regions defined as North, East, South, West. And for the example above, we could create the enumeration range 'Age Groups', defined as Young, Adult, Old.

! Enumeration Subranges: An enumeration subrange is a subrange of a enumeration range. The subranges North..South and Young..Adult will be subranges of the enumeration ranges described above.

! Numerical Subranges: An numerical subrange is similar to enumeration subranges, with the exception that it contains numerical value instead of named elements. A numerical subrange is a subrange of all integers rather than an enumeration range. The ranges 1..4, -3..3, and 10..20 are all examples of numerical subranges.

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.

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.

Create Queues Using Arrays

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.

How to model a queue in Studio.

The equations for the model are:

aux Input = <The Input> * 1<<1/da>> dim Input=1..1 aux 'In Transit' = FOR(i=1..9 | Container[i]*1<<1/da>>) dim 'In Transit' = 1..9 aux Output = Container[10] dim Output = 10..10 level Container = 0

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)

giving the automatic dimension of '1..N'.

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

A An exact position within a dimension. You can include one integer per dimension. Examples: Array[1], Array[1,1], Array[1,1,1], 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.

Automatically Detect Dimensions

You can create arrays in several ways that will make Studio automatically detect the dimension of the variable. The easiest way, which also illustrates how arrays are defined in the most basic way, is by listing the array elements separated by list separators, and using '{' and '}' to enclose the dimension. Thus, an array with one dimension containing four elements, can easily be defined using definition below. Studio will automatically detect the dimension.

aux Variable = {1,2,3,4} dim Variable = 1..4 // Automatically detected

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

A..B

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, 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.).

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.

aux Variable = {{1,2},{3,4},{5,6}} dim Variable = 1..3,1..2 // Automatically detected

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.

Assign Dimensions Explicitly

Sometimes the expression that defines each element is identical for all the elements in the array. In this case you can enter a "scalar" definition, and specify the variable's dimension explicitly, as is shown below. The dimension is entered in the Dimensions field for the variable.

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.

aux Variable_1 = {{7,10},{19,86}} dim Variable_1 = 3..4,7..8 aux Variable_2 = FOR(i=3..4,j=7..8 | Variable_1[i,j]*2) dim Variable_2 = 3..4,7..8 result Variable_2 = {{14,20},{38,172}}

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.

Create Arrays Using Ranges and Subranges

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.

range Regions = north,south,east,west // Added to Global Ranges aux Variable = 0 dim Variable = Regions // Manually assigned

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.

range Regions = north,south,east,west // Added to Global Ranges range 'Age Groups' = .youth,.adult,.old // Added to Local Ranges aux Variable = 0 dim Variable = Regions, .'Age Groups' // Manually assigned result Variable = {{0,0,0},{0,0,0},{0,0,0},{0,0,0}}

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.

Build Arrays Element by Element

The syntax for defining arrays element by element, is

{Element1, Element2, Element3, ... , ElementN}

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.

Build Arrays Using the FOR function

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

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},{3,4}}

{{5,6},{7,8}}

{{{1,2},{3,4}},{{5,6},{7,8}}}

1..2,1..2,1..2

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:

range Regions = north,east,south,west // Added to Global Ranges range 'Age Groups' = .infants, .youth, .adults, .old' // Added to Local Ranges

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}

Expression Result Dimension

FOR(1..3 | 0) {0,0,0} 1..3

FOR(i=4..8 | i) {4,5,6,7,8} 4..8

FOR(i=Regions | i*2) {2,4,6,8,10} n..w

FOR(i=.'Age Groups' | NUMERICAL(i)*100)

{100, 200, 300, 400} .infants .. .old

FOR(i=1..2,j=3..4 | i*j) {{3,4},{6,8} 1..2,3..4

FOR(i=1..3,j=1..3 | IF(i<=j,1,2))

{{1,1,1},{2,1,1},{2,2,1}}

1..3,1..3

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.

aux Variable_1 = CONCAT({1,2},{3,4,5,6},{7,8,9}) dim Variable_1 = 1..9 // Automatically detected result Varilable_1 = {1,2,3,4,5,6,7,8,9} aux Variable_2 = CONCAT(FOR(i=1..3, j=1..2 | i-j), FOR(i=1..3, j=3..4 | i+j)) dim Variable_2 = 1..3,1..4 result Variable_2 = {{0,-1,4,5},{1,0,5,6},{2,1,6,7}}

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.

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:

aux Array = {{48,39,0,42,94}, {69,57,19,51,18}, {8,15,35,63,68}, {97,1,67,45,11}} dim Array = 1..4,1..5 // Automatically detected

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.

Note! The two last examples shows how an array can be redimensioned in Studio. Redimensioning affects the dimensions of the resulting array.

Index Arrays Using INDEX Function

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.

aux Array = {{3,2,5,3},{6,3,4,1}} aux A = 2 type A = Integer aux B = 3 type B = Real aux Result1 = Array[INDEX(A)] = {6,3,4,1} aux Result2 = Array[INDEX(A),INDEX(INTEGER(B))] = 4

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

Definition: Select an expression...

Result: <--Result-->

Dimension: <--Dimensions-->

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.

aux Array = {1,2,3,4,5,6,7,8,9,10} aux Result = FOR(i=1..10 | IF(i<10, Array[INDEX(i-1)], A[10]))

Use Basic Variables as Index Variables

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.

aux B = LOOKUP(A,1) = {4,1,5} dim B = 1..3 aux C = LOOKUP(A,3) = {2,6,7} dim C = 1..3 aux D = LOOKUP(A,1,3) = 5 aux E = LOOKUP(A,3,2) = 6

Index Arrays Using Ranges and Subranges

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

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.

range Regions = north,east,south,west // Added to Global Ranges aux Array = {4,1,2,9} dim Array = Regions aux 'Result 1' = Array[north] = 4 aux 'Result 2' = Array[east..south] = {1,2} aux 'Result 3' = Array[south..?] = {2,9} aux 'Result 4' = Array[Regions] = {4,1,2,9}

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.

range Regions = north,east,south,west // Added to Global Ranges aux 'Array A' = {34,18,62,40} dim 'Array A' = Regions aux 'Array B' = {42,13,67,20} dim 'Array B' = 1..4 aux 'Result 1' = 'Array A'[1..?:2] = 18 aux 'Result 2' = 'Array A'[?..4:?..4] = {34,18,62,40} aux 'Result 2b' = REDIM(1..4 | 'Array A') = {34,18,62,40} aux 'Result 3' = CONCAT('Array A'[1..?:1..?],'Array B'[5..?:5..?] = {34,18,62,40,42,13,67,20} dim 'Result 3' = 1..8

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}}

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

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.

Using Summary Types in Controls

Summary types are available in the Time Graph and Time Table controls. The summary period for each of these will default to the Major Interval specified under Simulation Settings. You can change the summary period for each control individually later.

Using Field Codes in Controls

You can use field codes to automate the layout of controls. There are several field codes available, including variable names and units, range names, and time labels. The field codes can be used to insert text into control titles, axis titles, graph names, etc. When you are using field codes, the names presented in controls will change if you change the name of the corresponding variable, saving you a great deal of time when creating simulation presentations.

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!

Insert a Control in your Diagram

1. Click the button of the control you would like to insert in your diagram. The controls currently available are: Time Graph, Time Table, Chart, Table, Gauge, Slider, and

Switch. 2. Click inside the diagram, and drag the control to the desired size. 3. Double-click the control to define its appearance, or right-click it, and select Properties on the

shortcut menu.

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

A control can be moved in two ways. 1. Select the control and drag it to its new position while holding down the mouse button.

Or 1. Double-click the control, or right-click it and select Properties on the shortcut menu. 2. Select the Symbol tab in the property dialog box. 3. Change the values of the Horizontal and Vertical fields to the new position coordinates.

Use Index Variables in Controls

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

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.

Range Region = North, East, South, West // Defined in Global Ranges Range Products = Bolts, Washers, Nuts // Defined in Global Ranges

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:

Index Variable IV_Region = Region // Defined in Global Ranges

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:

Index Variable IV_Product = Products // Defined in Global Ranges

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.

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.

Toggle Between Design and User Mode

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.

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.

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.

Add Active Run Parameters to a Control

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

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.

Add Reference Data Parameters to a 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.

Add Simulation Control Parameters to a Control

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.

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.

To add a simulation control 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 Simulation Control node of the Value Source list. 4. Select the control parameter 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.

Add Index Variable Parameters to a Control

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.

Add Parameters with Summary Types

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

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

Adjust the Scale of a Parameter

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.

Remove Parameters from a Control

To remove parameters from a control: 1. Double-click the control that you wish to change, or right-click it and select Properties on the

shortcut menu. 2. Select the Parameters tab in the property dialog box. 3. Select the parameter(-s) to be removed in the list on the right side, and click <<Remove to

remove them from the parameter list of the control. 4. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

If the control you are working with is a time graph, time table, or chart control, you can also remove the parameter by deleting the corresponding graph or column in the control: 1. Right-click the corresponding column or graph of the parameter you wish to remove, and select

Delete on the shortcut menu.

Hide or Show Parameters in User Mode

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.

Change the Input Mode of a Control

There are four input modes available for controls: ! Never: The control will never accept input. ! Initially: The control will only accept input at the start of the simulation. ! When stopped: The control will only accept input when the simulation is stopped. ! Always: The control will always accept input.

Note! You can only set new values for constants of levels. Auxiliaries will never accept input from controls.

To change the input mode of a control: 1. Double-click the control that you wish to change, or click Properties. 2. Select the General tab in the Properties dialog box. 3. Select the input mode under Allow Input. 4. Select the Stop on Input option to make the simulation automatically stop whenever the control

receives input. 5. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

If the parameter selected is an auxiliary, the control will always be read only, and the settings of the options above will have no effect.

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.

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

The Value Axis and Parameters with Different Units

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.

Parameters with compatible (or equal) units

When the control contains several parameters with equal or compatible units, the value axis will choose the unit of the topmost parameter and use that as the unit for the axis. The unit of the axis is shown above the axis (you can customize the position manually, if you like).

When the parameters shown in the control have equal or compatible units, the unit of the topmost

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 Labels

Displays the unit with the tick labels of the value axis.

parameter is chosen for the value axis. The unit name of the value axis is displayed above the value axis.

Parameters with incompatible units

When the control contains several parameters with incompatible units, the unit of each parameter is shown in the legend. The numerical values are plotted against 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

A control can be resized in different ways. 1. Select the control, and use the resize handles that appear on the outline of the control.

Or 1. Double-click the control, or right-click it and select Properties on the shortcut menu. 2. Select the Symbol tab in the property dialog box. 3. Change the values of the Width and Height fields to the size you wish. 4. Click OK to save the changes, or click Apply to apply the changes without closing the dialog

box.

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

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.

Change the Position of an Axis

To change the position of an axis (time or value): 1. Right-click the axis you want to change, and select Axis Position on the shortcut menu. 2. Select the position from the shortcut menu that appears.

Tip! You can also change the position of the tick labels for the axis, on the axis' property page when clicking Properties.

Change the Orientation of Texts in Controls

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

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.

Note! If the label is empty, it will be automatically hidden.

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.

Change the Scaling of the Value Axis

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.

Customize the Appearance of a Control

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.

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.

Change Position of Unit Label

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.

Show and Format the Title

To show the title (if it is hidden): 1. Right-click the control, and select Show Title on the shortcut menu. 2. Type a title for your control.

Note! If the title is empty, it will automatically be hidden.

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.

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.

Object Property Switch Description Parameter Name - Display the full name of the parameter. If there are more

parameters available for the given text and they have different names, then the field code will display an empty string instead.

I Display only the part of the parameter's name that are different from the other displayed parameter names. This switch is only available in Legends and Parameter Titles.

Unit - Displays the unit of the parameter. I Displays the part of the unit of the parameter that are different

from the other displayed parameters. This switch is only available in Legends and Parameter Titles.

Range Name - Displays the name of the range. Time Label - Displays a time label

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.

Text Available Used in Default Description

Title

Parameter.Name Parameter.Unit Time.Label

Empty The title can be set up to display the time label, or the name or unit of the parameter(s) shown in the control. In the Chart control, it can also display the name of the parameters' range.

Parameter.Name Parameter.Unit Range.Name Time.Label

Legend

Parameter.Name Parameter.Unit

{Parameter.Name\I}{" ("!Parameter.Unit\I!")"}

By using the optional "\I" switch, you can shorten the 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 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.

Time Axis.Label

Parameter.Name Parameter.Unit Time.Label

{Time.Label} The time axis label can display the parameter name (if there is only one parameter available), the parameters' unit (if there is only one unit available), and the time label.

Element Axis.Label

Parameter.Name Parameter.Unit Time.Label Range.Name

{Range.Name} The element axis label can display the parameter name (if there is only one parameter available), the parameters' unit (if there is only one unit available), the time label, or the name of the range of the parameter(s).

Parameter.Name Parameter.Unit Time.Label

{Parameter.Name} The value axis label can display the parameter name (if there is only one parameter available), the parameters' unit

Field Codes and Languages

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!

Value Axis.Label

(if there is only one unit available), and the time label. NB! The property is named Gauge Display.Value Axis.Label in the Gauge control.

Time.Title

Parameter.Name Parameter.Unit Time.Label

{Time.Label} The time title (the header of the column or row containing time information) can display parameter names or units, or the time label.

Parameters[<name>].Title

Parameter.Name Parameter.Unit

{Parameter.Name\I}{" ("!Parameter.Unit\I!")"}

See description for Legend above.

Gauge Dial.Value Axis.Label

Parameter.Name Parameter.Unit

{Parameter.Name\I}{" ("!Parameter.Unit\I!")"}

See description for Legend above.

Label

Parameter.Name Parameter.Unit Time.Label

{Parameter.Name} The label can be set up to display the time label, or the name or unit of the parameter(s) shown in the control. In the Chart control, it can also display the name of the parameters' range.

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:

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

Define a Field Code

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:

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.

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 can show several types of charts: ! Line: The element points are connected by a straight line. ! Smooth Line: The line between the element points are smoothed (requires that the graph is

already shown as a line). ! Step: The element points are connected by a horizontal rather than a straight line. ! Bar: Shows the values of the elements as bars along the element 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

position 2, etc.) regardless of the dimension of the array.

Format the Graphs in the Chart Control

To format the color and line of the individual graphs: 1. Select the graph you wish to change. The cursor will change to a small square when it hovers over

a graph line. 2. Use the Format toolbar to format the line color and fill color of the graph.

You can format the graph with a pattern on the Fill property page, available when you double-click the graph or click Properties.

To change the type of the graph: 1. Right-click the graph, and select the graph type on the shortcut menu.

Tip! If a graph is filled, you can select the graph by clicking the filled area under the graph.

Change the Graph Type of a Parameter

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.

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. ! Send to Back: Sends the graph to the back of the control.

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.

Hide Parameters from the Chart

To hide a parameter from the control without deleting it: 1. Right-click the graph you wish to hide. 2. Select Hide on the shortcut menu.

or 1. Double-click the control that you wish to change, or select it and click Properties. 2. Select the Parameters tab in the Properties dialog box. 3. Select the parameter to hide in the list, and select the Visible option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

Show Hidden Parameters in the Chart Control

To show the graph of a parameter that you have previously hidden: 1. Double-click the control that you wish to change, or select it and click Properties. 2. Select the Parameters tab in the Properties dialog box. 3. Select the parameter to show in the list, and select the Visible option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

If you switch to User Mode, you can also toggle parameters on and off by right-clicking inside the control, and selecting (or deselecting) the parameter name.

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. ! Minor Horizontal Grid: The minor grid of the value axis. ! Major Horizontal Grid: The major grid of the value axis. ! Minor Vertical Grid: The minor grid of the time axis. ! Major Vertical Grid: The major grid of the time axis.

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.

Toggle on/off the Legend for the Chart

To hide or display the legend for the chart: 1. Right-click the chart you wish to change, and select Show Legend on the shortcut menu.

To hide the legend: 1. Right-click the legend, and select Hide on the shortcut menu.

You can also access the properties of the legend on the General tab when clicking Properties.

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.

aux 'Company A' = <any definition> aux 'Company B' = <any definition> aux 'Company C' = <any definition> aux 'Company D' = <any definition> aux 'Market Share' = {'Company A', 'Company B', 'Company C', 'Company D'}

The 'Market Share' variable is added to a chart control.

Use the Chart Control as an Input Object

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

simulation.

To prepare to use the chart control as an input object: 1. Insert a chart control in your diagram. 2. Drop the variable(s) on the control.

When you want to change the value of the parameter: 1. Point to the curve that you wish to change in the graph using the mouse pointer. The mouse

pointer changes to a small square with arrows in all directions to indicate that the graph accepts user input. By sweeping along the element axis, you can provide new values for all the elements in the array.

2. Drag the graph to its new shape, thereby providing input for all the elements in the array.

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.

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.

Examples of Gauge Formatting

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%

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%

Gauge Dial Properties

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.

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%

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°).

Dial and Display span

The Dial span property allows you to specify the curvature of the gauge dial. Possible values are 1 to 360.

The Display span property allows you to specify the portion of the dial that will be used to display the value of the parameter. Possible values are 1 to 360, although it cannot exceed the value of Dial span.

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.

Outer and Inner radius

The Outer and Inner radius are shown in the illustration below. The two properties allow you to control the shape and appearance of the gauge dial. Possible values are 0% to 100%.

a) Dial span. b) Display span. c) Inner radius. d) Outer radius.

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 Axis

The end of the needle touches the outer limit of the value axis.

At Axis The end of the needle touches the line of the value axis.

Inside Axis

The end of the needle touches the inner limit of the value axis.

Outside Dial

The end of the needle touches the outer line of the gauge dial.

Inside Dial

The end of the needle touches the inner line of the gauge dial.

At Dial Center

The end of the needle is placed exactly at the center of the gauge dial (at the center of 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

Various combinations of needle style and positions.

a) Triangle style, head outside dial, tail at dial center. b) Triangle style, head outside axis, tail at dial center. c) Triangle style, head at axis, tail inside dial. d) Triangle style, head inside dial, tail at dial center. e) Arrowhead style, head at axis, tail custom at 105%. d) Arrowhead style, head at axis, tail

custom at 80%.

Tip! You can hide the gauge hub if you like, by right-clicking it and selecting Hide on the shortcut menu.

Format the Gauge Dial

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.

Custom

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

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.

Format the Gauge Needle

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.

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 needle fill. 3. Click the small arrow next to Line Color, and select a color from the dropdown for the needle

line.

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.

Format the Gauge Hub

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.

Show or Hide the Gauge Hub

To hide the gauge hub: 1. Right-click the gauge hub, and select Hide 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, 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.

Rotate the Gauge Control

You can rotate the gauge control: 1. Double-click the gauge control that you wish to rotate, or right-click it and select Properties

on the shortcut menu. 2. Select the Gauge Dial tab. 3. Change the angle under Direction. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

The angle under Direction represents the direction that the gauge needle with point when in the center position. If the direction is 0, the needle will point to the right; a value of 90 will make the needle point downwards; 180 will cause the needle to point to the left; and the default value of 270 results in a gauge where the needle points upwards. This is illustrated below.

The illustration shows the gauge dial when rotated to various angles (0°, 90°, 180°, and 270°).

Use the Gauge Control as an Input Control

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.

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:

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.

Change the Orientation of the Slider Bar

To change the orientation of the slider bar: 1. Double-click the control that you wish to change, or click Properties. 2. Select the General tab in the property dialog box. 3. Specify the orientation by selecting either the Horizontal or the Vertical option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

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.

Create a Button

To create a button in a Constructor diagram: 1. Insert a Switch Control. 2. Add the parameter you wish to the control by drag-and-drop (or on the Parameters property

page). 3. Double-click the control, or select it and click Properties. 4. Select the General tab in the Properties dialog box. 5. Select Push Button under Type to create a push button. 6. Under States, you can control the values that will be set by the button. If you select the Automatic

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

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.

Create a Check Button

To create a check button in a Constructor diagram: 1. Insert a Switch Control. 2. Add the parameter you wish to the control by drag-and-drop (or on the Parameters property

page). 3. Double-click the control, or select it and click Properties. 4. Select the General tab in the Properties dialog box. 5. Select Check Button under Type to create a check button. 6. Under States, you can control the values that will be set by the button. If you select the Automatic

Value: Clear

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.

Create Radio Buttons

To create radio buttons in a Constructor diagram: 1. Insert a Switch Control. 2. Add the parameter you wish to the control by drag-and-drop (or on the Parameters property

page). 3. Double-click the control, or select it and click Properties. 4. Select the General tab in the Properties dialog box. 5. Select Radio Buttons under Type to create a set or radio buttons. 6. Under States, you can control the number of options that should be available in the group of radio

buttons, their value, and the text that will appear for each option. If you select the Automatic 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.

Select the number of options you wish to create under Count. Specify the value for each option under Value. 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.

Value: Clear Value: Clear

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

Create a List Box

To create a list box in a Constructor diagram: 1. Insert a Switch Control. 2. Add the parameter you wish to the control by drag-and-drop (or on the Parameters property

page). 3. Double-click the control, or select it and click Properties. 4. Select the General tab in the Properties dialog box. 5. Select List Box under Type to create a push button. 6. Under States, you can control the number of entries in the list, their value, and the text that will

appear for each entry. If you select the Automatic 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.

Select the number of entries you wish to create under Count. Specify the value for each entry under Value. 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.

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

Value: Val 1

FirstSecondThirdFourth

Value: Val 1

Create a Combo Box

To create a combo box in a Constructor diagram: 1. Insert a Switch Control. 2. Add the parameter you wish to the control by drag-and-drop (or on the Parameters property

page). 3. Double-click the control, or select it and click Properties. 4. Select the General tab in the Properties dialog box. 5. Select Combo Box under Type to create a combo box. 6. Select the number of entries in the combo box under States. 7. Under States, you can control the number entries, their value, and the text that will appear for

each entry. If you select the Automatic 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.

Select the number of entries you wish to create under Count. Specify the value for the entry under Value. 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.

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

Create a Static Text Object

To create a static text object in a Constructor diagram: 1. Insert a Switch Control. 2. Add the parameter you wish to the control by drag-and-drop (or on the Parameters property

page). 3. Double-click the control, or select it and click Properties. 4. Select the General tab in the Properties dialog box. 5. Select Static under Type to create a combo box. 6. Select the number of entries in the combo box under States. 7. Under States, you can control the number entries, their value, and the text that will appear for

each entry. If you select the Automatic 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.

Select the number of entries you wish to create under Count. Specify the value for the entry under Value.

First

Value: Val 1

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.

Use the Switch Control to Select Strategy

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.

Select Initial Value

You can allow the Switch Control to change the initial values of both constant auxiliaries and levels. To achieve this, simply drop the variable on the switch control, and format the control as radio buttons with two (or more) states. The two (or more) alternative values are entered under Values. When the user selects either radio button, the value is assigned to the variable. Using this approach you can allow the user to change conditions of the simulation.

Selecting between Strategies During Simulation

To achieve this effect, you need to have each strategy implemented in one auxiliary each, and an additional constant auxiliary that acts as the switch. The example below uses three different strategies for testing a model. Based on the value of a constant auxiliary, which in turn is controlled by a switch control, the variable Strategy can be either a wave, a step, or random.

The Switch variable controls the behavior of the Strategy variable.

The model is defined like this:

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

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.

Table 1: The values of the three radio buttons.

The switch control is shown below, together with a time graph showing the output from one simulation. The switch control was changed several times during the simulation.

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.

Value Text

Val 1 1 Wave

Val 2 2 Step

Val 3 3 Random

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.

Add an Array to 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

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.

Add or Insert a Column in the Table Control

To add a column below on the right side of the table control: 1. Right-click anywhere inside the tabular area of the control, and select Add Column on the

shortcut menu.

To insert a column to the right of the selected cell in the table control: 1. Right-click anywhere inside the tabular area of the control, and select Insert Column on the

shortcut menu.

Add or Insert a Row in the Table Control

To add a row at the bottom of the table: 1. Right-click anywhere inside the tabular area of the control, and select Add Row on the

shortcut menu.

To insert a row below the selected cell in the table: 1. Right-click anywhere inside the tabular area of the control, and select Insert Row on the

shortcut menu.

Display a Text in a Cell

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.

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.

Display a Variable's Name in a Cell

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.

Display a Variable's Value in a Cell

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

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.

Change the Height of Rows and Width of Columns

To change the width of a column: 1. Point to the line separating the columns you wish to resize. 2. When the resize cursor appears, click the mouse-button and hold it down while dragging the

column to its new width.

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.

To change the height of a row: 1. Point to the line separating the rows you wish to resize. 2. When the resize cursor appears, click the mouse-button and hold it down while dragging the row

to its new height.

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.

Delete a Column in the Table Control

1. Right-click the column you wish to delete, and select Delete Column on the shortcut menu.

Note! Deleting a column does not remove parameters from the control.

Delete a Row in the Table Control

1. Right-click the row you wish to delete, and select Delete Row on the shortcut menu.

Note! Deleting a row does not remove the parameters displayed in it from the control.

Use the Table Control as an Input Object

The table control allows you to input values to parameters that accept this input. This means that you

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.

To prepare to use the table control as an input object: 1. Insert a table control in your diagram. 2. Drop the variable(s) on the cell(s) where you want to display its value.

When you want to change the value of the parameter: 1. Select the cell. 2. Type the new value, or hit F2 to enter the existing value. 3. Hit Enter to send the value to the target variable.

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.

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.

Format the Graphs in the Time Graph Control

To format the individual graphs: 1. Select the graph you wish to change. The cursor will change to a small square when it hovers over

a graph line. 2. Use the Format toolbar to format the line color and fill color of the graph.

You can format the graph with a pattern on the Fill property page, available when you click double-click the graph or click Properties .

Tip! If a graph is filled, you can select the graph by clicking the filled area under the graph.

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

Property Available options Description

Placement

Automatic In intervals

Between intervals

Specify the placement of the first level tick labels relative to the tick marks. If you select In intervals, the tick label will be shown inside the interval and denote the period. If the major interval of the time axis 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.

Format

Short Medium

Long

Select the date and time format to use for the tick label. It is recommended that you try the various options to see how they work for various intervals and periods. As an example, Short will display the month number (1), Medium will display the month with three letters (Jan), while Long will display the entire month name (January).

Show static time elements

on/off Select whether time information that is common for all tick labels should be shown or not. If, say, the simulation runs for one full year, selecting this option will display the year in the tick label, while deselecting it will remove the year from the tick label.

Allow second level

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 tick labels will be shown below a range of tick labels. while deselecting it will include the common information in all the tick labels of the range.

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.

Format (second level)

Short Medium

Long

Select the data and time format to use for the second level tick labels.

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: Between intervals Format: Medium Show static time elements: On Allow second level: Off

Placement: In intervals Format: Short Show static time elements: On Allow second level: On Format (second level): Long

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.

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. ! Send to Back: Sends the graph to the back of the control.

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 using the Up and Down buttons. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

Change the Graph Type of a Parameter

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.

Hide Parameters from the Time Graph

To hide a parameter from the control without deleting it: 1. Right-click the graph you wish to hide. 2. Select Hide on the shortcut menu.

or 1. Double-click the control that you wish to change, or select it and click Properties. 2. Select the Parameters tab in the Properties dialog box. 3. Select the parameter to hide in the list, and select the Visible option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

Show Hidden Parameters in the Time Graph

To show the graph of a parameter that you have previously hidden: 1. Right-click the control and select Show or Hide Parameter on the shortcut menu. Select the

parameter you wish to show (or hide) in the submenu that appears.

or 1. Double-click the control that you wish to change, or select it and click Properties. 2. Select the Parameters tab in the Properties dialog box. 3. Select the parameter to show in the list, and select the Visible option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

Show and Export the History of a Parameter

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.

Format the Graph 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. ! Minor Horizontal Grid: The minor grid of the value axis. ! Major Horizontal Grid: The major grid of the value axis. ! Minor Vertical Grid: The minor grid of the time axis. ! Major Vertical Grid: The major grid of the time axis.

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.

Toggle on/off the Legend for the Time Graph

To hide or display the legend for the time graph: 1. Right-click the time graph you wish to change, and select Show Legend on the shortcut menu.

To hide the legend: 1. Right-click the legend, and select Hide on the shortcut menu.

You can also access the properties of the legend on the General tab when clicking Properties.

Create a Scrolling Time Graph

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.

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.

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.

Format the Time Display in the Time Table Control

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.

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

Change the Order of Parameters

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.

Change the Report Interval of the Time Table

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.

Times Options

Property Available options Description

Format

Short Medium

Long

Select the date and time format to use for the tick label. It is recommended that you try the various options to see how they work for various intervals and periods. As an example, Short will display the month number (1), Medium will display the month with three letters (Jan), while Long will display the entire month name (January).

Always show interval names

on/off Select whether to display interval names or not. If this option is selected, the time table will always display interval names, even when all the parameters are defined using the First summary type.

Show static time elements

on/off Select whether time information that is common for all tick labels should be shown or not. If, say, the simulation runs for one full year, selecting this option will display the year in the times, while deselecting it will remove the year.

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.

Change the Orientation of the Time Table

To change the orientation 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. Specify the orientation by selecting either the Horizontal or Vertical option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

Hide Parameters from the Time Table Control

To hide a parameter from the control without deleting it: 1. Double-click the control that you wish to change, or click Properties. 2. Select the Parameters tab in the Properties dialog box. 3. Select the parameter to hide in the list, and select the Visible option. 4. Click OK to save the changes, or Apply to save the changes without closing the dialog box.

Working with Risk Assessment

Why use the Risk Assessment task?

Risk Assessment helps an organization assess their potential and risk. With this tool you can easily disclose how likely best- and worst-case scenarios are. The Risk Assessment task automatically changes variable values and computes new results, to help determine the probability of obtaining the best strategy, or disclose the riskiest.

You are given the opportunity to optimize your policies, even to conflicting goals, and adjust your objectives to risk factors in your model. Studio analyzes how sensitive the results are to changes in these uncertainties, and thus discloses how vulnerable the model is.

How to use the Risk Assessment task

You can add the Risk Assessment task to any component in a simulation project, similar to a separate simulation run. The risk assessment runs will not affect the ordinary simulation runs that are performed on the component.

To define a Risk Assessment task, you will first select one or more assumption variables and one or more effect variables. The assumptions will be varied in the specified manner, and Studio will analyze the effects of the changes in assumptions on the selected effect variables. The result is a series of probability distributions showing the sensitivity of the effects variables to changes in the assumptions.

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.

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.

About Risk Assessment

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.

The Risk Assessment Process

The graphical overview below explains how the Risk Assessment task in Studio works.

How to Assess Risk

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.

1. Open the model

Open the simulation project that contains the component that you wish to perform the Risk Assessment on.

2. Add the Risk Assessment task

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.

3. Select assumption and effect variables for your analysis

You select the assumptions and effects in the Risk Assessment Variables window, available by double-clicking Risk Assessment Variables in the Project Window.

The Monte Carlo Sampling Method.

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 Method

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

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.

4. Define the simulation settings

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.

5. Make a presentation diagram for your 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.

6. Run the Risk Assessment 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.

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.

Select and Define a Sampling Method

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.

To select and define the sampling method: 1. Select Simulation Settings... on the Simulation menu, or right-click Risk Assessment in the

Project Window, and select Simulation Settings... on the shortcut menu. 2. Click the Risk Assessment tab in the dialog box. 3. Select the sampling method to be used in the Method drop-down box. Options are Latin

Hypercube and Monte Carlo. 4. Enter an integer indicating how many generations (samples) you want to use from the probability

distribution of each assumption, under Generations.. The default value is 40, whereas the maximum number allowed is 10 000. The Monte Carlo method would normally require at least ten times as many generations as Latin Hypercube. The recommended value is at least 40, but you may consider using fewer generations in test runs than in the final analysis. The minimum number of generations is 10.

5. Under Seed, you can enter a positive integer to initialize the random number generator. The default value is 100. (Using the same seed for successive runs will always yield the same results. Changing the seed might affect the results.) You can enter any value between 0 and +? (infinity).

6. The section History of Effects allows you to specify how the effects are recorded. If you select With Maximum Resolution, one value will be recorded for every time step of the simulation. By selecting Summarized over Period, however, you can determine a different interval to record. If you select this option, the summary type that is selected for each effect variable in their property page will be used.

Working with Risk Assessment Variables

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.

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.

Types of Probability Distribution

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.

Select Variables for Risk Assessment

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.

Define an Assumption with a Probability Distribution

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.

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:

Parameters: µ (Mu), β (Beta)

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

Define an Assumption with a Fixed Value

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

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.

To specify an effect variable: 1. Right-click the effect you wish to define in the Risk Assessment Variables window, and select

Properties on the shortcut menu. 2. Select the Effect tab. 3. Select the estimates you wish to compute in the Available Estimates lists. You can select as many

estimates per effect that you wish. 4. Select a summary type for the effect. This summary type will be used if the option Summarized

over Period is selected on the Risk Assessment tab of the Simulation Setting dialog box. 5. Click OK to save the changes, or click Apply to save the changes without closing the dialog box

Delete a Risk Assessment Variable

1. Open the Risk Assessment Variables window by double-clicking the node in the Project Window.

2. Select the variable you wish to delete in the list (under either Assumptions or Effects). 3. Hit Del on your keyboard to delete the variable.

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.

Presenting Results from Risk Assessment Analysis

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.

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

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.

The model structure that collects data for display in a histogram.

The level Histogram is an array, where each element represents a value category of the histogram. At the end of the simulation, Category will evaluate the input variable Input, and increase the value of the corresponding array element by one. You can control the size of the categories by setting the value of Category Size, and you can shift the starting point of the histogram by setting the value of Offset.

Notice that Histogram is defined as a permanent variable. This means that it retains it value between simulations. This allows the level to collect the inflows over all of the simulation runs that constitutes the Risk Assessment analysis. The Histogram level, Offset and Category Size constants, and the Category auxiliary are defined as public variables. This allows these variables to refer to variables and to be presented in controls outside the submodel.

The Reset flow resets the Histogram level at the start of the first simulation run.

The equations for the submodel is shown 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)

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.

Create a High-Low Chart

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.

To create a high-low chart in Studio: 1. Insert a Time Graph control in your diagram by clicking Time Graph 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. In a Risk Assessment analysis,

make sure to select corresponding pairs of parameters, such as High/Low, 5%/95%, 10%/90%, etc.

4. Use the Down and Up to sort the parameters in descending order (in Risk Assessment this would be High, 95%, 90%, etc.).

5. Use the Fill and Line property pages to set colors to the various parameters' graphs. By carefully selecting the fill and line colors, a graph like the one below can be created.

6. Click Apply to see the changes in the graph. Repeat step 5 until your graph looks right (see illustration below).

Note! If you are working with a Risk Assessment presentation, remember that you must perform

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.

Create a High-Low Table

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.

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

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.

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

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.

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.

About Summary Types

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.

About Dataset Variable Dimensions

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.

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.

About History in Datasets

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.

Edit and Write-back of Variable History

Provided the dataset supports manual editing of variable history, you can edit the history for a dataset variable. If you have specified that the dataset allows write-back in addition, the edited time series will also be transferred back to the data store, even if the variable in question is imported from the data store and to the simulation.

About Transfers in Datasets

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.

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.

Valid transfer directions for different variable types

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.

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.

Simulation Dataset Comments

Level

out

in

The history for the level is exported from the simulation and to the dataset.

in-out

out-in

An initial value is imported to the level from the dataset, while the rest of the history for the level is exported from the simulation and to the dataset.

Auxiliary

out

in

The history for the level is exported from the simulation and to the dataset.

in

out

The entire time series is imported to the auxiliary from the dataset.

Constant

out

in

The history for the constant is exported from the simulation and to the dataset. This is useful when you want to record the user inputs made during a simulation.

in

out

The entire time series for the constant is imported to the auxiliary from the dataset.

in-out

out-in

The initial value of the constant is imported from the time series for the constant, while the rest of the time series for the constant is exported from the constant to the dataset.

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.

Connect a Dataset to a Simulation

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.

Create Dataset Variables by Drag and Drop

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

drop it on the correct target.

Dropping model variables on dataset nodes 1. Select the model variable you wish to export of import from the model. 2. Drop the variable on the target of your choice.

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.

Dropping a model variable on an existing dataset variable

A single model variable can be dropped on a dataset variable in either the Co-models or Dataset view. If the model variable is not an interface variable yet, the transfer direction of the model variable will be set in accordance to the transfer direction of the dataset variable. In the opposite case, when the model variable already has a defined direction while the dataset variable has not, the dataset variable's transfer direction is defined in accordance of the model variable's direction.

If the model variable is dropped in the Co-models view, a connection is established, provided the transfer directions, units, types, and dimensions of the two variables match each other.

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.

Create Dataset Variables Manually

Dataset variables can be created manually in the Dataset view.

To add a new variable to the dataset: 1. Open the Dataset view of the dataset you wish to work on. 2. Right-click the Dataset node, and select Add Dataset Variable on the shortcut menu. 3. Enter the name for the dataset variable and hit Enter.

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.

To define a dataset variable: 1. Right-click the variable you wish to define, and select Properties on the shortcut menu. 2. Select the datatype of the variable under Type. Options are Complex, Real, Integer, and Boolean.

The datatype of the dataset variable must match the datatype of the model variable it is going to connect to.

3. Specify or select the Unit for the variable under Unit. Options are any unit that id'.s defined in the project's Global Units. The unit of the dataset variable must match the unit of the model variable it is going to connect to.

4. Specify or select the dimension of the variable under Dimension. The dimension of the dataset variable must match the dimension of the model variable it is going to connect to.

5. You can document the variable in the Documentation and Note fields available in the dialog box. 6. Click Apply to save the changes, or OK to save the changes and close the dialog box. 7. To define a transfer direction for the dataset variable, you right-click it and select Transfer

Direction on the shortcut menu. Options are None, In, Out and Out-In. 8. To define the summary type to be used for the dataset variable, you right-click it and select

Summary Type on the shortcut menu. Options are First, Last, Minimum, Maximum, Average, and Accumulated (some options may be excluded if they are not compatible with the selected transfer direction).

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.

Connect Model and Dataset 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.

Auto-connect all dataset variables at once 1. Right-click the Dataset Connection node of the connection you wish to auto-connect. Select

Auto-connect to Main Model on the shortcut menu.

The corresponding dataset and model variables will be connected to each other. You are only allowed to auto-connect these variables if all of the dataset variables can be properly connected (or are already

connected), and there exists model variable counterparts (with the same variable name) for all the dataset variables.

Auto-connect single variables 1. Right-click the dataset variable you wish to auto-connect, and select Auto-connect Variable on

the shortcut menu.

The dataset variable will be connected to the corresponding model variable (with the same variable name). You are only allowed to auto-connect variables that have corresponding properties and the same name.

Connect single variables manually 1. Right-click the dataset variable you wish to connect, and select Connect Variable on the shortcut

menu. 2. Select the model variable you wish to connect to on the submenu.

The list that appears contains only model variables that can be connected to the dataset variable in question. When the operation is performed, a connection is established between the two variables. This operation allows variables with different names to be connected to each other.

Connect single variables by drag and drop

You can establish variable connections by drag and drop as well. In this case, you can also drag variables from both the Equations View and Constructor diagrams, as well as from the Co-models view itself. 1. Select the model variable you wish to connect to the dataset variable. 2. Drag the model variable and drop it onto the dataset variable you wish to connect it to.

The model variable will be connected to the dataset variable. If the transfer directions (or other parts of the definitions) doesn't match, you will not be allowed to drop the model variable onto the dataset variable. Also, if only one of the variables have a defined transfer direction, the transfer direction of the other variable will be changed to the corresponding direction. Finally, if none of the variables have a defined transfer direction, the model variable will be exported to the dataset.

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.

Set the Transfer Directions for Model and Dataset Variable

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.

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.

To set the transfer direction for a model variable

The transfer direction of a model variable can be defined in Constructor diagrams, in the Equations View, and in the Properties dialog box: ! To set the transfer direction in the Properties dialog box: 1. Right-click the variable in the Equations View or the Constructor diagram, and select

Properties on the shortcut menu. 2. Click the Advanced tab. 3. Select the transfer direction in the Transfer Direction drop-down box. Options are In, Out, and

In-Out. ! To set the transfer direction in the Equations View: 1. Right-click the 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 In-Out. ! To set the transfer direction in a Constructor diagram: 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.

Set all the Dataset Variables to the Same Dimension

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.

Variable Type Allowed transfer directions

Level Out; In-Out

Auxiliary In; Out

Constant In; Out; In-Out

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.

Set the Summary Type for a Dataset Variable

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.

To set the summary type for a dataset variable 1. Right-click the dataset variable you wish to set the summary type for. 2. Select Summary Type on the shortcut menu, and select the summary type to use on the submenu

that appears. Options are First, Last, Minimum (transfer direction must be 'in'), Maximum (transfer direction must be 'in'), Average, and Accumulated.

Summary types works in the same way as they do in the simulation. The summary period is always identical to the period of the dataset.

Set the Dimension of a Dataset Variable

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

shortcut menu. There are several columns available for you.

Disconnect Dataset and Model Variables

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.

Disconnect a Dataset from a Simulation

Note! This operation cannot be undone!

To disconnect a dataset from a component: 1. Open the Co-models view. 2. Right-click the dataset you wish to disconnect in the list, and select Delete on the shortcut

menu.

The dataset will be removed from the list. Any connection to external data stores will be shut down.

Rename a Variable in the Dataset

You can rename a variable in a dataset on the Variables tab: 1. Select the variable in the Variables list. 2. Hit F2 to rename it.

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 .

Rename a Dataset in the Co-models View

To rename a dataset in the Co-models view: 1. Open the Co-models view. 2. Select the dataset to rename in the list. 3. Hit F2 to rename the dataset, and hit Enter when finished.

This operation doesn't rename the spreadsheet globally, just change the name it is shown by in the Co-models view.

Delete Dataset Variables

Dataset variables can be delete in the Dataset 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.

Note! The operation below cannot be undone!

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.

Load History from 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! You are only allowed to load data at the start of the simulation!

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.

Edit the History of a Dataset Variable

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.

To enable manual edit of dataset variable history 1. Open the dataset's view. 2. Right-click the Dataset node and select Allow Manual Edit on the shortcut menu. 3. Open the Co-models view.

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.

To edit a dataset variable's history 1. Right-click the dataset variable whose history you wish to edit, and select Properties on the

shortcut menu. 2. On the History property page you can edit the value for each period under the Value column.

Select the cell, hit F2 to edit the value, and hit Enter to finish typing. 3. Repeat the step above for all the time periods you wish to edit.

To save an edited history for a dataset variable

If the option Allow Write-back is selected for the dataset, the new series will be saved back to the dataset the next time you select Save External Data... 1. Open the dataset's view. 2. Right-click the Dataset node and select Allow Write-back on the shortcut menu.

Import the History of a Dataset Variable from a File or the Clipboard

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.

To import a history for a dataset variable 1. Open either the Studio Dataset view or the Co-models view by double-clicking their entries

in the Project Window, or by right-clicking them and selecting View on the shortcut menu. 2. Right-click the dataset variable for which you want to import a history, and select Properties

on the shortcut menu. 3. Click the History tab. 4. Click Import from File… or Import from Clipboard.… If you opted to import data from a file,

you will be prompted to select the file to import. 5. Select the separators to use under Separators.

1. Select the Decimal Separator. Options are '.' (point) and ',' (comma). 2. Select the Delimiter. Options are 'Tab', 'Space', ';' (semi-colon), and ',' (comma). 3. Select the Digit Grouping Symbol. Options are 'Space', '.' (point), and ',' (comma).

6. You can see the dimension of the impoted data under Dimensions. If you want to change the

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.

Export the History of a Dataset Variable to a File or the Clipboard

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.

To export the history for a dataset variable in the Studio dataset: 1. Right-click the dataset you wish to export either in the Studio Dataset view or the Co-

models view. Select Properties on the shortcut menu. 2. Click the History tab in the Properties dialog box. 3. Click Export…. 4. 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. 5. 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).

6. 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. 7. When you are satisfied with your selections, click OK to export the data. 8. Click Cancel to close the dialog box.

About the Studio Dataset

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.

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.

Times and summary types in the Studio Dataset

The Studio dataset can record the history from the dataset variables in three different intervals: months, quarters, and years. In addition to selecting a recording period for the dataset, you must also select the first and the last period to include in the dataset.

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.

Set Period Information for the Studio Dataset

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.

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.

The Inner Workings of the Spreadsheet Dataset

Connections between the Spreadsheet Dataset and the simulation

The connection between the Spreadsheet Dataset and the simulation is managed in the Co-models view. Interface variables and dataset variables with identical names and corresponding properties can

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.

Date formats and calendars in Studio and Microsoft Excel

The date formats in Studio and Microsoft Excel are different. Also, the range of available times is far higher in Studio, where you can virtually run a simulation from the start of the history, while Excel dates are more or less limited to the last century and on. However, when the dataset receives date information from Microsoft Excel, it will automatically convert the dates to simulation times in Studio. You don't have to think about this at all, simply enter the dates as you would normally do in Microsoft Excel, using the built-in date formats available.

While Powersim Studio supports three different calendars, Microsoft Excel only support the Gregorian calendar. Simulations run with the Gregorian calendar will be fully compatible with Excel, and the dates are exactly the same between the two. If your simulation is using the Bank or the Fiscal calendar however, you will notice that the dates and times exported to Excel are translated into the Gregorian calendar automatically. If the period selected for the dataset is less than a full month, this translation will become visible as the calendars must be stretched a little to be compatible.

As an example, as the Bank calendar January has 30 days, the Gregorian calendar January has 31 days. The dates in the Bank calendar are therefore stretched by 31/30 days, which will add exactly 2 seconds to the minute. The table below summarizes how the times correspond to eachother.

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.

Powersim Studio Bank Calendar

Microsoft Excel Gregorian Calendar

Comment

1/1/2003 1/1/2003 The start of the month is equal in both calendars. 1/15/2003 1/15/2003

11:12:00 Since January has 30 days in the Bank calendar and 31 days in the Gregorian calendar, 1/30 day must be added to each (Gregorian) day in order for the calendars to be compatible.

2/1/2003 2/1/2003 The start of the month is equal in both calendars. 2/15/2003 2/14/2003

01:36:00 Since January has 30 days in the Bank Calendar and 28 days in the Gregorian calendar, 1/28 day must be deducted from each (Gregorian) day in order for the calendars to be compatible.

3/1/2003 3/1/2003 The start of the month is equal in both calendars. 3/15/2003 3/15/2003

11:12:00 Since January has 30 days in the Bank calendar and 31 days in the Gregorian calendar, 1/30 day must be added to each (Gregorian) day in order for the calendars to be compatible.

4/1/2003 4/1/2003 The start of the month is equal in both calendars. 4/15/2003 4/15/2003 Since April has 30 days in both the Bank calendar and the

Gregorian calendar, all the dates in April are equal between the two calendars.

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.

Update Formatted or Unformatted Values

When the dataset transfers values from the simulation to the spreadsheet, it will automatically format the output in the spreadsheet. It will even include units in the format, making it easy to understand the output in the spreadsheet. In some cases, however, you might want to alter these formats yourself. In this case, you can specify that the dataset only update values and not formats. You control this on the Layout tab.

Set Sampling Times for the Dataset

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.

1. Double-click the Spreadsheet Dataset entry in the Project Window. 2. Right-click the Dataset node, and select Properties on the shortcut menu. 3. Click the Layout tab. 4. Select the Transfer at regular intervals option. 5. Use the boxes below the option to specify the sampling interval of the dataset. 6. Click Apply to save the changes, or OK to save the changes and close the dialog box.

Available time units for the sampling interval are Timestep, year, quarter, month, week, day, hour, minute, and second. The preceding number denotes the length of the interval. Example: 2xMonth indicates that the sampling interval is two months, thereby producing one value each second month.

This sampling period is also used for the summary types of the dataset variables.

Connect the Dataset to a Spreadsheet

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!

To use an existing spreadsheet with the dataset: 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 Workbook on the General tab, enter the name of the spreadsheet workbook you wish to

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

Control Spreadsheet Layout

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.

Change the Orientation of the Table

The orientation of the layout decides whether values are printed in columns - Variable Names Across - or in rows - Variable Names Down. The tables below show the difference between these options.

The illustration shows the difference between the two possible orientations of the output table.

Format Variable Header

Under Variable Names, you select the content of the variable header cell. The header cell can contain the name only; the name and subscript; the name, subscript and unit; or the name and unit. You can also hide the header completely. The table below shows the possible header layout for the variable My Var, with the unit m, and dimension 1..2,1..2.

The various variable header formats: a) Name, b) Name, Subscript, c) Name, Subscript, Unit, and d) Name, Unit.

Times Variable 1 Variable 2 ...

<Time> <Value> <Value> ...

<Time> <Value> <Value> ...

... ... ... ...

a) Variable Names Across

Times <Time> <Time> ...

Variable 1 <Value> <Value> ...

Variable 2 <Value> <Value> ...

... ... ... ...

b) Variable Names Down

My Var My Var[1,1] My Var[1,1] (m) My Var (m) a) b) c) d)

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.

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.

Define Starting Cell of the Spreadsheet

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

My Var

(m)

[1,1] [1,2] [2,1] [2,2] <Value> <Value> <Value> <Value> <Value> <Value> <Value> <Value>

Times Variable 1 Variable 2 ...

<Time> <Value> <Value> ...

<Time> <Value> <Value> ...

... ... ... ...

a) Times in separate cells selected

Variable 1 Variable 2 ... <Value> <Value> ... <Value> <Value> ...

... ... ... b) Times in separate cells not selected

new simulation runs. (Requires you to set the Run Count in Simulation Settings for the project.)

Format a Spreadsheet for Transfer to a Model Variable

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.

Format Array Dimensions

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)

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.

Sort the Order of Variables in the Spreadsheet

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.

Synchronize the Component and the Spreadsheet

Variable 1 ... Variable X 1 ... M ... 1 ... M 1 ... N ... 1 ... N ... 1 ... N ... 1 ... N

1 1 <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> 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>

P 1 <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> Q <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x> <x>

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.

Update the Spreadsheet with Values Only

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.

Use the Dataset without Saving the Spreadsheet

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.

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.

To make names change with run number: 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. Select the name you wish to update automatically with the run number - Sheet, Cell or Workbook. 4. Enter the name followed by the code '{RUNINDEX}'. 5. Click Apply to save the changes, or OK to save the changes and close the dialog box.

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.

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.

Use the Dataset to Transfer Immediate Behavior

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.

Use the Dataset to Transfer 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

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.

Create a Bi-directional Transfer for Variables

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.

To set up a bi-directional transfer: 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 Bi-Directional Transfer 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 have different transfer directions: it can be in, out, or out-in, which is a combination of the two in which the initial value is exported from the spreadsheet, while the rest of the time series is imported from studio.

Transfer Behavior from a Spreadsheet to a Model Variable

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.

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.

Transfer Behavior from a Model Variable to a Spreadsheet

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.

Interpolate Transferred Data between Data Points

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.

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.

Transfer Data at Given Times in the Spreadsheet

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

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.

Transfer All Data at the End of the Simulation

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

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.

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.

How the SEM Dataset Works

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.

Planning Areas, Levels, Packages, and Layouts

The user can define the SEM connection in the SEM Dataset view. The planning area, planning level, and a planning layout (more on the planning layout later) must be defined in the SEM Connection dialog box. When saved, the dataset will connect to SEM-BPS and read the master data information from SEM-BPS. The master data contain information about key figures and characteristics - such as ranges, time information, and units. The master data can also contain allowed values for characteristics. The master information is used to create global ranges and units and time information for the dataset.

The package information can be entered in the SEM dataset definition itself, or it can be entered for each dataset connection individually in the Co-models view (a package must be defined for the dataset connection to be able to establish communication with SEM-BPS). If the package is defined in

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.

Studio Compliant Layouts

You must select a Studio compliant planning layout when defining the SEM Dataset. The dataset uses the layout when reading and writing data to the SAP system. You define this Studio compliant layout in SEM-BPS. An SEM layout contains three parts: the header area, the lead columns, and the data columns. The list below summarizes the rules you must follow to be able to connect to the layout.

All the characteristics included in the planning level must be included in the planning layout. Characteristics that are going to be used as version ranges must be assigned to the header table of the layout. Characteristics that are assigned to the header table of the layout must be restricted to a single value on the level (although you can also assign such characteristics to the leading columns, if you wish to), unless they are characteristics that are going to be used as version ranges. Locked time characteristics (restricted to a single value) must be assigned to the header area. Time interval and unrestricted time characteristics must be assigned to the lead columns. Characteristics that are going to be used as dimension ranges must be assigned to the lead columns. The key figures that are going to be available to the dataset must be assigned to the value columns of the layout. A SEM layout cannot contain more than 10.000 rows of data (this is a restriction of the layouts in SEM). It is recommended that the number of decimals to use for the values in the layout should be set to undefined. (Otherwise, you must make sure that decimal count for each dataset variable in the

SEM Dataset corresponds to the decimal count set in SEM-BPS.)

Assigning single-valued characteristics and characteristics used as version ranges in the header area, characteristics defining dimension ranges and times to lead columns, and key figures to value columns will thus make the layout Studio compliant.

Language in SEM datasets

When you establish a connection between SEM-BPS and Studio, the SEM dataset will use the currently selected language when defining the necessary variables, ranges, and units. You may change all these names later, if you wish to. This will not affect the connection to SEM-BPS. As you will see, all SEM dataset variables will have a technical name that corresponds to the technical name in SEM, ensuring that connections are established correctly. This technical name is defined in a special technical language space within Powersim Studio. This technical language has a prefix of _07FF_. You should normally not have to worry about this when you establish or work with SEM Dataset connections.

Connection status for the SEM dataset

When a connection is established between Powersim Studio and SAP SEM-BPS, an icon will appear in the system tray of the Windows Task Bar. The three icons will illustrate the current connection

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.

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.

Units and currencies

Units and currencies must be restricted to single value in the planning level, or in the planning package if the package is specified in the dataset definition, in order to be transferred to the simulation properly. Although units and currencies are treated separately in SEM-BPS, they are treated equally in Studio. Both are imported as global units and when the dataset is defined or a dataset connection is established, they will both appear in Global Units.

Note! When connecting a dataset variable to a model variable, you must make sure that they have compatible units.

Version and Dimension Ranges

Characteristics describing ranges define the dimensions of the key figures in the SEM-BPS system, and denotes the structure of the storage. One key figure can contain several versions or elements, defined by the available range characteristics. These range characteristics may be used in two different ways in the simulation project. If such a range characteristic is assigned to the header area of the planning layout that the SEM Dataset connects to, it will be used as a Version Range in Powersim Studio.

Version dimensions affects the data source of the simulation, as they will control where in the SEM-BPS system data are transferred to and from. The version of a simulation is selected for each dataset

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.

Mapping Time Characteristics in SEM to Simulation Time

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

0CALWEEKDAY1 that are left unrestricted in the planning architecture, and combined with corresponding time interval characteristics as listed in the tables below.

Mapping fiscal time characteristics

When you include fiscal time characteristics in the planning level, you must always include the 0FISCVARNT characteristic as well, and it must be restricted to a single-value in either the planning level or the planning package. Furthermore, it must be assigned to the header area of the planning layout. The 0FISCVARNT time characteristic determines which fiscal calendar reporting scheme is used.

The SEM Dataset may use two different methods of translating the fiscal time characteristics to the simulation calendar. When you have synchronized the dataset with SEM-BPS, please ensure that the default fiscal time translation used is correct for your application. You find this on the Time Translation property page in the SEM Dataset view.

The table below summarizes the allowed combinations of fiscal time characteristics.

Mapping calendar time characteristics

When using calendar time characteristics in SEM-BPS, the calendar will be automatically mapped towards the simulation time. The table below summarizes the allowed combinations of various calendar time characteristics in the SEM-BPS system.

Locked Time Characteristic

Time Interval Characteristic

Unrestricted Time Characteristic

0FISCVARNT 0FISCYEAR — 0FISCVARNT 0FISCPER — 0FISCVARNT & 0FISCYEAR 0FISCPER3 — 0FISCVARNT 0FISCYEAR 0FISCPER3

Locked Time Characteristic

Time Interval Characteristic

Unrestricted Time Characteristic

— 0CALDAY — — 0CALWEEK — — 0CALMONTH — — 0CALQUARTER — — 0CALYEAR — 0CALYEAR 0CALMONTH2 — — 0CALYEAR 0CALMONTH2 0CALYEAR 0CALQUART1 — — 0CALYEAR 0CALQUART1 0CALYEAR 0HALFYEAR1 — — 0CALYEAR 0HALFYEAR1 0CALWEEK 0WEEKDAY1 — — 0CALWEEK 0WEEKDAY1

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.

Calendar Characteristics in SEM-BPS

Time characteristics in SEM-BPS that are related to the calendar (such as 0CALWEEK and 0CALMONTH) are mapped directly to the calendars in Studio as well. When the planning level (and package) contains these time characteristics, no calendar translation is required in the SEM Dataset.

Fiscal Time Characteristics in SEM-BPS

Fiscal calendars in the SAP system are different from "ordinary" calendars, because their starting period doesn't necessarily have to coincide with the regular calendar year, and because they often feature extra, special periods in addition to the regular (calendar) periods. Therefore, if the planning level includes fiscal time characteristics, then the SEM Dataset must relate the fiscal calendar to the calendar of the simulation using one of two different fiscal translation methods available in Studio. The two available methods are translating the fiscal calendar by fiscal variant or by fiscal periods.

If you select to translate the fiscal time characteristic by the fiscal variant, you will specify a general method of translating the fiscal calendar based on its features. The most common fiscal variants will be recognized by the SEM Dataset, and the settings of the fiscal variant translation method will be defined automatically. Please ensure that the automatic settings are correct, especially if you use a fiscal variant that is not very common. The SEM Dataset will map the fiscal periods to the simulation calendar in Studio based on these settings.

The fiscal variant translation method allows you to specify the starting time of the first period, the time unit to base the dataset period on, and how many relevant periods the data contains. As mentioned above, a fiscal calendar in SAP may contain some special (extra) periods each year. It is therefore important that you select how many of these periods should be used to report simulation data. The time unit that the dataset period is based combined with the number of relevant periods of the fiscal calendar will determine the length of the sampling period used by the dataset. If, say, the time unit is set to Month, and the number of relevant periods is set to 12, then the sampling period will be 1 month. Similarly, if the time unit is set to Month and the number of relevant periods is set to 4, then the sampling period will be 3 months.

For a fiscal calendar in SAP, the starting period may be shifted compared to the normal calendar. The fiscal year may for example run from July to July, rather than from January to January. It is therefore important that you select the starting time of the first period of the fiscal calendar you are using. As an example, if the first period of the fiscal year 2003 is 1 April 2003 (and the sampling time is one month), then the simulation time 1 April 2003 will be mapped to the fiscal time period 001.2003, the simulation time 1 May 2003 will be mapped to the fiscal time period 002.2003, and so on. Similarly, if the fiscal year 2003 starts on 1 July 2002, then the simulation time 1 July 2002 will be mapped to

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.

Times in the Co-models View

When you have created a dataset connection, the times are mapped, and you can view the reporting times of the dataset connection on the Times property page, available when you right-click the dataset connection and select Properties on the shortcut menu.

Ranges and Units in SEM Datasets

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.

Version and Dimension Ranges

Characteristics describing ranges can be interpreted in two ways in the dataset; as either Dimension Ranges or Version Ranges.

Whether a characteristic is used as a dimension range or a version range depends on where the characteristic appears in the planning layout. If the characteristic appears in the header area of the planning layout, it will be used as a version range. If the characteristic appears in the lead columns of the layout, it will be used as a dimension range.

If you use characteristics as dimension ranges, the range will be used to set the dimension of the dataset variable directly, turning them into arrays. These ranges will therefore be defined as global ranges, available in the Global Ranges view.

The order of the ranges in the Ranges property page of the dataset will affect the order the ranges appear in dimension definitions for the dataset variables. The topmost variable range will appear as

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.

Work Offline with the SEM Dataset

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.

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.

Connection status for the SEM dataset

When a connection is established between Powersim Studio and SAP SEM-BPS, an icon will appear in the system tray of the Windows Task Bar. The three icons will illustrate the current connection 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: You are not logged on to the SAP SEM-BPS system, and no data is currently transferred (obviously).

SEM Dataset Online: You are logged in to the SAP SEM-BPS system, but no data is currently being transferred.

SEM Dataset Active: You are logged in to the SAP SEM-BPS system, and data is 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.

How to Prepare SEM-BPS for the SEM Dataset

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.

Operation Connection 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, time translation details)

No

Viewing/Editing history for dataset variables No Running simulation No

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.

Setting up the planning level

The planning level is used to limit the characteristics and key figures available to those that are relevant to the business issue. In addition to selecting which characteristics and key figures should be available in the planning level, you can also restrict the characteristics to certain values or value ranges as well. This restriction will apply to all the planning packages that are created in the level as well.

You include all the key figures that you would like to access in Powersim Studio in the planning level.

The time characteristics to be used by the dataset connection must also be included in the planning level. Your planning level cannot contain both fiscal and calendar time characteristics. If your system uses the fiscal characteristics, the time characteristic 0FISCVARNT must always be present in the planning level. You must use an allowed time characteristic and restriction combination in order for the time characteristics to be properly interpreted by Powersim Studio. For a complete listing of allowed combinations of time characteristics, please read Mapping Time Characteristics to Simulation Time.

Superior characteristics must always be restricted to a single-value either in the planning level or in the planning package.

Characteristics that represent dimension ranges may be restricted in the planning level; or alternatively in the planning package, provided the planning package is defined in the dataset definition. Dimension range definitions will be created in the simulation project based on the characteristics available in the planning level. You may also leave such characteristics unrestricted, in which case the resulting dimension range in Powersim Studio will actually contain all the available elements of the characteristic. You should use unrestricted characteristics with great caution, as very large dimension ranges will result in an extremely high number of variable (array) elements in your simulation model.

Characteristics that represent version ranges must be marked as Selected in Package in the planning level. The value of the version ranges are used by Powersim Studio to decide where in the database to store the data, and Powersim Studio must therefore be able to control the value of the characteristic in the planning package. If the version range is restricted to a single value in the planning package, it will automatically be used by the SEM Dataset when data are transferred between the systems. The version can be selected in Studio either when the dataset connection is made, or at the time of loading and saving data between the two systems.

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

currencies, must be restricted to a single value either in the planning level or in the planning package.

Planning Level Checklist Include the key figures you wish to make available to the SEM Dataset(s). Include the time characteristics you wish to use. Include the characterstics you wish to use as ranges in the simulation project. Include other required characteristics, such as units and currencies. These characteristics must be restricted to a single value either in the planning level or in the planning package. You may restrict the characteristics that are to be used as dimension ranges in the simulation model. Only restrictions containing a continuous subset of elements are allowed. Characteristics that are to be used as version ranges in the simulation model must be defined as Selected in Package. Superior characteristics must be restricted to a single-value.

Setting up the planning package

The planning package is the lowest level in the planning architecture, and it takes the characteristics and key figures included in the planning level and serves to further restrict characteristics whose values have not already been restricted in the planning level.

Characteristics used as version ranges may be restricted in the planning package. This will limit the number of options available when you select the version to work on in the simulation model. If you leave it open, all the available elements will be visible when you specify the version for the dataset in Studio.

Characteristics used as dimension ranges that are not already restricted in the planning level, may be restricted in the planning package, but only as long as the planning package is selected in the dataset definition itself, and not in the dataset connection. They may also be left unrestricted, but be cautious to avoid that the ranges you import to the simulation model becomes too large to handle.

Other characteristics that haven't already been restricted in the planning level, must be restricted in the planning package.

Finally, you may also restrict time characteristics in the planning package. For a complete listing of allowed combinations of time characteristics and corresponding restrictions, please read Mapping Time Characteristics to Simulation Time.

Planning Package Checklist You may restrict the characteristics used as dimensions and versions that are not already restricted in the planning level. Only restrictions containing a continuous subset of elements are allowed. Other characteristics, such as units and currencies, that are not already restricted in the planning level, must be restricted to a single-value in the planning package. You may restrict time characteristics in the planning package, provided they match the requirements for time characteristics mapping to simulation time.

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.

Planning Layout Checklist

Assign the characteristics and the key figures to the various panes of the planning layout according to the lists below.

Header Area Locked time characteristics (restricted to a single value) Unit and currency characteristics (restricted to a single value) Superior characteristics (restricted to a single value)

Version range characteristics Lead Columns

Time interval characteristics Unrestricted time characteristics (if any) Dimension range characteristics

Data Columns Key figures

Define a SEM Dataset

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

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.

Synchronize a SEM Dataset with SEM-BPS

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.

Using Summary Types for Key Figures

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.

Load and Save Data using the SEM Dataset

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,

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.

Set and Lock Packages in the SEM Dataset

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.

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.

Allow the Simulation User to Specify Package and Version

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.

Specifying the package

The planning package can be specified in three different ways. In the dataset definition: If you specify the planning package in the dataset definition, the same planning package will be used for all dataset connections that use the dataset definition. It cannot be changed for each dataset connection independently, and a change in the dataset definition will affect all the dataset connections. Specified and locked in the dataset connection: If you specify the planning package in the dataset connection (which requires that a package is not selected in the dataset definition) and then lock it, each dataset definition can use its own individual package when connecting to SEM. Specified and unlocked in the dataset connection: If you specify the planning package in the dataset connection (which requires that a package is not selected in the dataset definition) and leave it unlocked, each dataset definition can use its own individual package when connecting to SEM. In addition, the user is allowed to select a different package when loading or saving data by clicking Load… or Save…, available under

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.

Specifying the version

The version that the SEM Dataset uses when writing or reading data to or from SEM can be specified in two different ways.

Specified and locked in the dataset connection: If you specify the version in the dataset connection and then lock it, the dataset connection will always use this version when loading and saving data. Specified and unlocked in the dataset connection: If you specify the version in the dataset connection and leave it unlocked, the dataset connection will use this version as the default version. In addition, the user is allowed to select a different version when loading or saving data by clicking Load… or Save…, available under

External Data…

Thus, to allow the user to specify the version when loading or saving data to and from SEM, specify the default version in the dataset connection, and leave the field unlocked.

Disconnect Powersim Studio from SEM

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.

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.

About the Presentation Mode

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

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.

Simulation Game Files

If Studio is opened in Presentation Mode (also called dedicated Presentation Mode), you will not be able to switch back to Design Mode. You can, however, save the your simulations in Simulation Game Files (*.sig). These files contain a reference to the simulation project, as well as the active run and the current state of the simulation. This enables you to create a simulator where your users can save their results when they find interesting decision parameters, for example.

Studio will open in dedicated Presentation Mode if you start it by double-clicking either a simulation project that is set to open in Presentation Mode, or by double-clicking a simulation game file.

What is Executive Authoring?

Note! This functionality requires an Enterprise license.

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

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 Difference between User and Presentation Modes

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.

Create a Simulator for Presentation 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!

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

Toggle between Design and User Mode

The Design mode allows you to make changes to your model.

To toggle between Design and User mode: 1. Click Toggle Design Mode.

The state of the button shows the mode of Studio: ! : If the button is depressed, Studio is in Design mode.

! : If the button is not depressed, Studio is in Run 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.

Switch to Presentation Mode

You can switch to Presentation Mode in two different ways: 1. Click Presentation Mode. 2. Hit F5 on your keyboard.

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.

Switch to Design Mode from Presentation Mode

To switch to Design Mode from Presentation Mode: 1. Click Presentation Mode to switch back to Design Mode.

If the simulation project is protected against edit access, you must enter the correct password to unlock the project.

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.

Start Project in Presentation Mode

To start a project in Presentation Mode: 1. Select Project Settings on the Project menu. 2. Click Presentation Mode Setup. 3. Select the Start up in Presentation Mode option.

When the project is opened, it will be automatically presented in Presentation Mode.

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.

Specify the Presentation of a Project

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.

Navigate in Presentation Mode

When your simulation project is supposed to be viewed in Presentation Mode, you should implement

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.

Add and View Project Documentation in Presentation Mode

There are several ways of adding documentation to your simulation project: ! You can use frames with text and pictures to explain and illustrate your simulation to your users. ! You can add a html-file with the same name as your project in the same folder.

Example: If your project is named MyProject.sip, you should place a file named MyProject.htm in the same folder. Note that this file can be the homepage of your documentation set, and link to other pages as you find necessary. The html file will be opened in the default browser when the user clicks Help.

! You can use the Hyperlink object in Studio to link your simulation project to html files (or other files containing the documentation) on the computer or on the web.

Use Game Files in Presentation Mode

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.

To Save a Simulator Game File 1. Click Save on the toolbar. 2. Specify the file name to save the file to. 3. Click OK.

To Load a Simulator Game File 1. Click Open on the toolbar. 2. Select the file you wish to load.

3. Click OK.

Protect Your Project in Presentation Mode

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

Note! This toolbar is only available in Presentation Mode!

The Presentation Toolbar allows you to navigate through your simulator interface, and also allows you to switch back to Design Mode.

Open Simulation Project or Simulation Game

Open Simulation Project or Simulation Game File allows you to open another simulation project or a simulation game file into Presentation mode. The button is only available when Studio is started in Presentation mode (by double-clicking either a simulation project or a simulation game file).

Open Simulation Project or Simulation Game

Save Simulation Game File allows you to save the decisions and the simulation you have done in the current project. The simulation game is saved in a simulation game file (*.sig), containing a link to the active project. You can load the game file later by double-clicking it in Windows Explorer, or by opening it directly in Presentation Mode.

Back and Forward

The Back and Forward buttons let you navigate through your browsing history in the same way as similar buttons in a web browser. By clicking the small arrow next to Back, a list of the most recently visited windows will be displayed.

Home

Brings you back to the default window of the simulator (as specified in the Presentation Mode Setup property page).

Reset, Play, Play Stepwise

Identical to the buttons on the Simulation toolbar, these commands let you reset the simulation, play and stop it, and play stepwise.

Reference Data

Allows you to select reference data to be presented in controls.

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

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.

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.

Language Groups and Common Namespaces

All the languages of the same "family" belong to the same language group, such as English (United States), English (United Kingdom), and English (Jamaica). All the languages belonging to the same language group share the same namespace in Studio. This means that within one language group, the same name can only be used to identify one unique variable. Thus, if a string is already used in one language of a language group, it cannot be used in any of the other languages of that language group, unless you are using it as the name for the same variable. However, a variable can obviously have two different names in two different languages of the same language group.

The table below shows a simple example, where four variables are named in two different languages. The first row of the table displays the original model (created in English (United Kingdom)), and the

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.

Automatic Language Selection

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

Language First Variable Name

Second Variable Name

Third Variable Name

Fourth Variable Name

Comment

English (United Kingdom)

Sales Behaviour Chips Crisps The original names of the variable.

English (United States)

Sales Behavior 'French Fries' Chips The model is localized to US English, but since the name Chips is already used in English (United Kingdom), an error message will be produced for that name. The others are valid and will be accepted.

English (United States)

Sales Behavior 'French Fries' 'Potato Chips' The model is localized to US English, and since all the names in both languages are either unique or identify the same variable, all names are accepted.

Norwegian (Bokmål)

Salg Adferd 'Pommes frites' Chips The model is localized to Norwegian (Bokmål), and since Norwegian doesn't belong to the same language group as English (United Kingdom), Chips is accepted as the name for the fourth variable, even though it is used to identify another variable.

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.

The Neutral Language

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.

System Language Languages in Project Selected Language English(US) English(US)

English(UK) English(US)

English(US) Greek Greek English(US) English(UK)

English(Australia) German(Germany)

English(UK)

English(US) German(Common) German(Germany) German(Austria) German(Luxembourg)

German(Germany)

English(US) German(Germany) Greek Norwegian(Bokmal) Finnish

One of the languages will be selected.

Separator Sign

List ; (semicolon)

Decimal . (punctuation)

Thousand , (comma)

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.

Set Language for a Project

To change the language of a project: 1. Select the new language in the Language box on the Project menu or on the toolbar.

The language selection is done for the entire simulation project, and you don't need to select the language again when switching views.

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.

Explicitly Set Language for a View

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.

Toggle Language Prefix on/off

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

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.

1. Create a new window by selecting New Window on the Window menu. 2. Arrange the windows in a practical way, either manually or by using the commands on the

Window menu. 3. Select the window where you will perform the translation, and select the new language for the

view by selecting Language on the View menu, click Select… and then select the language you wish to translate to. The texts will now appear with a prefix (if Language Prefix is not turned off) to indicate that they do not exist on the currently selected language (provided that the project has not been translated yet).

4. Translate the visible strings in the diagram by renaming them in their new language (select them and start typing).

5. Hidden strings, such as documentation and notes for variables and units, must be translated in the Properties dialog box (or in the Equations View of Details Window, if you prefer). To open the Properties dialog box, double-click the objects, or right-click them, and select Properties on the shortcut menu.

6. The various fields will be empty if a text doesn't exist in the selected language. Therefore, select the object in the window showing the original language. If you want to, you can copy the text. Switch to the new language window by selecting the identical object here, and write the translated text.

7. Click Apply before selecting the original language again, or your changes will get lost. 8. Repeat the above steps for all objects in the diagram. 9. Controls, like the Time Graph and Table Controls, can be translated directly. Just enter the

translated texts in the same way as for the original controls. 10. To translate global and local units, open two windows each as described above, and translate them

in the Properties dialog box. 11. To translate global and local ranges, open two windows each as described above. The range

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.

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.

About Problematic Variables

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.

aux A = undefined // A is left undefined aux B = undefined // B is left undefined aux C = A + B aux D = C / 10

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

will locate A and B for you.

Defining A will fix only part of the problem, as can be seen in the illustration below.

unit m = __METER // Added to Global Units aux A = 10<<m>> aux B = undefined // B is left undefined

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

Find Problematic Variables

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.

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.

Find Undefined Variables

To find an undefined variable in your model: 1. Click Go To Variable on the toolbar, or select Go To� on the Edit menu. 2. Select Variable named under Go to what, and select the Undefined option under Filter to display

only undefined variables in the Enter Variable Name combo box. 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 Go to Next Variable to view the next occurrence of the variable, or click Go to Previous Variable to go the previous occurrence of the 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.

Find Variables by Definition

Studio allows you to search for variables defined by a given variable: 1. Click Go To Variable on the toolbar, or select Go To � on the Edit menu. 2. Select the variable you wish to find in the Variable list. You can use the options below the list to

filter it, if necessary. 3. Select Variable(s) Defined by Selected Variable under Go To. 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. Hit F3 to find the next variable (if any).

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.

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.

Go to Next or Previous Variable

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.

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.

Example of an event in Powersim Studio.

Types of Event Actions

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

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

Description The button configuration of the message box you want to display. You can select between the standard button configurations available in Windows. These are listed below.

Options

Abort, Retry, Ignore OK OK, Cancel Retry, Cancel Yes, No Yes, No, Cancel

Icon

Description The type of message box you want to display. You can select between the standard message box types available in Windows. These are listed below together with the icon that they feature.

Options

<No Icon> Error: Information: Question: Warning:

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.

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.

The table below describes the properties of the Hyperlink Action.

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.

Title

Description The title of the message box.

Message Text

Description The message (body) text of the message box. The message box will automatically adjust to the size of the message text.

Parameter

Description The parameter you wish to change when the action is executed.

Value

Description The value you wish to assign to the parameter.

Destination

Description The destination that will be activated when the action is executed.

Add an Event

You can add an event to your simulation in the Events View: 1. In the Project Window, double-click Events to open the Events View. 2. Right-click inside the view, and select Add Event on the shortcut menu.

You then proceed to define the event on the property page, and add actions to it.

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

Property Description

Condition

Variable The variable that the event "listens" to. This variable must be a LOGICAL variable.

Trigger on TRUE

The event will be triggered when the value of the selected variable becomes TRUE. Note that the event will not be triggered again until the variable 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.

Trigger on NAN

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 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 Condition Becomes TRUE

The simulation will be paused when the condition becomes TRUE. You can continue the simulation immediately.

Prevent Play While Condition Is TRUE

The simulation cannot be started until the Condition is FALSE. By selecting this option you can prevent your user from running the simulation more until the input parameters are "correct." If your user attempts to start the simulation, a message box with the text entered under Prevent Play Message will appear.

Try Playing Simulation After Event

Once the event is finished, the event will attempt to start the simulation again. Normally this will work fine, unless you have other events that prevent the simulation from proceeding (see above).

Miscellaneous

Disabled This option disables the event, and gives you the opportunity to "turn off" an event without deleting it.

Prevent Play Message

The Prevent Play Message will appear if the user attempts to play the simulation while the Condition is TRUE.

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.

Change Event Order

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.

To move the event up in the list: ! Right-click the event and select Move Up.

Alternatively, if you wish to move the event down in the list: ! Right-click the event and select Move Down.

Add an Action to an 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.

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.

To move the action up in the list: ! Right-click the action and select Move Up.

Alternatively, if you wish to move the action down in the list: ! Right-click the action and select Move Down.

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.

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.

Syntax for Printed Equations

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

mainmodel A component in the simulation project. The variables are listed below the 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

A printed equation can look something like this:

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

Print One or More Diagrams

To print the all the diagrams in the component: 1. Click Print on the File menu. 2. Select Diagram under Print What, and then select All Diagrams. 3. Click OK to start printing and close the dialog box.

You can also select a range of diagrams to print: 1. Select the tabs of the diagrams you wish to print. Use the SHIFT or Ctrl key to select several

unit (or autounit)

appears inside a level or aux entry, it represents the unit of the variable. If the 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 autotype)

The data type of a variable. If the data type is automatically detected by Studio, the entry is named autotype.

dim (or autodim)

The dimension of a variable. If the dimension is automatically detected by Studio, 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.

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.

Set Page Margins

1. On the File menu, select Page Setup, and then click the Margins tab. 2. Under Top, select or type how much space you want there to be from the top edge of the paper to

the diagram. 3. Under Bottom, select or type how much space you want there to be from the bottom edge of the

paper to the diagram. 4. Under Left, select or type how much space you want there to be from the left edge of the paper to

the diagram. 5. Under Right, select or type how much space you want there to be from the right edge of the paper

to the diagram. 6. Under Header, select or type how far from the top edge of the paper you want to position the

header information. 7. Under Footer, select or type how far from the bottom edge of the paper you want to position the

footer information. 8. Click OK.

Under Preview you will immediately see the affect of any changes as you make them.

Set Page Orientation

1. Select Page Setup on the File menu. 2. Click the Page tab. 3. Select Portrait or Landscape. 4. Click OK.

Set Page Scaling

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.

Set Paper Size

1. Click Page Setup on the File menu, and then click the Page tab. 2. Select the required format under Paper size. 3. Click OK to save the page setup.

www.powersim.com

Powersim Software AS

E-mail powersim@powersim.no

Web www.powersim.com