ProMoT Step by Step for Reaction Models in Process Engineering A Tutorial

Transcription

1 ProMoT Step by Step for Reaction Models in Process Engineering A Tutorial Martin Ginkel, Sebastian Mirschel, Katrin Kolczyk August 19, promot@mpi-magdeburg.mpg.de MAX PLANCK INSTITUT DYNAMIK KOMPLEXER TECHNISCHER SYSTEME MAGDEBURG Max-Planck-Institute for Dynamics of Complex Technical Systems, Sandtorstr. 1, Magdeburg, Germany 1

2 Contents 1 Preliminary: Getting ProMoT setup for the first use How do I install ProMoT? How can I start ProMoT? Using the console Using the text editor Emacs Where can I find further information? Getting Started: A look at the ProMoT GUI 5 3 Simple Modeling and use of GUI How do I load an example model? How can I combine existing modules? The two-tanks example How do I save my models? How can I get an overview of a module? How do I create a plant model? The two-tanks-plant example How can I check the model for consistency? How can I simulate the plant model? Simulation with Diana Simulation with DIVA Are there other models to try? Advanced Modeling How do I write an elementary module? The tank example How can I find a specific modeling entity? Oops, an error occurred! How can I use inheritance and arrays in my models? The mc-tank example How can I finish ProMoT? 23 2

3 1 Preliminary: Getting ProMoT setup for the first use 1.1 How do I install ProMoT? Usually ProMoT is used from the text editor Emacs. Therefore the line (load "/usr/local/promot/promot/emacs/promot") must be inserted into your personal /.emacs 1. If ProMoT was installed into a different location /usr/local/promot/promot has to be substituted by your installation directory. This applies also for the following sections. 1. Open a new terminal window like konsole from the window manager. Usually there is a control panel in KDE and on this control panel you can find a screen-icon. Click on this icon one time, and you will get a terminal. 2. Type emacs /.emacs and hit the return (enter) key. In all following commands we will assume implicitly that you hit return. 3. Move the cursor to the beginning of the file (it may be empty) and type: (load "/usr/local/promot/promot/emacs/promot") 2. Save the file by the menu bar File > Save or by pressing the keys C-x C-s Exit the Emacs by the menu bar File > Exit Emacs or by pressing C-x C-c. At the next start of Emacs, ProMoT will be available. 1.2 How can I start ProMoT? Using the console 1. Use your Terminal window or start a new one as described in Type /usr/local/promot/promot/scripts/promot and ProMoT will get started Using the text editor Emacs 1. Use your Terminal window or start a new one as described in Type emacs and Emacs starts up. 3. Select in the menu of Emacs: Promot > Start Promot. 4. The Browser window of ProMoT shows up. 1 If the tilde seems to be broken on a German (QWERTZU) Keyboard, it is possibly necessary to type the tilde key followed by a space. Tilde is used in UNIX and Linux to refer to your personal home directory instead of typing the pathname all the time. 2 The.emacs is a configuration file for the start of the text editor Emacs. It is executed every time Emacs starts. By adding this line, some new entries are added to the menu of Emacs to start ProMoT. 3 C-x C-s is the Emacs notation for pressing Control and the x key at the same time followed by Control and the s key. 3

4 Inside Emacs there are now two windows, showing useful information about the ProMoT system: *promot-server* and *compilation*. It is also possible to work interactively with the *promot-server*. 1.3 Where can I find further information? More detailed documentation, particularly covering the application of ProMoT for logical and dynamic models and the ProMoT manual can be found at the ProMoT web-site: 4

5 2 Getting Started: A look at the ProMoT GUI Upon starting ProMoT the default (the bare necessities that compromise the program) ProMoT GUI 4 loads the ProMoT Browser, which is the main window of ProMoT, see Figure 1. In the following the ProMoT Browser is simply called Browser. The Browser contains six menus (File, Edit, View, Options, Tools and Help) with drop down selections and allows the user to find modeling entities, start graphical and textual editors as well as to load and save files. There are two distinct areas of the Browser, a left panel containing a tree that shows the class hierarchy with all the modeling entities currently loaded and a right panel where, if desired, the.mdl source code of the currently selected class can be viewed. (If you do not see the right panel we explain how to view this in a bit). The tree can be expanded and compacted by clicking the handle buttons to the left of each entity, where subclasses are shown in the subtree of the regarding super-classes. For example the default classes of ProMoT, as shown in Figure 1, are subclasses of the modeling-entity and include: 1. behavioral-modeling-entity > continuous-modeling-entity > > equation / variable > discrete-modeling-entity > > place / transition 2. structural-modeling-entity > module > terminal For the first-time user the most important modeling entities are located in the subtree of the structural-modeling-entity > module. The file tree also has a context-menu (which can be viewed upon right-clicking) for each entity within it and is used for starting most editing actions. To go to the structural-modeling-entity > module: 1. Click the handle button to the left of the folder icon of structural-modeling-entity. 2. Now there are two basic classes in view, module and terminal. There are currently no modeling-entities defined. 3. To view the context-menu right click on the modeling entity. 4. The Browser enables the user to view either just the left panel (with the file tree) or both the left panel and the right panel (with the source code of the currently selected class). To switch back and forth between modes click on the Browser menu View and select the check-box Show Quickview. With this option enabled the corresponding.mdl source code of the currently selected class will be displayed in the right panel of the Browser. ProMoT models are written in.mdl, however the modeling language.mdl is beyond the scope of this tutorial. 4 GUI is an acronym and stands for Graphical User Interface, i.e. the windows, menus items, scroll bars, etc. that frames the main content that ProMoT presents as a working environment. 5

6 Figure 1: The window of the ProMoT Browser. 6

7 3 Simple Modeling and use of GUI 3.1 How do I load an example model? 1. Select the terminal window from the beginning. 2. type mkdir ~/promot Now there is a separate directory promot in your home directory (~/) which we will use for all model files and simulations. 3. cd ~/promot 4. cp -r /usr/local/promot/promot/kb/practical/* Select the window of the Browser. 6. Click in the menu File > Open > Model In the file browser open (with double click) the directory promot in your home directory. You can remember the directory with the Add button on the right of the dialog. This creates a bookmark, that can be selected with the list below the button. 8. Select the file ~/promot/load.mdl and press the Open button. 6 Now there are modeling entities defined in the ProMoT system. You can select and visit them in the Browser window. If you load additional files, the contained modeling entities will be added to your current session. If you load the same file again, the (perhaps) changed definitions will override the previous version in memory. 3.2 How can I combine existing modules? The two-tanks example. We will now construct the two-tanks model. 1. Select the modeling-entity named module in the Browser (click with the left mouse button). 2. Activate the Context-Menu with the right mouse button and click on Add Subclass. 3. Select the Class Name:-field and press Ctrl-A to select the whole name newsubclass. 4. Type the name two-tanks. 5. Click the OK button. 5 The. is part of the command. This copies some example files into your working directory. 6 You can get easily to your home-directory / by pressing the little house icon in the Java file browser. 7

8 Figure 2: The Browser with example models loaded. Figure 3: Incomplete tank model. 6. Different types of classes can be specified in ProMoT. abstract classes: the default type for abstract library elements and modules. non-abstract classes: these are specific library elements and model parts. The source code of the class contains the following line: :PROPERTIES (("abstract" :VALUE "no")) executable classes: these are sealed models, which can be exported to a simulation or analysis environment. The source code of the class contains the following line: :PROPERTIES 8

9 (("model" :VALUE "yes")) At the moment the main purpose is a different visualization of the classes in the Browser. The internal class module is an abstract class (see Figure 2). You can change these boolean values by actions in the Context-Menu of a tree-node in the Browser. The options are Change Property > Abstract and Change Property > Model. 7. You can Undo/Redo every action you have made in the Browser except deleting all classes and loading a mdl-file. Try to undo/redo the Add Subclass -Action by clicking Edit > Undo and Edit > Redo respectively. Alternatively you can press Ctrl-Z and Ctrl-Y. 8. Select the new class two-tanks in the Browser. 9. Right-click on the new class and select Visual Edit from the Context-menu to start the Visual Editor, place the window besides the Browser. The Visual Editor window is divided into the work panel on the right and the palette on the left, holding available modules and terminals. 10. Select and drag the module tank from the Browser to the palette (left part of the Visual Editor) named Modules. This class is now available for use in the Visual Editor and shown with its icon and available terminals. 11. Select and drag the tank from the palette to the work panel (gray window on the right). The new tank instance appears and is named tank*. 12. A red box appears around the tank module. This box is part of a checker system that assists the modeler while editing the model. If you move the mouse pointer over the tank module you get a tool-tip descibing the problem. Solving the modeling problem removes the box. 13. Rename the new tank to t1 by selecting it and pressing the Backspace key (to finish editing, hit Return). Alternatively, you can use the Context-Menu > Edit Details to show a properties dialog which allows to change the name. 14. Repeat steps 11 and 13 to create another tank t Link t1 and t2 by dragging a line from the terminal out of t1 to the terminal in of t2. This connects the two tanks (see Figure 3, left). 16. Now the terminals to the external of two-tanks have to be constructed. The overall inlet is the inlet of the tank t1 the outlet is the outlet of the tank t2. Activate the Context-Menu on tank t1 and select Connect Terminals > Propagate in. A new external terminal is created. Rename this terminal to in as we showed it for the tanks in step 13. Propagate the terminal out of tank t2 in the same way and name it out. The result is depicted in Figure 3, right. 9

10 17. For a nice layout you can move around the modules and terminals with the mouse. For fine-tuning the layout it is recommended to use the cursor-keys (perhaps holding the Shift-Key for larger steps). Terminals cannot be moved into the module. They stick to the edges of the work panel and can only slide along the current edge. 18. Now the two-tanks are finished. In the menu of the Visual Editor select Model > Close. A save dialog appears, press the Save button. The new module now exists in the running ProMoT system. It can be used in other models and should be saved to a file soon. 19. Like in the Browser of ProMoT you can undo/redo the editing actions you have done in the Visual Editor. There are three possibilities: Click on Edit > Undo/Redo Press Ctrl-Z or Ctrl-Y respectively or click on the Undo/Redo buttons in the toolbar 3.3 How do I save my models? We will now save the newly created class two-tanks into a text file. 1. Select two-tanks in the Browser. 2. Choose from the Browser menu File > Save Selected Classes. 3. Choose the filename two-tanks.mdl into the text field and click the Save button. By doing so only the class two-tanks is saved in a separate file. Alternatively if you select multiple classes in the Browser (by pressing Shift or Control and click on classes in the tree), you will save all of them into one single file. You can also use the menu Edit > Select in the Browser. To save the complete currently loaded knowledge base, you can use File > Save All Classes. 3.4 How can I get an overview of a module? To explore the contents and relationships of a model in ProMoT some views of its contents are provided. Most of the views can be called from the menu View in the Browser. Two of the views are the Math Model View and the Aggregation View. They show all parts of the selected module, including inherited parts (see Figure 4). 1. Select in the Browser View > View Math Model for the class tank. 2. The view shows you terminals, variables and equations and also weak parts (references) in the module. In the tank the variables jn of the two terminals are weak parts (green). 3. By moving the mouse over the shown parts and resting for a while, a tool-tip is shown with details about the model-part. 10

11 Figure 4: Math Model View (left) and Aggregation View (right). Two of the several views in the ProMoT GUI. 4. Right-click on the ROOT element and from the context menu select Show Details of ROOT. The Aggregation View appears. 5. With View > Options you can select, which parts should be visible in the Aggregation View. Another view shows the source code of the current class, containing the directly defined (not inherited) parts. 1. Select in the Browser Context-Menu > View Source (or via menu View > View Source) for the class tank. 2. Try this out for other classes too! 3.5 How do I create a plant model? The two-tanks-plant example. The next step should be the generation of a simulation model. A complete simulation model in ProMoT is also represented by a module. Models like this are called closed models since they do not have terminals and therefore no interactions to the outside. Next we will complete a model to simulate the two-tanks model. 1. Open the Visual Editor with the Context-Menu > Visual Edit for the class tank-plant in the Browser tree. It shows a single tank connected with an inlet and an outlet reservoir. We want to build something similar for the two-tanks module. 2. If you are unsure, whether your two-tanks is correct, load the file two-tanks-correct as shown in Section 3.1. It contains a correctly prepared model of the two-tanks. 3. Select the class two-tank-plant and click on Context-Menu > Visual Edit. Place the editor window besides the Browser. 11

12 4. Drag one inlet, one two-tanks and one outlet into the Visual Editor as shown in Figure 5, and set the names of the modules. Link the terminal out of the inlet i1 with in of the tank tt and out of the tank with in of the outlet o1. If you are unsure, have a look at Section 3.2. Figure 5: Editing step for two-tank-plant. 5. You can visit the definition of submodules in the editor by Context-Menu > Visual Edit Class or double-clicking on the submodule. Try this out for the class twotanks. 6. Save the edited model to the running ProMoT by clicking in the menu Model > Close and then Save. 7. Save the model to a file two-tank-plant.mdl. Now we are ready to simulate. 3.6 How can I check the model for consistency? Before starting simulations ProMoT gives you the possibility to check your model for structural correctness. You can start the checker by choosing Tools > Check For Consistency from the Visual Editor menu for the current model. In the following the mc-tank is exemplified. If you want to check an open module (with outer terminals) you have to decide first, which variables on the modules interface are expected to be determined by the module itself (output-variables) and which variables are calculated by other modules (input-variables). Otherwise the check would fail with an over- or underdetermined equation set, because it has no information available about equations outside this module. If there are state-terminal-variables defined for the module you can choose new values. They are set temporarily for the time of checking. The terminal-variables of mc-tank do not have to be changed, see Figure 6. 12

13 Figure 6: Dialog to inspect the terminal-variables of the module The incidence matrix for your model is shown in the appearing dialog. The columns show the variables, the rows correspond to the equations of the considered system. If you click on a row-header in the matrix the row and the columns with an entry X in this row are highlighted, see the left screen-shot in Figure 7. The other way round (clicking on a column-header) works in the same manner. The matrix shows the assignments between the variables and equations in your system. Now you can apply algorithms to the model which run also while the output of the module. They can be started by pressing the buttons AssignEquations and BlockTriangular. If your model is well-determined the algorithms terminate without problems and the rows and columns get re-sorted trying to achieve a lower triangular matrix (see the middle and right screen-shot in Figure 7). In the case of under- or overdetermination of the system a dialog with a detailed description will pop up, which also allows you to mark the not-well determined parts in the matrix. In our example the system is well-determined. 3.7 How can I simulate the plant model? This part of the work with ProMoT is finally the moment of truth. If you have errors in your model, ProMoT tries to detect them here Simulation with Diana The recommended simulation environment is Diana (Dynamic Simulation and Numerical Analysis). Diana is the successor of DIVA and can be freely used. On the Diana website you can find further information and the link for download ProMoT provides two different ways to simulate models with Diana either by export or by direct simulation. The first option comprises several steps in order to simulate the model, namely export the ProMoT model, start Diana, load model into Diana, simulate the model and show simulation results. Sometimes, this procedure is overkill if you want to see just an overview of the simulation results. For this purpose, ProMoT provides the simulation of the model using Diana as a external tool and showing the simulation results directly in the GUI of ProMoT. Both options are explained in the following. For your convenience create a separate directory diana in your home directory under the 13

14 Figure 7: Application of algorithms to the EquationSet for the mc-tank 14

15 directory promot cd ~/promot mkdir diana Now there is a separate directory diana in your promot directory (~/promot) which we will use for all Diana simulation files. If you are unsure about the correctness of your definition of two-tank-plant, you can load the file two-tank-plant-correct.mdl. 1. Select the class two-tank-plant and choose in the Browser menu File > Export > Output To Diana. The Model-Output -Dialog is shown in Figure 8. Figure 8: Dialog to write a Diana model. 2. The directory for the simulation model, usually the current ProMoT directory (~/promot/diana, see Section 3.1) has to be supplied in the dialog. 3. With the button Diana Options you can start an additional dialog providing advanced export options. 4. With Check For Consistency you can check the model before the export, see Section The defaults supplied with this example are fine, press the Generate Model button. 6. Messages of export are shown in the Output Log. If an error is found by ProMoT, an error-message pops up. 7. After installation of Diana you can now run the simulation. In order to simulate the model directly perform the following steps. 15

16 Figure 9: Dialog for Diana simulation settings. 1. Select the class two-tank-plant and choose in the Browser menu Tools > Simulate Model. The Simulation Settings dialog is shown in Figure The Advanced button gives you additional option for the solver. However the default setting should be fine. 3. Press the Simulate Model button and a plot showing the simulation results appears (see Figure 10). 4. By pressing the button Edit Script you can also edit the Diana script that is used for simulation Simulation with DIVA At the Max-Planck-Institute in Magdeburg you also have the opportunity to use the simulation environment DIVA. Several file names for the generated DIVA files must be supplied. For your convenience create a separate directory diva in your home directory under the directory promot cd ~/promot mkdir diva Now there is a separate directory diva in your promot directory (~/promot) which we will use for all Diva simulation files. If you are unsure about the correctness of your definition of two-tank-plant, you can load the file two-tank-plant-correct.mdl. 16

17 Figure 10: Simulation results of the model. 1. Select the class two-tank-plant and and choose in the Browser menu File > Export > Output To Diva. The Model-Output -Dialog is shown in Figure The different file names to supply in the dialog are: The directory for the simulation model, usually the current ProMoT directory (~/promot/diva, see Section 3.1). The name of the CG-File; it will contain the complete equation system and can be used to look for shortened variable names that are valid in the Diva simulation. The user-defined part (Sub-name) of the generated Fortran files. This is only important, if you want to write your own.anl-files. The name of the.dat-file containing initial values and parameters (all numbers of the model). This name is also the name for the block in the Diva simulator later. There are two other files written, that are connected to the dat-file: a *.map-file containing the list of variables in the ProMoT model and their shortened names to access them in the Diva-simulator. a * pvmap.m-file that defines a mapping table to access the simulation results written by Diva in a simpler way in Matlab for plotting. The Latex-file contains a formatted documentation of the flat equation system of the current module. 17

18 Figure 11: Dialog to write a Diva model. And finally the *.anl file will be written to start only this closed ProMoT model in Diva. It does not contain any connection information and uses only one block. The name is needed for the inianl/a=* command in Diva. 3. The defaults supplied with this example are fine, press the Generate Model button. 4. The Code-Generator is invoked and creates the files. Messages of the Code- Generator and ProMoT are shown in the Output Log. If an error is found by ProMoT, an error-message pops up. 5. Open a new terminal window as described in Section 1.1 and change to the working directory (== generation directory in the Model-Output -Dialog): cd ~/promot/diva 6. Call on the command prompt of the terminal: dmake drun 7. Now you can run a simulation with the following commands in Diva: inianl/a=ttank/offline integrate/tend= Start another terminal, change to the correct directory with cd ~/promot and start Matlab, look at the results with dgr 7. 7 dgr is only working with Matlab version 7.5 (R2007b) or below 18

19 3.8 Are there other models to try? Other models are tank-plant and mc-tank-plant. You can test and modify them. They are ready for simulation. 19

20 4 Advanced Modeling 4.1 How do I write an elementary module? The tank example. Basic modeling in ProMoT works by defining not only the structure of the module, but also the behavior. This is mainly performed by defining variables and equations in the modeling language Mdl. An elementary modeling entity does not contain sub-modules but only terminals, variables and equations. We will now complete an implementation of an elementary module. There is a partial Mdl source provided and we have to define some more variables and equations in the respective sections of the Mdl-command ( :variables, :equations and :terminals ). The places to edit are marked with a Task! Comment. Figure 12: Completion of an elementary module within the editor Emacs. 1. Open the file ~/promot/my-tank.mdl in the editor Emacs with File > Open File. 2. Read the comments in the file and add a terminal out in the :terminals section, a variable a and an equation fd out as described by the Task! comments. Save the file with File > Save (C-x C-s). 3. Load the file as described in Section If errors occur, try to figure out what is wrong and repeat step 2 and step 3. 20

21 5. The file my-tank redefines the original class tank. You can write the Diva model again as described in 3.7. If errors occur here, you have to re-iterate steps 2, 3 and How can I find a specific modeling entity? Figure 13: Search dialog. 1. The GUI contains a Search -Dialog which allows to find specific classes or class parts by name (see Figure 13). 2. Click in the menu of the Browser Edit > Search. A dialog pops up. Enter mc-tank into the Class Name -Field and press the Search button. All classes containing the string mc-tank will be shown. You can also limit the search to find only the exact search phrase. The check-boxes Show classes and Show slots select, which entities you are looking for: whole classes or parts (submodules, terminals, variables) inside classes. With the context menu you can start actions on the found classes. 4.3 Oops, an error occurred! Figure 14: Error dialog. 21

22 1. ProMoT generates different kinds of errors: Syntax errors, when Mdl files are loaded or source-code has been changed. The example in the Figure 14 is of this kind. The numbers in front are the line numbers to locate the error inside the source file. Errors indicating inconsistent models when the Diva model is written. The final check of completeness and consistency is the model output, not the loading of your sources. There will be usually parts of your model named in the error text. The Visual Editor and the graphical views also show error messages, if an inconsistent module is opened (e.g. with links to undefined terminals). Sometimes (hopefully not too often) you may detect Bugs in the ProMoT software. These are also signaled as error messages. Please report them to the ProMoT authors. 2. Errors are not there to annoy the modeler. They get thrown to indicate that something has gone wrong. Hopefully they clearly indicate the reason for the problem. You can prevent some errors on model-output if you check your model before, see Section Please try to read and to understand the text of the error. Perhaps you can at least isolate the source of an error with the names occurring in the message. Names of modeling-entities are represented in a different way internally: part names (submodules, variables, equations, terminals) are prefixed by p- i.e. p-n means the variable n. Modeling entities have a prefix promot- in their internal name i.e. promot-tank is the class tank. 4. If you repeatedly get errors and you can not figure out, what is wrong, you can press the button Mail as Bug in the error-box and hopefully you will get an answer (or at least a counter-question) from a ProMoT-expert. 4.4 How can I use inheritance and arrays in my models? The mc-tank example. For experienced users there is a commented example of the multi-component tank (mctank) included in the directory. This module uses inheritance and indexed (arrayed) variables and equations. It inherits and uses the mass balance and all variables of the simple tank and adds component balances for 3 components. Also some of the previously used parameters and the torricelli-equation have to be adapted, to fit the new requirements. Look into the source file mc-tank.mdl. You can also simulate this model by writing the module mc-tank-plant as a Diva model. 22

23 5 How can I finish ProMoT? 1. Select the window of the Browser. 2. Important: Make sure you saved all classes. 3. Select in the Browser menu File > Exit UI & Server. 23