Fmi Add-in For Excel User`s Guide 1.3.8

Transcript

FMI Add-In for Excel User's Guide 1.3.8 FMI Add-In for Excel User's Guide 1.3.8 Publication date 2017-02-20 Copyright © 2017 Modelon AB Ideon Science Park SE-22370 LUND Self publishing ALL RIGHTS RESERVED. This document contains material protected under International Copyright Laws and Treaties. Any unauthorized reprint or use of this material is prohibited. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, or by any information storage and retrieval system without express written permission from the author / publisher. Table of Contents 1. Introduction .............................................................................................................................. 1 1. The FMI Add-In for Excel .................................................................................................. 1 1.1. Supported FMI standards .......................................................................................... 1 2. The Functional Mock-up Interface and FMUs ......................................................................... 1 2. Installation ................................................................................................................................ 4 1. Supported platforms ........................................................................................................... 4 2. Prerequisites ...................................................................................................................... 4 3. Installing FMI Add-In for Excel ........................................................................................... 4 4. Uninstalling FMI Add-In for Excel ....................................................................................... 5 5. License ............................................................................................................................ 5 5.1. License installation .................................................................................................. 5 5.2. License features ...................................................................................................... 5 5.3. Activating the license feature ..................................................................................... 5 5.3.1. First time configuration .................................................................................. 5 5.3.2. Activating and deactivating a license feature ...................................................... 7 5.3.3. Changing a license feature .............................................................................. 8 5.4. Demo mode ............................................................................................................ 8 6. Support ............................................................................................................................ 8 3. Simulation and Initialization ........................................................................................................ 9 1. Overview of the FMI Add-In for Excel .................................................................................. 9 1.1. License requirements overview .................................................................................. 9 2. Getting started ................................................................................................................. 10 2.1. License requirements .............................................................................................. 10 2.2. Introductory tutorial ............................................................................................... 10 3. The FMU sheet ................................................................................................................ 20 3.1. License requirements .............................................................................................. 20 3.2. Load FMU ............................................................................................................ 20 3.3. FMU sheet areas .................................................................................................... 20 3.3.1. The Model area ........................................................................................... 21 3.3.2. The Variables area ....................................................................................... 23 3.4. Create Experiment ................................................................................................. 25 3.4.1. Default Values of the Experiment column ........................................................ 28 3.5. Filtering ............................................................................................................... 28 4. The Experiment sheet ........................................................................................................ 29 4.1. License requirements .............................................................................................. 29 4.2. Simulation cases .................................................................................................... 29 4.2.1. Named ranges ............................................................................................. 31 4.2.2. Number of simulation cases .......................................................................... 31 4.2.3. Add a simulation case .................................................................................. 32 4.2.4. Delete a simulation case ............................................................................... 33 iii FMI Add-In for Excel User's Guide 1.3.8 4. 5. 6. 7. 4.2.5. Disabling/Enabling simulation cases ................................................................ 4.3. Experiment sheet areas ........................................................................................... 4.3.1. The Model area ........................................................................................... 4.3.2. The Settings area ......................................................................................... 4.3.3. The Indata area ........................................................................................... 4.3.4. The Outdata area ......................................................................................... 4.4. Setting values and input trajectories .......................................................................... 4.5. Simulation and Initialization .................................................................................... 4.5.1. Simulate FMU ............................................................................................ 4.5.2. Initialize FMU ............................................................................................ 4.5.3. Create Results ............................................................................................. 4.5.4. Show results and Show logs .......................................................................... 5. Examples ........................................................................................................................ 5.1. Batch simulation of the Robot 3D model .................................................................... 5.1.1. File location ............................................................................................... 5.1.2. License requirements .................................................................................... 5.1.3. Running the example ................................................................................... 5.2. Batch initialization of Heat Exchanger ....................................................................... 5.2.1. File location ............................................................................................... 5.2.2. License requirements .................................................................................... 5.2.3. Running the example ................................................................................... Scripting ................................................................................................................................. 1. Getting started ................................................................................................................. 1.1. License requirements .............................................................................................. 1.2. Enable FMI Add-in functions in a workbook .............................................................. 1.3. Run example ......................................................................................................... 2. Usage ............................................................................................................................. 2.1. Functions .............................................................................................................. Upgrading Workbooks .............................................................................................................. 1. Update sheet .................................................................................................................... 1.1. Specific version updates .......................................................................................... 1.1.1. From version 1.2.1 to 1.3 .............................................................................. Limitations .............................................................................................................................. License installation ................................................................................................................... 1. Retrieving a license file ..................................................................................................... 1.1. Get MAC address .................................................................................................. 2. Install a license ................................................................................................................ 2.1. Installing a node locked license ................................................................................ 2.1.1. Windows .................................................................................................... 2.1.2. Unix .......................................................................................................... 2.1.3. Updating the license .................................................................................... 2.2. Installing a server license ........................................................................................ iv 33 33 35 35 36 37 37 38 38 39 39 39 39 39 40 40 40 45 46 46 47 52 52 52 52 54 57 57 59 59 59 59 60 61 61 61 63 63 63 63 63 64 FMI Add-In for Excel User's Guide 1.3.8 2.2.1. Windows .................................................................................................... 2.2.2. Unix .......................................................................................................... 2.2.3. Using the environment variable ...................................................................... 2.2.4. Updating the license .................................................................................... 3. Installing a license server ................................................................................................... 3.1. Configure the license file ........................................................................................ 3.2. Installation on Windows .......................................................................................... 3.3. Installation on Unix ................................................................................................ 4. Troubleshooting license installation ..................................................................................... 4.1. Running lmdiag ..................................................................................................... 8. Release notes ........................................................................................................................... 1. Release 1.3.8 ................................................................................................................... 2. Release 1.3.7 ................................................................................................................... 3. Release 1.3.6 ................................................................................................................... 4. Release 1.3.5 ................................................................................................................... 5. Release 1.3.4 ................................................................................................................... 6. Release 1.3.3 ................................................................................................................... 7. Release 1.3.2 ................................................................................................................... 8. Release 1.3.1 ................................................................................................................... 9. Release 1.3 ...................................................................................................................... 10. Release 1.2.1 ................................................................................................................. 11. Release 1.2 .................................................................................................................... 12. Release 1.1.2 ................................................................................................................. 13. Release 1.1.1 ................................................................................................................. 14. Release 1.1 .................................................................................................................... 15. Release 1.0.1 ................................................................................................................. 16. Release 1.0 .................................................................................................................... v 64 65 65 66 66 66 66 68 69 69 71 71 71 71 71 71 71 71 72 72 72 72 72 72 72 73 73 Chapter 1. Introduction 1. The FMI Add-In for Excel The FMI Add-In for Excel integrates FMI-based parallel simulations in Excel. The add-in offers the following main features: • Running simulations of compiled dynamic models, FMUs. The FMUs may be generated by any FMI-compliant tool such as Dymola, OPTIMICA Studio by Modelon or SimulationX. • Taking advantage of powerful features in Excel to set up and perform batch simulations for parameter sweeps and simulations driven by data series. • Performing dynamic simulations or solve initialization problems, in parallel. 1.1. Supported FMI standards The FMI Add-In for Excel supports both FMI for Model Exchange 1.0 and FMI for Co-Simulation 1.0. 2. The Functional Mock-up Interface and FMUs The Functional Mock-up Interface (FMI) is a standard for exchange of compiled dynamic models and is intended to promote 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: FMI for Model (FMI-ME) Exchange The FMI-ME specification is based on a continuous-time hybrid Ordinary Differential Equation (ODE) representation. The FMU-ME provides inputs and outputs, exposing functions for setting parameters and computing the derivatives of the ODE. The FMI Add-In for Excel supports initialization of FMUMEs. FMI for Co-Simulation (FMICS) The FMI-CS specification provides a model representation where both the model and an integrator (ODE solver) are encapsulated in the FMU-CS. Similar to the FMI-ME, the FMU-CS provides inputs and outputs and means to set model parameters. It also provides a function to integrate the dynamics of the model for a specified time interval. The FMI Add-In for Excel supports dynamic simulation and initialization of FMU-CS. An FMU is a zip archive that contains a platform specific binary file, model metadata in an XML file and optional additional resource data. The metadata file specifies general model information such as the name of the model and when it was generated. It also specifies all the variables and parameters and how they may be used. A variable or parameter is referred to as a ScalarVariable in the FMI standard. In the listing below, a snippet from a metadata 1 Introduction file shows two ScalarVariables. This is an example of how the information about the model is exposed to the FMI tool that is importing the model, e.g, the FMI Add-In for Excel. The ScalarVariable element contains attributes and elements such as the data type, variable name, causality and variability. Some of the attributes have default values and are therefore not visible in the XML metadata file. Short descriptions of the most important attributes are given in Table 1.1. These attributes and their corresponding values are used in the FMI Add-In for Excel. Table 1.1 FMI attributes FMI attribute Description start Initial value of a variable. A start value can be changed before initialization (not allowed for variability set to "constant"). All constants, independent parameters and inputs of the FMU must have a start value in the XML metadata file. Parameters that do not have a start value are computed during initialization, e.g. as functions of other parameters). fixed Defines the meaning of the attribute start, if causality is not "input". This attribute is present if start is present. If fixed set to "true" the variable has this value after initialization. If fixed set to "false", start is used as an initial guess value and the variable is used as iteration variable during initialization. After initialization, the variable can have a different value than start in this case. causality Defines the causality of a variable. It is set to one of the following 4 values: input, output, internal or none. With causality set to "input", a value can be provided from the outside. Initially, the value is set to its start value (see above). For causality set to "output", the variable can be used in a connection. With causality set to "internal" after initialization it is only allowed to read a value, e.g., to store the value in a result file. It is not allowed to use this value in a connection. Before initialization, start values can be set. For causality set to "none" 2 Introduction FMI attribute variability Description the variable does not influence the model equations. It is a tool specific variable to, e.g., switch certain logging or storage features on and off. Defines when the value of the variable changes. It is set to one of the following 4 values: constant, parameter, discrete or continuous. If variability is set to "constant" this means that the value of the variable is fixed and does not change. For variability set to "parameter" the value of the variable does not change after initialization. A variable with variability set to "discrete" the value of the variable only changes during initialization and at event instants. For variability set to "continuous" there are no restrictions on value changes. Only variables with data type real can be continuous. The Functional Mock-up Interface website is available at https://www.fmi-standard.org/ and the specification documents can be downloaded at https://www.fmi-standard.org/downloads. 3 Chapter 2. Installation 1. Supported platforms The FMI Add-In for Excel is supported on Windows XP and Windows 7, 32- and 64-bit versions. 2. Prerequisites The FMI Add-In for Excel is a standard add-in for Excel 2007, Excel 2010 and Excel 2013, 32-bit. Table 2.1 Supported Excel versions Version Name 15 Excel 2013 14 Excel 2010 12 Excel 2007 Other prerequisites are: • Microsoft .NET Framework 4 (x86 and x64) • Microsoft Visual Studio 2010 Tools for Office Runtime (x86 and x64) • Visual C++ 2010 Runtime Libraries (x86) The necessary prerequisites, except for Excel, are installed during the installation of the add-in. For details, see Section 3. The installer does not require running in elevated mode unless any of the prerequisites is missing and requires elevated mode to be installed. 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 you start. 1. Make sure to have one of Excel 2007, Excel 2010 or Excel 2013 (32 bit) installed. 2. Run the FMI Add-In for Excel .exe installer. The installer should be self-explanatory, follow the instructions to install the add-in. 3. During the installation, you will be prompted with a license agreement. Please read this text carefully. The license agreement has to be accepted before the product is installed. If the license agreement is not accepted, the installation is aborted. 4 Installation 4. Uninstalling FMI Add-In for Excel FMI Add-In for Excel can be uninstalled through the "Add or Remove Programs" tool in the Control Panel in Windows or by using the "Uninstall" menu alternative in the FMI Add-In for Excel shortcut in the Windows Start menu. Make sure that Excel is closed before starting the uninstallation. 5. License 5.1. License installation The following section references are part of the general license instructions for all Flex enabled products by Modelon. Please follow the instructions in the appropriate section to install your license. Installing a license file For instructions on how to install a license file, see Section 2 in Chapter 7. Installing a license server For instructions on how to install a license server, see Section 3 in Chapter 7. Retrieving a license file For instructions on how to retrieve a license file, see Section 1 in Chapter 7. Troubleshooting and support For troubleshooting and contacting support, see Section 4 in Chapter 7. 5.2. License features There are two different license features available for the FMI Add-In for Excel: standard (FMI_ADDIN_EXCEL) and runtime (FMI_ADDIN_EXCEL_RUNTIME). They are described briefly below. standard No restrictions on the available functionality. The user can set up and run simulations using the FMI Add-In for Excel user interface or the API scripting functions. runtime The user can run simulations using the FMI Add-In for Excel user interface and use a restricted set of the API scripting functions. The Experiment sheet, in which the simulations are run, must have been created by a user with a standard license feature. For an overview of the differences in terms of available features, please see Section 1.1. 5.3. Activating the license feature 5.3.1. First time configuration After installing FMI Add-In for Excel, the add-in must be configured to use a specific license feature. Note that this must only be done the first time after installation. To configure the license, please follow the steps below: 5 Installation 1. Open the License Information window by clicking the button License in the "Info" button group in the FMI Add-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, see Figure 2.2. "Demo" will be selected by default, see Section 5.4 for more information. Note that all features in this list might not be available for your license. 6 Installation Figure 2.2 Selecting license feature 3. Click the button Change... and select "OK" when prompted with a verification question. 4. If the change was successful, a dialog window will inform you that the new feature will be used the next time the license feature is checked out. If the change failed, you will get an error message. Please contact support if this happens. 5. Restart Excel for the changes to take effect. 5.3.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 as you start using any of the functions (available as buttons in the FMI Add-In Ribbon) or any of the API scripting functions. This means that you can start and work with other parts of Excel without a license feature being checked out. 7 Installation 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 returned to the license server, it will remain checked out for 5 minutes. This is to ensure that a license feature is not lost if Excel is accidentally closed. 5.3.3. Changing a license feature To change the current active feature, the procedure is the same as when configuring the license feature for the first time. Please follow the step-by-step instructions in Section 5.3.1 to do this. Note that a runtime license user can, in this way, always change to demo mode (see Section 5.4) in order to try the full version of FMI Add-In for Excel. 5.4. Demo mode Running the add-in in demo mode limits usage to the examples included in the add-in distribution. That is, only the FMUs that are available in the examples folder found in the FMI Add-In for Excel installation can be used. 6. Support Support inquires should be sent to [email protected]. 8 Chapter 3. Simulation and Initialization 1. Overview of the FMI Add-In for Excel Most of the user interaction in FMI Add-In for Excel is performed from the FMI tab that can be found in the Ribbon, located in top of the Excel window. The FMI tab contains four different groups of buttons. Some of the buttons 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 2 in Chapter 1. 1.1. License requirements overview The table below lists all available button groups in the FMI tab and for which license feature the button group is available. Buttons will be grayed out if the required license feature does not match the license feature that is currently active. For more information about the different license features, see Section 5.2 in Chapter 2. Table 3.1 FMI Add-In button groups Button group Description Required license feature Load Buttons for loading an FMU and creating an FMU sheet. These buttons are always enabled. standard, demo* FMU Buttons for creating an Experiment sheet. The Create Experiment button is enabled when the active (visible) sheet is an FMU sheet. standard, demo* Experiment Buttons for simulating and initializing FMUs, showing standard, runtime, demo* and hiding results and log sheets. This group is enabled when the active (visible) sheet is an Experiment sheet. Info The button User´s Guide opens this document. The About button opens a window containing information about the add-in and the License button opens a win- 9 standard, runtime, demo* Simulation and Initialization Button group Description dow with information about the current license status. The buttons in this group are always enabled. Required license feature * Button group is available in demo mode (when no license feature is checked out) but usage is restricted to the example FMUs that come with the FMI Add-In for Excel installation. 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. 2.1. License requirements The tutorial in this section can be done with a standard license or in demo mode (no license). For more information about license features, see Section 5.2 in Chapter 2. 2.2. Introductory tutorial The model used in the tutorial is a Furuta pendulum expressed in Modelica code and exported as an FMU for Co-Simulation. The FMU file can be found in the installation folder of FMI Add-In for Excel: \Examples\Co-Simulation\Furuta\Furuta.fmu. Assuming that the installation procedure was successful, Excel should now have an FMI tab in the Ribbon, see Figure 3.2. 10 Simulation and Initialization Figure 3.2 FMI Add-In in Excel The FMI tab contains different groupings of buttons. Some of the buttons are disabled by default. They are enabled when the active sheet contains data in a matching format. Figure 3.3 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 FMU sheet. 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 creating an Experiment sheet. In the Experiment sheet, the different start and parameters values, input trajectories, simulation time, etc. defining the batch are entered. Also, the simulation results are written back to this sheet. 11 Simulation and Initialization Follow these steps to complete the tutorial: 1. Click the Load FMU button to create an FMU sheet. A file dialog is then opened. Select the Furuta pendulum FMU, see Figure 3.4. The Furuta FMU file is located in the /Examples/CoSimulation/Furuta folder. Figure 3.4 Loading an FMU 2. A new FMU sheet is created. There are two areas in the new sheet, one for model metadata ("Model") and one for the variables in the FMU ("Variables"), see Figure 3.5. The metadata section contains general information about the FMU, e.g. model name, FMU kind, number of state variables, etc. The Variables area lists the variables with name and their corresponding attributes, including start value, unit, data type, etc. There are two columns that do not correspond to any FMI attribute: the "Include" column and the "Experiment" column. The Include column indicates if the variable will be included in the experiment or not. The Experiment column indicates if a variable will be used as an input or an output. 12 Simulation and Initialization Figure 3.5 Layout of the FMU sheet 13 Simulation and Initialization Note that the Create Experiment button in the ribbon was enabled when the FMU sheet was created. It is only enabled when the active sheet is an FMU sheet. 3. The value in the Experiment column indicates whether a variable is included or not in an experiment. By default, no variable is included. Click the Add Filter button in the Ribbon to include all variables in the experiment. Then remove all variables starting with der(. Select a cell on a row corresponding to such a variable, and then click on the Remove Selection button in the Ribbon. 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 Remove Selection. 4. If a variable is included, the value in the Experiment column indicates whether the variable is included as indata, outdata or both. Configure which variables will be used in the Experiment sheet using the drop down list in the Experiment column, see Figure 3.6. 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 Experiment sheet. The variable is not included even if the include column value is set to true. 14 Simulation and Initialization Figure 3.6 Selecting experiment variables Note that the powerful Excel filter functions can be used to filter the variables, see Section 3.4. 5. Click the Create Experiment button to create an Experiment sheet, see Figure 3.7. Figure 3.7 Create Experiment button 6. An Experiment sheet is now created. The sheet has four areas, "Model", "Settings", "Indata" and "Outdata". The Indata and Outdata areas were generated based on the variables in the Load FMU sheet with their Include value set to "TRUE" and their corresponding Experiment selections. The number of simulation cases is defined by columns called "Case 1", "Case 2", etc. Three cases are generated by default. 15 Simulation and Initialization Figure 3.8 An Experiment sheet 16 Simulation and Initialization 7. Change the start values of theta_0 for each simulation case in the Indata area, and click the Simulate FMU button in the Ribbon to start the simulation. The Outdata area is then populated by the final variable trajectory values, see Figure 3.9. Note that empty cells in the Indata and Settings areas imply that the values in the default column will be used. 17 Simulation and Initialization 18 Figure 3.9 Layout of the Experiment sheet Simulation and Initialization 8. The trajectories for the output variables are written to an experiment result sheet that was created during the simulation. The plot below is created with Excel's plotting tools, and we can see the results for the theta variable corresponding to the different simulation cases. Figure 3.10 Result sheet with plot 9. To create the plot in Figure 3.10, follow the steps: a. Check the Create Results button in the Experiment button group. This will create a result sheet when the experiment is run. Click the Simulate FMU button to re-run the experiment. b. Check the Show results button in the Experiment button group to unhide the result sheet. Select the result sheet so it becomes the active sheet. c. Click Insert tab in the Ribbon. Click the Scatter with Smooth Lines button that is found in the Scatter drop down list in the Charts button group. d. A plot is now created. When the plot is selected, the Chart Tools are active in the Ribbon. Now click on the Design tab. 19 Simulation and Initialization e. Click the Select Data button in the Data button group. The "Select Data Source" window will now open. f. Remove all Legend Entries (Series) expect for the ones called "theta", in the list to the left. g. Click the OK button and the plot will now look similar to the one in Figure 3.10. 3. The FMU sheet The FMU sheet contains information that is extracted from the FMU, such as general model information and a list of the variables exposed by the FMU. The FMU sheet is an Excel worksheet that is populated with data in a specific format relaying on Named Ranges. Other add-in operations may not work properly if the values or the named ranges are changed. To prevent the user from making errors, parts of the sheet is made read only. 3.1. License requirements A standard license is required to create and work with an FMU sheet. A runtime license holder can open and view an FMU sheet, but not create and work with it. See Section 5.2 in Chapter 2 for more information about the different license features. When running in demo mode, FMU sheets can be created and used but are restricted to the example FMUs that come with the installation. 3.2. Load FMU An FMU sheet is created with the Load FMU button. Figure 3.11 Load button group The Load FMU button opens a file browser which prompts the user to select an FMU file. When an FMU file is selected in the browser, a new FMU sheet is created that becomes the current active sheet in Excel. The sheet name is set to "FMU " where "" is the name of FMU model. The sheet is partially read only in order to preserve the integrity of the FMU sheet. If the All variables check box in the Ribbon was checked when the FMU was loaded, all variables in the FMU are listed. If unchecked, only variables that have either start values, or top level outputs or are continuous are included in the sheet. This is the default behavior. 3.3. FMU sheet areas The sheet consists of two areas, "Model" and "Variables", see Figure 3.12. 20 Simulation and Initialization Figure 3.12 The FMU sheet areas, Model and Variables 3.3.1. The Model area The Model metadata area is dedicated to general information stored in the FMU and experiment metadata. When an Experiment is created, information is read from this area to create Experiment sheets. Table 3.2 Description of the Model metadata area Model metadata cell Corresponding FMI attribute Sheet version Named Ranges (Prefixed FMU_) sheetVersion 21 Description Version of FMI Add-In that generated the FMU sheet Simulation and Initialization Model metadata cell Corresponding FMI attribute Named Ranges (Prefixed FMU_) Description FMU path FMUPath FMU file path. Path to the FMU file that was used to create the sheet. The path is used as the default path in the experiment sheet. FMU file name FMUFileName FMU file name Model name modelName Model_modelName Name of the model Model Identifier modelIdentifier Model_modelIdentifier Model identifier GUID guid Model_guid A string, “Globally Unique IDentifier”, that is used to check that the metadata XML file is consistent with the C-functions in the DLL file. FMUKind Kind of FMU which can be either "ModelExchange", "CoSimulation_StandAlone", "CoSimulation_Tool" or "Unknown". FMU kind Description description Model_description Short description of the model Author author Model_author Name and organization of the model author FMI version fmiVersion Model_fmiVersion FMI version of the FMU Generation tool generationTool Model_generationTool Name of the tool that generated the FMU Generation date and time generationDateAndTime Model_generationDateAnd- Date and time when the Time FMU was generated Model version version Model_version Version of the model Naming convention variableNamingConvention Model_variableNamingConvention Defines whether the variable names follow a particular convention. Can be set to either "flat" or "structured". Where "flat" means: a list of 22 Simulation and Initialization Model metadata cell Corresponding FMI attribute Named Ranges (Prefixed FMU_) Description strings, and "structured" means: hierarchical names with “.” as hierarchy separator, and with array elements and derivative characterization. Number of states numberOfContinuousStates Number of event indicators numberOfEventIndicators Model_numberOfEventIndicators Number of event indicators Default start time startTime Model_startTime Default start time (optional) Default stop time stopTime Model_stopTime Default stop time (optional) Model_expiryDate Expiry date for the experiment. The generated experiment sheet will not be of use after this date. An empty cell means no time limit, this is the default behaviour. The date must be entered in the format dd-mmm-yyyy, e.g. 06mar-2014. Experiment expiry date Model_numberOfContinuousStates Number states of continuous 3.3.2. The Variables area This area contains information about each variable such as start value, unit, etc. If the All variables check box in the Load button group was unchecked (default) when the FMU was loaded, the only variables listed in the FMU sheet are: • Variables with the attribute start set • Variables which are top level outputs, i.e, causality attribute set to "output" • Variables with variability set to "continuous" 23 Simulation and Initialization Table 3.3 Description of the Variable area Variables area Correspondcolumn names ing FMI attribute or element Include Named Ranges (Prefixed FMU_) Description include Indicates whether variable is included in experiment or not Full, unique name of the variable Name name Variables_name Variability variability Variables_variability Defines when the value of the variable changes. It is set to one of the following 4 values: "constant", "parameter", "discrete" or "continuous": "constant": the value of the variable is fixed and does not change. "parameter": the value of the variable does not change after initialization. "discrete": the value of the variable only changes during initialization and at event instants. "continuous": no restrictions on value changes, only variables with data type real can be continuous. Experiment experiment See Section 3.4. Start start Variables_start Initial value of the variable. A different start value can be set before initialization (not allowed for constant variability). All constants, independent parameters and inputs of the FMU must have a start value in the metadata file. Parameters that do not have a start value are computed during initialization (e.g. as functions of other parameters). Unit unit Variables_unit Physical unit of the variable Type One of the elements Real, Integer, Boolean, String or Enumeration. Variables_type Data type of the scalar variable Causality causality Variables_causality Defines how the variable can be connected to other models. It is set to one of the following 4 values: "input", "output", "internal" or "none". "input": a value can be provided from the outside, initially, the 24 Simulation and Initialization Variables area column names Corresponding FMI attribute or element Named Ranges (Prefixed FMU_) Description value is set to its start value (see above). "output": the variable can be used in a connection. "internal": after initialization it is only allowed to read the value of the variable, e.g., to store the value in a result file. It is not allowed to use this value in a connection. Before initialization, start values can be set. "none": the variable does not influence the model equations. It is a tool specific variable to, e.g., switch certain logging or storage features on or off. Min min Variables_min Minimum value of the variable Max max Variables_max Maximum value of the variable Nominal nominal Variables_nominal Nominal value of the variable Displayunit displayUnit Variables_displayUnitDefault display unit Quantity quantity Variables_quantity Description description Variables_description Description of the variable Physical quantity of the variable, e.g., “Angle”, or “Energy” 3.4. Create Experiment An Experiment is set up by creating an Experiment sheet, this is done from the FMU sheet. Note that an Experiment sheet can only be created by a user with a standard license, see Section 5.2 for more information about different license features. The FMU sheet gives a convenient overview of the information and variables found in the FMU and allows the user to set the indata and outdata variables for simulation experiment by using the Excel filter functions. This approach limits the number of variables that Excel has to handle in the simulation which will speed up the simulation and make the data sets easier to maintain. By default, the experiment sheet name will be "Exp ". If the sheet already exists, a serial number is added to the name. An Experiment sheet is created by clicking the Create Experiment button in the Ribbon. The Create Experiment button is only enabled when the active sheet is an FMU sheet. The Add/Remove filter and Add/Remove selection buttons are used to set the values in the Include column in the Variables area. 25 Simulation and Initialization Figure 3.13 Experiment button group In the process of creating the Experiment, the Variables area in the FMU sheet is read and used to create the Indata and Outdata areas in the Experiment sheet, see Figure 3.20. To include a variable in the Experiment, the value in the Include column must be set to "TRUE" and the Experiment 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 be set using the Add/Remove filter buttons or the Add/Remove selection buttons in the Ribbon. Default value for this column is "FALSE". • Add/Remove filter Click the Add filter button to include all variables that are visible in the FMU sheet. Click Remove filter to remove them. These buttons should be used in combination with the filter functionality in Excel. To add or remove a specific variable or multiple variables, use the filter to find 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, regardless of the current selection in the sheet. In Figure 3.14, the Name cell was clicked to open the filter dialog. The checked check boxes corresponds to the variables that are visible while Excel hides the unchecked variables. This filter functionality can be used on all the other columns as well, e.g., Variability, Experiment, Start, Unit and Type. 26 Simulation and Initialization Figure 3.14 The filter function • Add/Remove selection Click the Add selection button to include the selected variables in the Excel sheet. Click Remove selection to remove them. To select a variable, click any row corresponding to a variable. To select multiple variables, hold down Ctrl while clicking the variable rows. • Experiment 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 (only valid for top level inputs). outdata Results for this variable are generated. indata & outdata Results for this variable are generated. n/a Do not include the variable in the Experiment sheet. 27 Simulation and Initialization Figure 3.15 The experiment column drop-down list The values in the Start column are used as default values in the Experiment sheet. 3.4.1. Default Values of the Experiment column These are the criteria for how the value in the Experiment column is set for a variable when the FMU sheet is created: indata • The start attribute is present for the variable and/or, • The causality of the variable is input. outdata • The causality of the variable is output and/or, • The variability of the variable is continuous. indata & outdata • Variables fulfilling at least one criterion for indata and at least one criterion for outdata. n/a • Variables not fulfilling any of the above criteria. 3.5. Filtering The filtering function in Excel is a powerful tool for finding and listing data in a flexible way. It is therefore encouraged to use filtering when creating experiments for FMUs that may contain thousands of variables. The filter 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 is hidden. After one filter criterion has been applied, another filter operation can be applied. This means that the number of visible rows decreases as filter operations are applied unless the "Add current selection to filter" is used, see Figure 3.16. Note that this feature is not available in Excel 2007. 28 Simulation and Initialization Figure 3.16 Filtering by variable name For more information on how to use filtering in Excel, see http://office.microsoft.com/en-us/excel-help/filter-data-in-a-range-or-table-HP010073941.aspx . 4. The Experiment sheet In the Experiment sheet, batch computations are configured and executed. The final variable values from a simulation or initialization experiment are also written to this sheet. 4.1. License requirements A user with a standard license can work with any experiment sheet without limitations. A user with a runtime license can also work with an experiment sheet, provided that the sheet has been created by a user with a standard license. For more information about different license features, see Section 5.2 in Chapter 2. When running in demo mode, Experiment sheets can be created and used but are restricted to the example FMUs that come with the installation. 4.2. Simulation cases A batch simulation consists of multiple simulations and each simulation is called a Case. Three cases are generated by default. 29 Simulation and Initialization A case is defined in a single column, see for example Case 2 is defined in column G in Figure 3.17. 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 is read from the Default column, see column E in the Figure 3.17. The default value can also be left empty in the Indata area. In this case, no value is set by the add-in, instead the predefined start value in the FMU is used. Figure 3.17 Default simulation cases 30 Simulation and Initialization 4.2.1. Named ranges Named ranges are used in the Experiment sheet to refer to cell values. When a batch simulation is started, the ranges in the Experiment sheet are analysed and an internal structure for the simulation is created. To locate the ranges in Excel, they have been given named ranges when they were created, and this is called "named ranges". A simulation case consists of data from multiple named ranges, e.g. "EXP_InData_Values" and "EXP_OutData_Values". Changing the values of the named ranges or what the named range refers to, may result in an invalid state of an Experiment sheet. Trying to simulate an experiment in an invalid state results in a error message and will not start the simulation. The Name Manager dialog, seen in Figure 3.18, lists all the named ranges along with related information. The Name Manager can be opened from the Ribbon menu Formulas, button Name Manager in the button group "Defined Names". Figure 3.18 Name Manager dialog 4.2.2. Number of simulation cases The number of simulation cases are defined by the number of columns in the named range "EXP_Settings_cases". In Figure 3.19, the named range "EXP_Settings_cases" is selected, and the Name Manager dialog is opened. 31 Simulation and Initialization In Name Manager, one can see that Name "EXP_Settings_cases" refers to 'Exp Furuta'!$F$10:$H$10. This implies that there are three simulation cases defined in this Experiment sheet. Figure 3.19 Defining three simulation cases 4.2.3. Add a simulation case When adding a simulation case, it is important that all named ranges expand their reference. To add simulation cases: 1. Select any cell in a column corresponding to a simulation case (except for first case) 32 Simulation and Initialization 2. Right click the sheet and select "Insert..." (Short cut key Ctrl + +) 3. Select "Entire column" and click "OK" Note that F4 or Ctrl + Y can be used to repeat the last command. 4.2.4. Delete a simulation case When removing a simulation case, it is important that all named ranges contracts their reference. To delete simulation cases: 1. Select any cell in a column corresponding to a simulation case. 2. Right click the sheet and select "Delete..." (Short cut key Ctrl + -) 3. Select "Entire column" and click "OK". Note that F4 or Ctrl + Y can be used to repeat the last command. 4.2.5. Disabling/Enabling simulation cases To disable or enable a simulation case, type "True" or "False" in the cell corresponding to the simulation case in the Enable row. The Enable row is located in the Settings area. When a simulation case is disabled, the simulation Message will be set to "Disabled". 4.3. Experiment sheet areas The Experiment sheet consists of four areas, "Model", "Settings", "Indata" and "Outdata". 33 Simulation and Initialization Figure 3.20 Experiment sheet areas, Model, Settings, Indata and Outdata 34 Simulation and Initialization 4.3.1. The Model area The Model area includes model and experiment metadata. The following table describes each row included in the area. Table 3.4 Description of the Model Metadata area Name in ExNamed Ranges periment sheet (Prefixed Exp_) Description Sheet version sheetVersion Version of FMI Add-In for Excel that generated the Experiment 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_StandAlone", "CoSimulation_Tool" and "Unknown". Number of processes numberOfProcesses Maximum number of processes running simultaneously simulating the cases. Default is set to the number of cores of the computer. Checksum Model_checksum A control sum used to verify that the sheet is valid for the active license feature. Users should not change this value as the sheet will then become invalid. Expiry date Model_expiryDate Expiry date for the experiment sheet. The sheet will become unusable after this date. If the cell is empty, there is no time limit on the sheet (default). The date is formatted as dd-mmm-yyyy, e.g. 06-mar-2014. 4.3.2. The Settings area The Settings area includes settings for all simulation cases. The table below describes all parts included in the area. Table 3.5 Description of the Settings area Name in ExNamed Ranges periment sheet (Prefixed Exp_) Description Settings_cases Case name range. Defines the number of simulation cases and case names. Default values are "Case 1", "Case 2", "Case 3" and so on. Settings_values Range referring to the cell values: "Start time", "Stop time", "FMU", "Log Level", "Enable", "Output points" and "Timeout" in the Settings area (described below) 35 Simulation and Initialization Name in Experiment sheet Named Ranges (Prefixed Exp_) Description This range defines all settings, including the defaults, for all simulation cases. 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 dynamic simulation with Co-Simulation FMUs. FMU Part of Settings_values Path to the FMU file that is simulated. Can be an absolute path or a relative path to the workbook document. Log level Part of Settings_values Log level used for the simulation(s). Can be set to one of "Disable", "Fatal", "Error", "Warning" or "Info". Enable Part of Settings_values Boolean value indicating whether or not a case is simulated Output points Part of Settings_values Number of result points in the output trajectory. The result point at initial time is automatically added. It is only used in dynamic simulation with Co-Simulation FMUs. Timeout Part of Settings_values Timeout in seconds. If the simulation process has not returned before this time limit, it is terminated abrupt. If timeout time is set to 0 seconds, infinity will be used. 4.3.3. The Indata area Parameter and variable start values or input trajectories for top level inputs in the different cases are set in the Indata area. The table below describes the ranges included in the area. Table 3.6 Description of the Input area Name in ExNamed Ranges periment sheet (Prefixed Exp_) Description InData_values Range referring to the start and parameter values of all simulation cases, including the values in the default column. InData_variables Range referring to columns "Name", "Variability", "Type" and "Unit" for all input variables in all simulation cases. The range includes the default column values. 36 Simulation and Initialization 4.3.4. The Outdata area For each simulation case, the final values of the variable trajectories are written in the Outdata area. In the row labled "Message" an error message is printed if a simulation failed. "Disabled" is printed if the simulation case is disabled, otherwise "OK" is printed. The following table describes this area. Table 3.7 Description of the Output area Name in ExNamed Ranges periment sheet (Prefixed Exp_) Message Description OutData_values Range where the results are printed OutData_variables Range referring to columns "Name", "Variability", "Type" and "Unit" of all output variables. Messages_values Range where the simulation messages are printed, indicating the success of the simulation cases. 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 path is expected to be a string and generates an error otherwise. Start values should only be set for variables that have default start values. Input trajectories can only be set to the variables in the Indata area. Input trajectories should only 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, see Figure 3.21. The variable must be a top level input. Figure 3.21 Setting an input trajectory of a variable 2. Start typing an equal sign in the cell, see Figure 3.22. Figure 3.22 Typing equal sign 3. Use the mouse to select a range containing the input trajectory data where time points are stored in the first row and input data is stored in the second row., see . 37 Simulation and Initialization Figure 3.23 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 data points. The first row or column must contain the time points and the second row or column must contain the data 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 range will be visible in the cell, in this case "0.1". Otherwise "#VALUE!" is visible in the cell. 4.5. Simulation and Initialization To execute a batch simulation or initialization experiment, click on the corresponding button in the "Experiment" button group, see Figure 3.24. These buttons are enabled when the active sheet is an Experiment sheet. Figure 3.24 The Experiment button group When the simulation/intialization experiment has started, no interaction with Excel is possible. If any editing or interaction with Excel is active when the button is clicked, the simulation will not start. Disabling user interaction during the simulation allows the add-in to perform optimized recalculations and graphical updates in Excel. The control is returned to the user when the simulation or initialization experiment is finished. 4.5.1. Simulate FMU To start a batch simulation of a Co-Simulation experiment, click the Simulate FMU button in the "Simulate" button group in the Ribbon. This will generate a Log sheet, called "Log ", and a Results sheet, called "Res ". Note that the Log sheet and Result sheet, will be cleaned and overwritten if they already exist. These sheets will be populated with data during the batch simulation after each simulation case has finished. The Log sheet and Result sheet are hidden by default, see Section 3.4 for more information about hiding and unhiding sheets. The Experiment sheet will also be updated after each simulation case with the final trajectory values in the Outdata area. 38 Simulation and Initialization 4.5.2. Initialize FMU To start a batch initialization of a Model Exchange or Co-Simulation experiment, click the Initialize FMU button in the "Simulate" button group in the Ribbon. This will generate one Log sheet, called "Log ". Which is populated by data during the batch simulation after each initialization case has finished. The Log sheet is hidden by default, see Section 3.4 for more information about hiding and unhiding sheets. The Experiment sheet will be updated after each simulation case with the results in the Outdata area. Note that when initialization is performed, no Result sheet is generated. 4.5.3. Create Results If the check box Create Results is checked, a result sheet is generated. 4.5.4. Show results and Show logs The Show results and Show logs check boxes are used to unhide the result and log sheets. When a box is checked or unchecked, all sheets of the corresponding type are unhidden or hidden. The value in the check-box is also applied to new sheets that are generated. 5. Examples 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 different parameter values. We will apply different loads on the arm and analyze how the joint angle trajectories are affected. 39 Simulation and Initialization Figure 3.25 The Multibody Robot from Modelica Standard Library 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-In for Excel, in folder \Examples\Co-Simulation\Robot3d. Before the example can be run, the path to the FMU must be updated in the Experiment sheet to point at the FMU. 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 5.2 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 able to run this example. See Section 5.3.3 on how to do this. 5.1.3. Running the example 1. Select the FMI tab in the Excel Ribbon and click the Load FMU button to open the file browser. Navigate to the Robot FMU file that is located in the /Examples/Co-Simulation/Robot3d folder and select "Open" to load the FMU. 40 Simulation and Initialization Figure 3.26 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 and click "OK". mLoad is the mass parameter that corresponds to the load attached to the robot arm. This parameter will be selected as indata in our experiment. This can be seen from the value in the Experiment column that is set to "Indata", see Figure 3.27. 41 Simulation and Initialization Figure 3.27 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 current selection to filter" (not available in Excel 2007). Figure 3.28 shows the order in which the actions are made, in order to add the variable using the filter function. If Excel 2007 is used, click on Add filter before this second filter is done so that mLoad Include column value is set to "TRUE". 42 Simulation and Initialization Figure 3.28 Adding filter in the Name column 4. Click the Add filter button to include the visible variables in the experiment. The value in the Include column should now change from "FALSE" to "TRUE". 5. Click the Create Experiment button. 6. Set Stop time, to 1.8s. Note that the decimal delimiter can differ depending on the regional settings. 7. Create 12 simulation cases, increasing mLoad by 30kg for each simulation case. To add 9 additional simulation cases, select a cell anywhere in the column for Case 3. Right Click and select "Insert...", "Entire column" and "OK". When "OK" is clicked, one additional column is added and all named ranges are updated. Now repeat the command 8 times with F4 or Ctrl + Y. To set the case names and the parameter values, use the auto fill function. This is done by first entering 15 in the mLoad cell for Case 1 and 45 for Case 2. This is used to initialize the auto fill function. Now select the two columns, F and G, by holding Shift and selecting one cell in each column, then press Ctrl + Space to select the columns. Now drag the little black box in the top right corner of the selection to column Q. 43 Simulation and Initialization Figure 3.29 Use the auto fill function to create 12 simulation Cases. 8. Check the Create Results and the Show Results check box in the Ribbon. 9. Click the Simulate FMU button. 10.When the simulations have finished, the output trajectories can be found in the results sheet. The results of the parameter sweep is shown in Figure 3.30. 44 Simulation and Initialization Figure 3.30 Plot of the output trajectory for variable mechanics.load.body.r_0[3]. 11.To create the plot in Figure 3.30: a. Select the Results sheet, making it the active sheet. b. Select the Insert tab in the Ribbon and click the Scatter with Smooth Lines button that is found in the Scatter drop down list in the "Charts" button group. c. A plot is created. Select the plot to activate the "Chart Tools" in the Ribbon and click the Design tab. d. Click Select Data in the "Data" button group to open the "Select Data Source" window. e. Remove all Legend Entries (Series) named "Time", in the list to the left. f. Click the OK button. The plot will now look similar to the one in Figure 3.30. 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 parameter values. The FMU is generated from the Air Conditioning Library by Modelon. In the experiment, different mass flows on both sides of the heat exchanger will be applied. 45 Simulation and Initialization Figure 3.31 Internal heat exchanger from the Air Conditioning Library by Modelon 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 AddIn for Excel, in the folder: \Examples\Model Exchange\FMU_0Examples_IHX. 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 5.2 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 able to run this example. See Section 5.3.3 on how to do this. 46 Simulation and Initialization 5.2.3. Running the example 1. Select the FMI tab in the Excel Ribbon and click the Load FMU button to open the file browser. Navigate to the heat exchanger FMU file that is located in /Examples/Model-Exchange/HeatExchanger 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", uncheck the other parameter and click "OK", see Figure 3.32. The variable "init.mdot_init" is the mass flow on both sides of the heat exchanger. We want to add this parameter to the experiment as indata. Accordingly, the value in the Experiment column column is set to "indata". Figure 3.32 Filter for "init.mdot_init" 3. Add all top level output temperatures: "Tin_inner", "Tout_inner", "Tin_outer" and "Tout_outer" as outputs to the experiment. First, click the filter box in the cell Name and select "Clear Filter From "Name" " to clear the filter. Now filter the Causality column for the value "output". If it is possible to only filter for internal, make sure the filter is cleared in all columns. The Variables area should then look like in Figure 3.33 with 19 top level outputs. 47 Simulation and Initialization Figure 3.33 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. You should now see 4 top level outputs. 5. Click the Add filter button to include the visible variables in the experiment. The value in the Include column should now change from "FALSE" to "TRUE". 6. Click the Create Experiment button. 7. Create 9 simulation cases, increasing "init.mdot_init" by 0.005kg/s for each simulation case. To add 6 more simulation cases, select a cell anywhere in the column for Case 3. Right Click, select "Insert...", "Entire column" and "OK". Clicking "OK" will add an additional column and update all named ranges. Now repeat the command 5 times with F4 or Ctrl + Y. Use the auto fill function to set the case names and the start values by first entering 0.01 in the "init.mdot_init" cell for Case 1 and 0.015 for Case 2. This is used to initialize the auto fill function. Select the two columns, F and G, by holding Shift and selecting one cell in each column, then press Ctrl + Space to select the columns. Drag the little black box in the top right corner of the selection to column N. 48 Simulation and Initialization Figure 3.34 Using the auto fill function to create 9 simulation cases 8. Click the Initialize FMU button to start the initializations. The Outdata value area should now be populated with results and each initialization case message should read "OK", see Figure 3.35. 9. Create a plot like the one in Figure 3.36: a. Select the Indata and Outdata ranges as seen in Figure 3.35 by selecting one of the ranges and, while holding Ctrl, selecting the other range. The selected cells have a blue gradient. "Tin_inner" is both selected and active, and is therefore white with a black border. 49 Simulation and Initialization Figure 3.35 Selecting data ranges b. Select the Insert tab in the Ribbon, then click on the Scatter with Smooth Lines that is found in the Scatter drop down list in the "Charts" button group. c. A plot is created, see Figure 3.36. 50 Simulation and Initialization Figure 3.36 Top level output temperatures plotted against init.mdot_init 51 Chapter 4. Scripting The 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, automatically when the macro is run from Excel. Macros and other Visual Basic functions can be used to automate tasks that are repeatedly performed. There are license restrictions on using the VB functions. See Table 4.1 for an overview of all functions and corresponding license requirement. 1. Getting started This tutorial demonstrates how to run a macro from Excel that loads an FMU, creates an Experiment sheet and finally simulates the experiment. The tutorial is divided in two parts, Section 1.2 and Section 1.3, where the first part demonstrates the steps needed to enable the FMI Add-in functions in a workbook and the second part demonstrates how the FMI Add-in code is called in a user defined macro. 1.1. License requirements This example can be run with a standard license or in demo mode. For more information about license features, see Section 5.2. Note that a user with a runtime license can always temporarily use FMI Add-In for Excel in demo mode to be able to run this example. See Section 5.3.3 on how to do this. 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 \Examples\FMIAddInScript.xlsm from inside Excel 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 for more information on how to make it visible. 52 Scripting 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, located at the bottom of the file, that may be left out. To continue this tutorial, the macro example "FMIExample1" must be copied. Figure 4.2 Selecting code and copying 5. Create a new workbook in Excel by selecting "File" and then "New". 53 Scripting 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. 1.3. Run example In the previous section, code was copied that enabled the FMI Add-in functions to be called from macros. The copied 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. 54 Scripting Figure 4.4 Macro dialog in Excel The code for theVisual Basic macro "FMIExample1" is shown below. This example macro was included in the code that was copied into the new workbook in the previous section. Public Sub FMIExample1() Dim fmuFile As String fmuFile = FMIGetInstallationFolder & "Examples\Co-Simulation\Furuta\Furuta.fmu" ' Create an FMU sheet and include all variables FMILoadFMU fmuFile, True, vbNullString ' Include all variables in the experiment FMISetFilterButton ActiveSheet, True ' Create Experiment sheet with 1 simulation case FMICreateExperiment ActiveSheet, vbNullString, 1 ' Simulate or initialize the experiment If Range("Exp_FMUKind").Value2 = "CoSimulation_StandAlone" Then FMISimulateButton Else FMIInitializeButton End If End Sub 2. Two sheets should now have been created, one FMU sheet, see Figure 4.5, and one Experiment sheet, see Figure 4.6. The experiment should be populated with simulation results. 55 Scripting Figure 4.5 Macro generated FMU sheet 56 Scripting Figure 4.6 Macro generated Experiment sheet 2. Usage In the file \Examples\FMIAddInScript.xlsm, the Visual Basic code for calling the FMI Add-in functions can be found. This code must be copied into the workbook or worksheet from which the FMI Add-in functions should be called, see Section 1.2. Note that this code includes some examples at the bottom that do not need to be copied. 2.1. Functions A list of all FMI Add-in functions with a short description and license requirement are found in Table 4.1. For more information, go to the FMI Add-in code in \Examples\FMIAddInScript.xlsm. 57 Scripting Table 4.1 FMI Add-in functions Function Short description Required license feature FMIGetVersion Returns the version of the FMI Add-in standard, runtime, demo* FMIUpdateSheet Updates the FMU sheet or Experiment sheet standard, runtime, demo* FMIIsLicenseCheckedOut Returns the licence status standard, runtime, demo* FMIGetCreateResults Returns checkbox status for Create Results in the Rib- standard, runtime, demo* bon FMISetCreateResults Sets the checkbox status for Create Results in the Rib- standard, runtime, demo* bon FMIGetShowResults Returns checkbox status for the Show Results in the Ribbon standard, runtime, demo* FMISetShowResults Sets the checkbox status for Show Results in the Ribbon standard, runtime, demo* FMIGetShowLogs Returns checkbox status for the Show Logs in the Rib- standard, runtime, demo* bon FMISetShowLogs Sets the checkbox status for Show Logs in the Ribbon standard, runtime, demo* FMICreateExperiment Creates an Experiment sheet standard, demo* FMILoadFMU Creates a new FMU sheet standard, demo* FMISetFilterButton Sets the Include column values for the current visible variables in the FMU sheet standard, demo* FMISetSelectionButton Sets the Include column values for the current selected standard, demo* variables in the FMU sheet FMISimulateButton Calls the Simulate FMU button in the Ribbon standard, runtime, demo* FMIInitializeButton Calls the Initialize FMU button in the Ribbon standard, runtime, demo* FMISimulate0 Starts a simulation (long input argument list) standard, demo* FMIInitialize0 Starts an initialization (long input argument list) standard, demo* FMISimulate1 Starts a simulation (short input argument list) standard, demo* FMIInitialize1 Starts an initialization (short input argument list) standard, demo* * Function is available in demo mode (when no license feature is checked out) but usage is restricted to the example FMUs that come with the FMI Add-In for Excel installation. 58 Chapter 5. Upgrading Workbooks 1. Update sheet When new versions of the FMI Add-in are released, FMU sheets and Experiments sheets generated with older FMI Add-ins may not be compatible with new versions. The Visual Basic function FMIUpdateSheet included in the add-in can be used to update sheets. Note there is an example macro "FMIExampleUpdateActiveSheet" in \Examples\FMIAddInScript.xlsm that uses FMIUpdateSheet to update the current active 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 sheet using the new version of FMI Add-in. 1.1. Specific version updates Updates that require extra explanation are listed in the sections below. 1.1.1. 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 license feature may only use experiment sheets that have been created by a user with a standard license feature. An experiment sheet is verified with a checksum which is generated when creating and saving the sheet. As a standard license feature is required to generate a checksum, a runtime license feature user can not update workbooks from version 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 be generated in this step. • Save the updated sheet. The checksum will be generated when saving. 59 Chapter 6. Limitations This page lists the current limitations of the FMI Add-In for Excel. • Only 1.0 FMUs containing 32-bit binaries are supported in both the 32-bit and the 64-bit version of FMI AddIn for Excel. • There is a limited number of columns and rows in Excels worksheets which limit the number of simulation cases that can be run. Excel 2007 and 2010 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. 60 Chapter 7. License installation 1. Retrieving a license file There 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. The license is locked to be used on a computer with a specific MAC address. • Server (Requires a license server) This licensing model represents a classic network with a server and users. The server grants or denies requests from computers in the network to use a program or feature. A maximum limit of computers in the network that is granted a request is set. There is no restriction for which computer is using the 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 be provided to Modelon. • Evaluation license (Node Locked) License used for evaluation that enables a program or feature a limit of time. This is the same as a Node locked license. Please contact the Modelon sales department at to purchase a license or to get an evaluation license. In order to obtain a license file for a node locked license, you need to provide the MAC address of your computer. If you are using a license server, you need to provide the MAC address of the server. In Section 1.1 below, you will find instructions for how to retrieve the MAC address of a computer. 1.1. Get MAC address Modelon uses the Ethernet address (MAC address) to uniquely identify a specific computer, also called host ID. Therefore, you must provide the MAC address of the computer on which you want to use the program or feature. If a Server license is used, the MAC address for the server computer is required, not all the computers in the network that are going to use the program or feature. If a Node locked license is used, the MAC address of the computer to which it is locked must be used. Note: Modelon only allows ONE MAC address for each computer. Please disable and unplug all network devices that are not permanently connected to the computer such as laptop docking stations, virtual machines and USB network cards. 61 License installation • 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 \license_tools\lmhostid.exe. 3. Use this hostid when you are in contact with Modelon. If multiple hostids are listed, select one that is permanent 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 /license_tools/. 62 License installation 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. 2. Install a license After purchasing a license, you should receive a license file with the file extension *.lic. This file must be put in a specific folder for the application to find it. 2.1. Installing a node locked license 2.1.1. Windows 1. Close the application if it is already running. 2. Open the Application Data folder. Windows 7 and Windows Vista a. Click the Start button. b. Type shell:AppData in the search bar and press enter. Windows XP a. Click the Start button. b. Click on Run.... c. Type shell:AppData in the text box and click OK. The Application Data folder should now open. 3. Create the folders Modelon\Licenses\Nodelocked if they do not exist already. 4. Put your license file in the folder Nodelocked. 2.1.2. Unix • Copy your license file to the folder \Licenses\Nodelocked. 2.1.3. Updating the license To update the license file, you shall overwrite the old license file with the new one. It is very important that the old and the new license file is not put in the same folder since the old license file may then be used and the application will fail to check out a license. Note that you must restart the program before the changes can take action. 63 License installation 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 user, who will use the program or feature. The assumption is that the server is already up and running and that the IP address to the server and the port number is already known. The IP address and the port number, if needed, should be provided by the license server administrator. The application can connect to the license-server and daemon either by reading a license file or an environment variable. 2.2.1. Windows 1. Close the application if it is already running. 2. Create an empty text file Windows 7 and Windows Vista a. Click the Start button. b. Type Notepad in the search bar and press enter. Windows XP a. Click the Start button. 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 ANY USE_SERVER b. Change to the IP address to the server. c. Change to the port number that is being used. If you do not have a port number, you can remove the whole . d. Save the file with a filename with the extension *.lic in a temporary place, the file will be moved in a later step. You can now close Notepad. 4. Open the Application Data folder. 64 License installation Windows 7 and Windows Vista a. Click the Start button. b. Type shell:AppData in the search bar and press enter. Windows XP a. Click the Start button. 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 folders Modelon\Licenses\Server if they do not exist already. 6. Put the license file you just created in the folder Server. 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 ANY USE_SERVER b. Change to the IP address to the server. c. Change to the port number that is being used. If you do not have a port number, you can remove the whole . The license file should now look like something like this: SERVER 192.168.0.12 ANY 1200 USE_SERVER 4. Copy your license file to the folder \Licenses\Server. 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 variable MODELON_LICENSE_FILE. The value can be set to port@host, where port and host are the TCP/IP port number 65 License installation and host name from the SERVER line in the license file. Alternatively, use the shortcut specification, @host, if the license file SERVER line uses a default TCP/IP port or specifies a port in the default port range (27000–27009). 2.2.4. Updating the license To update the license file, you can either redo the installation instructions described above or make the changes in the license file directly. It is very important that the old and the new license file is not put in the same folder since the old license file may then be used and the application will fail to check out a license. Note that you must restart the program before the changes can take action. 3. Installing a license server To install a license server, you must have a server license file. Please contact the sales department at Modelon to obtain such a file. This license file must also be configured before it can be used, for example the IP address and port number must be set. Modelon products use a licensing solution provided by Flexera Software. It is recommended that you install the latest version of the server software, which is available from http://learn.flexerasoftware.com/content/ELO-LMGRD . Modelon products requires a license server version number v11.10.0.0 or later. A license server and license daemon is required and is distributed with the product you are installing. The following step by step instructions for installing a license server assumes that no other Flexera license server is already installed. 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 configured before it can be used. 1. Open the license file in a text editor. The content may look like: SERVER 192.168.0.1 080027004ca5 25012 VENDOR modelon FEATURE FMI_TOOLBOX modelon 1.0 3-feb-2012 12 SIGN="0076 305..." 2. Edit the SERVER line where the IP number, 192.168.0.1, should be replaced with the IP number of the server. Also change the port number, 25012, to the desired port or remove it to use default ports. The IP number and potential also the port number should be provided to the end users so they can configure their license files to connect to the server. 3.2. Installation on Windows In the \license_tools folder that is distributed with your product, you will find the files listed below. 66 License installation The listed files are used to setup 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 service will 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 License Server. 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 the debug log file is the c:\winnt\System32 folder. To specify a different location, be careful to specify a fully qualified path. 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 Power Up check box. 10.To save the new Modelon License Server service, click Save Service. 67 License installation 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 this example, 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 server starts and writes its debug log output to the file specified in the Config Services tab. 3.3. Installation on Unix In the \license_tools folder that is distributed with the product you can find the files listed below. • lmgrd (license server) • modelon (license daemon) • lmutil (configure- and utility functions) Before you start the license server, lmgrd, make sure that license daemon modelon is in the same folder. 68 License installation 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 all files named *.lic are used. If the license_file_list value contains more than one license file or directory, they must be separated by colons. debug_log_path is the full path to the debug log file. Prepending debug_log_path with the + character appends logging entries. Starting lmgrd from a root account my introduce security risks and it is therefore recommended that non-root account is used instead. If lmgrd must be started by the root user, use the su command to run lmgrd as a nonprivileged 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. 4. Troubleshooting license installation If you experience any problems with the license, the error messages are usually descriptive enough to give a hint of what is wrong. If the problem persist, please contact Modelon at . Before you contact the Modelon support you should run lmdiag and provide the resulting information. Follow the instructions below to run lmdiag. 4.1. Running lmdiag • 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 lmdiag.exe. 69 License installation Type the full path to lmdiag.exe within quotes and press enter. lmdiag.exe is normally located in \license_tools\lmdiag.exe. • Unix • Open a terminal and change directory to the /license_tools/. Run lmdiag with the ./lmdiag command. 70 Chapter 8. Release notes 1. Release 1.3.8 • Fixed FMI Add-In for Excel to not require MSVCR100D.dll 2. 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. 3. Release 1.3.6 • Fixed bug with missing FMIAddInScript.xlsm. 4. 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 now always 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 before the workbook is saved. 5. 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. 6. Release 1.3.3 • Fixed bug with locale dependent expiry date. 7. Release 1.3.2 • Fixed bugs in the updating script and in loading invalid FMUs. 71 Release notes 8. Release 1.3.1 • Simulation results now includes the result point at initial time. 9. Release 1.3 • Introduced new license feature: runtime (FMI_ADDIN_EXCEL_RUNTIME). With this license feature, users can perform simulations, parameter sweeps, etc and use a restricted set of the API macro functions. For more information, see Section 5.2 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 with FMI Add-In for Excel, rather than at startup of Excel. 10. Release 1.2.1 • Fixed problem with loading FMUs containing external DLL files. 11. 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. 12. Release 1.1.2 • Fixed problem with parsing input trajectory values. • Fixed problem with long simulations causing Excel to display the dialog message: Excel is waiting for another application to complete an OLE action. 13. Release 1.1.1 • Changed simulation timeout time from 100s to infinity. 14. Release 1.1 • Parallel simulation and initialization support. • Excel sheets based on named ranges. 72 Release notes • 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 to perform a parameter sweep. 15. Release 1.0.1 • FMI Add-In is built with FMI Library 2.0a2 to fix bugs. 16. Release 1.0 Initial 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. 73