USERS_GUIDE_TO_MODELS_IN_ATP_ACKNOWLEDGM

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