HowToUseSIunits

Description

When implementing a Modelica model, every variable needs to be declared. Physical variables should be declared with a unit. The basic approach in Modelica is that the unit attribute of a variable is the unit in which the equations are written, for example:

   model MassOnGround
     parameter Real m(quantity="Mass", unit="kg") "Mass";
     parameter Real f(quantity="Force", unit="N") "Driving force";
     Real s(unit="m") "Position of mass";
     Real v(unit="m/s") "Velocity of mass";
   equation
     der(s) = v;
     m*der(v) = f;
   end MassOnGround;

This means that the equations in the equation section are only correct for the specified units. A different issue is the user interface, i.e., in which unit the variable is presented to the user in graphical user interfaces, both for input (e.g., parameter menu), as well as for output (e.g., in the plot window). Preferably, the Modelica tool should provide a list of units from which the user can select, e.g., "m", "cm", "km", "inch" for quantity "Length". When storing the value in the model as a Modelica modifier, it has to be converted to the unit defined in the declaration. Additionally, the unit used in the graphical user interface has to be stored. In order to have a standardized way of doing this, Modelica provides the following three attributes for a variable of type Real:

• quantity to define the physical quantity (e.g., "Length", or "Energy").
• unit to define the unit that has to be used in order that the equations are correct (e.g., "N.m").
• displayUnit to define the unit used in the graphical user interface as default display unit for input and/or output.

Note, a unit, such as "N.m", is not sufficient to define uniquely the physical quantity, since, e.g., "N.m" might be either "torque" or "energy". The "quantity" attribute might therefore be used by a tool to select the corresponding menu from which the user can select a unit for the corresponding variable.

For example, after providing a value for "m" and "f" in a parameter menu of an instance of MassOnGround, a tool might generate the following code:

   MassOnGround myObject(m(displayUnit="g")=2, f=3);

The meaning is that in the equations a value of "2" is used and that in the graphical user interface a value of "2000" should be used, together with the unit "g" from the unit set "Mass" (= the quantity name). Note, according to the Modelica specification a tool might ignore the "displayUnit" attribute.

In order to help the Modelica model developer, the Modelica.SIunits library provides about 450 predefined type names, together with values for the attributes quantity, unit and sometimes displayUnit and min. The unit is always selected as SI-unit according to the ISO standard. The type and the quantity names are the quantity names used in the ISO standard. "quantity" and "unit" are defined as "final" in order that they cannot be modified. Attributes "displayUnit" and "min" can, however, be changed in a model via a modification. The example above, might therefore be alternatively also defined as:

   model MassOnGround
     parameter Modelica.SIunits.Mass  m "Mass";
     parameter Modelica.SIunits.Force f "Driving force";
     ...
   end MassOnGround;

or in a short hand notation as

   model MassOnGround
     import SI = Modelica.SIunits;
     parameter SI.Mass  m "Mass";
     parameter SI.Force f "Driving force";
     ...
   end MassOnGround;

For some often used Non SI-units (like hour), some additional type definitions are present as Modelica.SIunits.Conversions.NonSIunits. If this is not sufficient, the user has to define its own types or use the attributes directly in the declaration as in the example at the beginning.

Complex units are also included in Modelica.SIunits. A complex unit is declared as:

  model QuasiStationaryMachine
    parameter Modelica.SIunits.ComplexPower SNominal = Complex(10000,4400)
       "Nominal complex power";
   ...
   end QuasiStationaryMachine;