Appearance of initialization variables in the parameter dialog

[abuntrock]

Description

During our Modelica library development at Bosch Rexroth we stumbled across the problem of initialization variables being shown in the parameter dialogue based on different conditions in different tools.

I read through existing issues regarding the default choice of Dialog.showStartAttribute #2823 and the usage of this Dialog annotation in the MSL https://github.com/modelica/ModelicaStandardLibrary/issues/1855, https://github.com/modelica/ModelicaStandardLibrary/pull/2896, https://github.com/modelica/ModelicaStandardLibrary/pull/2897. All those issues are still open or marked as a wontfix until a completely new initialization approach is developed for the MSL from my understanding. We do not want to debate those issues since we do not think that we are qualified to do so even though we would be highly interested in a solution.

For us, the most important thing is a coherent appearance in the parameter dialogue of different Modelica tools.
As shown by @beutlich in a comment to one of the above tickets https://github.com/modelica/ModelicaStandardLibrary/issues/2896#issuecomment-494942593_ the non-uniform handling of initialization leads to different visualizations in Dymola and SimulationX. Four years later this is still the case and now a problem in our development process as well. Our two pain points, which result in different visualizations are:

1. If only a start modifier and no Dialog (thus, also no showStartAttribute) annotation is present Dymola (and OMEdit) will show the variable's start value in the parameter dialogue and SimulationX won't.

   SI.Acceleration a(start=0) "Absolute acceleration of component";

2. If a start modifier and a showStartAttribute=false annotation is present, Dymola won't show the variable in the dialogue and SimulationX will show the variable (but not its start value, which is correct according to the specification section 18.7).

   SI.Position spoolPos(start=0) "Spool position" annotation (Dialog(showStartAttribute=false));

Way forward

We hope that there is a solution with a clarified specification regarding visualization that results in equally looking parameter dialogues without the need to redo the initialization concept in the tools and the MSL itself.

In the Modelica specification 3.6 I did not find a formulation regarding the appearance of variables in the user interface. I specifically searched in sections 4.4 (Component declarations) and 18.7 (annotations for graphical user interface). If I missed something, please let me know.

We expect that formulations like the two below would help to create a more uniform picture across different tools. (These formulations would obviously be overwritten by prefixes like final).

1. A variable with no dialogue annotation and a start modifier should (or should not) be displayed in the user interface. Tackles first pain point. Here the variable's start value should be displayed.
2. A variable with a dialogue annotation always has to appear in the user interface. Tackles second paint point. (The variable itself or its start value is shown depending on the value of Dialog.showStartAttribute).

Thanks for considering this Aaron Buntrock - Bosch Rexroth

[HansOlsson]

For the 2nd point I believe a better solution is the one implemented in Dymola - specifically that a variable with a Dialog-annotation has to appear in the user interface, unless it only contains showStartAttribute=false. (*)

The idea was based on requests, specifically that if you have a declaration: Real var(start=0, fixed=true); and for some reason don't want its start-value to appear you change the declaration to: Real var(start=0, fixed=true) annotation(Dialog(showStartAttribute=false));

But you don't want the variable itself to appear, just because you didn't want the start-value to appear!

However, if you set tab and/or group you obviously want the variable to appear there (and not the start-value).

For the 1st point, I also agree that if you have a start-value it makes sense to show it as if showStartAttribute=true. That logic was added before showStartAttribute=true was added to libraries, but it still makes sense - because it also covers other important cases:

• There is a start-value modification for this instance.
• There is a start-value modification inherited in some way.

This makes the handling more uniform - if a variable has a start-value you as default change it in the Initialization-group.

*: Another special case is that if it has connectorSizing=true, then it should not appear at all.

[abuntrock]

@HansOlsson Thanks for the explanation. I personally agree with both of your points and also think that Dymola's behaviour is better.

Regarding my first point (Appearance in UI based on start-value): Thanks for the explanation of those other important cases.

Regarding the second point (Non appearance in UI if dialogue annotation only contains showStartAttribute=false): We also have the exact scenario described by you in our own library.

However, both your explanations are not part of the Modelica Specification. Am I right? For us as a library developer this means, that we have not much leverage when trying to change the behavior in some tools using bug reports.

Thanks for your assessment Aaron Buntrock

[eshmoylova]

Other cases where I noticed tool inconsistencies are displaying in the Dialog of parameters with fixed = false and non-connector variables marked with input. Just adding here, so that, when we work on the specification, those cases do not get overlooked.

[HansOlsson]

Phone meeting: Add guideline (or recommendation) in the specification for this: Agree (to try at least).

[d-hedberg]

Regarding the first point:

If only a start modifier and no Dialog (thus, also no showStartAttribute) annotation is present Dymola (and OMEdit) will show the variable's start value in the parameter dialogue and SimulationX won't. SI.Acceleration a(start=0) "Absolute acceleration of component";

If I remember correctly this is only true if the specified start value is a literal. In the example below, Dymola will show none of the variables' start values in the GUI. Whether or not this is intentional or what the motivation behind it is I don't know.

SI.Acceleration a1(start=10+10) "Absolute acceleration of component";
SI.Acceleration a2(start=someOtherVariable) "Absolute acceleration of component";

[HansOlsson]

If I remember correctly this is only true if the specified start value is a literal. In the example below, Dymola will show none of the variables' start values in the GUI. Whether or not this is intentional or what the motivation behind it is I don't know.

It is intentional. (Without checking, I also believe it is only literal, where negative numbers are seen as literal.)

It's always a problem where to draw the line, but in the example below - it don't think you want both a2.start and someOtherVariable in the parameter dialog, or similarly if the start-value is some computation based on parameters.

parameter Real someOtherVariable;
SI.Acceleration a2(start=someOtherVariable) "Absolute acceleration of component"

If it is a literal value there's no similar confusion.

[HansOlsson]

So the relevant cases I can see are:

• Modifier in the current scope: clearly you want to be able change it - so show it! (except if connectorSizing=true, latter is specified).
• Dialog:
  • connectorSizing=true: Don't show at all (specified)
  • with only showStartAttribute=false: I believe we should follow Dymola and as default not show anything.
  • with showStartAttribute=true, show start-value (specified)
  • normal: show (specified)
• Non-connector input: I believe we should follow Dymola and show (since you can set inputs).
• Parameters without fixed=false. I'm not sure if specified, but clearly it makes sense to show them.
• Parameters with fixed=false. I would propose to say that they should as default not be shown (currently shown in Dymola).
• Non-parameters (and non-constant) with literal start-value. I believe we should follow Dymola and show start-value.

For consistency I believe we should generalize the showStartAttribute=false to also allow connectorSizing=false (even if no-one uses that). Obviously if the variable and/or modifier is final we shouldn't allow modification - and might skip showing them. (Dymola allows showing them - the reason is that you can also use the parameter dialog to see the current value.)

Added: I'm now unsure about connectorSizing=false, since the annotation is normally on parameters, so too weird.

[abuntrock]

This sounds reasonable to me. Thanks for the summary. An additional note since you brought constants up as well and we are already talking about what to show in the user interface:

1. Constants with a dialogue annotation (group and/or tab) should be displayed in the parameter dialogue as well.

Currently Dymola does not show this but for example OMEdit does. Not showing them would also be OK for us. As mentioned above a similar look is most important for our use case.

[HansOlsson]

This sounds reasonable to me. Thanks for the summary. An additional note since you brought constants up as well and we are already talking about what to show in the user interface:

1. Constants with a dialogue annotation (group and/or tab) should be displayed in the parameter dialogue as well.

Currently Dymola does not show this but for example OMEdit does. Not showing them would also be OK for us. As mentioned above a similar look is most important for our use case.

Showing public non-final constants would currently be problematic as MSL contain a number of such constants that are not intended to be changed, e.g.: Modelica.Magnetic.FundamentalWave.Examples.BasicMachines.SynchronousMachines.SMPM_Braking

  constant Integer m=3 "Number of phases";
  constant Real unitK( unit="rad/(s.Ohm)")=1 annotation(HideResult=true);

(Well, I believe there's a separate PR about removing the use of unitK.)

[abuntrock]

For clarification. OMEdit only displays non-final public constants if they include a dialog annotation. So the constants from your MSL example are not shown there and we also do not want them be shown.

The question whether non-final public constants with a dialog annotation should be displayed or not is also not that important for us. What matters most in our opinion is that a clarification in the specification is needed to reach a uniform dialog appearance across different tools.

[HansOlsson]

For clarification. OMEdit only displays non-final public constants if they include a dialog annotation. So the constants from your MSL example are not shown there and we also do not want them be shown.

The question whether non-final public constants with a dialog annotation should be displayed or not is also not that important for us. What matters most in our opinion is that a clarification in the specification is needed to reach a uniform dialog appearance across different tools.

We can certainly add state that they should be added if they have a Dialog-annotation; I hope no-one uses that for such cases.

[HansOlsson]

So the proposed logic is:

• If we have modifier in current scope and not Dialog(connectorSizing=true) - show
• If default modifier (or declaration) is final - don't show
• If we have Dialog (including constants and other non-parameters):
  • If contains connectorSizing=true, or only contains showStartAttribute=false, don't show
  • If showStartAttribute=true, show start-attribute
  • Otherwise show
• Non-connector input: show
• Parameter that does not have fixed=false: show
• Parameter with fixed=false: ?(I'm not sure; maybe show start-attribute for setting guess-value)
• non-parameter and non-constant with literal start-attribute: show start-attribute?

We might also skip specifying the last two for now, and encourage users to actually use showStartAttribute=true for the last case.

[henrikt-ma]

The specification shouldn't be overly detailed on what to show; tools also need freedom for intelligent behavior tailored for different situations. Also, not all tools look the same, and what makes sense to show in one tool may not always make sense to show in another tool, and vice versa.

[henrikt-ma]

Hopefully, we will get the Ternary type in the next version, allowing us to finally return to the introduction of a Ternary visible attribute of the Dialog-annotation, so that there is at least a standard way of requiring that a variable is either hidden or shown.