IDA Solver User’s Guide - equaonline.com · 1999-11-01 · 8 IDA Solver User's Guide, version...

IDA Solver

User’s Guide

Bris Data AB

October 1999

for IDA Solver v. 8.07 andIDA Simulation Environment 2.11

Bris Data AB 1994-1999

2

IDA Solver User's Guide, version 8.07, October 1999 Bris Data AB 1994 -1999

Table of Contents

1 GENERAL INFORMATION ................................................................................... 5

2 INSTALLATION OF IDA SIMULATION ENVIRONMENT ..................................... 7

2.1 Disk Organization.......................................................................................................................................... 7

3 OTHER SUPPORTING SOFTWARE ...................................................................... 8

3.1 Support Files for MS Excel........................................................................................................................... 8

3.2 HTML Documentation Generator ............................................................................................................... 8

4 DEVELOPMENT METHODOLOGY ...................................................................... 9

4.1 Setting up a Project Directory...................................................................................................................... 9

4.2 The Project Definition File ........................................................................................................................... 9

4.3 The IDA NMF Translator Configuration File .......................................................................................... 10

4.4 Translation from NMF to FORTRAN or C .............................................................................................. 10

4.5 Compiling ..................................................................................................................................................... 10

4.6 Running the Program.................................................................................................................................. 11

4.7 Cleaning-up.................................................................................................................................................. 11

4.8 Viewing the Results in Excel....................................................................................................................... 12

5 RUNNING A DEMONSTRATION ........................................................................ 13

5.1 Translation................................................................................................................................................... 13

5.2 Creation of a DLL ....................................................................................................................................... 13

5.3 Running a simulation .................................................................................................................................. 14

5.4 Inspection of the results .............................................................................................................................. 14

6 COMPONENT DEVELOPMENT ......................................................................... 15

7 SIMULATION PROGRAM SIZE .......................................................................... 16

8 THE SYSTEM DESCRIPTION FILE (FILE.IDA).................................................. 17

8.1 Model Description ....................................................................................................................................... 17

8.2 IDA Solver Configuration........................................................................................................................... 17

3


8.3 External Files ............................................................................................................................................... 17

8.3.1 External Files for Input Time Series....................................................................................................... 18

8.3.2 External Files for Output Time Series .................................................................................................... 18

8.4 Local Constants ........................................................................................................................................... 18

8.5 Tables for Time Dependent Input .............................................................................................................. 19

8.6 Instantiating NMF Components................................................................................................................. 19

8.7 Coupling of Modules ................................................................................................................................... 21

8.7.1 Coupling on the Level of Variables......................................................................................................... 21

8.7.2 Coupling on the Link Level ..................................................................................................................... 21

8.8 Boundary Conditions .................................................................................................................................. 22

8.9 Initial Values ................................................................................................................................................ 23

8.10 Integration Parameters ............................................................................................................................. 23

8.10.1 Specifying Output to file.RES and to the Screen ................................................................................. 24

8.10.2 Specifying Other Output........................................................................................................................ 25

8.11 Number Formats........................................................................................................................................ 26

9 THE OUTPUT...................................................................................................... 27

9.1 Output File file.RES .................................................................................................................................... 27

9.2 file.END ........................................................................................................................................................ 28

9.3 Files with the extension .PRN. .................................................................................................................... 28

10 THE IDA SOLVER CONFIGURATION.............................................................. 29

10.1 Command Line Options ............................................................................................................................ 29

10.2 Input - Output Options ............................................................................................................................. 30

10.3 Control Options ......................................................................................................................................... 30

APPENDIX 1 – GENERATED CODE OPTIONS...................................................... 31

APPENDIX 2 – CONTENTS OF MAE LIBRARY ..................................................... 32

APPENDIX 3 – SAMPLE SCREEN LOG ................................................................. 33

APPENDIX 4 – SAMPLE SYSTEM DESCRIPTION FILE (*.IDA) ............................ 34

4


APPENDIX 5 – HEADINGS IN THE SYSTEM DESCRIPTION FILE ....................... 37

APPENDIX 6 - CONFIGURATION OPTIONS FOR IDA SOLVER........................... 38

5


1 General information

IDA Simulation Environment (IDA SE) consists of IDA NMF Translator, IDA Modeller andIDA Solver. IDA NMF Translator translates mathematical models, or components, written inthe Neutral Model Format (NMF), to FORTRAN or C code. In order to model some process,i. e., to build a simulation model, a number of instantiated components, or modules, areconnected together. IDA Solver is employed to solve the system of differential-algebraicequations that the equations of the modules will form. IDA Modeller may be used tointeractively connect and parameterize components, run simulations and view results.

There is three different ways of constructing a simulation problem to be solved by IDASolver:

1. By generation of the IDA Solver system description file from IDA Modeller2. By manually setting up the system description file3. By generation of the system description file from some other front-end application

This manual explains how to manually set up an IDA Solver system description file. Thisinformation is, of course, also required to write ones own front-end application. However, it isnot necessary to understand this manual in order to set up simulation problems from IDAModeller.

In order to use the IDA SE in its minimum configuration, i.e, without IDA Modeller, makesure that:

• IDA NMF Translator has been installed.

• IDA Solver has been installed.

• A FORTRAN or C compiler has been installed and is available via the DOS path.

The following compilers are supported by IDA Simulation Environment 2.11:

- Lahey Fortran 90 v 4.0 & 4.5- Lahey/Fujitsu Fortran 95 v 5.5- Digital Visual Fortran v 6- GNU C, release gcs-1.1.2- Microsoft Visual C++, v.5 & 6

The C code generator is a recent addition to IDA Simulation Environment and may thereforebe less reliable than the FORTRAN counterpart.

IDA runs on PC's with Windows 95, 98 or NT. 16 Mb of RAM and 20 Mb of available diskspace is required but more of both is strongly recommended.

Finally, in this document the different fonts have the following meanings:

6


bold input on a command line in a DOS window

italic entities to be named by the user

CAPITAL LETTERS NAMES OF FILES, DIRECTORIES ETC.

KEY WORDS NAMES OF SECTIONS ETC., IN THE INPUT ANDOUTPUT FILES

7


2 Installation of IDA Simulation Environment

IDA SE is distributed in a single self-extracting file. Double-click on the file from theExplorer to start the installation procedure. The distribution may contain different installablecomponents depending on the configuration that has been purchased.

The user is asked about the following options in the installation process:

IDA Modeller with availableapplications

Installs IDA Modeller and enables the user to choosewhat included applications to install.

The distribution may contain one or more IDAapplications. It may be interesting to install anapplication as reference material even if it is from adomain that is of no immediate concern.

The Create new application option enables the user touse IDA Modeller for construction of IDA Solversystem description files.

IDA Solver stand alone The option enables a user to run IDA Solver directlyfrom a DOS prompt or from a foreign front-endapplication.

IDA NMF Translator Installs the IDA NMF Translator

2.1 Disk Organization

The installation will create a number of directories organized as a tree with its root in adirectory chosen by the user. Below, this is called the installation directory. A fileREADME.TXT in each main directory explains the contents.

The directory in which the development will take place, the project directory, may then belocated somewhere else. In this way, the files belonging to a certain project may be kept in onedirectory; different projects can be placed in separate directories. Each project directoryrequires a minimum set of files to be imported from the original IDA SE as installed.

8


3 Other supporting software

3.1 Support Files for MS Excel

Result files intended for plotting, with the extension .PRN, with or without column names(see 9.3), may be imported to MS Excel (see 4.8). For this purpose study the fileC:\inst_dir_path\EXCEL\README.TXT.

3.2 HTML Documentation Generator

An HTML presentation of an NMF library may be automatically generated using the NMF toHTML utility. A hyperlink list of all models including the first line of each abstract isgenerated. In the generated HTML presentation of each model, equation variables are linkedto their declaration location, making it easy to locate variable descriptions.

Developers are encouraged to make their libraries available to others by posting them on theInternet. A central page (www.brisdata.se/nmf/simone.htm) provides links to developerlibraries. The NMF to HTML utility may be downloaded from the same page.

http://www.brisdata.se/nmf/simone.htm

9


4 Development Methodology

The development from NMF components to a running program, in the form of an executableDynamic Link Library (DLL), includes the steps described in this chapter.

4.1 Setting up a Project Directory

Start the IDA NMF Translator (from the Programs menu under the Start button in Windows95). In IDA options under the Options menu select the compiler (see section 1) you are goingto use for the project. Then select New in the Project menu and create a project directory in asuitable location by entering the new directory name, proj_dir, and a file name, file.TYP,according to

proj_dir\file.TYP

The following support directory and files will be created in, or copied to, the new projectdirectory:

compiler_name directory to contain future object files

MAKEFILE input file for ”MAKE”

IDA.CFG configuration file for simulations by IDASolver

GLOBAL.NMF standard global definitions for NMF (onlycopied if it does not already exist)

file.TYP project definition file

4.2 The Project Definition File

A project definition file, file.TYP, was produced by the previous step. It should contain thenames of the user supplied NMF component files relevant to the current project. Therefore,the file is automatically opened by the translator for the user to enter the names of desiredNMF files. These should be residing in the project directory. A project definition file may beedited at any time.

Every project directory must contain at least one project definition file. It supplies the IDANMF Translator with a list of the NMF components to be translated. If there are more thanone project definition file in a project directory, one may choose which one to use by selectingit under Select (the first time after starting the translator) or Select Another in the Projectmenu.

The project definition file is also used for creating the files _CALLPRJ.FOR andMAKEOBJS described in 4.5. It should have the following format:

10


file1.NMF version_numberfile2.NMF version_number…

version_number is the version of the NMF language, currently 3.02. An example of a projectdefinition file may be found in 5.2.

4.3 The IDA NMF Translator Configuration File

The translator has several configuration parameters that may be saved in a file NMF.CFG inthe current project directory. The parameters are fully explained in the IDA NMF TranslatorUser’s Guide and online help (which contains the same material). See also the tutorial A newIDA Application, basic steps. Two standard option sets are available in the translator, NMFDebug and NMF Release. The former is useful for development of NMF code. It does notinclude generation of a DLL description file for IDA Modeller. The NMF Release set willgenerate such a file.

4.4 Translation from NMF to FORTRAN or C

To start a translation, select Current project in the Translate menu. The IDA NMF Translatorwill go through the NMF files one by one, check them for syntax and semantic errors and, ifthey are all correct, translate them to FORTRAN or C code.

One should remember that global definitions are usually not present in the listed NMF-files.The Translator takes the standard global definitions from files QUANT.NMF, LINK.NMFand CONST.NMF from subdirectory NMF of the installation directory. One can add somemore global definitions by editing the file GLOBAL.NMF in the current project directory.GLOBAL.NMF is not and should not be included in the list in the project definition file.Users who want to change or extend the global definitions may do so in the fileGLOBAL.NMF, in each project directory. To enhance maintenance properties, however, thefiles containing the original global definitions (QUANT.NMF, LINK.NMF andCONST.NMF) in the directory C:\inst_dir_path\NMF from the installation should be leftunaltered.

4.5 Compiling

By use of the MAKE utility, the FORTRAN or C code generated by the IDA NMF Translatoris compiled and stored as a DLL. It may then, at run-time, be called by IDA Solver. Thecompilation is started by selecting Make DLL in the Project menu. The compiled library willbe saved as project_name.DLL in the current project directory (project_name is the name of acurrent project definition file).

The files,

_CALLPRJ.FOR (used for calling components in Fortran from the solver)or_CALLPRJ.CPP (used for calling components in C from the solver)

11


MAKEOBJS (support file for the make utility)

are necessary for making IDA Solver and the compiler aware of what NMF components areused. These files are generated by the MAKE utility before compiling.

4.6 Running the Program

If the compilation terminates successfully, the generated DLL can be used in simulations,together with other precompiled DLLs. First, however, the system to be simulated has to bedefined in a system description file. There are three ways of running IDA Solver.

First, one may install the new set of components in IDA Modeller, as a new application or aspart of an existing. The former is described in the tutorial A new IDA Application, basic steps.The latter is explained in the documentation for IDA Modeller.

Secondly, one may enter the command line

IDA i=file

from the project directory in a DOS window. IDA refers to the main program IDA.EXE. istands for input and file.IDA is a system description file as described in chapter 8.

Thirdly, in the special case when the name of the system description file has been chosen toIDA_LISP.IDA, IDA Solver may be started by selecting Run in the Project menu of thetranslator.

If the execution proceeds without interruption, the results of the simulation may be inspectedin the output files (see chapter 9). Finally, it is possible to obtain files prepared for plotting(see chapter 10).

4.7 Cleaning-up

Working with IDA SE will generate a number of files. These files may be selectively deletedafter terminating a session. The following commands entered from a DOS prompt will removefiles produced during compiling, without loss of information necessary for a continuation ofthe work at a later time:

deletesDEL *.OBJ object files from compiling

(in sub-directory LF90 using the Lahey Fortran 90 compiler)DEL *.LST files for debugging purposes (using the Lahey compiler)

Finally, the following commands will remove files produced when running the program:

deletesDEL *.RES formatted result files

12


DEL *.END files containing final variable valuesDEL *.PRN plotting files

4.8 Viewing the Results in Excel

The Excel document described in 3.4 includes a macro sheet for plotting of results in MSExcel. The macro adds a new menu item, IDAplot, in the Tools menu of Excel. Selecting this,opens a dialogue box for choosing the desired result file (file.PRN without column names, see9.3). If Open is selected, a new workbook is created and the result file is read and stored in anew worksheet, called Sheet1, in this workbook. A chart sheet is then automatically producedfor every column of the result file except the first one, the time coordinate, that is used for thex-axes of all the charts.

13


5 Running a demonstration

This chapter illustrates the methodology of the previous chapter by describing how to run oneof the demonstration examples at a DOS prompt, i.e., without using IDA Modeller. A similarexample that uses IDA Modeller and with more explanations is described in the tutorial Anew IDA Application, basic steps.

The following steps are covered here:

• Translation, by IDA NMF Translator, of some selected NMF components• Creation of a DLL, containing the chosen components• Running of a simulation at the DOS prompt• Inspection of the results

5.1 Translation

The sample NMF files contain some simple electrical models, sufficient to build an electricaloscillator. To translate the NMF files, start the IDA NMF Translator (from the Program groupIDA Software). Start by selecting in IDA options under the Options menu the compiler (seesection 1) you are going to use for the project. Then in the Project menu of the translatorchoose New, find the directory C:\inst_dir_path\SAMPLES\ELOSC and type the file nameELOSC.

Choose Current project in the Translate menu. The NMF files in the directory are checked andtranslated into the following files (assuming that generation of FORTRAN has been selectedunder IDA options in the Options menu.)

ELCAP.FORELNODE.FORELCOIL.FORELDIOD.FORELRES.FOR

5.2 Creation of a DLL

Select Make in the Project menu to invoke the MAKE utility. Initially, it processes the projectdefinition file, ELOSC.TYP, to generate the two files _CALLPRJ.FOR and MAKEOBJS. Theproject definition file has the following contents:

ELCAP.NMF 3.02ELNODE.NMF 3.02ELCOIL.NMF 3.02

ELDIOD.NMF 3.02

14


ELRES.NMF 3.02

Then, the MAKE utility starts the compiler and the new FORTRAN sources are compiled and,finally, saved in a library called ELOSC.DLL.

5.3 Running a simulation

A simulation run is started by the command

IDA i=ELOSC

in a DOS window, entered from the directory C:\inst_dir_path\SAMPLES\ELOSC. ELOSCrefers to the system description file ELOSC.IDA. IDA Solver reads the system descriptionfile, performs the simulation and produces the following output files:

ELOSC.RES readable outputELOSC.END final simulation values, may be used for starting a new simulationELOSC.PRN file for post processing (i. e., plotting) as chosen in ELOSC.IDA

The output files are described in chapter 9.

5.4 Inspection of the results

The output files may be visually inspected. In the file ELOSC.RES, all variable values of allmodules at all timesteps can be found.

Diagrams of the output variables listed in the sub-section LOG of the INTEGRATION section(see 8.10.2) versus time are obtained using MS Excel as described in 4.8.

15


6 Component Development

In addition to the NMF components belonging to the demonstration examples, morecomponents, tested and assumed to be stable, may be included (depending on configuration)in the IDA Solver installation. Their NMF files can be found in the directoriesC:\inst_dir_path\LIB\appname\NMF, where appname is the name of an installed IDAapplication.

Making full use of the IDA SE definitely means writing your own NMF components. Thecraft of component development is supported by the NMF Handbook, which is included in theinstallation C:\inst_dir_path\DOCUMENTATION\HANDBOOK.PDF. The project definitionfile, file.TYP (described in 4.4), must contain references to new components underdevelopment in a project directory, for these to be translated, compiled and included in theDLL.

By performing step 1 - 6 in the Chapter Development Methodology, it is possible to checkthe new NMF components for correctness. The IDA NMF Translator will break on syntacticand semantic errors in the NMF code before translating it into FORTRAN or C. Likewise, thecompiler will break on errors in the code of, e. g., external functions, etc.

If a simulation run breaks before normal termination, debugging may be performed indifferent ways. Most errors in the system description file (see chapter 8) will be found andreported to screen by IDA Solver. A rich range of optional printouts from IDA Solver isavailable for problem diagnosis. By adding S to the command line, whatever is written on thescreen during execution is sent to a file. The name of this file will be the same as that of thesystem description file but with the extension .SCR. Appendix 3 contains an example of sucha file.

Adding a G on the command line displays the iteration evolution in greater detail on thescreen. Finally, L/n sends Jacobian matrices, etc. from IDA Solver to a file with theextension .TRC for tracing of irregularities, etc. n is the number of the timestep from whichthe display should commence. It is sometimes necessary to restrict the number of displayediterations when using the L option, since, sometimes, extremely large files may be produced.(See IDA Solver Configuration for information on control of maximum number of iterationsand other low level configuration possibilities.) If the error to be found occurs in the firstiteration, L/0 together with only one iteration is the best choice.

Finally, the option M/U is chosen if a modular solving procedure is desired instead of acompact one (default). A compact solving procedure requires less internal memory for smallproblems compared to a modular procedure. On the other hand, a modular procedure uses lessmemory compared to a compact one for large problems. The best way of finding out whichprocedure requires less internal memory (and time) for a certain problem is by testing.

16


7 Simulation Program Size

The amount of work space required for a simulation with a developed program will oftengrow almost quadratically with problem size, measured in number of equations. The amountof work space required for the simulation is assessed early in execution, before the integrationstarts. The amount of work space available is set in the file IDA.INI in the windows directory(usually C:\WINDOWS or C:\WINNT). There is, under the heading [SOLVER] in IDA.INI, aparameter, MEMORY-SIZE, displaying the amount of floating point numbers that is allocatedfor the program. If this number is to small, the text ”DYNAMIC MEMORY OVERFLOW”will be displayed when starting the program. MEMORY-SIZE may be increased up to amachine dependent level. When running IDA from the DOS prompt the program will try toincrease the work space itself when running out of memory. This could slow down the initialface of the simulation as the program will have to restart with a new, larger, work space.

Increasing the amount of work space available for the program will make it possible tosimulate larger systems, e. g., by including a greater number of modules (instantiatedcomponents). One may also use a finer grid for the discretization used in differenceapproximations (if any) of one or more modules. On the other hand, reserving much morework space than needed, may make the execution slower.

17


8 The System Description File (file.IDA)

To run a simulation, a system to simulate has to be described. Furthermore, a problem for thatsystem must be defined by providing suitable boundary conditions. This is done in a filecalled file.IDA, in a format required by IDA Solver. System description files of this type canbe created directly with any text editor. Note that all sections except OPTIONS,CONSTANTS, and TABLES must be present in a system description file. Furthermore, thecontents of any number of files may be included in the system description file by writing

INCLUDE file.ext

at the desired point of vocation.

The aim of this chapter is to explain the different sections and account for the structure of acorrect system description file readable to IDA Solver. It is advisable to study the exampleELOSC.IDA (Appendix 4) along with the following text that will be divided into sections inthe same way as the system description files are. For a complete list of all headings in theirright places, see Appendix 5. Note that all lines in the system description file beginning withan exclamation mark are comments, disregarded by IDA Solver. Finally, 8.11 explains whatformats may be used.

8.1 Model Description

The heading of the first section is ABSTRACT. Here, within quotation marks (”), thedeveloper may initially describe in words and with simple figures, the system being modeled.The first two lines of this text will be copied and appear in the beginning of the output file,file.RES.

8.2 IDA Solver Configuration

The section with the heading OPTIONS is optional and should only be included if the userwants to modify the configuration of IDA Solver. The most frequently used options aredescribed in chapter 10. Furthermore, Appendix 6 contains full descriptions of all availableoptions.

8.3 External Files

External files may be used as containers of input data for time dependent boundary values, orfor storage of output data, for instance for plotting. The specification of external files is donein the section FILES.

18


8.3.1 External Files for Input Time Series

The names of the external files for input data are to be listed according to:

INPUT infilePATH extfile.PRN

where infile is the local alias of the external file within the system description file, andextfile.PRN is the name of the external file on the disk. extfile.PRN may be preceded by a pathif the file is not located in the project directory.

IDA Solver allows for two different formats of the external files for output time series (see8.3.2) to be used in the external files for input time series.

8.3.2 External Files for Output Time Series

External files for output data may be declared as:

OUTPUT outfilePATH *out.PRN

under the heading FILES. outfile is the local alias of the output file within the systemdescription file. In the case above, the external name of the file will be the name of the systemdescription file with the addition of out. For example, with a system description file namedKNUT.IDA, a specification line

PATH *TED.PRN

generates an external file for output data named KNUTTED.PRN. One may also give acompletely new name to the external output file, e. g.

PATH EXTRA387.PRN

In this context, note that the limitations of Windows 3.X apply, concerning the length of a filename. Furthermore, paths must not contain directory names having extensions.

Each output file will contain a table of variable values as chosen in the sectionINTEGRATION. Each line of the table will correspond to one timestep.

If the extension .PRN is chosen explicitly, as in the example above, the result will just be thistable. If the PRN extension is not included in the path of an output file, .a PRN extension willstill be used, and an extra line with column headings will be added at the beginning of the file.For how to specify the output and possible column names, see 8.10.2.

8.4 Local Constants

19


It is possible to define local constants, in the optional section CONSTANTS. This isconvenient if the values of several parameters (see below) are the same and, especially, if thisvalue may be changed one or more times during the course of the work. In this section, localconstants, if any, are defined using the format:

constant_name value

8.5 Tables for Time Dependent Input

Time dependent boundary values may be explicitly given in tables in the optional sectionTABLES. A table consists of two or more columns, the first always containing time.

A table has the format:

TABLE table_numberDATAtime1 value11 value12 …time2 value21 …...END

Each column corresponds to one variable. The columns are numbered 1, 2, …, (the first onereserved for the time coordinate). The timesteps do not have to be equal. Step changes in avariable value are accomplished by letting two subsequent lines have the same timecoordinate, but different variable values. Sharp turns may be indicated by repeating time andvariable values in two identical lines. The solver will negotiate these steps and bends withspecial care. When a variable value in between two timesteps is required by IDA Solver,linear interpolation is utilized.

8.6 Instantiating NMF Components

A system description file describes a number of components, or, rather, instances ofcomponents, connected together to a system forming a model of the part of reality that is to besimulated. Each component instance taking part in such a system is called a module. Allmodules of a certain system are listed in a section called MODULES, in the following way:

MODULE nameTYPE component

parameter1 value1 or constant_name1parameter2 value2 or constant_name2parameter3 value3 or constant_name3…

name is a local name of maximum 15 characters (starting with a letter) given by the user. It isrecommended, that the names of the modules are chosen in such a way that they give an ideaof the structure of the system. This may be done, e. g., by ending the names with a number,

20


directly indicating the location of the module in relation to other modules. It is alsorecommended to include an abbreviation in name for the type of component.

component refers to the type of component by being equal to the name of the component inthe NMF code. Note, that many modules of the same type but with different names may existin one system. Frequently, the word component is used instead of module or componentinstance, but this does usually not lead to any misunderstandings.

Next, the component parameters and their values for the module in question are listed in theorder: dimensioning scalars (if any), scalars, and vectors (vectors with zero length must not beincluded). Within the two first groups, the parameters may be given in arbitrary order. In thethird group, however, some restrictions apply. All vectors dimensioned by the same parametermust appear together. All vectors dimensioned by CMP parameters must come before thosedimensioned by CMP parameters. Matrices have to appear in the second group (their sizeshave no explicit CMP parameter, but the size is calculated). Finally, constant_nameX refers tothe value defined for the constant with that name in the CONSTANT section.

For matrices, the fastest index to vary is the first. Thus, using the format:

A value1 value2 value3 value4 value5 value6 value7 value8 value9

for A(3,3), will generate the following matrix:

value1 value4 value7value2 value5 value8value3 value6 value9

As an alternative, vectors dimensioned by the same parameter may be given in a table with thename of each vector, vector_nameX, written above the column containing its values:

vector_name1 vector_name2 vector_name3 …value11 value21 value31value12 value22 value32…

valueXI is the input value of element I of vector X.

If this columnwise arrangement is used, all vectors having the same dimensioning parametermust be included in the same table.

A complete list of the parameters of a component is found towards the end of the NMF codeof that component. All component parameters with the role SMP (dimensioning scalars), mustbe given values in this section. Parameters with the role S_P (scalars and vectors) may begiven or omitted; in the latter case their default values from the NMF code will be used.

As an example, consider the case above and let a and b be the number of rows and columns ofthe matrix A, i. e., A = A(a,b). To complete the parameter list of the module, a scalar with thename a_b and the value of 9 (3 x 3) has to be included among the dimensioning scalars.

21


8.7 Coupling of Modules

There are two ways of coupling the modules to each other, by connections on the level ofvariables or on the level of links. Both types of connections are specified in a section calledCONNECTIONS, and may be freely mixed. In order to find out what component variables andlinks that may be connected, one must study the LINKS section of the NMF descriptions ofthe components taking part in the system of current interest. For variables referring to physicalflows (e. g., heat flux or mass flow) their positive direction is indicated by POS_IN orPOS_OUT. If two variables, both with POS_IN (or POS_OUT) as positive direction, are to beconnected, a minus sign must precede one of them. This is automatically taken care of whencoupling the modules on the level of links.

8.7.1 Coupling on the Level of Variables

A connection on the level of variables has the format

module_nameA.variable_name1 = module_nameB.variable_name2

or

module_nameA.variable_name1 = - module_nameB.variable_name2

and, for vectors

module_nameA.vector_name1(i) = module_nameB.vector_name2(j)

or

module_nameA.vector_name1(i) = - module_nameB.vector_name2(j)

where module_nameX is the name of the module as chosen by the user in the MODULESsection. variable_nameX and vector_nameX are variable and vector names, respectively, inthe NMF description of the connected component type. i and j are vector indices. Naturally,scalar variables may be connected to vectors by mixing of the two formats above. Note thatvariable_name1 may be identical to variable_name2 but that this is not necessarily the case. Itdepends on the variable names chosen in the NMF descriptions. This also applies tovector_name1 and vector_name2. Finally, if two variables referring to physical flows, bothwith POS_IN (or POS_OUT) as positive direction, are to be connected, a minus sign mustprecede one of them, as displayed above.

8.7.2 Coupling on the Link Level

Each component has one or more links, containing a set of variables, that may be used tocouple adjacent modules. The names of these links are found in the NMF descriptions and theconnections in the system description file are written as

module_nameA.link_name1 = module_nameB.link_name2

22


or, for vector links

module_nameA.veclink_name1(i) = module_nameB.veclink_name2(j)

where module_nameX is the name of the module as chosen by the user in the MODULESsection. link_nameX and veclink_nameX are link and vector link names, respectively, in theNMF description of the connected component type. i and j are vector indices. Scalar links maybe connected to vector links by mixing of the two formats above. However, vectorconnections may not be made in the current version. When two modules are coupled on thelevel of links, the variable sets of the links involved are automatically connected. For thisreason, only links of the same type may be connected. The type of each link is declared in theLINK section of the NMF descriptions.

8.8 Boundary Conditions

A system of modules connected as described above, normally has some variables appearing inmodule links still left unconnected. The system as it stands does not represent a well posedproblem, but is underdetermined. In order to perform simulations, the system needs boundaryconditions to be specified for some of these unconnected variables. In the BOUNDARIESsection one may choose among the following formats to supply boundary conditions:

module_name.variable_name valuemodule_name.variable_name constant_namemodule_name.variable_name TABLE table_number column_numbermodule_name.variable_name FILE file_name column_numbermodule_name.variable_name FILE file_name column_namemodule_name.variable_name FUNCTION function

constant_name refers to the value defined for the constant with that name in the CONSTANTsection. The third alternative is used when the variable values are given in a table in theTABLE section, and the following two alternatives when the values should be imported froman external file. file_name refers to the local alias declared in the FILES section. In the lastalternative, function may be one of SIN or EXP. One of the last four alternatives is used if aboundary condition is to vary during a dynamic simulation. Finally, variable_name above maybe substituted by vector_name(i), where i is a vector index.

The SIN function is defined as

mean + amp * SIN{ 2 * π / per * ( t - t_max ) + π / 2 }

and the input format for the function with its parameters is:

FUNCTION SINmean amp per t_max

23


where mean is the mean value and amp the amplitude of the sinus function. per is the period,for instance 24, for which the function is to be calculated. t_max is the time, for instance 15,when the maximum of the sinus function occurs.

The EXP function is defined as

init + incr * { 1 - EXP ( - t_const * t ) }

and the input format for the function with its parameters is:

FUNCTION EXPinit incr t_const

init and init + incr may be regarded as function start and end values, respectively, if the timeconstant, t_const, is positive. t_const then controls how fast the function value approaches theend value, init + incr. A different function behavior altogether is obtained with a negativet_const.

8.9 Initial Values

In the section START_VALUES, initial values may be given. These are values (valueX) or pre-defined constants (constant_nameX) for the variables to be calculated. The format of thesection is:

DEFAULT value1 or constant_name1module_name1.variable_name1 value2 or constant_name2module_name1.variable_name2 value3 or constant_name3…module_name2.variable_name3 value4 or constant_name4module_name2.variable_name4 value5 or constant_name5…

where the variables are specified by name (variable_nameX) and module (module_nameX). Inthe first line, an overall value, used for all variables not supplied with individual initial valuesin the following lines, must be given. Then, if desired, the user may supply initial values of hischoice to any of the variables that are to be calculated. constant_nameX refers to the valuedefined for the constant with that name in the CONSTANT section. variable_nameX abovemay be substituted for vector_nameX(i), where i is a vector index.

Finally, the end result of a previous simulation (the .END file) may be used as a starting pointfor a continuation of a simulation by simply including it into the system description file in theSTART_VALUES section. How to do this is described in chapter 9.2.

8.10 Integration Parameters

IDA Solver, in principle, simulates the system behavior between two time points, time1 andtime2. If a steady-state-problem is to be solved, time1 is set equal to time2 and a calculation of

24


the initial values of the simulation is performed. In the NMF models, the time unit is alwaysseconds, although flows may be in any suitable units, e. g. kg/h. Simulation time is also, bydefault, measured in seconds, but the time scale may be specified to some other timescale,e. g. hours or milliseconds.

Data on what period to simulate, and how, are given in the section INTEGRATION in thefollowing format (information within square brackets [] is optional):

[TIME_SCALE time_scale]FROM time1TO time2STEP start_stepTOL toleranceTOL_LIM limit[HMIN hmin][HMAX hmax][PERIOD_TOL per_tol][PERIODS per]

Integration TolerancesIDA Solver is a variable timestep solver and timesteps are chosen so that the localdiscretization error is below given tolerances. In the results, variables with absolute valuesgreater than limit will have the relative accuracy tolerance. Variables with absolute values lessthan limit will have the absolute accuracy limit * tolerance.

The optional specifications hmax and hmin can be used to override the accuracy control. Notimestep will be longer than hmax. Timesteps will not be made shorter than hmin to upholdaccuracy, but may be shorter, if this is required to obtain any solution at all.

Periodic vs Dynamic SimulationIn a dynamic simulation the specified integration period time1 -- time2 is run just once. In aperiodic simulation , the integration period is run repeatedly until successive integrationsproduce identical results, within a given tolerance. For a periodic simulation, per_tol is thetolerance for and per is the maximum number of periods. per_tol is used for a comparisonbetween end values of variables after successive integrations. For a dynamic simulation thesespecifications should be omitted.

The rest of the INTEGRATION section concerns output control. It contains two subsectionswith the headings LIST and LOG, respectively.

8.10.1 Specifying Output to file.RES and to the Screen

In the LIST subsection of the INTEGRATION section, the user can specify the output to thefile file.RES and to the screen. Initially, the text OUT_ALL should be included if all variablesare to be written at every timestep to the file file.RES:

25


LISTOUT_ALL

END

If only a selection of the variables is desired, and only at certain timesteps, OUT_ALL may beomitted. Instead, the variable values may be written to the file file.RES beginning at a certaintime, startX, and ending at stopX. The choice of stepX controls the time interval between theprintouts. startX, stopX and stepX should be given enclosed by OUT_TIMES andEND_TIMES, as in the following:

OUT_TIMESstart1 stop1 step1start2 stop2 step2…

END_TIMES

The variables to be written to file.RES, at these timesteps, follow in a list:

module_name.variable_name column_headingmodule_name.variable_name column_heading…

where the user may choose column_heading to denote the variable variable_name in themodule module_name.

The values, at all timesteps, of the first three of these variables will also be written to thescreen during execution, as well as to the file.RES file. A recommended output combination isOUT_ALL and a list of three variables to be printed to the screen. The screen variables canthen give rapid information of the outcome of the simulation and, for more detail, the file.RESfile may be scrutinized.

8.10.2 Specifying Other Output

The output to the external files for output time series (chosen in the FILES section) with theextensions .PRN is specified in the last subsection of the INTEGRATION section, under theheading LOG. The values of the desired variables will be written to the files outfileX,beginning at a certain time, startX, and ending at stopX, generating a table as described in8.3.2. The choice of stepX controls the time interval between the printouts. startX, stopX andstepX should be given enclosed by OUT_TIMES and END_TIMES. The subsection has thefollowing format:

LOGOUT_TIMES

start1 stop1 step1start2 stop2 step2…

END_TIMESFILE outfile1

module_name.variable_name column_heading

26


module_name.variable_name column_heading…

FILE outfile2…

END

The OUT_TIMES … END_TIMES subsection controls the output to all the external files thatfollow. If the subsection is omitted, the values of the desired variables will be written at everytimestep. This format is normally preferred, since it gives complete information on the timeseries produced and allows more accurate plotting.

8.11 Number Formats

In the system description file, 17 is an example of an integer constant. Floating point constantscontain a decimal point (47.11) or an exponent (1E-2) or both; their type will be DOUBLE inthe generated code. Decimal comma is not allowed.

Identifiers may contain up to 15 characters and must start by a letter (a-z). There is nodistinction between small and capital letters. Apostrophes, ”…”, should only be used aroundthe text in the ABSTRACT section (and never for any other type of string). The only type ofwhite space allowed is space characters. A hidden control character, for instance, will generatean error message and the simulation will not be started.

27


9 The Output

This chapter contains descriptions of the output files, file.RES and file.END, as well as outputfiles with the extension .PRN.

9.1 Output File file.RES

After some initial information concerning for instance the version of IDA Solver, the date andthe name of the system description file, the file.RES file contains an echo of the systemdescription file. In this, the CONSTANTS section is omitted and the constants have beenreplaced by their actual values. The CONNECTIONS section gives all connections at thevariable level.

In a special section, called PARAMETERS, all parameters are presented, whether they havebeen given, fetched from model defaults, or, calculated by the program as stated in thePARAMETER_PROCESSING section of the NMF code. The echo of the system descriptionfile ends with the INTEGRATION section, showing what variables will be written to thescreen and what to the chosen output files.

In order to fully understand the different parts of the output from IDA Solver, one must beaware of the fact that NMF allows linearization of non-linear equations to be used as a meansto aid the initial value calculations in the solver. This is done in the NMF code by using theLINEARIZE(#) construct, where # denotes the level of linearization. The linearized forms ofthe equations will be gradually replaced by the original equations during the course of solving.For more information on this subject, see the NMF handbook.

The output from the actual solving starts with the lines (provided that time1 is equal to zero):

Linearized ? Undamped Newton-Raphson ! TIME 0.0000

where TIME 0.0000 and Linearized ? tell the user that the solution after zero timeand with all levels of linearization included, will be displayed first. The middle line is thesolution method as chosen in the IDA.CFG file (see next chapter). Then the solutions (atTIME equal to zero) for the other levels of linearization follow. In each solution, all variablesare presented for every module.

The first solution without linearizations has the heading:

Linearization removed Undamped Newton-Raphson ! TIME 0.0000

The solutions for the rest of the timesteps, with the corresponding value of TIME in theirheadings, are then displayed.

28


Some general information about the simulation run is presented in a section towards the endof file.RES, for example:

! Integration time 88.9 sec * Number of steps * Initial 52 * Start 48 * Ivent 3 * Event 44 in 69 tries * Contract 2 * Expand 101 * Total 1033

* Number of * Modules 28 * Equations 83 * Boundaries 24 * IN/OUT Variables 230 * Total no of vars 559

9.2 file.END

The output file file.END where file is the same name as of the system description file,contains a simple list of all variables and their values after the last timestep. It may be used asa starting point for a continuation of the simulation, in time, by simply including it into thesystem description file in the START_VALUES section. After changing its name, to forinstance file.BEG, this can be accomplished with the line

INCLUDE file.BEG

in the START_VALUES section.

9.3 Files with the extension .PRN.

Output, as specified in the INTEGRATION section (8.10.2) of the system description file, willbe directed to output files with the extension .PRN, as chosen in the FILES section (8.3.2).These files are intended for plotting purposes and will vary in layout depending on how theirextensions were chosen.

The main content of the output files will be a table of variable values as chosen in the sectionINTEGRATION. Each line of the table will correspond to one timestep. The first column isreserved for the time coordinate and the second column for the integration order in each timestep.

If no extension is specified, a .PRN extension will still be used for the file produced, and thefile will start with a line of column headings. If the extension .PRN is chosen explicitly, theresult will be the same table but without column names.

29


10 The IDA Solver Configuration

There are several configuration options for modifying the operation of IDA Solver. Alloptions have default values in the source code of the solver. They may, however, be altered inthree different ways: via the configuration file IDA.CFG, via an OPTIONS section in thesystem description file (see 8.2), and via the command line when starting the solver in a DOSwindow (see 4.6).

Some options may be specified simultaneously in more than one of these ways. Then, theorder of (falling) priority is: command line, system description file, configuration file, default.Options specified in the configuration file or in the system description file use the sameformat, typically

KEYWORD value

where value may be of type integer or real depending on the option. The next three sectionscontain lists of the most frequently altered options and references to more detaileddescriptions in Appendix 6. The extended lists in the beginning of Appendix 6 contain allavailable options. The order between the options is irrelevant except when explicitly stated.Options may not be given repeatedly in the same source.

10.1 Command Line Options

The Option text in the list below is case insensitive and may be given on the command line.Corresponding keywords are the keywords to be used in the system description file or in theconfiguration file.

Optioncode

Option text Function Correspondingkeyword

Section inApp. 6

S S Screen log to file.SCR SCREEN_LOG C.1.1

S/file.ext Screen log to file.ext

S/0 Suppress screen log

G or GG Log initial value calculationin detail

INIT_LOG C.1.2

G Log each iteration

GG Describe timestep controlactions in more detail

L L/n Log details of iterationsduring timestep n

TRACE_LOG C.1.4

M M/U Select modular structure(instead of the default(global)) and uppertriangular sorting

JOIN_MODSORT_VAR

C.2.1.1

30


10.2 Input - Output Options

The keywords in the list below are case insensitive and may be given in the section OPTIONSof the system description file or in the configuration file. The extra output data producedconcerns logging of information about the simulated problem, especially for debuggingpurposes.

Keyword Commandlineoptionavailable

Range ofvalues

Defaultvalue

Function Section inApp. 6

SCREEN_LOG yes 0-2 1 Log integration progress, onscreen or disk

C.1.1

INIT_LOG yes 0-2 0 Log initial value calculation C.1.2

EVENT_LOG yes 0,1 0 Log event localization C.1.3

TRACE_LOG yes 0,1 0 Produce trace output, asdescribed by TRACE_BEGand TRACE_END

C.1.4

TRACE_BEG yes 0- 0 Start trace at step no .. C.1.4

TRACE_END yes 0- 0 End trace after step no .. C.1.4

10.3 Control Options

The keywords in the list below are case insensitive and may be given in the section OPTIONSof the system description file or in the configuration file. The extra output data producedconcerns the numerical methods used by IDA Solver.


Range ofvalues

Defaultvalue

Function Section inApp. 6

JOIN_MOD yes 0,1 1 Modular/Globalstructure

C.2.1

SORT_VAR yes 0-3 0 Modular sortingmethod

C.2.1.1

N_MAX_ITER 1- 10 No of Newtoniterations per timestep

C.4.2

INIT_METH 0-7 or-1 +recipe

-10 3 4

Initial value methods C.5.2

N_MAX_JAC_IV 1- 20 Tries with newJacobian at initial valuecalculation

C.5.3.1

N_MAX_H_IV 1- 5 Tries with shorter stepat initial value calcul.

C.5.3.1

31


Appendix 1 – Generated Code Options

Omitted in this version.

32


Appendix 2 – Contents of MAE library

MAE - Multizone Air ExchangeA sample model library for multizone airflow modelling. See alsowww.brisdata.se/nmf/simone.

BDZONE a room componentBDLEAK a leak (with uni-directional flow) between two roomsBDLVO a large vertical opening with bi-directional flow between two rooms, e.g., a

doorVXDUCT a straight ductVXBEND an elbow bend in a ductVXTEEC a T-piece with two inflows and one outflowVXTEED a T-piece with one inflow and two outflowsVXFAN a fanVXDAMP a flow resistanceVXCOIL a heaterVXFILT a filterVXEXP a duct area expansionVXCNTR a duct area contractionVXSUPT an air supply terminal from the ventilation system to a roomVXEXHT an air exhaust terminal from a room to the ventilation systemBDBRNC an undivided ductwork section with bi-directional flowBDNODE a ductwork node without pressure drops with bi-directional flowBDTERM an air in-/outlet terminal between bi-directional duct fittings and roomsUTLEAK a leak between a room and the outdoor airUTSUPT an air supply terminal from the outdoor air to the ventilation systemUTEXHT an air exhaust terminal from the ventilation system to the outdoor airUTGRIL a bi-directional inlet/outlet grille towards the environment

http://www.brisdata.se/nmf/simone

33


Appendix 3 – Sample Screen Log

An example of an .SCR file

! IDA Solver IDA Solver Version 5.51 (up to 960609)! Copyright (C) Bris Data AB 1994-1996 Size 4000000

! Input file: WE3.IDA Run at 96-12-05 15:16:00

* Testcase for IDATUN with all components represented,* link level connections

! Preparation time 2.0 sec

Dynamic memory use cells MB Requested 744602 2.840 Used effectively 691748 2.639Total available 4000000 15.259

Initial values Linearized ? Undamped Newton-Raphsontries= 3 max|dy|= 0.235E-05 ||res||= 0.217E-24 Linearized(2) Undamped Newton-Raphsontries= 5 max|dy|= 0.194E-04 ||res||= 0.300E-19 Linearization removed Undamped Newton-Raphsontries= 4 max|dy|= 0.140E-06 ||res||= 0.692E-21 NSTEP TIME H IT K J/S t07fire v07fire tw14 0 0.000000 1.000E-05 1 1 65.53 2.242 21.38

! Integration time 11.0 sec * Number of steps * Initial 1 * Start 0 * Ivent 0 * Event 0 in 0 tries * Contract 0 * Expand 0 * Total 0

* Number of * Modules 16 * Equations 193 * Boundaries 62 * IN/OUT Variables 396 * Total no of vars 1316

34


Appendix 4 – Sample System Description File (*.ida)

The input file ELOSC.IDA

ABSTRACT"Simple test of dynamics; RC-oscillator Constant input

/------ Res1 -------\ / \ -----*--- Res2 --- Diode1 ---*----- Node1 |\ /| Node2 | \------ Cap1 -------/ | | | |-------- Coil0 --------|"

FILES! Asterisk (*) in output paths represents the current inputfile,! .i.e. in this case, ELOSC.ida.! The output files will get the names! ELOSC_i1.prn & ELOSC_i2.prn respectively. OUTPUT output1 PATH *_i1.prn OUTPUT output2 PATH *_i2.prnEND_FILES

CONSTANTS! Names of local constants.! These may be used as parameter values below. res_1 10.END_CONSTANTS

TABLES TABLE 1 DATA! First column is reserved for the time coordinate! time col2 col3 (col3 is not used below) 0 0 2.5 3 0 3.1! A discontinuous change is noted at time 3 3 1 3.1 10 1 5 ENDEND_TABLES

! List of components included in simulated systemMODULES

35


MODULE Cap TYPE Capacitor c 0.1 MODULE coil0 TYPE Coil l 1. MODULE diode1 TYPE Diode r1 0.01 r2 10000 MODULE Node1 TYPE El_node n_link 4 MODULE Node2 TYPE El_node n_link 4 MODULE Res1 TYPE Resistor r res_1! replaced by constant value defined above in CONSTANTS section MODULE Res2 TYPE Resistor r res_1END_MODULES

CONNECTIONS diode1.U1 = Res2.U2 diode1.I = Res2.I Cap.U1 = Node1.U Cap.I = -Node1.I(1) Cap.U2 = Node2.U Cap.I = Node2.I(1) coil0.U1 = Node1.U coil0.I = -Node1.I(2) coil0.U2 = Node2.U coil0.I = Node2.I(2) Res1.U1 = Node1.U Res1.I = -Node1.I(3) Res1.U2 = Node2.U Res1.I = Node2.I(3) Res2.U1 = Node1.U Res2.I = -Node1.I(4) diode1.U2 = Node2.U diode1.I = Node2.I(4)END_CONNECTIONS

BOUNDARIES Node1.U 0. Node1.I0 1.END_BOUNDARIES

START_VALUESDEFAULT 0.00001 Cap.U 0.

36


coil0.I 0.END_START_VALUES

INTEGRATION FROM 0. TO 10. STEP 0.0001 TOL 0.001 TOL_LIM 1.

LIST OUT_ALL OUT_TIMES 0 1 1 END_TIMES

Cap.I Cap_I diode1.I diode1_I diode1.Dir diode1_Dir coil0.I coil0_I Res1.I Res1_I END

LOG FILE OUTPUT1 Cap.I Cap_I coil0.I coil0_I FILE OUTPUT2 diode1.I diode1_I Res1.I Res1_I ENDEND_INTEGRATION

37


Appendix 5 – Headings in the System Description File

A complete list of all section headings of file.IDA in their right places.

ABSTRACT

OPTIONS N.B. Optional heading!END_OPTIONS

FILESEND_FILES

CONSTANTS N.B. Optional heading!END_CONSTANTS

TABLES N.B. Optional heading!END_TABLES

MODULESEND_MODULES

CONNECTIONSEND_CONNECTIONS

BOUNDARIESEND_BOUNDARIES

START_VALUESEND_START_VALUES

INTEGRATIONEND_INTEGRATION N.B. More INTEGRATION sections may follow, for

consecutive time intervals

38


Appendix 6 - Configuration Options for IDA Solver

A. General

The operation of IDA Solver can be modified in several aspects via configuration options. Theoptions can be specified in three different manners: via a configuration file IDA.CFG, via anOPTIONS section in the system description file, and via the command line if the solver isstarted in DOS mode. All options have default values specified in the source code of thesolver.

The same option can be specified simultaneously in several of these ways, in which case theorder of (rising) priority is: default, configuration file, system description file, command line.Options specified in the configuration file or in the system description file use the sameformat, typically a line

KEYWORD value

where value may be integer or real depending on option. The next few sections contain lists ofavailable options and references to more detailed descriptions in subsequent sections.The order between the options is irrelevant except when explicitly stated, but options may notbe given repeatedly in the same source.

B. Summary of Available Options

The options fall into two groups, input-output options and control options

B.1 Input-output Options

Regular result output, for printing or plotting, is produced by the integration and is sent todisk. The frequency of output and what variables to follow is controlled by information in thesystem description file. The names of output files have default names, one of which (file.RES)may be changed by a command line option (see section B.3 below).

In addition to the regular result output, IDA Solver can produce several logs, which canprovide valuable information about the problem, especially for debugging purposes. Theselogs are controlled by options as described below. Details can be found in the sectionspecified and, when relevant, in section B.3 concerning command line options.


Range ofvalues

Defaultvalue

Function Section

SCREEN_LOG yes 0-2 1 Log integration progress, onscreen or disk

C.1.1

39


INIT_LOG yes 0-2 0 Log initial value calculation C.1.2

EVENT_LOG yes 0,1 0 Log event localization C.1.3

TRACE_LOG yes 0-2 0 Log details of iterationswithin timesteps

C.1.4

TRACE_BEG yes 0- 0 Start trace at step no .. C.1.4

TRACE_END yes 0- 0 End trace after step no .. C.1.4

SAVE_START yes 0,1 0 Write effective start valuesto disk

C.1.5

B.2 Control Options

In the table below, SMALL is equal to the square root of the floating precision (machinedependent). Open intervals are denoted (lo-hi), closed intervals [lo-hi], etc.

Keyword Commandline optionavailable

Range ofvalues

Defaultvalue

Function Section

JOIN_MOD yes 0,1 1 Modular/Globalstructure

C.2.1

SORT_VAR yes 0-3 0 Modular sortingmethod

C.2.1.1

MULTI_RATE 0,1 0 Separate integration ofmodules

C.2.1.2

KMAX 1-5 2 Max integration order C.3.1

THETA_MOLCOL [0.0-0.5]

0.0 Location of collocationpoint

C.3.2

C_MOLCOL [0.0-?] 0.0 Molcol correctionfactor, not normallyused

C.3.3

NEWTON_TOL (SMALL-1.0)

0.1 Newton accuracy C.4.1

N_MAX_ITER 1- 10 No of Newtoniterations

C.4.2

N_MAX_SHRINK 1- 10 No of step reductions C.4.2

H_FACT_FAIL (SMALL-1.0)

0.5 Step reduction atfailure

C.4.3

H_FACT_OK (SMALL-1.0)

0.8 Step reduction atsuccess

C.4.3

JAC_INTERV 1- 1 Steps between newJacobians

C.4.4

SCHUR_INTERV 1- 5 Steps between newSchur complements

C.4.4

EQ_WEIGHT_EXP [0.0-1.0]

0.0 Exponent for equationweighting

C.4.5

LINEARIZATION yes 0,1 1 Allow model C.5.1

40


linearization duringinitial value calculation

INIT_METH 0-7 or-1 +recipe

-10 3 4

Initial value methods C.5.2

UNDER_NEWT (0.0-1.0]

0.75 Underrelaxation fordamped Newton

C.5.2.3

H_INIT (0.0- 1E-5 Tentative step forinitial value calculation

C.5.3

N_MAX_JAC_IV 1- 20 Tries with newJacobian at initial valuecalculation

C.5.3.1

N_MAX_H_IV 1- 5 Tries with shorter stepat initial valuecalculation

C.5.3.1

N_MAX_INTERP_EV

1- 8 No of interpolated orinterval halved eventtries

C.6

H_FACT_INTERP_EV

(0.0-1.0)

0.05 Special factor for eventsearch

C.6

EQ_SOLVER 0,1 0 0 = dense matrixsolver.1 = SuperLU, sparsematrix solver

B.3 Command Line Options

The information given on the command line is case insensitive. file.ext represents an arbitraryfile name specified by the user and SYDE.IDA is the system description file.

Optioncode

Option text Function Correspondingkeyword

Section

R R/ file.ext

S S Screen log to SYDE.SCR SCREEN_LOG C.1.1

S/ file.ext Screen log to file.ext

S/0 Suppress screen log

G or GG Log initial value calculationin detail

INIT_LOG C.1.2

G Log each iteration

GG Log each decision taken

E E Log event localization indetail

EVENT_LOG C.1.3

L or B L/n Log details of iterationsduring timestep n

TRACE_LOG C.1.4

B/n Ditto, but Jacobiansreplaced by binary

41


incidence matrices

F F/file.ext Write consolidated startvalues to file.ext

SAVE_START C.1.5

M M/A Select global structure JOIN_MOD C.2.1

M M/F Select modular structureand Full Schur sorting

JOIN_MOD & SORT_VAR C.2.1.1

M M/U Select modular structureand upper triangular sorting

JOIN_MOD & SORT_VAR C.2.1.1

N N Suppress linearizationduring initial valuecalculation

LINEARIZATION

C. Detailed Descriptions of Options

C.1 Input and Output

C.1.1 General Log of Integration Progress

This log gives general information about size of problem, timesteps taken, methods chosen,etc. By default, it is sent to the screen; options exist to redirect it to disk or suppress it. Whenspecial logs described in sections C.1.2-4 are requested, they will be merged into this generallog and directed as prescribed by this option. (The trace log of section C.1.4 will add info intothe screen log, but will also generate a separate disk file with the name SYDE.TRC, if thesystem description file is SYDE.IDA.)

Configuration file Command line MeaningSCREEN_LOG 0 S/0 suppressSCREEN_LOG 1 default send to screenSCREEN_LOG 2 S send to SYDE.SCR- - S/file.ext send to file.ext

C.1.2 Log of Initial Value Calculation

In the default case, the initial value calculation will be recorded by number of iterations usedat each linearization level. Changes and residuals can also be logged for each iteration. Theoutput is merged into the screen log.

Configuration file Command line MeaningINIT_LOG 0 default minimum informationINIT_LOG 1 G log each iterationINIT_LOG 2 GG log each iteration and decisions taken

concerning timestep modifications

C.1.3 Log of Event Localization

Discontinuous changes in module equations require special handling. NMF supports modelingof such changes by an EVENT feature. (For details see the NMF Reference Manual.)

42


When an event is met during integration, IDA Solver will localize the event, step up to theevent, and pass it with an extra initial value calculation. Logging of the event handling ismerged into the screen log.

Configuration file Command line MeaningEVENT_LOG 0 default events are signaled when passedEVENT_LOG 1 E each step in the localization of an

event is logged

C.1.4 Detailed Log at Iteration Level

During model development, it is often desirable to study the [lack of] convergence of thesolution process. Extra output can be put in a trace file with the name SYDE.TRC, if thesystem description file is SYDE.IDA. The information produced is quite comprehensive andincludes features such as system organization, internal variable ordering, Jacobian matrices atcomponent and system level, detailed changes of every variable in each iteration, progress ofequation residual changes, etc.

Configuration file Command line MeaningTRACE_LOG 0 default no information producedTRACE_LOG 1 L/n Send trace output to SYDE.TRC

during timestep nTRACE_LOG 2 B/n Send trace output to SYDE.TRC

during timestep n. Use binaryincidence matrices for Jacobians

TRACE_BEG n1 - Start trace at timestep n1TRACE_END n2 - Stop trace after step n2

If it is desired to follow one single timestep, the command option L/n is suitable. The mostcommon source of problems is the initial value calculation at the outset of the simulation.This calculation is regarded as timestep number 0. Finally, if several steps are desired, theoptions TRACE_BEG and TRACE_END have to be used.

C.1.5 Consolidated Start Values to Disk

For some problems, the initial value calculation may be quite lengthy. In these cases, it may bedesirable to save the result of this calculation and use it as explicitly specified start values atlater runs. The values are written to a file SYDE.BEG, if the system description file isSYDE.IDA. This file may be renamed and then used via a line

INCLUDE SYDE.BEG

in the START_VALUES section of the system description file (see also C.5.1).

Configuration file Command line MeaningSAVE_START 0 default no file writtenSAVE_START 1 F write start values to SYDE.BEG

43


C.2 Overall Strategy

C.2.1 Modular or Global Matrix Structure

IDA Solver has facilities to utilize sparsity by different modular methods, where thecomponent structure of the system is preserved during integration. The modular methods arecompetitive on large problems, especially when there are few connections compared tointernal component equations.

The default choice is the 'compact' method, where all components are put together into oneglobal system matrix, by identifying of variables that are joined by connections. This methodis generally more robust than the modular methods, puts less restrictions on the formulation ofthe component models, leads to easier debugging, but is impractical on large problems.The choice of integration method relies on two complementary options, JOIN_MOD andSORT_VAR (see next section).

Configuration file Command line MeaningJOIN_MOD 1 default, or

M/Acompact method

JOIN_MOD 0 modular method, specified further bySORT_VAR, see next section

C.2.1.1 Sorting Method

Configuration file Command line MeaningJOIN_MOD 0 modular method, specified further by:SORT_VAR 1 M/B Put Schur matrix on band block

form (currently not supported)SORT_VAR 2 M/F Full Schur matrix is treatedSORT_VAR 3 M/U Upper-triangular block band

organization of Schur matrix

C.2.1.2 Separate Integration Rates

Sometimes, different parts of a system require timesteps of different order of magnitude. InIDA Solver, it is possible to handle this by letting all different components integrate atindividual rates. The timestep control is governed by a global accuracy requirement, which isapplied to each component separately. The separate integrations are matched against eachother at longer intervals, handled as global timesteps.

Configuration file Command line MeaningMULTI_RATE 0 - joint control of timestepping, defaultMULTI_RATE 1 - local control of timestepping

C.3 Integration Method

C.3.1 Integration Order

44


The integration in IDA Solver uses a MOLCOL (Modified One Leg Collocation) method. Theintegration order is variable between one and KMAX (KMAX <= 5).

Configuration file Default value MeaningKMAX n 2 maximum integration order

C.3.2 Collocation Point

The MOLCOL method evaluates equations at a collocation point, which may be placed insidethe current timestep. The fraction of displacement from the end of the timestep can bespecified; value has to be in [0,0.5]. If event handling is used in a problem, THETA_MOLCOLshould be kept at 0.

Configuration file Default value MeaningTHETA_MOLCOL x 0.0 locate collocation point a fraction x

before the end of the current timestep

C.3.3 Special MOLCOL Reduction

Configuration file Default value MeaningC_MOLCOL x 0.0 A tuning parameter in the MOLCOL

method which corrects changes in thecurrent step. The parameter is normallynot used.

C.4 Step Size Control

C.4.1 Accuracy

The accuracy of the integration is controlled in each timestep by comparing the calculatedsolution with the predicted solution. The deviations are checked at the variable level asprescribed by two values TOL and TOL_LIM in the system description file. Deviations arecalculated relative to variable values, if these are larger than TOL_LIM, otherwise relative toTOL_LIM. If the accuracy is insufficient, i.e.,

|dy|/|y| > TOL |y| > TOL_LIMor

|dy|/TOL_LIM > TOL|y| < TOL_LIM

the step is retraced and a shorter step is tried.

The solution is calculated by a Newton-Raphson iteration, which is continued until the largestchange satisfies the criterion

|dy|/|y| < TOL_LIM * NEWTON_TOL

Configuration file Default value Meaning

45


NEWTON_TOL x 0.1 tolerance for changes between Newton-Raphson iterations

C.4.2 Number of tries

The Newton-Raphson iterations in normal timesteps are discontinued if convergence has notbeen reached in N_MAX_ITER iterations. The timestep is then shortened and a new try ismade. This procedure may be repeated a maximum of N_MAX_SHRINK times. If convergencehas not been achieved after that, the integration is discontinued.

Configuration file Default value MeaningN_MAX_ITER n 10 max number of Newton-Raphson

iterations in a timestepN_MAX_SHRINK n 10 max number of tries with shorter step

C.4.3 Step adjustment

The stepsize is adjusted down after each failure, whether due to bad convergence orinsufficient accuracy. In the first case, the reduction is made by a factor H_FACT_FAIL, inthe second case, it depends on the accuracy observed.

Configuration file Default value MeaningH_FACT_FAIL x 0.5 reduction of timestep when

convergence lacking

After each successful timestep, a new stepsize is estimated, based on accuracy observed. Thisestimate is adjusted down by a factor H_FACT_OK, in order to avoid failure and to optimizeprogress.

Configuration file Default value MeaningH_FACT_OK x 0.8 reduction of estimated new timestep,

after successful step

C.4.4 Frequency of Updates

During the integration, it is possible to use the same Jacobians for several subsequenttimesteps. The possible saving in execution time will be offset against slower convergence,and the optimal choice is thus strongly problem dependent. If a timestep does not converge,the solver will freshen the Jacobian before reducing the timestep. The interval betweenJacobian calculations is specified by JAC_INTERV.

When using modular methods, the calculation of the Schur complement can be controlled in asimilar manner by SCHUR_INTERV.

Configuration file Default value MeaningJAC_INTERV n 1 number of timesteps between Jacobian

calculationsSCHUR_INTERV n 5 number of timesteps between calculation

46


of Schur matrix

C.4.5 Equation Weighting

Difficult initial value calculations may profit from a weighting of the equations used incalculating the residual norm. No systematic knowledge has yet been collected on this topic.When used, the weighting is done by:

RES_NORM = SUM(W(i)*Resid(i))**2

where W(i) is 1/max_norm(Jac(i,.))**EQ_WEIGHT_EXP.

Configuration file Default value MeaningEQ_WEIGHT_EXP x 0.0 exponent used in weighting of

equations

C.5 Initial Value Calculation

C.5.1 Model Linearization

NMF allows linearization of non-linear equations to be used as a means to aid the initial valuecalculation in the solver. Possible linearizations will only have effect during the very firstinitial value calculation at the outset of the integration.

If values are known that satisfy the initial equations, it may be desirable to suppresslinearization altogether. This can be done by setting LINEARIZATION to 0 (see also C.1.5).

Configuration file Default value MeaningLINEARIZATION 1 default use linearizationLINEARIZATION 0 suppress linearization

C.5.2 Solution Methods

C.5.2.1 Range of Available Methods

Alternative calculation methods can be used for the initial value calculations. Several methodscan be tried in sequence. Each method is identified by an integer method code.

Methodcode

Method description

0 Newton-Raphson iteration1 Newton homotopy with circular constant arc length2 Newton homotopy with tangent constant arc length3 Line seek along Newton direction4 Damped Newton iteration5 Steepest descent6 Hybrid Powell method (mix Newton and gradient)

47


C.5.2.2 Recipe of Methods

One single method can be specified after the keyword INIT_METH. If more than one methodis desired, put -1 and give a recipe as a list of method codes on the next line. For example,

INIT_METH -10 3 4

will try Newton-Raphson, line seek, and damped Newton in turn, if needed.

A special recipe can be requested for the first initial value calculation, when linearizationstypically are in effect. This recipe is given before the standard one, and the method codes aremarked special by adding 10 and changing sign. For example,

INIT_METH -1-10 -13 -14 3

will try Newton-Raphson, line seek, and damped Newton during first initial value calculation,but only line seek at later ones.

Configuration file Default value MeaningINIT_METH n single methodINIT_METH -1

n1 n2 …-10 3 4

sequence of methods

C.5.2.3 Parameters for Methods

Underrelaxation factor for Damped Newton can be specified.

Configuration file Default value MeaningUNDER_NEWT x 0.75 underrelaxation factor for damped

Newton

C.5.3 Initial Value Step

Initial value calculations are not performed as stationary but handled as very short timesteps.The step should be chosen so short that status variables only undergo negligible changes. Atentative step length can be specified as H_INIT. The solver will verify that the abovementioned changes on the average are smaller than 0.1*TOL, and repeat the initial valuecalculation with shorter step, if required.

Configuration file Default value MeaningH_INIT x 0.00001 tentative timestep for initial value

calculation

C.5.3.1 Number of tries

48


When an initial value calculation fails to converge with maximum number of tries with everysuggested method, the solver will first make a number new tries with new Jacobianscalculated in the point reached. If this doesn't help, the whole procedure is repeated in a newcycle with shorter timesteps.

Configuration file Default value MeaningN_MAX_JAC_IV n 20 number of times to calculate new

Jacobians with the same timestepN_MAX_H_IV n 5 number of times to try shorter timestep

C.6 Event Handling

During localization of an event, the solver will first calculate estimates of the timestep byinterpolating between values of the event function at the time coordinates tried. If the eventhas not been localized after N_MAX_INTERP_EV such tries, N_MAX_INTERP_EV moretries will be made using interval halving.

Configuration file Default value MeaningN_MAX_INTERP_EV n 8 max number of tries of event

localization, using either interpolationor interval halving

During event localization, a time gap straddling the event is successively shortened. Thesolver tries to find points on alternating sides of the event, and the best estimates aresafeguarded by reducing movements by a factor H_FACT_INTERP_EV.

Configuration file Default value MeaningH_ FACT_INTERP_EV x 0.05 reduction factor for event

localization

IDA Solver User’s Guide - equaonline.com · 1999-11-01 · 8 IDA Solver User's Guide, version...

Documents

Transcript of IDA Solver User’s Guide - equaonline.com · 1999-11-01 · 8 IDA Solver User's Guide, version...