fmi add-in for excel user's guide 2.0...before uninstalling fmi add-in close all instances of...

FMI Add-In for ExcelUser's Guide 2.0.1b1

FMI Add-In for Excel User's Guide 2.0.1b1

Publication date 2018-05-09Copyright © 2018 Modelon AB

Ideon Science Park

SE-22370 LUND

<[email protected]>

Self publishing

ALL RIGHTS RESERVED. This document contains material protected under International Copyright Laws and Treaties. Any unauthorizedreprint or use of this material is prohibited. No part of this document may be reproduced or transmitted in any form or by any means, electronicor mechanical, including photocopying, or by any information storage and retrieval system without express written permission from the author /publisher.

1

Chapter 1. Introduction1.1. The FMI Add-In for ExcelThe FMI Add-In for Excel integrates FMI-based parallel simulations in Excel. The add-in offers the followingmain features:

• Running simulations of compiled dynamic models, FMUs. The FMUs may be generated by any FMI-complianttool such as Dymola, FMI Toolbox for MATLAB/Simulink, FMI Composer or SimulationX.

• Taking advantage of powerful features in Excel to set up and perform batch simulations for parameter sweepsand simulations driven by data series.

• Performing dynamic simulations or solve initialization problems, in parallel.

1.1.1. Supported FMI standards

The FMI Add-In for Excel supports the following FMI standards:

• FMI for Model Exchange 1.0

• FMI for Co-Simulation 1.0

• FMI for Model Exchange and Co-Simulation 2.0

1.2. The Functional Mock-up Interface and FMUsThe Functional Mock-up Interface (FMI) is a standard for exchange of compiled dynamic models and is intended topromote model reuse and tool interoperability. Several tools provide export of Functional Mock-up Units (FMUs),all of which can be used with the FMI Add-In for Excel. FMI provides two different formats for exchange of models:

Model Exchange (ME) The Model Exchange specification is based on a continuous-time hybrid Or-dinary Differential Equation (ODE) representation. The ME FMU providesinputs and outputs, exposing functions for setting parameters and computingthe derivatives of the ODE. The FMI Add-In for Excel supports initializationof ME FMUs but not simulation.

Co-Simulation (CS) The Co-Simulation specification provides a model representation where boththe model and an integrator (ODE solver) are encapsulated in the CS FMU.Similar to an ME FMU, the CS FMU provides inputs and outputs and meansto set model parameters. It also provides a function to integrate the dynamics

Introduction

2

of the model for a specified time interval. The FMI Add-In for Excel supportsdynamic simulation and initialization of CS FMUs.

An FMU is a zip archive that contains a platform specific binary file, model metadata in an XML file and optionaladditional resource data. The metadata file specifies general model information such as the name of the modeland when it was generated. It also specifies all the variables and parameters and how they may be used. For moreinformation go to the Functional Mock-up Interface website, it is available at http://www.fmi-standard.org/ andthe specification documents can be downloaded at http://www.fmi-standard.org/downloads/.

1.3. TrademarksFMI Composer® and FMI Toolbox™ are trademarks of Modelon AB.

Modelica® is a trademark of Modelica Association.

Matlab® and Simulink® are trademarks of The MathWorks, Inc.

Windows is a trademark of Microsoft Corporation.

3

Chapter 2. Installation2.1. Supported platforms

The FMI Add-In for Excel is supported on Windows 7, and Windows 10, 32- and 64-bit versions.

2.2. Prerequisites

• Supported version of Microsoft Excel (32- or 64-bit version), see Table 2.1

• Microsoft .NET Framework 4 (x86 and x64)

• Microsoft Visual Studio 2010 Tools for Office Runtime (x86 and x64)

• Visual C++ 2010 Runtime Libraries (x86)

All necessary prerequisites, except for Excel, are installed during the installation of the Add-in. For details, seeSection 2.3. The installer does not require running in elevated mode unless any of the prerequisites is missing andrequires elevated mode to be installed.

Table 2.1 Supported Excel versions

Version Name

16 Excel 2016

15 Excel 2013

14 Excel 2010

12 Excel 2007

2.3. Installing FMI Add-In for Excel

Follow the instructions below to install the FMI Add-In for Excel. Please read through the instructions before youstart.

1. Make sure a supported version of Microsoft Excel is installed (32- or 64-bit), see Table 2.1

2. Select and run the correct installer for FMI Add-In.

• If a 32-bit Excel is installed run the installer named FMI Add-In for 32-bit Excel <version>.exeand follow its instructions to install the Add-in.

Installation

4

• If a 64-bit Excel is installed run the installer named FMI Add-In for 64-bit Excel <version>.exeand follow its instructions to install the Add-in.

2.4. Uninstalling FMI Add-In for ExcelBefore uninstalling FMI Add-In close all instances of Excel.

FMI Add-In for Excel can be uninstalled by using the "Uninstall" menu alternative in the FMI Add-In for Excelshortcut in the Windows Start menu.

FMI Add-In for Excel can also be uninstalled through the "Apps and Features" or "Add or Remove Programs",as described below.

1. Close all instances of Excel.

2. Navigate to "Apps and Features" or "Add or Remove Programs".

• For Windows 10, Open the Apps and Features view by going into Settings -> Apps and Features.

• For Windows 7, Open the Add or Remove Programs view by going into Control Panel -> Programs-> Uninstall a program.

3. Find FMI Add-in in the list of programs and choose uninstall.

2.5. LicenseFMI Add-in for Excel is one of Modelon's Flex enabled products, general license information for the Flex enabledproducts can be found in Chapter 7.

2.5.1. License features

There are two different license features available for the FMI Add-In for Excel: standard (FMI_ADDIN_EXCEL) andruntime (FMI_ADDIN_EXCEL_RUNTIME). They are described briefly below.

standard No restrictions on the available functionality. The user can set up and run sim-ulations using the FMI Add-In for Excel user interface or the API scriptingfunctions.

runtime The user can run simulations using the FMI Add-In for Excel user interfaceand use a restricted set of the API scripting functions. The Experiment sheet, inwhich the simulations are run, must have been created by a user with a standardlicense feature.

Installation

5

For an overview of the differences in terms of available features, please see Section 3.1.1.

2.5.2. Activating the license feature

2.5.2.1. First time configuration

After installing FMI Add-In for Excel, the add-in must be configured to use a specific license feature. Note thatthis must only be done the first time after installation. To configure the license, please follow the steps below:

1. Open the License Information window by clicking the button License in the "Info" button group in the FMIAdd-In Ribbon, see Figure 2.1.

Figure 2.1 License button

2. Using the drop-down list next to the label Active feature, select the license feature you want to check out, seeFigure 2.2. "Demo" will be selected by default, see Section 2.5.3 for more information. Note that all featuresin this list might not be available for your license.

Figure 2.2 Selecting license feature

3. Click the button Change... and select "OK" when prompted with a verification question.

Installation

6

4. If the change was successful, a dialog window will inform you that the new feature will be used the next timethe license feature is checked out. If the change failed, you will get an error message. Please contact supportif this happens.

5. Restart Excel for the changes to take effect.

2.5.2.2. Activating and deactivating a license feature

The license feature set for your FMI Add-In for Excel installation will be activated and checked out as soon asyou start using any of the functions (available as buttons in the FMI Add-In Ribbon) or any of the API scriptingfunctions. This means that you can start and work with other parts of Excel without a license feature being checkedout.

Closing Excel will return the checked out license feature.

For license server users, there is a linger time set to 5 minutes. This means that when a license feature is returnedto the license server, it will remain checked out for 5 minutes. This is to ensure that a license feature is not lostif Excel is accidentally closed.

2.5.2.3. Changing a license feature

To change the current active feature, the procedure is the same as when configuring the license feature for the firsttime. Please follow the step-by-step instructions in Section 2.5.2.1 to do this.

Note that a runtime license user can, in this way, always change to demo mode (see Section 2.5.3) in order to trythe full version of FMI Add-In for Excel.

2.5.3. Demo mode

Running the add-in in demo mode limits usage to the examples included in the add-in distribution. That is, onlythe FMUs that are available in the examples folder found in the FMI Add-In for Excel installation can be used.

2.6. SupportSupport inquires should be sent to [email protected].

7

Chapter 3. Simulation andInitialization3.1. Overview of the FMI Add-In for ExcelMost of the user interaction in FMI Add-In for Excel is performed from the FMI tab that can be found in theRibbon, located in top of the Excel window. The FMI tab contains four different groups of buttons. Some of thebuttons are disabled (grayed out), depending on the content of the active sheet and the current active license feature.

Figure 3.1 FMI Add-In Ribbon

For general information about the FMI technology and FMUs, see Section 1.2 in Chapter 1.

3.1.1. Cell Style Legend

The FMI-Add-In for Excel will have different color and layout styles for the cells in the sheets. The styles corre-spond to different things. The table below lists all the different styles and what they indicate.

Table 3.1 FMI Add-In button groups

Description Example

Cells with an orange style indicate that they are editable by the us-er.

Figure 3.2 An empty editable cell

Figure 3.3 An editable cell with a value

Cells with a light orange style indicate that they are editable by theuser and that the values in the cells will be used as default values.

Figure 3.4 An empty editable cell for de-fault values

Cells with a grey style indicate that they are output values to beread by the user.

Figure 3.5 An empty non-editable cell

Simulation and Initialization

8

Description Example

Figure 3.6 An non-editable cell with a val-ue

Cells that indicate the status of the initialization and simulationduring the different stages.

Figure 3.7 Waiting for the simulation tobegin

Figure 3.8 Simulation is running

Figure 3.9 Simulation is done

Figure 3.10 Simulation was successful

Figure 3.11 An error occured

3.1.2. License requirements overview

The table below lists all available button groups in the FMI tab and for which license feature the button groupis available. Buttons will be grayed out if the required license feature does not match the license feature that iscurrently active. For more information about the different license features, see Section 2.5.1 in Chapter 2.

Table 3.2 FMI Add-In button groups

Button group Description Required license feature

Import Model Buttons for loading an FMU and creating an FMUsheet. These buttons are always enabled.

standard, demoa

Setup Simula-tion Sheet

Buttons for creating a Simulation sheet. The CreateSimulation Sheet button is enabled when the active(visible) sheet is an FMU sheet.

standard, demoa

Simulate Buttons for simulating and initializing FMUs. Thisgroup is enabled when the active (visible) sheet is aSimulation sheet.

standard, runtime, demoa


9

Button group Description Required license feature

Results Buttons for handling results from simulations and ini-tializations, such as creating plots and showing/hid-ing result sheets. This group is enabled when the active(visible) sheet is a Simulation sheet.


Info The button User´s Guide opens this document. TheAbout button opens a window containing informationabout the add-in and the License button opens a win-dow with information about the current license status.The buttons in this group are always enabled.

standard, runtime, demo

aButton group is available in demo mode (when no license feature is checked out) but usage is restricted to the example FMUs that come withthe FMI Add-In for Excel installation.

3.2. Getting started

In this section, a tutorial is provided that demonstrates the use of all essential features of the FMI Add-In for Excel.

3.2.1. License requirements

The tutorial in this section can be done with a standard license or in demo mode (no license). For more informationabout license features, see Section 2.5.1 in Chapter 2.

3.2.2. Introductory tutorial

The model used in the tutorial is a Furuta pendulum expressed in Modelica code and exported as an FMU forCo-Simulation. The FMU file can be found in the installation folder of FMI Add-In for Excel: <installationdirectory>\Examples\Furuta\<FMI version>\<FMU kind>\Furuta.fmu.

Assuming that the installation procedure was successful, Excel should now have an FMI tab in the Ribbon, seeFigure 3.12.


10

Figure 3.12 FMI Add-In in Excel

The FMI tab contains different groupings of buttons. Some of the buttons are disabled by default. They are enabledwhen the active sheet contains data in a matching format.

Figure 3.13 FMI tab in the Excel Ribbon

The first step when simulating an FMU is to load an FMU into a worksheet. Such a sheet is referred to as an FMUsheet. From the FMU sheet, the user selects input and output variables that will be included in the batch simulation.The next step is to create a sheet from which the computations are configured and run. This is done by creatinga Simulation sheet. In the Simulation sheet, the different start and parameter values, input trajectories, simulationtime, etc. defining the batch are entered. Also, the final initialization/simulation results are written back to this sheet.

Follow these steps to complete the tutorial:

1. Click the FMU button to create an FMU sheet. A file dialog is then opened. Select the Furuta pendulum FMU,see Figure 3.14. The Furuta FMU file is located in the <installation directory>\Examples\Furuta\<FMIversion>\<FMU kind> folder.


11

Figure 3.14 Loading an FMU

2. A new FMU sheet is created. There are two areas in the new sheet, one for model metadata ("FMU Informa-tion") and one for the variables in the FMU, see Figure 3.15. The "FMU Information" section contains generalinformation about the FMU, e.g. model name, FMU kind, number of state variables, etc. The Variables area liststhe variables with name and their corresponding attributes, including default value, unit, data type, etc. Thereare three columns that do not correspond to any FMI attribute: the "Include" column, the "Include in", and the"Variable type" column. The "Include" column indicates if the variable will be included in the simulation ornot.The "Include in" column indicates if a variable will be used as an input, output, or both, a default value isderived from the variable. The "Variable Type" provides a short variable type info derived from the variable


12

Figure 3.15 Layout of the FMU sheet

Note that the Create Simulation Sheet button in the ribbon was enabled when the FMU sheet was created. Itis only enabled when the active sheet is an FMU sheet.


13

3. The value in the "Include" column indicates whether a variable is included or not in a simulation. By default,no variable is included. Click the Filtered Variables>Add Filter button in the Ribbon, see Figure 3.16 toinclude all variables in the simulation. Then remove all variables starting with der( . Select a cell on a rowcorresponding to such a variable, and then click on the Selected Variables>Remove Selection button in theRibbon. This will set the value in the Include column to "FALSE" for the variable at the corresponding row.Tip: to select multiple variables, hold down the Ctrl key while selecting variables and then click SelectedVariables>Remove Selection .

Figure 3.16 Add filtered variables

4. If a variable is included, the value in the "Include in" column indicates whether the variable is included as indata,outdata or both. Configure which variables will be used in the Simulation sheet using the drop down list in the"Include in" column, see Figure 3.17.

indata Set start values, or parameters or an input trajectory for this variable.

outdata The results for this variable is reported from the experiment.

indata & outdata Use the variable both as indata and outdata.

n/a Do not include the variable in the Simulation sheet. The variable is notincluded even if the include column value is set to true.

Figure 3.17 Selecting experiment variables

Note that the powerful Excel filter functions can be used to filter the variables, see Section 3.3.4.


14

5. Before creating a simulation sheet it is possible to set the number of simulation cases that shall be createdinitially. This is done by modifying the "Number of Cases"-field as seen in Figure 3.18.

6. Click the Create Simulation Sheet button to create a Simulation sheet, see Figure 3.18.

Figure 3.18 Create Simulation Sheet, and set Number of Cases

7. A Simulation sheet is now created. The sheet has 3 areas, see Figure 3.19:

• Info: Contains general information about the experiment.

• Experiment Setup: Contains the two sub-sections Simulation settings and Parametrization. The Simulationsettings sub-section contains general setup of the simulation, such as FMU Path, start time, and Output points.The Parametrization sub-section contains the variables selected to be included in indata when the simulationsheet was generated, divided into exact and guess initials depending on the variables initial type.

• Results: Contains the sub-section Final Values. The Final Values sub-section contains the variables selectedto be included in outdata when the simulation sheet was generated. When performing an initialization orsimulation the final result for each variable and case will be printed here.

The number of simulation cases is defined by the columns called "Case 1", "Case 2", etc.


15

Figure 3.19 Layout of the Simulation sheet

8. Change the start values of theta_0 for each simulation case in the Parametrization area to 0.1, 0.2, and 0.3rad. Change the default Stop time in the Simulation settings area to 10, and click the Simulate button in the


16

Ribbon to start the simulation. The Final Values area is then populated by the final variable trajectory values,see Figure 3.20.

Note that empty cells in the Indata and Settings areas imply that the values in the default column will be used.

Figure 3.20 Results after initialization and simulation

9. In the Final Values toggle the plot column to "FALSE" for all variables except "theta". This can be done bydouble-clicking the cells. Press the "Create Plot" button in the Results button group to create the plot shownin Figure 3.21.


17

Figure 3.21 Plot of Theta over 10 seconds

10.Navigate back to the simulation sheet. Toggle the buttons "Show Trajectories Sheet" and "Show Logs Sheet" tounhide the trajectories and log sheet created when the simulation was performed. In the log sheet information,warnings and errors will be recorded depending on the set log-level. In the trajectories sheet all recorded outputpoints are recorded.

3.3. The FMU sheet

The FMU sheet contains information that is extracted from the FMU, such as general model information and a listof the variables exposed by the FMU. The FMU sheet is an Excel worksheet that is populated with data in a specificformat relaying on Named Ranges. Other add-in operations may not work properly if the values or the namedranges are changed. To prevent the user from unintentionally making errors, parts of the sheet is made read only.


A standard license is required to create and work with an FMU sheet. A runtime license holder can open and viewan FMU sheet, but not create and work with it. See Section 2.5.1 in Chapter 2 for more information about thedifferent license features.

When running in demo mode, FMU sheets can be created and used but are restricted to the example FMUs thatcome with the installation.


18

3.3.2. Load FMU

An FMU sheet is created with the FMU button.

Figure 3.22 Load button group

The FMU button opens a file browser which prompts the user to select an FMU file. When an FMU file is selectedin the browser, a new FMU sheet is created that becomes the current active sheet in Excel. The sheet name is setto "FMU <FMU model name>" where "<FMU model name>" is the name of FMU model. The sheet is partiallyread only in order to preserve the integrity of the FMU sheet.

3.3.3. FMU sheet areas

The sheet consists of two areas, "FMU Information" and "Select variables to include in simulation...", see Fig-ure 3.23.


19

Figure 3.23 The FMU sheet areas, FMU Information and Select variables to include in simulation...

3.3.3.1. The Model area

The FMU information area is dedicated to general information stored in the FMU and experiment metadata. Whenan Experiment is created, information is read from this area to create Simulation sheets.


20

Table 3.3 Description of the Model metadata area

Model metadata cell CorrespondingFMI attribute

Named Ranges(Prefixed FMU_)

Description

FMU file name FMUFileName FMU file name

FMU path FMUPath FMU file path. Path to theFMU file that was used tocreate the sheet. The path isused as the default path inthe experiment sheet.

Model name modelName Model_modelName Name of the model

Model Identifier modelIdentifier Model_modelIdentifier Model identifier

FMU kind FMUKind Kind of FMU which can beeither "ModelExchange","CoSimulation","CoSimulation_StandAlone","CoSimulation_Tool" or"Unknown".

FMI version fmiVersion Model_fmiVersion FMI version of the FMU

Description description Model_description Short description of themodel

Generation tool generationTool Model_generationTool Name of the tool that gen-erated the FMU

Generation date and time generationDateAndTime Model_generationDate-AndTime

Date and time when theFMU was generated

Model version version Model_version Version of the model

Author author Model_author Name and organization ofthe model author

GUID guid Model_guid A string, “Globally UniqueIDentifier”, that is used tocheck that the metadataXML file is consistent withthe C-functions in the DLLfile.

Naming convention variableNamingConven-tion

Model_variableNaming-Convention

Defines whether the vari-able names follow a par-ticular convention. Canbe set to either "flat"


21

Model metadata cell CorrespondingFMI attribute


Description

or "structured". Where"flat" means: a list ofstrings, and "structured"means: hierarchical nameswith “.” as hierarchy sep-arator, and with array ele-ments and derivative char-acterization.

Number of states numberOfContinu-ousStates

Model_numberOf-ContinuousStates

Number of continuousstates

Number of event indica-tors

numberOfEventIndicators Model_numberOfEvent-Indicators

Number of event indicators

Default start time startTime Model_startTime Default start time (option-al)

Default stop time stopTime Model_stopTime Default stop time (optional)

Sheet version sheetVersion Version of FMI Add-In thatgenerated the FMU sheet

Experiment expiry date Model_expiryDate Expiry date for the exper-iment. The generated ex-periment sheet will notbe of use after this date.An empty cell means notime limit, this is the de-fault behaviour. The datemust be entered in the for-mat dd-mmm-yyyy, e.g. 06-mar-2014.

3.3.3.2. The Variables area

This area contains information about each variable such as default value, unit, etc.

Table 3.4 Description of the Variable area

Variables areacolumn names

Correspond-ing FMI at-

tribute or element


Description

Include include Indicates whether variable is included inexperiment or not


22

Variables areacolumn names

Correspond-ing FMI at-

tribute or element


Description

Include in includeIn See Section 3.3.4.

Name name Variables_name Full, unique name of the variable

Variable type Variables_variable-Type

Generated from the variable informationto provide a brief overview of the variabletype, such as input , parameter, or pa-rameter with start value

Default Value start Variables_default-Value

Initial value of the variable. A differentstart value can be set before initialization(not allowed for constant variability). Allconstants, independent parameters and in-puts of the FMU must have a start value inthe metadata file. Parameters that do nothave a start value are computed during ini-tialization (e.g. as functions of other param-eters).

Unit unit Variables_unit Physical unit of the variable

Quantity quantity Variables_quantity Physical quantity of the variable, e.g., “An-gle”, or “Energy”

Data type One of the ele-ments Real, Integer,Boolean, String orEnumeration.

Variables_type Data type of the scalar variable

Initial FMI 1.0: fixedFMI 2.0: initial

Variables_initial Describes how the initial value is set. canbe set to exact, approx, or calc

Description description Variables_description Description of the variable

3.3.4. Create Experiment

An Experiment is set up by creating a Simulation sheet, this is done from the FMU sheet. Note that a Simulationsheet can only be created by a user with a standard license, see Section 2.5.1 for more information about differentlicense features.

The FMU sheet provides a convenient overview of the information and variables found in the FMU and allowsthe user to set the indata and outdata variables for an experiment by using the Excel filter functions. This approachlimits the number of variables that Excel has to handle in the simulation which will speed up the simulation and


23

make the data sets easier to maintain. By default, the simulation sheet name will be "Exp <Load FMU sheet name>".If the sheet already exists, a serial number is added to the name.

The number of simulation cases that is created when generating the simulation sheet is set in the FMI ribbon, seeFigure 3.24. By default the number of cases that are generated is set to 3.

A Simulation sheet is created by clicking the Create Simulation Sheet button in the Ribbon. The Create Simu-lation Sheet button is only enabled when the active sheet is an FMU sheet. The Filtered Variables and SelectedVariables button groups are used to add/remove variables to the Simulation sheet being set up. Variables can alsobe added removed by double-clicking the variable row.

Figure 3.24 Setup Simulation Sheet button group

In the process of creating the Simulation sheet, the Variables area in the FMU sheet is read and used to createthe Indata and Outdata areas in the Simulation sheet, see Figure 3.31. To include a variable in the Experiment,the value in the Include column must be set to "TRUE" and the Include in column must be "indata", "outdata"or "indata & outdata".

• Include column

The value in the Include column must be set to "TRUE" to include the variable in the experiment. The value can beset using the Add/Remove filter buttons, the Add/Remove selection buttons in the Ribbon, or double-clickingon the variable's row. Default value for this column is "FALSE".

• Add/Remove filter

Click the Filtered Variables->Add filter button to include all variables that are visible in the FMU sheet.Click Filtered Variables->Removefilter to remove them. These buttons should be used in combination withthe filter functionality in Excel. To add or remove a specific variable or multiple variables, use the filter tofind them and then click the corresponding filter button. The value in the Include column is changed to "TRUE"when the Add filter button is clicked and to "FALSE" when the Remove filter button is clicked, regardlessof the current selection in the sheet.

In Figure 3.25, the Name cell was clicked to open the filter dialog. The checked check boxes corresponds tothe variables that are visible while Excel hides the unchecked variables. This filter functionality can be usedon all the other columns as well, e.g., Variable type, Include in, Unit, etc.


24

Figure 3.25 The filter function

• Add/Remove selection

Click the Selected Variables->Add selection button to include the selected variables in the Excel sheet. ClickSelected Variables->Remove selection to remove them. To select a variable, click any row correspondingto a variable. To select multiple variables, hold down Ctrl while clicking the variable rows.

• Include in column

Description of the values that a variable may be set to:

indata The variable is subject to parameter sweeping or is an input trajectory (onlyvalid for top level inputs).


25

outdata Results for this variable are generated.

indata & outdata Results for this variable are generated.

n/a Do not include the variable in the Simulation sheet.

Figure 3.26 The Include in column drop-down list

The values in the Default value column are used as default values in the Simulation sheet.

3.3.5. Filtering

The filtering function in Excel is a powerful tool for finding and listing data in a flexible way. It is thereforeencouraged to use filtering when creating experiments for FMUs that may contain thousands of variables. Thefilter function is added automatically to the headers in the Variables area in an FMU sheet.

A filter applies to all rows and is additive. When a variable does not match a filter selection, the whole row ishidden. After one filter criterion has been applied, another filter operation can be applied. This means that thenumber of visible rows decreases as filter operations are applied unless the "Add current selection to filter" is used,see Figure 3.27. Note that this feature is not available in Excel 2007.


26

Figure 3.27 Filtering by variable name

For more information on how to use filtering in Excel, see http://office.microsoft.com/en-us/excel-help/filter-da-ta-in-a-range-or-table-HP010073941.aspx .

3.4. The Simulation sheet

In the Simulation sheet, batch computations are configured and executed. The final variable values from a simu-lation or initialization experiment are also written to this sheet.


27


A user with a standard license can work with any simulation sheet without limitations. A user with a runtime licensecan also work with a simulation sheet, provided that the sheet has been created by a user with a standard license.For more information about different license features, see Section 2.5.1 in Chapter 2.

When running in demo mode, Simulation sheets can be created and used but are restricted to the example FMUsthat come with the installation.

3.4.2. Simulation cases

A batch experiment consists of multiple simulations and each experiment is called a Case.

A case is defined in a single column, see for example Case 2 is defined in column K in Figure 3.28. For each case,the start time, stop time, start values of the variables etc, can be set. If a cell is empty, the corresponding value isread from the Default column, see column I in Figure 3.28. The default value can also be left empty in the Indataarea. In this case, no value is set by the add-in, instead the predefined start value in the FMU is used.


28Figure 3.28 Three simulation cases


29

3.4.2.1. Named ranges

Named ranges are used in the Simulation sheet to refer to cell values. When a batch experiment is started, the rangesin the Simulation sheet are analysed and an internal structure for the simulation is created. To locate sections ofdata in Excel, areas of the sheets have been given names when they were created, and this is called "named ranges".

Due to the use of named ranges it is important to utilize the built-in functions when modifying the extent of thesheets, such as adding or removing cases.

3.4.2.2. Number of simulation cases

The number of simulation cases are defined by the first row in the Experiment setup area of the simulation sheet.There are always a default case followed by a number of cases, see Figure 3.29.

Figure 3.29 Default and three simulation cases

3.4.2.3. Add and remove simulation cases

A simulation case is added by pressing the button "Add Case", and removed by pressing the button "RemoveCase", see Figure 3.30.

Figure 3.30 Add and Remove Case buttons

3.4.2.4. Disabling/Enabling simulation cases

To disable or enable a simulation case, type "True" or "False" in the cell corresponding to the simulation case inthe Enable row. The Enable row is located in the Settings area. When a simulation case is disabled, the simulationMessage will be set to "Disabled".

3.4.3. Simulation sheet areas

The Simulation sheet consists of three areas, "Info", "Experiment Setup", and "Results".


30Figure 3.31 Simulation sheet areas, Info, Experiment Setup, and Results


31

3.4.3.1. The Info area

The Info area includes model and experiment metadata. The following table describes each row included in the area.

Table 3.5 Description of the Model Metadata area

Name in Sim-ulation sheet

Named Ranges(Prefixed Exp_)

Description

Sheet version sheetVersion Version of FMI Add-In for Excel that generated theSimulation sheet

Model name Model_modelName Name of the model

Generation tool Model_generationTool Name of the tool that generated the FMU file

FMU kind FMUKind Type of FMU. Can be one of: "ModelExchange","CoSimulation", "CoSimulation_StandAlone","CoSimulation_Tool" and "Unknown".

Checksum Model_checksum A control sum used to verify that the sheet is valid forthe active license feature. Users should not change thisvalue as the sheet will then become invalid.

Expiry date Model_expiryDate Expiry date for the experiment sheet. The sheet willbecome unusable after this date. If the cell is empty,there is no time limit on the sheet (default). The date isformatted as dd-mmm-yyyy, e.g. 06-mar-2014.

3.4.3.2. The Experiment setup area

The Experiment setup area contains two subsections "Simulation settings" and "Parametrization", described be-low. It also contains the defined case names and status from the last initialization/simulation performed. An errormessage is printed if a simulation failed, "Disabled" is printed if the simulation case is disabled, otherwise "OK"is printed.

Simulation settings

The Simulation settings subsection includes settings for all simulation cases. The table below describes all partsincluded in the area.

Table 3.6 Description of the Simulation area

Name in Ex-periment sheet


Description

Settings_values Range referring to the cell values: "FMU path", "Starttime", "Stop time", "Output points", "Timeout", "LogLevel", and "Enable" in the Simulation settings subsec-


32

Name in Ex-periment sheet


Description

tion (described below) This range defines all settings,including the defaults, for all simulation cases.

FMU path Part of Settings_values Path to the FMU file that is simulated. Can be an abso-lute path or a relative path to the workbook document.

Start time Part of Settings_values Start time of the simulation or initialization

Stop time Part of Settings_values Stop time of the simulation. It is only used in dynamicsimulation with Co-Simulation FMUs.

Output points Part of Settings_values Number of result points in the output trajectory. Theresult point at initial time is automatically added. It isonly used in dynamic simulation with Co-SimulationFMUs.

Timeout Part of Settings_values Timeout in seconds. If the simulation process has notreturned before this time limit, it is terminated abrupt.If timeout time is set to 0 seconds, infinity will be used.

Log level Part of Settings_values Log level used for the simulation(s). Can be set to oneof "Disable", "Fatal", "Error", "Warning" or "Info".

Enable Part of Settings_values Boolean value indicating whether or not a case is simu-lated

Parametrization

Parameter and variable start values or input trajectories for top level inputs in the different cases are set in theParametrization subsection.

The Parametrization subsection is divided into Exact initials and Guess initials areas. All variables which will beinitialized exactly is placed in the exact area, for variables in the guess area the start value will be calculated basedon other variables, or used to set the start value for an iteration variable. The table below describes the rangesincluded in both of the areas.

Table 3.7 Description of the Parametrization subsection



Description

InData_exactValues /InData_guessValues

Range referring to the start and parameter values of allsimulation cases, including the values in the defaultcolumn.

InData_exactVariables /InData_guessVariables

Range referring to columns "Name", "Unit", "Variabletype", "Data type", and "Description" for all input vari-ables in all simulation cases.


33

3.4.3.3. The Results area

The Results are contains the subsection "Final Values", as described below.

For each simulation case, the final values of the variable trajectories are written in the Final Values subsection.The following table describes this area.

Table 3.8 Description of the Final Values subsection



Description

OutData_values Range where the results are printed

OutData_variables Range referring to columns "Name", "Unit", "Variabletype" "Data type", "Description" and "Plot" of all out-put variables.

3.4.4. Setting values and input trajectories

Data type checking is performed in all cells that are read by the FMI Add-In for Excel. For example, the FMU pathis expected to be a string and generates an error otherwise. Start values should only be set for variables that havedefault start values. Input trajectories can only be set to the variables in the Indata area. Input trajectories shouldonly be used with variables that are top level inputs, i.e., has causality set to "input".

Note that variables of data type String, are not supported.

To set an input trajectory:

1. Select the cell corresponding to the variable and simulation case for which the input trajectory is to be set, seeFigure 3.32. The variable must be a top level input.

Figure 3.32 Setting an input trajectory of a variable

2. Start typing an equal sign in the cell, see Figure 3.33.

Figure 3.33 Typing equal sign

3. Use the mouse to select a range containing the input trajectory data where time points are stored in the first rowand input data is stored in the second row, see Figure 3.34.


34

Figure 3.34 Selecting the input trajectory data

The selected input trajectory range must have dimensions either 2 x M or M x 2, where M is the number of datapoints. The first row or column must contain the time points and the second row or column must contain thedata values. For 2 x 2 sets, the time points are in the first row.

4. Click Ctrl + Shift + Enter to create an array formula. If successful, the first value in the input trajectory rangewill be visible in the cell, in this case "0.1". Otherwise "#VALUE!" is visible in the cell.

3.4.5. Number of processes

Before executing simulation it is possible to set the number of paralell simulations to be launched. This is donein the "Simulate" button group by changing the value of the "Parallel Simulations" field, see Figure 3.35. Themaximum number of parallel processes is limited to the number of processes of the computer.

Figure 3.35 Setting number of processes

3.4.6. Simulation and Initialization

To execute a batch simulation or initialization experiment, click on the corresponding button in the "Simulate"button group, see Figure 3.36. These buttons are enabled when the active sheet is a Simulation sheet.

Figure 3.36 The Simulate button group

When the simulation/intialization experiment has started, no interaction with Excel is possible. If any editing orinteraction with Excel is active when the button is clicked, the simulation will not start. Disabling user interaction


35

during the simulation allows the add-in to perform optimized recalculations and graphical updates in Excel. Thecontrol is returned to the user when the simulation or initialization experiment is finished.

3.4.6.1. Simulate FMU

To start a batch simulation of a Co-Simulation experiment, click the Simulate button in the "Simulate" buttongroup in the Ribbon. This will generate a Log sheet, called "Log <Experiment sheet name>", and a Trajectoriessheet, called "Res <Experiment sheet name>". Note that the Log sheet and Trajectories sheet, will be cleaned andoverwritten if they already exist. These sheets will be populated with data during the batch simulation after eachsimulation case has finished. The Log sheet and Trajectories sheet are hidden by default, see Section 3.4.6.3 formore information about hiding and unhiding sheets.

The Simulation sheet will also be updated after each simulation case with the final trajectory values in the Resultsarea.

3.4.6.2. Initialize FMU

To start a batch initialization of a Model Exchange or Co-Simulation experiment, click the Initialize button in the"Simulate" button group in the Ribbon. This will generate one Log sheet, called "Log <Experiment sheet name>".Which is populated by data during the batch simulation after each initialization case has finished. The Log sheetis hidden by default, see Section 3.4.6.3 for more information about hiding and unhiding sheets. The Simulationsheet will be updated after each simulation case with the results in the Results area.

3.4.6.3. Show trajectories sheet and show logs sheet

The Show Trajectories Sheet and Show Logs Sheet toggle buttons are used to hide and unhide the trajectoriesand log sheets. When the button is toggled, all sheets of the corresponding type are unhidden or hidden. The statusof the button is also applied to new sheets that are generated.

3.4.7. Plotting

After performing a simulation it is possible to automatically generate plots for the output variables included inthe experiment.

In the column named "Plot" in the Final Values subsection of the Results area a boolean is set enabling/disablingplotting of the individual variable, see Figure 3.37. The values of the plot column can be toggled between "TRUE"and "FALSE" by double-clicking the cell. A plot is only created for variables where the plot value is set to "TRUE".


36

Figure 3.37 The plot column used for dsablin/enablig plot of variables

When pressing the "Create Plot" button in the Results button group in the ribbon a new sheet is created with thename "Plot <FMU model name>" where "<FMU model name>" is the name of the FMU model for the currentlyactive simulation sheet. If this sheet already exists it will be cleaned and overwritten.

The plot sheet will contain one plot sheet per variable that has the plot column set to "TRUE", where each case willbe plotted against the simulation time.

After changing the experiment setup and performing a new simulation the Create Plot button can be pressed againto properly update the plots.


37

Figure 3.38 Two automatically generated plots for three simulation cases


38

3.5. Examples

3.5.1. Batch simulation of the Robot 3D model

In this example, a Robot model from the Modelica Standard Library will be simulated with a set of differentparameter values. We will apply different loads on the arm and analyze how the joint angle trajectories are affected.

Figure 3.39 The Multibody Robot from Modelica Standard Library

3.5.1.1. File location

Both the FMU file and the Excel file for this example can be found in the installation directory of FMI Add-Infor Excel, in folder <installation directory>\Examples\Robot3D\<FMI version>\<FMU kind>. Before theexample can be run, the path to the FMU must be updated in the Experiment sheet to point at the FMU.

3.5.1.2. License requirements

This example can be run with a standard license or in demo mode. For more information about license features,see Section 2.5.1 in Chapter 2.

Note that a user with a runtime license can always temporarily use FMI Add-In for Excel in demo mode to be ableto run this example. See Section 2.5.2.3 on how to do this.


39

3.5.1.3. Running the example

1. Select the FMI tab in the Excel Ribbon and click the FMU button to open the file browser. Navigate to theRobot FMU file that is located in the <installation directory>\Examples\Robot3D\<FMI version>\<FMUkind> folder and select "Open" to load the FMU.

Figure 3.40 Loading the Robot Co-Simulation FMU

2. In the Variables area, click the cell "Name" so that the filter box is opened. Search for mLoad, uncheck thevariable mechanics.mLoad, and click "OK". mLoad is the mass parameter that corresponds to the load attachedto the robot arm. This parameter will be selected as indata in our experiment. This can be seen from the valuein the "Include in" column that is set to "indata", see Figure 3.41.


40

Figure 3.41 Filter for mLoad in the name column

3. Repeat the operation, but this time filter for mechanics.load.body.r_0[3], Check the check box "Add currentselection to filter" (not available in Excel 2007). Figure 3.42 shows the order in which the actions are made, inorder to add the variable using the filter function. If Excel 2007 is used, click on Add filter before this secondfilter is done so that mLoad Include column value is set to "TRUE".


41

Figure 3.42 Adding filter in the Name column

4. Click the Filtered Variables->Add filter button to include the visible variables in the experiment. The valuein the Include column should now change from "FALSE" to "TRUE".

5. Set "Number of Cases" in the "Setup Simulation Sheet" ribbon group to 12.

6. Click the Create Simulation Sheet button.

7. Set Stop time, to 1.8s. Note that the decimal delimiter can differ depending on the regional settings.

8. Increase mLoad by 30kg for each simulation case starting at 15kg.

To set the parameter values, use the auto fill function. This is done by first entering 15 in the mLoad cell forCase 1 and 45 for Case 2. This is used to initialize the auto fill function. Now select the two cells and drag thelittle black box in the lower right corner of the selection to fill all 12 cases.


42

Figure 3.43 Configured simulation sheet with 12 cases

9. Click the Simulate button.

10.When the simulations have finished press the "Create Plot" button in the Results button group to create the plotshown in Figure 3.44.


43

Figure 3.44 Plot of the output trajectory for variable mechanics.load.body.r_0[3].

3.5.2. Batch initialization of Heat Exchanger

In this example, an internal heat exchanger using CO2 as medium will be initialized with a range of different pa-rameter values. The FMU is generated from the Air Conditioning Library by Modelon. In the experiment, differentmass flows on both sides of the heat exchanger will be applied.


44

Figure 3.45 Internal heat exchanger from the Air Conditioning Library by Modelon

3.5.2.1. File location

Both the FMU file and the Excel file used in this example can be found in the installation directory of FMI Add-In for Excel, in the folder: <installation directory>\Examples\AC\<FMI version>\<FMU kind>.

3.5.2.2. License requirements

This example can be run with a standard license or in demo mode. For more information about license features,see Section 2.5.1 in Chapter 2.



45

3.5.2.3. Running the example

1. Select the FMI tab in the Excel Ribbon and click the FMU button to open the file browser. Navigate to theheat exchanger FMU file that is located in <installation directory>\Examples\AC\<FMI version>\<FMUkind> folder and select "Open" to load the FMU.

2. In the Variables area, open a filter box by selecting the cell "Name". Search for the variable "init.mdot_init"and click "OK", see Figure 3.46. The variable "init.mdot_init" is the mass flow on both sides of the heatexchanger. We want to add this parameter to the experiment as indata. Accordingly, the value in the "Inlcudein" column is set to "indata". Press the button Filtered Variables->Add Filter to add the variable to thesimulation.

Figure 3.46 Filter for "init.mdot_init"

3. Add all top level output temperatures: "Tin_inner", "Tout_inner", "Tin_outer" and "Tout_outer" as outputsto the experiment. First, click the filter box in the cell Name and select "Clear Filter From "Name" " to clear thefilter. Now filter the Variable type column for the value "output". If it is possible to only filter for "parameter",make sure the filter is cleared in all columns. The Variables area should then look like in Figure 3.47 with 19top level outputs.


46

Figure 3.47 Filter for Causality output

4. Since we are only interested in the outputs with the unit Kelvin, K, filter the Unit column for the value K. Youshould now see 4 top level outputs.

5. Click the Filtered Variables->Add filter button to include the visible variables in the experiment. The valuein the Include column should now change from "FALSE" to "TRUE".

6. Set "Number of Cases" in the "Setup Simulation Sheet" ribbon group to 9.

7. Click the Create Simulation Sheet button.

8. Increase the "init.mdot_init" parameter by 0.005kg/s for each simulation case, starting at 0.01kg/s.

To set the parameter values, use the auto fill function. This is done by first entering 0.01 in the init.mdot_initcell for Case 1 and 0.015 for Case 2. This is used to initialize the auto fill function. Now select the two cells anddrag the little black box in the lower right corner of the selection to fill all 9 cases.


47

Figure 3.48 Configured simulation sheet with 9 cases

9. Click the Initialize button to start the initializations. The Results area should now be populated with results andeach initialization case message should read "OK", see Figure 3.49.

10.Create a plot like the one in Figure 3.50:

a. Select the Parmetrization and Final Values ranges together with the names as seen in Figure 3.49 by selectingone of the ranges and, while holding Ctrl, selecting the other ranges. The selected cells have a blue gradient."Tin_inner" is both selected and active, and is therefore white with a black border.


48

Figure 3.49 Selecting data ranges

b. Select the Insert tab in the Ribbon, then click on the Scatter with Smooth Lines that is found in the Scatterdrop down list in the "Charts" button group.

c. A plot is created, see Figure 3.50.


49

Figure 3.50 Top level output temperatures plotted against init.mdot_init

50

Chapter 4. ScriptingThe FMI Add-in enables the user to programmatically control the add-in through Visual Basic code in Excel.This can be used to create macros that e.g load FMUs, setup experiments or run batch simulations, automaticallywhen the macro is run from Excel. Macros and other Visual Basic functions can be used to automate tasks thatare repeatedly performed.

There are license restrictions on using the VB functions. See Table 4.1 for an overview of all functions and corre-sponding license requirement.

4.1. Getting started

This tutorial demonstrates how to run a macro from Excel that loads an FMU, creates a Simulation sheet and finallysimulates the experiment. The tutorial is divided in two parts, Section 4.1.2 and Section 4.1.3, where the first partdemonstrates the steps needed to enable the FMI Add-in functions in a workbook and the second part demonstrateshow the FMI Add-in code is called in a user defined macro.


This example can be run with a standard license or in demo mode. For more information about license features,see Section 2.5.1.


4.1.2. Enable FMI Add-in functions in a workbook

1. Open Excel and make sure that the FMI tab is loaded in the Ribbon.

2. Open the already existing workbook <installation folder>\Examples\FMIAddInScript.xlsm from insideExcel with "File" -> "Open".

3. Open the Visual Basic Editor in Excel.

The Visual Basic editor is opened from the Developer tab with the Ribbon button Visual Basic, see Figure 4.1.If the Developer tab is not available, go to http://msdn.microsoft.com/en-us/library/vstudio/bb608625.aspx formore information on how to make it visible.

Scripting

51

Figure 4.1 Developer tab

4. Goto "ThisWorkbook" in FMIAddInScript.xlsm, select all code and copy it, see Figure 4.2.

This is the code that enables the FMI Add-in functions in Visual Basic. Some examples are also included, locatedat the bottom of the file, that may be left out. To continue this tutorial, the macro example "FMIExample1" mustbe copied.

Figure 4.2 Selecting code and copying

Scripting

52

5. Create a new workbook in Excel by selecting "File" and then "New".

6. Paste the content in the Visual Basic editor in the "ThisWorkbook" project for the newly created workbook,see Figure 4.3.

Figure 4.3 Pasting code into "ThisWorkbook"

7. Close the FMIAddInScript.xlsm workbook.

The newly created workbook can now call the FMI Add-in functions.

4.1.3. Run example

In the previous section, code was copied that enabled the FMI Add-in functions to be called from macros. Thecopied code also included some macro examples. One of the examples, "FMIExample1", will be used in this section.

1. Run the "FMIExample1" macro.

In Excel, go to the Developer tab, click the Macros button or press ALT + F8 to open the "Macro" dialog box,see Figure 4.4. Select "ThisWorkBook.FMIExample1" and click the Run button.

Scripting

53

Figure 4.4 Macro dialog in Excel

The code for theVisual Basic macro "FMIExample1" is shown below. This example macro was included in thecode that was copied into the new workbook in the previous section.

Public Sub FMIExample1()Dim fmuFile As StringfmuFile = FMIGetInstallationFolder & "Examples\Furuta\1.0\cs\Furuta.fmu"

' Create an FMU sheet and include all variablesFMILoadFMU fmuFile, True, vbNullString

' Include all variables in the experimentFMISetFilterButton ActiveSheet, True

' Create Simulation sheet with 1 simulation caseFMICreateExperiment ActiveSheet, vbNullString, 1

' Simulate or initialize the experimentIf Range("Exp_FMUKind").Value2 = "CoSimulation_StandAlone" ThenFMISimulateButtonElseFMIInitializeButtonEnd IfEnd Sub

2. Two sheets should now have been created, one FMU sheet, see Figure 4.5, and one Simulation sheet, see Fig-ure 4.6. The experiment should be populated with simulation results.

Scripting

54

Figure 4.5 Macro generated FMU sheet

Scripting

55

Figure 4.6 Macro generated Simulation sheet

4.2. UsageIn the file <installation folder>\Examples\FMIAddInScript.xlsm, the Visual Basic code for calling the FMIAdd-in functions can be found. This code must be copied into the workbook or worksheet from which the FMIAdd-in functions should be called, see Section 4.1.2. Note that this code includes some examples at the bottomthat do not need to be copied.

Error messages can be extracted in VBA by for example:

On Error GoTo HandleError

Scripting

56

Application.DisplayAlerts = False ' Do some operation here Application.DisplayAlerts = True HandleError: MsgBox Err.Description

4.2.1. Functions

A list of all FMI Add-in functions with a short description and license requirement are found in Table 4.1. Formore information, go to the FMI Add-in code in <installation folder>\Examples\FMIAddInScript.xlsm.

Table 4.1 FMI Add-in functions

Function Short description Required license feature

FMIGetVersion Returns the version of the FMI Add-in standard, runtime, demoa

FMIUpdateSheet Updates the FMU sheet or Simulation sheet standard, runtime, demoa

FMIIsLicenseCheckedOut Returns the licence status standard, runtime, demoa

FMIGetCreateResults Returns checkbox status for Create Results in the Rib-bon


FMISetCreateResults Sets the checkbox status for Create Results in the Rib-bon


FMIGetShowResults Returns checkbox status for the Show Results in theRibbon


FMISetShowResults Sets the checkbox status for Show Results in the Rib-bon


FMIGetShowLogs Returns checkbox status for the Show Logs in the Rib-bon


FMISetShowLogs Sets the checkbox status for Show Logs in the Ribbon standard, runtime, demoa

FMICreateExperiment Creates a Simulation sheet standard, demoa

FMILoadFMU Creates a new FMU sheet standard, demoa

FMISetFilterButton Sets the Include column values for the current visiblevariables in the FMU sheet

standard, demoa

FMISetSelectionButton Sets the Include column values for the current selectedvariables in the FMU sheet

standard, demoa

FMISimulateButton Calls the Simulate button in the Ribbon standard, runtime, demoa

FMIInitializeButton Calls the Initialize button in the Ribbon standard, runtime, demoa

FMISimulate0 Starts a simulation (long input argument list) standard, demoa

FMIInitialize0 Starts an initialization (long input argument list) standard, demoa

Scripting

57

Function Short description Required license feature

FMISimulate1 Starts a simulation (short input argument list) standard, demoa

FMIInitialize1 Starts an initialization (short input argument list) standard, demoa

aFunction is available in demo mode (when no license feature is checked out) but usage is restricted to the example FMUs that come withthe FMI Add-In for Excel installation.

58

Chapter 5. Upgrading Workbooks5.1. Update sheetWhen new versions of the FMI Add-in are released, FMU sheets and Experiments sheets generated with olderFMI Add-ins may not be compatible with new versions. The Visual Basic function FMIUpdateSheet includedin the add-in can be used to update sheets1. Note there is an example macro "FMIExampleUpdateActiveSheet"in <installation folder>\Examples\FMIAddInScript.xlsm that uses FMIUpdateSheet to update the currentactive sheet.

For more information on how to call an FMI Add-in function from a macro, see Chapter 4.

Before updating any file, make sure to create a backup file!

If FMI Add-in reports an error after the sheet has been updated, the recommend solution is to recreate the sheetusing the new version of FMI Add-in.

5.1.1. Specific version updates

Updates that require extra explanation are listed in the sections below.

5.1.1.1. From version 1.3.8 to version 2.0

There is no update function for updating a sheet to version 2.0 from any previous version of the sheet. Trying toperform the update will result in an error message. The recommended solution is to recreate the sheet using thenew version of FMI Add-in.

5.1.1.2. From version 1.2.1 to 1.3

In FMI Add-In for Excel version 1.3, a new license feature, runtime, is introduced. Users holding a runtime licensefeature may only use simulation sheets that have been created by a user with a standard license feature. An sim-ulation sheet is verified with a checksum which is generated when creating and saving the sheet. As a standardlicense feature is required to generate a checksum, a runtime license feature user can not update workbooks fromversion 1.2.1 to 1.3.

The following steps are required to update a workbook from version 1.2.1 to 1.3:

• A standard license feature for FMI Add-In for Excel (FMI_ADDIN_EXCEL) must be checked out.

• Update sheet with the Visual Basic function FMIUpdateSheet as described above. The checksum rows will begenerated in this step.

1Observe that it is not possible to update to version 2.0 from any previos version of the sheet, see Section 5.1.1.1.

Upgrading Workbooks

59

• Save the updated sheet. The checksum will be generated when saving.

60

Chapter 6. LimitationsThis page lists the current limitations of the FMI Add-In for Excel.

• There is a limited number of columns and rows in Excels worksheets which limit the number of simulation casesthat can be run. Excel 2007, 2010, 2013, and 2016 is limited to 1,048,576 rows and 16,384 columns.

• Input trajectories for variables with data type String are not supported.

• Output variables with data type String are not supported.

• Loading and simulating FMUs are not possible if their path contains non (extended) ASCII characters. Forexample, an FMU on a path containing Chinese characters will not work.

61

Chapter 7. License installation

7.1. Retrieving a license fileThere are different types of license models that can be used with Modelon products.

• Node-locked (No license server required)

This license enables use on a single computer. The license cannot be moved from one computer to another. Thelicense is locked for use on a computer with a specific MAC address.

• Server (Requires a license server)

This licensing model represents a classic network configuration with a server and users. The server grants ordenies requests from computers in the network to use a program or feature. The license file specifies the maxi-mum number of concurrent users for a program or feature. There is no restriction for which computer is usingthe program or feature, only in the number of programs and features that can be used simultaneously.

The computer on which the server is running cannot be changed. The server computer's MAC address must beprovided to Modelon to generate the license file.

• Evaluation license (Node Locked)

This license enables a program or feature for a limited amount of time and is the same as a node-locked license.

Please contact the Modelon sales department at <[email protected]> to purchase a license or to get an evaluationlicense. In order to obtain a license file for a node-locked license, you must provide the MAC address of yourcomputer. If you are using a license server, you must provide the MAC address of the server. In Section 7.1.1below, you will find instructions for how to retrieve the MAC address of a computer.

7.1.1. Get MAC address

Modelon uses the Ethernet address (MAC address), also called the host ID, to uniquely identify a specific computer.Therefore, you must provide the MAC address of the computer on which you want to use the program or feature.For a server license, the MAC address for the server computer is required, not all the client computers in the networkthat will use the program or feature. For a node-locked license, the MAC address of the computer on which thelicense will be used must be provided.

Note: Modelon only allows ONE MAC address for each computer. Please disable and unplug all network devicesthat are not permanently connected to the computer such as laptop docking stations, virtual machines and USBnetwork cards.

License installation

62

• Windows

1. Open cmd

Windows 7 and Vista

a. Click the Start button

b. Type cmd in the search bar and press enter.

Windows XP

a. Click the Start button.

b. Click on Run....

c. Type cmd in the text box and click OK.

2. Run lmhostid.exe.

Type the full path to lmhostid.exe within quotes and press enter. lmhostid.exe is normally located in <in-stallation folder>\license_tools\lmhostid.exe.

3. Use this hostid when you are in contact with Modelon. If multiple hostids are listed, select one that is perma-nent for the computer.

Figure 7.1 Lmhostid.exe run on Windows listing the computer's MAC address.

• Unix

1. Open a terminal and change directory to the <installation folder>/license_tools/.


63

Run lmhostid and use the hostid listed when you are in contact with Modelon. If multiple hostids are listed,select one that is permanent for the computer.

7.2. Install a license

After purchasing a license, you should receive a license file with the file extension *.lic. This file must be putin a specific folder for the application to find it.

7.2.1. Installing a node-locked license

7.2.1.1. Windows

1. Close the application if it is already running.

2. Open the Application Data folder.

Windows 7 and Windows Vista


b. Type shell:AppData in the search bar and press enter.

Windows XP


b. Click on Run....

c. Type shell:AppData in the text box and click OK.

3. The Application Data folder should now be open. Check that its path is of the form C:\Users\YourUser-Name\AppData\Roaming.

4. Create the folder Modelon\Licenses\Nodelocked if it does not exist already.

5. Put your license file in the folder Nodelocked.

7.2.1.2. Unix

• Copy your license file to the folder <installation folder>\Licenses\Nodelocked.


64

7.2.1.3. Updating the license

To update the license file, you should overwrite the old license file with the new one. Ensure that the old license fileis overwritten or removed from the folder since it may otherwise be used instead of the new one, and the applicationmay fail to check out a license. Note that you must restart the program for license changes to take effect.

7.2.2. Installing a server license

Note that these are not instructions for installing a license file on a server. These are instructions for the end userof the program or feature. The assumption is that the server is already up and running and that the IP address to theserver and the port number is already known. The IP address and the port number, if needed, should be providedby the license server administrator.

The application can connect to the license-server and daemon either by reading a license file or an environmentvariable.

7.2.2.1. Windows

1. Close the application if it is already running.

2. Create an empty text file



b. Type Notepad in the search bar and press enter.

Windows XP


b. Click on Run....

c. Type Notepad in the text box and click OK.

3. Configure the license file.

a. Copy the following text in to the text document

SERVER <ip-address> ANY <port>USE_SERVER

b. Change <ip-address> to the IP address of the server.


65

c. Change <port> to the port number that is being used. If you do not have a port number, you can removethe whole <port>. For example, the license file should look like the following for a license server withIP address 192.168.0.12 using port 1200.

SERVER 192.168.0.12 ANY 1200USE_SERVER

d. Save the file with a filename with the extension *.lic in a temporary place. The file will be moved in alater step. You can now close Notepad.

4. Open the Application Data folder.



b. Type shell:AppData in the search bar and press enter.

Windows XP


b. Click on Run....

c. Type shell:AppData in the text box and click OK.

The Application Data folder should now open.

5. Create the folder Modelon\Licenses\Server if it does not exist already.

6. Put the license file you just created in the folder Server.

7.2.2.2. Unix

1. Close the program if it is already running.

2. Create an empty file with the file extension name *.lic.

3. Configure the license file.

a. Copy the following text in to the text document

SERVER <ip-address> ANY <port>USE_SERVER

b. Change <ip-address> to the IP address of the server.


66

c. Change <port> to the port number that is being used. If you do not have a port number, you can removethe whole <port>. For example, the license file should look like the following for a license server withIP address 192.168.0.12 using port 1200.

SERVER 192.168.0.12 ANY 1200USE_SERVER

4. Copy your license file to the folder <installation folder>\Licenses\Server.

7.2.2.3. Using the environment variable

An alternative to specify how the application should connect to the license server is to set the environment variableMODELON_LICENSE_FILE. The value can be set to port@host, where port and host are the TCP/IP port numberand host name from the SERVER line in the license file. Alternatively, use the shortcut specification, @host, if thelicense file SERVER line uses a default TCP/IP port or specifies a port in the default port range (27000–27009).

7.2.2.4. Updating the license

To update the license file, you can either redo the installation instructions described above or make the changesin the license file directly. Ensure that the old license file is overwritten or removed from the folder since it mayotherwise be used instead of the new one, and the application may fail to check out a license. Note that you mustrestart the program before the changes can take effect.

7.3. Installing a license serverTo install a license server, you must have a server license file. Please contact <[email protected]> to obtainthe server license file. This license file must also be configured prior to use by by setting the IP address and portas shown in Section 7.3.1

Modelon products use a licensing solution provided by Flexera Software. It is recommended that you install thelatest version of the server software, which is available from http://learn.flexerasoftware.com/content/ELO-LM-GRD . Modelon products require a license server version number v11.10.0.0 or later. A license server and a licensedaemon are required and are distributed with the product you are installing. If you have not received the serverapplication or license daemon with your product, please contact <[email protected]>.

The following step by step instructions for installing a license server assume that no other Flexera license serveris already installed.

7.3.1. Configure the license file

When a license server is installed, the server needs a license file provided by Modelon. This file must be configuredbefore it can be used.

http://learn.flexerasoftware.com/content/ELO-LMGRD

http://learn.flexerasoftware.com/content/ELO-LMGRD


67

1. Open the license file in a text editor. The file may look like the example below:

SERVER 192.168.0.1 080027004ca5 25012VENDOR modelonFEATURE FMI_TOOLBOX modelon 1.0 3-feb-2012 12 SIGN="0076 305..."

2. Edit the SERVER line where the IP address, 192.168.0.1, should be replaced with the IP address of theserver. Also change the port address, 25012, to the desired port or remove it to use default ports. The IPaddress and potentially also the port address should be provided to the end users so they can configure theirlicense files to connect to the server.

7.3.2. Installation on Windows

In the <installation folder>\license_tools folder that is distributed with your product, you will find thefiles listed below.

The listed files are used to set up and configure the license server.

• lmgrd.exe (license server)

• modelon.exe (license daemon)

• lmutils.exe (configure- and utility functions)

• lmtools.exe (Windows GUI for setting up the license server as a Windows service)

To configure a license server manager (lmgrd) as a service, you must have Administrator privileges. The servicewill run under the LocalSystem account. This account is required to run this utility as a service.

1. Make sure that license daemon modelon.exe is in the same folder as the license server, lmgrd.exe.

2. Run lmtools.exe

3. Click the Configuration using Services button, and then click the Config Services tab.

4. In the Service Name, type the name of the service that you want to define, for example, Modelon LicenseServer.

5. In the Path to the lmgrd.exe file field, enter or browse to lmgrd.exe.

6. In the Path to the license file field, enter or browse to the server license file.

7. In the Path to the debug log file, enter or browse to the debug log file that this license server should write.Prepending the debug log file name with the + character appends logging entries. The default location for thedebug log file is the c:\winnt\System32 folder. To specify a different location, be careful to specify a fullyqualified path.


68

8. Make this license server manager a Windows service by selecting the Use Services check box.

9. Optional. Configure the license server to start at system startup time by selecting the Start Server at PowerUp check box.

10.To save the new Modelon License Server service, click Save Service.

Figure 7.2 Setup the license server with lmtools.exe

11.Click the Service/License File tab. Select the service name from the list presented in the selection box. In thisexample, the service name is Modelon License Server.

12.Click the Start/Stop/Reread tab.

13.Start Modelon License Server by clicking the Start Server button. Modelon License Server license serverstarts and writes its debug log output to the file specified in the Config Services tab.

7.3.3. Installation on Unix

In the <installation folder>\license_tools folder that is distributed with the product, you can find the fileslisted below.

• lmgrd (license server)

• modelon (license daemon)


69

• lmutil (configure- and utility functions)

Before you start the license server, lmgrd, make sure that license daemon modelon is in the same folder.

Start lmgrd from the UNIX command line using the following syntax:

lmgrd -c license_file_list -L [+]debug_log_path

where license_file_list is either the full path to a license file or a directory containing license files where allfiles named *.lic are used. If the license_file_list value contains more than one license file or directory, they mustbe separated by colons. debug_log_path is the full path to the debug log file. Prepending debug_log_path withthe + character appends logging entries.

Starting lmgrd from a root account my introduce security risks, and it is therefore recommended that a non-rootaccount is used instead. If lmgrd must be started by the root user, use the su command to run lmgrd as a non-privileged user:

su username -c "lmgrd -c license_file_list -l debug_log_path"

Ensure that the vendor daemons listed in the license file have execute permissions for username.

7.4. License borrowingLicense borrowing allows users to check out features from a license server for offline use for a limited period oftime. License borrowing is only enabled if it was specified in the license order. If you would have a server licenseand want to enable license borrowing, contact <[email protected]>.

7.4.1. Borrowing licenses for offline use

License borrowing is initiated with the lmborrow utility in lmutil, distributed with your modelon product. Licenseborrowing must be initiated while having a connection to the license server. lmborrow is invoked called from thecommand line, and the command syntax is

lmutil lmborrow modelon enddate [endtime]

The end date specifies for how long the license should be borrowed, and is on the form dd-mmm-yyyy, e.g. 01-dec-2016. The end time of the borrow period is optional, and if given it should be on the form hh:mm. If no endtime is specified, it defaults to 23:59, meaning that the license is borrowed for the full duration of the end date.

The default limit on the borrow time for Modelon products is 420 hours (2.5 weeks) from when license borrowingis initiated. License administrators may lower this limit, but it cannot be increased.

Once license borrowing is initiated, and until the end of the day that it is initiated, any license for a Modelon productthat is checked out will be borrowed for offline use until the end of the specified borrow period. Each license willbe borrowed only once even if it is checked out multiple times after initiating license borrowing.


70

In order to prevent borrowing of licenses that are not needed, the borrow status should be cleared after checkingout the licenses you need. As with initiating borrowing, clearing it is done with the lmborrow utility by issuingthe command

lmutil lmborrow -clear

Clearing the borrow status does not return any borrowed licenses.

To see which licenses are currently borrowed on your system, run the command

lmutil lmborrow -status

This will display all licenses currently borrowed, along with the end dates for their borrow periods.

7.4.2. Returning a borrowed license

Borrowed licenses can be returned before the specified end date by running

lmutil lmborrow -return featurename

featurename is the name of the specific feature in the license file, as shown by lmborrow -status. A singleproduct can contain multiple features, which have to be returned separately. Note that a connection to the licenseserver must exist in order to return borrowed licenses.

7.4.3. Options for the Vendor Daemon

The following options for the vendor daemon can be used to configure license borrowing.

7.4.3.1. BORROW_LOWWATER

Specifies a number of licenses that can not be borrowed. This will ensure that there are always at leastBORROW_LOWWATER licenses to use on the license server.

The option syntax is

BORROW_LOWWATER feature n

where feature is the name of the feature to limit and n is the amount of non-borrowable licenses for that feature.

7.4.3.2. EXCLUDE_BORROW

Specify a user or group who can not borrow licenses for a certain feature. EXCLUDE_BORROW takes precedenceover INCLUDE_BORROW, meaning that in case conflicting options for inclusion and exclusion are set, the onesfor exclusion will be used.



71

EXCLUDE_BORROW feature type name

where feature is the feature to prevent user(s) from borrowing, type is one of USER, HOST, DISPLAY, INTER-NET, PROJECT, GROUP or HOST_GROUP, and name is the name of the item to be excluded.

7.4.3.3. INCLUDE_BORROW

Specify a user or group who can borrow licenses for a certain feature. If options specified here conflict with thosefor EXCLUDE_BORROW, the options for exclusion are used.

The option syntax is the same as for EXCLUDE_BORROW.

7.4.3.4. MAX_BORROW_HOURS

Set the longest allowed borrow period. The default for Modelon products is 420 hours (2.5 weeks), and it is onlypossible to specify a lower max value than this.


MAX_BORROW_HOURS feature n

where feature is the feature to set a borrow period limit for, and n is the limit, in hours.

7.5. Troubleshooting license installation

If you experience any problems with the license, the error messages are usually descriptive enough to provide hintsas to the root cause of the problem. If the problem persists, please contact Modelon at <[email protected]>.Before contacting Modelon, support you should run lmdiag and provide the resulting information. Follow theinstructions below to run lmdiag.

7.5.1. Running lmdiag

• Windows

1. Open cmd

Windows 7 and Vista


b. Type cmd in the search bar and press enter.

Windows XP


72


b. Click on Run....

c. Type cmd in the text box and click OK.

2. Run lmdiag.exe.

Type the full path to lmdiag.exe within quotes and press enter. lmdiag.exe is normally located in <in-stallation folder>\license_tools\lmdiag.exe.

• Unix

• Open a terminal and change directory to the <installation folder>/license_tools/.

Run lmdiag with the ./lmutil lmdiag command.

Note: lmutil requires LSB (Linux Standard Base) compliance to run. Some distributions, e.g. Ubuntu, do nothave LSB compliance by default and can thus not run the program. ./lmutil then fails with a message like

$> ./lmutil lmdiag bash: ./lmutil: No such file or directory

If this error occurs, please check if the required interpreter is installed on your system. The requirement can befound with the readelf command, and the output should look similar to

$> readelf -a lmutil | grep interpreter [Requesting program interpreter: /lib64/ld-lsb-x86-64.so.3]

LSB should be available for install through a package manager. If installing it is not an alternative, a quick fixis to symlink the required interpreter to the one on your system, i.e.

$> ln -s <your ld> <required ld>

Note 2: FlexLM requires that network devices are named eth0, eth1, etc. When other names are used, lmhostidwill always return 0 as host ID. Device names can be shown with the ifconfig command. If your Linux distri-bution uses a different naming scheme, it needs to be changed. The steps to change the naming scheme dependon the distribution and release.

73

Chapter 8. Release notes8.1. Release 2.0.1• Made FMU simulation more robust.

• Removed numerical error affecting communicationStepSize.

• Increased robustness when dealing with non-compliant FMUs.

• Fixed bug where FMUs with multiple DLLs for one platform could not be simulated.

• Fixed broken script example found at <installation folder>\Examples\FMIAddInScript.xlsm

• Added log message for when the call to an FMUs doStep function fails during simulation.

8.2. Release 2.0• Support for loading and simulating 2.0 FMUs.

• It is now possible to simulate FMUs containing 64-bit Windows binaries. Both 32- and 64-bit FMUs can besimulated in both the 32- and 64-bit FMI Add-In for Excel distributions. If an FMU contains both 32- and 64-bit binaries the 32-bit binary will be used for simulation.

• New Ribbon design with improved usability and added features.

• Added new Add case and Remove case buttons.

• Number of processes are now in the Ribbon rather than the Simulation sheet.

• It is now possible to specify the number of cases that will initially be in a created Simulation sheet.

• New sheet styles and layouts with improved presentation of data and usability. Upgrading from Sheets generatedby earlier version is not supported.

• Color coding now clearly mark which cells the user is encouraged to interact with.

• Headers and better layout clearly separates different areas.

• And much more.

• It is now possible to create plots for an Simulation sheet using the new Create plot button in the Ribbon.

Release notes

74

• No need to save Simulation sheet before simulation or initialization. If saved, the old behavior with usingthe workbooks directory as current directory for simulation and initialization is used. If unsaved, a temporarydirectory is used.

• Changed default values for the experiment column in the FMU sheet for 1.0 FMUs:

• constants cannot be indata by default.

• discrete locals are at least outdata by default.

• inputs are not outdata by default.

• Script functions have input that is no longer used:

• inputTypes in FMIInitialize0 and FMISimulate0 is unused.

• Fixed bug where running an experiment with an FMU on a path with extended ASCII characters failed. Forexample, the path "C:/User/René/myFMU.fmu" will now work if used in the Simulation sheet.

• Pop-ups are no longer produced by FMI Add-In when the Excel flag Application.DisplayAlerts is set tofalse.

8.3. Release 1.3.8• Fixed FMI Add-In for Excel to not require MSVCR100D.dll

8.4. Release 1.3.7• Added FMI Add-In for Excel installer for 64-bit Excel.

• Removed data validation with drop-down menu for boolean values.

8.5. Release 1.3.6• Fixed bug with missing FMIAddInScript.xlsm.

8.6. Release 1.3.5• Simulation or initialization is now performed with current directory set to the workbook directory. This should

simplify the look up of external data in the FMU, that relays on current directory. The workbook must nowalways be saved before any simulation or initialization is run.

• Temporarily tries to unprotect a protected experiment sheet before a simulation or initialization is run, and beforethe workbook is saved.

Release notes

75

8.7. Release 1.3.4• Updated installer to not require running in elevated mode unless any of the prerequisites is missing and requires

elevated mode to be installed.

8.8. Release 1.3.3• Fixed bug with locale dependent expiry date.

8.9. Release 1.3.2• Fixed bugs in the updating script and in loading invalid FMUs.

8.10. Release 1.3.1• Simulation results now includes the result point at initial time.

8.11. Release 1.3• Introduced new license feature: runtime (FMI_ADDIN_EXCEL_RUNTIME). With this license feature, users can per-

form simulations, parameter sweeps, etc and use a restricted set of the API macro functions. For more informa-tion, see Section 2.5.1 in chapter Chapter 2.

• Introduced possibility to set an experiment expiry date.

• Changed license checkout procedure. The license will now be checked out when the user starts working withFMI Add-In for Excel, rather than at startup of Excel.

8.12. Release 1.2.1• Fixed problem with loading FMUs containing external DLL files.

8.13. Release 1.2• Support for calling the add-in functions from Visual Basic script in Excel.

• Simulation timeout time can now be specified for each case in the Experiment sheet.

8.14. Release 1.1.2• Fixed problem with parsing input trajectory values.

Release notes

76

• Fixed problem with long simulations causing Excel to display the dialog message: Excel is waiting for anotherapplication to complete an OLE action.

8.15. Release 1.1.1• Changed simulation timeout time from 100s to infinity.

8.16. Release 1.1• Parallel simulation and initialization support.

• Excel sheets based on named ranges.

• The FMU path in the Experiment sheet can be an absolute path or a relative path.

• New example added, a heat exchanger for steady-state computation that uses the initialization functionality toperform a parameter sweep.

8.17. Release 1.0.1• FMI Add-In is built with FMI Library 2.0a2 to fix bugs.

8.18. Release 1.0Initial release:

• Simulation of Co-Simulation FMUs supported.

• Initialization of Model Exchange FMUs supported.

• Input trajectories supported.

• Final simulation and initialization results are written to the experiment sheet.

• Simulation for Co-Simulation FMUs generates a result sheet with output trajectories.

fmi add-in for excel user's guide 2.0...before uninstalling fmi add-in close all instances of...

Documents