General design for (use of) annotations

[henrikt-ma]

No description provided.

[henrikt-ma]

Anyone who wants to add another possible design or add arguments for or against the different alternatives should feel free to edit this directly in the document on the PR branch. Similarly if you just see the need to clarify something. That way, we get the essence of what we are discussing nicely organized.

On the other hand, if there is an argument that you disagree with, please make a comment on that line so that we can have a discussion here before it gets removed or altered too much.

[henrikt-ma]

The main file of the PR is this one: https://github.com/modelica/ModelicaSpecification/blob/MCP/0031-annotations/RationaleMCP/0031/annotations.md

[olivleno]

From my perspective it was as simple as: "Leave it as it is in Modelilca." I see no point in moving things that are well defined in the Modelica language, e.g. constant, parameter,..., but also displayUnit and so on, into newly invented annotations.
In this sense the following rationale argument:

(+) For a Modelica user, it is unexpected to find things that impact the simulation result hidden away in annotations.

is a very striking one we should appreciate and don't reinvent the wheel.
If there is a need for additional information to be stored in annotations, then ok. But, why reformulate information in new types of annotations if they can be expressed in a well established form.

[olivleno]

I have a hard time grasp what the paragraph Class Properties is trying to say.

[henrikt-ma]

If there is a need for additional information to be stored in annotations, then ok. But, why reformulate information in new types of annotations if they can be expressed in a well established form.

What happens in Modelica is that annotations are so full of irrelevant stuff they have to be collapsed when looking at the Modelica code in order to have a chance to see the really important parts, and I believe it will be similar with Flat Modelica. The reason for reformulating is thus to avoid the problem of not seeing the important things that are hidden in collapsed annotations. Expanding the annotations doesn't really help either, as it is totally impractical to find the important parts lurking somewhere in a huge annotation. In other words, hiding important information in annotations is a bad design that will have a bad impact on adoption of Flat Modelica outside the Modelica world.

[henrikt-ma]

I have a hard time grasp what the paragraph Class Properties is trying to say.

Annotations can appear in many places in the grammar. The one we usually think of is the annotation-comment inside the comment of a component-declaration. For this one, there are several places where information can be placed instead of inside the annotation, such as the type-prefix or the modification.

What I'm trying to cover with the Class Properties is that annotation-comment of a composition. I wanted to show that hiding important information about a class in the annotation isn't the only option available when designing Flat Modelica.

[casella]

What happens in Modelica is that annotations are so full of irrelevant stuff

Of course nothing prevents us from specifying explicitly what are the relevant annotations in Flat Modelica, and state that all other annotations, which are irrelevant for simulation (e.g. graphical annotations, documentation) must be removed. I think this is totally consistent with the rationale behind Flat Modelica, i.e., to have an intermediate declarative representation of the system for simulation (or other mathematical operations such as linearization, optimization etc.) use only.

they have to be collapsed when looking at the Modelica code in order to have a chance to see the really important parts, and I believe it will be similar with Flat Modelica.
In other words, hiding important information in annotations is a bad design that will have a bad impact on adoption of Flat Modelica outside the Modelica world.

This is only true if we start from the premise that we should keep all annotations in Flat Modelica. Which I think is not the right premise. If we remove all the irrelevant annotations such as graphical and documentation, what is left will be a lot more manageable and by definition relevant, so it won't have to be collapsed or hidden at all.

I don't think we need to reinvent the wheel, just keep what is relevant and discard everything else

[henrikt-ma]

It is true that we are probably not going to carry annotations for icons, diagrams, or documentation over to Flat Modelica. However, when used as an intermediate representation, I imagine that there can be lots of information for purposes we haven't even thought of yet, that will end up in vendor-specific annotations.

Note that any annotation that has a clear role for the user interaction with a simulation, such as choices and (at least to some degree) Dialog should be carried over to Flat Modelica, even though it is irrelevant for symbolic processing and numeric solving. I don't know what the full list of such annotations is today, but who knows how this will develop in the future, and how bulky these will be?

Also, thinking of the MCP for figure annotations, it isn't obvious to me that these should be stripped off, as they have to do with what to do with a simulation result.

To me, it seems necessary to reserve annotations for information that isn't intended for human reading or writing, and that is allowed to become bulky.

[gkurzbach]

I think that the cause of the discussion is the too wide scope of FlatModelica.
There are obviously still too many use cases that cannot be reconciled. We should try to sharpen the goals.

There are obviously conflicts between human writeability and readability and the demand
to pass as much as possible information from the original model.
Also, there seems to be a conflict between the flat structure and the idea of using all the information from Modelica's class annotations as well in FlatModelica.

In FlatModelica there are no more classes from the original model except functions. There are also no components and connections and their graphical representation any more.
Therefore it does not make sense to keep graphical annotations.

Since there are no more components, and therefore no component-oriented dialogs, it doesn't make sense to keep dialogue annotations. And since there is no semiautomatic possibility to change the structure (redeclaration), we don't need choices anymore.
Etc.

We should narrow our focus to the possibility to use FlatModelica for the actual simulation purposes themselves and not try to catch everything.

We should only keep annotations which have effect on the simulation itself. These are special class annotations of functions (they still exist).
On simple variables there are basically no annotations having influence to the simulation in Modelica, but there might be a need to have such, because
the need of additional information from the translation process.

[casella]

I completely agree with @gkurzbach here.

Flat Modelica should be amenable to human inspection, but it won't be used for building models. I can see no use for Dialog annotations or any graphical representation at this stage, the only use of Flat Modelica is to retain the mathematical description of the problem for further processing, be it simulation, linearization, optimization, model reduction, parameter identification, sensitivity analysis, optimal control, or whatever.

The only annotations we should retain are what we call "structural annotations" in OMC, i.e., annotations that (may) have an influence on efficient code generation, (which are not that many and can be listed explicitly) and throw away everything else by default. We already do that in our pseudo-Flat Modelica output in OMC and I think it makes lots of sense.

[HansOlsson]

I agree that it depends on the scope.

Based on the discussion regarding final and evaluation of parameters we do not only consider simulating the model exactly as specified, and thus the Dialog annotations can make sense (for easier setting of parameters for the simulation), but as Gerd noted flattening changes this - and one possibility is to only use this for top-level parameters.

If we consider dynamic visualization of the model (the DynamicSelect for attributes) then the graphics makes sense in some form. However, if we remove object-oriented stuff it means that the graphics need to be statically transformed a bit (we regularly do that in Dymola and 3D Experience for other reasons

[olivleno]

Conclusions from discussion at web meeting:

• Information kept in annotations in Modelica shall remain annotation in Flat_Modelica.
• Additional information required for numeric and symbolic processing will have to be decided in the future case by case.
• All standardized annotations for Flat Modelica shall be listed in this file in the "Summary of Flat Modelica annotations" section at the bottom.
• Additional vendor annotations are possible.

Next steps:

• Complete the list of Flat Modelica annotations. [Francesco]
• Adopt the design guidelines based on these conclusions. [Henrik]
• Get comments before final merge [all]

[henrikt-ma]

When adopting the guidelines according to yesterday's meeting, I realized that there is a possible twist that I didn't think of during the meeting. The idea is to narrow down the allowed annotations depending on context. This could be done either using semantic rules or even in the grammar (the non-recursiveness of classes would make it possible to have separate annotation grammars for each type of class). This would allow for the same sort of error detection as with first class language constructs.

For example, Inline would be rejected when appearing anywhere except in the class annotation of a function.

(I suppose it would be possible to do this kind of checking of annotations also in full Modelica, but I don't know whether there is actually support for rejecting Modelica models based on irrelevant annotations, and I know that at least SystemModeler doesn't have this kind of check.)

[HansOlsson]

I'm not sure if removing Evaluate was the right choice. The reason is that we get multiple ways of evaluating parameters:

• If a parameter has the value of a function-call using other parameters, and has Evaluate=true, we need to evaluate(=constant-fold) the function call in the tool generate flat-Modelica.
• If it does not have Evaluate=true we might constant-fold it in the tool importing flat-Modelica.
• And if the expression involves time-varying expressions we need to evaluate it during execution.

[casella]

I'm not sure if removing Evaluate was the right choice. The reason is that we get multiple ways of evaluating parameters:

* If a parameter has the value of a function-call using other parameters, and has Evaluate=true, 
   we need to evaluate(=constant-fold) the function call in the tool generate flat-Modelica.

So your point is that the tool generating flat Modelica may not be able to so and hence pass along the burden to the downstream tool while keeping the annotation?

* If it does not have Evaluate=true we might constant-fold it in the tool importing flat-Modelica.

I don't get this, if you say we shouln't remove Evaluate = true, why not having it should be a problem?

* And if the expression involves time-varying expressions we need to evaluate it during execution.

I understand the binding equation of a parameter should have constant or parameter variability. Do I miss something here?

[HansOlsson]

I'm not sure if removing Evaluate was the right choice. The reason is that we get multiple ways of evaluating parameters:

• If a parameter has the value of a function-call using other parameters, and has Evaluate=true,
  we need to evaluate(=constant-fold) the function call in the tool generate flat-Modelica.

So your point is that the tool generating flat Modelica may not be able to so and hence pass along the burden to the downstream tool while keeping the annotation?

• If it does not have Evaluate=true we might constant-fold it in the tool importing flat-Modelica.

I don't get this, if you say we shouln't remove Evaluate = true, why not having it should be a problem?

• And if the expression involves time-varying expressions we need to evaluate it during execution.

I understand the binding equation of a parameter should have constant or parameter variability. Do I miss something here?

You are missing the heading for this and that there might be external code, which makes evaluation more complicated, and thus we have three different ways of evaluating function calls, constant-fold before generating flat-modelica, constant-fold in the tool importing flat-modelica and leave in the C-code.

[henrikt-ma]

I suggest we leave it out for now, so that the list only contains the annotations that are obviously needed. Exactly how to deal with things related to evaluation of parameters has a separate item in the roadmap, and if it turns out that Evaluate still has a role to play, we can add it to the list then.

[HansOlsson]

Ok, seems ready for now

[casella]

I'm not sure if I need to approve this as a reviewer, I couldn't find the button to do so.
Anyway, all's fine for me, please go ahead with the merge