class HowToUseSIunits "How to use SIunits"
extends Modelica.Icons.Information;
annotation (
DocumentationClass = true,
Documentation(info = "<html>\n<p>\nWhen implementing a Modelica model, every variable needs to\nbe declared. Physical variables should be declared with a unit.\nThe basic approach in Modelica is that the unit attribute of\na variable is the <strong>unit</strong> in which the <strong>equations</strong> are <strong>written</strong>,\nfor example:\n</p>\n\n<pre> <strong>model</strong> MassOnGround\n <strong>parameter</strong> Real m(quantity=\"Mass\", unit=\"kg\") \"Mass\";\n <strong>parameter</strong> Real f(quantity=\"Force\", unit=\"N\") \"Driving force\";\n Real s(unit=\"m\") \"Position of mass\";\n Real v(unit=\"m/s\") \"Velocity of mass\";\n <strong>equation</strong>\n <strong>der</strong>(s) = v;\n m*<strong>der</strong>(v) = f;\n <strong>end</strong> MassOnGround;\n</pre>\n\n<p>\nThis means that the equations in the equation section are only correct\nfor the specified units. A different issue is the user interface, i.e.,\nin which unit the variable is presented to the user in graphical\nuser interfaces, both for input (e.g., parameter menu), as well as\nfor output (e.g., in the plot window). Preferably, the Modelica tool\nshould provide a list of units from which the user can select, e.g.,\n\"m\", \"cm\", \"km\", \"inch\" for quantity \"Length\". When storing the value in\nthe model as a Modelica modifier, it has to be converted to the unit defined\nin the declaration. Additionally, the unit used in the graphical\nuser interface has to be stored. In order to have a standardized way\nof doing this, Modelica provides the following three attributes\nfor a variable of type Real:\n</p>\n\n<ul>\n<li><strong>quantity</strong> to define the physical quantity (e.g., \"Length\", or \"Energy\").</li>\n<li><strong>unit</strong> to define the unit that has to be used\n in order that the equations are correct (e.g., \"N.m\").</li>\n<li><strong>displayUnit</strong> to define the unit used in the graphical\n user interface as default display unit for input and/or output.</li>\n</ul>\n\n<p>\nNote, a unit, such as \"N.m\", is not sufficient to define uniquely the\nphysical quantity, since, e.g., \"N.m\" might be either \"torque\" or\n\"energy\". The \"quantity\" attribute might therefore be used by a tool\nto select the corresponding menu from which the user can select\na unit for the corresponding variable.\n</p>\n\n<p>\nFor example, after providing a value for \"m\" and \"f\" in a parameter\nmenu of an instance of MassOnGround, a tool might generate the following code:\n</p>\n\n<pre>\n MassOnGround myObject(m(displayUnit=\"g\")=2, f=3);\n</pre>\n\n<p>\nThe meaning is that in the equations a value of \"2\" is used\nand that in the graphical user interface a value of \"2000\" should be used,\ntogether with the unit \"g\" from the unit set \"Mass\" (= the quantity name).\nNote, according to the Modelica specification\na tool might ignore the \"displayUnit\" attribute.\n</p>\n\n<p>\nIn order to help the Modelica model developer, the Modelica.SIunits\nlibrary provides about 450 predefined type names,\ntogether with values for the attributes <strong>quantity</strong>, <strong>unit</strong> and sometimes\n<strong>displayUnit</strong> and <strong>min</strong>. The unit is always selected as SI-unit according to the\nISO standard. The type and the quantity names are the\nquantity names used in the ISO standard. \"quantity\" and \"unit\" are defined\nas \"<strong>final</strong>\" in order that they cannot be modified. Attributes \"displayUnit\"\nand \"min\" can, however, be changed in a model via a modification. The example above,\nmight therefore be alternatively also defined as:\n</p>\n\n<pre> <strong>model</strong> MassOnGround\n <strong>parameter</strong> Modelica.SIunits.Mass m \"Mass\";\n <strong>parameter</strong> Modelica.SIunits.Force f \"Driving force\";\n ...\n <strong>end</strong> MassOnGround;\n</pre>\n\n<p>\nor in a short hand notation as\n</p>\n\n<pre>\n <strong>model</strong> MassOnGround\n <strong>import</strong> SI = Modelica.SIunits;\n <strong>parameter</strong> SI.Mass m \"Mass\";\n <strong>parameter</strong> SI.Force f \"Driving force\";\n ...\n <strong>end</strong> MassOnGround;\n</pre>\n\n<p>\nFor some often\nused Non SI-units (like hour), some additional type definitions are\npresent as Modelica.SIunits.Conversions.NonSIunits. If this is not sufficient,\nthe user has to define its own types or use the attributes directly\nin the declaration as in the example at the beginning.\n</p>\n\n<p>\n<strong>Complex units</strong> are also included in Modelica.SIunits. A complex unit is declared as:\n</p>\n<pre>\n <strong>model</strong> QuasiStationaryMachine\n <strong>parameter</strong> Modelica.SIunits.ComplexPower SNominal = Complex(10000,4400)\n \"Nominal complex power\";\n ...\n <strong>end</strong> QuasiStationaryMachine;\n</pre>\n</html>"));
end HowToUseSIunits;