Change proposal to show calculation equation in icon of Division

[christiankral]

Every time I am using Modelica.Blocks.Math.Division I cannot figure out intuitively whether the output is calculated by y = u1 / u2 or y = u2 / u1. I thus propose to add the calculation formula y = u1 / u2 information to icon (right icon, division_proposal):

[christiankral]

It were actually also very helpful to allow modifications of doc strings, particularly in blocks:

block Division "Output first input divided by second input"
  extends Modelica.Blocks.Interfaces.SI2SO(
    u1 "Dividend",u2 "Divisior", y "Quotient u1 / u2");
equation
  y = u1/u2;
end Division;

Apparently this code is legal in Modelica but the doc strings are not modified, neither in OpenModelica nor Dymola.

[beutlich]

I'd propose to apply the same font style, size and color as in Modelica.Blocks.Math.Add.

[beutlich]

It were actually also very helpful to allow modifications of doc strings, particularly in blocks:

block Division "Output first input divided by second input"
  extends Modelica.Blocks.Interfaces.SI2SO(
    u1 "Dividend",u2 "Divisior", y "Quotient u1 / u2");
equation
  y = u1/u2;
end Division;

Apparently this code is legal in Modelica but the doc strings are not modified, neither in OpenModelica nor Dymola.

FYI, modification of description strings is properly supported by SimulationX.

[christiankral]

I'd propose to apply the same font style, size and color as in Modelica.Blocks.Math.Add.

I wonder if we should pick the same font and color as in Modelica.ComplexBlocks.ComplexMath.Sqrt, as the text is more related to calculation function (as sqrt) than the parameters in Add.

[christiankral]

FYI, modification of description strings is properly supported by SimulationX

Good to know. I think we should then at least add the description string modifiers, even though some tools do not yet support this feature.

[christiankral]

To be even more concise and consistent: the text string shall only be u1 / u2

[beutlich]

I think we should then at least add the description string modifiers, even though some tools do not yet support this feature.

I was not absolutely sure if comment modification is legal Modelica or not. If we add it here, it will open new possibilities for comments of all other classes as well.

[HansOlsson]

I was not absolutely sure if comment modification is legal Modelica or not. If we add it here, it will open new possibilities for comments of all other classes as well.

The comment modifications are legal in themselves (i.e. modifications can have such comments), but their semantics is not well-defined as far as I know. In particular it is not clear whether it is a description for the modification itself, or intended to override (or amend) the description of the original component.

For the actual proposals:
Having comments on u1, u2, and y seems like over-commenting - and sets a precedence for other libraries, that will take efforts that could be better spent elsewhere.

The updated original idea of just having "u1 / u2" in the icon-layer suffices for me, and can also be generalized to other cases where we don't have as well-known names for the operands, like matrix left-division.

[tobolar]

Should the text field height follow the recommendations in Modelica.UsersGuide.Conventions.Icons, i.e. 30 units?

Actually, there are recommendations only for Component Name and Parameter Name in that Icon design guide. I think there should also be some for other auxilliary text.

[christiankral]

@HansOlsson and @sjoelund: do you know whether the modified descriptions strings are legal? Both Dymola and OpenModelica process the modifiers without complaints (but without effect)...

[christiankral]

@HansOlsson and @sjoelund: do you know whether the modified descriptions strings are legal? Both Dymola and OpenModelica process the modifiers without complaints (but without effect)...

... sorry -- I didn't update my browser and did not see your comments when responding

I would then propose to add description text such as "u1 / u2" to the icon layer to better explain the behavior.

[christiankral]

Should the text field height follow the recommendations in Modelica.UsersGuide.Conventions.Icons, i.e. 30 units?

Actually, there are recommendations only for Component Name and Parameter Name in that Icon design guide. I think there should also be some for other auxiliary text.

I agree, we do not have guidelines for the text format of description strings. In Modelica.Blocks.Math the following text format is used:

• text height = 48
• text RGB color = {192,192,192}

Since we use text height of 40 for both %name and %parameter, I suppose it makes sense to unify the text height to 40 and put this into the documentation Modelica.UsersGuide.Conventions.Icons.

[tobolar]

@christiankral ... with option of 30 or minimum of 20 units. This could be esp. needed to not overcrowd the icon if there are used both an auxilliary text and a parameter text.

Should we also give a recommendation for the color? The icon guide states: ...main icon color of a component shall be the same for all components of one library. Does this also apply for the auxilliary text or would it be better to recommend some particular color (e.g. gray) as this is the case for the Parameter name?

[christiankral]

Sounds like a plan: default text height is 40, optional 30, minimum 20.

Personally, I think it is good to fix a default color for descriptive text. Once you understand the color scheme, you understand the meaning of each text element. I actually wanted to stick with the text color used in Modelica.Blocks.Math, i.e. text RGB color {192,192,192}, but this may be to light for e.g. Modelica.Electrical.Analog.Sensors.VoltageSensor. Therefore I propose color {128,128,128} as a compromise to be clearly distinguished by parameters.

Summary of icon text colors:

• RGB blue {0,0,255}: instance name
• RGB blue {0,0,0}: parameters
• RGB blue {128,128,128}: descriptive text, explaining how a model works

If we stick with such a scheme, we have to modify a couple more icons to my understanding. To start from somewhere, I listed some models of the Analog package. @tobolar could you please double check if you agree with my color change proposals?

• Modelica.Electrical.Analog.Basic.Transformer: text color of "L1", "L2" and "M"
• Modelica.Electrical.Analog.Basic.Gyrator: text color of "G1" and "G2"
• Modelica.Electrical.Analog.Basic.CurrentToVoltageAdaptor: text color of "v", ...
• Modelica.Electrical.Analog.Basic.VoltageToCurrentAdaptor: text color of "v", ...
• Modelica.Electrical.Analog.Ideal.IdealTransformer: text color of "1" and "2"
• Modelica.Electrical.Analog.Ideal.AD_Converter and DA_Converter:
  • text color of "%n-bit" shall be black since it is a parameter description
  • text color of "ADC": is it descriptive ? I guess yes, shall be gray
• Modelica.Electrical.Analog.Sensors.PotentialSensor and other sensors: text color of "V", etc.
• Modelica.Electrical.Analog.Sources.SupplyVoltage: text color of "+", "0" and "-" are descriptive strings on my opinion and shall thus be gray. However, one could also argue that they are part of the symbol such as the "+" and "-" lines in, e.g., Modelica.Electrical.Analog.Sources.SignalVoltage

[beutlich]

The comment modifications are legal in themselves (i.e. modifications can have such comments), but their semantics is not well-defined as far as I know. In particular it is not clear whether it is a description for the modification itself, or intended to override (or amend) the description of the original component.

@HansOlsson SimulationX interpretes the comment modification as overriding the description of the original component.

Can you please file a new Modelica language clarification ticket. Not sure if we need an MCP for this. Thanks.

[tobolar]

@christiankral I would prefer fixed color pattern as well. That shade of gray you suggest is also used in Modelica.Mechanics.MultiBody. So from my perspective the color is fine.

I have also checked the Analog package. Beside those listed in your post, I have additionally found the following classes which should be adapted:

• Modelica.Electrical.Analog.Lines.ULine and others: text color of "ULine", etc.

• Modelica.Electrical.Analog.Examples.Utilities:

  • Nand: text color of "&", "x1", "x2", "y"
  • DirectCapacitor: text color of "to FMU", "v", "dv", "i"
  • InverseCapacitor: text color of : text color of "to FMU", "v", "dv", "i"
  • Resistor: text color of "to FMU", "v1", "v2", "i2", "i1"
  • DirectInductor: text color of "to FMU", "v", "di", "i"
  • InverseInductor: text color of "to FMU", "v", "di", "i"
  • Conductor: text color of "to FMU", "v1", "v2", "i2", "i1"

I also wonder whether we should have a particular definition for a connector descriptive text as is often used in MultiBody, see e.g. text a and b in Modelica.Mechanics.MultiBody.Interfaces.PartialTwoFrames. I rather think about the position and size of the text. Such a definition would of course affect Modelica.Blocks.Interfaces.PartialFMUadaptors.FlowToPotentialAdaptor as well.
(at) all: Is there a need to standardize this particular text?

[christiankral]

@tobolar In order to reduce the complexity of rules I would go for the same color and size of descriptive text of connectors. The descriptive text "u1 / u2" of the Division block could also be seen as descriptive text of the output connector.

In terms of location, I would tend to keep the descriptive inside the icon. Actually, when playing with text sizes it turns out that text height of 30 is still OK, as the greater text size of 40 may dominate the icon appearance.

So my proposal in addition to Modelica.UsersGuide.Conventions.Icons for any kind of descriptive text is:

• text color RGB {128,128,128}
• text height 30, minimum 20
• descriptive text shall be placed inside the icon, if possible
• descriptive text of connectors shall
  • be inside the connector, if possible; in case the descriptive text exceeds the icon boundaries, the text shall be left or right aligned to be as close as possible to the inside of the icon
  • be place above the connector with vertical distance of 10 (if possible) or less; the text box margins shall be divisible by 10 without remainder

Example of Diagram View:

[tobolar]

@christiankral Your suggestion complies to my experience so far. So it's fully fine to me.

[christiankral]

Are there any additional comments and/or opinions on descriptive icon text?

[HansOlsson]

Are there any additional comments and/or opinions on descriptive icon text?

To me it seems a bit problematic to add a text "a", "b", "torque", "resolve" next to the connectors with the same names. That is nothing new with this ticket, but it made me realize this and instead of improving the text-layout we should reconsider it. Some problems are:

• It seems repetitive: we already have the name of the connector, why manually repeat something close to it? To me it seems close to information overload, since the connectors also have different graphical appearance, and it is trivial to get the name as a tooltip etc. On a related note I see that many other libraries skip this.
• Some of the names differ - e.g. frame_a vs a, but resolve is the same.
• Not all models have it - e.g. RollingWheel have frame1, frame2 without any text.
• The text is not linked to the connector, e.g. the resolve connector is conditional and is often disabled - a tool might want to remove disabled conditional connectors - but then the texts remain.

[HansOlsson]

Can you please file a new Modelica language clarification ticket. Not sure if we need an MCP for this. Thanks.

Done: https://trac.modelica.org/Modelica/ticket/2237

[tobolar]

To me it seems close to information overload, since the connectors also have different graphical appearance, and it is trivial to get the name as a tooltip etc.

You are right for physical connectors where the maning should be clear. I see the meaning of the connector descriptive text especially for the real/boolean/integer connectors where the signals depend on the component they are used.
I also think the idea is not to only repeat the connector name. So having text 'torque' where 'tau' real connector is used is admissible to my opinion. But the text 'resolve' in the above figure is really overloaded information.

The tooltips are meaningful rather for clarification of a conector of a particular instance in the model. In contrast, the connector descriptive text is helpful for fast understanding / checking of the model at once.

Not all models have it - e.g. RollingWheel have frame1, frame2 without any text.

This is a discrepancy to be solved once the convention is clearly defined.

The text is not linked to the connector, e.g. the resolve connector is conditional and is often disabled - a tool might want to remove disabled conditional connectors - but then the texts remain.

Could this be solved using visible attribute?

[HansOlsson]

You are right for physical connectors where the maning should be clear. I see the meaning of the connector descriptive text especially for the real/boolean/integer connectors where the signals depend on the component they are used.

I agree that it might be useful for those case, and not in other cases.

However, in those cases this leads to the problem with base-classes as for Division - and it would be unfortunate if people don't use base-classes because of such texts. Thus a more general tool setting to show the connector name and/or the description might be better.

Could this be solved using visible attribute?

The visible attribute might help to de-clutter - but also cause issues; since there are reasons to show a disabled connector in some cases.

[christiankral]

I think that we should rather try to avoid additional connector descriptive text, as tooltips help a lot in identifying which connector is which. Therefore, I would rather see descriptive text to be part of the icon than over-explaining the connectors.

I understand that "torque" is better to understand than "tau". In the same we use descriptive text to distinguish, e.g., the Electrical.Analog.Sensors, which would otherwise look (almost) all the same:

So I think it makes sense to avoid descriptive text associated to connectors as far as possible.

You are right for physical connectors where the maning should be clear. I see the meaning of the connector descriptive text especially for the real/boolean/integer connectors where the signals depend on the component they are used.

@tobolar Could you possibly provide an example of such a component?

[tobolar]

Well the most striking component to me is Modelica.Blocks.Interfaces.PartialFMUadaptors.FlowToPotentialAdaptor and its counterpart PotentialToFlowAdaptor, where it is explicitly demanded to add texts describing the actual connectors.

Another example is Modelica.Mechanics.Rotational.Sensors.MultiSensor. In contrast, in most sensors from Modelica.Mechanics it is really possible to use just descriptive text similar to Electrical.Analog.Sensors.

To conclude, a connector descriptive text would be probably helpful where more real/boolean/integer connectors are used within a component.

[beutlich]

Can you please file a new Modelica language clarification ticket. Not sure if we need an MCP for this. Thanks.

Done: modelica/ModelicaSpecification#2237

FYI: This will be clarified in specification version 3.5.