KREAN REFERENCE MANUAL - NTNU Reference Manual.pdf · The Norwegian Institute of Technology...

KREAN

REFERENCE MANUAL

JUNE 19, 1995

KREAN is a simulation program specially developed for simulations of power electronic circuits. The program is the result of a cooperation between the University of Trondheim and the EFI/SINTEF group in

Trondheim.

Responsibility for the development of Krean has been withRobert Nilssen and Olve Mo from the University of Trondheim.Ole Morten Stangvik has been responsible for the PC/Windows

interface programming.

This manual has been written by Olve Mo

Additional information are available from

University of TrondheimThe Norwegian Institute of Technology

Department of Electrical Power EngineeringGroup of power electronics and electrical machines

N-7034 TrondheimNorway

Doc.ref.no. KEM94.010

KREAN QUICK REFERENCE PAGE 1

RESISTOR

CAPACITOR

INDUCTOR

IDEAL SHORT

TRANSFORMER

DIODE

N+ N-

RES Name N+ N- R Plot

N+ N-

CAP Name N+ N- C Plot U0 Rs

N+ N-

IND Name N+ N- L Plot I0 Rp

N+ N-

CON N+ N-

NP+np:1

NP- NS-

NS+

TRF Name NP+ NP- NS+ NS- np Plot Rp Rs

N+ N-

DIO D1 N+ N- Plot Init Ron Roff Irr


GENERAL PIECEWISE LINEAR CURRENT SOURCE

SINUSOIDAL CURRENT SOURCE

GENERAL PIECEWISE LINEAR VOLTAGE SOURCE

SINUSOIDAL VOLTAGE SOURCE

SUB-CIRCUITS

N- N+

CNT Name N- N+ Plot 1 Period Rp Phi0 T2 T3 ... Tn-1 1.0I0 I2 I3 ... In-1 In

N- N+

CNT Name N- N+ Plot 2 Rp Irms Freq Phase

N- N+

VTG Name N- N+ Plot 1 Period Rs Phi0 T2 T3 ... Tn-1 1.0U0 U2 U3 ... Un-1 Un

N- N+

VTG Name N- N+ Plot 2 Rs Urms Freq Phase

Sub-circuit

SUB Type ( V1 V2 ...... ... Vn )


VOLTAGE CONTROLLED VOLTAGE SOURCE

VOLTAGE CONTROLLED CURRENT SOURCE

CURRENT CONTROLLED VOLTAGE SOURCE

CURRENT CONTROLLED CURRENT SOURCE

NC+

CTS Name NC+ NC- NS+ NS- 1 Gain Plot Rs

NC-

NS+

NS-

CTS Name NC+ NC- NS+ NS- 2 Gain Plot Rp

NS+

NS-

NC+NC-


NS+

NS-

NC+NC-


NS+

NS-

NC+NC-


TIME CONTROLLED BI-DIRECTIONAL SWITCH

VOLTAGE CONTROLLED BI-DIRECTIONAL SWITCH

TIME CONTROLLED UNI-DIRECTIONAL SWITCH AND TIME CONTROLLED THYRISTOR

VOLTAGE CONTROLLED UNI-DIRECTIONAL SWITCH / THYRISTOR

N+ N-

SW1 Name N+ N- Plot Period Ron Roff Phi0 T2 T3 ... 1.0S0 S2 S3 ... Sn

N+ N-

NC+ NC-

SW2 Name N+ N- NC+ NC- Plot Init Uc,off Uc,on Ron Roff

N+ N- N+ N-

TH1 Name N+ N- Plot Init Period Ron Roff Irr Phi0 T2 T3 ... 1.0S0 S2 S3 ... Sn

N+ N-

NC+ NC-

N+ N-

NC+ NC-

TH2 Name N+ N- NC+ NC- Plot Init Uc,off Uc,on Ron Roff Irr


CONTROL CODES FOR USE IN DATAFILES

Start time for the simulation

TMI Tstart

End time for the simulation

TMA Tend

Error tolerance

ERR Tolerance

Maximum time step length

HMA Hmax

Definition of symbols

SYM @Name Def Comment

Controlling the storage of results

SMI TstartSMA Tstop

Plotting point factor

PPF Nplot

Specify directory for sub-circuits

DIR DirName

Variable declaration in sub-circuit file

VAR @LocalVar Comment

Including other datafiles

INC FileName

PLOT CODES TO USE FOR THE MODELS-V Voltage (Volts)-C Current (Ampere)-A Current (Ampere)-P Power (Watt)-W Power (Watt)-S State of switch (0 or 1)- Nothing

( Any combination of the above plot codes is also possible, e.g. -VCW )


EXECUTE COMMANDS

GO Start or restart a simulation

EXIT Exit from KREAN (No save on exit)

DRAW Draw selected curves

DRAW <N> Draw selected curves together with reconstructed curves based on thefirst n-harmonic components.

PLOT Plot selected curves on printer

HARDRAW Draw harmonic bar diagram for selected and analysed curves

HARPLOT Plot harmonic bar diagram for selected and analysed curves on printer.

ANALYSE Start fourier analysis of selected curves.

CONTINUE Continue a simulation of which the end values have been saved on aINI-file.

SELECT Select curves for DRAW, PLOT, ANALYSIS or SAVE.

REFRESH Redraw the current display (if possible)

EMTY-PLOT-ARRAY Delete results created up to the current time in the simulation.

MACRO Read commands from a macro file (MAC-file)

FILE COMMANDS

DATAFILE Read a new datafile (KRE-file)

RELOAD Reload the current datafile.

SAVE Save formatted results (RES), un-formatted results (RUF), fourieranalysis results (ANA), plot setup/macro file (MAC), initial values(INI), selected results (RES) or matrix formatted results (MAT).

READ Read results from file (RES- or RUF-file)

MACRO Read commands from macro file (MAC-file)

SELECT Select curves to be saved by the SAVE command.

DISPLAY COMMANDS

STATUS Display the Status menu

SET-UP-PLOT Display the Set-up-plot menu

AXIS Display the Axis menu for the default window

WINDOW Set the default window for the Axis menu

FOURIER Display the fourier analysis menu

DRAW Draw selected curves

HARDRAW Draw the harmonic bar diagrams for selected and analysed curves

SELECT Display the Select menu and enter select mode.


SETTING COMMANDS

SIMULTANEOUS-PLOT Turn on and off simultaneous plotting of selected curves duringsimulation.

PU-PLOT Turn on and off per unit plot option

AUTO-SCALING Turn on and off automatic scaling of y-axis

GRID Turn on and off the grid points on plots

POINTS Turn on and off simulation point marks.

TIME-ON-PLOT Turn on and off the current time on plots

BORDERS Turn on and off borders on plots

COLOURS Turn on and off colours on curves

BLACK-AND-WHITE Turn on and off black-and-white plots

TMAX Set a new TMA (end-time) for a simulation (overrules the end time forthe simulation specified in the input datafile)

HMAX Set a new HMA for a simulation (overrules the maximum time steplength specified in the input datafile)

ERR Set a new ERR for a simulation (overrules the error tolerancespecified in the input datafile)

FOURIER ANALYSIS COMMANDS

ANALYSE Starts a fourier analysis of selected curves

FOURIER Displays the fourier menu which shows the current settings for thefourier analysis

HARSTART Set the start time of the time interval to be fourier analysed

HARPERIOD Set the fundamental period for the fourier analysis

HARMIN Change the minimum value on x-axis on fourier bar diagrams plots.

HARMAX Change the maximum value on x-axis on fourier bar diagrams plotsand/or set the maximum harmonic number to be calculated

HARDRAW Draw the harmonic bar diagram of selected and analysed curves.

HARPLOT Plot the harmonic bar diagram of selected and analysed curves(printer, file or clipboard)

DRAW <N> Draw the selected curves together with reconstructed curves based onthe first n-harmonic components.

PLOT If this command is given after a “DRAW <N>” command, thenselected curves together with reconstructed curves based on the firstn-harmonic components will be plotted on printer.

SAVE Write fourier results to a file (ANA-file)


AXIS SCALING COMMANDS

DRAW Draw the selected curves. Note: Changes in axis scaling are not seenuntil a new DRAW command is given.

AUTO-SCALING Turn on and off automatic y-axis scaling

XMIN Set a new minimum value on x-axis for the default window(s)

XMAX Set a new maximum value on x-axis for the default window(s)

YMIN Set a new minimum value on y-axis for the default window(s)

YMAX Set a new maximum value on y-axis for the default window(s)

WINDOW Set default window(s)

PU-PLOT Turn on and off per unit plot

RIGHT Draw the selected curves after an automatic change in the x-axisscaling such that the “view” is shifted half a window to the right (bothXMIN and XMAX is increased)

LEFT Draw the selected curves after an automatic change in the x-axisscaling such that the “view” is shifted half a window to the left (bothXMIN and XMAX is reduced)

ZOOM Zoom and draw the left half of the currently displayed curves (XMAXis reduced)

EXPAND Performs the opposite action of the zoom command. (XMAX isincreased)

ALL Draw selected curves after an automatic change of XMIN and XMAXsuch that the whole interval from the start to the end of the simulationis drawn.

AXIS Display axis menu which shows the axis settings for the defaultwindow(s)

WINDOW Select the default window(s) for the Axis menu

SAVE Save plot setup (MAC-file)

PLOT LAYOUT COMMANDS

DRAW Draw the selected curves. Note: Changes in plot layout commands arenot seen until a new DRAW command is given.

SELECT Select the curves for y-axis

LAYOUT Select the plot layout (one, two or four axis systems)

GRID Turn on and off the grid on plots

POINTS Turn on and off plot point marks.

TIME-ON-PLOTS Turn on and off the current time on each plot

BORDERS Turn on and off borders on the plots

COLOURED Turn on and off colours on curves

BLACK-AND-WHITE Turn on and off black-and-white plot

SAVE Save current plot setup (MAC-file)


CURVE TEXT COMMANDS

DRAW Draw the selected curves. Note: Changes in curve texts are not seenuntil a new DRAW command is given.

FIGURE Change figure text on the default window(s)

XTEXT Change x-axis text on the default window(s)

YTEXT Change y-axis text on the default window(s)

XUNITY Change x-axis unity text on the default window(s)

YUNITY Change y-axis unity text on the default window(s)

WINDOW Set default window(s)

LOCUS PLOT COMMANDS

XAXIS Select the curve for x-axis

SELECT Select the curves for y-axis

TLOW Set the lower time point in the result array for the locus plot.

TUPPER Set the upper time point in the result array for the locus plot.

DRAW Draw the locus plot with the selected curves on the x-axis and y-axis

PLOT Plot the locus plot with selected curves on x-axis and y-axis on aprinter.

FILE EXTENSIONS

.KRE Input datafile.

.PRE The “pre-compiled” input datafile. Datafile after the replacement of symbols andsub-circuits.

.LST The list file contains information on how Krean has understood the input datafile. Italso contains any error messages that occurred during the reading of the datafile.

.RUN The RUN-file contains statistics about the simulation (size of equation system,number of iterations etc.)

.ANA The results of the fourier analysis are written to the ANA-file (mean-, maximum-,minimum-, rms-values, harmonics etc.)

.RES The RES-file contains formatted results which can be read by krean or by a textediting program

.RUF The RUF-file contains un-formatted results which can only be read by the Kreanprogram.

.MAT The MAT-file contains formatted results stored in a “matrix” format. This file cannot be read by Krean, but programs such as Matlab, Lotus, Excel etc. can import thisfile.

.MAC Macro command file

.INI Initial values for a continued simulation (holds the final values of state variables andswitch states of a finished simulation)


Table of content Page I

The KREAN reference manual

1 About this manual 1-1

2 The program and its applications 2-1

2.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.2 The history of the KREAN program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-1

2.3 Characteristics of the KREAN program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2

2.4 The user interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

2.5 The models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6

2.6 Application examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-11

2.7 The applied numerical solution methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-14

2.8 References for more reading about KREAN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-16

3 The basic steps of a simulation 3-1

3.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-1

3.2 Define the objectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

3.3 Modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

3.4 Drawing the circuit. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

3.5 Giving a name to every node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

3.6 Giving a name to every component . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

3.7 Creating a data-file for the simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-3

3.8 Running the simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

3.9 Process and verify the results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4

4 Datafile syntax 4-1

4.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

4.2 Control commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-1

4.3 Circuit specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

4.4 Blank lines, spaces and comment lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-2

Page II Table of content


4.5 Format of numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

4.6 Example of a datafile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3

5 Control codes 5-1

5.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-1

5.2 Start time for the simulation (TMI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2

5.3 End time for the simulation (TMA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

5.4 Error tolerance (ERR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-4

5.5 Maximum time step length (HMA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-6

5.6 Use of symbols in datafiles (SYM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-8

5.7 Controlling the storage of results (SMI, SMA) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-10

5.8 Plotting point factor (PPF) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-11

5.9 Specify directory for sub-circuits (DIR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-12

5.10 Variable declaration in sub-circuit file (VAR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-13

5.11 Including other datafiles (INC) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-14

6 Models 6-1

6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-1

6.2 Resistor. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3

6.3 Capacitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-5

6.4 Inductor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-7

6.5 Current source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-10

6.6 Voltage source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-13

6.7 Controlled sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17

6.8 Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-21

6.9 Diode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-23

6.10 Time controlled bi-directional switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-26

6.11 Voltage controlled bi-directional switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-29

Table of content Page III


6.12 Time controlled uni-directional switchand Time controlled thyristor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-32

6.13 Voltage controlled uni-directional switchand Voltage controlled thyristor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-36

6.14 Ideal short. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-40

6.15 Sub-circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-41

6.16 Modules (general format). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-43

6.17 Specification of piecewise linear source functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-46

6.18 Specification of trigger signals for switches and thyristors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-48

7 Running a simulation 7-1

7.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

7.2 The basic steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-1

7.3 The LST- and PRE-files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2

7.4 Statistics from the simulation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

7.5 How to continue a simulation at some other time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-3

7.6 New defaults for plot set-up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

8 Result presentation and analysis 8-1

8.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

8.2 Time domain plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-1

8.3 Locus plot. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-4

8.4 Fourier analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5

8.5 Writing time domain results to files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

9 Commands 9-1

9.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-1

9.2 Execute commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

9.3 File commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-7

Page IV Table of content


9.4 Display commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-9

9.5 Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-10

9.6 Axis commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-12

9.7 Locus plot commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-15

9.8 Fourier analysis commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-16

10 Sub-circuits 10-1

10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

10.2 How to define sub-circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-1

10.3 How to use a defined sub-circuit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4

10.4 Single line three phase sub-circuits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8

11 Error and warning messages 11-1

11.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

11.2 The error messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-1

11.3 The warning messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-10

12 File extensions 12-1

13 Limits 13-1

14 Changing default values 14-1

14.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

14.2 The datafile syntax for default settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14-1

Index I

1. About this manual Page 1 - 1


1 ABOUT THIS MANUAL

This manual is the reference manual for the power electronic simulation program KREAN.Contained in this manual is a description of the commands and the basic models of this program.

Documentation of the more advanced models, the “KREAN modules”, are found in separatemanuals. The user modelling features are also not described here, but can be found in the“KREAN module manual”.

The contents of this manual are as follows:

Chapter 2: Describes the KREAN program, briefly outlines the solution methods,presents the available models, shows application examples and givesreferences for further reading.

Chapter 3: Outlines the basic steps necessary to perform a KREAN simulation.

Chapter 4: Outlines the input data-file syntax to describe a circuit to be simulated.

Chapter 5: Presents the datafile syntax for the control codes used to control a simulationjob.

Chapter 6: Presents the basic models and their data-file syntax.

Chapter 7: Describes how to run a simulation after a data-file has been created.

Chapter 8: Describes how to analyse and present results.

Chapter 9: Presents the available commands for the KREAN program.

Chapter 10: Describes how to define and use sub-circuits.

Chapter 11: List of error and warning messages

Chapter 12: List of the different files created by the program during a simulation job.

Chapter 13 List of the important limitations of Krean.

Chapter 14: Describes how to change default values.

Page 1 - 2 1. About this manual


2. The program and its applications Page 2- 1


2 THE PROGRAM AND ITS APPLICATIONS

2.1 INTRODUCTION

This chapter presents the KREAN program.

Short summary of the chapter:

• Circuits to be simulated by KREAN must be described in an input data-file (text-file). • The main output results are time domain plots and harmonic information. • The basic component models offered by KREAN are all linear or piece wise linear, but more

advanced models are also available.• The basic switch models are ideal. • The user can in a modular way, define new component models by means of fortran subroutines.• The program has automatic time step control.• Accurate numerical methods. • Accurate breakpoint detection methods. • Possible to include non-linear models.• User modelling facilities.• No schematic capture for the user interface.• The computational speed in some cases is slower than compared to programs dedicated for

special circuits. However, Krean has a similar speed of general simulation programs using lessaccurate and robust solution methods.

2.2 THE HISTORY OF THE KREAN PROGRAM

The history of KREAN goes back to 1984 when Ass. Prof. Robert Nilssen at the NorwegianInstitute of Technology initiated the development of a simulation tool for power electronics. Thedescription of the first version was ready in 1986. The work on a totally new version, based on theexperiences from the first version, started in 1987. Since then there have been many improvementsand extensions.

The development of Krean has been carried out in a close cooperation between the The NorwegianInstitute of Technology (NTH) and the Norwegian Electric Power Research Institute (EFI) (bothlocated in Trondheim, Norway). The EFI group has continuously used the program in researchprojects and this cooperation has enhanced the final result.

Page 2- 2 2.3. Characteristics of the KREAN program


2.3 CHARACTERISTICS OF THE KREAN PROGRAM

2.3.1 Qualities

KREAN has been developed specially for power electronic simulations. Thus it has been possibleto apply methods specially suitable for power electronic simulation. This fact, and the closecontact between developers and users of the program during the development is two of the reasonswhy Krean has become a powerful tool.

One of the characteristics of the program is its accuracy. The two most important properties whichinfluences on the accuracy of the program are the exactness in the breakpoint detections and theaccuracy of the differential equation solver algorithm1. These have both been focused on duringthe development of the program. Especially the treatment of switchings of the ideal switch modelsand other types of breakpoints. The differential equations are solved by means of a differentialequation solver algorithm developed by professional mathematicians.

Another important aspect of a simulation program is its robustness. A simulation program shouldnot crash or run into infinite loops (convergence problems). Also it should not introduce numericaloscillations in the results. These numerical oscillations typically confuse the user and even worse,they can initiate switchings at incorrect time instants.

A robust program also implies that an arbitrary connection of components is allowed and thatparameters can be selected over a wide range. This is especially important in the debugging of acircuit model or in case the user does not know in advance what the results should be, and thusmakes serious errors for instance in a control strategy. The program should then be capable ofgiving the “correct” result of the specified circuit, even if the “correct” result is far from anyreasonable answer (for instance voltages in the MVolt range across a capacitor). In this way theuser is allowed to inspect voltages and currents in the simulated circuit in order to find the errors inthe modelling (or in the topology).

The main properties which make KREAN a robust program are:

- the accurate treatment of breakpoints- the selected algorithm of differential equation solver- the models which all can be connected together arbitrarily- the precautions against floating node voltages

Other advantages of KREAN are the accurate treatment of nonlinearities and the flexibility in theKREAN-module concept. The user can include new models whenever necessary.

The ideal component models are also important. Because of the use of simple switch models, it ispossible to perform long term simulations covering thousands of switchings with a reasonablecomputational cost. This would not have been possible if “accurate” switch models with detaileddescription of the switching interval have been applied.

1. By accuracy it is meant the accuracy of the numerical solution of the circuit as it is modelled, not the accuracy of the models or the accuracy of the results compared to measurements.

2.3. Characteristics of the KREAN program Page 2- 3


2.3.2 Limitations

Programs have usually certain limitations, and KREAN is no exception.

Models. The development of KREAN has focused on efficient methods for long term simulationswith many switchings. Therefore, very simple switch models have been implemented. Moredetailed modelling will sometimes be desired. At the moment there exists no general detailedswitch models in the standard KREAN version. There exists although, detailed models of a diodewhich includes forward and reverse recovery. A detailed model of an IGBT has also beenimplemented.

What must be remembered is, that it is possible to add new models to the program withoutmodification of the program. A detailed switch model can be realized in a KREAN-module. Theproblem is to develop a proper mathematical model of the power electronic devices. Oncedeveloped it can be implemented in a KREAN-module. Thus, although the program lacks detailedmodels at the moment, it is prepared for implementation of more advanced ones.

Semiconductor models are found described in the literature and in conference proceedings. Thereason why none of these has not yet been implemented in KREAN-modules are mainly becausethere have been little interest from the current users and because the accuracy of the models havebeen questioned.

Computational speed. The program has been written to be as efficient as possible. Still, for certainapplications users claim that it is too slow. This is in particular true in simulations where powertransmission lines are modelled as RLC-networks. The reason why, is that accuracy androbustness have been given high priority. The selected method for integration of differentialequations has led to slower simulation compared to programs using more simplified andinaccurate methods. This is the drawback of a accurate and robust program.

The speed of a simulation always depends on the accuracy of the methods applied. It is also highlydependent on the circuit to be simulated. It is possible to develop special purpose simulationprogram, dedicated for one specific converter or topology. Such a program is usually faster than ageneral program. This because of the necessary internal “overhead” work in a more flexiblesimulation program (the worst cases must be considered).

Initial transients. Very often the desired part of the simulation results are the waveforms in somesteady state operation. The computation time needed to reach this steady state operation can oftenbe long. Initial transients force the user to simulate the circuit for a long time before the steadystate operating waveform is found. KREAN allows specification of initial values ofstate-variables, but there are no refined methods implemented for fast transition to steady stateoperation. The simulation must be run until the transients have decayed (the brute-force method).

Alternative analysis methods. It is frequently seen that simulation programs offers more than onetype of analysis. The others are frequency domain analysis, phasor analysis, pole/zero analysis,distortion analysis, transfer function analysis and noise analysis. KREAN only offers the timedomain analysis. Thus other programs must be used together with KREAN if other types ofanalysis are desired.

Page 2- 4 2.4. The user interface


2.4 THE USER INTERFACE

2.4.1 Introduction

A new user interface was developed for KREAN in 1988. Since then there have been a lot ofmodifications, but the basic ideas of the user interface are still the same.

Commands are written directly from the keyboard. All commands are available (i.e. can be used),independent of which display is presented on the screen. Separate commands select the display tobe shown on the screen. Any unique short forms of the commands can be used. This can be a veryefficient method for experienced users.

In the PC-Windows version it is also possible to use mouse menus together with the keyboard, likein other Windows applications.

The available commands are described in chapter 9.

2.4.2 The input

KREAN does not provide schematic input facilities. The circuit to be simulated is described in aninput datafile (“KRE-file”). The structure and syntax of the description are similar to what is usedfor the SPICE simulation program.

A KREAN-simulation consists of the steps illustrated in Fig. 2-1. The datafile is to be created in atext editing program. Each type of component has a specific syntax. A free format structure is usedin the input file such that extra spaces and extra lines can be inserted anywhere. Comment-linescan also be placed anywhere. The free format and the comment lines makes it easier to createsystematic and “easy to read” input datafiles.

Fig. 2-1 Illustration of the steps in a KREAN simulation.

Draw the circuit and give name to components and nodes

Write a datafile description for the circuit (KRE-file)

Simulate the circuit, analyse results and plot curves

(On a paper or by use of a drawing program)

(Using a text editing program capable of saving ASCII text (plain text))

(Using KREAN)

2.4. The user interface Page 2- 5


Every component in a circuit, and every circuit node, has to be given a unique name. These namesare used in the datafile and also as identifiers on the created results.

Each component specification in the datafile starts with a code which identifies the type ofcomponent to be specified. Then follows the component name, the name of the nodes to which it isconnected and finally a number of parameters. In addition, it is possible to specify initial values ofdynamic components (capacitor voltages and inductor currents) and also to specify initialconducting state of switches/thyristors (on or off). The syntax for the data input also includes oneparameter for selection of the component results to be stored (voltage, current etc.).

The datafile also contains control data for the simulation. This includes specification of the timeinterval for the simulation, error tolerance, maximum time step length etc.

2.4.3 The output

The output of the program is primarily time domain plots, either on the screen or on a printer/plotter. All the plots are quantities related to components (and not to nodes and branches). Thespecifications in the datafile decides which plots that are available (stored) after a simulation. Thepossible plot options for the basic models are:

- voltage across component (also control voltages/secondary voltages)- current through component (also control currents/secondary secondary)- instantaneous power (delivered or dissipated)- switch state (on/off)

For the KREAN modules to be described in section 2.5.3, there also exists other plot options.

Results, both un-formatted and formatted can be written to files. They can be read again by theprogram for later plotting and post-processing. The formatted results can also be read by otherprograms in case some special post-processing are desired.

KREAN offers post-processing facilities by means of discrete Fourier analysis. The user canspecify one interval of the time domain results to be analysed (the interval is assumed to be equalto the fundamental period). The results for each selected curve after a Fourier analysis are:

- total rms-value- rms value of fundamental component- rms value of the harmonics (absolute and relative to total rms)- mean value- phase angle of the fundamental and harmonics- minimum magnitude in the specified interval- maximum magnitude in the specified interval

The post-processed results can be written to file. The harmonic content can also be plotted as a bardiagram on screen or printer/plotter.

Page 2- 6 2.5. The models


2.5 THE MODELS

2.5.1 Introduction

KREAN provides one set of basic models. Additional component models are also found. These arecalled “KREAN-modules”. A number of KREAN-modules have been developed for KREAN. Theuser can also define new ones on his own. The reason to split the models in one basic group andone group named modules, is the different ways they are treated during the simulation (by thenumerical algorithms)

Note 1: Some early versions of the program does not include modules and/or does not allows theuser to define his own models. See separate description of the specific version in use forinformation about which modules that are included.

Note 2: This manual describes the basic models only. Each type of module is described in separatedocuments, although examples of modules are listed in section 2.5.3 of this manual.

2.5.2 The basic models

The basic models are all linear or piecewise linear. They are illustrated in Fig. 2-2. All the basicmodels are idealized and not all of them are models of physical devices, but they form a set wellsuited for modelling of circuits for studies of system behaviour. Details about the models are foundin chapter 6.

The passive models. The following passive models are implemented in the basic set of models:

• Resistor (Constant resistance)• Capacitor (Constant capacitance. The model includes an inner serial resistance which must be

specified in the datafile)• Inductor (Constant inductance. The model includes a parallel resistance to be specified in the

input datafile)• Transformer (Four terminals and constant transformer ratio. The model includes one serial

resistance on the primary side and one resistance parallel to the primary winding. Leakage andmagnetizing inductances is not included in the model.)

The switch models. The basic set of models includes idealized models of semiconductors. Theswitch model is not necessarily a model of a semiconductor switch. It can be looked upon as amodel of a general switching device.

All the switch models are modelled as high resistances in the off-state and low resistances in theon-state. The following models are included in the basic models:

• Diode (Ideal. It is possible to specify a minimum forward voltage for turn on and a peakreverse recovery current. Note that the model has an instantaneous snap off (no soft recovery)

• Switch, time controlled (Two-terminal device which conducts current in both directions. Theswitching period and one period of the switch on/off-pattern is specified in the input datafile)

• Thyristor, time controlled (Two-terminal device which conducts current in only one direction.The switching period and one period of the thyristor on/off-pattern is specified in the datafile.Both “normal” and GTO (Gate Turn Off) turn off can be specified.)

2.5. The models Page 2- 7


• Switch, voltage controlled (Four-terminal device of which two are ideal control terminals (infi-nite impedance). The voltage between the control terminals determines the time instants forturn on and off of the switch. The control voltage levels for turn on and turn off is specified inthe input datafile)

• Thyristor, voltage controlled (Four-terminal device of which two are ideal control terminals(infinite impedance). The voltage between the control terminals controls the time instants forturn on and off of the thyristor. The control voltage levels for turn on and turn off (“normal”and GTO) is specified in the input datafile)

Independent sources. The independent sources are time varying sources independent of voltageand currents across other components. The following independent sources are included in the basicset:

• General voltage source (A periodic piece-wise linear source. One period of the piece wise lin-ear voltage waveform must be specified. The voltage waveform is specified through a set oftime-voltage coordinates. Linear interpolation is used between the specified coordinates, giv-ing a piecewise linear relationship between time and voltage.)

• General current source. (A periodic piece-wise linear source. Specified in the same way as thegeneral voltage source)

• Sinusoidal voltage source (Frequency, rms-voltage and phase angle must be specified in thedatafile)

• Sinusoidal current source (Frequency, rms-current and phase angle must be specified in thedatafile)

Inductor Capacitor Resistor Current source Curr. controlled curr. source

Curr. controlled vol. source

Voltage control-led switch

Voltage control-led thyristor /

transistor

Diode Voltage source Vol. controlled curr. source

Vol. controlled vol. source

Time controlled switch

Time controlled thyristor / transistor

Transformer

N:1

Fig. 2-2 The figure illustrates the basic components available in KREAN. These are linear andpiece-wise liner models.



The voltage source models all include a serial resistor to be specified in the input datafile while thecurrent source models include a parallel resistor.

Dependent sources. A set of dependent sources are also included in the basic set of models. All thedependent sources are four terminal models with two control terminals and two source terminals.The dependent sources are linear with a constant gain.

• Voltage controlled voltage source.• Voltage controlled current source.• Current controlled voltage source.• Current controlled current source.

All control terminals are ideal. Thus no current flows into the control terminals of voltagecontrolled sources. Similarly, in current controlled sources there are zero voltage between the twocontrol terminals.

2.5.3 Modules

General. The KREAN-modules may be predefined and enclosed with the program or defined(programmed) by each user of the program. As mentioned, modules are treated in a special wayduring the solution of the circuit. This because they all are expected to be non-linear models. Amodule can be used to describe a wide variety of devices, systems and behaviours (e.g. motors,controllers, nonlinear device models). As already mentioned, the number of modules linked to theKREAN program differs for the different versions of the program.

A module in KREAN is a multi-terminal model which may have a dynamic and/or nonlinearbehaviour. Each type of module is described in a Fortran subroutine. Once specified and linked toKREAN, the module can be used together with, and in the same way as the basic models. Differenttypes of modules can be used in the same simulation. Several modules of the same type can also beused in the same simulation.

The modules can be arbitrarily connected in circuits in the same way as the basic models. The userspecifies the nodes to which the module is to be connected, the module parameters, initial valuesof internal module state-variables (dynamics of the module) and selects which internal moduleplots to store during the simulation.

The number of terminals, parameters, plots and internal state-variables are specified by thedeveloper of each type of module. Fig. 2-3 illustrates the general KREAN-module.

2.5. The models Page 2- 9


Examples of modules. A number of modules developed for the KREAN program is listed below.These can be used in simulations together with the basic models if they are included in theKREAN version which are in use. The modules are further described in separate documents(datafile syntax, parameters, etc.).

Examples of modules developed for the KREAN program:

MUL Multiplier where the output equals a gain multiplied by two input voltages.SH Sample and hold elementVCSIN Three phase voltage source with voltage controlled frequency and amplitude.ASYNC2 Induction machine motor model (based on two-axis theory)PMSM1 Permanent magnet rotor synchronous machine model (based on two-axis theory).SYNCRO Synchronous machine model (based on two-axis theory).COMP ComparatorELREL Electric to reluctance circuit interface (model of a winding).VCRES Voltage controlled resistor (the voltage at the control terminals controls the

resistance between two other terminals)VCCAP Voltage controlled capacitorVCIND Voltage controlled inductanceVCTRAN Voltage controlled transformer (the voltage at two transformer control terminals

controls the ratio of the transformer model) VCPOW Voltage controlled power source/sink.SATIND Saturable inductorVDRES Voltage dependent resistorVDCAP Voltage dependent capacitor

AAAAAAA

u1 = f1 (Y,U,I,t)

u2 = f2 (Y,U,I,t)

in-1 = fn-1 (Y,U,I,t)

in = fn (Y,U,I,t)

dY_dt = F(Y,U,I,t)

voltage response terminals

current response terminals

Fig. 2-3 A general KREAN-module. The number of terminals are variable. Some of theseterminals have a voltage response and some are current response terminals. Thedynamics can be described by a differential equation. Y is the internal state-variables,U is the terminal voltages, I is the terminal currents, t is the time. ui and ij are theresponses calculated by the module subroutine. The functions fi and F are linear ornonlinear functions described in Fortran statements.

AAAAAAAAAAAA

AAAAAAAAAAAA



Terminal behaviour of modules. The terminals of a module can be either of voltage or currentresponse type.

For the current response terminals, the module subroutine must calculate the response current of agiven exciting terminal voltage (passed to the subroutine from KREAN). For the voltage responseterminals it is opposite, that is, the subroutine calculates the voltage response to a excitationterminal current.

Note that the voltages and current at the module terminals are simultaneously iterated togetherwith the (piecewise) linear circuit. There is no time delay between excitation and response of themodule terminals. They are true nonlinear models, something which is important for the stabilityproperties of the numerical solution of the differential equations.

Individual parameters for modules. It is possible to specify individual parameters for the modulesin the datafile for a specific simulation. This increases the flexibility and reduces the number ofdifferent types of modules needed. This corresponds to the increased flexibility achieved byhaving only one resistor model with a parameter specifying the resistance instead of one model foreach resistance value.

The number of parameters for each type of module is optional and is defined by the programmer ofthe module.

Dynamic behaviour of modules. The modules are allowed to behave dynamically. This impliesthat state-variables can be defined within the modules. The differential equations describing thedynamics in the module are solved simultaneous to the differential equations for the rest of thecircuit. The differential equations are limited to those which can be described by the form:

(2-1)

where Y is the module state-variables, t is the time, U is the terminal voltages and I is the terminalcurrents. The function f can be any linear or nonlinear function which is possible to describe bymeans of Fortran statements.

Breakpoints. A module subroutine may order (require) breakpoints. Breakpoints are time instantsat which a simulation point is needed/wanted. This can typically be a discontinuity point in themodule behaviour or a discrete sampling of some input. At breakpoints it is also possible tore-initialize module state-variables. Thus, a module state-variable can for instance be set to zero ata breakpoint.

The module can order state breakpoints. State breakpoints are “implicit” breakpoints. This meansthat the module can order breakpoints at time instants where some voltage or current (or any otherquantities) becomes equal or reaches certain limits. The program detects when the breakpointcriteria is satisfied and places a simulation point at the time instant at which the criteria becomessatisfied. This is an important feature which makes the modules much more versatile.

Plot variables. It is possible to store internal results from modules to be plotted (and/orpost-processed) after a simulation. An optional number of plot variables can be defined for eachtype of module. The plots are not limited to terminal currents and voltages. The programmer of themodule can define plots which shows internal calculations. Information of interest depends onwhich device, system or behaviour the module describes. Examples are power, flux in nonlinearinductors, speed and flux in motor models, magnitudes and derivatives of state-variables incontrollers.

tddY

f Y,U,I,t( )=

2.6. Application examples Page 2- 11


Data flow. A set of variables is passed from the main program to the module subroutines each timethey are to be used. The variables passed to the routine are:

- the time variable in the simulation (t)- terminal voltages of the current response terminals (U)- terminal currents of the voltage response terminals (I)- the magnitudes of the internal state-variables (Y)- the individual parameters for the module (p)- command flag (specifies the action to be carried out by the module at each specific call)

Based on the input variables the module subroutine is expected to return:

- the current response of the current response terminals ( f1(U,I,Y,p,t) )- the voltage response of the voltage response terminals ( f2(U,I,Y,p,t) )- the time derivatives of internal state-variables (Y

.) at time t ( f3(U,I,Y,p,t) )

- plot variables at time t ( f4(U,I,Y,p,t) )

The above is the “normal” information returned by the module subroutine. In certain calls to themodule subroutine it is expected to give another kind of information back to KREAN. This iscontrolled by a command flag. The information expected in the special cases is:

- the next breakpoint time (time breakpoint)- the criteria for next state breakpoint

All information returned by the subroutine can be time dependent, determined as a function (linearor nonlinear) of the terminal voltages, currents and/or the state-variables. It can also be constantsor quantities depending on the individual parameters of the module. How the returned values aredetermined and formulated does not matter as long as they can be described by means of Fortranstatements.

For further details about KREAN modules, see the list of references at the end of this chapter.Programming of modules are described in the “KREAN module reference manual”.

2.6 APPLICATION EXAMPLES

KREAN has been used both in research projects and for educational purposes. Some examples ofapplications which have been analysed are:

- diode rectifiers - 6, 12, 24 pulse thyristor rectifiers in motor drives- controlled PWM converters- controlled resonant converters- uninterruptable power supply systems (UPS´s)- flyback converters- forward converters- sinusoidal line current rectifiers- snubber circuits

Page 2- 12 2.6. Application examples


- motor drives (induction motor, permanent magnet synchronous motor, dc-motor)- harmonics in power supply systems- induction motors drives with long cables between converter and motor (>30 Km). - active filters for converters

These are only some of the possible applications that Krean can be used for.

Some examples of results from KREAN simulations are presented in Fig. 2-4 to Fig. 2-8.

Fig. 2-4 The figure shows the simulated dc-current drawn by a a three phase sinusoidalPWM-converter operating at a frequency modulation of 15 and an amplitudemodulation of 0.8.

Fig. 2-5 The figure shows the simulated resonant inductor current (left) and the correspondingsimulated resonant capacitor voltage (right) in a serial loaded resonant converter.

2.6. Application examples Page 2- 13


Fig. 2-6 The figure shows the simulated phase currents (left) and the corresponding simulatedupper phase R transistor current (right) of a PWM motor-drive for an electric car.

Phase R line current

R-S-line to line voltage

Fig. 2-7 The figure shows one of the simulated line currents (left) and the correspondingsimulated line-to-line voltage (right) of a diode rectifier.

Page 2- 14 2.7. The applied numerical solution methods


2.7 THE APPLIED NUMERICAL SOLUTION METHODS

The equation system for a circuit to be simulated are automatically built by the program. The useronly specifies the circuit in terms of nodes, topology and parameters.

In a general circuit three equation systems are established:

• a differential equation system • a linear algebraic equation system • a non-linear algebraic equation system (the modules)

A numerical integration algorithm finds the time domain solution of the equation system. Theapplied algorithm uses a implicit Runge-Kutta method of second and third order. The second ordermethod is used for error estimation. The error estimate is then used by the time step selectionalgorithm. Time steps in the simulation are automatically adjusted such that the error estimatebecomes less than the specified tolerance.

The Runge-Kutta method is a stable SDIRK-method (Singly Diagonal Implicit Runge-Kutta).Thus, errors in the solution are damped and the program can use time steps larger than the smallesttime constant of a circuit.

The numerical integration of the differential equations requires dc-solutions of the circuit beingcalculated a number of times for each time step. The dc-solutions are the solution of the linear andnon-linear algebraic equation systems. The non-linear equations are iterated together with the

Fig. 2-8 The figure shows the simulated line current (left) of a six-pulse thyristor rectifier in aDC-motordrive. A plot of the calculated harmonics of the current is shown in the plot tothe right.

2.7. The applied numerical solution methods Page 2- 15


linear equations system. A newton iteration technique is used for this purpose. The linear system issolved by an algorithm applying sparse matrix methods and LU-factorisation.

Note that the linear and non-linear equation systems are iterated together. Therefore thisintroduces no time-step delay between input and output of non-linear model terminals. Thisproduces accurate results.

An important feature of the KREAN program is the carefully implemented breakpoint detectionmethods. Breakpoints (events) are time instants at which there are some sudden changes in circuitparameters or topology. Some examples are:

• Instantaneous change of conduction state of ideal switches and diodes • Transition from one linear segment to another on a piece wise linear time dependent source

(“edges” of piece wise linear sources).• Transition from one linear segment to another on a component description given by a piece

wise linear voltage current relationships.• A sampling or other actions of digital nature

There are basically two reasons why accurate detection of breakpoints is requested. First, theaccuracy of the simulation depends on accurate breakpoint detection. No additional random timedelay is for instance introduced in a switch operation if a simulation point is placed accurately atthe time instant where the criteria for turn-on and turn-off is satisfied.

The second reason for the accurate detection of breakpoints is related to the solution of thedifferential equations. The use of insufficient breakpoint handling can typical cause convergencefailure and numerical oscillations. These problems can be avoided by simply forcing onesimulation point at the time of breakpoint and then restarting the simulation “just” after thebreakpoint as if it was the first time point.

A piece-wise linear source is an example of a model that may cause trouble for the differentialequation solver algorithm. If an integration method which has variable time steps is used and thesource model switches to a new linear segment automatically, then the differential equation solveralgorithm detects an increased error and decreases the time steps before the breakpoint and pass itwith very small time steps. This because the differential equation solver algorithm feels the step inthe time derivatives of the source output. The routine passes the breakpoint with very small timesteps in order to keep the error estimate of the state-variables below the specified error tolerance.A better approach is to force the program to generate a simulation point at the exact time ofbreakpoint (the time at which the time derivatives of the source output changes instantaneously). Itis then possible to avoid small time steps before the breakpoint is reached. This is the approachapplied in the KREAN program.

The extra work introduced for the breakpoint detection does not increase the computation time.Improved convergence and removal of small time steps before breakpoints usually gives a lessoverall computation time.

Page 2- 16 2.8. References for more reading about KREAN


2.8 REFERENCES FOR MORE READING ABOUT KREAN

2.8.1 Description of working principles

Nilssen R. & Mo O. , 1990“KREAN, a new simulation program for power electronics”, Conference proceedings PESC 90,USA, pp.506-511.

Mo O. , 1993“Time domain simulation and modelling of power electronic circuits. Development of asimulation tool”, Doctoral dissertation 1993:74, University of Trondheim, The NorwegianInstitute of Technology.

2.8.2 Description of KREAN modules

Nilssen R. , 1991“Programmable Modules in Simulation Programs for Power Electronic Circuits”, EPE´91 Firenze,pp.4-373 - 4-377.

Mo O. , 1991“KREAN Module Reference Manual”, KEM.92.005, Norwegian Institute of Technology (NTH),Power Electronics and Electrical Machines group, Trondheim, Norway.

Ringheim N.A & Mo O. & Ljøkelsøy K. & Nygård & Råd R.O. , 1992“KREAN moduler” Technical report KEM.92.032, The Norwegian Institute Of Technology,Power Electronics and Electrical Machines group, Trondheim, Norway.

Mo O. , 1993“KREAN modules II” Technical report KEM.93.010, The Norwegian Institute Of Technology(NTH), Power Electronics and Electrical Machines group, Trondheim, Norway.

2.8.3 Examples of applications

Kvien O. & Undeland T.M. & Rogne T., 1993“Models for simulation of diode (and IGBT) switchings which include the effect of the depletionlayer”, Conference Proceedings IEEE-IAS Annual Meeting vol.2 pp. 1190-1195, Toronto,Canada, 1993.

Mo O. & Hernes M. & Rogne T., 1993“Calculation of temperature conditions in semiconductors for variable speed induction motordrive”, Conference Proceedings EPE´93 (European Power Electronic conference) Vol.5pp.338-341, Brighton, England, September 1993.

Rogne T. & Mo O. & Schludersheid M.“Paralleling of semiconductors including temperature feedback, using spreadsheet or simulationtool, to calculate current and temperature differences”, Conference Proceedings EPE´93 Vol.2pp.149-154, Brighton, England, September 1993.

2.8. References for more reading about KREAN Page 2- 17


Mo O. & Nilssen R., 1993“Low cost program for simulation of power electronic converters and systems”, ConferenceProceedings EPE´93 Vol.7 pp. 29-34 Brighton, England

Ådnanes A.K. & Nilssen R. & Råd R.O. , 1992“Power feed-back during controller failure in inverter fed permanent synchronous motor driveswith flux weakening” Conference proceedings PESC´92 Toledo, Spain. pp. 958-963.

Mo O. & Petterteig A. & Ringheim N.A. & Nilssen R., 1991“Application of programmable modules in simulation of power electronics”, ConferenceProceedings EPE´91 Firenze, pp.4-396 - 4-401.

Mo O. , 1992“How to simulate controlled thyristor rectifiers by use of KREAN”, Memo KEM.92.006, TheNorwegian Institute Of Technology, Power Electronics and Electrical Machines group,Trondheim, Norway.

Petterteig A. , 1992“Development and control of resonant dc-link converters for multiple motor drives” Doctoraldissertation 1992:10, University of Trondheim, The Norwegian Institute of Technology.

Petterteig A. & Undeland T., 1991“Control of a resonant dc-link converter with a high mains power factor - the need of a powerfulsimulation tool”, Conference Proceedings EPE´91 Firenze, volume 4, pp.4-378 - 4-383.

Undeland T. et al., 1988“Diode and thyristor turn-off snubbers simulation by KREAN and an easy to use designalgorithm”, 1988 IEEE Industry application meeting vol.1 pp. 647-654

Page 2- 18 2.8. References for more reading about KREAN


3. The basic steps of a simulation Page 3- 1


3 THE BASIC STEPS OF A SIMULATION

3.1 INTRODUCTION

This chapter gives an outline of the steps to go through when using the KREAN simulationprogram. The basic steps are illustrated in the Fig. 3-1.

Fig. 3-1 The basic steps in a simulation if the KREAN simulation program is used.

(On a paper or by use of a drawing program)

(Using a text editing program capable of saving ASCII text (plain text))

(Using KREAN)

(Using KREAN or other result analysis programs)

Define the objectives of the simulation

Select a level of mod-elling suited for the defined objectives

Make a drawing of the circuit to be simu-lated

Give names to nodes and components

Create a datafile which describes the circuit.

Run the simulation as specified in the data-file description

Process and verify results

Page 3- 2 3.2. Define the objectives


3.2 DEFINE THE OBJECTIVES

The very first step in a simulation job is to define the objectives of the simulation. This is neededto pose the appropriate questions and to construct the simulation so that it is possible to answerthese questions.

The questions to answer can be:

- What is the purpose of the simulation ?- Which phenomena/problems are to be studied ?- Which time span need to be simulated ?- What kind of results is needed in order to meet the purpose of the simulation ?

3.3 MODELLING

The next step in a simulation job is to select a modelling suitable for the questions to be answered.Each question requires specific emphasis in the simulation.

A usual mistake is to try to get answer to all questions from one single simulation with detailedmodelling of every part of the circuit. This is not advisable. An experienced user will split the jobin several simulations, each focusing on one specific topic of interest. It is then possible tosimplify major part of the circuit and use detailed modelling only on a selected part of the circuit.Such an approach reduces the input data needed, the simulation time and thus also the chances forserious errors. Results from such simplified simulations are also much easier to verify.

If for instance component stresses due to parasitics are to be calculated, then the components andparasitics need to be modelled in detail for a few switching cycles, and the dynamic behaviour ofthe system in response to control input variation is of no concern. On the other hand, if the systemresponse is of interest, then ideal models of switches can be used and the parasitics can usually beneglected.

3.4 DRAWING THE CIRCUIT

It is very important to have a drawing of circuits which are to be simulated. The usual mistake isthat the user keeps the drawing of the circuit in his mind and expect to make no mistakes.However, debugging and verification of a simulation is very difficult without a drawing.

3.5. Giving a name to every node Page 3- 3


A drawing makes it easier to keep control of nodes and positive directions of currents andvoltages. The KREAN program has no schematic input feature. The user must therefore draw hiscircuit by hand or in some other circuit drawing program.

3.5 GIVING A NAME TO EVERY NODE

An electric connection point to which one or more components are connected are called a “node”.Every node in a circuit must have a unique name of maximum 10 characters. The node names areused when the user writes the datafile for the simulation. In the datafile the user specifies the nameof the nodes to which a component are connected.

The usual mistakes are the use different names on the same node, or giving the same name to twodifferent nodes. A good drawing of the circuit makes it easier to avoid such problems.

3.6 GIVING A NAME TO EVERY COMPONENT

Every component in a circuit must be given a name of maximum 6 characters. The componentnames are used in the input datafile. The KREAN program uses the component names asidentifiers on the results created after a simulation. No error is introduced if two components aregiven the same name, but the user may have trouble to identify which results belongs to whichcomponent.

3.7 CREATING A DATA-FILE FOR THE SIMULATION

A datafile for a KREAN simulation must have a name with the extension “.KRE”. (For unixwork-stations the name must be in lower case letters). In the datafile, the user defines the circuittogether with some control commands for the simulation. Chapter 4 gives details about the syntaxof KREAN input datafiles.

The file must be created in a text edit program (not included in the KREAN program). The filemust be an ASCII-file. Any text editing program capable of writing ASCII or DOS-files (plaintext) can be used for creation of input datafiles for a KREAN simulation (for instance “Notepad”in Windows).

Page 3- 4 3.8. Running the simulation


Note: Most text edit programs stores files in a special format, but there is normally a “save as “option for ASCII or DOS text. It is important to store these files as ASCII-files. Note also thattabulators in datafiles are not recommended.

3.8 RUNNING THE SIMULATION

The next step is now to run the simulation. It is then time to start the KREAN program and load thedatafile (command DATAFILE). If there are syntax errors in the input file, the user is notified witha error message and the actual error is given in the LST-file. A simulation is started using the GOcommand. If everything works as expected the simulation runs to the end and the results are readyfor inspection.

Chapter 7 outlines how to run the program. Detailed descriptions of available commands are foundin chapter 9.

3.9 PROCESS AND VERIFY THE RESULTS

After a simulation, curves are selected and drawn on the computer screen. It is now time forverification of the results. The user should take a close look at currents and voltages at differentplaces around in the circuit and see if the results are reasonable compared to simplified handcalculations.

Commands are available for selection of layout, scaling of axis etc. It is also possible to performfourier analysis in order to obtain the mean values and magnitude of harmonics (see chapter 8).

The results can be written to files. These files can be read by KREAN later on, or they may be usedas input to other suitable post-processing programs.

Both time-domain plots and plots of harmonic content can be sent to a printer.

4. Datafile syntax Page 4 - 1


4 DATAFILE SYNTAX

4.1 INTRODUCTION

The input for a KREAN simulation is specified in a datafile. This chapter gives a brief introductionto the syntax of the input datafile.

This datafile consist of control commands, the circuit specification and comments.

Note: The name of datafiles for the KREAN program must have the extension “.KRE”.

4.2 CONTROL COMMANDS

Control commands can be inserted in the KREAN input datafile for the following purposes:

- Set the start time for simulation- Set the end time for simulation- Specify an error tolerance for the simulation- Specify the maximum time step length in the numerical integration- Control the storage of results- Define symbols- Include other datafiles

The general syntax of the control codes use a three letter code followed by one or moreparameters, as illustrated on the line below:

XXX P1 P2 ...

A free format is used in the datafile, therefore an optional number of blank characters (spaces) canbe inserted before and after each parameter. The specific syntax of the available control codes aredescribed in chapter 5.

Page 4 - 2 4.3. Circuit specification


4.3 CIRCUIT SPECIFICATION

The circuit is specified on a component by component basis. There is no restriction on thesequence of specification of the components.

A component definition includes the name of the component, the name of the nodes to which it isconnected and a number of parameters such as initial values. Like the control codes, a componentdefinition starts with a three letter code. This three letter code tells KREAN the format of thecomponent definition.

Component definitions for the basic models are given on one, two or three lines, depending on thetype of component. Thus the general format of component definitions are one of the following:

XXX P1 P2 ...

XXX P1 P2 ...Pn Pn+1 ...

XXX P1 P2 ...Pn Pn+1 ...Pm Pm+1 ...

A free format is also used, thus it is the sequence of the parameters that are important and not theircolumn positions. Any number of blank characters can be inserted between the parameters.

The description of the syntax for the available basic models are found in chapter 6.

4.4 BLANK LINES, SPACES AND COMMENT LINES

It is recommended to write datafiles which are easy to understand. Easy to read datafiles reducesthe chances for errors and makes it easier to perform changes later on. Blank lines, extra blankcharacters and comment lines can be used for this purpose.

Blank lines can be inserted anywhere and extra blank characters can be placed betweenparameters.

A comment line starts with an slash or an asterisk ( / or * ). Thus a comment line is written likeone of the two following lines:

/ This is a legal comment line* This is also a legal comment line

4.5. Format of numbers Page 4 - 3


4.5 FORMAT OF NUMBERS

The convention for defining numbers in KREAN is with a decimal point. No spaces are allowedbetween a minus sign and a number. Below are some examples of legal syntax for numbers in adatafile:

1.0 23 .888 0.000001 -3.7

Exponential numbers are written in the following way:

1.0E-4 -2.4E2 -5E-3

4.6 EXAMPLE OF A DATAFILE

A small example illustrates what a datafile may look like. The example is a RL-circuit feed by asinusoidal voltage source. The circuit is shown in Fig. 4-1. An example of a datafile for the circuitare shown in Fig. 4-2. In addition to the circuit specification, the datafile specifies that thesimulation is to cover 3 periods (0.06 seconds) and that the error tolerance is to be 1.0E-3. Theexplanation of the component codes and definitions are given in the following chapters.

Fig. 4-1 The RL-circuit

R110 Ohm

L131.8 mH

Source50 Hz220 Vrms

Node1 Node2

Node3

Page 4 - 4 4.6. Example of a datafile


Fig. 4-2 Example of datafile for the RL-circuit in Fig. 4-1

/ Control data for the simulation/--------------------------------

/ End time for simulation

TMA 0.06

/Error tolerance

ERR 1E-3

/ The circuit/-------------

/The sinusoidal voltage source

VTG Source Node3 Node1 -vcp 2 0.0001220 50 0

/The load

RES R1 Node1 Node2 10 -vcp

IND L1 Node2 Node3 31.8E-3 -vcp 0 10000

5. Control codes Page 5- 1


5 CONTROL CODES

5.1 INTRODUCTION

This chapter describes the control codes which can be used in a datafile. The only control codewhich needs to be specified in every datafile is the TMA control code. This control the end time forthe simulation. All other control codes have default values and need not to be specified. There aresome additional control codes which are not described in this chapter. These codes are for veryspecial purposes and are described in a separate chapter (chapter 14).

The control codes all start with a three letter code and are followed by one or more arguments(numbers or text). Control codes can be placed anywhere in a data-file.

Page 5- 2 5.2. Start time for the simulation (TMI)


5.2 START TIME FOR THE SIMULATION (TMI)

Datafile syntax

Parameter

Tstart [sec.] [Default: 0]The start time (seconds) for the simulation.

Description

The start time (Tstart) of a simulation can be specified. The KREAN program assumes that thestart time of the simulation is at time zero if nothing else is specified. Thus it is not needed tospecify the start time of the simulation.

Note: It is not recommended to specify a negative start-time.

Example

TMI 3.2E-3

The above line specifies the simulation to start at time equal to 3.2E-3 seconds.

TMI Tstart

5.3. End time for the simulation (TMA) Page 5- 3


5.3 END TIME FOR THE SIMULATION (TMA)

Datafile syntax

Parameter

Tend [sec.] The end time for the simulation.

Description

The end time (Tend) of a simulation must always be specified. The simulation will stop at thespecified Tend.

Note: The simulation can be continued beyond the specified Tend by using the appropriatekeyboard commands. This is achieved by using the command TMAX which is described on page9-11.

Example

TMA 4E-2

The above line specifies the simulation to end at time equal to 4E-2 (=0.04) seconds.

TMA Tend

Page 5- 4 5.4. Error tolerance (ERR)


5.4 ERROR TOLERANCE (ERR)

Datafile syntax

Parameter

Tolerance [Default: 0.001]The maximum acceptable local truncation error in the integration of statevariables.

Description

The user is allowed to specify a tolerance for the local truncation error for the time domainsolution of the state variables. The local truncation error is the error introduced in one time-step bythe applied numerical integration method. The state variables are the capacitor voltages andinductor currents (there may be additional state variables in KREAN modules).

The KREAN program uses error estimation formulas for the applied numerical integration methodin order to get an upper bound for the error in a computed time-step. If the estimated error is largerthan the user specified tolerance, then the last time-step is re-computed using a reduced time-step.Thus the program reduces the time-step until the estimated error is below the specified tolerance.

It should be noted that the maximum global error, that is, the maximum error in the solution duringa simulation from the beginning to the end, can only be controlled indirectly. This is a generalproperty of all numerical integration methods. It is only possible to control the error in each singletime step. The accumulated error can only be controlled indirectly by controlling the error in eachtime step. However, even if one controls the error in each time step, this gives no guarantee for aerror less than the tolerance multiplied by the number of time steps. This is because the circuitsusually contains non-linear elements like diodes and switches.

The above comments are valid for all circuit simulation programs using numerical integration, butthey are not as dangerous as they may seem. Usually the global error tends to be in the same orderas the specified local error tolerance. The error estimation formulas are also very conservative inthe sense that the estimate is usually much larger than the actual error.

It may be difficult for the inexperienced user to specify a proper tolerance. If it is to large, then theresults become inaccurate. On the other hand, if a very small tolerance is used, then the CPU timeneeded for the simulation soon becomes too long. It is recommended to start with an errortolerance of 1.0E-3. If the results are not “smooth” then it is recommended to use a smallertolerance. If the simulation is slow, one may try with a larger tolerance.

ERR Tolerance

5.4. Error tolerance (ERR) Page 5- 5


To get an idea of the actual error in the results, one may simply run two (or more) simulations withdifferent error tolerances. If there is no significant difference in the results, one may conclude thatthe results are to be trusted. This is usually not needed as if the error becomes significant it willusually appear as numerical oscillations which are easily seen on a plot (seen as simulation pointsonly at the top and bottom of a oscillating variable).

Note: The Tolerance can also be changed during a simulation by use of a keyboard command.See description of the ERR command on page 9-11.

Example

ERR 1E-4

The above line sets the maximum allowed local truncation error to 1.0E-4.

Page 5- 6 5.5. Maximum time step length (HMA)


5.5 MAXIMUM TIME STEP LENGTH (HMA)

Datafile syntax

Parameter

Hmax [sec.] [Default: See description below]The maximum time-step length to use in the time domain simulation.

Description

The Hmax parameter specifies the maximum time-step length to use in the simulation. TheKREAN program applies automatic time-step control. Thus the program selects time-steps inorder to achieve the specified accuracy. In some cases it may may be needed to specify amaximum time-step length, either because of convergence problems, problems with detection ofswitching instants or simply because the circuit (or part of it) are non-dynamic without any statevariables.

For non-dynamic circuits without state variables, there will be no need for the program to usesmall time steps in order to achieve a specified accuracy. Thus the user must specify the maximumtime step such that the plotted results are smooth. The typical case is a sinusoidal source feeding anon-dynamic circuit. A certain number of time steps are then needed for each period otherwise thesinusoidal waveforms will not be smooth on the plots (even if the solution at every time point isexactly correct).

The default value of Hmax is given by the sources and the time controlled switches and thyristorsin the simulation. Hmax is by default set equal to the minimum value of:

- the period of piecewise linear voltage and current sources

- 10% of the period of sinusoidal voltage and current sources

- the period of time controlled switches and thyristors

Thus, there will be at least 10 time-points for each sinusoidal. If a smoother plot of the sinusoidalis desired, then it may be needed to specify Hmax in the datafile.

Note: Hmax can also be changed during a simulation by use of a keyboard command. See thedescription of the HMAX command on page 9-11.

HMA Hmax

5.5. Maximum time step length (HMA) Page 5- 7


Example

HMA 0.0001

The above line sets the maximum time-step length to 0.0001 seconds.

Page 5- 8 5.6. Use of symbols in datafiles (SYM)


5.6 USE OF SYMBOLS IN DATAFILES (SYM)

Datafile syntax

Parameter

@Name The name of the symbol. Must start with an “@”. The maximum number ofcharacters in a symbol name is 15 including the “@”.

Def The definition of the symbol. Must be a sequence of numbers and/orcharacters (maximum of 30 characters/numbers). A space in the definition isnot allowed. If a space is included, everything after the space will beconsidered as comments.

Comment Description of symbol action in order to make the file easier to maintain.

Description

The use of symbols makes it easier to perform changes in the datafile. A symbol is defined once,and can afterwards be used in several places in the datafile. Multiple symbols can be defined in thesame datafile.

If for instance, a symbol is defined for the operating frequency, then the changing of the operatingfrequency can be performed by only changing the symbol definition, instead of changing thespecification of all sources in the circuit.

The symbols can also be used for the replacement of any text or number. The only restriction isthat the symbol must be without any blank characters (spaces).

The definition of the symbols can be placed anywhere in the .KRE file, but symbols must bedefined before they are used. Each symbol can only be defined once in each file. Any redefinitionof the symbols are ignored.

A symbol definition starts with the three letters “SYM”. Then follows the name of the symbol. Allsymbol names must start with a “@”. After the symbol name follows the definition, that is the text/numbers which are to replace all occurrences of the symbol name in the datafile. At the end of theline, any comment may be given.

The program will replace all occurrences of the “@Name” in the .KRE file by the character/numbers in “Def”.

If the KREAN program reads a file named *.KRE then a file named *.PRE will be produced. Onthis file it is possible to check if the symbols have been correctly handled. Look in this file if there

SYM @Name Def Comment

5.6. Use of symbols in datafiles (SYM) Page 5- 9


is some errors in the symbols. The *.PRE file shows how the KREAN program has converted the*.KRE file. The end of the *.PRE file shows where the error occurred.

Note: Symbols can not be used in sub-circuit definition files ( .SUB-files).

Example

The following lines shows how the symbol “@FREQ” is used in the specification of a sinusoidalvoltage source:

SYM @FREQ 50 System frequency..VTG V1 N1 N2 0 2 0.001 220 @FREQ 0

The first line defines a symbol named @FREQ. The symbol is defined to be equal to 50. Thecomment after the definition tells the user that this is the symbol for the system frequency.

The two lines afterwards shows the definition of a sinusoidal voltage source. In the position for thefrequency parameter, a symbol is used instead of the parameter value. When KREAN reads thedatafile, the symbol will be replaced by the symbol definition. In this case this means that thesource will be specified to operate at 50 Hz.

Below are two other examples of symbol definitions:

SYM @Amp 220 Amplitude of source V1

SYM @plot1 -P Plot code for component R1

Page 5- 10 5.7. Controlling the storage of results (SMI, SMA)


5.7 CONTROLLING THE STORAGE OF RESULTS (SMI, SMA)

Datafile syntax

Parameter

Tstart [sec.] [Default: 0]Start time for storage of results.

Tstop [sec.] [Default: End time for the simulation]Time at which storage of results is to end.

Description

It is possible to specify that only selected time spans of a simulation are to be stored. This isespecially useful if the computer in use has limited memory or if the simulation produces verymany results. The SMI and SMA control codes can be used to define up to ten different timeintervals in which the results are to be stored.

If SMI and SMA is not used, then the results for the whole simulation will be stored.

Examples

SMI 0SMA 0.1

SMI 0.3SMA 0.33

SMI 0.4SMA 0.5

The above lines specifies that only the results in the time intervals <0 , 0.1> , <0.3 , 0.33> and<0.4 , 0.5> are to be stored.

SMI 0.8

The above line specifies that only the results after time equal to 0.8 is to be stored.

SMI Tstart

SMA Tstop

5.8. Plotting point factor (PPF) Page 5- 11


5.8 PLOTTING POINT FACTOR (PPF)

Datafile syntax

Parameter

Nplot [Default: 1]Number of time steps to be calculated before a result is stored.

Description

Usually the program stores the results for every time-point in the simulation. The parameterNplot controls the number of time steps to be taken before a plot point is stored.

Note that breakpoints (switchings and corners of piecewise linear sources) are always stored as aplot point. Thus if Nplot is large (=1000), then only switching points will be stored.

If Nplot is set less than 1, there will be more than one plot point for each time step in thenumerical integration. An interpolation routine is used to get results in the interval betweencalculation points.

Example

PPF 2

The above line specifies that the solution at every second time step is to be stored.

PPF 0.5

The above line specifies that there should be 2 plot points for each time step in the numericalintegration.

PPF Nplot

Page 5- 12 5.9. Specify directory for sub-circuits (DIR)


5.9 SPECIFY DIRECTORY FOR SUB-CIRCUITS (DIR)

Datafile syntax

Parameter

DirName The full path-name of the directory where sub-circuits files for the KREANprogram are located.

Description

This control code must be used if sub-circuits are used in a datafile. The full path name of thedirectory of the sub-circuits must be given. Note that all sub-circuits must be located on the samedirectory. Thus the DIR control code must be used only once in each datafile.

See also description of how to use sub-circuits (chapter 10)

Example

DIR C:\KREAN\SUB\

The above line specifies that sub-circuits are located on the directory c:\krean\sub\. Note that thelast backlash must be given. The following will not work:

DIR DirName

DIR C:\KREAN\SUB

5.10. Variable declaration in sub-circuit file (VAR) Page 5- 13


5.10 VARIABLE DECLARATION IN SUB-CIRCUIT FILE (VAR)

Datafile syntax

Parameter

@LocalVar The local name of the variable inside the sub-circuit file. The name must startwith an “@”.

Comment Any comment, typical a description of the local variable.

Description

This control code can only be used inside sub-circuit files (.SUB-files). It is used to declare thelocal names of the variables in a sub-circuit. See description of the use of sub-circuits in chapter10.

Example

VAR @Resistance Serial resistance of output terminal

The above line specifies a local variable in a sub-circuit file (.SUB file). The name of the variableis @Resistance. A comment to the variable is also given.

VAR @LocalVar Comment

Page 5- 14 5.11. Including other datafiles (INC)


5.11 INCLUDING OTHER DATAFILES (INC)

Datafile syntax

Parameter

FileName The name of the file to include. A full directory specification is needed if thefile to include is not located on the default directory for the KREANprogram. The program treats both upper and lower case letters as lower case.Thus on a Unix system, only files with lower case names will be found by theprogram.

Description

The INC control code makes it possible to directly include a *.KRE file in another file.

Note that this is not a sub-circuit feature. The included file is simply copied into the *.KRE filewhere the INC control code is present. Thus, node names, component names etc. will be exactly asin the included file. If nodes with identical names are found in both the *.KRE file and theincluded file, they will simply be treated as the same node.

It is not recommended to use a nested include, i.e. the INC control codes should not be present inan included file. Nested includes works only for the special case where there is only one includecontrol command placed at the end of the files.

Examples

INC conv.kre

INC C:\kre\test.kre

The two lines above shows two examples of how to include a *.KRE files into another.

INC FileName


RELATIVE ERROR TOLERANCE (D24)

Datafile syntax

Parameter

RelTol [Default: 1.0E-8]The maximum relative acceptable local truncation error in the integration ofstate variables.

Description

The user can specify two different error tolerances for the time domain simulation. Thespecification of the absolute error tolerance (ERR) is described in the “Reference Manual” on page5-4.

It is also possible specify a relative error tolerance. This is especially recommended if there isvoltages or currents with large amplitudes ( kV, kA). A specified relative error tolerance of forinstance 0.001 may such cases speed up the simulation dramatically without serious loss ofaccuracy.

The maximum accepted error (TOL) at time t for a for a given state variable (capacitor voltage orinductor current) is given by:

TOL = AbsTol + ( Amp. * RelTol )

where AbsTol is the absolute error tolerance (specified by the ERR control code) and Amp is theamplitude of the given state variable at time t.

Read also page 5-4 and 5-5 in the Reference Manual.

Example

D24 1E-4

The above line sets the maximum relative allowed local truncation error to 1.0E-4.

D24 RelTol

This page belongs to chapter 5 of the “Krean Reference Manual”


PRESENTATION OF HARMONICS IN THE TIME DOMAIN

Illustrations of fourier results together with time domain plots are illustrated on the pages 8-10 and8-11 in the Krean reference manual. A time domain curve based on the sum of the mean value(0-th harmonic) up to the n-th harmonic can be plotted. However when the manual was written itwas not possible to plot a single harmonic in the time domain together with the fourier analysedtime domain curve. This feature has now been implemented.

It is now possible to set the “reconstruction mode” of the program. The command DRAW <n> arestill used for presentation of reconstructed curves on the screen. However, now the program willpresent sum of harmonics or single harmonics based on which reconstruction mode the user hasspecified before the DRAW <n> command is given. The command used for selection ofreconstruction mode is:

Reconstruction <n>

The parameter <n> specifies which reconstruction mode to use. The possible choices forparameter are:

0 Time domain curves will be presented together with a reconstructed curve based on thesum of the first n harmonics if a DRAW <n> command is given. This is the default.

1 Time domain curves will be presented together with a plot of only the n-th harmonic if aDRAW <n> command is given.

2 Time domain curves will be presented together with a plot of the sum of the mean value(0-th harmonic) and the n-th harmonic if a DRAW <n> command is given.

The figure below illustrates the result of the command DRAW 7 for the three differentreconstruction mode.

Mode 0

(Sum of mean value and first 7 harmonics)

Mode 1

(7th. harmonic only)

Mode 2

(Sum of mean value and 7th. harmonic)

This page belongs to chapter 8 of the “Krean Reference Manual”


VECTOR DIAGRAM

It is now possible to present the result of a fourier analysis as vectors (phasor diagrams). Thevectors is based on the fundamental rms value and the phase angle found in the fourier analysis.Thus, a fourier analysis needs to be performed (command ANALYSIS) before a phasor diagramcan be presented.

The DRAW command are used if a phasor diagram is to be presented. However, the Kreanprogram, must first be set in the appropriate “Vector mode” if a phasor diagram is to be drawn.The command for this purpose is:

Vector <n>

The parameter <n> specifies which vector mode to use. The possible choices for the parameter are:

0 Turn off vector mode (The DRAW command will give “normal” time domain plots)

1 Add vectors (The DRAW command will present vectors of all selected and analysedcurves. The second vector starts at the end of the first etc. )

2 Common start point (The DRAW command will present vectors of all selected and ana-lysed curves. All vectors starts from the same point)

The figure below illustrates the result of a DRAW command for vector mode 1 and 2.

Mode 1

(Add vectors)

Mode 2

(Common start point)


6. Models Page 6 - 1


6 MODELS

6.1 INTRODUCTION

This chapter describes the fundamental models of the KREAN simulation program. The datafilesyntax to use for each of the models is also presented. These models are available in all versions ofthe program. All other models are called “KREAN modules”. Information on the KREANmodules are described in separate memos and reports.

The definition of a component starts with a three letter code telling the program which type ofcomponent definition that follows. Each three letter code is followed by a number of parameters.Some of the components are to be described on one line, others on two or three lines.

6.1.1 Default values for parametersSome of the parameters have default values. These values need not be specified in the data-file.The default value will be used if a parameter is not specified. Alternatively an asterisk (*) can beplaced in a parameter position if the user wants the default value to be used.

6.1.2 Component namesEvery component is to be given a name. A component name can be made up by letters and/ornumbers. The maximum length of a component name is 6 characters.

An ordinary component name in a datafile should not include the special characters: !, @, £, $, #,%, ? ( ). These characters are reserved for special purposes.

6.1.3 Node namesComponents are connected to nodes. Every node in the circuit must be given a unique name. Legalnode names are combinations of letters and numbers. The maximum length of a node name is 9characters.

A node name should not include the special characters: !, @, £, $, #, %, ? ( ). These characters arereserved for special purposes.

6.1.4 Plot codes The syntax of almost all the component models include a “Plot”-parameter. This parameterspecifies the information to be stored for the component during the simulation. The informationcan typically be voltage or current.

All results after a KREAN simulation are related to components. The user may specify that noinformation is to be stored for a component or that several types of information are to be stored.

The specification of the plot-parameter should start with a “-”. If nothing is to be stored, then theplot code is simply set to “-”. The alternatives are:

Page 6 - 2 6.1. Introduction


- Nothing

-V Voltage (Volts)

-C Current (Ampere)

-A Current (Ampere)

-P Power (Watt)

-W Power (Watt)

-S State of switch (0 or 1)

Note that current and power are given two codes (both produces the same output).

Note that any combination of codes are also legal. Thus the following are also legal plot codes:

-VCP Voltage, Current and Power

-PVC Voltage, Current and Power

-PVCS Voltage, Current, Power and State of switch.

The free combination of plot codes makes it possible to plot any combination of curves for eachcomponent.

The only restriction is that there must be no spaces between the minus sign and the letters, and alsono spaces between the letters.

It is not possible to specify that a node voltage is to be stored (a measure resistor must be added ifa node voltage is of interest).

Note: The previous way to specify plot options in KREAN was to use numbers from 0 to 5. Thismethod still available. The old plot codes were:

0 Nothing

1 Voltage

2 Current

3 Voltage and current

4 Power

5 State of switch

6.2. Resistor Page 6 - 3


6.2 RESISTOR

Datafile syntax

Parameters

R [Ohm] The resistance of the resistor. To be specified in Ohms.

The specified resistance must be between 1.0E-12 and 1.0E12 Ohms. It isimportant to be aware of possible numerical round-off errors and numericalsolution problems if a very high and/or very low resistance is specified.

Model description

The ideal resistor model is linear. Fig. 6-1 defines positive current and voltage for the component.

N+ N-

RES Name N+ N- R Plot

Ires

Ures

N+ N-

R

Fig. 6-1 The figure shows the definition of positive voltage and current for the resistor model.

Page 6 - 4 6.2. Resistor


Plot

- Nothing

-V Voltage across the resistor (Ures).

-C Current through the resistor (Ires).

-P Power delivered to the resistor model (Ures multiplied by Ires).

Example

RES R1 N1 N3 10.5 -vc

The above example shows the specification of a 10.5 Ohm resistor named R1 connected from nodeN1 to N3. It is specified that both voltage and current (-vc) are to be stored for this component.

6.3. Capacitor Page 6 - 5


6.3 CAPACITOR

Datafile syntax

Parameters

C [Farad] The capacitance of the capacitor. To be specified in Farads.

The capacitance must be larger than 1.0E-12 Farads.

U0 [Volt] The initial capacitor voltage. That is, the voltage across the capacitor at thebeginning of the simulation. Be aware of the definition of positive voltage forthe capacitor. Note that the specified U0 is the initial voltage across thecapacitor only (U0), and not across the capacitor model (Ucap) (see Fig. 6-2)

Rs [Ohm] [Default: See model description below]Serial resistance for the capacitor. To be specified in Ohms. Minimumallowed value is 1.0E-12 Ohm. The default value will be used if a lowerresistance is specified or if the resistance is not specified at all.

Model description

The capacitor model is linear. The KREAN capacitor model includes a serial resistance as shownin Fig. 6-2. The resistance is included in the model in order to allow arbitrarily connection ofcomponents. The use of the resistance normally does not cause a problem because real capacitorsdo not have zero series resistance.

Note that it is not allowed to specify zero resistance for the capacitor model. If the resistance is setto zero (or not specified) then a default value will be used instead. The default value of the serialresistance is selected such that the time constant of the RC-circuit becomes equal to 1.0E-9seconds. This means that if no resistance is specified then the resistance as defined by thefollowing equation will be used:

(6-1)

N+ N-

CAP Name N+ N- C Plot U0 Rs

RsτC---

19–×10

C------------------= =

Page 6 - 6 6.3. Capacitor


Note: If the above equation results in a default resistance less than 1.0E-6 Ohm, then the serialresistance is by default set to 1.0E-6 Ohm.

Plot

- Nothing

-V Voltage across the capacitor (Ucap).

-C Current through the capacitor (Icap).

-P Instantaneous power delivered to the capacitor model (Ucap multiplied by Icap).

Comments

In many cases the resistance of the capacitor is not known, or the effect of the resistance is notwanted. In such cases the resistance must be set low enough to be negligible. However it is notrecommended to use lower values than necessary.

A low resistance results in a small time constant for the RC-branch. The applied numericalmethods introduce very little damping and small time constants are followed accurately. Theconsequence of small time constants is therefore small time steps in case of transients in thevoltage across the capacitor.

The conclusion is that if a negligible serial resistance is wanted, then it should be selected such thatthe time constant is small compared to the phenomena of interest.

Example

CAP C3 n12 ny 1.0E-6 -V 10.9 0.001

The above example shows the specification of a 1.0 microfarad capacitor named C3. It is to beconnected from node N12 to NY. The initial voltage across the capacitor is 10.9 Volt. It isspecified that the voltage across the capacitor model is to be stored during the simulation. Finally,a serial resistance of 0.001 Ohm is specified for C3.

Icap

Ucap

N+ N-Rs

C

U0

Fig. 6-2 The figure shows the KREAN capacitor model. A serial resistance is part of thecapacitor model.

6.4. Inductor Page 6 - 7


6.4 INDUCTOR

Datafile syntax

Parameters

L [Henry] The inductance of the inductor. To be specified in Henry. The specifiedinductance must be larger than 1.0E-12 Henry.

I0 [Ampere] The initial inductor current. That is, the current through the inductor at thebeginning of the simulation. Be aware of the definition of positive current forthe inductor. Note that the specified I0 is the initial current through theinductor (I0) and not the initial current through the inductor model (Iind) (seeFig. 6-3)

Rp [Ohm] [Default: See model description below]Parallel resistance in the inductor model. To be specified in Ohms. Maximumallowed value is 1.0E12 Ohm. If a the resistance is not specified then thedefault value will be used (see below).

Model description

The inductor model is linear. The KREAN inductor model includes a parallel resistance as shownin Fig. 6-3. The resistance is included in the model in order to allow arbitrarily connection ofcomponents. This is physically correct as an ideal inductor with zero parallel resistance does notexist.

Note that it is not allowed to specify an infinite resistance in the inductor model. The default valuewill be used if the resistance is set to zero or if it is not specified. The default value of the parallelresistance is selected such that the time constant of the RL-circuit becomes equal to 1.0E-9seconds. This means that if no resistance is specified then the resistance as defined by thefollowing equation will be used:

N+ N-

IND Name N+ N- L Plot I0 Rp

Page 6 - 8 6.4. Inductor


(6-2)

Note: If the above equation results in a default resistance larger than 1.0E6 Ohm, then the parallelresistance is by default set to 1.0E6 Ohm.

Plot

- Nothing

-V Voltage across the inductor (Uind).

-C Current through the inductor model (Iind).

-P Instantaneous power delivered to the inductor model (Uind multiplied by Iind).

Comments

In many cases the parallel resistance of the inductor is not known, or the effect of the resistance isnot wanted. In such cases the resistance should be set high enough to be negligible. However it isnot recommended to use values higher than necessary. High resistance results in a small timeconstant for the RL-branch. The applied numerical methods introduce very little damping andsmall time constants are followed accurately. The consequence of small time constants is thereforesmall time steps in case of transients in the current through the inductor.

The conclusion is that if a negligible parallel resistance is wanted, then it should be selected suchthat the time constant (equals L divided by Rp) is small compared to the phenomena of interest andon the same time, not smaller than necessary.

RpLτ---

L

19–×10

------------------= =

Iind

Uind

N+ N-

Rp

L

I0

Fig. 6-3 The figure shows the KREAN inductor model. A parallel resistor is part of the inductormodel.

6.4. Inductor Page 6 - 9


Example

IND Ind4 n12 ny 1.0E-3 - 50 1E4

The example shows the specification of a 1.0 mH inductor named Ind4. It is to be connected fromnode N12 to NY. It is specified that no plot information is to be stored (plot code “-”). It is alsospecified that the current through the inductor at the beginning of the simulation is 50 Amp.Finally, a parallel resistance of 10000 Ohm is specified for Ind4.

Page 6 - 10 6.5. Current source


6.5 CURRENT SOURCE

Datafile syntax type 1 : General piecewise linear source

Datafile syntax type 2: Sinusoidal source

Parameters

Period [sec] The period time of the defined piecewise linear source function. The periodtime must be greater than 1E-9 seconds.

Rp [Ohm] [Default: 10000 Ohm]The parallel resistance of the source. The specified value must be larger than1.0E-12 Ohm. A default value of 10kOhm will be used if it is not specified.

Phi [degree] [Default: 0°]Phase shift of the specified source function. To be specified in degrees (+/-360°). If set to zero or omitted the source function will be exactly asspecified, without any shift. See section 6.17 on page 46 for description ofhow to define piecewise linear source functions.

T1 T2 ... The specified time points in the piecewise linear function. The time pointsare relative values inside the defined period. The first point must be equal tozero and the last one must equal 1.0. See section 6.17 on page 46 fordescription of how to define piecewise linear source functions.

N- N+

CNT Name N- N+ Plot 1 Period Rp Phi0 T2 T3 ... Tn-1 1.0I0 I2 I3 ... In-1 In

CNT Name N- N+ Plot 2 Rp Irms Freq Phase

6.5. Current source Page 6 - 11


I0 I1 ...[A] The source values corresponding to the specified relative time points. To bespecified in amperes. See section 6.6 on page 13 for description of how todefine piecewise linear source functions.

Irms [Arms] The root mean squared (rms) value of a sinusoidal source. To be specified inArms.

Freq [Hz] The frequency (Hertz) of sinusoidal sources. The frequency must be greaterthan 1E-9 Hz.

Phase [deg] The phase of the sinusoidal source. To be specified in degrees (+/- 360°).

Model description

There are two types of current sources. The numbers 1 and 2 in the first line of the datafile syntaxtells KREAN whether the source is of type 1 or 2. Type 1 is general piecewise linear and type 2 issinusoidal current sources.

Fig. 6-4 presents the KREAN current source model. The same model is valid for both piecewiselinear and for sinusoidal sources.

For general piecewise linear sources, the user specifies Isource by pairs of time and current values.Linear interpolation is used between the defined timepoints. The time function is to be specified ina unified interval from 0 to 1.0. The specified time function is repeated with a period specified bythe parameter Period. Thus, in order to change the frequency of a piecewise linear source, oneneed only to change the Period parameter. The parameter Phi can be used to shift the sourcefunction in the time domain.

See section 6.17 on page 46 for more detailed description of how to define piecewise linear sourcefunctions.

Note that a constant dc current sources is defined by a piecewise linear source. Thus, constant dccurrent sources are to be specified as current sources of type 1.

For sinusoidal sources the user specifies the rms-value, the frequency and the phase shift of thesinusoidal current Isource. The following equation illustrates the use of the parameters:

(6-3)

Plot

- Nothing

-V Voltage across the current source (Ucur).

-C Current through the current source model (Icur).

-P Instantaneous power delivered from the current source model (Ucur multiplied by Icur).

Isource 2 Irms⋅( ) 2 π Freq t⋅ ⋅ ⋅Phase 2 π⋅ ⋅

360---------------------------------+

sin=

Page 6 - 12 6.5. Current source


Example: Square-wave current source

CNT I2 n4 n6 -p 1 0.02 10000 00 0.5 0.5 1.0 10 10 -10 -10

The above three lines specifies a piecewise linear source named I2 connected from node n4 to n6.It is specified that the power delivered from the current source model is to be stored during thesimulation. The period time of the source function is 0.02 seconds (50 Hz). The specified sourcefunction has a 50% duty-cycle square wave with an amplitude of +/- 10 Amp. The parallel resistorof the source model is set to 10kOhm. The phase shift of the source function is set to zero.

Example: Constant dc-current source

CNT I2 n4 n6 -p 1 1.0 10000 00 1.0 10 10

The above shows the specification of a similar source, except for the source function which in thiscase is a constant dc-current of 10 Amp. Note that in this case it seems to have no meaning todefine a period time. However a period time must always be given. It is recommended to use a“large” period time for constant sources because the simulation program places at least twosimulation points in every period.

Example: Sinusoidal current source

CNT I2 n4 n6 -p 2 10E3220 50 -20

The above lines shows a specification of a 220 Vrms, 50 Hz sinusoidal current source named I2connected from node n4 to n6. The instantaneous power delivered by the source is to be stored.The parallel resistance is set to 10kOhm. The phase shift of the sinusoidal is -20°.

Icur

Ucur

N- N+

Rp

Isource

Fig. 6-4 The figure shows the KREAN current source model. A parallel resistor is part of thecurrent source model. The current specified in the datafile is the current Isource.

6.6. Voltage source Page 6 - 13


6.6 VOLTAGE SOURCE

Datafile syntax type 1 : General piecewise linear source

Datafile syntax type 2: Sinusoidal source

Parameters

Period [sec] The period time of the defined piecewise linear source function. The periodtime must be greater than 1.0E-9 seconds.

Rs [Ohm] [default: 1E-3 Ohm] The serial resistance of the source. The specified value must be greater then1.0E-12 Ohm. A default value of 1 mΩ will be used if Rs is not specified.

Phi [degree] [default: 0°] Phase shift of the specified source function. To be specified in degrees (+/-360°). If set to zero or omitted, the source function will be exactly asspecified, without any shift. See section 6.17 on page 46 for description ofhow to define piecewise linear source functions.

T1 T2 ... The specified time points in the piecewise linear function. The time pointsare relative values inside the defined period. The first point must be equal tozero and the last one must equal 1.0. See section 6.17 on page 46 fordescription of how to define piecewise linear source functions.

N- N+

VTG Name N- N+ Plot 1 Period Rs Phi0 T2 T3 ... Tn-1 1.0U0 U2 U3 ... Un-1 Un

VTG Name N- N+ Plot 2 Rs Urms Freq Phase

Page 6 - 14 6.6. Voltage source


U0 U1 ...[V] The source values corresponding to the specified relative time points. To bespecified in volts. See section 6.17 on page 46 for description of how todefine piecewise linear source functions.

Urms [Vrms] The root mean squared (rms) value of a sinusoidal source. To be specified inVrms.

Freq [Hz] The frequency (Herz) of sinusoidal sources.

Phase [deg] The phase angle of the sinusoidal source. To be specified in degrees (+/-360°).

Model description

There are two types of voltage sources. The numbers 1 and 2 in the first line of the datafile syntaxtells KREAN whether the source is of type 1 or 2. Type 1 is general piecewise linear and type 2 issinusoidal voltage sources.

Fig. 6-5 presents the KREAN voltage source model. The same model is valid for both piecewiselinear and for sinusoidal sources.

For general piecewise linear sources, the user specifies Usource by pairs of time and voltagevalues. Linear interpolation is used between the defined timepoints. The time function is to bespecified in a unified interval from 0 to 1.0. The specified time function is repeated with a periodspecified by the parameter Period. Thus, in order to change the frequency of a piecewise linearsource, one need only to change the Period parameter. The parameter Phi can be used to shiftthe source function in the time domain.

See section 6.17 on page 46 for more detailed description of how to define piecewise linear sourcefunctions.

Note that a constant dc voltage source is defined by a piecewise linear source. Thus, constant dcvoltage sources are to be specified as voltage sources of type 1.

For sinusoidal sources the user specifies the rms-value, the frequency and the phase shift of thesinusoidal voltage Usource. The following equation illustrates the use of the parameters:

(6-4)

Plot

- Nothing

-V Voltage across the voltage source model (Uvol).

-C Current through the voltage source model (Ivol).

-P Instantaneous power delivered from the voltage source model (Uvol multiplied by Ivol).

Usource 2 Urms⋅( ) 2 π Freq t⋅ ⋅ ⋅Phase 2 π⋅ ⋅

360---------------------------------+

sin=

6.6. Voltage source Page 6 - 15


Example: Ramp voltage

VTG U n4 n6 -vcp 1 0.02 1E-3 300 1.0 0 10

The above three lines specifies a piecewise linear source named U connected from node n4 to n6.It is specified that the power, current and voltage for the source model is to be stored during thesimulation. The period time of the source function is 0.02 seconds. The specified source functionis a ramp voltage of 10 Volt. The serial resistor of the source model is set to 1E-3 Ohm. The phaseshift of the source function is set to 30 degree.

Example: Constant dc-voltage source

VTG U n4 n6 -vcp 1 1.0 1E-3 00 1.0 -10 -10

The above shows the specification of a constant dc voltage source. It is identical to the rampvoltage source except for the source function which in this case is a constant dc-voltage of -10Volt. Note that in this case it seems to have no meaning to define a period time. However a periodtime must always be given. It is recommended to use a “large” period time (here: 1sec.) forconstant sources because the simulation program places a simulation point at the end of everyperiod. The phase shift have no effect on constant source functions, thus it is set to zero for thissource.

Ivol

Uvol

N- N+

RsUsource

Fig. 6-5 The figure shows the KREAN voltage source model. A serial resistor is part of thevoltage source model. The voltage specified in the datafile is the voltage Usource.

Page 6 - 16 6.6. Voltage source


Example: Sinusoidal voltage source

VTG U2 n4 n6 -p 2 1E-3220 50 0

The above lines shows a specification of a 220 Vrms, 50 Hz sinusoidal voltage source named U2connected from node n4 to n6. Plot of the instantaneous power is to be stored. The serial resistanceis set to 1mΩ. The phase shift of the sinusoidal is set to 0° (which gives a sinusoidal starting atzero with a positive derivative).

6.7. Controlled sources Page 6 - 17


6.7 CONTROLLED SOURCES

Type 1 : Voltage controlled voltage source

Type 2: Voltage controlled current source

Type 3: Current controlled voltage source

Type 4: Current controlled current source

NS+

NS-

NS+

NS-

NS+

NS-

NC+

Type 1

NC-

NS+

NS-

NC+

NC-

NC+

NC-

NC+

NC-

Type 2 Type 3 Type 4





Page 6 - 18 6.7. Controlled sources


Parameters

Gain The gain between the control variable (current or voltage) and the sourcevariable (current or voltage). Zero, positive and negative gain can bespecified.

Rs [Ohm] [default: 1E-3 Ohm] The serial resistance of voltage sources. The specified value must be largerthan 1.0E-12 Ohm. A default value of 1 mΩ will be used if it is not specified.

Rp [Ohm] [default: 1E4 Ohm]The parallel resistance of current sources. The specified value must be largerthan 1.0E-12 Ohm. A default value of 10kΩ will be used if it is not specified.

Model description

There are four types of controlled sources. The numbers 1, 2, 3 and 4 in the datafile syntax tellsKREAN if the source is of type 1, 2, 3 or 4. All four types are linear and have ideal controlterminals.

Controlled sources of type 1 and 2 are controlled by the voltage applied between the controlterminals. The impedance between the control terminals are infinite. Thus no current flows intothe control terminals of the voltage controlled sources.

Controlled sources of type 3 and 4 are controlled by the current flowing through the controlterminals. The control terminals are ideal. Thus there is zero voltage across the control terminalsof current controlled sources.

The voltage sources are modelled with a serial resistor and the current sources with a parallelresistor as shown in Fig. 6-6.

The source output equals the control variable multiplied by the gain parameter. The equationswhich defines the models are shown below.

Type 1: Voltage controlled voltage source:

(6-5)

Type 2: Voltage controlled current source:

(6-6)

Type 3: Current controlled voltage source:

(6-7)

Type 4: Current controlled current source:

(6-8)

Usource Gain Ucon⋅=

Isource Gain Ucon⋅=

Usource Gain Icon⋅=

Isource Gain Icon⋅=

6.7. Controlled sources Page 6 - 19


Ivol

UvolUsource

Fig. 6-6 Controlled sources are modelled as shown in this figure. Parallel resistors to currentsources and serial resistance to voltage sources are part of the models. The controlterminals are ideal. This means zero current into voltage control terminals and zerovoltage between current control terminals.

Note that it is Usource and Isource that are equal to the ratio multiplied by the controlvariable and not Uvol and Icur.

UconType 1

Icur

UcurIsourceUconType 2

Rs

Rp

Ivol

UvolUsource

IconType 3

Rs

Icur

UcurIsourceType 4 Rp

Icon

Page 6 - 20 6.7. Controlled sources


Plot

- Nothing

-V Voltage across the controlled source model (Uvol and Ucur) and the control voltage Ucon.

-C Current through the controlled source model (Ivol and Icur) and the control current Icon.

-P Instantaneous power delivered from the controlled source model (Uvol multiplied by Ivol orUcur multiplied by Icur ).

Note that control current can only be plotted for current controlled sources and that control voltageonly can be plotted for voltage controlled sources. Only the power delivered from the source canbe plotted. The control terminal power will always be zero due to ideal control terminals.

Example: Voltage controlled voltage source

CTS Vol1 n1 n2 n5 n4 1 3.33 -v 0.001

The above line specifies a voltage controlled voltage source (type 1). The control voltage is thevoltage between node n1 and n2. The source is connected from node n5 to n4. The gain of thesource is 3.33 and a serial resistance of 0.001 Ohm is specified for the source. Both the controlvoltage and the voltage across the model are to be stored during the simulation.

Example: Current controlled current source

CTS Cur1 n1 n2 n5 n4 4 5 -v 10000

The above line specifies a current controlled current source (type 4). The control current is thecurrent flowing in the control terminal n1 and out of terminal n2. The source is connected fromnode n5 to n4. The gain of the source is 5 and a parallel resistance of 10000 Ohm is specified forthe source. The voltage across the model are to be stored during the simulation.

6.8. Transformer Page 6 - 21


6.8 TRANSFORMER

Datafile syntax

Parameters

np The transformation ratio. The primary voltage equals np times the secondaryvoltage. The parameter can be given any non-zero value.

Rserial [Ohm] [default: 1E-4] The serial resistance of the primary winding. The specified value must bebetween 1.0E-12 and 1.0E12 Ohm. A default value of 1 mΩ will be used if itis not specified.

Rparallel [Ohm][default: 1E4]The parallel resistance of the primary winding. A default value of 10kΩ willbe used if it is not specified.

Model description

The KREAN transformer model consists of a linear ideal, non-saturable transformer and tworesistors. The model is shown in Fig. 6-7. Note that the magnetizing current is not modelled. Thusthe transformer model also transforms dc-voltage and current. If the magnetizing current is to bemodelled, then an inductor must be added in parallel to either the primary or the secondary side ofthe transformer.

The equations which describes the behaviour of the transformer model are as follows:

(6-9)

NP+ np:1

NP- NS-

NS+

TRF Name NP+ NP- NS+ NS- np Plot Rparallel Rserial

U1 np Usec⋅=

Page 6 - 22 6.8. Transformer


(6-10)

Se Fig. 6-7 for the definition of U and I. From the figure it can be seen that two resistors are part ofthe transformer model. These are added in order to ensure that any arbitrarily connection ofmodels gives non-singular (solvable) equation systems. They are part of the model and can not beset to zero or infinite. They can be selected such that they become negligible. However, in order toavoid possible numerical problems, the serial resistance should not be set lower than necessary.

Plot

- Nothing

-V Voltage across the primary (Uprim) and secondary (Usec) side of the transformer model.

-C Current into the primary (Iprim) and current out of the secondary (Isec) side of the trans-former model.

-P Instantaneous power delivered into the primary side (Uprim multiplied by Iprim)

Example: Transformer

TRF Trafo N5 N6 N9 N8 10 -v 10E4 1E-4

The above line specifies a transformer with a ratio of 10. The primary side is connected to node N5and N6, the secondary to node N9 and N8. The primary and secondary voltage is to be storedduring the simulation. The primary parallel resistor is set to 10E4 Ohm and the primary serialresistance to 1E-4 Ohm.

Isec np I1⋅=

Fig. 6-7 The transformer model. Note that two resistors are part of the model. Note also that themagnetizing current is not modelled.

UsecRparallel

np:1Rserial

Uprim

Iprim Isec

U1

I1

6.9. Diode Page 6 - 23


6.9 DIODE

Datafile syntax

Parameters

Init [0/1] Initial state of the diode. This parameter specifies if the diode is to be in theconducting or non-conducting state at the beginning of the simulation. Init=0means non-conducting and Init=1 means conducting. The KREAN programwill change the setting if it opposes the switching criteria for the diode.

Ron [Ohm] [default: 0.01 Ohm]The on-state resistance of the diode. To be specified in Ohms. The specifiedresistance must be larger than 1.0E-12 Ohms.

Be aware of possible numerical round-off errors and numerical solutionproblems if very high and/or very low resistance is specified. It is notrecommended to use resistance much lower than 1.0E-4 Ohm.

Roff [Ohm] [default: 10 000 Ohm]The off-state resistance of the diode. To be specified in Ohms.

Irr [A] [default: 1.0E-4 A]This parameter specifies the peak reverse current at which the diode turnsoff. The program uses the unsigned value of the specified. Thus, a specifiedsign of Irr is ignored. The model have snap-off with no soft recovery. Seethe model description below.

Model description

The KREAN diode model is linear. In the on-state the diode is modelled as a low resistance and inthe off-state as a high resistance. The switching interval is not modelled. The model switches fromone state to another instantaneously.

The criteria for the turn on of the diode is that the voltage across it becomes larger than Uturn-on.The default value of Uturn-on is equal to 0.001 Volt. This value can only be changed by a defaultspecification (D23) as described in chapter 14.

N+ N-

DIO D1 N+ N- Plot Init Ron Roff Irr

Page 6 - 24 6.9. Diode


The criteria for turn-off is that the current Idio becomes equal to -Irr. At the moment thecurrent becomes equal to -Irr the program switches from the on-state model to the off-statemodel. A typical diode current is shown in Fig. 6-9.

Plot

- Nothing

-V Voltage across the diode (Udio).

-C Current through the diode (Idio).

-P Power dissipated in the diode model (Udio multiplied by Idio).

-s State of conduction for the diode. This plot is a function which is equal to 1 if the diode is inthe conducting state and equal to 0 if the diode is in the non-conducting state.

Idio

Udio

N+ N-

Ron

Fig. 6-8 The figure shows the KREAN diode model. The upper model is used in the on-stateand the lower in the off-state. Only these two models are used because the switchinginterval is not modelled.

Diode in on-state

Idio

Udio

N+ N-

Roff

Diode in off-state

Fig. 6-9 A typical diode current. The diode turns off at the time the current reaches -Irr.

Idiode

Time-Irr

6.9. Diode Page 6 - 25


Example

DIO Diode1 N3 N6 -s 0 1E-3 1E4 0.001

The above example shows the specification of a diode named Diode1 connected from node N3 toN6. It is specified that the state of the switch (-s) is to be stored during the simulation. The on-stateresistance is set to 1E-3 Ohm, the off-state resistance to 10kOhm and the snap-off reverse recoverycurrent to 0.001 Ampere.

Page 6 - 26 6.10. Time controlled bi-directional switch


6.10 TIME CONTROLLED BI-DIRECTIONAL SWITCH

Datafile syntax

Parameters

Period [sec] The period time of the defined turn on/off signal (trigger signal). The periodtime must be greater than 1E-9 seconds.

Phi [degree] Phase shift of the specified turn on/off signal. To be specified in degrees (+/-360°). If set to zero or omitted the turn on/off signal will be exactly asspecified, without any shift. A positive Phi shifts the signal to the left, anegative shift the signal to the right. See section 6.18 on page 48 fordescription of how to define trigger signals.

Ron [Ohm] [default: 0.01 Ohm]The on-state resistance of the switch. To be specified in Ohms. The specifiedresistance must be larger than 1.0E-12 Ohms.

Be aware of possible numerical round-off errors and numerical solutionproblems if a very high and/or very low resistance is specified.

Roff [Ohm] [default: 10 000 Ohm]The off-state resistance of the switch. To be specified in Ohms.

T1 T2 ... The specified time points in the trigger signal. The time points are relativevalues inside the defined Period. The first point must be equal to 0.0 andthe last one must equal 1.0. See section 6.18 on page 48 for description ofhow to define trigger signals.

S0 S1...[0/1] The trigger signal corresponding to the specified time points. Two values areallowed for the trigger signal:0 Off1 OnSee section 6.18 on page 48 for more on of how to define trigger signals.

N+ N-

SW1 Name N+ N- Plot Period Ron Roff Phi0 T2 T3 ... 1.0S0 S2 S3 ... Sn

6.10. Time controlled bi-directional switch Page 6 - 27


Model description

The KREAN bi-directional switch model has two distinct states either on or off (conducting andnon-conducting). The bi-directional switch model can conduct current in both directions. The stateof conduction for the switch is defined by the trigger signal pairs (T,S) specified in the data-file.

In the off-state the switch is modelled as a resistor with resistance Roff and in the on-state as aresistor with resistance Ron (see Fig. 6-10). The switching interval is not modelled. Thebi-directional switch model switches from one state to another instantaneously.

The trigger signal pairs (T,S) control the time instants for turn on and off of the switch. The timevariable T is specified in a interval from 0 to 1.0. The specified time function is repeated with aperiod given by the parameter Period. Thus, in order to change the frequency of a trigger signal,one need only to change the Period parameter. The parameter Phi can be used to time shift thesource function.

Note that the turn on and off of the switch is dependent only on time. The current through and thevoltage across the switch does not influence on the time instants for turn on and off.

Plot

- Nothing

-V Voltage across the switch (Uswitch).

-C Current through the switch (Iswitch).

-P Power dissipated in the bi-directional switch model (Uswitch multiplied by Iswitch).

-s State of conduction for the switch. This plot is a function which is equal to 1 if the switch isin the conducting state and equal to 0 if the switch is in the non-conducting state.

Iswitch

Uswitch

N+ N-

Ron

Fig. 6-10 The KREAN bi-directional switch model. The upper model is used in the on-state andthe lower in the off-state. Only these two models are used because the switchinginterval is not modelled.

Bi-directional switchin on-state

Iswitch

Uswitch

N+ N-

Roff

Bi-directional switch in off-state

Page 6 - 28 6.10. Time controlled bi-directional switch


Example

SW1 Switch2 N1 N2 -v 0.02 1E-3 1E4 00 0.3 0.3 1.01 1 0 0

The above lines define a bi-directional switch named Switch2 connected from node N1 to N2.Only the voltage across the switch is to be stored during the simulation (-v). The on-stateresistance is set to 1E-3 Ohm and the off-state to 1E4 Ohm.

The period of the trigger signal is set to 0.02 s and the phase shift Phi is set to 0. Thus the triggersignal will repeat every 0.02 seconds. The trigger signal is defined such that the switch will be onfor the first 30% of the period and off for the rest. This implies that the switch will turn on at timeinstants:

0 0.02 0.04 0.06 ...

This switch will turn off at the time instants:

0.006 0.026 0.046 0.066 ...

6.11. Voltage controlled bi-directional switch Page 6 - 29


6.11 VOLTAGE CONTROLLED BI-DIRECTIONAL SWITCH

Datafile syntax

Parameters

Init [0/1] The Init parameter selects if the switch is in the on or off state at thebeginning of the simulation. A “0” means off and a “1” means on. TheKREAN program automatically corrects the specification if it opposes theswitching criteria. The hysteresis in the control of the switch makes itnecessary to specify initial state of the switch.

Uc,on [V] [default: +0.001 Volt]The control voltage level at which the switch is to be turned on. The switch isturned on when the control voltage rises above Uc,on. There should alwaysbe some hysteresis in the control of the switch. Thus the specified Uc,onmust be at least 1.0E-4 Volts greater than Uc,off. The program willautomatically modify Uc,on and Uc,off if the difference is less. (See alsoFig. 6-11)

Uc,off [V] [default: 0.0 Volt]The control voltage level at which the switch is to be turned off. The switchis turned off when the control voltage falls below Uc,off. See alsocomment for Uc,on.

Ron [Ohm] [default: 0.01 Ohm]The on-state resistance of the switch. To be specified in Ohms. The specifiedresistance must be larger than 1.0E-12 Ohms.

Be aware of possible numerical round-off errors and numerical solutionproblems if a very high and/or a very low resistance is specified.


N+ N-

NC+ NC-

SW2 Name N+ N- NC+ NC- Plot Init Uc,off Uc,on Ron Roff

Page 6 - 30 6.11. Voltage controlled bi-directional switch


Model description

The KREAN voltage controlled bi-directional switch model has two distinct states either on or off(conducting and non-conducting). The voltage controlled bi-directional switch model conductscurrent in both directions. The state of conduction for the switch is controlled by the voltage Uconbetween the control terminals. If the control voltage goes above Uc,on then the switch is turned on.If the control voltage goes below Uc,off then the switch turns off. If the control voltage is betweenUc,off and Uc,on then the switch keeps its state (hysteresis). This is illustrated in Fig. 6-11.

In the off-state the switch is modelled as a resistor with resistance Roff and in the on-state as aresistor with resistance Ron (see Fig. 6-12). The switching interval is not modelled. The voltagecontrolled bi-directional switch model switches from one state to another instantaneous.

The control terminals are ideal. Thus, no current flows into the control terminals.

Note that the turn on and off of the switch only depends on the control voltage and due to thehysteresis also on the past values of the control voltage. The current through and the voltage acrossthe switch does not influence on the time instants for turn on and off.

Plot

- Nothing

-V Voltage across the switch (Uswitch) and control voltage for the switch (Ucon).

-C Current through the switch (Iswitch).

-P Power dissipated in the bi-directional switch model (Uswitch multiplied by Iswitch).

-s State of conduction for the switch. This plot is a function which is equal to 1 if the switch isin the conducting state and equal to 0 if the switch is in the non-conducting state.

Ucon

State [0/1]

1

Uc,off Uc,on

Fig. 6-11 The figure illustrates the relationship between the control voltage levels and the state ofthe switch. As can be seen, there is a hysteresis in the switch control. Turn-on onlyhappens if the control voltage goes above Uc,on while turn-off only happens if thecontrol voltage goes below Uc,off

6.11. Voltage controlled bi-directional switch Page 6 - 31


Example

SW2 Switch N1 N2 NC1 NC2 -v 0 -2 3 1E-3 1E4

The above line defines a voltage controlled bi-directional switch named Switch connected fromnode N1 to N2. The control voltage is the voltage between the nodes NC1 and NC2. The switch isinitially off. The voltage across the switch and the control voltage is to be stored during thesimulation (-v). The switch is to turn off at a control voltage equal to -2 Volt and on at a controlvoltage equal to 3 Volt. The on-state resistance is set to 1E-3 Ohm and the off-state to 1E4 Ohm.

Iswitch

Uswitch

RonVoltage controlled bi-directional switchin on-state

Voltage controlled bi-directional switch in off-state

Ucon

Iswitch

Uswitch

Roff

Ucon

Fig. 6-12 The KREAN voltage controlled bi-directional switch model. The upper model is usedin the on-state and the lower in the off-state. Only these two models are used becausethe switching interval is not modelled. The control voltage terminals are ideal. Nocurrent flows into these terminals.

Page 6 - 32 6.12. Time controlled uni-directional switch and Time controlled thyristor


6.12 TIME CONTROLLED UNI-DIRECTIONAL SWITCHAND TIME CONTROLLED THYRISTOR

Datafile syntax

Parameters

Init [0/1] Initial state of conduction for the switch/thyristor. The switch/thyristor willbe initially in the non-conducting state if the Init parameter is set to zero. IfInit is set to one, then the thyristor will be initially in the conducting state.The KREAN program will change the initial setting if it opposes theswitching criteria for the thyristor.

Period [sec] The period time of the defined gate signal. The period time must be greaterthan 1E-9 seconds.

Phi [degree] [Default: 0°]Phase shift of the specified gate signal. To be specified in degrees (+/- 360°).If set to zero or omitted the gate signal will be exactly as specified, withoutany shift. A positive Phi shifts the signal to the left, a negative shift thesignal to the right. See section 6.18 on page 48 for description of how todefine trigger signals.

Ron [Ohm] [default: 0.01 Ohm]The on-state resistance of the switch. To be specified in Ohms. The specifiedresistance must be between 1.0E-12 and 1.0E12 Ohms. A lower and higherspecified resistance will automatically be set to the minimum and maximumlimits respectively.

Be aware of possible numerical round-off errors and numerical solutionproblems if very high and/or very low resistance is specified.


N+ N- N+ N-

TH1 Name N+ N- Plot Init Period Ron Roff Irr Phi0 T2 T3 ... 1.0S0 S2 S3 ... Sn

6.12. Time controlled uni-directional switch and Time controlled thyristor Page 6 - 33


Irr [A] [default: 1.0E-4 A]This parameter specifies the peak reverse recovery current at which thethyristor turns off. The program uses the unsigned value of the one specifiedin the datafile. The model has a snap-off with no soft recovery. See Fig. 6-9in the description of the diode model for a definition of Irr.

T1 T2 ... The specified time points in the gate signal. The time points are relativevalues inside the defined period. The first point must be equal to 0.0 andthe last one must equal 1.0. See section 6.18 on page 48 for description ofhow to define trigger signals.

S0 S1... The gate signal corresponding to the specified time points. Three values areallowed for the trigger signal:0 No gate signal1 Turn on-1 Turn off (Gate turn off)See section 6.18 on page 48 for more on of how to define trigger signals.

Model description

The KREAN thyristor model has two distinct states, on and off (conducting and non-conducting).The thyristor model can be used to model any uni-directional switch which conducts current inonly one direction. The state of conduction for the switch is defined by the trigger signal pairs(T,S) specified in the data-file.

The thyristor model can be operated as a ordinary thyristor or as a gate turn-off thyristor (GTO).

For a ordinary thyristor only the turn-on of the thyristor can be controlled by the gate signal. Thegate signal (S0, S1 ...) to use in such cases are 0 for no gate signal and 1 for gate signal.

For a GTO-operated thyristor both the turn-on and turn-off can be controlled. The gate signal (S0,S1 ...) to use in such cases are 0 for no gate signal, 1 for turn-on gate signal and -1 for gateturn-off signal.

In the off-state the thyristor is modelled as a resistor with resistance Roff and in the on-state as aresistor with resistance Ron (see Fig. 6-10). The switching interval is not modelled. The thyristormodel switches from one state to another instantaneously.

The gate signal pairs (T,S) control the time instants for turn on and off of the thyristor. The timevariable T is specified in a unified interval from 0 to 1.0. The specified time function is repeatedwith a period given by the parameter Period. Thus, in order to change the frequency of a gatesignal, one need only to change the Period parameter. The parameter Phi can be used to shiftthe gate trigger function in the time domain.

Note that the actual state of conduction depends not only on the gate trigger signal but also on theapplied voltage across the thyristor. A positive voltage is needed in order to turn the thyristor on.

The criteria for turn on of the thyristor is that the voltage across the thyristor is larger than Uturn-onand a present gate signal for turn-on (S=1). Uturn-on is equal to 0.001 Volt by default .

There are two alternative criteria for turn-off. The thyristor turns off if the current through thethyristor becomes less than Irr or the thyristor turns off if a gate turn-off signal is given (S=-1)

Page 6 - 34 6.12. Time controlled uni-directional switch and Time controlled thyristor


Plot

- Nothing

-V Voltage across the thyristor (Uswitch).

-C Current through the thyristor (Iswitch).

-P Power dissipated in the thyristor model (Uswitch multiplied by Iswitch).

-s State of conduction for the thyristor. This plot is a function which is equal to 1 if the thyris-tor is in the conducting state and equal to 0 if the thyristor is in the non-conducting state.

Iswitch

Uswitch

N+ N-

Ron

Fig. 6-13 The KREAN thyristor model. The upper model is used in the on-state and the lower inthe off-state. Only these two models are used because the switching interval is notmodelled.

Thyristor in on-state

Iswitch

Uswitch

N+ N-

Roff

Thyristor in off-state

6.12. Time controlled uni-directional switch and Time controlled thyristor Page 6 - 35


Example

TH1 Thyr2 N1 N2 -v 1 0.02 1E-3 1E4 1E-4 00 0.3 0.3 0.5 0.5 1.00 0 1 1 -1 -1

The above lines defines a thyristor named Thyr2 connected from node N1 to N2. Only thevoltage across the thyristor is to be stored during the simulation (-v). The on-state resistance is setto 1E-3 Ohm and the off-state to 1E4 Ohm.

The period of the trigger signal is set to 0.02 s and the phase shift Phi is set to 0. Therefore thegate signal will repeat every 0.02 seconds. The thyristor is specified to be initially in the on-state(Init=1). The peak reverse recovery current is set to 1.0E-4 A.

The gate signal is defined such that the thyristor is given no gate signal for the first 30% of theperiod (S=0). A turn-on gate signal is then given for the next 20% of the period (S=1). For the last50% of the period a gate turn-off signal is applied (S=-1)

Page 6 - 36 6.13. Voltage controlled uni-directional switch and Voltage controlled thyristor


6.13 VOLTAGE CONTROLLED UNI-DIRECTIONAL SWITCHAND VOLTAGE CONTROLLED THYRISTOR

Datafile syntax

Parameters

Init [0/1] The Init parameter specifies if the thyristor is in the on or off state at thebeginning of the simulation. A “0” means off and a “1” means on. TheKREAN program automatically corrects the specification if it opposes theswitching criteria.

Uc,on [V] [default: +0.001 Volt]The control voltage level at which the thyristor is given a gate signal forturn-on. The thyristor is gated when the control voltage is above Uc,on.There should always be some hysteresis in the control of the thyristor. Thusthe specified Uc,on must be at least 1.0E-4 Volts greater than Uc,off. Theprogram will automatically modify Uc,on and Uc,off if the difference isless. (See also Fig. 6-14)

Uc,off [V] [default: 0.0 Volt]The control voltage level at which the thyristor is given a gate turn-off signal.The thyristor is turned off at the moment the control voltage falls belowUc,off. See also comment for Uc,on.

Ron [Ohm] [default: 0.01 Ohm]The on-state resistance of the thyristor. To be specified in Ohms. Thespecified resistance must be larger than 1.0E-12 Ohms.

Be aware of possible numerical round-off errors and numerical solutionproblems if very high and/or very low resistance is specified.

N+ N-

NC+ NC-

N+ N-

NC+ NC-

TH2 Name N+ N- NC+ NC- Plot Init Uc,off Uc,on Ron Roff Irr

6.13. Voltage controlled uni-directional switch and Voltage controlled thyristor Page 6 - 37



Irr [A] [default: 1E-4 A]This parameter specifies the peak reverse recovery current at which thethyristor turns off. The program uses the unsigned value of the one specifiedin the datafile. The model have snap-off with no soft recovery. See Fig. 6-9 inthe description of the diode model for a definition of Irr.

Model description

The KREAN voltage controlled thyristor model has two distinct states, on or off (conducting andnon-conducting). The voltage controlled thyristor model can also be used to model anyuni-directional switch which conducts current in only one direction. The state of conduction forthe thyristor is controlled by the voltage applied between the control terminals (Ucon).

The thyristor can be operated as an ordinary thyristor or as a gate turn-off thyristor (GTO). Thethyristor is gated if the control voltage is larger then Uc,on. The thyristor is given a gate turn-offsignal if the control voltage becomes less than Uc,off. Any voltage between Uc,off and Uc,onimplies that the thyristor has no gate signal. This is illustrated in Fig. 6-11.

In the off-state the switch is modelled as a resistor with resistance Roff and in the on-state as aresistor with resistance Ron (see Fig. 6-12). The switching interval is not modelled. The voltagecontrolled thyristor switch model switches from one state to another instantaneously.

The control terminals are ideal. Thus, no current flows into the control terminals.

Note that the turn on and off of the thyristor also depends on the applied voltage across thethyristor model itself. It is the combination of the thyristor voltage and control voltage which givesthe time instants for turn-on and off of the thyristor.

The criteria for turn on of the thyristor is that the control voltage is larger than Uc,on and that thevoltage across the thyristor is larger than Uturn on. Uturn-on is equal to 0.001 Volt by default.

There are two alternative criteria for turn-off. The thyristor turns off if the current through thethyristor becomes less than -Irr or the thyristor turns off if the control voltage becomes less thanUc,off.

Plot

- Nothing

-V Voltage across the thyristor (Uswitch) and control voltage for the thyristor (Ucon).

-C Current through the thyristor (Iswitch).

-P Power dissipated in the thyristor model (Uswitch multiplied by Iswitch).

-s State of conduction for the thyristor. This plot is a function which is equal to 1 if the thyris-tor is in the conducting state and equal to 0 if the thyristor is in the non-conducting state.

Page 6 - 38 6.13. Voltage controlled uni-directional switch and Voltage controlled thyristor


Control voltage (Ucon)

Gate signal

Turn-on signal

Uc,off

Uc,on

Fig. 6-14 The figure illustrates the relationship between the control voltage levels and the gatesignals. As can be seen, there is a hysteresis in the switch control. Turn-on signal areonly given if the control voltage is above Uc,on while turn-off signal only are given ifthe control voltage goes below Uc,off

Turn-off signal(GTO)

Iswitch

Uswitch

RonVoltage controlled thyristor in on-state

Voltage controlled thyristor in off-state

Ucon

Iswitch

Uswitch

Roff

Ucon

Fig. 6-15 The KREAN voltage controlled thyristor model. The upper model is used in theon-state and the lower in the off-state. Only these two models are used because theswitching interval is not modelled. The control voltage terminals are ideal. No currentflows into these terminals.

6.13. Voltage controlled uni-directional switch and Voltage controlled thyristor Page 6 - 39


Example

TH2 Thyr1 N1 N2 NC1 NC2 -v 0 -2 3 1E-3 1E4 1E-4

The above line defines a voltage controlled thyristor named Thyr1 connected from node N1 toN2. The control voltage is the voltage between the nodes NC1 and NC2. The switch is initially off(Init=0). The voltage across the switch and the control voltage is to be stored during thesimulation (-v).

The thyristor is given a gate turn-off signal if the control voltage becomes less than -2 Volt. Thethyristor is gated if the control voltage is greater than 3 Volt. The on-state resistance is set to 1E-3Ohm and the off-state to 1E4 Ohm. The peak reverse recovery current is set to 1.0E-4 A.

Page 6 - 40 6.14. Ideal short


6.14 IDEAL SHORT

Datafile syntax

Model description

The ideal short circuit “model” simply connects two nodes directly together (zero impedance). Ithas no other purpose than making it easier to perform changes in a datafile.

The effect of a specified short between two nodes is the same as if all occurrences in the datafile ofthe node name “N-” have been substituted by the node name “N+”

It is allowed to specify several direct connections in the same datafile. The same node may also beconnected to several other nodes, but only two node names can be specified on the same line in thedatafile.

Example

CON n13 n4

The above line specifies that the node named n4 is to be treated as node n13.

The following is illegal:

Use instead:

CON n13 n4CON n13 n5

N+ N-

CON N+ N-

CON n13 n4 n5

6.15. Sub-circuits Page 6 - 41


6.15 SUB-CIRCUITS

Datafile syntax

Parameters

Type The type of sub-circuit to include. This corresponds to the name of the filewhere the sub-circuit definition is found (file “Type.sub”)

V1 V2 .. Vn A number of variables passed to the sub-circuit definition. This may bemodel parameters such as resistance, inductance, plot codes, node names etc.The order and number of passed variables must correspond to those definedin the sub-circuit type.

The variables may be placed on several lines. A left parenthesis must alwaysbe placed before the first and a right parenthesis after the last variable. This istrue also if the variables are placed on one single line.

Description

See description of sub-circuits in chapter 10 (how to use and how to define).

See the sub-circuit definition files or the documentation of sub-circuits for description of differenttypes of sub-circuits and their variables.

Note that the directory of the sub-circuit files must be specified in the input datafile (the DIRcontrol code described in section 5.9)

Sub-circuit

SUB Type ( V1 V2 ......

... Vn )

Page 6 - 42 6.15. Sub-circuits


Example

SUB Bridge ( Node3 10 1.22 -VC NodeR )

The above line specifies that a sub-circuit of type Bridge is to be included. The variables passed tothe sub-circuit definition are:

Node3 101.22-VCNodeR

The program will include a sub-circuit of type Bridge with the specified variables passed to thesub-circuit definition.

In some cases there may not be space for all variables on one line. For such cases the sub-circuitcan be specified as follows:

SUB Bridge ( Node3 101.22 -VCNodeR )

Note that this is only possible for sub-circuits. None of the other models allow that parameters aregiven on several lines. Note also that the parenthesis must be placed on the first and last lines.

6.16. Modules (general format) Page 6 - 43


6.16 MODULES (GENERAL FORMAT)

Datafile syntax type MO2

Datafile syntax type MOD (Syntax of old modules)

Parameters

ModTyp Each type of module has an identification name which corresponds to thename of the subroutine which describes the module.

Rp [Default: 10 000 Ohm]Parallel resistance of all current response terminals.

Module

N1

Nm

Nm+1

Nn

MO2 ModTyp Name Rp RsNcurr N1 ... NmNvol Nm+1 ... NnNstate Init1 Init2 ...Nplot Plot1 Plot2 ...Nparam Par1 Par2 ...

...

...

MOD ModTyp Name Rp Ncurr N1 ... NmNstate Init1 Init2 ...Nplot Plot1 Plot2 ...Nparam Par1 Par2 ...

...

...

Page 6 - 44 6.16. Modules (general format)


Rs [Default: 0.001 Ohm]Serial resistance of all voltage response terminals.

Ncurr The number of current response terminals. The number are found in thedocumentation of the module.

N1 ... Nm The name of the nodes to which the current response terminals are to beconnected.

Nvol The number of voltage response terminals. The number are found in thedocumentation of the module.

Nm+1 ... Nn The name of the nodes to which the voltage response terminals are to beconnected.

Nstate The number of internal state variables. The number are found in thedocumentation of the module.

Init1 ... Initial values for the state variables.

Nplot The number of plots available for the module. The number are found in thedocumentation of the module.

Plot1 ... The selected plots to store during the simulation. This is the “plot code” forthe module. Plotn is the number identification of the results to be storedfrom the module during the simulation. The documentation of the moduleshows the identification numbers for the different available plot results forthe module.

Npar The number of parameters to be specified for the the module. The number arefound in the documentation of the module.

Par1 ... The parameters for the module. The purpose and legal values for theparameters are found in the documentation of the module. Note that theparameters, and only the parameters, can be specified on several lines.

Description

The syntax shown here are the generic format. All Krean modules have a datafile syntax like oneof the two presented syntaxes. However, the number of nodes, state variables, plot options andparameters are in general different for different modules. The documentation for the specificmodule is therefore needed in order to be able to use it in a simulation.

Example

MO2 COMP C1 100000 0.00012 NA NB2 NC ND03 2 35 0.0 5.0 0.0 0.01 -0.01

The above example shows a specification of a module of type COMP. It is named C1 and theparallel resistance of all current response terminals is set to 100000 Ohm, while the serialresistance of the voltage response terminals are set to to 0.0001 Ohm. There are two current

6.16. Modules (general format) Page 6 - 45


response terminals which are to be connected to node NA and NB, while the two voltage responseterminals are to be connected to the nodes NC and ND.

There is no state variables for this module. Therefore, the fourth line contains only a zero withnone initial values specified. The module has three possible output plot. In this example the plot 2and 3 are specified to be stored during the simulation.

Finally, the module has 5 parameters. The five parameters are in the example specified to 0.0, 5.0,0.0, 0.01, and -0.01.

Page 6 - 46 6.17. Specification of piecewise linear source functions


6.17 SPECIFICATION OF PIECEWISE LINEAR SOURCE FUNCTIONS

It is possible to specify general piecewise linear current and voltage sources. The source functionof these are given as a pair of time and function values ( (Tn,Un) for voltage sources and (Tn,In)for current sources). A source function is generated from these pairs, assuming a linearrelationship between the points. The number of pairs is only limited by the maximum allowed linelength in the KREAN input datafile.

Usually a source function is periodic. Therefore it is assumed that the user specifies one period ofthe source function. The time function is therefore defined in a unified time interval from 0 to 1.0.The source parameter Period specifies the time which corresponds to the time 1.0. This makes itvery easy to change the period of the source function without the need of calculating newtimepoints.

Once a source function has been specified it can be easily phase shifted by specifying the Phiparameter.

The phase shift Phi is specified in degrees. Both positive and negative values are allowed. Thephase shift is referred to the specified period for the source. Thus Phi=360 means that the signalis to be shifted one period (gives the same source function as Phi=0).

A positive Phi means that the signal is shifted to the left, a negative Phi shifts the sourcefunction to the right. If the source function is named F(t) the Phi shifts F(t) in the followingway:

(6-11)

(6-12)

Some examples are given in Fig. 6-16. A voltage source is used in the illustrations, but theprinciples are the same for a current source.

Fshifted t( ) Funshifted t t0+( )=

t0Phi360---------- Period⋅=

6.17. Specification of piecewise linear source functions Page 6 - 47


A)

B)

C)

D)

VTG V1 N1 N2 -v 1 0.02 10000 00 0.5 0.5 12 2 -2 -2

Fig. 6-16 Examples of specification of piecewise linear voltage sources. A) Square-wave with period 0.02 and zero phase shiftB) Square-wave with period 0.02 and -90° phase shiftC) Resulting source output if the second time-voltage pair is omitted in AA) Square-wave with period 0.0175 and zero phase shift

A)

B)

C)

D)

VTG V2 N2 N3 -v 1 0.02 10000 -900 0.5 0.5 12 2 -2 -2

VTG V3 N3 N4 -v 1 0.02 10000 00 0.5 12 -2 -2

VTG V4 N4 N5 -v 1 0.0175 10000 00 0.5 0.5 12 2 -2 -2

Page 6 - 48 6.18. Specification of trigger signals for switches and thyristors


6.18 SPECIFICATION OF TRIGGER SIGNALS FOR SWITCHES AND THYRISTORS

Specification of trigger signals for time controlled switches are very similar to the specification ofgeneral piecewise linear sources (see section 6.17). The difference is that the function value in thiscase has only the three distinct values -1, 0 and 1. The meaning of each of the function values arefound in the description of each type of switch.

It is very important that all “corners” of a trigger signal are specified (the dots in Fig. 6-17).Incorrect operation of the switch may occur if any of the “corners” are omitted. It may seemsufficient to specify one point at each time of change, but the program assumes that both points atthe time of the changes are specified. Fig. 6-17 illustrates these differences. Fig. 6-18 shows somecorrect specifications of trigger signals.

Trigger signals can be phase shifted in the same manner as explained for the voltage and currentsources in the previous section (section 6.17)

0 0.3 0.3 0.7 0.7 1.00 0 1 1 0 0

0 0.3 0.7 1.00 1 0 0

Fig. 6-17 Illustration of correct and incorrect specification of trigger signal for time controlledswitch. The upper one is incorrect because the corners are not specified, thus resultingin the dashed trigger signal in the figure. The lower specification is correct, resulting inthe trigger signal made up of the whole lines in the figure.

Fig. 6-18 Examples of some correct specifications of trigger signals.

0 0.2 0.2 0.4 0.4 0.6 0.6 1.00 0 1 1 -1 -1 0 0

0 0.7 0.7 0.8 0.8 1.00 0 1 1 0 0

7. Running a simulation Page 7 - 1


7 RUNNING A SIMULATION

7.1 INTRODUCTION

This chapter explains how to start and control a simulation job.

Note: In this chapter commands are given to run a simulation. No complete description of thecommands are given here. For a detailed and complete description of the commands see chapter 9.Note also that the commands mentioned here are the keyboard commands and not the mouse menucommands.

7.2 THE BASIC STEPS

7.2.1 Load a datafile and start a simulationA simulation job starts with the loading of the data-file for the new simulation. The command touse for this purpose is the DATAFILE command. The file to read must be a KRE-file (see chapter4 for description of the datafile syntax).

The simulation can be started as soon as a datafile has been successfully loaded. A simulation isstarted with the GO command. Errors in the datafile are listed in the LST-file.

7.2.2 The clock

After a GO-command a “clock” like the one in Fig. 7-1 will appear in the lower right corner of theKREAN window. The clock shows the relative value of the time variable in the simulation. Theinterval from the start time to the end time of the simulation corresponds to one revolution. Thusthe simulation is finished after one revolution.

Note that the “speed” of the clock need not to be constant. The applied variable time steps causes avariable “speed” of the time variable.

Fig. 7-1 The “clock” in the lower right corner is present during simulation and shows therelative value of the time variable in the simulation.

Page 7 - 2 7.3. The LST- and PRE-files


7.2.3 Stop and start the simulationA running simulation can be stopped. Press the carriage return key (CR or ENTER) in order tostop a running simulation. The program will then stop as soon as possible. This may take sometime as the simulation is stopped in a controlled way in order to be able to continue later on.

It is possible to view the stored results before continuing the simulation. To view the results thecommands SELECT and DRAW are used to select and draw curves after a stop in the simulation(see more about result presentation in chapter 8)

The command GO can be used again to continue the simulation after a stop. The simulation can bestopped any number of times during a simulation.

7.2.4 Simultaneous plottingIt is possible to tell the program to plot curves simultaneous to the simulation. It is then necessaryto select curves (command SELECT) before the simulation is started.

The scaling of the y-axis will usually not match the results during simultaneous plotting. However,if the simulation is stopped and started again (GO-command), the y-axis will be automaticallyscaled based on the results created up to the stop point.

It is possible to turn off the simultaneous plotting by using the commandSIMULTANEOUS-PLOT.

7.3 THE LST- AND PRE-FILES

Two files are created each time a datafile is read. These files have the same name as the datafile,but with different extensions.

The first file created is a file with extension “.PRE”. This file contains a “pre-compiled” versionof the input datafile. This file shows the .KRE-file after the program have included sub-circuitsand substituted symbols. In this file it is possible to check if symbols and sub-circuits have beencorrectly understood. Possible error messages are found at the end of the file. Fig. 7-2 shows anexample of a PRE-file.

The second file created is a file with extension “.LST”. This is a list file which shows howKREAN has understood the input datafile. In this file it is possible to check if the datafile has beencorrectly understood. Any error messages are found at the end of this file.

The LST-file also shows the number of nodes and the number of components. A list of all nodenames and the number of terminals connected to each node are also found. This can be useful fordebugging purposes. Fig. 7-3 shows an example of a LST-file.

7.4. Statistics from the simulation Page 7 - 3


7.4 STATISTICS FROM THE SIMULATION

A file containing statistical information on the simulation is created after each simulation job. Thefile will have the same name as the datafile, except for the extension which in this case will be“.RUN”. Fig. 7-4 shows a example of a RUN-file.

Statistics are written to the file several times if the simulation is stopped and started again beforethe end of the simulation is reached.

Note that only the unix-versions of the KREAN program writes CPU-times to the RUN-file.

7.5 HOW TO CONTINUE A SIMULATION AT SOME OTHER TIME

It is possible to save the current state of a circuit for use as initial values for a future continuedsimulation.

The SAVE command is used for this purpose. The current state of the circuit will then be written toa file with extension “.INI”. The current state consists of the time variable, capacitor voltage,inductor currents and the state of the switches and diodes. In cases where modules are used, theINI-file also holds the values of module state variables and module parameters.

An example of a INI-file is shown in Fig. 7-5.

***************************************************************** This file shows: ********* .KRE file after replacing symbols and subcircuits ****************************************************************

TMA 2ERR 0.001

VTG U N2 N1 3 1 10 0.5 0.5 11 1 -1 -1

IND L1 N1 N2 0.005 3 0

Fig. 7-2 Example of PRE-file

Page 7 - 4 7.6. New defaults for plot set-up


A simulation can be continued from the initial values saved on the INI-file. The CONTINUEcommand are to be used for this purpose. The program will ask for the name of the datafile whichdescribes the circuit. This datafile will be read followed by the corresponding INI-file.

A new end-time for the simulation must then be specified (command TMAX). Finally, a GOcommand must be given and the simulation will start from the time and initial conditions specifiedon the INI-file.

7.6 NEW DEFAULTS FOR PLOT SET-UP

Each time the KREAN program is started it will look at the working directory to see if there is afile named “AUTO.MAC”. (For the PC-version of KREAN, the working directory is defined in thefile menu in the program manager in the Windows operating system).

The file named “AUTO.MAC” is expected to be a macro-file with KREAN commands (see page9-6 for description of macro-files). The commands on this file will be executed as the firstcommands before the user can give any commands.

This file can be useful if other default settings than those at start-up are desired. It is then possibleto create a file named “AUTO.MAC” with the commands which changes the desired settings.

Note: The program does not require that a “AUTO.MAC” file exists.

7.6. New defaults for plot set-up Page 7 - 5


************************************************************ ***** This file shows: **** ***** How KREAN have understood the .KRE file. **** ***** (Look at the end of this file if there were errors) ** ************************************************************ --------------------------------------------------- READING TMA= 2.000000000000000

--------------------------------------------------- READING ERR= 1.0000000000000000E-03

--------------------------------------------------- READING DATA FOR VOLTAGE SOURCE:

NAME=U NODE1=N2 NODE2=N1 TYPE OF SOURCE= 1 PLOT-CODE=3 PERIOD-TIME= 1.000000000000000 INTERNAL RESISTANCE= 0.0000000000000000E+00 PHASE SHIFT (DEGREE)= 0.0000000000000000E+00

TIME: 0.0000000000000000E+00 0.5000000000000000 0.5000000000000000 1.000000000000000

VALUES: 1.000000000000000 1.000000000000000 -1.000000000000000 -1.000000000000000 --------------------------------------------------- READING DATA FOR INDUCTOR

NAME=L1 NODE1=N1 NODE2=N2 INDUCTANCE= 5.0000000000000000E-03 PLOT-CODE=3 INITAL CURRENT= 0.0000000000000000E+00 INTERNAL RESISTANCE= 0.0000000000000000E+00

********************************************** Number of components: 2 Number of nodes 2 ********************************************** Name of nodes and the number of terminals connected to each of them:

N2 2 N1 2 ********************************************** Name of nodes which are used as REFERENCE nodes (These are connected together and have zero node voltage)

N2 **********************************************

Fig. 7-3 Example of LST-file. This file shows how KREAN has understood the input datafile.



********************************************** STATISTIC AFTER : 1 GO-COMMAND(S) TIME IN SIMULATION : 0.40000E-01 ITERATION ERR.TOL. : 0.00000E+00 ********************************************** - SIZE - # OF DIFF. EQUATIONS.......... 4 # OF ALG.EQUATIONS............ 12 # OF NONLINEAR EQUATIONS...... 0 # OF NON-ZEROS IN ALG.SYS..... 38 PERCENT NON-ZEROS............. 26 # OF FILL-IN DURING LU-FACT... 14 # OF DROPS DURING LU-FACT..... 0 ********************************************** - GENERAL - # OF CALCULATION POINTS....... 667 # OF INTEGRATION STEPS........ 642 # OF DC-CALCULATIONS.......... 6496 # OF LU-FACT. OF ALG. SYSTEM.. 26 ********************************************** - EVENTS - # OF ACCEPTED STATE EVENT..... 25 # OF EVENT TIMES FOUND ....... 24 MEAN # OF ITER. FOR EACH EVENT 1.13 MAX # OF ITER. FOR EVENT...... 2 MEAN # OF ITER. FOR INIT. EV.. 1.04 MAX # OF ITER. FOR INIT. EV... 2 # OF INACCURATE DETECTIONS.... 0 ********************************************** - DIFFERENTIAL EQ. - # OF REJECTIONS (DIFF.ALG).... 175 PERCENT REJECTIONS............ 27 # OF INCREMENTED STEP LENGTHS. 94 # OF REDUCTIONS IN STEP LENGTH 53 # OF NEW JACOBIANTS........... 26 # OF FACTORISATIONS OF JAC.... 347 # OF SOLUTIONS OF EQ.SYSTEM... 2475 MEAN # OF SOL. PER. STEP...... 3.86 MEAN # OF ITERATIONS.......... 2.01 ********************************************** - MODULES - # OF SOLUTIONS OF NON-LIN.EQ.. 0 # OF RESIDUAL CALCUALTIONS.... 0 # OF JACOBIANT CALCULATIONS... 0 # OF FORCED JACOBIANT CALC.... 0 MEAN # OF ITERATIONS.......... 0.00 MEAN # OF JACOBIANT CALC...... 0.00 MEAN # OF RESIDUAL CALC....... 0.00 # OF INACCURATE ITERATIONS.... 0 ********************************************** - CPU - TOTAL CPU-TIME USED FOR SOL... 20.65 **********************************************

Fig. 7-4 Example of RUN-file which contains statistics from the the simulation.

7.6. New defaults for plot set-up Page 7 - 7


Data saved : 25-MAY-1994 08:36

From datafile : ex2.kre

This file contains information needed when a simulation is to be continued

Time : 0.159407652096276E-02

Inductor currents and capacitor voltagesand module state variables

L1 : 0.448130872636032E-01L2 : -369.667074848340 L3 : 369.622261761010 LLOAD : 369.531896808206

State of switches

D1 : 1D2 : 0D3 : 1D4 : 0D5 : 1D6 : 0

Module parameters

Fig. 7-5 The figure shows an example of a INI-file. The INI-file shows the values of statevariables and the state of switches.



8. Result presentation and analysis Page 8 - 1


8 RESULT PRESENTATION AND ANALYSIS

8.1 INTRODUCTION

This chapter describes the possibilities for presentation and analysis of results. Described is alsothe format of the result files of the KREAN program.

Time domain plots are available after a simulation. It is also possible to have locus plot where onevariable is plotted as a function of another. Besides these possibilities, the only result analysisoffered by the KREAN program is discrete fourier analysis of time domain results.

However, it is possible to write the results to ASCII-files for use of the results in more advancedanalysis programs (for instance Matlab).

Note: This chapter explains which commands to use for presentations however no completedescription of the commands is given here. See chapter 9 for detailed and complete description ofthe commands. Note also that the commands mentioned here are the keyboard commands and notthe mouse menu commands.

8.2 TIME DOMAIN PLOTS

The following sub-sections outlines the process of presenting time domain plots of simulatedresults.

8.2.1 Select the curves to be drawn or plottedAfter a simulation it is time to take a look at the simulation results. The first command to use is theSELECT command. In the select menu the user can select the curves which are to be plotted. Thewindow in which the curve is to appear is also set.

8.2.2 Draw and plot time domain curvesThe basic commands for presentation of time domain plots of simulated results are the twocommands DRAW and PLOT. The DRAW command plots result curves on the screen, while thePLOT command gives the same curves and layout on a printer or plotter.

Page 8 - 2 8.2. Time domain plots


8.2.3 Changing the layout and the scaling of the axisThere are four different layouts of time domain plots for the KREAN program. The commandLAYOUT is used to select the type of curve layout. The four possible layouts are shown in Fig.8-1.

The scaling of x-axis and y-axis are controlled by the commands XMIN, XMAX, YMIN andYMAX. Separate scaling for each window are controlled by the WINDOW command.

For the y-axis it is possible to specify that automatic scaling is to be used (commandAUTOMATIC-SCALING). There are commands also available for fast re-scaling of the x-axis.The ZOOM, EXPAND, RIGHT, LEFT and ALL commands effects the scaling of the x-axis.

It is possible to change the text labels in a plot. The commands XTEXT, YTEXT, XUNITY,YUNITY and FIGURE are available for this purpose. Fig. 8-2 illustrates the text for which each ofthese commands controls.

There are also other commands available for modification of plotted curves. See the commanddescription in chapter 9 for details.

Layout 0 Layout 1

Layout 4Layout 2

Fig. 8-1 The figure shows the four different layouts for plots in the KREAN program. Usecommand LAYOUT to select one of the above layouts (Layout 1 is default)

8.2. Time domain plots Page 8 - 3


8.2.4 Per unit plotIt is possible to let the program scale all curves such that the y-values appears in an interval from-1 to 1. This can be useful especially if the phase differences of two curves with very differentmagnitude is to be inspected.

The command PU-PLOT is used to turn on and off this option. The effect is illustrated in Fig. 8-3.

Fig. 8-2 The figure illustrates the text labels which are modified by the commands: XTEXT,YTEXT, XUNITY, YUNITY and FIGURE-TEXT.

PU-PLOT OFF PU-PLOT ON

Fig. 8-3 The figure illustrates the effect of using pu-plot. In the pu-plot case, both curves arescaled to fall between -1 and 1 in case of pu-plot. This makes it easier to study forinstance the phase shift between the two curves.

Page 8 - 4 8.3. Locus plot


8.3 LOCUS PLOT

It is possible to plot a variable as function of another (see examples in Fig. 8-4). Thus, curves neednot to be plotted as function of time.

8.3.1 Select the curve for x-axis

The command XAXIS are used to select the x-axis curve. The curve number of the desired x-axiscurve is used as the parameter to the XAXIS command (The curve numbers are found in theSELECT menu). The default x-axis curve is the time (XAXIS 0 ).

8.3.2 Select time interval for locus plot

It is possible to control the time interval of results on which the plotted locus plot is based. Thedefault is that a locus plot is based on the time interval in the latest time domain plot before theXAXIS command were used. However, the two commands TLOWER and TUPPER can be usedfor specification of the time interval for a locus plot.

8.3.3 Layout of locus plot

The LAYOUT of curves can be chosen in the same way as for time domain plots. The commandsXMIN, XMAX, YMIN, YMAX can be used to set the axis scaling on locus plots. AUTOMATICscaling can also be set for locus plot.

Fig. 8-4 Examples of locus plot

8.4. Fourier analysis Page 8 - 5


8.4 FOURIER ANALYSIS

The discrete fourier analysis in KREAN can be used for the calculation of mean-values,rms-values (root-mean-square), and harmonic content. Fig. 8-5 shows the basic steps to perform adiscrete Fourier analysis in the KREAN program.

8.4.1 Select curvesUsually only a few of the created curves are of interest to analyse. Therefore the user must selectwhich curves to analyse. The curves which are selected for time domain plot will be analysed.Thus the SELECT command is also used for selection of curves for harmonic analysis.

8.4.2 Setting HARPER, HARSTART and HARMAXThe discrete fourier analysis needs a defined fundamental period for the analysis. The HARPERcommand are used for this purpose. If for instance the fundamental frequency is 50 Hz and thepurpose is to study harmonics of the 50 Hz, then HARPER must be set to 0.02 seconds.

A time domain simulation usually covers several periods of the periodic function. The discretefourier analysis covers only one single period of the fundamental. It is therefore needed to specifywhere in the time-domain results the analysis is to start. The command HARSTART is to be usedfor this purpose. The analysed results will be those from time equal to HARSTART to time equalto HARSTART+HARPER.

8.4.3 Number of harmonicsIt is possible to calculate up to the 1000th harmonic of the fundamental. The default number ofharmonics calculated is 20. The command HARMAX can be used to set another number.

8.4.4 The analysisThe time needed for the analysis depends on the number of curves selected and the number ofharmonics to be calculated. The density of plot points in the analysed interval also influences onthe time needed.

Note: After changes in HARPER, HARSTART and HARMAX, a new analysis command must begiven before the changes effects the analysis results.

Page 8 - 6 8.4. Fourier analysis


Simulate the circuit(command GO)

Select curves to be analysed.(command SELECT)

Set the fundamental period of the analysis(command HARPER)

Perform the analysis(command ANALYSIS)

Draw bar diagram of harmonics and choose scaling of axis(command: HARDRAW, HARMIN, HARMAX, YMIN, YMAX)

Set start time for analysis(command HARSTART)

Select number of har-monics to calculate(command HARMAX)

Plot bar diagram of harmonics.(command: HARPLOT)

Write analysis results to file(command: SAVE 3 )

Draw analysis results together with time domain curve.(command: DRAW n )

Plot analysis results together with time domain curve.(command: PLOT)

Fig. 8-5 The figure illustrates the result analysis commands in the KREAN program.



8.4.5 Draw bar diagram of harmonicsIt is possible to present the analysis results in a bar diagram. The command HARDRAW is usedfor this purpose. The bar diagrams will appear in windows corresponding to the selections whenthe curves were selected for analysis. Fig. 8-6 shows an example of a bar diagram of harmonics.

The harmonics in the bar diagram in Fig. 8-6 are numbered from zero (mean value) to 10. Thenumbers corresponds to the harmonic order. Thus number 1 is the fundamental. The harmoniclabelled -1 is the total rms-value of the analysed curve in the specified interval.

Note that the results presented in the bar diagram are rms-values (root mean square).

The x- or y-axis scaling of the bar diagram can be changed. The commands YMIN and YMAX areused for the y-axis, and the commands HARMIN and HARMAX are used for the x-axis.Automatic Y-scaling can be selected (command AUTOMATIC).

8.4.6 Plot bar diagramThe bar diagram can be send to a printer by the HARPLOT command.

8.4.7 Write analysis results to fileNot all of the fourier analysis results can be presented on the screen. It is possible to write theresults to a file. The SAVE command with parameter 3 (SAVE 3) is used for this purpose. A filewith the same name as the datafile, but with extension “.ANA” will then be created.

The ANA-file is a text file which can be imported in any text editing program or which can besend to a printer. Fig. 8-7 shows an example of an ANA-file created by the KREAN program.

Note: Fourier analysis results written to a file can not be read by the KREAN program. It is onlytime domain results that may be read by the READ-RESULT-command.

The information found in the ANA-file are:

• Time interval for the analysis

Fig. 8-6 The figure shows an example of a bar diagram presentation of Fourier analysis results(The “harmonic” number -1 is the total rms-value of the analysed waveform)



• Selected fundamental frequency for the analysis

• Value of analysed curve at the beginning and at the end of the analysed interval

• Minimum and maximum value of the curve in the analysed interval

• Total root-mean-square (rms) value of the curve in the analysed interval

• Arithmetic mean value of the curve in the analysed interval

• Rms-value and phase angle of fundamental and harmonic components. The fundamental andharmonics are also given in percent of the total rms-value of the curve.

• Harmonic distortion

• Percent total harmonic distortion

Note that the reference of phase angles are selected such that a sinusoidal crossing zero with apositive derivative at the start time of the analysed interval will have a phase angle equal to zero.

Harmonic distortion is a “measure” of the harmonic content. The harmonic rms-distortion arefound from the following equation:

(8-1)

The percent total harmonic distortion are found from the equation:

(8-2)

In the above equations I1,rms is the rms value of the fundamental, Itotal,rms is the totalrms-value of the curve and Ih,rms is the rms-value of the h-th harmonic.

Note: The program finds the harmonic distortion for all selected curves, although there is no sensein calculating harmonic distortion for all kind of waveforms.

Idistortion Itotal rms,2

I1 rms,2

–[ ] Ih rms,2

h 2=

∞

∑= =

%THD 100Idistortion

I1 rms,-----------------------------------⋅=



8.4.8 Draw analysis results together with time domain resultsIt is possible to present results of the fourier analysis together with the time domain plot. After ananalysis, the DRAW command can be used for this purpose. If a parameter is given for the DRAWcommand it will automatically add the specified fourier analysis results to the time domain plot.

The parameter after the draw command tells the program to plot a reconstructed curve togetherwith the original curve. The following list illustrates the possibilities:

DRAW If the parameter is omitted, the command works as usual, i.e., the selectedcurves are drawn on the screen.

DRAW -1 The selected curves are plotted together with the total rms-value for the curve(a straight line) See Fig. 8-8

DRAW 0 The selected curves are plotted together with the mean value of the curve (astraight line) See Fig. 8-9

DRAW 1 The selected curves are drawn together with the fundamental (a sinusoidal)See Fig. 8-10

Fig. 8-7 The figure shows an example of an ANA-file with analysis results. In this case onlyone curve has been selected for analysis.

************************************************************ ANALYSIS RESULTS FROM KREAN SIMULATION ************************************************************ DATAFILE : ex2.ana TIME INTERVAL : 2.0000000E-02 3.9999999E-02 FUNDAMENTAL FREQUENCY : 50.00 Hz REFERENCE OF ANGLES : SIN ( W(t-T0) + angle ) ************************************************************ L1 <A> VALUE AT START : -0.47439E-05 VALUE AT END : -0.58221E-04 MINIMUM VALUE : -0.50465E+03 MAXIMUM VALUE : 0.50465E+03 TOTAL RMS-VALUE: 0.39148E+03 MEAN VALUE : -0.55271E-05 ANGLE PERCENT OF RMS (DEG) TOTAL RMS FUNDAMENTAL 0.38074E+03 -12.717 97.26 % 2.HARM 0.15704E-04 -47.069 0.00 % 3.HARM 0.15503E-04 -33.577 0.00 % 4.HARM 0.18698E-04 -33.858 0.00 % 5.HARM 0.76123E+02 -245.488 19.44 % 6.HARM 0.10864E-04 11.613 0.00 % HAR. DISTORTION: 0.91060E+02 % TOT.HAR.DIS. : 23.916 % ************************************************************



DRAW n ( 2<n<1000 ) The selected curves are drawn together with a reconstructedcurve based on the first n-harmonics. See Fig. 8-11

An analysis (command ANALYSIS) of the selected curves must be performed, before using theDRAW command with one of the above parameters.

The reconstructed curve will only be plotted in the time interval which corresponds to the timeinterval which were analysed.

8.4.9 Plot analysis results together with time domain resultsAnalysis results can be plotted on a printer together with time domain results. If the PLOTcommand is used after a “DRAW n”, then the curve send to the printer will be the same as the onedrawn on the screen.

Note: It is not possible to use a parameter after the PLOT command in order to select a number ofharmonics to be added. The parameters for the PLOT command has other purposes (see the PLOTcommand description). The above method must be used instead.

Fig. 8-8 Example of DRAW -1 command (straight line shows total rms-value)

Fig. 8-9 Example of DRAW 0 command (straight line shows arithmetic mean value)



Fig. 8-10 Example of DRAW 1 command (reconstruction based on the mean value and thefundamental)

Fig. 8-11 Example of DRAW 7 command (reconstructed curve based on the 7 first harmonicsand the mean value)

Page 8 - 12 8.5. Writing time domain results to files


8.5 WRITING TIME DOMAIN RESULTS TO FILES

Time domain results can be written to files therefore it is possible to save all results or onlyselected curves and time intervals.

There are three different formats for result files:

• Un-formatted results. (RUF-file)

• Formatted results with numbered plot points and curve labels (RES-file)

• Formatted results with time and values only (MAT-file)

8.5.1 Un-formatted result file (RUF-file)

Un-formatted results are written to file using the SAVE 2 command. Un-formatted results arestored on a file with extension “.RUF”. Un-formatted results can only be read by the KREANprogram itself. Un-formatted results files are much smaller in size than formatted files.

8.5.2 Writing formatted result with curve labels to a file (RES-file)

If the SAVE 1 command is used, then all the results will be saved in a formatted file withextension “.RES”. This file is a formatted file which can be read by the KREAN program, textediting programs and other programs such as spread-sheets. In the RES-files the curve labels of thecurves are also included. Fig. 8-12 shows an example of a RES-file.

8.5.3 Writing selected formatted result with curve labels to a file (RES-file)

It is possible to store only selected parts of the results. This makes it possible to write only themost interesting curves and intervals of a simulation. The SAVE 6 command are used for thispurpose. The SAVE 6 command writes a formatted file of results (RES-file) which containsselected curves only (the same curves as those selected for plotting by the SELECT command).

The time interval of the saved results will be the interval between the selected XMIN and XMAXof curve window 1 (upper left window). Results for curves selected for other windows will also bestored, but only for the time interval specified for window 1.

Fig. 8-12 shows an example of a RES-file.

8.5.4 Writing selected matrix format results to file (MAT-file)For some purposes it may be convenient to files without any curve labels. If a result file withnumbers only is desired, then the SAVE 7 command can be used. The selected curves and timeinterval (see previous sub-section) will then be written in a matrix form to a file with extension“.MAT”. Fig. 8-13 shows an example of a MAT-file.

The first column contains the time vector, the other columns contains the result vectors for theselected curves. The results are written in right justified 17 character columns.

Note: Matrix files of type MAT can not be read by the KREAN program.

8.5. Writing time domain results to files Page 8 - 13


9 3COUNT TIME <SEC> D2 <A> LLOAD <A> LLOAD <V> 189 0.997068640E-02 0.488140411E+03 0.488062347E+03 0.324082031E+02 190 0.100897020E-01 0.491825684E+03 0.491745636E+03 0.294742680E+02 191 0.102087185E-01 0.495100769E+03 0.495019165E+03 0.256265984E+02 192 0.103277341E-01 0.497934784E+03 0.497851501E+03 0.219912376E+02 193 0.104467506E-01 0.500299194E+03 0.500214478E+03 0.177958317E+02 194 0.105657671E-01 0.502169037E+03 0.502082886E+03 0.136451473E+02 195 0.106847826E-01 0.503521759E+03 0.503434418E+03 0.914002228E+01 196 0.107918978E-01 0.504280701E+03 0.504192322E+03 0.505801010E+01 197 0.108990120E-01 0.504592133E+03 0.504502808E+03 0.798308074E+00

Fig. 8-12 The figure shows an example of a RES-file. The two numbers on the first line is thenumber of time points and the number of curves. The second line holds the curvelabels.

0.997068640E-02 0.488140411E+03 0.488062347E+03 0.324082031E+02 0.100897020E-01 0.491825684E+03 0.491745636E+03 0.294742680E+02 0.102087185E-01 0.495100769E+03 0.495019165E+03 0.256265984E+02 0.103277341E-01 0.497934784E+03 0.497851501E+03 0.219912376E+02 0.104467506E-01 0.500299194E+03 0.500214478E+03 0.177958317E+02 0.105657671E-01 0.502169037E+03 0.502082886E+03 0.136451473E+02 0.106847826E-01 0.503521759E+03 0.503434418E+03 0.914002228E+01 0.107918978E-01 0.504280701E+03 0.504192322E+03 0.505801010E+01 0.108990120E-01 0.504592133E+03 0.504502808E+03 0.798308074E+00

Fig. 8-13 The figure shows an example of a MAT-file. The first column holds the time points,the other columns holds the corresponding values of the selected curves.

Page 8 - 14 8.5. Writing time domain results to files


9. Commands Page 9 - 1


9 COMMANDS

9.1 INTRODUCTION

This chapter describes the available commands in the KREAN program. The description is basedon the original keyboard commands. The keyboard commands works with both the unix and theWindows versions.

9.1.1 The KREAN keyboard commandsKREAN expects a command to be given if the text “Enter commands” appears at the lower leftcorner of the KREAN window. The user may then enter one of the commands described in thischapter. Commands are to be terminated by a carriage return (Enter-key). A parameter for acommand can be written on the same line as the command itself.

The program will ask for the parameter if the parameter is not given on the same line. Theparameter may be a text or a number.

Note that it is possible to shorten the commands. One needs not to write the long command namesfound in this chapter. One letter is enough for some commands, while others require that morecharacters are written because other commands starts with the same character(s).

9.1.2 Command parametersMany of the commands are followed by a number or text parameter. This is in the descriptionillustrated by <n> or <Text>. Examples of legal formats for a number parameters are:

1.01 2E-4 -3 0 -4E-3

Text parameters can be any text. If the length of the entered text is to long the program will onlyuse the first characters.

9.1.3 Mouse menu commands

On the PC-Windows version there are also mouse menu commands available. The commandsfound in the mouse menus are the same as the keyboard commands. There are some minordifferences in the name of the commands. However, this manual only describes the keyboardcommands.

9.1.4 ClipboardThe only command not available as a keyboard command is the copy to clipboard command. Thisfeature is only available on the PC/Windows version, and only as a mouse menu.

9.1.5 Keyboard short-cut commands

There are also keyboard short-cut commands available. The keyboard short-cut command for agiven command are found in the mouse menus.

Page 9 - 2 9.2. Execute commands


9.2 EXECUTE COMMANDS

GoThis command is used to start a simulation (after the DATAFILE command). The command is alsoused to re-start a simulation that has been stopped by the user. Finally, the GO command is used tocontinue a simulation that has been specified by the CONTINUE command

ExitExit from KREAN.

Note that all results that have not been saved are lost without any confirmation.

DrawSelected curves are drawn on the screen if this command is given. Curves are selected using theSELECT command. (The DRAW command is used for time domain plots and for locus plots. Usethe command HARDRAW to draw harmonic bar diagrams).

Note: The DRAW command must be given in order to see changes made in axis scaling, text onplots, plot layout etc.

Draw <n>If a parameter is added to the DRAW command it works as usual, except that a reconstructed curvebased on the first n-harmonic components of the curve is also drawn (see detailed description insection 8.4.8 on page 8-9) An ANALYSIS command (fourier analysis) must have been givenbefore this command can be used.

Note: The <n> parameter must be written on the same line as the command. The program willnever ask for this parameter. If it is not given, the program assumes that a “normal” DRAWcommand is given and no reconstructed curves will appear.

Plot <n>Plot selected curves on printer. The plot command are used for time domain and locus plots. If thiscommand is used after the DRAW <n> command, then reconstructed curves will also be added tothe plot (se section 8.4.8 on page 8-9) (Use the HARPLOT command if a plot of bar diagrams ofharmonic are desired instead of time domain plots).

The parameter <n> tells the program which type of plot to generate.

On the PC-Windows version the Windows printer setup are used for selection of printer and file.The parameter <n> can have the following values:

1: Printer, black and white2: Printer, coloured

On the unix version of the KREAN program all plots are written to files. The files are given thesame name as the datafile plus a two digit number. The extension of the files will be .PLT forHPGL-plot and .PS for postscript files. The parameter <n> can have the following values on theunix-version of the KREAN program:

9.2. Execute commands Page 9 - 3


1: HPGL-plotter2: Postscript3: Colour Postscript

HardrawTo draw bar diagrams of harmonics for selected and analysed curves. Note that the curves must befourier analysed (command ANALYSIS) before using the HARDRAW command. Note also that ifnew curves are selected, then a new analysis command must be given before use of HARDRAW.

See section 8.4.5 on page 8-7 for more information about bar diagrams of harmonics. The layoutof bar diagrams can be changed by the use of the same commands as for time domain plots exceptfor the x-axis scaling which in this case are controlled by the two commands HARMIN andHARMAX.

The command HARPLOT is used to send bar diagrams to a printer or plotter.

Harplot <n>This command works like the PLOT command except for the fact that harmonic bar diagrams areplotted instead of time domain or locus plots. See description of the PLOT command on page 9-2.

AnalyseThis command starts the fourier analysis of the selected curves. Use the command SELECT forselection of curves to analyse. The analysis is performed according to the settings in the FOURIERdisplay menu. See section 8.4 on page 8-5 for details about the fourier analysis.

Note: The results of a fourier analysis are lost if the SELECT command is used. Thus afterselection of new curves a new ANALYSIS command must be given.

Continue <file-name>The CONTINUE command tells the program to read initial values from an INI-file. Thecorresponding datafile (KRE-file) will also be read. After the CONTINUE command: use the TMAXcommand to set a new end time for the simulation and GO to start the simulation. See section 7.5for more about continued simulation.

SelectThe SELECT command is used to select curves for the commands DRAW, PLOT, HARDRAW,HARPLOT, ANALYSIS and SAVE. The program will display the SELECT menu and enter the“select-mode” if the SELECT command is given. The select menu presents the curves which canbe selected. Type a zero in order to exit from the select-mode and go back to command mode.

All curves in the select menu have a name. The name of the available curves corresponds to thename of the component to which the results belongs. A “unity”-text tells the type of result found ineach curve. The unity-texts used are:

<V> Voltage

<A> Current

<W> Power



<Vs> Voltage on secondary side of transformer

<As> Current on secondary side of transformer

<Vc> Control voltage for voltage controlled switches and sources

<Ac> Control current for current controlled sources

<nn> Curve number nn for a module

A box appear in the SELECT menu. The box can be moved around with the numeric keys. Thenumber keys 2, 4, 6 and 8 moves the box down, left, right and up respectively.

Move the box to one of the desired curves. A Curve is to be selected for presentation in one of four“windows” (see the WINDOW command described on page 9-12). Use the number keys 1, 3, 7 and9 for selection of presentation in the lower left, the lower right, the upper left and the upper rightwindow respectively. Note that several curves can be selected for the same window and that thesame curve can be selected for several windows.

Markers shows which curves that have been selected for which of the four windows. Fig. 9-1shows two examples of markers.

If a selection is to be cancelled: Move the box to the selected curve and type 5. The marker willthen disappear and the curve is no longer selected. All selections can be cancelled in one operationby typing the minus sign (-).

After the desired number of curves have been selected: Exit from the select-mode by typing thezero key.

A summary of the functions of the numeric keys in the select-mode are given in Fig. 9-2.

Fig. 9-1 Examples of markers which shows the selections in the select menu

The curve is selected to be presented in the upper left window (Window 1)

The curve is selected to be presented in the upper left and lower right window (Window 1 and 4)

9.2. Execute commands Page 9 - 5


RefreshThis command updates the current display.

Empty-plot-arrayThis command tells the KREAN program to delete all the stored results of a simulation. This canbe a useful command if the result array becomes full before the interesting part of a simulation isreached. The EMPTY-PLOT-ARRAY command deletes the results such that space again isavailable for storage of results. The simulation can thereafter be continued by a GO command.

Note: A confirmation must be given before the command is actually carried out.

Note also: The size of the result array can be set by the user at start-up of the program. See theinstallation description.

7

0 -

98

4 65

1 32

Cancel

Cancelall

Exitselect

Fig. 9-2 The figure summarizes the function of the numeric keys in “select-mode”

7: Select curve-in-box to be plotted upper left window (window 1)9: Select curve-in-box to be plotted upper right window (window 2)1: Select curve-in-box to be plotted lower left window (window 3)3: Select curve-in-box to be plotted lower right window (window 4)

8: Move box up2: Move box down4: Move box left6: Move box right

5: Cancel selection for curve-in-box-: Cancel all selections

0: Exit from select mode and go back to normal command mode



Macro <file-name>This command tells the program to read commands from a file named <file-name>.MAC. Theprogram will read and execute all commands in the file and then returns to normal command mode(keyboard or mouse).

Macro command files are text files with extension .MAC. A macro file can be created by the SAVEcommand or it may simply be written in a text editing program. Macro-files created by the SAVEcommand belongs to a specific KREAN-datafile and will automatically be read each time thespecific datafile is read. However, by using the MACRO-command the user can use the same setupfor another datafile.

Each line in the macro-file must contain a KREAN command with its necessary parameters. Thereis no restriction on the number of commands in a macro file. The only command that is not legal touse in a macro-file is the MACRO-command itself. Nested macro command files are therefore notlegal.

A macro command file can be especially useful if a number of datafiles is to be simulated. It isthen possible to write a macro command file like the one in Fig. 9-3. If this file is namedJOB.MAC and the command

MACRO JOB

is given, then File1 will be read (DATA command). The simulation will automatically start (GOcommand) and after it is finished the results will be written to a file (SAVE command). This willthereafter be repeated for File2 and File3. Commands for more datafiles could have beenadded and also for instance commands for fourier analysis and storage of fourier analysis results.

DATA File1GOSAVE 2DATA File2GOSAVE 2DATA File3GOSAVE 2

Fig. 9-3 Example of macro-file which specifies that the datafiles File1, File2 and File3 are to besimulated. After each simulation the results are saved.

9.3. File commands Page 9 - 7


9.3 FILE COMMANDS

Data <file-name>This command tells the program to read a new datafile for a simulation (KRE-file). The file readwill be <file-name>.KRE.

After reading the datafile the program automatically checks if there is a command macro filenamed <file-name>.MAC. If such a file is found, the commands on this file will be read andexecuted.

ReloadThis command tells the program to once again read the last read datafile. The command worksexactly as the DATAFILE command except for the fact that no file-name needs to be specified.The previously specified file name is instead used. This command is useful when changes aremade or errors are corrected in a datafile and it is to be simulated once again.

Save <n>The save command writes results to files. See chapter 8 for detailed examples of the format ofresult files.

The parameter <n> decides what to save. Different types of results are written to files withdifferent file name extension depending on the parameter <n>. The file names used by the SAVEcommand are the same as the name of the datafile to which the results belong. Previous results areover-written without confirmation.

The parameter <n> can have the following values:

1: Formatted results are written to a file with file name extension .RES. The results in thisfile can be read by KREAN (command READ) or by some other program. See section 8.5on page 8-12 for details about the format.

2: Un-formatted results are written to a file with file name extension .RUF. The results inthis file can be read by KREAN only (command READ) . Note that results saved on this for-mat requires much less disk space than the formatted results.

3: The results of a fourier analysis are written to a file with file name extension .ANA. Theresults in this file can not be read by KREAN. See section 8.4.7 on page 8-7 for details aboutthe analysis results written to file.

4: The current plot setup, including scaling and selected curves are written as a macro com-mand file with file name extension .MAC. This file will automatically be read next timethe corresponding datafile is read.

5: The values of the state variables (capacitor voltage and inductor currents) and the state ofthe switches are written to a file with file name extension .INI. Typically these are thevalues at the end of a simulation. This file will be read if the CONTINUE command is used.See section 7.5 on page 7-3 for more about continued simulation.

6: Formatted results are written to a file with file name extension .RES. Unlike the case for<n> = 1, only the results for the currently selected curves and the currently selected x-inter-val is saved. Note: It is the x-interval of window 1 which decides which results to save. Seesection 8.5 on page 8-12 for details about the format of the results.

Page 9 - 8 9.3. File commands


7: Results for the currently selected curves and the currently selected x-interval are written toa file with file name extension .MAT. The results are written on a matrix format whichcan easily be imported into other programs. See section 8.5 on page 8-12 for details aboutthe format.

Read-results <file-name>This command tells the program to read results which have been written to file (SAVE-command).If the <file-name> is specified without extension, then the program first looks for a RES-file andthen for a RUF-file. If both are present, only the RES-file will be read.

After reading the result file the program automatically checks if there is a command macro filenamed <file-name>.MAC. If such a file is found, then the commands on this file will be readand executed.

Note: ANA, MAT, MAC and INI files can not be read by use of this command. Note also that it isnot possible to read results and then continue a simulation.

Other commands related to file commandsRead a macro file: See MACRO command described on page 9-6

Select curves to be saved: See SELECT command described on page 9-3

9.4. Display commands Page 9 - 9


9.4 DISPLAY COMMANDS

StatusThis command tells the program to show the STATUS display. The STATUS display is the onewhich appears when the program is started. Found in this display are only the name of the datafileand some information about the program version in use.

Set-up-plotThis command tells the program to show the SET-UP-PLOT display. The SET-UP-PLOTdisplay shows the current settings for the plot layout. A zero in this display means off while a 1means on, except for the LAYOUT-command where the number indicates which plot layout iscurrently selected (0,1,2 or 4)

AxisThis command tells the program to show the AXIS display for the default window. The AXISdisplay shows the current text labels and axis scaling for the default window. The default windowis chosen by the WINDOW command described on page 9-12.

FourierThis command tells the program to show the FOURIER display. The FOURIER display shows thecurrent settings for the fourier analysis (fundamental period, number of harmonics to calculate,and start time for calculations). The settings can be changed by use of the fourier analysiscommands described in section 9.8 on page 9-16.

Other commands related to display commands

Display SELECT menu: See SELECT command described on page 9-3

Draw selected curves: See DRAW command described on page 9-2

Draw bar diagram of harmonics: See HARDRAW command described on page 9-3

Page 9 - 10 9.5. Settings


9.5 SETTINGS

Simultaneous-plot <n>Turns on (<n>=1) or off (<n>=0) the simultaneous plot option. Curves will be plottedsimultaneous as the simulation plots are calculated if this option is turned on.

Note: It is not enough to turn this option on. Curves must also be selected before any curve will beplotted simultaneously with the simulation.

Pu-plot <n>Turns on (<n>=1) or off (<n>=0) the per unit plot option. Per unit plot implies that the curves arescaled between -1 and 1 before they are plotted. This makes it possible to study for instance phaseshift between curves of very different amplitudes directly in the same axis system. See also section8.2.4 on page 8-3 for description of per unit plots.

Auto-scaling <n>Turns on (<n>=1) or off (<n>=0) automatic scaling of y-axis.

Note: This option is turned off automatically if one of the y-axis scaling commands YMIN orYMAX is used.

Grid <n>Turns on (<n>=1) or off (<n>=0) the grid-points on plots.

Points <n>Turns on (<n>=1) or off (<n>=0) plot point marks. Plot point marks appears as a cross in theplots at each simulation point. This can be useful if one wants to see the density and/or distributionof simulation points.

Time-on-plot <n>Turns on (<n>=1) or off (<n>=0) the text line in each plot which shows the current date and time.

Borders <n>Turns on (<n>=1) or off (<n>=0) the borders around the plots.

Colours <n>Turns on (<n>=1) or off (<n>=0) colours on the plotted curves on the screen. If this option is on,then the curves will be coloured and plotted on a black background. If this option is off, then allcurves will be white on a blue background.

Black-and-white <n>Turns on (<n>=1) or off (<n>=0) black-and-white plots. If this option is on, then curves on thescreen will be white on a black background. This is an old option which was introduced in order tomake it possible to take black and white screen copies.

9.5. Settings Page 9 - 11


Tmax <n>This command is used to specify a new end-time for a simulation. The specified time <n>overrules the end time for the simulation specified in the input datafile (the TMA control code)

This command is useful if one finds that it would be of interest to simulate beyond the specifiedTMA. It is then possible to specify a new TMA by use of the TMAX command followed by a GOcommand.

The TMAX command is also used after the CONTINUED command. See section 7.5 on page 7-3 formore about continued simulations.

Hmax <n>This command is used to specify new maximum time step length in a simulation. The specifiedmaximum time-step length <n> overrules the maximum time step length specified in the inputdatafile (the HMA control code).

Note: This command can be used before a simulation, but also after the simulation has run forsome time.

Err <n>This command is used to specify a new error tolerance for a simulation. The specified tolerance<n> overrules the error tolerance specified in the input datafile (the ERR control code).

Note: This command can be used before a simulation, but also after the simulation has run for awhile.

This command is very useful if the results of the first part of a simulation is of little interest. It isthen possible to use a large tolerance for the first part of the simulation and a less tolerance in thepart of the simulation were a higher accuracy is desired. In this way, the simulation time used toreach steady state operation can be reduced.

Density <n>

The density of plot points after a simulation may be larger than the resolution on the plotter orterminal which are used. This may also be the case for curves copied to the clip-board. In suchcases the amount of information in the plot files send to the printer or clipboard is higher thannecessary and gives therefore slower processing speed of the plotter.

The Density command can be used to reduce the number of points plotted on the screen, theplotter and to the clipboard. The parameter <n> specifies the density in percent between eachplotted point. 100 % is the default. If a less value is used then the density of plotted points will beless and vice versa.

Page 9 - 12 9.6. Axis commands


9.6 AXIS COMMANDS

Layout <n>This command is used for selection of plot layout. There are four different types of plot layouts.The different layouts are illustrated in section 8.2.3 on page 8-2. The choices are:

<n> = 0 One axis system in one large window

<n> = 1 Four axis systems in four square windows

<n> = 2 Two axis systems in two long windows

<n> = 4 Four axis systems in four long windows

Window <n>This command is used to set default window (Note: Each axis system here is considered as onewindow). All the commands for changing the axis scaling and curve texts effects only the defaultwindow.

The windows are numbered from 1 to 4. The numbering for the different plot layouts are shown inFig. 9-4.The parameter of the windows command (<n>) selects which window is to be set as thedefault. Note: If <n> is set equal to 5 then all windows are set as default. Scaling commands willthen affect all windows.

The choices for the parameter <n> are:

<n> = 1 Set window 1 as default for axis scaling commands




<n> = 5 Set all windows as default for axis scaling commands

1 2

43

1

3

12

43

Layout 1 Layout 2 Layout 4

Fig. 9-4 The figure shows the window numbers for the different plot layouts

9.6. Axis commands Page 9 - 13


Xmin <n>Set a new minimum value (<n>) on x-axis for the default window(s). Use the WINDOW commandto set the default window.

Xmax <n>Set a new maximum value (<n>) on x-axis for the default window(s). Use the WINDOW commandto set the default window.

Ymin <n>Set a new minimum value (<n>) on y-axis for the default window(s). Use the WINDOW commandto set the default window.

Note that automatic y-scaling is automatically turned off if this command is used. Use commandAUTO-SCALING to turn on automatic y-scaling again (see page 9-10).

Ymax <n>Set a new maximum value (<n>) on y-axis for the default window(s). Use the WINDOW commandto set the default window.

Note that automatic y-scaling is automatically turned off if this command is used. Use commandAUTO-SCALING to turn on automatic y-scaling again (see page 9-10).

ZoomThis command changes XMAX for all windows and draws the curves with the new XMAX setting.The new XMAX is selected such that the new plot will cover the left half of the time span coveredby the plot before the ZOOM command were used.

See also the commands EXPAND, RIGHT and LEFT.

ExpandThis command changes XMAX for all windows and draws the curves with the new XMAX setting.The new XMAX is selected such that the new plot will cover twice the time span of the plot beforethe EXPAND command are used.

See also the commands ZOOM, RIGHT and LEFT.

RightThis command changes XMAX and XMIN for all windows and draws the curves with the newsettings. The new XMIN and XMAX are selected such that the new plot is shifted half a window tothe right compared to the plot before the RIGHT command were given.

LeftThis command changes XMAX and XMIN for all windows and draws the curves with the newsettings. The new XMIN and XMAX are selected such that the new plot is shifted half a window tothe left compared to the plot before the RIGHT command were given.

Page 9 - 14 9.6. Axis commands


AllThis command changes XMAX and XMIN for all windows and draws the curves with the newsettings. The new XMIN and XMAX are selected such that the whole simulated interval is shown.

Figure <text>Change figure text on the default window(s). See Fig. 8-2 on page 8-3 for illustration of thepossible text labels on curves. Use command WINDOW to change default window.

Xtext <text>Change x-axis text on the default window(s). See Fig. 8-2 on page 8-3 for illustration of thepossible text labels on curves. Use command WINDOW to change default window.

Ytext <text>Change y-axis text on the default window(s). See Fig. 8-2 on page 8-3 for illustration of thepossible text labels on curves. Use command WINDOW to change default window.

Xunity <text>Change x-axis unity text on the default window(s). See Fig. 8-2 on page 8-3 for illustration of thepossible text labels on curves. Use command WINDOW to change default window.

Yunity <text>Change y-axis unity text on the default window(s). See Fig. 8-2 on page 8-3 for illustration of thepossible text labels on curves. Use command WINDOW to change default window.

Other commands related to axis commands

Draw selected curves: See DRAW command described on page 9-2

Auto-scaling: See AUTO-SCALING command described on page 9-10

Per unit scaling of y-axis: See PU-PLOT command described on page 9-10

Display the axis settings: See AXIS command described on page 9-9

Save current axis scaling: See SAVE command described on page 9-7

9.7. Locus plot commands Page 9 - 15


9.7 LOCUS PLOT COMMANDS

Xaxis <n> Selects the curve for x-axis in locus plots. See section 8.3 on page 8-4 for description of locus plot.

The parameter <n> selects which curve to use for the x-axis. The curve numbers can be seen in theselect menu (give command SELECT and then exit select). The numbers in front of each curvelabel is the curve number.

If <n> is set equal to zero, then the time will again be used on the x-axis.

Tlow <n>A locus plot does not need to be based on the whole simulated interval. The parameter <n>specifies the lowest time point result to include in the locus plot.

See section 8.3 on page 8-4 for description of locus plot.

Tupper <n>A locus plot does not need to be based on the whole simulated interval. The parameter <n>specifies the upper time point result to include in the locus plot.

See section 8.3 on page 8-4 for description of locus plot.

Other commands related to locus plots

Select curves for y-axis: See SELECT command described on page 9-3

Draw locus plot: See DRAW command described on page 9-2

Locus plot to printer: See PLOT command described on page 9-2

Page 9 - 16 9.8. Fourier analysis commands


9.8 FOURIER ANALYSIS COMMANDS

Harstart <n>Sets the start time of the time interval to be fourier analysed. See section 8.4 on page 8-5 for moreabout the fourier analysis.

Harperiod <n>Sets the fundamental period for the fourier analysis to <n> seconds. See section 8.4 on page 8-5for more about the fourier analysis.

Harmax <n>This command can be used to change the maximum value on the x-axis on fourier bar diagramsplots.

The command can also be used to set the number of harmonics to be calculated. See section 8.4 onpage 8-5 for more about the fourier analysis.

Harmin <n>This command can be used to change the minimum value on the x-axis on fourier bar diagramsplots.

Other commands related to the fourier analysis

Starts fourier analysis: See ANALYSE command described on page 9-3

Draws a harmonic bar diagram: See HARDRAW command described on page 9-3

Plots a harmonic bar diagram on printer: See HARPLOT command described on page 9-3

Draws selected curves together with reconstructed curves based on the first n-harmoniccomponents: See DRAW <n> command described on page 9-2

Writes fourier results to file (ANA-file): see SAVE command described on page 9-7

Displays the fourier menu: See the FOURIER command described on page 9-9

Selects curves for analysis: See the SELECT command described on page 9-3

10. Sub-circuits Page 10 - 1


10 SUB-CIRCUITS

10.1 INTRODUCTION

It is possible to define sub-circuits for the KREAN program. Sub-circuits are pre-defined circuitsconsisting of standard KREAN models and modules. A sub-circuit is included in a circuit by onesingle line in the datafile (.KRE file). Thus, if a large number of sub-circuit definitions areavailable, then it is possible to create new datafiles very easily.

For each type of sub-circuit a number of variables are defined. In the datafile, the user specifies thetype of sub-circuit to include and the variables to be passed to the sub-circuit definition. Thevariables can be component parameters (resistances, inductances etc.), names of nodes to beconnected to the main circuit, component names and also plot codes for one or more of thecomponents in the sub-circuit.

The user can easily define sub-circuits and thus create a library of his most used sub-circuits. Asub-circuit could consist of a complete converter with controller and load, a three phasestar-connected voltage source or a three-phase transformer and diode bridges. The two followingsub-sections describes how to define sub-circuits and how to use sub-circuits in a circuitdescription.

10.2 HOW TO DEFINE SUB-CIRCUITS

10.2.1 The sub-circuit fileEach sub-circuit is defined in a separate file. Sub-circuit definition files must have the extension“.SUB”. The name of the file will also be the name of the sub-circuit type. All sub-circuits shouldbe placed in the same directory. The directory of sub-circuits must be explicitly given in the inputdatafile for the KREAN program.

Two examples of sub-circuits and their corresponding definition files is shown in Fig. 10-1. Atypical sub-circuit file starts with some comments about the sub-circuit. Next follows the variabledeclarations and then the description of the components of the sub-circuit.

Page 10 - 2 10.2. How to define sub-circuits


10.2.2 The variable declarationA sub-circuit definition looks very much like an ordinary datafile for a simulation. The onlydifference is that the variables which are to be declared are at the top of sub-circuit files.

The number of variables are optional. The variables can be parameter values, node and componentnames and plot codes.

A variable declaration starts with the three letter code “VAR” followed by the name of thevariable. Variable names must always start with a “@” (like symbols in a datafile). Any commentmay be written after the variable name. Note that only one variable name can be written on eachline.

/ File: YRES.SUB/ Three phase Y-connected/ resistive load

/ VariablesVAR @N1 Node of phase 1VAR @N2 Node of phase 2VAR @N3 Node of phase 3VAR @R Resistance of all phasesVAR @NAME Prefix name for resistor names (plot id)VAR @PLOT Plot code for resistors

/ The sub-circuitRES @NAME.1 @N1 #NY @R @PLOTRES @NAME.2 @N2 #NY @R @PLOTRES @NAME.3 @N3 #NY @R @PLOT

Fig. 10-1 Two examples of sub-circuit and their definition files. The upper sub-circuit is namedYRES and is defined in the file YRES.SUB. The lower is named YVOL and is definedin the file YVOL.SUB. These two sub-circuits are used in the example shown in Fig.10-2

@NAME.1

@NAME.2

@NAME.3

@N1

@N2

@N3

#NY

@N1

#NY @N2

@N3

V1

V2

V3

/ File: YVOL.SUB/ Three phase Y-connected voltage source/ (isolated star point)

VAR @N1 Node of phase 1VAR @N2 Node of phase 2VAR @N3 Node of phase 3VAR @AMP Amplitude of the sources (RMS)VAR @FREQ Frequency of the sources VAR @R Source internal serial resistance

VTG V1 #NY @N1 - 2 @R@AMP @FREQ 0

VTG V2 #NY @N2 - 2 @R@AMP @FREQ -120

VTG V3 #NY @N3 - 2 @R@AMP @FREQ -240

10.2. How to define sub-circuits Page 10 - 3


After a variable has been declared, it can be used in the same way as a symbol in an ordinary file(see section 5.6). This means that the variable name can be used instead of node names,component names, component parameters and plot codes. See the examples in Fig. 10-1.

The program will replace all occurrences of variable names with the variables passed to thesub-circuit definition before the sub-circuit are included in the datafile.

10.2.3 Topological description of the sub-circuitAfter the variable declaration follows the topological description of the sub-circuit. Thetopological description is made in the same way as in an ordinary datafile (KRE-file).

The two differences are that the variable names can be used instead of node names, parameters etc.and that the local node names must start with a “#” (see next sub-section).

10.2.4 Local node names in sub-circuit filesIt is extremely important that all local node names in a sub-circuit start with a “#”. Local nodes are“private” nodes which are not to be connected to any external nodes outside the sub-circuit (thestar-point #NY in Fig. 10-1 is an example of a local node).

The program will automatically substitute the “#” with” nnn#” where nnn is a count variablewhich are increased by one each time the program starts reading a new sub-circuit. Therefore, if alllocal node names start with a “#” they will have a unique name in the final circuit to be simulated.

The name of the remaining nodes (nodes which are not to be local) should be variable names(names declared on a VAR-line). The nodes @N1, @N2 and @N3 in Fig. 10-1 are examples ofnodes to be connected to nodes outside the sub-circuit. Thus they have node names which aredeclared among the variables.

10.2.5 Component namesThe names given to components in a datafile and in a sub-circuit are used as labels for thegenerated results (the name of the curves in the SELECT menu). This means that the componentname is of no importance as long as no plot is saved for a component (plot code equal to “-”) . Thisis the case for the voltage sources in the example in Fig. 10-1.

On the other hand. If results for components in a sub-circuit are to plotted, then it is also desiredthat the simulated results have different labels. The component name must then be placed amongthe variables for the sub-circuit. It is then possible to pass different component names to differentsub-circuits if the same type of sub-circuit is used several times in one datafile.

It is possible to use a passed variable as a prefix of component names. This is done for the resistorsin the example in Fig. 10-1. The name of the resistors consists of a variable name (@NAME) withsuffixes starting with a decimal point:

@[email protected]@NAME.3

If for instance the @NAME variable passed to the sub-circuit is set equal to R1, then the resistorsand the results for the resistors will be named R1.1, R1.2 and R1.3. See example in Fig. 10-1, Fig.10-2 and Fig. 10-3.

Page 10 - 4 10.3. How to use a defined sub-circuit


10.2.6 Nested sub-circuitsNested sub-circuits are allowed. Thus a sub-circuit file may include one ore more calls to one orseveral other sub-circuits. A variable of one sub-circuit can be passed to another. A local nodename starting with # can also be passed as a variable to a lower sub-circuit.

10.2.7 Special restrictionsIt is not allowed to use symbols in sub-circuit files.

The maximum number of sub-circuits in one datafile is 100, including all the possible nestedsub-circuits.

The maximum total number of variables passed to sub-circuits is 500, including all the possiblevariables passed in nested sub-circuits.

10.2.8 Summary of the most important rules for sub-circuit definitions

- Sub-circuit definitions must be placed in a file with extension .SUB. - Variable names must start with a “@”- Local node names must start with the character “#”- Only one variable can be declared on each VAR-line- Symbols are not allowed in sub-circuit files

10.3 HOW TO USE A DEFINED SUB-CIRCUIT

10.3.1 Directory of sub-circuitsThe directory of sub-circuits must be specified before any sub-circuit can be used in a datafile. Thecontrol command code DIR is used for this purpose. See section 5.9 on page 5- 12 for descriptionof the DIR control command.

Note that only one directory specification is allowed in each datafile. Thus, the sub-circuit filesmust all be placed in the same directory.

10.3.2 Including a call to a sub-circuit description in the datafileIn order to use a sub-circuit the user needs:

- The name of the sub-circuit- The name of the directory where the description file for the sub-circuit is located- A description of the sequence of variables to be passed to the sub-circuit definition file.

The first task is to specify the directory of the sub-circuits (see the previous sub-section), followedby the sub-circuit and the variables which are given on one or more lines. Fig. 10-2 shows howtwo sub-circuits of type YRES and one of type YVOL (defined in Fig. 10-1) are used in a datafile.It can be seen that only one line of specification is needed for each of the three phase y-connectedloads and sources.

10.3. How to use a defined sub-circuit Page 10 - 5


As can be seen in Fig. 10-2, each call to a sub-circuit starts with the three letter code “SUB”. Afterthat the name of the type of sub-circuit to include is defined (corresponds to the name of the filewhere it is defined). This is followed by the variables to be passed to the sub-circuit definition(enclosed in parenthesis).

The first sub-circuit to be included is one sub-circuit of type YVOL. The KREAN program willinclude the content of the sub-circuit definition file YVOL.SUB into the datafile after thefollowing substitutions have been performed:

- Variable @N1 is replaced by NA- Variable @N2 is replaced by NB- Variable @N3 is replaced by NC- Variable @AMP is replaced by 220- Variable @FREQ is replaced by 50- Variable @R is replaced by 0.001- All occurrences of # will be replaced by 001# (001 because it is the first sub-circuit in the file)

/ Example of datafile using sub-circuits/ File : EX.KRE

/ Control codesTMA 0.04HMA 0.001

/The voltage sourcesSUB YVOL ( NA NB NC 220 50 0.001 )

/The loadsSUB YRES ( NA NB NC 10 R1 -C ) SUB YRES ( NA NB NC 20 R2 -C )

Fig. 10-2 Example of a circuit which can be specified using the sub-circuits YRES and YVOLdefined in Fig. 10-1. The figure shows both the circuit and a corresponding datafile.

NA

NB

NC

1

2

3

1

2

3

1 2 3

Sub-circuit of type YVOL

Sub-circuit of type YRESand named R1

Sub-circuit of type YRESand named R2

Page 10 - 6 10.3. How to use a defined sub-circuit


The second sub-circuit to include is one of type YRES. The substitutions in the YRES.SUB-filefor the first sub-circuit of type YRES will be as follows:

- Variable @N1 is replaced by NA- Variable @N2 is replaced by NB- Variable @N3 is replaced by NC- Variable @R is replaced by 10- Variable @NAME is replaced by R1- Variable @PLOT is replaced by -C- All occurrences of # will be replaced by 002# (002 because it is the second sub-circuit in the file)

The third sub-circuit to include is also of type YRES. The substitutions in the YRES.SUB-file forthe second sub-circuit of type YRES will be as follows:

- Variable @N1 is replaced by NA- Variable @N2 is replaced by NB- Variable @N3 is replaced by NC- Variable @R is replaced by 20- Variable @NAME is replaced by R2- Variable @PLOT is replaced by -C- All occurrences of # will be replaced by 003# (003 because it is the third sub-circuit in the file)

The example in Fig. 10-2 illustrates how component parameters, node names, plot-codes andcomponent names are passed to a sub-circuit.

Note that the variables in a call to a sub-circuit can be placed on several lines. See section 6.15 onpage 6- 41 for the general syntax of sub-circuits.

10.3.3 The PRE-fileThe KREAN program reads the input datafile (.KRE-file) and first creates a “pre-compiled”datafile. This is a file with extension .PRE instead of .KRE. The PRE-file shows how KREAN hasincluded sub-circuits (and also symbols). If there are no problems, the KREAN program will thenautomatically read the PRE-file as the final input file for the simulation.

It is possible to view the PRE-file in order to check how KREAN has included sub-circuits. In thisfile it is also possible to see the names of the local nodes in the sub-circuits. Note that the includedsub-circuits are located at the end of the file and not at the location where the SUB control line waswritten.

Fig. 10-3 shows the generated PRE-file corresponding to the datafile in Fig. 10-2. This file showshow KREAN has included the sub-circuit. It can be seen that a lot of comments are automaticallyadded in order to make it easier for the user to study the pre-compiled file.

It is always recommended to look at the PRE-file if there are problems with symbols orsub-circuits. At the end of the file there will usually be an error message. It is also recommended toview the PRE-file if there are strange errors in the simulation in case the error is caused by somemistake in the use of sub-circuits.

Note: All the comment lines in a sub-circuit are copied to the PRE-file. This implies that a lot ofcomments will be written in the PRE-file if a lot of comments are present in the SUB-file. If areduced number of comments are wanted in the PRE-file, then use // at the beginning of comments

10.3. How to use a defined sub-circuit Page 10 - 7


in a sub-circuit (instead of just / ). Comments defined by two slashes will not be copied from theSUB to the PRE-file.

***************************************************************** This file shows: ********* .KRE file after replacing symbols and subcircuits ****************************************************************/ EXAMPLE OF DATAFILE USING SUB-CIRCUITS/ FILE : EX.KRE

/ CONTROL CODESTMA 0.04HMA 0.001

/THE VOLTAGE SOURCES/SUB YVOL

/THE LOADS/SUB YRES/SUB YRES

/=======================================================/ INCLUDES SUB-CIRCUIT OF TYPE : yvol / FROM FILE : yvol.sub/ PREFIX FOR LOCAL NODE NAMES : 001#/=======================================================

/ FILE: YVOL.SUB/ THREE PHASE Y-CONNECTED VOLTAGE SOURCE/ (ISOLATED STAR POINT)

/ Var: @N1 <== NA ** NODE OF PHASE 1 / Var: @N2 <== NB ** NODE OF PHASE 2 / Var: @N3 <== NC ** NODE OF PHASE 3 / Var: @AMP <== 220 ** AMPLITUDE OF THE SOURCES (RMS) / Var: @FREQ <== 50 ** FREQUENCY OF THE SOURCES / Var: @R <== 0.001 ** INTERNAL SERIAL RESISTANCE OF T

VTG V1 001#NY NA - 2 0.001220 50 0

VTG V2 001#NY NB - 2 0.001220 50 -120

VTG V3 001#NY NC - 2 0.001220 50 -240

/=======================================================/ INCLUDES SUB-CIRCUIT OF TYPE : yres / FROM FILE : yres.sub/ PREFIX FOR LOCAL NODE NAMES : 002#/=======================================================

/ FILE: YRES.SUB/ THREE PHASE Y-CONNECTED/ RESISTIVE LOAD

/ VARIABLES/ Var: @N1 <== NA ** NODE OF PHASE 1 / Var: @N2 <== NB ** NODE OF PHASE 2 / Var: @N3 <== NC ** NODE OF PHASE 3 / Var: @R <== 10 ** RESISTANCE OF ALL PHASES / Var: @NAME <== R1 ** PREFIX NAME FOR RESISTOR NAMES / Var: @PLOT <== -C ** PLOT CODE FOR RESISTORS

/ THE SUB-CIRCUITRES R1.1 NA 002#NY 10 -CRES R1.2 NB 002#NY 10 -CRES R1.3 NC 002#NY 10 -C

/=======================================================/ INCLUDES SUB-CIRCUIT OF TYPE : yres / FROM FILE : yres.sub/ PREFIX FOR LOCAL NODE NAMES : 003#/=======================================================

/ FILE: YRES.SUB/ THREE PHASE Y-CONNECTED/ RESISTIVE LOAD

/ VARIABLES/ Var: @N1 <== NA ** NODE OF PHASE 1 / Var: @N2 <== NB ** NODE OF PHASE 2 / Var: @N3 <== NC ** NODE OF PHASE 3 / Var: @R <== 20 ** RESISTANCE OF ALL PHASES / Var: @NAME <== R2 ** PREFIX NAME FOR RESISTOR NAMES / Var: @PLOT <== -C ** PLOT CODE FOR RESISTORS

/ THE SUB-CIRCUITRES R2.1 NA 003#NY 20 -CRES R2.2 NB 003#NY 20 -CRES R2.3 NC 003#NY 20 -C

/+++++++++++++++++++++++++++++++++++++++++++/ NUMBER OF SUB-CIRCUITS : 3/ TOTAL NUMB. OF VARIABLES : 18/+++++++++++++++++++++++++++++++++++++++++++

Fig. 10-3 The figure shows the pre-compiled version (PRE-file) of the datafile in Fig. 10-2

Page 10 - 8 10.4. Single line three phase sub-circuits


10.4 SINGLE LINE THREE PHASE SUB-CIRCUITS

In simulation programs dedicated for system analysis it is usual to specify three phase circuits bysimply specifying a single line circuit. This is also possible in the KREAN program if theappropriate sub-circuits are defined.

Note that the calculations are to be carried out as a full three phase analysis. The purpose of thesingle line three phase sub-circuits is only to make it easier to set up a datafile for a simulation ofthree phase circuits.

10.4.1 Defining and using single line three phase sub-circuits

Fig. 10-4 and Fig. 10-5 shows examples of two different single line three phase sub-circuits. Thefirst one is a serial resistance, the second one is a star connected voltage source with isolated starpoint. The use of these two sub-circuits are illustrated in Fig. 10-6.

In figure Fig. 10-6, the nodes named T1, T2 and T3 are single line input three phase nodes. Thefirst call to a sub-circuit includes a sub-circuit of type VY which is a three phase voltage source.This is done by the datafile line:

SUB VY ( T1 0.001 220 50 V1 -C )

The variable T1 is the single line node to which the source is connected. The result, when thesub-circuit file is included, will be that all occurrences of @N in the sub-circuit file VY.SUB aresubstituted by the passed variable T1. The node names of the three voltage sources will then be:

T1.R for the node in phase R

T1.S for the node in phase S

T1.T for the node in phase T

The suffixes .R, .S and .T must always be used in sub-circuit files where the passed node namevariable is the name of a single line three phase node (see Fig. 10-4 and Fig. 10-5). If more thanthree phases are used, e.g. six phases, then the natural additional suffixes to use would be .U, .V,.W.

Note: Other suffixes could have been chosen. The main point is that the same suffix can be usedfor the same phase in all the sub-circuits. It is therefore recommended to use the suffixes describedabove in order to avoid problems with “incompatible” sub-circuits.

10.4.2 Connecting single line nodes to ordinary nodes

Even though the single line input is smaller it may be desired to specify part of a circuit with fullthree phase input (e.g. non-symmetric loads). It is then recommended to define a sub-circuit likethe one in Fig. 10-7. The sub-circuit has four variables, the first is a single line node and the threeothers are the names of three ordinary nodes.

Fig. 10-8 shows the use of the interface sub-circuit. A three phase node T1 is split in three nodesN1, N2 and N3 by the sub-circuit call:

10.4. Single line three phase sub-circuits Page 10 - 9


SUB INT31 ( T1 N1 N2 N3 )

The effect of this call is that:

Node T1.R is connected to N1

Node T1.S is connected to N2

Node T1.T is connected to N3

It is thereafter possible to connect any component to the nodes N1, N2 and N3.

Note: It is also possible to connect components directly to the nodes T1.R, T1.S and T1.T withoutusing any interface sub-circuit.

/ File: R3.SUB/ Three phase serial resistor/ NOTE: Three phase nodes

VAR @N1 Positive three phase nodeVAR @N2 Negative three phase nodeVAR @R ResistanceVAR @Name Name of resistors (plot id.)VAR @Plot Plot code

RES @Name.R @N1.R @N2.R @R @PlotRES @Name.S @N1.S @N2.S @R @PlotRES @Name.T @N1.T @N2.T @R @Plot

@N2@N1

Fig. 10-4 Example of single line three phase sub-circuit for a three phase serial resistor.

@Name.R

@Name.S

@Name.T

/ File: VY.SUB/ Three phase Y-connected voltage source/ (isolated star point)/ NOTE: Three phase nodes

VAR @N Three phase nodeVAR @R Internal resistance of each voltage sourceVAR @Amp Amplitude of the sources (RMS)VAR @Freq frequency of the sources VAR @Name Prefix name of voltage source (plot id.)VAR @Plot plot code for sources

VTG @NAME.R #NY @N.R @PLOT 2 @R@AMP @FREQ 0

VTG @NAME.S #NY @N.S @PLOT 2 @R@AMP @FREQ -120

VTG @NAME.T #NY @N.T @PLOT 2 @R@AMP @FREQ -240

@N

Fig. 10-5 Example of single line three phase sub-circuit for a three phase, Y-connectedsinusoidal voltage source with isolated star point.

#NY



/ File: LIN3.KRE/ Example: Use of single line input sub-circuits

TMA 0.2

/ The volatge sourcesSUB VY ( T1 0.001 220 50 V1 -C)SUB VY ( T3 0.001 210 50 V2 -C)

/ The serial resistorsSUB R3 ( T1 T2 10 R1 - )SUB R3 ( T2 T3 5 R2 - )

Fig. 10-6 Example of how to use single line three phase sub-circuits in a simulation. The figureshows both the circuit and the corresponding datafile for the simulation. Thesub-circuits R3 and VY are defined in Fig. 10-4 and Fig. 10-5. Note that the resultingdatafile describes a full three phase circuit (six voltage sources and six resistors). T1,T2 and T3 are single line three phase node names.

220 V 210 V

10 Ohm 5 Ohm

T1 T2 T3R1 R2

V1 V2

/ File: INT31.SUB/ Interface between three phase nodes/ and “normal” nodes

VAR @N3 Three phase nodeVAR @NR Node in phase RVAR @NS Node in phase SVAR @NT Node in phase T

CON @NR @N3.RCON @NS @N3.SCON @NT @N3.T

@N3

@NR

@NS

@NT

Fig. 10-7 Sub-circuit which expands a single line node to ordinary nodes

10.4. Single line three phase sub-circuits Page 10 - 11


/ Datafile ..SUB INT31 ( T1 N1 N2 N3 )SUB VY ( T1 0.001 220 50 V1 -C)

N1

N2

N3

Fig. 10-8 The figure illustrates the use of the INT31 sub-circuit in Fig. 10-7. The nodes N1, N2and N3 are “normal” nodes while T1 is a single line three phase node. Any standardKREAN model can be connected directly to the nodes N1, N2 and N3 while only singleline three phase sub-circuits can be connected to node T1.

220 VT1

V1



11. Error and warning messages Page 11- 1


11 ERROR AND WARNING MESSAGES

11.1 INTRODUCTION

This chapter describes the error and warning messages of the KREAN program. Guidelines forhow to correct the errors are given. Error messages implies that a simulation has stopped or thatthe last given command failed.

11.2 THE ERROR MESSAGES

ERR. 1 SIMULATION TIME EXCEEDED TMA

This message means that the simulation has reached the TMA specified in the datafile (end timefor the simulation). If a GO command is given, this error message will be given.

If you want to continue the simulation beyond TMA: Use the TMAX keyboard/menu command tospecify a larger TMA and then use the GO command again.

ERR. 3 UNIDENTIFIED COMMAND

A command has been given (from keyboard or macro file) that is unknown to the program.

ERR. 4 AMBIGUOUS COMMAND

The command was too shortened. There are more than one command with the same prefix, andthus the program does not know which of them to use.

ERR. 5 OPENING COMMAND FILE

The program was not able to open a macro file with commands (.MAC file). Macro files are readafter command MACRO. The program also searches for macrofiles after the commands

Page 11- 2 11.2. The error messages


DATAFILE and READ_RESULTS. In such cases, macrofiles with names equal to datafiles andresult files will be read.

The error may be caused by some disk error, but usually because of misspelling in connection withthe MACRO - command.

The error is not fatal and the work can continue, but the commands of the command file are ofcause not read.

ERR. 6 NO DATAFILE GIVEN AND NO RESULT READ

The SELECT command has been given but there is nothing to select from. A datafile must be read(command DATAFILE) or old results must be read (READ_RESULTS) first.

ERR. 7 NO PLOT CODES SET IN DATAFILE

This means that the program has read a datafile with all plot codes set to zero or “-”. No resultswill be available after the simulation and it is impossible to select curves.

ERR. 8 READING SELECTED CURVES

This error may occurs when the program reads a command/macro file that have been created bythe SAVE 4 command. An error is detected in the part of the file that specifies the selected curves(the selected curves and their corresponding windows)

The consequence of this error is that none curves are selected. The SELECT command must beused instead. The command file should be deleted or a new one saved (SAVE 4).

ERR. 9 CURVE NUMBER TOO HIGH

This error may occur when the program reads a command/macro file that has been created by theSAVE 4 command. An error is detected in the part of the file that specifies the selected curves (theselected curves and their corresponding windows)

The consequence of the error is that none curves are selected. Use the SELECT command to selectcurves instead.

This error will typical occur if the plot codes in the datafile are modified and an (old)corresponding .MAC file is read automatically.

ERR. 10 WINDOW NUMBER TOO HIGH

This error may occurs when the program reads a command/macro file that have been created bythe SAVE 4 command. An error is detected in the part of the file that specifies the selected curves(the selected curves and their corresponding windows)

11.2. The error messages Page 11- 3


The consequence of the error is that none curves are selected. The SELECT command must beused instead and a new command file should be saved.

The problem is that a too large window number is used in the .MAC file. Delete the old MAC-fileor make a new one (SAVE 4 command).

ERR. 11 COMMAND OUT OF USE, USE COMMAND MAC INSTEAD

This message simply tells that the old command COM is no longer available. The MACROcommand can be used instead.

ERR. 12 USE COMMAND ANALYSIS FIRST

This message is given if one tries to draw, plot or save Fourier results before the fourier resultshave been calculated.

Use the ANALYSIS command to calculate the fourier results.

ERR. 13 NO SIMULATION RESULTS, MAKE A GO FIRST.

This message is given if one tries to calculate fourier results (command ANALYSIS) before asimulation has been carried out.

Simulate the circuit first (command GO)

ERR. 14 NO DATAFILE GIVEN

No datafile is read. Thus it is impossible to SELECT curves or simulate the circuit. Use thecommand DATAFILE to read a datafile (.KRE-file)

(Note that if there was an error during the reading of a datafile, then the program will act as if nodatafile has been read)

ERR. 15 MAKE A GO OR READ_RESULTS

There are no results to PLOT or DRAW.

Old results must be read (READ_RESULTS) or a simulation must be carried out (GO)

ERR. 16 NO CURVES SELECTED, USE SELECT COM.

No curves have been selected, thus it is impossible to PLOT or DRAW time domain analysis andfourier results. It is also impossible to carry out a fourier analysis.

Use command SELECT to select curves.



ERR. 17 SIMULATION STUCK IN SWITCHING

The program is not able to find a switch state configuration that can be accepted. It can also beproblems with piece-wise linear relationships in KREAN modules (check parameters).

The problem is usually some sort of feedback in the circuit. The program is forced into an endlessloop.

Example: A diode or voltage controlled device is turned on, the program immediately (in the sametime point) detects that it switch condition have changed, and thus turns it off again. But now thecondition have changed again and thus the program turns the switch on again. If the situation isdifficult this will last forever.

To avoid the problem one must take a careful look at the circuit and try to detect a situation like theone described above. The error is usually due to some logic error in the circuit.

It may help to include some hysteresis in voltage controlled devices or filtering of control signals.

ERR. 18 X-INTERVAL TOO SHORT

This means that the selected interval between XMIN and XMAX are too short. There is only oneor no simulation point in the specified interval. Specify a new XMIN or XMAX in order to avoidthe problem.

The message may also be caused by a result array that contains garbage. This may be caused byerrors in the datafile, errors in the program or errors in an old result files. Very often it is caused byerrors in the plot codes (missing or illegal plot code)

It is very difficult to give any general comment on where to find the error in such cases.

ERR. 19 TOO MANY NODES

The circuit is too large for the KREAN version in use. Try to reduce the number of nodes bysimplifying the circuit.

ERR. 20 OPENING DATAFILE

The datafile was not found or there were problems with the opening of the datafile.

This may be caused by misspelling or the use of upper/lower case letters (UNIX-stations). A usualerror is that the file is not in the default directory.

ERR. 21 OPENING .INC FILE

The include file specified in the datafile was not found or the program was not allowed to open thefile.



ERR. 22 WRITING TO .LST FILE

During reading of a datafile a .LST file is generated. This file contains information about the readdatafile. The program was not able to write to this file.

The error is usually caused by a full disk (no disk space available) or because the file is locked byanother user/process.

ERR. 23 READING DATAFILE, SEE .LST-FILE

An error in the datafile has been detected (after command DATAFILE or READ_RESULTS)

An illegal syntax or some illegal parameters have been used. The .LST is written at the same timeas the datafile is read. At the end of the .LST file it is possible to see where the error was detectedbecause the program stops reading as soon as an error is detected.

An usual error is that the number 0 and the letter o have been mixed.

ERR. 24 READING .INC FILE, SEE .LST FILE

There was an error in the INCLUDE file. See the .LST file to find the location of the error.

ERR. 25 OPENING .MAC FILE

The program was not able to open a .MAC file for storage of the current setup. The error may becaused by a disk error (no empty space) or because no datafile is read (and thus there is no name togive the macro file)

ERR. 26 NO RESULTS TO SAVE

There are no results available, thus it is impossible to save results.

Use the GO command to get results.

ERR. 27 OPENING .ANA FILE

The program could not open a file for the fourier results (.ANA-file). This may be cased by diskerror (no empty space)

ERR. 28 OPENING RESULT FILE

The program could not open a file for the simulation results (.RES or .RUF-file). This may becaused by disk error (no space available or write protection)



ERR. 29 WRITING TO RESULT FILE

An error occurred while writing results. This may be cased by disk error (no empty space)

ERR. 30 READING RESULT FILE

There was an error in the result file. Probably there was also an error when the file was saved orthe file have been modified in an text editing program such that the format has been changed.

Problems may occur in .RUF files when exchanged between different operating systems. In suchcases: use .RES files (see SAVE command)

Note: A KREAN version with a smaller plot array will cause trouble with results from versionswith a larger plot array.

ERR. 35 OPENING .LST-FILE

The program could not open a file to write the list file (.LST - file). A list file is created every timea data-file is read. The error is usually cased by disk error (no empty space)

ERR. 36 SINGULAR MATRIX (A, B, C)

An error has occurred during the solution of the linear equation system. The numbers a, b and cgives some information of the error (for the programmer).

This error may be caused by very large or very small resistors. Be especially aware of internalsource resistance and internal resistance of capacitors and inductors.

The error may also be caused by some strange data in the data-file. Thus check the data-file forerrors and extreme resistance values.

ERR. 37 NO CONVERGENCE FOR MODULES

This error message is given if the program is not able to find a solution for the terminal voltage andcurrents of a KREAN module.

It is very difficult to say what is wrong. Some possible causes are:

- Too non-linear behaviour.

- The module is working with too large or too small numbers (ex. division by zero).

- Error in the module programming, “non-physical” behaviour.

- Sum of currents is not equal to zero out of module terminals.

- Error in the specified parameters

- Too large time steps compared to the non-linear behaviour. Use HMA control code in data-file.



Because of the very different nature of different types of modules it is not possible to give anygeneral advice on where to look for the error.

ERR. 38 PARAMETER ERROR IN MODULE NNN

The modules can be programmed with parameter check. If an error is detected in the parameter listof module NNN then this message will be given.

(For those familiar to module programming: This is the message given if the module subroutinereturns FLAG=-4 after being called with FLAG=4)

ERR. 39 SPECIFIED HARSTART TOO LOW

The specified start point for a fourier analysis is set lower than the first available time point.Specify a new and larger start time for the analysis (command HARSTART)

ERR. 40 SPECIFIED HARSTART+HARPER TOO LARGE

The fourier analysis uses the time domain results from HARSTART to HARSTART+HARPER(see description of fourier analysis). This error message means that HARSTART+HARPER islarger than the end time of the simulation. HARSTART or HARPER must be changed (commandsHARSTART and HARPER)

ERR. 41 READING INI-FILE

An error occurred while reading a INI-file (after CONTINUE-command). The error may becaused by mismatch between INI-file and corresponding KRE-file. Example: components addedor deleted to the KRE-file after last saving on the INI-file.

It can also be caused by disk error.

ERR. 42 WRITING TO INI-FILE

An error occurred while writing the INI-file. The error is usually caused by a disk error (no space,write protection etc.). Example: Components have been added or deleted to the KRE-file since thelast saving on a INI-file.

ERR. 43 OPENING FILE FOR SPECIAL OUTPUT

An error occurred when the program tried to open a file for special output (debugging purposes)

ERR. 44 WRITING TO STA-FILE

An error occurred when the program tried to write special output (debugging purposes)



ERR. 45 ILLEGAL STATE OF SWITCH SPECIFIED

The user has specified an illegal initial condition for a switch or diode. Thus, check all specifiedINIT-parameters in the datafile. They should all be 0 or 1 (zero or one).

ERR. 46 ERROR READING COMMANDS

Some error occurred when reading a command. Check the manual and/or try again.

ERR. 47 WRITING TO ANA-FILE

Problems occurred while writing to ANA-file (fourier results). Usually caused by disk problems(no empty space or write protection).

ERR. 48 MODULE “XXX” IS NOT LINKED

The module “XXX” is not linked to the KREAN version in use. This message is given if the userhas specified the use of a KREAN module not linked to the program. Not all modules are linked toall KREAN versions.

Note that the error can be caused by misspelling in the datafile (misspelling in the type of module).

For those programming their own modules: Check if the subroutine name is equal to the file nameof the subroutine and also equal to the type of module specified in the datafile.

ERR. 49 ILLEGAL INTEGER PARAMETER

A non-integer command parameter was specified, while an integer parameter was expected by theprogram.

ERR. 50 READING INTEGER PARAMETER

Some error occurred while reading an integer command parameter.

ERR. 51 ILLEGAL REAL NUMBER PARAMETER

A non-real command parameter was specified, while a real parameter was expected by theprogram.

ERR. 52 READING REAL NUMBER

Some error occurred while reading a real number command parameter.



ERR. 53 OPENING RUN-FILE

The program could not open a file for simulation statistics (.RUN-file). This may be cased by diskerror (no empty space or write protection)

ERR. 55 NOT ENOUGH MEMORY FOR SPECIFIED ANALYSIS

The program does not have enough memory for the specified ANALYSIS. Try to select fewercurves or reduce the number of harmonics to be calculated.

ERR. 56 UNDEFINED SYMBOL OR VARIABLE FOR SUB-CIRCUIT IN DATAFILE

There is a missing symbol definition in the datafile (program have found a @nnnn but nocorresponding “SYM @nnnn” definition.

It may also be a missing variable in a sub-circuit call.

ERR. 57 OPENING PRE-FILE

The program could not open a file for “pre-compiled” datafiles (.PRE-file). This may be cased bydisk error (no empty space or write protection).

ERR. 59 WRITING TO PRE-FILE

An error occurred while writing to a .PRE-file. This may be cased by disk error (no empty space orwrite protection). It can also be some strange error in the datafile.

ERR. 60 READING KRE-FILE, SEE PRE-FILE

This message usually means that there were some syntax error in the datafile. See the end of the.PRE-file for more details about what went wrong.

Every datafile read by the KREAN program is “pre-compiled”. This pre-compiling replacessymbols and sub-circuits. A file with the same name as the datafile, but with extension .PREinstead of .KRE shows the results of this pre-compiling. At the end of the .PRE-file there willusually also be an error message.

ERR. 61 INDUCTANCE TOO LOW

This message means that the user has specified at too low inductance.

ERR. 62 CAPACITANCE TOO LOW

This message means that the user has specified at too low capacitance.

Page 11- 10 11.3. The warning messages


ERR. 63 RESISTANCE VALUE TOO LOW

This message means that the user has specified a too low resistance.

Note that many models have resistors as part of the model. These resistor values can not be toolow. Thus, this error message may not be caused by a resistor component, it can also be caused bythe serial resistor of, for example a voltage source that have been given a too low resistance. Seethe model descriptions for details.

ERR. 64 OPENING SUB-CIRCUIT FILE

The program could not find or was not able to open a sub-circuit file. The usual error ismisspelling of sub-circuit name and missing/wrong directory specification for sub-circuits in thedatafile.

The directory of sub-circuits must be specified in the datafile (control code DIR).

ERR. 65 OPENING .LST-FILE

The program could not open a file (.LST-file) for listing on how the program understood thedatafile . This may be cased by disk error (no empty space or write protection).

11.3 THE WARNING MESSAGES

WARN. 1 NO PLOT CODES SET IN DATAFILE

There were no plot codes set in the datafile. It is therefore meaningless to simulate this circuitalthough it is still possible. No results will be available after the simulation.

WARN. 2 SIMULATION STOPPED, TYPE GO TO CONTINUE

The simulation was stopped by the user. It may be continued by a GO command.

WARN. 3 PROGRAM HAS CHANGED Y-SCALING

The scaling set by the user was illegal (YMIN greater than YMAX). The program has chosenanother one (YMIN=-100 and YMAX=100).

Use command AUTOMATIC_SCALING to get automatic y-scaling.

11.3. The warning messages Page 11- 11


WARN. 4 PROGRAM HAS CHANGED X-SCALING

XMIN was specified larger than XMAX. The program has changed XMIN and XMAX such thatthe whole simulated interval is plotted instead.

WARN. 5 AUTOMATIC SCALING IS NOW TURNED OFF

The automatic scaling is automatically turned off if the user uses the commands YMIN andYMAX. This message is given to inform the user. Use the command AUTOMATIC_SCALING toturn on automatic y-scaling again.

WARN. 7 ONLY ONE TERMINAL CONNECTED TO NODE NN

This means that there is a node called NN in the circuit to which only one component terminal isconnected. A warning message is given because it is unusual (still allowable) to have one node towhich only one terminal is connected.

It may be caused by misspelling of one ore more node names.

WARN. 8 CORRESPONDING DATAFILE NOT FOUND

The datafile corresponding to a result file was not found.

WARN. 9 SOME PLOT CODES WERE IGNORED

The number of plots specified in the datafile was larger than the maximum allowed. The last plotcodes were therefore ignored. The simulation can be carried out, but not all specified plots will beavailable after the simulation.

WARN. 11 ALL WINDOWS WERE DEFAULT, WINDOWS 1 USED

This message means that all windows were selected as default for plot layout 0 (single plot). Seecommands LAYOUT and WINDOW.

Default window after this warning will be window 1. Thus all scale commands etc. will work onwindow 1 only until a new WINDOW command is given.

WARN. 12 ITERATION TOLERANCE INCREASED

This message means that there are convergence problems in the iteration of KREAN moduleterminal currents and voltage. The iteration tolerance is increased automatically in order to be ableto solve the equation. Thus the results may become less accurate after this message have beengiven. The default tolerance is very low. Thus the results may be very accurate even if thiswarning is given.

The .RUN file written after the simulation shows the final tolerance used in the simulation.

Page 11- 12 11.3. The warning messages


WARN. 13 LENGTH OF PLOT ARRAY EXCEEDED

This message means that there is no space left for storage of results. The amount of storageavailable depends on the way the program is installed (see installation description).

There are several ways of reducing the memory needed for storage of results:

- Reduce the number of plots stored (change plot codes in the datafile)

- Use control code PPF in datafile (possible to store for instance every second time step)

- Use control codes SMI, SMA in the datafile (only part of the time domain results are stored)

- Use command EMPTY_PLOT_ARRAY to delete all results and then continue the simulation

- Change the plot array parameter in the installation of the program

12. File extensions Page 12 - 1


12 FILE EXTENSIONS

This chapter gives a summary of the information found in the files which are used and created bythe KREAN program. The user creates the *.KRE file. When KREAN creates a file, the name ofthe file will be the same as for the KRE-file, except for the the file name extensions. Theextensions used are:

.KRE Input datafile. The circuit and control data for the simulation specified in the.KRE-file.

.PRE The “pre-compiled” input datafile. This file shows the .KRE-file after theprogram has included sub-circuits and substituted symbols. In this file it ispossible to check if symbols and sub-circuits have been correctly interpreted.Possible error messages are found at the end of the file.

.LST The list file shows how KREAN has interpreted the input datafile. In this fileit is possible to check if the datafile has been correctly understood. Possibleerror messages are found at the end of the file.

.RUN The RUN-file contains statistics from the simulation (size of equationsystem, number of iterations, number of switchings etc.). In some cases thisfile may give valuable information during the search for errors.

.ANA The results of the fourier analysis are written to the ANA-file (mean-,maximum-, minimum-, rms-values, harmonic rms-values etc.)

.RES The RES-file contains formatted results which can be read by KREAN or bysome text editing program.

.RUF The RUF-file contains un-formatted results which can be read by theKREAN program only.

.MAT The MAT-file contains formatted results stored on a “matrix” format. Thisfile can not be read by KREAN, but Matlab, Lotus, Excel etc. can import thisfile.

.MAC Macro command file. The setup for curves, scaling of axis etc. are written toMAC-files. These are automatically read the next time the same datafile isread. Alternatively, the user creates the MAC-file in a text editing program.

.INI Initial values to be used in continued simulation (final values of statevariables and switch states).

Page 12 - 2 12. File extensions


13. Limits Page 13 - 1


13 LIMITS

The following list shows some important limits for the KREAN program.

Maximum number of components in one circuit 600Maximum number of each type of component 150Maximum number of state variables 300Maximum number of nodes 300Maximum number of module terminals 300

Maximum number of curves stored in each simulation 32Maximum number of selected curves for plotting 12Size of result array Optional (see installation)

Maximum number of harmonics to calculate 1000Maximum number of curves selected for Fourier analysis 12

Page 13 - 2 13. Limits


14. Changing default values Page 14 - 1


14 CHANGING DEFAULT VALUES

14.1 INTRODUCTION

Control codes for use in the KREAN input datafile were presented in chapter 5. There are howevermore control codes available. These are for more special purposes, typically if one wants tochange the default values used when a parameter is not specified or if a * is placed in a parametersposition. The special purpose control codes are described in this chapter.

The syntax of the special purpose control codes is a three character code consisting of the letter Dfollowed by two integer numbers (D11, D03 etc.). After the three character code follows a“number” parameter which are the new default value to use.

The codes presented here can be used in any KREAN datafile (KRE-file).

14.2 THE DATAFILE SYNTAX FOR DEFAULT SETTINGS

Maximum change in time step lengths

This code can be used for specification of the maximum change in the length of a time-step. Thedefault is that the next time step to use is maximum 100 times larger than the previous. TheNumber parameter gives the new limit.

Default time constant for L and C

This code can be used for specification of the time constant used to calculate the default resistanceof capacitors and inductors. The default is a time constant of 1.0E-9 seconds. The Numberparameter specifies the new time constant.

D02 Number

D04 Number

Page 14 - 2 14.2. The datafile syntax for default settings


Parallel resistance of current sources

This code can be used for specification of the default parallel resistance of current sources. Thedefault is 10000 Ohm. The Number parameter specifies the new default resistance.

Serial resistance of voltage sources

This code can be used for specification of the default serial resistance of voltage sources. Thedefault is 0.001 Ohm. The Number parameter specifies the new default resistance.

Parallel resistance of transformers

This code can be used for specification of the default parallel resistance of primary windings ontransformers. The default is 10000 Ohm. The Number parameter specifies the new defaultresistance.

On-state resistance

This code can be used for specification of the default on-state resistance of diodes, switches andthyristors. The default is 0.01 Ohm. The Number parameter specifies the new default resistance.

Off-state resistance

This code can be used for specification of the default off-state resistance of diodes, switches andthyristors. The default is 10000 Ohm. The Number parameter specifies the new default resistance.

D05 Number

D06 Number

D07 Number

D09 Number

D10 Number

14.2. The datafile syntax for default settings Page 14 - 3


Maximum default parallel resistance of inductors

This code can be used for specification of the maximum default parallel resistance to be used forinductors. The default parallel resistance of inductors is automatically chosen such that the timeconstant becomes equal to 1.0E-9 second. However, the default resistance used is a maximum of1E6 Ohm. This limit can be changed by the D11 control code. The Number parameter specifiesthe new limit.

Minimum default serial resistance of capacitors

This code can be used for specification of the minimum default serial resistance to be used forcapacitors. The default serial resistance of capacitors is automatically chosen such that the timeconstant becomes equal to 1.0E-9 second. However, the default resistance used is a minimum of1E-6 Ohm. This limit can be changed by the D12 control code. The Number parameter specifiesthe new limit.

Serial resistance of transformers

This code can be used for specification of the default serial resistance of primary windings ontransformers. The default is 1E-4 Ohm. The Number parameter specifies the new defaultresistance.

Turn-off level for voltage controlled switches

This code can be used for specification of the default turn-off control voltage level (Uc,off) forvoltage controlled switches and thyristors. The switches turns off if the control voltage goes belowthis level. The default is 0 Volt. The Number parameter specifies the new default turn-off voltagelevel.

D11 Number

D12 Number

D13 Number

D16 Number

Page 14 - 4 14.2. The datafile syntax for default settings


Turn-on level for voltage controlled switches

This code can be used for specification of the default turn-on control voltage level (Uc,on) forvoltage controlled switches and thyristors. The switches turns on if the control voltage goes abovethis level. The default is 1E-3 Volt. The Number parameter specifies the new default turn-onvoltage level.

Default reverse recovery current

This code can be used for specification of the default reverse recovery current for diodes andthyristors. The default is 1E-4 Ampere. The Number parameter specifies the new default reverserecovery current.

Turn-on voltage for thyristors and diodes

This code can be used for specification of the forward voltage needed before a diode or thyristorturns-on (Uturn-on). The default is 1E-3 Volt. The Number parameter specifies the new defaultforward voltage for turn on.

Error tolerance for module iterations

This code can be used for specification of the error tolerance when non-linear module terminalsare iterated together with the linear circuit. The default is 1E-8 (Volt or Ampere). The Numberparameter specifies the new tolerance.

D17 Number

D18 Number

D23 Number

D26 Number

Index Page I


Aall 9-14analyse 9-3application examples 2-11auto.mac 7-4auto-scaling 9-10axis 9-9

Bbar diagram of harmonics 8-7bi-directional switch 6-26, 6-29black-and-white 9-10boarders 9-10

Ccall to a sub-circuit 10-4cap 6-5capacitor 6-5changing default values 14-1characteristics krean 2-2circuit specification 4-2clipboard 9-1clock 7-1cnt 6-10colours 9-10command parameters 9-1commands 9-1comment lines 4-2component names 6-1computational speed 2-3con 6-40continue 9-3control codes 5-1controlled sources 6-17cts 6-17current controlled current source 6-17current controlled voltage source 6-17current source 6-10

Ddata 9-7data-file for the simulation 3-3datafile syntax 4-1defaults for plot set-up 7-4define sub-circuits 10-1density 9-11dio 6-23diode 6-23dir 5-12directory for sub-circuits 5-12directory of sub-circuits 10-4display commands 9-9draw 9-2, 9-2draw harmonic bar diagram 9-3

Eempty-plot-array 9-5end time 5-3err 5-4err 9-11error messages 11-1error tolerance 5-4error tolerance for module iterations 14-4example of a datafile 4-3execute commands 9-2exit 9-2expand 9-13

Ffigure text 9-14file commands 9-7file extensions 12-1format of numbers 4-3fourier 9-9fourier analysis 8-5fourier analysis commands 9-16fundamental period 8-5

INDEX

Page II Index


Ggetting started 1-1go 9-2grid 9-10

Hhardraw 9-3harmax 9-16harmin 9-16harmonic distortion 8-8harperiod 9-16harplot 9-3harstart 9-16history of krean 2-1hma 5-6hmax 9-11

Iideal short 6-40inc 5-14including other datafiles 5-14ind 6-7inductor 6-7ini-file 7-3initial transients 2-3

Kkeyboard commands 9-1keyboard short-cut 9-1kre-file 12-1

Llayout 8-2layout 9-12left 9-13limits 13-1local node names 10-3locus plot 8-4locus plot commands 9-15lst-file 7-2, 12-1

Mmacro 9-6matrix format results 8-12

maximum number of components 13-1maximum number of nodes 13-1maximum time step length 5-6mean value 8-8mo2 6-43mod 6-43modelling 3-2models 6-1modules 2-8, 6-43mouse menu commands 9-1

Nnested sub-circuits 10-4node names 6-1number of harmonics 8-5numerical solution methods 2-14

Ooutput of the program 2-5

Pper unit plot 8-3phi parameter 6-46plot 9-2plot codes 6-1plot harmonic bar diagram 9-3plotting point factor 5-11points 9-10post-processing 2-5ppf 5-11pre-file 7-2, 10-6, 12-1pu-plot 9-10

Rread-results 9-8reconstructed curves 8-9references 2-16refresh 9-5reload 9-7res 6-3resistor 6-3result analysis 8-1result file 8-12result presentation 8-1

Index Page III


right 9-13root-mean-square 8-8run-file 7-3, 12-1

Ssave 9-7scaling of axis 8-2select 9-3settings 9-10set-up-plot 9-9short 6-40simultaneous plotting 7-2simultaneous-plot 9-10single line 10-8sma 5-10smi 5-10start time 5-2statistics 7-3status 9-9stop a simulation 7-2sub 6-41sub-circuit file 10-1sub-circuits 10-1sw1 6-26sw2 6-29switch 6-26, 6-29, 6-32, 6-36sym 5-8symbols in datafiles 5-8

Ttext on figures 9-14th1 6-32th2 6-36three phase sub-circuits 10-8thyristor 6-32, 6-36time constant for l and c 14-1time domain plots 8-1time-on-plot 9-10tlow 9-15tma 5-3tmax 9-11tmi 5-2total harmonic distortion 8-8transformer 6-21

trf 6-21trigger signals for switches 6-48tupper 9-15turn-on voltage for thyristors and diodes

14-4

Uuni-directional switch 6-32, 6-36use a defined sub-circuit 10-4user interface 2-4

Vvar 5-13variable declaration 5-13variable declaration in sub-cir. 10-2voltage controlled current source 6-17voltage controlled voltage source 6-17voltage source 6-13vtg 6-13

Wwarning messages 11-1window 9-12write analysis results 8-7writing time domain results 8-12

Xxaxis 9-15xmax 9-13xmin 9-13xtext 9-14xunity 9-14

Yymax 9-13ymin 9-13ytext 9-14yunity 9-14

Zzoom 9-13

Page IV Index


Date post:	31-Aug-2020
Category:	Documents
Upload:	others
View:	3 times
Download:	0 times

KREAN REFERENCE MANUAL - NTNU Reference Manual.pdf · The Norwegian Institute of Technology...

Documents