USERS GUIDE TO MODELS IN ATP

April 1996

i

ACKNOWLEDGMENTS
The writing of this manual would not have been possible without the participation of the many users of MODELS who, over the years, have contributed suggestions and prompted discussions on many aspects of the language and its use in ATP. These people certainly deserve a large share of the credit for the work that has been done.

USERS GUIDE TO MODELS IN ATP

i

PREFACE
This Users Guide has been written with the purpose of introducing the MODELS language for use with ATP. It is written mostly in a conversational style, as opposed to the more formal descriptions found in the MODELS Language Manual of the ATP Rule Book. The purpose of this guide is to explain how the MODELS language is held together, and to illustrate its usage with discussions and examples. I realize that a manual like this is never done. There are many aspects to using a programming language and to doing simulation. They are best understood through one's own experience and glimpses at the experience of others. We can continue adding examples to this Guide forever. This first version covers the basic aspects of using the MODELS language. The main features of the language are discussed in detail and illustrated with examples. The interface between MODELS and ATP is also discussed at length. What is not included are detailed examples of electrical and control components, descriptions which, in my opinion, are beyond the scope of this introduction. The objective of this manual is to explain the "how" and the "why" of using MODELS. The "what" of the applications belongs to one or more separate tutorials covering those subjects, for the application specialists to provide. As it is true for any tool, how much a program is used depends to a large extent on how much its features are understood. With the usual time pressure of our work, of course we wish to be able to use something like this instantly. Having the time to play with a new tool is a luxury we can't always afford. But one has to realize that any product that took a few years to prepare needs at least a few hours of exposure to it to get the whole picture. I hope that the time looking at this manual will be time well spent. Laurent Dubé, April 1996.

USERS GUIDE TO MODELS IN ATP

. Using MODELS in ATP 7. Writing expressions 4. Basic aspects of the MODELS language 2.. Libraries of models and functions Appendix A – Syntax of the MODELS language Appendix B – Keywords of the MODELS language Appendix C – Pre-defined constants and variables Appendix D – Pre-defined functions Bibliography Index In closing . Writing a model 3. Using a model 6. Specifying simulation directives 5.i OUTLINE Acknowledgments Preface Outline Contents Introduction 1. USERS GUIDE TO MODELS IN ATP .

........................................................................... Names ......................................5....... Basic aspects of the MODELS language .......... Representation of numbers .................9 1......... Defining constant elements.........................7 1........................... Defining input elements ...... iv Introduction ......... MODELS in ATP...1................................... brackets.............................3.........................2........................... Delimiters...........3......... Overall form .............................................................................13 2...............13 2..................................2 1..3.......................................2 1..........2..............................i CONTENTS Acknowledgments ...5........................................ and values ...................1............................. and braces .....3 1....3 1...........................1....21 2........................ Equal sign and assignment sign ....... Limits ..............................................................6 1..... and MODEL .2....1.......................................................................i Preface.......2................................................3....1..................... Kinds of value-holding elements ............. Defining output elements ....................17 2..........1...5.1..........2......1.................................7........1......................5 1.................. What about TACS?......3.......................... Line indentation .....................................................................................................2.......1.......................4......4.................3........ Dependent data values............................1..................2......... Statement functions ........11 1.........13 2........................................3................................................4......8........................2....................... iii Contents.............12 1...1.................1.......3................................... What's particular to MODELS . Starting to use MODELS ...............................2...9 1.......................................................................................6 1...........................1..2...................14 2........................2. Defining data elements ............................................................3.........5......................................................2...........3......... Blank lines ............2. External submodels .................1... Defining the submodels. MODELS..14 2.........................6.................... Comments ....4...................1..............9 1........................................................................... format............................. Foreign submodels ........1......3.........................1.....................15 2............2....................................1...................4 1...........3....................................... Similar to a programming language ......................................................................10 1..... Use of arrays .......................19 2...........................................................23 USERS GUIDE TO MODELS IN ATP ................. and conventions .........18 2..........6..17 2..................................................................................................................3. Defining variable elements... Scalars and arrays...............................................................3......16 2.... Writing a model ............................................................................................................1.............2................3...................1............. Using a data value as an array dimension......................2.............. Defining the value-holding elements ........................2.1.................11 1............................3..............2 1... Locally-defined submodels ............ Reasons for using MODELS in a project ....... Parentheses...................................... Defining the functions.. Value-holding elements............. Why use MODELS..............7.......................12 2........2.1 1.................................8 1............... ii Outline.............................................................9 1...............23 2................ Notation..........10 1....... Model..................6 1.............2 1.........14 2................................11 1..1...............

...............1....... Call to a procedure ........4......5.......4.......5................10...............................2.25 2.... WRITE2() procedure ............... USE statement........................................4....2......6................................................9...........2.........5..............................33 2............26 2.............. WRITE1().....59 3..........5...... Limits ...42 2.............................2.......................28 2.................32 2.........................................2... Implicit IF statement .....5.....................................58 3..............................................29 2....2. Logical and numerical operators......................... DO statement................................5...37 2.....10.......... Values of y at t0.............................................................38 2.46 2................5................34 2..........1.................10.2...... ERROR statement ......55 3. WRITE() procedure .54 3............10...........2..............53 2...5........... History expression assignment ...............................5...................................4.....1.1............ Writing expressions ..3............................................45 2........50 2...........3.... Specifying a numerical value ......................... INIT procedure and HISTORY assignment .......5....1..................................2..................24 2....60 3..2...... Explicit IF statement ..... The EXEC procedure.............. Using the iterated COMBINE for nonlinear equations .11..........5.........3.................. Using the linear COMBINE for linear equations..1...............1............................29 2.......2.....................6.......45 2........................................ The INIT procedure.........................55 3.................. Pointlist functions...2.......................4....... Executing both INIT and EXEC at time zero....................................51 2........................... Writing the procedures ............5........5..................................... Using expressions with arrays .................1...4.................................................... Limits on a regular expression .1.....5.1.............55 3................................................5......... Value assignment statement...1.....62 3.............. Named procedures ...58 3................. Special expressions ....4....5...1..........1...... Writing the statements of a procedure ............................................... Using a value calculated by a procedure ..............5.40 2.2.......... and CZFUN ..... Laplace and z transfer functions ................49 2.........................52 2...........2......................1....................... WHILE statement...5............. IF statement..........62 USERS GUIDE TO MODELS IN ATP ... REDO statement......................43 2...........................................14...... Using a value calculated by a function.........5..........................3......................................................................5..................................3....................................... Using CDIFFEQ......................... CLAPLACE............................5...........40 2..................14............7......... Linear sum ............14..........1...........................................................5.............................................. External point list .... Integral value assignment ......... Initialization..........................30 2..13... Using the linear COMBINE for nonlinear equations.3.................61 3....59 3........2........... Referring to a named value-holding element .................................. Foreign functions ........ Differential equation........53 2..5.................................37 2...32 2.........39 2...............................................................8............................................7..................5....................................28 2...... Numerical solution ............4... COMBINE statement ..........36 2... FOR statement .......2...........1....5....2.......5...............4........................28 2....2.........44 2.37 2.............3...41 2......1...............1.............5...................... Call to a pre-defined procedure ......................... Regular expressions ..........2..........................i 2...........................................5....5.................12.....5....5.......................53 2.....5.................3...........3......

i 3.2.2. Polynomial of derivatives .................................................................63 3.2.3. Integral expression ..........................................................................63 Specifying simulation directives......................................................................66 4.1. Specifying the time step range................................................................66 4.2. Specifying the input interpolation method ...............................................67 4.3. Specifying the size of the delay storage..................................................68 4.4. Specifying history expressions................................................................69 Using a model ................................................................................................71 5.1. Assigning data values .............................................................................71 5.2. Assigning input values ............................................................................71 5.3. Retrieving output values..........................................................................72 5.4. Specifying simulation directives ..............................................................72 5.5. Calling a model more than once per time step........................................73 5.6. State of a model......................................................................................74 Using MODELS in ATP ..................................................................................76 6.1. The MODELS section of a data case......................................................76 6.1.1. Inputs from ATP...............................................................................77 6.1.1.1. Inputs from the circuit ...............................................................77 6.1.1.2. Inputs from a PL4 plot file.........................................................78 6.1.1.3. Inputs from the TACS section...................................................80 6.1.1.4. Inputs from ATP program variables ..........................................82 6.1.2. Outputs to ATP ................................................................................83 6.1.3. Variables in the MODELS section....................................................84 6.1.4. RECORD for printout/plotting...........................................................84 6.1.5. Model descriptions...........................................................................85 6.1.6. MODELS formatting vs. ATP formatting ..........................................87 6.2. Using a model in the MODELS section ...................................................87 6.3. Using a model with the type-94 component ............................................90 6.3.1. Thevenin, iterated, and Norton ........................................................91 6.3.2. Initializing the type-94 component ...................................................94 6.3.3. Foreign models with a type-94.........................................................95 6.4. Using MODELS with ATP's FREQUENCY SCAN...................................96 6.5. Steady-state initialization ........................................................................97 6.6. List sizes in ATP for MODELS ................................................................99 Libraries of models and functions.................................................................100 7.1. Signal sources ......................................................................................100 7.1.1. Examples of some common sources .............................................101 7.1.2. Sample data case ..........................................................................102 7.2. Library of complex-value functions........................................................103 7.2.1. Examples of complex-value functions............................................103 7.2.2. Sample data case ..........................................................................105 7.3. Library of TACS-like devices.................................................................106 7.3.1. TACS type-50 frequency meter .....................................................106 7.3.2. TACS type-51 relay-operated switch .............................................107 7.3.3. TACS type-52 level-triggered switch..............................................107 7.3.4. TACS type-53 transport delay........................................................108 7.3.5. TACS type-54 pulse delay .............................................................108
USERS GUIDE TO MODELS IN ATP

4.

5.

6.

7.

i 7.3.6. TACS type-55 digitizer ...................................................................110 7.3.7. TACS type-56 point-by-point nonlinearity ......................................110 7.3.8. TACS type-57 time-sequenced switch...........................................110 7.3.9. TACS type-58 controlled integrator................................................111 7.3.10. TACS type-59 simple derivative...................................................112 7.3.11. TACS type-60 input-IF component ..............................................112 7.3.12. TACS type-61 signal selector ......................................................112 7.3.13. TACS type-62 sample/hold and track/hold...................................113 7.3.14. TACS type-63 instantaneous min/max ........................................114 7.3.15. TACS type-64 min/max tracking ..................................................115 7.3.16. TACS type-65 accumulator / counter...........................................116 7.3.17. TACS type-66 RMS value............................................................117 Appendix A – Syntax of the MODELS language .............................................118 MODELS section in ATP...............................................................................118 Description of a local model ..........................................................................119 Statement......................................................................................................123 Directive in a USE statement ........................................................................128 Expression ....................................................................................................129 Regular expression .......................................................................................130 Value-holding element ..................................................................................132 Syntactic element..........................................................................................133 Appendix B – Keywords of the MODELS language.........................................135 Keywords of the MODELS section of ATP ....................................................135 Keywords of the Model description ...............................................................136 Keywords of the Statements .........................................................................137 Keywords of the Directives in a USE statement............................................138 Keywords of the Expressions........................................................................138 Keywords of the Regular expression ............................................................139 Keywords of the Comments ..........................................................................139 Appendix C – Pre-defined constants and variables.........................................140 Pre-defined constants ...................................................................................140 Pre-defined global variables..........................................................................140 Pre-defined local variables............................................................................141 Appendix D – Pre-defined functions ................................................................143 Numerical functions ......................................................................................143 1-to-1 functions returning one value for each argument ...........................143 2-argument functions returning a single value ..........................................144 n-argument functions returning a single value ..........................................145 Logical functions ...........................................................................................145 1-to-1 functions returning one value for each argument ...........................145 n-argument functions returning a single value ..........................................146 Random value functions................................................................................146 Simulation functions ......................................................................................148 deriv(x)......................................................................................................149 deriv2(x)....................................................................................................150 prevval(x)..................................................................................................151 delay(x, dval, pol)......................................................................................151
USERS GUIDE TO MODELS IN ATP

i predval(x, tval, pol) ...................................................................................151 predtime(x, xval, pol) ................................................................................152 backval(x, tval, pol) ...................................................................................152 backtime(x, xval, pol) ................................................................................152 histval(x, tval)............................................................................................153 histdef(x)...................................................................................................153 Bibliography ......................................................................................................154 Index .................................................................................................................159 In closing ... .......................................................................................................165

USERS GUIDE TO MODELS IN ATP

what is special about the language. They are built for use as a quick reference to the MODELS language. and the nuts and bolts of its rules and conventions. writing expressions. It includes an explanation of the different declarations that can be included in the MODELS section. Four sections are added as appendices to this manual. with discussions and examples. providing a general presentation of what the language does. The other two appendices show the pre-defined constants and variables. presenting only the structure and the diagrams. without the details of the full syntax rules. The first is a summary reference to the syntax of the MODELS language. without the text. This is then followed by a detailed presentation about using MODELS in ATP.1 INTRODUCTION This manual starts with a discussion of the basic aspects of the MODELS language. USERS GUIDE TO MODELS IN ATP . providing a structured overview of only the keywords of the MODELS language. It condenses the contents of the Language Manual. The text concludes with a discussion and examples of building libraries of models and functions that can be assembled as a toolkit to be used in present and future simulation projects. and how each approach can be used in the simulation of a circuit. Various aspects of using a model are discussed next. and the pre-defined functions of MODELS. This is followed by a more in-depth look at the process of writing a model. Next comes a summary of that summary. and specifying simulation directives in a model. It also describes the different ways in which MODELS is interfaced with ATP.

It can also be used for generating signals or for analyzing measurements from the circuit. MODELS in ATP The purpose of having MODELS available in ATP is four-fold: 1) to have a tool for developing models of circuit and control components which cannot be built easily with the set of existing components available in ATP and TACS. Starting with examples provides an easy exposure to the main aspects of the language as well as. It is a programming language targeted to time-domain simulation. In ATP.2 1. and subroutines of ATP. as opposed to an interface which would be defined at the programming level in terms of the variables. 3) to be able to describe not only how a component operates. access to measurements. BASIC ASPECTS OF THE MODELS LANGUAGE MODELS is a general technical description language supported by a simulation solver. to the finer details of its syntax.1. 1. at any required detail level. 1. but also how the initial state (initial values and initial history) of the component is established. it can be used as the interface between ATP and outside programs.2. Finally. currents. With some guidance at the beginning. or interaction with equipment. 2) to have the flexibility of a full programming language without having to interact with ATP at the programming level. 4) to have a standard program interface to ATP defined at the modeling level in terms of voltages.1. common blocks. and can be used as a base from which modifications can be made to describe more complex operations. Why use MODELS 1. later on. USERS GUIDE TO MODELS IN ATP . and without requiring any modification to be made to the source code of ATP. this makes it possible to connect external programs to ATP for modeling of components. and is used as a tool for describing the dynamic behavior of complex physical systems.1. it can be used for describing the operation of circuit components and of control components. Starting to use MODELS Looking at the MODELS language for the first time can feel like a large task. Many examples are provided with this guide. and control signals. it can be easily divided into simple parts.1. without requiring a programming knowledge of the internal operation of ATP.

and is similar to the structure of other programming languages. expressions. In this regard.the use of various types of variables. Two standard procedures can be defined for each model. . A model is defined independently from the directives and location of where it will be used. and functions.3 1. for example. Overall form The structure of the language is simple.a regular syntax for the use of variables. A model consists of procedures describing how the model operates. MODELS includes the following capabilities: .1.4. for example. Pascal or Modula-2. and directives influencing the operation of the model in a simulation. so that it may be used and read with familiarity. Users who more occasionally apply the language to represent a component or a numerical process. each maintaining its individual operating point and history. The simulation directives include control of the size of the time step used in the model. assignment of history expressions describing the pre-simulation values of some of the variables of the model.3. Similar to a programming language Users who apply the language to develop models of components and to possibly build library of components need sufficient power and flexibility from the description language. variables can be numerical and logical. choice of interpolation method for determining input values at internal substeps. value-holding elements to carry the state and the history of its operation and to exchange information with the outside. Value-holding elements can be constant or variable. arrays. and every construct is introduced by a descriptive keyword. The execution procedure (EXEC) describes how the operation of the model is updated at each successive instant of the simulation. The basic module is called a model. USERS GUIDE TO MODELS IN ATP . Additional procedures can be defined for describing other actions of the model and to access the value of specific variables of the model. There are no formatting rules to complicate its use. The initialization procedure (INIT) describes the initial point of operation of the model before the simulation is started. It has a small number of keywords that can be remembered easily. Multiple instances of the same model can be used.1. Using a programming language approach seemed to fill both types of needs. in either scalar or array form. and can be assigned values from inside the model (types CONST and VAR) or from outside the model where the model is used (types DATA and INPUT). 1. holding values modified by the procedures of the model. need the language to be simple. and allocation of special storage required for the past values of variables referenced in the model using a delay() function.

5. .the use of arbitrarily-long names to facilitate self-documentation. . as an aid to producing models and procedures that are self-documenting. an example would be referring to the time value of an oscillating signal by simply using A*sin(omega*t).a set of pre-defined numerical and logical functions. and use of prototyping during model development. for reduced model complexity. time derivatives. . 1.) for structuring the execution flow of a procedure. this expression automatically takes on the appropriate value at different times of the simulation. . different inputs. in the form of parametrized expressions. without the risk of conflicting with names chosen in other parts of the simulation. time differential equations.time automatically increases during a simulation. from its use in a simulation.expressions can be described as generic functions of the time "t". . .a mechanism for dividing a large component description into smaller units. .individual instances of the models of a system automatically update their operation according to the increasing value of the simulation time.separation of the description of a model. each possibly supplied with different parameters.the use of comments within a description.4 . and externally-programmed functions. for example for initialization. and references to past and predicted values of a variable. . or different simulation directives. What's particular to MODELS Two aspects differentiate MODELS from a regular programming language.1. Laplace and z transfer functions. allowing a clear symbolic representation.the use of conditions and loops (if. while. explicit identification of interfaces and operation.an individual naming scope for each model. to allow the user to assign meaningful names to the variables used in a description.a number of pre-defined time-based functions are available. and maintain their value during the simulation until assigned a different value. . . One aspect is the set of operations and functions needed for the representation of systems that vary in time: . including time integrals. with A and omega being defined elsewhere in the model. USERS GUIDE TO MODELS IN ATP . easier testing. etc.the use of multiple instances of the same component.the values of the variables are persistent over successive instants of time. additional functions can be defined by the user. point lists.the possibility to specify operations that are executed only when some conditions are met. . or when simulation difficulties or errors are detected. . for.

At each time step. as control devices always involve an element of delay in their operation in the real systems. it is possible to control the value of an impedance in the circuit without adverse effects due to the delay (for example. Depending on the size of the time step and on the nature of the simulated system. this delay provides satisfactory results. Any feedback loop involving a nonlinear device is automatically cut open so it can fit in the linear matrix solution of TACS. effectively inserting delays of one timestep on the outputs of such nonlinear devices. passing measured values from the circuit to TACS. the user is not limited to a pre-defined set of components. No iteration mechanism is provided.6. the consequences of this approach can range from satisfactory to numerically unstable.1. When TACS is used for representing control system components. the circuit is first solved completely. 1. in contrast with TACS. The interface between TACS and the simulated circuit is a unidirectional information-type interface. The time-based functions of the language all have direct access to the past values of a variable. USERS GUIDE TO MODELS IN ATP . as needed during the execution of the simulation. as in the case of using a Norton equivalent to represent an inductance using bilinear transformation. What about TACS? TACS had been designed to represent mostly-linear control systems described in the form of a block diagram. depending on the size of the time step and on the nature of the simulated system. unless the injected currents or voltages are strictly history values calculated from a past state of the simulation. without imposing on the user the task of specifying how that information is stored and accessed. it was not designed to accommodate operations represented by algorithms. this arrangement ranges from satisfactory to numerically unstable. Similarly. TACS doesn't provide a mechanism to solve sets of nonlinear simultaneous equations. Finally. TACS allows the user to assemble a description of a control system using a set of pre-defined function blocks and devices. However. However. Again. representing an arc by controlling the value of a resistance). but can build libraries of components and submodels as required by different applications. as needed for the calculations. measured values are passed to TACS.5 The other aspect is that MODELS automatically manages the storage and retrieval of the history values of the variables of a model. although we can achieve some measure of conditional assignments by using type-60 and type-61 devices. then TACS is solved and its outputs applied to the circuit at the next time step of the simulation. and control variables from TACS to the circuit. using a control signals to inject currents or voltages intended to represent the true power connection of a circuit component is typically not a stable proposition.

variables.1. stoptime. inf. closed.2.for values global to all instances of one model: .when we need a component to be solved simultaneously with the rest of the circuit. avoiding the one-step delay otherwise imposed by TACS.when we need to do incremental development of the various parts of the simulated system. starttime. 1. we can do some of this in TACS. yes.for values global to a simulation (i.global numerical constants: pi.e. .when we want to include the representation of elements of the system that are already developed and available as separate subroutines written in a different program.when we have to develop from scratch the modeling of some of the components of the system.constants . . undefined . Value-holding elements. .global logical constants: false. in the case that they could not be easily represented by using what's already available in ATP. Kinds of value-holding elements If we sort the types of value-holding elements according to the value held by each named element.global variables: t.data.1. Reasons for using MODELS in a project Here are some of the reasons why it may be beneficial to use MODELS in a project: . we have: . resident variables If we look at the value-holding elements in terms of where we specify the expressions used for calculating their value. to all model instances of all models): . and values 1.6 1. prototyping individual elements as we go.2. .for values local to each instance of a model: . but MODELS provides a full algorithmic description language that can simplify the work.when we need to include multiple or detailed aspect of the operation of some of the elements of the system. we can note the difference between model definition and model use: USERS GUIDE TO MODELS IN ATP . off true. an example might be using a model supplied by the manufacturer of a particular element. on . startstep .7. inputs. no. open. for example representing the thermodynamic behavior in conjunction with the electrical behavior.

.use expression of inputs If we look at the value-holding elements in terms of where they are visible. specified in the USE statement: .use expression of data .7 . d2. Scalars and arrays Value-holding elements in a model can be declared as individually-named scalar elements: DATA d1. 1. and inputs are certainly as variable as the variables. d3 VAR y10.3] VAR y[10. y11.2. and names that are visible outside the model where they are declared: Type constant data variable input output Access private public private public public Where value is specified model definition default value in model definition local value in use instance model definition default value in model definition local value in use instance local value in use instance The naming of the types is not perfect. specified in the model definition: value expression of constants default expression of data default expression of inputs all value assignment expressions of variables . They are identified by separate type names to underline their difference of being public or private with respect to the model where they are defined. in the sense that data are as constant as the constants. y12 or as elements grouped in array form: DATA d[1..in expressions local to each instance of a model.12] The elements of an array can be declared using an index range: USERS GUIDE TO MODELS IN ATP . we can see the difference between names that are private to a model.in expressions global to all instances of a model.2.

1. and also contributes to reducing the execution time of the simulation. numerical operators can be applied to Boolean values and vice versa).3...12] := d[1.6]) In the few circumstances where a group of array elements cannot be used as a range..7] 1..6] := fire[1. After being declared....3] -vm[1. Use of arrays Array elements can be grouped by range inside numerical and logical equations: vbr[1. inside array-value expressions: y[10.. USERS GUIDE TO MODELS IN ATP .0 or 1.3] or individually (useful for inserting separate comments for each): DATA d[1] d[2] d[2] -...3] gate[1.2.8 DATA d[1. -.6] := abs(w[1.the value of a Boolean operation or conversion is 0. for example on the left side of a Laplace assignment..2.3] + k[5. array elements can be used separately: y[10] := d[1] + k[5] y[11] := d[2] + k[6] y[12] := d[3] + k[7] or they can be used in a group defined by range.4. it is still possible to use an indexed array notation inside a FOR structure. Some observations follow: ...0 in doubleprecision (note that in MODELS..... as in the following: FOR i=1 TO 3 DO laplace(y[i]/x[i]) := (s_polynomial)/(s_polynomial) ENDFOR The use of an array notation can simplify the description of a model.6] AND flag>0 as well as when specifying function arguments: wabs[1.some descriptive comment -. Representation of numbers All quantities inside a MODELS simulation are represented as double-precision floating point numbers.3] := vk[1.

9 . The upper case singular form MODEL is the keyword that starts a model description.5. to the left and to the right.all operations involving some kind of value comparison automatically include a round-off multiplier of 10-8. When a value is assigned to a named value-holding element. and expressions. we use the word model written in regular lower case. and conventions 1. in the sections on COMBINE. Equal sign and assignment sign A distinction is made in the MODELS language between value assignment and value equality. the result of an expression is internally rounded to the nearest integer. MODELS. max: amax} y := integral(x) {dmax: 3*a} laplace(y/x) := (s_numerator)/(s_denominator) {dmin: ymin*cos(omega*t)} 1. integrals. Limits Values are specified in expressions. each expression can be qualified by a minimum value and a maximum value.2.1.2. we use all upper case characters for the word. format. In addition. Value assignment is an action. These limits are themselves described using an expression which may vary in value during a simulation. for example: USERS GUIDE TO MODELS IN ATP . the assignment operation is expressed using ":=".3.when used as index to an array. . 1. Model. where margin = b times 10-8 : a>b a=b a >= 0 is calculated as is calculated as is calculated as a > b+margin a >= b-margin AND a <= b+margin a >= 0 (because margin=0) 1. and MODEL When referring to the MODELS language. Notation.3. Limits are discussed in more detail below. Examples. which means that the granularity of any point value is 10-8 times its value. a := 3*b -c {min: amin. anywhere on the number line. When referring to a model description written in the MODELS language. Value assignment is identified by the assignment operator ":=".3. differential equations and transfer functions.both rounding and truncation can be forced inside an expression using the functions round() and trunc(). .

and braces The left and right parenthesis characters "(" and ")" are used to enclose the arguments of a function.3. for example: IF a = b THEN . In this case. without any space. Parentheses.. vc-va] The left and right brace characters "{" and "}" are used to identify some attribute.n]) The brackets can also be used by themselves inside an expression to indicate a grouping of values into an array value: vpp[1. It is used as a logical relation in a logical expression. like default value. In this case. For example: INPUT va { v(NODEA) } CONST twopi { val: 2*pi } DATA freq { dflt: 50 } FUNCTION windspeed FOREIGN { ixarg: 2 } USERS GUIDE TO MODELS IN ATP . the left bracket must immediately follow the function name.. limit value. argument count. They can be used with an array name to identify elements of that array: wabs[1. delay_value) integral(w) := expression laplace(x1/x2) := (1|s0) / (1|s0 + tau|s1) histdef(integral(y2)) := 2*histdef(y1) The parentheses can also be used by themselves inside an expression to designate a sub-expression: y := a -(2*b -c) The left and right square bracket characters "[" and "]" are used to identify an element or a range of elements of an array. brackets. the left parenthesis must immediately follow the function name. etc. ENDIF 1.. without any space..3. vb-vc.10 w[2] := expression or laplace(y/x) := (s_numerator)/(s_denominator) Value equality is identified by the equality operator "=". Value equality is a condition that can be true or false.3] := [va-vb.. type. For example: y := delay(x1.n] := abs(w[1.

there is no need to start blank lines in the MODELS section with "C ". For example. Keywords of the language are typically written in capitals for readability. separate from ATP.3. An in-line comment starts with a string of two or more hyphens. and values terminate at the first character that is not a legal value character. necessary for indicating comment lines in the rest of ATP.3. but not for distinguishing two names of the same spelling. with the restriction that a name must start with a letter.3. Explicit end delimiters are keywords that indicate the end of a construct.5.3. Names are not case-sensitive. This can be used to annotate a model. The first is to choose names that are appropriately descriptive of the value or function they are representing.7. An implicit delimiter is what is used for indicating the end of a name. USERS GUIDE TO MODELS IN ATP . and the underscore character "_". This means that some kind of end delimiter indicates where a construct ends. The other is the liberal use of in-line comments and block comments. 1. Names Names can be composed using any combination of letters. Among other things. but this is not necessary for interpretation by the parser. all constructs of the language are self-delimiting. operator. Comments Two aspects contribute to making a model understandable. A block comment is a block of text starting with the keyword COMMENT and ending with the keyword ENDCOMMENT. Blank lines MODELS has its own syntax rules. and will be interpreted as a minus sign. or value. and automatically terminates at the end of the line. Upper and lower case can be used for readability. it allows the insertion of white space anywhere in the MODELS section. whether implicitly or explicitly. 1. for example. Hyphens are not permitted inside a name. ENDMODEL or ENDIF.4. Delimiters From a parsing point-of-view.6. So. 1. or to temporarily block out a part during model development or testing.11 1. names terminate at the first character that is not a recognized name character. including blank lines and tabs. for example. keyword. digits.

8.12 MODEL m1 comment --------------------------------------------------| This is a block comment describing this model | | (the vertical bars and the hyphens are only decorative) | -----------------------------------------------.3. There are no pre-defined formatting rules imposed by the language. USERS GUIDE TO MODELS IN ATP .this is an in-line comment describing this variable 1. However. the use of tabs is often counter-productive if a model description is to be viewed on different text editors treating tabs in different ways. Indentation rules are therefore a matter of arbitrary style.endcomment VAR a -. Line indentation Line indentation in the form of tab or space characters can be used to increase the readability of a model description.

256]} There is a set of constants that have pre-defined names and values. data. and.. variables.8] {val: [1.1. They can be used without needing to be declared: USERS GUIDE TO MODELS IN ATP . if an array. data. by means of simulation directives specified in the model definition and in the USE statements introducing each instance. 2. output. and that do not vary during the simulation. in the declaration. variables. The value of a variable or input can vary in time. Defining constant elements Constants are used for holding values that are defined inside the model. The use of each model and submodel can be customized for each use instance. The value of a constant or data is constant in time. identified by type. and outputs). and range of these elements must first be declared in a model before they can be used.1. Various types of statements are available for representing how a value is calculated and assigned. The type.4. The names of the CONST elements are only visible inside the model where they are declared. Defining the value-holding elements Each model can contain any number of value-holding elements.128. input. Their value is assigned inside the model. and by a description of how these values are calculated and used.1. inputs.16.32. Submodels and functions can also be defined to carry out some of the calculation of these values.13 2. The same value is used in all use instances of the model. name.8.2. CONST twopi {val: 2*pi} CONST power_of_2[0. the names of data and inputs are public (although they can be assigned private default expression).64. Procedures contain the statements where these values are used and assigned. In summary. These declarations are grouped in a model by type: constant. WRITING A MODEL This section introduces the elements used when building a model description of something. name. The dynamic operation of a model is represented by the named elements that hold the values used in and created by the model (constants. 2. The names of constants and variables are private (can't be referenced in the USE statement). range of array indices.

2.a dimension assigned differently in each use instance -. typically 1020 the special value 88888.14159. A default value can also be optionally assigned inside the model. in the declaration. DATA n DATA freq {dflt: 50} -. The names of the DATA elements are visible inside the model where they are declared.88888 the value 0 the value 1 . off true. Using a data value as an array dimension A data value can be used in the expressions defining the range of indices of an array.2..2. Their value is constant over the full length of a simulation. Their value is assigned in the USE statements. and that do not vary during the simulation.false.. open. on 3.pre-defined numerical constants: . Defining data elements Data are used for holding values that are defined outside the model..n] -. closed.1.a variably-dimensioned input -.1.2.pre-defined logical constants 2.1. DATA n INPUT vterm[1. Data values are automatically calculated in the USE statement the first time the use instance is called.n] VAR vtmax[1. and also in the USE statements defining instances of the model. yes.a variably-dimensioned variable 2. Different values can be used in different use instances of the model. When a default value exists for a data element. DATA values do not vary in time. Dependent data values If we declare what should be a dependent data value (one that depends on the value of another data) as DATA in order to assign it a default value. we risk that it be reassigned an erroneous value in a USE statement. no.14 . This can be useful for dimensioning an array to just the size needed in an application.providing a default value Data elements are typically used for parameters and dimensions that can be assigned a different value in different use instances of the model..inf .an array dimension -.2.1.undefined .pi .an array dimension used in the model -. a large value. For example: DATA n DATA n2 {dflt: n*n} -. Once assigned.another array dimension USERS GUIDE TO MODELS IN ATP . assigning that element a value in the USE statement is optional.

Their value is assigned in the USE statements. -.. Input values are automatically re-calculated in the USE statement each time the use instance is called. and that vary during the simulation..15 This is because it's inadvertently making public a name that is really private to the model. and then assign its value in the INIT procedure in function of the data value it depends on. INIT omega := 2*pi*freq . this is unavoidable.1. Defining input elements Inputs are used for holding values that are defined outside the model.another array dimension .. INIT IF n2<>n*n THEN ERROR write('Some error message.. When a default value exists for an input element. When the data is not needed as the dimension of an array.') STOP ENDIF .value of measured terminal voltages -. and also in the USE statements defining instances of the model.n] vref {dflt: 0} -.value of measured terminal voltages -. =0 if not used USERS GUIDE TO MODELS IN ATP . it's better practice to hide it to the outside by declaring it as a variable.. For array dimensions. with the value of n determined at simulation time as a data in the USE statement: DATA n INPUT vterm[1..3. The above example of a 3-terminal model can be replaced with a model designed for n terminals... INPUT vterm[1.a frequency in Hz -. DATA n -.an array dimension DATA n2 {dflt: n*n} -..3] vref {dflt: 0} -.. assigning that element a value in the USE statement is optional.the equivalent frequency in rad/sec it would be safer to use: DATA freq {dflt: 50} VAR omega .value of a reference voltage.a frequency in Hz -. For example.value of a reference voltage. A default value can also be optionally assigned inside the model. instead of doing: DATA freq {dflt: 50} DATA omega {dflt: 2*pi*freq} -. in the declaration. =0 if not used Arrays of inputs can be variably dimensioned..the equivalent frequency in rad/sec 2. and at best could be checked for consistency in the INIT procedure of the model..number of terminals -. The names of the INPUT elements are visible inside the model where they are declared.

ENDINIT EXEC .initialize overall tracked maximum value . except when they are declared as OUTPUT (see section below). one could track the input voltages for maximum amplitude for each terminal. Defining output elements Variables can be declared as OUTPUT of a model. statements describing how to do that can be included in the EXEC procedure of the model... and the maximum for all terminals.. vtmax[1. Defining variable elements Variables are used for holding values that are defined inside the model. =0 if not used tracked maximum absolute value of each terminal voltage tracked maximum absolute value of all terminal voltages To update the value of these variables during the simulation. Let's define the variables vtmax[ ] and vmax: DATA n INPUT vterm[1. To continue the previous example.1. until it is assigned a new value. No other variable is visible outside the model.n] vmax -----number of terminals value of measured terminal voltages value of a reference voltage.. The names of the VAR elements are only visible inside the model where they are declared.n]:=0 -. Their value can be assigned in any statement inside the model. and that vary during the simulation. vtmax[1...n]) -.. a variable maintains that value during the simulation. in the section on "Writing the statements of a procedure".. Once assigned a value.for each terminal vtmax[i]:= max(vtmax[i].16 2. Continuing the above example.update overall tracked maximum . 2.1. as shown here: USERS GUIDE TO MODELS IN ATP . the values of vtmax[ ] and vmax can be specified as output of the model.initialize tracked maximum values vmax:=0 -.4. let's say.. with initialization in the INIT procedure.update tracked maximum ENDFOR vmax:= max(vmax... The names of variables declared as output are made visible to the USE statements defining instances of the model.n] vref {dflt: 0} VAR vtmax[1. ENDEXEC Various other ways of assigning values to variables are described in more detail in this manual.. abs(vterm[i])) -.5. FOR i:=1 TO n DO -. for example: INIT .

each one maintaining its own separate state of operation. and without modifying the state of the model in which it is defined. For a given set of arguments. with its description inserted locally in the declarations of the calling model. except for the fact that it is declared and used inside another model. Locally-defined submodels This is the standard way of introducing a submodel. A submodel is a full model of its own. and by a description of how these values are calculated and used.. When used as a submodel inside another model. How do we select to represent something as a model rather than defining it as a procedure or a function? A function has the characteristic of an expression. Functions don't need that kind of storage.. This is declared in the calling model as an external submodel. 2.1. This is the locally-defined submodel. each holding the description of a specific aspect of what is being modeled. A model has both value holders. as there is nothing to store between calls.. written in any language. vmax number of terminals value of measured terminal voltages value of a reference voltage. Once it is declared. to represent the state of operation of what is modeled.n] -vmax -OUTPUT vtmax[1. Procedures use the existing storage of the model where they are defined.n]. modifying and making reference to values held in the model. without holding any state to be used by future calls to the function. =0 if not used tracked maximum absolute value of each terminal voltage tracked maximum absolute value of all terminal voltages -. and accessed through the programming interface of MODELS. A local or foreign model can possibly be described outside the calling model where it is used.n] -vref {dflt: 0} -VAR vtmax[1. This representation can be decomposed into a hierarchy of models. to act on that state. a model can be written in the MODELS language.can be used as outputs of the model 2. A procedure expresses how something is done. A model can also be a separate program. This is a foreign submodel. and procedures. A model maintains its own memory storage of values for each instance in which it's used.17 DATA n -INPUT vterm[1.2. without maintaining any trace of previous calls to the function. it calculates and returns a set of values. it can be used in that model in as many use instances as required. Defining the submodels As mentioned before.2. USERS GUIDE TO MODELS IN ATP . the dynamic operation of a model is represented by the named elements that hold the values used in and created by the model.

The data. $INCLUDE filename { inserting a local submodel (notice the ATP formatting) .defining a local submodel CONST . inputs. is to replace the actual description of the submodel by a reference to the file containing that description.defining a model CONST .using the submodel .. and one for execution The four arrays hold values of data.. and stored variables.. ENDUSE . that is still a locally-defined submodel.. VAR . The array of stored variables is a service of MODELS. and must start in column 1 of a new line....it has two separate entry points... Foreign submodels MODELS has a simple interface for accessing other programs that can be used as submodels or functions inside a model.. and outputs of a model..... EXEC .... one for initialization. outputs.its call arguments are pointers to four arrays ........ inputs.. 2.. EXEC . ENDUSE .. allowing the called program to be used for more than one use instance without requiring the called program to manage separate storage for individual instances.. to hold internal values of the program between calls. A program accessed as a model has to meet the following requirements: . DATA . DATA .2. OUTPUT . USERS GUIDE TO MODELS IN ATP . DATA ... .. and outputs correspond to the regular data.. The above example could be rewritten as: MODEL component -.2... USE controller AS control_1 -. USE controller AS control_1 -.defining a model CONST .. ENDEXEC ENDMODEL The $INCLUDE directive is an ATP command used for accessing the contents of other files. INPUT . .. ENDEXEC ENDMODEL An alternate way. It's a formatted command.using the submodel .. ENDMODEL .18 MODEL component -.. inputs. MODEL controller -.

DATA . MODEL component -. ixvar:5} . That subroutine needs to be edited when installing calls to new foreign programs. USE controller AS control_1 -.using the submodel ... ENDEXEC ENDMODEL In the above example.19 The two entry points correspond to the INIT and EXEC procedures of a model. the foreign name of the model.. The initialization routine is called only when an instance of the model is used for the first time. to recognize which foreign model is being called. and the foreign name is "control_program". EXEC .. and should present no difficulty when used.. That subroutine is fully documented with comments. The declaration of the foreign model indicates the local name identifying that submodel in the calling model. the local name is "controller". ENDUSE . and the length of each of the four arrays.. The execution routine is called when the state of the model is to be updated according to new conditions. ixin:2*n+4... ixout:n.. Part of that subroutine is shown below. It is inside that subroutine that the actual call to the foreign program is made. That foreign name is not necessarily the name of the foreign program itself. showing how the identifier "controller" of the previous example would be used: USERS GUIDE TO MODELS IN ATP .defining a model CONST ..... MODEL controller FOREIGN control_program {ixdata:3. It is a unique identifier used in the subroutine "fgnmod" of MODELS.. .

4 ) THEN .EQ.20 SUBROUTINE FGNMOD ( name. "xin".EQ.1) THEN CALL contri(xdata. and history values are calculated. it is possible to specify how data.EQ. xin. xin.EQ. In the following lines..1) THEN CALL sampli(xdata.EQ. Note that the four arrays have the pre-defined names "xdata". "xout".EQ. xin. namlen.2 ) THEN ! "sample_c_model" IF (iniflg.dat" DATA refnam(2) / 'SAMPLE_C_MODEL' / ! Example "cmodel. just like in a regular USE statement.notice how each one uses both an initialization routine and an execution routine IF ( iname. register the foreign model names as declared in the models: DATA refnam(1) / 'SAMPLE_MODEL' / ! Example "ftnmodel. it is possible to assign initial values to these variables using HISTORY directives. xvar. xout. xout. xin. One difference is that the value of the local simulation time must be explicitly passed to the foreign program as one of the inputs. xin(*). xvar) ENDIF CONTINUE ! ------------------------------------------ELSE IF ( iname. Just like when using a local model. The following lines call the actual foreign subroutines/procedures: . xout. not in the USE statement. xvar) ELSE CALL contrm(xdata. Note that only initial values are passed to the foreign program.dat" DATA refnam(3) / 'CONTROLLER' / ! Added for this example DATA refnam(4) / ' ' / . and "xvar": USERS GUIDE TO MODELS IN ATP . xvar(*) .. input. xvar) ENDIF CONTINUE ! ------------------------------------------ELSE IF ( iname. xin. xout.EQ. xout(*).3 ) THEN ! "controller" IF (iniflg. It's not done "magically" in the background. INTEGER*4 (I-N) DIMENSION xdata(*). not full history expressions available only for regular models. xvar) ELSE CALL c_sample_m(xdata. xout. and output arrays is identified. The following example illustrates the definition and the use of a simple foreign model. C C C C C C C It is when actually using the foreign model that the contents of the data.1 ) THEN ! "sample_model" IF (iniflg. xvar) ENDIF CONTINUE ! ------------------------------------------ELSE IF ( iname. The contents of the array of variables is specified and managed inside the called program. input. xin. xvar) ELSE CALL samplm(xdata. xin. ierflg) IMPLICIT REAL*8 (A-H.. xout. xdata... 1 iniflg. Outputs of the foreign model are used just like those of a local model..1) THEN CALL c_sample_i(xdata. However. O-Z). xout.actual names may be different from the foreign names used in the models .

xout.n]:=xout[1..xdata(1) xvar(i)=(2*xvar(i)+xin(i))/2 xout(i)=xvar(i)+100.set value of xdata[1] INPUT xin[1.n] OUTPUT a[1... -..n]:= .' CALL OUTSIX( text80. External submodels If a submodel is used in a model. but defined somewhere else. xvar) text80 = 'Initializing model "sample_model".. xin..' CALL OUTSIX( text80.. like this: USERS GUIDE TO MODELS IN ATP ..n] -.3. EXEC . xvar(*) CHARACTER*80 text80 ! Buffer used to assemble messages for output text80 = 'Executing model "sample_model". 80 ) RETURN END In the example.use outputs xout[1. xin. xout(*). xin(*). ixout:n. "xin" holds input values received from the calling model. it can be introduced in the calling model as "external".. ixin:n.load inputs xin[1. ixvar:n} ..n] HISTORY xvar[1. requiring a reference to the initial value of xvar at the first execution of the subroutine.. without using the value of time (which is thus not passed as an input): SUBROUTINE samplm(xdata.n] ENDUSE . xout.n] . in this case. "xout" holds output values sent back to the calling model. 80 ) ! Send text80 (arg 1) to ATP listing DO 1000 i=1.21 DATA n VAR a[1. is a Fortran subroutine that writes some text and updates the values of the outputs.. It needs to be declared in the calling model. Note how xvar is referenced before a new value is assigned to it. USE ftnmodel AS ftnmodel DATA xdata[1]:=n -. xvar) DIMENSION xdata(*)..set history of xvar[1...n]:=0 -.. 2.. "xvar" holds state values stored in memory by MODELS between calls.. "xdata[1]" holds the dimension of the other three arrays.2.0 1000 CONTINUE RETURN ENTRY sampli(xdata. MODEL ftnmodel FOREIGN sample_model {ixdata:1. The foreign program. but the declaration can be as simple as mentioning the model's name and saying it's external.

For the previous example.. ENDMODEL or at the same level as a foreign model: MODEL component -.... EXEC ... ENDMODEL MODEL controller CONST ....... ENDUSE . MODEL controller EXTERNAL ...... ... ixvar:5} .. ENDMODEL MODEL sub_system_2 . as part of a library of models: USERS GUIDE TO MODELS IN ATP . . MODEL controller EXTERNAL .. or at a higher level: MODEL system MODEL sub_system_1 MODEL component -...... DATA .. ENDMODEL ... USE controller AS control_1 -... ixout:n.defining a model .. ENDEXEC ENDMODEL The full definition of the external model can be placed anywhere at the same level of the calling model or above. . ENDMODEL MODEL controller FOREIGN control_program {ixdata:3.. MODEL controller EXTERNAL . it could be found either at the same level of the "component" model as a locally-defined model: MODEL component -.22 MODEL component -..defining a model . ixin:2*n+4..using the submodel .defining a model CONST .... ENDMODEL MODEL controller ... DATA .. MODEL controller EXTERNAL .defining a model . ENDMODEL or at the same level or above..

When it is called. ) USERS GUIDE TO MODELS IN ATP . it uses the existing values of all the named references used in the function. Array-returning functions can be used inside expressions that use array arithmetic. That expression can contain references to the named arguments of the function. . However. ) := expression These functions are macro-expressions that can be used in other expressions of a model. In addition to the pre-defined functions supplied by MODELS..1.. value2. argname2. that is. The function is used by indicating the name of the function. as well as to any value-holding element of the model.... Statements functions are simply reusable named expressions.defining a model .3.. a function doesn't carry a state.23 MODEL component -. Point list functions express a relation between input and output in terms of (x. and by providing a list of values used by the arguments of the function: somename(value1. Foreign functions are functions that are defined in a separate program and accessed through the programming interface of MODELS. The function's expression can be a single-value expression or an expression returning an array of values. or a list of values in the form of an array.3. MODEL controller EXTERNAL . three types of custom functions can be defined in a model. y) coordinates. a function does not have internal variables that can retain values between calls.. Statement functions Statement functions are defined inside a model in the form: FUNCTION somename(argname1. to calculate and return a result to the expression from where it was called. . A function has access to the value of its arguments and to the values of all valueholding elements of a model. A function can return a single value.. 2.. 2. ENDMODEL $INCLUDE filename { a file holding a library of models . as compared to a procedure. Defining the functions A function operates like an expression. a function cannot modify any value other than the result it is returning.. As compared to a model.

1.. Pointlist functions Pointlist functions are useful when data about a function is available in the form of a table... imag) := sqrt(real*real +imag*imag) . ) An example of this would be a two-argument function used for calculating the amplitude of a complex number. xi) or can be supplied as an array of two values. (0. An interesting example is the description of a parametrized family of curves. 2. a curve of resistance in function of temperature could be expressed as: FUNCTION temp_dep POINTLIST (-273.24 The form under which the list of values is provided is flexible.e-6). USERS GUIDE TO MODELS IN ATP . Pointlist functions are single-valued functions expressed as a list of coordinates in a 2-dimension plane.. Very complex functions can be assembled using this possiblilty. array_expr.. 1. being a representation of the real and imaginary part of a complex number: VAR cx[1.. with the array.. ym := c_ampl(cx[1. using expressions and array expressions. in this case. . and can be a mixture of single values and of ranges of array elements. sorted in increasing value of the input coordinate.3. for example: somename(expr. The first coordinate of each pair corresponds to the input value. The following example illustrates a simple 1-parameter family of curves.2] -.. ym := c_ampl(xr. given its real and imaginary part. imag) := sqrt(real*real +imag*imag) .. What gets interesting is that the values of the coordinates can be expressed using regular expressions making reference to other variables or functions of the model. Each curve can in turn be described using an expression that contains a reference to another function of any type. A pointlist function specifies what curve the function will use for different values of a parameter "k". (-60. etc. 1..a complex variable as real and imaginary FUNCTION c_ampl(real.2. and the second coordinate corresponds to the output value of the function.e-4). The arguments can be supplied as a list of two separate values. like this: FUNCTION c_ampl(real.e2). For example.2]) Refer to the section on "Using a function" for more examples.

k FUNCTION FUNCTION FUNCTION FUNCTION curve2(x) .. or 2. The formatting requirements are that each pair be enclosed in parentheses. that is.. Interpolation is provided automatically. The interpolation order can be specified as a second argument when using the function..0) (1..6) etc. although a maximum line length of 80 characters is imposed by ATP.6) etc.5) in the above example.25 VAR a.lst". 2. the family is reduced to a set of three representative curves.. As everywhere else in a model. -. and can be either 0.5 y:=f(k) In the above example.4) (3.with data points located in the following file: USERS GUIDE TO MODELS IN ATP .2) (2. curve2(a)) (6. curve1(a)) (4.2.5 .lst -. quadratic). and interpolates linearly between the two values to return a value for k=2....1. 1. the function calculates the values of f(a) for k=2 and for k=4. as shown in the section on "Using a function".3.2) (2. curve3(a)) -.a statement function or a point list for k=2 curve4(x) . -. linear.. for example: (0.any value between 2 and 6 . possibly generated by another program.. Using separate lines is not required. Supposing that these coordinates are available in a file named "xy. they could be included in a model as follows: FUNCTION xyfun POINTLIST $INCLUDE xy. (none. with the enclosed coordinates separated by a comma. and 6.a statement function or a point list for k=4 curve6(x) . a:= some value k:= 2. spacing characters are ignored. 4.used inside the function f(k) -.. as in y:=f(2. (0.a statement function or a point list for k=6 f POINTLIST (2.4) (3. -. the interpolation is linear. External point list It is possible to use the $INCLUDE function of ATP for gaining access to a list of points stored in a separate file. The pointlist function simply specifies which of these curves (themselves functions) will be used for the three representative parameter values 2..0) (1. The pairs must be sorted in increasing value of the first coordinate. When the interpolation order is not specified.

It is a unique identifier used in the subroutine "fgnfun" of MODELS.. and should present no difficulty when used. speed[1. the foreign name of the function..26 2.it has one function argument that is a pointer to an array .. That subroutine is fully documented with comments.. The function call is handled by the programming interface of MODELS. That subroutine needs to be edited when installing calls to new foreign procedures.. the local name is "windspeed".. EXEC .. and the foreign name is "wind_speed". Foreign functions Foreign functions are functions written in any language and linked to ATP before execution.. The dimension of the argument array is indicated as "2".2] := windspeed(t) . and the length of the argument array. The indicated foreign name is not necessarily the name of the foreign procedure itself. because even if there is only one input argument when the function is used.3. ENDEXEC ENDMODEL In the above example.2] -.velocity [m/s] and direction [deg] .. showing how the identifier "wind_speed" of the previous example would be used: USERS GUIDE TO MODELS IN ATP . The declaration of the foreign function in a model indicates the local name identifying that function in the calling model. Part of that subroutine is shown below. A foreign procedure accessed as a function must meet the following requirements: .3. the function returns two values that it places in that array.it returns the number of output values placed by the function in the argument array The values returned by the function in the argument array must be placed at the beginning of that array.. MODEL component VAR speed[1. It is inside that subroutine that the actual call to the foreign procedure is made. FUNCTION windspeed FOREIGN wind_speed {ixarg: 2} . to recognize which foreign function is being called.

If the operation of the function varies in function of time. namlen. MODELS uses the value returned by the function. to find out how many values the function has placed in the argument array..3) THEN nval= wind(xarg) .. the only input argument used by the function is the value of the simulation time "t". y[1..2]. C C C C C It is when actually using the foreign function that the values of the input arguments are identified. which in this case will be "2". The foreign procedure. k FUNCTION f1 FOREIGN sample_function {ixarg:2} .dat" DATA refnam(2) / 'SAMPLE_C_FUNCTION' / ! Example "cfun. Internally.1) THEN nval= samplf(xarg) ELSE IF (iname. it is possible to specify how the function arguments are calculated..2) THEN nval= cfun(xarg) ELSE IF (iname. O-Z).EQ.dat" DATA refnam(3) / 'WIND_SPEED' / ! Added for this example DATA refnam(4) / ' ' / . Just as when using a local function. the wind velocity and direction. -k) -.. in this case. The following example illustrates the definition and the use of another simple foreign function: VAR y[1. In the following lines.. for example: USERS GUIDE TO MODELS IN ATP . ierflg) IMPLICIT REAL*8 (A-H. INTEGER*4 (I-N) DIMENSION xarg(*) .. EXEC .each argument can be an arbitrary expression .27 SUBROUTINE fgnfun ( name.. the value of time must be explicitly passed to the function as one of its input arguments..EQ. In the example of the wind speed function shown above.2]:=f1(k+t. placed in the argument array of the function. xarg. The following lines call the actual foreign procedures: .. register the foreign function names as declared in the models: DATA refnam(1) / 'SAMPLE_FUNCTION' / ! Example "ftnfun.. and returns two output values placed in the argument array: FUNCTION samplf(arg) DIMENSION arg(2) arg(1)=arg(1) +arg(2) arg(2)=arg(1)*10 samplf=2 RETURN END The same function could be written in C...actual names may be different from the foreign names used in the models IF (iname. The function returns two values. is a Fortran function that uses two input values. nval.EQ..

Two procedures have pre-defined names: EXEC and INIT. ERROR). as expressed by the value of its variables. WHILE. arg[1] = 10 * arg[0]. It is called automatically each time a USE statement is executed. 2. the INIT procedure of the model is executed. At subsequent time steps. identified by arbitrary names and performing arbitrary operations on the variables of the model. FOR. Additional named procedures can be defined. The EXEC procedure describes how the state of a model.4. Laplace and z transfer functions.28 int CFUN(double arg[]) { arg[0] = arg[0] + arg[1]. 2.1. for example. The INIT procedure The first time that a model instance is called during a simulation. The EXEC procedure is the procedure that is called when it is time to update an instance of the model to a new simulation time. The INIT procedure describes how to initialize the values of the variables before the simulation begins. This evolution is described by means of an arbitrary arrangement of assignment statements (value assignment. It is called each time a USE statement calling that model is executed. and procedure calls.2. but see the following discussion on the subject of executing both INIT and EXEC.4.4. only the EXEC procedure is executed. It is called automatically when a USE statement introduces a new instance of a model. return 2. differential equations. The EXEC procedure can be prevented to execute at the initial use by placing its contents inside an IF statement. followed by the EXEC procedure. The initial call to a model instance can be at a time different than time zero if. the corresponding USE statement is written inside an IF statement in the EXEC procedure of the calling model. } 2. integral assignment. algorithm control statements (for conditions and repetitions using IF. The EXEC procedure The EXEC procedure is the main operating procedure of the model. and combined simultaneous equations). Writing the procedures The procedures describe the methods used by the model for accessing and modifying the values of the value-holding elements of the model during the simulation. calls to other models (USE). evolves over the time of the simulation. It describes how the model operates as time increases. USERS GUIDE TO MODELS IN ATP .

2. 2.a_old where "a_old" has of course not been defined yet.2. By having both the INIT and EXEC procedures executing at the initial time. as in: slope_v := deriv(v) where the function deriv() needs to access. Let's turn the thing on its head and consider instead what would prevent us from having only the EXEC procedure run at t0 without an INIT procedure. again a duplication of the contents of the EXEC procedure. then it would have to contain value assignments for all the variables in the model. It can also happen in implicit references to past values. This mechanism owes its existence to the need of being able to assign history and initial values differently for different uses of the same model. so that they be initialized too.4.4.1. which runs counter to the approach of separating the definition from the use of the models. Similarly. we minimize the size of INIT. as in a_increase := a . All we need to do in the INIT procedure is define any past values which will be referenced in the EXEC procedure before the model has had the opportunity to store these past values itself in its running history. which of course has not yet been stored in the model's running history. and is therefore undefined.29 2. we would need to somehow call all the submodels used in the EXEC procedure. a more flexible three-level mechanism is available in MODELS. the value of v at the previous time step.this is level one. then the contents of the model would have to be modified from one use to another. and avoid code duplication which would easily create maintenance problems in the development life of the model. behind the scene. Executing both INIT and EXEC at time zero Here is the reasoning at the base of the approach of having both the INIT and EXEC procedures execute at the initial time t0. The problem would be that any past value that needs to be referenced in the model during the first execution would be undefined. INIT procedure and HISTORY assignment Rather than forcing one to define all initial values and history expressions in the INIT procedure of a model. This can happen either explicitly. This is why MODELS has been built so that it be possible to assign HISTORY expressions in the USE statement calling a model -.2. If only the INIT procedure ran at t0. If the definition of history and initial values had to be hard-coded in the INIT procedure of the model. USERS GUIDE TO MODELS IN ATP . which means that much of the INIT procedure would duplicate what's in the EXEC procedure.

30 In addition, default history expressions can be specified for any of a model's inputs and variables which require a history to be defined. The default history expression will be used only if no history is specified for that element in the USE statement. This is level two. Note that if an element is declared in a model as requiring a history, and that no default history is defined for it, then its history expression must be specified in the USE. What's left for the INIT procedure is assigning history and initial values which are private to the model, that is, which the user of the model doesn't need to know about (see the section on history expression assignment). This is level three. Of course, it's desirable to build the INIT procedure so that it takes care of as much of the history and initial value assignments as possible, leaving a minimum of concern to the user of the model. Notice that the expression defining the history of an element can make reference to the history expression of another element, which can be very useful in the INIT procedure.

2.4.3. Named procedures Although not yet available at the time this text is being written, it will soon be possible to define named procedures in a model. This is to provide the possibility of performing operations on a model other than what is done in the EXEC procedure. The implicit message guiding the operation of the EXEC procedure is "updating to a new simulation time". Using additional procedures, other operations can be executed, for example asking a model instance to reset a group of variables or to perform a write operation, or accessing the value of a specific variable of the model. This also makes it possible to connect to the operation of a model from more than one locations in the calling model, otherwise reserved to one USE statement for each instance. The final format for defining a procedure is not yet definitive, but would be in the line of this example:
MODEL proc_example DATA inival {dflt:0} INPUT x VAR y INIT -- this is executed when the instance is created or first USEd integral(x) := inival ENDINIT EXEC -- this is the default operation procedure, -- executed when the instance is used from a USE statement y := integral(x) -- assigns value of integral to y self.write_y -- calls the procedure 'write_y' ENDEXEC

USERS GUIDE TO MODELS IN ATP

31
PROC write_y write('In model proc_example, y=', y) ENDPROC PROC reset_integral(resetval) integral(x) := resetval ENDPROC PROC integral_value integral_value := integral(x) ENDPROC ENDMODEL -- uses one input argument -- resets the value of the integral

-- returns the value of the integral

As shown in the above example, a procedure can have zero or more input arguments, and can return zero or more output values. A procedure can be called from inside the model where it is defined, using the instance identifier "self". As shown in the next example, a procedure can also be called from another model that uses an instance of the model where the procedure is defined:
MODEL test_proc MODEL proc_example EXTERNAL -- identifies a model description VAR k -- counter INIT k:=0 ENDINIT EXEC k:=k+1 USE proc_example AS example -- creates and updates an instance named -- "example" of the model "proc_example" DATA inival := -4 INPUT x := 2*t +3 ENDUSE IF k=4 THEN example.reset_integral(0) -- calls a proc of "example" ENDIF write('In test_proc at t=', t, ', integral value=', example.integral_value) -- calls another proc ENDEXEC ENDMODEL

In the above example, a procedure is called by identifying the name of the model instance to which it belongs, the name of the procedure, and the value of its input arguments, if any. The procedure "reset_integral" expects one input value, and returns no value. The procedure "integral_value" expects no input value, and returns one output value. A procedure can be used as a function inside an expression, returning one or more values to the expression. A procedure returning no values can be used as a statement inside another procedure. A procedure can be recursive.

2.5. Writing the statements of a procedure
Various types of statements can be used in a procedure for assigning values to the variables of the model, for controlling the algorithmic flow of a procedure, for defining and using instances of other models, and for calling the procedures of a model. They are:
USERS GUIDE TO MODELS IN ATP

32 - assigning values element := expression diffeq(d-polynomial)|y := x laplace(y/x) := (s-polynomial)/(s-polynomial) zfun(y/x) := (z-polynomial)/(z-polynomial) integral(element) := expression histdef(element) := expression - controlling the algorithm IF ... WHILE ... FOR ... DO ... REDO COMBINE ... ERROR ... - using and updating an instance of a model USE ... - using a procedure of a model instance.procname(argument values) write( ... )

2.5.1. Value assignment statement There are two types of equations available for assigning a value to a variable: explicit and implicit. The explicit value assignment has the simple form:
element := expression

The element can be a single variable y, a single element of an array variable y[expr], or a range of elements of an array variable y[expr..expr]. The types of expressions available are regular expression, sum expression, derivative polynomial expression, and integral (see the section about Expressions). A regular expression can be written to return either a single value or a list of values. Single elements, of course, can only be assigned a single value. But a range of elements can be assigned either a single value applied to all the elements of the range, or individual values taken from the list of values returned by the expression. Minimum and maximum limits can be placed on the value or values returned by the expression (see Expressions). It is also possible to assign a value explicitly to the integral of a variable, as discussed in the section on integral value assignment.
USERS GUIDE TO MODELS IN ATP

. Laplace and z transfer functions These three types of assignments can each describe how the value of a variable changes with respect to the value of another variable over time.. Differential equation. expressed as a ratio of two linear polynomials in z-1: Y (z) b0 + b1z −1 + b2 z −2 +.33 Finally. 2.. it is possible to associate a value expression to the history of an element (see History expression assignment).. ) The z-transform transfer function describes the variation of a variable y with respect to a variable x. USERS GUIDE TO MODELS IN ATP .. This is expressed using the following notation.2.. The built-in form of the differential equation is a first-degree (the exponent applied to the derivatives) nth-order (the highest order of the derivative) ordinary differential equation (of one variable).. using the operator D to replace d/dt : (a0 D0 + a1D1 + a2D 2 +. with the value of each coefficient described by an expression: expr|D0 ± expr|D1 ± expr|D2 ± . The Laplace-transform transfer function describes the variation of a variable y with respect to a variable x.. as follows: or. again using the vertical bar as the operator "applies to": LAPLACE(y/x) := (numerator)/(denominator) where the numerator and the denominator are each expressed as (expr|s0 ± expr|s1 ± expr|s2 ± . = X (s) a0 + a1s + a2 s2 +. and the vertical bar as an operator meaning "applies to": DIFFEQ(polynomial)|y := x where the polynomial in D is expressed as follows. Laplace transfer function. They are discussed together because their representation and their solution are similar.5.. The available implicit forms of value assignment are differential equation.... discussed below... expressed as a ratio of two linear polynomials in s: Y (s) b0 + b1s + b2 s2 +. = X (z) a0 + a1z −1 + a2 z −2 +. and are based on the same approach. and z transfer function.) ⋅ y = x expressed using the keyword DIFFEQ.

as the variable s translates to the time derivative d/dt when converted from the frequency domain to the time domain. .) ⋅ y (t ) = (b0 + b1D + b2D 2 +. the use of the keyword CDIFFEQ. When the coefficients are known to be constant. 2. becomes (a0 + a1D + a2D 2 +. This process produces an equation expressed in terms of the present and past values of y and x: y(t0) = f( x(t0)..2. the polynomials are linear in D.5. .. s... However the coefficients of the polynomials can be arbitrary time-variant nonlinear expressions. Numerical solution Using the differential equation is equivalent to using the Laplace transfer function with N(s)=1. y(t1). again using the vertical bar as the operator "applies to": ZFUN(y/x) := (numerator)/(denominator) where the numerator and the denominator are each expressed as (expr|z0 ± expr|z-1 ± expr|z-2 ± .. The elements y and x are single-value elements. Conversely.. or z-1. we can integrate symbolically this equation with respect to time on both sides.) ⋅ x(t ) where D is the operator d/dt.. the Laplace representation can be solved in the time-domain by converting the numerator and the denominator to polynomials of derivatives of the variables y and x.34 This is expressed using the following notation.. each time using the bilinear transformation.. As seen below.. = X (s) a0 + a1s + a2 s2 +.1. x(t2). where Y (s) b0 + b1s + b2 s2 +.. x(t1)... (a0 D0 + a1D1 + a2D 2 +.. ) where USERS GUIDE TO MODELS IN ATP ... and CZFUN will reduce execution time by avoiding the recalculation of the coefficients at each time step.. whether single variables or single elements of a variable array. To avoid having to calculate derivatives. as many times as required to eliminate all derivatives.) ⋅ y = x is equivalent to Y (s) 1 = X (s) a0 + a1s + a2 s2 +. y(t2).. CLAPLACE.. ) In each of the above types of representations. and cannot be a range of multiple array elements.

This situation is not representative of typical simulations. using the z-domain notation.2. each a function of the original coefficients of the respective polynomials. It is sufficient to describe the value of the variable at past times before time zero. Some textbook examples of differential equations set t=0 at a time when the system is in a transient condition. The solver will continue the calculation from time zero onward just as if all the initial conditions on the derivatives had been provided. Initialization Because of the transformation discussed above.. or. and then let the transient behavior start only at or after the beginning of the simulation.35 x(t0) = x(t). we can initialize the solution of any of these equations without having to provide initial conditions for the derivatives of a differential equation or Laplace transfer function.. This is done in the solver by applying a numerical transformation to the coefficients of each polynomial. and need initial conditions on the derivatives in order to solve the equations analytically. one certainly has enough information to also know the shape of the variables in the form of a history expression f(t). x(t1) = z-1⋅x.5. even if one needs to start a simulation from a transient condition. the equation is solved numerically by making simple references to as many past values of y and x as needed in each case. simply using a history expression f(t) written in function of time. = X (z) A0 + A1z −1 + A2 z −2 +. To summarize. In any case. . where we start a simulation from a known simple state.2.. not a steady-state condition.. x(t0) = t. Let's look at an example where we have to find the time domain solution for the following differential equation using Laplace transforms (from Kuo): d2x/dt2 + 3 dx/dt + 2 x(t) = 5 u(t) with initial conditions x(0) = -1 dx/dt = 2 USERS GUIDE TO MODELS IN ATP . it can be argued that if one has enough information to know analytically the initial conditions of all the derivatives... . The equation now shows a new set of coefficients. x(t2) = z-2⋅x. differential equations and Laplace transfer functions are converted to z-transform transfer functions. 2.. x(t1) = x(t-Δt). Instead of using values of derivatives. x(t2) = x(t-2Δt). to produce an equivalent z-transform transfer function Y (z) B0 + B1z −1 + B2 z −2 +.

Using CDIFFEQ. the above equations don't need to be recalculated. For doing mathematical exercises not requiring simulation. is evaluated at each time step. therefore changing the internal state of the "component" used to produce the output represented by that variable. we apply a static limit to that variable in a separate equation. whether the coefficients are constant or variable. instead of at every time step. all the derivatives of that variable become zero. This is because when a limit is reached. If we need to apply a limit (minimum and/or maximum) which does not modify the internal state of the represented component. Limits The only limit that can be applied directly to the value of a variable calculated using a differential equation and a Laplace or z transfer function.2. 2.2. But then. implemented using z-transforms). we could go around the problem and provide the analytical form of the signal as history expression f(t). It is a simulation solver. CLAPLACE.4. at the initial time at which each instance of that model is called). or CZFUN. The solution of differential equations in MODELS is not based on the calculated values of the inner derivatives of the signals (the analytical approach). because the value of the variable to which they apply is already defined by its history expression. if we have enough information to know not only the instantaneous value of an output but also the instantaneous value of its derivative(s) at initial time t0. we don't need a differential equation to simulate it. is a dynamic limit. of course. The equation itself. but instead uses the measured values of the signals at one or more past simulation times (the empirical approach. 2.5. That is what we can then provide to MODELS as history of the signal at time t0 in the form of a function f(t). it may be more appropriate to use a symbolic or analytical mathematical solver. we can just use the analytical expression directly as y = f(t) MODELS is not meant to serve as a symbolic or analytical equation solver. The same reasoning applies to the value of the integrals.5. we also certainly have enough information to have a very good idea of the shape of that signal around time t0. USERS GUIDE TO MODELS IN ATP . In a simulation situation. CLAPLACE.3.36 This problem is not a simulation problem. and CZFUN Using CDIFFEQ. the coefficients of the polynomials are considered to be constant.5. Values of y at t0 At the first execution of a model-use (that is. if we know the analytical expression of y.2. and are evaluated only once at the start of the simulation of each instance of a model.5. To use this example in MODELS. 2.

If the arm is mounted on a spiral spring. This is a static limit. But if a Zener diode is placed in parallel with the feedback branch to limit the output voltage.. This is shown in the figure below. the arm will simply slip on its shaft. the spring will compress while the driving torque attempts to push the arm past its allowed range. When the torque decreases. for the spring winding up. comparing the effect of a static and a dynamic limiter on a the output value of a simple integrator: 2. without any unwinding delay. when the torque attempts to push the arm past its maximum position. the voltage across the capacitor will also be limited. the time integral is defined as: USERS GUIDE TO MODELS IN ATP .) z := y {min: expr} An example of a component that reaches a limit is an op amp used with a resistor and a capacitor in the feedback branch.)/(.3.. the spring needs to unwind to its resting position before the arm will start moving away from the peg. also called "windup" limit. This is a limit operating internally to the component.. If instead the arm is mounted on a slip bushing. as it dynamically affects the internal operating behavior of the component.5. also called "no windup". ready to come off the peg as soon as the torque starts decreasing. A mechanical example is the indicating arm of a meter reaching a stop peg at the upper end of the scale..)/(. If the output of the component is clipped by a limiter placed past the component. outside the Laplace equation: LAPLACE(y/x) := (. This is a dynamic limit... This is a dynamic limit. a dynamic minimum limit can be specified along with the equation: LAPLACE(y/x) {dmin: expr} := (. The external limit is a static limit as seen from the component. the voltage across the capacitor in the feedback branch will show the same values as if there was no limiter.. Integral value assignment At any time t0 of a simulation..) and a static limit. for example.37 For a Laplace function.

t1 → t 0 ) The running value of an integral is calculated during a simulation by using the value of the integral at the previous time. and adding to it the value of the incremental integral over the past step. t1) + ΔI (x. and so on. Then further on in the EXEC at the same time step. any reference to the value of the integral will always return the same value. the value of the integral is not dependent on the present value of x anymore for the rest of that EXEC at that simulation time. to zero or some other value. we may assign a different value to x. multiplied by the time interval t0-t1: ΔI = x(t1) + x(t 0 ) ⋅ (t 0 − t1) 2 However.38 t0 −∞ ∫ x ⋅ dt the integral of x with respect to time. we use a history expression assignment: histdef(y) := expression written as a function of the variable "t" USERS GUIDE TO MODELS IN ATP .5. This increment. as the average of x(t1) and x(t0). by using an integral value assignment of the form: integral(x) := expression This new value becomes the starting point to which the next incremental integral will be added at the next time step. we may assign a value to x. This can be decomposed. At a given simulation time inside the EXEC of a model. then use the value of its time integral (which will use the present value of x to calculate the integral increment). is calculated using the trapezoidal approximation. History expression assignment To associate a history expression with a variable in the INIT procedure. in effect resetting the value of the integral. No matter how often one changes the value of x after the reset inside the same time step.Δt. from -infinity to the present time. t 0 ) = I ( x. the reset value that was assigned directly to the integral by the integral value assignment.4. 2. in MODELS. as: t0 −∞ ∫ x ⋅ dt = t1 −∞ ∫ x ⋅ dt + ∫ x ⋅ dt t1 t0 or I (x. But from the point in the EXEC where a value is directly assigned to the integral. it is possible to bypass this process and assign a value to the integral directly. One detail to notice is the following. then again use the value of the integral (which will use the new x to recalculate its increment). using t1 = t0 .

39 This is the third form of history assignment. 2. Explicit IF statement The simple form of the IF statement consists of a single conditional clause: IF condition_is_true THEN statement list ENDIF Multiple clauses can be chained inside the same IF statement. 2.. to make the history expression of y dependent on the history expression associated with another variable x. Only the first clause found with a true condition is executed: IF condition_is_true THEN statement list ELSIF another_condition_is_true THEN another statement list ELSIF .5. The expression can itself make reference to the history expression associated with other variables. ELSE another statement list ENDIF USERS GUIDE TO MODELS IN ATP . as discussed in the section on the INIT procedure..5. IF statement IF statements are used for grouping statements that are executed only when certain conditions are met. For example. but instead only use the most recent value of x whenever the history expression of y needs to be evaluated.. .5..5. the ELSE clause.. can also be defined.. ENDIF A default clause. and the following: histdef(y) := 2 * x which would not achieve the intended purpose. It is executed only when no other clause of the IF statement is found with a true condition: IF condition_is_true THEN statement list ELSIF another_condition_is_true THEN another statement list . we can use the histdef() function in the expression: histdef(y) := 2 * histdef(x) Notice the difference between the equation above.1.

A case statement can be described using an IF statement with multiple clauses. and the IF statement can be rewritten as: IF onswa=2 AND ia<=ichop AND di_dta<di_lim THEN onswa:=3 ELSIF dva>ds THEN onswa:=2 ENDIF USERS GUIDE TO MODELS IN ATP . for example: IF onswa=2 THEN IF ia<=ichop THEN IF di_dta<di_lim THEN onswa:=3 ENDIF ENDIF ELSE IF dva>ds THEN onswa:=2 ENDIF ENDIF The first three conditions can be grouped using a logical expression. as shown in the following example: MODEL if_example -. ENDIF . in any of its clauses: IF condition_is_true THEN statement 1 statement 2 IF condition THEN another statement list . Implicit IF statement When we need to determine the value taken by a variable under a variety of conditions.5...2. ENDIF There is no "CASE" statement in MODELS at this time. we can use an explicit IF statement.40 An IF statement can be enclosed inside another IF statement.illustrates the IF structure in MODELS VAR k INIT k:=0 ENDINIT EXEC IF k=0 THEN k:=1 ELSIF k=1 THEN write("In first 'elsif' with k=1") k:=2 ELSIF k=2 THEN write("In second 'elsif' with k=2") k:=3 ELSE write("In 'else' with k=3") ENDIF ENDEXEC ENDMODEL 2.. although it may be added later..5.

it can be used directly inside a function expression.6. as soon as one clause has been executed. On the other hand. This is because of the automatic optimization used by MODELS when evaluating expressions. if a=1 is true.. logical expressions return a numerical value. because the factor (a=2) has a zero value. 0 or 1. for as long as a condition is evaluated as true.. the implicit form is not as clear. cond_2 is false.. and the expression evaluates to: 3*1 +2*0 +onswa*0.41 But in MODELS. economy of execution time is almost not an issue. ENDIF In this example. If a factor is found to be zero. if only to find that the first factor of each remaining term is zero. In the end. This has the same effect as using the IF statement. then only f1(x) is evaluated. the value of the whole term is immediately set to zero without evaluating its other factors. Certainly. Each term of an expression is evaluated from left to right. its numerical value is 1. This IF statement can therefore also be expressed as a value assignment that uses the value of a condition inside a numerical expression: cond_1 := onswa=2 AND ia<=ichop AND di_dta<di_lim cond_2 := NOT cond_1 AND dva>ds cond_3 := NOT cond_1 AND NOT cond_2 onswa := 3*cond_1 + 2*cond_2 +onswa*cond_3 If cond_1 is true.. which is equivalent to: IF a=1 THEN y:=f1(x) ELSIF a=2 THEN y:=f2(x) . In the above case. 2. the decision to use implicit conditions instead of explicit ones depends on what is being expressed. The only difference is that in the IF statement. while an IF statement can only be used inside a procedure. Conditional expressions can also use a variable as a selector: y := (a=1)*f1(x) +(a=2)*f2(x) + . in the assignment. the terms of the expression are not mutually exclusive.5. WHILE statement Using a WHILE statement allows a group of statements to be executed zero or more times during the same time step. WHILE condition_is_true DO statement list ENDWHILE USERS GUIDE TO MODELS IN ATP . not f2(x). the execution immediately jumps to the end of the IF statement. and so on. and each one must be calculated.

' after loop ') write("*** End results of model 'while_example' ***") ENDIF ENDEXEC ENDMODEL The word "while". applied to the same DO list: FOR n:= 1 to 4 FOR m:= n to 4 DO write( m ) -.0.2. 6.1.7. ' in loop ') k:=k-1 ENDWHILE write('k='.8. in this case.. we can use an IF statement to take care of that. 2. 3.4. k. FOR i:= list of values FOR j:= list of values FOR . If we need to express "when a condition is true then do this". as shown in the example above with "IF t=timestep THEN". FOR statement A FOR statement is used for repeating the execution of a group of statements using a list of values given to one or more parameters.illustrates the use of WHILE VAR k EXEC IF t=timestep THEN -. The first one is that we can specify values for more than one parameter.3.5 -..4.9 USERS GUIDE TO MODELS IN ATP .42 This structure can be used for doing iterations inside a model.4. DO statement list ENDFOR Two differences can be observed between the implementation of the FOR statement in the MODELS language. 7 TO 9 BY 1 -.6 -.4. with the simulation time "frozen" for the duration of the iteration: MODEL while_example -. and that found in many programming languages. where each term of the list can be either a single value or a range of values: FOR z:= 0 TO 5. and does not mean "when". does not imply a reference to time. k. 4 ENDFOR The other difference is the values to be taken by each parameter are given in the form of a value list.3.2.5.3. 2.7.1.execute only at the first time step write("*** Begin results of model 'while_example' ***") k:=5 WHILE k>0 DO write('k='.

the DO statement is used for repeating the execution of a group of statements.5.8. deg(angle).10. the simulation time is frozen while control of the execution is kept inside a FOR statement.90. ') = '..6.98 -.6.execute only at the first time step write("*** Begin results of model 'for_example' ***") FOR z:= 0 TO 5.3.95.10...0 write("*** End results of model 'for_example' ***") ENDIF ENDEXEC ENDMODEL As shown in this example..1.5.85.1. DO statement Like the WHILE statement.illustrates the use of FOR in MODELS VAR k EXEC IF t=timestep THEN -. the values of the parameters are assigned and combined in the sequence in which they are specified.0. DO statement list ENDDO The first difference is that in the DO statement.5 6 7.4.3.9. Even though the simple examples above show only integer values.75. The names of the parameters are local to the FOR statement.2.15.6.12.43 The statement list placed inside the FOR statement is executed repeatedly until all combinations of the parameter values have been covered: MODEL for_example -.5. the statement list is executed at least once. the parameters can also be assigned non-integer values: FOR angle:= 0 TO 2*pi BY pi/4 DO write('tan('.2. and don't need to be declared as variables of the model.4..80.2.2.8 -.4..5. tan(angle)) ENDFOR As for the WHILE statement..7. 0 DO write(z*10 +y) ENDFOR ----0..4.8.8.96. 7 TO 9 BY 1 FOR y:= 0 TO 8 BY 2 DO k:=z*10 +y write(k) ENDFOR FOR z:= 9 to 0 by -1 FOR y:= 5. 6.0 -.8.0 -.9 0.94. 2. USERS GUIDE TO MODELS IN ATP .

44 The second difference is that the condition determining whether the loop will be repeated or not, is carried by a flag set by executing the REDO statement anywhere inside the statement list. The DO statement is like a WHILE statement written as follows:
redo_flag := TRUE WHILE redo_flag = TRUE DO statement list ENDWHILE

The DO statement is used instead of the WHILE statement in situations where the loop condition is more complex than can be expressed in the simple conditional expression of the WHILE statement. Instead of having to declare and use a flag explicitly as in the last example above, we can directly use the REDO statement in one or more places inside the statement list. As for the WHILE statement, the simulation time is frozen while control of the execution is kept inside a DO statement.

2.5.9. REDO statement The REDO statement is used in combination with the DO statement described above. Each time the REDO statement is executed, it sets a flag that tells the DO group to repeat its execution from top to bottom the next time that decision is made. The status of the flag is checked only when execution of the group reaches the bottom of the group. The status of the flag is automatically reset to false each time the execution restarts at the top of the DO group.

2.5.10. COMBINE statement The default flow of execution inside a procedure is sequential. Sets of variables that need to be assigned a value simultaneously are identified in MODELS by being placed inside a COMBINE statement. An alternative is for them to be described and solved in a separate user-supplied program called by MODELS at each time step of the simulation. There are two types of solutions for simultaneous variables in MODELS. One is linear, solved using a simple Gaussian method. The other method handles simultaneous nonlinear equations using Newton iteration. The linear method is faster but less flexible. The nonlinear method is more general, although it consumes more execution time and its convergence is dependent on the set of equations being solved and on the appropriate choice of initial conditions. This is why it may be advantageous in some situations to use the linear method to solve a group of nonlinear simultaneous equations, either for the sake of speed of execution or for avoiding convergence problems.

USERS GUIDE TO MODELS IN ATP

45 2.5.10.1. Using the linear COMBINE for linear equations The linear COMBINE statement is used in the following format:
COMBINE AS identifier statement list ENDCOMBINE

The identifier is a name uniquely identifying each COMBINE group:
COMBINE AS feedback_controller equations of the feedback controller ENDCOMBINE

When a COMBINE is used in the statement list of a repetition statement (either WHILE or FOR or DO), the identifier must be written in an indexed form, in order that each time the COMBINE statement is executed inside the repetition loop, it refers to a different set of variables:
FOR i:=1 TO n DO COMBINE AS probe[i] equations of the probe circuit, indexed with "i" ENDCOMBINE ENDFOR

The statement list of a linear COMBINE can include any arrangement of the following types of linear equations: - differential equations, which in MODELS use a linear polynomial of the time derivatives of a variable; - Laplace transfer functions, which are described using two linear polynomials of the "s" operator; - z transfer functions, which are described using two linear polynomials of the "z -1" operator; - linear value assignments of a variable or of an array element of a variable, using: - a sum expression, which is a linear sum of variables - a derivative expression, which is a polynomial of the time derivatives of a variable - the integral of a variable - the first or second derivative of a variable - no regular expression (considered nonlinear) Here is an example combining two simultaneous linear equations: a+b=6 a=t*b ( rewritten as b = 6 - a )

USERS GUIDE TO MODELS IN ATP

46
MODEL comb1 VAR a, b EXEC COMBINE AS first_group b := sum( 6| - 1|a ) a := sum( t|b ) ENDCOMBINE write('t=',t,', a=',a,', b=',b,', a+b=',a+b) ENDEXEC ENDMODEL

Each line of the COMBINE group describes how a value is assigned to each simultaneous variable. This is why the first equation is rewritten to express the value of b, as we were already using the second line to express the value of a. The syntax of the sum() expression is explained in the section on "Expressions". Notice how the format of the sum() expression requires that we place the coefficient of the left of each term, and the variable on the right of the term. This is why we could not write a := sum( b | t ), because in this case, t is not a variable of the group, b is. The linear COMBINE allows us to add min/max limits to one of the equations:
MODEL comb1 VAR a, b EXEC COMBINE AS first_group b := sum( 6| - 1|a ) a := sum( t|b ) { max: 4 } ENDCOMBINE write('t=',t,', a=',a,', b=',b,', a+b=',a+b) ENDEXEC ENDMODEL

Here are four versions of the same set of simultaneous equations showing the relationship between sin(t) and cos(t), all with the same solution of: y1 = sin(t), y2 = cos(t), y3 = -sin(t) The first set uses integrals: y1 = integral(y2) y2 = integral(y3) y3 = - y1 The second set uses derivatives: y2 = deriv(y1) y3 = deriv(y2) y1 = - y3 The third set uses a Laplace version of the integrals: Laplace(y1/y2) = 1/s Laplace(y2/y3) = 1/s y3 = - y1

USERS GUIDE TO MODELS IN ATP

(s/1) 2. y2. All assignment types allowed in the linear COMBINE can be used.y1) COMBINE AS third_group laplace(y1/y2) := 1|s0 / 1|s1 laplace(y2/y3) := 1|s0 / 1|s1 y3:= sum(-1|y1) ENDCOMBINE write(sin(t).y1) ENDEXEC ENDMODEL -. plus assignments using linear and nonlinear regular expressions. t. Each statement in the COMBINE USERS GUIDE TO MODELS IN ATP . x. As in the linear COMBINE. there are no restrictions on the types of value assignments and on the number of limits that can be used.':'.47 The fourth set uses a z-transform and Laplace version of the derivatives: z-transform(y2/y1) = (1 .illustrates linear COMBINE groups in MODELS VAR y1.':'.y1) COMBINE AS second_group y2:= deriv(y1) y3:= deriv(y2) y1:= sum(-1|y3) ENDCOMBINE write(sin(t). ' :') COMBINE AS first_group y1:= integral(y2) y2:= integral(y3) y3:= sum(-1|y1) ENDCOMBINE write(sin(t).z -1) / (h + hz -1) Laplace(y3/y2) = s/1 y1 = .10. y3.y3 MODEL comb2 -. Using the iterated COMBINE for nonlinear equations Using the iterated COMBINE.2. h HISTORY y1 {dflt: sin(t)} y2 {dflt: cos(t)} y3 {dflt: -sin(t)} integral(y2) {dflt: sin(t)} integral(y3) {dflt: cos(t)} x {dflt: cos(t)} INIT h:=timestep/2 ENDINIT EXEC write(' ') write('Results at t='.y1) COMBINE AS fourth_group zfun(y2/y1) := (1|z0 -1|z-1)/(h|z0 +h|z-1) laplace(y3/y2) := 1|s1 / 1|s0 y1:= sum(-1|y3) ENDCOMBINE write(sin(t).5. all assignment statements placed in an iterated COMBINE are evaluated simultaneously.':'.':'.

a a := t * b ENDCOMBINE indicating that we would allow only 5 iterations for convergence to take place.48 statement list specifies how to calculate the value of one of the simultaneous variables.5 * y2 / t } y4 = deriv(y3) * (y2 < 4) ( Solution: y1 = 1 ) ( Solution: y2 = 2 t ) ( Solution: y3 = t 2 { max: 15 } ) USERS GUIDE TO MODELS IN ATP . The tolerance value is fixed at 10-8 times each value. A maximum number of iterations other than 10 can be specified inside braces following the keyword ITERATE.'. It describes a somewhat acrobatic set of simultaneous equations that should provide the following solution: y1 = y4 -y2 +2 { max: y4/y2 } y2 = 2 * t * y1 y3 = integral(y2) { max: 7. The maximum allowed number of iterations per step is user-definable. for example: COMBINE ITERATE {5} AS first_group b := 6 . b EXEC COMBINE ITERATE AS first_group b := 6 .a a := t * b ENDCOMBINE write('t='. The iterated COMBINE statement is used in the following format: COMBINE ITERATE AS identifier statement list ENDCOMBINE The same rules apply to the identifier as in the linear COMBINE.b. with a default of 10. shown in the section above using the linear COMBINE. can be rewritten for the iterated COMBINE as follows: MODEL comb1i VAR a. a='.t.'. a+b='. b='.'. The example of the two algebraic equations.a+b) ENDEXEC ENDMODEL Similarly.a. the example using the integrals could be rewritten as follows: COMBINE ITERATE AS first_group y1:= integral(y2) y2:= integral(y3) y3:= -y1 ENDCOMBINE Iterated COMBINE groups are solved using the Newton method. Here is an example that illustrates how an iterated COMBINE can be used with different types of assignments and multiple min/max limits.

y4) ( Solution: y4 = 2 t ) ( Solution: y5 = t 2 { max: 15 } ) MODEL comb3 -. sum(). y2. that is documented in the MODELS Rule Book (rule of thumb: always on signals that vary more slowly than the others. y2=' y2 '. we need to keep the time step small. and we apply some form of prediction on the inputs that should be simultaneous but that we chose to solve separately. but not in terms of the coefficients applied to the variables. As discussed at the beginning of the section on the COMBINE statement.0} -.3. it may be desirable in some circumstances to "squeeze" a set of nonlinear equations into a linear COMBINE. y3=' y3 '. either to save on execution time by eliminating the iteration. and we use a linear COMBINE to solve the remaining linearized set of equations simultaneously.5*y2*recip(t) } y4:=deriv(y3)*(y2<4) + 2*t*(y2>=4) y5:=sum(y3| +1|y2 -1|y4) ENDCOMBINE write('t='. y4=' y4 '.10. y5=' y5) ENDEXEC ENDMODEL 2. or to solve a convergence problem. Using the linear COMBINE for nonlinear equations It is possible to use the linear COMBINE statement with a group of nonlinear simultaneous assignments.49 + 2 * t * (y2 >= 4) y5 = sum(y3 + y2 . ' y1=' y1 '. y3. t.illustrates nonlinear COMBINE ITERATE groups in MODELS VAR y1. there is still a constraint on USERS GUIDE TO MODELS IN ATP . y4. c) we use a) or b). laplace(). Following are some options for dealing with sets of simultaneous nonlinear equations using a linear COMBINE: a) we replace the nonlinear COMBINE by breaking the evaluation loop open and by describing the equations in the best sequence one can find. should be 1 y2 {dflt: 2*t} integral(y2) {dflt: t*t} y3 {dflt: t*t} y4 {dflt: 2*t} y5 {dflt: t*t} EXEC COMBINE ITERATE {9} AS first_group y1:=y4-y2+2 {max:y4*recip(y2)} y2:=2*t*y1 y3:=integral(y2) {dmax: 7. The linear COMBINE group is restricted to linear expressions only in terms of the simultaneous variables of the group.wrong on purpose. or derivpol() inside a COMBINE can be a nonlinear expression in terms of variables other than the simultaneous variables of the group. This means that any coefficient of a diffeq(). of course there is the problem of deciding where it is best to open the evaluation loop. like the output of an integral or the output of a low-pass filter) b) we use a) on the nonlinear equations of the group. of course. because it's equivalent to using zero-order prediction (like Forward Euler). because this is prediction without correction. y5 HISTORY y1 {dflt: 0.5.

ERROR statement The ERROR statement is a simple sequential structure formatted as follows: ERROR statement list STOP It is normally used inside an IF statement to terminate execution when the model detects some specified condition. plus it saves the effort of having to reinvent it. An example would be to diagnose the situation with a write() statement or by writing information to a file. by localizing the iteration to where it's needed (so that in fact we provide both prediction and correction).a model contains at least one variable EXEC IF t>=2 THEN -. e) instead of building the iteration mechanism in MODELS.50 keeping the time step small. but depending on the situation. The list of statements can then describe a list of actions to be taken before the simulation is terminated. we rewrite the equations and provide a local iteration mechanism using a WHILE statement with an iteration condition -this allows to ease the constraints on the size of the time step. and we attach that external program as a regular submodel or function in our model. 2. We have the choice to represent and solve some of these subsystems using MODELS. we use an external program that solves the equations that we need to solve. STOP ENDIF ENDEXEC ENDMODEL USERS GUIDE TO MODELS IN ATP . local domain-specific solutions will always be more efficient that trying to use general representation or solution mechanisms that are not taking advantage of the specific conditions of the domain that is being represented. and some of them using other programs called by MODELS. b). When using MODELS to represent large systems. this approach is particularly appropriate when the set of equations is the result of trying to simulate in MODELS something that would be better represented and better solved in a program which has representations and solution methods specifically designed for the domain of the application.execute only when t reaches 2 ERROR write('*** Demonstrating error stop in MODELS ***'). or c) above. we might be able to use a larger time step than with the implicit zero-order prediction approach. we look at MODELS as the procedural and numerical glue between the locallymore-tightly-coupled subsystems.5. MODEL errstp -.illustrates the ERROR statement in MODELS VAR x -.11. d) instead of a).

the default directives of the called model. and what instance of that model is called (there can be more than one instance of a model).13. The first function of the USE statement is to identify what model is called. USE somemodel AS someid[i] . and initialized.reset_integral(expression) It could also be called from the model in which it is defined.. Indexed names are needed when placing a USE statement inside an indexed loop. the corresponding instance will update itself to the present simulation time of the calling model.. by running its EXEC procedure. Whenever a USE statement is executed during a simulation. USE statement The USE statement is the main point of call to instances of models used in a simulation. it will be automatically created. For example. This procedure would be called from another model as follows: instance_identifier. using the reserved instance identifier self: USERS GUIDE TO MODELS IN ATP . supposing that the called model includes a procedure called reset_integral(value).5.. ENDFOR letting the USE statement call a different instance of the model for each value of the loop variable i. This is done as follows: USE modelname AS instance_identifier use directives ENDUSE The instance identifier is either a name. or an indexed name.12. and the INIT procedure of the called model. Call to a procedure Procedure calls are auxiliary points of call to an instance of a model. If the instance does not exist at the time it is called. before running its EXEC procedure.. for example: FOR i:=1 TO n DO .51 2. The use directives are described in the section "Using a model". A procedure call is used for executing a named procedure of a specified instance of a model. The initialization will take into account the use directives of the USE statement. 2.5. the main point of call being the USE statement that creates and updates that instance during a simulation.

alpha) where normalized is the name of a procedure defined. They always apply to the model from where they are called. Call to a pre-defined procedure A number of procedures are pre-defined.5. in the same model.reset_integral(expression) If a procedure expects input arguments.2 respectively.14. for example: y := 3*x + self. WRITE1().write_y If a procedure returns values. Only three pre-defined procedures are available at this point. abs(x)+4 ) 2.1 or models. in this case. although more will be added in the future. 2. and therefore do not require an instance identifier (self is implied). then only its name is needed in the procedure call: instance_identifier. USERS GUIDE TO MODELS IN ATP . 2. and are available in any model. If a procedure expects no input argument. and sends a corresponding formatted line of text to the program output.52 self.14.2. write('This text is followed by a value equal to '. it is used just like a function is used in an expression.5.1.14. they are supplied as a list of expressions or array values when the procedure is called. WRITE() procedure This procedure receives a list of numerical and text values as input. WRITE2() procedure These two procedures are used just like the WRITE() procedure. Text values are strings of characters delimited by apostrophes or quotes.5.normalized( w. Numerical values are described using regular expressions. with the exception that they send the formatted line of text to a file named models.

1. true. for example a variable. we can refer to the value of a value-holding element of the model. Special expressions including the linear sum. by mentioning its name: name If the variable is an array. numerical and logical values. the polynomial of derivatives.53 3. and the integral expression. false. Referring to a named value-holding element In an expression. etc. First. and can calculate a list of values in the form of a onedimension array. It can include references to named value-holding elements. the declared constants of the model USERS GUIDE TO MODELS IN ATP . A set of numerical and logical operators is available for joining the members of an expression in an arbitrary level of complexity.the constants: global constants constants the pre-defined constants pi. 3.1..1. WRITING EXPRESSIONS Regular expressions are used in a model everywhere a value needs to be specified.expr] A simple set of rules determines how the named value-holding elements of a model are visible for reference inside used expressions in different parts of the model. Expressions can use array arithmetic. Any value in a model can be represented by an expression describing symbolically how to calculate that value. we can refer to a single element of that array by also indicating its index in the form of an expression: name[expr] We can refer to a group of elements of an array by indicating its range: name[expr. here are the definitions of the types of constant and variable named elements that can be referenced in a model: .. and calls to functions and procedures. can only be used as the right-hand side of an assignment statement.. Regular expressions A regular expression is the standard mechanism used in a model for representing how to calculate a value. 3. inf.

array index in any declaration .array dimensions of foreign models and functions visible only inside the FOR loop where they are defined visible only inside the statement function where they are defined FOR arguments function arguments An additional distinction needs to be made when using named elements inside a USE statement. timestep. except in a CONST declaration not visible in constant-valued expressions.54 data . for example. prevtime.value of a constant or data .) of cells in the submodel from the USE statement) USERS GUIDE TO MODELS IN ATP . startstep. such as: . as to whether we may be referring to a named element belonging to the local model or belonging to the used model: simulation variables visible in expressions defining the number of delay cells (allowing.directives of interpolation degree and delay cells . maxstep the declared inputs of the model the declared variables of the model the loop variables of FOR loops the named input arguments of statement functions Here are the rules of reference. fullstep. to use the size of the of the used model submodel's time step for determining the number (t. minstep. etc. endtime.the variables: global variables simulation variables inputs variables FOR arguments function arguments the declared parameters of the model the pre-defined variables global to a simulation: starttime. defining what elements are visible in what parts of a model: visible in any expression global constants constants data variables of any type visible in any expression visible in any expression. timestep. stoptime the pre-defined variables local to each instance of each model: t.

. not of the used model: USE . that is.n] := _____ But if the name n is used in an expression on the right-hand side (for example.n]:= 2*n*(t-2) Specifying the context of the named elements we are referring to inside a USE statement is not a simple matter. For example.n] or USERS GUIDE TO MODELS IN ATP . either with a keyword or an operator. we can write USE . In a USE statement... INPUT a[1. These rules do satisfy most applications. not the used model. if the name n is used in an array index of one of the assignments.. This way.55 data of the used model visible in expressions specifying the array index of data.. DATA n := _____ INPUT a[1... And the present set of rules doesn't allow the second example. according to the above rules. but we can always find examples where it would be useful to do just the opposite of what the rule says. not of the used model. INPUT a[1. an indication that tells directly if a name belongs to the local model or to the used submodel. For example.. The present set of rules allow us to use an implicit notation.. input. it would be useful to write USE . i2 := 2*i1 The only way we can do the first one..n] := b[1.sub.. it would be referring to the value n of the local model. it will be referring to the value of n from the used model. of arrays assigned a history.. is if n is a name defined in the local model. let's suppose there is a data n defined in both the local model and the used model (and carrying different values.. and output arrays.n] := b[1... and of arrays specified in interpolation degrees and delay cells Names used in any other expressions inside a USE statement are taken to be references to elements of the local model (calling model).n] or USE . INPUT a[1. The alternative to implicit notation would be to use an explicit notation. of course).. for example: USE . INPUT i1 := . defining the assigned value of an input)..sub..

It might be tempting to avoid the problem altogether by not duplicating names in the two models.1. And it is possible to include in a model functions represented in separate programs (foreign functions). Using a value calculated by a function MODELS provides a set of pre-defined functions for numerical and logical operations.. including statement functions and point list functions. etc.n]:=sqrt(v[1. and a set of pre-defined simulation-related functions like prevval().2.. In a small project. we need the flexibility of being able to define names without worrying about their use somewhere else. Here are some valid examples: 0. -1E-6. that is. Specifying a numerical value There are no different types of numerical values in MODELS. but it will become available in the future. we need a local name space for each model. v[1. the value of each input argument can be described using a regular expression. Notice that the left parenthesis must immediately follow the name of the function.prevval(w) y3:= min(va.1.n]) ----single input. For example: y1:= 2*abs(x+w) +4 y2:= prevval(x) . and only when the same name is used for different purposes in both the local model and the used submodel.i1 This is not available yet. multiple output As shown in these examples. 3.. which is one of the principles on which MODELS is designed. A value may be signed. Integer. delay(). single output multiple input.E3. but it simplifies the language greatly. and no specification of their storage to use a small or large number of bytes.n]) p[1.. No distinction needs to be made between Booleans or integers or reals. INPUT i1 := . Values are all stored as reals. USERS GUIDE TO MODELS IN ATP .3. 1. inside an expression. decimal.. It is also possible to define local functions in a model.1.56 USE . by indicating the name of the function and the value of its arguments.. deriv(). like abs(). But when we start building libraries of models. 0. and cannot be a decimal point. -0. This approach may require a slightly larger area of memory for storage. etc. and scientific notations are accepted. Note that this potential ambiguity of names exists only inside a USE statement.0. and it removes the burden of doing type conversion during the simulation. 0. and(). The first character following the optional sign must be a digit. sin(). When a function expects a list of values as input. single output single input.. These functions are all used in the same way.. using the maximum precision available. i2 := 2*sub. this is easy to do. 2*vb.2E-9 3. single output multiple input.

3. just like a function.1. and normalized is the name of a procedure called from the same model where it is defined.*. 3. for example: w := controller./ ** MOD logical unary op numerical unary op NOT true if either member is true true only if both members are true true if left greater than right true if left greater than or equal to right true if left smaller than right true if left smaller than or equal to right true if left equal to right true if left not equal to right addition and subtraction multiplication and division exponentiation modulo (division remainder) true if member is false or <=0 negative of member USERS GUIDE TO MODELS IN ATP . The only difference is that instead of indicating just the name of the procedure. Procedures that return one or more values are called from inside an expression.5.status y := 3*x + self.normalized( w. Logical and numerical operators A set of operators can be used inside an expression to express how its members are joined: logical binary op OR AND > >= < <= = <> numerical binary op +. alpha) where status is the name of a procedure defined in a submodel used with the instance name controller. and ones that also return a value or a list of values. Using a value calculated by a procedure Two types of procedures can be defined: ones that perform an operation on a model without returning a value to the point of call. including expressions that return multiple values in the form of an array.57 these values can be described using a list of expressions. we also need to indicate in which model instance it is operating.4.1.

= (a AND b) OR ((t-ton)>0) -. The same approach is used with the logical operations. and the returned value is false. not to the last member of that expression.(c/(d**2)) Parentheses can be used for explicitly indicating the sequence of operations. that is. the limits are applied to the value of 3*b+c. Here. the remaining members of that level are not evaluated.... As soon as a member in an OR sequence is found to be true. . the evaluation proceeds from left to right. These are static limits. the expression is not applied to c. Again.1. and do not affect how the expression is evaluated: a*b {min: 3*abs(c)-d} In the above example. notice that the limit is applied to the complete expression to which it is attached.. }) In this example.)+c if the value of b is found to be zero. Additional parentheses can be used to make this more explicit: a*((3*b +c) {min: .. It is possible to apply limits to part of an expression.. .. they are calculated and applied after the expression has been evaluated.. thus making it a separate expression to which a limit can be applied: a*(3*b +c {min: . Here are some examples: a AND b OR t-ton>0 a*b-c/d**2 -. that is. For example. 3. max: . max: . At each level of precedence. the evaluation of the sub-expression inside the parentheses is skipped. by enclosing that part in parenthesis. the rest of the sequence is not evaluated. c. and the returned value is true..= (a*b) . and the value of the expression is a*0 +c..6. In cases when the result of an operation provides a value that cannot be further modified at that level of precedence. As soon as a member in an AND sequence is found to be false. in the expression a*b*(more. Limits on a regular expression We can specify minimum and maximum limits to be applied to the value returned by an expression.58 The above sequence also shows the default order of precedence among the operators. the rest of the sequence is not evaluated. the minimum is applied to the result of the complete expression. }) USERS GUIDE TO MODELS IN ATP . not to the value of b.

3] [11.1-to-n divide -.9.1-to-n modulo -.n-to-n add -.2.6] := 10 * a[1.9] a[4.6] := a[1..1-to-n subtract -.1. Here are some examples: a[1.3.8] a[4. a[2..3] AND [0.3] / 0.1-to-n multiply -.20. and can return lists of values in the form of an array.10] [11.6] := a[1.0.6] := a[1....1 [10.6] -1 [0.12.3] [1.6] := a[1.. Individual values can be assembled in array form by enclosing them inside square brackets.3] -[1...0] a[4..6] := 10**a[1. 2.3] := c[1.n-to-n assign -.2] -.0] c[1.3] := 0 [0..6] := a[4.3] [12.n-to-n AND -.1] [0.bool(a[3])] a[1.3] -a[4...3] a[1.3] a[4.8] a[1.3] [10.30] a[4. USERS GUIDE TO MODELS IN ATP ...6] MOD 6 [3. See the respective sections for details..1-to-n limit -.0.1-to-n modulo = = = = = = = = = = = [-10..100..3] := 11 MOD a[1.6] := [1.3] := a[4.3] *10 [10.6..6] := a[1..8]} [10..3]**2 [1.3] +[10.....13] a[4...100.0.6] := 10 +a[1.1-to-n exponent -.= = = = = = = = = Functions and procedures can receive lists of values and arrays as arguments.1-to-n add -.n-to-n limit -.7.13] a[4.1] a[4.30] a[4.6] := a[1.3] +10 [11.10.1-to-n exponent -.4..0.12.1-to-n multiply -....3] := [1.1000] a[4.4] a[4.6] := 12 / a[1..30] a[4.1-to-n divide -.59 3.6] {max:[100..1..100.3] [10.n-to-n assign -.20.13] a[4....6] 10] a[4.. 3] [1.3] [0.20.12.6] {max:9} [9.6] := a[4.1-to-n add -.2. Using expressions with arrays Operators can be used with ranges of array elements..n-to-n subtract -.6] := a[4.1.1-to-n assign -. and can return groups of array values.3] := a[1..2] a[1. 2]] [1.-10.n-to-n subtract -.

allowing the use of nonlinear coefficients while still retaining the overall form of a linear summation. three special types of expressions can only be used as the right-hand side of an assignment statement. Linear sum A polynomial of variables can be grouped in a sum() expression. In MODELS. For example: sum((b+c*d){max:a1max}|x1 +c|x2) {min:minvalue. The coefficients are separated from their respective variables using the "applies to" operator.. and the integral expression. we write that coefficient followed by an "applies to" operator followed by no variable. each of these coefficients can be described using a regular expression. and also to the value of each of its coefficients. When used in a linear COMBINE statement. They are the linear sum. to prevent that coefficient to simply be included in the expression of the coefficient of the next term. but without any advantage over simply using a regular expression. which can be used anywhere in a model.2. without that first operator. the variables of the sum can only be any of the simultaneous variables of the COMBINE group. Minimum and maximum limits can be attached to this expression. This form of expression distinguishes the summed variables from their coefficients. sum((b+c*d)|x1 + c|x2) To express the bias term a0.. a special expression used in a linear COMBINE group of statements. the polynomial of derivatives. Special expressions Unlike regular expressions. the expression would be interpreted as: sum((a+b)+(b+c*d)|x1 + c|x2) The linear sum can also be used outside of a COMBINE statement.1. 3. The symbolic notation is: a0 + a1 ⋅ x1 + a2 ⋅ x2 +. sum((a+b)| +(b+c*d)|x1 + c|x2) because. max:maxvalue} USERS GUIDE TO MODELS IN ATP .2.60 3. a coefficient without a variable. But the coefficient expressions can refer to any other variable of the model.

.2. rewritten using the operator D to replace d/dt : (a0 D0 + a1D1 + a2D 2 +. That value is updated automatically at each time step. Δintegral = x1 + x0 ⋅ Δt 2 USERS GUIDE TO MODELS IN ATP .3. For example: derivpol((b+c*d){max:a1max}|D1 +c|D2)|x {min:minvalue. But the coefficient expressions can refer to any other variable of the model.61 3. The symbolic notation is: or. using the current value of x to calculate its updated value. and also to the value of each of its coefficients. Polynomial of derivatives A polynomial of time derivatives of a variable can be grouped in a derivpol() expression for use in a linear COMBINE statement. Integral expression Using the integral of a variable x in a model automatically creates an extra variable carrying the value of the integral.. The value of the integral is accessed using an integral expression: y := integral(x) That value can also be reset.2.) ⋅ x In MODELS. When used in a linear COMBINE statement. with the assumption that x is linear over each step interval. Minimum and maximum limits can be attached to this expression. The expression follows the same notation as used in a DIFFEQ statement. the expressions describing each coefficient are separated from the D operator using the "applies to" operator.2. max:maxvalue} 3. derivpol((a+b)|D0 +(b+c*d)|D1 + c|D2)|x The polynomial of derivatives can also be used outside of a COMBINE statement. the variable to which the derivatives are applied can only be any of the simultaneous variables of the COMBINE group. using the integral assignment statement: integral(x) := new_value The integral of x with respect to time is calculated using the trapezoidal rule. with the advantage of being able to indicate higher orders of time derivatives than those provided by the functions deriv() and deriv2().

=-1 for t>1 integral(x). y dlim nolim slim -.7 applied to 'nolim' HISTORY x {dflt: 0} y {dflt: 0} integral(x) {dflt: 0} integral(y) {dflt: 0} EXEC x:= 1 IF t>1 THEN x:= -1 ENDIF y:= x dlim :=integral(x) {dmax: 0. but without consequences on the numerical stability of the calculation. dynamic limit=0. no limit static limit=0. that is. this limit is a dynamic limit.7 integral(y).62 This is a reasonable assumption to make when the time step is small enough to follow the faster variations of x with respect to time. max:expression} -. dmax:expression} -. these faster variations are simply filtered out of the integral value. that is.dynamic limits To only apply a static limit.illustrates dynamic limit on integral in MODELS ----step signal =1 from t=0 to t<=1. Limits are applied to the value of an integral as follows: y:=integral(x) {dmin:expression. not the state of the integral. and dlim are shown in the following figure: USERS GUIDE TO MODELS IN ATP . the value of the limit modifies not only the output value of the integral. we apply the limit outside the use of the integral: y := integral(x) y := y {min:expression.7} nolim :=integral(y) slim :=nolim {max:0.7} ENDEXEC ENDMODEL The values of the variables x. slim. nolim.static limits Following is an example showing the different effect of using a dynamic limit and a static limit on an integral: MODEL ilim VAR x. In cases where the time step is too large. It is possible to apply limits to the calculated value of a time integral. with a possible loss of accuracy. Because the integral does carry an internal state from one step to the next. but also its internal state. the value that will be carried over to the next time step. a limit that affects only the value of the output.

63 USERS GUIDE TO MODELS IN ATP .

minimum and maximum. on the size of the local time step to be used for the step-by-step solution of a model. This is what is covered in this section. in Appendix C. It is also possible to specify or modify simulation directives in the USE statement of individual instances of a model. being either too large or too small. If the outside time step is too large for the model. Specifying the time step range It is possible to define local limits. smaller than the specified minimum. that is. That is covered in the section on "Using a model". and consequently the size of the time step. that is. 4. the model will subdivide the outside step into finer internal steps. which would provide no significant change in the state of the model. we can maintain it within an appropriate range. But this outside step may not be properly scaled to the fineness of representation needed to follow the internal dynamic operation of the model.the interpolation method to be used on the external input values at intermediate internal time steps . USERS GUIDE TO MODELS IN ATP . If the outside time step is too small for the model. When a model is called from outside for updating its internal state to a new simulation time. the interval of time since the last call for update determines the step that the model could take to carry on its operation.the number of delay cells to be reserved for storing the past values of variables and inputs affected by the delay() function . are discussed in the section on "Pre-defined local variables".and the history expressions describing analytically the value of some of the inputs and variables of the model prior to its simulation. the model will ignore the request for update. larger than the specified maximum.1. providing the possibility to dynamically adjust these limits.64 4. By specifying a minimum and/or a maximum limit on the size of the time step. The expressions used for describing these limits can make reference to the value of any variable in the model. to changing conditions monitored in the operation of the model. It is possible to specify default characteristics for these directives in each model description.the constraints placed on the size of the time step used by the model . SPECIFYING SIMULATION DIRECTIVES The simulation directives affecting the operation of a model are: . The implications of updating a model at a smaller or larger time step than the one used outside the model.

tau2. the method specified in the model definition can be modified later in the USE statement of individual instances of the model. for step. Quadratic interpolation uses the values y(t-2Δt). y2): 1 INTERPOLATION DEGREE(y3): 2 USERS GUIDE TO MODELS IN ATP . A default method can also be specified.2.1 * min(tau1. 1. and y(t) to fit a parabola used for finding the values of y(ti) between t-Δt and t. and that fits inside the allowed limit. tau2. tau3) 4. for all times ti between t-Δt and t0. tau3) TIMESTEP MIN: 0. The following notation is used: INTERPOLATION DEGREE DFLT: 0 DEGREE(y1. A finer step would be a waste of execution time. Linear interpolation uses a straight line between the values y(t-Δt) and y(t). But when this happens. A larger step would affect accuracy. y2): 1 DEGREE(y3): 2 and the INTERPOLATION keyword can also be repeated: INTERPOLATION DEGREE DFLT: 0 INTERPOLATION DEGREE(y1. y(t-Δt). we don't have values for the external inputs to the model at those intermediate time steps. respectively. Specifying the input interpolation method When the time step size is limited to a maximum value. the model will select a local time step that is a sub-multiple of the outer time step. TIMESTEP MAX: 0. The directives are flexible. We use the input interpolation directive to specify what method of interpolation will be used for estimating the value of the inputs at the sub-steps. and quadratic interpolation. and the outside step exceeds that value. that is. When not specified. Step interpolation is no interpolation. or 2. linear interpolation is used. Also.65 Typically. We can select different methods for different inputs. linear. y(ti) keeps the value y(t-Δt). the size of the time step would be maintained between 1/100 and 1/10 times the size of the smallest time constant of the model.01 * min(tau1. The degree of the fitting polynomial can be specified as 0.

The size of the storage needed for recording the past values of a variable to be accessed by a delay() function depends on what size of delay will be used. considering that both the size of the delay used and the size of the time step can be described in the form of symbolic expressions. for example. Specifying the size of the delay storage Many functions of MODELS require past values of a variable for calculating the value of the function. And this estimation is not necessarily so simple. derivatives and integrals. that is. the expression specifying the number of cells will include a reference to the size of the time step used in the model. the value of which may vary dynamically during a simulation. and that the size cannot be adjusted later. The storage needed for recording these past values is taken care of automatically by the solver. delay2)/timestep +1 CELLS(y1. It must be understood.66 4. The storage needs can be considerable. for use with the function pastval(). because the timestep can also vary. would require 500 cells of storage for that variable. in the model definition and/or in the USE statement. however. a process that consumes more execution time. The following notation is used: DELAY CELLS DFLT: max(delay1. Choosing to store all past values in order to avoid having to specify any storage dimensions is not a practical alternative either. As a footnote. The present approach is to provide a simulation directive. indicating how many cells must be reserved for storing a moving window of past values for each variable accessed by a delay() function. in a simulation using a time step of 1 ms. we have to specify the maximum delay time for which the device will be used. This has been tried in earlier versions of MODELS. specifying the number of cells is also the approach that was used in TACS. A reference to the variable timestep would be using the value of that variable at the time when it is used. especially when considering the fact that most of those past values are never used. For example. Specifying the maximum time delay in MODELS would not suffice. because the storage window is never much longer than two or three cells back depending on the level of interpolation needed. at the time when the instance of the model is created and initialized. and on the size of the time step at which the samples are recorded.3. although in a different form. a delay value of 500 ms. This can be easily determined by the solver. that this expression is evaluated only once when each instance of the model is created. Typically. For each delay device (type 53). and require paging from memory to external storage. y2): 50 CELLS(y3): 10 USERS GUIDE TO MODELS IN ATP . Such is not the case for the delay() function.

But if t-delaysize < t0. Specifying history expressions To summarize what has been discussed in other sections. When a default value is not specified. From this definition. etc. To understand the need to specify history functions. 4. as in y := delay(x. for example. a default value of 100 cells will be used. then that value is undefined unless the model has access to an analytical expression describing how to calculate the value of x at times t<t0 .67 and the DELAY keyword can also be repeated. this is also useful for defining the initial values of a model when it is impossible to predict exactly the time at which an instance of the model will be first executed during the simulation. deriv(). using a delay function which would make reference to the past value of a variable for a time preceding the time of the first execution of that model instance. The other is histdef(y). One is hidden and is made internally by the solver whenever it needs to access a non-existing past value from a time t preceding the simulation of the model. it can be seen that history expressions can be used also for defining initial values.t) for the generic value of time t. One is histval(y. then the value of x at that time has been stored in the delay storage cells of the model. diffeq(). Two functions are available for this. it is possible to specify history expressions in three places in a model: as simulation directives in the model definition.t1) which will use the history expression of variable y to evaluate y(t1). which is equivalent to writing histval(y. That is the purpose of being able to define history expressions for some of the variables and inputs of a model. A history expression is an expression that the model will use when it needs to find the value of a variable or input from a time for which no value has been stored in the model's running history. or when needing pre-simulation values for the first few evaluations of a laplace(). In addition to allowing the definition of history expressions as an explicit function of time. As discussed in the section about the INIT procedure. for example when needing a delay value from a time before the simulation was started. two types of references to the history expression of a variable or input are possible.4. consider. The possibility of referring to the variable t in history expressions allows us to define history values as regular expressions described as a function of time. The other type of reference is one that can be written explicitly in the model description in any expression. delaysize) which corresponds to asking for the value of x at time t-delaysize. as simulation directives in the USE statement of each instance of USERS GUIDE TO MODELS IN ATP . If t-delaysize >= t0.

.n2] {dflt: array expression} element -. If it is written as a list of values.. expr3.. When no expression is specified..n2] {dflt: expression} HISTORY y[n1. and depends on data determined in the USE statement. the history expression may include a reference to the variable t. whatever its size. it depends on how the array expression is written.. the directive indicates that a history expression will be needed for that variable in the USE statement of each instance where the model is used. In the second case. The expressions will be evaluated only when and if required during the simulation. Consider that HISTORY directives are only declarations of history expressions. ]} then there may not be enough values in the list to cover the size of the group.n2] and to specify the history expressions in the USE statement.n2] {dflt: [expr1. expr2.n2] := [expr1.same value for each element -. and in the INIT procedure of the model.. In the first example above. The notation is the following: HISTORY y1 y2 {dflt: 0} y3 {dflt: A*sin(omega*t)} As shown here. ] USERS GUIDE TO MODELS IN ATP . A history expression specified as a simulation directive in the model definition is only a default expression that the model will use when it is not re-specified in the USE statement or in the INIT procedure. expr3.individual value for each There is one difficulty with assigning a history expression in the model definition if the exact size of the group is variable. The solution for this is to declare only the names in the model definition: HISTORY y[n1. because the same value will be assigned to all elements of the group. for example: HISTORY y[n1. they are not a list of executed statements. where the number of required values will be known: HISTORY y[n1. expr2.68 the model.. there is no problem. ... The initial value of integrals can also be specified using a history expression: HISTORY integral(y) {dflt: expression} It is possible to assign history expressions to groups of array elements: HISTORY y[n1. .

The same data name can carry different values in different instances of the same model. ENDUSE A data element that had been assigned a default value in the model definition does not need to be specified in the USE statement.2.overriding a default value of 50 . defined when a new instance of a model is created in a USE statement. 5... We can also specify different simulation directives for different instances of the same model.. 5.number of terminals -. USERS GUIDE TO MODELS IN ATP . ENDUSE -. Assigning input values A model receives information through its input elements. Input values are specified in a USE statement using the following notation: USE modelname AS instance_name DATA n := 3 INPUT vterm[1. replacing default value An input element that had been assigned a default value in the model definition does not need to be specified in the USE statement. Data values are assigned in a USE statement using the following notation: USE modelname AS instance_name DATA n :=3 -. Assigning data values As discussed in the section about writing a model. the new value will replace the default value of the model definition. It is in the USE statement that we specify how to calculate. It is in the USE statement that we assign values to the data and the inputs of a model.3] := [va.vb. the values of its inputs.an array dimension used in the model freq := 60 -.value of measured terminal voltages -. data are constant values of a model.vc] vref := sqrt(3)*abs(v0) . But if it is.reference voltage.1.69 5. such as parameters and array dimensions. the new value will replace the default value of the model definition. at each time that the model instance is called. USING A MODEL Each USE statement defines an individual instance of a model. But if it is.. and that we have access to the values of its outputs.. Different input expressions can be assigned to the inputs of a model in different instances where the model is used.

3] := vtmax[1.3. Notice how the variable named vmax exists in both the calling model and the called model.4...vc] -. are names of variables in the calling model. The values of the outputs of a model can be assigned to variables of the calling model. TIMESTEP MAX: 1E-4 MIN: 1E-5 USERS GUIDE TO MODELS IN ATP .vb.. are names of output variables from the used model. 5.. the assignment operator ":=" is used instead of the "dflt:" attribute. the number of delay cells to allocate for the storage of the past values of some variables and inputs.number of terminals INPUT vterm[1.. The formats are similar to those used in the model definition. Retrieving output values The only values of a model that are visible to a calling model in a USE statement are the values of the model's outputs.3] and vmax. Specifying simulation directives The simulation directives of a model are the limits on the time step size. the interpolation method used for different inputs of the model during sub-steps. ENDUSE An important aspect of using a model is illustrated in the above example. and the history expressions to associate with some variables and inputs of the model. as shown below: USE modelname AS instance_name DATA n := 3 -. using an output assignment inside a USE statement.value of measured terminal voltages vref := sqrt(3)*abs(v0) -. they can be defined individually for each instance. replacing default value OUTPUT vmax[1.70 5. just as for data and inputs. vmax[1.3] maxval := vmax . possibly replacing the default directives of the model definition. they apply to all instances of the model.3] and maxval. vtmax[1. The names on the lefthand side of the output assignments.. with the difference that for history expressions. Simulation directives can be specified in the model definition and in the USE statements.. The names on the right-hand side of the OUTPUT assignments.reference voltage. In the model definition. In the USE statements. This illustrates how the meaning and the value of a named element are local to each model where the name is defined. with a different meaning and a different array size.3] := [va.

71 INTERPOLATION DEGREE DFLT: 0 DEGREE(y1. The ITERATE is indicated just after the instance name. y2): 100 CELLS(y3): 20 HISTORY y1 := B*cos(omega*t +rad(shift)) 5.repeating from model def. for example when called from inside an iteration loop. for clarity -. and re-starts from that saved initial state at each re-update of the model at the same time step. USERS GUIDE TO MODELS IN ATP .5. This is needed when a model is used by another model or program from inside an iteration loop. It requires that the solver be able to reset the state of the called model to its previous original state from which to execute the model again.modifying from model def -. MODELS saves the initial state of the model when called at a new time step. This is done automatically by the program when using the option ITERATE in a USE statement. When this option is specified. Calling a model more than once per time step It is possible to call a model for update from a USE statement more than once per simulation time.modifying from model def DELAY CELLS DFLT: 200 CELLS(y1. The following data case provides a simple illustration. y2): 0 DEGREE(y3): 1 -. as follows: USE modelname AS instance_name ITERATE This option indicates to the solver that the model can be used more than once at each time step.

in='. and the instance names would need to be indexed. A loose definition of the state variables of the model would be the set of variables for which the model needs a value from time t1 in order to calculate the new state of the model at time t0. USERS GUIDE TO MODELS IN ATP . the program would create separate instances of that model for each pass. '. and are available to the model at the beginning of the next execution. This is done automatically by MODELS. Let us consider a model with a certain number of variables.the values of all of its variables . t. out) ENDEXEC ENDMODEL Notice how it is the same instance of the model that is re-updated for each value of i inside the FOR loop.the state of all submodels used in the model. When talking about the "state" of a model. this description of the state of a model instance at the completion of an execution step includes: . a='. we need to retain the value of some variables of a model from one simulation step to the next. All values of a model at the end of an execution are kept in memory. '.72 MODEL iteruse MODEL sub EXTERNAL VAR a EXEC FOR i:=1 TO 3 DO USE sub AS sub ITERATE INPUT in:=i*t OUTPUT a:=out ENDUSE write('in iteruse at t='. in. If we did not indicate the keyword ITERATE. as a snapshot of all information relevant to the condition of a model at a given instant of time. t. the word "state" is taken in its generic meaning. as: USE sub AS sub[i] 5.6. out='. As indicated in the Language Manual. '. without requiring any special directives. a) ENDFOR write(' ') ENDEXEC ENDMODEL MODEL sub INPUT in OUTPUT out VAR out EXEC out:=10*in write('in sub at t='.the history of some of its variables . State of a model Normally in a simulation.

a model needs to have access to the previous value of a variable x when x is used in an expression before a value has been assigned to it at the current execution time. USERS GUIDE TO MODELS IN ATP . The history of x is also used by the program in the implicit value assignments of laplace(y/x). A model also uses the history of variable x whenever a time function is applied to x. etc. laplace(x/u). This is also why there is the possibility of assigning history expressions to a variable or an input. Values that need to be carried from the past are automatically made part of the running history of the model. integral(x). which can include values from the previous step and from earlier steps of the simulation. such as deriv(x). and the same for diffeq() and zfun(). so that values can be found by the program if needed for reference to instants that fall before the start of the simulation of the model. For example.73 This is what is taken care of automatically by MODELS. and implicitly in interpolations.

we assemble the data case as follows: BEGIN NEW DATA CASE . BEGIN NEW DATA CASE BLANK When we use a MODELS section without a circuit. The MODELS section of a data case When we have one or more models in an ATP data case. Models can also be used in ATP for performing calculations in the frequency domain. using a type-94 nonlinear component.. USE . and after the TACS section. VAR . we need to define a MODELS section. MODEL ... USING MODELS IN ATP This section covers the details of using MODELS in ATP..... When we use the MODELS section in conjunction with a circuit. .. its use is specified directly in the circuit...74 6.. ENDMODELS circuit description ..... if any.. if any. OUTPUT . It is placed before the branch section. we use the following: USERS GUIDE TO MODELS IN ATP .... 6.. . MODEL . RECORD . We use the words MODELS section to refer to the section of an ATP data case containing the declarations and directives related to defining and using one or more models in a simulation. when conducting FREQUENCY SCAN simulations. MODELS INPUT . USE . All models used in a simulation are defined in the MODELS section. When a model is used as a control-type component.1.. When a model is used as a circuit-type component.. its use is also specified in the MODELS section in a USE statement. plotting instructions .....

. or by the name of a node to which it is connected.. They are: .... USE . USE . We do the same for a switch status.1.the status of a switch .. we just identify the name of the node..variables from the TACS section . RECORD . MODELS STAND ALONE VAR . we specify its name.. MODEL ... MODEL . Inputs from the circuit When we declare an input in the MODELS section.1.. Inputs from ATP Some values can be passed from the circuit to the MODELS section at each time step of the simulation.the current through a switch . This is done using the following notation: INPUT name1 name2 name3 name4 switch name5 name6 { { { { v(nodename) } i(switchname) } imssv(nodename) } imssi(switchname) } ----voltage at a node current through a switch imaginary part of s-s voltage at a node imaginary part of s-s current at a { switch(switchname) } { mach(variable) } -.. For a current. . BEGIN NEW DATA CASE BLANK 6.the voltage at a node ....1.status of a switch (open or closed) -.1. They are: .internal values from the ATP program 6. we identify the switch (the only way to measure a current in ATP) by its branch name.1. and we describe what value is carries. other types of values can also be used as inputs to the MODELS section.values from a PL4 plot file . USERS GUIDE TO MODELS IN ATP .75 BEGIN NEW DATA CASE . ENDMODELS plotting instructions .variable of a machine For a voltage..electrical and mechanical quantities from a machine component In addition. .....

POSTPROCESS PLOT FILE MULPPF 2 LUNPPF 63 L63TYP 3 where: . ENDMODEL ... But in the steady-state phasor solution... For a machine value. the values of voltages and currents are calculated in the time domain.. vb-vc. both real and imaginary parts of a voltage or current are available. indicate to ATP that an existing plot file is to be processed: C --. adjust the time step accordingly to keep the simulation synchronized with the PL4 data . MODEL test INPUT v[1. and the imaginary part in imssv() and imssi(). When the inputs expected by a model are in the form of an array.1.selecting a different unit may conflict with units already used by ATP USERS GUIDE TO MODELS IN ATP .2. and we pass them to the model in array form.76 During the simulation. we use the variable names identified in the description of the machine.if left blank. At simulation time t=0.3] := [va-vb.MULPPF defines in what multiple the original plot points will be used .template for next card.1 means all points will be used..LUNPPF indicates the I/O unit allocated to the connection .1. a default value of 63 is assigned .if using a multiple. the real part of the complex value is carried in the regular v() and i(). as illustrated below: MODELS INPUT va {v(NODEA)} vb {v(NODEB)} vc {v(NODEC)} . USE test AS example INPUT v[1... n means every nth point is used . vc-va] .phase-phase 6.. -.this is the same request as when using POSTPROCESS PLOT FILE with TACS .. we declare them as individual input variables in the MODELS section. Inputs from a PL4 plot file It is possible to input values from a PL4 file directly into the MODELS section.3] . The connection to the PL4 file is done in 3 steps: 1) before the MODELS section.

2=FORMATTED. curr {PL4(2)} MODEL postprocess_example INPUT voltage. timestep) ENDEXEC ENDMODEL USE postprocess_example AS test INPUT voltage := gen. UNIT=63 FILE=dc45.pl4 3) in the MODELS section.1. gen_1 INIT integral(voltage) := 0 integral(power) := 0 histdef(voltage) := 0 -.1=UNFORMATTED.77 . energy. since use every 2nd step C print points connec s-s minmax vary again plot 1 1 0 0 1 -1 0 2 5 5 20 20 50 50 MODELS STAND ALONE INPUT gen {PL4(1)}. power.L63TYP indicates the type of formatting of the PL4 file .needed for the delay function ENDINIT EXEC flux := integral(voltage) energy := integral(power) power := voltage * current gen_1 := delay(voltage. first line C of plot data at time t=0 is ignored.PL4 is the input type . It is not required to use MODELS C as STAND ALONE. current := -curr USERS GUIDE TO MODELS IN ATP . but can also be mixed with solution of a circuit. current VAR flux. specify any number of signals from the PL4 file as inputs to MODELS: INPUT gen {PL4(1)} curr {PL4(2)} where: .050 { Note DELTAT is twice that of DC-45. Just like with TACS. a default value of 1 is assigned . but illustrates the new C connection to a plot file from MODELS. UNIT=63 FILE=dc45. 2. etc indicate the corresponding curve number in the PL4 file The 3rd subcase of benchmark case DC46.UNFORMATTED is the default because it allows use of double precision when preparing the PL4 file using the request CUSTOM PLOT FILE (see the July 1995 issue of Can/Am EMTP News for details) 2) before the MODELS section.pl4 ! { Expected to be C-like (L4BYTE = 1) C deltat tmax .DAT illustrates the use of PL4 values as input to the MODELS section: BEGIN NEW DATA CASE C BENCHMARK DC-46 C 3rd of 3 subcases produces the same solution. POSTPROCESS PLOT FILE 2 63 3 $OPEN. open the ATP connection to the existing PL4 file: $OPEN.000100 .if left blank.gen and curr are arbitrary input names of the MODELS section . 3=C-LIKE .

while still being able to add one or more models to the data case as needed... ENDMODELS circuit description .circuit solution .78 ENDUSE RECORD gen AS gen test. During the simulation. BLANK card ending TACS section MODELS . The voltages BUS2 and BUS3 are input to TACS.MODELS section solution The following subcase of benchmark case DC30.DAT illustrates the use of TACS variables as input to the MODELS section: BEGIN NEW DATA CASE C 4th of 4 subcases is the same as the first and the third. the order of execution at each time step is: .gen_1 AS gen_1 ENDMODELS BLANK card ending plot cards BEGIN NEW DATA CASE BLANK curr AS curr test. except that C it uses both TACS and MODELS.0E-3 USERS GUIDE TO MODELS IN ATP .flux AS flux test. GRID is output from MODELS.0E-6 3.. We can use the value of any TACS variable as input to the MODELS section. C deltat tmax xopt copt epsiln tolmat tstart 1. this allows the use of existing data cases containing a TACS section. a TACS variable named signal could be used as input to the MODELS section as follows: INPUT somename {TACS(signal)} indicating that the TACS variable named signal would be available in the MODELS section under the name somename.. C VSW is output from TACS and input to MODELS.. TACS HYBRID ..TACS section solution .energy AS nrg 6.power AS power test. Typically. C Compare values at t=0 with 3rd subcase.1. Inputs from the TACS section It is possible to include both a TACS section and a MODELS section in the same ATP data case...3. For example. When both TACS and MODELS are used in a data case. the TACS section precedes the MODELS section: BEGIN NEW DATA CASE .1.

0 1. -2. A local name can be specified.E9 NAME: Valve ! { Request "NAME: " of cols. BLANK card terminates electric network sources { No node voltages printout/plotting BLANK card ending node voltage request BLANK card ending plot cards BEGIN NEW DATA CASE BLANK 6.value of ATP variable 'tmax' USERS GUIDE TO MODELS IN ATP .0508 -1. BUS2 BUS2R 24.5E-3 90BUS2 90BUS3 99VSW = BUS2 . BUS1 2. along with an indication of the name of the ATP program variable used as input: INPUT atp_t { ATP(t) } tmax { ATP(tmax) } -.0 0.1. GRID 12 BLANK card ends all switches 14GEN 66500.4.value of ATP variable 't' -. 1. Inputs from ATP program variables Any numerical non-array variables from the ATP program that are accessible to ATP's SPY can also be used as inputs to MODELS.1 BUS3 .1.34 BUS3 BUS3R BUS2 BUS2R BLANK card terminates electric network branches BUS2 BUS3 -1. 50.1 BUS2 0.017 BUS3 490. 3-8 precedes A6 valve name in 9-14 11BUS2R BUS3R 20.dv AS dv ENDMODELS C ============================================================================== GEN BUS1 15.79 C print points connec s-s minmax vary again plot 1 1 0 0 1 -1 5 5 20 20 100 100 TACS HYBRID 1DUMMY +UNITY 1.BUS3 33BUS2 BUS3 VSW BLANK card ends all TACS data C ============================================================================== MODELS INPUT deltav {TACS(vsw)} OUTPUT grid MODEL dc30 INPUT dv VAR grid OUTPUT grid EXEC IF abs(dv)>=1.9 BUS1 BUS2 0.5e8*t +1e5 THEN grid:=1 ELSE grid:=0 ENDIF ENDEXEC ENDMODEL USE dc30 AS dc30 INPUT dv:=deltav OUTPUT grid:=grid ENDUSE RECORD dc30.

. and of the procedure deposit() that can also be used in a model. This is discussed in the following section on Outputs to ATP.. BLANK card ending electric network source cards -. step := atp(istep) estimated_voltage := atp(voltk[2*index]) ..step AS istep tmax AS tmax ENDMODELS C ============================================================================== A1 A2 1. BLANK card ending electric network branches BLANK card ending switches 14A1 100. 0. This provides the added advantage of being able to also access elements or array variables used in the ATP program.get value of ATP variable 't' -. by using the special procedure deposit().80 Another way to have access to internal variable values of the ATP program is to use the special function atp() in an expression inside a model description. atp(e[2])) write(' e(3) = '. BEGIN NEW DATA CASE { ATPVAR.. MODEL example . -1. of the special function atp() that can be used in a model. A2 1. which is not possible in the INPUT declarations of the MODELS section. EXEC .DAT } C deltat tmax xopt copt epsiln tolmat tstart 0.. Following is an example combining illustrations of the atp() input that can be used in the MODELS section.get value of ATP variable 'istep' -.value of element of array 'voltk' It is also possible to modify the value of internal program variables of ATP.write value of ATP variable e(2) -.001 0.get value of ATP variable 'tmax' -.modify value of ATP variable 'tmax' USERS GUIDE TO MODELS IN ATP . ENDEXEC ENDMODEL -.value of ATP variable 'istep' -.0095) ENDIF ENDEXEC ENDMODEL USE atpvar AS example ENDUSE RECORD atp_t AS t example. atp(e[3])) step := atp(istep) IF step=4 THEN deposit(tmax..write value of ATP variable e(3) -. 50.005 C print points connec s-s minmax vary again plot 1 1 0 0 0 0 0 0 C ============================================================================== MODELS INPUT atp_t {atp(t)} tmax {atp(tmax)} MODEL atpvar VAR step EXEC write('*** e(2) = '.

value ) USERS GUIDE TO MODELS IN ATP . without distinguishing between the two. In either case. The latter is done using a RECORD directive. controlling the value of voltage and control sources..1. discussed in a separate section below. everywhere a TACS variable can be used. There is a difference between declaring a MODELS variable as output to the circuit.comment describing the value -.comment describing the value The names of these outputs are stored and used by ATP. The deposit() procedure allows a model to modify the value of any numerical program variable of ATP that can be changed using ATP's SPY command DEPOSIT. Variables declared as outputs of the MODELS section are not automatically recorded for printout or plotting. switches. and specifying a variable to be recorded for printout and plotting during the simulation. value ) DEPOSIT( name[ expr ] . The deposit() procedure can be used to modify the value of single variables and of single or multiple elements of array variables of the ATP program.2. The ATP documentation of the SPY commands describes what variables can be modified. and are therefore limited to the 6-character naming convention of ATP.. the keyword TACS used on these cards indicates control variables coming from a "control system" described outside the circuit. -. controlling the value of a type-91 resistance and other nonlinear components. Also. Another type of output to ATP can be made directly from inside a model. No modifications have been made to the format rules of ATP branches. unless they are also included in the RECORD directives of the MODELS section. and controlling the value of internal variables in the machine components The output names are declared using the following notation: OUTPUT name1 name2 . and can be used as control variable to the components of the circuit. only single outputs. and machines regarding the use of control variables from TACS or MODELS. value ) DEPOSIT( name[ expr . Applications include controlling the operation of switches. no arrays can be used. Outputs to ATP Any variable declared as output in the MODELS section becomes visible in the circuit. using either TACS or MODELS. sources.81 BLANK card ending voltage printout requests BLANK card ending plot requests BEGIN NEW DATA CASE BLANK 6. expr ] .. using the following notation: DEPOSIT( name.

Also. the variable field from a model used as subuse in a model with instance name top.r AS rs The first example adds to the printout list. on the left-hand side of the output assignments. by using a RECORD directive.SRC1". 6. and by specifying a 1. because the element source1 exists at the top level of the MODELS section.82 where name is the name of a program variable accessible from SPY.comment describing the variable -. RECORD for printout/plotting Any value-holding element existing in MODELS can be added to the printout/plotting list of ATP.field AS field1 RECORD source1 AS src1 RECORD SRCE__CT1___LIMR__.1. for example: RECORD controller_A.. receiving values from the outputs of the used models.1. the value of an element named control. Each RECORD identifies an element by specifying its path-name in MODELS. the element named source1 defined as a variable or input or output of the MODELS section. identified in the list as "MODELS CTRL"..4. The second example adds to the printout list. idendified as "MODELS .comment describing the variable The names of these variables are stored and used by ATP. and are therefore limited to the 6-character naming convention of ATP. The third example adds to the printout list.FIELD1". from a model used at the top level of the MODELS section with the instance name controller_A. identified as "MODELS . only single variables.control AS ctrl RECORD top. Note that the outputs of the MODELS section can also be used for the same purpose as the variables. They are named and declared as variables using the following notation: VAR name1 name2 . 6. Note that no instance name is needed in the path. outside of any model instance.subuse. An illustration is included in the example used in the previous section.3. it is possible to define internal variables that can be used for passing values between the models used in the MODELS section. -.to 6-character label to be used by ATP in the printout heading. Values are assigned to these variables in the USE statements of the MODELS section. no array variables can be used. and where the index of the array elements can be specified using regular expressions. Variables in the MODELS section In addition to the input and output variables that can be declared in the MODELS section. USERS GUIDE TO MODELS IN ATP .

Here is an example: BEGIN NEW DATA CASE C deltat tmax xopt copt epsiln tolmat tstart 1. 6.1.get value of ATP variable 't' -. The $INCLUDE command of ATP can also be used to refer to a file containing a model description.83 The fourth example adds to the printout list. which is not necessarily at the initial time of the simulation. Model descriptions All models used in a simulation must be described in the MODELS section of a data case.get value of ATP variable 'tmax' { insert file containing the model 'atpvar' USE atpvar AS example ENDUSE RECORD atp_t AS t example. they can also be declared at the top level of the MODELS section. the element named r from the model named limr used by a type-94 component connected to the circuit between nodes SRCE and CT1. C print points connec s-s minmax vary again plot 1 1 0 0 0 0 0 0 C ============================================================================== MODELS STAND ALONE USERS GUIDE TO MODELS IN ATP .88888) because it would affect the scale limits of a plot if we used that value until the time an actual value starts being assigned to the variable. something like minus zero. And of course we cannot use the undefined value from MODELS (=88888. Non-existing instance names found in a record path don't trigger an error. as well as models used from a type-94 circuit component. above. as it may simply not have been yet created in the simulation. instead of including the full text of the model in the data case. with the label "MODELS .5. The example illustrating variables of the MODELS section. 10. It is therefore not an error for the program to not find a given instance name.step AS istep tmax AS tmax ENDMODELS Just as foreign models can be declared inside a model (see Foreign submodels). The notation is identical to when a foreign model is declared inside a regular model. could be rewritten in a more simple way using an $INCLUDE command: MODELS INPUT atp_t {atp(t)} tmax {atp(tmax)} $INCLUDE atpvar. This includes models used from a USE statement in the MODELS section. The only way to provide a clear indication that the record has an undefined value would be to be able to assign it the value "undefined".RS".m -. because an instance name starts its existence only at the instant of the simulation when the associated instance of the model is first used.

MODELS formatting vs.. For example. for the Salford version of ATP. The other reason is that a model written with this type of comment lines would not be compatible with other versions of MODELS used outside of ATP.1.set history of xvar[. Typically. Then we have to link our compiled file with the compiled files of ATP using a linker compatible with the compiler(s) that we have used. ixvar:3} USE ftnmodel AS example DATA xdata[1]:=3 -. a2.. C. t+1. 6.load inputs xin[1]. as they really don't belong to the MODELS language. It also means that we need all the compiled files of ATP in order to be able to relink them with the additional files that we create. There is no need to start blank lines in the MODELS section with the C-in-column-one format used for indicating comment lines in the rest of ATP. a3. identified with the instance name example.xin[1] AS xin1 example. or Pascal compilers for our routines. ixin:3.] OUTPUT a1:=xout[1]. three variables are defined. we must use the same compiler that the rest of our version of ATP was compiled on.set value of xdata[1] INPUT xin[1. we can use the Salford Fortran. Even if the "C "-formatted ATP comments can be used in the MODELS section without producing a syntax error.its value after each execution a1 AS xout1 ENDMODELS C ============================================================================== BLANK card ending plot requests BEGIN NEW DATA CASE BLANK In this example. and the Salford linker. a1. The foreign model is declared. Various values are then recorded during the simulation in the printout/plotting list of ATP.6..xdata[1] AS xdata1 example.xvar[1] AS xvar1 -. a3:=xout[3] ENDUSE RECORD example. t+2] -. xin[2]. a2. One is simply style. ATP formatting MODELS has syntax rules separate from the formatting rules of ATP. it allows the insertion of white space (space characters. The details of this process are dependent on the platform on which we are running ATP. One instance of that model is used. USERS GUIDE TO MODELS IN ATP . tabs.84 VAR a1. a2:=xout[2]. Among other things. we must link our program with ATP. a3 MODEL ftnmodel FOREIGN sample_model {ixdata:1. carriage returns. To use our own Fortran or C code with ATP.3]:=0 -. xin[3] HISTORY xvar[1. blank lines) anywhere in the text of a model and in the MODELS section of a data case. ixout:3. their use is not encouraged for two reasons.3]:=[t.

Using a model in the MODELS section When we access a model with a USE statement in the MODELS section. This approach can also be used without problem for representing passive circuit elements in the form of a Norton equivalent. are not a limitation. In this case. as any physical control component will include transmission delays in its operation.or current-driven voltage source or current source). if present. range of time step. This includes any component for which a Norton equivalent would use concurrent (as opposed to delayed) values of voltages or currents to calculate the value of the equivalent source (for example.2. USERS GUIDE TO MODELS IN ATP .85 6. and specifying history expressions. where the value of the equivalent current source. capacitance. the model instance that we create interacts with the circuit as a control component. This is the mode of operation that was also available between the circuit and TACS. The control signals are simply applied to the operation of the circuit at the next time step of the simulation. and delay cells storage size. This includes assigning data and input values. When used for representing true control components. is calculated using values of voltages and currents already delayed by one or more time steps (see the representation of inductance. a variable current-limiting resistance. this decoupling. input interpolation methods. and a variable load. The control-type component receives measurements from the circuit (the inputs). and its one-step delay. The complete data case represents a circuit that uses three models to describe the operation of a variable source. This forced decoupling will create numerical stability problems when used for representing circuit components that should be solved simultaneously with the rest of the circuit. and transmission lines in ATP). it is necessary to use a type-94 Thevenin or iterated circuit element to connect the model representing the operation of the component. Here is an example where models are used from USE statements in the MODELS section. ATP performs no iteration. and sends back control signals (the outputs) to be used in the circuit. retrieving output values. any type of voltage. This is to be compared to the circuit approach available when using a model with the type-94 circuit element (see a separate section below). The USE statement available in the MODELS section lets us use all features of the USE statement available inside a regular model (see the section on the Use statement). In this mode.

86 Here is the corresponding data case: BEGIN NEW DATA CASE { LIMR-USE.source driving voltage rs -.vmeas OUTPUT rs := r ENDUSE source rms voltage source frequency source driving voltage source min resistance source max current USE variable_resistance AS res OUTPUT rl := r -.E-5 0.m { inserts model variable_resistance USE source_voltage AS source DATA vrms := 100 -.[ A ] INPUT v := srce .2 { Fixed load R-L 91LOAD TACS RL { Variable load resistance BLANK card ending branches ----------------------------------------------------CT1 CT2 MEASURING 1 BLANK card ending switches ----------------------------------------------------60SRCE { Source driving voltage BLANK card ending sources -----------------------------------------------------SRCE CT1 USERS GUIDE TO MODELS IN ATP .load resistance $INCLUDE vs.1 0.[ohm] ENDUSE RECORD rl AS rl rs.16 C print points connec s-s minmax vary again plot 100 1 0 0 0 0 0 1 C ============================================================================== MODELS INPUT vmeas {v(CT1)} -.m { inserts model source_voltage $INCLUDE limr-use.[ V ] ENDUSE USE limr AS rs DATA rsmin := 1.load voltage measured at node CT1 OUTPUT srce -.r AS rs load resistance control ENDMODELS C ============================================================================== 91SRCE CT1 TACS RS { Variable limiting resistance CT2 LOAD 0.[ Hz] OUTPUT srce := vs -.limiting resistance rl -.[ V ] freq := 60 -.m { inserts model limr $INCLUDE resist.[ohm] ilim := 20 -.0 -.DAT } C deltat tmax xopt copt epsiln tolmat tstart 5.

This model can be written as a native model using the MODELS language.16 { LIMR-94. For comparison. and is then limited to be no less than the value specified by rsmin. but by a type-94 component in the circuit. where the resistance is first calculated to create a current equal to ilim. a version of this circuit is shown using a type-94 component. except that the limiting resistance model is used as a circuit component (type-94) instead of being used as a control component called from a USE statement. the interface with the circuit is a true electrical connection defined in terms of the voltages and currents of the data case.87 BLANK card ending voltage printout request ------------------------------------BLANK card ending plot --------------------------------------------------------BEGIN NEW DATA CASE BLANK The included file LIMR-USE.3. Using a model with the type-94 component In ATP. in the section below. The solution of the Norton uses the control-type approach. BEGIN NEW DATA CASE C deltat tmax xopt 5.[ohm] min resistance ilim -. as follows: MODEL limr -. placed in the MODELS section of the data case. with a one-step delay. or it can call a foreign model using other programming languages. 6.[ A ] max current INPUT v -. the type-94 nonlinear component is a user-defined multi-branch circuit component. and Norton. The operation of the component is completely described by the user in a model.M contains the description of the limiting resistance model. iterated.DAT } copt epsiln tolmat tstart USERS GUIDE TO MODELS IN ATP . without any time delay. and used not by a USE statement.E-5 0. The solution of the Thevenin and the iterated modes is simultaneous with the solution of the rest of the circuit. The following example is the same data case as shown in the previous section. The type-94 component can be used in three different modes: Thevenin.[ V ] voltage across terminals VAR r -. Each one can be used for representing multi-branch nonlinear circuit elements. with or without associated controls.[ohm] resistance OUTPUT r EXEC r := abs(v)/ilim {min: rsmin} ENDEXEC ENDMODEL The operation of that model is described in its one-line EXEC procedure.limiting resistance DATA rsmin -. In each case.

[ V ] freq := 60 -.[ V ] ENDUSE USE variable_resistance AS res OUTPUT rl := r -.2 { Fixed load R-L 91LOAD TACS RL { Variable load resistance BLANK card ending branches ----------------------------------------------------CT1 CT2 MEASURING 1 BLANK card ending switches ----------------------------------------------------60SRCE { Source driving voltage BLANK card ending sources -----------------------------------------------------SRCE CT1 BLANK card ending voltage printout request ------------------------------------BLANK card ending plot --------------------------------------------------------BEGIN NEW DATA CASE BLANK source rms voltage source frequency source driving voltage load resistance control The included file LIMR-94.[ohm] ENDUSE RECORD rl AS rl SRCE__CT1___LIMR__.source driving voltage rl -. >DATA ILIM 20.load resistance $INCLUDE vs.1 0.m { inserts model source_voltage $INCLUDE limr-94. >END CT2 LOAD 0.m { inserts model variable_resistance USE source_voltage AS source DATA vrms := 100 -.m { inserts type-94 model limr $INCLUDE resist.[ Hz] OUTPUT srce := vs -. as follows: USERS GUIDE TO MODELS IN ATP .M contains the description of the limiting resistance model.88 C print points connec s-s minmax vary again plot 100 1 0 0 0 0 0 1 C ============================================================================== MODELS OUTPUT srce -.r AS rs ENDMODELS C ============================= Electrical circuit ============================= 94SRCE CT1 LIMR ITER { Variable limiting resistance >DATA RSMIN 1.

current is a vector. if multi-branch.calculated current into terminal 1 didv -.calculated conductance 1-2 OUTPUT i. didv -.89 MODEL limr -.number of matrix elements INPUT v -. Thevenin resistance is a matrix. if multi-branch. if multibranch.3.number of node pairs n2 {dflt: n*n} -.[ohm] resistance EXEC r := abs(v)/ilim {min: rsmin} IF r>rsmin -. slower than Norton. uses a vector of voltages.Local declarations --------------------------------------------------------DATA rsmin -.if the current is at the limit THEN didv := 0 ELSE didv := 1/r ENDIF i := v/r ENDEXEC ENDMODEL 6. Thevenin source is a vector.steady-state current into terminal 1 VAR i -. USERS GUIDE TO MODELS IN ATP .1. value of branch current from the component.Fixed declarations for a type-94 iterated model ---------------------------DATA n -.steady-state voltage across terminals 1-2 i0 -.[ A ] max current VAR r -. output implementation uses the compensation interface of ATP usage solution assurance speed restricted to one nonlinear component per subnetwork numerical solution is assured (no iteration between ATP and the type-94 component) faster than iterated. because no iteration is needed. because a Thevenin equivalent must be calculated Iterated type-94 input most-recent branch voltage value calculated by ATP. iterated.[ohm] min resistance ilim -. Thevenin.limiting resistance -. and Norton What follows is a comparison between the three different modes of the type-94 circuit component: Thevenin type-94 input Thevenin voltage source behind Thevenin equivalent resistance or admittance of the network seen from the component.guessed voltage across terminals 1-2 v0 -.

if multi-branch.but this could be restricted by the model's logic) possibly slower overall execution than Thevenin if many iterations are required at each time step due either to the interaction between many iterated nonlinear components. if multinode.90 output branch current and branch di/dv calculated by the model. current source is a vector. implementation uses the iteration mechanism of ATP usage solution assurance no restriction on how many are used the ATP iterated solution is not guaranteed to converge (especially if any of the iterated components are allowed to have oscillating step discontinuities in their operating point during an iteration . [δi/δv] is a matrix. values of current source and admittance are predicted for next time step . vector if multi-node. except that it is extended to a matrix form. right node is not used. or to discontinuities in any of the nonlinear components. Norton equivalent of the component. may be possible to use larger step size to compensate. . in the form of a current source in parallel with the equivalent admittance of the component.is not treated as a nonlinear element by ATP USERS GUIDE TO MODELS IN ATP .is similar to presently using a combination of a type-60 controlled current source in parallel with a type-51 controlled resistance.the solution of this component is not simultaneous with that of the circuit (a delay of one time step is introduced between input and output) implementation . speed Norton type-94 non-transmission input output left node voltage at time t. as seen from the electrical circuit. current is a vector. admittance is a matrix.

values of current source and admittance are predicted for next time step output implementation same as for the non-transmission type. current source is a vector. admittance is a matrix.where the component is not a current-controlled or voltage-controlled voltage source or current source that would need to be solved simultaneously with the circuit solution assurance the ATP solution is always assured (the equivalent circuit of the component is linear). slower execution when admittance varies often during the simulation. like the state of an arc) . the component represents a transmission element (cable or line). because the component is represented directly in the nodal admittance matrix of the circuit (it's not treated as an exception to the circuit). in the form of a current source in parallel with the equivalent admittance of the component. requiring a retriangularization of the full admittance matrix of the ATP circuit at each change speed Norton type-94 with transmission input left node voltage and right node voltage at time t. vectors if multi-node.91 usage . allows to separate each side into a different subnetwork. just like a regular transmission line component usage used where the component operates as a transmission device. two Norton equivalents of the component. numerical instability can be expected when the represented element is not a passive circuit element.where the operating point of the component can be easily predicted with sufficient accuracy from one time step to the next (for example when the operating point of the component changes more slowly than the operating point of the rest of the circuit) . if multi-node. the two sides are decoupled by the component.where the exact timing of the operating point of the component is not critical to the operation of the rest of the circuit (for example when representing something with an element of randomness. faster execution than both Thevenin and iterated. USERS GUIDE TO MODELS IN ATP . as seen from the electrical circuit on each side.

In the case of the Norton type.initialize variable inductance value histdef(v) := v0 histdef(i) := i0 ENDINIT EXEC COMBINE AS group1 CLAPLACE(i/v) := (1|s0)/(L|s1) v := sum(vth| -rth|i) ENDCOMBINE ENDEXEC -. Notice where the steady-state measured values of v0 and i0 are used: Thevenin: INIT L := L1 -.n] carry the values of voltages and currents measured at the end of the steady-state solution.n] carry the values of voltages and currents measured at the end of the steady-state solution. to properly operate the model... the pre-defined inputs v0[1.3. and next at a type-94 Norton.n] and i0[1. values that we can use to initialize the operating point of the corresponding model when it is first called for execution. Here again. built first as a type-94 Thevenin.i/v=1/sL -. but also the values of the Norton equivalent that will be used in the circuit at the next time step... In the case of the Thevenin and the iterated types. but before the circuit solution at the first time step. the model is called for the first time at time t=0 immediately after the steady-state solution. which can be used to initialize the model.92 6.sum(a0| +a1|x1) USERS GUIDE TO MODELS IN ATP . which in this case will be the first time step. Initializing the type-94 component The type-94 component is not included in the steady-state initialization of the ATP circuit at t=0. and can be used in a special section of the EXEC procedure. a temporary equivalent linear circuit can be used for representing the component in the steady-state circuit solution. The pre-defined inputs v0[1. This gives us a chance to initialize not only the model.2. compare below the INIT and EXEC procedures of a simple model representing a constant inductance.n] and i0[1. To illustrate this last point. This provides us with representative values of voltages and currents at the component. executed only at time t=0. the model is not called until the circuit solution is already under way at the first time step of the simulation. As for other nonlinear elements used in a circuit.

reset flag. For instance: . They can be written in any programming language that can be linked with ATP on the used platform.4.applying trapezoidal rule. The foreign programs are connected to ATP using the simple foreign interface of MODELS. . This provides a way to represent the operation of a circuit component in ATP using a set of subroutines or procedures written as a separate program.conductance values have been changed -. and initial conditions.trapezoidal rule conversion from Laplace -. This is illustrated in the example below. the value of the frequency is passed to MODELS. calculate from v(t) -. f1) returns the predicted value of y at frequency f1 USERS GUIDE TO MODELS IN ATP . This operation can be described locally in the model itself. Foreign models with a type-94 The type-94 component automatically calls the specified model at each time step of the simulation.3.prevval(y) returns the value of y at the previous frequency step .predval(y. Using MODELS with ATP's FREQUENCY SCAN It is possible to include a MODELS section to be used with the FREQUENCY SCAN operation of ATP. no more change in g -. for next step 6.93 Norton: INIT st:= 2/timestep L := L1 g := 1/(st*L) ENDINIT EXEC IF t=0 flag i is ELSE flag i is ENDIF ENDEXEC -.history term from trapezoidal rule.deriv(y) calculates the derivative of y with respect to frequency .conductance converted from Laplace 1/sL THEN := 1 := i0 := -i0 -g*v0 := 0 := g*v -is := -i -g*v -. in terms of data.initialize variable inductance value -. until one considers that this trick provides built-in access to derivatives and integrals of values with respect to frequency. instead of with respect to time. 6.t=0 current through L -. output. (See the section on Foreign submodels). input. This may seem odd at first look. At each frequency step.integral(y) calculates the integral of y with respect to frequency .timestep holds the step in frequency between the previous frequency (now prevtime) and the present frequency (now t). or can be programmed in a foreign model called by that model.3. That model describes how the component operates during the simulation. carried using the variable t.history term for next step -.

a0*y + a1*(dy/df) + a2*(d2y/df2) + . v_Re_2.5 -1. 2.diffeq(a0|D0 +a1|D1 +.0.94 .) | y := x calculates the value of y from a differential equation expressed in terms of the frequency. state_1 ) ENDEXEC ENDMODEL -) ) ) <<=== <<==== USE m1 as m1 INPUT v_Re_1 := v_Re_swit v_Im_1 := v_Im_swit v_Re_2 := v_Re_load v_Im_2 := v_Im_load i_Re_1 := i_Re_swit i_Im_1 := i_Im_swit state_1 := state_swit ENDUSE ENDMODELS C Begin branches =============================================================== SWIT LOAD 10. 1=closed) MODEL m1 ----------------------------------------------------------------------VAR pass INPUT v_Re_1 {dflt: 0} v_Im_1 {dflt: 0} v_Re_2 {dflt: 0} v_Im_2 {dflt: 0} i_Re_1 {dflt: 0} i_Im_1 {dflt: 0} state_1 {dflt: 0} INIT pass:=0 ENDINIT -.0. '. v_Im_1 write(' Re{v2}. '. 1. Im{i1} = '. v_Re_1. i. BLANK card ending source cards USERS GUIDE TO MODELS IN ATP .0 1 1 1 1 { Note request for phasor branch flows C ============================================================================== MODELS INPUT v_Re_swit v_Im_swit v_Re_load v_Im_load i_Re_swit i_Im_swit state_swit {v(swit)} {imssv(swit)} {v(load)} {imssv(load)} {i(swit)} {imssi(swit)} {switch(swit)} -------real part of voltage imag part of voltage real part of voltage imag part of voltage real part of current imag part of current state of switch SWIT at node SWIT at node SWIT at node LOAD at node LOAD at switch SWIT at switch SWIT (0=open. t) write(' Re{v1}. 0. i_Im_1 write(' state_1 = '. v_Im_2 write(' Re{i1}. BLANK card ending all branches GEN SWIT -1.to verify that its value is kept between passes -. BLANK card ending all switch cards 14GEN 1. '.. '. pass) write(' freq= '. = x . Im{v1} = '.3055 5. '.e.0 0.to verify that all types of inputs are -accessed correctly -(machine quantities are not tested here) EXEC pass:=pass+1 write('************** In models. Im{v2} = '. 15. LOAD 1000. 1..laplace(y/x) doesn't make any sense in this context BEGIN NEW DATA CASE C BENCHMARK DC-52 with addition of a model and its use FREQUENCY SCAN. i_Re_1.. -1SWIT OPEN ... '.82 . pass= '.0 0.012 138.

95
GEN LOAD BLANK card ends output requests (just node voltages, for FREQUENCY SCAN) 197 .2 0.0 1.6 -20. 60.LOAD angle BLANK card ending plot cards BEGIN NEW DATA CASE BLANK

6.5. Steady-state initialization
The ac steady-state initialization of the electrical circuit in ATP is performed on a linearized circuit driven by one or more sinusoidal sources. All nonlinear components are ignored by the electrical side of ATP for that initial steady-state solution (which is done using phasor algebra, superposing sources at different frequencies, if any). Two aspects of the initialization process must be considered: 1) what is considered "nonlinear" 2) what is considered to be in "steady-state" In ATP parlance, anything that cannot be represented by a linear expression in the frequency domain is considered "nonlinear" for initialization. Components and control systems represented using TACS and MODELS certainly qualify as nonlinear in this regard, even if in some rare cases a linear or linearized analytical representation of the component could be derived from the component's description. A common technique used by ATP users is to create a linear equivalent of a nonlinear component only for the purpose of initialization, and then disconnect that equivalent circuit from the rest of the circuit by means of switches opening before the first time step of the simulation. Of course, determining the correct operating point of the nonlinear element around which the equivalent circuit is to be linearized is the difficult part. Often the user will choose to start a simulation from a more simple state for which the operating point of the various nonlinear elements are more completely known, and then let the first part of the simulation bring the circuit to a more elaborate state from which, in a second part, the transient behavior of interest can be initiated and observed. The AC steady-state solution of ATP is driven by sinusoidal sources at one or more frequencies (representing DC sources as sinusoidal sources with a very small frequency). The user is required to provide (and therefore to know before doing the simulation) the amplitude and frequency of these signal or power sources. The approaches commonly used are similar to the approaches shown above. Equivalent sources can be used for the initialization and then disconnected and replaced by the real sources as soon as the simulation begins. And the initialization can be done using simplified frequency representation of the sources, letting the simulation bring the circuit to a more complex frequency contents in the first part of the simulation, from which the transient behavior can then be initiated. To initialize a component described outside the electrical circuit, we likely would use a combination of both aspects described above, in the form of an equivalent
USERS GUIDE TO MODELS IN ATP

96 source behind an equivalent impedance, with values obtained from a known operating point, and then let the simulation build the operation of the circuit to a more complete frequency contents, from which we can then initiate the transient behavior we want to study. The better the initial approximation, of course, the shorter becomes the first stabilizing part of the simulation, but also the more specific it becomes. The decisions we have to make in this iterative process in order to reach a satisfactory starting point will, if anything, make us more aware of the sensitivity of the components we are modeling with respect to the conditions of their operation. One more practical point. Models used in the MODELS section with a USE statement are updated at each time step of the simulation after the solution of the electrical circuit by ATP at that time step. This is also true at time zero of the initialization. The steady-state solution of the circuit is done first, then the USE statements are executed for the first time at t=0. Using inputs such as the real and imaginary part of currents and voltages of the circuit gives us the possibility to take into account the steady-state solution of the circuit when initializing the operating point of the models.

6.6. List sizes in ATP for MODELS
Two dimensions in the file LISTSIZE.DAT control the size of the storage area reserved for MODELS in ATP. list 15: character storage -- needs about 2000 + size of MODELS section list 28: numerical storage -- integer and real storage of simulation The user has control on the size of these lists in the file LISTSIZE.DAT, up to their maximum dimension. In the regular version of ATP, these maxima are 64800 and 126000 respectively. Users requiring storage larger than this must obtain a version of ATP dimensioned with larger values. Getting error messages that do not make any sense when using MODELS may indicate a storage problem. Most cases of memory overflow are reported with the correct error message, but some cases will create a problem in another area before being detected correctly.

USERS GUIDE TO MODELS IN ATP

97

7. LIBRARIES OF MODELS AND FUNCTIONS
Most modeling projects involve creating and using a set of basic components, that can also possibly be re-used in other projects. Using this approach, assembling a simulation can be reduced to a task of providing the framework and the logical glue for the use of components gathered out of one's developed toolkit. What follows is meant to be used as a starting point for building a library of various models, functions, and components needed in the simulation projects that one can consider doing.

7.1. Signal sources
Simple signal sources can often be described by a single logical and/or numerical equation. Using a statement function to express this equation is then the easiest way to create such sources. For example, a cosine source with variable amplitude, frequency, and phase angle can be represented as:
FUNCTION cos_source(a,f,p):= a*cos(2*pi*f*t +rad(p))

or, in fact, doesn't even need a function, because the expression is simple enough that it can be inserted explicitly in full wherever it needs to be used. However, a less obvious formulation, like that of the triangular waveform below, is better described only once in a function definition, and then used as a function call when it's needed. The use of a function is possible when the representation of the source is stateless, that is, doesn't carry history between the times when it is called. When history is carried, then we need to use a model for describing the operation of the signal source. Included below are a few commonly-used signal sources. For those examples, if turn-on and turn-off times need to be added, this can be easily done on the outside of the function definition. For example, to have a source operating between t>=t_on and t<t_off, one would use ramp_train(), for example, as:
signal := (t >= ... AND t < ...)*ramp_train(100, 1e-4, 0)

where the value of the logical expression is taken as numerical "1" when the expression is true, and zero otherwise, multiplied by the rest of the expression.

7.1.1. Examples of some common sources The first function is a simple one-shot pulse of specified amplitude, width, and starting time. This is an example where using a function does not present much of an advantage over using the expression directly.
USERS GUIDE TO MODELS IN ATP

than to have to figure out how to use the modulo operator each time the signal needs to be generated. with the beginning of the reference period (the phase. width. period. starting at a specified starting time: FUNCTION single_ramp(ampl. tstart) := ampl*(t>=tstart AND t<tstart+width) comment --------------------------------------------| ampl : [ ] on-value of pulse (off-value is 0) | | width : [s] width of pulse | | tstart : [s] pulse start time | | pulse starts at t=tstart and lasts "width" seconds | -----------------------------------------. tshift) := ampl/width*((t-tshift+width) MOD width) comment --------------------------------------------------| ampl : [ ] amplitude of ramp | | width : [s] widthor period of each ramp | | tshift : [s] period shift time | | the beginning of the period is shifted by "tshift" sec | | each ramp is on for "width" seconds | | ramps are repeated every "width" seconds | -----------------------------------------------. width. It is easier to call the function with its four arguments. tstart) := ampl/width*(t-tstart)*(t>=tstart AND t<tstart+width) comment -------------------------------------------| ampl : [ ] amplitude of ramp | | width : [s] width of ramp | | tstart : [s] ramp start time | | ramp starts at t=tstart and lasts "width" seconds | ----------------------------------------. and the period is equal to the width: FUNCTION ramp_train(ampl. In this example.98 FUNCTION single_pulse(ampl.endcomment USERS GUIDE TO MODELS IN ATP .endcomment Refer to the sample model "test_sources" below to see how this and the following functions can be used. in seconds) shifted to a specified time: FUNCTION pulse_train(ampl. The next example is simplified when using a function call. with the beginning of the reference period (the phase. The function generates a sequence of pulses of a specified amplitude. width. in seconds) shifted to a specified time.endcomment The next function shows a simple ramp of specified maximum amplitude and width. there is no dead zone. and period.endcomment The next function generates a train of ramps of specified amplitude and width. width. tshift) := ampl*(((t-tshift+period) MOD period) < width) comment --------------------------------------------------| ampl : [ ] on-value of each pulse (off-value is 0) | | width : [s] width of each pulse | | period : [s] period of each pulse (on_time + off_time) | | tshift : [s] period shift time | | the beginning of the period is shifted by "tshift" sec | | each pulse is on for "width" seconds | | pulses are repeated every "period" seconds | -----------------------------------------------. width.

0. The $INCLUDE directive refers to a file named "sources. width. tmodT) := ampl*4/per*((tmodT/per<0.1. Sample data case The following model illustrates how the above signal source functions can be used in a model.4 ) -. Even if the file (a library) contains more functions than we need to use in a data case. it is not costly to include the whole file.6) mod 0.4. width. tshift ) pulsetrain := pulse_train( 100.25*per) +(tmodT/per>=0. tri EXEC -.5)*(-tmodT+0.lib". That value is specified as the expression: (t . tstart ) pulse := single_pulse( 100. per.4 ) -. ramp.using ramp_train( ampl. 0. The value of the third argument is calculated once when calling the function. 0. BEGIN NEW DATA CASE { SOURCES. 0.99 The next function generates a triangular wave of specified amplitude and period.0 C print points connec s-s minmax vary again plot 1 1 1 C ============================================================================== MODELS STAND ALONE ------------------------------------------------------------.4 ) -.using pulse_train( ampl.DAT } C deltat tmax xopt copt epsiln tolmat tstart 0.4. ramptrain.2. tshift ) ramptrain := ramp_train( 100. 0. width. tstart ) ramp := single_ramp( 100. the program uses only the functions needed during the simulation. period.using single_pulse( ampl. FUNCTION triang(ampl. in phase with a cosine shifted to a specified time. 0.75*per)) comment -----------------------------------------------------------| ampl : [ ] amplitude of triangular waveform | | per : [s] period of waveform | | tmodT : [s] pre-calculated value of (t-tshift+period) MOD period | | where tshift : [s] period shift time | | the beginning of the period is shifted by "tshift" sec | | value at start of period is positive maximum. like cosine | --------------------------------------------------------.using single_ramp( ampl. Then.tshift + period) MOD period using values for a specified period and shift time.6. pulsetrain.4.4 ) -.lib $LISTON VAR pulse.using triang( ampl.6 ) ENDEXEC USERS GUIDE TO MODELS IN ATP .Model definitions: MODEL test_sources $LISTOFF $INCLUDE sources. 0. and is used many times inside the function. width.01 2. period.4+0.6. (t-0. tmodT ) tri := triang( 100.endcomment 7. It is useful to use a file to store the definition of the functions we need most often. 0. The only cost is reading and storing the contents of the file once at the beginning of the simulation. 0.5)*(tmodT-0. 0.6.

as a pair of rectangular coordinates (real part.br. These functions would normally be kept in a separate file. ai*br-ar*bi]*recip(br*br-bi*bi) USERS GUIDE TO MODELS IN ATP .ai]: ar=real part of A.2] | | without having to call any function | -----------------------------------------------------------..ai.ai.2. subtraction. the representation can be held in a 2-element vector. imaginary part) .ai.2]-b[1..ai.tri AS tri ENDMODELS C ============================================================================== BLANK card ending plot requests BEGIN NEW DATA CASE BLANK 7. angle) In either case. Because functions can return an array of values.2]+b[1. but is costly for multiplication and especially for division: comment --------------------------------------------------------------| operations on complex numbers using rectangular coordinates | | where a[1. and included together in a model when needed. this representation works well for addition and subtraction. ai+bi] [ar-br.bi) cr_mul(ar.ramptrain AS rampt test..2]=[br. ar*bi+ai*br] [ar*br+ai*bi.Model uses: USE test_sources AS test ENDUSE ----------------------------------------------------.pulsetrain AS pulset test.as a pair of polar coordinates (magnitude.2] and a[1.1.. Library of complex-value functions A complex number can be represented: .ramp AS ramp test.endcomment FUNCTION FUNCTION FUNCTION FUNCTION cr_add(ar.bi) cr_sub(ar. 7.2]=[ar. Examples of complex-value functions The first set of functions shows the basic operations on complex numbers expressed in rectangular coordinates.pulse AS pulse test..br. ai=imaginary part of A | | and b[1. multiplication. As can be seen. ai-bi] [ar*br-ai*bi.bi) := := := := [ar+br.2.bi]: br=real part of B. The following is a library of ready-to-use functions covering the basic operations we can apply to complex numbers. bi=imaginary part of B | | | | complex rectangular addition.Printed/plotted variables: RECORD test.100 ENDMODEL -------------------------------------------------------------------.br. we can use functions to define the 2-element array arithmetic of complex numbers. division | | note: complex rectangular addition and subtraction can also be | | done directly using a[1.bi) cr_div(ar.br..

division. with d[1] = real part.bm.aa]: am=magnitude of A.2].bi) := [norm(br. f[1. d[1...2] d[1.ba]: bm=magnitude of B. atan2(bi.aa) := := := := [am*bm.bm. aa+ba] [am/bm.2]) or := c[1. It also shows how easily the power and root operations can be expressed: comment --------------------------------------------------------------| operations on complex numbers using polar coordinates | | where a[1. aa-ba] [am**n. For example. f.2].br)] These functions are ready to be used in a model..2] f[1. and the array variables c.bi). f[2] = angle in radians we can represent the following operations: c+r c+d c-d r*c c*d c/r c/d e*f y[1.ba) cp_powern(n..endcomment FUNCTION FUNCTION FUNCTION FUNCTION cp_mul(am.aa) := [am*cos(aa).2] with c[1] = real part.2] y[1... n*aa] [am**(1/n).2] := cr_add(c[1...am.2] := c[1.2]) USERS GUIDE TO MODELS IN ATP .2]) y[1.2]. aa/n] The following pair of functions provide conversions between rectangular and polar coordinates: comment -----------------------------------------------------------------| conversion between rectangular and polar coordinates of complex numbers | | where a[1. bi=imaginary part of B | --------------------------------------------------------------.2] .. e..2] y[1. d[1.2]=[bm.2]) or := c[1..2] := cp_mul(e[1.2] := r * c[1.2] + [r.2] / r y[1. powern.aa) cp_rootn(n.2]=[am.101 The next group of functions shows multiplication and division of complex numbers expressed in polar coordinates. 0] y[1. rootn | -----------------------------------------------------------.2]=[br. ba=angle of B in radians | | | | complex polar multiplication.d[1... given the real variable r.2] := cr_div(c[1..2]=[am. d..2] := cr_mul(c[1.bi]: br=real part of B.2] y[1.. am*sin(aa)] FUNCTION crp_conv(br.2]) y[1. d[1..aa...ba) cp_div(am....endcomment FUNCTION cpr_conv(am.2].2] := c[1.....aa]: am=magnitude of A. e[2] = angle in radians with f[1] = magnitude.....am.2] := cr_sub(c[1. aa=angle of A in radians | | and b[1. aa=angle of A in radians | | and b[1.. d[1.2]..aa..2] + d[1. where: c[1.2] e[1. c[2] = imaginary part d[2] = imaginary part with e[1] = magnitude.

. e[1.= [1.= [10.2..2]) y[1. f[1.2]:=cpr_conv(e[1.2]:=cpr_conv([100....lib".2] := cp_powern(n.Printed/plotted variables: RECORD test..2]) y[1. 0.complex number in polar form omega VAR x[1.2] := cp_div(e[1.2]:=crp_conv(2*c[1... angle=60 degrees omega:=2*pi*50 ENDUSE ----------------------------------------------------..complex variables EXEC x[1. A file named "complex.sqrt(3)] -.2]:=[3. e[1..DAT } C deltat tmax xopt copt epsiln tolmat tstart 0.2].. Sample data case The following example illustrates how some of the above complex functions can be applied in a model.x[1] AS xmag test..2]) 7.2]) y[1. y[1.2.lib $LISTON DATA c[1. z[1.2]. It contains the function declarations.102 e/f e ** n e root n polar to rect rect to polar y[1.magnitude=2.2] := cp_rootn(n.complex number in rectangular form e[1. imaginary part=4 e[1.2])-[0.Model uses: USE test_complex AS test DATA c[1.z[1]=100*cos(omega*t) ENDEXEC ENDMODEL -------------------------------------------------------------------. 0] z[1.y[1] AS yreal test.2] -.z[1] AS cosine ENDMODELS C ============================================================================== BLANK card ending plot requests BEGIN NEW DATA CASE BLANK USERS GUIDE TO MODELS IN ATP . 4] -.Model definitions: MODEL test_complex $LISTOFF $INCLUDE complex.927 rad] y[1..2] := cpr_conv(e[1.2]) -. omega*t]) -.2]...2] -. as shown in the above section: BEGIN NEW DATA CASE { COMPLEX.2] := crp_conv(c[1.y[2] AS yimag test.2]) y[1.2] -.....real part=3.2]:=[2.001 0.. is inserted in the model..x[2] AS xang test... containing these functions.02 C print points connec s-s minmax vary again plot 1 1 1 C ============================================================================== MODELS STAND ALONE ------------------------------------------------------------. rad(60)] -.

1.interpolate to find the zero-crossing time f := 0. Together. Better frequency meters can be modeled. Others need their operation expressed using a more elaborate algorithm.just skipping the first step ELSIF txing = -1 AND xprev*x <=0 THEN txing:=t ELSIF xprev*x <=0 AND t-txing >= dtmin AND t-txing <= dtmax THEN a := backtime(x.monitored signal [any units] VAR f -.time of last detected zero-crossing xprev -.initial frequency [Hz] (used until the 2nd zero-crossing) band -. The device is used by specifying the initial frequency of the signal.5/(a-txing) -.5/(1-band/100)/f0 -.5/(1+band/100)/f0 -.smallest value of half-period ENDINIT EXEC IF txing = -2 THEN txing := -1 -.3.auxiliary variable OUTPUT f INIT f := f0 -. 0) -.maximum sampling half-period a -.max acceptable change on either side of f0 [%] INPUT x -.initial value of measured frequency txing := -2 -.adjust the measured frequency txing := a -. Some can be expressed using nothing more than an expression.3. This model simply reproduces the operation of the frequency meter installed in TACS. expressed as a percentage of the initial frequency.minimum sampling half-period dtmax -.remember the zero-crossing time ENDIF xprev := x -.measured frequency [Hz] txing -.previous value of signal dtmin -. and the size of the acceptable band of frequencies.initially holding a flag value xprev := x -. 7.largest value of half-period dtmin := 0. they illustrate a good cross-section of the features of the MODELS language. Rudimentary noise filtering is accomplished by simply rejecting zero-crossings that fall outside a specified frequency range. Library of TACS-like devices The control system devices available in TACS can also be described using MODELS.will be the previous value at next time step dtmax := 0. MODEL fmeter DATA f0 -.will be the previous value at next time step ENDEXEC ENDMODEL Using an instance of this model is done with a USE statement: USERS GUIDE TO MODELS IN ATP .103 7. TACS type-50 frequency meter The frequency-meter in TACS operates by measuring the time elapsed between successive zero-crossings of its input signal.

3. The task is facilitated in MODELS by being able to specify a default that applies to all uses of the delay function in a model.104 USE fmeter AS DATA f0 band INPUT x OUTPUT ____ ENDUSE local_name := ___________ := ___________ := __________ := f in Hertz in percent 7. so we need to specify the required number of cells directly. we have to specify the maximum delay time to be used by the device. as it cannot be calculated.3. by dividing the maximum delay time by the size of the time step. the function returns the value input * 0 . TACS type-52 level-triggered switch The level-triggered switch in TACS operates similarly to the relay-operated switch. driving. TACS type-51 relay-operated switch The relay-operated switch in TACS passes the value of the input signal when the absolute value of the driving signal is at or above a specified threshold value. the output value is zero. This can be represented in MODELS with a simple function: FUNCTION relay_switch ( input. threshold ) := input * ( abs(driving) >= threshold ) When the condition is true. The same approach can be used as above. 7.4. But in MODELS. driving. 7. the function returns the value input * 0 . without the absolute value.2. The difference is imposed by the fact that in TACS. the time step being fixed. Functions like this one are so simple that it is as easy to use the expression directly in a model as it is to create and call a function. When the condition is false.3. the function returns the value input * 1 . using a simple function: FUNCTION relay_switch ( input. TACS type-53 transport delay The operation of the transport delay of TACS can be represented directly by using the delay() function of MODELS. Otherwise. the time step can be variable. USERS GUIDE TO MODELS IN ATP . threshold ) := input * ( driving >= threshold ) When the condition is true. it is possible to calculated the number of memory cells required by the device. The only difference is that in TACS. while in MODELS. When the condition is false. we specify the number of value cells to be used by the device. the function returns the value input * 1 .3.

don -.time when x became <=0 OUTPUT out INIT out := 0 IF ton_ini = -9999 THEN state:=0 ELSE ton := ton_ini IF toff_ini = -9999 THEN IF t-ton >= delay_val THEN out:=1 state:=2 ELSE state:=1 ENDIF ELSE toff := toff_ini IF t-toff >= delay_val THEN state:=0 ELSIF t-ton >= delay_val THEN out:=1 state:=5 ELSE state:=3 ENDIF ENDIF ENDIF ENDINIT EXEC IF state = 0 THEN IF x > 0 THEN ton:=t state:=1 ENDIF ELSIF state = 1 THEN IF t-ton >= delay_val THEN out:=1 state:=2 ENDIF IF x<=0 THEN toff:=t state:=3 ENDIF IF state=3 AND out=1 THEN state:=5 ENDIF ELSIF state = 2 THEN IF x<=0 THEN toff:=t state:=5 ENDIF ELSIF state = 3 THEN IF t-ton >= delay_val THEN out:=1 state:=5 IF x > 0 THEN ton:=t state:=6 ENDIF ENDIF ELSIF state = 5 THEN USERS GUIDE TO MODELS IN ATP .variable delay value VAR out -.input signal delay_val -.initial value of pulse beginning time toff_ini {dflt:-9999} -.4= got toff. xon -.initial value of pulse ending time INPUT x -.6= waiting for doff.time when x became >0 toff -. The device simply detects the instants when the input signal becomes positive and ceases to be positive. as it does not require the large amount of storage that was needed to track the value of a signal at each time step in the case of the transport delay. It gets more complex when combinations of initial conditions are considered. MODEL pulse_delay DATA ton_ini {dflt:-9999} -.5= waiting for doff -. got ton ton -.3= got toff -.5. and determines if the delay falls within an "on" period or an "off" period.3.delayed pulse state -.105 7. TACS type-54 pulse delay The pulse delay is more interesting. The logical operation of the device is best represented by a state machine.1= got ton -. A much more simple model can be constructed for cases where the delay value is known to remain constant during the simulation.2= got ton. shown here with 7 states. Without considering initial conditions. as shown in the model below. the algorithm is quite simple.0= waiting for ton -.

2] := [x. replacing the above INIT and EXEC procedures of the model by a call to the foreign model.delayed pulse MODEL compiled_pulse_delay FOREIGN C_pulse_delay {ixdata:2..6. ixout:1. delay_val] -OUTPUT out := xout[1] -ENDUSE ENDEXEC ENDMODEL pulse beginning time pulse ending time this is array notation just loading the values and retrieving the output 7. The output value is the value of the closest point below the level of the input. Then. MODEL pulse_delay DATA ton_ini {dflt:-9999} -. One approach would be to write it in C or in Fortran. ( value_2. ixin:2.2] := [ton_ini. value_1 )..initial value of INPUT x -.106 IF t-toff >= delay_val THEN out:=0 state:=0 ENDIF IF x>0 THEN ton:=t IF state=0 THEN state:=1 ELSE state:=6 ENDIF ENDIF ELSIF state = 6 THEN IF t-toff >= delay_val THEN out:=0 state:=1 ENDIF IF x<=0 THEN toff:=t IF state=1 THEN state:=3 ENDIF ENDIF ENDIF ENDEXEC ENDMODEL The model can be used as follows: USE pulse_delay AS DATA ton_ini toff_ini INPUT x delay_val OUTPUT _________ ENDUSE somename := __________ in seconds (optional) := __________ in seconds (optional) := __________ := __________ in seconds := out Long models like this one would execute faster by being pre-compiled. USERS GUIDE TO MODELS IN ATP .input signal delay_val -. value_3 ). ixvar:4} EXEC USE compiled_pulse_delay AS pdelay DATA xdata[1. value_2 ).3.initial value of toff_ini {dflt:-9999} -. etc. all we need to put in this library is the following. and link it with ATP.variable delay value VAR out -. ( value_3. toff_ini] -INPUT xin[1. TACS type-55 digitizer The digitizer in TACS is defined as a list of points on a straight line of slope equal to a "gain". This can be represented in MODELS using a straight-line pointlist function: FUNCTION digitizer POINTLIST ( value_1.

etc. y2 ). and is multiplied by the value of the input signal.9. This can be represented directly in MODELS using a pointlist function: FUNCTION point_by_point POINTLIST ( x1. The function is used with an interpolation degree of zero.8. The x coordinate shows the values of switching times. TACS type-58 controlled integrator The TACS type-58 integrator is a resettable Laplace function of the form gain d0 + d1 ⋅ s A control signal determines when the output is reset to a specified reset value. ( x2. and using the function with the default interpolation degree of one: y := point_by_point( signal) 7. 0 ).3.107 This function is then used with the interpolation degree set at zero. y3 ). 1 ). ( t2. 0 ). ( x3. 0) 7. resulting in level steps between the defined points on the line: y := digitizer( signal. y := signal * time_seq_switch(t) 7. TACS type-56 point-by-point nonlinearity The type-56 device is a pointlist function with linear interpolation. ( t3. FUNCTION time_seq_switch POINTLIST ( t1.3. and the y coordinate is either one or zero. y1 ).3. Both operations are included in the simple model below. The model also accepts an initial value: USERS GUIDE TO MODELS IN ATP .7. etc. TACS type-57 time-sequenced switch The time-sequenced switch can also be represented using a pointlist function.

function output OUTPUT out INIT out := out_ini ENDINIT EXEC IF control<=0 THEN out:=reset_value ELSIF t>=timestep THEN LAPLACE(out/x):=(gain|s0)/(d0|s0 + d1|s1) ENDIF ENDEXEC ENDMODEL The model can be used as follows: USE type_58 AS somename DATA out_ini := gain := d0 := d1 := INPUT x := control := reset_value := OUTPUT _____________ := ENDUSE ________ ________ ________ ________ ________ ________ ________ out (optional) (optional) (optional) (optional (optional) (optional) 7.input signal control {dflt:1} -. TACS type-59 simple derivative The type-59 derivative of TACS is a mid-point derivative of the form gain ⋅ x(t ) − x(t − timestep) timestep It can be translated directly into a MODELS expression: y := gain * ( x . that is. If we need to reproduce the operation of the TACS device.denominator coefficient of s1 INPUT x -. then we use the mid-point derivative expression.denominator coefficient of s0 d1 {dflt:1} -. as in TACS.initial value of out gain {dflt:1} -.prevval(x) ) / timestep One may wonder why the above expression did not use the built-in function deriv() of MODELS as follows: y := gain * deriv(x) It is because the deriv() function in MODELS calculates the end-point derivative.10.108 MODEL type_58 DATA out_ini {dflt:0} -. else reset reset_value {dflt:0} -.3.used on reset VAR out -. USERS GUIDE TO MODELS IN ATP .apply function when positive. not at time=(2t-timestep)/2.function gain d0 {dflt:0} -. the derivative of x at time=t.

5 4. The sample/hold device takes samples of the input signal on each rising front of the control signal.5 1.11. TACS type-60 input-IF component The type-60 input-IF device was an attempt to provide the equivalent of an IF statement in the confines of a signal-flow block-diagram representation. TACS type-61 signal selector The type-61 signal selector is a switch that gives as output the value of one input signal from among up to 8 inputs.5 2.5 5. The operation is represented as a simple state machine: USERS GUIDE TO MODELS IN ATP .5 THEN THEN THEN THEN THEN THEN THEN out:=i0 out:=i1 out:=i2 out:=i3 out:=i4 out:=i5 out:=i6 out:=i7 7.12. TACS type-62 sample/hold and track/hold The sample and track device of TACS can perform the functions of a sample/hold device and of a track/hold device.13. The two modes of operation are separated here in two different models.5 6.109 7. depending on the value of a selector signal. It is possible to specify an initial output value.5 3.3.3. The device is a switch that passes one of three inputs depending on the value of a control variable with respect to a threshold. It can be expressed in a model using an IF statement: IF x1 < x2 THEN out:=in1 ELSIF x1 = x2 THEN out:=in2 ELSE out:=in3 ENDIF 7. It can be represented in a model using an IF statement: IF ELSIF ELSIF ELSIF ELSIF ELSIF ELSIF ELSE ENDIF selector selector selector selector selector selector selector < < < < < < < 0.3. The output maintains the sampled value between sampling.

sampled signal sample_control -.110 MODEL sample_hold DATA out_ini {dflt:0} -. MODEL track_hold DATA out_ini {dflt:0} -. and holds its most recent value when the control signal is not positive. the value last-held by the output variable. any variable of a model maintains its value until it is changed to another value.initial value of out INPUT x -.tracked signal track_control -. The track/hold model can be used as follows: USERS GUIDE TO MODELS IN ATP .triggers sampling on rising positive front VAR out state -.initial value of out INPUT x -. The only reason why this device needs to be represented as a model rather than as a function is that we need to carry a value from one time step to the next. so writing out := out is redundant.tracks when positive VAR out OUTPUT out INIT out := out_ini ENDINIT EXEC IF track_control > 0 THEN out:=x ENDIF ENDEXEC ENDMODEL Notice that we do not need to specify an ELSE clause in the IF statement. The complete IF statement could be written as: IF track_control > 0 THEN out:=x ELSE out:=out ENDIF but by default.0= waiting for control>0 -.1= waiting for control<=0 OUTPUT out INIT state := 0 out := out_ini ENDINIT EXEC IF state = 0 AND sample_control > 0 THEN state:=1 out:=x ELSIF state = 1 AND sample_control <= 0 THEN state:=0 ENDIF ENDEXEC ENDMODEL The model can be used with the following USE statement: USE sample_hold AS somename DATA out_ini := ________ (optional) INPUT x := ________ sample_control := ________ OUTPUT ______________ := out ENDUSE The track/hold device passes the value of the input signal when the control signal is positive.

not only the name of a variable. respectively.3. x2.3. as follows: USERS GUIDE TO MODELS IN ATP . prevval.) to perform that operation..14. etc. 7. To find the minimum of many signals. ) where each argument can be an entire expression.111 USE track_hold AS somename DATA out_ini := ________ (optional) INPUT x := ________ track_control := ________ OUTPUT _____________ := out ENDUSE 7.) and max(x1.). we can use the built-in functions min(x1. expr2.. TACS type-64 min/max tracking The min/max tracking device of TACS is a resettable track/hold device that uses as input the minimum or maximum value of a group of signals. ) and for the instantaneous maximum: y := max( expr1. we can use: y := min( expr1. expr2.x2. etc.x2. just as for any function in MODELS except the built-in simulation functions (deriv.. we can use the track/hold model that has been defined above. ) track_control := ________ OUTPUT _____________ := out ENDUSE If we need a reset control.15. In MODELS... and supply as input an instantaneous minimum or maximum: USE track_hold AS somename DATA out_ini := ________ (optional) INPUT x := min( x1. etc. If the reset function is not needed. TACS type-63 instantaneous min/max The output of the instantaneous min/max device of TACS is that of the lowestvalued or highest-valued input.. then we can add on to the previously-defined track/hold model. etc.

holds when positive reset_control {dflt:0} -. First. The second is that we do not need to specify the third clause of the IF statement to indicate that the output value maintains its value when the two other conditions are not true.holds when positive reset_control {dflt:0} -.initial value of out. defaulted to +infinity INPUT x -.used on reset VAR out OUTPUT out INIT IF out_ini = -inf THEN out := x ELSE out := out_ini ENDIF ENDINIT EXEC IF reset_control > 0 THEN out:=reset_value ELSIF hold_control <= 0 THEN out:=max(x. except for the value of the initial condition: MODEL maxtrack_hold DATA out_ini {dflt:-inf} -. defaulted to -infinity INPUT x -.used on reset VAR out OUTPUT out INIT IF out_ini = inf THEN out := x ELSE out := out_ini ENDIF ENDINIT EXEC IF reset_control > 0 THEN out:=reset_value ELSIF hold_control <= 0 THEN out:=min(x.resets when positive reset_value {dflt:0} -. as this is done by default.out) ENDIF ENDEXEC ENDMODEL There are two details to notice.out) ENDIF ENDEXEC ENDMODEL and would be used as follows: USERS GUIDE TO MODELS IN ATP . This model can be used as follows: USE mintrack_hold AS somename DATA out_ini := ________ INPUT x := ________ hold_control := ________ reset_control := ________ reset_value := ________ OUTPUT _____________ := out ENDUSE (optional) (optional) (optional) (optional) The maximum track/hold model is similar.resets when positive reset_value {dflt:0} -.initial value of out.112 MODEL mintrack_hold DATA out_ini {dflt:inf} -. the reset control signal has priority over the hold control signal.tracked signal hold_control {dflt:0} -.tracked signal hold_control {dflt:0} -.

3.holds when positive reset_control {dflt:0} -.initial value of out.to prepare for out+x below ENDINIT EXEC IF reset_control > 0 THEN out:=reset_value ELSIF hold_control <= 0 THEN out:=out+x ENDIF ENDEXEC ENDMODEL Here is the corresponding USE statement: USE accumulator AS somename DATA out_ini := ________ INPUT x := ________ hold_control := ________ reset_control := ________ reset_value := ________ OUTPUT _____________ := out ENDUSE (optional) (optional) (optional) (optional) 7.3. defaulted to zero INPUT x -.17. and its output value can be reset to a specified value.used on reset VAR out OUTPUT out INIT out := out_ini IF hold_control <= 0 THEN out:=out-x ENDIF -. using a moving window of fixed width corresponding to the base frequency. Its operation can be described using the following model: MODEL accumulator DATA out_ini {dflt:0} -. TACS type-65 accumulator / counter The type-65 accumulator keeps a running sum of its input over time. USERS GUIDE TO MODELS IN ATP . It can be put on hold.input signal hold_control {dflt:0} -.16.113 USE maxtrack_hold AS unique_name_in_your_model DATA out_ini := ________ (optional) INPUT x := ________ hold_control := ________ (optional) reset_control := ________ (optional) reset_value := ________ (optional) OUTPUT _____________ := out ENDUSE 7.resets when positive reset_value {dflt:0} -. TACS type-66 RMS value The type-66 rms meter in TACS continuously updates the output value of the meter.

initial rms value INPUT x -.delay(ix2. period))/period) ENDIF ENDEXEC ENDMODEL Using a pre-determined fixed period keeps the model simple.base frequency xrms_ini {dflt:-1} -.monitored signal VAR xrms -. A more complete rms meter would allow for variable period and arbitrary dc bias.internal. integral of x2 period -. x*x ix2 -.1/freq OUTPUT xrms DELAY CELLS(ix2): 1/freq/timestep +1 INIT period := recip(freq) histdef(ix2) := 0 integral(x2) := 0 IF xrms_ini <0 THEN xrms:=0 ELSE xrms:=xrms_ini ENDIF ENDINIT EXEC x2 := x*x ix2 := integral(x2) IF t>period THEN xrms := sqrt((ix2 . The above model can be used as follows: USE rms_meter AS unique_name_in_your_model DATA freq := _______ in Hz xrms_ini := _______ (optional) INPUT x := _______ in any units OUTPUT ________ := xrms ENDUSE USERS GUIDE TO MODELS IN ATP .114 MODEL rms_meter DATA freq -.rms value of monitored signal x2 -.internal.

115 APPENDIX A – SYNTAX OF THE MODELS LANGUAGE This is a summary reference to the syntax of the MODELS language. i. tacs. switch. without any of the explanatory text. MODELS section in ATP MODELS section input declaration type: v. imssv. imssi. pl4. atp MODELS section output declaration MODELS section variable declaration MODELS section model declaration declaration of a local model declaration of a foreign model USERS GUIDE TO MODELS IN ATP . It consists of all the structure and the syntax diagrams contained in the Language Manual. mach.

116 MODELS section USE statement MODELS section RECORD directive record element Description of a local model declaration in a model constant element data element input element output element variable element function submodel declaration of a constant element USERS GUIDE TO MODELS IN ATP .

117 declaration of a data element declaration of an input element declaration of an output element declaration of a variable element declaration of a function statement function point list function foreign function declaration of a statement function declaration of a point list function declaration of a foreign function USERS GUIDE TO MODELS IN ATP .

118 declaration of a submodel local model foreign model external model declaration of a local model declaration of a foreign model declaration of an external model simulation directive in a model history directive time step directive input interpolation directive delay cells directive history directive time step directive USERS GUIDE TO MODELS IN ATP .

119 input interpolation directive delay cells directive Procedure in a model initialization procedure execution procedure named procedure initialization procedure execution procedure named procedure USERS GUIDE TO MODELS IN ATP .

x D-polynomial USERS GUIDE TO MODELS IN ATP .120 Statement assignment statement algorithm control statement assignment statement value assignment differential equation Laplace transfer function z transfer function integral value reset assignment history assignment value assignment differential equation y.

x S-polynomial limits z transfer function ZFUN(y / x) := (z-1-polynomial) / (z-1-polynomial) CZFUN(y / x) := (z-1-polynomial) / (z-1-polynomial) ZFUN(y / x) { limits } := (z-1-polynomial) / (z-1-polynomial) CZFUN(y / x) { limits } := (z-1-polynomial) / (z-1-polynomial) USERS GUIDE TO MODELS IN ATP .121 limits Laplace transfer function LAPLACE(y / x) := (S-polynomial) / (S-polynomial) CLAPLACE(y / x) := (S-polynomial) / (S-polynomial) LAPLACE (y / x) { limits } := (S-polynomial) / (S-polynomial) CLAPLACE (y / x) { limits } := (S-polynomial) / (S-polynomial) y.

122 y. x z-1-polynomial limits integral value reset assignment history assignment algorithm control statement IF statement WHILE statement FOR statement DO statement REDO statement COMBINE statement ERROR statement USE statement procedure call USERS GUIDE TO MODELS IN ATP .

. ENDDO COMBINE statement COMBINE AS identifier statement-list ENDCOMBINE COMBINE ITERATE AS identifier statement-list ENDCOMBINE COMBINE ITERATE { max-iter } AS identifier statement-list ENDCOMBINE USERS GUIDE TO MODELS IN ATP .123 IF statement WHILE statement FOR statement DO statement REDO statement DO . REDO ....

124 ERROR statement USE statement procedure call instance.procname(arg-list) WRITE(write-list) WRITE1(write-list) WRITE2(write-list) write-list Directive in a USE statement USE data directive USE input directive USE output directive USE history directive USE time step directive USE input interpolation directive USE delay cells directive USERS GUIDE TO MODELS IN ATP .

125 USE data directive USE input directive USE output directive USE history directive USE time step directive USE input interpolation directive USE delay cells directive USERS GUIDE TO MODELS IN ATP .

126 Expression regular expression sum expression in a value assignment derivative expression in a value assignment integral expression in a value assignment regular expression regular expression regular expression { limits } sum expression in a value assignment derivative expression in a value assignment integral expression in a value assignment Regular expression USERS GUIDE TO MODELS IN ATP .

<=. >=.127 logical term logical factor logical relation num-expr rel-op num-expr relational operators >. <. <> numerical expression numerical term numerical factor exponent relation value reference ** value reference USERS GUIDE TO MODELS IN ATP . =.

128 modulo relation value reference MOD value reference value reference numerical value where 'n' is any contiguous sequence of one or more decimal digits array value named value function value USERS GUIDE TO MODELS IN ATP .

129 Value-holding element single-value element array-value element single-value element array-value element Syntactic element name numerical value logical value text value in-ine comment block comment separator name numerical value where 'n' is any contiguous sequence of one or more decimal digits USERS GUIDE TO MODELS IN ATP .

semicolons. on/off. yes/no text value "text" or 'text' in-line comment start: two or more contiguous hyphens (hyphen string) end: end of line block comment separator commas. white-space characters USERS GUIDE TO MODELS IN ATP . closed/open.130 logical value true/false.

.... switch.. } use directives USE .. atp OUTPUT.... imssi... { type( . i. ENDMODEL MODEL .. imssv.. ENDMODELS element declarations INPUT . FOREIGN .. AS . { IXDATA: ... tacs. IXOUT: . Keywords of the MODELS section of ATP start/end MODELS . without the details of the full syntax rules. VAR .. ) } type: v. model declarations MODEL . It shows only the keywords of the language.. mach.. USERS GUIDE TO MODELS IN ATP ......131 APPENDIX B – KEYWORDS OF THE MODELS LANGUAGE This section provides a condensed structured overview of the syntax of the MODELS language... ENDUSE record directives RECORD . IXIN: .. IXVAR: . pl4....

... IXIN: . USERS GUIDE TO MODELS IN ATP . ENDMODEL element declarations CONST ..... ....... { IXARG: .. } INPUT .. ) ( . VAR ... INTERPOLATION DEGREE DFLT: .. } DATA ... IXVAR: ....... DELAY CELLS DFLT : ... FUNCTION . ) : ... . ) .. ) : .. { DFLT: ...... FUNCTION .. MAX: ....... := . POINTLIST ( . } HISTORY INTEGRAL( .. { IXDATA: ....... { VAL: .. FOREIGN ... } submodel declarations MODEL ... } OUTPUT ... function declarations FUNCTION ...... INTERPOLATION DEGREE ( . { DFLT: .. ENDMODEL MODEL .132 Keywords of the Model description start/end MODEL . } MODEL .. DELAY CELLS ( .. ...... .. { DFLT: ... EXTERNAL simulation directives HISTORY .. ) { DFLT: .. FOREIGN . } TIMESTEP MIN: .... IXOUT: ..

HISTDEF( ... ) := ..... } AS .. LAPLACE( ........ := . ) := ...... ZFUN( . DMAX: .. DMAX: . ENDFOR DO .. } := ... { DMIN: .. ENDWHILE FOR . ENDEXEC PROC ... ) | . ) WRITE( . ENDDO COMBINE AS . algorithm control statements IF ..... ENDUSE instance...... ELSE ....... { DMIN: . ) | .... := .. STOP USE . } := ...... ) USERS GUIDE TO MODELS IN ATP ...133 procedures INIT .. THEN .... } := . CLAPLACE( .. ) | .. DMAX: ..... } := .... REDO ..... ENDIF WHILE .. DO . CZFUN( ..procname( ... ENDCOMBINE COMBINE ITERATE AS . DMAX: . INTEGRAL( . } := . { DMIN: .. DMAX: ... } := ..... ENDCOMBINE ERROR ... { DMIN: ...... ELSIF ...... { DMIN: .... ) | . ENDPROC Keywords of the Statements assignment statements .... CDIFFEQ( ...... ) WRITE1( ... DIFFEQ( . ) | . ) | . .. ENDCOMBINE COMBINE ITERATE { .... { DMIN: ... ENDINIT EXEC ... ) WRITE2( . THEN ....... DO ... ...... DMAX: .

OUTPUT .. MAX: .. DELAY CELLS( .. MAX: ..... DMAX: ..... } USERS GUIDE TO MODELS IN ATP . ) { MIN: . DELAY CELLS DFLT : .... } INTEGRAL( .... ) { DMIN: ..... ) : ... } SUM( ............. := .. ) : ... INTERPOLATION DEGREE( .134 Keywords of the Directives in a USE statement DATA . MAX: ...... TIMESTEP MIN: . := . := .. INPUT .. Keywords of the Expressions regular-expression { MIN: . } DERIVPOL( . INTERPOLATION DEGREE DFLT: . HISTORY ....... MAX: .. := .. ) { MIN: ..

ENDILLUSTRATION USERS GUIDE TO MODELS IN ATP . . . OR .. . . = .... + ...... . . > ..... * ... . AND . .... ] function name ( ... .... ] name [ .... MOD . .... NOT ...... .. >= . ... / . ..... end-of-line COMMENT .... ] ........ ... .....135 Keywords of the Regular expression . num value [ .. ) ( regular expression ) Keywords of the Comments -.. .. ..... .. < ... ENDCOMMENT ILLUSTRATION .. . ** .. ... <> .... .... name name [ ........ .. .... <= ...

The value of the logical constants are represented internally as the numerical values 0 and 1. or application controlling the simulation. Their names are pre-defined. a large number. They are: starttime stoptime the value of t at which the simulation started the value of t at which the simulation will end USERS GUIDE TO MODELS IN ATP . and are visible in any model. The value of these variables can be accessed by name inside any expression. true no. Pre-defined constants The pre-defined constants have pre-assigned values. Pre-defined global variables Three variables are defined globally in a simulation. They carry the value of the starting and ending time of the simulation. in any model of a simulation. typically 1020 88888. shell. The value undefined is the value carried by any variable that has not yet been assigned a value during a simulation. closed off. in any model of a simulation. The values of the pre-defined variables carry simulation information that can be accessed inside any model.14159. yes open.136 APPENDIX C – PRE-DEFINED CONSTANTS AND VARIABLES The MODELS language provides a set of pre-defined constants and pre-defined global and local variables. on 3. and can be used inside any expression.. The values of the pre-defined constants are-defined globally. They are: pi inf undefined false.88888 the equivalent numerical values 0 and 1 the equivalent numerical values 0 and 1 the equivalent numerical values 0 and 1 the equivalent numerical values 0 and 1 The infinity value inf is dependent on the computer platform being used. and the value of time step imposed by the environment..

In a case where timestep. the relationship between these variables is simple: t0 fullstep endtime t timestep minstep <= fullstep <= maxstep timestep = fullstep t = endtime = t0 + fullstep = t0 + timestep prevtime = t0 USERS GUIDE TO MODELS IN ATP . is the same size as fullstep. which is also the time step of the calling model. the calling interval. Pre-defined local variables The names of the pre-defined local variables are the same in all models of a simulation. on each update call to a model instance from a USE statement. The value of these variables can be accessed by name inside any expression. the time step used in the called model. They are: t prevtime timestep endtime fullstep minstep maxstep the present simulation time the simulation time at the last update the size of the interval between prevtime and t the target simulation time of a USE call the size of the interval over which to update at USE call the variable lower limit imposed on timestep the variable upper limit imposed on timestep These variables carry information about how the state of a model is updated from a previous simulation time to a target simulation time. but their values are local to each instance of each model used in a simulation. in any model of a simulation. and may change during a simulation. The value of stoptime is defined by the application controlling the simulation.137 startstep the value of the initial time step at the outermost level The values of starttime and startstep are set at the start of the simulation.

Only then is control passed back to the calling model. the full step is subdivided into sub-steps of a size that satisfies the maxstep upper limit. For this case. . because the time increase is considered to be too small to change the present state of the model significantly. until the target time endtime is reached. . and the model instance is executed for each sub-step successively. ...timestep } USERS GUIDE TO MODELS IN ATP .t0 >= minstep to update its state. the relationship between the variables is as follows: t0 fullstep endtime t timestep timestep timestep fullstep > maxstep timestep <= maxstep timestep < fullstep t = { t0 + timestep. in one large time step.138 In a case where fullstep is smaller than minstep. t0 + timestep. t0 + 2*timestep. The model waits until endtime . along with the model's output values at time t = endtime. the model instance does not update itself to the outside time.. t0 fullstep fullstep fullstep endtime t timestep In a case where fullstep is larger than the largest time step allowed maxstep. endtime .. . endtime } prevtime = { t0.

When given a list of arguments as input. each corresponding to the function being applied to each value supplied in the argument list.139 APPENDIX D – PRE-DEFINED FUNCTIONS MODELS provides a set of pre-defined functions.returns [abs(x[1]). these functions return a single output value. and n-argument functions returning a single value. They are grouped as one-to-one functions..returns array of absolute values of each list element -. x[1.returns array of absolute values of each array element Following are the 1-to-1 numerical functions: abs( ) sqrt( ) exp( ) ln( ) absolute value square root exponential natural log arg<0 produces error arg<0 produces error USERS GUIDE TO MODELS IN ATP . This is illustrated below using the absolute value function: abs(a) abs(expression) expression abs(a.2]) abs(array expression) -. abs(b)] -. they return as many output values. MODELS allows single-argument functions to be used with lists of arguments.returns one value: the absolute value of the -.returns one value: the absolute value of a -. abs(x[2])] -. a function that is normally a singleargument function will return a corresponding list of single values as output. one output for each argument (one-to-one).returns [abs(a). There is also a set of simulation functions that make explicit or implicit reference to the stored history of the variables of a model. There are built-in numerical functions.returns [abs(a). 1-to-1 functions returning one value for each argument When used with a single argument. b) abs(expression list) abs(x[1. abs(x[1]). In order to extend the use of single-argument functions to array arithmetic. two-argument functions returning a single value. logical functions.2]) abs(a.. and random value functions. abs(x[2])] -. Numerical functions This is a list of all the pre-defined functions that return numerical values. When used with a list of argument values.

atan( ) sinh( ). tanh( ) asinh( ). acos( ). This is illustrated here using the atan2() function: atan2(a.returns one value: arctan(x[1]/x[2]) Following are the 2-to-1 numerical functions: atan2( ) binom( ) permut( ) 4-quadrant arctan(a/b) binomial function C(n. atanh( ) base 10 log base 2 log protected division factorial integer part fractional part rounding sign function degrees to radians radians to degrees trigonometric inverse trigonometric hyperbolic inverse hyperbolic arg in radians return value in radians arg in radians return value in radians -1 if <0.returns one value: arctan(expr1/expr2) -. tan( ) asin( ). acosh( ).140 log10( ) log2( ) recip( ) factorial( ) trunc( ) fract( ) round( ) sign( ) rad( ) deg( ) sin( ).r) permutation function P(n. cos( ).r) accepts zero-value arguments returns n! / (n-r)! r! returns n! / (n-r)! USERS GUIDE TO MODELS IN ATP .returns one value: arctan(a/b) -. b) atan2(expr1. or the two arguments can be specified together as a two-element array expression.2]) -. 0 if 0. cosh( ). expr2) atan2(x[1. +1 if >0 arg<0 produces error arg<0 produces error division by zero returns value=inf arg<0 produces error 2-argument functions returning a single value These functions always return a single value. and cannot be extended to array arithmetic as the previous 1-to-1 functions.. Each of the two arguments can be given in the form of a single-value expression.

corresponding to each value in the argument list.returns the minimum value of a. The list of input expressions can include single values and array values. It provides explicit conversion from numerical to logical ("Boolean"). bool( ) numerical to logical returns true if arg>0.returns the minimum value of the two args x[1] and -. and n-argument functions returning a single value. Conversion between numerical and logical values is automatic.. They are grouped as one-to-one functions. and return a single value. and x[2] -. and logical values to be used in a numerical context ( true is 1..returns the minimum value of the two arguments a and b min(expr1.141 n-argument functions returning a single value These functions take as input a list of values. When used with a list of argument values. The following example illustrates how the input values can be specified: min(a. When used with a single argument. 1-to-1 functions returning one value for each argument There is only one function in this category.2]) min(array expression) -.2]) x[2] min(a.. b) -. The logical values true and false are represented in MODELS by the numerical values 1 and 0.returns the minimum value of the argument list min(x[1. it returns a single output value. false if arg<=0 USERS GUIDE TO MODELS IN ATP . false is 0 ). expr2. . or magnitude returns sqrt(sum(arg2))) Logical functions This is a list of all the pre-defined functions that return logical values.) -. x[1]. and is determined by the context in which they are used.returns the minimum value of all array elements Following are the n-to-1 numerical functions: min( ) max( ) norm( ) minimum value maximum value Euclidian norm. This allows numerical values to be used in a logical context ( >0 is true.. it return as many output values. <=0 is false ). x[1.

bool(x[2])] -. If numerical values are supplied.returns one value: conversion value of a -. bool(x[2])] -. The following example illustrates how the input values can be specified: and(a. b) -. x[1. In the present Fortran version of MODELS.returns one value: conversion value of the expression -..returns true only if all argument values are true and(x[1...returns [bool(a). expr2. Logical values are expected for each argument.2]) and(array expression) -.2]) and(a. x[1. they are automatically converted to their logical equivalent.. using the same rule as shown above. and returns a value between zero and one: random( ) random value returns a random value between 0 and 1 The sequence of random numbers generated from repeated calls to the function random() is reproducible from one simulation run to the next.returns true only if a and b are true and(expr1.) -..returns true only if a and x[1] and x[2] are true -.returns true only if all array elements are true Following are the n-to-1 logical functions: and( ) or( ) nand( ) nor( ) xor( ) logical AND logical OR logical NOT AND logical NOT OR logical exclusive OR returns true only if all args are true returns true if one or more args are true returns true if one or more args are false returns true only if all args are false returns true if only one arg is true Random value functions There is one random value function pre-defined in MODELS at this point. this USERS GUIDE TO MODELS IN ATP . . To generate nonreproducible sequences requires a call by the program to the date/time routine of the computer's operating system.returns true only if x[1] and x[2] are true -.returns array of conversion value of each element n-argument functions returning a single value These functions take as input a list of values. b) bool(expression list) element bool(x[1.2]) bool(a. The function uses no arguments. bool(x[1]).returns array of conversion value of each list -.returns [bool(a). The list of input expressions can include single values and array values. bool(b)] -.2]) bool(array expression) -.returns [bool(x[1]). and return a single logical value.142 Here are examples showing how the function can be used: bool(a) bool(expression) bool(a..

} double C_RANDOM(void) /* returns a random number between 0 and 1 */ { return (double)rand()/(double)RAND_MAX. y := x * rand(0) . It returns no value. the functions can then be used as in the following example: INIT dum := seed(0) expression .returns a value between 0 and 1.. it will be available.functions in MODELS can only be used inside an -. When provided.... because C provides a standard compilerindependent function for this.for of ATP. return 0. two foreign C functions have been pre-linked to ATP: C_seed() to generate a new seed.. and C_random() to generate a sequence of random numbers based on that seed. In the meantime. After being declared in a model. The use of these functions does not affect the sequence of numbers generated by the MODELS function random(). It returns a value between 0 and 1. C_seed(x) uses a dummy argument of any value. ENDEXEC -. } These functions can be declared in a model as follows: FUNCTION seed FOREIGN C_SEED {ixarg: 1} FUNCTION rand FOREIGN C_RANDOM {ixarg: 1} where the names C_SEED and C_RANDOM are already registered in subroutine fgnfun in the file named fgnmod.h> double C_SEED(void) /* randomly seeds the C library function rand() */ { date_time_seed().. C_random(x) uses a dummy argument of any value. it is compiler-dependent. ENDINIT EXEC . because Fortran doesn't provide a standard function for doing this. The source code for the two C functions is the following: #include <stdlib.143 is not available. In the future C version of MODELS. then multiplied by x USERS GUIDE TO MODELS IN ATP .

1. and 2 are recognized for this. indicating respectively: no interpolation (the signal varies in steps). This is because an expression has no history which can be referred to when calculating the value of the function. calculated at mid-step value of x at previous time step value of x at time (t . pol) predval(x. tval) backval(x. dval. linear interpolation. and the "1" can always be omitted. and is never an expression. Linear interpolation is the default. When using the simulation functions. etc. dval) delay(x. tval) predval(x. previous value. xval) predtime(x. xval. pol) backtime(x. equivalent to writing histval(x.t) USERS GUIDE TO MODELS IN ATP . calculated at end of step d2x/dt2. tval) histdef(x) dx/dt. except histval(). Some simulation functions require a second argument. tval. for example x. the value of the delay applied to a variable.144 Simulation functions MODELS provides special simulation functions not available in regular programming languages. These are functions such as derivative. pol) histval(x. tval. the first argument in the argument list is always a single value-holding element. as shown below. xval. accept an optional third argument to indicate the interpolation method used by the function. or y[n]. pol) backval(x. pol) predtime(x. using the history expression associated with x value of the history expression of x evaluated at generic time t. and quadratic interpolation. xval) backtime(x. Only the values 0. The simulation functions are: deriv(x) deriv2(x) prevval(x) delay(x. for example. for the fact that they make an implicit reference to the advancing value of time and to the accumulated history of the variables to which they are applied. All 2-argument functions.dval) predicted value of x at time tval predicted time when x will equal xval value of x(tval) within last step interval time when x was equal to xval within last step value of x(tval).

the mid-step derivative is less sensitive to discontinuities.5 − t15 . in order to calculate the second derivative at t1: deriv 2t1 = which is then used to extrapolate linearly the first mid-step derivative. The program first calculates the two mid-step derivatives deriv0. However.145 deriv(x) The time derivative of x is calculated with the assumption that it is linear over each time step interval. The second derivative is calculated using: USERS GUIDE TO MODELS IN ATP . Only static limits can be applied to a derivative. Because the function doesn't carry any internal variables from one step to the next. as part of the expression where the function is used: y:=deriv(x) {min:expression. by doing: y:=(x-prevval(x))/timestep instead of using the built-in function: y:=deriv(x) It is possible to apply limits to the calculated value of a derivative.5 + deriv 2t1 ⋅ t 0 − t1 2 When the time step is small enough to cover the higher frequencies of the signal. = x(t 0 ) − x(t1) t 0 − t1 x(t1) − x(t 2) t1 − t 2 deriv0. The method takes into account the possibility for the time step to be variable. this method is more accurate than using the simple mid-step derivative. d2x/dt2. deriv0.5 − deriv15 . max:expression} deriv2(x) The second order derivative of x with respect to time.5 = deriv15 . that is. that the second derivative is constant over the interval. t0. using the second derivative as its slope: derivt 0 = deriv0. to the end of the interval. a dynamic limit has no meaning for the derivative. itself calculated at mid-step for the last two intervals. and should be used instead of deriv() when the time step is not well matched to the frequency contents of the signal. is calculated as the mid-step derivative of the first derivative.5.

substituting with the full calculation details: x(t 0 ) − x(t1) x(t1) − x(t 2) − t 0 − t1 t1 − t 2 t 0 + t1 t1 + t 2 − 2 2 When the time step is constant. max:expression} prevval(x) This function returns x(t-Δt).146 deriv0. because of the mid-step method.5 − deriv15 . this is equivalent to calculating the second derivative as: x(t ) − 2 x(t − Δt ) + x(t − 2 Δt ) Δt 2 It must be observed that the calculated value is in fact the value of the second derivative at the previous time t1. or. Only static limits can be applied to a second derivative. The second derivative of a variable can be used in any expression. for example: y:=deriv2(x) It is possible to apply limits to the calculated value of a second derivative. max:expression} delay(x. a dynamic limit has no meaning for this operation. It can be used in any expression. the value of a variable at the previous time step.5 − t15 . dval. as part of the expression where the function is used: y:=deriv2(x) {min:expression. t0. USERS GUIDE TO MODELS IN ATP . for example: y:=prevval(x) Static limits can be applied as part of the expression where the function is used: y:=prevval(x) {min:expression. This means that the value of the second derivative at time t is available only after a delay of one time step. Because the function doesn't carry any internal variables from one step to the next. pol) This function returns x(t-dval). the value of a variable at a past time of the simulation.

with the restriction that it must fall inside the last step interval. as it uses a binary search to locate the stored values. for step. By default. predtime(x. predval(x. because if xval is different from x(t). when the third argument is not specified. or quadratic interpolation. pol) This function returns t(xval). pol) This function returns x(tval). when the third argument is not specified. linear. By default. Otherwise. The value is calculated using extrapolation from the most recent values of the variable. t-dval). the pol argument can be given a value of 0. and returns the value histval(x. because it simply returns the present value of the variable. tval. linear interpolation is used. tval. where tracked values of the variable are available. the function returns the value undefined. then that value cannot be reached using step extrapolation. equal to 88888. Using step extrapolation is not useful in this case. when the third argument is not specified. or quadratic interpolation. Otherwise. the pol argument can be given a value of 0. the predicted value of a variable at a future time of the simulation. linear. backval(x. linear extrapolation is used. For USERS GUIDE TO MODELS IN ATP . 1. or quadratic interpolation. the calculation is fast. linear extrapolation is used. interpolation is used for cases where the value t-dval does not correspond exactly to one of the discrete instants of the simulation. the predicted future time when the variable will take the value xval. linear. or 2. the delay() function uses the history expression associated with that variable to calculate the past value. for step. The value is calculated using extrapolation from the most recent values of the variable. When the requested past time falls after the start of the simulation. the value of a variable at a past time of the simulation. 1. for step. or 2. 1. However. By default. pol) This function returns the value x(tval). before the value of the variable could started being tracked. xval. When the extrapolated value of the variable cannot reach the value xval. Using the delay function can require a considerable amount of storage for keeping track of the past values of a variable (see the simulation directive DELAY CELLS). the pol argument can be given a value of 0. Otherwise. Using step extrapolation is not useful in this case. or 2.88888 .147 When that requested past time falls before the start of the simulation. that is.

88888 . or quadratic interpolation. the requested past time will fall before the start of the simulation. When the interpolated value of the variable cannot reach the value xval. with the restriction that the time must fall within the last step interval. xval. when the third argument is not specified. See the section on simulation directives for a discussion on assigning a history expression to a variable. When the requested past time falls after the start of the simulation. where tracked values of the variable are available. because if xval is different from x(t-timestep). the histval() function can be used without any restriction on the value of tval. For whatever value of t. before the value of the variable could started being tracked. linear interpolation is used. the solver manipulates the value of the variable t behind the scenes whenever it needs to evaluate a USERS GUIDE TO MODELS IN ATP . for step. equal to 88888. the pol argument can be given a value of 0. In this case. pol) This function returns the time t(xval) at which the variable had the value xval. or 2.t). The value is calculated using interpolation from the most recent values of the variable. the pol argument can be given a value of 0. because the history expression will provide a value calculated at t equal to tval. histval(x. then that value cannot be reached using step interpolation. tval). backtime(x. or 2. histdef(x) Using this function is equivalent to using histval(x. By default. No interpolation is needed. By default. Otherwise. Using step extrapolation is not useful in this case. we need to use the delay() function. tval) This function uses the history expression specified for the variable x in order to calculate the value of x(tval). this function will return the corresponding value of the history expression associated with the variable x. 1. the backval() function uses the history expression associated with that variable to calculate the past value. or quadratic interpolation. Although a history expression is intended to be used for calculating values of a variable at values of t preceding the start of the simulation. for step. linear. interpolation is used for calculating the value of the variable between the simulation points. At first look. Otherwise. 1. that is. linear. when the third argument is not specified.148 access to past values beyond the previous step. linear interpolation is used. this may seem useless. It becomes more interesting when we consider that during the simulation. and returns the value histval(x. the function returns the value undefined. At the first step of a simulation.

t) . it would have been equivalent to write the expression of the history expression as: histval(x.2*histdef(w)} or in a history assignment in a USE statement: HISTORY y := histdef(x) .2*histdef(w) In each case.149 history expression at a certain time t.2*histval(w.t) to access the value of the history expression of x and w at whatever value of t selected by the solver at the time it evaluates the expression. Using the function histdef(x) inside the expression defining the history expression of another variable y gives us a way to make a history expression dependent on the history expression defined for another variable. For example.2*histdef(w) or in a history assignment in the INIT procedure: histdef(y) := histdef(x) . we would use it in a history declaration as follows: HISTORY y {dflt: histdef(x) . USERS GUIDE TO MODELS IN ATP .

Bonfanti (CESI. USA). G. Denmark. USERS GUIDE TO MODELS IN ATP . J. Lingby. "TACS and MODELS: Drive simulation languages in a general purpose program". no. Jornadas Luso-Espanholas de Engenharia Electrotecnica. Dubé (DEI Simulation Software. Jan/Feb 1992. no. Denmark) Paper 92-R-006. S. USA) EMTP News. France) Proc. Marseille (France). Marseille (France). USA). 45-50. 22nd European EMTP Meeting. I. Italy) Paper 89-11. Rønne-Hansen (Tech. 2. Politècnica Catalunya. Martinez-Velasco (Univ. Capolino (Mediterranean Inst. Leuven (Belgium). Univ. May 1989 "Development of a new three-phase synchronous machine code using MODELS". Oregon. Ballerup. July 1991.. J. Marseille. J. Oregon. Knudsen (ELKRAFT Power Co. Bortoni. 5. Capolino (Mediterranean Inst. Dubrovnik (Yugoslavia). Marseille.. 22nd European EMTP Meeting. Vol. Crete (Greece).A. Politècnica Catalunya. Tech. Gústavsen. July 1991. USA). I. Mork (No. Spain). Denmark). Denmark) Paper 92-R-014.A. 16th european EMTP Meeting. pp. "Variable capacitance and inductance in ATP using MODELS".A. Milano. Ballerup. Martinez-Velasco (Univ. N. J. 21st European EMTP Meeting. "The EMTP's new TACS".A. J.A. Dubé (DEI Simulation Software. L. L. France). "Aplicaciones del código MODELS". Spain) 2as. Dakota Univ. 1. Vol. November 1992. Leuven (Belgium). Italy) European Transactions on Electrical Power Engineering. Italy) Paper 90-M3. Oregon. Milano. Spain). B. Bortoni (CESI.] using EMTP MODELS". G. MCED '91. L. Støvring-Hallsson (ELKRAFT Power Co. "MODELS: A new simulation tool in the EMTP". H. 18th European EMTP Meeting. Martinez-Velasco (Univ.. "Simulation of a microprocessor-controlled SVC". Politècnica Catalunya. Leuven (Belgium).A. Spain) Paper 92-013. June 1992 "Implementation of a 6-phase synchronous machine model [. March 1992.. Martinez-Velasco (Univ.A. G. Tech. Milano. Dubé (DEI Simulation Software. May 1990. "Modelling a generator relay protection scheme in EMTP using MODELS". G.150 BIBLIOGRAPHY This bibliography provides a list of published articles describing or referring to the MODELS language. 1. November 1992. Bonfanti (CESI. Politècnica Catalunya. Coimbra (Portugal).

M. L. measurement of power flow and voltage phasor oscillation at any point of the simulated system using MODELS". Portugal). USA) EMTP News. Univ. UK) First European Conference on Power Systems Transients. Lisbon.W. Spain) First European Conference on Power Systems Transients. "A 6. Kizilcay (Lahmeyer Int'l. Belgium) Proc. Oregon.3 KV vacuum breaker model for ATP simulations". of Nottingham.P. Lisbon (Portugal). "EMTP simulation of source-insulator interaction in pollution tests". Politècnica Catalunya. USA) European EMTP User Group Meeting. Thomas (Univ.151 "Educational use of EMTP MODELS for the study of rotating machine transients". Spain) IEEE PES Winter Power Meeting. pp. Lingby (Denmark). of Nottingham. "Using the simulation language MODELS with EMTP". Columbus (USA). L. M.S. Oregon.. M. Bonfanti (CESI. Kalat. June 1993. April 1994 "Including a transmission line with corona in ATP using MODELS". D. J. Vanderstockt (LABORELEC. J. Dubé (DEI Simulation Software. Correia de Barros (IST/Univ.T. Milano. 11th Power Systems Computation Conference. D. no. 6. Oregon.Martinez-Velasco (Univ. Dubé (DEI Simulation Software. L. Técnica de Lisboa. Pochanke (Warsaw Tech. Correia de Barros. Slovenia) First European Conference on Power Systems Transients. Z. 1063-1069. Poland) European EMTP User Group Meeting. M. UK) European EMTP User Group Meeting. Lingby (Denmark). M. Martinez-Velasco (Univ. 1. USA). "Power swing simulation studies. Portugal). April 1994 USERS GUIDE TO MODELS IN ATP . Frankfurt.A. Avignon (France). Dubé (DEI Simulation Software. August 1993. W. Técnica de Lisboa. Jones. Germany) European EMTP User Group Meeting. Zunko (Ljubljana Univ. June 1993. Vol. I.T.A. April 1994 "Grounding system simulation by means of ATP MODELS". Almeida (IST/Univ. February 1993 "Connection of user-supplied programs to EMTP using MODELS". "Utilizing the frequency scan feature of ATP-EMTP". Paper 93 WM 126-3-PWRS. Mechraoui. V. J. Lisbon (Portugal). Leuven (Belgium). Lingby (Denmark). Italy). June 1993.P. P.E. Politècnica Catalunya. Loboda. Lisbon (Portugal). M. Kosmac. A. Lisbon. Lingby (Denmark). March 1993.. Thomas (Univ. April 1994 "Modelling of a travelling wave phase selector for EHV transmission lines".W.

paper 94 SM 452-3 PWRD. Dubé (DEI Simulation Software. Germany) Int'l Conf.A. "Using the Electromagnetic Transient Program for frequency scans". Estanqueiro. Spain) IEEE PES Summer Power Meeting. July 1994. July 1994. July 1995. L. April 1994 "EMTP simulation of a digitally-controlled static VAR system for optimal load compensation". paper 94 SM 477-0 PWRD.T. Portugal) Int'l Conf. M. (Oregon State University. Lisbon.. B. Almeida (IST/Univ. Portland. Ferreira de Jesus (INETI / ITE. USERS GUIDE TO MODELS IN ATP . Portugal). G. Correia de Barros. Politècnica Catalunya. M. Univ. "Representacion avanzada de interruptores mediante el EMTP". J. F. Lisbon. USA) IEEE PES Summer Power Meeting. J. M. Portugal). Spain) 1995 "Inclusion of corona in the evaluation of surge propogation with EMTP". San Francisco (USA). M. Oregon. on Power systems Transients (IPST ' 95).T. Wrate. San Francisco (USA). Sept 1995. Oregon. Martinez (Univ.E. Oregon.Almeida. Lisbon. Lingby (Denmark). Mork (Michigan Tech.E. Técnica de Lisboa. Oct 1994. Dellwo (Northern States Power Co.Stockholm Power Tech 95. Corvallis. M. July 1995. Técnica de Lisboa. S. Portugal). Portugal). IEEE PES Summer Power Meeting. A.. Lisbon. Stockholm (Sweden). M. "Interfacing with EMTP a general-purpose transmission line model". I. M. A. Técnica de Lisboa. "As EMTP Study of SSR Mitigation Using the Thyristor Controlled Series Capacitor". M.P. S. USA). Técnica de Lisboa. Sept 1995.E.A. Castro (IST/Univ. Stein (FGH. L.T. W. L. Portugal) European EMTP User Group Meeting. Spain) Porto (Portugal). June 1995. "Transient analysis of rotating machines using EMTP MODELS". Politècnica Catalunya.K. Mannheim. M. Lisbon. USA) MIPSYCON. K. Dubé (DEI Simulation Software. "Including a wind energy conversion system model in electromagnetic transients program". J. Correia de Barros (IST/Univ. Almeida (IST/Univ. Martinez-Velasco (Univ. Técnica de Lisboa. M. G. SPT HV 07-04-0253. Lisbon. on Power systems Transients (IPST ' 95). Lisbon.T. USA) International Symposium on Electric Power Engineering . Correia de Barros. Zhu et al.A. Paper No.T. Portugal.E. Mustaphi. Politècnica Catalunya. B. Almeida (IST/Univ. USA). Martinez-Velasco (Univ.A. Correia de Barros. R. Portugal. J.152 "Tower modelling for lightning surge analysis using EMTP". Lisbon. "Computation of Electromagnetic transients on nonuniform transmission lines". Reis. G. Minneapolis.

Germany. Sept 1995. Hannover. Curitiba. L. Spain).. Técnica de Lisboa. Z. J. European EMTP User Group Meeting. "Advanced representation of power semiconductors using the EMTP". F. Nov 1995 "SF6 circuit breaker modelling for shunt reactors switching". Politècnica de Catalunya. Hannover. Nov 1995 "A neural network vacuum circuit breaker model for simulation of transients overvoltages". Hannover. C. Lisbon. Sept 1995. Portugal) Int'l Conf. Sweden) European EMTP User Group Meeting. Martinez-Velasco (Univ. "Modelling the electrical and thermal behaviour of metal oxide arresters using MODELS". of Budapest. G. Zunko (Ljubljana Univ. Nov 1995 USERS GUIDE TO MODELS IN ATP . J. European EMTP User Group Meeting. M. V. Prikler (Technical Univ. Barcelona. Tennakoon (Staffordshire Univ. on Power systems Transients (IPST ' 95). Politècnica de Catalunya. Brazil) Int'l Conf. Germany. Germany. Barcelona. Ban. Marseille. Bichels (COPEL. Harris. Portugal. Bliss. B.A. Tang. Lisbon. Lisbon. Sept 1995. Portugal. France) Int'l Conf. Hannover. Nov 1995 "A gas discharge tube module based on discharge physics for use in ATP-EMTP simulation". Barcelona. A. Scuka (Uppsala Univ. Hungary) European EMTP User Group Meeting.A. Sousa. H. Correia de Barros (IST/Univ. Nov 1995 "Circuit breaker representation for TRV calculations".F.. Politècnica de Catalunya.A. M. Portugal. France).A. Larsson. Ma. Germany.A. Germany. A. Martinez-Velasco (Univ.W. Hannover. A. J. Somogyi. R. A. S. D.153 "Tripping analysis of generator negative sequence relay during a transformer energization".B. UK) European EMTP User Group Meeting. Aix-Marseille II. on Power systems Transients (IPST ' 95). Lisbon. Hannover. Spain). Abdo (Univ. on Power systems Transients (IPST ' 95). Ushikubo. Nov 1995 "Modelling of curcuit breakers using the type-94 component". Capolino (Univ. Spain). Santos. de Picardie. Martinez-Velasco (Univ. Kosmac. Germany. T. J. Amiens. J. "Fault arc modeling in EMTP". P. Slovenia) European EMTP User Group Meeting.

European EMTP User Group Meeting. Saha. J. Nov 1995 "Investigation of transformer differential protection schemes by using ATP-MODELS". E. Oregon. Germany. Västeras. B. Dubé (DEI Simulation Software. M. B. Spain). Germany) L. Sweden) European EMTP User Group Meeting. Proc. Politècnica de Catalunya. Barcelona. Nov 1995 "A new method for EMTP implementation of nonlinear components". August 1996.A. Rosolowski (ABB Network Partner. 12th Power Systems Computation Conference. M. Hannover.154 "Postprocessing of measured transient data using MODELS in the ATP-EMTP". Hannover.M. Germany. USERS GUIDE TO MODELS IN ATP . Dresden (Germany). USA). Hillström. Martinez-Velasco (Univ. Kasztenny. Kizilcay (FH Osnabrueck.

.................. 126 Curly braces '{ }' ........................................................................................................................ 140 Control components........... 152 backval( ) ............................ 82 B backtime( ) .................................................................................. 4 Blank lines ...................... 129 delay( )................................... 45.............................................................. 90 COMBINE statements.......................................... 151 USERS GUIDE TO MODELS IN ATP ............................................................................. 32..................... 9 Braces '{ }'................................................................................................ 59 Boolean values ....... 71......................................................................... 11.............................................................................................. 10 D Data ........................................................................................................................................................................................ 10 ATP inputs .............. 14............................. 143 Assigning data values .................... 126 Arithmetic operators........................................ 103 Conditional control ........................... 5 Controlling a procedure.......................................................................................................................................... 61.................................. 68......................................... 6............................................................. 108.............................................. 14.............................................................................................................. 59 Arrays ........................................................................................................... 80 ATP outputs .......................... 123 Assignment operator......................................................155 INDEX A Algorithm control ...................................................................... 12 Complex-value functions......................................... 87 Control systems .................................................................... 6.................... 87 Block comments.............. 122............... 68............. 40 Constants................................................................. 127 Comments ........ 72 Assigning values ..................................... 10 Brackets '[ ]' .......... 32........................................... 152 Basic aspects........................................... 32............................... 7.............................. 13.............................................................................................................. 128 Delay storage......... 83 ATP variables..................................................................................... 78............................................. 77............................................. 19........................................................ 71 Assigning output values ................................................................. 71 Assigning input values ............................................................................................................................ 2...... 10 C C programs ............................. 26 Circuit components ................................................ 8................. 12 Boolean operators..............

................................................................................................... 6 Global variables ................................ 44....... 4 Differential equations .............................................. 19.................................. 40..... 58.............................. 112................................................................... 129 External models (either local or foreign) ........................................................................................................... 87 Fortran programs .......................................... 11......................... 143 G Global constants ......................................... 25 External programs................................................... 21................... 126 Dynamic limits.............................. 120................................................................................... 123 Dimensions of MODELS storage in ATP ...................................................... 126 Foreign functions ..... 126 Indentation ......................... 96 Functions ......................................................... 127 EXEC procedure ......... 41 IF statements ............................................................................................... 95.......... 69......................................................156 Delimiters . 23.................................................... 63 Derivatives ....................... 26 Frequency meter.......... 122................. 149.......................................................... 37 E Equal sign .................................................................................. 55........................................... 6................................................. 128................................................... 99 DO statements ............ 121 Formatting.......................... 63 Difference between simulation language and programming language..................... 12 INIT procedure .......................................................... 29............................... 106 Frequency-domain use of a model................................ 19............. 95 F FOR arguments .......... 121 External point list for pointlist function................................... 33.................................................................... 28 Expressions ........................................................ 26....................................................................................................................................................................................................................................................................................................................................................... 19........ 26................... 125... 10 ERROR statements ................ 17................................. 153 I IF expressions................... 11 Derivative polynomials ........................................................ 28 USERS GUIDE TO MODELS IN ATP .................. 121 Foreign models ........................ 150 derivpol( ).............................. 55 FOR statements..................................................................................................... 153 History....... 51............................................................. 153 histval( ) ................... 6 H histdef( )............................................... 39............................................ 43.......................................

....................................... 15................ 33............................................................... 38................................ 119 Model instance..................... 128 Inputs from ATP .......... 124 Libraries of models and functions ............................................................................................. 82 Instance of a model................... 44 K Keywords of the MODELS language ............................................. 9 Numerical functions ....................................................157 Initialization .. 100 Limits ................................................................ 135 L Laplace transfer functions................. 12 Inputs ................................. 97 Initializing the type-94 component................... 11 Norton type-94 circuit component ................................................. 91 Numbers . 60 Linear sum ..................................................................... 9.. 2....................................................................................... 6................................... 62 List sizes in ATP for MODELS ...................................................................... 59 Logical values ............... 145 Logical operators ....................... 6 Local models................................ 91 Iteration and re-updating a model ..................................... 29.......................................... 71..................................................... 80........................................................................................ 94 Inline comments.................................................... 121 Local variables ............ 6 Logical functions ... 77.............................................................. 59 Numerical values ........................... 43..... 30.......... 63...... 17........................................ 125 Interpolation on inputs at sub-steps of the simulation ............................................................................................................................................ 122............ 42........................................................................................................................................................................................ 2 N Named procedures ....................................................................................................... 69........... 118 MODELS language ................................................................................ and MODEL .......... 58 USERS GUIDE TO MODELS IN ATP ................................................. 67................................................................................................ 73 Iteration control ..................... 52 Integrals ............................................. 9........ 115 Model description................... 52 Model.................. 76....................... 143 Numerical operators........ 9 MODELS in ATP ........................................................................... 9 M Min/max tracking............ 99........... 18.......................................................................................................................................................................... 123 Names .... 36........................................................................................... MODELS.......................................................... 99 Local constants ............................................... 78........... 85... 129 Iterated type-94 circuit component.............................................................................. 37..........................................

.... 74 USERS GUIDE TO MODELS IN ATP . 128 Simulation functions................................................................158 O Operators.......................................................................................................... 3 Project............................................................................................................................................................. 126 Referring to a named value........... 151 Procedures ..................................... 122....................... 66....................................... 17............................................ 128 Outputs to ATP ............................................ 84 REDO statements ..................................................... 151 prevval( ).................................................................................................................................................................................................................... plotting ............. 44...................................................................................................................................................................................................................................................................... 17...................................................................... 84 Simultaneous equations............................ 139 Outputs .................. 148 Simulation language = Programming language + Time flow .............................. 117 S Sample/hold model .................................................................................................................................................. 11 Plot data as input to a model ...................... 127 Programming language.................................................................................................................................................. 78 Plotting results ................. 10 Parsing................................... 113 Signal sources ..................................................................................... 59............................ 28............................................................... 10 State of a model.............................................................................................................................. 120 Polynomials of derivatives ...... 44 Results........... 6 R Random value functions ..................... plotting ................. 121.......................................................... 43............................ 42...................................... 45 Sources of signal .................................. 84 Pointlist functions ..... 72...................................... 6 Prototyping.................................................................................................................................... 143 predtime( ) .............. 55 Repetition control .................................................................. 55 Regular expressions ................... 100 Special expressions ......... 140 Pre-defined functions ............. 53...... 146 RECORD printout/plotting data .................. 83 P Parentheses '( )' ........... 59. 63 Post-processing existing plot data .......................................................................................................................................................................................................................................... 62 Square brackets '[ ]' ............................ 72...................................................................................................................................... 110......................... 78 Pre-defined constants and variables.............................................. 24.......... 84 RMS value ..... 32............................................... 152 predval( )... 4 Simulation results.............................. 100 Simulation directives ...

.................................................................................... 115 U USE ITERATE .......................................................... 106 Thevenin type-94 circuit component .................................................................. 6............................................................................................... 73 USE statements ...................... 72.. 66.............................................. 32... 123 Value-holding elements ..... 55 Statement functions ....................... 55 Values............................ 6...................................................................................... 6 Windup and no-windup limits .............. 127 Writing a model ..................... 55 W WHILE statements ........... 52........................................................................................ 37 write().................................... 11................................................................... 87....... 6......... 60 Steady-state circuit initialization ........................................................................................................ 55 Z Z transfer functions .................................................................................................................................. 13 Writing expressions............ write2() .........................................................................159 Statement function arguments .................................................................................................................................. 76 V Value assignment ................ 9 Variables ............................ 17 sum( )............ 71.............................. 37................................................................................................................................................................................................................................................. 97 Submodels ......... 126 White space .................................... 125 USERS GUIDE TO MODELS IN ATP ............ 23................................................. 62 Syntax of the MODELS language ........................ 113 Tracking min/max....................................... 123 Static limits........... 13.............................................................................................................................. 118 T TACS ..................... 16............ 91 Time step ....... 53.......................................................................... 42....................................................................................... 90 Using MODELS in ATP........ 120 Statements.............................. 141 Track/hold model .................................... 122.............................................................. 32.... 128................................................ 127 Using a model ................................... 80 TACS devices .............. write1().............................................................. 140 Variables of the MODELS section................................................................. 33...... 84 Visibility of value-holding elements .............. 5... 71...... 87 Why use MODELS....... 2...............................................................

models of the TACS devices 60+ examples illustrating various MODELS features 20+ examples of type-94 circuit components using MODELS examp..edu in directory pub/atp/models ftp. A4 format the Language Manual of MODELS in WordPerfect 5. including: .zip typ94. 8.ee.zip The author of MODELS and of this document can be reached as follows: Laurent Dubé DEI 7000 Rowan Road Neskowin.mtu. for example 964. A4 format technical notes on MODELS libraries of models and functions. Oregon USA 97149 tel: +1-503-392-4551 fax: +1-503-392-4575 email: dube@peak.zip techn.5x11 format the Language Manual of MODELS in WordPerfect 5.0.1.zip libs.0.zip lma4w.1.zip lma4p.160 IN CLOSING .zip this Users Guide of MODELS in ATP in Word for Windows 2. 8. Further information on the use of MODELS in ATP can be obtained by anonymous ftp from the following two addresses: ftp.0.org USERS GUIDE TO MODELS IN ATP .5x11 format the Language Manual of MODELS in Word for Windows 2.de in directory pub/special/atp/models The available material includes the following files. A4 format the Language Manual of MODELS in Word for Windows 2.zip ugma4.0.signal sources .zip lmusw.zip lmusp. Some of these file names are preceded by a three-digit number.rrzn. 8.complex-value functions .5x11 format this Users Guide of MODELS in ATP in Word for Windows 2.. indicating the year and month of the file: ugmus.uni-hannover.