Briefly explain the compilation pipeline and the role of compilation vs. simulation flags

[casella]

Today I had an interesting discussion with Tobias Krenz, a German master student using OMC to study sulphuric acid production plants. He told me he was quite confused by the difference between compilation and simulation flags. Eventually he read the book by Peter Fritzson and got it, but maybe having some indications in the User's Guide would be nice.

We could add a short section in the Introduction, after System Overview and before Interactive session, where we explain what the main steps do (front-end, backend, code generation, C code compilation, simulation execution) and the role of compilation and simulation flags.

@Karim, @AnHeuermann, would you mind doing that? Otherwise, I can take care of that myself.

Thanks!

[sjoelund.se]

The user's guide has the following chapters and sections:

• OpenModelica Compiler Flags
  • Options
  • Debug flags
  • Flags for Optimization Modules
• Small Overview of Simulation Flags
  • OpenModelica (C-runtime) Simulation Flags

[anonymous]

In OMEdit we have "Translation flags" and "Simulation Flags". Probably translation flags are compiler flags. In that case, probably the same terminology should be used.

[casella]

Replying to sjoelund.se:

The user's guide has the following chapters and sections:

• OpenModelica Compiler Flags
  • Options
  • Debug flags
  • Flags for Optimization Modules
• Small Overview of Simulation Flags
  • OpenModelica (C-runtime) Simulation Flags

Yes. The problem is that we have no explanation whatsoever of why we have these two separate sets of flags. After many years of development work we give this for granted as the air we breathe, but it's not for anybody who is beginning to use the tool and has not yet studied Peter's book. Which is quite thick, so maybe a quick summary would help :)

[casella]

Replying to anonymous:

In OMEdit we have "Translation flags" and "Simulation Flags". Probably translation flags are compiler flags. In that case, probably the same terminology should be used.

I fully agree. In fact we have

• "Compilation flags" in the User's Guide
• "Translation flags" in OMEdit
• "commandLineOptions" in the ​vendor annotation
• "setCommandLineOptions" and "oms_setCommandLineOption" (witout the 's) in the API

Consistency is not our forte...

We also have C compilation flags in the General tab of OMEdit, but that is yet another story. Which is also not explained clearly.

Changing the API function names is probably not a good idea because of backwards compatibility. But I guess we could change the "Translation flags" tab name into "Compilation flags" in OMEdit, and also add some indication in the introductory section I mentioned above on what are the different possibilities to set those flags.

Comments?

[adeas31]

Replying to casella:

Changing the API function names is probably not a good idea because of backwards compatibility. But I guess we could change the "Translation flags" tab name into "Compilation flags" in OMEdit, and also add some indication in the introductory section I mentioned above on what are the different possibilities to set those flags.

Previously they were called Command Line Options in OMEdit and AFAIR they are changed to Translation Flags based on your suggestion (there should be an old ticket about it) though I am not sure. Basically in OMEdit the simulation is split in 3 steps. This is what happens when you click on the simulate button.

• Model is translated to generate the C-code using translateModel API. That is where Translation Flags are used hence the name Tranlsation Flags.
• The generated C-code is compiled to get the simulation executable. That is where C/C++ Compiler Flags (Optional): are used.
• The simulation executable is started with Simulation Flags.

Maybe the above information can be added to users guide specifically ​here.

[casella]

Replying to adeas31:

Previously they were called Command Line Options in OMEdit and AFAIR they are changed to Translation Flags based on your suggestion (there should be an old ticket about it)

I couldn't find it but I guess you ar right.

Basically in OMEdit the simulation is split in 3 steps. This is what happens when you click on the simulate button.

• Model is translated to generate the C-code using translateModel API. That is where Translation Flags are used hence the name Tranlsation Flags.
• The generated C-code is compiled to get the simulation executable. That is where C/C++ Compiler Flags (Optional): are used.
• The simulation executable is started with Simulation Flags.

Makes perfect sense, once you explain it.

Maybe the above information can be added to users guide specifically ​here.

Sounds good. Shall I try to do that?

[adeas31]

Sure!

[casella]

@adeas31, for the record, I couldn't find any translateModel() ​API call. What is the API funtion that OMEdit calls?

[casella]

See ​PR #6654.

Feel free to add direct links to other relevant parts of the User's Guide, and to amend the text in the PR if you deem it necessary. For example, the existing guide was only referring to experiment and simulation annotations, I understand command line annotations apply as well, so I updated the text accordingly - please check.

[adeas31]

Replying to casella:

@adeas31, for the record, I couldn't find any translateModel() ​API call. What is the API funtion that OMEdit calls?

translateModel is an API function but not part of ModelicaBuiltin.mo and the users guide read the API functions defined in ModelicaBuiltin.mo.

[casella]

I guess we need to fix that. Do you have any suggestions? Just add it manually?

[casella]

Retargeted to 1.17.0 after 1.16.0 release

[casella]

Retargeted to 1.18.0 because of 1.17.0 timed release.

[casella]

Ticket retargeted after milestone closed