HowToUseSIunits

How to use SIunits

    HowToUseSIunits

Library

Modelica/SIunits/UsersGuide

Description

When implementing a Modelica model, every variable needs tobe declared. Physical variables should be declared with a unit.The basic approach in Modelica is that the unit attribute ofa 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 correctfor the specified units. A different issue is the user interface, i.e.,in which unit the variable is presented to the user in graphicaluser interfaces, both for input (e.g., parameter menu), as well asfor output (e.g., in the plot window). Preferably, the Modelica toolshould provide a list of units from which the user can select, e.g.,"m", "cm", "km", "inch" for quantity "Length". When storing the value inthe model as a Modelica modifier, it has to be converted to the unit definedin the declaration. Additionally, the unit used in the graphicaluser interface has to be stored. In order to have a standardized wayof doing this, Modelica provides the following three attributesfor 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 thephysical quantity, since, e.g., "N.m" might be either "torque" or"energy". The "quantity" attribute might therefore be used by a toolto select the corresponding menu from which the user can selecta unit for the corresponding variable.

For example, after providing a value for "m" and "f" in a parametermenu 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 usedand 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 specificationa tool might ignore the "displayUnit" attribute.

In order to help the Modelica model developer, the Modelica.SIunitslibrary provides about 450 predefined type names,together with values for the attributes quantity, unit and sometimesdisplayUnit and min. The unit is always selected as SI-unit according to theISO standard. The type and the quantity names are thequantity names used in the ISO standard. "quantity" and "unit" are definedas "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 oftenused Non SI-units (like hour), some additional type definitions arepresent as Modelica.SIunits.Conversions.NonSIunits. If this is not sufficient,the user has to define its own types or use the attributes directlyin 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;