Models en atp

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
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
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
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
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............................................................................28
2.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
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.............................................101
7.1.2. Sample data case..........................................................................102
7.2. Library of complex-value functions........................................................103
7.2.1. Examples of complex-value functions............................................103
7.2.2. Sample data case..........................................................................105
7.3. Library of TACS-like devices.................................................................106
7.3.1. TACS type-50 frequency meter .....................................................106
7.3.2. TACS type-51 relay-operated switch .............................................107
7.3.3. TACS type-52 level-triggered switch..............................................107
7.3.4. TACS type-53 transport delay........................................................108
7.3.5. TACS type-54 pulse delay .............................................................108

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

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

1
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 of the 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
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
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
- 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 a variable.

5
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
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
- 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
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
Boolean values and vice versa);

9
- 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
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
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
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
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
- 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
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

16
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:
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
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
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:
CONST ...
DATA ...
...
$INCLUDE filename { inserting a local submodel (notice the ATP formatting)
...
EXEC
...
...
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
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.
CONST ...
DATA ...
...
MODEL controller FOREIGN control_program
{ixdata:3, ixin:2*n+4, ixout:n, ixvar:5}
...
EXEC
...
...
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
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"
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"
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
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
CONST ...
DATA ...
...
MODEL controller EXTERNAL
...
EXEC
...
...
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:
...
...
ENDMODEL
MODEL controller
CONST ...
DATA ...
...
ENDMODEL
or at the same level as a foreign model:
...
...
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
...
...
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
...
...
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
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
VAR a, k
FUNCTION curve2(x) ... -- a statement function or a point list for k=2
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 values 2, 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
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
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
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
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 time t0. If only the INIT procedure ran at
t0, then it would have to contain value assignments for all the variables in the
model, which means that much of the INIT procedure would duplicate what's in
the EXEC procedure. Similarly, we would need to somehow call all the submodels
used in the EXEC procedure, so that they be initialized too, again a duplication of
the contents of the EXEC procedure.
Let's turn the thing on its head and consider instead what would prevent us from
having only the EXEC procedure run at t0 without an INIT procedure. The
problem would be that any past value that needs to be referenced in the model
during the first execution would be undefined. This can happen either explicitly, as
in
a_increase := a - a_old
where "a_old" has of course not been defined yet.
It can also happen in implicit references to past values, as in:
slope_v := deriv(v)
where the function deriv() needs to access, behind the scene, the value of v at the
previous time step, which of course has not yet been stored in the model's
running history, and is therefore undefined.
By having both the INIT and EXEC procedures executing at the initial time, we
minimize the size of INIT, and avoid code duplication which would easily create
maintenance problems in the development life of the model. All we need to do in
the INIT procedure is define any past values which will be referenced in the EXEC
procedure before the model has had the opportunity to store these past values
itself in its running history.
2.4.2.2. INIT procedure and HISTORY assignment
Rather than forcing one to define all initial values and history expressions in the
INIT procedure of a model, a more flexible three-level mechanism is available in
MODELS.
This mechanism owes its existence to the need of being able to assign history
and initial values differently for different uses of the same model. If the definition
of history and initial values had to be hard-coded in the INIT procedure of the
model, then the contents of the model would have to be modified from one use to
another, which runs counter to the approach of separating the definition from the
use of the models.
This is why MODELS has been built so that it be possible to assign HISTORY
expressions in the USE statement calling a model -- this is level one.

30
In addition, default history expressions can be specified for any of a model's
inputs and variables which require a history to be defined. The default history
expression will be used only if no history is specified for that element in the USE
statement. This is level two. Note that if an element is declared in a model as
requiring a history, and that no default history is defined for it, then its history
expression must be specified in the USE.
What's left for the INIT procedure is assigning history and initial values which are
private to the model, that is, which the user of the model doesn't need to know
about (see the section on history expression assignment). This is level three.
Of course, it's desirable to build the INIT procedure so that it takes care of as
much of the history and initial value assignments as possible, leaving a minimum
of concern to the user of the model. Notice that the expression defining the history
of an element can make reference to the history expression of another element,
which can be very useful in the INIT procedure.
2.4.3. Named procedures
Although not yet available at the time this text is being written, it will soon be
possible to define named procedures in a model. This is to provide the possibility
of performing operations on a model other than what is done in the EXEC
procedure. The implicit message guiding the operation of the EXEC procedure is
"updating to a new simulation time". Using additional procedures, other operations
can be executed, for example asking a model instance to reset a group of
variables or to perform a write operation, or accessing the value of a specific
variable of the model. This also makes it possible to connect to the operation of a
model from more than one locations in the calling model, otherwise reserved to
one USE statement for each instance.
The final format for defining a procedure is not yet definitive, but would be in the
line of this example:
MODEL proc_example
DATA inival {dflt:0}
INPUT x
VAR y
INIT -- this is executed when the instance is created or first USEd
integral(x) := inival
ENDINIT
EXEC -- this is the default operation procedure,
-- executed when the instance is used from a USE statement
y := integral(x) -- assigns value of integral to y
self.write_y -- calls the procedure 'write_y'
ENDEXEC

31
PROC write_y
write('In model proc_example, y=', y)
ENDPROC
PROC reset_integral(resetval) -- uses one input argument
integral(x) := resetval -- resets the value of the integral
ENDPROC
PROC integral_value
integral_value := integral(x) -- returns the value of the integral
ENDPROC
ENDMODEL
As shown in the above example, a procedure can have zero or more input
arguments, and can return zero or more output values. A procedure can be called
from inside the model where it is defined, using the instance identifier "self". As
shown in the next example, a procedure can also be called from another model
that uses an instance of the model where the procedure is defined:
MODEL test_proc
MODEL proc_example EXTERNAL -- identifies a model description
VAR k -- counter
INIT k:=0 ENDINIT
EXEC
k:=k+1
USE proc_example AS example -- creates and updates an instance named
-- "example" of the model "proc_example"
DATA inival := -4
INPUT x := 2*t +3
ENDUSE
IF k=4 THEN
example.reset_integral(0) -- calls a proc of "example"
ENDIF
write('In test_proc at t=', t,
', integral value=', example.integral_value) -- calls another proc
ENDEXEC
ENDMODEL
In the above example, a procedure is called by identifying the name of the model
instance to which it belongs, the name of the procedure, and the value of its input
arguments, if any. The procedure "reset_integral" expects one input value, and
returns no value. The procedure "integral_value" expects no input value, and
returns one output value.
A procedure can be used as a function inside an expression, returning one or
more values to the expression. A procedure returning no values can be used as a
statement inside another procedure. A procedure can be recursive.
2.5. Writing the statements of a procedure
Various types of statements can be used in a procedure for assigning values to
the variables of the model, for controlling the algorithmic flow of a procedure, for
defining and using instances of other models, and for calling the procedures of a
model. They are:

32
- assigning values
element := expression
diffeq(d-polynomial)|y := x
laplace(y/x) := (s-polynomial)/(s-polynomial)
zfun(y/x) := (z-polynomial)/(z-polynomial)
integral(element) := expression
histdef(element) := expression
- controlling the algorithm
IF ...
WHILE ...
FOR ...
DO ...
REDO
COMBINE ...
ERROR ...
- using and updating an instance of a model
USE ...
- using a procedure of a model
instance.procname(argument values)
write( ... )
2.5.1. Value assignment statement
There are two types of equations available for assigning a value to a variable:
explicit and implicit. The explicit value assignment has the simple form:
element := expression
The element can be a single variable y, a single element of an array variable
y[expr], or a range of elements of an array variable y[expr..expr].
The types of expressions available are regular expression, sum expression,
derivative polynomial expression, and integral (see the section about
Expressions).
A regular expression can be written to return either a single value or a list of
values. Single elements, of course, can only be assigned a single value. But a
range of elements can be assigned either a single value applied to all the
elements of the range, or individual values taken from the list of values returned
by the expression.
Minimum and maximum limits can be placed on the value or values returned by
the expression (see Expressions).
It is also possible to assign a value explicitly to the integral of a variable, as
discussed in the section on integral value assignment.

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

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

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

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

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

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

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

Models en atp

Recommended

Recommended

More Related Content

Similar to Models en atp

Similar to Models en atp (20)

Recently uploaded

Recently uploaded (20)

Models en atp