FMI: LS: Variable interface Bypass-Mode for performance increase

[timrulebosch]

General principle of operation:

1. FMU defines a typedef containing bypass variables (i.e. those variables which will see a performance increase).
2. FMU defines/set/calculates the VRef of bypassed variables to the offset of those variables in the "bypass" typedef.
3. FMU allocates an instance of the "bypass" typdef and assigns to a pointer variable.
4. Legacy Get/Set operates against the "bypass" instance using the VRef: pointer + offset.
5. FMU defines a variable which gives the "bypass" pointer (i.e. using uint64).
6. Importer requests the "bypass" pointer and accesses variables directly using the VRef of those variables: pointer + offset.

• Alternative (to 6):
  • FMU exports (optionally) a known symbol representing the bypass pointer.
  • The importer attempts to locate that symbol, the presence of which indicates that bypass-mode is supported.

Noteworthy items:

• FMU may define variables in blocks according to type, allowing importer to use vectorization when accessing variables.
• Ownership of variable memory belongs with FMU.
• Existing constraints for Get/Set interface applies; during do_step() model only access, otherwise only importer access (and so on).
• Pointer variables may need to be references (void**) so that they can be reallocated. Annotations should indicate that, as well as associating a variable that indicates the size of that allocated resource (if required, for instance, a dynamic resizing buffer).

[timrulebosch]

The likely mechanism to indicate if an FMU supports this mechanism will be to export a symbol as follows:

• void* fmu2VariableInterfaceBypass - for FMI 2 FMU's
• void* fmu3VariableInterfaceBypass - for FMI 3 FMU's

When these symbols are present the Value-Reference of a variable can be interpreted as an offset to the value stored in that variable. The FMU will set that value during the call to fmi2Instantiate() (or the FMI 3 equivalent). All scalar variable must support this access method. The exact method of locating complex variables needs to be defined (i.e. the length of a binary variable), however it would likely be vRef/Offset + X, where X is derived from the number of variables of that type - so a block of memory for binary variable data (pointers), followed by a block of binary variable size/length values (at a constant offset of X = N x 8 or similar).

[IZacharias]

@timrulebosch Could you explain where you see the difference to the approach from the Efficiency Working group? We do not fully see the difference. We should not create two layered standards that solve similiar or the same problem.

[IZacharias]

@timrulebosch See also our draft adaptions of the standard (XSD & header files) here: https://github.com/modelica/fmi-efficiency

[timrulebosch]

@IZacharias We have a very narrow use case, you don't need to worry about it interfering with your efforts.

Technically, at the moment, the minimal solution is to use variable reference indexing "VRef: pointer + offset"; where the pointer is an exported symbol representing the variable "space", and the offset is calculated as the FMU is generated/packaged. This is a normal mechanism for FMU's ... so the only difference is to make the pointer available, which should be trivial.

Binary signals will have a layout in the variable "space" as follows: data_pointer : data_length : allocated_size; where VRef is the offset of the data_pointer, and the subsequent values can be retrieved from their relative offset (to the VRef of the data_pointer).

A similar mechanism would/might be needed for other complex variables (e.g. arrays).

[timrulebosch]

Implementation details (WIP):

fmu.h

Eventually located in fmi2Functions.h and fmi3Functions.h, or another header (see fmi2Binary.h LS).

/* FMI Direct Variable Access Interface. */
typedef void* fmi2ValueBypassMapTYPE;
typedef void* fmi3ValueBypassMapTYPE;

fmi2fmu.c

fmi2ValueBypassMapTYPE fmi2ValueBypassMap = NULL;

fmi2Component fmi2Instantiate(...)
{
    fmi2ValueBypassMap = create_map(...);
}

Importer.c

fmi2ValueBypassMapTYPE value_bypass_map = NULL;
...
static int _run_fmu2_cosim(...)
{
...
    void* map = dlsym(handle, "fmi2ValueBypassMap");
    if (map) {
        value_bypass_map = *map;
    }
...
    if (value_bypass_map) {
        for (size_t i = 0; i < importer_nvr; i++) {
            *(double*)(value_bypass_map + vr[i]) = importer_value[i];
        }
    }
...
}
```

## Observation

Condition: FMI 2 Co_Simulation, 1 Model, 2000 signals, step size 0.0005, steps 2000 (1 second)

The overhead of calling _all_ the FMI functions is not significant (cannot be measured). Overhead of copying data _also_ not significant ... but will need to be confirmed.

At some point these inefficient mechanisms must have an impact, however, importer/fmu implementation can be dominant factors.