Invoke a Functional Mock-up Interface (FMI)
Functional Mock-up Unit (FMU).
<p>Read in a <code>.fmu</code> file named by the
<i>fmuFile</i> parameter. The <code>.fmu</code> file is a zipped
file that contains a file named <code>modelDescription.xml</code>
that describes the ports and parameters that are created.
At run time, method calls are made to C functions that are
included in shared libraries included in the <code>.fmu</code>
file.</p>
<p>To use this actor from within Vergil, use File -> Import -> Import
FMU, which will prompt for a .fmu file. This actor is <b>not</b>
available from the actor pane via drag and drop. The problem is
that dragging and dropping this actor ends up trying to read
fmuImport.fmu, which does not exist. If we added such a file, then
dragging and dropping the actor would create an arbitrary actor
with arbitrary ports.</p>
<p>FMI documentation may be found at
<a href="http://www.modelisar.com/fmi.html">http://www.modelisar.com/fmi.html</a>.
</p>
<p>
Under the Continuous director, this actor invokes fmiDoStep() at the
beginning of the fire() method whenever time has advanced since the
last invocation of the fire() method. If at this point the FMU
discards the step, then the fire method will nonetheless produce
outputs, but they may not be valid for the current time.
This should not matter because the Continuous director will call
<a href="../../../../ptolemy/actor/lib/fmi/FMUImport.html#isStepSizeAccurate">isStepSizeAccurate()</a>, which will return false, and it will
revert to the last committed and proceed with a smaller step size.
Under the Continuous director, when time is advanced, this actor
will be fired several times. The first firing will be at the
beginning of the time interval, which matches the last commit time of
the last postfire() invocation. The remaining firings will be at
times greater than the last commit time. These firings are all
speculative, in that any actor may reject the step size when they
occur. In the event that a step is rejected, the Continuous director
will call <a href="../../../../ptolemy/actor/lib/fmi/FMUImport.html#rollBackToCommittedState">rollBackToCommittedState()</a>. If the FMU supports
it, then this method will use fmiSetFMUstate() to restore the state
to the state of the FMU at the time of the last postfire() (or
initialize(), if postfire() has not yet been invoked).
</p><p>
<b>If the FMU does not support rolling back (indicated by the
canGetAndSetFMUstate element in the XML file), then this actor
assumes that the FMU is stateless and hence can be rolled back
without any particular action.</b> This may not be a good
assumption, so it issues a warning.
</p>
<p>
Many tools that export FMUs fail to correctly declare when outputs
do not depend on inputs. For this reason, this actor provides each
output port with a "dependencies" parameter. If this parameter is
left blank, then the dependencies are determined by the FMU's
modelDescription.xml file. Otherwise, if this parameter contains
a space-separated list of names of input ports, then the output
port depends directly on those named input ports. If this parameter
contains the string "none", then the output port depends directly
on none of the input ports. If contains the string "all", then this
output port depends on all input ports.
Although the FMI standard is ambiguous, we infer dependency to
mean that the value of an output at time <i>t</i> depends on the
input at time <i>t</i>. It is irrelevant whether it depends on
the input at earlier times.
</p><p>
Note that if the display name of a port is set, display name is
used in as the name of the FMU scalar variable instead of the port
name. This is useful in case FMU scalar variable names contain a
period, because periods are not allowed in port names.</p>
<p>
Note that if you use an instance of this class with the ContinuousDirector,
you should in general use model exchange, not cosimulation. This is
because the ContinuousDirector may advance time by calling fmiDoStep,
and then later reject a step size. The only exception is that if the
FMU implements rollback (via fmiGetFMUState and fmiSetFMUState), then
it can be used with the ContinuousDirector.
Christopher Brooks, Michael Wetter, Edward A. Lee
$Id: FMUImport.java 70717 2014-11-21 23:37:52Z cxh $
Ptolemy II 10.0
Red (cxh)
Red (cxh)
The FMI version of the FMU. This is a string that defaults to "1.0"
if the FMU file does not specify a version, and otherwise is the
version specified in the file.
The Functional Mock-up Unit (FMU) file. The FMU file is a zip
file that contains a file named "modelDescription.xml" and any
necessary shared libraries. The file is read when this actor
is instantiated or when the file name changes. The initial
default value is "fmuImport.fmu".
If true, then this FMU is for model exchange rather than co-simulation.
This is a boolean that defaults to false. The value of this parameter
gets determined when FMU is imported. This parameter is set to expert
mode because normally a user should not be allowed to change it.
If true, then previously received input values will be re-used on subsequent firings where
inputs are absent. If there are no previously received input values,
then the value used will be whatever default the FMU has for the
corresponding input variable. If false (the default), then an exception will be
thrown if an input is absent on any firing.
If true, suppress warnings about the FMU not being able to roll
back. It is reasonable to set this to true if you know that the
FMU can be executed at an earlier time than it was previously
executed. This is safe, for example, if the FMU is stateless.
This is a boolean that defaults to false.
If true, indicate to the FMU (if it supports it) that it is
allowed to create displays and otherwise interact with the user.
This is a boolean that defaults to false.