Instantiation

fmi2Instantiate: This function creates an instance of the FMU and returns a handle that can be used to access the FMU's functions and data.

Doc

(pag.19) The function returns a new instance of an FMU or a null pointer when failed.

An FMU can be instantiated many times (provided capability flag canBeInstantiatedOnlyOncePerProcess = false).

This function must be called successfully before any of the following functions can be called. For co-simulation, this function call has to perform all actions of a slave which are necessary before a simulation run starts (for example, loading the model file, compilation...).

Argument instanceName is a unique identifier for the FMU instance. It is used to name the instance, for example, in error or information messages generated by one of the fmi2XXX functions. It is not allowed to provide a null pointer and this string must be non-empty (in other words, must have at least one character that is no white space). [If only one FMU is simulated, as instanceName attribute modelName or <ModelExchange/CoSimulation modelIdentifier=”..”> from the XML schema fmiModelDescription might be used.]

Argument fmuType defines the type of the FMU:

•  = fmi2ModelExchange: FMU with initialization and events; between events simulation of continuous systems is performed with external integrators from the environment (see section 3).
•  = fmi2CoSimulation: Black box interface for co-simulation (see section 4). Argument fmuGUID is used to check that the modelDescription.xml file (see section 2.3) is compatible with the C code of the FMU. It is a vendor specific globally unique identifier of the XML file (for example, it is a “fingerprint” of the relevant information stored in the XML file). It is stored in the XML file as attribute “guid” (see section 0) and has to be passed to the fmi2Instantiate function via argument fmuGUID. It must be identical to the one stored inside the fmi2Instantiate function; otherwise the C code and the XML file of the FMU are not consistent with each other. This argument cannot be null.

Argument fmuResourceLocation is a URI according to the IETF RFC3986 syntax to indicate the location to the “resources” directory of the unzipped FMU archive. The following schemes must be understood by the FMU: Mandatory: “file” with absolute path (either including or omitting the authority component)  Optional: “http”, “https”, “ftp”  Reserved: “fmi2” for FMI for PLM.

[Example: An FMU is unzipped in directory “C:\temp\MyFMU”, then fmuResourceLocation = “file:///C:/temp/MyFMU/resources” or “file:/C:/temp/MyFMU/resources”. Function fmi2Instantiate is then able to read all needed resources from this directory, for example maps or tables used by the FMU.] Argument functions provides callback functions to be used from the FMU functions to utilize resources from the environment (see type fmi2CallbackFunctions below). Argument visible = fmi2False defines that the interaction with the user should be reduced to a minimum (no application window, no plotting, no animation, etc.). In other words, the FMU is executed in batch mode. If visible = fmi2True, the FMU is executed in interactive mode, and the FMU might require to explicitly acknowledge start of simulation / instantiation / initialization (acknowledgment is non-blocking). If loggingOn = fmi2True, debug logging is enabled. If loggingOn = fmi2False, debug logging is disabled. [The FMU enable/disables LogCategories which are useful for debugging according to this argument. Which LogCategories the FMU sets is unspecified.]