forked from modelica/ModelicaSpecification
/
annotations.tex
2310 lines (1943 loc) · 125 KB
/
annotations.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{Annotations}\label{annotations}
Annotations are intended for storing extra information about a model, such as graphics, documentation or versioning, etc.
A Modelica tool is free to define and use other annotations, in addition to those defined here, according to \cref{vendor-specific-annotations}.
Annotations are optional in the Modelica grammar, and when present, indicated using the \lstinline!annotation!\indexinline{annotation} keyword, see \lstinline[language=grammar]!annotation-clause! in the grammar (\cref{expressions1}).
The structure of the annotation content is the same as a class modification (\lstinline[language=grammar]!class-modification! in the grammar).
(For replaceable class declarations with a \lstinline[language=grammar]!constraining-clause! also refer to \cref{constraining-clause-annotations}.)
The specification in this document defines the semantic meaning if a tool implements any of these annotations.
\section{Vendor-Specific Annotations}\label{vendor-specific-annotations}
A vendor may -- anywhere inside an annotation -- add specific, possibly undocumented, annotations which are not intended to be interpreted by other tools.
The only requirement is that any tool shall save files with all vendor-specific annotations (and all annotations from this chapter) intact.
Two variants of vendor-specific annotations\index{vendor-specific annotation} exist; one simple and one hierarchical.
Double underscore concatenated with a vendor name as initial characters of the identifier are used to identify vendor-specific annotations.
\begin{example}
\begin{lstlisting}[language=modelica]
annotation(
Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
graphics = {__NameOfVendor(Circle(center = {0, 0}, radius = 10))}));
\end{lstlisting}
This introduces a new graphical primitive \lstinline!Circle! using the
hierarchical variant of vendor-specific annotations.
\begin{lstlisting}[language=modelica]
annotation(
Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
graphics = {Rectangle(extent = {{-5, -5}, {7, 7}},
__NameOfVendor_shadow = 2)}));
\end{lstlisting}
This introduces a new attribute \lstinline!__NameOfVendor_shadow!
for the \lstinline!Rectangle! primitive using the simple variant of
vendor-specific annotations.
\end{example}
\section{Documentation}\label{annotations-for-documentation}\label{documentation}
The \fmtannotationindex{Documentation} annotation has the following contents, where the \lstinline!info! and \lstinline!revisions! annotations are described in \cref{annotation-info-revisions}, and the \lstinline!figures! annotation is described in \cref{annotations-for-figures}:
\begin{lstlisting}[language=modelica]
record Documentation
String info = "" "Description of the class";
String revisions = "" "Revision history";
Figure[:] figures = {}; "Simulation result figures";
end Documentation;
\end{lstlisting}
How the tool interprets the information in \lstinline!Documentation! is unspecified.
\subsection{Class Description and Revision History}\label{annotation-info-revisions}
Inside the \lstinline!Documentation! annotation, the \lstinline!info! annotation gives a textual description of the class, and the \lstinline!revisions! annotation gives a revision history.
\begin{nonnormative}
The \lstinline!revisions! documentation may be omitted in printed documentation.
\end{nonnormative}
If the string starts with the tag \lstinline!<html>! or \lstinline!<HTML>! the entire string is HTML encoded (and is assumed to end with \lstinline!</html>! or \lstinline!</HTML>! and shall be rendered as HTML even if the end-tags are missing), otherwise the entire string is rendered as is.
The HTML encoded content may contain links.
For external links, see \cref{external-resources}.
Links to Modelica classes may be defined with the HTML link command using scheme \lstinline!Modelica! (using its lower case form in the URI, see \cref{external-resources}), e.g.,
\begin{lstlisting}[language=modelica]
<a href="modelica:/MultiBody.Tutorial">MultiBody.Tutorial</a>
\end{lstlisting}
Together with scheme \lstinline!Modelica! the (URI) fragment specifiers
\lstinline!#diagram!, \lstinline!#info!, \lstinline!#text!, \lstinline!#icon! may be used to reference different
layers. User-defined fragment specifiers (anchors) may also be used, and they may be renamed
when generating HTML (in particular to avoid collisions).
Example:
\begin{lstlisting}[language=modelica]
<a href="modelica:/MultiBody.Joints.Revolute#info">Revolute</a>
\end{lstlisting}
\subsection{Figures}\label{annotations-for-figures}\label{figures}
Inside the \lstinline!Documentation! annotation, each element of the \lstinline!figures! annotation array has the following content:
\begin{lstlisting}[language=modelica]
record Figure
String title = "" "Title meant for display";
String identifier = "" "Identifier meant for programmatic access";
String group = "" "Name of plot group";
Boolean preferred = false "Automatically display figure after simulation";
Plot[:] plots "Plots";
String caption = "" "Figure caption";
end Figure;
\end{lstlisting}
A \fmtannotationindex{Figure} is a graphical container that can contain several \lstinline!plots! described by \fmtannotationindex{Plot} annotations:
\begin{lstlisting}[language=modelica]
record Plot
String title "Title meant for display";
String identifier = "" "Identifier meant for programmatic access";
Curve[:] curves "Plot curves";
Axis x "X axis properties";
Axis y "Y axis properties";
end Plot;
\end{lstlisting}
A \lstinline!Plot! can contain several \lstinline!curves!, see \cref{plot-curves}, that all share a common \lstinline!x! and \lstinline!y! axis with properties described in \cref{axis-properties}.
Both \lstinline!Figure! and \lstinline!Plot! can have an optional title.
When the \lstinline!Figure! \lstinline!title! is the empty string (the default), the tool must produce a non-empty title based on the figure content.
On the other hand, the \lstinline!Plot! \lstinline!title! has a tool-dependent default, but the default may be the empty string.
When the \lstinline!Plot! \lstinline!title! is the empty string, no title should be shown.
The plot title is not to be confused with the plot \emph{label} which is never empty, see below.
Variable replacements, as described in \cref{variable-replacements}, can be used in the \lstinline!title! of \lstinline!Figure! and \lstinline!Plot!.
The \lstinline!identifier! in \lstinline!Figure! and \lstinline!Plot! is a \lstinline!String! identifier, and is intended to identify the \lstinline!Figure! and \lstinline!Plot! for programmatic access.
The \lstinline!figures! annotation is inherited in the sense that each class has a collection of figures comprised by the contents of the \lstinline!figures! annotation in the class itself, as well as the \lstinline!figures! annotations from any base classes.
A \lstinline!Figure! must be uniquely identified by its \lstinline!identifier! and a class having it in its collection.
This means that a \lstinline!Figure! \lstinline!identifier! must be unique among all \lstinline!Figure! annotations within the same \lstinline!figures! annotation as well as among all \lstinline!figures! annotations from inherited classes.
A \lstinline!Plot! \lstinline!identifier! on the other hand is only required to be unique among the \lstinline!plots! in the the same \lstinline!Figure! annotation.
If an \lstinline!identifier! is an empty string it cannot be used for programmatic access and is exempt from the uniqueness requirements.
\begin{nonnormative}
For \lstinline!Figure!, this makes it possible to reference the plot from a tool-specific scripting environment.
For \lstinline!Plot!, this makes it possible to reference the plot in the figure caption, which becomes useful when the \lstinline!Figure! contains more than one \lstinline!Plot!.
\end{nonnormative}
% henrikt-ma 2020-06: Once there is Modelica URI support for referring to a figure in the collection of a class, it will be easier to explain
% the following statement.
Even though a \lstinline!Figure! annotation can be shared through inheritance between classes in a class hierarchy, note that each simulated class provides its own data to be displayed in the figure.
Every \lstinline!Plot! has an automatically generated \emph{label} which is required to be shown as soon as at least one \lstinline!Plot! in the \lstinline!Figure! has an \lstinline!identifier!.
A tool is free to choose both labeling scheme (such as \emph{a}, \emph{b}, \dots, or \emph{i}, \emph{ii}, \dots), placement in the plot, and styling in the plot itself as well as in other contexts.
When a \lstinline!Figure! defines a non-empty \lstinline!group!, it is used to organize figures similar to how \lstinline!group! is used in the \lstinline!Dialog! annotation (see \cref{annotations-for-the-graphical-user-interface}).
However, leaving \lstinline!group! at the default of an empty string does not mean that a group will be created automatically, but that the figure resides outside of any group.
The \lstinline!group! is both the key used for grouping, and the name of the group for display purposes.
The \lstinline!preferred! attribute of \lstinline!Figure! indicates whether the figure should be given preference when automatically determining which figures to show, and a class may define any number of \lstinline!preferred! figures.
For example, a tool might choose to automatically show all preferred figures when the class is simulated.
The \lstinline!caption! attribute of \lstinline!Figure! can use the restricted form of text markup described in \cref{text-markup-in-captions} as well as the variable replacements described in \cref{variable-replacements}.
\subsubsection{Axis Properties}\label{axis-properties}
Properties may be defined for each \lstinline!Plot! axis\annotationindex{Axis}:
\begin{lstlisting}[language=modelica]
record Axis
Real min "Axis lower bound, in 'unit'";
Real max "Axis upper bound, in 'unit'";
String unit = "" "Unit of axis tick labels";
String label "Axis label";
AxisScale scale = Linear() "Mapping between axis values and position on axis"
end Axis;
\end{lstlisting}
When an axis bound is not provided, the tool computes one automatically.
A non-empty \lstinline!unit! shall match \lstinline[language=grammar]!unit-expression! in \cref{unit-expressions}.
An empty \lstinline!unit! means that the axis is unitless, and each expression plotted against it may use its own unit determined by the tool.
The tool is responsible for conveying the information about choice of unit for the different variables, for instance by attaching this information to curve legends.
The Modelica tool is responsible for showing that values at the axis tick marks are expressed in \lstinline!unit!, so the axis \lstinline!label! shall not contain this information.
\begin{nonnormative}
When \lstinline!unit! is empty, and axis bounds are to be determined automatically, a natural choice of unit could be the variable's \lstinline!displayUnit!. When axis bounds are specified by the user, on the other hand, a tool may choose a unit for the variable such that the range of the variable values (expressed in the chosen unit) fit nicely with the range of the unitless axis.
\end{nonnormative}
If a tool does not recognize the \lstinline!unit!, it is recommended to issue a warning and treat the \lstinline!unit! as if it was empty, as well as ignore any setting for \lstinline!min! and \lstinline!max!.
When \lstinline!label! is not provided, the tool produces a default label.
Providing the empty string as \lstinline!label! means that no label should be shown.
Variable replacements, as described in \cref{variable-replacements}, can be used in \lstinline!label!.
The Modelica tool is responsible for showing the unit used for values at the axis tick marks, so the axis \lstinline!label! shall not contain the unit.
The type of \lstinline!scale! is defined as an empty partial record:
\begin{lstlisting}[language=modelica]
partial record AxisScale
end AxisScale;
\end{lstlisting}%
\annotationindex{AxisScale}
The standardized annotations extending from \lstinline!AxisScale! are \lstinline!Linear! and \lstinline!Log!, but it is also allowed to use a vendor-specific annotation.
Use \lstinline!Linear! for a linear mapping between axis values and position on axis:
\begin{lstlisting}[language=modelica]
record Linear
extends AxisScale;
end Linear;
\end{lstlisting}%
\index{Linear@\robustinline{Linear} (axis scale)}
Use \lstinline!Log! for a logarithmic mapping between axis values and position on axis:
\begin{lstlisting}[language=modelica]
record Log
extends AxisScale;
Integer base(min = 2) = 10;
end Log;
\end{lstlisting}%
\index{Log@\robustinline{Log} (axis scale)}
The \lstinline!base! of a \lstinline!Log! scale determines preferred positions of major axis ticks.
It is not required that the presentation of axis tick labels reflect the \lstinline!base! setting.
For example, when \lstinline!base! is 10, major axis ticks should preferrably be placed at integer powers of 10, and natural alternatives that a tool may use for major axis tick labels could look like $0.001$ or $10^{-3}$.
Under some circumstances, such as when the axis range does not span even a single order of magnitude, a tool may disregard the preference in order to get useful axis ticks.
\begin{example}
A \emph{symmetric log} axis scale is sometimes used for axes spanning across several orders of magnitude of both positive and negative values.
Details vary, but the mapping from value to linear position along axis is some variation of $y \mapsto \operatorname{sign}(y)\, \operatorname{log}(1 + \frac{\abs{y}}{10^{\alpha}})$.
A tool may implement this as a vendor-specific axis scale:
\begin{lstlisting}[language=modelica]
Axis(
min = -1e5, max = 1e5,
scale = __NameOfVendor_symlog(1),
)
\end{lstlisting}
\end{example}
\subsubsection{Plot Curves}\label{plot-curves}
The actual data to plot is specified in the \lstinline!curves!\annotationindex{Curve} of a \lstinline!Plot!:
\begin{lstlisting}[language=modelica]
record Curve
expression x = time "X coordinate values";
expression y "Y coordinate values";
String legend "Legend";
end Curve;
\end{lstlisting}
The mandatory \lstinline!x! and \lstinline!y! expressions are restricted to be result references in the form of \lstinline[language=grammar]!result-reference! in the grammar (\cref{expressions1}), referring to a scalar variable (or a derivative thereof) or \lstinline!time!.
It is an error if \lstinline!x! or \lstinline!y! does not designate a scalar result.
If \lstinline!x! or \lstinline!y! is a derivative, \lstinline!der(v, $n$)!, then $n$ must not exceed the maximum amount of differentiation applied to \lstinline!v! in the model.
A diagnostic is recommended in case the simulation result is missing a trajectory for a valid result reference.
\begin{nonnormative}
While the syntax for referring to a second order derivative is \lstinline!der(v, 2)!, the appearance is left for tools to decide.
For example, a tool might choose to present this as \lstinline!der(der(v))!.
\end{nonnormative}
When the \lstinline!unit! of an \lstinline!Axis! is non-empty, it is an error if the unit of the corresponding \lstinline!x! or \lstinline!y! expression (i.e., a variable's \lstinline!unit!, or second for \lstinline!time!) is incompatible with the axis unit.
When \lstinline!legend! is not provided, the tool produces a default based on \lstinline!x! and/or \lstinline!y!.
Providing the empty string as \lstinline!legend! means that the curve shall be omitted from the plot legend.
Variable replacements, as described in \cref{variable-replacements}, can be used in \lstinline!legend!.
\subsubsection{Escape Sequences}\label{text-markup-escape-sequences}
In an attribute inside a figure where the variable replacements of \cref{variable-replacements} or the text markup of \cref{text-markup-in-captions} can be used, the following use of \firstuse[text markup escape sequence]{text markup escape sequences}\index{escape sequence!text markup} applies.
These escape sequences are applied after the application of other markup, and is not applied at all inside some of the other markup, see details for the respective markup.
The percent character `\%' shall be encoded \lstinline!%%!. The following are all the recognized escape sequences:
\begin{center}
\begin{tabular}{c c l}
\hline
\tablehead{Sequence} & \tablehead{Encoded character} & \tablehead{Comment}\\
\hline
\hline
{\lstinline!%%!} & `\%' & Only way to encode character. \\
{\lstinline!%]!} & `]' & Prevents termination of markup delimited by {\lstinline![$\ldots$]!}. \\
\hline
\end{tabular}
\end{center}
\begin{nonnormative}
With the percent character being encoded as \lstinline!%%!, the behavior of \lstinline!%! appearing in any other way than the escape sequences above, for variable replacement (\cref{variable-replacements}), or for the text markup (\cref{text-markup-in-captions}) is undefined, and thus possible to define in the future without breaking backward compatibility.
\end{nonnormative}
\subsubsection{Variable Replacements}\label{variable-replacements}
In the places listed in \cref{attributes-with-variable-replacements} where text for display is defined, the final value of a result variable can be embedded by referring to the variable as \lstinline!%{inertia1.w}!.
This is similar to the \lstinline!Text! graphical primitive in \cref{text}.
\begin{table}[H]
\caption{Attributes that can use variable replacements.}
\label{attributes-with-variable-replacements}
\begin{center}
\begin{tabular}{l l}
\hline
\tablehead{Attribute} & \tablehead{Annotation}\\
\hline
\hline
{\lstinline!title!} & {\lstinline!Figure!} and {\lstinline!Plot!} \\
{\lstinline!caption!} & {\lstinline!Figure!} \\
{\lstinline!legend!} & {\lstinline!Curve!} \\
{\lstinline!label!} & {\lstinline!Axis!} \\
\hline
\end{tabular}
\end{center}
\end{table}
In \lstinline!%{$\mathit{variable}$}!, text markup escape sequences don't apply inside the $\mathit{variable}$, which has the form of \lstinline[language=grammar]!result-reference!.
This means that a complete \lstinline[language=grammar]!result-reference! shall be scanned before looking for the terminating closing brace.
\begin{example}
The variable replacement \lstinline!%{'%%'}! references the variable \lstinline!'%%'!, not the variable \lstinline!'%'!.
\end{example}
\begin{example}
The variable replacement \lstinline!%{foo . '}bar{'}! makes a valid reference to the variable\linebreak[4] \lstinline!foo.'}bar{'!.
\end{example}
Note that expansion to the final value means that expansion is not restricted to parameters and constants, so that values to be shown in a caption can be determined during simulation.
\begin{nonnormative}
By design, neither \lstinline!%class! nor \lstinline!%name! is supported in this context, as this information is expected to already be easily accessible (when applicable) in tool-specific ways.
(Titles making use of \lstinline!%class! or \lstinline!%name! would then only lead to ugly duplication of this information.)
\end{nonnormative}
\subsubsection{Text Markup in Captions}\label{text-markup-in-captions}
In addition to variable replacements, a very restricted form of text markup is used for the \lstinline!caption!.
Note that the text markup escape sequences described in \cref{text-markup-escape-sequences} generally apply inside \lstinline!caption!, with one exception given below for links.
Links take the form \lstinline!%[$\mathit{text}$]($\mathit{link}$)!, where the \lstinline![$\mathit{text}$]! part is optional, and text markup escape sequences don't apply inside the $\mathit{link}$.
The $\mathit{link}$ can be in either of the following forms, where the interpretation is given by the first matching form:
\begin{itemize}
\item
A \lstinline!variable:$\mathit{id}$!, where $\mathit{id}$ is a component reference in the form of \lstinline[language=grammar]!result-reference! in the grammar, such as \lstinline!inertia1.w!.
\item
% The 'plot:id' form below should be deprecated in favor of using an improved form of Modelica URI reference in the future, making 'variable:id' the only non-URI reference.
A \lstinline!plot:$\mathit{id}$!, where $\mathit{id}$ is the identifier of a \lstinline!Plot! in the current \lstinline!Figure!.
\item
% Use very short Modelica URI combined with carefully chosen wording below to deal with difficult line breaking.
A URI.
Well established schemes such as \lstinline[language={[nocomment]modelica}]!https://github.com/modelica! or \lstinline[language={[nocomment]modelica}]!modelica:/Modelica!, as well as lesser known schemes may be used.
(A tool that has no special recognition of a scheme can try sending the URI to the operating system for interpretation.)
\end{itemize}
When \lstinline![$\mathit{text}$]! is omitted, a Modelica tool is free to derive a default based on the $\mathit{link}$.
\begin{nonnormative}
Note that for the character `]' to appear in $\mathit{text}$, it needs to be encoded as the escape sequence \lstinline!%]!, or it would be interpreted as the terminating delimiter of the \lstinline![$\mathit{text}$]!.
Similarly, the closing parenthesis `)' must be handled with care in $\mathit{link}$ in order to not be interpreted as the terminating delimiter of the \lstinline!($\mathit{link}$)!.
\begin{itemize}
\item
For a \lstinline!variable:!, no special treatment is needed, as the component reference syntax of the $\mathit{id}$ allows parentheses to appear without risk of misinterpretation inside a quoted identifier.
For example, \lstinline"%(variable:'try)me!')" has a parenthesis in \lstinline"'try)me!'" that must not be mistaken for the end of the \lstinline!($\mathit{link}$)!.
% The following shortcoming would be resolved if the 'plot:id' form was replaced by a Modelica URI reference, thanks to URL encoding.
\item
For a \lstinline!plot:!, there is currently no way to reference a plot with `)' in its \lstinline!identifier!.
\item
For a URI, a closing parenthesis must be URL encoded in order to not be interpreted as the end of the \lstinline!($\mathit{link}$)!.
For example, the URL in \lstinline[language={[nocomment]modelica}]!%(http://example.org/(tryme))! is just \filename{http://example.org/(tryme}, and the entire link is followed by a stray closing parenthesis.
To make it work, one has to use URL encoding: \lstinline[language={[nocomment]modelica}]!%(http://example.org/%28tryme%29)! (using URL encoding of the opening parenthesis just for symmetry, and note that the \lstinline!%! of the percent-encoded sequences are not subject to text markup escape sequences).
\end{itemize}
\end{nonnormative}
The styling of the link text, as well as the link action, is left for each Modelica tool to decide.
\begin{nonnormative}
For example, \lstinline!%(variable:inertia1.w)! could be displayed as the text \lstinline!inertia1.w! formatted with upright monospaced font, and have a pop-up menu attached with menu items for plotting the variable, setting its start value, or investigating the equation system from which it is solved.
On the other hand, \lstinline!%[angular velocity](variable:inertia1.w)! could be formatted in the same style as the surrounding text, except some non-intrusive visual clue about it being linked.
\end{nonnormative}
\begin{nonnormative}
% This non-normative text explains why we don't want to assume that the 'link' must have a scheme.
Note that $\mathit{link}$ is currently not allowed to be a \emph{URI reference}, i.e., a URI or a \emph{relative reference} such as \lstinline!#foo!.
This is due to to the current inability to define a base URI referencing the current figure.
Once this becomes possible, the URI form of $\mathit{link}$ may be changed into a URI reference.
\end{nonnormative}
A sequence of one or more newlines (encoded either literally or using the \lstinline!\n! escape sequence) means a paragraph break.
(A line break within a paragraph is not supported, and any paragraph break before the first paragraph or after the last paragraph has no impact.)
\firstuse[vendor-specific markup]{Vendor-specific markup} takes the form \lstinline!%__$\mathit{nameOfVendor}_{1}$($\mathit{data}_{1}$)$\ldots$__$\mathit{nameOfVendor}_{n}$($\mathit{data}_{n}$)[$\mathit{text}$]!, where $n \geq 1$.
The $\mathit{nameOfVendor}$ consists of only digits and letters, and shall only convey the name of the vendor defining the meaning of the associated $\mathit{data}$.
Text markup escape sequences don't apply inside the $\mathit{data}$, implying that it cannot contain the closing parenthesis, `)'.
A tool which does not understand any of the vendor-specific meanings shall only display the mandatory $\mathit{text}$, but the $\mathit{text}$ may also be used together with the vendor-specific $\mathit{data}$.
\begin{example}
One application of vendor-specific markup is to prototype a feature that can later be turned into standardized markup.
For example, say that the tool AVendor wants to generalize the variable replacements such that the duration of a simulation can be substituted into a caption.
During the development, this could be represented as the vendor-specific markup \lstinline!%__AVendor(?duration)[10 s]!, if the simulation has a duration of 10~seconds at the time of writing the caption.
When AVendor renders this, it ignores the text \lstinline!10 s! and just displays the actual duration instead.
Later, if this would become supported by standard markup, it might take the form of something like \lstinline!%{experiment:duration}! instead (note that \lstinline!experiment:duration! is not in the form of a component reference, avoiding conflict with current use of variable replacements).
In a similar way, vendor-specific markup can be used to prototype a link for future inclusion in the link markup (either by extending the meaning of Modelica URIs, or by introducing another pseudo-scheme similar to \lstinline!variable:!).
This is an example where the vendor-specific markup could make use of the $\mathit{text}$ (for link text) together with the vendor-specific $\mathit{data}$ (describing the actual link).
\end{example}
\section{Symbolic Processing}\label{annotations-for-symbolic-processing}\label{symbolic-processing}
The annotation listed below, in addition to annotations described in \crefrange{derivatives-and-inverses-of-functions}{function-inlining-and-event-generation}, can influence the symbolic processing.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!Evaluate!} & Use parameter value for symbolic processing & \Cref{modelica:Evaluate}\\
\hline
\end{tabular}
\end{center}
\begin{annotationdefinition}[Evaluate]
\begin{synopsis}[grammar]\begin{lstlisting}
"Evaluate" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
The annotation \lstinline!Evaluate! can occur in the component declaration, its type declaration, or a base class of the type-declaration.
In the case of multiple conflicting annotations it is handled similarly to modifiers (e.g., an \lstinline!Evaluate! annotation on the component declaration takes precedence).
In the case of hierarchical components it is applied to all components, overriding any \lstinline!Evaluate!-setting for specific components.
The annotation \lstinline!Evaluate! is only allowed for parameters and constants.
Setting \lstinline!Evaluate = true! for an evaluable parameter, means that it must be an evaluated parameter (i.e., its value must be determined during translation, similar to a constant).
For a non-evaluable parameter, it has no impact and it is recommended to issue a warning in most cases.
The exception for recommending this warning is when the parameter is non-evaluable due to dependency on a parameter with \lstinline!Evaluate = false!, as this could be a sign of intentional overriding of \lstinline!Evaluate = true!, see example below.
For both evaluable parameters and constants, the model developer further proposes to utilize the value for symbolic processing.
A constant can never be changed after translation, and it is normal for its value to be used for symbolic processing even without \lstinline!Evaluate = true!.
For a parameter, \lstinline!Evaluate = false! ensures that the parameter is a non-evaluable parameter according to \cref{component-variability} (meaning it is not allowed to be used where an evaluable expression (\cref{evaluable-expressions}) is expected).
For both parameters and constants -- even when the value can be determined during translation -- the model developer further proposes to not utilize the value for symbolic processing.
\begin{nonnormative}
\lstinline!Evaluate = true! is for example used for axis of rotation parameters in the \lstinline!Modelica.Mechanics.MultiBody! library in order to improve the efficiency of the generated code.
Conversely, a possible use of \lstinline!Evaluate = false! is to ensure that a parameter can be changed after translation, even when a tool might be tempted to evaluate it to improve the efficiency of the generated code.
\end{nonnormative}
\begin{example}
When a parameter has \lstinline!Evaluate = true! for optimization reasons (not because it needs to be evaluable), it is possible to prevent the value from being determined during translation without modifying the original model:
\begin{lstlisting}[language=modelica]
model M_evaluable
/* Here, 'b' is evaluable, and will be evaluated. */
parameter Boolean b = false annotation(Evaluate = true);
Real x(start = 1.0, fixed = true);
equation
if b then /* No need for b to be evaluable. */
der(x) = x;
else
der(x) = -x;
end if;
end M_evaluable;
model M_non_evaluable
/* Here, 'bn' is non-evaluable, which in turn will cause 'b' to be
* non-evaluable, thereby preventing it from being determined during
* translation.
*/
extends M_evaluable(b = bn);
parameter Boolean bn = false annotation(Evaluate = false);
end M_non_evaluable;
\end{lstlisting}
\end{example}
\end{semantics}
\end{annotationdefinition}
\section{Simulations}\label{annotations-for-simulations}\label{simulations}
The annotations listed below define how models can be checked, translated, and simulated.
\begin{center}
\begin{tabular}{l|l l}
\hline
\tablehead{Annotation} & \tablehead{Description} & \tablehead{Details}\\
\hline
\hline
{\lstinline!experiment!} & Simulation experiment settings & \Cref{modelica:experiment}\\
{\lstinline!HideResult!} & Don't show component's simulation result & \Cref{modelica:HideResult}\\
{\lstinline!TestCase!} & Information for model used as test case & \Cref{modelica:TestCase}\\
\hline
\end{tabular}
\end{center}
\begin{annotationdefinition}[experiment]
% henrikt-ma 2021-04: Seems strange to allow 'experiment' completely without list of options -- what would it mean?
\begin{synopsis}[grammar]\begin{lstlisting}
"experiment"
[ "(" [ experimentOption { "," experimentOption } ] ")" ]
experimentOption:
"StartTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER
| "StopTime" "=" [ "+" | "-" ] UNSIGNED-NUMBER
| "Interval" "=" UNSIGNED-NUMBER
| "Tolerance" "=" UNSIGNED-NUMBER
\end{lstlisting}\end{synopsis}
\begin{semantics}
The \lstinline{experiment} annotation defines the default start time (\lstinline!StartTime!) in {[}s{]}, the default stop time (\lstinline!StopTime!) in {[}s{]}, the suitable time resolution for the result grid (\lstinline!Interval!) in {[}s{]}, and the default relative integration tolerance (\lstinline!Tolerance!) for simulation experiments to be carried out with the model or block at hand.
If \lstinline!StartTime! is not specified it is assumed to be \lstinline!0.0!.
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[HideResult]
\begin{synopsis}[grammar]\begin{lstlisting}
"HideResult" "=" ( false | true )
\end{lstlisting}\end{synopsis}
\begin{semantics}
\lstinline!HideResult = true! defines that the model developer proposes to not show the simulation results of the corresponding component.
\lstinline!HideResult = false! defines that the developer proposes to show the corresponding component.
\begin{nonnormative}
For example, a tool is not expected to provide means to plot a variable with \lstinline!HideResult = true!. If a variable is declared in a protected section, a tool might not include it in a simulation result. By setting \lstinline!HideResult = false!, the modeler would like to have the variable in the simulation result, even if in the protected section.
\lstinline!HideResult! is for example used in the connectors of the \lstinline!Modelica.StateGraph! library to not show variables to the modeler that are of no interest to him and would confuse him.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\begin{annotationdefinition}[TestCase]
\begin{synopsis}[grammar]\begin{lstlisting}
"TestCase" "(" "shouldPass" "=" ( false | true ) ")"
\end{lstlisting}\end{synopsis}
\begin{semantics}
If \lstinline!shouldPass! is \lstinline!false! it indicates that the translation or the simulation of the model should fail.
If a tools checks a package where classes have \lstinline!shouldPass = false! they should not generate errors, and checking may even be skipped.
On the other hand, models with \lstinline!shouldPass = false! may be useful for creation of negative tests in tool-specific ways.
Similarly as a class with obsolete-annotation, a class with \lstinline!TestCase! annotation (regardless of the value of \lstinline!shouldPass!) shall not be used in other models, unless those models also have a \lstinline!TestCase! annotation.
\begin{nonnormative}
The intent of the test-case can be included in the documentation of the class.
This annotation can both be used for models intended as test-cases for implementations, and for models explaining detectable errors.
\end{nonnormative}
\end{semantics}
\end{annotationdefinition}
\section{Usage Restrictions}\label{usage-restrictions}
\subsection{Single Use of Class}\label{annotation-for-single-use-of-class}\label{single-use-of-class}
For state machines it is useful to have single instances of local classes.
This can be done using:
\begin{lstlisting}[language=modelica]
annotation(singleInstance = true)
\end{lstlisting}
The annotation \fmtannotationindex{singleInstance} in a class indicates that there should only be one component instance of the class, and it should be in the same scope as the class is defined.
The intent is to remove the class when the component is removed and to prevent duplication of the component.
\subsection{Connection Restrictions}\label{connection-restrictions}
A connector component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
annotation(mustBeConnected = "message");
\end{lstlisting}%
\annotationindex{mustBeConnected}
It makes it an error if the connector is not connected from the outside (for a conditional connector this check is only active if the connector is enabled).
For an array of connectors it applies separately to each element.
\begin{nonnormative}
This annotation is intended for non-causal connectors, see \cref{restrictions-of-connections-and-connectors}.
It is particularly suited for stream connectors, see \cref{stream-connectors}.
\end{nonnormative}
\begin{example}
This can be used for some optional connectors that should be connected when conditionally enabled.
\begin{lstlisting}[language=modelica]
partial model PartialWithSupport
Flange_b flange;
parameter Boolean useSupport;
Support support if useSupport
annotation(
mustBeConnected = "Support connector should be connected if activated.");
end PartialWithSupport;
\end{lstlisting}
The protected components and connections needed to internally handle the support-connector is omitted.
\end{example}
A connector component declaration may have the following annotation:
\begin{lstlisting}[language=modelica]
annotation(mayOnlyConnectOnce = "message");
\end{lstlisting}%
\annotationindex{mayOnlyConnectOnce}
It makes it an error if the connector is connected from the outside and:
\begin{itemize}
\item For non-stream connectors the connection set has more than two elements.
\item For stream connectors (see \cref{stream-connectors}), the connection set has more than two elements whose flow variable may be negative (based on evaluation of the \lstinline!min!-attribute).
\end{itemize}
For an array of connectors it applies separately to each element.
\begin{nonnormative}
This annotation is intended for non-causal connectors, see \cref{restrictions-of-connections-and-connectors}.
The connection handling operates on connection sets, and thus this restriction should also operate on those sets.
The set handling avoids the case where only one of two equivalent models generate diagnostics.
The stream connector part is primarily intended to exclude sensor-variables, see \cref{connection-of-3-stream-connectors-where-one-mass-flow-rate-is-identical-to-zero-n-3-and}, but also excludes non-reversible outgoing flows.
\end{nonnormative}
\begin{example}
This can be used for components that implement mixing of fluids where it is not desired to combine that with the normal stream-connector mixing.
\begin{lstlisting}[language=modelica]
partial model MultiPort
parameter Integer n = 0 annotation(Dialog(connectorSizing = true));
FluidPort_a port_a(redeclare package Medium = Medium);
FluidPorts_b ports_b[n](redeclare each package Medium = Medium)
annotation (mayOnlyConnectOnce = "Should only connect once per element!");
end MultiPort;
\end{lstlisting}
\end{example}
\section{Graphical Objects}\label{annotations-for-graphical-objects}\label{graphical-objects}
A graphical representation of a class consists of two abstraction
layers, icon layer and diagram layer showing graphical objects,
component icons, connectors and connection lines. The icon
representation typically visualizes the component by hiding hierarchical
details. The hierarchical decomposition is described in the diagram
layer showing icons of subcomponents and connections between these.
Graphical annotations described in this chapter ties into the Modelica
grammar as follows.
\begin{lstlisting}[language=grammar]
graphical-annotations :
annotation "(" [ layer-annotations ] ")"
layer-annotations :
( icon-layer | diagram-layer ) [ "," layer-annotations ]
\end{lstlisting}
Layer descriptions (start of syntactic description):
\begin{lstlisting}[language=grammar]
icon-layer :
"Icon" "(" [ coordsys-specification "," ] graphics ")"
diagram-layer :
"Diagram" "(" [ coordsys-specification "," ] graphics ")"
\end{lstlisting}%
\annotationindex{Icon}\annotationindex{Diagram}
\begin{example}
\begin{lstlisting}[language=modelica]
annotation(
Icon(coordinateSystem(extent = {{-100, -100}, {100, 100}}),
graphics = {Rectangle(extent = {{-100, -100}, {100, 100}}),
Text(extent = {{-100, -100}, {100, 100}},
textString = "Icon")}));
\end{lstlisting}
\end{example}
The graphics is specified as an ordered sequence of graphical primitives, which are described below.
First base class contents is drawn according to the order of the \lstinline!extends!-clauses, and then graphical primitives are drawn according to the order such that later objects can cover earlier ones.
\begin{nonnormative}
Note that the ordered sequence is syntactically a valid Modelica annotation, although there
is no mechanism for defining an array of heterogeneous objects in Modelica.
\end{nonnormative}
These \lstinline!Icon!, \lstinline!Diagram!, and \lstinline!Documentation! annotations are only allowed directly in classes (e.g., not on components or connections).
The allowed annotations for a short class definition is the union of the allowed annotations in classes and on \lstinline!extends!-clauses.
\subsection{Common Definitions}\label{common-definitions}
The following common definitions are used to define graphical annotations in the later sections.
\begin{lstlisting}[language=modelica]
type DrawingUnit = Real(final unit="mm");
type Point = DrawingUnit[2] "{x, y}";
type Extent = Point[2] "Defines a rectangular area {{x1, y1}, {x2, y2}}";
\end{lstlisting}%
\annotationindex{DrawingUnit}\annotationindex{Point}\annotationindex{Extent}
The interpretation of \lstinline!unit! is with respect to printer output in natural size (not zoomed).
All graphical entities have a visible attribute which indicates if the entity should be shown.
\begin{lstlisting}[language=modelica]
partial record GraphicItem
Boolean visible = true;
Point origin = {0, 0};
Real rotation(quantity="angle", unit="deg")=0;
end GraphicItem;
\end{lstlisting}%
\annotationindex{GraphicItem}
The \lstinline!origin! attribute specifies the origin of the graphical item in the coordinate system of the layer in which it is defined.
The origin is used to define the geometric information of the item and for all transformations applied to the item.
All geometric information is given relative the \lstinline!origin! attribute, which by default is \lstinline!{0, 0}!.
The \lstinline!rotation! attribute specifies the rotation of the graphical item
counter-clockwise around the point defined by the \lstinline!origin! attribute.
\subsubsection{Coordinate Systems}\label{coordinate-systems}
Each of the layers has its own coordinate system.\annotationindex{CoordinateSystem}
A coordinate system is defined by the coordinates of two points, the left (x1) lower (y1) corner and the right (x2) upper (y2) corner, where the coordinates of the first point shall be less than the coordinates of the second point.
The attribute \lstinline!preserveAspectRatio! specifies a hint for the shape of
components of the class, but does not actually influence the rendering of the component.
If \lstinline!preserveAspectRatio! is true, changing the
extent of components should preserve the current aspect ratio of the coordinate
system of the class.
The attribute \lstinline!initialScale! specifies the default component size as
\lstinline!initialScale! times the size of the coordinate system of the class. An
application may use a different default value of \lstinline!initialScale!.
The attribute \lstinline!grid! specifies the spacing between grid points which can
be used by tools for alignment of points in the coordinate system, e.g., ``snap-to-grid''.
Its use and default value is tool-dependent.
\begin{lstlisting}[language=modelica]
record CoordinateSystem
Extent extent;
Boolean preserveAspectRatio = true;
Real initialScale = 0.1;
DrawingUnit grid[2];
end CoordinateSystem;
\end{lstlisting}
\begin{example}
A coordinate system for an icon could for example be defined as:
\begin{lstlisting}[language=modelica]
CoordinateSystem(extent = {{-10, -10}, {10, 10}});
\end{lstlisting}
i.e., a coordinate system with width 20 units and height 20 units.
\end{example}
The coordinate systems for the icon and diagram layers are by default defined as follows; where the array of \lstinline!GraphicItem! represents an ordered list of graphical primitives.
\begin{lstlisting}[language=modelica]
record Icon "Representation of the icon layer"
CoordinateSystem coordinateSystem(extent = {{-100, -100}, {100, 100}});
GraphicItem[:] graphics;
end Icon;
record Diagram "Representation of the diagram layer"
CoordinateSystem coordinateSystem(extent = {{-100, -100}, {100, 100}});
GraphicItem[:] graphics;
end Diagram;
\end{lstlisting}
The coordinate system attributes (\lstinline!extent! and \lstinline!preserveAspectRatio!) of a class are separately defined by the following priority:
\begin{enumerate}
\item
The coordinate system annotation given in the class (if specified).
\item
The coordinate systems of the first base class where the extent on the \lstinline!extends!-clause specifies a null-region (if any).
Note that null-region is the default for base classes, see \cref{extends-clause}.
\item
The default coordinate system \lstinline!CoordinateSystem(preserveAspectRatio=true, extent = {{-100, -100}, {100, 100}})!.
\end{enumerate}
\subsubsection{Graphical Properties}\label{graphical-properties}
Properties of graphical objects and connection lines are described using the following attribute types.
\begin{lstlisting}[language=modelica]
type Color = Integer[3](min = 0, max = 255) "RGB representation";
constant Color Black = zeros(3);
type LinePattern = enumeration(None, Solid, Dash, Dot, DashDot, DashDotDot);
type FillPattern = enumeration(None, Solid, Horizontal, Vertical,
Cross, Forward, Backward, CrossDiag,
HorizontalCylinder, VerticalCylinder, Sphere);
type BorderPattern = enumeration(None, Raised, Sunken, Engraved);
type Smooth = enumeration(None, Bezier);
type EllipseClosure = enumeration(None, Chord, Radial);
\end{lstlisting}%
\annotationindex{Color}\annotationindex{LinePattern}\annotationindex{FillPattern}\annotationindex{BorderPattern}\annotationindex{Smooth}\annotationindex{EllipseClosure}
The \lstinline!LinePattern! attribute \lstinline!Solid! indicates a normal line, \lstinline!None! an invisible line, and the other attributes various forms of dashed/dotted lines.
The \lstinline!FillPattern! attributes \lstinline!Horizontal!, \lstinline!Vertical!, \lstinline!Cross!, \lstinline!Forward!, \lstinline!Backward! and \lstinline!CrossDiag! specify fill patterns drawn with the line color over the fill color.
The attributes \lstinline!HorizontalCylinder!, \lstinline!VerticalCylinder! and \lstinline!Sphere! specify
gradients that represent a horizontal cylinder, a vertical cylinder and
a sphere, respectively. The gradient goes from line color to fill color.
The border pattern attributes \lstinline!Raised!, \lstinline!Sunken! and \lstinline!Engraved! represent frames which are rendered in a tool-dependent way --- inside the extent of the filled shape.
\begin{figure}[H]
\begin{center}
\includegraphics{bezierpoints}
\end{center}
\caption{Line with \lstinline!smooth = Bezier!. The four line points $P_{1}$, \ldots{}, $P_{4}$ result in two quadratic splines and two straight line segments.}\label{fig:smooth-bezier}
\end{figure}
The \lstinline!smooth! attribute specifies that a line can be drawn as straight line segments (\lstinline!None!) or using a spline (\lstinline!Bezier!), where the line's points specify control points of a quadratic Bezier curve, see \cref{fig:smooth-bezier}.
For lines with only two points, the \lstinline!smooth! attribute has no effect.
For lines with three or more points ($P_{1}$, $P_{2}$, \ldots{}, $P_{n}$), the middle point of each line segment ($P_{12}$, $P_{23}$, \ldots{}, $P_{(n-1)n}$) becomes the starting point and ending
points of each quadratic Bezier curve. For each quadratic Bezier curve, the common point of the two line segment becomes the control point. For instance, point $P_{2}$ becomes the control point for
the Bezier curve starting at $P_{12}$ and ending at $P_{23}$. A straight line is drawn between the starting point of the line and the starting point of the first quadratic Bezier curve, as well as
between the ending point of the line and the ending point of the last quadratic Bezier curve.
In the illustration above, the square points ($P_{1}$, $P_{2}$, $P_{3}$, and $P_{4}$) represent the points that define the line, and the circle points ($P_{12}$, $P_{23}$, and $P_{34}$) are the
calculated middle points of each line segment. Points $P_{12}$, $P_{2}$, and $P_{23}$ define the first quadratic Bezier curve, and the points $P_{23}$, $P_{3}$, and $P_{34}$ define the second
quadratic Bezier curve. Finally a straight line is drawn between points $P_{1}$ and $P_{12}$ as well as between $P_{34}$ and $P_{4}$.
The values of the \lstinline!EllipseClosure! enumeration specify if and how the endpoints of an elliptical arc are to be joined (see \cref{ellipse}).
\begin{lstlisting}[language=modelica]
type Arrow = enumeration(None, Open, Filled, Half);
type TextStyle = enumeration(Bold, Italic, UnderLine);
type TextAlignment = enumeration(Left, Center, Right);
\end{lstlisting}%
\annotationindex{Arrow}\annotationindex{TextStyle}\annotationindex{TextAlignment}
Filled shapes have the following attributes for the border and interior.
\begin{lstlisting}[language=modelica]
record FilledShape "Style attributes for filled shapes"
Color lineColor = Black "Color of border line";
Color fillColor = Black "Interior fill color";
LinePattern pattern = LinePattern.Solid "Border line pattern";
FillPattern fillPattern = FillPattern.None "Interior fill pattern";
DrawingUnit lineThickness = 0.25 "Line thickness";
end FilledShape;
\end{lstlisting}%
\annotationindex{FilledShape}
The extent/points of the filled shape describe the theoretical zero-thickness filled shape, and the actual rendered border is then half inside and half outside the extent.
\subsection{Component Instance}\label{component-instance}
A component instance can be placed within a diagram or icon layer.
It has an annotation with a \lstinline!Placement! modifier to describe the placement.
Placements are defined in terms of coordinate system transformations:
\begin{lstlisting}[language=modelica]
record Transformation
Extent extent;
Real rotation(quantity = "angle", unit = "deg") = 0;
Point origin = {0, 0};
end Transformation;
\end{lstlisting}%
\annotationindex{Transformation}
The attributes are applied in the order \lstinline!extent!, \lstinline!rotation!, \lstinline!origin!, as follows:
\begin{enumerate}
\item
The \lstinline!extent! of the component icon is mapped to the \lstinline!extent! rectangle (possibly shifting, scaling, and flipping contents).
\item
The \lstinline!rotation! specifies counter-clockwise rotation around the origin (that is \lstinline!{0, 0}!, not the \lstinline!origin! attribute).
\item
The \lstinline!origin! specifies a shift (moving \lstinline!{0, 0}! to \lstinline!origin!).
\end{enumerate}
\begin{lstlisting}[language=modelica]
record Placement
Boolean visible = true;
Transformation transformation "Placement in the diagram layer";
Boolean iconVisible "Visible in icon layer; for public connector";
Transformation iconTransformation
"Placement in the icon layer; for public connector";
end Placement;
\end{lstlisting}%
\annotationindex{Placement}
If no \lstinline!iconTransformation! is given the \lstinline!transformation! is also used for placement in the icon layer.
If no \lstinline!iconVisible! is given for a public connector the \lstinline!visible! is also used for visibility in the icon layer.
\begin{nonnormative}
A connector can be shown in both an icon layer and a diagram
layer of a class. Since the coordinate systems typically are different,
placement information needs to be given using two different coordinate
systems. More flexibility than just using scaling and translation is
needed since the abstraction views might need different visual placement
of the connectors. The attribute \lstinline!transformation! gives the placement in
the diagram layer and \lstinline!iconTransformation! gives the placement in the icon
layer. When a connector is shown in a diagram layer, its diagram layer
is shown to facilitate opening up a hierarchical connector to allow
connections to its internal subconnectors.
\end{nonnormative}
For connectors, the icon layer is used to represent a connector when it
is shown in the icon layer of the enclosing model. The diagram layer of
the connector is used to represent it when shown in the diagram layer of
the enclosing model. Protected connectors are only shown in the diagram
layer. Public connectors are shown in both the diagram layer and the
icon layer. Non-connector components are only shown in the diagram
layer.
\subsection{Extends-Clause}\label{extends-clause}
Each \lstinline!extends!-clause (and short class definition, as stated in \cref{annotations-for-graphical-objects}) may have layer specific annotations which describe the rendering of the base class' icon and diagram layers in the derived class.
\begin{lstlisting}[language=modelica]
record IconMap
Extent extent = {{0, 0}, {0, 0}};
Boolean primitivesVisible = true;
end IconMap;
record DiagramMap
Extent extent = {{0, 0}, {0, 0}};
Boolean primitivesVisible = true;
end DiagramMap;
\end{lstlisting}%
\annotationindex{IconMap}\annotationindex{DiagramMap}
All graphical objects are by default inherited from a base class.
If the \lstinline!primitivesVisible! attribute is false, components and connections are visible but graphical primitives are not.
\begin{itemize}
\item
If the \lstinline!extent! is \lstinline!{{0, 0}, {0, 0}}! (the default), the base class contents is mapped to the same coordinates in the derived class, and the coordinate system (including \lstinline!preserveAspectRatio!) can be inherited as described in \cref{coordinate-systems}.
\item
For any other \lstinline!extent!, the base class coordinate system is mapped to this region, with the exception that \lstinline!preserveAspectRatio = true! in the base class requires that the mapping shall preserve the aspect ratio.
The base class coordinate system (and \lstinline!preserveAspectRatio!) is not inherited.
\end{itemize}
\begin{nonnormative}
A zero area \lstinline!extent! other than \lstinline!{{0, 0}, {0, 0}}! will result in none of the base class contents being visible.
By affecting components and connections as well as graphical primitives, this is different from setting \lstinline!primitivesVisible = false!.
Reversed corners of the \lstinline!extent! will result in mirrored (rotated if reversed in both direction) base class contents.
\end{nonnormative}
\begin{example}
\begin{lstlisting}[language=modelica]
model A
extends B annotation(
IconMap(extent = {{-100, -100}, {100, 100}}, primitivesVisible = false),
DiagramMap(extent = {{-50, -50}, {0, 0}}, primitivesVisible = true)
);
end A;
model B
extends C annotation(DiagramMap(primitivesVisible = false));
$\ldots$
end B;
\end{lstlisting}
In this example the diagram of \lstinline!A! contains the graphical primitives
from \lstinline!A! and \lstinline!B! (but not from \lstinline!C! since they were hidden in \lstinline!B!) -- the ones
from \lstinline!B! are rescaled, and the icon of \lstinline!A! contains the graphical primitives
from \lstinline!A! (but neither from \lstinline!B! nor from \lstinline!C!).
\end{example}
\subsection{Connections}\label{connections1}
A connection is specified with an annotation containing a \lstinline!Line!\index{Line@\robustinline{Line}!\robustinline{connect} annotation} primitive and optionally a \lstinline!Text! primitive, as specified below.
\begin{example}
\begin{lstlisting}[language=modelica]
connect(a.x, b.x)
annotation(Line(points = {{-25, 30}, {10, 30}, {10, -20}, {40, -20}}));
\end{lstlisting}
\end{example}
The optional \lstinline!Text!\index{Text@\robustinline{Text}!\robustinline{connect} annotation} primitive defines a text that will be written on the connection line.
It has the following definition (it is not equal to the \lstinline!Text! primitive as part of graphics -- the differences are marked after \emph{Note} in the description-strings):
\begin{lstlisting}[language=modelica]
record Text
extends GraphicItem;
Extent extent;
String string "Note: different name";
Real fontSize = 0 "unit pt";
String fontName;
TextStyle textStyle[:];
Color textColor = Color.Black;
TextAlignment horizontalAlignment =
if index < 0 then TextAlignment.Right else TextAligment.Left "Note: different default";
Integer index "Note: new";
end Text;
\end{lstlisting}
The \lstinline!index! is one of the points of Line (numbered 1, 2, 3, \ldots{} where negative numbers count from the end, thus -1 indicate the last one).
The \lstinline!string! may use the special symbols \lstinline!"%first"! and \lstinline!"%second"! to indicate the connectors in the \lstinline!connect!-equation.
The \lstinline!extent! and \lstinline!rotation! are relative to the \lstinline!origin! (default \lstinline!{0, 0}!) and the \lstinline!origin! is relative to the point on the \lstinline!Line!.
The \lstinline!textColor! attribute defines the color of the text. The text is drawn with transparent background and no border around the text (and without outline). The contents inherited from \lstinline!FilledShape! is deprecated, but kept for compatibility reasons. The default value for \lstinline!horizontalAlignment! is deprecated. Having a zero size for the \lstinline!extent! is deprecated and is handled as if upper part is moved up an appropriate amount.
\begin{example}
\begin{lstlisting}[language=modelica]
connect(controlBus.axisControlBus1, axis1.axisControlBus)
annotation(
Text(string = "%first", index = -1, extent = [-6, 3; -6, 7]),
Line(points = {{41, 30}, {50, 30}, {50, 50}, {58, 50}})
);
\end{lstlisting}
Draws a connection line and adds the text \emph{axisControlBus1} ending at $(-6,\, 3) + (58,\, 50)$ and 4 vertical units of space for the text.
Using a height of zero, such as \lstinline!extent = [-6, 3; -6, 3]! is deprecated, but gives similar result.
\end{example}
\subsection{Graphical Primitives}\label{graphical-primitives}
This section describes the graphical primitives that can be used to
define the graphical objects in an annotation.
\subsubsection{Line}\label{line}
A line is specified as follows:
\begin{lstlisting}[language=modelica]
record Line
extends GraphicItem;
Point points[:];
Color color = Black;
LinePattern pattern = LinePattern.Solid;
DrawingUnit thickness = 0.25;
Arrow arrow[2] = {Arrow.None, Arrow.None} "{start arrow, end arrow}";
DrawingUnit arrowSize = 3;
Smooth smooth = Smooth.None "Spline";
end Line;
\end{lstlisting}%
\annotationindex{Line}
Note that the \lstinline!Line! primitive is also used to specify the graphical representation of a connection.
For arrows:
\begin{itemize}
\item
The arrow is drawn with an aspect ratio of 1/3 for each arrow half, i.e., if the arrow-head is 3~mm long an arrow with \lstinline!Half! will extend 1~mm from the mid-line and with \lstinline!Open! or \lstinline!Filled! extend 1~mm to each side, in total making the base 2~mm wide.
\item
The \lstinline!arrowSize! gives the width of the arrow (including the imagined other half for \lstinline!Half!) so that \lstinline!lineThickness = 10! and \lstinline!arrowSize = 10! will touch at the outer parts.
\item
All arrow variants overlap for overlapping lines.
\item
The lines for the \lstinline!Open! and \lstinline!Half! variants are drawn with \lstinline!lineThickness!.
\end{itemize}
\subsubsection{Polygon}\label{polygon}
A polygon is specified as follows:
\begin{lstlisting}[language=modelica]
record Polygon
extends GraphicItem;
extends FilledShape;
Point points[:];
Smooth smooth = Smooth.None "Spline outline";
end Polygon;
\end{lstlisting}%
\annotationindex{Polygon}
The polygon is automatically closed, if the first and the last points are not identical.
\subsubsection{Rectangle}\label{rectangle}
A rectangle is specified as follows:
\begin{lstlisting}[language=modelica]
record Rectangle