-
Notifications
You must be signed in to change notification settings - Fork 41
/
connectors.tex
1149 lines (1042 loc) · 50 KB
/
connectors.tex
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\chapter{Connectors and Connections}\label{connectors-and-connections}
This chapter covers connectors, connect-equations, and connections.
Connectors and connect-equations are designed so that different components can be connected graphically
with well-defined semantics. However, the graphical part is optional and found in \cref{annotations}.
\section{Connect-Equations and Connectors}\label{connect-equations-and-connectors}
Connections between objects are introduced by connect-equations in the
equation part of a class. A connect-equation has the following syntax:
\begin{lstlisting}[language=modelica]
connect(component-reference, component-reference);
\end{lstlisting}
\begin{nonnormative}
A \emph{connector} is an instance of a connector class.
\end{nonnormative}
The connect-equation construct takes two references to connectors, each of which is either of the following forms:
\begin{itemize}
\item
$c_1.c_2...c_n$,
where $c_1$ is a connector of the class,
$n$\textgreatereq 1 and $c_{i+1}$ is a connector element of
$c_i$ for \lstinline!i=1:(n-1)!.
\item
\lstinline!m.c!, where \lstinline!m! is a non-connector element in the class and \lstinline!c! is a
connector element of \lstinline!m!.
\end{itemize}
There may optionally be array subscripts on any of the components; the
array subscripts shall be parameter expressions or the special operator
\lstinline!:!. If the connect construct references array of connectors, the
array dimensions must match, and each corresponding pair of elements
from the arrays is connected as a pair of scalar connectors.
\begin{example}
Array usage:
\begin{lstlisting}[language=modelica]
connector InPort = input Real;
connector OutPort = output Real;
block MatrixGain
input InPort u[size(A,2)];
output OutPort y[size(A,1)];
parameter Real A[:,:] = [1];
equation
y=A*u;
end MatrixGain;
Modelica.Blocks.Sources.Sine sinSource[5];
MatrixGain gain (A = 5*identity(5));
MatrixGain gain2(A = ones(2,5));
OutPort x[2];
equation
connect(sinSource.y, gain.u); // Legal
connect(gain.y, gain2.u); // Legal
connect(gain2.y, x); // Legal
\end{lstlisting}
\end{example}
The three main tasks are to:
\begin{itemize}
\item
Elaborate expandable connectors.
\item
Build connection sets from connect-equations.
\item
Generate equations for the complete model.
\end{itemize}
\subsection{Connection Sets}\label{connection-sets}
A connection set is a set of variables connected by means of
connect-equations. A connection set shall contain either only flow
variables or only non-flow variables.
\subsection{Inside and Outside Connectors}\label{inside-and-outside-connectors}
In an element instance M, each connector element of M is called an
outside connector with respect to M. All other connector elements that
are hierarchically inside M, but not in one of the outside connectors of
M, is called an inside connector with respect to M. This is done before
resolving \lstinline!outer! elements to corresponding \lstinline!inner! ones.
\begin{example}
\begin{figure}[H]
\begin{center}
\includegraphics{innerouterconnector}
\end{center}
\caption{Example for inside and outside connectors.}
\end{figure}
The figure visualizes the following \lstinline!connect! equations to
the connector \lstinline!c! in the models \lstinline!m!$i$. Consider the
following \lstinline!connect! equations found in the model for component \lstinline!m0!:
\begin{lstlisting}[language=modelica]
connect(m1.c, m3.c); // m1.c and m3.c are inside connectors
connect(m2.c, m3.c); // m2.c and m3.c are inside connectors
\end{lstlisting}
and in the model for component \lstinline!m3! (\lstinline!c.x! is a sub-connector inside
\lstinline!c!):
\begin{lstlisting}[language=modelica]
connect(c, m4.c); // c is an outside
connector, m4.c is an inside connector
connect(c.x, m5.c); // c.x is an outside
connector, m5.c is an inside connector
connect(c , d) ; // c is an outside connector, d is an outside connector
\end{lstlisting}
and in the model for component \lstinline!m6!:
\begin{lstlisting}[language=modelica]
connect(d, m7.c); // d is an outside connector, m7.c is an inside connector
\end{lstlisting}
\end{example}
\subsection{Expandable Connectors}\label{expandable-connectors}
If the \lstinline!expandable! qualifier is present on a connector definition, all
instances of that connector are referred to as expandable connectors.
Instances of connectors that do not possess this qualifier will be
referred to as non-expandable connectors.
Before generating connection equations non-parameter scalar variables and non-parameter array elements declared in expandable connectors are marked as only being
potentially present. A non-parameter array element may be declared with array dimensions \lstinline!:! indicating that the size is unknown (note that the size of
such a dimension cannot be determined using \lstinline!size!, see \cref{array-dimension-and-size-functions}). This applies to both variables of simple types,
and variables of structured types.
Then connections containing expandable connectors are elaborated:
\begin{itemize}
\item
One connector in the connect equation must reference a declared
component, and if the other connector is an undeclared element in a
declared expandable connector it is handled as follows (elements that
are only potentially present are not seen as declared):
\begin{itemize}
\item
The expandable connector instance is automatically augmented with a
new component having the used name and corresponding type.
\item
If the undeclared component is subscripted, an array variable is created, and a connection to the specific array element is performed. Introducing elements in an
array gives an array with at least the specified elements, other elements are either not created or have a default value (i.e.\ as if they were only potentially present,
and the same note regarding the use of `size` also applies here).
\item
If the variable on the other side of the connect-equation is input or output the new component will be either input or output to satisfy the restrictions in
\cref{restrictions-of-connections-and-connectors} for a non-expandable connector.
\begin{nonnormative}
If the existing side refers to an inside connector (i.e.\ a connector of a component) the new variable will copy its causality, i.e.\ input
if input and output if output, since the expandable connector must be an outside connector.
\end{nonnormative}
For an array the input/output property can be deduced separately for each array element.
\end{itemize}
\item
When two expandable connectors are connected, each is augmented with
the variables that are only declared in the other expandable connector
(the new variables are neither input nor output). This is repeated
until all connected expandable connector instances have matching
variables.
\begin{nonnormative}
I.e.\ each of the connector instances is expanded to be the union of all connector variables.
\end{nonnormative}
\item
The variables introduced in the elaboration follow additional rules
for generating connection sets (given in \cref{generation-of-connection-equations}).
\item
If a variable appears as an input in one expandable connector, it
should appear as a non-input in at least one other expandable
connector instance in the same augmentation set. An augmentation set
is defined as the set of connected expandable connector instances that
through the elaboration will have matching variables.
\begin{example}
\begin{lstlisting}[language=modelica]
expandable connector EngineBus
end EngineBus;
block Sensor
RealOutput speed; // Output, i.e., non-input
end Sensor;
block Actuator
RealInput speed; // Input
end Actuator;
model Engine
EngineBus bus;
Sensor sensor;
Actuator actuator;
equation
connect(bus.speed, sensor.speed); // provides the non-input from sensor.speed
connect(bus.speed, actuator.speed);
end Engine;
\end{lstlisting}
\end{example}
\item
All components in an expandable connector are seen as connector
instances even if they are not declared as such.
\begin{nonnormative}
I.e.\ it is possible to connect to e.g.\ a \lstinline!Real! variable.
\end{nonnormative}
\begin{example}
\begin{lstlisting}[language=modelica]
expandable connector EngineBus // has predefined signals
import Modelica.Units.SI;
SI.AngularVelocity speed;
SI.Temperature T;
end EngineBus;
block Sensor
RealOutput speed;
end Sensor;
model Engine
EngineBus bus;
Sensor sensor;
equation
connect(bus.speed, sensor.speed);
// connection to non-connector speed is possible
// in expandable connectors
end Engine;
\end{lstlisting}
\end{example}
\item
An expandable connector may not contain a component declared with the
prefix \lstinline!flow!, but may contain non-expandable connector components with
\lstinline!flow! components.
\begin{example}
\begin{lstlisting}[language=modelica]
import Interfaces=Modelica.Electrical.Analog.Interfaces;
expandable connector ElectricalBus
Interfaces.PositivePin p12, n12; // OK
flow Modelica.Units.SI.Current i; // Error
end ElectricalBus;
model Battery
Interfaces.PositivePin p42, n42;
ElectricalBus bus;
equation
connect(p42, bus.p42); // Adds new electrical pin
connect(n42, bus.n42); // Adds another pin
end Battery;
\end{lstlisting}
\end{example}
\item
expandable connectors can only be connected to other expandable connectors.
\end{itemize}
If a connect equation references a potentially present variable, or variable element, in an expandable connector the variable or variable element is marked as being present, and due to the
paragraphs above it is possible to deduce whether the bus variable shall be treated as input, or shall be treated as output in the connect equation. That \lstinline!input! or \lstinline!output!
prefix is added if no \lstinline!input!/\lstinline!output! prefix is present on the declaration.
\begin{example}
\begin{lstlisting}[language=modelica]
expandable connector EmptyBus
end EmptyBus;
model Controller
EmptyBus bus1;
EmptyBus bus2;
RealInput speed;
equation
connect(speed, bus1.speed); // OK; only one undeclared and not subscripted.
connect(bus1.pressure, bus2.pressure); // Error; both undeclared.
connect(speed, bus2.speed[2]); // Introduces speed array (with element [2]).
end Controller;
\end{lstlisting}
\end{example}
An expandable connector array component for which \lstinline!size! is not defined (see \cref{array-dimension-and-size-functions}) is referred to as a \emph{sizeless array component}. Such a
component may not be used without subscripts, and the subscripts must slice the array so that the sizeless dimensions are removed.
\begin{example}
Valid and invalid uses of sizeless array components:
\begin{lstlisting}[language=modelica]
expandable connector EngineBus
end EngineBus;
block Sensor
RealOutput speed;
end Sensor;
model Engine
parameter Integer n = 1;
EngineBus bus;
Sensor sensor;
RealOutput sensorSpeeds[:];
equation
/* Comments below refer to the use of sizeless array bus.speed. */
connect(bus.speed[n], sensor.speed) ; // OK; subscript to scalar component.
connect(bus.speed, sensorSpeeds); // Error; missing subscripts.
public
Real s[:] = bus.speed; // Error; missing subscripts.
Real s[2] = bus.speed[{1, 3}]; // OK; subscript selects fixed size sub-array.
end Engine;
\end{lstlisting}
\end{example}
After this elaboration the expandable connectors are treated as normal
connector instances, and the connections as normal connections, and all
potentially present variables and array elements that are not actually
present are undefined. It is an error if there
are expressions referring to potentially present variables or array
elements that are not actually present or non-declared variables. This
elaboration implies that expandable connectors can be connected even if
they do not contain the same components.
\begin{nonnormative}
A tool may remove undefined variables in an expandable connector, or set them to the default value, e.g.\ zero for \lstinline!Real! variables.
\end{nonnormative}
\begin{nonnormative}
Expressions can only ``read'' variables from the bus that
are actually declared and present in the connector, in order that the
types of the variables can be determined in the local scope.
\end{nonnormative}
\begin{nonnormative}
Note that the introduction of variables, as described above, is
conceptual and does not necessarily impact the flattening hierarchy in
any way. Furthermore, it is important to note that these elaboration
rules must consider:
\begin{enumerate}
\item Expandable connectors nested hierarchically. This means that
both outside and inside connectors must be included at every level of
the hierarchy in this elaboration process.
\item When processing an expandable connector that possesses the
\lstinline!inner! scope qualifier, all outer instances must also be taken into
account during elaboration.
\end{enumerate}
\end{nonnormative}
\begin{example}
Engine system with sensors, controllers, actuator and plant that
exchange information via a bus (i.e.\ via expandable connectors):
\begin{lstlisting}[language=modelica]
import Modelica.Units.SI;
import Modelica.Blocks.Interfaces.RealInput;
// Plant Side
model SparkPlug
RealInput spark_advance;
...
end SparkPlug;
expandable connector EngineBus
// No minimal set
end EngineBus;
expandable connector CylinderBus
Real spark_advance;
end CylinderBus;
model Cylinder
CylinderBus cylinder_bus;
SparkPlug spark_plug;
...
equation
connect(spark_plug.spark_advance,
cylinder_bus.spark_advance);
end Cylinder;
model I4
EngineBus engine_bus;
Modelica.Mechanics.Rotational.Sensors.SpeedSensor speed_sensor;
Modelica.Thermal.HeatTransfer.Sensors.TemperatureSensor temp_sensor;
parameter Integer nCylinder = 4 "Number of cylinders";
Cylinder cylinder[nCylinder];
equation
// adds engine_speed (as output)
connect(speed_sensor.w, engine_bus.engine_speed);
// adds engine_temp (as output)
connect(temp_sensor.T, engine_bus.engine_temp);
// adds cylinder_bus1 (a nested bus)
for i in 1:nCylinder loop
connect(cylinder[i].cylinder_bus,
engine_bus.cylinder_bus[i]);
end for;
end I4;
\end{lstlisting}
Due to the above connection, conceptually a connector consisting
of the union of all connectors is introduced.
The \lstinline!engine_bus! contains the following variable declarations:
\begin{lstlisting}[language=modelica]
RealOutput engine_speed;
RealOutput engine_temp;
CylinderBus cylinder_bus[1];
CylinderBus cylinder_bus[2];
CylinderBus cylinder_bus[3];
CylinderBus cylinder_bus[4];
\end{lstlisting}
\end{example}
\section{Generation of Connection Equations}\label{generation-of-connection-equations}
When generating connection equations, \lstinline!outer! elements are resolved to the
corresponding \lstinline!inner! elements in the instance hierarchy (see instance
hierarchy name lookup \cref{instance-hierarchy-name-lookup-of-inner-declarations}). The arguments to each \lstinline!connect!-equation are
resolved to two connector elements.
For every use of the \lstinline!connect!-equation
\begin{lstlisting}[language=modelica]
connect(a, b);
\end{lstlisting}
the primitive components of \lstinline!a! and \lstinline!b! form a connection set, together with an indication of whether they are from an inside or an outside connector. The primitive elements are
of simple types or of types defined as \lstinline!operator record! (i.e.\ a component of an \lstinline!operator record! type is not split into sub-components). The elements of the connection sets
are tuples of primitive variables together with an indication of inside or outside; if the same tuple belongs to two connection sets those two sets are merged, until every tuple is only present in
one set. Composite connector types are broken down into primitive components. The \lstinline!outer! components are handled by mapping the objects to the corresponding \lstinline!inner! components,
and the inside indication is not influenced. The outer connectors are handled by mapping the objects to the corresponding inner connectors, and they are always treated as outside connectors.
\begin{nonnormative}
Rationale: The inside/outside as part of the connection sets
ensure that connections from different hierarchical levels are treated
separately. Connection sets are formed from the primitive elements and
not from the connectors; this handles connections to parts of
hierarchical connectors and also makes it easier to generate equations
directly from the connection sets. All variables in one connection set
will either be flow variables or non-flow variables due to restriction
on connect-equations. The mapping from an \lstinline!outer! to an \lstinline!inner!
element must occur before merging the sets in order to get one
zero-sum equation, and ensures that the equations for the \lstinline!outer!
elements are all given for one side of the connector, and the
\lstinline!inner! element can define the other side.
\end{nonnormative}
The following connection sets with just one member are also present (and
merged):
\begin{itemize}
\item
Each primitive flow-variable as inside connector.
\item
Each flow variable \emph{added} during augmentation of expandable
connectors, both as inside and as outside.
\begin{nonnormative}
Note that the flow variable is not directly in the expandable connector, but in a connector inside the expandable connector.
\end{nonnormative}
\end{itemize}
\begin{nonnormative}
Rationale: If these variables are not connected they will
generate a set comprised only of this element, and thus they will be
implicitly set to zero (see below). If connected, this set will be
merged and adding this at the start has no impact.
\end{nonnormative}
Each connection set is used to generate equations for potential and flow
(zero-sum) variables of the form
\begin{itemize}
\item
$a_{1} = a_{2} = \ldots = a_{n}$ (neither flow nor stream variables)
\item
$z_{1} + z_{2} + (-z_{3}) + \ldots + z_{n} = \mathbf{0}$ (flow-variables)
\end{itemize}
The bold-face $\mathbf{0}$ represents an array or scalar zero of
appropriate dimensions (i.e.\ the same size as $z$).
For an \lstinline!operator record! type this uses the operator \lstinline!'0'! -- which must be defined in the operator record -- and all of the flow-variables for the \lstinline!operator record!
must be of the same \lstinline!operator record! type. This implies that in order to have flow variables of an \lstinline!operator record! type the \lstinline!operator record! must define addition,
negation, and \lstinline!'0'!; and these operations should define an additive group.
In order to generate equations for flow variables (using the
\lstinline!flow! prefix), the sign used for the connector variable
$z_{i}$ above is +1 for inside connectors and -1 for outside
connectors ($z_{3}$ in the example above).
\begin{example}
Simple example:
\begin{lstlisting}[language=modelica]
model Circuit
Ground ground;
Load load;
Resistor resistor;
equation
connect(load.p , ground.p);
connect(resistor.p, ground.p);
end Circuit;
model Load
extends TwoPin;
Resistor resistor;
equation
connect(p, resistor.p);
connect(resistor.n, n);
end Load;
\end{lstlisting}
The connection sets are before merging (note that one part of the load and resistor is not connected):
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.v!, inside\textgreater{}\}
After merging this gives:
\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!load.resistor.n.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}, \textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}, \textless{}\lstinline!resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}
And thus the equations:
\begin{lstlisting}[language=modelica]
load.p.v = load.resistor.p.v;
load.n.v = load.resistor.n.v;
load.p.v = ground.p.v;
load.p.v = resistor.p.v;
0 = (-load.p.i) + load.resistor.p.i;
0 = (-load.n.i) + load.resistor.n.i;
0 = load.p.i + ground.p.i + resistor.p.i;
0 = load.n.i;
0 = resistor.n.i;
\end{lstlisting}
\end{example}
\begin{example}
Outer component example:
\begin{lstlisting}[language=modelica]
model Circuit
Ground ground;
Load load;
inner Resistor resistor;
equation
connect(load.p, ground.p);
end Circuit;
model Load
extends TwoPin;
outer Resistor resistor;
equation
connect(p, resistor.p);
connect(resistor.n, n);
end Load;
\end{lstlisting}
The connection sets are before merging (note that one part of the load and resistor is not connected):
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!resistor.n.v!, inside\textgreater{}\}
After merging this gives:
\{\textless{}\lstinline!load.p.i!, outside\textgreater{}, \textless{}\lstinline!resistor.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, outside\textgreater{}, \textless{}\lstinline!resistor.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, outside\textgreater{}, \textless{}\lstinline!resistor.n.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.v!, outside\textgreater{}, \textless{}\lstinline!resistor.n.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.i!, inside\textgreater{}, \textless{}\lstinline!ground.p.i!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.p.v!, inside\textgreater{}, \textless{}\lstinline!ground.p.v!, inside\textgreater{}\}\\
\{\textless{}\lstinline!load.n.i!, inside\textgreater{}\}
And thus the equations:
\begin{lstlisting}[language=modelica]
load.p.v = resistor.p.v;
load.n.v = resistor.n.v;
load.p.v = ground.p.v;
0 = (-load.p.i) + resistor.p.i;
0 = (-load.n.i) + resistor.n.i;
0 = load.p.i + ground.p.i;
0 = load.n.i;
\end{lstlisting}
This corresponds to a direct connection of the resistor.
\end{example}
\section{Restrictions of Connections and Connectors}\label{restrictions-of-connections-and-connectors}
\begin{itemize}
\item
The connect-equations (and the special functions for overdetermined
connectors) may only be used in equations and may not be used inside
if-equations with non-parametric condition, or in when-equations.
\begin{nonnormative}
For-equations always have parameter expressions for the array expression.
\end{nonnormative}
\item
A connector component may not be declared with the prefix parameter or
constant. In the connect-equation the primitive components may only
connect parameter variables to parameter variables and constant
variables to constant variables.
\item
The connect-equation construct only accepts forms of connector
references as specified in \cref{connect-equations-and-connectors}.
\item
In a connect-equation the two connectors must have the same named
component elements with the same dimensions; recursively down to the
primitive components. The primitive components with the same name are
matched and belong to the same connection set.
\item
The matched primitive components of the two connectors must have the
same primitive types, and flow-variables may only connect to other
flow-variables, stream-variables only to other stream-variables, and
causal variables (\lstinline!input!/\lstinline!output!) only to causal variables
(\lstinline!input!/\lstinline!output!).
\item
A connection set of causal variables (\lstinline!input!/\lstinline!output!) may at most
contain variables from one inside \lstinline!output! connector or one public
outside \lstinline!input! connector.
\begin{nonnormative}
I.e., a connection set may at most contain one source of a signal.
\end{nonnormative}
\item
At least one of the following must hold for a connection set
containing causal variables generated for a non-partial model or
block:
\begin{enumerate}
\item the connection set includes variables from an outside public
expandable connector,
\item the set contains variables from protected
outside connectors,
\item it contains variables from one inside \lstinline!output!
connector, or
\item from one public outside \lstinline!input! connector, or
\item the set is comprised solely of one variable from one inside \lstinline!input!
connector that is not part of an expandable connector. \label{enum:exc-conn-case}
\end{enumerate}
\begin{nonnormative}
I.e., a connection set must -- unless the model or block is partial -- contain one source of a signal (\cref{enum:exc-conn-case}
covers the case where a connector of a component is left unconnected and the source given textually).
\end{nonnormative}
\item
Variables from a protected outside connector must be part of a
connection set containing at least one inside connector or one
declared public outside connector (i.e.\ it may not be an implicitly
defined part of an expandable connector).
\begin{nonnormative}
Otherwise it would not be possible to deduce the causality for the expandable connector element.
\end{nonnormative}
\item
In a connection set all variables having non-empty quantity attribute
must have the same quantity attribute.
\item
A \lstinline!connect! equation may not (directly or indirectly) connect two
connectors of \lstinline!outer! elements.
\begin{nonnormative}
Indirectly is similar to them being part of the same connection set. However, connections to \lstinline!outer! elements are ``moved up'' before forming
connection sets. Otherwise the connection sets could contain redundant information breaking the equation count for locally balanced models and blocks.
\end{nonnormative}
\item
Subscripts in a connector reference shall be parameter expressions or
the special operator \lstinline!:!.
\item
Constants or parameters in connected components yield the appropriate
assert statements to check that they have the same value; connections
are not generated.
\item
For conditional connectors, see \cref{conditional-component-declaration}.
\end{itemize}
\subsection{Balancing Restriction and Size of Connectors}\label{balancing-restriction-and-size-of-connectors}
For each non-partial non-expandable connector class the number of flow variables shall
be equal to the number of variables that are neither \lstinline!parameter!,
\lstinline!constant!, \lstinline!input!, \lstinline!output!, \lstinline!stream!
nor \lstinline!flow!. The \emph{number of variables} is
the number of all elements in the connector class after expanding all
records and arrays to a set of scalars of primitive types. The number of
variables of an overdetermined type or record class (see \cref{overconstrained-equation-operators-for-connection-graphs})
is the size of the output argument of the corresponding
\lstinline!equalityConstraint!() function.
\begin{nonnormative}
Expandable connector classes are excluded from this, since their component declarations are only a form of constraint.
\end{nonnormative}
\begin{example}
\begin{lstlisting}[language=modelica]
connector Pin // a physical connector of
Modelica.Electrical.Analog
Real v;
flow Real i;
end Pin;
connector Plug // a hierarchical connector of
Modelica.Electrical.MultiPhase
parameter Integer m=3;
Pin p[m];
end Plug;
connector InputReal = input Real; // A causal input connector
connector OutputReal = output Real; // A causal output connector
connector Frame_Illegal
Modelica.Units.SI.Position r0[3] "Position vector of frame origin";
Real S[3, 3] "Rotation matrix of frame";
Modelica.Units.SI.Velocity v[3] "Abs. velocity of frame origin";
Modelica.Units.SI.AngularVelocity w[3] "Abs. angular velocity of frame";
Modelica.Units.SI.Acceleration a[3] "Abs. acc. of frame origin";
Modelica.Units.SI.AngularAcceleration z[3] "Abs. angular acc. of frame";
flow Modelica.Units.SI.Force f[3] "Cut force";
flow Modelica.Units.SI.Torque t[3] "Cut torque";
end Frame_Illegal;
\end{lstlisting}
The \lstinline!Frame_Illegal! connector (intended to be used in a
simple MultiBody-package without over-determined connectors) is illegal
since the number of flow and non-flow variables do not match. The
solution is to create two connector classes, where two 3-vectors (e.g.,
a and z) are acausal Real and the other variables are matching pairs of
\lstinline!input! and \lstinline!output!. This ensures that the models can only be
connected in a tree-structure or require a ``loop-breaker'' joint for
every closed kinematic loop:
\begin{lstlisting}[language=modelica]
connector Frame_a "correct connector"
input Modelica.Units.SI.Position r0[3];
input Real S[3, 3];
input Modelica.Units.SI.Velocity v[3];
input Modelica.Units.SI.AngularVelocity w[3];
Modelica.Units.SI.Acceleration a[3];
Modelica.Units.SI.AngularAcceleration z[3];
flow Modelica.Units.SI.Force f[3];
flow Modelica.Units.SI.Torque t[3];
end Frame_a;
connector Frame_b "correct connector"
output Modelica.Units.SI.Position r0[3];
output Real S[3, 3];
output Modelica.Units.SI.Velocity v[3];
output Modelica.Units.SI.AngularVelocity w[3];
Modelica.Units.SI.Acceleration a[3];
Modelica.Units.SI.AngularAcceleration z[3];
flow Modelica.Units.SI.Force f[3];
flow Modelica.Units.SI.Torque t[3];
end Frame_b;
\end{lstlisting}
The subsequent connectors \lstinline!Plug_Expanded! and \lstinline!PlugExpanded2!
are correct, but \lstinline!Plug_Expanded_Illegal! is illegal since
the number of non-flow and flow variables is different if \lstinline!n! and \lstinline!m! are different. It is not clear how a tool can detect in
general that connectors such as \lstinline!Plug_Expanded_Illegal! are
illegal. However, it is always possible to detect this defect after
actual values of parameters and constants are provided in the simulation
model.
\begin{lstlisting}[language=modelica]
connector Plug_Expanded "correct connector"
parameter Integer m=3;
Real v[m];
flow Real i[m];
end Plug_Expanded;
connector Plug_Expanded2 "correct connector"
parameter Integer m=3;
final parameter Integer n=m;
Real v[m];
flow Real i[n];
end Plug_Expanded2;
connector Plug_Expanded_Illegal "connector is illegal"
parameter Integer m=3;
parameter Integer n=m;
Real v[m];
flow Real i[n];
end Plug_Expanded_Illegal;
\end{lstlisting}
\end{example}
\section{Equation Operators for Overconstrained Connection-Based Equation Systems}\label{equation-operators-for-overconstrained-connection-based-equation-systems1}
There is a special problem regarding equation systems resulting from
\emph{loops} in connection graphs where the connectors contain
\emph{non-flow} (i.e., potential) variables \emph{dependent} on each
other. When a loop structure occurs in such a graph, the resulting
equation system will be \emph{overconstrained}, i.e., have more
equations than variables, since there are implicit constraints between
certain non-flow variables in the connector in addition to the
connection equations around the loop. At the current state-of-the-art,
it is not possible to automatically eliminate the unneeded equations
from the resulting equation system without additional information from
the model designer.
This section describes a set of equation operators for such
overconstrained connection-based equation systems, that makes it
possible for the model designer to specify enough information in the
model to allow a Modelica environment to automatically remove the
superfluous equations.
\begin{nonnormative}
Connectors may contain redundant variables. For example, the
orientation between two coordinate systems in $3$ dimensions can be
described by $3$ independent variables. However, every description of
orientation with $3$ variables has at least one singularity in the region
where the variables are defined. It is therefore not possible to declare
only $3$ variables in a connector. Instead $n$ variables ($n > 3$) have to be used. These variables are no longer independent from each
other and there are $n - 3$ constraint equations that have to be fulfilled.
A proper description of a redundant set of variables with constraint
equations does no longer have a singularity. A model that has loops in
the connection structure formed by components and connectors with
redundant variables, may lead to a differential algebraic equation
system that has more equations than unknown variables. The superfluous
equations are usually consistent with the rest of the equations, i.e., a
unique mathematical solution exists. Such models cannot be treated with
the currently known symbolic transformation methods. To overcome this
situation, operators are defined in order that a Modelica translator can
remove the superfluous equations. This is performed by replacing the
equality equations of non-flow variables from connection sets by a
reduced number of equations in certain situations.
This section handles a certain class of overdetermined systems due
to connectors that have a redundant set of variables. There are other
causes of overdetermined systems, e.g., explicit zero-sum equations for
flow variables, that are not handled by the method described below.
\end{nonnormative}
\subsection{Overconstrained Equation Operators for Connection Graphs}\label{overconstrained-equation-operators-for-connection-graphs}
A type or record declaration may have an optional definition of function
\lstinline!equalityConstraint! that shall have the following prototype:
\begin{lstlisting}[language=modelica]
type Type // overdetermined type
extends <base type>;
function equalityConstraint // non-redundant equality
input Type T1;
input Type T2;
output Real residue[ <n> ];
algorithm
residue := ...
end equalityConstraint;
end Type;
record Record
< declaration of record fields>
function equalityConstraint // non-redundant equality
input Record R1;
input Record R2;
output Real residue[ <n> ];
algorithm
residue := ...
end equalityConstraint;
end Record;
\end{lstlisting}
The \lstinline!residue! output of the \lstinline!equalityConstraint! function shall have
known size, say constant n. The function shall express the equality
between the two type instances \lstinline!T1! and \lstinline!T2! or the record instances
\lstinline!R1! and
\lstinline!R2!, respectively, with a non-redundant number $n \ge 0$ of equations. The
residues of these equations are returned in vector \lstinline!residue! of size
$n$. The set of n non-redundant equations stating that \lstinline!R1 = R2! is given by
the equation (\lstinline!0! represents a vector of zeros of appropriate size):
\begin{lstlisting}[language=modelica]
Record R1, R2;
equation
0 = Record.equalityConstraint(R1,R2);
\end{lstlisting}
\begin{nonnormative}
If the elements of a record \lstinline!Record! are not independent from each other, the equation \lstinline!R1 = R2! contains redundant equations.
\end{nonnormative}
A type class with an \lstinline!equalityConstraint! function declaration is called \firstuse{overdetermined type}. A record class with an \lstinline!equalityConstraint! function definition is called
\firstuse{overdetermined record}. A connector that contains instances of overdetermined type and/or record classes is called overdetermined connector. An overdetermined type or record may neither
have flow components nor may be used as a type of flow components. If an array is used as argument to any of the \lstinline!Connections.*! functions it is treated as one unit -- unlike
\lstinline!connect!, there is no special treatment of this case, compare \cref{connect-equations-and-connectors}.
Every instance of an overdetermined type or record in an overdetermined
connector is a node in a virtual connection graph that is used to
determine when the standard equation \lstinline!R1 = R2! or when the equation
\lstinline!0 = equalityConstraint(R1, R2)! has to be used for the generation of
\lstinline!connect! equations. The edges of the virtual connection graph are
implicitly defined by \lstinline!connect! and explicitly by
\lstinline!Connections.branch! statements, see table below. \lstinline!Connections! is a
built-in package in global scope containing built-in operators.
Additionally, corresponding nodes of the virtual connection graph have
to be defined as roots or as potential roots with functions
\lstinline!Connections.root! and \lstinline!Connections.potentialRoot!, respectively.
In the following table, \lstinline!A! and \lstinline!B! are connector instances that may be
hierarchically structured, e.g., \lstinline!A! may be an abbreviation for
\lstinline!EnginePort.Frame!.
\begin{longtable}[]{|p{5.1cm}|p{10cm}|}
\hline \endhead
\lstinline!connect(A,B);! &
Defines \firstuse{optional spanning-tree edge} from the
overdetermined type or record instances in connector instance \lstinline!A! to the
corresponding overdetermined type or record instances in connector
instance \lstinline!B! for a virtual connection graph. The types of the
corresponding overdetermined type or record instances shall be the
same.\\ \hline
\lstinline!Connections.branch(A.R,B.R);! &
Defines a \firstuse{required spanning-tree edge}
from the overdetermined type or record instance \lstinline!R! in connector instance
\lstinline!A! to the corresponding overdetermined type or record instance \lstinline!R! in
connector instance \lstinline!B! for a virtual connection graph. This function can
be used at all places where a \lstinline!connect! statement is allowed.
\par
\begin{nonnormative*}
E.g., it is not allowed to use this function in a when-clause. This definition shall be used if in a model with connectors \lstinline!A! and \lstinline!B! the overdetermined
records \lstinline!A.R! and \lstinline!B.R! are algebraically coupled in the model, e.g., due to \lstinline!B.R = f(A.R!, \textless{}other unknowns\textgreater{}).
\end{nonnormative*}
\\ \hline
\lstinline!Connections.root(A.R);! & The overdetermined type or record instance \lstinline!R! in
connector instance \lstinline!A! is a (definite) \firstuse{root node} in a virtual connection graph.
\par
\begin{nonnormative*}
This definition shall be used if in a model with connector \lstinline!A! the overdetermined record \lstinline!A.R! is (consistently) assigned, e.g., from a parameter expressions.
\end{nonnormative*}
\\ \hline
\begin{tabular}{@{}p{5.1cm}@{}}
\lstinline!Connections.potentialRoot(A.R);!\\
\lstinline!Connections.potentialRoot(!\\
\lstinline!A.R, priority = p)!;
\end{tabular}
& The overdetermined type or record instance \lstinline!R! in connector instance \lstinline!A! is
a \firstuse{potential root node} in a virtual connection graph with priority
\lstinline!p! ($p\ge 0$). If no second argument is provided, the priority is zero.
\lstinline!p! shall be a parameter expression of type \lstinline!Integer!. In a
virtual connection subgraph without a \lstinline!Connections.root! definition, one
of the potential roots with the lowest priority number is selected as
root.
\par
\begin{nonnormative*}
This definition may be used if in a model with connector \lstinline!A! the overdetermined record \lstinline!A.R! appears differentiated -- \lstinline!der(A.R)! -- together
with the \emph{constraint equations} of \lstinline!A.R!, i.e., a non-redundant subset of \lstinline!A.R! maybe used as states.
\end{nonnormative*}
%\strut
%\end{minipage}
\\ \hline
\lstinline!b = Connections.isRoot(A.R);! & Returns true, if the overdetermined type
or record instance \lstinline!R! in connector instance A is selected as a root in
the virtual connection graph.\\ \hline
\begin{tabular}{@{}p{5.1cm}@{}}
\lstinline!b = Connections.rooted(A.R);!\\
\lstinline!b = rooted(A.R); // deprecated!
\end{tabular}
& If the operator \lstinline!Connections.rooted(A.R)!
is used, or the equivalent but deprecated operator \lstinline!rooted(A.R)!, then
there must be exactly one statement \lstinline!Connections.branch(A.R,B.R)!
involving \lstinline!A.R! (the argument of \lstinline!Connections.rooted! must be the first
argument of \lstinline!Connections.branch!). In that case \lstinline!Connections.rooted(A.R)!
returns true, if \lstinline!A.R! is closer to the root of the spanning tree than
\lstinline!B.R!; otherwise false is returned.
\par
\begin{nonnormative*}
This operator can be used to avoid equation systems by providing analytic inverses, see \lstinline!Modelica.Mechanics.MultiBody.Parts.FixedRotation!.
\end{nonnormative*}
\\ \hline
\end{longtable}
\begin{nonnormative}
Note, that \lstinline!Connections.branch!, \lstinline!Connections.root!,
\lstinline!Connections.potentialRoot! do not generate equations. They only
generate nodes and edges in the virtual graph for analysis purposes.
\end{nonnormative}
\subsection{Converting the Connection Graph into Trees and Generating Connection Equations}\label{converting-the-connection-graph-into-trees-and-generating-connection-equations}
Before \lstinline!connect! equations are generated, the virtual connection
graph is transformed into a set of spanning trees by removing optional spanning tree edges
from the graph. This is performed in the following way:
\begin{enumerate}
\item
Every root node defined via the \lstinline!Connections.root! statement is
a definite root of one spanning tree.
\item
The virtual connection graph may consist of sets of subgraphs that are
not connected together. Every subgraph in this set shall have at least
one root node or one potential root node in a simulation model. If a
graph of this set does not contain any root node, then one potential
root node in this subgraph that has the lowest priority number is
selected to be the root of that subgraph. The selection can be
inquired in a class with function \lstinline!Connections.isRoot!, see table
above.
\item
If there are n selected roots in a subgraph, then optional spanning-tree edges
have to be removed such that the result shall be a set of n spanning
trees with the selected root nodes as roots.
\end{enumerate}
After this analysis, the connection equations are generated in the
following way:
\begin{enumerate}
\item
For every optional spanning-tree edge (i.e., a \lstinline!connect(A, B)!
equation), in one of the spanning trees, the connection
equations are generated according to \cref{generation-of-connection-equations}.
\item
For every optional spanning-tree edge not in any of the spanning trees, the
connection equations are generated according to \cref{generation-of-connection-equations}, except
for overdetermined type or record instances R. Here the equations
\lstinline!0 = R.equalityConstraint(A.R, B.R)! are generated instead