Baixe o app para aproveitar ainda mais
Prévia do material em texto
USERS GUIDE TO MODELS IN ATP April 1996 i USERS GUIDE TO MODELS IN ATP 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. i USERS GUIDE TO MODELS IN ATP 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. i USERS GUIDE TO MODELS IN ATP OUTLINE Acknowledgments Preface Outline Contents Introduction 1. Basic aspects of the MODELS language 2. Writing a model 3. Writing expressions 4. Specifying simulation directives 5. Using a model 6. Using MODELS in ATP 7. 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 ... i USERS GUIDE TO MODELS IN ATP CONTENTS Acknowledgments ..................................................................................................i Preface.................................................................................................................. ii Outline.................................................................................................................. iii Contents............................................................................................................... iv Introduction ...........................................................................................................1 1. Basic aspects of the MODELS language .........................................................2 1.1. Why use MODELS....................................................................................2 1.1.1. MODELS in ATP................................................................................2 1.1.2. Starting to use MODELS ...................................................................2 1.1.3. Overall form .......................................................................................3 1.1.4. Similar to a programming language ...................................................3 1.1.5. What's particular to MODELS ............................................................4 1.1.6. What about TACS?............................................................................5 1.1.7. Reasons for using MODELS in a project ...........................................6 1.2. Value-holding elements, and values .........................................................6 1.2.1. Kinds of value-holding elements ........................................................6 1.2.2. Scalars and arrays.............................................................................7 1.2.3. Use of arrays .....................................................................................8 1.2.4. Representation of numbers ...............................................................9 1.2.5. Limits .................................................................................................9 1.3. Notation, format, and conventions ............................................................9 1.3.1. Model, MODELS, and MODEL ..........................................................9 1.3.2. Equal sign and assignment sign ......................................................10 1.3.3. Parentheses, brackets, and braces .................................................10 1.3.4. Blank lines .......................................................................................11 1.3.5. Names .............................................................................................11 1.3.6. Delimiters.........................................................................................11 1.3.7. Comments .......................................................................................12 1.3.8. Line indentation ...............................................................................12 2. Writing a model ..............................................................................................13 2.1. Defining the value-holding elements .......................................................13 2.1.1. Defining constant elements..............................................................13 2.1.2. Defining data elements ....................................................................14 2.1.2.1. Using a data value as an array dimension................................14 2.1.2.2. Dependent data values.............................................................14 2.1.3. Defining input elements ...................................................................15 2.1.4. Defining variable elements...............................................................16 2.1.5. Defining output elements .................................................................17 2.2. Defining the submodels...........................................................................17 2.2.1. Locally-defined submodels ..............................................................18 2.2.2. Foreign submodels ..........................................................................19 2.2.3. External submodels .........................................................................21 2.3. Defining the functions..............................................................................23 2.3.1. Statement functions .........................................................................23 i USERS GUIDE TO MODELS IN ATP 2.3.2. Pointlist functions.............................................................................24 2.3.2.1. External point list ......................................................................25 2.3.3. Foreign functions .............................................................................26 2.4. Writing the procedures............................................................................282.4.1. The EXEC procedure.......................................................................28 2.4.2. The INIT procedure..........................................................................28 2.4.2.1. Executing both INIT and EXEC at time zero.............................29 2.4.2.2. INIT procedure and HISTORY assignment ..............................29 2.4.3. Named procedures ..........................................................................30 2.5. Writing the statements of a procedure ....................................................32 2.5.1. Value assignment statement............................................................32 2.5.2. Differential equation, Laplace and z transfer functions ....................33 2.5.2.1. Numerical solution ....................................................................34 2.5.2.2. Initialization...............................................................................36 2.5.2.3. Values of y at t0........................................................................37 2.5.2.4. Using CDIFFEQ, CLAPLACE, and CZFUN..............................37 2.5.2.5. Limits ........................................................................................37 2.5.3. Integral value assignment ................................................................38 2.5.4. History expression assignment ........................................................39 2.5.5. IF statement.....................................................................................40 2.5.5.1. Explicit IF statement .................................................................40 2.5.5.2. Implicit IF statement .................................................................41 2.5.6. WHILE statement.............................................................................42 2.5.7. FOR statement ................................................................................43 2.5.8. DO statement...................................................................................44 2.5.9. REDO statement..............................................................................45 2.5.10. COMBINE statement .....................................................................45 2.5.10.1. Using the linear COMBINE for linear equations......................46 2.5.10.2. Using the iterated COMBINE for nonlinear equations ............49 2.5.10.3. Using the linear COMBINE for nonlinear equations................50 2.5.11. ERROR statement .........................................................................51 2.5.12. USE statement...............................................................................52 2.5.13. Call to a procedure ........................................................................53 2.5.14. Call to a pre-defined procedure .....................................................53 2.5.14.1. WRITE() procedure ................................................................53 2.5.14.2. WRITE1(), WRITE2() procedure ............................................54 3. Writing expressions ........................................................................................55 3.1. Regular expressions ...............................................................................55 3.1.1. Referring to a named value-holding element ...................................55 3.1.2. Specifying a numerical value ...........................................................58 3.1.3. Using a value calculated by a function.............................................58 3.1.4. Using a value calculated by a procedure .........................................59 3.1.5. Logical and numerical operators......................................................59 3.1.6. Limits on a regular expression .........................................................60 3.1.7. Using expressions with arrays .........................................................61 3.2. Special expressions ................................................................................62 3.2.1. Linear sum.......................................................................................62 i USERS GUIDE TO MODELS IN ATP 3.2.2. Polynomial of derivatives .................................................................63 3.2.3. Integral expression ..........................................................................63 4. 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 5. 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 6. 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 7. Libraries of models and functions.................................................................100 7.1. Signal sources ......................................................................................100 7.1.1. Examples of some common sources .............................................1017.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 i USERS GUIDE TO MODELS IN ATP 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 i USERS GUIDE TO MODELS IN ATP 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 1 USERS GUIDE TO MODELS IN ATP INTRODUCTION This manual starts with a discussion of the basic aspects of the MODELS language, providing a general presentation of what the language does, what is special about the language, and the nuts and bolts of its rules and conventions. This is followed by a more in-depth look at the process of writing a model, writing expressions, and specifying simulation directives in a model. Various aspects of using a model are discussed next. This is then followed by a detailed presentation about using MODELS in ATP. It includes an explanation of the different declarations that can be included in the MODELS section. It also describes the different ways in which MODELS is interfaced with ATP, and how each approach can be used in the simulation of a circuit. 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. Four sections are added as appendices to this manual. They are built for use as a quick reference to the MODELS language. The first is a summary reference to the syntax ofthe MODELS language. It condenses the contents of the Language Manual, presenting only the structure and the diagrams, without the text. Next comes a summary of that summary, providing a structured overview of only the keywords of the MODELS language, without the details of the full syntax rules. The other two appendices show the pre-defined constants and variables, and the pre-defined functions of MODELS, with discussions and examples. 2 USERS GUIDE TO MODELS IN ATP 1. BASIC ASPECTS OF THE MODELS LANGUAGE MODELS is a general technical description language supported by a simulation solver. It is a programming language targeted to time-domain simulation, and is used as a tool for describing the dynamic behavior of complex physical systems. In ATP, it can be used for describing the operation of circuit components and of control components. It can also be used for generating signals or for analyzing measurements from the circuit. Finally, it can be used as the interface between ATP and outside programs. 1.1. Why use MODELS 1.1.1. 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; 2) to have the flexibility of a full programming language without having to interact with ATP at the programming level; 3) to be able to describe not only how a component operates, but also how the initial state (initial values and initial history) of the component is established, at any required detail level; 4) to have a standard program interface to ATP defined at the modeling level in terms of voltages, currents, and control signals, as opposed to an interface which would be defined at the programming level in terms of the variables, common blocks, and subroutines of ATP; this makes it possible to connect external programs to ATP for modeling of components, access to measurements, or interaction with equipment, without requiring a programming knowledge of the internal operation of ATP, and without requiring any modification to be made to the source code of ATP. 1.1.2. Starting to use MODELS Looking at the MODELS language for the first time can feel like a large task. With some guidance at the beginning, it can be easily divided into simple parts. Starting with examples provides an easy exposure to the main aspects of the language as well as, later on, to the finer details of its syntax. Many examples are provided with this guide, and can be used as a base from which modifications can be made to describe more complex operations. 3 USERS GUIDE TO MODELS IN ATP 1.1.3. Overall form The structure of the language is simple, and is similar to the structure of other programming languages, for example, Pascal or Modula-2. It has a small number of keywords that can be remembered easily. There are no formatting rules to complicate its use, and every construct is introduced by a descriptive keyword. The basic module is called a model. A model consists of procedures describing how the model operates, value-holding elements to carry the state and the history of its operation and to exchange information with the outside, and directives influencing the operation of the model in a simulation. Value-holding elements can be constant or variable, 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). Two standard procedures can be defined for each model. The initialization procedure (INIT) describes the initial point of operation of the model before the simulation is started. The execution procedure (EXEC) describes how the operation of the model is updated at each successive instant of the simulation. Additional procedures can be defined for describing other actions of the model and to access the value of specific variables of the model. The simulation directives include control of the size of the time step used in the model, choice of interpolation method for determining input values at internal sub- steps, assignment of history expressions describing the pre-simulation values of some of the variables of the model, and allocation of special storage required for the past values of variables referenced in the model using a delay() function. A model is defined independently from the directives and location of where it will be used. Multiple instances of the same model can be used, each maintaining its individual operating point and history. 1.1.4. 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. Users who more occasionally apply the language to represent a component or a numerical process, for example, need the language to be simple, so that it may be used and read with familiarity. Using a programming language approach seemed to fill both types of needs. In this regard, MODELS includes the following capabilities: - a regular syntax for the use of variables, arrays, expressions, and functions; - the use of various types of variables, holding values modified by the procedures of the model; variables can be numerical and logical, in either scalar or array form; 4 USERS GUIDE TO MODELS IN ATP - a set of pre-defined numerical and logical functions; additional functions can be defined by the user, in the form of parametrized expressions, point lists, and externally-programmed functions; - the use of conditions and loops (if, while, for, etc.) for structuring the execution flow of a procedure; - the use of comments within a description, as an aid to producing models and procedures that are self-documenting; - the use of arbitrarily-long names to facilitate self-documentation; - an individual naming scope for each model, to allow the user to assign meaningful names to the variables used in a description, without the risk of conflicting with names chosen in other parts of the simulation; - separation of the description of a model, from its use in a simulation; - the use of multiple instances of the same component, each possibly supplied with different parameters, different inputs, or different simulation directives; - a mechanism for dividing a large component description into smaller units, for reduced model complexity, explicit identification of interfaces and operation, easier testing, and use of prototyping during model development; - the possibility to specify operations that are executed only when some conditions are met, for example for initialization, or when simulation difficulties or errors are detected. 1.1.5. What's particular to MODELS Two aspects differentiate MODELS from a regular programming language. One aspect is the set of operations and functions needed for the representation of systems that vary in time: - time automatically increases during a simulation; - individual instances of the models of a system automatically update their operation according to the increasing value of the simulation time; - the values of the variables are persistent over successive instants of time, and maintain their value during the simulation until assigned a different value; - expressions can be described as generic functions of the time "t", allowing a clear symbolic representation; an example would be referring to the time value of an oscillating signal by simply using A*sin(omega*t), with A and omega being defined elsewhere in the model; this expression automatically takes on the appropriate value at different times of the simulation; - a number of pre-defined time-based functions are available, including time integrals, time derivatives, time differential equations, Laplace and z transfer functions, and references to past and predicted values of avariable. 5 USERS GUIDE TO MODELS IN ATP The other aspect is that MODELS automatically manages the storage and retrieval of the history values of the variables of a model, as needed during the execution of the simulation. The time-based functions of the language all have direct access to the past values of a variable, as needed for the calculations, without imposing on the user the task of specifying how that information is stored and accessed. 1.1.6. What about TACS? TACS had been designed to represent mostly-linear control systems described in the form of a block diagram. TACS allows the user to assemble a description of a control system using a set of pre-defined function blocks and devices. However, it was not designed to accommodate operations represented by algorithms, although we can achieve some measure of conditional assignments by using type-60 and type-61 devices. TACS doesn't provide a mechanism to solve sets of nonlinear simultaneous equations. 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. Depending on the size of the time step and on the nature of the simulated system, the consequences of this approach can range from satisfactory to numerically unstable. The interface between TACS and the simulated circuit is a unidirectional information-type interface, passing measured values from the circuit to TACS, and control variables from TACS to the circuit. No iteration mechanism is provided. At each time step, the circuit is first solved completely, measured values are passed to TACS, then TACS is solved and its outputs applied to the circuit at the next time step of the simulation. Again, depending on the size of the time step and on the nature of the simulated system, this arrangement ranges from satisfactory to numerically unstable. When TACS is used for representing control system components, this delay provides satisfactory results, as control devices always involve an element of delay in their operation in the real systems. Similarly, it is possible to control the value of an impedance in the circuit without adverse effects due to the delay (for example, representing an arc by controlling the value of a resistance). However, 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, unless the injected currents or voltages are strictly history values calculated from a past state of the simulation, as in the case of using a Norton equivalent to represent an inductance using bilinear transformation. Finally, in contrast with TACS, the user is not limited to a pre-defined set of components, but can build libraries of components and submodels as required by different applications. 6 USERS GUIDE TO MODELS IN ATP 1.1.7. Reasons for using MODELS in a project Here are some of the reasons why it may be beneficial to use MODELS in a project: - when we need to do incremental development of the various parts of the simulated system, prototyping individual elements as we go; - when we need to include multiple or detailed aspect of the operation of some of the elements of the system, for example representing the thermodynamic behavior in conjunction with the electrical behavior; - 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; an example might be using a model supplied by the manufacturer of a particular element; - when we have to develop from scratch the modeling of some of the components of the system, in the case that they could not be easily represented by using what's already available in ATP; we can do some of this in TACS, but MODELS provides a full algorithmic description language that can simplify the work; - when we need a component to be solved simultaneously with the rest of the circuit, avoiding the one-step delay otherwise imposed by TACS. 1.2. Value-holding elements, and values 1.2.1. Kinds of value-holding elements If we sort the types of value-holding elements according to the value held by each named element, we have: - for values global to a simulation (i.e. to all model instances of all models): - global variables: t, starttime, stoptime, startstep - global numerical constants: pi, inf, undefined - global logical constants: false, no, open, off true, yes, closed, on - for values global to all instances of one model: - constants - for values local to each instance of a model: - data, inputs, variables, resident variables If we look at the value-holding elements in terms of where we specify the expressions used for calculating their value, we can note the difference between model definition and model use: 7 USERS GUIDE TO MODELS IN ATP - in expressions global to all instances of a model, specified in the model definition: - value expression of constants - default expression of data - default expression of inputs - all value assignment expressions of variables - in expressions local to each instance of a model, specified in the USE statement: - use expression of data - use expression of inputs If we look at the value-holding elements in terms of where they are visible, we can see the difference between names that are private to a model, and names that are visible outside the model where they are declared: Type Access Where value is specified constant private model definition data public default value in model definition local value in use instance variable private model definition input public default value in model definition local value in use instance output public local value in use instance The naming of the types is not perfect, in the sense that data are as constant as the constants, and inputs are certainly as variable as the 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. 1.2.2. Scalars and arrays Value-holding elements in a model can be declared as individually-named scalar elements: DATA d1, d2, d3 VAR y10, y11, y12 or as elements grouped in array form: DATA d[1..3] VAR y[10..12] The elements of an array can be declared using an index range: 8 USERS GUIDE TO MODELS IN ATP DATA d[1..3] or individually (useful for inserting separate comments for each): DATA d[1] -- some descriptive comment d[2] -- ... d[2] -- ... After being declared, 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, inside array-value expressions: y[10..12] := d[1..3] + k[5..7] 1.2.3. Use of arrays Array elements can be grouped by range inside numerical and logical equations: vbr[1..3] := vk[1..3] -vm[1..3] gate[1..6] := fire[1..6] AND flag>0 as well as when specifying function arguments: wabs[1..6] := abs(w[1..6]) In the few circumstances where a group of array elements cannot be used as a range, for example on the left side of a Laplace assignment, it is still possible to use an indexed array notation inside a FOR structure, 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, and also contributes to reducing the execution time of the simulation. 1.2.4. Representation of numbers All quantities inside a MODELS simulation are represented as double-precision floating point numbers. Some observations follow: - the value of a Boolean operation or conversion is 0.0 or 1.0 in double- precision (note that in MODELS, numerical operators can be applied to Booleanvalues and vice versa); 9 USERS GUIDE TO MODELS IN ATP - when used as index to an array, the result of an expression is internally rounded to the nearest integer; - both rounding and truncation can be forced inside an expression using the functions round() and trunc(); - all operations involving some kind of value comparison automatically include a round-off multiplier of 10-8, which means that the granularity of any point value is 10-8 times its value, to the left and to the right, anywhere on the number line. Examples, where margin = b times 10-8 : a > b is calculated as a > b+margin a = b is calculated as a >= b-margin AND a <= b+margin a >= 0 is calculated as a >= 0 (because margin=0) 1.2.5. Limits Values are specified in expressions. In addition, each expression can be qualified by a minimum value and a maximum value. These limits are themselves described using an expression which may vary in value during a simulation. Limits are discussed in more detail below, in the sections on COMBINE, differential equations and transfer functions, integrals, and expressions. a := 3*b -c {min: amin, max: amax} y := integral(x) {dmax: 3*a} laplace(y/x) := (s_numerator)/(s_denominator) {dmin: ymin*cos(omega*t)} 1.3. Notation, format, and conventions 1.3.1. Model, MODELS, and MODEL When referring to the MODELS language, we use all upper case characters for the word. When referring to a model description written in the MODELS language, we use the word model written in regular lower case. The upper case singular form MODEL is the keyword that starts a model description. 1.3.2. Equal sign and assignment sign A distinction is made in the MODELS language between value assignment and value equality. Value assignment is identified by the assignment operator ":=". Value assignment is an action. When a value is assigned to a named value-holding element, the assignment operation is expressed using ":=", for example: 10 USERS GUIDE TO MODELS IN ATP 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. It is used as a logical relation in a logical expression, for example: IF a = b THEN ... ENDIF 1.3.3. Parentheses, brackets, and braces The left and right parenthesis characters "(" and ")" are used to enclose the arguments of a function. In this case, the left parenthesis must immediately follow the function name, without any space. For example: y := delay(x1, 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. In this case, the left bracket must immediately follow the function name, without any space. They can be used with an array name to identify elements of that array: wabs[1..n] := abs(w[1..n]) The brackets can also be used by themselves inside an expression to indicate a grouping of values into an array value: vpp[1..3] := [va-vb, vb-vc, vc-va] The left and right brace characters "{" and "}" are used to identify some attribute, like default value, limit value, type, argument count, etc. For example: INPUT va { v(NODEA) } CONST twopi { val: 2*pi } DATA freq { dflt: 50 } FUNCTION windspeed FOREIGN { ixarg: 2 } 11 USERS GUIDE TO MODELS IN ATP 1.3.4. Blank lines MODELS has its own syntax rules, separate from ATP. Among other things, it allows the insertion of white space anywhere in the MODELS section, including blank lines and tabs. So, for example, there is no need to start blank lines in the MODELS section with "C ", necessary for indicating comment lines in the rest of ATP. 1.3.5. Names Names can be composed using any combination of letters, digits, and the underscore character "_", with the restriction that a name must start with a letter. Names are not case-sensitive. Upper and lower case can be used for readability, but not for distinguishing two names of the same spelling. Keywords of the language are typically written in capitals for readability, but this is not necessary for interpretation by the parser. Hyphens are not permitted inside a name, and will be interpreted as a minus sign. 1.3.6. Delimiters From a parsing point-of-view, all constructs of the language are self-delimiting. This means that some kind of end delimiter indicates where a construct ends, whether implicitly or explicitly. An implicit delimiter is what is used for indicating the end of a name, keyword, operator, or value. For example, names terminate at the first character that is not a recognized name character, and values terminate at the first character that is not a legal value character. Explicit end delimiters are keywords that indicate the end of a construct, for example, ENDMODEL or ENDIF. 1.3.7. Comments Two aspects contribute to making a model understandable. The first is to choose names that are appropriately descriptive of the value or function they are representing. The other is the liberal use of in-line comments and block comments. An in-line comment starts with a string of two or more hyphens, and automatically terminates at the end of the line. A block comment is a block of text starting with the keyword COMMENT and ending with the keyword ENDCOMMENT. This can be used to annotate a model, or to temporarily block out a part during model development or testing. 12 USERS GUIDE TO MODELS IN ATP MODEL m1 comment --------------------------------------------------- | This is a block comment describing this model | | (the vertical bars and the hyphens are only decorative) | ------------------------------------------------ endcomment VAR a -- this is an in-line comment describing this variable 1.3.8. Line indentation Line indentation in the form of tab or space characters can be used to increase the readability of a model description. There are no pre-defined formatting rules imposed by the language. Indentation rules are therefore a matter of arbitrary style. 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. 13 USERS GUIDE TO MODELS IN ATP 2. WRITING A MODEL This section introduces the elements used when building a model description of something. The dynamic operation of a model is represented by the named elements that hold the values used in and created by the model (constants, data, inputs, variables, and outputs), and by a description of how these values are calculated and used. Procedures contain the statements where these values are used and assigned. Various types of statements are available for representing how a value is calculated and assigned. Submodels and functions can also be defined to carry out some of the calculation of these values. The use of each model and submodel can be customized for each use instance, by means of simulation directives specified in the model definition and in the USE statements introducing each instance. 2.1. Defining the value-holding elements Each model can contain any number of value-holding elements, identified by type, name, and, if an array, range of array indices. The type, name, and range of these elements must first be declared in a model before they can be used. These declarations are grouped in a model by type: constant, data, input, output, variables. In summary, the names of data and inputs are public (although they can be assigned private default expression). The names of constants and variables are private (can't be referenced in the USE statement). The value of a constant or data is constant in time.The value of a variable or input can vary in time. 2.1.1. Defining constant elements Constants are used for holding values that are defined inside the model, and that do not vary during the simulation. The names of the CONST elements are only visible inside the model where they are declared. Their value is assigned inside the model, in the declaration. The same value is used in all use instances of the model. CONST twopi {val: 2*pi} CONST power_of_2[0..8] {val: [1,2,4,8,16,32,64,128,256]} There is a set of constants that have pre-defined names and values. They can be used without needing to be declared: 14 USERS GUIDE TO MODELS IN ATP - pre-defined numerical constants: - pi 3.14159... - inf a large value, typically 1020 - undefined the special value 88888.88888 - pre-defined logical constants - false, no, open, off the value 0 true, yes, closed, on the value 1 2.1.2. Defining data elements Data are used for holding values that are defined outside the model, and that do not vary during the simulation. The names of the DATA elements are visible inside the model where they are declared, and also in the USE statements defining instances of the model. Their value is assigned in the USE statements. A default value can also be optionally assigned inside the model, in the declaration. When a default value exists for a data element, assigning that element a value in the USE statement is optional. Different values can be used in different use instances of the model. DATA n -- an array dimension used in the model DATA freq {dflt: 50} -- 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. Once assigned, DATA values do not vary in time. Their value is constant over the full length of a simulation. Data values are automatically calculated in the USE statement the first time the use instance is called. 2.1.2.1. 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. This can be useful for dimensioning an array to just the size needed in an application. DATA n -- a dimension assigned differently in each use instance INPUT vterm[1..n] -- a variably-dimensioned input VAR vtmax[1..n] -- a variably-dimensioned variable 2.1.2.2. 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. For example: DATA n -- an array dimension DATA n2 {dflt: n*n} -- another array dimension 15 USERS GUIDE TO MODELS IN ATP This is because it's inadvertently making public a name that is really private to the model. For array dimensions, this is unavoidable, and at best could be checked for consistency in the INIT procedure of the model. DATA n -- an array dimension DATA n2 {dflt: n*n} -- another array dimension ... INIT IF n2<>n*n THEN ERROR write('Some error message...') STOP ENDIF ... When the data is not needed as the dimension of an array, it's better practice to hide it to the outside by declaring it as a variable, and then assign its value in the INIT procedure in function of the data value it depends on. For example, instead of doing: DATA freq {dflt: 50} -- a frequency in Hz DATA omega {dflt: 2*pi*freq} -- the equivalent frequency in rad/sec it would be safer to use: DATA freq {dflt: 50} -- a frequency in Hz VAR omega -- the equivalent frequency in rad/sec ... INIT omega := 2*pi*freq ... 2.1.3. Defining input elements Inputs are used for holding values that are defined outside the model, and that vary during the simulation. The names of the INPUT elements are visible inside the model where they are declared, and also in the USE statements defining instances of the model. Their value is assigned in the USE statements. A default value can also be optionally assigned inside the model, in the declaration. When a default value exists for an input element, assigning that element a value in the USE statement is optional. Input values are automatically re-calculated in the USE statement each time the use instance is called. INPUT vterm[1..3] -- value of measured terminal voltages vref {dflt: 0} -- value of a reference voltage, =0 if not used Arrays of inputs can be variably dimensioned. The above example of a 3-terminal model can be replaced with a model designed for n terminals, with the value of n determined at simulation time as a data in the USE statement: DATA n -- number of terminals INPUT vterm[1..n] -- value of measured terminal voltages vref {dflt: 0} -- value of a reference voltage, =0 if not used 16 USERS GUIDE TO MODELS IN ATP 2.1.4. Defining variable elements Variables are used for holding values that are defined inside the model, and that vary during the simulation. The names of the VAR elements are only visible inside the model where they are declared, except when they are declared as OUTPUT (see section below). Their value can be assigned in any statement inside the model. Once assigned a value, a variable maintains that value during the simulation, until it is assigned a new value. To continue the previous example, one could track the input voltages for maximum amplitude for each terminal, let's say, and the maximum for all terminals. Let's define the variables vtmax[ ] and vmax: DATA n -- number of terminals INPUT vterm[1..n] -- value of measured terminal voltages vref {dflt: 0} -- value of a reference voltage, =0 if not used VAR vtmax[1..n] -- tracked maximum absolute value of each terminal voltage vmax -- tracked maximum absolute value of all terminal voltages To update the value of these variables during the simulation, statements describing how to do that can be included in the EXEC procedure of the model, with initialization in the INIT procedure, for example: INIT ... vtmax[1..n]:=0 -- initialize tracked maximum values vmax:=0 -- initialize overall tracked maximum value ... ENDINIT EXEC ... FOR i:=1 TO n DO -- for each terminal vtmax[i]:= max(vtmax[i], abs(vterm[i])) -- update tracked maximum ENDFOR vmax:= max(vmax, vtmax[1..n]) -- update overall tracked maximum ... ENDEXEC Various other ways of assigning values to variables are described in more detail in this manual, in the section on "Writing the statements of a procedure". 2.1.5. Defining output elements Variables can be declared as OUTPUT of a model. The names of variables declared as output are made visible to the USE statements defining instances of the model. No other variable is visible outside the model. Continuing the above example, the values of vtmax[ ] and vmax can be specified as output of the model, as shown here: 17 USERS GUIDE TO MODELS IN ATP DATA n -- number of terminals INPUT vterm[1..n] -- value of measured terminal voltages vref {dflt: 0} -- value of a reference voltage, =0 if not used VAR vtmax[1..n] -- tracked maximum absolute value of each terminal voltage vmax -- tracked maximum absolute value of all terminal voltages OUTPUT vtmax[1..n], vmax -- can be used as outputs of the model 2.2. Defining the submodels As mentioned before, the dynamic operation of a model is represented by the named elements that hold the values used in and created by the model, and by a description of how these values are calculated and used. This representation can be decomposed into a hierarchy of models, each holding the description of a specific aspect of what is being modeled.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. For a given set of arguments, it calculates and returns a set of values, without maintaining any trace of previous calls to the function, without holding any state to be used by future calls to the function, and without modifying the state of the model in which it is defined. A procedure expresses how something is done, modifying and making reference to values held in the model. A model has both value holders, to represent the state of operation of what is modeled, and procedures, to act on that state. A model maintains its own memory storage of values for each instance in which it's used. Functions don't need that kind of storage, as there is nothing to store between calls. Procedures use the existing storage of the model where they are defined. When used as a submodel inside another model, a model can be written in the MODELS language, with its description inserted locally in the declarations of the calling model. This is the locally-defined submodel. A model can also be a separate program, written in any language, and accessed through the programming interface of MODELS. This is a foreign submodel. A local or foreign model can possibly be described outside the calling model where it is used. This is declared in the calling model as an external submodel. 2.2.1. Locally-defined submodels This is the standard way of introducing a submodel. A submodel is a full model of its own, except for the fact that it is declared and used inside another model. Once it is declared, it can be used in that model in as many use instances as required, each one maintaining its own separate state of operation. 18 USERS GUIDE TO MODELS IN ATP MODEL component -- defining a model CONST ... DATA ... INPUT ... VAR ... OUTPUT ... MODEL controller -- defining a local submodel CONST ... DATA ... ... ENDMODEL ... EXEC ... USE controller AS control_1 -- using the submodel ... ENDUSE ... ENDEXEC ENDMODEL An alternate way, that is still a locally-defined submodel, is to replace the actual description of the submodel by a reference to the file containing that description. The above example could be rewritten as: MODEL component -- defining a model CONST ... DATA ... ... $INCLUDE filename { inserting a local submodel (notice the ATP formatting) ... EXEC ... USE controller AS control_1 -- using the submodel ... ENDUSE ... ENDEXEC ENDMODEL The $INCLUDE directive is an ATP command used for accessing the contents of other files. It's a formatted command, and must start in column 1 of a new line. 2.2.2. Foreign submodels MODELS has a simple interface for accessing other programs that can be used as submodels or functions inside a model. A program accessed as a model has to meet the following requirements: - its call arguments are pointers to four arrays - it has two separate entry points, one for initialization, and one for execution The four arrays hold values of data, inputs, outputs, and stored variables. The data, inputs, and outputs correspond to the regular data, inputs, and outputs of a model. The array of stored variables is a service of MODELS, to hold internal values of the program between calls, 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. 19 USERS GUIDE TO MODELS IN ATP The two entry points correspond to the INIT and EXEC procedures of a model. The initialization routine is called only when an instance of the model is used for the first time. The execution routine is called when the state of the model is to be updated according to new conditions. The declaration of the foreign model indicates the local name identifying that submodel in the calling model, the foreign name of the model, and the length of each of the four arrays. MODEL component -- defining a model CONST ... DATA ... ... MODEL controller FOREIGN control_program {ixdata:3, ixin:2*n+4, ixout:n, ixvar:5} ... EXEC ... USE controller AS control_1 -- using the submodel ... ENDUSE ... ENDEXEC ENDMODEL In the above example, the local name is "controller", and the foreign name is "control_program". That foreign name is not necessarily the name of the foreign program itself. It is a unique identifier used in the subroutine "fgnmod" of MODELS, to recognize which foreign model is being called. It is inside that subroutine that the actual call to the foreign program is made. That subroutine needs to be edited when installing calls to new foreign programs. That subroutine is fully documented with comments, and should present no difficulty when used. Part of that subroutine is shown below, showing how the identifier "controller" of the previous example would be used: 20 USERS GUIDE TO MODELS IN ATP SUBROUTINE FGNMOD ( name, namlen, xdata, xin, xout, xvar, 1 iniflg, ierflg) IMPLICIT REAL*8 (A-H, O-Z), INTEGER*4 (I-N) DIMENSION xdata(*), xin(*), xout(*), xvar(*) ... C In the following lines, register the foreign model names C as declared in the models: DATA refnam(1) / 'SAMPLE_MODEL' / ! Example "ftnmodel.dat" DATA refnam(2) / 'SAMPLE_C_MODEL' / ! Example "cmodel.dat" DATA refnam(3) / 'CONTROLLER' / ! Added for this example DATA refnam(4) / ' ' / ... C The following lines call the actual foreign subroutines/procedures: C - actual names may be different from the foreign C names used in the models C - notice how each one uses both an initialization routine C and an execution routine IF ( iname.EQ.1 ) THEN ! "sample_model" IF (iniflg.EQ.1) THEN CALL sampli(xdata, xin, xout, xvar) ELSE CALL samplm(xdata, xin, xout, xvar) ENDIF CONTINUE ! ------------------------------------------- ELSE IF ( iname.EQ.2 ) THEN ! "sample_c_model" IF (iniflg.EQ.1) THEN CALL c_sample_i(xdata, xin, xout, xvar) ELSE CALL c_sample_m(xdata, xin, xout, xvar) ENDIF CONTINUE ! ------------------------------------------- ELSE IF ( iname.EQ.3 ) THEN ! "controller" IF (iniflg.EQ.1) THEN CALL contri(xdata, xin, xout, xvar) ELSE CALL contrm(xdata, xin, xout, xvar) ENDIF CONTINUE ! ------------------------------------------- ELSE IF ( iname.EQ.4 ) THEN ... It is when actually using the foreign model that the contents of the data, input, and output arrays is identified. Just like when using a local model, it is possible to specify how data, input, and history values are calculated. One difference is that the value of the local simulation time must be explicitly passed to the foreign program as one of the inputs. It's not done "magically" in the background. Outputs of the foreign model are used just like those of a local model. The contents of the array of variables is specified and managed inside the called program, not in the USE statement. However, it is possible to assign initial values to these variables using HISTORY directives, just like in a regular USE statement. Note that only initial values are passed to the foreign program, not full history expressions available only for regular models. The following example illustrates the definition and the use of a simple foreign model. Note that the four arrays have the pre-defined names "xdata", "xin", "xout", and "xvar": 21 USERS GUIDE TO MODELS IN ATP DATA n VAR a[1..n] ... MODEL ftnmodel FOREIGN sample_model {ixdata:1, ixin:n,ixout:n, ixvar:n} ... EXEC ... USE ftnmodel AS ftnmodel DATA xdata[1]:=n -- set value of xdata[1] INPUT xin[1..n]:= ... -- load inputs xin[1..n] HISTORY xvar[1..n]:=0 -- set history of xvar[1..n] OUTPUT a[1..n]:=xout[1..n] -- use outputs xout[1..n] ENDUSE ... The foreign program, in this case, is a Fortran subroutine that writes some text and updates the values of the outputs, without using the value of time (which is thus not passed as an input): SUBROUTINE samplm(xdata, xin, xout, xvar) DIMENSION xdata(*), xin(*), xout(*), xvar(*) CHARACTER*80 text80 ! Buffer used to assemble messages for output text80 = 'Executing model "sample_model".' CALL OUTSIX( text80, 80 ) ! Send text80 (arg 1) to ATP listing DO 1000 i=1,xdata(1) xvar(i)=(2*xvar(i)+xin(i))/2 xout(i)=xvar(i)+100.0 1000 CONTINUE RETURN ENTRY sampli(xdata, xin, xout, xvar) text80 = 'Initializing model "sample_model".' CALL OUTSIX( text80, 80 ) RETURN END In the example, "xdata[1]" holds the dimension of the other three arrays, "xin" holds input values received from the calling model, "xout" holds output values sent back to the calling model, "xvar" holds state values stored in memory by MODELS between calls. Note how xvar is referenced before a new value is assigned to it, requiring a reference to the initial value of xvar at the first execution of the subroutine. 2.2.3. External submodels If a submodel is used in a model, but defined somewhere else, it can be introduced in the calling model as "external". It needs to be declared in the calling model, but the declaration can be as simple as mentioning the model's name and saying it's external, like this: 22 USERS GUIDE TO MODELS IN ATP MODEL component -- defining a model CONST ... DATA ... ... MODEL controller EXTERNAL ... EXEC ... USE controller AS control_1 -- using the submodel ... ENDUSE ... ENDEXEC ENDMODEL The full definition of the external model can be placed anywhere at the same level of the calling model or above. For the previous example, it could be found either at the same level of the "component" model as a locally-defined model: MODEL component -- defining a model ... MODEL controller EXTERNAL ... ENDMODEL MODEL controller CONST ... DATA ... ... ENDMODEL or at the same level as a foreign model: MODEL component -- defining a model ... MODEL controller EXTERNAL ... ENDMODEL MODEL controller FOREIGN control_program {ixdata:3, ixin:2*n+4, ixout:n, ixvar:5} ... or at a higher level: MODEL system MODEL sub_system_1 MODEL component -- defining a model ... MODEL controller EXTERNAL ... ENDMODEL ... ENDMODEL MODEL sub_system_2 ... ENDMODEL MODEL controller ... ... ENDMODEL or at the same level or above, as part of a library of models: 23 USERS GUIDE TO MODELS IN ATP MODEL component -- defining a model ... MODEL controller EXTERNAL ... ENDMODEL $INCLUDE filename { a file holding a library of models ... 2.3. Defining the functions A function operates like an expression. When it is called, it uses the existing values of all the named references used in the function, 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 value- holding elements of a model. However, as compared to a procedure, a function cannot modify any value other than the result it is returning. As compared to a model, a function does not have internal variables that can retain values between calls, that is, a function doesn't carry a state. A function can return a single value, or a list of values in the form of an array. Array-returning functions can be used inside expressions that use array arithmetic. In addition to the pre-defined functions supplied by MODELS, three types of custom functions can be defined in a model. Statements functions are simply re- usable named expressions. Point list functions express a relation between input and output in terms of (x, y) coordinates. Foreign functions are functions that are defined in a separate program and accessed through the programming interface of MODELS. 2.3.1. Statement functions Statement functions are defined inside a model in the form: FUNCTION somename(argname1, argname2, ... ) := expression These functions are macro-expressions that can be used in other expressions of a model. The function's expression can be a single-value expression or an expression returning an array of values. That expression can contain references to the named arguments of the function, as well as to any value-holding element of the model. The function is used by indicating the name of the function, and by providing a list of values used by the arguments of the function: somename(value1, value2, ... ) 24 USERS GUIDE TO MODELS IN ATP The form under which the list of values is provided is flexible, and can be a mixture of single values and of ranges of array elements, using expressions and array expressions, for example: somename(expr, array_expr, ... ) An example of this would be a two-argument function used for calculating the amplitude of a complex number, given its real and imaginary part. The arguments can be supplied as a list of two separate values, like this: FUNCTION c_ampl(real, imag) := sqrt(real*real +imag*imag) ... ym := c_ampl(xr, xi) or can be supplied as an array of two values, with the array, in this case, being a representation of the real and imaginary part of a complex number: VAR cx[1..2] -- a complex variable as real and imaginary FUNCTION c_ampl(real, imag) := sqrt(real*real +imag*imag) ... ym := c_ampl(cx[1..2]) Refer to the section on "Using a function" for more examples. 2.3.2. Pointlist functions Pointlist functions are useful when data about a function is available in the form of a table. Pointlist functions are single-valued functions expressed as a list of coordinates in a 2-dimension plane, sorted in increasing value of the input coordinate. For example, a curve of resistance in function of temperature could be expressed as: FUNCTION temp_dep POINTLIST (-273, 1.e-6), (-60, 1.e-4), (0, 1.e2), etc... The first coordinate of each pair corresponds to the input value, and the second coordinate corresponds to the output value of the function. 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. Very complex functions can be assembled using this possiblilty. An interesting example is the description of a parametrized family of curves. A pointlist function specifies what curve the function will use for different values of a parameter "k". Each curve can in turn be described using an expression that contains a reference to another function of any type. The following example illustrates a simple 1-parameter family of curves. 25 USERS GUIDE TO MODELS IN ATP VAR a, k FUNCTION curve2(x) ... -- a statement function or a point list for k=2 FUNCTION curve4(x) ... -- a statement function or a point list for k=4 FUNCTION curve6(x) ... -- a statement function or a point list for k=6 FUNCTION f POINTLIST (2, curve1(a)) (4, curve2(a)) (6, curve3(a)) ... a:= some value -- used inside the function f(k) k:= 2.5 -- any value between 2 and 6 y:=f(k) In the above example, the family is reduced to a set of three representative curves. The pointlist function simply specifies which of these curves (themselves functions) will be used for the three representative parameter values2, 4, and 6. Interpolation is provided automatically. When the interpolation order is not specified, as in y:=f(2.5) in the above example, the interpolation is linear, that is, the function calculates the values of f(a) for k=2 and for k=4, and interpolates linearly between the two values to return a value for k=2.5 . The interpolation order can be specified as a second argument when using the function, and can be either 0, 1, or 2, (none, linear, quadratic), as shown in the section on "Using a function". 2.3.2.1. 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, possibly generated by another program. The formatting requirements are that each pair be enclosed in parentheses, with the enclosed coordinates separated by a comma. The pairs must be sorted in increasing value of the first coordinate, for example: (0,0) (1,2) (2,4) (3,6) etc... Using separate lines is not required, although a maximum line length of 80 characters is imposed by ATP. As everywhere else in a model, spacing characters are ignored. (0,0) (1,2) (2,4) (3,6) etc... Supposing that these coordinates are available in a file named "xy.lst", they could be included in a model as follows: FUNCTION xyfun POINTLIST -- with data points located in the following file: $INCLUDE xy.lst 26 USERS GUIDE TO MODELS IN ATP 2.3.3. Foreign functions Foreign functions are functions written in any language and linked to ATP before execution. The function call is handled by the programming interface of MODELS. A foreign procedure accessed as a function must meet the following requirements: - it has one function argument that is a pointer to an 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. The declaration of the foreign function in a model indicates the local name identifying that function in the calling model, the foreign name of the function, and the length of the argument array. MODEL component VAR speed[1..2] -- velocity [m/s] and direction [deg] ... FUNCTION windspeed FOREIGN wind_speed {ixarg: 2} ... EXEC ... speed[1..2] := windspeed(t) ... ENDEXEC ENDMODEL In the above example, the local name is "windspeed", and the foreign name is "wind_speed". The dimension of the argument array is indicated as "2", because even if there is only one input argument when the function is used, the function returns two values that it places in that array. The indicated foreign name is not necessarily the name of the foreign procedure itself. It is a unique identifier used in the subroutine "fgnfun" of MODELS, to recognize which foreign function is being called. It is inside that subroutine that the actual call to the foreign procedure is made. That subroutine needs to be edited when installing calls to new foreign procedures. That subroutine is fully documented with comments, and should present no difficulty when used. Part of that subroutine is shown below, showing how the identifier "wind_speed" of the previous example would be used: 27 USERS GUIDE TO MODELS IN ATP SUBROUTINE fgnfun ( name, namlen, xarg, nval, ierflg) IMPLICIT REAL*8 (A-H, O-Z), INTEGER*4 (I-N) DIMENSION xarg(*) ... C In the following lines, register the foreign function names C as declared in the models: DATA refnam(1) / 'SAMPLE_FUNCTION' / ! Example "ftnfun.dat" DATA refnam(2) / 'SAMPLE_C_FUNCTION' / ! Example "cfun.dat" DATA refnam(3) / 'WIND_SPEED' / ! Added for this example DATA refnam(4) / ' ' / ... C The following lines call the actual foreign procedures: C - actual names may be different from the foreign C names used in the models IF (iname.EQ.1) THEN nval= samplf(xarg) ELSE IF (iname.EQ.2) THEN nval= cfun(xarg) ELSE IF (iname.EQ.3) THEN nval= wind(xarg) ... It is when actually using the foreign function that the values of the input arguments are identified. Just as when using a local function, it is possible to specify how the function arguments are calculated. If the operation of the function varies in function of time, the value of time must be explicitly passed to the function as one of its input arguments. In the example of the wind speed function shown above, the only input argument used by the function is the value of the simulation time "t". The function returns two values, the wind velocity and direction, placed in the argument array of the function. Internally, MODELS uses the value returned by the function, which in this case will be "2", to find out how many values the function has placed in the argument array. The following example illustrates the definition and the use of another simple foreign function: VAR y[1..2], k FUNCTION f1 FOREIGN sample_function {ixarg:2} ... EXEC ... y[1..2]:=f1(k+t, -k) -- each argument can be an arbitrary expression ... The foreign procedure, in this case, is a Fortran function that uses two input values, 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, for example: 28 USERS GUIDE TO MODELS IN ATP int CFUN(double arg[]) { arg[0] = arg[0] + arg[1]; arg[1] = 10 * arg[0]; return 2; } 2.4. 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. Two procedures have pre-defined names: EXEC and INIT. 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. It is called automatically each time a USE statement is executed. It describes how the model operates as time increases. The INIT procedure describes how to initialize the values of the variables before the simulation begins. It is called automatically when a USE statement introduces a new instance of a model. Additional named procedures can be defined, identified by arbitrary names and performing arbitrary operations on the variables of the model. 2.4.1. The EXEC procedure The EXEC procedure is the main operating procedure of the model. It is called each time a USE statement calling that model is executed. The EXEC procedure describes how the state of a model, as expressed by the value of its variables, evolves over the time of the simulation. This evolution is described by means of an arbitrary arrangement of assignment statements (value assignment, integral assignment, Laplace and z transfer functions, differential equations, and combined simultaneous equations), algorithm control statements (for conditions and repetitions using IF, WHILE, FOR, ERROR), calls to other models (USE), and procedure calls. 2.4.2. The INIT procedure The first time that a model instance is called during a simulation, the INIT procedure of the model is executed, followed by the EXEC procedure. At subsequent time steps, only the EXEC procedure is executed. The EXEC procedure can be prevented to execute at the initial use by placing its contents inside an IF statement, but see the following discussion on the subject of executing both INIT and EXEC. The initial call to a model instance can be at a time different than time zero if, for example, the corresponding USE statement is written inside an IF statement in the EXEC procedure of the calling model. 29 USERS GUIDE TO MODELS IN ATP 2.4.2.1. 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
Compartilhar