Clarify implementation of instantiation and initialization modes

[restenb]

We recently ran into some confusion wrt. whether or not input values should be / were being set during instantiation. This is what the FMI2 docs have to say about instantiation and initialization:

To me at least, this clearly reads like inputs should not be included in state instantiating. This filter then correctly excludes variability constant and causality input from the first call to set_variables.

For the current implementation, in slave_simulator.cpp and fmu.cpp, the setup(...) function seems to be covering both instantiation and initialization.

Note that in the FMI3 documentation, inputs are included also in state instantiated:

So either the FMI2 wording is wrong, or this was intentionally changed for FMI3.

I think we should at least clarify this and tidy up the implementation on our end to avoid confusion in the future. Perhaps an easy fix is to explicitly name our functions after the FMI states, splitting the current setup(...) into separate functions for instantiation and initialization. Especially since it seems we have to treat this differently again in FMI3.

[kyllingstad]

the setup(...) function seems to be covering both instantiation and initialization.

Not quite. Instantiation (i.e., fmi2Instantiate()) happens in the simulator constructor, while setup() calls fmi2SetupExperiment() followed by fmi2EnterInitializationMode(). And then fmi2ExitInitialization() is called within start_simulation().