Giving unit to literals

[HansOlsson]

As part of unit-checking #3491 various ways of attaching units to Reals are proposed including withUnit(...) and 1 'm'. After additional internal discussion we have found a simpler proposal that voids most of the pitfalls.

The simple proposal is that Real (and any type derived from Real) can be called as follows:

function Real
  input Real _v;
  input String unit;
  input String displayUnit=unit;
  output Real y(unit=unit, displayUnit=displayUnit)=_v;
end Real;

Benefits:

• No, new syntax or reserved words needed.
• Close to the syntax of component declarations, and with the same semantics.
• Would allow replacing parameter Real p(unit="m", displayUnit="mm")=0.001; by parameter Real p=Real(0.001, unit="m", displayUnit="mm"); - with the same semantics, in particular we make it easy to avoid non-base-units in equations.
• Possible to vectorize (at least in the first argument)

Including types derived from Real would allow something like the following in the IdealDiode:

 v = (s * SI.Current(1) ) * (if off then 1 else Ron) + Vknee;
  i = (s * SI.Voltage(1) ) * (if off then Goff else 1) + Goff*Vknee;

[henrikt-ma]

I am strongly against the idea of using the types derived from Real, mainly because of the following two related reasons:

• The name of a type is generally not expected to clearly express the value of its unit-attribute.
• Pretty much all of the types in Modelica.Units are named based on the quantity, not the unit.

The use of SI.Current and friends is also limited in that the solution becomes dependent on having a nice selection of types with unit to choose from, in order to avoid being back on square one with one-off type definitions instead of one-off constant declarations. Further, even if the MSL comes with a fairly big collection of units mapped to types, finding the right type to use will require special tool support when editing the equations where a unitful literal is needed.

Regarding Real(0.001, unit = "m"), I can see that it would be an alternative to withUnit(0.001, "m"). However, since I believe that we will also want to have operators for unit conversion and extraction of numeric values in the end, it makes more sense to me to go for a new operator such as withUnit instead of overloading Real. For me, however, the introduction of withUnit is a topic for the future, and what matters more right now is that 0.001'm' is so much more readable compared to Real(0.001, "m").

Vectorization will not be a problem once we get to the operator forms in the future. In the meantime, there are still the two options of using a one-off constant array or to add the unit to each of the array elements in case the array is small. By the way, how many examples have we encountered so far where this is needed?

[HansOlsson]

I am strongly against the idea of using the types derived from Real, mainly because of the following two related reasons:

• The name of a type is generally not expected to clearly express the value of its unit-attribute.
• Pretty much all of the types in Modelica.Units are named based on the quantity, not the unit.

Those are some of the reasons why it is a good idea, as it expresses the underlying intent which isn't tied to the unit. I hadn't realized that when I wrote it, but now it becomes much clearer.

One reason is that quantities have understandable (and familiar) names, and that's why they are used in Modelica - and similarly the current work-arounds are normally called unitTime, unitCurrent, etc.

I simply don't see a problem with someone using Enthalpy in a formula to indicate that it is enthalpy and not something else that happen to have the same unit (even if only the unit is used for checking) - but I do see the benefits in terms of understandability.

More fundamentally the title of this issue says "Giving units to literals" - whereas it in the SI-standard is introduced as "Defining the unit of a quantity"; and the definition of base units are preceded by the corresponding quantities. That shift in perspective is important - one shouldn't think of starting with 1.6 in a formula and slap a unit on it, but start with a quantity - that has a numeric value and a unit.

The use of SI.Current and friends is also limited in that the solution becomes dependent on having a nice selection of types with unit to choose from, in order to avoid being back on square one with one-off type definitions instead of one-off constant declarations. Further, even if the MSL comes with a fairly big collection of units mapped to types, finding the right type to use will require special tool support when editing the equations where a unitful literal is needed.

Yes, tools can spend the effort of one simple way of finding them; that can be used both for declarations and for these cases; whereas we otherwise need one way of finding the type when declaring parameter with a certain quantity and another for finding units when defining the unit of a quantity inside equations.

[henrikt-ma]

More fundamentally the title of this issue says "Giving units to literals" - whereas it in the SI-standard is introduced as "Defining the unit of a quantity"; and the definition of base units are preceded by the corresponding quantities. That shift in perspective is important - one shouldn't think of starting with 1.6 in a formula and slap a unit on it, but start with a quantity - that has a numeric value and a unit.

I agree in the sense that slapping units to 1.6 isn't how we should think about what we are doing. The problem I see that we need to solve is how to express a length of 160 centimeters in an equation. While the kind of quantity (here, length) is quite useful information about a variable, the role is minor if any inside equations (connect-equations being an exception). What really matters within equations is knowing the unit associated with the numeric value.

Who really cares if the 5e3'J' in this equation is work or energy?

Power power = 5e3'J' / 600's';

[HansOlsson]

More fundamentally the title of this issue says "Giving units to literals" - whereas it in the SI-standard is introduced as "Defining the unit of a quantity"; and the definition of base units are preceded by the corresponding quantities. That shift in perspective is important - one shouldn't think of starting with 1.6 in a formula and slap a unit on it, but start with a quantity - that has a numeric value and a unit.

I agree in the sense that slapping units to 1.6 isn't how we should think about what we are doing. The problem I see that we need to solve is how to express a length of 160 centimeters in an equation. While the kind of quantity (here, length) is quite useful information about a variable, the role is minor if any inside equations (connect-equations being an exception). What really matters within equations is knowing the unit associated with the numeric value.

Who really cares if the 5e3'J' in this equation is work or energy?

Power power = 5e3'J' / 600's';

I would say it is Work, but I view objecting to Energy there as a bit of nitpicking.
However, Enthalpy would seem quite odd (all of them have the same unit).

The difference is that Work is the Energy transferred, which goes together with a time-period (and Enthalpy is quite different).

However, I see two major drawbacks with 'J':

• Having units as both strings and variable names interpreted as strings will be confusing.
• There is a major ambiguity for 5'kJ' - normally equations in Modelica are written using base-units; so the natural interpretation is that 5'kJ' means Real(5000,unit="J",displayUnit="kJ") - but there are also less common cases of using prefixed units, other derived units, units acceptable for use with the SI-system and also other units. Thus thinking that it was meant to have unit "kJ" wouldn't seem outlandish - and that ambiguity would just break the good parts of units in Modelica. (Automatic conversions between prefixed units in equations is a big can of worms.)

I view both as blockers on their own, and and none of this is currently needed. There are some literals in libraries that need to be converted to quantities with unit to have better unit-checking.

[henrikt-ma]

However, I see two major drawbacks with 'J':

• Having units as both strings and variable names interpreted as strings will be confusing.

It is not nice, but still so good that it has support both in SimulationX and System Modeler.

Perhaps you would prefer 5e3["J"], which is also easy to implement?

• There is a major ambiguity for 5'kJ' - normally equations in Modelica are written using base-units; so the natural interpretation is that 5'kJ' means Real(5000,unit="J",displayUnit="kJ") - but there are also less common cases of using prefixed units, other derived units, units acceptable for use with the SI-system and also other units. Thus thinking that it was meant to have unit "kJ" wouldn't seem outlandish - and that ambiguity would just break the good parts of units in Modelica. (Automatic conversions between prefixed units in equations is a big can of worms.)

There is no ambiguity here:

Real x(unit = "J") = 1;
Real y(unit = "kJ") = 5;
Real a = x + y;     // Unit error.
Real b = x + 5'kJ'; // Unit error, just like above.

To think about automatic conversions is making this a lot more complicated than it should be.

[HansOlsson]

However, I see two major drawbacks with 'J':

• Having units as both strings and variable names interpreted as strings will be confusing.

It is not nice, but still so good that it has support both in SimulationX and System Modeler.

Whereas we have support in Dymola for:
5000 J and 5 kJ
in the parameter dialog, which conforms to BIPM recommendations (except for a minor issue with degree-symbol); and we also show them in that form (with correct handling of the degree-symbol). (And I'm not sure which interpretation SimulationX uses, I hope it is the same as Dymola.)

Real x(unit = "J") = 1;
Real y(unit = "kJ") = 5;
Real a = x + y;        // Unit error.
Real b = x + 5'kJ'; // Unit error, just like above.

That will just bring chaos and disappointed users.

In Modelica we have for decades used displayUnit to write SI.Energy y(displayUnit="kJ") = 5000; and show 5 kJ.
Introducing another way of writing 5 kJ - that will not work in the same scenario (even if you can write it) - is just a massive step backwards.

And more fundamentally I don't see that as needed to solve the actual issue of improving unit-checking of equations, as equations should normally be in base-SI-units whereas non-base-unit normally only appear in the external interface (as parameters and for plots).

[henrikt-ma]

I would say it is Work, but I view objecting to Energy there as a bit of nitpicking. However, Enthalpy would seem quite odd (all of them have the same unit).

The point is that reasoning about the kind of quantity is not possible in the way we can do it for units. The following looks stupid to me, but not possible to reject based on any general principle that I am aware of:

Power power = Torque(5e3) / 600's';

Hence, what you can see here is only the inapplicable information that the author had torque in mind, while you cannot see the important part, being the unit of 5e3.

[henrikt-ma]

Whereas we have support in Dymola for:
5000 J and 5 kJ
in the parameter dialog, which conforms to BIPM recommendations (except for a minor issue with degree-symbol); and we also show them in that form (with correct handling of the degree-symbol). (And I'm not sure which interpretation SimulationX uses, I hope it is the same as Dymola.)

You are mixing things up. The introduction of a syntax for attaching a unit to a literal is not replacing the old way of editing parameter values in a chosen display unit. This mechanism works great for setting parameter values where the parameter is properly declared with a type that comes with quantity, unit, and possibly a displayUnit. This is working great also in System Modeler (not even a tiny space between the number and the degree symbol), and there is no intention of changing this.

Literals with unit should be used deeper down in expressions and equations, where the unit is not immediately available from the context.

In Modelica we have for decades used displayUnit to write SI.Energy y(displayUnit="kJ") = 5000; and show 5 kJ.
Introducing another way of writing 5 kJ - that will not work in the same scenario (even if you can write it) - is just a massive step backwards.

No, since tools will guide the users to using the decades old mechanism when editing these declaration equations.

[HansOlsson]

I would say it is Work, but I view objecting to Energy there as a bit of nitpicking. However, Enthalpy would seem quite odd (all of them have the same unit).

The point is that reasoning about the kind of quantity is not possible in the way we can do it for units. The following looks stupid to me, but not possible to reject based on any general principle that I am aware of:

Power power = Torque(5e3) / 600's';

Hence, what you can see here is only the inapplicable information that the author had torque in mind, while you cannot see the important part, being the unit of 5e3.

So, you are claiming that the syntax, that solves all of the actual problems without introducing any, would be bad because people might write bad code that we cannot currently detect?

Added: And similarly we wouldn't detect an error for Power power =5e3'N.m' / 600's'; even if the unit is visible.

[HansOlsson]

Whereas we have support in Dymola for:
5000 J and 5 kJ
in the parameter dialog, which conforms to BIPM recommendations (except for a minor issue with degree-symbol); and we also show them in that form (with correct handling of the degree-symbol). (And I'm not sure which interpretation SimulationX uses, I hope it is the same as Dymola.)

You are mixing things up.

No. I'm staying consistent - since I care about the entire user experience.

I don't want two different ways of writing 5 kJ with wildly different semantics (especially not to handle a corner case that we don't see a need for), and I don't want two different ways of introducing literals with unit - when one will do.

I'm trying to solve actual problems - where MSL have a few equations with real values that are some quantity with unit where the unit is currently omitted (and similarly in other libraries); and I want an actual solution.

This proposal shows that:

• It doesn't require new syntax or keywords.
• It can be done in a way that is consistent with existing Modelica
• It doesn't introduce the risk of ambiguities (or "mixing things up")

[henrikt-ma]

And more fundamentally I don't see that as needed to solve the actual issue of improving unit-checking of equations, as equations should normally be in base-SI-units whereas non-base-unit normally only appear in the external interface (as parameters and for plots).

Sticking to SI base units doesn't remove the need for attaching units to literals:

  Modelica.Units.SI.Distance d = 50;
  Modelica.Units.SI.Velocity v = d / 20's';

[henrikt-ma]

So, you are claiming that the syntax, that solves all of the actual problems without introducing any, would be bad because people might write bad code that we cannot currently detect?

No. I'm saying that it solves the wrong problem. It solves the problem of being able to express the kind of quantity for a sub-expression, but doesn't solve the problem of clearly attaching a certain unit to the literal.

[HansOlsson]

And more fundamentally I don't see that as needed to solve the actual issue of improving unit-checking of equations, as equations should normally be in base-SI-units whereas non-base-unit normally only appear in the external interface (as parameters and for plots).

Sticking to SI base units doesn't remove the need for attaching units to literals:

  Modelica.Units.SI.Distance d = 50;
  Modelica.Units.SI.Velocity v = d / 20's';

And the proposal solves that either as:

Modelica.Units.SI.Distance d = 50;
Modelica.Units.SI.Velocity v = d / Real(20,unit="s");

or as:

import Modelica.Units.SI;
SI.Distance d = 50;
SI.Velocity v = d / SI.Time(20);

No new syntax, no new keywords even though in this case I would just write:

import Modelica.Units.SI;
SI.Distance d = 50;
SI.Time t = 20;
SI.Velocity v = d / t;

(Even if Real t(unit="s")=20; is legal as well. Added: As well as Real t=SI.Time(20);, Real t=Real(20, unit="s");, and SI.Time t = SI.Time(20);)

[gkurzbach]

For me, the proposals are not a big contradiction. One could allow both spellings. For simple units, such as 1 kJ, you could omit them single quotes, if you want to write 1 '°C' or 1 'm/s' you just have to use them. Syntactically, both are just IDENTs. The quotes only increase the number of representable units.
One could also allow the notation as a record constructor. However, I find it very cumbersome and writing or reading
d / Real(20, unit="s"); is not a good user experience. I don't think it's a good idea to require this just to avoid introducing new syntax (although 1 kJ is already new syntax).
Further, the provided type information with this notation is not needed, because currently there is no defined semantics about the quantity attribute and there is no way to infer the permitted units from the quantity attribute. Also the unit checking only deals with units.
The notation as a function also raises another question: one could come up with the idea of giving other attributes besides unit to the constructor call. What happens to them then? Or does that lead to an error message? I find it a bit excessive to do this only for the special case of the unit attribute.