Fsim The process simulation for the Amiga 1992 by J. Hartkopf 0 Introduction This is the documentation of Fsim V1.0, a process simulation for the Amiga. Programming Fsim I used some object files created by Electronic Arts and published on Fish 185, which I have included to this disk. Notice that the author makes no guarantees or warrantees with this program and claims no responsibility for any damage or loss caused by this program. Notice that this program should not be used as part of any commercial package without my explicit written consent. Please send bug reports, critics and good ideas to J. Hartkopf Vorwerk 21 W-2058 Schnakenbek Germany Ok, here is an overview about the doc contents: 1 What´s Fsim 2 How it works 3 Some stuff needed to run Fsim 4 Installing Fsim 5 Create a simulation - use of the FsimParser 5.1 Starting FsimParser 5.2 The Main window 5.2.1 Configuring the Parser 5.2.2 Load a model 5.2.3 Parsing and compiling the model 5.2.4 Exit FsimParser 5.3 The Run/Save window 6 The simulation´s user interface 6.1 How to start a simulation 6.2 The main menu 6.2.1 Start simulation run 6.2.2 Break simulation run 6.2.3 Change the inital values of the DEQ´s 6.2.4 Change the model parameter 6.2.5 Change the graphical output boundaries 6.2.6 Measuring the X-axis 6.2.7 Exit the simulation 6.3 The ´Data Handling´ window 6.3.1 Save Simulation parameter 6.3.2 Save simualtion results 6.3.3 Push calculated values into a file 7. How to create a model 7.1 Model programming and exeptions from C language 7.2 System Variable 7.3 Four funktions to create a model 7.3.1 The ´SimSys´ funktion 7.3.1.1 Differential equations 7.3.1.2 Algebraic equations 7.3.1.3 Output definitions 7.3.2 The ´IniX´ funktion 7.3.3 The ´IniPar´ funktion 7.3.4 The ´IniDEQ´ funktion 8 Bugs 9 Future of Fsim 1 What´s Fsim During my studies of chemical engineering it was my instruction to automate a bioreactor with an industrial process control system. The development and testing of new control strategies is limited by high experimental expenditures in biological production process. A very effective methode is the ( online ) emulation of the entire bioreactor-plant with an online simulation system. During the development the simulator, a VMEbus system, is linked to the control system instead of the plant. As I noticed the effect of the methode, the idea was born to create a (offline!) simulation system for the Amiga. It should be able ( his prototype alike ) to calculate complexe systems consisting of algebraic and differential equations and show the results in a graphic representation. The idea: A user with only a small knowledge of C programming should be enabled to create complexe models and connect them to a comfortable user interface. The interface enables the user to take an interactive influence to the simulated process and save the simulation results to disk. Fsim is not a professional simulation system, and there are still some problems which have to be fixed. Anyway, Fsim keeps the significant characteristics of commercial simulation systems and I think it is useful for someone who engages in system simulation for the first time. 2 How it works If we like to create a simultion which discribes a special process in nature or technology, we need at first a mathematical model description, which must be written as an ACSII text file. So the user must be able to define formulas in C language. There are some examples in the folder which show how to do this ( see 7. ). The model, written in C language, will be adapted by a program called ´FsimParser´. The first result of this process will be a new code code called ´Fsim.c´. On a second stage the FsimParser calls a C compiler and a linker to produce an objet code ´Fsim.o´. This object will be linked with some other objects to a runable simulation called ´Fsim`. In order to do all these things, the FsimParser executes a batch file named ´s:MakeSim.BAT´ which starts compiler and linker. FsimParser C compiler linker model ----------> Fsim.c ----------> Fsim.o --------> Fsim | | Main.o ------| SaveILBM.o---| Packer.o-----| ilbmw.o -----| iffw.o-------| The source file ´Fsim.c´ contents a system of functions to solve differential equations ( DEQ´s) in defined steps by the methode of Runge and Kutta . The object file Main.o´ contents all functions of the user interface and the graphic routines. The other object files are from Fish 185 which make it possible to save the results as IFF ILBM. Thanks to Electronic Arts. In the following chapters is discribed how to install Fsim, how to use the FsimParser and handle its results, which means compiled simulation. 3 Some stuff needed to run Fsim If you like to run Fsim, you need some files and programs which are not included ( Copyright! ) to this disk. As Fsim fetches the user specific model and creates a new source code in C language, we need access to a C compiler and a linker. In this version Fsim only supportes the Lattice/SAS compiler V5.x , sorry. The Lattice/SAS compiler must be assigned to drive , otherwise Fsim won´t work. On drive we need: - RUN (from WB disk) - SORT (from WB disk) - COPY (from WB disk) - SHOW (from Fish 185 ) - MuchMore (should be included to this disk in the c folder) In the folder we need the - Icon.library - ARP.library 4 Installing Fsim There are two different ways to install Fsim: INSTALLATION VIA CLI. If you are a fellow who preferes the well known and well tried methods, then - open a CLI window - change current directory, ´cd Fsim´ - type ´execute install.bat dh0:´ and hit to install Fsim to drive . INSTALLATION VIA INSTALL-PROGRAM The alternative way to install Fsim to disk: - A double click on the the ´Install_it´ icon starts the Fsim installing routine. A mouseclick to the string gadget, and the cursor will appear. Now enter drive and path where Fsim shall be installed and click on the ´Do it´ gadget. LAST STEP - No matter how do you installed Fsim, finally you have to include assign Fsim: /FsimX in your startup-sequence, and release a system reset. Otherwise the linker won´t be able to find the necessary object files. 5 Create a simulation - use of the FsimParser After the model is defined as ASCII file, we have to analyse it and create some formulas which enables the system to solve differntial equations. Last of all we have to compile the code and connect the resulting object file to a graphical user interface. That´s it, what the FsimParser does. 5.1 Starting FsimParser In this version the FsimParser can only be started from CLI. Change directory to and type ´FsimParser´. If you are so dare to start the FsimParser from workbench, your system will crash and the Guru will visit you immediately. Maybe I´ll fix this offence in a next version. 5.2 The Main window If the parser has been startet, a window opens with four gadgets, the - Configure gadget - Load gadget - Parse gadget - Exit gadget Let´s look what we can do with them .... 5.2.1 Configuring the Parser Clicking on the ´Configure´ gadget of the main window, the configuration window opens. Since some functions of the FsimParser requiring an editor, the user is requested to define path and name of his favorite editor ( Memacs, DME... ). As mentioned in chapter 2, the FsimParser needs a batch file to start the compiler and the linker. Path and name of this file are also defined in the configuration window. To change path/name of editor or batch file, click on the input field and enter a new path/name. Pushing the ´Exit´ gadget will use the actual configuration, but if you leave the FsimParser, all changes will be lost. To avoid this, save the Fsim configuration by pushing the ´Save´ gadget. 5.2.2 Load a model Clicking on the ´Load´ gadget, the ARP file requester opens and asks for path and name of a model to be loaded. After a file is selected by pushing the ´OK´ gadget of the file requester, it will be loaded as temporary file . Now we are ready to parse the model and execute the batch file for compiling and linking. 5.2.3 Parsing and compiling the model Clicking on the ´Parse´ gadget, the parser is going to analyse the model and creates the source code named . After complation of the source code the FsimParser opens a CLI window and executes the batch file. If everything has been gone all right, the Main window will close and the Run/Save window will appear. More about this: see 5.3 If something is going wrong with the compiler or linker, the user is promted to close the CLI window with the ´Endcli´ command. If done, a small error window will appear with three gadgets connected to. - The ´Aha´ gadget With a mouseclick to the ´Aha´ gadget the user acknowledges the compiler or linker failure and the FsimParser returns to the Main menu. - The ´Edit´ gadget a mouseclick to ´Edit´ gadget starts the editor which is defined in the ´Configure´ window and edits the model that should be adapted. Leaving the editor will cause a reload process. It means that the ( corrected ? ) model will be copied again from disk to . - The ´Show´ gadget A click to the ´Show´ gadget starts the program ´MuchMore´ which should included in the folder. It shows the compiler errors which occured during compilation. With the ´q´ key we are leaving ´MuchMore´ and the program returns to the error window. 5.2.4 Exit FsimParser A mouseclick to the ´Exit´ gadget in the Main menu will quit the FsimParser. 5.3 The Run/Save window If parser, compiler and linker have finished its work successfully, a source code and a runable simulation have been created. The Run/Save window allows to save these files to disk or start the simulation immediately. - The ´Save´ Gadgets With a mouse click to one of the two ´Save´ gadget we can save the C source code completed by the parser, or the compiled and linked simulation to disk. - the ´Run´ gadget closes the window and starts the simulation. Notice: in this case the simulation is started as independent process and the FsimParser is still in the system memory. So it can happen to you that the simulation runs a little bit slow. In this case quit the parser and start the simulation from workbench ( see: 6.1 ) - a click to the ´Edit´ gadget edits the model ( see: 5.2.1), - the ´Exit´ gadget closes the window and the program returns to the main menu. 6 The simulation´s user interface The following chapter describes how to use the compiled simulation. It shows how to modify the graphic output, how to take an influence to the process and how to save the simulation results. 6.1 How to start a simulation In contrast to the FsimParser, which can´t started from worbench, the compiled simulation can alternative be started from CLI or workbench. Remember, there is a third possibility to start the simulation - from the parser. But in this case the parser still keeps on running, occupies memory and steals system time. 6.2 The main menu Starting the simulaiton, the main menu appears. In this menu it is possible to select one of the eight menu points, marked by a red frame which follows the mouse moves. A click on the left mouse buttom activates one of the selected menu points which are dicribed in the next sections. 6.2.1 Start simulation run Select ´Simulation´ and push the left mousebuttom to start the simulation. If the ´data push´ is enabled ( see 6.3.3 ), it will be disabled at the end of the simulation run. 6.2.2 Break simulation run During simulation a click on the left mousebuttom will break the simulation run and the ´BREAK´ menu with four items connected to appears. - The ´Stop simulation´ item stops the simulation run and the program returns to the main menu - The ´Continue Simulation´ item closes the ´break´ menu and continues the simulation run - The ´Show Results´ item brings the output screen to front. With another push to the left mousebuttom, the ´BREAK´ menu appears again instead of the output screen. - The ´Parameter´ item opens the parameter window. Now the user is enabled to change some simulation parameter. As consequence of this manipulation the simulation will have a changed characteristic. 6.2.3 Change the inital values of the DEQ´s A simulation which contents differential equations (DEQ), calculates its results with the results one calculation step before. Starting the simulation, there is no previous calculation step and so we have to define a starting value for DEQ´s. In the ´Initial Value´ window it is possible to select one of this values which has to be changed. Similar to the main menu the selected variable is marked by a red frame. A push on the left mouse buttom, and the user is promted to enter a value at the input field. If there is not enough room to show all variables on one page, select the next page by clicking the ´More´ gadget ( previous page: ´Less´ gadget ). 6.2.4 Change the Model parameter If the user likes to study the influence of a parameter to the simulated system and the consequences of its manipulation, it is necessary to change the value of the inquired simulation parameter. This is possible by selecting the ´Parameter´ item in the main menu. An other possibility to watch the influence of a parameter is to break the simulation, change parameter, and continue the simulation again. The handling of the ´Parameter´ window is similar to initial values ( see: 6.2.3 ). Notice: Leaving the simulation will cause a loss of all changes. To avoid this: see 6.3.1. 6.2.5 Change the graphical output boundaries The boundaries ( Min/Max ) of the graphical output are pre-defined by the user in the simulation model. Sometimes the graph breaks the output boundarys, as soon as some parameter had been changed. If this happens to you, it is adviseable to change the boundaries by selecting the ´Graph´ item. 6.2.6 Measuring the X-axis Selecting the ´Interval X-Axis´ item opens a small window with three gadgets conneted to. With these gadgets we have an influence to the X-axis of the graphical output, to the calculation step and the simulation speed. - ´X-Axis Max´ The intervall for the graphical representation starts at 0 and it will end with a value named ´EndTime´. During simulation a system-variable named ´time´ will be increased until it will reach the ´endtime´ value. The passing of the ´time´ variable over the ´EndTime´ value consequences the termination of the simulation. A mouseclick at the ´X-Axis MAX´ gadget activates the cursor, and the user is requested to enter a ´EndTime´ value. - ´Calculation Step´ During simulation the mathematical system will be calculated cyclically. We have noticed: the system-variable ´time´ will be increased by a value named ´step´. A modification of these step consequences two effects. A magnification of this value will speed up the simulation, but it magnifies the calculation inaccuracy too. This deviation can go too far, so that the differential domain of the Runge/Kutta methode is left. If this happens to you, we can´t talk about ´simulation´ any more, since the graph will react violently and draws wild patterns. Changing the step is similary to a change of the ´endtime´ by a mouseclick to the ´Calculation Step´ gadget. 6.2.7 Exit the simulation Selecting the ´Exit´ item quits the simulation. 6.3 The ´Data Handling´ window Selection of the ´Data Handling´ item opens a window which enables the user to save parameter and the simulated datas in different ways: 6.3.1 Save simulation parameter If the operator quits the simulation, all changes to the parameter, intial values and output boundaries will be lost. To avoid this, all these stuff has to be changed in the model file . Thus is useful to save all parameters, inital values and boundaries to a ASCI file. The Data Handling´ window shows path and name where the datas should be saved to. A mouseclick to the input field opens a requester, asking for a new path/name, and a mouseclick to the ´Save Parameter´ gadget starts the save-procedure. 6.3.2 Save simulation results Similar to 6.3.1 it is possible to save the simulation results as IFF ILBM. A mouseclick to the ´Save Results´ gadget saves the result screen to the selected path/name. During the save-process the graphic chart is shown as front screen. 6.3.3 Push calculated values into a file An other way to save the simulation results is given with the push option. A mouseclick to the ´Data Push´ gadget toggles its image from ´no´ to ´yes´ or vice versa. If the image shows ´yes´, during simulation the simulated datas will be written into as ASCII file. Path and name of the file can be selected with a file requester which opens by a mouseclick to the ´Path/File´gadget. Notice: A termination of the simulation enables the data push option. 7. How to create a model The following chapters are describing how to create a model code which can be analysed by the FsimParser. Some examples are included to this disc, but it I would go too far to explain its technical and scientific attributes. 7.1 Model programming and exeptions from C language As shown in the chapter 2, the FsimParser creates a source code in C language. So the model programmer must be able to define his model in C language. In this version the user must pay attention to some perculiarities: - It makes no sence to declare variable types like int ene, mene, miste; bool es, rappelt, in, der; float kiste; as the FsimParser declares all variables. ( see 7.2 ) - It is forbidden to use the ´=´ character in comments Example: /* HT = Heat transfer [KW/h] */ - Never use Pre-processor commands like #define BlaBlaBla 08_15 in your model source, since ´#´ is a reserved character. ( See 7.3.1.1 ) 7.2 System Variable As mentioned in 7.1, the user needs not to declare any variables. The parser will detect the variables in the model and declare them as FLOAT. Its is allowed to name the variables and parameter with any names, excepted by three reseved words: endtime time step ´endtime´ is the simulation interval of the X-axis ´time´ is the actual simulation time which runs from 0 to ´endtime´ and will be increased by the ´step´ value It is allowed to use this three variables in your model. An expression like up = contant * time / endtime; calculates a graph which begins with ´0´ and ends at ´constant´ when the simulation is finished. 7.3 Four functions to create a model There are four functions required by Fsim: - The ´SimSys´ function - The ´IniX´ function - The ´IniPar´ function - The ´IniDEQ´ function You must declare this functions in your model, even if one of them is not used. If not, the parser will display an error message. In the following chapters is declared how to use this functions. For this I will explain a model called ´Fox and rabbit´ which simulates the population of fox and rabbit on a limited area. Here it is: void SimSys() { MYrabbit = MYrabbitMAX - fox * MYrabbitDeath; MYfox = - MYfoxDeath + rabbit * MYfoxmax; #fox = fox * MYfox; #rabbit = rabbit * MYrabbit; out(0, fox , 0.0 ,300.0); out(1, MYfox ,-0.5 ,0.5); out(2, rabbit , 0.0 ,2000.0); out(3, MYrabbit ,-0.5 ,0.5); } void IniX() { endtime = 220; step = 0.5; } void IniPar() { MYrabbitmax = 0.1; MYrabbitdeath = 0.001; MYfoxmax = 0.0001; MYfoxdeath = 0.05; } void IniDEQ() { fox = 80.0; rabbit = 80.0; } This model is very simple and it simulates the populations not truthful, but it shows how to create a dynamical model with only a few lines. 7.3.1 The ´SimSys´ function In the SimSys function we are able to define algebraic and differential equations and connect them to a complexe system. 7.3.1.1 Differential equations Fsim allows the user to define differential equations (DEQ´s) of the first order like . dX X = -- = f( X, c1, c2 ... ) dt Fsim builds the function to solve these DEQ´s and calculates the X value during simulation. NOTICE: The first derivative of a DEQ is marked with the ´#´ character. For example: Equations first order like dX -- = X + 1 dt , X = X + 1 . X = X + 1 are written as #X = X + 1 IT IS NOT ALLOWED to define a DEQ of second or higher order 2 d X dX --- = -- + X 2 dt dt ,, , X = X + X .. . X = X + X as ##X = #X + X IN THIS CASE you have to split it in two DEQ´s. . X = X + A written as #X = X + A and . A = X written as #A = X Ok, this are the Fsim specifically rules for DEQ´s. Now we try to define the population of fox and rabbit with differential equations (DEQ). We know about fox and rabbit: - The increase of the fox population is dependet by the quantity of foxes ´fox´ and a specifically growth rate ´MYfox´. So we can formulate the DEQ . dfox fox = ---- = fox * MYfox dt . ( It is the typical form of a DEQ: X = X * A ) In our model we define #fox = fox * MYfox; to describe the fox population. - Similar to the fox population we define the DEQ for the rabbit population. It includes the quantity of rabbits and a specifical growth rate ´MYrabbit´ . drabbit rabbit = ------- = rabbit * MYrabbit dt and in our model we have to write #rabbit = rabbit * MYrabbit; Our model is not completed since we have not calculated the specifical growth rates ´MYfox´and ´MYrabbit´ which connect the two DEQ to a dynamical system. 7.3.1.2 Algebraic equations In the first lines of the SimSys-function is specfically growth rate of fox and rabbit declared as MYrabbit and MYfox. A population of rabbits is growing with a maximal rate ´MYrabbitMAX´ ( If there is enough food! ). Some rabbits will be catched by the foxes. This lowers the growth rate by the of the population of foxes ( More foxes, less rabbits! ) and a rate ´MYrabbitDeath´. MYrabbit = MYrabbitMAX - fox * MYrabbitDeath; If there are no rabbits, the foxes will starve by hunger with a rate named ´MYfoxDeath´. If there are some rabbits, they will be catched by the foxes and the famine is mitigated. MYfox = - MYfoxDeath + rabbit * MYfoxMAX; As long as the growth rate ´MYfox´ are smaller than zero, the population lowers, if the rate is greater than zero, the population grows. 7.3.1.3 Output definitions At last we have to specify the output variable which shall be plot by Fsim. It is possible to define 7 output canals with the number 0 to 6. out(canal, variable, min, max ); At first we have define the canal number and then we have to select the variable name. Ok, now it is necessary to define the graphical output boundaries ´min´ and ´max´. Example: In our model we like the population of the foxes and the rabbits. We know that fox population will be 0 at the minimum and 300 at its maximum and the population of the rabbits will be 200 (maximum!). So we define: out(0, fox ,0.0 ,300.0); out(2, rabbit ,0.0 ,2000.0); NOTICE: You MUST define the min/max output values as floating point values. If you define the boundaries as integer values Fsim won´t work correctly. 7.3.2 The ´IniX´ function In this functions we define our simulation interval. During simulation a variable named ´time´ will be increased by the value of the ´step´ variable until ´time´ has reached the ´endtime´ value we have defined in the ´IniX´ function. void IniX() { endtime = 220; step = 0.5; } 7.3.3 The ´IniPar´ function In the SimSys function we are using some parameter but we don´t care about it´s values. It is possible to attach values to the parameter in the SimSys function. In this case it is impossible to change the value during running simulation. If we like to change the parameter during simulation, we have to define our parameter in the ´IniPar´ function. void IniPar() { MYrabbitmax = 0.1; MYrabbitdeath = 0.001; MYfoxmax = 0.0001; MYfoxdeath = 0.05; } NOTICE: These values MUST be defined as floating point. 7.3.4 The ´IniDEQ´ function If the model includes some DEQ´s, Fsim calculates its results by the methode of Runge and Kutta. The solving of a DEQ by this methode requires the result of the DEQ one step before. At the begin of the simulation we have to define a start value, because there is no previous calculation step and so there is no result of the DEQ. We define this starting values for every DEQ in the ´IniDEQ´ functions. We are calculating the population of fox and rabbit with two DEQ´s, so we define two starting values in our model: void IniDEQ() { fox = 80.0; rabbit = 80.0; } 8 Bugs There are still some bugs which have to be fixed. - The FsimParser can only be started from CLI - If you select a variable or parameter in the ´Parameter´, ´Graph´ or ´Initial´ menu, the actual value does not appear in the input field correctly. Maby there are some more bugs I have not noticed. If you find some more, please let me know. 9 Future of Fsim In this version I have tried programming the basic functions of a simulation system. It works, but there is a still some work to be done. - The bugs have to be fixed - The user should be enabled to define his own functions - Fsim should use the DICE compiler. For the moment I am glad that Fsim is working. If you use it and you have written some interesting models, please let me know. Have fun. J. Hartkopf