Modelica.UsersGuide.Conventions

A Modelica main package should be compliant with the UsersGuide stated in this documentation:

1. Conventions of the Modelica code
2. Consistent HTML documentation
3. Structure to be provided by a main package
   • User's Guide
   • Examples containing models demonstrating the usage of the library.
   • Components -- in case of a complex library a more detailed structure can be established.
   • Sensors
   • Sources
   • Interfaces containing connectors and simple partial interface models.
   • BaseClasses containing partial models with physical equations other than trivial and balance equations.
   • Types containing type, enumeration and choice definitions.
4. These packages should appear in the listed order.

Extends from Modelica.Icons.Information (Icon for general information packages).

Package Content

Name	Description
Documentation	HTML documentation
Terms	Terms and spelling
ModelicaCode	Modelica code
UsersGuide	User's Guide
Icons	Icon design

Modelica.UsersGuide.Conventions.Icons

The icon of a Modelica class shall consider the following guidelines:

Color and Shapes

The main icon color of a component shall be the same for all components of one library. White fill areas of an icon shall not be used to hide parts of an icon, see #2031. In the Modelica Standard Library the following color schemes apply:

Color schemes applied to particular libraries

Package	Color RGB code	Color sample
Modelica.Blocks	{0,0,127}
Modelica.ComplexBlocks	{85,170,255}
Modelica.Clocked	{95,95,95}
Modelica.StateGraph	{0,0,0}
Modelica.Electrical.Analog	{0,0,255}
Modelica.Electrical.Digital	{128,0,128}
Modelica.Electrical.Machines	{0,0,255}
Modelica.Electrical.Polyphase	{0,0,255}
Modelica.Electrical.QuasiStatic	{85,170,255}
Modelica.Electrical.Spice3	{170,85,255}
Modelica.Magnetic.FluxTubes	{255,127,0}
Modelica.Magnetic.FundamentalWave	{255,127,0}
Modelica.Magnetic.QuasiStatic	{255,170,85}
Modelica.Mechanics.MultiBody	{192,192,192}
Modelica.Mechanics.Rotational	{95,95,95}
Modelica.Mechanics.Translational	{0,127,0}
Modelica.Fluid	{0,127,255}
Modelica.Media	none
Modelica.Thermal.FluidHeatFlow	{0,0,255}
Modelica.Thermal.HeatTransfer	{191,0,0}
Modelica.Math	none
Modelica.ComplexMath	none
Modelica.Utilities	none
Modelica.Constants	none
Modelica.Icons	none
Modelica.Units	none

Icon size

The icon of a Modelica class shall not be significantly greater or smaller than the default Diagram limits of 200 units x 200 units. These default diagram limits are

• -100 units ≤ horizontal coordinate ≤ +100 units
• -100 units ≤ vertical coordinate ≤ +100 units

If possible, the icon shall be designed such way, that the icon name %name and the most significant parameter can be displayed within the vertical Diagram range of the icon.

Fig. 1: (a) Typical icon, (b) including dimensions

(a)

(b)

Component Name

The component name %name shall be in RGB (0,0,255) blue color.

• Text height: 40 units
• Text width: 300 units

The text shall be located above the actual icon. If there is enough space, the upper text limit of the component name shall be 10 units below the upper icon boundary, see Fig. 1.

If the icon is as big as the entire icon range of 200 units x 200 units, e.g. in blocks, the component name shall be placed above the icon with vertical 10 units of space between icon and lower text box, see Fig. 2.

Fig. 2: Block component name

If there is a connector located at the top icon boundary and it is obvious that this connector influences the model behavior compared to a similar model without such connector, then a line from the connector to the actual icon shall be avoided to keep the design straight, see Fig. 4. If it is required to use a line indicating the connector dependency, then the line shall be interrupted such that this line does not interfere with component name.

Fig. 3: Component name between actual icon and connector

In some cases, if there is not alternative, the component name has to be placed below the actual icon, see. Fig. 4.

Fig. 4: Component name below actual icon

Parameter Name

One significant parameter shall be placed below the icon, see Fig. 1 and Fig. 2. The parameter name shall be RGB (0,0,0) black color.

• Text height: 40 units (or 30 units, minimum 20 units, if required)
• Text width: 300 units

The parameter text box shall be placed 10 units below the actual icon.

Connector location

Physical connectors shall always be located on the icon boundary. Input and output connector shall be placed outside the icon, see Fig. 2 and Fig. 3. Preferred connector locations are:

• at the four corners of the icon diagram, see Fig. 5
• at vertical or horizontal symmetry line of an icon, see Fig. 1–3
• alternative connection points shall be located in a raster of 20 units (or 10 units) if required, see Fig. 4

Fig. 5: Connectors located at the four corners of the icon diagram

Sensors

Based on #2628 the following guidelines for the design of sensors apply:

• The sensor outputs shall be indicated by its SI unit, not its quantity; the proper SI unit shall be compliant with the unit definitions of Modelica.Units.SI, e.g. heat flow is indicated by W, torque is indicated by N.m
• The text color of the SI units is {64,64,64} in RGB code
• For a sensor with a single output signal the SI unit shall be placed within the sensor, see Fig. 6 and 7
  • In a round sensor the text size shall be
    • either {{-30,-10},{30,-70}} (Fig. 6(a))
    • or {{-50,-12},{50,-48}} (Fig. 6(b)), depending on the better readability
  • In a rectangular sensor the text size shall be {{-24,20},{66,-40}} (Fig. 7)
• For a sensor with multiple output signals the SI unit shall be placed next to the output signal; a signal connectors and the SI units may overlap, see Fig. 8
  • Text height: 40 units (or 30 units, minimum 20 units, if required)
  • Text width: 40 units (or 30 units, minimum 20 units, if required)

Fig. 6: Round sensor with (a) short and (b) longer SI unit

(a)

(b)

Fig. 7: Rectangular sensor

Fig. 8: Sensor with multiple signal outputs and SI units located next to the output connectors

Diagram layer

The diagram layer is intended to contain the graphical components, and if there are no graphical components it shall be left empty. In particular do not make the diagram layer a copy of the icon layer. Graphical illustrations shall not be added in the diagram layer, but can be added in the HTML documentation.

Extends from Modelica.Icons.Information (Icon for general information packages).