Professional Documents
Culture Documents
TO
MODELS IN ATP
April 1996
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.
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.
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 ...
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
USERS GUIDE TO MODELS IN ATP
4.
5.
6.
7.
i
7.3.6. TACS type-55 digitizer ...................................................................110
7.3.7. TACS type-56 point-by-point nonlinearity ......................................110
7.3.8. TACS type-57 time-sequenced switch...........................................110
7.3.9. TACS type-58 controlled integrator................................................111
7.3.10. TACS type-59 simple derivative...................................................112
7.3.11. TACS type-60 input-IF component ..............................................112
7.3.12. TACS type-61 signal selector ......................................................112
7.3.13. TACS type-62 sample/hold and track/hold...................................113
7.3.14. TACS type-63 instantaneous min/max ........................................114
7.3.15. TACS type-64 min/max tracking ..................................................115
7.3.16. TACS type-65 accumulator / counter...........................................116
7.3.17. TACS type-66 RMS value............................................................117
Appendix A Syntax of the MODELS language .............................................118
MODELS section in ATP...............................................................................118
Description of a local model ..........................................................................119
Statement......................................................................................................123
Directive in a USE statement ........................................................................128
Expression ....................................................................................................129
Regular expression .......................................................................................130
Value-holding element ..................................................................................132
Syntactic element..........................................................................................133
Appendix B Keywords of the MODELS language.........................................135
Keywords of the MODELS section of ATP ....................................................135
Keywords of the Model description ...............................................................136
Keywords of the Statements .........................................................................137
Keywords of the Directives in a USE statement............................................138
Keywords of the Expressions........................................................................138
Keywords of the Regular expression ............................................................139
Keywords of the Comments ..........................................................................139
Appendix C Pre-defined constants and variables.........................................140
Pre-defined constants ...................................................................................140
Pre-defined global variables..........................................................................140
Pre-defined local variables............................................................................141
Appendix D Pre-defined functions ................................................................143
Numerical functions ......................................................................................143
1-to-1 functions returning one value for each argument ...........................143
2-argument functions returning a single value ..........................................144
n-argument functions returning a single value ..........................................145
Logical functions ...........................................................................................145
1-to-1 functions returning one value for each argument ...........................145
n-argument functions returning a single value ..........................................146
Random value functions................................................................................146
Simulation functions ......................................................................................148
deriv(x)......................................................................................................149
deriv2(x)....................................................................................................150
prevval(x)..................................................................................................151
delay(x, dval, pol)......................................................................................151
USERS GUIDE TO MODELS IN ATP
i
predval(x, tval, pol) ...................................................................................151
predtime(x, xval, pol) ................................................................................152
backval(x, tval, pol) ...................................................................................152
backtime(x, xval, pol) ................................................................................152
histval(x, tval)............................................................................................153
histdef(x)...................................................................................................153
Bibliography ......................................................................................................154
Index .................................................................................................................159
In closing ... .......................................................................................................165
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.
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.
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.
7
- in expressions global to all instances of a model, specified in the model
definition:
-
Access
constant
private
model definition
data
public
variable
private
model definition
input
public
output
public
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.
8
DATA d[1..3]
The use of an array notation can simplify the description of a model, and also
contributes to reducing the execution time of the simulation.
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 >= 0
is calculated as
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)}
10
w[2] := expression
or
laplace(y/x) := (s_numerator)/(s_denominator)
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 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.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
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.
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
- inf
- undefined
3.14159...
a large value, typically 1020
the special value 88888.88888
the value 0
the value 1
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
INPUT vterm[1..n]
VAR vtmax[1..n]
-- an array dimension
-- 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}
DATA omega {dflt: 2*pi*freq}
-- a frequency in Hz
-- the equivalent frequency in rad/sec
-- a frequency in Hz
-- the equivalent frequency in rad/sec
-- number of terminals
-- value of measured terminal voltages
-- value of a reference voltage, =0 if not used
16
------
number of terminals
value of measured terminal voltages
value of a reference voltage, =0 if not used
tracked maximum absolute value of each terminal voltage
tracked maximum absolute value of all terminal voltages
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".
17
DATA n
-INPUT vterm[1..n]
-vref {dflt: 0} -VAR vtmax[1..n]
-vmax
-OUTPUT vtmax[1..n], vmax
number of terminals
value of measured terminal voltages
value of a reference voltage, =0 if not used
tracked maximum absolute value of each terminal voltage
tracked maximum absolute value of all terminal voltages
-- can be used as outputs of the model
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
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.
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.
MODEL component
-- defining a model
CONST ...
DATA ...
...
MODEL controller FOREIGN control_program
{ixdata:3, ixin:2*n+4, ixout:n, ixvar:5}
...
EXEC
...
USE controller AS control_1
-- using the submodel
...
ENDUSE
...
ENDEXEC
ENDMODEL
In the above example, the local name is "controller", and the foreign name is
"control_program". That foreign name is not necessarily the name of the foreign
program itself. It is a unique identifier used in the subroutine "fgnmod" of
MODELS, to recognize which foreign model is being called. It is inside that
subroutine that the actual call to the foreign program is made. That subroutine
needs to be edited when installing calls to new foreign programs. That subroutine
is fully documented with comments, and should present no difficulty when used.
Part of that subroutine is shown below, showing how the identifier "controller" of
the previous example would be used:
20
C
C
C
C
C
C
C
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.
22
MODEL component
-- defining a model
CONST ...
DATA ...
...
MODEL controller EXTERNAL
...
EXEC
...
USE controller AS control_1
-- using the submodel
...
ENDUSE
...
ENDEXEC
ENDMODEL
The full definition of the external model can be placed anywhere at the same level
of the calling model or above. For the previous example, it could be found either
at the same level of the "component" model as a locally-defined model:
MODEL component
-- defining a model
...
MODEL controller EXTERNAL
...
ENDMODEL
MODEL controller
CONST ...
DATA ...
...
ENDMODEL
or at a higher level:
MODEL system
MODEL sub_system_1
MODEL component
-- defining a model
...
MODEL controller EXTERNAL
...
ENDMODEL
...
ENDMODEL
MODEL sub_system_2
...
ENDMODEL
MODEL controller ...
...
ENDMODEL
23
MODEL component
-- defining a model
...
MODEL controller EXTERNAL
...
ENDMODEL
$INCLUDE filename
{ a file holding a library of models
...
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, ... )
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])
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
FUNCTION
FUNCTION
FUNCTION
...
a:= some value
k:= 2.5
y:=f(k)
Supposing that these coordinates are available in a file named "xy.lst", they could
be included in a model as follows:
FUNCTION xyfun POINTLIST
$INCLUDE xy.lst
26
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
C
C
C
C
C
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
28
int CFUN(double arg[])
{ arg[0] = arg[0] + arg[1];
arg[1] = 10 * arg[0];
return 2;
}
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 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.
31
PROC write_y
write('In model proc_example, y=', y)
ENDPROC
PROC reset_integral(resetval)
integral(x) := resetval
ENDPROC
PROC integral_value
integral_value := integral(x)
ENDPROC
ENDMODEL
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.
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( ... )
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.
expressed using the keyword DIFFEQ, and the vertical bar as an operator
meaning "applies to":
DIFFEQ(polynomial)|y := x
This is expressed using the following notation, again using the vertical bar as the
operator "applies to":
LAPLACE(y/x) := (numerator)/(denominator)
34
This is expressed using the following notation, again using the vertical bar as the
operator "applies to":
ZFUN(y/x) := (numerator)/(denominator)
is equivalent to
Y (s)
1
=
X (s) a0 + a1s + a2 s2 +...
becomes
(a0 + a1D + a2D 2 +...) y (t ) = (b0 + b1D + b2D 2 +...) x(t )
35
x(t0) = x(t), x(t1) = x(t-t), x(t2) = x(t-2t), ..
or, using the z-domain notation,
x(t0) = t, x(t1) = z-1x, x(t2) = z-2x, ...
to produce an equivalent z-transform transfer function
Y (z) B0 + B1z 1 + B2 z 2 +...
=
X (z) A0 + A1z 1 + A2 z 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 recalculated, 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} := (...)/(...)
38
t0
x dt
the integral of x with respect to time, from -infinity to the present time. This can be
decomposed, using t1 = t0 - t, as:
t0
t1
t0
t1
x dt =
or
x dt + x dt
x(t1) + x(t 0 )
(t 0 t1)
2
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.
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:
IF condition_is_true THEN
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:
IF condition_is_true THEN
statement list
ELSIF another_condition_is_true THEN
another statement list
...
ELSE
another statement list
ENDIF
40
An IF statement can be enclosed inside another IF statement, in any of its
clauses:
IF condition_is_true THEN
statement 1
statement 2
IF condition THEN
another statement list
...
ENDIF
...
ENDIF
The first three conditions can be grouped using a logical expression, and the IF
statement can be rewritten as:
IF onswa=2 AND ia<=ichop AND di_dta<di_lim THEN onswa:=3
ELSIF dva>ds
THEN onswa:=2
ENDIF
41
But in MODELS, logical expressions return a numerical value, 0 or 1. This IF
statement can therefore also be expressed as a value assignment that uses the
value of a condition inside a numerical expression:
cond_1 := onswa=2 AND ia<=ichop AND di_dta<di_lim
cond_2 := NOT cond_1 AND dva>ds
cond_3 := NOT cond_1 AND NOT cond_2
onswa := 3*cond_1 + 2*cond_2 +onswa*cond_3
If cond_1 is true, its numerical value is 1, cond_2 is false, and the expression
evaluates to: 3*1 +2*0 +onswa*0, and so on.
Conditional expressions can also use a variable as a selector:
y := (a=1)*f1(x) +(a=2)*f2(x) + ...
42
This structure can be used for doing iterations inside a model, with the simulation
time "frozen" for the duration of the iteration:
MODEL while_example -- illustrates the use of WHILE
VAR k
EXEC
IF t=timestep THEN -- execute only at the first time step
write("*** Begin results of model 'while_example' ***")
k:=5
WHILE k>0 DO
write('k=', k, ' in loop ')
k:=k-1
ENDWHILE
write('k=', k, ' after loop ')
write("*** End results of model 'while_example' ***")
ENDIF
ENDEXEC
ENDMODEL
The word "while", in this case, does not imply a reference to time, and does not
mean "when". If we need to express "when a condition is true then do this", we
can use an IF statement to take care of that, as shown in the example above with
"IF t=timestep THEN".
The other difference is the values to be taken by each parameter are given in the
form of a value list, where each term of the list can be either a single value or a
range of values:
FOR z:= 0 TO 5,
6,
7 TO 9 BY 1
-- 0,1,2,3,4,5
-- 6
-- 7,8,9
43
The statement list placed inside the FOR statement is executed repeatedly until
all combinations of the parameter values have been covered:
MODEL for_example
-- illustrates the use of FOR in MODELS
VAR k
EXEC
IF t=timestep THEN
-- execute only at the first time step
write("*** Begin results of model 'for_example' ***")
FOR z:= 0 TO 5,
6,
7 TO 9 BY 1
FOR y:= 0 TO 8 BY 2
DO
k:=z*10 +y
write(k)
ENDFOR
FOR z:= 9 to 0 by -1
FOR y:= 5, 0
DO
write(z*10 +y)
ENDFOR
-----
0,1,2,3,4,5
6
7,8,9
0,2,4,6,8
-- 0,2,4,6,8,10,12,...,94,96,98
-- 9,8,7,6,5,4,3,2,1,0
-- 5,0
-- 95,90,85,80,75,...,15,10,5,0
As shown in this example, the values of the parameters are assigned and
combined in the sequence in which they are specified.
The names of the parameters are local to the FOR statement, and don't need to
be declared as variables of the model.
Even though the simple examples above show only integer values, the
parameters can also be assigned non-integer values:
FOR angle:= 0 TO 2*pi BY pi/4
DO
write('tan(', deg(angle), ') = ', tan(angle))
ENDFOR
As for the WHILE statement, the simulation time is frozen while control of the
execution is kept inside a FOR statement.
2.5.8. DO statement
Like the WHILE statement, the DO statement is used for repeating the execution
of a group of statements.
DO
statement list
ENDDO
The first difference is that in the DO statement, the statement list is executed at
least once.
44
The second difference is that the condition determining whether the loop will be
repeated or not, is carried by a flag set by executing the REDO statement
anywhere inside the statement list.
The DO statement is like a WHILE statement written as follows:
redo_flag := TRUE
WHILE redo_flag = TRUE DO
statement list
ENDWHILE
The DO statement is used instead of the WHILE statement in situations where the
loop condition is more complex than can be expressed in the simple conditional
expression of the WHILE statement. Instead of having to declare and use a flag
explicitly as in the last example above, we can directly use the REDO statement
in one or more places inside the statement list.
As for the WHILE statement, the simulation time is frozen while control of the
execution is kept inside a DO statement.
45
2.5.10.1. Using the linear COMBINE for linear equations
The linear COMBINE statement is used in the following format:
COMBINE AS identifier
statement list
ENDCOMBINE
The statement list of a linear COMBINE can include any arrangement of the
following types of linear equations:
- differential equations, which in MODELS use a linear polynomial of the time
derivatives of a variable;
- Laplace transfer functions, which are described using two linear polynomials of
the "s" operator;
- z transfer functions, which are described using two linear polynomials of the
"z -1" operator;
- linear value assignments of a variable or of an array element of a variable,
using:
- a sum expression, which is a linear sum of variables
- a derivative expression, which is a polynomial of the time derivatives of a
variable
- the integral of a variable
- the first or second derivative of a variable
- no regular expression (considered nonlinear)
Here is an example combining two simultaneous linear equations:
a+b=6
( rewritten as b = 6 - a )
a=t*b
46
MODEL comb1
VAR a, b
EXEC
COMBINE AS first_group
b := sum( 6| - 1|a )
a := sum( t|b )
ENDCOMBINE
write('t=',t,', a=',a,', b=',b,', a+b=',a+b)
ENDEXEC
ENDMODEL
Each line of the COMBINE group describes how a value is assigned to each
simultaneous variable. This is why the first equation is rewritten to express the
value of b, as we were already using the second line to express the value of a.
The syntax of the sum() expression is explained in the section on "Expressions".
Notice how the format of the sum() expression requires that we place the
coefficient of the left of each term, and the variable on the right of the term. This is
why we could not write a := sum( b | t ), because in this case, t is not a variable of
the group, b is.
The linear COMBINE allows us to add min/max limits to one of the equations:
MODEL comb1
VAR a, b
EXEC
COMBINE AS first_group
b := sum( 6| - 1|a )
a := sum( t|b ) { max: 4 }
ENDCOMBINE
write('t=',t,', a=',a,', b=',b,', a+b=',a+b)
ENDEXEC
ENDMODEL
Here are four versions of the same set of simultaneous equations showing the
relationship between sin(t) and cos(t), all with the same solution of:
y1 = sin(t), y2 = cos(t), y3 = -sin(t)
The first set uses integrals:
y1 = integral(y2)
y2 = integral(y3)
y3 = - y1
The second set uses derivatives:
y2 = deriv(y1)
y3 = deriv(y2)
y1 = - y3
The third set uses a Laplace version of the integrals:
Laplace(y1/y2) = 1/s
Laplace(y2/y3) = 1/s
y3 = - y1
47
The fourth set uses a z-transform and Laplace version of the derivatives:
z-transform(y2/y1) = (1 - z -1) / (h + hz -1)
Laplace(y3/y2) = s/1
y1 = - y3
MODEL comb2
-- illustrates linear COMBINE groups in MODELS
VAR y1, y2, y3, x, h
HISTORY y1
{dflt: sin(t)}
y2
{dflt: cos(t)}
y3
{dflt: -sin(t)}
integral(y2) {dflt: sin(t)}
integral(y3) {dflt: cos(t)}
x
{dflt: cos(t)}
INIT
h:=timestep/2
ENDINIT
EXEC
write(' ')
write('Results at t=', t, ' :')
COMBINE AS first_group
y1:= integral(y2)
y2:= integral(y3)
y3:= sum(-1|y1)
ENDCOMBINE
write(sin(t),':',y1)
COMBINE AS second_group
y2:= deriv(y1)
y3:= deriv(y2)
y1:= sum(-1|y3)
ENDCOMBINE
write(sin(t),':',y1)
COMBINE AS third_group
laplace(y1/y2) := 1|s0 / 1|s1
laplace(y2/y3) := 1|s0 / 1|s1
y3:= sum(-1|y1)
ENDCOMBINE
write(sin(t),':',y1)
COMBINE AS fourth_group
zfun(y2/y1)
:= (1|z0 -1|z-1)/(h|z0 +h|z-1)
laplace(y3/y2) := 1|s1 / 1|s0
y1:= sum(-1|y3)
ENDCOMBINE
write(sin(t),':',y1)
-- (s/1)
ENDEXEC
ENDMODEL
48
statement list specifies how to calculate the value of one of the simultaneous
variables.
The iterated COMBINE statement is used in the following format:
COMBINE ITERATE AS identifier
statement list
ENDCOMBINE
Iterated COMBINE groups are solved using the Newton method. The tolerance
value is fixed at 10-8 times each value. The maximum allowed number of
iterations per step is user-definable, with a default of 10.
A maximum number of iterations other than 10 can be specified inside braces
following the keyword ITERATE, for example:
COMBINE ITERATE {5} AS first_group
b := 6 - a
a := t * b
ENDCOMBINE
indicating that we would allow only 5 iterations for convergence to take place.
Here is an example that illustrates how an iterated COMBINE can be used with
different types of assignments and multiple min/max limits. It describes a
somewhat acrobatic set of simultaneous equations that should provide the
following solution:
y1 = y4 -y2 +2 { max: y4/y2 }
y2 = 2 * t * y1
y3 = integral(y2) { max: 7.5 * y2 / t }
y4 = deriv(y3) * (y2 < 4)
( Solution: y1 = 1 )
( Solution: y2 = 2 t )
( Solution: y3 = t 2 { max: 15 } )
49
+ 2 * t * (y2 >= 4)
y5 = sum(y3 + y2 - y4)
( Solution: y4 = 2 t )
( Solution: y5 = t 2 { max: 15 } )
MODEL comb3
-- illustrates nonlinear COMBINE ITERATE groups in MODELS
VAR y1, y2, y3, y4, y5
HISTORY y1
{dflt: 0.0} -- wrong on purpose, should be 1
y2
{dflt: 2*t}
integral(y2) {dflt: t*t}
y3
{dflt: t*t}
y4
{dflt: 2*t}
y5
{dflt: t*t}
EXEC
COMBINE ITERATE {9} AS first_group
y1:=y4-y2+2 {max:y4*recip(y2)}
y2:=2*t*y1
y3:=integral(y2) {dmax: 7.5*y2*recip(t) }
y4:=deriv(y3)*(y2<4) + 2*t*(y2>=4)
y5:=sum(y3| +1|y2 -1|y4)
ENDCOMBINE
write('t=', t, ' y1=' y1 ', y2=' y2 ', y3=' y3 ', y4=' y4 ', y5=' y5)
ENDEXEC
ENDMODEL
50
keeping the time step small, but depending on the situation, we might be able
to use a larger time step than with the implicit zero-order prediction approach;
d) instead of a), b), or c) above, we rewrite the equations and provide a local
iteration mechanism using a WHILE statement with an iteration condition -this allows to ease the constraints on the size of the time step, by localizing
the iteration to where it's needed (so that in fact we provide both prediction
and correction);
e) instead of building the iteration mechanism in MODELS, we use an external
program that solves the equations that we need to solve, and we attach that
external program as a regular submodel or function in our model; this
approach is particularly appropriate when the set of equations is the result of
trying to simulate in MODELS something that would be better represented and
better solved in a program which has representations and solution methods
specifically designed for the domain of the application; local domain-specific
solutions will always be more efficient that trying to use general representation
or solution mechanisms that are not taking advantage of the specific
conditions of the domain that is being represented; plus it saves the effort of
having to reinvent it. When using MODELS to represent large systems, we
look at MODELS as the procedural and numerical glue between the locallymore-tightly-coupled subsystems. We have the choice to represent and solve
some of these subsystems using MODELS, and some of them using other
programs called by MODELS.
51
The instance identifier is either a name, or an indexed name. Indexed names are
needed when placing a USE statement inside an indexed loop, for example:
FOR i:=1 TO n DO
...
USE somemodel AS someid[i]
...
ENDFOR
letting the USE statement call a different instance of the model for each value of
the loop variable i.
The use directives are described in the section "Using a model".
It could also be called from the model in which it is defined, using the reserved
instance identifier self:
52
self.reset_integral(expression)
where normalized is the name of a procedure defined, in this case, in the same
model.
53
3. WRITING EXPRESSIONS
Regular expressions are used in a model everywhere a value needs to be
specified. Any value in a model can be represented by an expression describing
symbolically how to calculate that value. Special expressions including the
linear sum, the polynomial of derivatives, and the integral expression, can
only be used as the right-hand side of an assignment statement.
If the variable is an array, we can refer to a single element of that array by also
indicating its index in the form of an expression:
name[expr]
54
data
- the variables:
global variables
simulation
variables
inputs
variables
FOR arguments
function arguments
Here are the rules of reference, defining what elements are visible in what parts of
a model:
visible in any expression
global constants
constants
data
variables of any
type
FOR arguments
function
arguments
55
data of the used
model
Names used in any other expressions inside a USE statement are taken to be
references to elements of the local model (calling model), not of the used model.
For example, let's suppose there is a data n defined in both the local model and
the used model (and carrying different values, of course). In a USE statement, if
the name n is used in an array index of one of the assignments, it will be referring
to the value of n from the used model.
This way, we can write
USE ...
DATA n
:= _____
INPUT a[1..n] := _____
But if the name n is used in an expression on the right-hand side (for example,
defining the assigned value of an input), it would be referring to the value n of the
local model, not of the used model:
USE ...
INPUT a[1..n]:= 2*n*(t-2)
Specifying the context of the named elements we are referring to inside a USE
statement is not a simple matter. The present set of rules allow us to use an
implicit notation. These rules do satisfy most applications, but we can always find
examples where it would be useful to do just the opposite of what the rule says.
For example, it would be useful to write
USE ...
INPUT a[1..n] := b[1..n]
or
USE ...
INPUT i1 := ...
i2 := 2*i1
The only way we can do the first one, according to the above rules, is if n is a
name defined in the local model, not the used model. And the present set of rules
doesn't allow the second example.
The alternative to implicit notation would be to use an explicit notation, that is, an
indication that tells directly if a name belongs to the local model or to the used
submodel, either with a keyword or an operator, for example:
USE ...
INPUT a[1..sub.n] := b[1..sub.n]
or
USERS GUIDE TO MODELS IN ATP
56
USE ...
INPUT i1 := ...
i2 := 2*sub.i1
This is not available yet, but it will become available in the future.
Note that this potential ambiguity of names exists only inside a USE statement,
and only when the same name is used for different purposes in both the local
model and the used submodel. It might be tempting to avoid the problem
altogether by not duplicating names in the two models. In a small project, this is
easy to do. But when we start building libraries of models, we need the flexibility
of being able to define names without worrying about their use somewhere else,
that is, we need a local name space for each model, which is one of the principles
on which MODELS is designed.
0.0,
-0.1,
-1E-6,
1.E3,
0.2E-9
-----
As shown in these examples, the value of each input argument can be described
using a regular expression. When a function expects a list of values as input,
57
these values can be described using a list of expressions, including expressions
that return multiple values in the form of an array.
where status is the name of a procedure defined in a submodel used with the
instance name controller, and normalized is the name of a procedure called from
the same model where it is defined.
OR
AND
numerical binary op
numerical unary op
>
>=
<
<=
<>
+,-
*,/
**
logical unary op
exponentiation
MOD
NOT
negative of member
58
The above sequence also shows the default order of precedence among the
operators. Here are some examples:
a AND b OR t-ton>0
a*b-c/d**2
-- = (a AND b) OR ((t-ton)>0)
-- = (a*b) - (c/(d**2))
In the above example, the minimum is applied to the result of the complete
expression, not to the value of b.
It is possible to apply limits to part of an expression, by enclosing that part in
parenthesis, thus making it a separate expression to which a limit can be applied:
a*(3*b +c {min: ... , max: ... })
In this example, the limits are applied to the value of 3*b+c. Again, notice that the
limit is applied to the complete expression to which it is attached, not to the last
member of that expression. Here, the expression is not applied to c. Additional
parentheses can be used to make this more explicit:
a*((3*b +c) {min: ... , max: ... })
59
-- 1-to-n assign
c[1..3] := [1, 2, 3]
[1,2,3]
-- n-to-n assign
a[1..3] := c[1..3]
[1,2,3]
-- n-to-n assign
-- n-to-n subtract
a[4..6] := a[4..6] -1
[0,0,0]
-- 1-to-n subtract
-- 1-to-n add
a[4..6] := 10 +a[1..3]
[11,12,13]
-- 1-to-n add
-- n-to-n add
-- n-to-n subtract
-- 1-to-n multiply
a[4..6] := 10 * a[1..3]
[10,20,30]
-- 1-to-n multiply
-- 1-to-n divide
a[4..6] := 12 / a[1..3]
[12,6,4]
-- 1-to-n divide
-- n-to-n AND
a[1..3] := a[1..3]**2
[1,4,9]
-- 1-to-n exponent
a[4..6] := 10**a[1..3]
[10,100,1000]
-- 1-to-n exponent
-- n-to-n limit
-- 1-to-n limit
-- 1-to-n modulo
-- 1-to-n modulo
= [-10,-10,-
=
=
=
=
=
Functions and procedures can receive lists of values and arrays as arguments,
and can return lists of values in the form of an array. See the respective sections
for details.
60
To express the bias term a0, a coefficient without a variable, we write that
coefficient followed by an "applies to" operator followed by no variable, to prevent
that coefficient to simply be included in the expression of the coefficient of the
next term.
sum((a+b)| +(b+c*d)|x1 + c|x2)
because, without that first operator, the expression would be interpreted as:
sum((a+b)+(b+c*d)|x1 + c|x2)
The linear sum can also be used outside of a COMBINE statement, but without
any advantage over simply using a regular expression.
Minimum and maximum limits can be attached to this expression, and also to the
value of each of its coefficients. For example:
sum((b+c*d){max:a1max}|x1 +c|x2) {min:minvalue, max:maxvalue}
61
In MODELS, the expressions describing each coefficient are separated from the
D operator using the "applies to" operator.
derivpol((a+b)|D0 +(b+c*d)|D1 + c|D2)|x
That value can also be reset, using the integral assignment statement:
integral(x) := new_value
The integral of x with respect to time is calculated using the trapezoidal rule, with
the assumption that x is linear over each step interval.
integral =
x1 + x0
t
2
62
This is a reasonable assumption to make when the time step is small enough to
follow the faster variations of x with respect to time. In cases where the time step
is too large, these faster variations are simply filtered out of the integral value,
with a possible loss of accuracy, but without consequences on the numerical
stability of the calculation.
It is possible to apply limits to the calculated value of a time integral. Because the
integral does carry an internal state from one step to the next, this limit is a
dynamic limit, that is, the value of the limit modifies not only the output value of
the integral, but also its internal state, the value that will be carried over to the
next time step. Limits are applied to the value of an integral as follows:
y:=integral(x) {dmin:expression, dmax:expression}
-- dynamic limits
To only apply a static limit, that is, a limit that affects only the value of the output,
not the state of the integral, we apply the limit outside the use of the integral:
y := integral(x)
y := y {min:expression, max:expression}
-- static limits
Following is an example showing the different effect of using a dynamic limit and
a static limit on an integral:
MODEL ilim
VAR x, y
dlim
nolim
slim
HISTORY x {dflt: 0}
y {dflt: 0}
integral(x) {dflt: 0}
integral(y) {dflt: 0}
EXEC
x:= 1
IF t>1 THEN x:= -1 ENDIF
y:= x
dlim :=integral(x) {dmax: 0.7}
nolim :=integral(y)
slim :=nolim {max:0.7}
ENDEXEC
ENDMODEL
The values of the variables x, nolim, slim, and dlim are shown in the following
figure:
63
64
65
Typically, the size of the time step would be maintained between 1/100 and 1/10
times the size of the smallest time constant of the model. A finer step would be a
waste of execution time. A larger step would affect accuracy.
TIMESTEP MAX: 0.1 * min(tau1, tau2, tau3)
TIMESTEP MIN: 0.01 * min(tau1, tau2, tau3)
66
67
and the DELAY keyword can also be repeated. When a default value is not
specified, a default value of 100 cells will be used.
which corresponds to asking for the value of x at time t-delaysize. If t-delaysize >=
t0, then the value of x at that time has been stored in the delay storage cells of
the model. But if t-delaysize < t0, then that value is undefined unless the model
has access to an analytical expression describing how to calculate the value of x
at times t<t0 .
That is the purpose of being able to define history expressions for some of the
variables and inputs of a model. A history expression is an expression that the
model will use when it needs to find the value of a variable or input from a time for
which no value has been stored in the model's running history.
From this definition, it can be seen that history expressions can be used also for
defining initial values.
The possibility of referring to the variable t in history expressions allows us to
define history values as regular expressions described as a function of time. In
addition to allowing the definition of history expressions as an explicit function of
time, this is also useful for defining the initial values of a model when it is
impossible to predict exactly the time at which an instance of the model will be
first executed during the simulation.
As discussed in the section about the INIT procedure, it is possible to specify
history expressions in three places in a model: as simulation directives in the
model definition, as simulation directives in the USE statement of each instance of
USERS GUIDE TO MODELS IN ATP
68
the model, and in the INIT procedure of the model. A history expression specified
as a simulation directive in the model definition is only a default expression that
the model will use when it is not re-specified in the USE statement or in the INIT
procedure. The notation is the following:
HISTORY y1
y2 {dflt: 0}
y3 {dflt: A*sin(omega*t)}
As shown here, the history expression may include a reference to the variable t.
When no expression is specified, the directive indicates that a history expression
will be needed for that variable in the USE statement of each instance where the
model is used.
Consider that HISTORY directives are only declarations of history expressions,
they are not a list of executed statements. The expressions will be evaluated only
when and if required during the simulation.
The initial value of integrals can also be specified using a history expression:
HISTORY integral(y) {dflt: expression}
There is one difficulty with assigning a history expression in the model definition if
the exact size of the group is variable, and depends on data determined in the
USE statement. In the first example above, there is no problem, because the
same value will be assigned to all elements of the group, whatever its size. In the
second case, it depends on how the array expression is written. If it is written as a
list of values, for example:
HISTORY y[n1..n2] {dflt: [expr1, expr2, expr3, ... ]}
then there may not be enough values in the list to cover the size of the group. The
solution for this is to declare only the names in the model definition:
HISTORY y[n1..n2]
and to specify the history expressions in the USE statement, where the number of
required values will be known:
HISTORY y[n1..n2] := [expr1, expr2, expr3, ... ]
69
5. USING A MODEL
Each USE statement defines an individual instance of a model. It is in the USE
statement that we assign values to the data and the inputs of a model, and that
we have access to the values of its outputs. We can also specify different
simulation directives for different instances of the same model.
A data element that had been assigned a default value in the model definition
does not need to be specified in the USE statement. But if it is, the new value will
replace the default value of the model definition.
-- number of terminals
-- value of measured terminal voltages
-- reference voltage, replacing default value
An input element that had been assigned a default value in the model definition
does not need to be specified in the USE statement. But if it is, the new value will
replace the default value of the model definition.
70
71
INTERPOLATION DEGREE DFLT:
0
DEGREE(y1, y2): 0
DEGREE(y3):
1
This option indicates to the solver that the model can be used more than once at
each time step, for example when called from inside an iteration loop. When this
option is specified, MODELS saves the initial state of the model when called at a
new time step, and re-starts from that saved initial state at each re-update of the
model at the same time step.
The following data case provides a simple illustration.
72
MODEL iteruse
MODEL sub EXTERNAL
VAR a
EXEC
FOR i:=1 TO 3 DO
USE sub AS sub ITERATE
INPUT in:=i*t
OUTPUT a:=out
ENDUSE
write('in iteruse at t=', t, ', a=', a)
ENDFOR
write(' ')
ENDEXEC
ENDMODEL
MODEL sub
INPUT in
OUTPUT out
VAR out
EXEC
out:=10*in
write('in sub at t=', t, ', in=', in, ', out=', out)
ENDEXEC
ENDMODEL
Notice how it is the same instance of the model that is re-updated for each value
of i inside the FOR loop. If we did not indicate the keyword ITERATE, the program
would create separate instances of that model for each pass, and the instance
names would need to be indexed, as:
USE sub AS sub[i]
73
This is what is taken care of automatically by MODELS.
Values that need to be carried from the past are automatically made part of the
running history of the model, which can include values from the previous step and
from earlier steps of the simulation. This is also why there is the possibility of
assigning history expressions to a variable or an input, so that values can be
found by the program if needed for reference to instants that fall before the start
of the simulation of the model.
For example, a model needs to have access to the previous value of a variable x
when x is used in an expression before a value has been assigned to it at the
current execution time.
A model also uses the history of variable x whenever a time function is applied to
x, such as deriv(x), integral(x), etc, and implicitly in interpolations. The history of x
is also used by the program in the implicit value assignments of laplace(y/x),
laplace(x/u), and the same for diffeq() and zfun().
74
75
BEGIN NEW DATA CASE
...
MODELS STAND ALONE
VAR ...
MODEL ...
MODEL ...
...
USE ...
USE ...
...
RECORD ...
ENDMODELS
plotting instructions ...
BEGIN NEW DATA CASE
BLANK
{
{
{
{
v(nodename) }
i(switchname) }
imssv(nodename) }
imssi(switchname) }
{ switch(switchname) }
{ mach(variable) }
-----
voltage at a node
current through a switch
imaginary part of s-s voltage at a node
imaginary part of s-s current at a
For a voltage, we just identify the name of the node. For a current, we identify the
switch (the only way to measure a current in ATP) by its branch name, or by the
name of a node to which it is connected. We do the same for a switch status.
76
During the simulation, the values of voltages and currents are calculated in the
time domain. But in the steady-state phasor solution, both real and imaginary
parts of a voltage or current are available. At simulation time t=0, the real part of
the complex value is carried in the regular v() and i(), and the imaginary part in
imssv() and imssi().
For a machine value, we use the variable names identified in the description of
the machine.
When the inputs expected by a model are in the form of an array, we declare
them as individual input variables in the MODELS section, and we pass them to
the model in array form, as illustrated below:
MODELS
INPUT va {v(NODEA)}
vb {v(NODEB)}
vc {v(NODEC)}
...
MODEL test
INPUT v[1..3]
...
-- phase-phase
ENDMODEL
...
USE test AS example
INPUT v[1..3] := [va-vb, vb-vc, vc-va]
...
MULPPF
2
LUNPPF
63
L63TYP
3
where:
- this is the same request as when using POSTPROCESS PLOT FILE with
TACS
- MULPPF defines in what multiple the original plot points will be used
- 1 means all points will be used, n means every nth point is used
- if using a multiple, adjust the time step accordingly to keep the simulation
synchronized with the PL4 data
- LUNPPF indicates the I/O unit allocated to the connection
- if left blank, a default value of 63 is assigned
- selecting a different unit may conflict with units already used by ATP
77
- L63TYP indicates the type of formatting of the PL4 file
- if left blank, a default value of 1 is assigned
- 1=UNFORMATTED, 2=FORMATTED, 3=C-LIKE
- UNFORMATTED is the default because it allows use of double precision
when preparing the PL4 file using the request CUSTOM PLOT FILE (see
the July 1995 issue of Can/Am EMTP News for details)
2) before the MODELS section, open the ATP connection to the existing PL4 file:
$OPEN,
UNIT=63
FILE=dc45.pl4
3) in the MODELS section, specify any number of signals from the PL4
file as inputs to MODELS:
INPUT gen {PL4(1)}
curr {PL4(2)}
where:
- gen and curr are arbitrary input names of the MODELS section
- PL4 is the input type
- 1, 2, etc indicate the corresponding curve number in the PL4 file
The 3rd subcase of benchmark case DC46.DAT illustrates the use of PL4 values
as input to the MODELS section:
BEGIN NEW DATA CASE
C
BENCHMARK DC-46
C
3rd of 3 subcases produces the same solution, but illustrates the new
C
connection to a plot file from MODELS. Just like with TACS, first line
C
of plot data at time t=0 is ignored. It is not required to use MODELS
C
as STAND ALONE, but can also be mixed with solution of a circuit.
POSTPROCESS PLOT FILE
2
63
3
$OPEN, UNIT=63
FILE=dc45.pl4 !
{ Expected to be C-like (L4BYTE = 1)
C deltat
tmax
.000100
.050 { Note DELTAT is twice that of DC-45, since use every 2nd step
C print points connec
s-s minmax
vary
again
plot
1
1
0
0
1
-1
0
2
5
5
20
20
50
50
MODELS STAND ALONE
INPUT gen {PL4(1)}, curr {PL4(2)}
MODEL postprocess_example
INPUT voltage, current
VAR flux, energy, power, gen_1
INIT
integral(voltage) := 0
integral(power)
:= 0
histdef(voltage) := 0 -- needed for the delay function
ENDINIT
EXEC
flux
:= integral(voltage)
energy := integral(power)
power := voltage * current
gen_1 := delay(voltage, timestep)
ENDEXEC
ENDMODEL
USE postprocess_example AS test
INPUT voltage := gen, current := -curr
78
ENDUSE
RECORD gen
AS gen
test.power AS power
test.gen_1 AS gen_1
ENDMODELS
BLANK card ending plot cards
BEGIN NEW DATA CASE
BLANK
curr
AS curr
test.flux
AS flux
test.energy AS nrg
indicating that the TACS variable named signal would be available in the
MODELS section under the name somename.
When both TACS and MODELS are used in a data case, the TACS section
precedes the MODELS section:
BEGIN NEW DATA CASE
...
TACS HYBRID
...
BLANK card ending TACS section
MODELS
...
ENDMODELS
circuit description ...
During the simulation, the order of execution at each time step is:
- circuit solution
- TACS section solution
- MODELS section solution
The following subcase of benchmark case DC30.DAT illustrates the use of TACS
variables as input to the MODELS section:
BEGIN NEW DATA CASE
C
4th of 4 subcases is the same as the first and the third, except that
C
it uses both TACS and MODELS. The voltages BUS2 and BUS3 are input to TACS.
C
VSW is output from TACS and input to MODELS. GRID is output from MODELS.
C
Compare values at t=0 with 3rd subcase.
C deltat
tmax
xopt
copt epsiln tolmat tstart
1.0E-6 3.0E-3
79
C
80
Another way to have access to internal variable values of the ATP program is to
use the special function atp() in an expression inside a model description. This
provides the added advantage of being able to also access elements or array
variables used in the ATP program, which is not possible in the INPUT
declarations of the MODELS section.
MODEL example
...
EXEC
...
step := atp(istep)
estimated_voltage := atp(voltk[2*index])
...
ENDEXEC
ENDMODEL
81
BLANK card ending voltage printout requests
BLANK card ending plot requests
BEGIN NEW DATA CASE
BLANK
The names of these outputs are stored and used by ATP, and are therefore
limited to the 6-character naming convention of ATP. Also, no arrays can be used,
only single outputs.
There is a difference between declaring a MODELS variable as output to the
circuit, and specifying a variable to be recorded for printout and plotting during the
simulation. The latter is done using a RECORD directive, discussed in a separate
section below. Variables declared as outputs of the MODELS section are not
automatically recorded for printout or plotting, unless they are also included in the
RECORD directives of the MODELS section.
No modifications have been made to the format rules of ATP branches, switches,
sources, and machines regarding the use of control variables from TACS or
MODELS. In either case, the keyword TACS used on these cards indicates
control variables coming from a "control system" described outside the circuit,
using either TACS or MODELS, without distinguishing between the two.
Another type of output to ATP can be made directly from inside a model. The
deposit() procedure allows a model to modify the value of any numerical program
variable of ATP that can be changed using ATP's SPY command DEPOSIT. The
ATP documentation of the SPY commands describes what variables can be
modified.
The deposit() procedure can be used to modify the value of single variables and
of single or multiple elements of array variables of the ATP program, using the
following notation:
DEPOSIT( name, value )
DEPOSIT( name[ expr ] , value )
DEPOSIT( name[ expr .. expr ] , value )
82
where name is the name of a program variable accessible from SPY, and where
the index of the array elements can be specified using regular expressions. An
illustration is included in the example used in the previous section.
The names of these variables are stored and used by ATP, and are therefore
limited to the 6-character naming convention of ATP. Also, no array variables can
be used, only single variables.
Values are assigned to these variables in the USE statements of the MODELS
section, on the left-hand side of the output assignments, receiving values from the
outputs of the used models. Note that the outputs of the MODELS section can
also be used for the same purpose as the variables.
The first example adds to the printout list, identified in the list as "MODELS CTRL", the value of an element named control, from a model used at the top level
of the MODELS section with the instance name controller_A.
The second example adds to the printout list, identified as "MODELS - FIELD1",
the variable field from a model used as subuse in a model with instance name
top.
The third example adds to the printout list, idendified as "MODELS - SRC1", the
element named source1 defined as a variable or input or output of the MODELS
section. Note that no instance name is needed in the path, because the element
source1 exists at the top level of the MODELS section, outside of any model
instance.
USERS GUIDE TO MODELS IN ATP
83
The fourth example adds to the printout list, with the label "MODELS - RS", the
element named r from the model named limr used by a type-94 component
connected to the circuit between nodes SRCE and CT1.
Non-existing instance names found in a record path don't trigger an error,
because an instance name starts its existence only at the instant of the simulation
when the associated instance of the model is first used, which is not necessarily
at the initial time of the simulation. It is therefore not an error for the program to
not find a given instance name, as it may simply not have been yet created in the
simulation. The only way to provide a clear indication that the record has an
undefined value would be to be able to assign it the value "undefined", something
like minus zero. And of course we cannot use the undefined value from MODELS
(=88888.88888) because it would affect the scale limits of a plot if we used that
value until the time an actual value starts being assigned to the variable.
Just as foreign models can be declared inside a model (see Foreign submodels),
they can also be declared at the top level of the MODELS section. The notation is
identical to when a foreign model is declared inside a regular model. Here is an
example:
BEGIN NEW DATA CASE
C deltat
tmax
xopt
copt epsiln tolmat tstart
1.
10.
C print points connec
s-s minmax
vary
again
plot
1
1
0
0
0
0
0
0
C ==============================================================================
MODELS STAND ALONE
84
VAR a1, a2, a3
MODEL ftnmodel FOREIGN sample_model {ixdata:1, ixin:3, ixout:3, ixvar:3}
USE ftnmodel AS example
DATA xdata[1]:=3
-- set value of xdata[1]
INPUT xin[1..3]:=[t, t+1, t+2]
-- load inputs xin[1], xin[2], xin[3]
HISTORY xvar[1..3]:=0
-- set history of xvar[..]
OUTPUT a1:=xout[1], a2:=xout[2], a3:=xout[3]
ENDUSE
RECORD example.xdata[1] AS xdata1
example.xin[1]
AS xin1
example.xvar[1] AS xvar1 -- its value after each execution
a1
AS xout1
ENDMODELS
C ==============================================================================
BLANK card ending plot requests
BEGIN NEW DATA CASE
BLANK
In this example, three variables are defined, a1, a2, a3. The foreign model is
declared. One instance of that model is used, identified with the instance name
example. Various values are then recorded during the simulation in the
printout/plotting list of ATP.
To use our own Fortran or C code with ATP, we must link our program with ATP.
The details of this process are dependent on the platform on which we are
running ATP. Typically, we must use the same compiler that the rest of our
version of ATP was compiled on. Then we have to link our compiled file with the
compiled files of ATP using a linker compatible with the compiler(s) that we have
used. For example, for the Salford version of ATP, we can use the Salford
Fortran, C, or Pascal compilers for our routines, and the Salford linker. It also
means that we need all the compiled files of ATP in order to be able to relink them
with the additional files that we create.
85
86
RECORD rl
AS rl
rs.r AS rs
ENDMODELS
C ==============================================================================
91SRCE CT1
TACS RS
{ Variable limiting resistance
CT2
LOAD
0.1
0.2
{ Fixed load R-L
91LOAD
TACS RL
{ Variable load resistance
BLANK card ending branches ----------------------------------------------------CT1
CT2
MEASURING
1
BLANK card ending switches ----------------------------------------------------60SRCE
{ Source driving voltage
BLANK card ending sources -----------------------------------------------------SRCE CT1
87
BLANK card ending voltage printout request ------------------------------------BLANK card ending plot --------------------------------------------------------BEGIN NEW DATA CASE
BLANK
The included file LIMR-USE.M contains the description of the limiting resistance
model, as follows:
MODEL limr
-- limiting resistance
DATA rsmin -- [ohm] min resistance
ilim
-- [ A ] max current
INPUT v
-- [ V ] voltage across terminals
VAR
r
-- [ohm] resistance
OUTPUT r
EXEC
r := abs(v)/ilim {min: rsmin}
ENDEXEC
ENDMODEL
The operation of that model is described in its one-line EXEC procedure, where
the resistance is first calculated to create a current equal to ilim, and is then
limited to be no less than the value specified by rsmin.
For comparison, a version of this circuit is shown using a type-94 component, in
the section below.
{ LIMR-94.DAT }
copt
epsiln
tolmat
tstart
88
C
RECORD rl
AS rl
SRCE__CT1___LIMR__.r AS rs
ENDMODELS
C ============================= Electrical circuit =============================
94SRCE CT1
LIMR ITER
{ Variable limiting resistance
>DATA RSMIN
1.
>DATA ILIM
20.
>END
CT2
LOAD
0.1
0.2
{ Fixed load R-L
91LOAD
TACS RL
{ Variable load resistance
BLANK card ending branches ----------------------------------------------------CT1
CT2
MEASURING
1
BLANK card ending switches ----------------------------------------------------60SRCE
{ Source driving voltage
BLANK card ending sources -----------------------------------------------------SRCE CT1
BLANK card ending voltage printout request ------------------------------------BLANK card ending plot --------------------------------------------------------BEGIN NEW DATA CASE
BLANK
The included file LIMR-94.M contains the description of the limiting resistance
model, as follows:
89
MODEL limr
-- limiting resistance
-- Fixed declarations for a type-94 iterated model ---------------------------DATA n
-- number of node pairs
n2 {dflt: n*n} -- number of matrix elements
INPUT v
-- guessed voltage across terminals 1-2
v0
-- steady-state voltage across terminals 1-2
i0
-- steady-state current into terminal 1
VAR
i
-- calculated current into terminal 1
didv
-- calculated conductance 1-2
OUTPUT i, didv
-- Local declarations --------------------------------------------------------DATA rsmin
-- [ohm] min resistance
ilim
-- [ A ] max current
VAR
r
-- [ohm] resistance
EXEC
r := abs(v)/ilim {min: rsmin}
IF r>rsmin -- if the current is at the limit
THEN didv := 0
ELSE didv := 1/r
ENDIF
i := v/r
ENDEXEC
ENDMODEL
output
solution
assurance
speed
Iterated type-94
input
90
output
solution
assurance
speed
output
91
usage
solution
assurance
speed
output
92
-- i/v=1/sL
-- sum(a0| +a1|x1)
93
Norton:
INIT
st:= 2/timestep
L := L1
g := 1/(st*L)
ENDINIT
EXEC
IF t=0
flag
i
is
ELSE
flag
i
is
ENDIF
ENDEXEC
THEN
:= 1
:= i0
:= -i0 -g*v0
:= 0
:= g*v -is
:= -i -g*v
94
- diffeq(a0|D0 +a1|D1 +...) | y := x
calculates the value of y from a differential equation expressed in terms of the
frequency, i.e.
a0*y + a1*(dy/df) + a2*(d2y/df2) + ... = x
- laplace(y/x) doesn't make any sense in this context
BEGIN NEW DATA CASE
C
BENCHMARK DC-52 with addition of a model and its use
FREQUENCY SCAN, 1.0, 0.0, 15., 2,
1.0
0.0
1
1
1
1
{ Note request for phasor branch flows
C ==============================================================================
MODELS
INPUT v_Re_swit
v_Im_swit
v_Re_load
v_Im_load
i_Re_swit
i_Im_swit
state_swit
{v(swit)}
{imssv(swit)}
{v(load)}
{imssv(load)}
{i(swit)}
{imssi(swit)}
{switch(swit)}
--------
at node SWIT
at node SWIT
at node LOAD
at node LOAD
at switch SWIT
at switch SWIT
(0=open, 1=closed)
INIT
pass:=0
ENDINIT
EXEC
pass:=pass+1
write('************** In models, pass= ', pass)
write('
freq= ', t)
write(' Re{v1}, Im{v1} = ', v_Re_1, ', ', v_Im_1
write(' Re{v2}, Im{v2} = ', v_Re_2, ', ', v_Im_2
write(' Re{i1}, Im{i1} = ', i_Re_1, ', ', i_Im_1
write(' state_1 = ', state_1 )
ENDEXEC
ENDMODEL
-)
)
)
<<===
<<====
USE m1 as m1
INPUT v_Re_1 := v_Re_swit
v_Im_1 := v_Im_swit
v_Re_2 := v_Re_load
v_Im_2 := v_Im_load
i_Re_1 := i_Re_swit
i_Im_1 := i_Im_swit
state_1 := state_swit
ENDUSE
ENDMODELS
C Begin branches ===============================================================
SWIT LOAD
10.
LOAD
1000.
-1SWIT OPEN
.3055 5.82 .012 138.
BLANK card ending all branches
GEN
SWIT
-1.
BLANK card ending all switch cards
14GEN
1.0
0.5
-1.
BLANK card ending source cards
95
GEN
LOAD
BLANK card ends output requests (just node voltages, for FREQUENCY SCAN)
197 .2 0.0 1.6 -20. 60.LOAD angle
BLANK card ending plot cards
BEGIN NEW DATA CASE
BLANK
96
source behind an equivalent impedance, with values obtained from a known
operating point, and then let the simulation build the operation of the circuit to a
more complete frequency contents, from which we can then initiate the transient
behavior we want to study. The better the initial approximation, of course, the
shorter becomes the first stabilizing part of the simulation, but also the more
specific it becomes. The decisions we have to make in this iterative process in
order to reach a satisfactory starting point will, if anything, make us more aware of
the sensitivity of the components we are modeling with respect to the conditions
of their operation.
One more practical point. Models used in the MODELS section with a USE
statement are updated at each time step of the simulation after the solution of the
electrical circuit by ATP at that time step. This is also true at time zero of the
initialization. The steady-state solution of the circuit is done first, then the USE
statements are executed for the first time at t=0. Using inputs such as the real and
imaginary part of currents and voltages of the circuit gives us the possibility to
take into account the steady-state solution of the circuit when initializing the
operating point of the models.
97
or, in fact, doesn't even need a function, because the expression is simple
enough that it can be inserted explicitly in full wherever it needs to be used.
However, a less obvious formulation, like that of the triangular waveform below, is
better described only once in a function definition, and then used as a function call
when it's needed.
The use of a function is possible when the representation of the source is stateless, that is, doesn't carry history between the times when it is called. When
history is carried, then we need to use a model for describing the operation of the
signal source.
Included below are a few commonly-used signal sources. For those examples, if
turn-on and turn-off times need to be added, this can be easily done on the
outside of the function definition. For example, to have a source operating
between t>=t_on and t<t_off, one would use ramp_train(), for example, as:
signal := (t >= ... AND t < ...)*ramp_train(100, 1e-4, 0)
where the value of the logical expression is taken as numerical "1" when the
expression is true, and zero otherwise, multiplied by the rest of the expression.
98
FUNCTION single_pulse(ampl, width, tstart)
:= ampl*(t>=tstart AND t<tstart+width)
comment --------------------------------------------| ampl
: [ ] on-value of pulse (off-value is 0)
|
| width : [s] width of pulse
|
| tstart : [s] pulse start time
|
| pulse starts at t=tstart and lasts "width" seconds |
------------------------------------------ endcomment
Refer to the sample model "test_sources" below to see how this and the following
functions can be used.
The next example is simplified when using a function call. It is easier to call the
function with its four arguments, than to have to figure out how to use the modulo
operator each time the signal needs to be generated. The function generates a
sequence of pulses of a specified amplitude, width, and period, with the beginning
of the reference period (the phase, in seconds) shifted to a specified time:
FUNCTION pulse_train(ampl, width, period, tshift)
:= ampl*(((t-tshift+period) MOD period) < width)
comment --------------------------------------------------| ampl
: [ ] on-value of each pulse (off-value is 0)
|
| width : [s] width of each pulse
|
| period : [s] period of each pulse (on_time + off_time)
|
| tshift : [s] period shift time
|
| the beginning of the period is shifted by "tshift" sec
|
| each pulse is on for "width" seconds
|
| pulses are repeated every "period" seconds
|
------------------------------------------------ endcomment
The next function shows a simple ramp of specified maximum amplitude and
width, starting at a specified starting time:
FUNCTION single_ramp(ampl, width, tstart)
:= ampl/width*(t-tstart)*(t>=tstart AND t<tstart+width)
comment -------------------------------------------| ampl
: [ ] amplitude of ramp
|
| width : [s] width of ramp
|
| tstart : [s] ramp start time
|
| ramp starts at t=tstart and lasts "width" seconds |
----------------------------------------- endcomment
The next function generates a train of ramps of specified amplitude and width,
with the beginning of the reference period (the phase, in seconds) shifted to a
specified time. In this example, there is no dead zone, and the period is equal to
the width:
FUNCTION ramp_train(ampl, width, tshift)
:= ampl/width*((t-tshift+width) MOD width)
comment --------------------------------------------------| ampl
: [ ] amplitude of ramp
|
| width : [s] widthor period of each ramp
|
| tshift : [s] period shift time
|
| the beginning of the period is shifted by "tshift" sec
|
| each ramp is on for "width" seconds
|
| ramps are repeated every "width" seconds
|
------------------------------------------------ endcomment
99
The next function generates a triangular wave of specified amplitude and period,
in phase with a cosine shifted to a specified time. The value of the third argument
is calculated once when calling the function, and is used many times inside the
function. That value is specified as the expression:
(t - tshift + period) MOD period
using values for a specified period and shift time.
FUNCTION triang(ampl, per, tmodT)
:= ampl*4/per*((tmodT/per<0.5)*(-tmodT+0.25*per)
+(tmodT/per>=0.5)*(tmodT-0.75*per))
comment -----------------------------------------------------------| ampl
: [ ] amplitude of triangular waveform
|
| per
: [s] period of waveform
|
| tmodT : [s] pre-calculated value of (t-tshift+period) MOD period |
|
where tshift : [s] period shift time
|
| the beginning of the period is shifted by "tshift" sec
|
| value at start of period is positive maximum, like cosine
|
--------------------------------------------------------- endcomment
100
ENDMODEL
-------------------------------------------------------------------- Model uses:
USE test_sources AS test
ENDUSE
----------------------------------------------------- Printed/plotted variables:
RECORD test.pulse
AS pulse
test.pulsetrain AS pulset
test.ramp
AS ramp
test.ramptrain AS rampt
test.tri
AS tri
ENDMODELS
C ==============================================================================
BLANK card ending plot requests
BEGIN NEW DATA CASE
BLANK
cr_add(ar,ai,br,bi)
cr_sub(ar,ai,br,bi)
cr_mul(ar,ai,br,bi)
cr_div(ar,ai,br,bi)
:=
:=
:=
:=
[ar+br, ai+bi]
[ar-br, ai-bi]
[ar*br-ai*bi, ar*bi+ai*br]
[ar*br+ai*bi, ai*br-ar*bi]*recip(br*br-bi*bi)
101
The next group of functions shows multiplication and division of complex numbers
expressed in polar coordinates. It also shows how easily the power and root
operations can be expressed:
comment --------------------------------------------------------------| operations on complex numbers using polar coordinates
|
|
where a[1..2]=[am,aa]: am=magnitude of A, aa=angle of A in radians |
|
and
b[1..2]=[bm,ba]: bm=magnitude of B, ba=angle of B in radians |
|
|
| complex polar multiplication, division, powern, rootn
|
------------------------------------------------------------ endcomment
FUNCTION
FUNCTION
FUNCTION
FUNCTION
cp_mul(am,aa,bm,ba)
cp_div(am,aa,bm,ba)
cp_powern(n,am,aa)
cp_rootn(n,am,aa)
:=
:=
:=
:=
[am*bm, aa+ba]
[am/bm, aa-ba]
[am**n, n*aa]
[am**(1/n), aa/n]
The following pair of functions provide conversions between rectangular and polar
coordinates:
comment -----------------------------------------------------------------| conversion between rectangular and polar coordinates of complex numbers |
|
where a[1..2]=[am,aa]: am=magnitude of A, aa=angle of A in radians
|
|
and
b[1..2]=[br,bi]: br=real part of B, bi=imaginary part of B
|
--------------------------------------------------------------- endcomment
FUNCTION cpr_conv(am,aa) := [am*cos(aa), am*sin(aa)]
FUNCTION crp_conv(br,bi) := [norm(br,bi), atan2(bi,br)]
These functions are ready to be used in a model. For example, given the real
variable r, and the array variables c, d, e, f, where:
c[1..2]
d[1..2]
e[1..2]
f[1..2]
c+d
c-d
r*c
y[1..2] := r * c[1..2]
c*d
c/r
y[1..2] := c[1..2] / r
c/d
e*f
102
e/f
e ** n
e root n
polar to rect
y[1..2] := cpr_conv(e[1..2])
rect to polar
y[1..2] := crp_conv(c[1..2])
103
104
USE fmeter AS
DATA
f0
band
INPUT x
OUTPUT ____
ENDUSE
local_name
:= ___________
:= ___________
:= __________
:= f
in Hertz
in percent
When the condition is true, the function returns the value input * 1 . When the
condition is false, the function returns the value input * 0 .
When the condition is true, the function returns the value input * 1 . When the
condition is false, the function returns the value input * 0 . Functions like this one
are so simple that it is as easy to use the expression directly in a model as it is to
create and call a function.
105
106
IF t-toff >= delay_val THEN out:=0 state:=0 ENDIF
IF x>0 THEN
ton:=t
IF state=0 THEN state:=1
ELSE state:=6
ENDIF
ENDIF
ELSIF state = 6 THEN
IF t-toff >= delay_val THEN out:=0 state:=1 ENDIF
IF x<=0 THEN
toff:=t
IF state=1 THEN state:=3 ENDIF
ENDIF
ENDIF
ENDEXEC
ENDMODEL
somename
:= __________ in seconds (optional)
:= __________ in seconds (optional)
:= __________
:= __________ in seconds
:= out
Long models like this one would execute faster by being pre-compiled. One
approach would be to write it in C or in Fortran, and link it with ATP. Then, all we
need to put in this library is the following, replacing the above INIT and EXEC
procedures of the model by a call to the foreign model.
MODEL pulse_delay
DATA
ton_ini {dflt:-9999} -- initial value of
toff_ini {dflt:-9999} -- initial value of
INPUT x
-- input signal
delay_val -- variable delay value
VAR
out
-- delayed pulse
MODEL compiled_pulse_delay FOREIGN C_pulse_delay
{ixdata:2, ixin:2, ixout:1, ixvar:4}
EXEC
USE compiled_pulse_delay AS pdelay
DATA
xdata[1..2] := [ton_ini, toff_ini] -INPUT xin[1..2]
:= [x, delay_val]
-OUTPUT out
:= xout[1]
-ENDUSE
ENDEXEC
ENDMODEL
107
This function is then used with the interpolation degree set at zero, resulting in
level steps between the defined points on the line:
y := digitizer( signal, 0)
and using the function with the default interpolation degree of one:
y := point_by_point( signal)
The function is used with an interpolation degree of zero, and is multiplied by the
value of the input signal.
y := signal * time_seq_switch(t)
A control signal determines when the output is reset to a specified reset value.
Both operations are included in the simple model below. The model also accepts
an initial value:
108
MODEL type_58
DATA
out_ini {dflt:0}
-- initial value of out
gain
{dflt:1}
-- function gain
d0
{dflt:0}
-- denominator coefficient of s0
d1
{dflt:1}
-- denominator coefficient of s1
INPUT x
-- input signal
control {dflt:1}
-- apply function when positive, else reset
reset_value {dflt:0}
-- used on reset
VAR
out
-- function output
OUTPUT out
INIT
out := out_ini
ENDINIT
EXEC
IF control<=0 THEN out:=reset_value
ELSIF t>=timestep THEN LAPLACE(out/x):=(gain|s0)/(d0|s0 + d1|s1)
ENDIF
ENDEXEC
ENDMODEL
________
________
________
________
________
________
________
out
(optional)
(optional)
(optional)
(optional
(optional)
(optional)
One may wonder why the above expression did not use the built-in function
deriv() of MODELS as follows:
y := gain * deriv(x)
109
selector
selector
selector
selector
selector
selector
selector
<
<
<
<
<
<
<
0.5
1.5
2.5
3.5
4.5
5.5
6.5
THEN
THEN
THEN
THEN
THEN
THEN
THEN
out:=i0
out:=i1
out:=i2
out:=i3
out:=i4
out:=i5
out:=i6
out:=i7
110
MODEL sample_hold
DATA
out_ini {dflt:0} -- initial value of out
INPUT x
-- sampled signal
sample_control
-- triggers sampling on rising positive front
VAR
out
state -- 0= waiting for control>0
-- 1= waiting for control<=0
OUTPUT out
INIT
state := 0
out
:= out_ini
ENDINIT
EXEC
IF
state = 0 AND sample_control > 0 THEN state:=1 out:=x
ELSIF state = 1 AND sample_control <= 0 THEN state:=0
ENDIF
ENDEXEC
ENDMODEL
The track/hold device passes the value of the input signal when the control signal
is positive, and holds its most recent value when the control signal is not positive.
The only reason why this device needs to be represented as a model rather than
as a function is that we need to carry a value from one time step to the next, the
value last-held by the output variable.
MODEL track_hold
DATA
out_ini {dflt:0} -- initial value of out
INPUT x
-- tracked signal
track_control
-- tracks when positive
VAR
out
OUTPUT out
INIT
out := out_ini
ENDINIT
EXEC
IF track_control > 0 THEN out:=x ENDIF
ENDEXEC
ENDMODEL
Notice that we do not need to specify an ELSE clause in the IF statement. The
complete IF statement could be written as:
IF track_control > 0 THEN out:=x
ELSE out:=out
ENDIF
but by default, any variable of a model maintains its value until it is changed to
another value, so writing out := out is redundant.
The track/hold model can be used as follows:
111
USE track_hold AS somename
DATA
out_ini
:= ________ (optional)
INPUT x
:= ________
track_control := ________
OUTPUT _____________ := out
ENDUSE
where each argument can be an entire expression, not only the name of a
variable, just as for any function in MODELS except the built-in simulation
functions (deriv, prevval, etc.).
112
MODEL mintrack_hold
DATA
out_ini {dflt:inf}
-- initial value of out, defaulted to +infinity
INPUT x
-- tracked signal
hold_control {dflt:0} -- holds when positive
reset_control {dflt:0} -- resets when positive
reset_value
{dflt:0} -- used on reset
VAR
out
OUTPUT out
INIT
IF out_ini = inf THEN out := x
ELSE out := out_ini
ENDIF
ENDINIT
EXEC
IF reset_control > 0
THEN out:=reset_value
ELSIF hold_control <= 0 THEN out:=min(x,out)
ENDIF
ENDEXEC
ENDMODEL
There are two details to notice. First, the reset control signal has priority over the
hold control signal. The second is that we do not need to specify the third clause
of the IF statement to indicate that the output value maintains its value when the
two other conditions are not true, as this is done by default.
This model can be used as follows:
USE mintrack_hold AS somename
DATA
out_ini
:= ________
INPUT x
:= ________
hold_control := ________
reset_control := ________
reset_value
:= ________
OUTPUT _____________ := out
ENDUSE
(optional)
(optional)
(optional)
(optional)
The maximum track/hold model is similar, except for the value of the initial
condition:
MODEL maxtrack_hold
DATA
out_ini {dflt:-inf}
-- initial value of out, defaulted to -infinity
INPUT x
-- tracked signal
hold_control {dflt:0} -- holds when positive
reset_control {dflt:0} -- resets when positive
reset_value
{dflt:0} -- used on reset
VAR
out
OUTPUT out
INIT
IF out_ini = -inf THEN out := x
ELSE out := out_ini
ENDIF
ENDINIT
EXEC
IF reset_control > 0
THEN out:=reset_value
ELSIF hold_control <= 0 THEN out:=max(x,out)
ENDIF
ENDEXEC
ENDMODEL
113
USE maxtrack_hold AS unique_name_in_your_model
DATA
out_ini
:= ________ (optional)
INPUT x
:= ________
hold_control := ________ (optional)
reset_control := ________ (optional)
reset_value
:= ________ (optional)
OUTPUT _____________ := out
ENDUSE
(optional)
(optional)
(optional)
(optional)
114
MODEL rms_meter
DATA
freq
-- base frequency
xrms_ini {dflt:-1} -- initial rms value
INPUT x
-- monitored signal
VAR
xrms
-- rms value of monitored signal
x2
-- internal, x*x
ix2
-- internal, integral of x2
period
-- 1/freq
OUTPUT xrms
DELAY CELLS(ix2): 1/freq/timestep +1
INIT
period
:= recip(freq)
histdef(ix2) := 0
integral(x2) := 0
IF xrms_ini <0 THEN xrms:=0 ELSE xrms:=xrms_ini ENDIF
ENDINIT
EXEC
x2 := x*x
ix2 := integral(x2)
IF t>period THEN
xrms := sqrt((ix2 - delay(ix2, period))/period)
ENDIF
ENDEXEC
ENDMODEL
Using a pre-determined fixed period keeps the model simple. A more complete
rms meter would allow for variable period and arbitrary dc bias.
The above model can be used as follows:
USE rms_meter AS unique_name_in_your_model
DATA
freq
:= _______ in Hz
xrms_ini := _______ (optional)
INPUT x
:= _______ in any units
OUTPUT ________ := xrms
ENDUSE
115
116
record element
declaration in a model
constant element
data element
input element
output element
variable element
function
submodel
117
declaration of a function
statement function
point list function
foreign function
118
declaration of a submodel
local model
foreign model
external model
history directive
119
Procedure in a model
initialization procedure
execution procedure
named procedure
initialization procedure
execution procedure
named procedure
120
Statement
assignment statement
algorithm control statement
assignment statement
value assignment
differential equation
Laplace transfer function
z transfer function
integral value reset assignment
history assignment
value assignment
differential equation
y, x
D-polynomial
121
limits
y, x
S-polynomial
limits
z transfer function
ZFUN(y / x) := (z-1-polynomial) / (z-1-polynomial)
CZFUN(y / x) := (z-1-polynomial) / (z-1-polynomial)
ZFUN(y / x) { limits } := (z-1-polynomial) / (z-1-polynomial)
CZFUN(y / x) { limits } := (z-1-polynomial) / (z-1-polynomial)
122
y, x
z-1-polynomial
limits
history assignment
123
IF statement
WHILE statement
FOR statement
DO statement
REDO statement
DO ... REDO ... ENDDO
COMBINE statement
COMBINE AS identifier statement-list ENDCOMBINE
COMBINE ITERATE AS identifier statement-list ENDCOMBINE
COMBINE ITERATE { max-iter } AS identifier statement-list
ENDCOMBINE
124
ERROR statement
USE statement
procedure call
instance.procname(arg-list)
WRITE(write-list)
WRITE1(write-list)
WRITE2(write-list)
write-list
125
126
Expression
regular expression
sum expression in a value assignment
derivative expression in a value assignment
integral expression in a value assignment
regular expression
regular expression
regular expression { limits }
Regular expression
127
logical term
logical factor
logical relation
num-expr rel-op num-expr
relational operators
>, >=, <, <=, =, <>
numerical expression
numerical term
numerical factor
exponent relation
value reference ** value reference
128
modulo relation
value reference MOD value reference
value reference
numerical value
array value
named value
function value
129
Value-holding element
single-value element
array-value element
single-value element
array-value element
Syntactic element
name
numerical value
logical value
text value
in-ine comment
block comment
separator
name
numerical value
130
logical value
true/false, on/off, closed/open, yes/no
text value
"text" or 'text'
in-line comment
start: two or more contiguous hyphens (hyphen string)
end: end of line
block comment
separator
commas, semicolons, white-space characters
131
start/end
MODELS ... ENDMODELS
element declarations
INPUT ... { type( ... ) }
type: v, i, switch, mach, imssv, imssi, tacs, pl4, atp
OUTPUT...
VAR ...
model declarations
MODEL ... ENDMODEL
MODEL ... FOREIGN ... { IXDATA: ... IXIN: ... IXOUT: ... IXVAR: ... }
use directives
USE ... ENDUSE
record directives
RECORD ... AS ...
132
start/end
MODEL ... ENDMODEL
element declarations
CONST ... { VAL: ... }
DATA ... { DFLT: ... }
INPUT ... { DFLT: ... }
OUTPUT ...
VAR ...
function declarations
FUNCTION ... := ...
FUNCTION ... POINTLIST ( ... , ... ) ( ... , ... ) ...
FUNCTION ... FOREIGN ... { IXARG: ... }
submodel declarations
MODEL ... ENDMODEL
MODEL ... FOREIGN ... { IXDATA: ... IXIN: ... IXOUT: ... IXVAR: ... }
MODEL ... EXTERNAL
simulation directives
HISTORY ... { DFLT: ... }
HISTORY INTEGRAL( ... ) { DFLT: ... }
TIMESTEP MIN: ... MAX: ...
INTERPOLATION DEGREE ( ... ) : ...
INTERPOLATION DEGREE DFLT: ...
DELAY CELLS ( ... ) : ...
DELAY CELLS DFLT : ...
133
procedures
INIT ... ENDINIT
EXEC ... ENDEXEC
PROC ... ENDPROC
assignment statements
... := ...
DIFFEQ( ... ) | ... { DMIN: ... DMAX: ... } := ...
CDIFFEQ( ... ) | ... { DMIN: ... DMAX: ... } := ...
LAPLACE( ... ) | ... { DMIN: ... DMAX: ... } := ...
CLAPLACE( ... ) | ... { DMIN: ... DMAX: ... } := ...
ZFUN( ... ) | ... { DMIN: ... DMAX: ... } := ...
CZFUN( ... ) | ... { DMIN: ... DMAX: ... } := ...
INTEGRAL( ... ) := ...
HISTDEF( ... ) := ...
134
135
136
Pre-defined constants
The pre-defined constants have pre-assigned values, and can be used inside any
expression, in any model of a simulation. They are:
pi
3.14159...
inf
undefined
88888.88888
false, true
no, yes
open, closed
off, on
The infinity value inf is dependent on the computer platform being used. The
value undefined is the value carried by any variable that has not yet been
assigned a value during a simulation. The value of the logical constants are
represented internally as the numerical values 0 and 1.
stoptime
137
startstep
The values of starttime and startstep are set at the start of the simulation. The
value of stoptime is defined by the application controlling the simulation, and may
change during a simulation.
prevtime
timestep
endtime
fullstep
minstep
maxstep
These variables carry information about how the state of a model is updated from
a previous simulation time to a target simulation time, on each update call to a
model instance from a USE statement.
In a case where timestep, the time step used in the called model, is the same size
as fullstep, the calling interval, which is also the time step of the calling model, the
relationship between these variables is simple:
endtime
t0
fullstep
timestep
138
In a case where fullstep is smaller than minstep, the model instance does not
update itself to the outside time, because the time increase is considered to be
too small to change the present state of the model significantly. The model waits
until endtime - t0 >= minstep to update its state, in one large time step.
endtime
t0
fullstep
fullstep
fullstep
timestep
In a case where fullstep is larger than the largest time step allowed maxstep, the
full step is subdivided into sub-steps of a size that satisfies the maxstep upper
limit, and the model instance is executed for each sub-step successively, until the
target time endtime is reached. Only then is control passed back to the calling
model, along with the model's output values at time t = endtime. For this case, the
relationship between the variables is as follows:
endtime
t0
fullstep
timestep
timestep
t
timestep
139
Numerical functions
This is a list of all the pre-defined functions that return numerical values. They are
grouped as one-to-one functions, two-argument functions returning a single value,
and n-argument functions returning a single value.
abs(a, b)
abs(expression list)
abs(x[1..2])
abs(a, x[1..2])
abs(array expression)
absolute value
sqrt( )
square root
exp( )
exponential
ln( )
natural log
140
log10( )
base 10 log
log2( )
base 2 log
recip( )
protected division
factorial( )
factorial
trunc( )
integer part
fract( )
fractional part
round( )
rounding
sign( )
sign function
rad( )
degrees to radians
deg( )
radians to degrees
trigonometric
arg in radians
inverse trigonometric
hyperbolic
arg in radians
inverse hyperbolic
-1 if <0; 0 if 0; +1 if >0
4-quadrant arctan(a/b)
binom( )
returns n! / (n-r)! r!
permut( )
returns n! / (n-r)!
141
minimum value
max( )
maximum value
norm( )
returns sqrt(sum(arg2)))
Logical functions
This is a list of all the pre-defined functions that return logical values. They are
grouped as one-to-one functions, and n-argument functions returning a single
value.
The logical values true and false are represented in MODELS by the numerical
values 1 and 0. Conversion between numerical and logical values is automatic,
and is determined by the context in which they are used. This allows numerical
values to be used in a logical context ( >0 is true, <=0 is false ), and logical values
to be used in a numerical context ( true is 1, false is 0 ).
numerical to logical
142
Here are examples showing how the function can be used:
bool(a)
bool(expression)
bool(a, b)
bool(expression list)
element
bool(x[1..2])
bool(a, x[1..2])
bool(array expression)
logical AND
or( )
logical OR
nand( )
nor( )
logical NOT OR
xor( )
logical exclusive OR
random value
The sequence of random numbers generated from repeated calls to the function
random() is reproducible from one simulation run to the next. To generate nonreproducible sequences requires a call by the program to the date/time routine of
the computer's operating system. In the present Fortran version of MODELS, this
143
is not available, because Fortran doesn't provide a standard function for doing
this. When provided, it is compiler-dependent. In the future C version of
MODELS, it will be available, because C provides a standard compilerindependent function for this.
In the meantime, two foreign C functions have been pre-linked to ATP: C_seed()
to generate a new seed, and C_random() to generate a sequence of random
numbers based on that seed. C_seed(x) uses a dummy argument of any value. It
returns no value. C_random(x) uses a dummy argument of any value. It returns a
value between 0 and 1. The use of these functions does not affect the sequence
of numbers generated by the MODELS function random().
The source code for the two C functions is the following:
#include <stdlib.h>
double C_SEED(void)
/* randomly seeds the C library function rand() */
{ date_time_seed();
return 0;
}
double C_RANDOM(void)
/* returns a random number between 0 and 1 */
{ return (double)rand()/(double)RAND_MAX;
}
where the names C_SEED and C_RANDOM are already registered in subroutine
fgnfun in the file named fgnmod.for of ATP.
After being declared in a model, the functions can then be used as in the following
example:
INIT
dum := seed(0)
expression
...
ENDINIT
EXEC
...
y := x * rand(0)
...
ENDEXEC
144
Simulation functions
MODELS provides special simulation functions not available in regular
programming languages, for the fact that they make an implicit reference to the
advancing value of time and to the accumulated history of the variables to which
they are applied. These are functions such as derivative, previous value, etc, as
shown below.
When using the simulation functions, the first argument in the argument list is
always a single value-holding element, for example x, or y[n], and is never an
expression. This is because an expression has no history which can be referred
to when calculating the value of the function.
Some simulation functions require a second argument, for example, the value of
the delay applied to a variable.
All 2-argument functions, except histval(), accept an optional third argument to
indicate the interpolation method used by the function. Only the values 0, 1, and 2
are recognized for this, indicating respectively: no interpolation (the signal varies
in steps), linear interpolation, and quadratic interpolation. Linear interpolation is
the default, and the "1" can always be omitted.
The simulation functions are:
deriv(x)
deriv2(x)
prevval(x)
delay(x, dval)
delay(x, dval, pol)
predval(x, tval)
predval(x, tval, pol)
predtime(x, xval)
predtime(x, xval, pol)
backval(x, tval)
backval(x, tval, pol)
backtime(x, xval)
backtime(x, xval, pol)
histval(x, tval)
histdef(x)
145
deriv(x)
The time derivative of x is calculated with the assumption that it is linear over
each time step interval, that is, that the second derivative is constant over the
interval. The program first calculates the two mid-step derivatives
deriv0.5 =
x(t 0 ) x(t1)
t 0 t1
deriv15
. =
x(t1) x(t 2)
t1 t 2
deriv0.5 deriv15
.
t0.5 t15
.
which is then used to extrapolate linearly the first mid-step derivative, deriv0.5, to
the end of the interval, using the second derivative as its slope:
derivt 0 = deriv0.5 + deriv 2t1
t 0 t1
2
When the time step is small enough to cover the higher frequencies of the signal,
this method is more accurate than using the simple mid-step derivative.
However, the mid-step derivative is less sensitive to discontinuities, and should be
used instead of deriv() when the time step is not well matched to the frequency
contents of the signal, by doing:
y:=(x-prevval(x))/timestep
deriv2(x)
The second order derivative of x with respect to time, d2x/dt2, is calculated as the
mid-step derivative of the first derivative, itself calculated at mid-step for the last
two intervals. The method takes into account the possibility for the time step to be
variable.
The second derivative is calculated using:
146
deriv0.5 deriv15
.
t0.5 t15
.
t 0 t1
t1 t 2
t 0 + t1 t1 + t 2
2
2
When the time step is constant, this is equivalent to calculating the second
derivative as:
x(t ) 2 x(t t ) + x(t 2 t )
t 2
It must be observed that the calculated value is in fact the value of the second
derivative at the previous time t1, because of the mid-step method. This means
that the value of the second derivative at time t is available only after a delay of
one time step.
The second derivative of a variable can be used in any expression, for example:
y:=deriv2(x)
prevval(x)
This function returns x(t-t), the value of a variable at the previous time step. It
can be used in any expression, for example:
y:=prevval(x)
Static limits can be applied as part of the expression where the function is used:
y:=prevval(x) {min:expression, max:expression}
147
When that requested past time falls before the start of the simulation, that is,
before the value of the variable could started being tracked, the delay() function
uses the history expression associated with that variable to calculate the past
value, and returns the value histval(x, t-dval).
When the requested past time falls after the start of the simulation, where tracked
values of the variable are available, interpolation is used for cases where the
value t-dval does not correspond exactly to one of the discrete instants of the
simulation. By default, when the third argument is not specified, linear
interpolation is used. Otherwise, the pol argument can be given a value of 0, 1, or
2, for step, linear, or quadratic interpolation.
Using the delay function can require a considerable amount of storage for keeping
track of the past values of a variable (see the simulation directive DELAY CELLS).
However, the calculation is fast, as it uses a binary search to locate the stored
values.
148
access to past values beyond the previous step, we need to use the delay()
function.
At the first step of a simulation, the requested past time will fall before the start of
the simulation, that is, before the value of the variable could started being tracked.
In this case, the backval() function uses the history expression associated with
that variable to calculate the past value, and returns the value histval(x, tval).
When the requested past time falls after the start of the simulation, where tracked
values of the variable are available, interpolation is used for calculating the value
of the variable between the simulation points. By default, when the third argument
is not specified, linear interpolation is used. Otherwise, the pol argument can be
given a value of 0, 1, or 2, for step, linear, or quadratic interpolation.
histval(x, tval)
This function uses the history expression specified for the variable x in order to
calculate the value of x(tval). No interpolation is needed, because the history
expression will provide a value calculated at t equal to tval. Although a history
expression is intended to be used for calculating values of a variable at values of t
preceding the start of the simulation, the histval() function can be used without
any restriction on the value of tval. See the section on simulation directives for a
discussion on assigning a history expression to a variable.
histdef(x)
Using this function is equivalent to using histval(x,t). For whatever value of t, this
function will return the corresponding value of the history expression associated
with the variable x. At first look, this may seem useless. It becomes more
interesting when we consider that during the simulation, the solver manipulates
the value of the variable t behind the scenes whenever it needs to evaluate a
149
history expression at a certain time t. Using the function histdef(x) inside the
expression defining the history expression of another variable y gives us a way to
make a history expression dependent on the history expression defined for
another variable. For example, we would use it in a history declaration as follows:
HISTORY y {dflt: histdef(x) - 2*histdef(w)}
In each case, it would have been equivalent to write the expression of the history
expression as:
histval(x,t) - 2*histval(w,t)
150
BIBLIOGRAPHY
This bibliography provides a list of published articles describing or referring to the
MODELS language.
"The EMTP's new TACS",
L. Dub (DEI Simulation Software, Oregon, USA),
G. Bortoni, I. Bonfanti (CESI, Milano, Italy)
Paper 89-11, 16th european EMTP Meeting,
Dubrovnik (Yugoslavia), May 1989
"Development of a new three-phase synchronous machine code using MODELS",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain),
G.A. Capolino (Mediterranean Inst. Tech., Marseille, France),
G. Bortoni (CESI, Milano, Italy)
Paper 90-M3, 18th European EMTP Meeting,
Marseille (France), May 1990.
"TACS and MODELS: Drive simulation languages in a general purpose program",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain),
G.A. Capolino (Mediterranean Inst. Tech., Marseille, France)
Proc. MCED '91, Marseille (France), July 1991.
"Aplicaciones del cdigo MODELS",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain)
2as. Jornadas Luso-Espanholas de Engenharia Electrotecnica,
Coimbra (Portugal), July 1991.
"MODELS: A new simulation tool in the EMTP",
L. Dub (DEI Simulation Software, Oregon, USA),
I. Bonfanti (CESI, Milano, Italy)
European Transactions on Electrical Power Engineering,
Vol. 2, no. 1, pp. 45-50, Jan/Feb 1992.
"Variable capacitance and inductance in ATP using MODELS",
L. Dub (DEI Simulation Software, Oregon, USA),
B.A. Mork (No. Dakota Univ, USA)
EMTP News, Vol. 5, no. 1, Leuven (Belgium), March 1992.
"Simulation of a microprocessor-controlled SVC",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain)
Paper 92-013, 21st European EMTP Meeting,
Crete (Greece), June 1992
"Implementation of a 6-phase synchronous machine model [...] using EMTP MODELS",
H. Knudsen (ELKRAFT Power Co, Ballerup, Denmark)
Paper 92-R-014, 22nd European EMTP Meeting,
Leuven (Belgium), November 1992.
"Modelling a generator relay protection scheme in EMTP using MODELS",
N. Gstavsen, J. Rnne-Hansen (Tech. Univ. Denmark, Lingby, Denmark),
S. Stvring-Hallsson (ELKRAFT Power Co, Ballerup, Denmark)
Paper 92-R-006, 22nd European EMTP Meeting,
Leuven (Belgium), November 1992.
151
"Educational use of EMTP MODELS for the study of rotating machine transients",
J.A.Martinez-Velasco (Univ. Politcnica Catalunya, Spain)
IEEE PES Winter Power Meeting, Paper 93 WM 126-3-PWRS,
Columbus (USA), February 1993
"Connection of user-supplied programs to EMTP using MODELS",
L. Dub (DEI Simulation Software, Oregon, USA)
EMTP News, Vol. 6, no. 1, Leuven (Belgium), March 1993.
"A 6.3 KV vacuum breaker model for ATP simulations",
J. Kosmac, P. Zunko (Ljubljana Univ., Slovenia)
First European Conference on Power Systems Transients,
Lisbon (Portugal), June 1993.
"EMTP simulation of source-insulator interaction in pollution tests",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain)
First European Conference on Power Systems Transients,
Lisbon (Portugal), June 1993.
"Power swing simulation studies, measurement of power flow and voltage phasor
oscillation at any point of the simulated system using MODELS",
A. Mechraoui, D.W.P. Thomas (Univ. of Nottingham, UK)
First European Conference on Power Systems Transients,
Lisbon (Portugal), June 1993.
"Using the simulation language MODELS with EMTP",
L. Dub (DEI Simulation Software, Oregon, USA),
I. Bonfanti (CESI, Milano, Italy),
M.T. Correia de Barros (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal),
V. Vanderstockt (LABORELEC, Belgium)
Proc. 11th Power Systems Computation Conference, pp. 1063-1069,
Avignon (France), August 1993.
"Utilizing the frequency scan feature of ATP-EMTP",
M. Kizilcay (Lahmeyer Int'l, Frankfurt, Germany)
European EMTP User Group Meeting,
Lingby (Denmark), April 1994
"Modelling of a travelling wave phase selector for EHV transmission lines",
M.S. Jones, D.W.P. Thomas (Univ. of Nottingham, UK)
European EMTP User Group Meeting,
Lingby (Denmark), April 1994
"Grounding system simulation by means of ATP MODELS",
W. Kalat, M. Loboda, Z. Pochanke (Warsaw Tech. Univ., Poland)
European EMTP User Group Meeting,
Lingby (Denmark), April 1994
"Including a transmission line with corona in ATP using MODELS",
M.T. Correia de Barros, M.E. Almeida (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal),
L. Dub (DEI Simulation Software, Oregon, USA)
European EMTP User Group Meeting,
Lingby (Denmark), April 1994
152
"Tower modelling for lightning surge analysis using EMTP",
M.E.Almeida, M.T. Correia de Barros (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal)
European EMTP User Group Meeting,
Lingby (Denmark), April 1994
"EMTP simulation of a digitally-controlled static VAR system for optimal load
compensation",
J.A. Martinez (Univ. Politcnica Catalunya, Spain)
IEEE PES Summer Power Meeting, paper 94 SM 452-3 PWRD,
San Francisco (USA), July 1994.
"As EMTP Study of SSR Mitigation Using the Thyristor Controlled Series Capacitor",
W. Zhu et al. (Oregon State University, Corvallis, Oregon, USA)
IEEE PES Summer Power Meeting, paper 94 SM 477-0 PWRD,
San Francisco (USA), July 1994.
"Using the Electromagnetic Transient Program for frequency scans",
G.T. Wrate, B.A. Mork (Michigan Tech. Univ., USA),
K.K. Mustaphi, S.P. Dellwo (Northern States Power Co., Minneapolis, USA)
MIPSYCON, Oct 1994.
"Transient analysis of rotating machines using EMTP MODELS",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain)
1995
"Inclusion of corona in the evaluation of surge propogation with EMTP",
M.T. Correia de Barros, M.E. Almeida (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal),
L. Dub (DEI Simulation Software, Oregon, USA)
International Symposium on Electric Power Engineering - Stockholm Power Tech 95,
Paper No. SPT HV 07-04-0253,
Stockholm (Sweden), June 1995.
"Representacion avanzada de interruptores mediante el EMTP",
J.A. Martinez-Velasco (Univ. Politcnica Catalunya, Spain)
Porto (Portugal), July 1995.
"Computation of Electromagnetic transients on nonuniform transmission lines",
M.T. Correia de Barros, M.E. Almeida (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal),
IEEE PES Summer Power Meeting,
Portland, July 1995.
"Interfacing with EMTP a general-purpose transmission line model",
M.T. Correia de Barros, M.E. Almeida (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal),
L. Dub (DEI Simulation Software, Oregon, USA),
B. Stein (FGH, Mannheim, Germany)
Int'l Conf. on Power systems Transients (IPST ' 95),
Lisbon, Portugal, Sept 1995.
"Including a wind energy conversion system model in electromagnetic transients
program",
F. A. G. S. Reis, R. M. G. Castro (IST/Univ. Tcnica de Lisboa, Lisbon, Portugal),
A. I. L. Estanqueiro, J. M. Ferreira de Jesus (INETI / ITE, Lisbon, Portugal)
Int'l Conf. on Power systems Transients (IPST ' 95),
Lisbon, Portugal, Sept 1995.
153
"Tripping analysis of generator negative sequence relay during a transformer
energization",
M. F. Ushikubo, A. Bichels (COPEL, Curitiba, Brazil)
Int'l Conf. on Power systems Transients (IPST ' 95),
Lisbon, Portugal, Sept 1995.
"Fault arc modeling in EMTP",
J. Sousa, D. Santos, M. T. Correia de Barros (IST/Univ. Tcnica de Lisboa, Lisbon,
Portugal)
Int'l Conf. on Power systems Transients (IPST ' 95),
Lisbon, Portugal, Sept 1995.
"Advanced representation of power semiconductors using the EMTP",
J.A. Martinez-Velasco (Univ. Politcnica de Catalunya, Barcelona, Spain),
R. Abdo (Univ. Aix-Marseille II, Marseille, France),
G.A. Capolino (Univ. de Picardie, Amiens, France)
Int'l Conf. on Power systems Transients (IPST ' 95),
Lisbon, Portugal, Sept 1995.
"Modelling the electrical and thermal behaviour of metal oxide arresters using
MODELS",
A. Somogyi, B, Ban, L. Prikler (Technical Univ. of Budapest, Hungary)
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"A gas discharge tube module based on discharge physics for use in ATP-EMTP
simulation",
A. Larsson, H. Tang, V. Scuka (Uppsala Univ, Sweden)
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"Circuit breaker representation for TRV calculations",
J.A. Martinez-Velasco (Univ. Politcnica de Catalunya, Barcelona, Spain),
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"SF6 circuit breaker modelling for shunt reactors switching",
Z. Ma, C.A. Bliss, A.F.W. Harris, S.B. Tennakoon (Staffordshire Univ., UK)
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"A neural network vacuum circuit breaker model for simulation of transients
overvoltages",
J. Kosmac, P. Zunko (Ljubljana Univ., Slovenia)
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"Modelling of curcuit breakers using the type-94 component",
J.A. Martinez-Velasco (Univ. Politcnica de Catalunya, Barcelona, Spain),
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
154
"Postprocessing of measured transient data using MODELS in the ATP-EMTP",
M. Kizilcay (FH Osnabrueck, Germany)
L. Dub (DEI Simulation Software, Oregon, USA),
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"Investigation of transformer differential protection schemes by using ATP-MODELS",
M.M. Saha, B. Hillstrm, B. Kasztenny, E. Rosolowski (ABB Network Partner,
Vsteras, Sweden)
European EMTP User Group Meeting,
Hannover, Germany, Nov 1995
"A new method for EMTP implementation of nonlinear components",
J.A. Martinez-Velasco (Univ. Politcnica de Catalunya, Barcelona, Spain),
Proc. 12th Power Systems Computation Conference,
Dresden (Germany), August 1996.
155
INDEX
A
Algorithm control .............................................................................. 32, 126
Arithmetic operators................................................................................. 59
Arrays ................................................................................ 7, 8, 14, 61, 143
Assigning data values .............................................................................. 71
Assigning input values ............................................................................. 71
Assigning output values ........................................................................... 72
Assigning values .............................................................................. 32, 123
Assignment operator................................................................................ 10
ATP inputs ................................................................................... 77, 78, 80
ATP outputs ............................................................................................. 83
ATP variables........................................................................................... 82
B
backtime( ) ............................................................................................. 152
backval( ) ............................................................................................... 152
Basic aspects......................................................................................... 2, 4
Blank lines ......................................................................................... 11, 87
Block comments....................................................................................... 12
Boolean operators.................................................................................... 59
Boolean values .......................................................................................... 9
Braces '{ }'................................................................................................ 10
Brackets '[ ]' ............................................................................................. 10
C
C programs ........................................................................................ 19, 26
Circuit components .................................................................................. 90
COMBINE statements...................................................................... 45, 127
Comments ............................................................................................... 12
Complex-value functions........................................................................ 103
Conditional control ................................................................................... 40
Constants..................................................................................... 6, 13, 140
Control components................................................................................. 87
Control systems ......................................................................................... 5
Controlling a procedure.................................................................... 32, 126
Curly braces '{ }' ....................................................................................... 10
D
Data ....................................................................................... 6, 14, 71, 128
Delay storage........................................................................... 68, 122, 129
delay( )..................................................................................... 68, 108, 151
156
Delimiters ................................................................................................. 11
Derivative polynomials ............................................................................. 63
Derivatives ............................................................................. 112, 149, 150
derivpol( )................................................................................................. 63
Difference between simulation language and programming language....... 4
Differential equations ....................................................................... 33, 123
Dimensions of MODELS storage in ATP ................................................. 99
DO statements ................................................................................. 44, 126
Dynamic limits.......................................................................................... 37
E
Equal sign ................................................................................................ 10
ERROR statements ......................................................................... 51, 127
EXEC procedure ...................................................................................... 28
Expressions ..................................................................................... 55, 129
External models (either local or foreign) .......................................... 21, 121
External point list for pointlist function...................................................... 25
External programs.................................................................... 6, 19, 26, 95
F
FOR arguments ....................................................................................... 55
FOR statements............................................................................... 43, 126
Foreign functions ............................................................................. 26, 121
Foreign models .......................................................................... 19, 95, 121
Formatting.......................................................................................... 11, 87
Fortran programs ............................................................................... 19, 26
Frequency meter.................................................................................... 106
Frequency-domain use of a model........................................................... 96
Functions ..................................................................... 17, 23, 58, 120, 143
G
Global constants ........................................................................................ 6
Global variables ......................................................................................... 6
H
histdef( )................................................................................................. 153
History.......................................................... 29, 39, 69, 122, 125, 128, 153
histval( ) ................................................................................................. 153
I
IF expressions.......................................................................................... 41
IF statements ................................................................................... 40, 126
Indentation ............................................................................................... 12
INIT procedure ......................................................................................... 28
157
Initialization ............................................................................ 29, 36, 69, 97
Initializing the type-94 component............................................................ 94
Inline comments....................................................................................... 12
Inputs ..................................................................................... 6, 15, 71, 128
Inputs from ATP ..................................................................... 77, 78, 80, 82
Instance of a model.................................................................................. 52
Integrals ..................................................................................... 38, 63, 125
Interpolation on inputs at sub-steps of the simulation .............. 67, 122, 129
Iterated type-94 circuit component........................................................... 91
Iteration and re-updating a model ............................................................ 73
Iteration control ............................................................................ 42, 43, 44
K
Keywords of the MODELS language ..................................................... 135
L
Laplace transfer functions................................................................ 33, 124
Libraries of models and functions .......................................................... 100
Limits ............................................................................................. 9, 37, 60
Linear sum ............................................................................................... 62
List sizes in ATP for MODELS ................................................................. 99
Local constants .......................................................................................... 6
Local models.................................................................................... 18, 121
Local variables ........................................................................................... 6
Logical functions .................................................................................... 145
Logical operators ..................................................................................... 59
Logical values ............................................................................................ 9
M
Min/max tracking.................................................................................... 115
Model description....................................................................... 17, 85, 119
Model instance......................................................................................... 52
Model, MODELS, and MODEL .................................................................. 9
MODELS in ATP .................................................................... 2, 76, 99, 118
MODELS language .................................................................................... 2
N
Named procedures .......................................................................... 30, 123
Names ..................................................................................................... 11
Norton type-94 circuit component ............................................................ 91
Numbers .................................................................................................... 9
Numerical functions ............................................................................... 143
Numerical operators................................................................................. 59
Numerical values ................................................................................. 9, 58
158
O
Operators......................................................................................... 59, 139
Outputs ...................................................................................... 17, 72, 128
Outputs to ATP ........................................................................................ 83
P
Parentheses '( )' ....................................................................................... 10
Parsing..................................................................................................... 11
Plot data as input to a model ................................................................... 78
Plotting results ......................................................................................... 84
Pointlist functions ..................................................................... 24, 110, 120
Polynomials of derivatives ....................................................................... 63
Post-processing existing plot data ........................................................... 78
Pre-defined constants and variables...................................................... 140
Pre-defined functions ............................................................................. 143
predtime( ) ............................................................................................. 152
predval( )................................................................................................ 151
prevval( )................................................................................................ 151
Procedures ...................................................... 17, 28, 32, 53, 59, 122, 127
Programming language.............................................................................. 3
Project........................................................................................................ 6
Prototyping................................................................................................. 6
R
Random value functions ........................................................................ 146
RECORD printout/plotting data ................................................................ 84
REDO statements ............................................................................ 44, 126
Referring to a named value...................................................................... 55
Regular expressions ................................................................................ 55
Repetition control ......................................................................... 42, 43, 44
Results, plotting ....................................................................................... 84
RMS value ............................................................................................. 117
S
Sample/hold model ................................................................................ 113
Signal sources ....................................................................................... 100
Simulation directives .......................................................... 66, 72, 121, 128
Simulation functions............................................................................... 148
Simulation language = Programming language + Time flow ...................... 4
Simulation results, plotting ....................................................................... 84
Simultaneous equations........................................................................... 45
Sources of signal ................................................................................... 100
Special expressions ................................................................................. 62
Square brackets '[ ]' ................................................................................. 10
State of a model....................................................................................... 74
USERS GUIDE TO MODELS IN ATP
159
Statement function arguments ................................................................. 55
Statement functions ......................................................................... 23, 120
Statements....................................................................................... 32, 123
Static limits......................................................................................... 37, 60
Steady-state circuit initialization ............................................................... 97
Submodels ............................................................................................... 17
sum( )....................................................................................................... 62
Syntax of the MODELS language .......................................................... 118
T
TACS ................................................................................................... 5, 80
TACS devices ........................................................................................ 106
Thevenin type-94 circuit component ........................................................ 91
Time step ......................................................................... 66, 122, 128, 141
Track/hold model ................................................................................... 113
Tracking min/max................................................................................... 115
U
USE ITERATE ......................................................................................... 73
USE statements ................................................................... 52, 71, 72, 127
Using a model .............................................................................. 71, 87, 90
Using MODELS in ATP............................................................................ 76
V
Value assignment ............................................................................ 32, 123
Value-holding elements ................................................................. 6, 13, 55
Values........................................................................................................ 9
Variables ...................................................................................... 6, 16, 140
Variables of the MODELS section............................................................ 84
Visibility of value-holding elements ...................................................... 6, 55
W
WHILE statements ........................................................................... 42, 126
White space ....................................................................................... 11, 87
Why use MODELS................................................................................. 2, 6
Windup and no-windup limits ................................................................... 37
write(), write1(), write2() ................................................................... 53, 127
Writing a model ........................................................................................ 13
Writing expressions.................................................................................. 55
Z
Z transfer functions .......................................................................... 33, 125
160
IN CLOSING ...
Further information on the use of MODELS in ATP can be obtained by
anonymous ftp from the following two addresses:
ftp.ee.mtu.edu in directory pub/atp/models
ftp.rrzn.uni-hannover.de in directory pub/special/atp/models
The available material includes the following files. Some of these file names are
preceded by a three-digit number, for example 964, indicating the year and month
of the file:
ugmus.zip
ugma4.zip
lmusw.zip
lma4w.zip
lmusp.zip
lma4p.zip
techn.zip
libs.zip
examp.zip
typ94.zip
tel: +1-503-392-4551
fax: +1-503-392-4575
email: dube@peak.org