Vendor-specific annotations for advanced flags and options

[Francesco Casella]

Testing is essential to guide the development of new advanced features in the OMC. This requires setting compiler/simulation flags, which might be specific to an entire library, or possibly just to single models.

It is much easier for all people involved in the process if these flags are specified once in the model source code as an annotation, instead of requiring to set up test-scripts/hudson flags/command line flags/OMEdit options or other heterogeneous and exotic means. The rationale is that there is only one Modelica source code but many ways to execute it (including the automated test suites), so the options should be specified in the source code and only there.

On the other hand, the ultimate goal is to set up the OMC so that it makes the best choices automatically. It should then be possible to enable/disable all these advanced settings annotations at once by just setting one global flag, so that it is very easy to compare the performance one can get with the ad-hoc flags to the performance obtained by a plain vanilla compilation of the same test suite.

Based on these requirements, I would propose introducing the annotation __OpenModelica_setCommandLineOptions(<String>). When applied to a package, it is automatically propagated to all models in the package. If a sub-package has another such annotation, it overrides the one of the container package. When applied to a model, it is used for compiling and simulating that model, and overrides any package annotations. This is a very flexible mechanism, it is based on the well-documented omc flags, and works at the source-code level.

I would also propose introducing yet another OMC flag --useCommandLineAnnotations (Boolean, default: true), that could be used to disable all such annotations and see how the plain vanilla compiler works on a given model or library with default settings.

The only thing which is still unclear to me is how to combine these command line options specified by annotations with other command line options that are given when invoking OMC at the command line or through the API. For instance, one might want to additionally turn on profiling, or enable some logging for debugging purposes. It would be nice if the two can be merged somehow, without losing either one. In case of conflict, I guess the options set when invoking OMC should override the ones specified by the annotations.

[Martin Sjölund]

Milestone pushed to 1.9.5

[Martin Sjölund]

Milestone renamed

[Francesco Casella]

Let me come up with a simpler concrete proposal, that should be readily implemented. Forget about the package annotations, only consider annotations within individual models.

annotation(__OpenModelica_setCommandLineOptions(String options)); is equivalent to running the setCommandLineOptions(options) API command before it is run from a user supplied .mos script, or by applying the options set by the user with command line flags. This provides baseline defaults that can be overridden by the end-user without changing the library.

annotation(__OpenModelica_setSimFlags(String options)); prepends the options string to the simflags string set by the simflags input of the simulate() API function, or by the argument of simulation executable. This provides baseline defaults that can be overridden by the ed-user without changing the library.

With these two annotations, it is possible to record any specific translation and simulation settings in a model. The syntax is consistent with what is already provided in the online documentation.

Provides a solution for #3859, just add

annotation(__OpenModelica_setCommandLineOptions("-s=optimization"));

and possily also a foundation for #3887.

[Martin Sjölund]

__OpenModelica_setCommandLineOptions sounds simple, but is not really since we don't know if the user set a flag explicitly. And how would he reset a flag to the default?

[Francesco Casella]

Just apply the annotation flags blindly, and then apply the user's one. If a library developer sets a flag in an annotation, he/she should know what he's doing, if he doesn't, then it's a bad library. If any flag cannot be unset, too bad. IMHO this would be anyway much better than the current situation, where you cannot set anything.

[Martin Sjölund]

We cannot do it in that order as it is. We just know what the current flags are and then see the annotation. We cannot apply those and then try to re-apply whatever changes were made to the current state of the flags.

It also makes sense to have the annotation actually override the user flags in some cases. If the user has set as default skip tearing and the modeler knows that this example does not work unless tearing is used, the annotation use tearing should probably be preferred anyway, right? (This is also much easier to implement)

[Francesco Casella]

Replying to sjoelund.se:

We cannot do it in that order as it is. We just know what the current flags are and then see the annotation.

I see.

We cannot apply those and then try to re-apply whatever changes were made to the current state of the flags.

It also makes sense to have the annotation actually override the user flags in some cases. If the user has set as default skip tearing and the modeler knows that this example does not work unless tearing is used, the annotation use tearing should probably be preferred anyway, right? (This is also much easier to implement)

In fact, there are some cases where it would make sense that the user's flags override the library's, and some where it is the other way round. It depends on whether the expert user is writing the library or playing around with omc flags.

If it is easier to implement a scheme where the annotation wins, that's perfectly fine for me. In that case, I would only recommend to add two flags --ignoreCommandLineOptionsAnnotation and -ignoreSimulationFlagsAnnotation, so that an expert user can always override the library settings (which will simply be ignored) without the need to change the library source code. Of course in that case one has to explicitly apply all the annnotation-set flags which make sense, but this is crystal clear and trivial to implement for any expert user.

Would this be ok?

[Adeel Asghar]

I can implement support for commandLineOptions rather quickly if you agree on the following syntax,

model A
  annotation(__OpenModelica_commandLineOptions = "+d=initialzation");
end A;

If we use the above syntax then we can use existing OMC API getNamedAnnotation,

>> getNamedAnnotation(A, __OpenModelica_commandLineOptions);
<< {"+d=initialzation"}

and addClassAnnotation to update it,

>> addClassAnnotation(A, annotate = __OpenModelica_commandLineOptions("+d=initialzation +indexReductionMethod=dynamicStateSelection"));
<< true

The resulting model will look like,

model A
  annotation(__OpenModelica_commandLineOptions = "+d=initialzation +indexReductionMethod=dynamicStateSelection");
end A;

[Francesco Casella]

Adeel, I'm not sure I understand your proposal exactly.

Q1: Are the other options besides +d=initialization the ones already set in the environment by the .mos script or by command line options?

Q2: Will the resulting model be saved somewhere (I hope not...), or is it just used on the fly for code generation?

[Adeel Asghar]

You can specify any command line option.
Yes the model could be saved if you want to save it.

I see that my description was not clear enough. So I am attaching two file that shows how we can do this.

The only question is that if you think that its fine then I will implement support for it in OMEdit.

[Francesco Casella]

Sorry Adeel, we don't understand each other. Let me present the two use cases I am interested in.

Case 1: Hudson testing

I want some of the models to use Heuns's algorithm instead of the default DASSL, and to turn off some options in the back-end. I would write this annotation in those models:

annotation(__OpenModelica_commandLineOptions = 
  "-s=heun --postOptModules-=detectJacobianSparsePattern");

Then, I'd like these options to be used by Hudson to run the tests, on top of what is specified in the MOSCOMMANDS and EXTRA_SIMFLAGS parameters of the job. I don't write any .mos script.

Case 2: OMEdit testing

If I load the same models with OMEdit, I would like those two options to be considered on top of what is specified in the OMEdit preferences and in the simulation settings window, unless I set some checkbox to ignore those annotations.

I'm not sure I understand what your test.mos file would mean in those contexts. Can you please elaborate?

[Adeel Asghar]

It seems like we need to do it at the compiler level.

I added some support for it. See here ​https://github.com/OpenModelica/OMCompiler/pull/824

[arunkumar palanisamy]

@casella: I am trying to write an API which will list the simulation flags. Currently there are lot of simulation flags available, I discussed this with Adeel, I would like to know what are the most important flags you like to use in the annotations

[Martin Sjölund]

Why do we need to be able to list the possible simulation flags? OMEdit already links directly into the flags and gets possible values directly from the data structure. It's not like OMEdit cannot already query all of the possible values.

[Adeel Asghar]

Replying to sjoelund.se:

Why do we need to be able to list the possible simulation flags? OMEdit already links directly into the flags and gets possible values directly from the data structure. It's not like OMEdit cannot already query all of the possible values.

For models like this,

model M
 annotation(__OpenModelica_simulationFlags(method="euler"));
end M;

We need an API which should read __OpenModelica_simulationFlags annotation. OMEdit will use it and when you open the Simulation Dialog the solver method is automatically changed from dassl to euler.

[Adeel Asghar]

I added support for __OpenModelica_commandLineOptions annotation in e652a20/OMCompiler and --ignoreCommandLineOptionsAnnotation flag in 9c5ab12/OMCompiler.

Also added support for it in OMEdit. You can add/edit __OpenModelica_commandLineOptions annotation from the GUI via diagram view->right click->Properties->OMC Flags. Can set/unset --ignoreCommandLineOptionsAnnotation flag from Options->Tools->Simulation.

[Martin Sjölund]

Replying to adeas31:

For models like this,

model M
 annotation(__OpenModelica_simulationFlags(method="euler"));
end M;

We need an API which should read __OpenModelica_simulationFlags annotation. OMEdit will use it and when you open the Simulation Dialog the solver method is automatically changed from dassl to euler.

But you still don't need an API to do that... You just need your boxes to know which simulation flag they correspond to. And you already know that since you use whatever you put into those boxes in order to produce the simulation flags passed to the simulation executable.

[Adeel Asghar]

Replying to sjoelund.se:

Replying to adeas31:

For models like this,

model M
 annotation(__OpenModelica_simulationFlags(method="euler"));
end M;

We need an API which should read __OpenModelica_simulationFlags annotation. OMEdit will use it and when you open the Simulation Dialog the solver method is automatically changed from dassl to euler.

But you still don't need an API to do that... You just need your boxes to know which simulation flag they correspond to. And you already know that since you use whatever you put into those boxes in order to produce the simulation flags passed to the simulation executable.

I do need an API to read the annotation. It's the same as experiment annotation.

[Martin Sjölund]

So what you need is something like:

getAnnotationNamedModifiers(M, __OpenModelica_simulationFlags); // Returns {"method"}
getAnnotationValue(M, __OpenModelica_simulationFlags.method); // Returns "euler"

[Martin Sjölund]

(And make it part of the CevalScript API)

[Francesco Casella]

Replying to arun3688:

@casella: I am trying to write an API which will list the simulation flags. Currently there are lot of simulation flags available, I discussed this with Adeel, I would like to know what are the most important flags you like to use in the annotations

I agree with Martin's observation, OMEdit already knows the flags it supports via checkboxes. Those who do not show up there, should end up in the additional flags field.

Also note that simulation flags and compiler flags need to be treated differently.

For simulation flags, it makes sense that they are read from the annotation (together with standard stuff such as experiment(StopTime)) and used to update the fields of the simulation setup window before opening it, of course unless --ignoreCommandLineOptionsAnnotation has been set.

For compiler flags, I would say that it doesn't make much sense that they are used to modify the content of the Options | Simulation | OMC flags field, because these are global tool settings, not settings specific to single simulations.

Maybe we should add and OMC flags field also to the simulation setup window, and have its content updated by the contents of the command line annotation (unless they must be ignored) and by the contents of the Options|Simulation|OMC flags field as well, then sent to omc for the actual compilation.

What do you think?

[Adeel Asghar]

Replying to casella:

Replying to arun3688:

@casella: I am trying to write an API which will list the simulation flags. Currently there are lot of simulation flags available, I discussed this with Adeel, I would like to know what are the most important flags you like to use in the annotations

I agree with Martin's observation, OMEdit already knows the flags it supports via checkboxes. Those who do not show up there, should end up in the additional flags field.

I have already discussed it with Martin. We need two new APIs as Martin suggested above. I have already explained it to Arun and hopefully he will implement them soon.

Also note that simulation flags and compiler flags need to be treated differently.

True. Compiler flags are handled via __OpenModelica_commandLineOptions (which is already supported now) and simulation flags will be handled via __OpenModelica_simulationFlags.

For simulation flags, it makes sense that they are read from the annotation (together with standard stuff such as experiment(StopTime)) and used to update the fields of the simulation setup window before opening it, of course unless --ignoreCommandLineOptionsAnnotation has been set.

You mean --ignoreSimulationFlagsAnnotation, right?

For compiler flags, I would say that it doesn't make much sense that they are used to modify the content of the Options | Simulation | OMC flags field, because these are global tool settings, not settings specific to single simulations.

They don't modify it.

Maybe we should add and OMC flags field also to the simulation setup window, and have its content updated by the contents of the command line annotation (unless they must be ignored) and by the contents of the Options|Simulation|OMC flags field as well, then sent to omc for the actual compilation.

What do you think?

I can do this but I don't think is really needed. It will be like we are just setting the same flag again and again. For example, by default OMEdit has +d=initialization in Options | Simulation | OMC flags field. If we add it to simulation setup window then we are just setting this flag for every simulation which is really unnecessary.

[Francesco Casella]

Sorry, I messed up a bit with simulation flags and compiler flags.

Summing up

• model-specific simulation flags can be set using the __OpenModelica_simulationFlags annotation. Unless --ignoreSimulationFlagsAnnotation is set, these will be processed by OMC and displayed in the simulation setup window.
• conversely, if I set model-specific simulation flags in the simulation setup window and press the Save button, they will be recorded in the __OpenModelica_simulationFlags annotation

It is still not clear to me how we want to process the compiler flags. Assume for example that a model contains annotation(__OpenModelica_CommandLineOption("--disableLinearTearing"));. When I simulate it with OMEdit, the --disableLinearTearing flag will be used to build the code. However, I will only see this in the log window, but there will be no GUI support for this, right?

Also, if I want to set up such a flag, I have to do it manually in the textual view, by adding or modifying the __OpenModelica_CommandLineOption.

Is this what you have in mind?

This would be ok for me, but it is only a first step. For example, Willi is currently implementing the support for a sparse DAE solver (IDA), which is expected to be a lot more efficient than dense ODE solvers in many cases. In order to simulate a model with this solver, besides some simulation flags, you also need to switch on the --daeMode compiler flag.

At the moment, it is really essential that we have full support with textual annotations, as this can still be considered a somwhat "advanced" feature for experts. In the long run, it should be possible to give access to these advanced features via the GUI also to non-experts, because they can really make the difference.

Maybe we could introduce a wizard-like setup procedure, that would ask you a number of questions about the features of your model and propose some settings to obtain efficient simulation code.

See also #3908

[Adeel Asghar]

Replying to casella:

Sorry, I messed up a bit with simulation flags and compiler flags.

Summing up

• model-specific simulation flags can be set using the __OpenModelica_simulationFlags annotation. Unless --ignoreSimulationFlagsAnnotation is set, these will be processed by OMC and displayed in the simulation setup window.
• conversely, if I set model-specific simulation flags in the simulation setup window and press the Save button, they will be recorded in the __OpenModelica_simulationFlags annotation

It is still not clear to me how we want to process the compiler flags. Assume for example that a model contains annotation(__OpenModelica_CommandLineOption("--disableLinearTearing"));. When I simulate it with OMEdit, the --disableLinearTearing flag will be used to build the code. However, I will only see this in the log window, but there will be no GUI support for this, right?

What do you mean by no GUI support?

Also, if I want to set up such a flag, I have to do it manually in the textual view, by adding or modifying the __OpenModelica_CommandLineOption.

Seems like you haven't read my comment:17. Here it is again,

Also added support for it in OMEdit. You can add/edit __OpenModelica_commandLineOptions annotation from the GUI via diagram view->right click->Properties->OMC Flags. Can set/unset --ignoreCommandLineOptionsAnnotation flag from Options->Tools->Simulation."

Is this what you have in mind?

This would be ok for me, but it is only a first step. For example, Willi is currently implementing the support for a sparse DAE solver (IDA), which is expected to be a lot more efficient than dense ODE solvers in many cases. In order to simulate a model with this solver, besides some simulation flags, you also need to switch on the --daeMode compiler flag.

At the moment, it is really essential that we have full support with textual annotations, as this can still be considered a somwhat "advanced" feature for experts. In the long run, it should be possible to give access to these advanced features via the GUI also to non-experts, because they can really make the difference.

Maybe we could introduce a wizard-like setup procedure, that would ask you a number of questions about the features of your model and propose some settings to obtain efficient simulation code.

See also #3908

[Francesco Casella]

Seems like you haven't read my comment:17.

Oops. In fact I read it too quickly and I mis-interpreted it, sorry.

I'll try this out and get back to you asap.

[Adeel Asghar]

I added support for __OpenModelica_simulationFlags annotation in 06da538/OMEdit. Now OMEdit can read/write __OpenModelica_simulationFlags annotation.

Also added flag --ignoreSimulationFlagsAnnotation in c40d6c4/OMCompiler. OMEdit supports the flag.

You can write models like this,

model M
  annotation(__OpenModelica_simulationFlags(s="euler", lv="LOG_STATS"));
end M;

OMEdit will simulate the above with model with euler solver. If you open the Simulation Dialog then euler will be selected automatically as integration method. However, you can explicitly change it if you want.

[Francesco Casella]

All the required functionality is now implemented

[Martin Sjölund]

Milestone deleted