Usage of setCommandLineOptions vs. CompilerFlag and SimulationFlag

[olivleno]

Description

The scripting API docu is providing

setCommandLineOptions

with an explanation limited to:

"The input is a regular command-line flag given to OMC, e.g. -d=failtrace or -g=MetaModelica"

and no type definition of the function arguments

OMEdit has in the Settings Dialog:

• C/C++ CompilerFlags
• Translation Flags
• Simulation Flags

Looking for flags one can find:

• simulationflags
• compiler flags

There seems to be no place where these terms are properly defined.

Steps to Reproduce

1. Try to figure out how to use: setCommandLineOptions
2. Search the scripting API docu
3. scroll through 2000 lines of options
4. Finally search for "LOG_ASSERT", as this is given in the OMEdit Options Dialog and find it under simulation flags
5. Try the following:

sim_flags="-lv=-LOG_ASSERT"
OMJulia.API.setCommandLineOptions(omc, sim_flags) 

ERROR: Failed to set command line options "-lv=-LOG_ASSERT".
Error: Unknown option -lv.

Expected Behavior

• Clear definition of used terminology
• explanation of the syntax of the flags, including how to enable/disable, concatenate
• example code
• OMJulia.API functions documented with typed function signature, example code
• scripting API with a syntax how to map MetaModelica to mos

Version and OS

Additional Context

The API is powerful but really hard to use.

[casella]

@olivleno you are right, this thing is a bit messy, we got used to it but it's unecessarily obscure to beginners. I tried to describe it in the user's guide, but probably this is not clear enough. Have you read that already?

There are indeed three sets of flags

• flags affecting the code generation: these are defined as Translation Flags in the OMEdit Simulation Setup menu, and as Command Line Options in the API. The former definition refers to the fact that these flags affect the translation of Modelica code into C code, the latter to the fact that you can pass these flags as command line options when you invoke omc from the command line. These names were defined a very long time ago, unifying them now could create backwards compatibility issues; I guess we should just explain them clearly.
• flags affecting the C/C++ compilation, i.e., flags passed to the gcc/clang compiler. These may affect the compile time, executable size, and simulation performance
• flags affecting the runtime simulation (e.g. stop time, tolerance, integration algorithm, etc.) which are passed as command line option when running the simulation executable. These can be changed when re-simulating a model, without the need of re-compiling it

I can try to improve the documentation, where would you suggest to discuss this in the User's Guide? I guess we should also explicitly explain the relationship between settings in OMEdit, setting when using the command line interface, and settings when using the scripting API, as well as OMPython/OMJulia/OMMatlab

[olivleno]

@casella thanks for the link. I must admit that I did not read this section of the user's guide. I was looking for this type of information in the context of the scripting API. Unfortunately these terms are used as if they were self-explaining. As it cannot be expected that a documentation is read top to bottom I would appreciate if these terms were introduced in the first sentence of the respective section, e.g. Translation Flags and Simulation Flags.

Other places like scripting api or OMJulia.API.setCommandLineOptions could then link to these definitions or simply add a few words.

Generally speaking the api docu is very sparse. It's basically repeating the function signature without explanations of its purpose.

[olivleno]

I see very big potential in having this scripting api. Giving a good introduction on how to use it in practice, including which console or tool to use, how to choose/set the work directory, which environment variables/modelica path are needed, e.g., to report a bug as reproducible mos script would be a good starting point.

Second, the scripting functions must contain at least on explaining sentence that is more than the repetition of the name of the function.

[casella]

@olivleno I agree with all your comments. I can't take care of that now, please come back to me in September and we'll try to improve this substantially.

[casella]

See also #12712