Chapter 18 Annotations

Inside the Documentation annotation, each element of the styleSheets annotation array specifies a cascading style sheet. The style sheets are used when displaying the info and revisions annotations found in the Documentation annotations of the package. The styleSheets annotation is only considered for top-level packages, and applies to the entire package. The style sheets will be cascaded in the given order. Specifying just a string for styleSheets has the same meaning as specifying a singleton array containing the string.

[It is recommended to use class and id selectors with a $N\mathtt{}a\mathtt{}m\mathtt{}e\mathtt{}O\mathtt{}f\mathtt{}L\mathtt{}i\mathtt{}b\mathtt{}r\mathtt{}a\mathtt{}r\mathtt{}y$- prefix to avoid collisions when the content is included in a larger context.]

The style sheet rules should not use type or universal selectors, due to possible interference with tool-specific styling.

Vendors should use a $N\mathtt{}a\mathtt{}m\mathtt{}e\mathtt{}O\mathtt{}f\mathtt{}V\mathtt{}e\mathtt{}n\mathtt{}d\mathtt{}o\mathtt{}r$- prefix to style vendor generated HTML content surrounding the user provided documentation. If tools want to give users (of that tool) the possibility to override the tool-specific CSS they can document that. The prefix is used to avoid this happening by accident.

Properties may be defined for each Plot axis:

When an axis bound is not provided, the tool computes one automatically.

A non-empty unit shall match unit-expression in chapter 19. An empty 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 unit, so the axis label shall not contain this information.

[When unit is empty, and axis bounds are to be determined automatically, a natural choice of unit could be the variable’s 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.]

If a tool does not recognize the unit, it is recommended to issue a warning and treat the unit as if it was empty, as well as ignore any setting for min and max.

When label is not provided, the tool produces a default label. Providing the empty string as label means that no label should be shown. Variable replacements, as described in section 18.5.2.4, can be used in label. The Modelica tool is responsible for showing the unit used for values at the axis tick marks, so the axis label shall not contain the unit.

The type of scale is defined as an empty partial record:

The standardized annotations extending from AxisScale are Linear and Log, but it is also allowed to use a vendor-specific annotation.

Use Linear for a linear mapping between axis values and position on axis:

Use Log for a logarithmic mapping between axis values and position on axis:

The base of a Log scale determines preferred positions of major axis ticks. It is not required that the presentation of axis tick labels reflect the base setting. For example, when 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.

[Example: A 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\mathrm{\mapsto }\mathrm{sign}\mathit{}\mathrm{(}y\mathrm{)}\mathit{}\log \mathit{}\mathrm{(}\mathrm{1}\mathrm{+}\frac{\mathrm{\left|}y\mathrm{\right|}}{{\mathrm{10}}^{\alpha }}\mathrm{)}$. A tool may implement this as a vendor-specific axis scale:

]

The actual data to plot is specified in the curves of a Plot:

The mandatory x and y expressions are restricted to be result references in the form of result-reference in the grammar (section A.2.7), referring to a scalar variable (or a derivative thereof) or time. It is an error if x or y does not designate a scalar result. If x or y is a derivative, der(v, $n$), then $n$ must not exceed the maximum amount of differentiation applied to v in the model. A diagnostic is recommended in case the simulation result is missing a trajectory for a valid result reference.

[While the syntax for referring to a second order derivative is der(v, 2), the appearance is left for tools to decide. For example, a tool might choose to present this as der(der(v)).]

When the unit of an Axis is non-empty, it is an error if the unit of the corresponding x or y expression (i.e., a variable’s unit, or second for time) is incompatible with the axis unit.

When legend is not provided, the tool produces a default based on x and/or y. Providing the empty string as legend means that the curve shall be omitted from the plot legend. Variable replacements, as described in section 18.5.2.4, can be used in legend. The order of presentation within the plot legend corresponds to order of appearance in the curves of a Plot.

The zOrder gives control over drawing order, with higher values corresponding to closer to front. Ties are resolved using order of appearance in the curves of a Plot, with later appearance corresponding to closer to front.

In an attribute inside a figure where the variable replacements of section 18.5.2.4 or the text markup of section 18.5.2.5 can be used, the following use of text markup escape sequences 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 %%. The following are all the recognized escape sequences:

[With the percent character being encoded as %%, the behavior of % appearing in any other way than the escape sequences above, for variable replacement (section 18.5.2.4), or for the text markup (section 18.5.2.5) is undefined, and thus possible to define in the future without breaking backward compatibility.]

In the places listed in table 18.1 where text for display is defined, the final value of a result variable can be embedded by referring to the variable as %{inertia1.w}. This is similar to the Text graphical primitive in section 18.9.5.5.

In %{$\mathrm{𝑣𝑎𝑟𝑖𝑎𝑏𝑙𝑒}$}, text markup escape sequences don’t apply inside the $\mathrm{𝑣𝑎𝑟𝑖𝑎𝑏𝑙𝑒}$, which has the form of result-reference. This means that a complete result-reference shall be scanned before looking for the terminating closing brace.

[Example: The variable replacement %{'%%'} references the variable '%%', not the variable '%'.]

[Example: The variable replacement %{foo . '}bar{'} makes a valid reference to the variable foo.'}bar{'.]

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.

[By design, neither %class nor %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 %class or %name would then only lead to ugly duplication of this information.)]

In addition to variable replacements, a very restricted form of text markup is used for the caption. Note that the text markup escape sequences described in section 18.5.2.3 generally apply inside caption, with one exception given below for links.

Links take the form %[$\mathrm{𝑡𝑒𝑥𝑡}$]($\mathrm{𝑙𝑖𝑛𝑘}$), where the [$\mathrm{𝑡𝑒𝑥𝑡}$] part is optional, and text markup escape sequences don’t apply inside the $\mathrm{𝑙𝑖𝑛𝑘}$. The $\mathrm{𝑙𝑖𝑛𝑘}$ can be in either of the following forms, where the interpretation is given by the first matching form:

• •

  A variable:$\mathrm{𝑖𝑑}$, where $\mathrm{𝑖𝑑}$ is a component reference in the form of result-reference in the grammar, such as inertia1.w.

• •

  A plot:$\mathrm{𝑖𝑑}$, where $\mathrm{𝑖𝑑}$ is the identifier of a Plot in the current Figure.

• •

  A URI. Well established schemes such as https://github.com/modelica or 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.)

When [$\mathrm{𝑡𝑒𝑥𝑡}$] is omitted, a Modelica tool is free to derive a default based on the $\mathrm{𝑙𝑖𝑛𝑘}$.

[Note that for the character ‘]’ to appear in $\mathrm{𝑡𝑒𝑥𝑡}$, it needs to be encoded as the escape sequence %], or it would be interpreted as the terminating delimiter of the [$\mathrm{𝑡𝑒𝑥𝑡}$].

Similarly, the closing parenthesis ‘)’ must be handled with care in $\mathrm{𝑙𝑖𝑛𝑘}$ in order to not be interpreted as the terminating delimiter of the ($\mathrm{𝑙𝑖𝑛𝑘}$).

• •

  For a variable:, no special treatment is needed, as the component reference syntax of the $\mathrm{𝑖𝑑}$ allows parentheses to appear without risk of misinterpretation inside a quoted identifier. For example, %(variable:'try)me!') has a parenthesis in 'try)me!' that must not be mistaken for the end of the ($\mathrm{𝑙𝑖𝑛𝑘}$).

• •

  For a plot:, there is currently no way to reference a plot with ‘)’ in its identifier.

• •

  For a URI, a closing parenthesis must be URL encoded in order to not be interpreted as the end of the ($\mathrm{𝑙𝑖𝑛𝑘}$). For example, the URL in %(http://example.org/(tryme)) is just 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: %(http://example.org/%28tryme%29) (using URL encoding of the opening parenthesis just for symmetry, and note that the % of the percent-encoded sequences are not subject to text markup escape sequences).

]

The styling of the link text, as well as the link action, is left for each Modelica tool to decide.

[For example, %(variable:inertia1.w) could be displayed as the text 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, %[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.]

[Note that $\mathrm{𝑙𝑖𝑛𝑘}$ is currently not allowed to be a URI reference, i.e., a URI or a relative reference such as #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 $\mathrm{𝑙𝑖𝑛𝑘}$ may be changed into a URI reference.]

A sequence of one or more newlines (encoded either literally or using the \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.)

Vendor-specific markup takes the form %__${\mathrm{𝑛𝑎𝑚𝑒𝑂𝑓𝑉𝑒𝑛𝑑𝑜𝑟}}_{\mathrm{1}}$(${\mathrm{𝑑𝑎𝑡𝑎}}_{\mathrm{1}}$)$\mathrm{\dots }$__${\mathrm{𝑛𝑎𝑚𝑒𝑂𝑓𝑉𝑒𝑛𝑑𝑜𝑟}}_n$(${\mathrm{𝑑𝑎𝑡𝑎}}_n$)[$\mathrm{𝑡𝑒𝑥𝑡}$], where $n\ge 1$. The $\mathrm{𝑛𝑎𝑚𝑒𝑂𝑓𝑉𝑒𝑛𝑑𝑜𝑟}$ consists of only digits and letters, and shall only convey the name of the vendor defining the meaning of the associated $\mathrm{𝑑𝑎𝑡𝑎}$. Text markup escape sequences don’t apply inside the $\mathrm{𝑑𝑎𝑡𝑎}$, 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 $\mathrm{𝑡𝑒𝑥𝑡}$, but the $\mathrm{𝑡𝑒𝑥𝑡}$ may also be used together with the vendor-specific $\mathrm{𝑑𝑎𝑡𝑎}$.

[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 %__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 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 %{experiment:duration} instead (note that 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 variable:). This is an example where the vendor-specific markup could make use of the $\mathrm{𝑡𝑒𝑥𝑡}$ (for link text) together with the vendor-specific $\mathrm{𝑑𝑎𝑡𝑎}$ (describing the actual link).]

Each of the layers has its own coordinate system. 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 preserveAspectRatio specifies a hint for the shape of components of the class, but does not actually influence the rendering of the component. If preserveAspectRatio is true, changing the extent of components should preserve the current aspect ratio of the coordinate system of the class.

The attribute initialScale specifies the default component size as initialScale times the size of the coordinate system of the class. An application may use a different default value of initialScale.

The attribute 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.

[Example: A coordinate system for an icon could for example be defined as:

i.e., a coordinate system with width 20 units and height 20 units.]

The coordinate systems for the icon and diagram layers are by default defined as follows; where the array of GraphicItem represents an ordered list of graphical primitives.

The coordinate system attributes (extent and preserveAspectRatio) of a class are separately defined by the following priority:

1. 1.

   The coordinate system annotation given in the class (if specified).

2. 2.

   The coordinate systems of the first base class where the extent on the extends-clause specifies a null-region (if any). Note that null-region is the default for base classes, see section 18.9.3.

3. 3.

   The default coordinate system CoordinateSystem(preserveAspectRatio=true, extent = {{-100, -100}, {100, 100}}).

Properties of graphical objects and connection lines are described using the following attribute types.

The LinePattern attribute Solid indicates a normal line, None an invisible line, and the other attributes various forms of dashed/dotted lines.

The FillPattern attributes Horizontal, Vertical, Cross, Forward, Backward and CrossDiag specify fill patterns drawn with the line color over the fill color.

The attributes HorizontalCylinder, VerticalCylinder and 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 Raised, Sunken and Engraved represent frames which are rendered in a tool-dependent way — inside the extent of the filled shape.

The smooth attribute specifies that a line can be drawn as straight line segments (None) or using a spline (Bezier), where the line’s points specify control points of a quadratic Bezier curve, see figure 18.1.

For lines with only two points, the smooth attribute has no effect.

For lines with three or more points ($P_1$, $P_2$, …, $P_n$), the middle point of each line segment ($P_{12}$, $P_{23}$, …, $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 EllipseClosure enumeration specify if and how the endpoints of an elliptical arc are to be joined (see section 18.9.5.4).

Filled shapes have the following attributes for the border and interior.

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.

A line is specified as follows:

Note that the Line primitive is also used to specify the graphical representation of a connection.

For arrows:

• •

  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 Half will extend 1 mm from the mid-line and with Open or Filled extend 1 mm to each side, in total making the base 2 mm wide.

• •

  The arrowSize gives the width of the arrow (including the imagined other half for Half) so that thickness = 10 and arrowSize = 10 will touch at the outer parts.

• •

  All arrow variants overlap for overlapping lines.

• •

  The lines for the Open and Half variants are drawn with thickness.

A polygon is specified as follows:

The polygon is automatically closed, if the first and the last points are not identical.

A rectangle is specified as follows:

The extent attribute specifies the bounding box of the rectangle. If the radius attribute is specified, the rectangle is drawn with rounded corners of the given radius.

An ellipse is specified as follows:

The extent attribute specifies the bounding box of the ellipse.

Partial ellipses can be drawn using the startAngle and endAngle attributes. These specify the endpoints of the arc prior to the stretch and rotate operations. The arc is drawn counter-clockwise from startAngle to endAngle, where startAngle and endAngle are defined counter-clockwise from 3 o’clock (the positive x-axis).

The closure attribute specifies whether the endpoints specified by startAngle and endAngle are to be joined by lines to the center of the extent (closure = EllipseClosure.Radial), joined by a single straight line between the end points (closure = EllipseClosure.Chord), or left unconnected (closure = EllipseClosure.None). In the latter case, the ellipse is treated as an open curve instead of a closed shape, and the fillPattern and fillColor are not applied (if present, they are ignored).

The default closure is EllipseClosure.Chord when startAngle is 0 and endAngle is 360, or EllipseClosure.Radial otherwise.

[The default for a closed ellipse is not EllipseClosure.None, since that would result in fillColor and fillPattern being ignored, making it impossible to draw a filled ellipse. EllipseClosure.Chord is equivalent in this case, since the chord will be of zero length.]

A text string is specified as follows:

The textColor attribute defines the color of the text. The text is drawn with transparent background and no border around the text (and without outline).

There are a number of common macros that can be used in the text, and they should be replaced when displaying the text as follows (in order such that the earliest ones have precedence, and using the longest sequence of identifier characters – alphanumeric and underscore):

• •

  %% replaced by %

• •

  %name replaced by the name of the component (i.e., the identifier for it in the enclosing class).

• •

  %class replaced by the name of the class (only the last part of the hierarchical name).

• •

  %par and %{par} replaced by the value of the parameter par. If the value is numeric, tools shall display the value with displayUnit, formatted according to the BIPM specification. E.g., for

  ⬇

  parameter Real t(unit = "s", displayUnit = "ms") = 0.1

  tools shall display 100 ms. The intent is that the text is easily readable, thus if par is of an enumeration type, replace %par by the item name, not by the full name.

  [Example: If par = "Modelica.Blocks.Types.Enumeration.Periodic", then %par should be displayed as Periodic.]

  When quoted identifiers (e.g., quoted ident! or '}') or composite names (i.e., not simple identifiers) are involved, the form %{par} must be used. Here, par is a general component-reference, and %{a.p} gives the value of the parameter p in the component a. The macro can be directly followed by a letter. Thus %{w}x%{h} gives the value of w directly followed by x and the value of h, while %wxh gives the value of the parameter wxh. If the parameter does not exist it is an error.

The style attribute fontSize specifies the font size. If the fontSize attribute is 0 the text is scaled to fit its extent. Otherwise, the size specifies the absolute size. The text is vertically centered in the extent.

If the extent specifies a box with zero width and positive height the height is used as height for the text (unless fontSize attribute is non-zero – which specifies the absolute size), and the text is not truncated (the horizontalAlignment is still used in this case).

[A zero-width extent is convenient for handling texts where the width is unknown.]

If the string fontName is empty, the tool may choose a font. The font names "serif", "sans-serif", and "monospace" shall be recognized. If possible the correct font should be used – otherwise a reasonable match, or treat as if fontName was empty.

The style attribute textStyle specifies variations of the font.

A bitmap image is specified as follows:

The Bitmap primitive renders a graphical bitmap image. The data of the image can either be stored on an external file or in the annotation itself. The image is scaled to fit the extent. Given an extent {{$x_{\mathrm{1}}$, $y_{\mathrm{1}}$}, {$x_{\mathrm{2}}$, $y_{\mathrm{2}}$}}, defines horizontal flipping and defines vertical flipping around the center of the object.

The graphical operations are applied in the order: scaling, flipping and rotation.

When the attribute fileName is specified, the string refers to an external file containing image data. The mapping from the string to the file is specified for some URIs in section 13.6. The supported file formats include PNG, BMP, JPEG, and SVG.

When the attribute imageSource is specified, the string contains the image data, and the image format is determined based on the contents. The image is represented as a Base64 encoding of the image file format (see RFC 4648, http://tools.ietf.org/html/rfc4648).

The image is uniformly scaled (preserving the aspect ratio) so it exactly fits within the extent (touching the extent along one axis). The center of the image is positioned at the center of the extent.

A Boolean variable can be changed when the cursor is held over a graphical item or component and the selection button is pressed if the interaction annotation contains OnMouseDownSetBoolean:

[Example: A button can be represented by a rectangle changing color depending on a Boolean variable on and toggles the variable when the rectangle is clicked on:

]

In a similar way, a variable can be changed when the mouse button is released:

Note that several interaction objects can be associated with the same graphical item or component.

[Example:

]

The OnMouseMoveXSetReal interaction object sets the variable to the position of the cursor in X direction in the local coordinate system mapped to the interval defined by the minValue and maxValue attributes.

The OnMouseMoveYSetReal interaction object works in a corresponding way as the OnMouseMoveXSetReal object but in the Y direction.

The OnMouseDownEditInteger interaction object presents an input field when the graphical item or component is clicked on. The field shows the actual value of the variable and allows changing the value. If a too small or too large value according to the min and max parameter values of the variable is given, the input is rejected.

The OnMouseDownEditReal interaction object presents an input field when the graphical item or component is clicked on. The field shows the actual value of the variable and allows changing the value. If a too small or too large value according to the min and max parameter values of the variable is given, the input is rejected.

The OnMouseDownEditString interaction object presents an input field when the graphical item or component is clicked on. The field shows the actual value of the variable and allows changing the value.

There are a number of functions: convertClass, convertClassIf, convertElement, convertModifiers, convertMessage defined as follows. The calls of these functions do not directly convert, instead they define conversion rules as below. It is recommended, but not required, to terminate each such function call with a semi-colon. The order between the function calls does not matter, instead the longer paths (in terms of number of hierarchical names) are used first as indicated below, and it is an error if there are any ambiguities.

The conversion should generate correct Modelica models using the new version of the library corresponding to the old version.

[Whenever possible tools should preserve the original style of the model, e.g., use of imports. Conversions should be applied in all places where named element are used in code, including Modelica URIs (for example, in Documentation annotations).]

These functions can be called with literal strings or arrays of literal strings and vectorize according to section 12.4.6. The empty literal string is only allowed when constructing an empty array using fill.

All of these convert-functions only use inheritance among user models, and not in the library that is used for the conversion – thus conversions of base classes will require multiple conversion calls; this ensures that the conversion is independent of the new library structure. The name of the class used as argument to convertElement and convertModifiers is similarly the old name of the class, i.e., the name before it is possibly converted by convertClass.

[Specifying conversions using the old name of a class allows the conversion to be done without access to the old version of the library (by suitable modifications of the lookup). Another alternative is to use the old version of the library during the conversion.

The invalid but previously used form convertElement("OldClass", "OldName", "") should be handled as convertModifiers("OldClass", {"OldName"}, fill("", 0)) without any conversion applied to equations.]