translator to flat modelica
TRANSCRIPT
Translator to flat Modelica
May 2007
Copyright IMAGINE S.A. 1995-2007 AMESim® is the registered trademark of IMAGINE S.A. AMESet® is the registered trademark of IMAGINE S.A. LMS Imagine.Lab is a registered trademark of LMS International N.V. ADAMS is a registered United States trademark of Mechanical Dynamics, Incorporated. ADAMS/Solver and ADAMS/View are trademarks of Mechanical Dynamics, Incorporated. MATLAB and SIMULINK are registered trademarks of the Math Works, Inc. PostScript is a trademark of Adobe Systems Inc. UNIX is a registered trademark in the United States and other countries exclusively licensed by X / Open Company Ltd. Windows , Windows NT, Windows 2000 and Windows XP are registered trademarks of the Microsoft Corporation. X windows is a trademark of the Massachusetts Institute of Technology. All other product names are trademarks or registered trademarks of their respective companies.
MMaayy 22000077 TTaabbllee ooff CCoonntteennttss 11//22
TABLE OF CONTENTS
1. Introduction.................................... ....................................................................68
2. How it works .................................... ..................................................................68
3. Compilation error messages...................... ......................................................69
4. Component instantiation errors.................. .....................................................88
5. Code generation errors.......................... ...........................................................89
6. Modelica supported subset....................... .......................................................90
6.1. Built-in operators..........................................................................................91 6.2. Built-in array operators ................................................................................91 6.3. Reduction expressions ................................................................................91 6.4. Array constructors, array concatenation and array access .........................91 6.5. Equality ........................................................................................................92 6.6. Addition and subtraction ..............................................................................92 6.7. Multiplication ................................................................................................92 6.8. Division ........................................................................................................92 6.9. Exponentiation .............................................................................................92 6.10. Slice operation ...........................................................................................92 6.11. Boolean operators .....................................................................................92 6.12. Vectorized call of functions ........................................................................92 6.13. Definition of package classes ....................................................................92 6.14. Restrictions that apply to definitions of package classes ..........................93 6.15. Definitions of connector classes ................................................................94 6.16. Restrictions that apply to definitions of connector classes ........................94 6.17. Definitions of partial model classes ...........................................................94 6.18. Restrictions that apply to definitions of partial model classes ...................94 6.19. Definitions of submodel classes ................................................................94 6.20. Restrictions that apply to definitions of submodel classes ........................95 6.21. Definitions of self-contained model classes...............................................95 6.22. Restrictions that apply to definitions of self-contained model classes ......95 6.23. Definitions of models classes whose instances require connections with external AMESim submodels..............................................................................96 6.24. Restrictions that apply to models classes whose instances require connections with external AMESim submodels..................................................97
1. Introduction
This manual assumes knowledge of Modelica, in particular the vocabulary associated to object-oriented modeling using that language. The following references can be consulted for more information about Modelica: ● The WWW site of the Modelica Association (http://www.modelica.org), in
particular the documentation page (http://www.modelica.org/documents) where the Modelica Language Specification 2.x can be found
● “Introduction to Physical Modeling with Modelica”, by M. Tiller ● “Principles of Object-Oriented Modeling and Simulation with Modelica
2.1”, by P. Fritzson Some AMESim-specific terms are described in the tableau below.
Term Definition
Package (class)
A Modelica package
Connector class
A Modelica class defined with “connector”
Connector instance
The value of a variable declared with type “connector” (i.e., with the name of a connector class as type name)
Partial model class
A Modelica class defined using the prefix “partial”
Model class A Modelica class defined with “model”
Model instance
The value of a variable declared with type “model” (i.e., with the name of a model class as type name)
Function (class)
A Modelica class defined with “function”
Record class A Modelica class defined with “record”
Record instance
The value of a variable declared with type “record” (i.e., with the name of a record class as type name), or an object explicitely created using a record constructor
2. How it works
The usage statement for the translator to flat Modelica program is as follows:
translator [-lib <file name>] [-o <file name>] [-fundir <dir. name>] –command “command”
Where
• -lib <file name>: define <file name> to be a file containing a Modelica library of classes,
• -o <file name>: specify target file name (default is “<instance name>.mo”),
• -fundir <dir. name>: specify the name of the directory where external function prototypes have to be generated (default is “<current directory>/functions”),
• -command “command”: define the component to be created as a regular Modelica component declaration.
You can display the precedent list of options, using “-help” or “--help” command line arguments.
3. Compilation error messages
Code Error message Explanation and examples
0001 Unknown Identifier “identifier name”.
An undefined identifier is encountered during compilation. To be used, an identifier must either be defined in the scope of where it is used or predefined in the Modelica language. In the example below identifier “z” is undefined. possible causes are: - incorrect name of variable: rename this variable, - undeclared Identifier: declare this identifier within
the scope where it’s used. Example:
model M equation z = 0.; end M;
0002 Enumeration type
definition with duplicated literal “literal name”.
Literal names cannot be duplicated in enumeration type definitions. In the example below, the literal “Blue” is duplicated. Action to take: remove or rename the duplicated literal. Example:
class M type color = enumeration(Red, Blue , Green, Blue , Yellow); color z;
end M;
0003 “encapsulated” keyword cannot be applied to “class definition”.
The following “class definitions” cannot be encapsulated: - short class definition, - “type” definition, - class definition by extension. In the example below, “encapsulated” keyword is applied to “type” definition. Example:
class M encapsulated type N = Real[3]; N n; end M;
0004 Invalid “type” definition. Restricted class “type” must be defined using either a
short class definition or an enumeration type definition. Other definitions are not allowed. Example:
class M type N Real a; end N; N n; end M;
0005 Enumeration literals not
specified. The list of literals is empty in an enumeration type definition. Example:
class M type N = enumeration (); N n; end M;
0006 Use of not yet
implemented feature: “feature name”
“feature name” can be one of the following: - “within” clause, - “import” clause, - Class definition by extension, - Element redeclaration, - Field access in element modification expression, - Implicit iteration range, - Component type equation, - Algorithm clause - binary operator ==, - binary operator <>, - Function argument reduction, - Matrix expression, - Non integer range expression, - unary operator +,
- Non numeric vector expression, - Modification of predefined type attribute “attribute
name”, - “block” element, - “expandable connector” element, - External call with left hand side expression. The example below contains an import clause. Example:
import A.B; class M Real x = 2.; end M;
0007 Use of Modelica
unsupported feature: “feature name”
This feature is not supported by the current version of the Modelica language. “feature name” can be like the following: - An external call to an unsupported language:
“Language name”. In the example below, an external function “ext_func” uses the unsupported language “Java”. Example:
function ext_func input Real x; output Real y; external "JAVA" y = java_func(x); end ext_func; model M Real y; equation y = ext_func(y);
end M;
0008 External call language not specified.
The name of the external call language is missing. Example:
function ext_func input Real x; output Real y; external y = java_func(x); end ext_func; model M Real y; equation y = ext_func(y); end M;
0009 “operator symbol” operator between scalar and array type elements.
“operator symbol” can be one of the following: “+”, ”-”. These operations are element-wise and require the operands to be of the same size. You cannot subtract or add a scalar to an array type element. In the example below "+" operator is used between scalar element “b” and array element “a”. Example:
class M Real[3] a; Real b; equation a = a + b; end M;
0010 Array dimensions must
agree to perform “operation”.
“operation” can be either “addition” or “subtraction”. These operations are element-wise and require the operands to be of the same dimension. You cannot subtract or add two arrays of different length. In the example below, arrays “a” and “b” are added, whereas their dimensions are different. Example:
class M Real[3] a; Real[2] b; equation a = a + b;
end M;
0011 Function call with duplicate named argument: “argument name”.
An argument is named twice in the list of function call arguments. In the erroneous example below, the function “func” is called by passing the same argument twice (x = 3.0, x = 2.6). Example:
function func input Real x; input Real z; output Real y; algorithm y := 2 * y; end func;
model M Real y; equation y = func(x = 3.0, x = 2.6); end M;
0012 Too many arguments in
function call. In the example below, two arguments are passed to the function “func”, while this function is defined with only one input parameter.
Example:
function func input Real x; output Real y; algorithm y := 2 * y; end func; model M Real y; equation y = func(3, 2); end M;
0013 Mixed positional and
named function argument passing not allowed.
Positional and named argument passing styles cannot be mixed in a function call. Example:
function func input Real x; input Real z; output Real y; algorithm y := 2 * y; end func; model M Real y; equation y = func(x = 3, 2); end M;
0014 Type of operands
inconsistent with comparison operation.
Comparison operators: “<”, “>”, “<=”, “>=”, “==”, and “<>” can be applied only to simple numerical elements of the same type (Integer or Real). Example:
class M Boolean y; Real x[3]; equation y = (x < x ); end M;
0015 Equation terms must be
of the same type. In equation “A = B”, A and B must be of the same type. Example:
class M Boolean y; Real x[3]; equation y = x ;
end M;
0016 Function called with non input-named argument.
In function calls, all arguments must be defined as inputs (using the “input” prefix). In the example below, function “func” is called by passing the named argument “y = 3”, whereas y is declared as an output variable. Example:
function func input Real x; input Real z; output Real y; algorithm y := 2 * y; end func; model M Real y; equation y = func(y = 3, x = 2); end M;
0017 “operator symbol”
operator applied to non numeric expression.
“operator symbol” can be one of the following: “*”, “/”, “+”, “-”, “^”. These operators can be applied only to numerical expressions (i.e. Integer or Real scalars, vectors, matrices and arrays). In the example below, a boolean “z” cannot be added to a real “x” in equation “y = x + z”. Example:
model M Real y; Real x; Boolean z; equation y = x + z; end M;
0018 Arrays do not have
compatible dimensions to be multiplied.
Multiplication of arrays “A * B” is defined only for the following combinations: - A = Vector [n] and B = Vector [n], - A = Vector [n] and B = Matrix [n, m], - A = Matrix [n, m] and B = Vector [m], - A = Matrix [n, m] and B = Matrix [m, p]. In the example below, arrays x and z cannot be multiplied. Example:
model M Real[3, 2] y; Real[3, 3] x; Real[4, 2] z;
equation y = x * z; end M;
0019 Cannot perform power
operation on non square array.
Trying to apply a power operator “^” to non square array. Example:
model M Real[3, 3] y; Real[3, 2] x; equation y = x ^ 2 ; end M;
0020 Non boolean “if”
condition expression. In expression “if A then…” or “…elseif A then…”, A must be a Boolean type expression. In the expression below, “if” condition “a” is of type Real. Example:
model M Real y; Real x; Real a; equation y = if a then x else y; end M;
0021 If alternative expressions
must be of the same type.
In expressions “if A then B else C”, B and C must be of the same type. Example:
model M Real y; Integer x; Boolean a; equation y = if a then x else y ; end M;
0022 “operator symbol”
operator applied to non-Boolean expression.
“operator symbol” can be one of the following: “or”, “and”, “not”. These operators cannot be applied to non-boolean expressions. In the example below, the “and” operator is used with Integer type variable “x”. Example:
model M Boolean y; Boolean z; Integer x; equation y = x and z ; end M;
0023 Type of operands
inconsistent with division operation.
In the example below, division cannot be performed between Integer variable “x” and Boolean variable “z”. Example:
model M Real y; Boolean z; Integer x; equation y = x / z; end M;
0024 “type name” element
expected. This error occurs when an element type is expected, but another type is found. “type name” can be one of the following: - “class”: a class name element is expected. - “type”: expected element is a class name, a
predefined type name or a component type name. - “function”: a function class name or function
instance element is expected. In the example below, a real argument is passed to variable “x”, whereas “x” is of type Integer. Displayed message is: function element expected. Example:
model M Real y; Integer x; equation y = x (3.); end M;
0025 Cannot modify final
element “element name”. An element defined as “final” in an element modification or declaration cannot be modified by a modification or by redeclaration. All elements of a “final” element are also “final”. In the example below, the class modification “x = 2.0” cannot be done, since “x” is declared as a final variable. Example:
class N final Real x = 1.0; end N; class M N n (x = 2.0); equation n.x = 5.0; end M;
0026 Elements of different
types in vector expression.
Elements of a vector must be of the same type. Example:
class M Real[2] x = {1.0, 3}; end M;
0027 Cannot apply “each”
keyword to non-array type element.
The “each” keyword on a modifier requires that it is applied in an array declaration or modification. Example:
class M Real x (each start = 0.0); end M;
0028 Invalid expression in
element modification. Only identifiers and field access expressions are allowed in element modification. Other kinds of expressions are not allowed: function call, indexed access… In the example below, the modifier “(b[2] = 1.0)” uses “indexed access” expression “b[2]”. Example:
class A Real[3] b; end A; class M parameter A a (b[2] = 1.0) ; end M;
0029 Component element
expected, but class element found
A component element is expected in an expression, but a class element (including predefined type and component type elements) is found. Example:
model M Real a; equation a = Integer ; end M;
0030 Array dimensions don't
agree in equation. Equality of arrays is defined element-wise and requires both arrays to have the same dimension number. Example:
class M Real[5] p; Real[3] q; equation p = q ; end M;
0031 Invalid use of expression
“end”. The expression “end” may only appear inside an array subscripts. Example:
class M Integer y = 4 + end ; Real z; equation z = y; end M;
0032 Invalid type of element in
range expression. Type of range expression must be Integer array. In the example below, the Real variable “y” is used as a range expression in for clause “for i in y…”. Example:
class M Integer x[10]; Real y; equation for i in y loop x[i] = i; end for; end M;
0033 Invalid extension
definition. Invalid use of “extends” keyword. Example:
class M extends Real; Integer i = 5; end M;
0034 Invalid use of
“enumeration” keyword. An “enumeration” keyword can only be used within enumeration type declaration. Example:
class M = enumeration(Blue, Green, Black);
0035 Use of type prefix not allowed in short class definition.
Type prefixes: parameter, discrete, constant, flow, input and output, cannot be used in short class definitions. In the example below the prefix “parameter” cannot be used in short definition of class N. Example:
class M class N = parameter Real; end M;
0036 Use of subscripts not
allowed in short class definition.
In the example below, subscript “[5]” is used in short definition of class N. Example:
class M class N = Real[5] ; end M;
0037 Non-empty function call cannot be used as an equation.
In the example below, the expression “F(1.0)” is used as an equation, whereas its type is Real. Example:
function F input Real z; output Real x; equation x = 2.0 * z; end F; class M Real y; equation F(1.0); end M;
0038 Duplicated modification
of element “element name”.
Two arguments of a modification cannot designate the same attribute of an element. Example:
class N Real z = 4.0; Real y = 3.0; end N; class M N x (final z = 5.0, final z = 2.0); equation x.z = x.y; end M;
0039 Invalid modification of
class element. When modifying a class element A, you must use the following syntax: “X (arg1, arg2…)” where arg1, arg2… is the list of modifications. Example:
class N class K = Real; end N; class M N n (K = Integer ); end M;
0040 Cannot access protected
element “element name”. Elements defined with the prefix “protected” cannot be referenced outside the class declaration. Example:
class N protected Real a = 4.0;
end N; class M N n (a = 2.0); end M;
0041 Cannot access outer
element “element name”. In the example below, outer element “a”, cannot be used in modification expression “a = 2.0”. Example:
class N outer Real a = 4.0; end N; class M inner Real a; N n (a = 2.0); end M;
0042 Cannot subscript a non
array type element. In the example below, expression “[4]” is used with non array variable “x”. Example:
class M Real x; equation x[4] = 2.0; end M;
0043 Non-Integer array
subscript. Array index expressions can be either scalar integer expressions or integer vector expressions. Example:
class M Real[5] x; equation x[3.0] = 2.0; end M;
0044 Range step value cannot
be null. Zero is not a valid range step value. Example:
class M Integer x = 1:0:5 ; end M;
0045 Cannot inherit from
component element. Inheritance is possible only from class elements. Example:
class N Real x = 5.0; end N;
class M N n; class K extends n ; end K; end M;
0046 “element name” already
declared in parent class. This error occurs when an inherited class element has the same name as a local class element. Example:
class N Real x = 5.0; end N; class M extends N; Real x = 2.0; end M;
0047 Inheritance from different
class kinds not allowed. This error occurs when a class A inherits from a class B of different kind. A class kind can be: generic class, record, function, model… For example, if A is a model class and B is a generic class, A cannot inherit from B, and vice-versa. Example:
record N Real x = 5.0; end N; class M extends N; Real x = 2.0; end M;
0048 Inheritance from function
not allowed. Definition of a class which inherits from a class of type function is not allowed. Example:
function N Real x = 5.0; end N; function M extends N; Real x = 2.0; end M;
0049 Invalid annotation of
inverse functions: “error cause”
If F is a function with some real inputs and some real outputs, the Annotation of the inverse functions of F must be defined as follows: annotation(Imagine(AMESim(InverseFunctions(<arg1>,
<arg2>…)))); Where arguments <arg1>, <arg2>… define inverse functions as follows: <arg1>: Inverse[1] = F(x = y, z = w…), <arg2>: Inverse[2] = F(x’ = y’, z’ = w’…)… Where x, y, z, w, x’, y’, z’, w’ denotes real inputs and outputs of function F. The “error cause”, displayed within the error message, can be one of the following: - Redeclaration not allowed: occurs when
“redeclare” keyword is used, - Use of each keyword not allowed: occurs when the
“each” keyword is used, - Use of final keyword not allowed: occurs when the
“final” keyword is used, - Unspecified modification: occurs when the
modification expression “= F(x=y, z=w…)” is not specified,
- Invalid modification expression: occurs when the modification expression is different from “= F(a, b…)”.
- Invalid function call expression: occurs when the function call expression “F” is not a local or top level identifier.
- Invalid type of function call expression: occurs when the function call identifier “F” is not a class function name,
- Use of partial class element: occurs when the function call identifier “F” is declared with the prefix “partial”,
- Function argument reduction not allowed: occurs when argument reduction is used within function call expression “F(…)”,
- Cannot use unnamed function argument: occurs when an unnamed argument is used within function call expression “F(…)”,
- Unknown identifier “id”: occurs when a function argument name “id” is not found in the definition of function “F”,
- Invalid function argument modification: occurs when the function “F” is called with an argument “x = y”, where y is not a local identifier of function F.
0050 Input or output
component found in generic class “class name”.
Use of fixed causality (input or output) components is not allowed for generic (i.e. non restricted) classes. Example:
class F input Real x = 5.0; output Real y = 4.0; end F;
class M Real x; Real y; equation y = F(x); end M;
0051 Invalid type of argument
in “connect” statement. In connect statement: “connect(A, B)”, A and B must be of type connector. Example:
connector Pin Voltage v; flow Current i; end Pin; class M Pin pin1; Real pin2; equation connect(pin1, pin2); end M;
0052 Cannot connect flow and
non-flow components. In connect statement: connect(A, B), A and B must have the same flow property value, i.e. A and B are both either declared as flow, or both declared as non-flow. Example:
connector Pin Real v; end Pin; class M flow Pin pin1; Pin pin2; equation connect(pin1, pin2); end M;
0053 Non-Boolean when
condition expression. In expression “…when A then…”, “A” must be Boolean. Example:
class M Real x, y; equation when x - 2.0 then y = x; end when; end M;
0054 “class kind” instance
used in connection statement
“class kind” can be one of the following: - package, - function,
- record. These restricted classes cannot be used with connections. Example:
connector P Real x; end P; record R P h; end R; class M R a, b; equation connect(a.h, b.h); end M;
0055 When clauses cannot be
nested When equations are not allowed to be nested (see the example below) Example:
model M Integer x, y; equation when x > 1 then when y > 2 then x = y + 1; end when; end when; end M;
0056 Invalid form of equation
within when clause Only the following equation forms are allowed within when clause:
- variable = expression;
- tuple of variables = function call;
- call to assert(), terminate(), reinit();
- for and if clauses (if the equations within are of the allowed forms).
Example:
model M Real x, y; equation x + y = 5; when sample(0, 2) then 2 * x + y = 7; end when; end M;
0057 When condition must be
discrete-time expression This error occurs when a continuous expression is used as a when condition.
Example:
model M Real x, y; equation when noEvent(x > 1) then x = y + 1; end when; end M;
0058 Argument type mismatch.
The type of the actual argument expression is not compatible with the declared type of the corresponding input variable.
Example:
model M Real x, y; equation x = cos(y > 1); end M;
0059 Variability conflicts in assignment expression.
Variability of right hand side of assignment must be lower or equal to variability of left hand side.
Example:
model M Real x; parameter Real y := x; equation x = y + 1; end M;
0060 Cannot use named argument with a built-in operator or function.
Use of named argument in function call is not allowed for built-in operators and functions.
Example:
model M Real x; equation x = cos(z = 4); end M;
0061 "operator name" operator argument must be a variable.
For the following built-in operators the first argument must be a variable (and not the result of an operation or a function call): pre, edge, change and reinit.
Example:
model M Real x, y; equation x = pre(y + 1); end M;
0062 Argument variability mismatch.
The variability of an argument of a function call is not compatible with the range of variability allowed for this argument. In the example below, the operator “der” cannot be applied the discrete variable “y” (for allowed range of variability of built-in functions and operators see the Modelica language specifications).
Example:
model M Real x; discrete Real y; equation x = der(y); end M;
0063 Equations not allowed in the definition of “class kind”.
Class kind can be one of the following:
- function,
- record,
- connector.
Example:
function M input Real x; output Real y; equation y = der(x); end M;
0064 “operator name” operator cannot be used within function definition.
The following operators cannot be used within function definition: der, initial, terminal, sample, pre, edge, change, reinit and delay.
Example:
function M input Real x; output Real y = der(x); end M;
0065 Arguments dimensions mismatch in vectorized function call of function.
The application of a function “f” to a vector {x1, x2, …, xn} is said to be a vectorized function call if the function “f” can be applied to each element x1, x2, …, xn of the vector. In this case the result is a vector obtained as follows:
f({x1, x2, …, xn}) = {f(x1), f(x2}, …, f(xn)}
If more than one vector argument is passed to the function “f”, all of the arguments have to be of the same size, and they are traversed in parallel as follows:
f({x1, x2, …, xn}, {y1, y2, …, yn}) = {f(x1, y1), f(x2, y2}, …, f(xn, yn)}
This error occurs when more than one vector argument is passed to the function, and the arguments are of different sizes.
Example:
model M Real[4] x, z; Real[3] y; equation z = div(x, y); end M;
0066 Argument dimension mismatch.
This error occurs when the dimension of an argument in a function call mismatch with the declared dimension of the corresponding argument in function definition. In example below, the function F is called with a Real argument of dimension 4, whereas in function F definition, the argument is declared with the dimension 3.
Example:
function F input Real[3] x; output Real y = x[1]; end F; model M Real[4] x;
Real y; equation y = F(x); end M;
0067 Too few arguments in function call.
In example below, one argument is passed to the function “reinit”, while this function requires two input arguments.
Example:
model M Real[4] x; Real y; equation y = reinit(x); end M;
0068 Left hand side of discrete equation must be a variable.
An equation is said to be “discrete” if its left and right hand side expressions are both discrete (see the Modelica specifications for the definition of discrete expressions). For this kind of equation, the left hand side expression must be a variable (and not the result of an operation or a function call). In the example below, the expressions “x” and “y” are variables, whereas the expression “x + 1” is not a variable. Therefore the equation “x + 1 = y” produce an error at compilation.
Example:
model M Integer x, y; equation x + 1 = y; end M;
4. Component instantiation errors
Code Error message Explanation and examples
1000 Use of not yet implemented feature: “feature name”.
“feature name” can be one of the following: - Component type element instantiation, - Predefined type element instantiation, - Short class definition,
- Integer raised to an integer power, - Real raised to an integer power, - Component function invocation. In the example below, an error occurs at instantiation of component type element “m.n[0, 0].K”. Example:
class N type K = Real; end N; class M N n[3, 2]; end M;
1001 Zero raised to the zero power. In the example below, the expression “0^0” is not
allowed. Example:
class M Real x; Integer y; equation x = 0^0 ; end M;
1002 Missing declaration equation
for fixed identifier “Id” Parameters and constants must be assigned an initial value at declaration; except for parameters with attribute “fixed” set to false (this attribute is true by default). Example:
model M parameter Real a; Real x = a; end M;
5. Code generation errors
Code Error message Explanation and examples
2000 Use of not yet implemented feature: “feature name”.
“feature name” can be one of the following: - String type, - Boolean type, - Boolean operator “and”, - Boolean operator “or”, - Expression “false”,
- Indexed access expression, - Range expression, - Expression of type “String”, - Expression “true”, - Tuple expression, - External procedure call, - Use of class reference in expression is
allowed only for an external function call, - Non Real function input, - Non Real function output, - Function with many outputs. In the example below, variable “a” is of String type. Example:
class M String a; end M;
6. Modelica supported subset
The current version of the compiler does not support the whole Modelica language specification, for several reasons: ● The aim of this version is to provide a first step of Modelica integration
into AMESim, so sticking to a Modelica subset that is easy to learn and use and that integrates well within AMESim was an important point
● The Modelica specification is not stable enough for risking to let users write models using libraries for which no long-time support will be garanteed
● The Modelica specifiaction is ambiguous with respect to several aspects (that will be hopefully fixed in the years to come)
It results from the above constraints that the best way to ensure specifications written in Modelica to be compatible between present and future versions of AMESim is to write them in a subset that is unambiguous, yet providing enough language contructs to develop useful models. Algorithms are not supported. Models can be structured as, or using: ● packages ● connectors ● (partial) models ● records ● arrays In particular, functions used as model are not supported, and so are blocks. In the previous sections, an example of Modelica package has been presented. The following sections explain in more details the restrictions
that apply to the current construct. A program that does not follow these restrictions triggers undefined behavior.
6.1. Built-in operators The following built-in operators are not supported: ● cardinality() ● isPresent() ● semiLinear()
6.2. Built-in array operators The following built-in array operators are supported: ● size() (restriction: only the two-argument version is supported) ● fill() The following built-in array operators are not supported: ● ndims() ● scalar() ● vector() ● matrix() ● transpose() ● outerProduct() ● identity() ● diagonal() ● zeros() ● ones() ● linspace() ● min() ● max() ● sum() ● product() ● symetric() ● cross() ● skew()
6.3. Reduction expressions Reduction expressions are not supported.
6.4. Array constructors, array concatenation and array access
Array constructors with iterators are supported with the following restrictions: ● The range of the iteration variable should be explicit and should have at
most parameter variability ● The syntax “array(...)” is not supported
Array concatenation is not supported Array access operators are supported with the following restrictions: ● subscripts can only have type Integer (in particular they cannot be array
or column expressions)
6.5. Equality Equality is supported for both scalar and arrays (the size of arrays must have at most parameter variability).
6.6. Addition and subtraction Addition and subtraction are supported for both scalars and arrays (the size of arrays must have at most parameter variability).
6.7. Multiplication Multiplication is supported for both scalars and arrays (the size of arrays must have at most parameter variability).
6.8. Division Division of both scalars and arrays by scalars is supported (the size of arrays must have at most parameter variability).
6.9. Exponentiation Exponentiation of scalars is supported. Exponentiation of matrices is not supported.
6.10. Slice operation Slice operation is supported (the size of arrays must have at most parameter variability).
6.11. Boolean operators Boolean operators are restricted to scalar boolean expressions.
6.12. Vectorized call of functions Vectorized call of functions are partially supported: because of restrictions applied to functions, the result of vectorized calls should only contain calls to functions with scalar arguments (see Definition of function classes for more information).
6.13. Definition of package classes Packages are special kind of definitions that are only used to structure Modelica projects: they are used to group sets of related definitions together in order to ease further information retrieval. Packages are totally
optional: it is possible to write a complete Modelica project without enclosing definitions into packages1. However, as Modelica code bases grow, the need for structured code becomes rapidly necessary, hence the existence of that construct in AMESim's Modelica subset. Figure 1 shows some simple examples of packages. Inheritance can be used with packages although it does not make things clearer: it is preferable not to use it since packages generally contain definitions that are intended to be used directly, not duplicated.
// Valid definitions of packages
package Empty "The simplest possible package definition" end Empty;
package Constants "Package containing useful constants" constant Real PI = acos(-1.0); constant Real E = exp(1.0); end Constants;
package MyLibrary
package Constants "Constants of MyLibrary" constant Real c = 2.99792458e8; constant Real G = 6.67259e-11; end Constants;
package Models model Simple Real x(start = 0.0); equation der (x) = x; end Simple; end models; end MyLibrary;
Figure 1: Examples of valid definitions of packages
6.14. Restrictions that apply to definitions of package classes
The following AMESim-specific restrictions apply to package classes: ● partial package classes are not allowed
1An implicit “toplevel” package always exists in Modelica, but from the user perspective it can be ignored.
● “short package class definitions” (i.e., package P1 = P2(...);) are not allowed
● “extends definitions” (i.e., package extends P... end P;) are not allowed
6.15. Definitions of connector classes Connectors are used to build models that can be connected together (generally using connect() ). A connector typically contains parameters, variables and subconnectors. Actually, only simple connectors (i.e., containing only parameters and variables) are supported.
6.16. Restrictions that apply to definitions of connector classes
The following AMESim-specific restrictions apply to connector classes: ● subconnectors (i.e., connectors inside connectors) are not allowed ● expandable connectors are not allowed
6.17. Definitions of partial model classes Partial model classes are defined to factor common definitions that can be reused through inheritance (e.g., see partial model “TwoPin” in Figure 2). It is highly recommended to use them whenever the same definitions should be reused into several model classes: those definitions are just written once and for all and any correction or enhancement is automatically repercuted in “client” classes (see model classes in Figure 3).
6.18. Restrictions that apply to definitions of partial model classes
The following AMESim-specific restrictions apply to partial classes: ● “short partial model class definitions” (i.e., partial model PM1 =
PM2(...);) are not allowed ● “extends definitions” (i.e., partial model extends PM... end PM;) are not
allowed
6.19. Definitions of submodel classes Submodel classes are used to build model classes by aggregating their instances and connecting them together. Submodel classes contain generally declarations of parameters, instances of connectors, internal variables and constraints between variables (only equations are supported actually). Inheritance is used to avoid repeating the same declarations when several submodel classes naturally share them.
6.20. Restrictions that apply to definitions of submodel classes
Since there is no real difference between submodels and models, definitions of submodels classes are subject to the same restrictions than self-contained model classes
/* Example of a simple package written in Modelica */ package Electrical "A package of simple electrical models" constant Real PI = acos(-1.0) "A useful constant"; package Connectors connector Pin "Simple electrical connector" Real v "Voltage"; // Variable verifying Kirchhof's second law flow Real i "Current"; // Variable verifying Kirchhof's first law end Pin; end Connectors; package PartialModels "Bases to build more eleaborated submodels" partial model TwoPin "Common structure for two-pin models" Pin p "Positive pin", n "Negative pin"; Real v "Internal voltage value", i "Internal current value"; equation v = p.v – n.v; // Voltage difference between the pins i = p.i; // Current is positive when entering (user convention) n.i + p.i = 0.0; // The current flows through the two-pin models end TwoPin; end PartialModels;
Figure 2: First lines of a typical Modelica package (keywords appear in bold face)
6.21. Definitions of self-contained model classes Self-contained model classes are typically build by aggregating declarations of instances of submodel classes and by connecting them together. They constitute the most elaborated kind of pure-modelica constructs and are intended to be directly instantiated to perform simulations (AMESim's Modelica compiler translates them to submodels with no ports).
6.22. Restrictions that apply to definitions of self-contained model classes
The following AMESim-specific restrictions apply to self-contained model classes: ● “short model class definitions” (i.e., model M1 = M2(...);) are not allowed
● “extends definitions” (i.e., model extends M... end M;) are not allowed
package Models model Ground Pin p(v = 0.0); end Ground; model Resistor "Simple resistor" extends TwoPin; parameter Real R "Resistance"; equation v = R * i; end Resistor; model VoltageSource "Alternative voltage source" extends TwoPin; parameter Real V0 = 220.0, f = 50.0, phi; equation v = V0 * sin(2.0 * PI * f * time + phi); end VoltageSourceAC; model Inductor "Simple inductor" extends TwoPin; parameter Real L "Inductance"; equation L * der(i) = v; end Inductor; model Capacitor "Simple capacitor" extends TwoPin; parameter Real C "Capacitance"; equation C * der(v) = i; end Capacitor;
Figure 3: Simple model classes
6.23. Definitions of models classes whose instances require connections with external AMESim submodels
Sometimes it is necessary to make modelica models communicate with AMESim submodels. This is possible by adding special annotations to Modelica (sub)models indicating that, from the Modelica point of view, some variables have to be inputs from the outside world (i.e., AMESim world) and some others, outputs to the outside world. AMESim's Modelica compiler then generates submodels with the appropriate number of ports.
6.24. Restrictions that apply to models classes whose instances require connections with external AMESim submodels
The following AMESim-specific restrictions apply to those model classes: ● “short model class definitions” (i.e., model M1 = M2(...);) are not allowed ● “extends definitions” (i.e., model extends M... end M;) are not allowed