Adding additional Units? Utilising Type definitions

What is a type class?

Often in a physical modelling environment, the parameters and variables used equate to physical quantities defined as a number and unit declaration. In Modelica this unit quantity is defined using a ‘type’ class:

type Density = Real (
  final quantity="Density",
  final unit="kg/m3",
  min=0);

The Modelica Standard Library includes definitions of the units from the ISO standards in the SIunits package and this is done using types. These type definitions are then used when defining parameters and variables within the model:

parameter Modelica.SIunits.Density rho=1000 "Density of Material";

This builds in physical quantities directly into the definition of model variables and parameters in an efficient way.

We can also create simple ‘lists’ of possible values using types to provide easy to use ways to control behaviour in models using the ‘enumeration’ keyword, for example:

type GearHand = enumeration(
  Right "Right handed helical gear",
  Left "Left handed helical gear",
  Spur "Straight cut spur gear");

To add a new type, simply click on the package you wish to add them in to and go to the Modelica text layer. For further examples of the syntax, see Modelica.SIunits or for enumeration types see Modelica.Blocks.Types.

Why are they useful?

Some of the advantages of using types in this way include the ability to:

• Check that the units of equations balance. Dymola automatically performs these checks during model checking (F8) and model translation and will generate warnings of any inconsistent units. A unit derivation feature is also built in to the checks Dymola performs to handle undefined units.
• Avoid the need for unit conversion functions directly within the equations as these are built in to the user interface
• Enter parameter information in supplied unit form without manual conversion
• Plot variables in any pre-defined or derived unit of measure easily

How can I use them?

Use of the types defined in Modelica.SIunits package is strongly encouraged when defining parameters and variables within a model. Types are often used in combination with an import statement i.e.

model TypeExample
  import SI = Modelica.SIunits;
  parameter SI.Angle phi=0 "Angle offset";
  end TypeExample;

or for use of the shortcut consistently within a whole package:

package Examples
  import SI = Modelica.SIunits;
  model TypeExample
    parameter SI.Angle phi=0 "Angle offset";
  end TypeExample;
end Examples;

This form of shorthand often makes the code easier to read and reference units without dragging and dropping units from the SIunits package.

We can also use a type class to control model behaviour; Example 1 below defines a parameter using the GearHand enumeration type created earlier with its use underlined:

model Example1
  import SI = Modelica.SIunits "This creates the shorthand SI";
  parameter Claytex.Types.GearHand toothDesign=Claytex.Types.GearHand.Right "Tooth Design";
  SI.Force f "Define force variable";
equation
  if toothDesign == Claytex.Types.GearHand.Right then
    f = 1;
  elseif toothDesign == Claytex.Types.GearHand.Left then
    f = -1;
  else
    f = 0;
  end if;
end Example1;

This will allow selection of the elements defined in the type directly as a parameter. This is shown as:

Types can also be used for defining sizes of an array and limits to for loops; the number a variables within the type define the size. For example:

model Example1
  Real a[Claytex.Types.GearHand];
equation
  for i in Claytex.Types.GearHand loop
    a[i] = i+1.;
  end for;
end Example1;

This works because an enumeration actually gains an integer value that depends on the order in which the options are defined in the type.  The first option would gain the value 1, the second option would gain the value 2, etc.

How can I add my own Units?

In this example we will add a unit conversion to allow us to parameterise the Spring Damper component (Modelica.Mechanics.Rotational.Components.SpringDamper) with common stiffness and damping units corresponding to the RotationalStiffnessConstant and RotationalDampingConstant SI units respectively.

Unit conversion is handled in the displayunit.mos file found within the <Dymola>Insert directory (Where <Dymola> is the directory where Dymola has been installed)

Firstly, close Dymola if open and make a backup of displayunit.mos. Open the original displayunit.mos in Notepad and include the new unit conversion using the syntax defineUnitConversion(“unit”, “DisplayUnit”, conversion factor). For this example we add the lines:

// Damping
defineUnitConversion(“N.m.s/rad”, “N.m.s/deg”,180/3.14159265358979323846);
defineUnitConversion(“N.m.s/rad”, “N.mm.s/deg”,1000*180/3.14159265358979323846);

// Stiffness
defineUnitConversion(“N.m/rad”, “N.m/deg”,180/3.14159265358979323846);
defineUnitConversion(“N.m/rad”, “N.mm/deg”,1000*180/3.14159265358979323846);

Save and close displayunit.mos (this may require administrator access rights) and open the Spring Damper in Dymola. The parameter units should now allow the new units to be entered as shown below: