Opened 7 years ago

Closed 22 months ago

#2357 closed umbrella (fixed)

Options to FMU runtime system

Reported by: jakesson Owned by: Iakov Nakhimovski
Priority: major Milestone: Pending
Component: FMI/Export Version: trunk
Keywords: Cc:

Description (last modified by Jesper Mattsson)

We need a mechanism to propagate options into FMUs to control the behavior of the FMI runtime system. Such options include:

  • Log level of FMU (Note that FMI 2.0 supports different log categories, whereas FMI 1.0 only supports turning logging on and off)
  • Enabling/disabling features in run-time system, including bounds checking and scaling of equation systems

It is proposed to use the standard mechanism for setting parameters in FMUs to propagate options: fmiSetReal/fmiSetInteger/fmiSetBoolean/fmiSetString.

The solution consists of the following steps:

  • The compiler generates additional FMU-runtime parameters and add them to the list of parameters. Note that the names need to be constructed in such a way that they cannot interfere with legal Modelica variable names, e.g., by prefixing with '_'.
  • In order to describe options in a simple and easy-to-extend manner it would be convenient to use a similar functionality offered by the OptionsRegistry for handling compiler options. Perhaps the same mechanism can be used?
  • In the code generation of the FMU, the runtime options parameters automatically added by the compiler will be generated by standard mechanism.
  • In the runtime system, there needs to be a mechanism to access the values of the options. One possibility would be to generate one C function for each option in the options registry. Example: say that there is an integer option '_fmu_log_level'. The following function could then be generated:
    int fmi_get_fmu_log_level(jmi_t jmi) {
      return _fmu_log_level;
    }
    

where the right hand side of the return statement is the macro that resolves the value of the parameter '_fmu_log_level'. The runtime system code could then call this function when needed.

Subtickets

New subticket

Open:

Closed:


Change History (16)

comment:1 Changed 7 years ago by Jesper Mattsson

Specifying the set of runtime options to be added to the parameter list in the same manner as is done in the OptionsRegistry class seems reasonable.

comment:2 Changed 7 years ago by Iakov Nakhimovski

From run-time developer point of view:

  • it'd be convenient to be able to add new options to the run-time without modifying the compiler
  • there should be a way to assign defaults to some options from the Modelica input file.

Therefore I'd propose that just two (or two per basic type) variables are introduced by the compiler:

  • "runtimeOptionSelector" - used to select the option that is accessed via the other variable. This can be either integer or standard enumeration.
  • "runtimeOptionValue" - setting/getting provides access to the specific option. This can be real that is internally converted to integer/boolean if needed. Alternatively a pair of variables for each basic type is provided.

Internally in the runtime the options may be read with:

double fmi_get_real_option(jmi_t jmi, int optionID);

Default values for the options may be introduced with annotations and/or on the command line. In both cases this is a couple (opname, value) that translates to a line in the generated C code:

fmi_set_runtime_option_opname(jmi, value)

"opname" is not processed by the compiler and put unchanged into the code as a part of function name. It is expected that the run-time has a header file where the corresponding function is defined. Note that in this way the "value" gets the correct data type set. Alternative with "opname" defined as optionID and all values of the same type:

fmi_set_runtime_option(jmi, opname, value)

Note that since the variables are fixed they can be added to the XML template and do not need to be generated.

comment:3 Changed 7 years ago by Jesper Mattsson

This means that the compiler would be unable to do any error-checking on the options set in annotations. The only feedback to the user from an unknown option name (or one of wrong type) would be the C code failing to compile.

comment:4 in reply to:  3 Changed 7 years ago by Iakov Nakhimovski

Replying to jmattsson:

This means that the compiler would be unable to do any error-checking on the options set in annotations. The only feedback to the user from an unknown option name (or one of wrong type) would be the C code failing to compile.

That's true. Another alternative is to use a single string variable to propagate the options. Again no errors during compilation (neither Modelica nor C) but a "warning" from fmiInitialize().
This is, however, not a big problem since run-time options are quite advanced.
It can also be a solution to implement both ways with some more common options checked and handled by the compiler.

comment:5 in reply to:  2 Changed 7 years ago by jakesson

The two main arguments for the alternative design are:
Replying to iakov:

From run-time developer point of view:

  • it'd be convenient to be able to add new options to the run-time without modifying the compiler

I don't think that this is a complication. On the contrary, adding new options is easy if we use the options registry, and is done by adding an entry to the OptionsRegistry class:

ENABLE_TEARING   ("enable_tearing", false, 
	          "If this option is set to true "+
                  "(default is false), tearing of equation "+
                  "systems is enabled."),

In addition, we get:

  • One single spot where all run-time options are defined
  • Consistent handling between compiler options and run-time options
  • Automatic checking of options
  • At some point we talked about automatically generating documentation of options from the OptionsRegistry, something that will get more attractive as the number of options grow.
  • there should be a way to assign defaults to some options from the Modelica input file.

I don't see any reason why this could not be done if we use the OptionsRegistry.

In addition, the OptionsRegistry supports reading options stored on XML files which are located in the JModelica.org installation. Users can then change default values of options easily.

With this arguments, I would opt for going with a solution based on an OptionsRegistry.

comment:6 Changed 7 years ago by jakesson

Better solutions for accessing options from inside the FMU runtime system

  • Generate a header file and a C file to the FMI runtime - these files are compiled whith the runtime system
  • Generate a table into the generated FMU C code with string (option name) and value reference

Go with the second option

comment:7 Changed 7 years ago by Jesper Mattsson

Description: modified (diff)

comment:8 Changed 7 years ago by Jesper Mattsson

As of #2374, #2383 and #2391 being fixed, a first version is ready.

OptionsRegistry contains a couple of dummy runtime options to excite the tests - these can be removed once real options are added.

Current limitations:

  • The option descriptions are not added to the parameters (and thus not written in XML file). This should be fixed.
  • The map contains the names as the parameters are named, i.e. with a '_' prepended. Is this desired, or should it be without the '_'?

comment:9 Changed 7 years ago by jakesson

Milestone: 1.9.x1.10.x

comment:10 Changed 6 years ago by jakesson

Milestone: 1.10.x1.11.x

comment:11 Changed 6 years ago by Jesper Mattsson

Type: enhancementumbrella

comment:12 Changed 6 years ago by Jesper Mattsson

Milestone: 1.11.x

comment:13 Changed 6 years ago by Tove Bergdahl

Milestone: Pending

comment:14 Changed 6 years ago by Tove Bergdahl

Owner: set to Iakov Nakhimovski
Status: newassigned

comment:15 Changed 6 years ago by Jesper Mattsson

Description: modified (diff)

comment:16 Changed 22 months ago by Jesper Mattsson

Resolution: fixed
Status: assignedclosed
Note: See TracTickets for help on using tickets.