Modelica.UsersGuide.Conventions.ModelicaCode

In this section guidelines on creating Modelica code are provided.

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

Package Content

Name	Description
Format	Format
Naming	Naming convention
ParameterDefaults	Parameter defaults

Modelica.UsersGuide.Conventions.ModelicaCode.Format

Comments and Annotations

Comments and annotations should start with a capital letter, for example:
parameter Real a = 1 "Arbitrary factor";.
For Boolean parameters, the description string should start with "= true, …", for example:
parameter Boolean useHeatPort = false "= true, if heatPort is enabled";.

Tabs and Groups

The annotations "tab" and "group" define the placement of component or of variables in a dialog.

Using the group annotation, the following rules shall be followed:

1. Avoid excessively long group labels.
2. Use nouns rather than verbs, without ending punctuation.
3. Use sentence-style capitalization.

Using the tab annotation, the following rules shall be followed:

1. Try to group components or variables in the default "general" tab first. But feel free to define a new tab it they are so many.
2. Label tabs based on their pattern. The label shall clearly reflect the content of the collected variables.
3. Avoid long tab labels. One or two words are mostly sufficient.
4. Use nouns rather than verbs, without ending punctuation.
5. Use sentence-style capitalization.
6. Visibility of parameters collected in one tab shall not be dependent on parameters shown in another tab.

Example

Imagine you define a controlled electric drive being composed of a controller and an electrical machine. The latter has parameters number of pole pairs p, nominal frequency f_nom, rotor's moment of inertia J_rotor and others. The controller itself is divided into several sub-controllers – such as the one for speed control with parameters like gain k or time constant T. Then, the above parameters of your electrical drive model could be sorted using tabs and groups as follows: p, f_nom and J_rotor grouped in the "Electrical machine" group in the "general" tab; k and T in the group "Speed control" under tab "Controller".

In the Modelica code, for example the parameter k will then be defined like:

parameter Real k=1 "Gain"
  annotation(
    Dialog(
      tab="Controller",
      group="Speed control"));

Whitespace and Indentation

Trailing white-space (i.e., white-space at the end of the lines) shall not be used. The tab-character shall not be used, since the tab-stops are not standardized.

The code in a class shall be indented relative to the class in steps of two spaces; except that the headings public, protected, equation, algorithm, and end of class marker shall not be indented. The keywords public and protected are headings for a group of declarations.

Long modifier lists shall be split into several indented lines with at most one modifier per line.

Full class definitions shall be separated by an empty line.

Example

package MyPackage
  partial model BaseModel
    parameter Real p;
    input Real u(unit="m/s");
  protected
    Real y;
    Real x(
      start=1,
      unit="m",
      nominal=10);
  equation
    der(x) = u;
    y = 2*x;
  end BaseModel;

  model ModelP2
    extends BaseModel(p=2);
  end ModelP2;
end MyPackage;

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

Modelica.UsersGuide.Conventions.ModelicaCode.Naming

1. Class and instance names are usually written in upper and lower case letters, e.g., "ElectricCurrent". An underscore may be used in names. However, it has to be taken into account that the last underscore in a name might indicate that the following characters are rendered as a subscript. Example: "pin_a" may be rendered as "pin_a".
2. Class names start always with an upper case letter, with the exception of functions, that start with a lower case letter.
3. Instance names, i.e., names of component instances and of variables (with the exception of constants), start usually with a lower case letter with only a few exceptions if this is common sense (such as T for a temperature variable).
4. Constant names, i.e., names of variables declared with the "constant" prefix, follow the usual naming conventions (= upper and lower case letters) and start usually with an upper case letter, e.g., UniformGravity, SteadyState.
5. The two connectors of a domain that have identical declarations and different icons are usually distinguished by _a, _b or _p, _n, e.g., Flange_a, Flange_b, HeatPort_a, HeatPort_b.
6. A connector class has the instance name definition in the diagram layer and not in the icon layer.

Variable names

In the following table typical variable names are listed. This list should be completed.

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

Modelica.UsersGuide.Conventions.ModelicaCode.ParameterDefaults

In this section the convention is summarized how default parameters are handled in the Modelica Standard Library (since version 3.0).

Many models in this library have parameter declarations to define constants of a model that might be changed before simulation starts. Example:

model SpringDamper
parameter Real c(final unit="N.m/rad") = 1e5    "Spring constant";
parameter Real d(final unit="N.m.s/rad") = 0    "Damping constant";
parameter Modelica.Units.SI.Angle phi_rel0 = 0  "Unstretched spring angle";
...
end SpringDamper;

In Modelica it is possible to define a default value of a parameter in the parameter declaration. In the example above, this is performed for all parameters. Providing default values for all parameters can lead to errors that are difficult to detect, since a modeler may have forgotten to provide a meaningful value (the model simulates but gives wrong results due to wrong parameter values). In general the following basic situations are present:

1. The parameter value could be anything (e.g., a spring constant or a resistance value) and therefore the user should provide a value in all cases. A Modelica translator should warn, if no value is provided.
2. The parameter value is not changed in > 95 % of the cases (e.g., initialization or visualization parameters, or parameter phi_rel0 in the example above). In this case a default parameter value should be provided, in order that the model or function can be conveniently used by a modeler.
3. A modeler would like to quickly utilize a model, e.g.,
   • to automatically check that the model still translates and/or simulates (after some changes in the library),
   • to make a quick demo of a library by drag-and-drop of components,
   • to implement a simple test model in order to get a better understanding of the desired component.
   In all these cases, it would be not practical, if the modeler would have to provide explicit values for all parameters first.

To handle the conflicting goals of (1) and (3), the Modelica Standard Library uses two approaches to define default parameters, as demonstrated with the following example:

model SpringDamper
parameter Real c(final unit="N.m/rad"  , start = 1e5) "Spring constant";
parameter Real d(final unit="N.m.s/rad", start = 0)   "Damping constant";
parameter Modelica.Units.SI.Angle phi_rel0 = 0        "Unstretched spring angle";
...
end SpringDamper;

SpringDamper sp1;              // warning for "c" and "d"
SpringDamper sp2(c=1e4, d=0);  // fine, no warning

Both definition forms, using a "start" value (for "c" and "d") and providing a declaration equation (for "phi_rel0"), are valid Modelica and define the value of the parameter. By convention, it is expected that Modelica translators will trigger a warning message for parameters that are not defined by a declaration equation, by a modifier equation or in an initial equation/algorithm section. A Modelica translator might have options to change this behavior, especially, that no messages are printed in such cases and/or that an error is triggered instead of a warning.

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